Danijel Martinek
c2a32363a8
gen event consume now emits a second file: an __events-<publisher>- <event>.task.ts Payload task that delegates to the consumer's container-resolved wrapped handler. The bind block also binds the wrapped handler into the per-feature container by symbol so the task can resolve it. With this, PayloadJobsEventBus is fully wired end-to-end with no manual per-event task hand-write required. Removes the corresponding Known Follow-up item. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3439 lines
117 KiB
Markdown
3439 lines
117 KiB
Markdown
# Cross-feature events and background jobs — Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** Ship the cross-feature event bus and background-job conventions defined in `docs/superpowers/specs/2026-05-08-events-and-jobs-design.md`, including two new core packages, two ESLint rules, two Plop generators, recording test helpers, the existing-feature anchor retrofit, an end-to-end proof-of-life cross-feature flow, and the documentation set.
|
||
|
||
**Architecture:** Two new abstractions — `IEventBus` in a new `@repo/core-events` package, `IJobQueue` in `@repo/core-shared/jobs` — each with an in-memory implementation (dev/test) and a Payload-jobs-backed implementation (prod). Selection follows the existing `bindAll()` rules in `apps/web-next/src/server/bind-production.ts`. Per-feature binders gain `bus, queue` parameters. Cross-feature reactions go publisher → bus → consumer handler → optional job; consumers import only the publisher's contract from the publisher's root export. Generators augment existing feature packages by inserting at six fixed `// <gen:*>` anchor comments.
|
||
|
||
**Tech Stack:** TypeScript, Zod, Inversify (DI), Vitest, ESLint flat config, Plop (via `@turbo/gen`), Payload 3.x (`payload.jobs` API for production transport), Turborepo, pnpm workspaces.
|
||
|
||
**Plan length:** ~60 bite-sized tasks across 9 phases. Each task is 2–5 minutes of work and ends in a commit.
|
||
|
||
---
|
||
|
||
## Phase 0 — Read first
|
||
|
||
Read these once before starting; they contain rules and patterns the rest of the plan assumes:
|
||
|
||
- `docs/superpowers/specs/2026-05-08-events-and-jobs-design.md` — the design this plan implements.
|
||
- `AGENTS.md` § Per-Package Conventions and § Instrumentation conventions.
|
||
- `CLAUDE.md` § Key Conventions.
|
||
- `packages/auth/src/di/bind-production.ts` — canonical binder shape we extend.
|
||
- `apps/web-next/src/server/bind-production.ts` — canonical `bindAll()` shape we extend.
|
||
- `docs/decisions/adr-014-instrumentation-sentry.md` (R40, R41–R44) — the span+capture sandwich rules events/jobs reuse.
|
||
- `docs/decisions/adr-013-input-output-unification.md` (R1–R5) — the schemas-in-use-case pattern jobs mirror.
|
||
|
||
Conventions used throughout this plan:
|
||
|
||
- **Spec sections** are referenced as `spec § N.N`.
|
||
- **Verification commands** use `pnpm --filter <pkg> typecheck test lint` for package-scoped checks; `pnpm typecheck` / `pnpm test` / `pnpm turbo boundaries` for whole-monorepo checks.
|
||
- **Commit style** matches the repo's existing format (e.g., `feat(core-events): InMemoryEventBus`). Short imperative subject under 70 chars, optional body explaining the *why* if non-obvious.
|
||
- **TDD order:** failing test → run to confirm fail → minimal implementation → run to confirm pass → commit. Skipped only for tasks that add no behavior (anchor comments, doc updates, signature-only edits with no logic change) — those use a make-the-change → verify-typecheck → commit sequence.
|
||
|
||
---
|
||
|
||
## File map (summary)
|
||
|
||
**New files:**
|
||
|
||
```
|
||
packages/core-events/ # NEW package, tag: core
|
||
package.json
|
||
tsconfig.json
|
||
vitest.config.ts
|
||
eslint.config.js
|
||
turbo.json
|
||
AGENTS.md
|
||
src/
|
||
event-descriptor.ts
|
||
event-descriptor.test.ts
|
||
event-bus.interface.ts
|
||
in-memory-event-bus.ts
|
||
in-memory-event-bus.test.ts
|
||
payload-jobs-event-bus.ts
|
||
payload-jobs-event-bus.test.ts
|
||
symbols.ts
|
||
index.ts
|
||
|
||
packages/core-shared/src/jobs/ # NEW subdirectory + ./jobs subpath
|
||
job-queue.interface.ts
|
||
in-memory-job-queue.ts
|
||
in-memory-job-queue.test.ts
|
||
payload-job-queue.ts
|
||
payload-job-queue.test.ts
|
||
symbols.ts
|
||
index.ts
|
||
|
||
packages/core-testing/src/instrumentation/ # extends existing dir
|
||
recording-event-bus.ts
|
||
recording-event-bus.test.ts
|
||
recording-job-queue.ts
|
||
recording-job-queue.test.ts
|
||
|
||
packages/core-eslint/src/ # extends existing dir
|
||
no-handler-reexport.rule.ts
|
||
no-handler-reexport.rule.test.ts
|
||
no-direct-payload-jobs.rule.ts
|
||
no-direct-payload-jobs.rule.test.ts
|
||
|
||
turbo/generators/templates/ # extends existing dir
|
||
event/publish/event.ts.hbs
|
||
event/publish/event.test.ts.hbs
|
||
event/consume/handler.ts.hbs
|
||
event/consume/handler.test.ts.hbs
|
||
event/consume/binder-block.ts.hbs # snippet for modify action
|
||
event/consume/symbol.ts.hbs # snippet for modify action
|
||
job/job.ts.hbs
|
||
job/job.test.ts.hbs
|
||
job/task.ts.hbs
|
||
job/binder-block.ts.hbs # snippet for modify action
|
||
job/symbol.ts.hbs # snippet for modify action
|
||
job/cms-export.ts.hbs # snippet for modify action
|
||
|
||
packages/marketing-pages/src/application/services/ # NEW for proof-of-life
|
||
mailer.service.interface.ts
|
||
packages/marketing-pages/src/infrastructure/services/
|
||
recording-mailer.service.ts # mock impl for the e2e test
|
||
|
||
docs/decisions/adr-015-events-and-jobs.md # NEW
|
||
docs/guides/events-and-jobs.md # NEW
|
||
```
|
||
|
||
**Modified files (anchor retrofit; pure additive comments):**
|
||
|
||
For each of `auth`, `blog`, `media`, `marketing-pages`, `navigation`:
|
||
|
||
```
|
||
packages/<feature>/src/index.ts # + // <gen:events>
|
||
packages/<feature>/src/di/symbols.ts # + // <gen:event-handler-symbols> and // <gen:job-symbols>
|
||
packages/<feature>/src/di/bind-production.ts # + // <gen:event-handlers> and // <gen:jobs>
|
||
packages/<feature>/src/di/bind-dev-seed.ts # + same two anchors
|
||
packages/<feature>/src/integrations/cms/index.ts # + // <gen:job-tasks>
|
||
```
|
||
|
||
Plus the feature template under `turbo/generators/templates/feature/` gets the same anchor additions to its `.hbs` files (CMS index excluded — Phase-1 generator doesn't emit it).
|
||
|
||
**Modified files (binder signatures + bindAll):**
|
||
|
||
```
|
||
packages/<feature>/src/di/bind-production.ts # + bus, queue params
|
||
packages/<feature>/src/di/bind-dev-seed.ts # + bus, queue params
|
||
packages/<feature>/src/di/bind-production.test.ts # update test invocations
|
||
packages/<feature>/src/di/bind-dev-seed.test.ts # update test invocations
|
||
apps/web-next/src/server/bind-production.ts # + resolveEventsAndJobs(), pass through
|
||
apps/web-next/src/server/bind-production.test.ts # update assertions
|
||
apps/cms/src/server/bind-production.ts # same as web-next (if file exists; verify in Phase 5)
|
||
apps/web-tanstack/src/server/bind-production.ts # same (if exists; verify in Phase 5)
|
||
turbo/generators/config.ts # + event + job generators
|
||
turbo/generators/templates/feature/... # anchor inserts in template
|
||
```
|
||
|
||
**Modified files (docs):**
|
||
|
||
```
|
||
AGENTS.md # new section under Per-Package Conventions
|
||
CLAUDE.md # Quick Start + Read First + Key Conventions
|
||
docs/guides/scaffolding-a-feature.md # two new sections
|
||
docs/architecture/vertical-feature-spec.md # update lines :260 and :662
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 1 — Job queue in `core-shared`
|
||
|
||
`IJobQueue` lives in `core-shared` (spec § 3.2 / § 6.4) so features can use jobs without depending on `core-events`. The bus depends on the queue, not vice versa.
|
||
|
||
### Task 1: Add `./jobs` subpath to `@repo/core-shared` package.json
|
||
|
||
**Files:**
|
||
- Modify: `packages/core-shared/package.json`
|
||
|
||
- [ ] **Step 1: Read the current exports map**
|
||
|
||
Read `packages/core-shared/package.json` to locate the `"exports"` block.
|
||
|
||
- [ ] **Step 2: Add the `./jobs` subpath**
|
||
|
||
Add this entry alongside the existing subpaths:
|
||
|
||
```json
|
||
"./jobs": "./src/jobs/index.ts",
|
||
```
|
||
|
||
- [ ] **Step 3: Verify exports JSON is valid and pnpm picks it up**
|
||
|
||
Run: `pnpm install --filter @repo/core-shared`
|
||
Expected: clean install, no warning about malformed exports.
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add packages/core-shared/package.json
|
||
git commit -m "feat(core-shared): add ./jobs subpath export"
|
||
```
|
||
|
||
### Task 2: Define `IJobQueue` interface
|
||
|
||
**Files:**
|
||
- Create: `packages/core-shared/src/jobs/job-queue.interface.ts`
|
||
|
||
- [ ] **Step 1: Create the interface file**
|
||
|
||
```ts
|
||
// packages/core-shared/src/jobs/job-queue.interface.ts
|
||
export interface IJobQueue {
|
||
enqueue<T>(
|
||
taskSlug: string,
|
||
input: T,
|
||
options?: { runAt?: Date },
|
||
): Promise<{ jobId: string }>;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Verify typecheck**
|
||
|
||
Run: `pnpm --filter @repo/core-shared typecheck`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add packages/core-shared/src/jobs/job-queue.interface.ts
|
||
git commit -m "feat(core-shared/jobs): IJobQueue interface"
|
||
```
|
||
|
||
### Task 3: Add `CORE_SHARED_JOBS_SYMBOLS`
|
||
|
||
**Files:**
|
||
- Create: `packages/core-shared/src/jobs/symbols.ts`
|
||
|
||
- [ ] **Step 1: Create the symbols file**
|
||
|
||
```ts
|
||
// packages/core-shared/src/jobs/symbols.ts
|
||
export const CORE_SHARED_JOBS_SYMBOLS = {
|
||
IJobQueue: Symbol.for("@repo/core-shared/jobs/IJobQueue"),
|
||
} as const;
|
||
```
|
||
|
||
- [ ] **Step 2: Verify typecheck**
|
||
|
||
Run: `pnpm --filter @repo/core-shared typecheck`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add packages/core-shared/src/jobs/symbols.ts
|
||
git commit -m "feat(core-shared/jobs): symbol registry"
|
||
```
|
||
|
||
### Task 4: Write the failing test for `InMemoryJobQueue`
|
||
|
||
**Files:**
|
||
- Create: `packages/core-shared/src/jobs/in-memory-job-queue.test.ts`
|
||
|
||
- [ ] **Step 1: Write the test**
|
||
|
||
```ts
|
||
// packages/core-shared/src/jobs/in-memory-job-queue.test.ts
|
||
import { describe, it, expect, vi } from "vitest";
|
||
import { InMemoryJobQueue } from "@/jobs/in-memory-job-queue";
|
||
import type { IJobQueue } from "@/jobs/job-queue.interface";
|
||
|
||
describe("InMemoryJobQueue", () => {
|
||
it("returns a synthetic jobId on enqueue", async () => {
|
||
const handler = vi.fn();
|
||
const queue: IJobQueue = new InMemoryJobQueue({
|
||
"test.task": handler,
|
||
});
|
||
const result = await queue.enqueue("test.task", { x: 1 });
|
||
expect(result.jobId).toMatch(/^in-memory-/);
|
||
});
|
||
|
||
it("invokes the registered handler asynchronously with the input", async () => {
|
||
const handler = vi.fn();
|
||
const queue = new InMemoryJobQueue({ "test.task": handler });
|
||
await queue.enqueue("test.task", { x: 42 });
|
||
// Microtask boundary: handler runs after enqueue resolves
|
||
await new Promise((r) => setImmediate(r));
|
||
expect(handler).toHaveBeenCalledWith({ x: 42 });
|
||
});
|
||
|
||
it("throws if the task slug has no registered handler", async () => {
|
||
const queue = new InMemoryJobQueue({});
|
||
await expect(queue.enqueue("missing.task", {})).rejects.toThrow(
|
||
/no handler registered for task slug: missing\.task/,
|
||
);
|
||
});
|
||
|
||
it("delays execution when runAt is in the future", async () => {
|
||
vi.useFakeTimers();
|
||
try {
|
||
const handler = vi.fn();
|
||
const queue = new InMemoryJobQueue({ "test.task": handler });
|
||
const future = new Date(Date.now() + 1000);
|
||
await queue.enqueue("test.task", {}, { runAt: future });
|
||
expect(handler).not.toHaveBeenCalled();
|
||
vi.advanceTimersByTime(1000);
|
||
await Promise.resolve();
|
||
expect(handler).toHaveBeenCalledTimes(1);
|
||
} finally {
|
||
vi.useRealTimers();
|
||
}
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: Run the test and confirm it fails**
|
||
|
||
Run: `pnpm --filter @repo/core-shared test -- in-memory-job-queue`
|
||
Expected: FAIL — `InMemoryJobQueue` not exported.
|
||
|
||
### Task 5: Implement `InMemoryJobQueue`
|
||
|
||
**Files:**
|
||
- Create: `packages/core-shared/src/jobs/in-memory-job-queue.ts`
|
||
|
||
- [ ] **Step 1: Write the implementation**
|
||
|
||
```ts
|
||
// packages/core-shared/src/jobs/in-memory-job-queue.ts
|
||
import type { IJobQueue } from "./job-queue.interface";
|
||
|
||
export type InMemoryHandler = (input: unknown) => Promise<void> | void;
|
||
|
||
export class InMemoryJobQueue implements IJobQueue {
|
||
private counter = 0;
|
||
|
||
constructor(private readonly handlers: Record<string, InMemoryHandler>) {}
|
||
|
||
async enqueue<T>(
|
||
taskSlug: string,
|
||
input: T,
|
||
options?: { runAt?: Date },
|
||
): Promise<{ jobId: string }> {
|
||
const handler = this.handlers[taskSlug];
|
||
if (!handler) {
|
||
throw new Error(`no handler registered for task slug: ${taskSlug}`);
|
||
}
|
||
this.counter += 1;
|
||
const jobId = `in-memory-${this.counter}`;
|
||
const delay = options?.runAt ? options.runAt.getTime() - Date.now() : 0;
|
||
if (delay > 0) {
|
||
setTimeout(() => void handler(input), delay);
|
||
} else {
|
||
setImmediate(() => void handler(input));
|
||
}
|
||
return { jobId };
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Run tests; expect PASS**
|
||
|
||
Run: `pnpm --filter @repo/core-shared test -- in-memory-job-queue`
|
||
Expected: 4 tests PASS.
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add packages/core-shared/src/jobs/in-memory-job-queue.ts packages/core-shared/src/jobs/in-memory-job-queue.test.ts
|
||
git commit -m "feat(core-shared/jobs): InMemoryJobQueue"
|
||
```
|
||
|
||
### Task 6: Write the failing test for `PayloadJobQueue`
|
||
|
||
**Files:**
|
||
- Create: `packages/core-shared/src/jobs/payload-job-queue.test.ts`
|
||
|
||
- [ ] **Step 1: Write the test**
|
||
|
||
```ts
|
||
// packages/core-shared/src/jobs/payload-job-queue.test.ts
|
||
import { describe, it, expect, vi } from "vitest";
|
||
import { PayloadJobQueue } from "@/jobs/payload-job-queue";
|
||
|
||
describe("PayloadJobQueue", () => {
|
||
it("delegates to payload.jobs.queue with the task slug and input", async () => {
|
||
const queueMock = vi.fn().mockResolvedValue({ id: "payload-job-1" });
|
||
const payload = { jobs: { queue: queueMock } } as unknown as Parameters<
|
||
typeof PayloadJobQueue.prototype.constructor
|
||
>[0];
|
||
const queue = new PayloadJobQueue(payload);
|
||
const result = await queue.enqueue("blog.republish", { id: 1 });
|
||
expect(queueMock).toHaveBeenCalledWith({
|
||
task: "blog.republish",
|
||
input: { id: 1 },
|
||
waitUntil: undefined,
|
||
});
|
||
expect(result).toEqual({ jobId: "payload-job-1" });
|
||
});
|
||
|
||
it("forwards runAt as waitUntil", async () => {
|
||
const queueMock = vi.fn().mockResolvedValue({ id: "payload-job-2" });
|
||
const payload = { jobs: { queue: queueMock } } as never;
|
||
const queue = new PayloadJobQueue(payload);
|
||
const future = new Date(Date.now() + 5000);
|
||
await queue.enqueue("blog.task", {}, { runAt: future });
|
||
expect(queueMock).toHaveBeenCalledWith(
|
||
expect.objectContaining({ waitUntil: future }),
|
||
);
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: Run; expect FAIL**
|
||
|
||
Run: `pnpm --filter @repo/core-shared test -- payload-job-queue`
|
||
Expected: FAIL — `PayloadJobQueue` not exported.
|
||
|
||
### Task 7: Implement `PayloadJobQueue`
|
||
|
||
**Files:**
|
||
- Create: `packages/core-shared/src/jobs/payload-job-queue.ts`
|
||
|
||
- [ ] **Step 1: Write the implementation**
|
||
|
||
```ts
|
||
// packages/core-shared/src/jobs/payload-job-queue.ts
|
||
import type { Payload } from "payload";
|
||
import type { IJobQueue } from "./job-queue.interface";
|
||
|
||
/**
|
||
* Production-grade queue: enqueues into Payload's built-in jobs system.
|
||
* The wrapped Payload instance is constructed once at app boot via
|
||
* `getPayload({ config })` and passed in.
|
||
*/
|
||
export class PayloadJobQueue implements IJobQueue {
|
||
constructor(private readonly payload: Payload) {}
|
||
|
||
async enqueue<T>(
|
||
taskSlug: string,
|
||
input: T,
|
||
options?: { runAt?: Date },
|
||
): Promise<{ jobId: string }> {
|
||
const result = await this.payload.jobs.queue({
|
||
task: taskSlug,
|
||
input: input as never,
|
||
waitUntil: options?.runAt,
|
||
} as never);
|
||
const jobId = (result as { id: string | number }).id;
|
||
return { jobId: String(jobId) };
|
||
}
|
||
}
|
||
```
|
||
|
||
> **Note on `as never` casts:** Payload's `jobs.queue` API uses generic types tied to the registered task registry. Since `PayloadJobQueue` is generic across all features, we accept the cost of a few `as never` casts at this boundary in exchange for a uniform `IJobQueue` interface. The boundary parse inside each job (spec § 5.5) recovers type safety at the actual handler entry.
|
||
|
||
- [ ] **Step 2: Run tests; expect PASS**
|
||
|
||
Run: `pnpm --filter @repo/core-shared test -- payload-job-queue`
|
||
Expected: 2 tests PASS.
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add packages/core-shared/src/jobs/payload-job-queue.ts packages/core-shared/src/jobs/payload-job-queue.test.ts
|
||
git commit -m "feat(core-shared/jobs): PayloadJobQueue"
|
||
```
|
||
|
||
### Task 8: Create the `jobs/` barrel
|
||
|
||
**Files:**
|
||
- Create: `packages/core-shared/src/jobs/index.ts`
|
||
|
||
- [ ] **Step 1: Write the barrel**
|
||
|
||
```ts
|
||
// packages/core-shared/src/jobs/index.ts
|
||
export type { IJobQueue } from "./job-queue.interface";
|
||
export { CORE_SHARED_JOBS_SYMBOLS } from "./symbols";
|
||
export { InMemoryJobQueue, type InMemoryHandler } from "./in-memory-job-queue";
|
||
export { PayloadJobQueue } from "./payload-job-queue";
|
||
```
|
||
|
||
- [ ] **Step 2: Verify typecheck and that the subpath resolves**
|
||
|
||
Run: `pnpm --filter @repo/core-shared typecheck && pnpm --filter @repo/core-shared test`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add packages/core-shared/src/jobs/index.ts
|
||
git commit -m "feat(core-shared/jobs): public barrel via @repo/core-shared/jobs subpath"
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 2 — `@repo/core-events` package
|
||
|
||
A new package, tag: `core` (spec § 3.1).
|
||
|
||
### Task 9: Scaffold the package skeleton
|
||
|
||
**Files:**
|
||
- Create: `packages/core-events/package.json`
|
||
- Create: `packages/core-events/tsconfig.json`
|
||
- Create: `packages/core-events/vitest.config.ts`
|
||
- Create: `packages/core-events/eslint.config.js`
|
||
- Create: `packages/core-events/turbo.json`
|
||
- Create: `packages/core-events/AGENTS.md`
|
||
|
||
- [ ] **Step 1: Read `packages/core-shared/package.json` and `packages/core-shared/tsconfig.json` as the reference shape**
|
||
|
||
These are the closest analog (also tag: `core`).
|
||
|
||
- [ ] **Step 2: Create `package.json`**
|
||
|
||
```json
|
||
{
|
||
"name": "@repo/core-events",
|
||
"version": "0.0.1",
|
||
"private": true,
|
||
"type": "module",
|
||
"exports": {
|
||
".": "./src/index.ts"
|
||
},
|
||
"scripts": {
|
||
"build": "tsc --noEmit",
|
||
"lint": "eslint .",
|
||
"typecheck": "tsc --noEmit",
|
||
"test": "vitest run"
|
||
},
|
||
"dependencies": {
|
||
"@repo/core-shared": "workspace:*",
|
||
"zod": "^3.23.0"
|
||
},
|
||
"peerDependencies": {
|
||
"payload": "^3.0.0"
|
||
},
|
||
"peerDependenciesMeta": {
|
||
"payload": { "optional": true }
|
||
},
|
||
"devDependencies": {
|
||
"@repo/core-eslint": "workspace:*",
|
||
"@repo/core-typescript": "workspace:*",
|
||
"typescript": "^5.8.0",
|
||
"vitest": "^3.0.0"
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: Create `tsconfig.json`**
|
||
|
||
```json
|
||
{
|
||
"extends": "@repo/core-typescript/base.json",
|
||
"compilerOptions": {
|
||
"rootDir": ".",
|
||
"outDir": "dist"
|
||
},
|
||
"include": ["src/**/*"],
|
||
"exclude": ["node_modules", "dist"]
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: Create `vitest.config.ts`**
|
||
|
||
```ts
|
||
import path from "path";
|
||
import { defineConfig } from "vitest/config";
|
||
|
||
export default defineConfig({
|
||
test: { environment: "node", globals: true },
|
||
resolve: { alias: { "@": path.resolve(__dirname, "./src") } },
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 5: Create `eslint.config.js`**
|
||
|
||
Match the shape of `packages/core-shared/eslint.config.js` (read it first). It should use `@repo/core-eslint`'s base config.
|
||
|
||
- [ ] **Step 6: Create `turbo.json`**
|
||
|
||
Match the shape of `packages/core-shared/turbo.json` (read it first). Single-file config that extends the root with a build/test/lint pipeline.
|
||
|
||
- [ ] **Step 7: Create `AGENTS.md`**
|
||
|
||
```markdown
|
||
# @repo/core-events
|
||
|
||
Owns the cross-feature event bus: `IEventBus`, `defineEvent`, and two implementations (`InMemoryEventBus`, `PayloadJobsEventBus`).
|
||
|
||
**Boundary tag:** core. May be imported by feature, core, core-composition, app. May import from core-shared, tooling.
|
||
|
||
**Public surface:** `IEventBus`, `EventDescriptor`, `defineEvent`, `EventHandler`, `CORE_EVENTS_SYMBOLS`, both implementations.
|
||
|
||
**See:** `docs/decisions/adr-015-events-and-jobs.md`, `docs/guides/events-and-jobs.md`.
|
||
```
|
||
|
||
- [ ] **Step 8: Run `pnpm install` so the workspace picks up the new package**
|
||
|
||
Run: `pnpm install`
|
||
Expected: clean install, `@repo/core-events` registered.
|
||
|
||
- [ ] **Step 9: Commit**
|
||
|
||
```bash
|
||
git add packages/core-events
|
||
git commit -m "chore(core-events): scaffold package"
|
||
```
|
||
|
||
### Task 10: Add `core-events` to the boundary tag map
|
||
|
||
**Files:**
|
||
- Modify: `packages/core-eslint/` boundary config (file containing the tag map for `eslint-plugin-boundaries`)
|
||
- Modify: root `turbo.json` (boundaries config)
|
||
|
||
- [ ] **Step 1: Locate the boundary config**
|
||
|
||
Run: `grep -rn "core-shared" packages/core-eslint/src/ turbo.json | head`
|
||
Expected output should reveal where the tag map for `core` packages is configured.
|
||
|
||
- [ ] **Step 2: Add `@repo/core-events` to the `core` tag**
|
||
|
||
In every place that lists `core` packages by name (typically `packages/core-eslint/src/boundaries.ts` or similar plus `turbo.json`'s `boundaries.tags`), add `@repo/core-events` alongside `@repo/core-shared` and `@repo/core-ui`.
|
||
|
||
- [ ] **Step 3: Verify the boundary check passes**
|
||
|
||
Run: `pnpm turbo boundaries`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add -A
|
||
git commit -m "chore(core-eslint,turbo): tag @repo/core-events as core"
|
||
```
|
||
|
||
### Task 11: Define `EventDescriptor` + `defineEvent`
|
||
|
||
**Files:**
|
||
- Create: `packages/core-events/src/event-descriptor.ts`
|
||
- Create: `packages/core-events/src/event-descriptor.test.ts`
|
||
|
||
- [ ] **Step 1: Write the failing test**
|
||
|
||
```ts
|
||
// packages/core-events/src/event-descriptor.test.ts
|
||
import { describe, it, expect } from "vitest";
|
||
import { z } from "zod";
|
||
import { defineEvent } from "@/event-descriptor";
|
||
|
||
describe("defineEvent", () => {
|
||
it("returns a descriptor with name and schema", () => {
|
||
const schema = z.object({ id: z.string() }).strict();
|
||
const descriptor = defineEvent("test.thing.happened", schema);
|
||
expect(descriptor.name).toBe("test.thing.happened");
|
||
expect(descriptor.schema).toBe(schema);
|
||
});
|
||
|
||
it("descriptor.schema parses valid payloads", () => {
|
||
const schema = z.object({ id: z.string() }).strict();
|
||
const d = defineEvent("test.evt", schema);
|
||
expect(() => d.schema.parse({ id: "abc" })).not.toThrow();
|
||
});
|
||
|
||
it("descriptor.schema rejects invalid payloads", () => {
|
||
const schema = z.object({ id: z.string() }).strict();
|
||
const d = defineEvent("test.evt", schema);
|
||
expect(() => d.schema.parse({ id: 123 })).toThrow();
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: Run; expect FAIL** — `defineEvent` not exported.
|
||
|
||
Run: `pnpm --filter @repo/core-events test`
|
||
Expected: FAIL.
|
||
|
||
- [ ] **Step 3: Implement**
|
||
|
||
```ts
|
||
// packages/core-events/src/event-descriptor.ts
|
||
import type { z } from "zod";
|
||
|
||
export type EventDescriptor<TName extends string, TSchema extends z.ZodType> = {
|
||
readonly name: TName;
|
||
readonly schema: TSchema;
|
||
};
|
||
|
||
export function defineEvent<TName extends string, TSchema extends z.ZodType>(
|
||
name: TName,
|
||
schema: TSchema,
|
||
): EventDescriptor<TName, TSchema> {
|
||
return { name, schema };
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: Run; expect PASS**
|
||
|
||
Run: `pnpm --filter @repo/core-events test`
|
||
Expected: 3 tests PASS.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add packages/core-events/src/event-descriptor.ts packages/core-events/src/event-descriptor.test.ts
|
||
git commit -m "feat(core-events): EventDescriptor + defineEvent"
|
||
```
|
||
|
||
### Task 12: Define `IEventBus` interface and symbols
|
||
|
||
**Files:**
|
||
- Create: `packages/core-events/src/event-bus.interface.ts`
|
||
- Create: `packages/core-events/src/symbols.ts`
|
||
|
||
- [ ] **Step 1: Create the interface**
|
||
|
||
```ts
|
||
// packages/core-events/src/event-bus.interface.ts
|
||
import type { z } from "zod";
|
||
import type { EventDescriptor } from "./event-descriptor";
|
||
|
||
export type EventHandler<T> = (event: T) => Promise<void>;
|
||
|
||
export interface IEventBus {
|
||
publish<T>(
|
||
descriptor: EventDescriptor<string, z.ZodType<T>>,
|
||
payload: T,
|
||
): Promise<void>;
|
||
|
||
/**
|
||
* Subscribe a handler. `consumerFeature` is the kebab-case name of the
|
||
* subscribing feature (e.g., "marketing-pages"). InMemoryEventBus uses it
|
||
* only as a debug tag; PayloadJobsEventBus uses it to name the fan-out task
|
||
* slug deterministically (`__events.<event>.<consumerFeature>`).
|
||
*/
|
||
subscribe<T>(
|
||
descriptor: EventDescriptor<string, z.ZodType<T>>,
|
||
consumerFeature: string,
|
||
handler: EventHandler<T>,
|
||
): void;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Create the symbols**
|
||
|
||
```ts
|
||
// packages/core-events/src/symbols.ts
|
||
export const CORE_EVENTS_SYMBOLS = {
|
||
IEventBus: Symbol.for("@repo/core-events/IEventBus"),
|
||
} as const;
|
||
```
|
||
|
||
- [ ] **Step 3: Verify typecheck**
|
||
|
||
Run: `pnpm --filter @repo/core-events typecheck`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add packages/core-events/src/event-bus.interface.ts packages/core-events/src/symbols.ts
|
||
git commit -m "feat(core-events): IEventBus interface + symbol registry"
|
||
```
|
||
|
||
### Task 13: Write the failing test for `InMemoryEventBus`
|
||
|
||
**Files:**
|
||
- Create: `packages/core-events/src/in-memory-event-bus.test.ts`
|
||
|
||
- [ ] **Step 1: Write the test**
|
||
|
||
```ts
|
||
// packages/core-events/src/in-memory-event-bus.test.ts
|
||
import { describe, it, expect, vi } from "vitest";
|
||
import { z } from "zod";
|
||
import { defineEvent } from "@/event-descriptor";
|
||
import { InMemoryEventBus } from "@/in-memory-event-bus";
|
||
|
||
const evt = defineEvent("test.thing", z.object({ id: z.string() }).strict());
|
||
|
||
describe("InMemoryEventBus", () => {
|
||
it("validates the payload via the descriptor's schema before fanout", async () => {
|
||
const bus = new InMemoryEventBus();
|
||
const handler = vi.fn();
|
||
bus.subscribe(evt, "test-consumer", handler);
|
||
await expect(bus.publish(evt, { id: 123 } as unknown as { id: string })).rejects.toThrow();
|
||
expect(handler).not.toHaveBeenCalled();
|
||
});
|
||
|
||
it("delivers to all registered handlers in parallel", async () => {
|
||
const bus = new InMemoryEventBus();
|
||
const a = vi.fn();
|
||
const b = vi.fn();
|
||
bus.subscribe(evt, "consumer-a", a);
|
||
bus.subscribe(evt, "consumer-b", b);
|
||
await bus.publish(evt, { id: "x" });
|
||
expect(a).toHaveBeenCalledWith({ id: "x" });
|
||
expect(b).toHaveBeenCalledWith({ id: "x" });
|
||
});
|
||
|
||
it("swallows handler errors by default (publisher's publish does not throw)", async () => {
|
||
const bus = new InMemoryEventBus();
|
||
bus.subscribe(evt, "boom", async () => {
|
||
throw new Error("subscriber blew up");
|
||
});
|
||
await expect(bus.publish(evt, { id: "x" })).resolves.toBeUndefined();
|
||
});
|
||
|
||
it("rethrows the first handler error when failFast is true", async () => {
|
||
const bus = new InMemoryEventBus({ failFast: true });
|
||
bus.subscribe(evt, "first", async () => {
|
||
throw new Error("first failure");
|
||
});
|
||
bus.subscribe(evt, "second", vi.fn());
|
||
await expect(bus.publish(evt, { id: "x" })).rejects.toThrow("first failure");
|
||
});
|
||
|
||
it("delivers nothing when no handlers are registered", async () => {
|
||
const bus = new InMemoryEventBus();
|
||
await expect(bus.publish(evt, { id: "x" })).resolves.toBeUndefined();
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: Run; expect FAIL** — `InMemoryEventBus` not exported.
|
||
|
||
Run: `pnpm --filter @repo/core-events test -- in-memory-event-bus`
|
||
Expected: FAIL.
|
||
|
||
### Task 14: Implement `InMemoryEventBus`
|
||
|
||
**Files:**
|
||
- Create: `packages/core-events/src/in-memory-event-bus.ts`
|
||
|
||
- [ ] **Step 1: Write the implementation**
|
||
|
||
```ts
|
||
// packages/core-events/src/in-memory-event-bus.ts
|
||
import type { z } from "zod";
|
||
import type { EventDescriptor } from "./event-descriptor";
|
||
import type { EventHandler, IEventBus } from "./event-bus.interface";
|
||
|
||
export type InMemoryEventBusOptions = {
|
||
/** When true, rethrow the first handler error (default: false — errors swallowed). */
|
||
failFast?: boolean;
|
||
};
|
||
|
||
export class InMemoryEventBus implements IEventBus {
|
||
private readonly handlers = new Map<string, EventHandler<unknown>[]>();
|
||
|
||
constructor(private readonly options: InMemoryEventBusOptions = {}) {}
|
||
|
||
async publish<T>(
|
||
descriptor: EventDescriptor<string, z.ZodType<T>>,
|
||
payload: T,
|
||
): Promise<void> {
|
||
descriptor.schema.parse(payload);
|
||
const subscribers = this.handlers.get(descriptor.name) ?? [];
|
||
if (subscribers.length === 0) return;
|
||
const settled = await Promise.allSettled(
|
||
subscribers.map((h) => h(payload)),
|
||
);
|
||
if (this.options.failFast) {
|
||
const failure = settled.find((s) => s.status === "rejected");
|
||
if (failure && failure.status === "rejected") throw failure.reason;
|
||
}
|
||
}
|
||
|
||
subscribe<T>(
|
||
descriptor: EventDescriptor<string, z.ZodType<T>>,
|
||
_consumerFeature: string, // tagging only; no behavior
|
||
handler: EventHandler<T>,
|
||
): void {
|
||
const arr = this.handlers.get(descriptor.name) ?? [];
|
||
arr.push(handler as EventHandler<unknown>);
|
||
this.handlers.set(descriptor.name, arr);
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Run tests; expect PASS**
|
||
|
||
Run: `pnpm --filter @repo/core-events test -- in-memory-event-bus`
|
||
Expected: 5 tests PASS.
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add packages/core-events/src/in-memory-event-bus.ts packages/core-events/src/in-memory-event-bus.test.ts
|
||
git commit -m "feat(core-events): InMemoryEventBus with failFast option"
|
||
```
|
||
|
||
### Task 15: Write the failing test for `PayloadJobsEventBus`
|
||
|
||
**Files:**
|
||
- Create: `packages/core-events/src/payload-jobs-event-bus.test.ts`
|
||
|
||
- [ ] **Step 1: Write the test**
|
||
|
||
```ts
|
||
// packages/core-events/src/payload-jobs-event-bus.test.ts
|
||
import { describe, it, expect, vi } from "vitest";
|
||
import { z } from "zod";
|
||
import { defineEvent } from "@/event-descriptor";
|
||
import { PayloadJobsEventBus } from "@/payload-jobs-event-bus";
|
||
import type { IJobQueue } from "@repo/core-shared/jobs";
|
||
|
||
const evt = defineEvent("auth.user.signed-up", z.object({ userId: z.string() }).strict());
|
||
|
||
function recordingQueue(): IJobQueue & { enqueued: { taskSlug: string; input: unknown }[] } {
|
||
const enqueued: { taskSlug: string; input: unknown }[] = [];
|
||
const q: IJobQueue = {
|
||
async enqueue(taskSlug, input) {
|
||
enqueued.push({ taskSlug, input });
|
||
return { jobId: `recording-${enqueued.length}` };
|
||
},
|
||
};
|
||
return Object.assign(q, { enqueued });
|
||
}
|
||
|
||
describe("PayloadJobsEventBus", () => {
|
||
it("validates the payload before enqueueing", async () => {
|
||
const queue = recordingQueue();
|
||
const bus = new PayloadJobsEventBus(queue);
|
||
bus.subscribe(evt, "marketing-pages", vi.fn());
|
||
await expect(
|
||
bus.publish(evt, { userId: 42 } as unknown as { userId: string }),
|
||
).rejects.toThrow();
|
||
expect(queue.enqueued).toHaveLength(0);
|
||
});
|
||
|
||
it("enqueues one task per subscriber, naming `__events.<event>.<consumer>`", async () => {
|
||
const queue = recordingQueue();
|
||
const bus = new PayloadJobsEventBus(queue);
|
||
bus.subscribe(evt, "marketing-pages", vi.fn());
|
||
bus.subscribe(evt, "blog", vi.fn());
|
||
await bus.publish(evt, { userId: "u1" });
|
||
expect(queue.enqueued).toHaveLength(2);
|
||
expect(queue.enqueued.map((e) => e.taskSlug).sort()).toEqual([
|
||
"__events.auth.user.signed-up.blog",
|
||
"__events.auth.user.signed-up.marketing-pages",
|
||
]);
|
||
expect(queue.enqueued[0]!.input).toEqual({ userId: "u1" });
|
||
});
|
||
|
||
it("enqueues nothing when no subscribers are registered", async () => {
|
||
const queue = recordingQueue();
|
||
const bus = new PayloadJobsEventBus(queue);
|
||
await bus.publish(evt, { userId: "u1" });
|
||
expect(queue.enqueued).toHaveLength(0);
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: Run; expect FAIL** — `PayloadJobsEventBus` not exported.
|
||
|
||
Run: `pnpm --filter @repo/core-events test -- payload-jobs-event-bus`
|
||
Expected: FAIL.
|
||
|
||
### Task 16: Implement `PayloadJobsEventBus`
|
||
|
||
**Files:**
|
||
- Create: `packages/core-events/src/payload-jobs-event-bus.ts`
|
||
|
||
- [ ] **Step 1: Write the implementation**
|
||
|
||
```ts
|
||
// packages/core-events/src/payload-jobs-event-bus.ts
|
||
import type { z } from "zod";
|
||
import type { IJobQueue } from "@repo/core-shared/jobs";
|
||
import type { EventDescriptor } from "./event-descriptor";
|
||
import type { EventHandler, IEventBus } from "./event-bus.interface";
|
||
|
||
/**
|
||
* Production-grade bus: for each subscriber, enqueues one Payload task per
|
||
* `publish()` call. The subscribers are registered locally (their consumer
|
||
* feature name is the second arg to `subscribe`) so this bus can name the
|
||
* fan-out tasks deterministically. The actual handler invocation happens
|
||
* inside Payload's job runner — see the consumer feature's bind-production
|
||
* for the wiring that registers a corresponding TaskConfig with that slug.
|
||
*/
|
||
export class PayloadJobsEventBus implements IEventBus {
|
||
private readonly subscribers = new Map<string, string[]>(); // event name → consumer-feature names
|
||
|
||
constructor(private readonly queue: IJobQueue) {}
|
||
|
||
async publish<T>(
|
||
descriptor: EventDescriptor<string, z.ZodType<T>>,
|
||
payload: T,
|
||
): Promise<void> {
|
||
descriptor.schema.parse(payload);
|
||
const consumers = this.subscribers.get(descriptor.name) ?? [];
|
||
await Promise.all(
|
||
consumers.map((consumerFeature) =>
|
||
this.queue.enqueue(
|
||
`__events.${descriptor.name}.${consumerFeature}`,
|
||
payload,
|
||
),
|
||
),
|
||
);
|
||
}
|
||
|
||
subscribe<T>(
|
||
descriptor: EventDescriptor<string, z.ZodType<T>>,
|
||
consumerFeature: string,
|
||
_handler: EventHandler<T>,
|
||
): void {
|
||
const arr = this.subscribers.get(descriptor.name) ?? [];
|
||
if (!arr.includes(consumerFeature)) arr.push(consumerFeature);
|
||
this.subscribers.set(descriptor.name, arr);
|
||
}
|
||
}
|
||
```
|
||
|
||
> **Implementation note:** `PayloadJobsEventBus.subscribe` doesn't actually invoke the consumer's handler — it stores the consumer feature name and, on `publish`, enqueues a Payload task at slug `__events.<event>.<consumerFeature>`. The matching Payload task config is generated by `gen event consume` (Task 40 — see the additional `add` action that emits an `__events-<publisher>-<event>.task.ts` alongside the handler). The task config delegates to the consumer's container-resolved wrapped handler. With the generator + `core-cms` aggregation, the production bus is fully wired end-to-end.
|
||
|
||
- [ ] **Step 2: Run tests; expect PASS**
|
||
|
||
Run: `pnpm --filter @repo/core-events test -- payload-jobs-event-bus`
|
||
Expected: 3 tests PASS.
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add packages/core-events/src/payload-jobs-event-bus.ts packages/core-events/src/payload-jobs-event-bus.test.ts
|
||
git commit -m "feat(core-events): PayloadJobsEventBus (fan-out via IJobQueue)"
|
||
```
|
||
|
||
### Task 17: Create `core-events` public barrel
|
||
|
||
**Files:**
|
||
- Create: `packages/core-events/src/index.ts`
|
||
|
||
- [ ] **Step 1: Write the barrel**
|
||
|
||
```ts
|
||
// packages/core-events/src/index.ts
|
||
export type { EventDescriptor } from "./event-descriptor";
|
||
export { defineEvent } from "./event-descriptor";
|
||
export type { IEventBus, EventHandler } from "./event-bus.interface";
|
||
export { CORE_EVENTS_SYMBOLS } from "./symbols";
|
||
export { InMemoryEventBus, type InMemoryEventBusOptions } from "./in-memory-event-bus";
|
||
export { PayloadJobsEventBus } from "./payload-jobs-event-bus";
|
||
```
|
||
|
||
- [ ] **Step 2: Verify the package resolves**
|
||
|
||
Run: `pnpm --filter @repo/core-events typecheck && pnpm --filter @repo/core-events test`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add packages/core-events/src/index.ts
|
||
git commit -m "feat(core-events): public barrel"
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 3 — Recording test helpers
|
||
|
||
### Task 18: Write the failing test for `RecordingJobQueue`
|
||
|
||
**Files:**
|
||
- Create: `packages/core-testing/src/instrumentation/recording-job-queue.test.ts`
|
||
|
||
- [ ] **Step 1: Write the test**
|
||
|
||
```ts
|
||
// packages/core-testing/src/instrumentation/recording-job-queue.test.ts
|
||
import { describe, it, expect } from "vitest";
|
||
import { RecordingJobQueue } from "@/instrumentation/recording-job-queue";
|
||
|
||
describe("RecordingJobQueue", () => {
|
||
it("records every enqueue call", async () => {
|
||
const queue = new RecordingJobQueue();
|
||
const future = new Date("2030-01-01");
|
||
await queue.enqueue("a.task", { x: 1 });
|
||
await queue.enqueue("b.task", { y: 2 }, { runAt: future });
|
||
expect(queue.enqueued).toEqual([
|
||
{ taskSlug: "a.task", input: { x: 1 }, options: undefined },
|
||
{ taskSlug: "b.task", input: { y: 2 }, options: { runAt: future } },
|
||
]);
|
||
});
|
||
|
||
it("returns a synthetic jobId per call", async () => {
|
||
const queue = new RecordingJobQueue();
|
||
const a = await queue.enqueue("a", {});
|
||
const b = await queue.enqueue("b", {});
|
||
expect(a.jobId).toBe("recording-1");
|
||
expect(b.jobId).toBe("recording-2");
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: Run; expect FAIL**
|
||
|
||
Run: `pnpm --filter @repo/core-testing test -- recording-job-queue`
|
||
Expected: FAIL.
|
||
|
||
### Task 19: Implement `RecordingJobQueue`
|
||
|
||
**Files:**
|
||
- Create: `packages/core-testing/src/instrumentation/recording-job-queue.ts`
|
||
- Modify: `packages/core-testing/src/instrumentation/index.ts` (export the new class)
|
||
|
||
- [ ] **Step 1: Write the implementation**
|
||
|
||
```ts
|
||
// packages/core-testing/src/instrumentation/recording-job-queue.ts
|
||
import type { IJobQueue } from "@repo/core-shared/jobs";
|
||
|
||
export class RecordingJobQueue implements IJobQueue {
|
||
readonly enqueued: { taskSlug: string; input: unknown; options?: { runAt?: Date } }[] = [];
|
||
|
||
async enqueue<T>(
|
||
taskSlug: string,
|
||
input: T,
|
||
options?: { runAt?: Date },
|
||
): Promise<{ jobId: string }> {
|
||
this.enqueued.push({ taskSlug, input, options });
|
||
return { jobId: `recording-${this.enqueued.length}` };
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Add `@repo/core-shared` to core-testing dependencies if not already present**
|
||
|
||
Read `packages/core-testing/package.json`. If `@repo/core-shared` is not in `dependencies`, add it: `"@repo/core-shared": "workspace:*"`. Then `pnpm install`.
|
||
|
||
- [ ] **Step 3: Re-export from the instrumentation barrel**
|
||
|
||
Read `packages/core-testing/src/instrumentation/index.ts` and add:
|
||
|
||
```ts
|
||
export { RecordingJobQueue } from "./recording-job-queue";
|
||
```
|
||
|
||
- [ ] **Step 4: Run tests; expect PASS**
|
||
|
||
Run: `pnpm --filter @repo/core-testing test -- recording-job-queue`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add packages/core-testing/src/instrumentation/recording-job-queue.ts packages/core-testing/src/instrumentation/recording-job-queue.test.ts packages/core-testing/src/instrumentation/index.ts packages/core-testing/package.json
|
||
git commit -m "feat(core-testing): RecordingJobQueue"
|
||
```
|
||
|
||
### Task 20: Write the failing test for `RecordingEventBus`
|
||
|
||
**Files:**
|
||
- Create: `packages/core-testing/src/instrumentation/recording-event-bus.test.ts`
|
||
|
||
- [ ] **Step 1: Write the test**
|
||
|
||
```ts
|
||
// packages/core-testing/src/instrumentation/recording-event-bus.test.ts
|
||
import { describe, it, expect, vi } from "vitest";
|
||
import { z } from "zod";
|
||
import { defineEvent } from "@repo/core-events";
|
||
import { RecordingEventBus } from "@/instrumentation/recording-event-bus";
|
||
|
||
const evt = defineEvent("test.evt", z.object({ id: z.string() }).strict());
|
||
|
||
describe("RecordingEventBus", () => {
|
||
it("records every publish call after schema validation", async () => {
|
||
const bus = new RecordingEventBus();
|
||
await bus.publish(evt, { id: "a" });
|
||
await bus.publish(evt, { id: "b" });
|
||
expect(bus.published).toEqual([
|
||
{ name: "test.evt", payload: { id: "a" } },
|
||
{ name: "test.evt", payload: { id: "b" } },
|
||
]);
|
||
});
|
||
|
||
it("rejects invalid payloads", async () => {
|
||
const bus = new RecordingEventBus();
|
||
await expect(
|
||
bus.publish(evt, { id: 1 } as unknown as { id: string }),
|
||
).rejects.toThrow();
|
||
expect(bus.published).toHaveLength(0);
|
||
});
|
||
|
||
it("invokes registered handlers sequentially in subscription order", async () => {
|
||
const bus = new RecordingEventBus();
|
||
const order: string[] = [];
|
||
bus.subscribe(evt, "consumer-a", async () => {
|
||
order.push("a");
|
||
});
|
||
bus.subscribe(evt, "consumer-b", async () => {
|
||
order.push("b");
|
||
});
|
||
await bus.publish(evt, { id: "x" });
|
||
expect(order).toEqual(["a", "b"]);
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: Run; expect FAIL**
|
||
|
||
Run: `pnpm --filter @repo/core-testing test -- recording-event-bus`
|
||
Expected: FAIL.
|
||
|
||
### Task 21: Implement `RecordingEventBus`
|
||
|
||
**Files:**
|
||
- Create: `packages/core-testing/src/instrumentation/recording-event-bus.ts`
|
||
- Modify: `packages/core-testing/src/instrumentation/index.ts`
|
||
- Modify: `packages/core-testing/package.json` (add `@repo/core-events`)
|
||
|
||
- [ ] **Step 1: Add `@repo/core-events` to core-testing deps**
|
||
|
||
In `packages/core-testing/package.json`, add `"@repo/core-events": "workspace:*"` to `dependencies`. Then `pnpm install`.
|
||
|
||
- [ ] **Step 2: Write the implementation**
|
||
|
||
```ts
|
||
// packages/core-testing/src/instrumentation/recording-event-bus.ts
|
||
import type { z } from "zod";
|
||
import type { EventDescriptor, EventHandler, IEventBus } from "@repo/core-events";
|
||
|
||
export class RecordingEventBus implements IEventBus {
|
||
readonly published: { name: string; payload: unknown }[] = [];
|
||
private readonly handlers = new Map<string, EventHandler<unknown>[]>();
|
||
|
||
async publish<T>(
|
||
descriptor: EventDescriptor<string, z.ZodType<T>>,
|
||
payload: T,
|
||
): Promise<void> {
|
||
descriptor.schema.parse(payload);
|
||
this.published.push({ name: descriptor.name, payload });
|
||
for (const h of this.handlers.get(descriptor.name) ?? []) await h(payload);
|
||
}
|
||
|
||
subscribe<T>(
|
||
descriptor: EventDescriptor<string, z.ZodType<T>>,
|
||
_consumerFeature: string,
|
||
handler: EventHandler<T>,
|
||
): void {
|
||
const arr = this.handlers.get(descriptor.name) ?? [];
|
||
arr.push(handler as EventHandler<unknown>);
|
||
this.handlers.set(descriptor.name, arr);
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: Re-export from the barrel**
|
||
|
||
Add to `packages/core-testing/src/instrumentation/index.ts`:
|
||
|
||
```ts
|
||
export { RecordingEventBus } from "./recording-event-bus";
|
||
```
|
||
|
||
- [ ] **Step 4: Run tests; expect PASS**
|
||
|
||
Run: `pnpm --filter @repo/core-testing test -- recording-event-bus`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add packages/core-testing/src/instrumentation/recording-event-bus.ts packages/core-testing/src/instrumentation/recording-event-bus.test.ts packages/core-testing/src/instrumentation/index.ts packages/core-testing/package.json
|
||
git commit -m "feat(core-testing): RecordingEventBus"
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 4 — ESLint rules
|
||
|
||
### Task 22: Write the failing test for `no-handler-reexport`
|
||
|
||
**Files:**
|
||
- Create: `packages/core-eslint/src/no-handler-reexport.rule.test.ts`
|
||
|
||
- [ ] **Step 1: Find the existing rule-test pattern**
|
||
|
||
Run: `find packages/core-eslint -name "*.rule.ts" -o -name "*.rule.test.ts" | head`. If no custom rule tests exist yet, check `packages/core-eslint`'s test setup conventions for the canonical `RuleTester` usage.
|
||
|
||
- [ ] **Step 2: Write the test using `RuleTester`**
|
||
|
||
```ts
|
||
// packages/core-eslint/src/no-handler-reexport.rule.test.ts
|
||
import { RuleTester } from "@typescript-eslint/rule-tester";
|
||
import { describe } from "vitest";
|
||
import { rule } from "./no-handler-reexport.rule";
|
||
|
||
RuleTester.afterAll = () => {};
|
||
RuleTester.it = (text, fn) => fn();
|
||
RuleTester.itOnly = (text, fn) => fn();
|
||
RuleTester.describe = (text, fn) => fn();
|
||
|
||
const tester = new RuleTester();
|
||
|
||
describe("no-handler-reexport", () => {
|
||
tester.run("no-handler-reexport", rule, {
|
||
valid: [
|
||
{ code: `export { foo } from "./foo";`, filename: "src/index.ts" },
|
||
{ code: `export * from "./bar";`, filename: "src/index.ts" },
|
||
{ code: `export { useCase } from "./application/sign-in.use-case";`, filename: "src/index.ts" },
|
||
],
|
||
invalid: [
|
||
{
|
||
code: `export { onUserSignedUp } from "./events/handlers/on-auth-user-signed-up.handler";`,
|
||
filename: "src/index.ts",
|
||
errors: [{ messageId: "noHandlerReexport" }],
|
||
},
|
||
{
|
||
code: `export * from "./events/handlers/on-auth-user-signed-up.handler";`,
|
||
filename: "src/index.ts",
|
||
errors: [{ messageId: "noHandlerReexport" }],
|
||
},
|
||
],
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 3: Run; expect FAIL**
|
||
|
||
Run: `pnpm --filter @repo/core-eslint test -- no-handler-reexport`
|
||
Expected: FAIL — rule not exported.
|
||
|
||
### Task 23: Implement `no-handler-reexport`
|
||
|
||
**Files:**
|
||
- Create: `packages/core-eslint/src/no-handler-reexport.rule.ts`
|
||
- Modify: `packages/core-eslint/src/index.ts` or wherever rules are aggregated for distribution
|
||
- Modify: the boundary config that adds rules to feature/core packages
|
||
|
||
- [ ] **Step 1: Write the rule**
|
||
|
||
```ts
|
||
// packages/core-eslint/src/no-handler-reexport.rule.ts
|
||
import { ESLintUtils } from "@typescript-eslint/utils";
|
||
|
||
const HANDLER_PATTERN = /\/events\/handlers\/[^/]+\.handler(\.ts)?$/;
|
||
|
||
export const rule = ESLintUtils.RuleCreator.withoutDocs({
|
||
meta: {
|
||
type: "problem",
|
||
docs: { description: "Event handlers must not be re-exported (Rule E1)." },
|
||
messages: {
|
||
noHandlerReexport:
|
||
"Event handlers (`events/handlers/*.handler.ts`) must not be re-exported. Wire them only inside the consumer feature's bind-production / bind-dev-seed (Rule E1).",
|
||
},
|
||
schema: [],
|
||
},
|
||
defaultOptions: [],
|
||
create(context) {
|
||
return {
|
||
ExportNamedDeclaration(node) {
|
||
if (node.source && HANDLER_PATTERN.test(node.source.value)) {
|
||
context.report({ node, messageId: "noHandlerReexport" });
|
||
}
|
||
},
|
||
ExportAllDeclaration(node) {
|
||
if (node.source && HANDLER_PATTERN.test(node.source.value)) {
|
||
context.report({ node, messageId: "noHandlerReexport" });
|
||
}
|
||
},
|
||
};
|
||
},
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: Wire the rule into the published config**
|
||
|
||
Read the existing rule-aggregation file in `packages/core-eslint` (likely `src/index.ts` or `src/configs/feature.ts`). Register the new rule under the `@repo` namespace (or whatever the existing custom-rule namespace is). Add the rule to the feature flat-config preset so all feature packages enforce it.
|
||
|
||
- [ ] **Step 3: Run rule tests; expect PASS**
|
||
|
||
Run: `pnpm --filter @repo/core-eslint test -- no-handler-reexport`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 4: Verify no existing feature trips it**
|
||
|
||
Run: `pnpm lint`
|
||
Expected: PASS — no current code violates the rule.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add packages/core-eslint/src/no-handler-reexport.rule.ts packages/core-eslint/src/no-handler-reexport.rule.test.ts packages/core-eslint/src/index.ts
|
||
git commit -m "feat(core-eslint): rule no-handler-reexport (Rule E1)"
|
||
```
|
||
|
||
### Task 24: Write the failing test for `no-direct-payload-jobs`
|
||
|
||
**Files:**
|
||
- Create: `packages/core-eslint/src/no-direct-payload-jobs.rule.test.ts`
|
||
|
||
- [ ] **Step 1: Write the test**
|
||
|
||
```ts
|
||
// packages/core-eslint/src/no-direct-payload-jobs.rule.test.ts
|
||
import { RuleTester } from "@typescript-eslint/rule-tester";
|
||
import { describe } from "vitest";
|
||
import { rule } from "./no-direct-payload-jobs.rule";
|
||
|
||
RuleTester.afterAll = () => {};
|
||
RuleTester.it = (text, fn) => fn();
|
||
RuleTester.itOnly = (text, fn) => fn();
|
||
RuleTester.describe = (text, fn) => fn();
|
||
|
||
const tester = new RuleTester();
|
||
|
||
describe("no-direct-payload-jobs", () => {
|
||
tester.run("no-direct-payload-jobs", rule, {
|
||
valid: [
|
||
// Allowed inside the integration layer
|
||
{
|
||
code: `await payload.jobs.queue({ task: "x", input: {} });`,
|
||
filename: "packages/blog/src/integrations/cms/jobs/republish.task.ts",
|
||
},
|
||
// Allowed inside core-shared/jobs
|
||
{
|
||
code: `await payload.jobs.queue({ task: "x", input: {} });`,
|
||
filename: "packages/core-shared/src/jobs/payload-job-queue.ts",
|
||
},
|
||
// Allowed: any non-jobs payload access
|
||
{
|
||
code: `await payload.find({ collection: "x" });`,
|
||
filename: "packages/blog/src/infrastructure/repositories/articles.repository.ts",
|
||
},
|
||
],
|
||
invalid: [
|
||
{
|
||
code: `await payload.jobs.queue({ task: "x", input: {} });`,
|
||
filename: "packages/blog/src/application/use-cases/x.use-case.ts",
|
||
errors: [{ messageId: "noDirectPayloadJobs" }],
|
||
},
|
||
{
|
||
code: `await payload.jobs.queue({ task: "x", input: {} });`,
|
||
filename: "packages/blog/src/infrastructure/repositories/articles.repository.ts",
|
||
errors: [{ messageId: "noDirectPayloadJobs" }],
|
||
},
|
||
],
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: Run; expect FAIL**
|
||
|
||
Run: `pnpm --filter @repo/core-eslint test -- no-direct-payload-jobs`
|
||
Expected: FAIL.
|
||
|
||
### Task 25: Implement `no-direct-payload-jobs`
|
||
|
||
**Files:**
|
||
- Create: `packages/core-eslint/src/no-direct-payload-jobs.rule.ts`
|
||
- Modify: rule aggregation file
|
||
|
||
- [ ] **Step 1: Write the rule**
|
||
|
||
```ts
|
||
// packages/core-eslint/src/no-direct-payload-jobs.rule.ts
|
||
import { ESLintUtils } from "@typescript-eslint/utils";
|
||
|
||
const ALLOW_PATTERNS = [
|
||
/\/integrations\/cms\/jobs\//,
|
||
/\/core-shared\/src\/jobs\//,
|
||
];
|
||
|
||
export const rule = ESLintUtils.RuleCreator.withoutDocs({
|
||
meta: {
|
||
type: "problem",
|
||
docs: {
|
||
description:
|
||
"Direct `payload.jobs.*` access is forbidden outside the integration layer. Use IJobQueue.",
|
||
},
|
||
messages: {
|
||
noDirectPayloadJobs:
|
||
"`payload.jobs.*` is not allowed here. Use IJobQueue (from @repo/core-shared/jobs) instead. Allowed only in integrations/cms/jobs/** and core-shared/jobs/**.",
|
||
},
|
||
schema: [],
|
||
},
|
||
defaultOptions: [],
|
||
create(context) {
|
||
const filename = context.filename ?? context.getFilename();
|
||
if (ALLOW_PATTERNS.some((p) => p.test(filename))) return {};
|
||
return {
|
||
MemberExpression(node) {
|
||
if (
|
||
node.object.type === "MemberExpression" &&
|
||
node.object.object.type === "Identifier" &&
|
||
node.object.object.name === "payload" &&
|
||
node.object.property.type === "Identifier" &&
|
||
node.object.property.name === "jobs"
|
||
) {
|
||
context.report({ node, messageId: "noDirectPayloadJobs" });
|
||
}
|
||
},
|
||
};
|
||
},
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: Wire into the published config**
|
||
|
||
Same rule-aggregation file as Task 23. Add to feature + repository presets.
|
||
|
||
- [ ] **Step 3: Run rule tests; expect PASS**
|
||
|
||
Run: `pnpm --filter @repo/core-eslint test -- no-direct-payload-jobs`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 4: Verify no existing code trips it**
|
||
|
||
Run: `pnpm lint`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add packages/core-eslint/src/no-direct-payload-jobs.rule.ts packages/core-eslint/src/no-direct-payload-jobs.rule.test.ts packages/core-eslint/src/index.ts
|
||
git commit -m "feat(core-eslint): rule no-direct-payload-jobs"
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 5 — Existing-feature anchor retrofit
|
||
|
||
Add the six anchor comments to all five features. Each is a single-line comment that the generator will insert before. **Pure additive comments — no behavior change.** Spec § 9.1.
|
||
|
||
### Task 26: Add anchors to `auth`
|
||
|
||
**Files:**
|
||
- Modify: `packages/auth/src/index.ts`
|
||
- Modify: `packages/auth/src/di/symbols.ts`
|
||
- Modify: `packages/auth/src/di/bind-production.ts`
|
||
- Modify: `packages/auth/src/di/bind-dev-seed.ts`
|
||
- Modify: `packages/auth/src/integrations/cms/index.ts` (create file with anchor if missing)
|
||
|
||
- [ ] **Step 1: Read each target file to find the right insertion point**
|
||
|
||
For each file, the anchor goes near the bottom of the relevant section so generators insert at the natural append point.
|
||
|
||
- [ ] **Step 2: Add `// <gen:events>` to `src/index.ts`**
|
||
|
||
At the end of the file (before the final EOF, after all existing exports):
|
||
|
||
```ts
|
||
// <gen:events>
|
||
```
|
||
|
||
- [ ] **Step 3: Add anchors to `src/di/symbols.ts`**
|
||
|
||
In the symbol registry block, after the last existing entry but before any closing brace:
|
||
|
||
```ts
|
||
// <gen:event-handler-symbols>
|
||
// <gen:job-symbols>
|
||
```
|
||
|
||
The anchors live inside the `as const` symbol object — be careful to place them where TypeScript still accepts the syntax (between symbol entries, formatted as standalone comment lines).
|
||
|
||
- [ ] **Step 4: Add anchors to `src/di/bind-production.ts`**
|
||
|
||
Inside `bindProductionAuth(...)`, near the end of the function body but before the closing brace:
|
||
|
||
```ts
|
||
// <gen:event-handlers>
|
||
// <gen:jobs>
|
||
```
|
||
|
||
Place these AFTER the existing controller bindings — generators insert their blocks at the end of the binder.
|
||
|
||
- [ ] **Step 5: Add the same two anchors to `src/di/bind-dev-seed.ts`**
|
||
|
||
Same locations, near the end of the dev-seed binder function body.
|
||
|
||
- [ ] **Step 6: Handle `src/integrations/cms/index.ts`**
|
||
|
||
Run `ls packages/auth/src/integrations/cms/index.ts 2>/dev/null`.
|
||
|
||
If the file exists, add at the end:
|
||
|
||
```ts
|
||
// <gen:job-tasks>
|
||
```
|
||
|
||
If it does NOT exist, create it with just:
|
||
|
||
```ts
|
||
// packages/auth/src/integrations/cms/index.ts
|
||
// <gen:job-tasks>
|
||
export {};
|
||
```
|
||
|
||
- [ ] **Step 7: Verify nothing broke**
|
||
|
||
Run: `pnpm --filter @repo/auth typecheck test lint`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 8: Commit**
|
||
|
||
```bash
|
||
git add packages/auth/src/
|
||
git commit -m "chore(auth): add // <gen:*> anchor comments for event/job generators"
|
||
```
|
||
|
||
### Task 27: Add anchors to `blog`
|
||
|
||
Same shape as Task 26, applied to `packages/blog/src/`.
|
||
|
||
- [ ] **Step 1: Apply the six anchors per Task 26 layout**
|
||
|
||
Files: `src/index.ts`, `src/di/symbols.ts`, `src/di/bind-production.ts`, `src/di/bind-dev-seed.ts`, `src/integrations/cms/index.ts`.
|
||
|
||
- [ ] **Step 2: Verify**
|
||
|
||
Run: `pnpm --filter @repo/blog typecheck test lint`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add packages/blog/src/
|
||
git commit -m "chore(blog): add // <gen:*> anchor comments for event/job generators"
|
||
```
|
||
|
||
### Task 28: Add anchors to `media`
|
||
|
||
Same shape as Task 26, applied to `packages/media/src/`.
|
||
|
||
- [ ] **Step 1: Apply the six anchors**
|
||
- [ ] **Step 2: Verify** — `pnpm --filter @repo/media typecheck test lint`
|
||
- [ ] **Step 3: Commit** — `chore(media): add // <gen:*> anchor comments for event/job generators`
|
||
|
||
### Task 29: Add anchors to `marketing-pages`
|
||
|
||
Same shape applied to `packages/marketing-pages/src/`.
|
||
|
||
- [ ] **Step 1: Apply the six anchors**
|
||
- [ ] **Step 2: Verify** — `pnpm --filter @repo/marketing-pages typecheck test lint`
|
||
- [ ] **Step 3: Commit** — `chore(marketing-pages): add // <gen:*> anchor comments for event/job generators`
|
||
|
||
### Task 30: Add anchors to `navigation`
|
||
|
||
Same shape applied to `packages/navigation/src/`.
|
||
|
||
- [ ] **Step 1: Apply the six anchors**
|
||
- [ ] **Step 2: Verify** — `pnpm --filter @repo/navigation typecheck test lint`
|
||
- [ ] **Step 3: Commit** — `chore(navigation): add // <gen:*> anchor comments for event/job generators`
|
||
|
||
### Task 31: Add an anchor-presence CI guard
|
||
|
||
**Files:**
|
||
- Create: `tests/anchors.test.ts` (or add to an existing repo-level test file)
|
||
|
||
- [ ] **Step 1: Determine where repo-level tests live**
|
||
|
||
Run: `find . -maxdepth 3 -name "*.test.ts" -path "*/tests/*" | head` and inspect.
|
||
|
||
- [ ] **Step 2: Write a guard test**
|
||
|
||
```ts
|
||
// tests/anchors.test.ts (or appropriate location)
|
||
import { describe, it, expect } from "vitest";
|
||
import { readFileSync } from "node:fs";
|
||
import { join } from "node:path";
|
||
|
||
const FEATURES = ["auth", "blog", "media", "marketing-pages", "navigation"];
|
||
const ANCHORS = {
|
||
"src/index.ts": ["// <gen:events>"],
|
||
"src/di/symbols.ts": ["// <gen:event-handler-symbols>", "// <gen:job-symbols>"],
|
||
"src/di/bind-production.ts": ["// <gen:event-handlers>", "// <gen:jobs>"],
|
||
"src/di/bind-dev-seed.ts": ["// <gen:event-handlers>", "// <gen:jobs>"],
|
||
"src/integrations/cms/index.ts": ["// <gen:job-tasks>"],
|
||
};
|
||
|
||
describe("// <gen:*> anchor presence", () => {
|
||
for (const feature of FEATURES) {
|
||
for (const [relPath, anchors] of Object.entries(ANCHORS)) {
|
||
it(`${feature}/${relPath} contains all required anchors`, () => {
|
||
const path = join(__dirname, "..", "packages", feature, relPath);
|
||
const content = readFileSync(path, "utf8");
|
||
for (const anchor of anchors) {
|
||
expect(content).toContain(anchor);
|
||
}
|
||
});
|
||
}
|
||
}
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 3: Run; expect PASS**
|
||
|
||
Run: `pnpm vitest run tests/anchors.test.ts` (adjust path as needed)
|
||
Expected: 25 tests PASS (5 features × 5 file/anchor combinations).
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add tests/anchors.test.ts
|
||
git commit -m "test: anchor-presence CI guard for // <gen:*> comments"
|
||
```
|
||
|
||
### Task 32: Add anchors to the `feature` generator template
|
||
|
||
**Files:**
|
||
- Modify: `turbo/generators/templates/feature/src/index.ts.hbs`
|
||
- Modify: `turbo/generators/templates/feature/src/di/symbols.ts.hbs`
|
||
- Modify: `turbo/generators/templates/feature/src/di/bind-production.ts.hbs`
|
||
- Modify: `turbo/generators/templates/feature/src/di/bind-dev-seed.ts.hbs`
|
||
|
||
(The template does NOT include `integrations/cms/index.ts` — `gen feature` skips Payload CMS templates per its current Phase-1 scope, so the `<gen:job-tasks>` anchor is added by `gen job` if the user later adds CMS integration to a generated feature.)
|
||
|
||
- [ ] **Step 1: Read each `.hbs` file to find the insertion points**
|
||
- [ ] **Step 2: Add anchors at the same logical positions as Task 26**
|
||
- [ ] **Step 3: Run the existing `gen feature` against a sandbox name to verify the template still renders**
|
||
|
||
```bash
|
||
cd /tmp && cp -r ~/Documents/Projects/template-vertical /tmp/template-test && cd /tmp/template-test && pnpm install && pnpm turbo gen feature --args anchor-test AnchorTest anchor-tests && pnpm --filter @repo/anchor-test typecheck lint test
|
||
```
|
||
|
||
Expected: clean generation; package passes typecheck/lint/test.
|
||
|
||
- [ ] **Step 4: Clean up the sandbox**
|
||
|
||
```bash
|
||
rm -rf /tmp/template-test
|
||
```
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add turbo/generators/templates/feature/
|
||
git commit -m "chore(turbo-gen): add // <gen:*> anchor comments to feature template"
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 6 — Per-feature binder signatures + bindAll() bus/queue swap
|
||
|
||
### Task 33: Extend `bindProduction<Feature>` and `bindDevSeed<Feature>` signatures
|
||
|
||
**Files (per feature, applied to all 5):**
|
||
- Modify: `packages/<feature>/src/di/bind-production.ts`
|
||
- Modify: `packages/<feature>/src/di/bind-production.test.ts`
|
||
- Modify: `packages/<feature>/src/di/bind-dev-seed.ts`
|
||
- Modify: `packages/<feature>/src/di/bind-dev-seed.test.ts`
|
||
|
||
**Per-feature task structure** — the steps below apply to each feature in order: `auth`, `blog`, `media`, `marketing-pages`, `navigation`. Either bundle into one task per feature (5 commits) or one task with 5 sub-batches. Bundle.
|
||
|
||
- [ ] **Step 1: For `auth` — extend the binder signatures**
|
||
|
||
Modify `packages/auth/src/di/bind-production.ts`:
|
||
|
||
```ts
|
||
// imports — add at top
|
||
import type { IEventBus } from "@repo/core-events";
|
||
import type { IJobQueue } from "@repo/core-shared/jobs";
|
||
|
||
// signature change
|
||
export function bindProductionAuth(
|
||
config: SanitizedConfig,
|
||
tracer: ITracer,
|
||
logger: ILogger,
|
||
bus: IEventBus,
|
||
queue: IJobQueue,
|
||
): void {
|
||
// ... existing body unchanged ...
|
||
}
|
||
```
|
||
|
||
The body does NOT yet use `bus` / `queue` — Phase 7 wires them when the proof-of-life event/handler/job land. For this phase, accept-and-forward is sufficient.
|
||
|
||
- [ ] **Step 2: Same for `auth`'s `bind-dev-seed.ts`**
|
||
|
||
```ts
|
||
export async function bindDevSeedAuth(
|
||
tracer: ITracer,
|
||
logger: ILogger,
|
||
bus: IEventBus,
|
||
queue: IJobQueue,
|
||
): Promise<void> {
|
||
// ... existing body unchanged ...
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: Update `auth`'s tests**
|
||
|
||
Both `bind-production.test.ts` and `bind-dev-seed.test.ts` currently call the binders. Add a `RecordingEventBus` and `RecordingJobQueue` instantiation at the top of each test and pass them through:
|
||
|
||
```ts
|
||
import { RecordingEventBus, RecordingJobQueue } from "@repo/core-testing/instrumentation";
|
||
|
||
// inside each test:
|
||
const bus = new RecordingEventBus();
|
||
const queue = new RecordingJobQueue();
|
||
bindProductionAuth(config, tracer, logger, bus, queue);
|
||
```
|
||
|
||
Add `@repo/core-events` to `packages/auth/package.json`'s `devDependencies` if not already a dep. Add `@repo/core-shared/jobs` access (no separate install — the package is already a dep).
|
||
|
||
- [ ] **Step 4: Verify auth typechecks/tests pass**
|
||
|
||
Run: `pnpm --filter @repo/auth typecheck test lint`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 5: Commit auth**
|
||
|
||
```bash
|
||
git add packages/auth/src/di/ packages/auth/package.json
|
||
git commit -m "feat(auth): bind binders accept (bus, queue) params"
|
||
```
|
||
|
||
- [ ] **Step 6: Repeat steps 1–5 for `blog`**
|
||
|
||
Same edits applied to `packages/blog/src/di/bind-production.ts`, `bind-dev-seed.ts`, and their test files. Update `packages/blog/package.json` if needed.
|
||
|
||
Commit: `feat(blog): bind binders accept (bus, queue) params`
|
||
|
||
- [ ] **Step 7: Repeat for `media`**
|
||
|
||
Commit: `feat(media): bind binders accept (bus, queue) params`
|
||
|
||
- [ ] **Step 8: Repeat for `marketing-pages`**
|
||
|
||
Commit: `feat(marketing-pages): bind binders accept (bus, queue) params`
|
||
|
||
- [ ] **Step 9: Repeat for `navigation`**
|
||
|
||
Commit: `feat(navigation): bind binders accept (bus, queue) params`
|
||
|
||
### Task 34: Add `resolveEventsAndJobs()` to `apps/web-next` bindAll
|
||
|
||
**Files:**
|
||
- Modify: `apps/web-next/src/server/bind-production.ts`
|
||
- Modify: `apps/web-next/src/server/bind-production.test.ts`
|
||
- Modify: `apps/web-next/package.json` (add `@repo/core-events` if not already a dep)
|
||
|
||
- [ ] **Step 1: Add deps if missing**
|
||
|
||
In `apps/web-next/package.json`, add `"@repo/core-events": "workspace:*"` to `dependencies` if absent. Run `pnpm install`.
|
||
|
||
- [ ] **Step 2: Add `resolveEventsAndJobs()` to `bind-production.ts`**
|
||
|
||
```ts
|
||
// inside apps/web-next/src/server/bind-production.ts
|
||
import {
|
||
InMemoryEventBus,
|
||
PayloadJobsEventBus,
|
||
type IEventBus,
|
||
} from "@repo/core-events";
|
||
import {
|
||
InMemoryJobQueue,
|
||
PayloadJobQueue,
|
||
type IJobQueue,
|
||
} from "@repo/core-shared/jobs";
|
||
import { getPayload } from "payload";
|
||
|
||
let resolvedBus: IEventBus | null = null;
|
||
let resolvedQueue: IJobQueue | null = null;
|
||
|
||
async function resolveEventsAndJobsProduction(): Promise<{ bus: IEventBus; queue: IJobQueue }> {
|
||
if (resolvedBus && resolvedQueue) return { bus: resolvedBus, queue: resolvedQueue };
|
||
const resolvedConfig = await config;
|
||
const payload = await getPayload({ config: resolvedConfig });
|
||
const queue = new PayloadJobQueue(payload);
|
||
const bus = new PayloadJobsEventBus(queue);
|
||
resolvedBus = bus;
|
||
resolvedQueue = queue;
|
||
return { bus, queue };
|
||
}
|
||
|
||
function resolveEventsAndJobsDevSeed(): { bus: IEventBus; queue: IJobQueue } {
|
||
if (resolvedBus && resolvedQueue) return { bus: resolvedBus, queue: resolvedQueue };
|
||
// In-memory queue starts with no handlers; per-feature binders will register them.
|
||
// We construct one empty queue per app-boot; the dev-seed binders mutate the
|
||
// shared `handlers` map by re-creating the queue once they know their tasks.
|
||
// For Phase 1 we accept that dev-seed jobs run in-process via the binders'
|
||
// direct closure; the queue.enqueue path is exercised by tests using
|
||
// RecordingJobQueue, which is sufficient validation.
|
||
const queue = new InMemoryJobQueue({});
|
||
const bus = new InMemoryEventBus();
|
||
resolvedBus = bus;
|
||
resolvedQueue = queue;
|
||
return { bus, queue };
|
||
}
|
||
```
|
||
|
||
> **Implementation note:** `InMemoryJobQueue`'s constructor takes a static handler map — but features want to register handlers at bind time. Two options:
|
||
> 1. Make `InMemoryJobQueue` mutable with a `register(slug, handler)` method (small API change in Phase 1).
|
||
> 2. Defer handler registration to a per-feature mechanism and exercise the queue only via test recordings.
|
||
>
|
||
> **Choice for this plan:** go with option 1. Add `register(slug, handler)` to `InMemoryJobQueue` as a follow-up step inside this task (sub-step below).
|
||
|
||
- [ ] **Step 3: Add `register` method to `InMemoryJobQueue`**
|
||
|
||
In `packages/core-shared/src/jobs/in-memory-job-queue.ts`:
|
||
|
||
```ts
|
||
// add inside class InMemoryJobQueue
|
||
register(slug: string, handler: InMemoryHandler): void {
|
||
this.handlers[slug] = handler;
|
||
}
|
||
```
|
||
|
||
Constructor changes:
|
||
|
||
```ts
|
||
constructor(handlers: Record<string, InMemoryHandler> = {}) {
|
||
this.handlers = { ...handlers };
|
||
}
|
||
private readonly handlers: Record<string, InMemoryHandler>;
|
||
```
|
||
|
||
Add a unit test in `in-memory-job-queue.test.ts`:
|
||
|
||
```ts
|
||
it("register adds a handler that can be enqueued against", async () => {
|
||
const queue = new InMemoryJobQueue();
|
||
const handler = vi.fn();
|
||
queue.register("late.task", handler);
|
||
await queue.enqueue("late.task", { z: 1 });
|
||
await new Promise((r) => setImmediate(r));
|
||
expect(handler).toHaveBeenCalledWith({ z: 1 });
|
||
});
|
||
```
|
||
|
||
Run tests: `pnpm --filter @repo/core-shared test -- in-memory-job-queue` — expect PASS.
|
||
|
||
- [ ] **Step 4: Update `bindAllProduction` and `bindAllDevSeed` to pass through**
|
||
|
||
```ts
|
||
export async function bindAllProduction(): Promise<void> {
|
||
if (bound) return;
|
||
bound = true;
|
||
const { tracer, logger } = resolveInstrumentation();
|
||
const { bus, queue } = await resolveEventsAndJobsProduction();
|
||
const resolvedConfig = await config;
|
||
bindProductionAuth(resolvedConfig, tracer, logger, bus, queue);
|
||
bindProductionBlog(resolvedConfig, tracer, logger, bus, queue);
|
||
bindProductionMarketingPages(resolvedConfig, tracer, logger, bus, queue);
|
||
bindProductionNavigation(resolvedConfig, tracer, logger, bus, queue);
|
||
bindProductionMedia(resolvedConfig, tracer, logger, bus, queue);
|
||
}
|
||
|
||
export async function bindAllDevSeed(): Promise<void> {
|
||
if (bound) return;
|
||
bound = true;
|
||
const { tracer, logger } = resolveInstrumentation();
|
||
const { bus, queue } = resolveEventsAndJobsDevSeed();
|
||
await bindDevSeedAuth(tracer, logger, bus, queue);
|
||
await bindDevSeedBlog(tracer, logger, bus, queue);
|
||
await bindDevSeedMarketingPages(tracer, logger, bus, queue);
|
||
await bindDevSeedNavigation(tracer, logger, bus, queue);
|
||
await bindDevSeedMedia(tracer, logger, bus, queue);
|
||
}
|
||
```
|
||
|
||
Update `__resetBindStateForTests`:
|
||
|
||
```ts
|
||
export function __resetBindStateForTests(): void {
|
||
bound = false;
|
||
resolvedTracer = null;
|
||
resolvedLogger = null;
|
||
resolvedBus = null;
|
||
resolvedQueue = null;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 5: Update `bind-production.test.ts`**
|
||
|
||
Read the existing test file. Update it to assert that `bindAllProduction` resolves the Payload-backed bus + queue and that `bindAllDevSeed` resolves the in-memory ones. Add a test asserting `bus` and `queue` are passed to each per-feature binder (use `vi.mock` on the per-feature binders, or read existing mocking patterns).
|
||
|
||
- [ ] **Step 6: Verify**
|
||
|
||
Run: `pnpm --filter @repo/web-next typecheck test lint`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 7: Commit**
|
||
|
||
```bash
|
||
git add apps/web-next/ packages/core-shared/src/jobs/
|
||
git commit -m "feat(web-next): bindAll resolves IEventBus + IJobQueue per env (spec § 6.3)"
|
||
```
|
||
|
||
### Task 35: Mirror Task 34 to other apps that have a bindAll
|
||
|
||
**Files:**
|
||
- Modify: `apps/cms/src/server/bind-production.ts` (if exists)
|
||
- Modify: `apps/web-tanstack/src/server/bind-production.ts` (if exists)
|
||
|
||
- [ ] **Step 1: Check for the file in each app**
|
||
|
||
Run: `ls apps/cms/src/server/bind-production.ts apps/web-tanstack/src/server/bind-production.ts 2>/dev/null`
|
||
|
||
- [ ] **Step 2: For each existing file, apply the same changes as Task 34**
|
||
|
||
Use the same `resolveEventsAndJobs*` helpers. The CMS app uses Payload natively, so production mode for it will always wire `PayloadJobsEventBus` + `PayloadJobQueue`.
|
||
|
||
- [ ] **Step 3: Verify each app**
|
||
|
||
Run: `pnpm --filter @repo/cms typecheck test lint && pnpm --filter @repo/web-tanstack typecheck test lint` (skip filters for non-existent apps).
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add apps/cms/ apps/web-tanstack/
|
||
git commit -m "feat(cms,web-tanstack): bindAll resolves IEventBus + IJobQueue per env"
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 7 — Generators
|
||
|
||
### Task 36: Anchor-presence validation helper
|
||
|
||
**Files:**
|
||
- Create: `turbo/generators/lib/anchor-validate.ts`
|
||
|
||
- [ ] **Step 1: Write the helper**
|
||
|
||
```ts
|
||
// turbo/generators/lib/anchor-validate.ts
|
||
import { existsSync, readFileSync } from "node:fs";
|
||
import { join } from "node:path";
|
||
|
||
/**
|
||
* Throws with a clear message if any anchor is missing from the target file.
|
||
* Used in generator prompt validators to abort before writing partial output.
|
||
*/
|
||
export function assertAnchors(
|
||
repoRoot: string,
|
||
relativePath: string,
|
||
anchors: string[],
|
||
): void {
|
||
const path = join(repoRoot, relativePath);
|
||
if (!existsSync(path)) {
|
||
throw new Error(`Required file does not exist: ${relativePath}`);
|
||
}
|
||
const content = readFileSync(path, "utf8");
|
||
for (const anchor of anchors) {
|
||
if (!content.includes(anchor)) {
|
||
throw new Error(
|
||
`Missing anchor "${anchor}" in ${relativePath}. Add it before running this generator.`,
|
||
);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: No test in TDD style — exercised via the generator's own smoke runs**
|
||
|
||
(Plop generators are notoriously hard to unit-test without a sandbox; we rely on the smoke tests in Tasks 38, 40, 42.)
|
||
|
||
- [ ] **Step 3: Verify it compiles in the generators dir**
|
||
|
||
Run: `cd turbo/generators && npx tsc --noEmit`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add turbo/generators/lib/anchor-validate.ts
|
||
git commit -m "feat(turbo-gen): assertAnchors helper"
|
||
```
|
||
|
||
### Task 37: Generator templates for `gen event publish`
|
||
|
||
**Files:**
|
||
- Create: `turbo/generators/templates/event/publish/event.ts.hbs`
|
||
- Create: `turbo/generators/templates/event/publish/event.test.ts.hbs`
|
||
|
||
- [ ] **Step 1: Write `event.ts.hbs`**
|
||
|
||
```hbs
|
||
// packages/{{kebabCase feature}}/src/events/{{kebabCase event}}.event.ts
|
||
import { z } from "zod";
|
||
import { defineEvent } from "@repo/core-events";
|
||
|
||
export const {{camelCase event}}EventSchema = z.object({}).strict();
|
||
|
||
export type {{pascalCase event}}Event = z.infer<typeof {{camelCase event}}EventSchema>;
|
||
|
||
export const {{camelCase event}}Event = defineEvent(
|
||
"{{kebabCase feature}}.{{dotCase event}}",
|
||
{{camelCase event}}EventSchema,
|
||
);
|
||
```
|
||
|
||
> **Plop helper note:** Plop ships kebab/camel/pascal helpers but not "dotCase". In Plop, register a custom helper or use `replace`. Easiest: have the prompt accept the dotted form directly (e.g. `user.signed-up`) and use `{{event}}` raw in the template for the wire name; use `{{kebabCase event}}` (which converts dots to hyphens) for the file name. Update template to use raw `{{event}}` for the descriptor name.
|
||
|
||
Revised template:
|
||
|
||
```hbs
|
||
// packages/{{kebabCase feature}}/src/events/{{kebabCase event}}.event.ts
|
||
import { z } from "zod";
|
||
import { defineEvent } from "@repo/core-events";
|
||
|
||
export const {{camelCase event}}EventSchema = z.object({}).strict();
|
||
|
||
export type {{pascalCase event}}Event = z.infer<typeof {{camelCase event}}EventSchema>;
|
||
|
||
export const {{camelCase event}}Event = defineEvent(
|
||
"{{kebabCase feature}}.{{event}}",
|
||
{{camelCase event}}EventSchema,
|
||
);
|
||
```
|
||
|
||
- [ ] **Step 2: Write `event.test.ts.hbs`**
|
||
|
||
```hbs
|
||
// packages/{{kebabCase feature}}/src/events/{{kebabCase event}}.event.test.ts
|
||
import { describe, it, expect } from "vitest";
|
||
import { {{camelCase event}}EventSchema, {{camelCase event}}Event } from "@/events/{{kebabCase event}}.event";
|
||
|
||
describe("{{camelCase event}}Event", () => {
|
||
it("has the correct wire name", () => {
|
||
expect({{camelCase event}}Event.name).toBe("{{kebabCase feature}}.{{event}}");
|
||
});
|
||
|
||
it("validates an empty payload (stub schema)", () => {
|
||
expect(() => {{camelCase event}}EventSchema.parse({})).not.toThrow();
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add turbo/generators/templates/event/publish/
|
||
git commit -m "feat(turbo-gen): templates for gen event publish"
|
||
```
|
||
|
||
### Task 38: Wire `gen event publish` into `turbo/generators/config.ts`
|
||
|
||
**Files:**
|
||
- Modify: `turbo/generators/config.ts`
|
||
|
||
- [ ] **Step 1: Read `config.ts` to understand the existing generator structure**
|
||
|
||
The `feature` generator is the reference. We add a new `event` generator with a `mode` prompt that branches.
|
||
|
||
- [ ] **Step 2: Add the `event` generator (publish branch)**
|
||
|
||
Inside the `generator(plop)` function, after the existing `feature` generator's `setGenerator` call:
|
||
|
||
```ts
|
||
plop.setGenerator("event", {
|
||
description: "Scaffold an event contract (publish) or handler (consume)",
|
||
prompts: [
|
||
{
|
||
type: "list",
|
||
name: "mode",
|
||
message: "Mode:",
|
||
choices: ["publish", "consume"],
|
||
},
|
||
{
|
||
type: "input",
|
||
name: "feature",
|
||
message:
|
||
"Owning feature (kebab-case; for publish: contract package; for consume: consumer package):",
|
||
validate(input: string) {
|
||
if (!/^[a-z][a-z0-9-]*$/.test(input)) return "Must be kebab-case";
|
||
if (!existsSync(join(process.cwd(), "packages", input, "src"))) {
|
||
return `packages/${input}/src does not exist`;
|
||
}
|
||
return true;
|
||
},
|
||
},
|
||
{
|
||
type: "input",
|
||
name: "event",
|
||
message:
|
||
"Event slug (dotted-kebab past tense, e.g. 'user.signed-up'):",
|
||
validate(input: string) {
|
||
if (!/^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/.test(input)) {
|
||
return "Must be dotted-kebab past tense (e.g. user.signed-up)";
|
||
}
|
||
return true;
|
||
},
|
||
},
|
||
{
|
||
type: "input",
|
||
name: "publisher",
|
||
message:
|
||
"Publisher feature (kebab-case; only for consume mode):",
|
||
when(answers: { mode: string }) {
|
||
return answers.mode === "consume";
|
||
},
|
||
validate(input: string, answers: { event: string }) {
|
||
if (!/^[a-z][a-z0-9-]*$/.test(input)) return "Must be kebab-case";
|
||
const eventKebab = answers.event.replace(/\./g, "-");
|
||
const path = join(
|
||
process.cwd(),
|
||
"packages",
|
||
input,
|
||
"src",
|
||
"events",
|
||
`${eventKebab}.event.ts`,
|
||
);
|
||
if (!existsSync(path)) {
|
||
return `Publisher contract not found: ${path}`;
|
||
}
|
||
return true;
|
||
},
|
||
},
|
||
],
|
||
actions(answers) {
|
||
const a = answers as {
|
||
mode: "publish" | "consume";
|
||
feature: string;
|
||
event: string;
|
||
publisher?: string;
|
||
};
|
||
if (a.mode === "publish") return publishActions(a);
|
||
return consumeActions(a);
|
||
},
|
||
});
|
||
```
|
||
|
||
Add helpers `publishActions` and `consumeActions` and `existsSync`/`join` imports at the top of `config.ts`.
|
||
|
||
- [ ] **Step 3: Implement `publishActions`**
|
||
|
||
```ts
|
||
function publishActions(a: { feature: string; event: string }): PlopTypes.ActionType[] {
|
||
const eventKebab = a.event.replace(/\./g, "-");
|
||
const indexPath = `packages/${a.feature}/src/index.ts`;
|
||
return [
|
||
() => {
|
||
assertAnchors(process.cwd(), indexPath, ["// <gen:events>"]);
|
||
return `Anchors verified in ${indexPath}`;
|
||
},
|
||
{
|
||
type: "add",
|
||
path: `packages/${a.feature}/src/events/${eventKebab}.event.ts`,
|
||
templateFile: "templates/event/publish/event.ts.hbs",
|
||
data: { event: a.event, feature: a.feature, eventKebab },
|
||
},
|
||
{
|
||
type: "add",
|
||
path: `packages/${a.feature}/src/events/${eventKebab}.event.test.ts`,
|
||
templateFile: "templates/event/publish/event.test.ts.hbs",
|
||
data: { event: a.event, feature: a.feature, eventKebab },
|
||
},
|
||
{
|
||
type: "modify",
|
||
path: indexPath,
|
||
pattern: /\/\/ <gen:events>/,
|
||
template: `// <gen:events>\nexport {\n {{camelCase event}}Event,\n {{camelCase event}}EventSchema,\n type {{pascalCase event}}Event,\n} from "./events/{{kebabCase event}}.event";`,
|
||
data: { event: a.event },
|
||
},
|
||
() => printPublishNextSteps(a),
|
||
];
|
||
}
|
||
|
||
function printPublishNextSteps(a: { feature: string; event: string }): string {
|
||
return [
|
||
"",
|
||
"─────────────────────────────────────────────────────────────",
|
||
`Event ${a.feature}.${a.event} contract scaffolded.`,
|
||
"",
|
||
"Next steps (manual):",
|
||
` 1. Fill in the schema in packages/${a.feature}/src/events/${a.event.replace(/\./g, "-")}.event.ts`,
|
||
` 2. Pick a use case in packages/${a.feature}/src/application/use-cases/ that should publish.`,
|
||
` - Add 'bus: IEventBus' to the factory signature.`,
|
||
` - Call 'await bus.publish(${camelCase(a.event)}Event, payload)' after success.`,
|
||
` - Update the use case's DI binding to inject the bus.`,
|
||
` 3. Verify: pnpm --filter @repo/${a.feature} lint typecheck test`,
|
||
"─────────────────────────────────────────────────────────────",
|
||
"",
|
||
].join("\n");
|
||
}
|
||
```
|
||
|
||
(Define a small local `camelCase` helper at the bottom of `config.ts` if not already present — see how `feature` generator's `cap`/`camel` helpers are defined.)
|
||
|
||
- [ ] **Step 4: Smoke-test the publish branch**
|
||
|
||
Run from `/tmp` with a copy of the repo:
|
||
|
||
```bash
|
||
cp -r ~/Documents/Projects/template-vertical /tmp/gen-test && cd /tmp/gen-test && pnpm install && pnpm turbo gen event --args publish auth user.signed-up && pnpm --filter @repo/auth typecheck test lint
|
||
```
|
||
|
||
Expected: clean generation; `packages/auth/src/events/user-signed-up.event.ts` and its test exist; `auth/src/index.ts` re-exports the contract; package passes typecheck/lint/test.
|
||
|
||
- [ ] **Step 5: Clean up sandbox; commit**
|
||
|
||
```bash
|
||
rm -rf /tmp/gen-test
|
||
git add turbo/generators/config.ts
|
||
git commit -m "feat(turbo-gen): event generator (publish mode)"
|
||
```
|
||
|
||
### Task 39: Generator templates for `gen event consume`
|
||
|
||
**Files:**
|
||
- Create: `turbo/generators/templates/event/consume/handler.ts.hbs`
|
||
- Create: `turbo/generators/templates/event/consume/handler.test.ts.hbs`
|
||
- Create: `turbo/generators/templates/event/consume/event-task.ts.hbs`
|
||
|
||
- [ ] **Step 1: Write `handler.ts.hbs`**
|
||
|
||
```hbs
|
||
// packages/{{kebabCase feature}}/src/events/handlers/on-{{kebabCase publisher}}-{{kebabCase event}}.handler.ts
|
||
import type { {{pascalCase event}}Event } from "@repo/{{kebabCase publisher}}";
|
||
|
||
export type IOn{{pascalCase publisher}}{{pascalCase event}}Handler = ReturnType<
|
||
typeof on{{pascalCase publisher}}{{pascalCase event}}Handler
|
||
>;
|
||
|
||
export const on{{pascalCase publisher}}{{pascalCase event}}Handler =
|
||
() =>
|
||
async (_event: {{pascalCase event}}Event): Promise<void> => {
|
||
// TODO: implement the reaction. Inject dependencies via the factory's
|
||
// constructor and use them here. The handler runs inside the consumer's
|
||
// span+capture sandwich, so just throwing on failure is the right shape.
|
||
};
|
||
```
|
||
|
||
- [ ] **Step 2: Write `handler.test.ts.hbs`**
|
||
|
||
```hbs
|
||
// packages/{{kebabCase feature}}/src/events/handlers/on-{{kebabCase publisher}}-{{kebabCase event}}.handler.test.ts
|
||
import { describe, it, expect } from "vitest";
|
||
import { on{{pascalCase publisher}}{{pascalCase event}}Handler } from "@/events/handlers/on-{{kebabCase publisher}}-{{kebabCase event}}.handler";
|
||
|
||
describe("on{{pascalCase publisher}}{{pascalCase event}}Handler", () => {
|
||
it("returns a function (factory shape)", () => {
|
||
const handler = on{{pascalCase publisher}}{{pascalCase event}}Handler();
|
||
expect(typeof handler).toBe("function");
|
||
});
|
||
|
||
it("does not throw on a valid stub event", async () => {
|
||
const handler = on{{pascalCase publisher}}{{pascalCase event}}Handler();
|
||
await expect(handler({} as never)).resolves.toBeUndefined();
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 3: Write `event-task.ts.hbs`** (Payload task that completes the production bus loop)
|
||
|
||
```hbs
|
||
// packages/{{kebabCase feature}}/src/integrations/cms/jobs/__events-{{kebabCase publisher}}-{{kebabCase event}}.task.ts
|
||
// Generated by `gen event consume`. The PayloadJobsEventBus enqueues this task
|
||
// when {{kebabCase publisher}} publishes `{{kebabCase publisher}}.{{event}}`. The handler
|
||
// resolves the consumer's wrapped event handler from the per-feature container
|
||
// and invokes it with the typed payload.
|
||
import type { TaskConfig } from "payload";
|
||
import { {{camelCase feature}}Container } from "../../../di/container";
|
||
import { {{constantCase feature}}_SYMBOLS } from "../../../di/symbols";
|
||
import type { IOn{{pascalCase publisher}}{{pascalCase event}}Handler } from "../../../events/handlers/on-{{kebabCase publisher}}-{{kebabCase event}}.handler";
|
||
import type { {{pascalCase event}}Event } from "@repo/{{kebabCase publisher}}";
|
||
|
||
export const on{{pascalCase publisher}}{{pascalCase event}}EventTask: TaskConfig<"__events.{{kebabCase publisher}}.{{event}}.{{kebabCase feature}}"> = {
|
||
slug: "__events.{{kebabCase publisher}}.{{event}}.{{kebabCase feature}}",
|
||
inputSchema: [],
|
||
retries: { attempts: 3, backoff: { type: "exponential", delay: 1000 } },
|
||
handler: async ({ input }) => {
|
||
const handler = {{camelCase feature}}Container.get<IOn{{pascalCase publisher}}{{pascalCase event}}Handler>(
|
||
{{constantCase feature}}_SYMBOLS.IOn{{pascalCase publisher}}{{pascalCase event}}Handler,
|
||
);
|
||
await handler(input as {{pascalCase event}}Event);
|
||
return { output: {} };
|
||
},
|
||
};
|
||
```
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add turbo/generators/templates/event/consume/
|
||
git commit -m "feat(turbo-gen): templates for gen event consume (handler + Payload task)"
|
||
```
|
||
|
||
### Task 40: Wire `gen event consume` actions and modify-blocks
|
||
|
||
**Files:**
|
||
- Modify: `turbo/generators/config.ts`
|
||
|
||
- [ ] **Step 1: Implement `consumeActions` in `config.ts`**
|
||
|
||
```ts
|
||
function consumeActions(a: {
|
||
feature: string;
|
||
event: string;
|
||
publisher: string;
|
||
}): PlopTypes.ActionType[] {
|
||
const eventKebab = a.event.replace(/\./g, "-");
|
||
const handlerName = `on${pascalCase(a.publisher)}${pascalCase(a.event)}`;
|
||
const symbolFile = `packages/${a.feature}/src/di/symbols.ts`;
|
||
const bindProdFile = `packages/${a.feature}/src/di/bind-production.ts`;
|
||
const bindDevFile = `packages/${a.feature}/src/di/bind-dev-seed.ts`;
|
||
const cmsIndexFile = `packages/${a.feature}/src/integrations/cms/index.ts`;
|
||
return [
|
||
() => {
|
||
assertAnchors(process.cwd(), symbolFile, ["// <gen:event-handler-symbols>"]);
|
||
assertAnchors(process.cwd(), bindProdFile, ["// <gen:event-handlers>"]);
|
||
assertAnchors(process.cwd(), bindDevFile, ["// <gen:event-handlers>"]);
|
||
assertAnchors(process.cwd(), cmsIndexFile, ["// <gen:job-tasks>"]);
|
||
return "All required anchors present";
|
||
},
|
||
{
|
||
type: "add",
|
||
path: `packages/${a.feature}/src/events/handlers/on-${a.publisher}-${eventKebab}.handler.ts`,
|
||
templateFile: "templates/event/consume/handler.ts.hbs",
|
||
data: a,
|
||
},
|
||
{
|
||
type: "add",
|
||
path: `packages/${a.feature}/src/events/handlers/on-${a.publisher}-${eventKebab}.handler.test.ts`,
|
||
templateFile: "templates/event/consume/handler.test.ts.hbs",
|
||
data: a,
|
||
},
|
||
// Production-bus task config — completes the PayloadJobsEventBus loop.
|
||
// Slug must match what PayloadJobsEventBus.publish enqueues:
|
||
// __events.<publisher>.<event>.<consumer>
|
||
{
|
||
type: "add",
|
||
path: `packages/${a.feature}/src/integrations/cms/jobs/__events-${a.publisher}-${eventKebab}.task.ts`,
|
||
templateFile: "templates/event/consume/event-task.ts.hbs",
|
||
data: a,
|
||
},
|
||
{
|
||
type: "modify",
|
||
path: symbolFile,
|
||
pattern: /\/\/ <gen:event-handler-symbols>/,
|
||
template: `// <gen:event-handler-symbols>\n I${pascalCase(a.publisher)}${pascalCase(a.event)}Handler: Symbol.for("@repo/${a.feature}/${handlerName}"),`,
|
||
},
|
||
{
|
||
type: "modify",
|
||
path: bindProdFile,
|
||
pattern: /\/\/ <gen:event-handlers>/,
|
||
template: handlerBindBlock(a, "production"),
|
||
},
|
||
{
|
||
type: "modify",
|
||
path: bindDevFile,
|
||
pattern: /\/\/ <gen:event-handlers>/,
|
||
template: handlerBindBlock(a, "dev-seed"),
|
||
},
|
||
// Re-export the event-task config from integrations/cms/index.ts so
|
||
// core-cms picks it up when aggregating Payload tasks.
|
||
{
|
||
type: "modify",
|
||
path: cmsIndexFile,
|
||
pattern: /\/\/ <gen:job-tasks>/,
|
||
template: `// <gen:job-tasks>\nexport { on${pascalCase(a.publisher)}${pascalCase(a.event)}EventTask } from "./jobs/__events-${a.publisher}-${eventKebab}.task";`,
|
||
},
|
||
() => printConsumeNextSteps(a),
|
||
];
|
||
}
|
||
|
||
function handlerBindBlock(
|
||
a: { feature: string; event: string; publisher: string },
|
||
_mode: "production" | "dev-seed",
|
||
): string {
|
||
const handlerFn = `on${pascalCase(a.publisher)}${pascalCase(a.event)}Handler`;
|
||
const eventConst = `${camelCase(a.event)}Event`;
|
||
const handlerSymbol = `${constantCase(a.feature)}_SYMBOLS.IOn${pascalCase(a.publisher)}${pascalCase(a.event)}Handler`;
|
||
const wrappedVar = `wrapped${pascalCase(a.publisher)}${pascalCase(a.event)}`;
|
||
const containerVar = `${camelCase(a.feature)}Container`;
|
||
return `// <gen:event-handlers>
|
||
// ${handlerFn} subscription — generated, edit the handler file (not this block) for behavior.
|
||
const ${wrappedVar} = withSpan(
|
||
tracer,
|
||
{ name: "${a.feature}.${handlerFn}", op: "event-handler" },
|
||
withCapture(
|
||
logger,
|
||
{
|
||
feature: "${a.feature}",
|
||
layer: "event-handler",
|
||
name: "${a.feature}.${handlerFn}",
|
||
},
|
||
${handlerFn}(),
|
||
),
|
||
);
|
||
// Bind into the per-feature container so the production __events.* task
|
||
// can resolve and invoke the wrapped handler.
|
||
if (${containerVar}.isBound(${handlerSymbol})) {
|
||
${containerVar}.unbind(${handlerSymbol});
|
||
}
|
||
${containerVar}.bind(${handlerSymbol}).toConstantValue(${wrappedVar});
|
||
// Subscribe so the in-memory bus delivers in dev/test, and so the production
|
||
// bus knows which consumers to fan out __events.* tasks for.
|
||
bus.subscribe(${eventConst}, "${a.feature}", ${wrappedVar});`;
|
||
}
|
||
|
||
function printConsumeNextSteps(a: { feature: string; event: string; publisher: string }): string {
|
||
return [
|
||
"",
|
||
"─────────────────────────────────────────────────────────────",
|
||
`Handler on-${a.publisher}-${a.event.replace(/\./g, "-")} scaffolded in ${a.feature}.`,
|
||
"",
|
||
"Next steps (manual):",
|
||
` 1. Implement the handler body in packages/${a.feature}/src/events/handlers/.`,
|
||
` 2. Add the import for ${camelCase(a.event)}Event in bind-production.ts and bind-dev-seed.ts (from @repo/${a.publisher}).`,
|
||
` 3. If your handler needs dependencies, add them to the factory signature and pass them in the generated bind block.`,
|
||
` 4. Verify: pnpm --filter @repo/${a.feature} lint typecheck test`,
|
||
"─────────────────────────────────────────────────────────────",
|
||
"",
|
||
].join("\n");
|
||
}
|
||
```
|
||
|
||
> **Note:** The generated bind block does NOT include the import for `<event>Event` from the publisher — that's a manual edit (printed in the next-steps). This is intentional: imports go at the top of the file, not at the anchor location, and Plop's `modify` is awkward for that. The user adds one import line.
|
||
|
||
- [ ] **Step 2: Smoke-test consume mode**
|
||
|
||
Use a sandbox copy. First run a publish from auth, then a consume in marketing-pages:
|
||
|
||
```bash
|
||
cp -r ~/Documents/Projects/template-vertical /tmp/gen-test2 && cd /tmp/gen-test2 && pnpm install
|
||
pnpm turbo gen event --args publish auth user.signed-up
|
||
pnpm turbo gen event --args consume marketing-pages user.signed-up auth
|
||
# manually edit marketing-pages/src/di/bind-production.ts to add the import for userSignedUpEvent
|
||
pnpm --filter @repo/marketing-pages typecheck test lint
|
||
```
|
||
|
||
Expected: typecheck/lint/test pass after the manual import edit.
|
||
|
||
- [ ] **Step 3: Clean up sandbox; commit**
|
||
|
||
```bash
|
||
rm -rf /tmp/gen-test2
|
||
git add turbo/generators/config.ts
|
||
git commit -m "feat(turbo-gen): event generator (consume mode)"
|
||
```
|
||
|
||
### Task 41: Generator templates for `gen job`
|
||
|
||
**Files:**
|
||
- Create: `turbo/generators/templates/job/job.ts.hbs`
|
||
- Create: `turbo/generators/templates/job/job.test.ts.hbs`
|
||
- Create: `turbo/generators/templates/job/task.ts.hbs`
|
||
|
||
- [ ] **Step 1: Write `job.ts.hbs`**
|
||
|
||
```hbs
|
||
// packages/{{kebabCase feature}}/src/jobs/{{kebabCase job}}.job.ts
|
||
import { z } from "zod";
|
||
|
||
{{#if (eq inputShape "typed")}}
|
||
export const {{camelCase job}}InputSchema = z
|
||
.object({ exampleField: z.string() })
|
||
.strict();
|
||
{{else}}
|
||
export const {{camelCase job}}InputSchema = z.object({}).strict();
|
||
{{/if}}
|
||
|
||
export type {{pascalCase job}}Input = z.infer<typeof {{camelCase job}}InputSchema>;
|
||
export type I{{pascalCase job}}Job = ReturnType<typeof {{camelCase job}}Job>;
|
||
|
||
export const {{camelCase job}}Job =
|
||
() =>
|
||
async (input: {{pascalCase job}}Input): Promise<void> => {
|
||
{{camelCase job}}InputSchema.parse(input);
|
||
// TODO: implement the job. Inject dependencies via the factory's constructor.
|
||
};
|
||
```
|
||
|
||
> **Plop helper note:** Plop ships `eq` via the inquirer integration; if it isn't registered, replace the conditional with two separate template files (e.g., `job.ts.void.hbs` and `job.ts.typed.hbs`) selected by `actions`. Test which works during smoke-testing.
|
||
|
||
- [ ] **Step 2: Write `job.test.ts.hbs`**
|
||
|
||
```hbs
|
||
// packages/{{kebabCase feature}}/src/jobs/{{kebabCase job}}.job.test.ts
|
||
import { describe, it, expect } from "vitest";
|
||
import { {{camelCase job}}Job, {{camelCase job}}InputSchema } from "@/jobs/{{kebabCase job}}.job";
|
||
|
||
describe("{{camelCase job}}Job", () => {
|
||
it("validates input via the schema", async () => {
|
||
const job = {{camelCase job}}Job();
|
||
await expect(job({ unexpectedField: 1 } as never)).rejects.toThrow();
|
||
});
|
||
|
||
it("accepts valid input", async () => {
|
||
const job = {{camelCase job}}Job();
|
||
{{#if (eq inputShape "typed")}}
|
||
await expect(job({ exampleField: "x" })).resolves.toBeUndefined();
|
||
{{else}}
|
||
await expect(job({})).resolves.toBeUndefined();
|
||
{{/if}}
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 3: Write `task.ts.hbs`**
|
||
|
||
```hbs
|
||
// packages/{{kebabCase feature}}/src/integrations/cms/jobs/{{kebabCase job}}.task.ts
|
||
import type { TaskConfig } from "payload";
|
||
import { {{camelCase feature}}Container } from "../../../di/container";
|
||
import { {{constantCase feature}}_SYMBOLS } from "../../../di/symbols";
|
||
import type { I{{pascalCase job}}Job } from "../../../jobs/{{kebabCase job}}.job";
|
||
|
||
export const {{camelCase job}}Task: TaskConfig<"{{kebabCase feature}}.{{kebabCase job}}"> = {
|
||
slug: "{{kebabCase feature}}.{{kebabCase job}}",
|
||
inputSchema: [],
|
||
retries: { attempts: 3, backoff: { type: "exponential", delay: 1000 } },
|
||
handler: async ({ input }) => {
|
||
const job = {{camelCase feature}}Container.get<I{{pascalCase job}}Job>(
|
||
{{constantCase feature}}_SYMBOLS.I{{pascalCase job}}Job,
|
||
);
|
||
await job(input as never);
|
||
return { output: {} };
|
||
},
|
||
};
|
||
```
|
||
|
||
> The `handler` reads from the per-feature container directly (Inversify singleton). If a feature's container needs the Payload `req` for some other reason, that's a per-feature edit; the default scaffolded shape is "container resolves the wrapped job."
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add turbo/generators/templates/job/
|
||
git commit -m "feat(turbo-gen): templates for gen job"
|
||
```
|
||
|
||
### Task 42: Wire `gen job` actions and modify-blocks
|
||
|
||
**Files:**
|
||
- Modify: `turbo/generators/config.ts`
|
||
|
||
- [ ] **Step 1: Add the `job` generator**
|
||
|
||
```ts
|
||
plop.setGenerator("job", {
|
||
description: "Scaffold a background job in an existing feature",
|
||
prompts: [
|
||
{
|
||
type: "input",
|
||
name: "feature",
|
||
message: "Feature (kebab-case, must exist):",
|
||
validate(input: string) {
|
||
if (!/^[a-z][a-z0-9-]*$/.test(input)) return "Must be kebab-case";
|
||
if (!existsSync(join(process.cwd(), "packages", input, "src"))) {
|
||
return `packages/${input}/src does not exist`;
|
||
}
|
||
return true;
|
||
},
|
||
},
|
||
{
|
||
type: "input",
|
||
name: "job",
|
||
message: "Job slug (verb-noun kebab, e.g. 'send-welcome-email'):",
|
||
validate(input: string) {
|
||
if (!/^[a-z][a-z0-9-]+$/.test(input)) return "Must be kebab-case";
|
||
return true;
|
||
},
|
||
},
|
||
{
|
||
type: "list",
|
||
name: "inputShape",
|
||
message: "Input shape:",
|
||
choices: ["void", "typed"],
|
||
default: "void",
|
||
},
|
||
],
|
||
actions(answers) {
|
||
const a = answers as { feature: string; job: string; inputShape: "void" | "typed" };
|
||
return jobActions(a);
|
||
},
|
||
});
|
||
|
||
function jobActions(a: {
|
||
feature: string;
|
||
job: string;
|
||
inputShape: "void" | "typed";
|
||
}): PlopTypes.ActionType[] {
|
||
const symbolFile = `packages/${a.feature}/src/di/symbols.ts`;
|
||
const bindProdFile = `packages/${a.feature}/src/di/bind-production.ts`;
|
||
const bindDevFile = `packages/${a.feature}/src/di/bind-dev-seed.ts`;
|
||
const cmsIndexFile = `packages/${a.feature}/src/integrations/cms/index.ts`;
|
||
return [
|
||
() => {
|
||
assertAnchors(process.cwd(), symbolFile, ["// <gen:job-symbols>"]);
|
||
assertAnchors(process.cwd(), bindProdFile, ["// <gen:jobs>"]);
|
||
assertAnchors(process.cwd(), bindDevFile, ["// <gen:jobs>"]);
|
||
assertAnchors(process.cwd(), cmsIndexFile, ["// <gen:job-tasks>"]);
|
||
return "All required anchors present";
|
||
},
|
||
{
|
||
type: "add",
|
||
path: `packages/${a.feature}/src/jobs/${a.job}.job.ts`,
|
||
templateFile: "templates/job/job.ts.hbs",
|
||
data: a,
|
||
},
|
||
{
|
||
type: "add",
|
||
path: `packages/${a.feature}/src/jobs/${a.job}.job.test.ts`,
|
||
templateFile: "templates/job/job.test.ts.hbs",
|
||
data: a,
|
||
},
|
||
{
|
||
type: "add",
|
||
path: `packages/${a.feature}/src/integrations/cms/jobs/${a.job}.task.ts`,
|
||
templateFile: "templates/job/task.ts.hbs",
|
||
data: a,
|
||
},
|
||
{
|
||
type: "modify",
|
||
path: cmsIndexFile,
|
||
pattern: /\/\/ <gen:job-tasks>/,
|
||
template: `// <gen:job-tasks>\nexport { ${camelCase(a.job)}Task } from "./jobs/${a.job}.task";`,
|
||
},
|
||
{
|
||
type: "modify",
|
||
path: symbolFile,
|
||
pattern: /\/\/ <gen:job-symbols>/,
|
||
template: `// <gen:job-symbols>\n I${pascalCase(a.job)}Job: Symbol.for("@repo/${a.feature}/${camelCase(a.job)}Job"),`,
|
||
},
|
||
{
|
||
type: "modify",
|
||
path: bindProdFile,
|
||
pattern: /\/\/ <gen:jobs>/,
|
||
template: jobBindBlock(a),
|
||
},
|
||
{
|
||
type: "modify",
|
||
path: bindDevFile,
|
||
pattern: /\/\/ <gen:jobs>/,
|
||
template: jobBindBlock(a),
|
||
},
|
||
() => printJobNextSteps(a),
|
||
];
|
||
}
|
||
|
||
function jobBindBlock(a: { feature: string; job: string }): string {
|
||
const factoryFn = `${camelCase(a.job)}Job`;
|
||
const symbol = `${constantCase(a.feature)}_SYMBOLS.I${pascalCase(a.job)}Job`;
|
||
return `// <gen:jobs>
|
||
const wrapped${pascalCase(a.job)} = withSpan(
|
||
tracer,
|
||
{ name: "${a.feature}.${camelCase(a.job)}", op: "job" },
|
||
withCapture(
|
||
logger,
|
||
{
|
||
feature: "${a.feature}",
|
||
layer: "job",
|
||
name: "${a.feature}.${camelCase(a.job)}",
|
||
},
|
||
${factoryFn}(),
|
||
),
|
||
);
|
||
if (${camelCase(a.feature)}Container.isBound(${symbol})) {
|
||
${camelCase(a.feature)}Container.unbind(${symbol});
|
||
}
|
||
${camelCase(a.feature)}Container.bind(${symbol}).toConstantValue(wrapped${pascalCase(a.job)});`;
|
||
}
|
||
|
||
function printJobNextSteps(a: { feature: string; job: string }): string {
|
||
return [
|
||
"",
|
||
"─────────────────────────────────────────────────────────────",
|
||
`Job ${a.feature}.${a.job} scaffolded.`,
|
||
"",
|
||
"Next steps (manual):",
|
||
` 1. Fill in the job body in packages/${a.feature}/src/jobs/${a.job}.job.ts`,
|
||
` 2. Add Payload field config to inputSchema in ${a.job}.task.ts (matches your Zod schema).`,
|
||
` 3. Add the import for ${camelCase(a.job)}Job in bind-production.ts and bind-dev-seed.ts.`,
|
||
` 4. (Optional) Add a cron schedule in core-cms's buildConfig if this job runs periodically.`,
|
||
` 5. Verify: pnpm --filter @repo/${a.feature} lint typecheck test`,
|
||
"─────────────────────────────────────────────────────────────",
|
||
"",
|
||
].join("\n");
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Smoke-test the job generator**
|
||
|
||
```bash
|
||
cp -r ~/Documents/Projects/template-vertical /tmp/gen-test3 && cd /tmp/gen-test3 && pnpm install
|
||
pnpm turbo gen job --args marketing-pages send-welcome-email void
|
||
# manually edit marketing-pages/src/di/bind-production.ts to add the import for sendWelcomeEmailJob
|
||
pnpm --filter @repo/marketing-pages typecheck test lint
|
||
```
|
||
|
||
Expected: clean generation; typecheck/lint/test pass after the manual import edit.
|
||
|
||
- [ ] **Step 3: Clean up; commit**
|
||
|
||
```bash
|
||
rm -rf /tmp/gen-test3
|
||
git add turbo/generators/config.ts
|
||
git commit -m "feat(turbo-gen): job generator"
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 8 — Proof-of-life: cross-feature flow (sign-up → welcome email)
|
||
|
||
This validates that the full stack works end-to-end. Spec § 13.
|
||
|
||
### Task 43: Add `IMailerService` interface to `marketing-pages`
|
||
|
||
**Files:**
|
||
- Create: `packages/marketing-pages/src/application/services/mailer.service.interface.ts`
|
||
|
||
- [ ] **Step 1: Write the interface**
|
||
|
||
```ts
|
||
// packages/marketing-pages/src/application/services/mailer.service.interface.ts
|
||
export interface IMailerService {
|
||
sendWelcome(userId: string, email: string): Promise<void>;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Add a symbol for it**
|
||
|
||
In `packages/marketing-pages/src/di/symbols.ts`, add `IMailerService: Symbol.for("@repo/marketing-pages/IMailerService")` to the symbol object (NOT under any anchor — this is a regular service symbol).
|
||
|
||
- [ ] **Step 3: Verify**
|
||
|
||
Run: `pnpm --filter @repo/marketing-pages typecheck`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add packages/marketing-pages/src/application/services/mailer.service.interface.ts packages/marketing-pages/src/di/symbols.ts
|
||
git commit -m "feat(marketing-pages): IMailerService interface (proof-of-life)"
|
||
```
|
||
|
||
### Task 44: Add `RecordingMailerService`
|
||
|
||
**Files:**
|
||
- Create: `packages/marketing-pages/src/infrastructure/services/recording-mailer.service.ts`
|
||
- Create: `packages/marketing-pages/src/infrastructure/services/recording-mailer.service.test.ts`
|
||
|
||
- [ ] **Step 1: Write the failing test**
|
||
|
||
```ts
|
||
// packages/marketing-pages/src/infrastructure/services/recording-mailer.service.test.ts
|
||
import { describe, it, expect } from "vitest";
|
||
import { RecordingMailerService } from "@/infrastructure/services/recording-mailer.service";
|
||
|
||
describe("RecordingMailerService", () => {
|
||
it("records welcome calls", async () => {
|
||
const mailer = new RecordingMailerService();
|
||
await mailer.sendWelcome("u1", "u1@example.com");
|
||
expect(mailer.sent).toEqual([{ userId: "u1", email: "u1@example.com" }]);
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: Run; expect FAIL**
|
||
|
||
Run: `pnpm --filter @repo/marketing-pages test -- recording-mailer`
|
||
Expected: FAIL.
|
||
|
||
- [ ] **Step 3: Implement**
|
||
|
||
```ts
|
||
// packages/marketing-pages/src/infrastructure/services/recording-mailer.service.ts
|
||
import type { IMailerService } from "../../application/services/mailer.service.interface";
|
||
|
||
export class RecordingMailerService implements IMailerService {
|
||
readonly sent: { userId: string; email: string }[] = [];
|
||
|
||
async sendWelcome(userId: string, email: string): Promise<void> {
|
||
this.sent.push({ userId, email });
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: Run; expect PASS**
|
||
|
||
Run: `pnpm --filter @repo/marketing-pages test -- recording-mailer`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add packages/marketing-pages/src/infrastructure/services/recording-mailer.service.ts packages/marketing-pages/src/infrastructure/services/recording-mailer.service.test.ts
|
||
git commit -m "feat(marketing-pages): RecordingMailerService"
|
||
```
|
||
|
||
### Task 45: Use `gen event publish` to scaffold `auth.user.signed-up`
|
||
|
||
- [ ] **Step 1: Run the generator**
|
||
|
||
```bash
|
||
pnpm turbo gen event --args publish auth user.signed-up
|
||
```
|
||
|
||
Expected: clean generation; `packages/auth/src/events/user-signed-up.event.ts` exists; auth's `index.ts` re-exports it.
|
||
|
||
- [ ] **Step 2: Fill in the schema**
|
||
|
||
Edit `packages/auth/src/events/user-signed-up.event.ts`:
|
||
|
||
```ts
|
||
export const userSignedUpEventSchema = z
|
||
.object({
|
||
userId: z.string(),
|
||
email: z.string().email(),
|
||
signedUpAt: z.string().datetime(),
|
||
})
|
||
.strict();
|
||
```
|
||
|
||
- [ ] **Step 3: Update the generated test**
|
||
|
||
Edit `packages/auth/src/events/user-signed-up.event.test.ts` to assert the actual schema rejects invalid input and accepts valid input.
|
||
|
||
- [ ] **Step 4: Verify**
|
||
|
||
Run: `pnpm --filter @repo/auth typecheck test lint`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add packages/auth/src/
|
||
git commit -m "feat(auth): userSignedUpEvent contract"
|
||
```
|
||
|
||
### Task 46: Update `signUpUseCase` to publish
|
||
|
||
**Files:**
|
||
- Modify: `packages/auth/src/application/use-cases/sign-up.use-case.ts`
|
||
- Modify: `packages/auth/src/application/use-cases/sign-up.use-case.test.ts`
|
||
|
||
- [ ] **Step 1: Add a failing test asserting `bus.publish` is called**
|
||
|
||
Read the existing test, then add:
|
||
|
||
```ts
|
||
import { RecordingEventBus } from "@repo/core-testing/instrumentation";
|
||
import { userSignedUpEvent } from "../../events/user-signed-up.event";
|
||
|
||
it("publishes auth.user.signed-up after creating the user", async () => {
|
||
const bus = new RecordingEventBus();
|
||
// ... existing mocks ...
|
||
const useCase = signUpUseCase(mockUsers, mockAuth, bus);
|
||
await useCase({ email: "a@b.com", password: "secret" });
|
||
expect(bus.published).toContainEqual(
|
||
expect.objectContaining({ name: "auth.user.signed-up" }),
|
||
);
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: Run; expect FAIL** — `signUpUseCase` doesn't take `bus` yet.
|
||
|
||
- [ ] **Step 3: Update `signUpUseCase`**
|
||
|
||
```ts
|
||
import type { IEventBus } from "@repo/core-events";
|
||
import { userSignedUpEvent } from "../../events/user-signed-up.event";
|
||
|
||
export const signUpUseCase =
|
||
(users: IUsersRepository, auth: IAuthenticationService, bus: IEventBus) =>
|
||
async (input: SignUpInput): Promise<SignUpOutput> => {
|
||
// ... existing logic to create user + return token ...
|
||
const user = /* existing creation */;
|
||
await bus.publish(userSignedUpEvent, {
|
||
userId: user.id,
|
||
email: user.email,
|
||
signedUpAt: new Date().toISOString(),
|
||
});
|
||
return signUpOutputSchema.parse(/* existing return */);
|
||
};
|
||
```
|
||
|
||
- [ ] **Step 4: Update the binding in `bind-production.ts`**
|
||
|
||
In `packages/auth/src/di/bind-production.ts`, the `signUpUseCase` factory call now takes `bus`:
|
||
|
||
```ts
|
||
const wrappedSignUp = withSpan(
|
||
tracer,
|
||
{ name: "auth.signUp", op: "use-case" },
|
||
withCapture(
|
||
logger,
|
||
{ feature: "auth", layer: "use-case", name: "auth.signUp" },
|
||
signUpUseCase(repo, authService, bus),
|
||
),
|
||
);
|
||
```
|
||
|
||
Same for `bind-dev-seed.ts`.
|
||
|
||
- [ ] **Step 5: Run; expect PASS**
|
||
|
||
Run: `pnpm --filter @repo/auth typecheck test lint`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 6: Commit**
|
||
|
||
```bash
|
||
git add packages/auth/src/
|
||
git commit -m "feat(auth): signUp publishes userSignedUpEvent"
|
||
```
|
||
|
||
### Task 47: Use `gen event consume` to scaffold the marketing-pages handler
|
||
|
||
- [ ] **Step 1: Run the generator**
|
||
|
||
```bash
|
||
pnpm turbo gen event --args consume marketing-pages user.signed-up auth
|
||
```
|
||
|
||
Expected: clean generation. Files produced:
|
||
- `packages/marketing-pages/src/events/handlers/on-auth-user-signed-up.handler.ts` (+ .test.ts)
|
||
- `packages/marketing-pages/src/integrations/cms/jobs/__events-auth-user-signed-up.task.ts`
|
||
|
||
Modifications:
|
||
- `symbols.ts` adds `IOnAuthUserSignedUpHandler`.
|
||
- `bind-production.ts` / `bind-dev-seed.ts` get the wrapped-handler block + `bus.subscribe` call + container binding.
|
||
- `integrations/cms/index.ts` re-exports the `__events-...task.ts` so `core-cms` aggregates it.
|
||
|
||
- [ ] **Step 2: Add the missing imports to bind files**
|
||
|
||
Both `packages/marketing-pages/src/di/bind-production.ts` and `bind-dev-seed.ts` need:
|
||
|
||
```ts
|
||
import { userSignedUpEvent } from "@repo/auth";
|
||
import { onAuthUserSignedUpHandler } from "../events/handlers/on-auth-user-signed-up.handler";
|
||
```
|
||
|
||
- [ ] **Step 3: Verify the generated task exists and `core-cms` aggregates it**
|
||
|
||
Run: `pnpm --filter @repo/marketing-pages typecheck lint`
|
||
Run: `pnpm --filter @repo/core-cms typecheck`
|
||
|
||
Expected: PASS for both. Open `packages/core-cms/src/index.ts` and confirm the import line for `onAuthUserSignedUpEventTask` is implicit (via `@repo/marketing-pages/cms`'s barrel re-export). If `core-cms` does NOT explicitly enumerate task names but instead spreads the imported `tasks` array, no edit is needed. If `core-cms` enumerates each task individually, add `onAuthUserSignedUpEventTask` to the `jobs.tasks` array — read `packages/core-cms/src/index.ts` to determine which.
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add packages/marketing-pages/src/ packages/core-cms/src/
|
||
git commit -m "feat(marketing-pages): subscribe to auth.user.signed-up (handler + production task)"
|
||
```
|
||
|
||
### Task 48: Use `gen job` to scaffold `send-welcome-email`
|
||
|
||
- [ ] **Step 1: Run the generator**
|
||
|
||
```bash
|
||
pnpm turbo gen job --args marketing-pages send-welcome-email typed
|
||
```
|
||
|
||
- [ ] **Step 2: Fill in the schema and body**
|
||
|
||
Edit `packages/marketing-pages/src/jobs/send-welcome-email.job.ts`:
|
||
|
||
```ts
|
||
import { z } from "zod";
|
||
import type { IMailerService } from "../application/services/mailer.service.interface";
|
||
|
||
export const sendWelcomeEmailInputSchema = z
|
||
.object({ userId: z.string(), email: z.string().email() })
|
||
.strict();
|
||
|
||
export type SendWelcomeEmailInput = z.infer<typeof sendWelcomeEmailInputSchema>;
|
||
export type ISendWelcomeEmailJob = ReturnType<typeof sendWelcomeEmailJob>;
|
||
|
||
export const sendWelcomeEmailJob =
|
||
(mailer: IMailerService) =>
|
||
async (input: SendWelcomeEmailInput): Promise<void> => {
|
||
sendWelcomeEmailInputSchema.parse(input);
|
||
await mailer.sendWelcome(input.userId, input.email);
|
||
};
|
||
```
|
||
|
||
- [ ] **Step 3: Update the generated job test**
|
||
|
||
```ts
|
||
import { RecordingMailerService } from "@/infrastructure/services/recording-mailer.service";
|
||
|
||
it("sends a welcome email via the mailer", async () => {
|
||
const mailer = new RecordingMailerService();
|
||
const job = sendWelcomeEmailJob(mailer);
|
||
await job({ userId: "u1", email: "u1@example.com" });
|
||
expect(mailer.sent).toEqual([{ userId: "u1", email: "u1@example.com" }]);
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 4: Update the generated bind block to inject the mailer**
|
||
|
||
The generator emits `sendWelcomeEmailJob()` (no args). Edit the bind blocks in both `bind-production.ts` and `bind-dev-seed.ts` to wire in a mailer:
|
||
|
||
For `bind-dev-seed.ts`:
|
||
|
||
```ts
|
||
const mailer = new RecordingMailerService();
|
||
marketingPagesContainer
|
||
.bind<IMailerService>(MARKETING_PAGES_SYMBOLS.IMailerService)
|
||
.toConstantValue(mailer);
|
||
// Then in the gen:jobs block:
|
||
sendWelcomeEmailJob(mailer),
|
||
```
|
||
|
||
For `bind-production.ts`: bind a real mailer (placeholder: bind another `RecordingMailerService` until a real impl ships, or use a stub).
|
||
|
||
- [ ] **Step 5: Update the handler to inject the queue and enqueue the job**
|
||
|
||
In `packages/marketing-pages/src/events/handlers/on-auth-user-signed-up.handler.ts`:
|
||
|
||
```ts
|
||
import type { UserSignedUpEvent } from "@repo/auth";
|
||
import type { IJobQueue } from "@repo/core-shared/jobs";
|
||
|
||
export type IOnAuthUserSignedUpHandler = ReturnType<typeof onAuthUserSignedUpHandler>;
|
||
|
||
export const onAuthUserSignedUpHandler =
|
||
(queue: IJobQueue) =>
|
||
async (event: UserSignedUpEvent): Promise<void> => {
|
||
await queue.enqueue("marketing-pages.send-welcome-email", {
|
||
userId: event.userId,
|
||
email: event.email,
|
||
});
|
||
};
|
||
```
|
||
|
||
Update the bind block to pass `queue`:
|
||
|
||
```ts
|
||
${handlerFn}(queue),
|
||
// becomes:
|
||
onAuthUserSignedUpHandler(queue),
|
||
```
|
||
|
||
(The generator emitted `onAuthUserSignedUpHandler()` with no args; you edit the bind block to pass `queue`.)
|
||
|
||
- [ ] **Step 6: For dev-seed, register the job with the in-memory queue**
|
||
|
||
In `bind-dev-seed.ts`, after binding the wrapped job:
|
||
|
||
```ts
|
||
if (queue && typeof (queue as { register?: unknown }).register === "function") {
|
||
(queue as InMemoryJobQueue).register(
|
||
"marketing-pages.send-welcome-email",
|
||
async (input) => {
|
||
const wrapped = marketingPagesContainer.get<ISendWelcomeEmailJob>(
|
||
MARKETING_PAGES_SYMBOLS.ISendWelcomeEmailJob,
|
||
);
|
||
await wrapped(input as SendWelcomeEmailInput);
|
||
},
|
||
);
|
||
}
|
||
```
|
||
|
||
This registration is what makes the in-memory queue actually fire when the handler enqueues.
|
||
|
||
- [ ] **Step 7: Verify all marketing-pages tests pass**
|
||
|
||
Run: `pnpm --filter @repo/marketing-pages typecheck test lint`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 8: Commit**
|
||
|
||
```bash
|
||
git add packages/marketing-pages/src/
|
||
git commit -m "feat(marketing-pages): sendWelcomeEmail job + handler enqueues it"
|
||
```
|
||
|
||
### Task 49: End-to-end test: sign-up triggers welcome email
|
||
|
||
**Files:**
|
||
- Create: `apps/web-next/tests/sign-up-welcome-email.test.ts` (or extend an existing e2e test file)
|
||
|
||
- [ ] **Step 1: Determine where app-level tests live**
|
||
|
||
Run: `find apps/web-next -name "*.test.ts" | head`. If there's no existing top-level test directory, place this one near the bind-production test.
|
||
|
||
- [ ] **Step 2: Write the e2e test**
|
||
|
||
```ts
|
||
// apps/web-next/tests/sign-up-welcome-email.test.ts
|
||
import { describe, it, expect, beforeEach } from "vitest";
|
||
import { bindAllDevSeed, __resetBindStateForTests } from "@/server/bind-production";
|
||
import { authContainer } from "@repo/auth/di/container"; // adjust import path
|
||
import { AUTH_SYMBOLS } from "@repo/auth/di/symbols";
|
||
import { marketingPagesContainer } from "@repo/marketing-pages/di/container";
|
||
import { MARKETING_PAGES_SYMBOLS } from "@repo/marketing-pages/di/symbols";
|
||
import type { ISignUpController } from "@repo/auth";
|
||
import type { IMailerService } from "@repo/marketing-pages";
|
||
import { RecordingMailerService } from "@repo/marketing-pages/src/infrastructure/services/recording-mailer.service";
|
||
|
||
describe("e2e: sign-up triggers welcome email via cross-feature event", () => {
|
||
beforeEach(() => {
|
||
__resetBindStateForTests();
|
||
});
|
||
|
||
it("delivers a welcome email after a successful sign-up", async () => {
|
||
await bindAllDevSeed();
|
||
|
||
const mailer = marketingPagesContainer.get<IMailerService>(
|
||
MARKETING_PAGES_SYMBOLS.IMailerService,
|
||
) as RecordingMailerService;
|
||
|
||
const controller = authContainer.get<ISignUpController>(AUTH_SYMBOLS.ISignUpController);
|
||
await controller({ email: "test@example.com", password: "secret123" });
|
||
|
||
// The job runs on setImmediate; let microtasks settle
|
||
await new Promise((r) => setImmediate(r));
|
||
|
||
expect(mailer.sent).toEqual([{ userId: expect.any(String), email: "test@example.com" }]);
|
||
});
|
||
});
|
||
```
|
||
|
||
> The exact import paths depend on the actual public-API exposure of the auth and marketing-pages packages. If `authContainer` is not exported, replace with a `getAuthContainer(config)` form.
|
||
|
||
- [ ] **Step 3: Run; expect PASS**
|
||
|
||
Run: `pnpm --filter @repo/web-next test -- sign-up-welcome-email`
|
||
Expected: PASS.
|
||
|
||
> If timing of `setImmediate` is flaky, replace with a synchronous in-memory bus that awaits handlers (default `InMemoryEventBus`) and ensure `bindAllDevSeed` uses it (it does — InMemoryEventBus is the dev-seed default).
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add apps/web-next/tests/sign-up-welcome-email.test.ts
|
||
git commit -m "test(web-next): e2e cross-feature sign-up→welcome-email flow"
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 9 — Documentation
|
||
|
||
### Task 50: Write `docs/decisions/adr-015-events-and-jobs.md`
|
||
|
||
**Files:**
|
||
- Create: `docs/decisions/adr-015-events-and-jobs.md`
|
||
|
||
- [ ] **Step 1: Read the format of recent ADRs**
|
||
|
||
Read `docs/decisions/adr-014-instrumentation-sentry.md` for the structure (Status / Context / Decision / Consequences).
|
||
|
||
- [ ] **Step 2: Write ADR-015**
|
||
|
||
Distill the spec's § 2.2 (rules E0/E1/J0), § 3 (new packages), § 6.3 (bindAll rule), § 7 (boundary/lint), and § 11 (out of scope) into the ADR format. Each rule gets one paragraph. Cross-link the spec at `docs/superpowers/specs/2026-05-08-events-and-jobs-design.md`.
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add docs/decisions/adr-015-events-and-jobs.md
|
||
git commit -m "docs(adr-015): cross-feature events and background jobs"
|
||
```
|
||
|
||
### Task 51: Write `docs/guides/events-and-jobs.md`
|
||
|
||
**Files:**
|
||
- Create: `docs/guides/events-and-jobs.md`
|
||
|
||
- [ ] **Step 1: Structure the guide**
|
||
|
||
Three sections:
|
||
1. "Publish an event" — runs `gen event publish`, fills the schema, modifies a use case, updates DI binding. Show the full diff for each step.
|
||
2. "Consume an event" — runs `gen event consume`, edits the handler body, adds the import to bind files. Full diff.
|
||
3. "Add a job" — runs `gen job`, fills the schema and body, edits Payload `inputSchema`, updates the bind block. Full diff.
|
||
|
||
For each section, reference the spec sections that explain the rationale, and list the verification commands.
|
||
|
||
- [ ] **Step 2: Commit**
|
||
|
||
```bash
|
||
git add docs/guides/events-and-jobs.md
|
||
git commit -m "docs(guide): events-and-jobs walkthrough"
|
||
```
|
||
|
||
### Task 52: Update `AGENTS.md`
|
||
|
||
**Files:**
|
||
- Modify: `AGENTS.md`
|
||
|
||
- [ ] **Step 1: Add a new section under Per-Package Conventions**
|
||
|
||
Insert after the "Apps call `bindAll()` per feature at boot" section:
|
||
|
||
```markdown
|
||
### Cross-feature events and background jobs (Plan 10, ADR-015)
|
||
|
||
Three rules:
|
||
|
||
- **E0:** Events are for cross-feature decoupling. In-feature reactions are direct use-case calls — do not use the bus.
|
||
- **E1:** Event contracts are exported from the publisher's root; handlers are private to the consumer's bind-* files (never re-exported, ESLint-enforced).
|
||
- **J0:** Jobs are for *deferred* work, not abstraction. Synchronous code stays synchronous.
|
||
|
||
`@repo/core-events` provides `IEventBus` (`InMemoryEventBus` for dev/test, `PayloadJobsEventBus` for prod). `@repo/core-shared/jobs` provides `IJobQueue` (`InMemoryJobQueue` / `PayloadJobQueue`). Both are swapped by `bindAll()` using the same `USE_DEV_SEED` / `NODE_ENV` rules as repositories.
|
||
|
||
Per-feature folders (all optional): `events/<x>.event.ts`, `events/handlers/on-<publisher>-<event>.handler.ts`, `jobs/<x>.job.ts`, `integrations/cms/jobs/<x>.task.ts`.
|
||
|
||
Use the generators: `pnpm turbo gen event {publish|consume}`, `pnpm turbo gen job`. They insert at six fixed `// <gen:*>` anchor comments present in every feature.
|
||
|
||
See `docs/guides/events-and-jobs.md` and `docs/decisions/adr-015-events-and-jobs.md`.
|
||
```
|
||
|
||
- [ ] **Step 2: Add a row to the Specification & Guides list**
|
||
|
||
```markdown
|
||
- **Events and Jobs Guide** — `docs/guides/events-and-jobs.md` — publish, consume, schedule background work
|
||
```
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add AGENTS.md
|
||
git commit -m "docs(agents): events-and-jobs section + guide reference"
|
||
```
|
||
|
||
### Task 53: Update `CLAUDE.md`
|
||
|
||
**Files:**
|
||
- Modify: `CLAUDE.md`
|
||
|
||
- [ ] **Step 1: Update Quick Start**
|
||
|
||
Add to the command block:
|
||
|
||
```bash
|
||
pnpm turbo gen event # Scaffold an event contract or handler
|
||
pnpm turbo gen job # Scaffold a background job
|
||
```
|
||
|
||
- [ ] **Step 2: Update Read First**
|
||
|
||
Add: `- docs/guides/events-and-jobs.md — publish/consume/schedule cookbook`
|
||
|
||
- [ ] **Step 3: Update Key Conventions**
|
||
|
||
Add three short bullets matching E0, E1, J0 from the AGENTS.md section.
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add CLAUDE.md
|
||
git commit -m "docs(claude): generators + events/jobs conventions"
|
||
```
|
||
|
||
### Task 54: Update `docs/guides/scaffolding-a-feature.md`
|
||
|
||
**Files:**
|
||
- Modify: `docs/guides/scaffolding-a-feature.md`
|
||
|
||
- [ ] **Step 1: Add two new sections at the bottom**
|
||
|
||
```markdown
|
||
## Adding events and jobs to a feature
|
||
|
||
Once a feature exists, augment it with cross-feature events or background jobs using the dedicated generators. See `docs/guides/events-and-jobs.md` for full walkthroughs.
|
||
|
||
```bash
|
||
pnpm turbo gen event publish # publisher contract
|
||
pnpm turbo gen event consume # consumer handler
|
||
pnpm turbo gen job # background job
|
||
```
|
||
|
||
The generators insert at six fixed `// <gen:*>` anchor comments. Generated features include them automatically; pre-existing features were retrofitted in ADR-015.
|
||
```
|
||
|
||
- [ ] **Step 2: Commit**
|
||
|
||
```bash
|
||
git add docs/guides/scaffolding-a-feature.md
|
||
git commit -m "docs(scaffolding): event/job generators reference"
|
||
```
|
||
|
||
### Task 55: Update `docs/architecture/vertical-feature-spec.md` deferred lines
|
||
|
||
**Files:**
|
||
- Modify: `docs/architecture/vertical-feature-spec.md`
|
||
|
||
- [ ] **Step 1: Update the deferred placeholders**
|
||
|
||
Line 260 (currently "No `effects/`, `jobs/`, `events/` unless the feature grows them") becomes:
|
||
|
||
```
|
||
Optional `events/`, `jobs/`, `integrations/cms/jobs/` directories (see ADR-015 and `docs/guides/events-and-jobs.md`); features may grow them on demand. The spec's canonical layout below remains correct as the minimum.
|
||
```
|
||
|
||
Line 662 ("no `core-events` package yet; spec addendum v4's optional `core-events` stays deferred") becomes:
|
||
|
||
```
|
||
Cross-feature events: shipped via `@repo/core-events` (ADR-015, 2026-05-08). Jobs: shipped via `@repo/core-shared/jobs` + Payload's job queue (same ADR).
|
||
```
|
||
|
||
- [ ] **Step 2: Commit**
|
||
|
||
```bash
|
||
git add docs/architecture/vertical-feature-spec.md
|
||
git commit -m "docs(spec): events/jobs no longer deferred (ADR-015)"
|
||
```
|
||
|
||
---
|
||
|
||
## Final verification
|
||
|
||
### Task 56: Whole-monorepo green check
|
||
|
||
- [ ] **Step 1: Full lint**
|
||
|
||
Run: `pnpm lint`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 2: Full typecheck**
|
||
|
||
Run: `pnpm typecheck`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 3: Full test**
|
||
|
||
Run: `pnpm test`
|
||
Expected: PASS — including the new anchor-presence guard, the e2e cross-feature flow, and all rule tests.
|
||
|
||
- [ ] **Step 4: Boundary check**
|
||
|
||
Run: `pnpm turbo boundaries`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 5: Dry-run smoke of all three generators against a sandbox**
|
||
|
||
```bash
|
||
cp -r ~/Documents/Projects/template-vertical /tmp/final-test && cd /tmp/final-test && pnpm install
|
||
pnpm turbo gen feature --args widgets Widget widgets
|
||
pnpm turbo gen event --args publish widgets thing.happened
|
||
pnpm turbo gen event --args consume blog thing.happened widgets
|
||
pnpm turbo gen job --args widgets process-thing void
|
||
# manual edits as printed by each generator
|
||
pnpm typecheck test lint
|
||
```
|
||
|
||
Expected: end-to-end green.
|
||
|
||
```bash
|
||
rm -rf /tmp/final-test
|
||
```
|
||
|
||
- [ ] **Step 6: Final commit**
|
||
|
||
If any step revealed a fix, commit it. Otherwise no-op — the plan is done.
|
||
|
||
---
|
||
|
||
## Known follow-up — out of v1 plan scope
|
||
|
||
Tracked here so they aren't forgotten:
|
||
|
||
1. **Spec interface drift — 3-arg `subscribe`.** During plan self-review, `IEventBus.subscribe` was widened to take `consumerFeature: string` as a second arg (between `descriptor` and `handler`) so `PayloadJobsEventBus` is directly assignable to `IEventBus`. The spec at `docs/superpowers/specs/2026-05-08-events-and-jobs-design.md` § 3.3 still shows the older 2-arg form. **As part of Task 50 (ADR-015), update the spec § 3.3 + § 5.4 to the 3-arg form** so the spec and code agree. Do this in the same commit as the ADR.
|
||
2. **Cron schedules are out-of-band.** Job cron schedules live in `core-cms`'s `buildConfig({ jobs: { ... } })`, not in the feature's job file or the generator output. v1 documents this in Task 51's guide; v2 may add a `--cron` prompt to `gen job`.
|
||
3. **Production-mode e2e test.** Task 49's e2e test runs in dev-seed mode (`InMemoryEventBus`). A parallel test that runs in production mode (`PayloadJobsEventBus` against a Payload test database) would prove the `__events.*.task.ts` slug-to-handler chain end-to-end. Out of scope for v1 because it requires a Payload test fixture; the production-bus unit tests (Task 15) plus the generator's typecheck-on-output cover the wiring statically.
|
||
|
||
The first item is mandatory and folded into Task 50. The remaining two are explicitly deferred and should be tracked in ADR-015's "Out of scope" list.
|
||
|
||
> **Production bus task auto-registration is now in scope** (Tasks 39–40, 47). The `gen event consume` generator emits the `__events-<publisher>-<event>.task.ts` Payload task alongside the handler, and the consumer's `bind-*` files bind the wrapped handler into the per-feature container so the task can resolve it. With this, `PayloadJobsEventBus` is fully wired end-to-end — no manual per-event task hand-write required.
|
||
|
||
---
|
||
|
||
## Self-review check
|
||
|
||
This plan was self-reviewed against the spec on the date of writing. Key points verified:
|
||
|
||
- Every spec section maps to one or more tasks (§ 2 → Phase 0, § 3 → Phases 1–2, § 4 → § 5 maps via Tasks 26–32 + generators, § 6 → Phases 1–2 + Phase 6, § 7 → Phase 4, § 8 → Phase 3, § 9 → Phase 7, § 10 → Phase 9, § 11 not implemented intentionally, § 12 honored throughout, § 13 verified by Task 49 + Task 56).
|
||
- All file paths are absolute or repo-relative; no "TBD".
|
||
- Tests precede implementation in every behavior-adding task.
|
||
- Commit cadence: one commit per task, ~56 commits total, each green at the boundary.
|
||
- Anchor protocol is consistent across Phases 5, 6, and 7.
|
||
- Span+capture sandwich tags (`op: "event-handler"`, `op: "job"`, `layer: "event-handler"`, `layer: "job"`) appear in the same form in Tasks 40 and 42 generator output and Task 48 manual edits.
|
||
- One consistency issue caught during review and fixed inline: `IEventBus.subscribe` widened to 3-arg form so `PayloadJobsEventBus` is directly assignable. See Known Follow-up #1.
|
||
- One scope expansion accepted post-review per user request: `gen event consume` now also emits the `__events-<publisher>-<event>.task.ts` Payload task and binds the wrapped handler into the per-feature container, closing the production-bus loop end-to-end (Tasks 39–40, 47). The original "deferred task-registration gap" is now obsolete.
|