ts-procedures 7.1.1 → 7.2.0

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

@@ -0,0 +1,254 @@
+# Astro adapter for ts-procedures
+
+**Date:** 2026-05-07
+**Status:** Design — pending implementation
+**Subpath export:** `ts-procedures/astro`
+
+## Problem
+
+Downstream developers using Astro want to host ts-procedures handlers inside Astro server endpoints (`src/pages/**/*.ts`). Today they must hand-roll the bridge: take an Astro `APIRoute`, convert its `APIContext` into a `Request`, find a way to dispatch through their procedure factories, and translate the result back. Astro's filesystem-as-router model also resists the existing `register(...).build()` pattern, which produces one app for many routes.
+
+The goal is a "drop in the entry point" adapter: a single catch-all Astro file delegates every procedure call to one or more already-built ts-procedures apps, with full access to Astro's per-request data (`locals`, `cookies`, `redirect`) inside procedure handlers.
+
+## 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`.
+- `dispatch: 'merge'` strategy. YAGNI — users who want one Hono app can pre-merge with `app.route(...)` themselves.
+
+## Approach
+
+The adapter is a thin Web-fetch delegator. It accepts already-built Hono apps (from any of `HonoAPIAppBuilder`, `HonoRPCAppBuilder`, `HonoStreamAppBuilder`) and exposes Astro `APIRoute` exports the developer re-exports from a catch-all file.
+
+```
+Browser → /api/users/123
+  ↓
+Astro invokes ALL({ request, locals, cookies, params, redirect, url, ... })
+  ↓
+Adapter:
+  1. Strip pathPrefix from request URL (if configured) → `rewritten`
+       (when no prefix configured, `rewritten` IS `request`)
+  2. astroContextMap.set(rewritten, apiContext)            — WeakMap stash
+  3. For each app in order: response = await app.fetch(rewritten)
+       — first response with status !== 404 is returned (a 500 from
+         app A stops dispatch; it is treated as a real answer, not a
+         miss). Only a literal 404 falls through to the next app.
+  4. All apps 404 → new Response(null, { status: 404 })
+  ↓
+Inside any factory-context closure:
+  getAstroContext(c) → reads c.req.raw → WeakMap lookup → APIContext
+```
+
+The WeakMap is keyed by the `Request` object that Hono ends up seeing — i.e., the post-rewrite Request when `pathPrefix` is configured, and the original Request when it isn't. Hono exposes that same Request on `c.req.raw`, which is what `getAstroContext` reads. Stashing happens AFTER the rewrite so the key matches what Hono observes. Entries clear when the Request is GC'd — no manual cleanup, no leak.
+
+## Public API
+
+Two exports:
+
+```ts
+import type { Hono, Context as HonoContext } from 'hono'
+import type { APIContext, APIRoute } from 'astro'
+
+export type AstroAdapterConfig = {
+  /** One or more built Hono apps. Order matters in 'first-match' dispatch. */
+  apps: Hono | Hono[]
+
+  /**
+   * Path prefix matching the Astro catch-all mount point.
+   * For src/pages/api/[...rest].ts use '/api'. The adapter strips this
+   * before delegating, so Hono routes do NOT need to repeat the prefix.
+   *
+   * Normalization: leading and trailing slashes are optional; '/api',
+   * 'api', and '/api/' are equivalent.
+   */
+  pathPrefix?: string
+}
+
+export type AstroHandlers = {
+  ALL: APIRoute
+  GET: APIRoute
+  POST: APIRoute
+  PUT: APIRoute
+  PATCH: APIRoute
+  DELETE: APIRoute
+  HEAD: APIRoute
+  OPTIONS: APIRoute
+}
+
+export function createAstroHandler(config: AstroAdapterConfig): AstroHandlers
+
+/**
+ * Read Astro's APIContext from inside a Hono factory-context closure.
+ * Throws if called outside an Astro request scope (e.g., if the Hono app
+ * is also being served outside the adapter and the closure ran there).
+ */
+export function getAstroContext(c: HonoContext): APIContext
+```
+
+`createAstroHandler` returns every method handler so the developer can destructure whichever they want. Most consumers use `ALL`. Per-method exports support cases where Astro's behavior diverges by method (e.g., `HEAD` auto-derived from `GET`).
+
+## Developer-facing usage
+
+```ts
+// src/server/procedures/users.ts
+import { Procedures } from 'ts-procedures'
+import { Type } from 'typebox'
+
+export const usersAPI = Procedures<{ db: Db; user: User | null }, APIConfig>()
+
+usersAPI.Create('GetUser', {
+  path: '/users/:id',
+  method: 'get',
+  schema: {
+    input: { pathParams: Type.Object({ id: Type.String() }) },
+    returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+  },
+}, async (ctx, { pathParams }) => {
+  return ctx.db.users.findOne(pathParams.id)
+})
+```
+
+```ts
+// src/server/api.ts
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import { getAstroContext } from 'ts-procedures/astro'
+import { usersAPI } from './procedures/users'
+import { db } from './db'
+
+export const apiApp = new HonoAPIAppBuilder()
+  .register(usersAPI, (c) => {
+    const astro = getAstroContext(c)
+    return { db, user: astro.locals.user ?? null }
+  })
+  .build()
+```
+
+```ts
+// src/pages/api/[...rest].ts
+import { createAstroHandler } from 'ts-procedures/astro'
+import { apiApp } from '../../server/api'
+
+export const { ALL } = createAstroHandler({
+  apps: apiApp,
+  pathPrefix: '/api',
+})
+```
+
+Multi-app variant:
+
+```ts
+export const { ALL } = createAstroHandler({
+  apps: [apiApp, rpcApp, streamsApp],
+  pathPrefix: '/api',
+})
+```
+
+## Path-prefix rewrite
+
+```ts
+function stripPrefix(request: Request, prefix: string | undefined): Request | null {
+  if (!prefix) return request
+  const url = new URL(request.url)
+  const norm = '/' + prefix.replace(/^\/|\/$/g, '')   // → '/api'
+  if (norm === '/') return request
+  if (!url.pathname.startsWith(norm)) return null      // 404 fast-path
+  const rest = url.pathname.slice(norm.length)
+  url.pathname = rest === '' ? '/' : rest
+  return new Request(url, request)                     // copies method/headers/body/signal/duplex
+}
+```
+
+`new Request(url, request)` per the Web spec init pattern preserves method, headers, body stream, abort signal, and `duplex` mode. Body streams pass through; client disconnect aborts continue to fire on `c.req.raw.signal` inside Hono.
+
+Edge cases:
+- `pathPrefix` undefined → no rewrite
+- `pathPrefix` normalizes to `'/'` → no rewrite (root mount)
+- Request path doesn't start with the normalized prefix → adapter returns 404 without invoking any app
+- Exact prefix match (`/api` with request `/api`) → rewrites to `/`
+
+## Streams & abort signals
+
+Hono stream builders return `Response` with a `ReadableStream` body. Astro SSR forwards that body verbatim — no special handling.
+
+`request.signal` flow on client disconnect:
+```
+Browser closes EventSource
+  → Astro aborts request.signal
+  → rewriteRequest preserves signal via new Request(url, request)
+  → Hono's c.req.raw.signal === request.signal
+  → Stream builder's ctx.signal fires (reason 'client-disconnect')
+```
+
+Same path the existing Hono stream tests cover; one new integration test wires Astro→Hono-stream end-to-end.
+
+## Error handling
+
+The adapter performs no error handling of its own. Errors flow through whatever the underlying Hono builder is configured with — taxonomy, `onError`, `onRequestError`. The adapter returns whatever Response Hono produced.
+
+The only Response the adapter constructs itself: a stock `new Response(null, { status: 404 })` returned when (a) the path-prefix rewrite fails (request path outside the mount), or (b) every registered app returned 404.
+
+If `getAstroContext(c)` is called outside an Astro request (the Hono app is also being served via a non-Astro path and the closure ran there), it throws with a clear message. This propagates into Hono's normal error path and through the configured taxonomy.
+
+## File layout
+
+```
+src/implementations/http/astro/
+├── README.md
+├── index.ts                   # public exports
+├── create-handler.ts          # createAstroHandler, multi-app dispatch
+├── astro-context.ts           # WeakMap + getAstroContext
+├── rewrite-request.ts         # stripPrefix
+└── index.test.ts              # integration tests vs real Hono builders
+```
+
+## Tests
+
+Integration-style, real builders, simulated `Request`:
+
+1. Single Hono API app — GET and POST roundtrip, request/response bodies intact, headers preserved
+2. Path prefix normalization: `/api`, `api`, `/api/`, exact-match → root, missing prefix → 404 short-circuit, no prefix configured, query string preserved through the rewrite (`/api/users?limit=10` → inner app sees `/users?limit=10`)
+3. `getAstroContext(c)` returns the same `APIContext` object passed to `ALL`
+4. Multi-app first-match: app A returns 404 → app B handles → app B's response returned
+5. Multi-app non-404 short-circuit: app A returns 500 → app B is NOT invoked; app A's 500 is returned
+6. All-404 fallback returns adapter's 404 (status 404, empty body), not Hono's
+7. Stream pass-through: `HonoStreamAppBuilder` + generator yielding 3 events; verify all 3 reach the consumer through the adapter
+8. Abort signal flow: simulate client disconnect by aborting the incoming `Request` mid-stream; assert `ctx.signal.aborted === true` inside the handler with `signal.reason !== 'stream-completed'`
+9. `getAstroContext` outside Astro scope throws a clear error
+
+## Package wiring
+
+```json
+// package.json (additions)
+"exports": {
+  "./astro": {
+    "types": "./build/implementations/http/astro/index.d.ts",
+    "import": "./build/implementations/http/astro/index.js"
+  }
+},
+"optionalDependencies": {
+  "ajsc": "...",
+  "express": "...",
+  "hono": "...",
+  "astro": "^5.0.0"
+},
+"devDependencies": {
+  "...": "...",
+  "astro": "^5.0.0"
+}
+```
+
+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.
+
+## Agent config / docs
+
+Mirror the pattern used when other builders shipped:
+- New `docs/astro-adapter.md` end-to-end walkthrough
+- Update `agent_config/claude-code/skills/ts-procedures/api-reference.md` and `patterns.md` to teach downstream Claude/Cursor/Copilot rules the Astro path
+- New `agent_config/claude-code/skills/ts-procedures-scaffold/templates/astro-catchall.ts` template
+- `src/implementations/http/astro/README.md` with usage and the prefix-semantics table
+
+## Open questions
+
+None at design time. Ready for implementation planning.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "7.1.1",
+  "version": "7.2.0",
   "description": "A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation, and framework integration hooks.",
   "main": "build/exports.js",
   "types": "build/exports.d.ts",
@@ -23,6 +23,10 @@
       "types": "./build/exports.d.ts",
       "import": "./build/exports.js"
     },
+    "./astro": {
+      "types": "./build/implementations/http/astro/index.d.ts",
+      "import": "./build/implementations/http/astro/index.js"
+    },
     "./http": {
       "types": "./build/implementations/types.d.ts"
     },
@@ -75,10 +79,29 @@
     "validation",
     "procedures",
     "api",
-    "framework"
+    "framework",
+    "hono",
+    "express",
+    "http",
+    "rest",
+    "schema",
+    "json-schema",
+    "typebox",
+    "ajv",
+    "schema-validation",
+    "type-inference",
+    "codegen",
+    "code-generation",
+    "client-generation",
+    "streaming",
+    "sse",
+    "server-sent-events",
+    "endpoint",
+    "trpc"
   ],
   "optionalDependencies": {
-    "ajsc": "7.2.0",
+    "ajsc": "^7.2.0",
+    "astro": "6.x.x || 7.x.x",
     "express": "^5.2.1",
     "hono": "^4.7.4"
   },
@@ -93,6 +116,7 @@
     "@eslint/js": "^9.17.0",
     "@types/express": "^5.0.6",
     "@types/supertest": "^7.2.0",
+    "astro": "^6.3.1",
     "eslint": "^9.17.0",
     "express": "^5.2.1",
     "hono": "^4.7.4",

package/src/implementations/http/astro/README.md

@@ -0,0 +1,89 @@
+# `ts-procedures/astro`
+
+Drop one or more pre-built Hono apps (from `HonoAPIAppBuilder`, `HonoRPCAppBuilder`, or `HonoStreamAppBuilder`) into a single Astro catch-all endpoint. Procedure handlers can read Astro's per-request data (`locals`, `cookies`, `redirect`, `params`) inside their factory-context closures.
+
+> **Requires SSR.** Your Astro project must use `output: 'server'` or `output: 'hybrid'` with `export const prerender = false` in the catch-all file. Static-prerender mode bypasses live endpoints.
+
+## Install
+
+The adapter is part of `ts-procedures`. Astro is an optional peer; install it in your Astro app:
+
+```bash
+npm install ts-procedures hono astro
+```
+
+## Quick start
+
+```ts
+// src/server/api.ts
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import { getAstroContext } from 'ts-procedures/astro'
+import { usersAPI } from './procedures/users'
+import { db } from './db'
+
+export const apiApp = new HonoAPIAppBuilder()
+  .register(usersAPI, (c) => {
+    const astro = getAstroContext(c)
+    return { db, user: astro.locals.user ?? null }
+  })
+  .build()
+```
+
+```ts
+// src/pages/api/[...rest].ts
+import { createAstroHandler } from 'ts-procedures/astro'
+import { apiApp } from '../../server/api'
+
+export const { ALL } = createAstroHandler({
+  apps: apiApp,
+  pathPrefix: '/api',
+})
+```
+
+## Config reference
+
+| Option       | Type                  | Description                                                                                  |
+| ------------ | --------------------- | -------------------------------------------------------------------------------------------- |
+| `apps`       | `Hono \| Hono[]`      | One or more built Hono apps. Order matters in first-match dispatch.                          |
+| `pathPrefix` | `string \| undefined` | Path prefix matching the Astro catch-all mount point. `/api`, `api`, `/api/` are equivalent. |
+
+## Path prefix semantics
+
+The catch-all file is at `src/pages/api/[...rest].ts`, so Astro receives requests with paths like `/api/users/123`. The Hono builder routes you registered probably use just `/users/:id`. Configuring `pathPrefix: '/api'` strips the prefix before delegating — your Hono routes don't need to repeat the prefix.
+
+| Request path     | `pathPrefix` | Inner Hono sees       |
+| ---------------- | ------------ | --------------------- |
+| `/api/users/123` | `'/api'`     | `/users/123`          |
+| `/api`           | `'/api'`     | `/`                   |
+| `/somewhere`     | `'/api'`     | (404, no app invoked) |
+| `/users/123`     | `undefined`  | `/users/123`          |
+
+The prefix match is segment-aware: `/apikey/secret` does NOT match `pathPrefix: '/api'` and will return 404.
+
+**Diagnostic:** if your routes 404 unexpectedly, the most common cause is a `pathPrefix` mismatch. The prefix MUST match the directory the catch-all file lives in. For `src/pages/api/[...rest].ts` use `pathPrefix: '/api'`; for `src/pages/v1/[...rest].ts` use `pathPrefix: '/v1'`.
+
+## Multi-app dispatch
+
+Pass an array. The adapter tries each app in order:
+
+```ts
+export const { ALL } = createAstroHandler({
+  apps: [apiApp, rpcApp, streamsApp],
+  pathPrefix: '/api',
+})
+```
+
+Dispatch rules:
+- The first response with `status !== 404` is returned.
+- A `500` from app A stops dispatch (it is treated as a real answer, not a miss).
+- Only literal 404s fall through to the next app.
+- All apps 404 → adapter returns its own `Response(null, { status: 404 })`.
+
+## Streams
+
+`HonoStreamAppBuilder` returns a `Response` with a `ReadableStream` body. Astro SSR forwards that body verbatim — no additional configuration. Client disconnects abort `ctx.signal` inside the stream handler.
+
+## What's NOT included
+
+- Express RPC support (Express uses Node `req`/`res`, not Web Fetch).
+- DocRegistry coupling — wire `DocRegistry` against the same builders separately for client codegen.

package/src/implementations/http/astro/astro-context.ts

@@ -0,0 +1,34 @@
+import type { APIContext } from 'astro'
+import type { Context as HonoContext } from 'hono'
+
+const astroContextMap = new WeakMap<Request, APIContext>()
+
+/**
+ * Internal — stash the Astro APIContext for the Request that Hono will receive.
+ *
+ * The key MUST be the post-rewrite Request (the one passed to `app.fetch`),
+ * because that is what Hono exposes via `c.req.raw` and what `getAstroContext`
+ * reads back. When no `pathPrefix` rewrite happens, this is the same Request
+ * that Astro originally invoked the adapter with.
+ */
+export function setAstroContext(request: Request, apiContext: APIContext): void {
+  astroContextMap.set(request, apiContext)
+}
+
+/**
+ * Reads Astro's APIContext from inside a Hono factory-context closure.
+ *
+ * Throws when the request is not in scope — typically because the Hono app
+ * is being served outside the Astro adapter (e.g., bound to a Node listener
+ * or via a different adapter) and the closure was invoked there.
+ */
+export function getAstroContext(c: HonoContext): APIContext {
+  const ctx = astroContextMap.get(c.req.raw)
+  if (!ctx) {
+    throw new Error(
+      'getAstroContext was called outside an Astro request scope. ' +
+        'Ensure this Hono app is being served via createAstroHandler when this closure runs.'
+    )
+  }
+  return ctx
+}

package/src/implementations/http/astro/create-handler.ts

@@ -0,0 +1,59 @@
+import type { Hono } from 'hono'
+import type { APIRoute } from 'astro'
+import { setAstroContext } from './astro-context.js'
+import { stripPrefix } from './rewrite-request.js'
+
+export type AstroAdapterConfig = {
+  /** One or more built Hono apps. Order matters in first-match dispatch. */
+  apps: Hono | Hono[]
+  /**
+   * Path prefix matching the Astro catch-all mount point.
+   * For src/pages/api/[...rest].ts use '/api'. The adapter strips this
+   * before delegating, so Hono routes do NOT need to repeat the prefix.
+   *
+   * Normalization: leading and trailing slashes are optional; '/api',
+   * 'api', and '/api/' are equivalent. Undefined or '/' means no rewrite.
+   */
+  pathPrefix?: string
+}
+
+export type AstroHandlers = {
+  ALL: APIRoute
+  GET: APIRoute
+  POST: APIRoute
+  PUT: APIRoute
+  PATCH: APIRoute
+  DELETE: APIRoute
+  HEAD: APIRoute
+  OPTIONS: APIRoute
+}
+
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'] as const
+
+export function createAstroHandler(config: AstroAdapterConfig): AstroHandlers {
+  const apps = Array.isArray(config.apps) ? config.apps : [config.apps]
+
+  if (apps.length === 0) {
+    throw new Error('createAstroHandler: `apps` must contain at least one Hono app.')
+  }
+
+  const ALL: APIRoute = async (apiContext) => {
+    const rewritten = stripPrefix(apiContext.request, config.pathPrefix)
+    if (rewritten === null) {
+      return new Response(null, { status: 404 })
+    }
+    setAstroContext(rewritten, apiContext)
+
+    for (const app of apps) {
+      const res = await app.fetch(rewritten)
+      if (res.status !== 404) return res
+    }
+    return new Response(null, { status: 404 })
+  }
+
+  const handlers = { ALL } as AstroHandlers
+  for (const method of HTTP_METHODS) {
+    handlers[method] = ALL
+  }
+  return handlers
+}