Checks: doctor and CI
stack doctor
Section titled “stack doctor”stack doctor catches the mistakes that make a template silently generate
broken projects. It runs in CI and before every release.
- Versions agree.
package.json,.claude-plugin/plugin.jsonand every plugin entry in.claude-plugin/marketplace.jsoncarry the same version. - Every marker names a declared feature. A typo in a marker would silently delete code.
- Every feature’s
filesglobs match something, and everyrequiresnames a declared feature. - 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: theCLAUDE.mdand skills every template ships. - 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
.tsfile 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.
- brackets still balance in every
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.