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.
2026-05-06 19:49:58 +02:00
parent 6bf19f35c5
commit 8f34daca36
6 changed files with 99 additions and 43 deletions
--- a/docs/architecture/data-flow-explainer.html
+++ b/docs/architecture/data-flow-explainer.html
@@ -1338,7 +1338,8 @@ footer .colophon {
      <span class="tree-row" data-layer="di">    <span class="dim">├─</span> symbols.ts<span class="dim">            ← inversify Symbol.for(...) keys</span></span>
      <span class="tree-row" data-layer="di">    <span class="dim">├─</span> module.ts<span class="dim">             ← ContainerModule with .toDynamicValue</span></span>
      <span class="tree-row" data-layer="di">    <span class="dim">├─</span> container.ts<span class="dim">          ← Container + .load(Module)</span></span>
-      <span class="tree-row" data-layer="di">    <span class="dim">└─</span> bind-production.ts<span class="dim">    ← swaps mocks → real impls at boot</span></span>
+      <span class="tree-row" data-layer="di">    <span class="dim">├─</span> bind-production.ts<span class="dim">    ← swaps mocks → real impls at boot</span></span>
+      <span class="tree-row" data-layer="di">    <span class="dim">└─</span> bind-dev-seed.ts<span class="dim">       ← swaps empty mocks → populated mocks</span></span>
      <span class="tree-row" data-layer="integrations"><span class="dim">├─</span> integrations/</span>
      <span class="tree-row" data-layer="integrations">    <span class="dim">├─</span> api/</span>
      <span class="tree-row" data-layer="integrations">    <span class="dim">│   ├─</span> procedures.ts<span class="dim">     ← xProcedure + defineErrorMiddleware</span></span>
@@ -1349,6 +1350,7 @@ footer .colophon {
      <span class="tree-row" data-layer="ui">    <span class="dim">└─</span> query.ts<span class="dim">              ← React Query option builders</span></span>
      <span class="tree-row" data-layer="testing"><span class="dim">├─</span> __factories__/<span class="dim">           ← defineFactory&lt;Entity&gt;((seq)=&gt;{...})</span></span>
      <span class="tree-row" data-layer="testing"><span class="dim">├─</span> __contracts__/<span class="dim">           ← defineContractSuite&lt;IRepo&gt;(...)</span></span>
+      <span class="tree-row" data-layer="seeds"><span class="dim">├─</span> __seeds__/<span class="dim">               ← buildDev&lt;Entities&gt;() — dev-mode realistic data</span></span>
      <span class="tree-row" data-layer="public"><span class="dim">└─</span> index.ts<span class="dim">                  ← root: contracts only</span></span>
    </div>

@@ -1854,8 +1856,14 @@ const LAYERS = {
  di: {
    tag: "wiring",
    title: "DI — <em>per-feature</em> container",
-    body: "Symbols are <code>Symbol.for(\"&lt;feature&gt;:I&lt;X&gt;\")</code> keys. The <code>ContainerModule</code> wires them: the repository to its mock by default; use cases and controllers via <code>.toDynamicValue</code> so their factory functions are constructed on every <code>container.get()</code>. <code>bind-production.ts</code> swaps the mock for the real impl at app boot using <code>.toConstantValue</code>.",
-    meta: "Files · symbols.ts · module.ts · container.ts · bind-production.ts"
+    body: "Symbols are <code>Symbol.for(\"&lt;feature&gt;:I&lt;X&gt;\")</code> keys. The <code>ContainerModule</code> wires them: the repository to its mock by default; use cases and controllers via <code>.toDynamicValue</code> so their factory functions are constructed on every <code>container.get()</code>. Three binders sit alongside: <code>bind-production.ts</code> swaps the mock for the real Payload impl, <code>bind-dev-seed.ts</code> swaps the empty mock for a populated one. App boot's <code>bindAll()</code> picks one based on <code>USE_DEV_SEED</code> + <code>NODE_ENV</code>. See the dedicated <a href=\"di-explainer.html\">DI explainer page</a> for the full lifecycle.",
+    meta: "Files · symbols.ts · module.ts · container.ts · bind-production.ts · bind-dev-seed.ts"
+  },
+  seeds: {
+    tag: "dev ergonomics",
+    title: "<em>__seeds__/</em> — dev-mode data",
+    body: "A lazy <code>buildDev&lt;Entities&gt;()</code> function per feature, built on top of the feature's existing factory. The dev-seed binder calls it to populate a <code>MockXRepository</code> at app boot when <code>USE_DEV_SEED=true</code> or <code>NODE_ENV ≠ 'production'</code>. Tests never touch this file — they construct mocks and seed via factories per-test.",
+    meta: "Powered by · the feature's __factories__ · consumed by di/bind-dev-seed.ts"
  },
  integrations: {
    tag: "outside world",
@@ -1878,8 +1886,8 @@ const LAYERS = {
  public: {
    tag: "package.json exports",
    title: "<em>index.ts</em> — the public surface",
-    body: "Five subpaths per feature: <code>.</code> (contracts: types, errors, schemas, IUseCase / IController aliases, router type, constants), <code>./ui</code> (queries + components), <code>./api</code> (the tRPC router — only <code>core-api</code> consumes it), <code>./cms</code> (Payload collections — only <code>core-cms</code> consumes), <code>./di/bind-production</code> (called by app boot). Anything else is private.",
-    meta: "Five subpaths · enforced by ESLint boundaries + Turborepo + the package.json exports map"
+    body: "Six subpaths per feature: <code>.</code> (contracts: types, errors, schemas, IUseCase / IController aliases, router type, constants), <code>./ui</code> (queries + components), <code>./api</code> (the tRPC router — only <code>core-api</code> consumes it), <code>./cms</code> (Payload collections — only <code>core-cms</code> consumes), <code>./di/bind-production</code> (production binder, called by app boot), <code>./di/bind-dev-seed</code> (dev-seed binder, also called by app boot or by storybook). Anything else is private.",
+    meta: "Six subpaths · enforced by ESLint boundaries + Turborepo + the package.json exports map"
  }
 };

--- a/docs/architecture/vertical-feature-spec.md
+++ b/docs/architecture/vertical-feature-spec.md
@@ -198,6 +198,8 @@ packages/blog/
      module.ts                                     # ContainerModule — .toDynamicValue() for use cases + controllers
      container.ts                                  # blogContainer singleton
      bind-production.ts                            # swaps mock → real Payload impls at app boot
+      bind-dev-seed.ts                              # swaps empty mock → populated mock for dev mode (post-Plan-9)
+      bind-dev-seed.test.ts
      container.test.ts

    integrations/                                   # renamed from spec's adapters/
@@ -223,12 +225,15 @@ packages/blog/
    __contracts__/
      articles-repository.contract.ts              # repo interface contract suite (Plan 7)

+    __seeds__/
+      dev.ts                                        # buildDev<Entities>() — uses factory; consumed by bind-dev-seed (post-Plan-9)
+
    index.ts                                        # contracts only: types, errors, schemas, IUseCase/IController aliases, router type, constants

  tests/
    article-by-slug.feature.test.ts                 # cross-layer integration test

-  package.json                                      # exports: ".", "./ui", "./api", "./cms", "./di/bind-production"
+  package.json                                      # exports: ".", "./ui", "./api", "./cms", "./di/bind-production", "./di/bind-dev-seed"
  tsconfig.json
  turbo.json                                        # tags: ["feature"]
 ```
--- a/docs/superpowers/refactor-logs/2026-05-06-input-output-unification.md
+++ b/docs/superpowers/refactor-logs/2026-05-06-input-output-unification.md
@@ -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).