Agentic Node + TypeScript Starter

📊 Build Status & Quality Metrics

CI/CD Workflows

Test Coverage & Quality

Code Quality Metrics

Meta

A batteries-included TypeScript starter template with comprehensive testing, code quality automation, and security scanning. Built for modern Node.js development with AI-assisted (agentic) coding workflow.

Note: This template includes example code to demonstrate its capabilities. These example files are clearly marked with header comments and should be removed when starting your project. See Getting Started for details.

🤔 What is Agentic Development?

"Agentic" in this context refers to AI-assisted development workflow, not AI agent runtime. This template is designed to work seamlessly with AI development tools to enhance your productivity through:

• 🤖 AI-powered code generation - Let AI assistants help write boilerplate and tests
• 🔄 Automated refactoring - AI tools can safely refactor with comprehensive test coverage
• 📝 Documentation assistance - AI can help maintain docs in sync with code
• 🎯 Issue-to-implementation workflows - Custom commands for AI-driven development

Important: This is a template repository for starting new projects. No AI agents or chatbots are included - the "agentic" aspect comes from using AI development tools to assist you in building your application faster and with higher quality.

🛠️ Tech Stack

Core: Node.js 24 • TypeScript ^5.9.3 (strict, NodeNext ES modules) • pnpm 10.22.0 (pinned via mise)
Testing: Vitest + V8 coverage • fast-check property testing • lines/functions/statements ≥90%, branches ≥80%
Quality: ESLint 9 • Prettier • Husky • Commitlint
Security: CodeQL • OSV Scanner • SBOM • SLSA attestations
CI/CD: GitHub Actions • Changesets • Automated releases

📖 Documentation

Full Documentation →

• Getting Started - Setup and installation
• Development - Workflows and commands
• Testing - Test patterns and coverage
• Docker - Docker configuration and healthchecks
• Patterns - Copy-paste code examples
• Troubleshooting - Common issues

🚀 Quick Start

# Clone and setup
git clone https://github.com/sapientpants/agentic-node-ts-starter.git my-project
cd my-project

# Install dependencies (requires Node.js 24 and pnpm 10.22.0 - use mise if available)
pnpm install

# No .env file needed for the template defaults; add variables via src/config.ts + .env.example
cp .env.example .env   # optional: customize values (all keys have safe defaults)

# Verify everything works
pnpm test
pnpm precommit  # Full quality check, same as CI (several minutes)

# Start developing
pnpm dev     # TypeScript watch mode

Prerequisites: Node.js 24+, pnpm 10.15, GitHub repo (for CI/CD)
Full setup guide: docs/GETTING_STARTED.md

📚 Key Commands

# Development
pnpm dev          # TypeScript watch mode
pnpm build        # Build to dist/
pnpm precommit    # Run all quality checks

# Testing (80% coverage required)
pnpm test         # Run tests
pnpm test:watch   # Watch mode
pnpm test:coverage # With coverage report

# Quality
pnpm lint         # Check linting
pnpm lint:fix     # Fix linting issues
pnpm format       # Check formatting
pnpm format:fix   # Fix formatting
pnpm typecheck    # Type check only

# Releases
pnpm changeset    # Create changeset
pnpm sbom         # Generate SBOM

Full command reference: docs/DEVELOPMENT.md

📊 Code Quality Dashboard

Comprehensive quality metrics tracked automatically on every CI run:

Testing Metrics

Metric	Current	Threshold	Status	Local Command
Line Coverage	93.77%	≥80%	✅ Pass	pnpm test:coverage
Branch Coverage	84.95%	≥80%	✅ Pass	pnpm test:coverage
Function Coverage	100%	≥80%	✅ Pass	pnpm test:coverage
Statement Coverage	93.65%	≥80%	✅ Pass	pnpm test:coverage
Mutation Score	N/A	≥80%	⏳ Pending	pnpm mutation-test

Code Quality Metrics

Metric	Current	Threshold	Status	Local Command
Code Duplication	0%	<2%	✅ Pass	pnpm duplication
Cyclomatic Complexity	Max 10	≤10	✅ Pass	pnpm lint
Max Function Lines	Max 50	≤50	✅ Pass	pnpm lint
Max Function Parameters	Max 4	≤4	✅ Pass	pnpm lint
Max Nesting Depth	Max 3	≤3	✅ Pass	pnpm lint
Circular Dependencies	0	0	✅ Pass	pnpm deps:circular
Dead Code	0	0	✅ Pass	pnpm dead-code

Security Metrics

Metric	Status	Tool	Local Command
Critical Vulnerabilities	✅ 0	pnpm audit	pnpm audit
High Vulnerabilities	✅ 0	OSV Scanner	CI only
CodeQL Findings	✅ 0	CodeQL	CI only
Container Vulnerabilities	✅ 0	Trivy	pnpm scan:container

Build & Dependencies

Metric	Status	Tool	Local Command
TypeScript Compilation	✅ Pass	tsc	pnpm typecheck
ESLint Violations	✅ 0	ESLint	pnpm lint
Prettier Formatting	✅ Pass	Prettier	pnpm format
Workflow Validation	✅ Pass	actionlint	pnpm lint:workflows

Tools & Analyzers Used

• Coverage: Vitest with V8 coverage provider
• Mutation Testing: Stryker Mutator (JavaScript/TypeScript)
• Duplication: jscpd (Copy/Paste Detector)
• Complexity: ESLint with complexity rules
• Circular Deps: madge (dependency graph analyzer)
• Dead Code: Knip (unused exports, files, dependencies, types)
• Security: pnpm audit, OSV Scanner, CodeQL, Trivy
• Type Safety: TypeScript strict mode + type-aware ESLint rules

Note: Metrics are auto-updated on every push to main as part of the build workflow. The quality-metrics.json file is committed automatically after validation completes.

🎯 Quality Standards

This project enforces strict quality standards to ensure maintainability, security, and reliability:

Why These Standards?

80% Coverage Minimum - Ensures comprehensive test coverage without requiring 100% (which can lead to diminishing returns)

Low Complexity Limits - Functions with cyclomatic complexity >10 are harder to understand, test, and maintain

Zero Duplication Target - DRY principle reduces maintenance burden and bugs

No Circular Dependencies - Prevents tight coupling and enables better modularity

No Dead Code - Keeps codebase lean and maintainable

Zero Critical/High Vulnerabilities - Security-first approach protects users and infrastructure

Complexity Rationale

Limit	Rationale
Cyclomatic Complexity ≤10	Industry standard for maintainable code (NIST, IEEE)
Max 50 Lines/Function	Single screen view improves comprehension
Max 4 Parameters	Reduces cognitive load, encourages better abstractions
Max 3 Nesting Depth	Prevents deeply nested code that's hard to reason about
Max 15 Statements	Forces function decomposition, improves testability
Code Duplication <2%	Minimal threshold allowing for small necessary repetition
Mutation Score ≥80%	Ensures tests actually verify behavior, not just achieve coverage

Test File Exceptions

Test files (tests/**/*.ts) have relaxed limits:

• Cyclomatic complexity: ≤15 (vs 10)
• Max lines per function: ≤600 (vs 50) - allows large describe blocks with many test cases

Pre-commit Quality Gates

The pnpm precommit command runs checks in optimized order for fast feedback:

1. Security (pnpm audit) - Blocks commits with critical vulnerabilities
2. Formatting (pnpm format) - Fast, easy to fix
3. YAML/Markdown Linting - Fast file validation
4. Workflow Validation - Prevents broken GitHub Actions
5. Type Checking (pnpm typecheck) - Required for type-aware lint rules
6. Linting (pnpm lint) - Comprehensive quality checks
7. Structural Analysis - Circular deps, duplication, dead code
8. Tests with Coverage (pnpm test:coverage) - Slowest check runs last

Mutation testing is excluded from pre-commit due to performance - run it periodically (weekly/monthly).

🤖 AI Tool Integration

This project includes special configurations for AI development tools:

Custom Commands (OpenCode)

• /spec-feature - Create a Gherkin feature specification as a GitHub issue
• /implement-github-issue - Full issue-to-PR workflow: branch, code, tests, changeset, PR
• /update-dependencies - Curated dependency updates with PR workflow

The commands live in .opencode/commands/ and the project config in .opencode/opencode.json, which injects this repo's docs as agent instructions and denies force-pushes and --no-verify bypasses.

Git Hooks

• Prevents bypassing verification with --no-verify flag
• Ensures all commits pass quality checks

See AGENTS.md for project conventions and quality gates.

📁 Project Structure

.
├── .github/           # GitHub Actions workflows
├── docs/              # Documentation
├── src/               # Source code
├── tests/             # Test files
│   ├── *.spec.ts      # Unit tests
│   └── *.property.spec.ts # Property-based tests
├── mise.toml          # Tool version management
├── package.json       # Dependencies and scripts
└── tsconfig.json      # TypeScript configuration

🔄 Features

Configuration & Environment

• 🔐 Type-safe configuration with Zod validation
• 🔌 Configurable logging output - Redirect logs to stderr, files, syslog, or disable entirely (see docs/LOGGING_OUTPUT.md)
• 🔐 Environment validation at startup with clear errors
• 🔐 Sensitive value masking in error messages
• 📝 See docs/CONFIG.md for configuration guide

Testing & Quality

• ✅ Vitest with property-based testing (fast-check)
• ✅ 80% coverage minimum enforced
• ✅ Strict TypeScript with type-aware linting
• ✅ Pre-commit hooks with Husky & lint-staged
• ✅ Markdown and YAML linting for docs/config consistency

Security & Supply Chain

• 🔒 CodeQL static analysis
• 🔒 OSV Scanner for dependencies
• 🔒 SBOM generation (CycloneDX)
• 🔒 SLSA attestations for artifacts

Automation

• 🚀 GitHub Actions CI/CD pipeline
• 🚀 Changesets for versioning
• 🚀 Automated releases with changelog

⚙️ Required Setup

GitHub Repository Settings

Actions permissions (Settings → Actions → General):

• ✅ Read and write permissions
• ✅ Allow GitHub Actions to create and approve pull requests

Auto-merge (Settings → General → Pull Requests):

• ✅ Allow auto-merge
• ✅ Automatically delete head branches

For automated releases, add secrets:

• RELEASE_TOKEN - GitHub PAT with repo/workflow scopes (triggers publish workflow)
• NPM_TOKEN - For npm publishing (optional)

📦 Release Distribution Setup

NPM Publishing

To enable npm publishing:

1. Add NPM_TOKEN secret in repository settings
2. Remove "private": true from package.json
3. Use a scoped package name: @yourorg/package-name

Docker Publishing

⚠️ Important: The default Dockerfile includes a healthcheck that expects a web server with a /health endpoint on port 3000. See Docker Configuration Guide for detailed instructions on configuring healthchecks for different application types (web services, CLI tools, workers).

To enable Docker builds:

1. Set repository variable ENABLE_DOCKER_RELEASE to true
2. Add secrets for Docker Hub (optional):
   • DOCKERHUB_USERNAME
   • DOCKERHUB_TOKEN
3. Images are automatically pushed to GitHub Container Registry

🔒 Security Features

• Dependency Auditing: Critical vulnerability checks on every CI run
• SBOM Generation: CycloneDX format for supply chain transparency
• CodeQL Analysis: Static security analysis
• OSV Scanning: Open Source Vulnerability detection
• SLSA Provenance: Build attestations
• Container Attestations: SBOM and provenance for Docker images

📚 Additional Resources

• Contributing Guide - How to contribute to this project
• Development Process - End-to-end workflow and checklists
• Architecture Decisions - ADR records

📄 License

This is a template repository. Feel free to use it for your projects.