ts-procedures 7.3.0 → 8.0.0

package/docs/superpowers/specs/2026-05-07-astro-adapter-design.md

@@ -12,7 +12,6 @@ The goal is a "drop in the entry point" adapter: a single catch-all Astro file d
 
 ## Non-goals
 
-- Express RPC support. Express uses Node `req`/`res`, not Web `Request`/`Response`. A bridge is non-trivial (body streams, hijacked sockets, `res.flushHeaders`); defer until requested.
 - Native Astro builders. Mirroring `HonoAPIAppBuilder` as `AstroAPIAppBuilder` would duplicate path-matching, schema validation, error taxonomy, and DocRegistry plumbing. The catch-all pattern covers the request without that cost.
 - Per-procedure file scaffolding (one Astro file per procedure). Out of scope for v1.
 - DocRegistry / codegen integration. Users keep wiring `DocRegistry` against the same builders they pass to the adapter; the adapter returns no `.docs`.
@@ -229,7 +228,6 @@ Integration-style, real builders, simulated `Request`:
 },
 "optionalDependencies": {
   "ajsc": "...",
-  "express": "...",
   "hono": "...",
   "astro": "^5.0.0"
 },
@@ -239,7 +237,7 @@ Integration-style, real builders, simulated `Request`:
 }
 ```
 
-Matching the existing pattern for `hono` and `express`: listed as `optionalDependencies` so it isn't pulled into non-Astro deployments, and as `devDependencies` so types resolve at build time. Astro is imported via `import type` only — zero runtime dependency on the published package.
+Matching the existing pattern for `hono`: listed as `optionalDependencies` so it isn't pulled into non-Astro deployments, and as `devDependencies` so types resolve at build time. Astro is imported via `import type` only — zero runtime dependency on the published package.
 
 ## Agent config / docs
 

package/docs/superpowers/specs/2026-05-08-create-http-design.md

@@ -0,0 +1,409 @@
+# CreateHttp & CreateHttpStream — Design
+
+Date: 2026-05-08
+Branch: TBD (next major — v8)
+Status: design
+
+## Goal
+
+Eliminate the long-standing `schema.params` vs `schema.input` ambiguity on the core `Create` / `CreateStream` primitives by splitting the surface into four purpose-shaped creators. RPC stays as the lean primitive; HTTP becomes its own first-class shape with structured request channels and response (body + headers) typing.
+
+| Creator | Purpose | Schema shape |
+|---|---|---|
+| `Create` | RPC unary (today's primitive, simplified) | `{ params, returnType }` |
+| `CreateStream` | RPC streaming (today's primitive, simplified) | `{ params, yieldType, returnType }` |
+| `CreateHttp` | HTTP unary (new) | `{ req: { pathParams?, query?, body?, headers? }, res?: { body?, headers? } }` |
+| `CreateHttpStream` | HTTP streaming (new) | `{ req: {...}, yield, returnType?, res?: { headers? } }` |
+
+The `Create` / `CreateStream` shape stops accepting `schema.input` entirely. HTTP-specific config (`path`, `method`, `successStatus`, `scope`, `errors`) becomes first-class on the HTTP creators rather than living on a `TExtendedConfig` generic. Response headers — previously not modelable — become a typed first-class concept.
+
+## Non-goals
+
+- **Runtime validation of `res.body` / `res.headers`.** Today `schema.returnType` is doc-only at runtime; the same rule applies to `res`. Adding a `validateResponse: true` opt-in is a clean follow-up but kept out to bound the breaking-changes scope to the input ambiguity cleanup.
+- **`ctx.res.setHeader(...)` style imperative API.** Headers flow through the handler return value only. Pure return-driven, type-checkable end-to-end.
+- **Per-builder migration adapters.** This is a major version. Clean break with informative `ProcedureRegistrationError` migration messages — no v7-compat shim layer.
+- **Renaming `Create` or `CreateStream`.** Their shapes simplify (lose `schema.input`), but the names and the RPC posture stay.
+
+## Decisions locked during brainstorming
+
+1. **Four creators, one factory.** `Procedures<TContext>()` returns `{ Create, CreateStream, CreateHttp, CreateHttpStream }`. Mirrors the existing `Create` / `CreateStream` split.
+2. **Conditional return shape on HTTP creators.** Handler return widens type-driven from declared `res`:
+   - no `res` → `void`
+   - `res: { body }` → bare body (matches today's `schema.returnType` ergonomics)
+   - `res: { headers }` → `{ headers }`
+   - `res: { body, headers }` → `{ body, headers }`
+3. **HTTP fields baked into CreateHttp config.** `path`, `method`, `successStatus`, `scope`, `errors` live directly on the `CreateHttp` / `CreateHttpStream` config — no `Procedures<Ctx, APIConfig>()` plumbing for HTTP routes. `Create` / `CreateStream` keep `TExtendedConfig` for non-HTTP extensions (`RPCConfig`, etc.).
+4. **`CreateHttpStream` initial response headers** via async-preamble shape: when `res.headers` is declared, the handler is an `async` function returning `{ headers, stream: AsyncGenerator }`. When not, the handler is a plain `async function*`.
+5. **`schema.input` and `APIInput` removed.** Not deprecated — removed. `ProcedureRegistrationError` thrown at registration time with a v8 migration message.
+
+## API surface
+
+### The four creators
+
+```ts
+const procs = Procedures<MyContext>()
+
+// 1. RPC unary — schema.input removed; schema.params is the only input shape
+procs.Create('GetUser', {
+  schema: {
+    params: Type.Object({ id: Type.String() }),
+    returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+  },
+}, async (ctx, { id }) => ({ id, name: 'John' }))
+
+// 2. RPC streaming — schema.input removed
+procs.CreateStream('Tail', {
+  schema: {
+    params: Type.Object({ source: Type.String() }),
+    yieldType: Type.Object({ line: Type.String() }),
+    returnType: Type.Object({ totalLines: Type.Number() }),
+  },
+}, async function* (ctx, { source }) { /* ... */ })
+
+// 3. HTTP unary
+procs.CreateHttp('GetUser', {
+  path: '/users/:id',
+  method: 'get',
+  successStatus: 200,         // optional, defaulted by method
+  scope: 'users',              // optional, codegen grouping
+  errors: ['UserNotFound'],    // optional, taxonomy keys (TErrorKey-narrowable)
+  schema: {
+    req: {
+      pathParams: Type.Object({ id: Type.String() }),
+      query: Type.Object({ include: Type.Optional(Type.String()) }),
+    },
+    res: {
+      body: Type.Object({ id: Type.String(), name: Type.String() }),
+      headers: Type.Object({ 'x-rate-limit-remaining': Type.String() }),
+    },
+  },
+}, async (ctx, { pathParams, query }) => ({
+  body: { id: pathParams.id, name: 'John' },
+  headers: { 'x-rate-limit-remaining': '99' },
+}))
+
+// 4. HTTP streaming — async preamble + generator when res.headers declared
+procs.CreateHttpStream('TailLogs', {
+  path: '/streams/logs',
+  method: 'get',
+  scope: 'streams',
+  schema: {
+    req: { query: Type.Object({ source: Type.String() }) },
+    yield: Type.Object({ line: Type.String() }),
+    returnType: Type.Object({ totalLines: Type.Number() }),
+    res: { headers: Type.Object({ 'x-stream-id': Type.String() }) },
+  },
+}, async (ctx, { query }) => {
+  const streamId = await openStream(query.source)
+  return {
+    headers: { 'x-stream-id': streamId },
+    stream: (async function* () {
+      yield { line: 'a' }
+      return { totalLines: 1 }
+    })(),
+  }
+})
+
+// 4b. Without res.headers — plain async generator (today's CreateStream shape)
+procs.CreateHttpStream('TailLogs', {
+  path: '/streams/logs', method: 'get',
+  schema: {
+    req: { query: Type.Object({ source: Type.String() }) },
+    yield: Type.Object({ line: Type.String() }),
+    returnType: Type.Object({ totalLines: Type.Number() }),
+  },
+}, async function* (ctx, { query }) {
+  yield { line: 'a' }
+  return { totalLines: 1 }
+})
+```
+
+### Handler signature inference
+
+```ts
+type CreateHttpHandler<TReq, TRes, TContext> = (
+  ctx: TContext & TLocalContext,
+  req: PrettifyChannels<TReq>,
+) => Promise<HttpReturn<TRes>>
+
+type HttpReturn<TRes> =
+  TRes extends { body: infer B; headers: infer H } ? { body: Infer<B>; headers: Infer<H> }
+  : TRes extends { headers: infer H }              ? { headers: Infer<H> }
+  : TRes extends { body: infer B }                  ? Infer<B>
+  : void
+```
+
+`PrettifyChannels<TReq>` maps each declared channel through `TSchemaLib<TReq[K]>` — same machinery as today's `schema.input` inference at `src/index.ts:127-130`.
+
+`ctx` shape is unchanged from today: `TContext & { error, signal? }` for `CreateHttp`, `TContext & { error, signal: AbortSignal }` for `CreateHttpStream`. Hono builders inject `c.req.raw.signal` automatically.
+
+### Generic over `TErrorKey`
+
+Same compile-time typo protection as today's `APIConfig<TErrorKey>`, lifted onto the creator. `TErrorKey` defaults to `string` (unconstrained) and gets narrowed in one of two ways:
+
+**Per-call narrowing via `satisfies`** (zero ceremony):
+
+```ts
+const appErrors = defineErrorTaxonomy({
+  UserNotFound: { class: UserNotFoundError, statusCode: 404 },
+})
+type AppErrorKey = keyof typeof appErrors & string
+
+procs.CreateHttp('GetUser', {
+  path: '/users/:id', method: 'get',
+  errors: ['UserNotFound', 'NotARealKey'] satisfies AppErrorKey[],  //  ^^ TS error
+  schema: { req: {...}, res: {...} },
+}, handler)
+```
+
+**App-wide narrowing via aliased creator** (DRYer for large apps): expose a typed alias once at module-init time and use it everywhere:
+
+```ts
+const procs = Procedures<MyContext>()
+const HttpRoute = procs.CreateHttp as
+  <TName extends string, TReq, TRes>(
+    name: TName,
+    config: CreateHttpConfig<TReq, TRes, AppErrorKey>,
+    handler: CreateHttpHandler<TReq, TRes, MyContext>,
+  ) => ReturnType<typeof procs.CreateHttp<TName, TReq, TRes, AppErrorKey>>
+
+HttpRoute('GetUser', { ..., errors: ['UserNotFound'] }, handler)
+```
+
+The framework ships `CreateHttpConfig` and `CreateHttpHandler` as exported helper types so the alias pattern is a one-liner per app.
+
+### `kind` discriminant on every registration
+
+Replaces today's `isStream?: boolean`. Builders filter by kind; non-matching procedures recorded in `skippedProcedures` and warned at `DocRegistry.toJSON()` time.
+
+```ts
+type ProcedureKind = 'rpc' | 'rpc-stream' | 'http' | 'http-stream'
+```
+
+| Creator | `kind` | Served by |
+|---|---|---|
+| `Create` | `'rpc'` | hono-rpc |
+| `CreateStream` | `'rpc-stream'` | hono-stream |
+| `CreateHttp` | `'http'` | hono-api |
+| `CreateHttpStream` | `'http-stream'` | hono-api |
+
+## Builder integration
+
+### `HonoAPIAppBuilder` — unified HTTP builder
+
+Serves both `'http'` and `'http-stream'` registrations. Single mount, single error config, single doc source. Internal branch on kind:
+
+- **`'http'` branch:** today's flow with three differences:
+  1. Reads `path` / `method` / `successStatus` / `scope` / `errors` directly off the registration (no `Procedures<Ctx, APIConfig>()` generic plumbing).
+  2. Drops the `schema.params` body/query fallback. `req` channels are the only source.
+  3. When the handler returns `{ body, headers }`, iterate headers via `c.header(k, v)` before `c.json(body, status)` / `c.body(null, status)`. Error responses don't carry handler-declared headers.
+- **`'http-stream'` branch:** pre-stream phase (validation + async preamble if `res.headers` declared) → if it throws, error taxonomy serializes a normal HTTP error (no SSE opened); if it succeeds, response headers are written, then the SSE/text stream opens. Mid-stream errors continue through `onMidStreamError`. The `isPrevalidated` flag pattern (today used by HonoStreamAppBuilder) extends to this branch.
+
+`HonoAPIFactoryItem<TFactory>` simplifies — no `APIConfig` extension generic. `extendProcedureDoc` callback signature is unchanged, but the `base` doc handed to it has the new `req`/`res` grouping (callbacks reading `base.jsonSchema.body` directly need to read `base.jsonSchema.req.body` after upgrade).
+
+The path-param consistency check (`extractPathParamNames` + schema key matching) **moves from the Hono builder into core `CreateHttp` registration** — fires at registration time regardless of which HTTP builder is attached. `ProcedureRegistrationError` with the existing well-formed message.
+
+### Other builders — minimal change
+
+- **`HonoStreamAppBuilder`:** unchanged externally. Internally filters by `kind === 'rpc-stream'`. Symmetric pair to `HonoRPCAppBuilder` for serving `Create` / `CreateStream`.
+- **`HonoRPCAppBuilder`:** unchanged externally. Internally filters by `kind === 'rpc'`. CreateHttp registrations on the same factory get recorded in `skippedProcedures`.
+- **Astro adapter** (`src/implementations/http/astro/`): same kind-aware updates as hono-api. Mirrors the hono-api pattern. Implementation phase.
+
+### Mixed-kind factories
+
+Because all four creators share one `Procedures()` factory, you *can* mix `Create` and `CreateHttp` in the same factory. Builders pick out what they serve. The user-facing rule: register a builder for each kind you want to serve.
+
+## Doc envelope & codegen impact
+
+### `APIHttpRouteDoc` regroups under `req` / `res`
+
+Symmetric with the registration shape — removes the awkward "request `headers` vs response `headers`" overload at the JSON schema level (today both would just be top-level `headers`):
+
+```ts
+// before
+jsonSchema: { pathParams?, query?, body?, headers?, response? }
+
+// after
+jsonSchema: {
+  req:  { pathParams?, query?, body?, headers? }
+  res?: { body?, headers? }
+}
+```
+
+### New `'http-stream'` kind in the envelope
+
+Existing `StreamHttpRouteDoc` (kind `'stream'`) keeps serving `CreateStream` unchanged. New variant for `CreateHttpStream`:
+
+```ts
+interface HttpStreamRouteDoc {
+  kind: 'http-stream'
+  name: string
+  scope?: string
+  path: string
+  method: HttpMethod
+  fullPath: string
+  streamMode: StreamMode
+  jsonSchema: {
+    req:  { pathParams?, query?, body?, headers? }
+    res?: { headers? }       // body absent — yield/returnType replace it
+    yield?: Record<string, unknown>
+    returnType?: Record<string, unknown>
+  }
+  errors?: string[]          // pre-stream only
+}
+```
+
+`AnyHttpRouteDoc = RPCHttpRouteDoc | APIHttpRouteDoc | StreamHttpRouteDoc | HttpStreamRouteDoc`.
+
+### Generated callable shape (TS target)
+
+Conditional return widens symmetric to the server side:
+
+```ts
+// res: { body } only — bare body (no break for routes without res.headers)
+function getUser(req, opts?): Promise<GetUser.Response.Body>
+
+// res: { body, headers }
+function getUser(req, opts?): Promise<{ body: GetUser.Response.Body; headers: GetUser.Response.Headers }>
+
+// res: { headers } only
+function getUser(req, opts?): Promise<{ headers: GetUser.Response.Headers }>
+```
+
+Generated namespace (namespace mode):
+```
+Users.GetUser.Req.PathParams
+Users.GetUser.Req.Query
+Users.GetUser.Req.Body
+Users.GetUser.Req.Headers
+Users.GetUser.Response.Body
+Users.GetUser.Response.Headers
+Users.GetUser.Errors
+```
+
+Flat-mode aliases: `GetUserReqPathParams`, `GetUserReqBody`, `GetUserResponseBody`, `GetUserResponseHeaders`. Naming lives in `src/codegen/emit-scope.ts` and per-target run modules; `targets/_shared/route-slots.ts` gets a response-headers slot.
+
+`.safe()` widens identically: `Result<{ body, headers }, ETyped>` when headers declared. The `'typed'` arm omission rule (when no `route.errors`) is unchanged.
+
+### `CreateHttpStream` generated callable
+
+Returns `TypedStream<TYield, TReturn>` as today; `TypedStream` gains an optional `.headers` field surfaced by the adapter when `res.headers` is declared on the route:
+
+```ts
+interface TypedStream<TYield, TReturn> {
+  [Symbol.asyncIterator](): AsyncIterator<TYield>
+  result: Promise<TReturn>
+  headers?: Headers   // populated at stream-open time
+}
+```
+
+At runtime `.headers` is always populated (the adapter has the response Headers object). The TypeScript surface marks it optional and emits it on the route's `TypedStream` type only when `res.headers` is declared, so callers without declared response headers don't see it in their type — no behavior difference, just type-level discipline. `AdapterStreamResponse` extends with a `headers: Headers` field; `executeStream` wires it onto the constructed `TypedStream`.
+
+### Kotlin / Swift targets
+
+Mobile devs own the HTTP layer entirely (existing posture). Emit a `Response.Headers` data class / struct only when `res.headers` is declared. Consumer's HTTP wrapper maps response headers into it. No runtime adapter changes for these targets.
+
+### Self-contained codegen
+
+`_client.ts` extends to read response headers from the unary response and surface initial headers on the stream response. Everything else (error registry, runtime classes, dispatch, `_errors.ts`, `_types.ts`) is unchanged. Source-hash invalidation forces regeneration on upgrade — no migration tooling needed.
+
+## Error handling
+
+The existing taxonomy system (`defineErrorTaxonomy`, `resolveErrorResponse`, `defaultErrorTaxonomy`) carries forward unchanged. Per-route `errors` keys, dispatch order (`onRequestError` observer → taxonomy → `onError` → hard default), and the client error registry / dispatch all keep their shape.
+
+### `CreateHttpStream` error lifecycle
+
+- **Pre-stream** (validation, async preamble): unary error dispatch — taxonomy / `onError` / hard default. SSE response never opened. Identical to today's HonoStreamAppBuilder pre-stream behavior, extended to the async preamble step.
+- **Mid-stream** (errors thrown after first yield): `onMidStreamError`, unchanged. Taxonomy doesn't apply — response already committed.
+
+### `isPrevalidated` and `noRuntimeValidation`
+
+Both unchanged. `isPrevalidated` flag pattern extends to the new `'http-stream'` builder branch. `noRuntimeValidation` opts the entire factory out of per-call AJV for all four creators (JSON Schema still computed at registration time).
+
+### New registration-time errors (all `ProcedureRegistrationError`)
+
+| Trigger | Migration message |
+|---|---|
+| `schema.input` on `Create` / `CreateStream` | "`schema.input` was removed in v8. Use `CreateHttp` / `CreateHttpStream` for per-channel HTTP validation." |
+| `path` / `method` / `req` / `res` on `Create` / `CreateStream` | "HTTP fields require `CreateHttp` / `CreateHttpStream`." |
+| `schema.params` on `CreateHttp` / `CreateHttpStream` | "Use `schema.req.body` (or `query`) instead of `schema.params`." |
+| Path template params don't match `req.pathParams` schema keys | (existing message, moved into core) |
+
+Phrased as "X was removed in v8, use Y" so anyone running v7 code against the v8 core gets pointed straight at the fix.
+
+## Source organization
+
+`src/index.ts` is 537 lines today. Adding two more creators inline doubles the surface. Split:
+
+```
+src/
+  index.ts                # Procedures factory, glue (~80 lines)
+  create.ts               # Create
+  create-stream.ts        # CreateStream
+  create-http.ts          # CreateHttp + path-param consistency check
+  create-http-stream.ts   # CreateHttpStream
+  types.ts                # TLocalContext, TStreamContext, registration types, ProcedureKind
+  schema/                 # unchanged
+  implementations/        # builders updated per "Builder integration" section
+  codegen/                # updated per "Doc envelope & codegen impact" section
+  client/                 # _client.ts response.headers + TypedStream.headers
+```
+
+Each creator is independent and self-contained — passes the "what does it do, how do you use it, what does it depend on" test.
+
+## Migration
+
+Major version (v8). No deprecation period. Registration errors are the migration safety net.
+
+| v7 | v8 |
+|---|---|
+| `Procedures<Ctx, APIConfig>()` | `Procedures<Ctx>()` |
+| `.Create('GetUser', { path, method, schema: { input: {...} } }, h)` | `.CreateHttp('GetUser', { path, method, schema: { req: {...}, res: { body: ... } } }, h)` |
+| `.CreateStream('Tail', { path, method, schema: { input: {...} } }, g)` | `.CreateHttpStream('Tail', { path, method, schema: { req: {...}, yield: ... } }, g)` |
+| `schema.input.pathParams` | `schema.req.pathParams` |
+| `schema.params` on an HTTP route | `schema.req.body` or `schema.req.query` (explicit channel) |
+| `APIInput<{...}>` satisfies type | removed — channels typed by `req` directly |
+| `Procedures<Ctx, RPCConfig>().Create(...)` | unchanged — RPC factories keep `TExtendedConfig` |
+| Handler `(ctx, { pathParams, query, body }) => result` | unchanged — request side identical |
+| Handler `return result` | unchanged unless `res.headers` declared → `return { body, headers }` |
+
+### What's NOT changing
+
+- `HonoRPCAppBuilder`, `HonoStreamAppBuilder` external APIs.
+- `DocRegistry`, error taxonomy public API.
+- Client error dispatch, generated error registry, per-route `Errors` union.
+- Per-call `ProcedureCallOptions`, hooks pipeline, `RequestMeta` augmentation.
+- `TypedStream` external API (only addition: optional `.headers`).
+- AJV config (`allErrors`, `coerceTypes`, `removeAdditional`).
+- Codegen flag set, CLI surface, `--target ts/kotlin/swift`.
+
+### Codegen consumer migration
+
+1. `npm install` v8 server packages.
+2. Restart the dev server / rebuild.
+3. Re-run `npx ts-procedures-codegen` (or `--watch`). Source hash invalidates; fresh files written.
+4. TS callers update flat-mode aliases (`GetUserResponse` → `GetUserResponseBody`); namespace-mode users get `Users.GetUser.Response.Body` automatically.
+5. Routes adopting `res.headers` update await sites: `const { body, headers } = await api.users.getUser(req)`.
+
+## Testing
+
+| Test file | Coverage |
+|---|---|
+| `src/create.test.ts` | Extracted from `index.test.ts`. Create-only path. Schema-input rejection. |
+| `src/create-stream.test.ts` | CreateStream-only. Schema-input rejection. Yield validation, abort, generator return value. |
+| `src/create-http.test.ts` | All four req-channel combos. Response shape: body-only, body+headers, headers-only, void. Registration errors (HTTP fields rejected on Create, path-param mismatch, `schema.params` rejected). `TErrorKey` compile-time narrowing via `expectTypeOf`. |
+| `src/create-http-stream.test.ts` | Both handler shapes (async generator vs. async-returning-`{headers, stream}`). Pre-stream errors as HTTP errors. Mid-stream errors → `onMidStreamError`. Initial headers applied before first yield. |
+| `src/implementations/http/hono-api/index.test.ts` | Both `'http'` and `'http-stream'` kinds. Response headers application. `skippedProcedures` for non-http kinds. |
+| `src/implementations/http/{hono-rpc,hono-stream}/index.test.ts` | Filter by `kind`. `skippedProcedures` populated when CreateHttp procedures are registered to RPC factories. |
+| `src/codegen/__fixtures__/users-envelope.json` | Regenerated to v8 envelope (`req`/`res` grouping, new `'http-stream'` kind). |
+| `src/codegen/targets/{ts,kotlin,swift}/run.test.ts` | Snapshot updates. New tests for `Response.Headers` emission. |
+| `src/client/call.test.ts`, `stream.test.ts` | Response-headers parsing on unary; `TypedStream.headers` populated for streams declaring `res.headers`. |
+
+## Out-of-scope follow-ups
+
+These are flagged for the implementation phase but not part of this design:
+
+- **`agent_config/` updates** — `claude-code/skills/ts-procedures-scaffold/templates/`, `claude-code/skills/ts-procedures/patterns.md`, `anti-patterns.md`, `cursor/cursorrules`, `copilot/copilot-instructions.md` updated to use `CreateHttp` for HTTP examples.
+- **`CHANGELOG.md` and `README.md`** — major-version entry with migration table and v7→v8 expectations.
+- **`validateResponse: true` opt-in** — runtime validation of `res.body` / `res.headers`. Clean follow-up; non-breaking.
+- **Astro adapter detail design** — mirrors hono-api; called out as "same kind-aware updates" but not specced separately.