ts-procedures 10.1.2 → 10.2.1

package/build/stack-utils.js

@@ -0,0 +1,95 @@
+/**
+ * Internal ts-procedures files that should be skipped when finding user code.
+ * Only skip the core library files, not test files or user code.
+ */
+const INTERNAL_FILES = [
+    '/index.ts',
+    '/index.js',
+    '/errors.ts',
+    '/errors.js',
+    '/stack-utils.ts',
+    '/stack-utils.js',
+    '/compute-schema.ts',
+    '/compute-schema.js',
+    '/parser.ts',
+    '/parser.js',
+];
+/**
+ * Captures the stack trace at the call site and extracts the definition location.
+ * Finds the first stack frame outside of ts-procedures internal files.
+ */
+export function captureDefinitionInfo() {
+    const err = new Error();
+    const stack = err.stack;
+    if (!stack) {
+        return {};
+    }
+    const lines = stack.split('\n');
+    // Find the first frame that's not from ts-procedures internals
+    // Skip the first line (Error message) and frames from this module
+    let userFrame;
+    for (let i = 1; i < lines.length; i++) {
+        const rawLine = lines[i];
+        if (!rawLine)
+            continue;
+        const line = rawLine.trim();
+        // Skip empty or invalid frames
+        if (!line.startsWith('at ')) {
+            continue;
+        }
+        // Skip frames from ts-procedures internal source files
+        const isInternalFile = INTERNAL_FILES.some(file => line.includes(file));
+        if (isInternalFile) {
+            continue;
+        }
+        // Skip frames from ts-procedures in node_modules (when used as a dependency)
+        if (line.includes('/node_modules/ts-procedures/') || line.includes('\\node_modules\\ts-procedures\\')) {
+            continue;
+        }
+        // Skip internal node frames
+        if (line.includes('node:') || line.startsWith('at Module.') || line.startsWith('at Object.<anonymous> (node:')) {
+            continue;
+        }
+        userFrame = line;
+        break;
+    }
+    if (!userFrame) {
+        return { definitionStack: stack };
+    }
+    const definedAt = parseStackFrame(userFrame);
+    return {
+        definedAt,
+        definitionStack: stack,
+    };
+}
+/**
+ * Parses a V8 stack frame line to extract file, line, and column info.
+ * Handles formats like:
+ * - "at Object.<anonymous> (/path/to/file.ts:10:5)"
+ * - "at functionName (/path/to/file.ts:10:5)"
+ * - "at /path/to/file.ts:10:5"
+ */
+function parseStackFrame(frame) {
+    // Match patterns like "(path:line:column)" or just "path:line:column"
+    const match = frame.match(/\(([^)]+):(\d+):(\d+)\)$/) || frame.match(/at ([^:]+):(\d+):(\d+)$/);
+    if (match && match[1] && match[2] && match[3]) {
+        return {
+            file: match[1],
+            line: parseInt(match[2], 10),
+            column: parseInt(match[3], 10),
+            raw: frame,
+        };
+    }
+    return undefined;
+}
+/**
+ * Formats definition info for appending to error stacks.
+ */
+export function formatDefinitionInfo(info, procedureName) {
+    if (!info.definedAt) {
+        return undefined;
+    }
+    const { file, line, column } = info.definedAt;
+    return `\n--- Procedure "${procedureName}" defined at ---\n    at ${file}:${line}:${column}`;
+}
+//# sourceMappingURL=stack-utils.js.map

package/build/stack-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-utils.js","sourceRoot":"","sources":["../src/stack-utils.ts"],"names":[],"mappings":"AAkBA;;;GAGG;AACH,MAAM,cAAc,GAAG;IACrB,WAAW;IACX,WAAW;IACX,YAAY;IACZ,YAAY;IACZ,iBAAiB;IACjB,iBAAiB;IACjB,oBAAoB;IACpB,oBAAoB;IACpB,YAAY;IACZ,YAAY;CACb,CAAA;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,GAAG,GAAG,IAAI,KAAK,EAAE,CAAA;IACvB,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAA;IAEvB,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,CAAA;IACX,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAE/B,+DAA+D;IAC/D,kEAAkE;IAClE,IAAI,SAA6B,CAAA;IAEjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;QACxB,IAAI,CAAC,OAAO;YAAE,SAAQ;QACtB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAA;QAE3B,+BAA+B;QAC/B,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,SAAQ;QACV,CAAC;QAED,uDAAuD;QACvD,MAAM,cAAc,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAA;QACvE,IAAI,cAAc,EAAE,CAAC;YACnB,SAAQ;QACV,CAAC;QAED,6EAA6E;QAC7E,IAAI,IAAI,CAAC,QAAQ,CAAC,8BAA8B,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,iCAAiC,CAAC,EAAE,CAAC;YACtG,SAAQ;QACV,CAAC;QAED,4BAA4B;QAC5B,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,8BAA8B,CAAC,EAAE,CAAC;YAC/G,SAAQ;QACV,CAAC;QAED,SAAS,GAAG,IAAI,CAAA;QAChB,MAAK;IACP,CAAC;IAED,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,CAAA;IACnC,CAAC;IAED,MAAM,SAAS,GAAG,eAAe,CAAC,SAAS,CAAC,CAAA;IAE5C,OAAO;QACL,SAAS;QACT,eAAe,EAAE,KAAK;KACvB,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,KAAa;IACpC,sEAAsE;IACtE,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,0BAA0B,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAA;IAE/F,IAAI,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,OAAO;YACL,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;YACd,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YAC5B,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YAC9B,GAAG,EAAE,KAAK;SACX,CAAA;IACH,CAAC;IAED,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAoB,EAAE,aAAqB;IAC9E,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;QACpB,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAA;IAC7C,OAAO,oBAAoB,aAAa,4BAA4B,IAAI,IAAI,IAAI,IAAI,MAAM,EAAE,CAAA;AAC9F,CAAC"}

package/build/stack-utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/stack-utils.test.js

@@ -0,0 +1,80 @@
+import { describe, expect, test } from 'vitest';
+import { captureDefinitionInfo, formatDefinitionInfo } from './stack-utils.js';
+describe('Stack Utils', () => {
+    describe('captureDefinitionInfo', () => {
+        test('returns definition info with definedAt', () => {
+            const info = captureDefinitionInfo();
+            // Should capture the call site in this test file
+            expect(info).toBeDefined();
+            expect(info.definitionStack).toBeDefined();
+            expect(typeof info.definitionStack).toBe('string');
+        });
+        test('definedAt contains file, line, column when available', () => {
+            const info = captureDefinitionInfo();
+            // The definedAt should be present since we're calling from user code (test file)
+            if (info.definedAt) {
+                expect(info.definedAt.file).toBeDefined();
+                expect(typeof info.definedAt.file).toBe('string');
+                expect(info.definedAt.line).toBeDefined();
+                expect(typeof info.definedAt.line).toBe('number');
+                expect(info.definedAt.line).toBeGreaterThan(0);
+                expect(info.definedAt.column).toBeDefined();
+                expect(typeof info.definedAt.column).toBe('number');
+                expect(info.definedAt.column).toBeGreaterThan(0);
+                expect(info.definedAt.raw).toBeDefined();
+                expect(typeof info.definedAt.raw).toBe('string');
+            }
+        });
+        test('definitionStack contains Error stack trace', () => {
+            const info = captureDefinitionInfo();
+            expect(info.definitionStack).toContain('Error');
+            expect(info.definitionStack).toContain('at ');
+        });
+    });
+    describe('formatDefinitionInfo', () => {
+        test('returns undefined when definedAt is not present', () => {
+            const info = {};
+            const result = formatDefinitionInfo(info, 'TestProcedure');
+            expect(result).toBeUndefined();
+        });
+        test('returns formatted string when definedAt is present', () => {
+            const info = {
+                definedAt: {
+                    file: '/app/procedures/test.ts',
+                    line: 42,
+                    column: 5,
+                    raw: 'at Object.<anonymous> (/app/procedures/test.ts:42:5)',
+                },
+            };
+            const result = formatDefinitionInfo(info, 'TestProcedure');
+            expect(result).toBeDefined();
+            expect(result).toContain('--- Procedure "TestProcedure" defined at ---');
+            expect(result).toContain('/app/procedures/test.ts:42:5');
+        });
+        test('includes procedure name in formatted output', () => {
+            const info = {
+                definedAt: {
+                    file: '/path/to/file.ts',
+                    line: 10,
+                    column: 3,
+                    raw: 'at /path/to/file.ts:10:3',
+                },
+            };
+            const result = formatDefinitionInfo(info, 'MyCustomProcedure');
+            expect(result).toContain('"MyCustomProcedure"');
+        });
+    });
+    describe('integration with procedure creation', () => {
+        test('captures location from calling code', () => {
+            // Helper to simulate what happens in Create()
+            function simulateCreate() {
+                return captureDefinitionInfo();
+            }
+            const info = simulateCreate();
+            // Should have captured the location of the simulateCreate() call
+            expect(info).toBeDefined();
+            expect(info.definitionStack).toBeDefined();
+        });
+    });
+});
+//# sourceMappingURL=stack-utils.test.js.map

package/build/stack-utils.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-utils.test.js","sourceRoot":"","sources":["../src/stack-utils.test.ts"],"names":[],"mappings":"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"}

package/docs/ai-agent-setup.md

@@ -2,7 +2,7 @@
 
 # AI Agent Setup
 
-ts-procedures ships with built-in AI assistant configuration for **Claude Code**, **Cursor**, and **GitHub Copilot**. This gives AI tools framework-aware context when writing ts-procedures code in your project.
+ts-procedures ships a single, spec-compliant **Agent Skill** that gives AI coding tools framework-aware context when writing ts-procedures code in your project. It follows the open [Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) / `SKILL.md` standard, so a wide range of tools — Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and others — read the same files.
 
 ## Quick Setup
 
@@ -10,52 +10,44 @@ ts-procedures ships with built-in AI assistant configuration for **Claude Code**
 npx ts-procedures-setup
 ```
 
-This installs rules for all supported AI tools. You can also target specific tools:
-
-```bash
-npx ts-procedures-setup claude       # Claude Code only
-npx ts-procedures-setup cursor       # Cursor only
-npx ts-procedures-setup copilot      # GitHub Copilot only
-```
+This installs the skill into the standard agent directories. There are no per-tool targets — one skill works everywhere.
 
 ## What Gets Installed
 
-| Tool | Files | Auto-updates? |
-|------|-------|---------------|
-| **Claude Code** | `.claude/skills/ts-procedures/` (single skill — reference + `review`/`scaffold` modes + Kotlin/Swift codegen), `.claude/agents/ts-procedures-architect.md` | Yes |
-| **Cursor** | `.cursorrules` (marker-based section) | Yes |
-| **GitHub Copilot** | `.github/copilot-instructions.md` (marker-based section) | Yes |
+The same skill is copied into two standard locations:
+
+| Path | Read by |
+|------|---------|
+| `.agents/skills/ts-procedures/` | The cross-tool standard — 30+ agents (Codex, Cursor, GitHub Copilot, Gemini CLI, …) scan `.agents/skills` from the working directory up to the repo root |
+| `.claude/skills/ts-procedures/` | Claude Code's native project skills location |
+
+The skill bundles the framework reference plus `review` / `scaffold` modes (checklist + templates) and Kotlin/Swift client-codegen reference, using progressive disclosure so tools load detail only as needed.
 
 ## Auto-Updates
 
-After initial setup, rules are automatically refreshed on every `npm install` or `npm update`. When ts-procedures publishes a new version, your AI tools get the latest framework guidance without any manual steps.
+After initial setup, the skill is automatically refreshed on every `npm install` or `npm update` via the package's postinstall hook. When ts-procedures publishes a new version, your AI tools get the latest framework guidance with no manual steps. Auto-update is opt-in: it only runs once the skill has been installed at least once.
 
-## Claude Code Features
+## Skill Modes
 
-Once installed, Claude Code gets:
+Once installed, the `ts-procedures` skill exposes three modes selected by the first word of its arguments:
 
-- **Unified `ts-procedures` skill** — one skill with three modes selected by the first word of its arguments:
-  - *Reference* (no argument) — core API, schema system, error handling, decision framework, plus Kotlin/Swift client-codegen reference (auto-discovered by Claude Code)
-  - *Scaffold* — `/ts-procedures scaffold <type> <Name>` generates procedures, streams, and HTTP setups with correct patterns
-  - *Review* — `/ts-procedures review <path>` checks code against a 60+ item checklist
-- **Architecture agent** — `ts-procedures-architect` helps plan procedure structure, schema design, and HTTP implementation choices
+- *Reference* (no argument) — core API, schema system, error handling, decision framework, plus Kotlin/Swift client-codegen reference (auto-discovered by the agent)
+- *Scaffold* — `scaffold <type> <Name>` generates procedures, streams, and HTTP setups with correct patterns
+- *Review* — `review <path>` checks code against a 60+ item checklist
 
 ## CLI Options
 
 ```bash
-npx ts-procedures-setup --force      # Overwrite without prompting
 npx ts-procedures-setup --dry-run    # Preview what would be created/updated
 npx ts-procedures-setup --check      # Exit with code 1 if files are outdated (for CI)
 ```
 
 ## Gitignore
 
-The `.claude/` files are auto-generated and regenerated on `npm install`. You can add them to `.gitignore`:
+The installed skill is generated and regenerated on `npm install`. You can add the install roots to `.gitignore`:
 
 ```gitignore
-# Auto-generated AI agent rules (regenerated on npm install)
+# Auto-generated AI agent skill (regenerated on npm install)
+.agents/skills/ts-procedures/
 .claude/skills/ts-procedures/
-.claude/agents/ts-procedures-*.md
 ```
-
-Cursor and Copilot files use marker-based sections that coexist with your own rules, so they should typically be committed.

package/docs/client-error-handling.md

@@ -414,7 +414,7 @@ A framework-level "skip `onError` for `.safe()`" toggle was deliberately deferre
 
 - Codegen setup, per-call options, hooks, and typed-error wiring: [`docs/client-and-codegen.md`](./client-and-codegen.md)
 - Client types and interfaces: package source under `src/client/` (`types.ts`, `errors.ts`, `error-dispatch.ts`)
-- Agent config patterns and anti-patterns: [`agent_config/claude-code/skills/ts-procedures/patterns.md`](../agent_config/claude-code/skills/ts-procedures/patterns.md) and [`anti-patterns.md`](../agent_config/claude-code/skills/ts-procedures/anti-patterns.md)
+- Agent config patterns and anti-patterns: [`agent_config/skills/ts-procedures/patterns.md`](../agent_config/skills/ts-procedures/patterns.md) and [`anti-patterns.md`](../agent_config/skills/ts-procedures/anti-patterns.md)
 
 ---
 

package/docs/core.md

@@ -14,6 +14,7 @@ Procedures<TContext, TExtendedConfig>(options?: {
     schema?: { adapters?: SchemaAdapter[] }
     http?: { pathPrefix?: string; scope?: string }
     onCreate?: (procedure: AnyProcedureRegistration<TContext, TExtendedConfig>) => void
+    middleware?: FactoryMiddleware<TContext>[]   // runs with final ctx + input for all procedures
 })
 ```
 
@@ -25,9 +26,12 @@ Procedures<TContext, TExtendedConfig>(options?: {
 | `options.schema.adapters` | Plug in additional schema libraries via the `SchemaAdapter` interface. TypeBox is built in. See [Other Schema Libraries](#other-schema-libraries--schemaadapter). |
 | `options.http` | Factory-level defaults for `CreateHttp` / `CreateHttpStream`: `pathPrefix` is prepended to every route's `path` at registration time (part of the route's identity, unlike a server builder's mount prefix), and `scope` is the default codegen scope for routes that don't set one. Per-route config always wins. |
 | `options.onCreate` | Optional callback invoked when each procedure is registered (runtime)      |
+| `options.middleware` | Array of middleware functions that run for every procedure on this factory. They receive the final resolved `ctx` (your `TContext` + `error()` + `signal`) plus the validated input, and can inspect ("parse the incoming call"), augment via `next({ ctx?, input? })`, or short-circuit. See `FactoryMiddleware`. |
 
 **Returns:** `Create`, `CreateStream`, `CreateHttp`, `CreateHttpStream`, plus introspection helpers `getProcedures()`, `getProcedure(name)`, `removeProcedure(name)`, and `clear()`.
 
+Factory `middleware` runs with the resolved context + input for every procedure defined through the factory (transport-independent, useful for authorization that needs `ctx` + call data). Builder-level middleware lives on `HonoAppBuilder` (see [HTTP Integrations](./http-integrations.md)).
+
 ## Create Function
 
 The `Create` function defines individual procedures:
@@ -74,6 +78,7 @@ const { UpdateUser } = CreateHttp(
 **Rules:**
 - `schema.req` and `schema.params` are **mutually exclusive** — `schema.params` belongs to RPC procedures (`Create`/`CreateStream`), `schema.req` to HTTP procedures. Using `schema.params` on `CreateHttp` throws `ProcedureRegistrationError`.
 - Valid channels are `pathParams`, `query`, `body`, and `headers`; each is validated independently with per-channel error messages.
+- The channel names are provided by `THttpReqInput` (and its alias `APIInput` from `ts-procedures/http`) so that IDEs offer autocomplete when writing `schema: { req: { ... } }`. Use `satisfies APIInput` for additional typo protection on the keys.
 - `schema.res.body` documents the response body (drives codegen); omit `schema.res` entirely for 204-style no-content routes.
 - Factory-level `http.pathPrefix` / `http.scope` defaults apply; per-route config wins.
 - For HTTP streaming routes, use `CreateHttpStream` — same `schema.req` channels plus `schema.yield`.
@@ -500,6 +505,7 @@ Creates a procedure factory.
 - `options.schema.adapters` - Additional schema-library adapters (see [Other Schema Libraries](#other-schema-libraries--schemaadapter))
 - `options.http` - Factory-level `pathPrefix` / `scope` defaults for `CreateHttp` / `CreateHttpStream`
 - `options.onCreate` - Callback invoked when each procedure is registered
+- `options.middleware` - Factory-level middleware with access to final `ctx` + input (for authz, enrichment, call parsing, etc.)
 
 **Returns:**
 - `Create` / `CreateStream` / `CreateHttp` / `CreateHttpStream` - Functions to define procedures
@@ -560,6 +566,8 @@ import type {
   TNoContextProvided,
   HttpMethod,
   HttpReturn,
+  FactoryMiddleware,                // for Procedures({ middleware }) — receives final ctx + input
+
 
   // Errors
   ProcedureErrorKind,               // 'procedure' | 'validation' | 'yield-validation' | 'registration'

package/docs/http-integrations.md

@@ -178,7 +178,7 @@ new HonoAppBuilder({
 }).register(procs, /* ... */).build()
 ```
 
-(Need to route different error classes to different status codes? Use the taxonomy — that's exactly what it's designed for. Hand-writing `instanceof` ladders inside `onError` is [anti-pattern #20](../agent_config/claude-code/skills/ts-procedures/anti-patterns.md).)
+(Need to route different error classes to different status codes? Use the taxonomy — that's exactly what it's designed for. Hand-writing `instanceof` ladders inside `onError` is [anti-pattern #20](../agent_config/skills/ts-procedures/anti-patterns.md).)
 
 `HonoAppBuilder`'s `onError` signature: `(procedure, c: Context, error) => Response | Promise<Response>` — for streaming procedures, pre-stream only.
 
@@ -219,6 +219,46 @@ new HonoAppBuilder({
 
 The observer is awaited before the response is sent, and any error it throws is swallowed (logged to the console) so a broken instrumentation hook can't corrupt the primary flow.
 
+### Middleware (auth, tenancy, guards)
+
+Middleware can be declared at two levels that compose naturally.
+
+**At the `HonoAppBuilder` (serving / transport level):**
+
+- `new HonoAppBuilder({ middleware: [mw, ...] })`
+- `builder.use(mw)` or `builder.use('/specific/*', mw)` (chainable)
+- Per registration: `.register(factory, ctx, { middleware: [mw], context?: extraLayer })`
+
+Signature: `(c: Context, next) => Response | Promise<Response|void> | void`.
+
+**At the `Procedures()` factory (definition / business-logic level):**
+
+```ts
+const Protected = Procedures<MyCtx>({
+  middleware: [({ ctx, input, next }) => { ... }]
+})
+```
+
+These run *after* context resolution but before your handler. They receive the final `ctx` (same one the handler sees) + the validated `input`, so you can "parse the incoming call", perform authz using `ctx.user` + `input`, or augment via `next({ ctx?, input? })`. Defined as `FactoryMiddleware<TContext>`.
+
+See the `Procedures()` options in [Core](./core.md).
+
+Use builder middleware for raw request concerns and factory middleware for ctx-aware logic. Errors from either flow through your taxonomy / `onError`.
+
+The builder example below shows the two layers working together:
+
+```ts
+const app = new HonoAppBuilder({ pathPrefix: '/api', middleware: [authenticate] })
+  .register(Protected, (c) => ({
+    tenant: c.get('tenant'),
+    user: getUser(c),
+  }))
+  .register(Public, (c) => ({ requestId: c.req.header('x-rid') }))
+  .build()
+```
+
+`context` layers (via `register(..., { context })` or arrays) are resolved left-to-right via `composeContextInits`. Middleware declared at either level flows errors through `onRequestError` → taxonomy → `onError`.
+
 ### Dispatch order inside each builder's catch block
 
 1. **`onRequestError`** (observer) — awaited, can't alter dispatch or response
@@ -311,33 +351,7 @@ const docs = new DocRegistry({ errors: appErrors, basePath: '/api' })
 
 `http-stream` route docs include the route's `yield` and `res.headers` schemas. (Through v8, live envelopes silently dropped these for `http-stream` routes, so generated clients lost those types unless the envelope was hand-authored; v9 fixed this.)
 
-### Envelope versioning
-
-Every envelope carries two top-level metadata fields so downstream consumers (docs viewers, codegen, dashboards) can reason about format compatibility:
-
-```jsonc
-{
-  "specVersion": 1,             // wire-format version of the envelope itself
-  "generatorVersion": "10.0.0", // ts-procedures package version that produced it
-  "basePath": "/api",
-  "headers": [],
-  "errors": [ /* ... */ ],
-  "routes": [ /* ... */ ]
-}
-```
-
-- **`specVersion`** is a small monotonic integer, bumped **only** when the envelope shape changes in a way parsers must react to — never on ordinary package releases. Branch on it. An envelope with no `specVersion` predates the field and must be treated as `1`. The current value is exported as `DOC_ENVELOPE_SPEC_VERSION` from `ts-procedures` and `ts-procedures/server`.
-- **`generatorVersion`** is the producing package version (`DOC_ENVELOPE_GENERATOR_VERSION`, exported from `ts-procedures/server`). It is informational only — for telemetry and "which release served this?" — and must **not** drive parse-compatibility decisions, since it churns on every release regardless of the envelope format.
-
-If you'd rather not advertise the exact package version on a public docs endpoint, strip it with the `transform` hook:
-
-```typescript
-app.get('/docs', (c) => c.json(
-  builder.toDocEnvelope({ transform: ({ generatorVersion, ...env }) => env }),
-))
-```
-
-The `DocRegistry` output is the input for [Client Code Generation](./client-and-codegen.md). Building a third-party docs viewer or other tool that consumes the served envelope? The full wire contract — every field, per-kind shapes, and a validatable JSON Schema — is in [DocEnvelope Spec](./doc-envelope-spec-v1.md) (`doc-envelope-v1.schema.json`).
+The `DocRegistry` output is the input for [Client Code Generation](./client-and-codegen.md).
 
 ## Type Exports
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "10.1.2",
+  "version": "10.2.1",
   "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",
@@ -76,15 +76,15 @@
     "typebox": "^1.0.30"
   },
   "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@typescript-eslint/eslint-plugin": "^8.53.0",
-    "@typescript-eslint/parser": "^8.53.0",
-    "astro": "^7.0.2",
-    "eslint": "^10.5.0",
-    "globals": "^17.7.0",
+    "@eslint/js": "^9.17.0",
+    "astro": "^6.3.1",
+    "eslint": "^9.17.0",
+    "globals": "^15.0.0",
     "hono": "^4.7.4",
-    "typescript": "^6.0.3",
+    "typescript": "^5.7.0",
     "typescript-eslint": "^8.53.0",
+    "@typescript-eslint/eslint-plugin": "^8.53.0",
+    "@typescript-eslint/parser": "^8.53.0",
     "vitest": "^4.0.18"
   }
 }

package/src/adapters/astro/README.md

@@ -86,3 +86,5 @@ Dispatch rules:
 ## What's NOT included
 
 - DocRegistry coupling — wire `DocRegistry` against the same builders separately for client codegen.
+
+Middleware, guards, and context layering are configured on the `HonoAppBuilder` instances you pass in (`.use()`, `middleware`, per-`register` options). The Astro adapter just dispatches the pre-built apps.

package/src/adapters/hono/envelope-parity.test.ts

@@ -3,10 +3,8 @@ import { dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 import { Type } from 'typebox'
-import pkg from '../../../package.json' with { type: 'json' }
 import { Procedures } from '../../core/procedures.js'
 import { HonoAppBuilder, defineErrorTaxonomy } from './index.js'
-import { DOC_ENVELOPE_SPEC_VERSION } from '../../server/spec-version.js'
 import type { RPCConfig } from '../../server/types.js'
 
 /**
@@ -18,15 +16,12 @@ import type { RPCConfig } from '../../server/types.js'
  * The envelope is codegen's input; if this test fails, generated client output
  * WILL drift.
  *
- * TWO documented deviations from the raw v8 capture:
- *   1. v8's CreateHttpStream dropped the `yield` schema (and `res.headers`) from
- *      http-stream route docs — the registration stored `yieldType` while the
- *      doc builder read `yield`. v9 fixes that, so the fixture's TailUser route
- *      was patched to include the `yield` schema the builder now emits.
- *   2. v9 adds envelope-level `specVersion`/`generatorVersion` metadata that v8
- *      never emitted. These are asserted explicitly below, then stripped before
- *      the deep-equal so the rest stays byte-for-byte with the v8 capture.
- * Everything else is the untouched v8 capture.
+ * ONE documented deviation from the raw v8 capture: v8's CreateHttpStream
+ * dropped the `yield` schema (and `res.headers`) from http-stream route docs —
+ * the registration stored `yieldType` while the doc builder read `yield`. v9
+ * fixes that, so the fixture's TailUser route was patched to include the
+ * `yield` schema the builder now (correctly) emits. Everything else is the
+ * untouched v8 capture.
  */
 class TeapotError extends Error {}
 
@@ -126,13 +121,6 @@ describe('DocEnvelope parity with v8.6.0', () => {
     const expected = JSON.parse(await readFile(fixturePath, 'utf-8'))
     const actual = JSON.parse(JSON.stringify(builder.toDocEnvelope()))
 
-    // Deviation #2: assert the new v9 envelope metadata, then strip it so the
-    // remaining shape matches the untouched v8 capture.
-    expect(actual.specVersion).toBe(DOC_ENVELOPE_SPEC_VERSION)
-    expect(actual.generatorVersion).toBe(pkg.version)
-    delete actual.specVersion
-    delete actual.generatorVersion
-
     expect(actual).toEqual(expected)
   })
 })

package/src/adapters/hono/handlers/http-stream.ts

@@ -7,9 +7,9 @@ import { resolveFactoryContext } from '../../../server/context.js'
 import { extractReqChannels } from '../../../server/request/params.js'
 import { parseQueryNative } from '../../../server/request/query.js'
 import { SseEventSequencer } from '../../../server/sse.js'
-import { honoRequestSource, respondToDispatch } from '../request.js'
+import { honoRequestSource, respondToDispatch, runMiddlewareList } from '../request.js'
 import { midStreamErrorConfig, preStreamErrorConfig } from '../types.js'
-import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem } from '../types.js'
+import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem, HonoRequestMiddleware } from '../types.js'
 
 export function installHttpStreamRoute(params: {
   app: Hono
@@ -17,8 +17,9 @@ export function installHttpStreamRoute(params: {
   factoryItem: HonoFactoryItem
   cfg: HonoAppBuilderConfig
   docs: DocAccumulator
+  builderMiddleware?: HonoRequestMiddleware[]
 }): void {
-  const { app, procedure, factoryItem, cfg, docs } = params
+  const { app, procedure, factoryItem, cfg, docs, builderMiddleware } = params
   const queryParser = cfg.api?.queryParser ?? parseQueryNative
 
   const route = buildHttpStreamRouteDoc(procedure, cfg.pathPrefix, factoryItem.extendProcedureDoc as any)
@@ -26,8 +27,16 @@ export function installHttpStreamRoute(params: {
 
   const reqSchema = procedure.config.schema?.req
 
+  const combinedMw = [
+    ...(builderMiddleware ?? []),
+    ...(factoryItem.middleware ?? []),
+  ]
+
   app.on(procedure.config.method.toUpperCase(), route.fullPath, async (c: Context) => {
     try {
+      const early = await runMiddlewareList(c, combinedMw)
+      if (early) return early
+
       const context = await resolveFactoryContext(factoryItem.factoryContext, c)
 
       const reqParams = reqSchema

package/src/adapters/hono/handlers/http.ts

@@ -5,9 +5,9 @@ import { buildHttpRouteDoc } from '../../../server/docs/http-doc.js'
 import { resolveFactoryContext } from '../../../server/context.js'
 import { defaultSuccessStatus, extractReqChannels } from '../../../server/request/params.js'
 import { parseQueryNative } from '../../../server/request/query.js'
-import { honoRequestSource, respondToDispatch } from '../request.js'
+import { honoRequestSource, respondToDispatch, runMiddlewareList } from '../request.js'
 import { preStreamErrorConfig } from '../types.js'
-import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem } from '../types.js'
+import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem, HonoRequestMiddleware } from '../types.js'
 
 export function installHttpRoute(params: {
   app: Hono
@@ -15,8 +15,9 @@ export function installHttpRoute(params: {
   factoryItem: HonoFactoryItem
   cfg: HonoAppBuilderConfig
   docs: DocAccumulator
+  builderMiddleware?: HonoRequestMiddleware[]
 }): void {
-  const { app, procedure, factoryItem, cfg, docs } = params
+  const { app, procedure, factoryItem, cfg, docs, builderMiddleware } = params
   const queryParser = cfg.api?.queryParser ?? parseQueryNative
 
   const route = buildHttpRouteDoc(procedure, cfg.pathPrefix, factoryItem.extendProcedureDoc as any)
@@ -25,8 +26,16 @@ export function installHttpRoute(params: {
   const successStatus = procedure.config.successStatus ?? defaultSuccessStatus(procedure.config.method)
   const reqSchema = procedure.config.schema?.req
 
+  const combinedMw = [
+    ...(builderMiddleware ?? []),
+    ...(factoryItem.middleware ?? []),
+  ]
+
   app.on(procedure.config.method.toUpperCase(), route.fullPath, async (c: Context) => {
     try {
+      const early = await runMiddlewareList(c, combinedMw)
+      if (early) return early
+
       const context = await resolveFactoryContext(factoryItem.factoryContext, c)
 
       const reqParams = reqSchema

package/src/adapters/hono/handlers/rpc.ts

@@ -4,9 +4,9 @@ import type { RPCConfig } from '../../../server/types.js'
 import { dispatchPreStreamError } from '../../../server/errors/dispatch.js'
 import { buildRpcRouteDoc } from '../../../server/docs/rpc-doc.js'
 import { resolveFactoryContext } from '../../../server/context.js'
-import { respondToDispatch } from '../request.js'
+import { respondToDispatch, runMiddlewareList } from '../request.js'
 import { preStreamErrorConfig } from '../types.js'
-import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem } from '../types.js'
+import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem, HonoRequestMiddleware } from '../types.js'
 
 export function installRpcRoute(params: {
   app: Hono
@@ -14,14 +14,23 @@ export function installRpcRoute(params: {
   factoryItem: HonoFactoryItem
   cfg: HonoAppBuilderConfig
   docs: DocAccumulator
+  builderMiddleware?: HonoRequestMiddleware[]
 }): void {
-  const { app, procedure, factoryItem, cfg, docs } = params
+  const { app, procedure, factoryItem, cfg, docs, builderMiddleware } = params
 
   const route = buildRpcRouteDoc(procedure, cfg.pathPrefix, factoryItem.extendProcedureDoc as any)
   docs.push(route)
 
+  const combinedMw = [
+    ...(builderMiddleware ?? []),
+    ...(factoryItem.middleware ?? []),
+  ]
+
   app.post(route.path, async (c: Context) => {
     try {
+      const early = await runMiddlewareList(c, combinedMw)
+      if (early) return early
+
       const context = await resolveFactoryContext(factoryItem.factoryContext, c)
       const body = await c.req.json().catch(() => ({}))
       const result = await procedure.handler({ ...context, signal: c.req.raw.signal }, body)