Skip to content

Checks: doctor and CI

stack doctor catches the mistakes that make a template silently generate broken projects. It runs in CI and before every release.

  1. Versions agree. package.json, .claude-plugin/plugin.json and every plugin entry in .claude-plugin/marketplace.json carry the same version.
  2. Every marker names a declared feature. A typo in a marker would silently delete code.
  3. Every feature’s files globs match something, and every requires names a declared feature.
  4. No text follows an HTML-comment marker (<!-- @feature x -->) on its line. A marker owns its whole line, so text after it is deleted with the line or kept for the wrong selection. Markdown is where this happens: the CLAUDE.md and skills every template ships.
  5. For every selection it tries (all features; the defaults; each default dropped along with everything that needs it; each opt-in added):
    • brackets still balance in every .ts file that carries markers, which is what a marker on the closing line of a multi-line construct breaks;
    • every JSON file still parses (comments and trailing commas allowed);
    • every import still resolves, including aliased ones through aliasRoots, so a barrel that re-exports a dropped module is caught.

It doesn’t try every combination of features: generate the ones you care about and build them (CI does that for the important ones).

.github/workflows/ci.yml runs on every pull request and push to main, and again as the first stage of every release:

Job Variants Runs
CLI, manifests and package stack doctor; check-package (every template file is in the npm package, nothing private leaks)
nest-api default, --all, without media, without observability, without users, minimal, without testing typecheck, build, lint, unit tests, and e2e tests against real Postgres and Redis services
node-worker default, --all, without pm2 typecheck, lint, format check, build
nest-monorepo default, --all, without the worker, without testing build, typecheck, lint across the workspace; the API’s unit and e2e tests
py-worker default, --with temporal byte-compile every module
react-app, react-monorepo default, --all typecheck, lint, build
next-site business site (default), --with shop, --all, minimal format check, typecheck, lint, build (without a database), and the integration tests against a real Postgres service
stack add nest-api + realtime, react-app + marketing, react-monorepo + app-admin, node-worker + temporal, py-worker + temporal, nest-monorepo + temporal, next-site + shop scripts/check-add.mjs: generate with the defaults, stack add the feature, and require the result to match stack new --with it exactly
stack upgrade every template in the latest published release scripts/check-upgrade.mjs: generate with the latest published release, stack upgrade with this checkout, and require the result to match a fresh stack new (.env compared by keys)
Docker images nest-api, node-worker, node-worker --with temporal, nest-monorepo’s API, nest-monorepo --all’s worker, next-site --with shop docker build
Docs build this site, including the env-coverage and link checks

Every job generates its project with --strict, so a failing install or format hook fails the job.