diff --git a/docs/guides/runbook.md b/docs/guides/runbook.md new file mode 100644 index 0000000..c4fa253 --- /dev/null +++ b/docs/guides/runbook.md @@ -0,0 +1,283 @@ +# Developer Runbook + +You just cloned this repo. This is the only doc you need to read end-to-end. Everything else is reference. + +--- + +## Prerequisites + +| Tool | Version | Why | +| ------- | ------- | ------------------------------------- | +| Node.js | 22+ | Runtime for all apps + scripts | +| pnpm | 9+ | Package manager (workspace-aware) | +| Docker | 24+ | Local Postgres + sandcastle sandboxes | +| Git | 2.40+ | Version control + worktrees | + +Recommended editor: VS Code or Cursor with the official TypeScript, ESLint, and Prettier extensions. + +--- + +## First-time setup + +```bash +# 1. Clone + install +git clone template-vertical +cd template-vertical +pnpm install + +# 2. Start Postgres (background) +docker compose up -d + +# 3. Copy env template and fill in secrets +cp .env.example .env +# Edit .env (see "Environment variables" section below for what each one does) + +# 4. Verify the gate stack is green +pnpm typecheck +pnpm test +pnpm lint +pnpm conformance +pnpm fallow +pnpm turbo boundaries +``` + +All six should exit 0. If any fails on a fresh clone, file an issue — the main branch is supposed to stay green. + +```bash +# 5. Start the dev servers +pnpm dev +``` + +This runs Next.js (3000), Payload CMS (3001), TanStack Start (3002), and Storybook (6006) in parallel. The `bindAll()` dispatcher in each app picks the dev-seed binders by default (mock repositories, no Payload connection needed beyond Postgres). + +--- + +## Daily commands + +```bash +# Development +pnpm dev # all dev servers +pnpm dev --filter @repo/web-next # one app + +# Tests +pnpm test # everything +pnpm test --filter @repo/auth # one package +pnpm test:e2e # Playwright e2e +pnpm test:stories # Storybook smoke tests +pnpm test:visual # visual regression (Playwright screenshots) + +# Linting + type checking +pnpm typecheck # tsc across all packages +pnpm lint # ESLint across all packages +pnpm format # Prettier write +pnpm format:check # Prettier check (CI mode) + +# Conformance gates +pnpm conformance # cross-feature event closure +pnpm fallow # whole-codebase: dead exports, dupes, complexity +pnpm fallow:audit # AI-change audit (run before commits) + +# Boundary validation +pnpm turbo boundaries # workspace dependency graph + +# Work system +pnpm work status # tree of epics + stories +pnpm work next # next ready story +pnpm work ready # all ready stories +pnpm work blocked # blocked stories + what they wait on +pnpm work rebuild-state # regenerate docs/work/_state.json +pnpm work dispatch # print next dispatch plan +pnpm work dispatch --execute # invoke sandcastle (requires ANTHROPIC_API_KEY) +``` + +--- + +## Environment variables + +Copy `.env.example` to `.env` and fill what you need. NOT every variable is required for `pnpm dev` — defaults are dev-friendly. + +### Required for `pnpm dev` + +| Var | Example | Why | +| ---------------- | -------------------------------------------------------- | -------------------------------------------------------------- | +| `DATABASE_URL` | `postgresql://postgres:postgres@localhost:5433/template` | Postgres connection (docker compose default) | +| `PAYLOAD_SECRET` | `your-secret-here` | Payload CMS encryption key (any random 32+ char string in dev) | + +### Optional — app URLs (defaults work in dev) + +| Var | Default | Why | +| --------------------- | ----------------------- | ------------------------------------------------------ | +| `NEXT_PUBLIC_APP_URL` | `http://localhost:3000` | Public-facing web-next URL | +| `CMS_URL` | `http://localhost:3001` | Payload CMS URL | +| `USE_DEV_SEED` | `true` in dev | Force dev-seed binders (mock repos) instead of Payload | +| `NODE_ENV` | inherited | `production` flips bind dispatcher to real Payload | + +### Optional — Sentry observability (no DSN = no-op tracer/logger) + +| Var | Why | +| ----------------------------------------------------- | ------------------------------------------------- | +| `WEB_NEXT_SENTRY_DSN` | Server-side OTel + Sentry for web-next | +| `NEXT_PUBLIC_WEB_NEXT_SENTRY_DSN` | Browser Sentry for web-next | +| `CMS_SENTRY_DSN` | Server-side for Payload CMS | +| `WEB_TANSTACK_SENTRY_DSN` | Server-side for TanStack Start | +| `VITE_WEB_TANSTACK_SENTRY_DSN` | Browser-side for TanStack Start | +| `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, `SENTRY_PROJECT_*` | Source-map upload at build time | +| `SENTRY_TRACES_SAMPLE_RATE` | OTel trace sample rate (`0.1` recommended in dev) | +| `SENTRY_ENVIRONMENT` | `development` / `staging` / `production` | + +### Optional — Git commit SHA for releases + +| Var | Why | +| ------------------------------------------------------------------------------------- | --------------------------------------------------- | +| `VERCEL_GIT_COMMIT_SHA` / `VITE_GIT_COMMIT_SHA` / `NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA` | Surfaces commit SHA in Sentry releases + UI footers | + +### Optional — core-audit (only when `gen core-package audit` is scaffolded) + +| Var | Why | +| ---------------------- | -------------------------------------------------------------------------------------------------- | +| `AUDIT_PSEUDONYM_SALT` | Salt for the audit log's GDPR-erasure pseudonymisation (production only — must be a stable secret) | + +### Optional — sandcastle dispatch (only when running `pnpm work dispatch --execute`) + +| Var | Why | +| --------------------- | ------------------------------------------------- | +| `ANTHROPIC_API_KEY` | Claude API key (sandcastle's default agent) | +| `OPENAI_API_KEY` | OpenAI/Codex alternative | +| `GITHUB_TOKEN` | GitHub access for PR creation by the orchestrator | +| `SANDCASTLE_PROVIDER` | `docker` (default) / `podman` / `vercel` | + +--- + +## The agent-first workflow + +This template enforces a **manifest-first, generator-driven, gate-protected** workflow. + +### When adding a new feature + +```bash +pnpm turbo gen feature +``` + +This emits: + +- `packages//src/feature.manifest.ts` — the conformance manifest (use cases, audits, publishes, consumes) +- `packages//src/di/bind-production.ts` with `assertFeatureConformance(...)` at the tail (refuses to boot on drift) +- Mock repository, factory, seed, entity, use-case, controller, tests — full Lazar-conformant shape +- `packages//src/index.ts` exports + +After scaffolding, the four-step ordering for any new use case: + +1. **Manifest entry** — declare the use case in `feature.manifest.ts` +2. **Contracts** — export `xInputSchema`, `xOutputSchema`, `IXUseCase` (factory body throws `not implemented`) +3. **Tests (red)** — write the failing test +4. **Implementation (green)** — fill the factory body + +The five conformance gates catch drift at every step. See `docs/guides/conformance-quickref.md` for the manifest field reference. + +### When adding cross-feature primitives + +```bash +pnpm turbo gen event # event contract or handler (needs gen core-package events) +pnpm turbo gen job # background job +pnpm turbo gen realtime # realtime channel or handler (needs gen core-package realtime) +pnpm turbo gen core-package # optional core package (events/realtime/trpc/ui/audit) +pnpm turbo gen core-ui-component # atomic-design component (needs gen core-package ui) +``` + +**Always prefer generators over hand-rolling.** The generators emit the canonical shape; hand-rolled code drifts from generator output and breaks the CI scaffold-drift check. + +### Tracking work + +The repo uses `docs/work/` for epic/story/task tracking: + +``` +docs/work/ +├── README.md +├── _state.json # derived, regenerated by pre-commit hook +├── prds/ # PRDs go here +├── _templates/ # markdown templates +└── / + ├── _epic.md + └── / + └── _story.md # contains the Tasks checklist +``` + +Use `pnpm work next` to see what's ready. Use `pnpm work dispatch` to plan the next sandcastle dispatch. + +--- + +## The five conformance gates + +| Gate | Latency | What it catches | Runs when | +| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------ | --------------------- | +| TypeScript brands | 0s | forgotten `withSpan` / `withCapture` / `withAudit`; manifest ↔ binding-slot type mismatch | on save (IDE) | +| ESLint (8 conformance/\* rules) | <1s | manifest ↔ code drift; missing sibling test; missing manifest; atomic-tier import direction | on save / `pnpm lint` | +| Boot assertion | ~3s | runtime binding without required brand; manifest edited without rebinder | `pnpm dev` startup | +| `pnpm conformance` | ~120s | orphan event consumers across features | CI | +| `pnpm fallow` | ~30–60s | dead exports / unused files; duplicate code; circular deps; complexity hotspots; AI-change audit | CI | + +For the full design see `docs/architecture/agent-first-workflow-and-conformance.md`. For the daily reference see `docs/guides/conformance-quickref.md`. + +--- + +## Troubleshooting + +**`pnpm dev` refuses to boot with `ConformanceError`** +— A feature's binding lost a required brand. The error message tells you which use case + which brand. Re-bind through `withSpan` / `withCapture` / `withAudit` as needed. + +**`pnpm lint` errors with `conformance/feature-must-have-manifest`** +— You created a feature with use cases but no `feature.manifest.ts`. Run `pnpm turbo gen feature ` to scaffold the canonical shape, or hand-write the manifest at `packages//src/feature.manifest.ts`. + +**`pnpm conformance` says "orphan consumer"** +— A feature declares `consumes: ["X"]` but no feature publishes `X`. Either add the publish to the producing feature's manifest + factory, or remove the consumer. + +**`pnpm fallow` reports new dead exports or dupes** +— Your change added unused exports or duplicated logic. Either remove the dead code or accept with `pnpm fallow:audit --gate all` (the audit considers the baseline; only NEW findings fail). + +**Pre-commit hook refuses to commit with "state-sync-guard"** +— You staged `docs/work/_state.json` but it's not byte-identical to `pnpm work rebuild-state` output. Run `pnpm work rebuild-state && git add docs/work/_state.json` and try again. + +**Tests fail in `@repo/turbo-generators` with Vitest worker timeouts** +— Known flaky on slow machines. Re-run; if persistent, increase the `turbo-generators` package's vitest `testTimeout`. + +**`pnpm work dispatch --execute` errors with "ANTHROPIC_API_KEY required"** +— You're trying to run the sandcastle orchestrator without an agent API key. Set the env var, or run `pnpm work dispatch` (no flag) to just print the plan. + +--- + +## Where to read next + +Once you've got `pnpm dev` running: + +1. **`AGENTS.md`** — package map, boundary rules, per-package conventions +2. **`CLAUDE.md`** — full convention reference (manifest-first ordering, factory patterns, instrumentation rules) +3. **`docs/guides/conformance-quickref.md`** — daily manifest + gates reference +4. **`docs/guides/tdd-workflow.md`** — red-green-refactor with the gate stack +5. **`docs/guides/scaffolding-a-feature.md`** — `pnpm turbo gen feature` reference +6. **`docs/guides/adding-a-feature.md`** — end-to-end walkthrough +7. **`docs/architecture/agent-first-workflow-and-conformance.md`** — the full design +8. **`docs/architecture/feature-conformance-explainer.html`** — interactive explainer (open in browser) + +For deeper topics: + +- **`docs/guides/events-and-jobs.md`** — cross-feature events (requires `gen core-package events`) +- **`docs/guides/realtime.md`** — Socket.IO channels (requires `gen core-package realtime`) +- **`docs/guides/audit-and-compliance.md`** — DPA-compliant audit logging (requires `gen core-package audit`) +- **`docs/guides/frontend-work-shape.md`** — atomic design + Storybook conventions +- **`docs/guides/infrastructure-work-shape.md`** — ADR-first flow for new infrastructure + +--- + +## Common pitfalls + +- **Skipping the generator.** Always run `pnpm turbo gen ` before hand-rolling. Generators emit the canonical shape; the CI scaffold-drift check will fail on hand-rolled features. +- **Forgetting `pnpm work rebuild-state` after editing `docs/work/` markdown.** The pre-commit hook handles this automatically when you stage markdown; only matters if you push without committing. +- **Bypassing `--no-verify` on commits.** The pre-commit hook catches drift early. If it's blocking a legitimate change, fix the underlying issue, not the hook. +- **Hand-editing `_state.json`.** Don't. The state-sync-guard refuses commits that drift from rebuild output. Edit the markdown; let the rebuild script propagate. +- **Committing `.env`.** It's gitignored. Use `.env.example` for new vars. + +--- + +For deeper philosophy: this template is built around the assumption that **AI agents will author most feature work**. The conformance system is designed as an agent feedback loop. Latency-layered gates compound: 0s + <1s + 3s + 120s + 60s. The faster the inner loop, the more iterations agents can make per task. + +If you're a human contributor, the same workflow applies — the gates aren't punitive, they're navigational aids.