feat(turbo): turbo gen feature generator (Phase 1, single-entity)

Adds `pnpm turbo gen feature` to scaffold a Lazar-conformant feature
package matching the navigation reference shape: entity + Zod schema,
single use case (`get<Entity>`), controller, mock + Payload-stub real
repository (with span + capture), DI module/container/symbols, and tRPC
router with full BAD_REQUEST/NOT_FOUND error mapping. The generated
`bind-production.ts` and `bind-dev-seed.ts` compose the post-R44
`withSpan(tracer, opts, withCapture(logger, tags, factory(deps)))`
sandwich at bind time.

Verified by generating a sample `packages/example/` feature and running
`pnpm --filter @repo/example lint typecheck test` — all three pass
(9 test files, 25 tests). Cleaned up after verification so no example
package is committed.

Phase-1 limitations (documented in `docs/guides/scaffolding-a-feature.md`
and printed by the generator on success): no Payload CMS templates, no
React Query helpers, faker-driven factories left as stubs, single
entity / single use case, and aggregator wiring (core-api/root,
apps/web-next bindAll) is left as a manual checklist.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

turbo/generators/templates/feature/src/infrastructure/repositories/entity.repository.mock.test.ts.hbs

@@ -0,0 +1,15 @@
+import { describe } from "vitest";
+import { RecordingTracer } from "@repo/core-testing/instrumentation";
+import { Mock{{pascalCase entity}}Repository } from "@/infrastructure/repositories/{{kebabCase entity}}.repository.mock";
+import {
+  {{camelCase entity}}RepositoryContract,
+  CONTRACT_{{constantCase entity}}_SEED,
+} from "@/__contracts__/{{kebabCase entity}}-repository.contract";
+
+describe("Mock{{pascalCase entity}}Repository", () => {
+  const tracer = new RecordingTracer();
+  {{camelCase entity}}RepositoryContract.run(
+    () => new Mock{{pascalCase entity}}Repository(new Map(CONTRACT_{{constantCase entity}}_SEED), tracer),
+    { tracer: () => tracer },
+  );
+});

turbo/generators/templates/feature/src/infrastructure/repositories/entity.repository.mock.ts.hbs

@@ -0,0 +1,45 @@
+import "reflect-metadata";
+import { injectable } from "inversify";
+import {
+  NoopTracer,
+  NoopLogger,
+  type ITracer,
+  type ILogger,
+} from "@repo/core-shared/instrumentation";
+
+import type { I{{pascalCase entity}}Repository } from "../../application/repositories/{{kebabCase entity}}.repository.interface";
+import type { {{pascalCase entity}} } from "../../entities/models/{{kebabCase entity}}";
+
+const DEFAULT_DATA = new Map<string, {{pascalCase entity}}>([
+  ["seed-1", { id: "seed-1", name: "Seed One" }],
+  ["seed-2", { id: "seed-2", name: "Seed Two" }],
+]);
+
+@injectable()
+export class Mock{{pascalCase entity}}Repository implements I{{pascalCase entity}}Repository {
+  private readonly data: Map<string, {{pascalCase entity}}>;
+  private tracer: ITracer;
+  private logger: ILogger;
+
+  constructor(
+    initialData?: Map<string, {{pascalCase entity}}>,
+    tracer: ITracer = new NoopTracer(),
+    logger: ILogger = new NoopLogger(),
+  ) {
+    this.data = initialData ?? new Map(DEFAULT_DATA);
+    this.tracer = tracer;
+    this.logger = logger;
+    void this.logger; // currently unused; reserved for future mock-thrown captures
+  }
+
+  async get{{pascalCase entity}}(id: string): Promise<{{pascalCase entity}} | null> {
+    return this.tracer.startSpan(
+      { name: "{{camelCase entity}}.get{{pascalCase entity}}", op: "repository", attributes: {} },
+      async (span) => {
+        const found = this.data.get(id) ?? null;
+        span.setAttribute("found", found !== null);
+        return found;
+      },
+    );
+  }
+}

turbo/generators/templates/feature/src/infrastructure/repositories/entity.repository.span.test.ts.hbs

@@ -0,0 +1,19 @@
+import { describe, it, expect } from "vitest";
+import { RecordingTracer, RecordingLogger } from "@repo/core-testing/instrumentation";
+import { Mock{{pascalCase entity}}Repository } from "@/infrastructure/repositories/{{kebabCase entity}}.repository.mock";
+
+// Mock repo also wraps in spans (R42).
+describe("Mock{{pascalCase entity}}Repository emits spans", () => {
+  it("get{{pascalCase entity}} emits one span with op='repository'", async () => {
+    const tracer = new RecordingTracer();
+    const logger = new RecordingLogger();
+    const repo = new Mock{{pascalCase entity}}Repository(undefined, tracer, logger);
+    await repo.get{{pascalCase entity}}("seed-1");
+    expect(tracer.spans).toHaveLength(1);
+    expect(tracer.spans[0]).toMatchObject({
+      name: "{{camelCase entity}}.get{{pascalCase entity}}",
+      op: "repository",
+    });
+    expect(typeof tracer.spans[0]!.attributes.found).toBe("boolean");
+  });
+});

turbo/generators/templates/feature/src/infrastructure/repositories/entity.repository.test.ts.hbs

@@ -0,0 +1,34 @@
+import { describe, it, expect } from "vitest";
+import { RecordingTracer, RecordingLogger } from "@repo/core-testing/instrumentation";
+import { stubPayloadConfig } from "@repo/core-testing/payload/stub-config";
+import { {{pascalCase entity}}Repository } from "@/infrastructure/repositories/{{kebabCase entity}}.repository";
+
+// Phase-1 scaffold: the real repository returns null until the Payload
+// collection is wired. These tests pin the span shape and the stub return
+// value so that callers (use case + DI tests) keep working when the body is
+// later replaced with a real `payload.find()` call.
+
+describe("{{pascalCase entity}}Repository (Phase-1 stub)", () => {
+  it("returns null and emits a span with op='repository'", async () => {
+    const tracer = new RecordingTracer();
+    const logger = new RecordingLogger();
+    const repo = new {{pascalCase entity}}Repository(stubPayloadConfig, tracer, logger);
+
+    const result = await repo.get{{pascalCase entity}}("anything");
+
+    expect(result).toBeNull();
+    expect(tracer.spans).toHaveLength(1);
+    expect(tracer.spans[0]).toMatchObject({
+      name: "{{camelCase entity}}.get{{pascalCase entity}}",
+      op: "repository",
+    });
+  });
+
+  it("records the requested id as a span attribute", async () => {
+    const tracer = new RecordingTracer();
+    const repo = new {{pascalCase entity}}Repository(stubPayloadConfig, tracer);
+    await repo.get{{pascalCase entity}}("custom-id");
+    expect(tracer.spans[0]!.attributes.id).toBe("custom-id");
+    expect(tracer.spans[0]!.attributes.found).toBe(false);
+  });
+});

turbo/generators/templates/feature/src/infrastructure/repositories/entity.repository.ts.hbs

@@ -0,0 +1,62 @@
+import "reflect-metadata";
+import { injectable } from "inversify";
+import type { SanitizedConfig } from "payload";
+import {
+  NoopTracer,
+  NoopLogger,
+  type ITracer,
+  type ILogger,
+} from "@repo/core-shared/instrumentation";
+
+import type { I{{pascalCase entity}}Repository } from "../../application/repositories/{{kebabCase entity}}.repository.interface";
+import type { {{pascalCase entity}} } from "../../entities/models/{{kebabCase entity}}";
+
+const FEATURE = "{{kebabCase name}}" as const;
+const REPO = "{{kebabCase entity}}" as const;
+
+/**
+ * Phase-1 scaffold — the Payload collection has not been added yet, so this
+ * repository emits a span but always resolves to `null`. Once you add the
+ * collection at `integrations/cms/collections/{{kebabCase entity}}.ts` and
+ * register it with Payload, replace the stub below with a real `payload.find`
+ * call (see `packages/blog/src/infrastructure/repositories/articles.repository.ts`
+ * for the canonical pattern).
+ */
+@injectable()
+export class {{pascalCase entity}}Repository implements I{{pascalCase entity}}Repository {
+  private config: SanitizedConfig;
+  private tracer: ITracer;
+  private logger: ILogger;
+
+  constructor(
+    config: SanitizedConfig,
+    tracer: ITracer = new NoopTracer(),
+    logger: ILogger = new NoopLogger(),
+  ) {
+    this.config = config;
+    this.tracer = tracer;
+    this.logger = logger;
+    void this.config;
+  }
+
+  async get{{pascalCase entity}}(id: string): Promise<{{pascalCase entity}} | null> {
+    return this.tracer.startSpan(
+      { name: "{{camelCase entity}}.get{{pascalCase entity}}", op: "repository", attributes: {} },
+      async (span) => {
+        try {
+          // TODO: replace with `payload.find({ collection: "{{entityPlural}}", where: { id: { equals: id } } })`
+          // once the Payload collection is registered.
+          span.setAttribute("id", id);
+          span.setAttribute("found", false);
+          return null;
+        } catch (err) {
+          this.logger.captureException(err, {
+            tags: { feature: FEATURE, repo: REPO, method: "get{{pascalCase entity}}" },
+          });
+          span.setStatus("error", err instanceof Error ? err.message : String(err));
+          throw err;
+        }
+      },
+    );
+  }
+}