From ee069574baaef16283abeba39fac10737f92f197 Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Sat, 9 May 2026 15:01:40 +0200 Subject: [PATCH] fix: address final-review polish (docs + comments + test coverage) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - AGENTS.md bind-production code block: shows the slim default state (no @repo/core-events / @repo/core-realtime imports, BindProductionContext with no generic args) with a comment pointing to the scaffold workflow. The previous block showed a fully-wired post-scaffold state without signaling that none of those packages exist in main. - bind-protocols.test.ts: top-of-file comment clarifies what these tests actually verify (protocol shapes have required methods) vs what the spec text might suggest (full assignability of optional packages' interfaces — that's verified by the e2e reconstruction tests, not here). - core-package-generator.md: drops two stale "Until Phases 3-6 land" parentheticals — the phases shipped. - config.test.ts: extends the choices assertion to cover all 4 names (realtime, events, trpc, ui). - marketing-pages bind-* comments: reverse the inverted optional/required language. queue (IJobQueue) is from core-shared and always present; bus is the optional one (from @repo/core-events when scaffolded). Co-Authored-By: Claude Opus 4.7 (1M context) --- AGENTS.md | 21 +++++++------------ docs/scaffolding/core-package-generator.md | 2 -- .../core-shared/src/di/bind-protocols.test.ts | 8 +++++++ .../marketing-pages/src/di/bind-dev-seed.ts | 3 ++- .../marketing-pages/src/di/bind-production.ts | 3 ++- turbo/generators/config.test.ts | 2 ++ 6 files changed, 22 insertions(+), 17 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b8244f3..cf85d94 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -321,24 +321,21 @@ Each app (`web-next`, `web-tanstack`, `cms`) imports both binders per feature an ```typescript // apps/web-next/src/server/bind-production.ts +// Slim default template — no optional packages scaffolded yet. +// After running e.g. `pnpm turbo gen core-package events`, the full +// IEventBus type can be plugged via the generic args +// `BindProductionContext` and the bus/queue construction +// (resolveEventsAndJobsProduction) wires back in per the printed next-steps. import type { BindProductionContext, BindContext } from "@repo/core-shared/di"; -import type { IEventBus } from "@repo/core-events"; -import type { IRealtimeBroadcaster, IRealtimeHandlerRegistry } from "@repo/core-realtime"; -export async function bindAllProduction(deps: BindAllDeps): Promise { +export async function bindAllProduction(): Promise { const { tracer, logger } = resolveInstrumentation(); - const { bus, queue } = await resolveEventsAndJobsProduction(); const resolvedConfig = await config; - const { realtime, realtimeRegistry } = deps; - const ctx: BindProductionContext = { + const ctx: BindProductionContext = { config: resolvedConfig, tracer, logger, - bus, - queue, - realtime, - realtimeRegistry, }; bindProductionAuth(ctx); @@ -348,10 +345,8 @@ export async function bindAllProduction(deps: BindAllDeps): Promise { bindProductionMedia(ctx); } -export async function bindAllDevSeed(deps: BindAllDeps): Promise { +export async function bindAllDevSeed(): Promise { const { tracer, logger } = resolveInstrumentation(); - const { bus, queue } = resolveEventsAndJobsDevSeed(); - const { realtime, realtimeRegistry } = deps; const ctx: BindContext = { tracer, logger, bus, queue, realtime, realtimeRegistry, diff --git a/docs/scaffolding/core-package-generator.md b/docs/scaffolding/core-package-generator.md index a4ebd57..115bcea 100644 --- a/docs/scaffolding/core-package-generator.md +++ b/docs/scaffolding/core-package-generator.md @@ -24,8 +24,6 @@ The generator emits the package files, updates consuming-app config (e.g. `apps/ | `trpc` | tRPC server setup | Phase 5 | | `ui` | Design-system package | Phase 6 | -(Until Phases 3-6 land, the generator will list an empty choices array and reject any selection.) - ## Verifying an existing project If your project already has a core-* package and you want to verify the generator's template hasn't drifted from the shipped source, use the byte-identical reconstruction snapshot: diff --git a/packages/core-shared/src/di/bind-protocols.test.ts b/packages/core-shared/src/di/bind-protocols.test.ts index 2d2bbec..90a5783 100644 --- a/packages/core-shared/src/di/bind-protocols.test.ts +++ b/packages/core-shared/src/di/bind-protocols.test.ts @@ -5,6 +5,14 @@ import type { RealtimeRegistryProtocol, } from "./bind-protocols"; +// Protocol-shape tests. These verify each protocol type EXPORTS the +// expected method names. Full assignability of `IEventBus` / +// `IRealtimeBroadcaster` / `IRealtimeHandlerRegistry` to their respective +// protocols is verified at the optional-package level — when those packages +// are scaffolded back via `pnpm turbo gen core-package `, the +// `extends`-link in their interface declarations forces a typecheck +// failure if the protocol surface ever drifts. + describe("EventBusProtocol", () => { it("requires publish(event, payload) and subscribe(event, consumer, handler)", () => { type Bus = EventBusProtocol; diff --git a/packages/marketing-pages/src/di/bind-dev-seed.ts b/packages/marketing-pages/src/di/bind-dev-seed.ts index 5fb97bb..a563570 100644 --- a/packages/marketing-pages/src/di/bind-dev-seed.ts +++ b/packages/marketing-pages/src/di/bind-dev-seed.ts @@ -139,7 +139,8 @@ export async function bindDevSeedMarketingPages(ctx: BindContext): Promise // // onAuthUserSignedUpHandler subscription — generated, edit the handler file (not this block) for behavior. - // queue is optional: guard so the handler is only bound when core-jobs is wired (Phase 3+). + // bus is optional: when @repo/core-events is not scaffolded, ctx.bus is undefined and the handler is not bound. + // queue (IJobQueue) is in core-shared and always provided; the inner if (queue) below is belt-and-suspenders. if (queue) { const wrappedAuthUserSignedUp = withSpan( tracer, diff --git a/packages/marketing-pages/src/di/bind-production.ts b/packages/marketing-pages/src/di/bind-production.ts index 4447753..de21601 100644 --- a/packages/marketing-pages/src/di/bind-production.ts +++ b/packages/marketing-pages/src/di/bind-production.ts @@ -129,7 +129,8 @@ export function bindProductionMarketingPages(ctx: BindProductionContext): void { // // onAuthUserSignedUpHandler subscription — generated, edit the handler file (not this block) for behavior. - // queue is optional: guard so the handler is only bound when core-jobs is wired (Phase 3+). + // bus is optional: when @repo/core-events is not scaffolded, ctx.bus is undefined and the handler is not bound. + // queue (IJobQueue) is in core-shared and always provided; the inner if (queue) below is belt-and-suspenders. if (queue) { const wrappedAuthUserSignedUp = withSpan( tracer, diff --git a/turbo/generators/config.test.ts b/turbo/generators/config.test.ts index 45a0e3e..025b026 100644 --- a/turbo/generators/config.test.ts +++ b/turbo/generators/config.test.ts @@ -17,6 +17,8 @@ describe("core-package generator", () => { expect(prompts[0]!.name).toBe("name"); expect(prompts[0]!.choices).toContain("realtime"); expect(prompts[0]!.choices).toContain("events"); + expect(prompts[0]!.choices).toContain("trpc"); + expect(prompts[0]!.choices).toContain("ui"); }); });