ts-procedures 8.6.0 → 9.1.0

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

@@ -1,428 +0,0 @@
-# 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?**