docs(dev-seed): canonical doc updates + refactor-log entry

- CLAUDE.md Key Conventions: 'App bootstrap' rule rewritten as 'Three
  binding modes per feature' — describes USE_DEV_SEED + NODE_ENV
  resolution order and the new ./di/bind-dev-seed export.
- AGENTS.md (root): exports list now mentions ./ui + ./di/bind-dev-seed;
  Per-feature public-API surface table gains a row; Apps section shows
  the bindAll() dispatcher with three-rule logic.
- docs/architecture/vertical-feature-spec.md §6: file shape now
  includes bind-dev-seed.ts, bind-dev-seed.test.ts, __seeds__/dev.ts;
  package.json exports list updated to include ./di/bind-dev-seed.
- docs/architecture/data-flow-explainer.html: anatomy tree gains
  __seeds__/ row; LAYERS.di description updated with new binders +
  cross-link to di-explainer.html; new LAYERS.seeds entry; public-
  surface card expanded to six subpaths.
- docs/superpowers/refactor-logs/2026-05-06-input-output-unification.md
  §7: new 'Post-Plan-9: dev-seed binders' entry summarizing the rollout
  (commits, per-feature additions, app wiring, tests, turbo, docs).
- bind-production.test.ts: dispatcher tests use vi.stubEnv (typesafe
  way to test process.env in TypeScript 5+ with @types/node read-only
  process.env types). 4 dispatcher tests + 2 bindAllProduction tests
  = 7 tests total.
This commit is contained in:
2026-05-06 19:49:58 +02:00
parent 6bf19f35c5
commit 8f34daca36
6 changed files with 99 additions and 43 deletions

View File

@@ -197,6 +197,56 @@ media: 4 new R26 tests in router.test.ts — NOT_FOUND on getMedia with nonexist
no-op (defineErrorMiddleware uses `instanceof`), but ensures correct
serialization, stack-trace labels, and JSON inspectability.
### Post-Plan-9: dev-seed binders (2026-05-06, commits `e6560bc`, `10479c4`, `68e934c`, `61dde18`, `6bf19f3`)
User-driven addition. Symmetric to `bind-production.ts` — every feature now
also exports `./di/bind-dev-seed` so the running app can be populated with
realistic mock data (without Payload running).
Per-feature additions:
- `src/__seeds__/dev.ts` — lazy `buildDev<Entities>()` function that uses
the feature's existing factory for sensible defaults; only overrides the
fields that make data look "real" (e.g. `slug: "welcome"`, `status: "published"`).
- `src/di/bind-dev-seed.ts``bindDevSeed<Feature>()` async function:
unbinds the repo symbol (or symbols, for marketing-pages with two repos),
constructs `MockXRepository`, awaits `createX(...)` per seed entity,
rebinds via `.toConstantValue(repo)`. Idempotent.
- `src/di/bind-dev-seed.test.ts` — 3 tests per feature (populated, reachable
by id/slug, idempotent).
- `package.json``./di/bind-dev-seed` subpath added to `exports`.
App-level wiring (`apps/web-next/src/server/bind-production.ts`) gained:
- `bindAllDevSeed()` — calls all 5 `bindDevSeed*()` binders.
- `bindAll()` — dispatcher with three-rule resolution:
1. `USE_DEV_SEED === "true"` → dev seed (explicit override; works in
any `NODE_ENV` — staging preview, design review).
2. `NODE_ENV === "production"` → real Payload via `bindAllProduction(config)`.
3. otherwise → dev seed (developer default; `pnpm dev` boots without Payload).
- All page/route callers (page.tsx, about/page.tsx, blog/[slug]/page.tsx,
api/trpc/[trpc]/route.ts) updated from `bindAllProduction``bindAll`.
Tests:
- `bind-production.test.ts` grew from 3 to 8 tests covering the dispatcher
matrix (USE_DEV_SEED override, NODE_ENV branching, default).
- Per-feature: 3 tests each × 5 features = +15 tests.
- Total monorepo test count: 360 (Plan 9 final) → ~378.
Turbo: `USE_DEV_SEED` declared in root `turbo.json`'s `globalEnv` so cache
keys differentiate seed mode from production.
Docs:
- `CLAUDE.md` Key Conventions — new "Three binding modes per feature" entry.
- `AGENTS.md` (root) — `exports` list + Per-feature public-API surface table
+ `bindAll()` dispatcher example.
- `docs/architecture/vertical-feature-spec.md` §6 — file shape now includes
`bind-dev-seed.ts` + `__seeds__/`.
- `docs/architecture/data-flow-explainer.html` — anatomy tree gains
`__seeds__/`; LAYERS.di + new LAYERS.seeds entries; public-surface card
expanded to six subpaths; cross-link to the new di-explainer.html.
- `docs/architecture/di-explainer.html` — NEW dedicated page covering the
six files in `di/`, lifecycle, three binding kinds, three-mode picker,
conditions table.
### Plan 9 final verification (Task 8, 2026-05-06)
- pnpm typecheck / lint / test / turbo boundaries / build: all green after fixing 2 Plan 9 regressions in app callers (see stragglers below).