ts-procedures 10.2.0 → 10.2.2

package/src/codegen/emit-errors.integration.test.ts

@@ -91,7 +91,7 @@ describe('generated _errors.ts — runtime behavior', () => {
         const err = e as { stdout?: Buffer; stderr?: Buffer }
         const stdout = err.stdout?.toString() ?? ''
         const stderr = err.stderr?.toString() ?? ''
-        throw new Error(`tsc failed in ${outDir}:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`)
+        throw new Error(`tsc failed in ${outDir}:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`, { cause: e })
       }
 
       // Dynamic import of the compiled output.
@@ -164,7 +164,7 @@ describe('generated _errors.ts — runtime behavior', () => {
         const err = e as { stdout?: Buffer; stderr?: Buffer }
         const stdout = err.stdout?.toString() ?? ''
         const stderr = err.stderr?.toString() ?? ''
-        throw new Error(`tsc failed in ${outDir}:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`)
+        throw new Error(`tsc failed in ${outDir}:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`, { cause: e })
       }
 
       const errorsUrl = `file://${join(outDir, 'out', '_errors.js')}`

package/src/codegen/resolve-envelope.ts

@@ -21,7 +21,7 @@ export async function resolveEnvelope(input: ResolveInput): Promise<DocEnvelope>
       response = await fetch(input.url)
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
-      throw new Error(`[ts-procedures-codegen] Failed to connect to ${input.url}: ${msg}`)
+      throw new Error(`[ts-procedures-codegen] Failed to connect to ${input.url}: ${msg}`, { cause: err })
     }
     if (!response.ok) {
       throw new Error(`[ts-procedures-codegen] ${input.url} returned HTTP ${response.status} ${response.statusText}`)

package/src/codegen/test-helpers/run-tsc.ts

@@ -51,6 +51,7 @@ export function runTsc(args: {
     const combined = [stdout, stderr].filter(Boolean).join('\n').trim()
     throw new Error(
       `[runTsc] tsc failed for ${tsconfigPath}:\n${combined || (e.message ?? '(no output)')}`,
+      { cause: err },
     )
   }
 }

package/src/exports.surface.test.ts

@@ -0,0 +1,134 @@
+import { dirname, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import ts from 'typescript'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * PUBLIC-SURFACE PORTABILITY GUARD.
+ *
+ * Every type that appears in the *inferred* return/value type of a public API
+ * (e.g. `Procedures(...)`, the four creators, the Hono builder) must be
+ * re-exported from one of the package's public entry points. If it is only
+ * exported from an internal module, a downstream app that writes
+ * `export const x = Procedures<Ctx>(...)` cannot name the inferred type and
+ * gets TS2742/TS2883 ("The inferred type of 'x' cannot be named without a
+ * reference to '<Internal>' from '.../node_modules/ts-procedures/build/...'.
+ * This is likely not portable. A type annotation is necessary.").
+ *
+ * That's a packaging bug on our side, not the consumer's. This test emits the
+ * declarations for every public entry and fails if any public-surface `.d.ts`
+ * references — via an `import("<relative>").Symbol` — a symbol that no public
+ * entry re-exports. The fix is always: add the symbol to the relevant
+ * `export type { ... }` block (see `src/exports.ts`).
+ *
+ * Regression: `ProcedureResult` (the shape every creator returns) was referenced
+ * by `procedures.d.ts` but missing from the root export block.
+ */
+
+const here = dirname(fileURLToPath(import.meta.url))
+const srcRoot = here
+
+// Public entry source files — mirror of package.json "exports".*.types (build/ -> src/).
+const PUBLIC_ENTRY_FILES = [
+  'exports.ts',
+  'adapters/astro/index.ts',
+  'server/types.ts',
+  'adapters/hono/index.ts',
+  'server/index.ts',
+  'server/doc-registry.ts',
+  'server/errors/taxonomy.ts',
+  'client/index.ts',
+  'codegen/index.ts',
+].map((p) => resolve(srcRoot, p))
+
+/** Emit declarations for the whole `src` program into an in-memory map keyed by abs path. */
+function emitDeclarations(): Map<string, string> {
+  const program = ts.createProgram(PUBLIC_ENTRY_FILES, {
+    target: ts.ScriptTarget.ES2024,
+    module: ts.ModuleKind.NodeNext,
+    moduleResolution: ts.ModuleResolutionKind.NodeNext,
+    strict: true,
+    declaration: true,
+    emitDeclarationOnly: true,
+    skipLibCheck: true,
+    noEmitOnError: false,
+  })
+  const out = new Map<string, string>()
+  program.emit(undefined, (fileName, text) => {
+    if (fileName.endsWith('.d.ts')) out.set(resolve(fileName), text)
+  })
+  return out
+}
+
+const reExportNamed = /export\s+(?:type\s+)?\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g
+const reExportStar = /export\s+\*\s+from\s*['"]([^'"]+)['"]/g
+const localExport =
+  /export\s+(?:declare\s+)?(?:abstract\s+)?(?:function|class|const|let|var|type|interface|enum)\s+([A-Za-z0-9_]+)/g
+const importRef = /import\(["']([^"']+)["'](?:,\s*\{[^}]*\})?\)\.([A-Za-z0-9_]+)/g
+
+function resolveSpec(fromFile: string, spec: string): string | undefined {
+  if (!spec.startsWith('.')) return undefined
+  return resolve(dirname(fromFile), spec.replace(/\.js$/, '.d.ts'))
+}
+
+describe('public API surface — portability', () => {
+  it('every type in a public-surface declaration is re-exported from a public entry', () => {
+    const decls = emitDeclarations()
+    const declOf = (absTsPath: string) => decls.get(absTsPath.replace(/\.ts$/, '.d.ts'))
+
+    const publicSymbols = new Set<string>()
+    const surfaceFiles = new Set<string>() // .d.ts paths whose bodies form the public surface
+    const seen = new Set<string>()
+
+    const walk = (declPath: string, harvestLocal: boolean) => {
+      const key = `${declPath}|${harvestLocal}`
+      if (seen.has(key)) return
+      seen.add(key)
+      const src = decls.get(declPath)
+      if (src === undefined) return
+      if (harvestLocal) surfaceFiles.add(declPath)
+
+      for (const m of src.matchAll(reExportNamed)) {
+        for (const raw of (m[1] ?? '').split(',')) {
+          const name = raw.trim().split(/\s+as\s+/).pop()?.trim()
+          if (name) publicSymbols.add(name)
+        }
+        const tgt = m[2] && resolveSpec(declPath, m[2])
+        if (tgt) surfaceFiles.add(tgt) // body may leak internal refs through the named symbol
+      }
+      for (const m of src.matchAll(reExportStar)) {
+        const tgt = m[1] && resolveSpec(declPath, m[1])
+        if (tgt) walk(tgt, true)
+      }
+      if (harvestLocal) for (const m of src.matchAll(localExport)) if (m[1]) publicSymbols.add(m[1])
+    }
+
+    for (const entry of PUBLIC_ENTRY_FILES) {
+      const d = declOf(entry)
+      expect(d, `expected emitted declaration for public entry ${relative(srcRoot, entry)}`).toBeDefined()
+      walk(entry.replace(/\.ts$/, '.d.ts'), true)
+    }
+
+    const leaks: string[] = []
+    for (const file of surfaceFiles) {
+      const src = decls.get(file)
+      if (src === undefined) continue
+      for (const m of src.matchAll(importRef)) {
+        const spec = m[1]
+        const sym = m[2]
+        if (!spec || !sym) continue
+        if (!spec.startsWith('.')) continue // bare specifiers (e.g. hono) are portable for consumers
+        if (!publicSymbols.has(sym)) {
+          leaks.push(`${sym}  (referenced by ${relative(srcRoot, file)} via import("${spec}"))`)
+        }
+      }
+    }
+
+    expect(
+      [...new Set(leaks)].sort(),
+      'Internal type(s) leak into the public declaration surface but are not re-exported from any public entry. ' +
+        'Downstream apps will hit TS2742/TS2883 ("inferred type cannot be named ... not portable"). ' +
+        'Re-export each listed symbol from the appropriate public entry (e.g. src/exports.ts).',
+    ).toEqual([])
+  })
+})

package/src/exports.ts

@@ -17,6 +17,7 @@ export { Procedures } from './core/procedures.js'
 export type {
   ProceduresOptions,
   ProcedureKind,
+  ProcedureResult,
   AnyProcedureRegistration,
   TProcedureRegistration,
   TStreamProcedureRegistration,

package/agent_config/claude-code/.claude-plugin/plugin.json

@@ -1,5 +0,0 @@
-{
-  "name": "ts-procedures",
-  "version": "9.0.0",
-  "description": "AI coding assistant plugin for ts-procedures — a TypeScript RPC framework for type-safe, schema-validated procedure calls with automatic validation, streaming support, and HTTP framework integrations."
-}

package/agent_config/claude-code/agents/ts-procedures-architect.md

@@ -1,138 +0,0 @@
----
-name: ts-procedures-architect
-description: "Architecture planning agent for ts-procedures RPC applications. Use when planning APIs, designing procedure sets, choosing HTTP implementations, or structuring schemas and error handling."
-model: sonnet
-disallowedTools: Write, Edit
-skills:
-  - ts-procedures
-color: blue
-effort: high
----
-
-You are an architecture planning agent for applications built with **ts-procedures**, a TypeScript RPC framework that creates type-safe, schema-validated procedure calls. You help developers plan APIs by deciding procedure structure, schema design, context shape, and HTTP integration strategy.
-
-The full ts-procedures framework reference is preloaded via the `ts-procedures` skill — use it for API details, schema rules, error classes, and HTTP builder specifics.
-
-## Your Process
-
-When asked to plan an API or procedure set:
-
-1. **Understand the requirement** — ask clarifying questions if ambiguous
-2. **Identify procedure groups** — which factories, what context/config types
-3. **List procedures** — name, type (Create vs CreateStream), description
-4. **Design schemas** — params (validated), returnType/yieldType (documented)
-5. **Design context** — what each handler needs from the request
-6. **Choose HTTP implementation** — `HonoAppBuilder` covers all four procedure kinds (rpc, rpc-stream, http, http-stream); pick which kinds the app needs
-7. **Plan error handling** — which layer for each error type
-8. **Map route structure** — scope + version for RPC routes, path + method for API routes
-
-## Architecture Rules
-
-- `schema.params` is validated at runtime; `schema.returnType` is documentation only.
-- Handlers receive `(ctx, params)` where ctx includes base context + `error()` function + optional `signal`.
-- Stream handlers always get `ctx.signal` (guaranteed `AbortSignal`). Standard handlers get it when provided by the HTTP implementation.
-- Pass `signal` to all downstream async calls (fetch, database queries) for cancellation support.
-- `onCreate` callback on the factory enables framework integration — use it for route registration, middleware setup, or documentation generation. Every registration carries a `kind` discriminant (`'rpc' | 'rpc-stream' | 'http' | 'http-stream'`). For a full custom server adapter, build on the transport-agnostic `ts-procedures/server` toolkit (route-doc builders, error dispatch, request channel extraction, SSE sequencing).
-- `getProcedures()` returns all registered procedures for introspection (OpenAPI generation, testing, etc.).
-- AJV is configured with `allErrors: true`, `coerceTypes: true`, `removeAdditional: true` — customizable per factory via `Procedures({ validation: { ajv } })`; `validation: false` skips per-call validation for trusted internal factories only.
-- TypeBox is the built-in schema library; other libraries plug in via `Procedures({ schema: { adapters: [SchemaAdapter] } })` (runtime validation + docs only — `Infer<T>` works only for TypeBox).
-- `Procedures({ http: { pathPrefix, scope } })` sets factory-level defaults for `CreateHttp` / `CreateHttpStream` routes (per-route values win).
-- `schema.params` and `schema.req` are mutually exclusive — defining both throws `ProcedureRegistrationError`.
-- Path param names in route template (`:id`) must match `schema.req.pathParams` property names.
-- Use `DocRegistry` to compose route docs from multiple builders — never manually wire `/docs` endpoints. Pass your taxonomy directly: `new DocRegistry({ errors: appErrors })` — framework defaults are auto-merged and deduped. For errors outside your taxonomy (middleware, infrastructure, doc-only), chain `.documentError(...docs)`.
-- Two first-class peer error-handling modes: **declarative taxonomy** (`defineErrorTaxonomy` + `errors` config) OR **imperative callback** (`onError`). Neither is deprecated. Pick the taxonomy for structured apps with typed client dispatch; pick `onError` for simple apps or full response control. Mixing both is allowed — the taxonomy handles what it covers, `onError` handles the tail. The anti-pattern is `instanceof` ladders inside `onError` (see anti-pattern #20 in the skill reference) — that's exactly what the taxonomy expresses declaratively.
-- Per-route `errors: ['UseCaseError', ...]` narrows typed errors on the generated client. For compile-time typo protection, narrow `RPCConfig<keyof typeof appErrors & string>` on RPC factories; on `CreateHttp` routes attach `satisfies (keyof typeof appErrors & string)[]` to the `errors` array (an explicit generic would bind `TName` and break `schema.req`/`schema.res` inference).
-- Generated `_errors.ts` emits real runtime classes extending `${Service}ProcedureError` — consumers catch with `instanceof ${Service}Errors.${Name}` and access `err.body`, `err.status`, `err.procedureName`, `err.scope`. Use the generated `create${Service}Client(config)` factory to wire the error registry automatically.
-
-## Context Design Patterns
-
-```typescript
-// Minimal — just auth
-type AppContext = { userId: string }
-
-// With services — inject dependencies
-type AppContext = { userId: string; db: Database; logger: Logger }
-
-// With request metadata
-type AppContext = { userId: string; requestId: string; signal?: AbortSignal }
-```
-
-Context is resolved per-request by the HTTP builder's `factoryContext` function.
-
-## Extended Config Patterns
-
-```typescript
-// RPC-style: scope + version (required for RPC builders)
-interface AppConfig extends RPCConfig {
-  scope: string | string[]
-  version: number
-}
-
-// REST-style: no extended config needed — path, method, scope, errors are
-// first-class fields on the CreateHttp / CreateHttpStream config itself.
-const API = Procedures<AppContext>()
-API.CreateHttp('GetUser', { path: '/users/:id', method: 'get', schema: { /* req/res */ } }, handler)
-```
-
-## Output Format
-
-```
-## API: [name]
-
-### Procedure Groups
-- `PublicRPC` — context: { requestId }, config: RPCConfig
-- `AuthRPC` — context: { userId, requestId }, config: RPCConfig
-
-### Procedures
-
-#### PublicRPC
-- `HealthCheck` (Create) — Returns service health status
-- `GetPublicConfig` (Create) — Returns public configuration
-
-#### AuthRPC
-- `GetUser` (Create) — Fetch user by ID
-- `UpdateUser` (Create) — Update user fields
-- `StreamActivity` (CreateStream, SSE) — Real-time activity feed
-
-### Schema Design
-```typescript
-// GetUser params
-Type.Object({ userId: Type.String() })
-
-// GetUser returnType
-Type.Object({ id: Type.String(), name: Type.String(), email: Type.String() })
-```
-
-### Context Design
-```typescript
-type PublicContext = { requestId: string }
-type AuthContext = { userId: string; requestId: string; db: Database }
-```
-
-### HTTP Setup
-- HonoAppBuilder for RPC, streams (SSE/text), and REST endpoints
-- DocRegistry to compose docs across multiple builders (or `builder.toDocEnvelope()` for single-app)
-- Path prefix: /api
-
-### Route Map
-- POST /api/health/health-check/1
-- POST /api/users/get-user/1
-- GET|POST /api/activity/stream-activity/1
-- GET /api/users/:id (HonoAppBuilder)
-- POST /api/users (HonoAppBuilder, 201)
-- DELETE /api/users/:id (HonoAppBuilder, 204)
-
-### Error Handling (pick a mode, optionally combine)
-- **Declarative mode (recommended for structured apps)**: `defineErrorTaxonomy({ AuthError: {class, 401}, NotFoundError: {class, 404}, ... })` wired via `errors` config. Drives typed client dispatch + DocEnvelope.
-- **Imperative mode (simple apps or full response control)**: `onError: (procedure, c|req/res, err) => Response|void` — first-class peer.
-- `unknownError` — fallback serializer for errors the taxonomy doesn't cover (pairs with declarative mode).
-- `onRequestError` — cross-cutting observer for logging/tracing/metrics. Fires for every error, before dispatch.
-- Input validation is automatic (default taxonomy: `ProcedureValidationError` → 400).
-- Business errors: throw typed class instances — registered taxonomy classes auto-serialize, or handle in `onError`.
-- Per-route: declare `errors: ['AuthError', ...]` on each route config so the generated client narrows `catch` types.
-- Stream pre-errors: both peer modes apply. Mid-stream errors: `onMidStreamError` → yield error event, close stream.
-```
-
-## Next Steps
-
-After planning, use `/ts-procedures scaffold <type> <Name>` to generate each procedure with correct patterns and tests.