ts-procedures 8.5.0 → 8.6.0

package/docs/superpowers/plans/2026-06-08-codegen-dx-surfacing.md

@@ -0,0 +1,428 @@
+# Codegen DX Surfacing (Workstream A) 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:** Make three already-present client capabilities discoverable in the generated TS output — input-less calls (`api.auth.Me()` instead of `Me({})`), the per-call options bag (`signal`/`timeout`), declared route errors — and emit per-scope client interfaces so DI seams don't force `as unknown as typeof api` casts.
+
+**Architecture:** All changes live in the TS codegen emitters (`src/codegen/emit-scope.ts`, `src/codegen/emit-index.ts`). No runtime/client changes. #9 flips four `paramsTypeName` fallbacks from `'unknown'` to `'void'` (verified: a required `void` param is omittable at the call site, so `Me()` compiles while `Me({})` is a type error). #8/#10 replace the single-line callable JSDoc with a shared `buildCallableJsDoc` helper that names the options bag and (for error routes) the declared `Errors`. #15 derives per-scope client types from the factory's `ReturnType`, reusing the pattern already in `emit-index.ts`.
+
+**Tech Stack:** TypeScript, Vitest, ajsc (JSON Schema → TS). Tests are string assertions over `emitScopeFile` / `emitIndexFile` output.
+
+**Source spec:** `docs/superpowers/specs/2026-06-08-dx-feedback-round-2-design.md` (Workstream A: #9, #8, #10-breadcrumb, #15).
+
+**Pre-verified facts (do not re-litigate):**
+- `tsc --strict`: `declare const a: (params: void, options?: Opts) => Promise<number>` ⇒ `a()` compiles, `a({})` / `a({ nonsense: 1 })` are type errors. So `void` for `TParams` is sufficient — no signature restructuring.
+- Current input-less output is `client.bindCallable<unknown, void>` (`emit-scope.test.ts:1255,1281`).
+- `paramsTypeName` fallback sites (params position only): `emit-scope.ts:398` (RPC), `:536` (API), `:679` (http-stream), `:816` (stream). The response/yield `unknown` fallbacks at `:399`, `:680`, `:817` MUST stay `unknown`.
+- Callable JSDoc single-line sites: `:412` (RPC), `:641` (API), `:777` (http-stream), `:822` (stream).
+- Per-route `Errors` type is already emitted + reachable (`Users.GetUser.Errors` / `GetUserErrors`, `emit-scope.test.ts:740,750`); generated error classes are real, so `instanceof` already works on the throwing path. #10 here is a JSDoc breadcrumb only — the consumer-facing prose is Workstream D.
+- `emit-index.ts` already emits `create${Service}Bindings` returning `{ <scope>: … }` and already uses `ReturnType<typeof factoryName>` (`:128,145`).
+
+---
+
+## File Structure
+
+- **Modify** `src/codegen/emit-scope.ts` — (a) four `paramsTypeName` fallbacks `'unknown'`→`'void'`; (b) add `buildCallableJsDoc` helper; (c) call it at the four callable sites.
+- **Modify** `src/codegen/emit-scope.test.ts` — update the two `apiGroupNoBody` assertions; add input-less RPC + stream cases; add JSDoc assertions.
+- **Modify** `src/codegen/emit-index.ts` — emit `export type ${Service}Client = ReturnType<typeof create${Service}Bindings>` + one `export type ${Pascal}Client = …['<scope>']` per scope.
+- **Modify** `src/codegen/emit-index.test.ts` — assert the new per-scope client type exports.
+
+Each task is independently testable and committable.
+
+---
+
+### Task 1: #9 — input-less routes emit `void` params
+
+**Files:**
+- Modify: `src/codegen/emit-scope.ts:398,536,679,816`
+- Test: `src/codegen/emit-scope.test.ts` (update `apiGroupNoBody`; add input-less RPC + stream fixtures)
+
+- [ ] **Step 1: Update the existing input-less assertions to the target output (failing test)**
+
+In `src/codegen/emit-scope.test.ts`, the `apiGroupNoBody` describe block currently asserts the old output. Change both occurrences:
+
+```ts
+// flat mode — was: client.bindCallable<unknown, void>
+it('neither body nor headers: param type is void, return type is void', async () => {
+  const out = await emitScopeFile(apiGroupNoBody)
+  expect(out).toContain('client.bindCallable<void, void>')
+  expect(out).not.toContain('client.bindCallable<unknown,')
+})
+```
+
+```ts
+// namespace mode — was: client.bindCallable<unknown, void>
+it('neither body nor headers: param type is void, return type is void', async () => {
+  const out = await emitScopeFile(apiGroupNoBody, { namespaceTypes: true })
+  expect(out).toContain('client.bindCallable<void, void>')
+})
+```
+
+- [ ] **Step 2: Add input-less RPC and stream fixtures + assertions (failing test)**
+
+Append to `src/codegen/emit-scope.test.ts`:
+
+```ts
+// Input-less RPC (no body) and stream (no params) — exercise the void-param fallback
+// across the RPC and stream emission paths, not just API.
+const rpcGroupNoInput: ScopeGroup = {
+  scopeKey: 'session',
+  camelCase: 'session',
+  routes: [
+    {
+      kind: 'rpc',
+      name: 'Logout',
+      path: '/session/logout',
+      method: 'post',
+      scope: 'session',
+      version: 1,
+      jsonSchema: {
+        response: { type: 'object', properties: { ok: { type: 'boolean' } }, required: ['ok'] },
+      },
+    } satisfies RPCHttpRouteDoc,
+  ],
+}
+
+const streamGroupNoParams: ScopeGroup = {
+  scopeKey: 'ticks',
+  camelCase: 'ticks',
+  routes: [
+    {
+      kind: 'stream',
+      name: 'WatchTicks',
+      path: '/ticks/stream',
+      methods: ['get'],
+      streamMode: 'sse',
+      scope: 'ticks',
+      version: 1,
+      jsonSchema: {
+        params: undefined,
+        yieldType: { type: 'object', properties: { n: { type: 'number' } }, required: ['n'] },
+        returnType: undefined,
+      },
+    } satisfies StreamHttpRouteDoc,
+  ],
+}
+
+describe('emitScopeFile input-less routes (void params)', () => {
+  it('RPC route with no body emits void as the params type arg', async () => {
+    const out = await emitScopeFile(rpcGroupNoInput)
+    expect(out).toContain('client.bindCallable<void,')
+    expect(out).not.toContain('client.bindCallable<unknown,')
+  })
+
+  it('stream route with no params emits void as the params type', async () => {
+    const out = await emitScopeFile(streamGroupNoParams)
+    // Stream callables are direct methods: WatchTicks(params: void, options?)
+    expect(out).toContain('WatchTicks(params: void')
+    expect(out).not.toContain('WatchTicks(params: unknown')
+  })
+})
+```
+
+- [ ] **Step 3: Run the tests to verify they fail**
+
+Run: `npx vitest run src/codegen/emit-scope.test.ts -t "void"`
+Expected: FAIL — the four assertions report `unknown` where `void` is expected.
+
+- [ ] **Step 4: Flip the four params fallbacks to `void`**
+
+In `src/codegen/emit-scope.ts`, change only the params-position fallbacks (leave response/yield fallbacks as `unknown`):
+
+```ts
+// line 398 (emitRpcRoute)
+const paramsTypeName = refs['Params'] ?? 'void'
+```
+```ts
+// line 536 (emitApiRoute)
+let paramsTypeName = 'void'
+```
+```ts
+// line 679 (emitHttpStreamRoute)
+let paramsTypeName = 'void'
+```
+```ts
+// line 816 (emitStreamRoute)
+const paramsTypeName = refs['Params'] ?? 'void'
+```
+
+Do NOT touch `:399` (`responseTypeName`), `:680` (`yieldTypeName`), or `:817` (`yieldTypeName`) — those are return/yield positions and stay `unknown`.
+
+- [ ] **Step 5: Run the new + existing scope tests to verify they pass**
+
+Run: `npx vitest run src/codegen/emit-scope.test.ts`
+Expected: PASS — all assertions green, including the unchanged input-ful routes (regression guard: routes with channels still emit `${Pascal}Req` / `Params`, never `void`).
+
+- [ ] **Step 6: Extend the canonical envelope fixture with an input-less route (pipeline-level guard)**
+
+Add an input-less route to `src/codegen/__fixtures__/users-envelope.json` so the full pipeline + any compile-level e2e exercises it (the existing five routes all have ≥1 req channel). Append to `routes`:
+
+```json
+{
+  "kind": "api",
+  "name": "Heartbeat",
+  "scope": "users",
+  "method": "GET",
+  "fullPath": "/users/heartbeat",
+  "jsonSchema": { "req": {}, "res": {} },
+  "errors": []
+}
+```
+
+- [ ] **Step 7: Run the full codegen suite to confirm nothing else snapshots the fixture route count**
+
+Run: `npx vitest run src/codegen/`
+Expected: PASS. If a fixture-count assertion in `pipeline.test.ts` / `e2e.test.ts` fails, update that count from 5 to 6 (the added route is intentional). Verify the failure is only the count, not a behavior change.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/codegen/emit-scope.ts src/codegen/emit-scope.test.ts src/codegen/__fixtures__/users-envelope.json
+git commit -m "feat(codegen): emit void params for input-less routes so api.X() needs no ({})"
+```
+
+---
+
+### Task 2: #8 + #10 — callable JSDoc surfaces the options bag and declared errors
+
+**Files:**
+- Modify: `src/codegen/emit-scope.ts` (add `buildCallableJsDoc`; replace single-line JSDoc at `:412,641,777,822`)
+- Test: `src/codegen/emit-scope.test.ts`
+
+- [ ] **Step 1: Write failing tests for the JSDoc breadcrumbs**
+
+Append to `src/codegen/emit-scope.test.ts`:
+
+```ts
+describe('emitScopeFile callable JSDoc surfaces options + errors', () => {
+  it('mentions the per-call options bag on an RPC callable', async () => {
+    const out = await emitScopeFile(rpcGroup)
+    expect(out).toContain('POST') // existing method label preserved
+    expect(out).toContain('@param options')
+    expect(out).toContain('ProcedureCallOptions')
+    expect(out).toContain('signal')
+  })
+
+  it('mentions declared errors + Scope.Route.Errors on a route with errors (namespace)', async () => {
+    const out = await emitScopeFile(rpcGroupWithErrors, {
+      namespaceTypes: true,
+      errorKeys: new Set(['NotFound']),
+      serviceName: 'Api',
+    })
+    expect(out).toContain('@throws')
+    expect(out).toContain('Users.GetUser.Errors')
+    expect(out).toContain('instanceof')
+  })
+
+  it('omits the @throws line when a route declares no errors', async () => {
+    const out = await emitScopeFile(rpcGroupNoErrors, { serviceName: 'Api' })
+    expect(out).not.toContain('@throws')
+    expect(out).toContain('@param options') // options line still present
+  })
+
+  it('mentions options on a stream callable but no @throws', async () => {
+    const out = await emitScopeFile(streamGroup)
+    expect(out).toContain('@param options')
+    expect(out).not.toContain('@throws')
+  })
+})
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `npx vitest run src/codegen/emit-scope.test.ts -t "JSDoc surfaces"`
+Expected: FAIL — current JSDoc is a single line (`/** POST /users/1 */`) with no `@param options` / `@throws`.
+
+- [ ] **Step 3: Add the `buildCallableJsDoc` helper**
+
+Add to `src/codegen/emit-scope.ts` (near the other route-emission helpers, above `emitRpcRoute`):
+
+```ts
+/**
+ * Builds the multi-line JSDoc comment for a route callable. Surfaces the
+ * second `options` argument (the per-call AbortSignal/timeout seam — DX #8) and,
+ * for routes that declare typed errors, points at the route's `Errors` type and
+ * how to narrow it on the throwing path (DX #10). Indented for placement inside
+ * the bind-object (4 spaces).
+ */
+function buildCallableJsDoc(opts: {
+  methodLabel: string
+  path: string
+  errorsRef: string | null
+}): string {
+  const lines = [
+    `    /**`,
+    `     * ${opts.methodLabel} ${opts.path}`,
+    `     *`,
+    `     * @param options Optional per-call {@link ProcedureCallOptions} —`,
+    `     *   \`signal\` (cancel on dispose), \`timeout\`, \`headers\`, \`basePath\`.`,
+  ]
+  if (opts.errorsRef) {
+    lines.push(
+      `     * @throws Declared typed errors: {@link ${opts.errorsRef}}. Narrow with`,
+      `     *   \`instanceof\` on the throwing path, or call \`.safe()\` for a \`Result\`.`,
+    )
+  }
+  lines.push(`     */`)
+  return lines.join('\n')
+}
+```
+
+- [ ] **Step 4: Replace the four single-line JSDoc comments with the helper**
+
+`emit-scope.ts:412` (RPC) — replace `` `    /** ${route.method.toUpperCase()} ${route.path} */`, `` with:
+```ts
+    buildCallableJsDoc({
+      methodLabel: route.method.toUpperCase(),
+      path: route.path,
+      errorsRef: hasErrors ? errorsRef : null,
+    }),
+```
+
+`emit-scope.ts:641` (API) — replace the single-line comment with:
+```ts
+    buildCallableJsDoc({
+      methodLabel: route.method.toUpperCase(),
+      path: route.fullPath,
+      errorsRef: hasErrors ? errorsRef : null,
+    }),
+```
+
+`emit-scope.ts:777` (http-stream) — streams carry no `.safe()` typed-error arm, so `errorsRef: null`:
+```ts
+    buildCallableJsDoc({
+      methodLabel: route.method.toUpperCase(),
+      path: route.fullPath,
+      errorsRef: null,
+    }),
+```
+
+`emit-scope.ts:822` (stream) — `errorsRef: null`:
+```ts
+    buildCallableJsDoc({
+      methodLabel: route.methods.map((m) => m.toUpperCase()).join('|'),
+      path: route.path,
+      errorsRef: null,
+    }),
+```
+
+> Note: `hasErrors` and `errorsRef` are already in scope at the RPC (`:403,:404`) and API (`:627`-region) call sites. Confirm before editing; if a site computes them later, hoist the computation above the callable array.
+
+- [ ] **Step 5: Run to verify the new tests pass and the existing method/path JSDoc assertions still hold**
+
+Run: `npx vitest run src/codegen/emit-scope.test.ts`
+Expected: PASS — including the existing `callable includes JSDoc with method and path` tests (`POST` / `/users/1` still present on the first comment line).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/codegen/emit-scope.ts src/codegen/emit-scope.test.ts
+git commit -m "feat(codegen): surface per-call options + declared errors in callable JSDoc"
+```
+
+---
+
+### Task 3: #15 — per-scope client interfaces derived from the bindings factory
+
+**Files:**
+- Modify: `src/codegen/emit-index.ts` (after the factory function, before/after `create${Service}Client`)
+- Test: `src/codegen/emit-index.test.ts`
+
+- [ ] **Step 1: Write failing tests for the derived client types**
+
+Add to `src/codegen/emit-index.test.ts` (use the existing multi-scope fixture in that file; if it has scopes `users` and `posts`, assert both):
+
+```ts
+describe('emitIndexFile per-scope client types (DX #15)', () => {
+  it('emits the aggregate client type from the factory return type', async () => {
+    const out = emitIndexFile(groups, { serviceName: 'Api' })
+    expect(out).toContain('export type ApiClient = ReturnType<typeof createApiBindings>')
+  })
+
+  it('emits one per-scope client type as an indexed access into the aggregate', async () => {
+    const out = emitIndexFile(groups, { serviceName: 'Api' })
+    // groups here are camelCase 'users' / 'posts' (adjust to the fixture's scopes)
+    expect(out).toContain("export type UsersClient = ApiClient['users']")
+    expect(out).toContain("export type PostsClient = ApiClient['posts']")
+  })
+
+  it('honors a custom serviceName in the client type names', async () => {
+    const out = emitIndexFile(groups, { serviceName: 'Catalog' })
+    expect(out).toContain('export type CatalogClient = ReturnType<typeof createCatalogBindings>')
+    expect(out).toContain("export type UsersClient = CatalogClient['users']")
+  })
+})
+```
+
+> Before writing, open `src/codegen/emit-index.test.ts` and reuse its existing `groups` fixture + `import { emitIndexFile }` line. Match the scope camelCase names it already defines rather than introducing new ones.
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `npx vitest run src/codegen/emit-index.test.ts -t "per-scope client types"`
+Expected: FAIL — no `export type ApiClient` / `UsersClient` in current output.
+
+- [ ] **Step 3: Emit the derived client types in `emit-index.ts`**
+
+In `src/codegen/emit-index.ts`, after the `${factoryName}` function is pushed onto `pieces` (after the block ending at line 107, before the `create${Service}Client` block at line 109), insert:
+
+```ts
+  // Per-scope client interfaces, derived from the bindings factory's return type
+  // (DX #15). Reuses the `ReturnType<typeof factory>` pattern already used by the
+  // convenience client below. Lets a consumer type a dependency as the narrow scope
+  // port — `constructor(client: UsersClient = api.users)` — and a fake satisfies just
+  // that scope with no `as unknown as typeof api` cast. `${Service}Client` is the
+  // callable bundle; it does NOT collide with the `${Service}.<Scope>` type namespace.
+  const aggregateClientType = `${servicePascal}Client`
+  pieces.push(
+    `export type ${aggregateClientType} = ReturnType<typeof ${factoryName}>`,
+    ...groups.map(
+      (g) => `export type ${toPascalCase(g.camelCase)}Client = ${aggregateClientType}['${g.camelCase}']`,
+    ),
+    '',
+  )
+```
+
+- [ ] **Step 4: Run to verify the new tests pass**
+
+Run: `npx vitest run src/codegen/emit-index.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Confirm the generated index still type-checks end-to-end**
+
+Run: `npx vitest run src/codegen/`
+Expected: PASS. The added type aliases are pure derivations of an existing emitted value, so any compile-level e2e test that builds the generated index continues to compile. If `e2e.test.ts` snapshots the full index text, update the snapshot and eyeball the diff (only the new `export type …Client` lines added).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/codegen/emit-index.ts src/codegen/emit-index.test.ts
+git commit -m "feat(codegen): emit per-scope client types so DI seams need no aggregate-client cast"
+```
+
+---
+
+## Self-Review
+
+**Spec coverage (Workstream A items #9, #8, #10-breadcrumb, #15):**
+- #9 → Task 1 (four `void` fallbacks + RPC/API/stream coverage + fixture). ✓
+- #8 → Task 2 (`@param options` on all four callable kinds). ✓
+- #10 (breadcrumb half) → Task 2 (`@throws` + `Scope.Route.Errors` + `instanceof`). The consumer prose half is Workstream D, out of this plan by design. ✓
+- #15 → Task 3 (`${Service}Client` + per-scope indexed types). ✓
+
+**Type consistency:** `buildCallableJsDoc({ methodLabel, path, errorsRef })` — same three-field shape at all four call sites. `errorsRef` is `string | null` everywhere (the RPC/API sites pass `hasErrors ? errorsRef : null`; stream sites pass `null`). `aggregateClientType` / `${Pascal}Client` naming consistent between emit code and tests.
+
+**Placeholder scan:** no TBD/TODO; every code step shows the literal edit; every run step shows the command + expected result.
+
+**Known follow-ups (NOT this plan):** the `isProcedureError` guard (deferred sugar — `instanceof` already works); the consumer-facing docs for #10/#8 (Workstream D); #6 no-content (Workstream B, server-side); correlation-id (Workstream E).
+
+---
+
+## Execution Handoff
+
+**Plan complete and saved to `docs/superpowers/plans/2026-06-08-codegen-dx-surfacing.md`. Two execution options:**
+
+**1. Subagent-Driven (recommended)** — fresh subagent per task, review between tasks, fast iteration.
+
+**2. Inline Execution** — execute tasks in this session via executing-plans, batch execution with checkpoints.
+
+**Which approach?**