ts-procedures 5.2.0 → 5.3.0

package/agent_config/claude-code/skills/review/checklist.md

@@ -0,0 +1,141 @@
+# ts-procedures Review Checklist
+
+## Procedure Definition Checks
+
+### CRITICAL
+- [ ] Uses `ctx.error()` for business logic errors, never throws raw `Error` instances
+- [ ] Does not expect `schema.returnType` to be validated at runtime (it's documentation only)
+- [ ] No duplicate procedure names within the same factory
+- [ ] Schema uses TypeBox builders (`Type.Object(...)`, etc.), not plain JSON Schema objects
+- [ ] Stream handlers check `ctx.signal.aborted` in loops to prevent infinite resource consumption
+
+### WARNING
+- [ ] Passes `ctx.signal` to all downstream async calls (fetch, database queries, etc.)
+- [ ] Does not put manual validation logic in handler when `schema.params` handles it
+- [ ] Does not swallow errors in try/catch without re-throwing (hides failures)
+- [ ] Uses `validateYields: true` only when `schema.yieldType` is also defined
+- [ ] Does not mix Create procedures and CreateStream procedures in confusing ways
+
+### SUGGESTION
+- [ ] Has `description` field set for documentation/introspection
+- [ ] Uses meaningful procedure names (PascalCase, verb-noun: `GetUser`, `CreateOrder`)
+- [ ] Destructures return value for clean exports: `const { GetUser, info } = Create(...)`
+
+---
+
+## Schema Checks
+
+### CRITICAL
+- [ ] Uses TypeBox (`Type.Object(...)`, `Type.String()`, etc.) — not plain objects
+- [ ] Required fields use `Type.String()` directly; optional fields wrapped with `Type.Optional(...)`
+
+### WARNING
+- [ ] Understands AJV `coerceTypes: true` — no manual type parsing for query string values
+- [ ] Understands AJV `removeAdditional: true` — extra fields in params are silently stripped
+- [ ] Does not rely on params fields not in the schema (they get removed)
+
+### SUGGESTION
+- [ ] `returnType` schema provided for documentation generation
+- [ ] `yieldType` schema provided for streaming procedures
+
+---
+
+## Context Checks
+
+### CRITICAL
+- [ ] Factory has explicit `TContext` type parameter when using HTTP builders
+- [ ] Context factory function handles errors gracefully (async failures don't crash requests)
+
+### WARNING
+- [ ] Context type includes `signal?: AbortSignal` if procedures need cancellation support
+- [ ] Context factory resolves only what handlers need (avoid expensive unused computations)
+
+### SUGGESTION
+- [ ] Context type is documented or self-descriptive
+- [ ] Separate factories for different access levels (public vs authenticated)
+
+---
+
+## HTTP Builder Checks (Express/Hono)
+
+### CRITICAL
+- [ ] Standard `Create` procedures registered with `ExpressRPCAppBuilder` or `HonoRPCAppBuilder`, NOT `HonoStreamAppBuilder`
+- [ ] Stream `CreateStream` procedures registered with `HonoStreamAppBuilder`, NOT the RPC builders
+- [ ] `onError` callback handles `ProcedureValidationError` and `ProcedureError` differently
+
+### WARNING
+- [ ] `pathPrefix` set consistently across builders
+- [ ] `scope` and `version` set on all procedures when using `RPCConfig`
+- [ ] Uses `extendProcedureDoc` for documentation generation instead of manual doc building
+- [ ] `onRequestEnd` used for cleanup/logging, not business logic
+
+### SUGGESTION
+- [ ] Route documentation accessed via `builder.docs` for OpenAPI generation
+- [ ] Lifecycle hooks used for observability (logging, metrics)
+
+---
+
+## Streaming Checks (HonoStreamAppBuilder)
+
+### CRITICAL
+- [ ] `onPreStreamError` handles validation errors before streaming starts (returns HTTP response)
+- [ ] `onMidStreamError` handles runtime errors during streaming (yields error event)
+- [ ] Stream handler does not assume `signal.reason` is always `'stream-completed'` — check for external abort
+
+### WARNING
+- [ ] Uses `sse()` helper for SSE metadata when custom event types or IDs are needed
+- [ ] Correctly distinguishes stream modes: `'sse'` for EventSource clients, `'text'` for simple consumers
+- [ ] Does not yield after `ctx.signal.aborted` is true
+
+### SUGGESTION
+- [ ] Stream mode documented in comments or config
+- [ ] Error data shape matches `yieldType` schema for consistent client parsing
+
+---
+
+## Error Handling Checks
+
+### CRITICAL
+- [ ] Handler errors use `ctx.error(message, meta?)` — not `throw new Error()`
+- [ ] Does not catch and swallow errors without re-throwing (hides failures from caller)
+- [ ] HTTP builder has `onError` callback — default behavior may expose internal details
+
+### WARNING
+- [ ] `ProcedureValidationError` handled separately (400 status) from `ProcedureError` (4xx/5xx)
+- [ ] Error `meta` object contains useful context (error codes, IDs) — not sensitive data
+- [ ] Stack traces not exposed in production responses
+
+### SUGGESTION
+- [ ] Consistent error response shape across all procedures
+- [ ] Error codes documented for API consumers
+
+---
+
+## Test File Checks
+
+### CRITICAL
+- [ ] Tests both valid and invalid param scenarios
+- [ ] Tests `ProcedureValidationError` is thrown for schema violations
+- [ ] Tests `ProcedureError` is thrown for business logic failures
+
+### WARNING
+- [ ] Tests pass context with required fields (doesn't rely on undefined context)
+- [ ] HTTP builder tests verify response status codes and body shape
+- [ ] Stream tests consume values with `for await...of` and break after expected count
+
+### SUGGESTION
+- [ ] Tests verify `info` metadata (name, schema, description)
+- [ ] Tests verify `getProcedures()` returns expected registrations
+- [ ] Tests verify error `meta` contains expected fields
+
+---
+
+## Extended Config Checks
+
+### WARNING
+- [ ] All procedures include required `TExtendedConfig` fields (e.g., `scope`, `version` for `RPCConfig`)
+- [ ] Custom config fields used consistently across procedure group
+
+### SUGGESTION
+- [ ] Custom config fields documented
+- [ ] `getProcedures()` used for config introspection (permissions audit, etc.)

package/agent_config/claude-code/skills/scaffold/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: scaffold
+description: "Scaffold ts-procedures code with correct patterns. Usage: /ts-procedures:scaffold <type> <Name>"
+invocable_by:
+  - user
+  - model
+user_instructions: |
+  Usage: /ts-procedures:scaffold <type> <Name>
+
+  Types: procedure, stream-procedure, express-rpc, hono-rpc, hono-stream
+
+  Examples:
+    /ts-procedures:scaffold procedure GetUser
+    /ts-procedures:scaffold stream-procedure StreamActivity
+    /ts-procedures:scaffold express-rpc UserApi
+    /ts-procedures:scaffold hono-rpc OrderApi
+    /ts-procedures:scaffold hono-stream LiveFeed
+---
+
+# Scaffold ts-procedures Code
+
+Parse `$ARGUMENTS` as `<type> <Name>` (case-insensitive type, PascalCase Name).
+
+## Instructions
+
+1. Parse the arguments. If missing, ask the user for `<type>` and `<Name>`.
+2. Derive placeholder variants from the provided PascalCase Name:
+   - `{{Name}}` — PascalCase as given (e.g., `UserProfile`)
+   - `{{name}}` — camelCase (e.g., `userProfile`)
+   - For URL scopes and file paths, use kebab-case (e.g., `user-profile`)
+3. Read the template file from `templates/<type>.md` in this skill directory.
+4. Replace all `{{Name}}` and `{{name}}` placeholders with the appropriate variants.
+5. Generate the implementation file(s) following the template exactly.
+6. Also generate a colocated test file following ts-procedures test conventions.
+
+## Valid Types
+
+| Type | Template | Files Generated |
+|------|----------|----------------|
+| `procedure` | `templates/procedure.md` | `{{Name}}.procedure.ts`, `{{Name}}.procedure.test.ts` |
+| `stream-procedure` | `templates/stream-procedure.md` | `{{Name}}.stream.ts`, `{{Name}}.stream.test.ts` |
+| `express-rpc` | `templates/express-rpc.md` | `{{Name}}.rpc.ts`, `{{Name}}.rpc.test.ts` |
+| `hono-rpc` | `templates/hono-rpc.md` | `{{Name}}.rpc.ts`, `{{Name}}.rpc.test.ts` |
+| `hono-stream` | `templates/hono-stream.md` | `{{Name}}.stream-rpc.ts`, `{{Name}}.stream-rpc.test.ts` |
+
+## Rules
+
+- Use `ctx.error()` for business logic errors, never throw raw `Error`.
+- `schema.params` is validated at runtime; `schema.returnType` is documentation only.
+- Pass `ctx.signal` to all downstream async calls.
+- Stream handlers always have `ctx.signal` (guaranteed `AbortSignal`).
+- Use TypeBox for schema definitions (`import { Type } from 'typebox'`).
+- AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`.
+- Test files use `describe`/`test` from vitest.

package/agent_config/claude-code/skills/scaffold/templates/express-rpc.md

@@ -0,0 +1,134 @@
+# Express RPC Template: {{Name}}
+
+## Implementation — `{{Name}}.rpc.ts`
+
+```typescript
+import { Procedures, ProcedureError, ProcedureValidationError } from 'ts-procedures'
+import { ExpressRPCAppBuilder } from 'ts-procedures/express-rpc'
+import type { RPCConfig } from 'ts-procedures/http'
+import { Type } from 'typebox'
+
+// ─── Context ──────────────────────────────────────────────
+
+type {{Name}}Context = {
+  userId: string
+  requestId: string
+}
+
+// ─── Procedures ───────────────────────────────────────────
+
+const RPC = Procedures<{{Name}}Context, RPCConfig>()
+
+export const { GetItem } = RPC.Create(
+  'GetItem',
+  {
+    scope: '{{name}}',  // TODO: set URL scope
+    version: 1,
+    description: 'Fetch item by ID',
+    schema: {
+      params: Type.Object({
+        id: Type.String(),
+      }),
+      returnType: Type.Object({
+        id: Type.String(),
+        name: Type.String(),
+      }),
+    },
+  },
+  async (ctx, params) => {
+    // TODO: implement
+    return { id: params.id, name: 'Example' }
+  }
+)
+
+export const { ListItems } = RPC.Create(
+  'ListItems',
+  {
+    scope: '{{name}}',
+    version: 1,
+    description: 'List all items',
+    schema: {
+      params: Type.Object({
+        page: Type.Optional(Type.Number()),
+        limit: Type.Optional(Type.Number()),
+      }),
+    },
+  },
+  async (ctx, params) => {
+    // TODO: implement
+    return { items: [], total: 0 }
+  }
+)
+
+// ─── Express App Builder ──────────────────────────────────
+
+export const {{name}}App = new ExpressRPCAppBuilder({
+  pathPrefix: '/api',
+  onError: (procedure, req, res, error) => {
+    if (error instanceof ProcedureValidationError) {
+      res.status(400).json({
+        error: error.message,
+        details: error.errors,
+        procedure: error.procedureName,
+      })
+    } else if (error instanceof ProcedureError) {
+      res.status(422).json({
+        error: error.message,
+        meta: error.meta,
+        procedure: error.procedureName,
+      })
+    } else {
+      res.status(500).json({ error: 'Internal server error' })
+    }
+  },
+})
+  .register(RPC, async (req) => ({
+    userId: req.headers['x-user-id'] as string || 'anonymous',
+    requestId: req.headers['x-request-id'] as string || crypto.randomUUID(),
+  }))
+  .build()
+
+// Route map:
+// POST /api/{{name}}/get-item/1
+// POST /api/{{name}}/list-items/1
+
+// Documentation: {{name}}App.docs
+```
+
+## Test — `{{Name}}.rpc.test.ts`
+
+```typescript
+import { describe, test, expect } from 'vitest'
+import supertest from 'supertest'
+import { {{name}}App } from './{{Name}}.rpc'
+
+describe('{{Name}} RPC', () => {
+  test('GET item returns expected result', async () => {
+    const res = await supertest({{name}}App)
+      .post('/api/{{name}}/get-item/1')
+      .send({ id: 'item-1' })
+      .expect(200)
+
+    expect(res.body).toEqual({ id: 'item-1', name: 'Example' })
+  })
+
+  test('returns 400 for invalid params', async () => {
+    const res = await supertest({{name}}App)
+      .post('/api/{{name}}/get-item/1')
+      .send({})
+      .expect(400)
+
+    expect(res.body.error).toBeDefined()
+  })
+
+  test('LIST items returns array', async () => {
+    const res = await supertest({{name}}App)
+      .post('/api/{{name}}/list-items/1')
+      .send({ page: 1, limit: 10 })
+      .expect(200)
+
+    expect(res.body).toHaveProperty('items')
+    expect(res.body).toHaveProperty('total')
+  })
+})
+```

package/agent_config/claude-code/skills/scaffold/templates/hono-rpc.md

@@ -0,0 +1,139 @@
+# Hono RPC Template: {{Name}}
+
+## Implementation — `{{Name}}.rpc.ts`
+
+```typescript
+import { Procedures, ProcedureError, ProcedureValidationError } from 'ts-procedures'
+import { HonoRPCAppBuilder } from 'ts-procedures/hono-rpc'
+import type { RPCConfig } from 'ts-procedures/http'
+import { Type } from 'typebox'
+
+// ─── Context ──────────────────────────────────────────────
+
+type {{Name}}Context = {
+  userId: string
+  requestId: string
+}
+
+// ─── Procedures ───────────────────────────────────────────
+
+const RPC = Procedures<{{Name}}Context, RPCConfig>()
+
+export const { GetItem } = RPC.Create(
+  'GetItem',
+  {
+    scope: '{{name}}',  // TODO: set URL scope
+    version: 1,
+    description: 'Fetch item by ID',
+    schema: {
+      params: Type.Object({
+        id: Type.String(),
+      }),
+      returnType: Type.Object({
+        id: Type.String(),
+        name: Type.String(),
+      }),
+    },
+  },
+  async (ctx, params) => {
+    // TODO: implement
+    return { id: params.id, name: 'Example' }
+  }
+)
+
+export const { ListItems } = RPC.Create(
+  'ListItems',
+  {
+    scope: '{{name}}',
+    version: 1,
+    description: 'List all items',
+    schema: {
+      params: Type.Object({
+        page: Type.Optional(Type.Number()),
+        limit: Type.Optional(Type.Number()),
+      }),
+    },
+  },
+  async (ctx, params) => {
+    // TODO: implement
+    return { items: [], total: 0 }
+  }
+)
+
+// ─── Hono App Builder ─────────────────────────────────────
+
+export const {{name}}App = new HonoRPCAppBuilder({
+  pathPrefix: '/api',
+  onError: (procedure, c, error) => {
+    if (error instanceof ProcedureValidationError) {
+      return c.json({
+        error: error.message,
+        details: error.errors,
+        procedure: error.procedureName,
+      }, 400)
+    } else if (error instanceof ProcedureError) {
+      return c.json({
+        error: error.message,
+        meta: error.meta,
+        procedure: error.procedureName,
+      }, 422)
+    }
+    return c.json({ error: 'Internal server error' }, 500)
+  },
+})
+  .register(RPC, (c) => ({
+    userId: c.req.header('x-user-id') || 'anonymous',
+    requestId: c.req.header('x-request-id') || crypto.randomUUID(),
+  }))
+  .build()
+
+// Route map:
+// POST /api/{{name}}/get-item/1
+// POST /api/{{name}}/list-items/1
+
+// Documentation: {{name}}App.docs
+```
+
+## Test — `{{Name}}.rpc.test.ts`
+
+```typescript
+import { describe, test, expect } from 'vitest'
+import { {{name}}App } from './{{Name}}.rpc'
+
+describe('{{Name}} RPC', () => {
+  test('GET item returns expected result', async () => {
+    const res = await {{name}}App.request('/api/{{name}}/get-item/1', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ id: 'item-1' }),
+    })
+
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body).toEqual({ id: 'item-1', name: 'Example' })
+  })
+
+  test('returns 400 for invalid params', async () => {
+    const res = await {{name}}App.request('/api/{{name}}/get-item/1', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    })
+
+    expect(res.status).toBe(400)
+  })
+
+  test('LIST items returns array', async () => {
+    const res = await {{name}}App.request('/api/{{name}}/list-items/1', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ page: 1, limit: 10 }),
+    })
+
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body).toHaveProperty('items')
+    expect(body).toHaveProperty('total')
+  })
+})
+```

package/agent_config/claude-code/skills/scaffold/templates/hono-stream.md

@@ -0,0 +1,134 @@
+# Hono Stream Template: {{Name}}
+
+## Implementation — `{{Name}}.stream-rpc.ts`
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
+import type { RPCConfig } from 'ts-procedures/http'
+import { Type } from 'typebox'
+
+// ─── Context ──────────────────────────────────────────────
+
+type {{Name}}Context = {
+  userId: string
+}
+
+// ─── Stream Procedures ────────────────────────────────────
+
+const StreamRPC = Procedures<{{Name}}Context, RPCConfig>()
+
+export const { {{Name}}Stream } = StreamRPC.CreateStream(
+  '{{Name}}Stream',
+  {
+    scope: '{{name}}',  // TODO: set URL scope
+    version: 1,
+    description: 'TODO: describe what this streams',
+    schema: {
+      params: Type.Object({
+        // TODO: define input parameters
+        channel: Type.String(),
+      }),
+      yieldType: Type.Object({
+        // TODO: define shape of each yielded value
+        type: Type.String(),
+        payload: Type.Any(),
+        timestamp: Type.Number(),
+      }),
+    },
+  },
+  async function* (ctx, params) {
+    // ctx.signal is ALWAYS present in stream handlers
+
+    // TODO: implement streaming logic
+    let counter = 0
+    while (!ctx.signal.aborted) {
+      const event = await pollForEvents(params.channel, { signal: ctx.signal })
+
+      // Use sse() to attach SSE metadata (event type, id, retry)
+      yield sse(
+        { type: event.type, payload: event.data, timestamp: Date.now() },
+        { event: event.type, id: String(counter++) }
+      )
+    }
+  }
+)
+
+// Placeholder — replace with real event source
+async function pollForEvents(channel: string, opts?: { signal?: AbortSignal }) {
+  await new Promise(r => setTimeout(r, 1000))
+  return { type: 'update', data: { value: Math.random() } }
+}
+
+// ─── Hono Stream App Builder ──────────────────────────────
+
+export const {{name}}StreamApp = new HonoStreamAppBuilder({
+  pathPrefix: '/api',
+  defaultStreamMode: 'sse',  // or 'text' for newline-delimited JSON
+  onPreStreamError: (procedure, c, error) => {
+    return c.json({ error: error.message }, 400)
+  },
+  onMidStreamError: (procedure, c, error) => ({
+    data: { type: 'error', payload: { message: error.message }, timestamp: Date.now() },
+    closeStream: true,
+  }),
+})
+  .register(StreamRPC, (c) => ({
+    userId: c.req.header('x-user-id') || 'anonymous',
+  }))
+  .build()
+
+// Routes:
+// GET  /api/{{name}}/{{name}}-stream/1?channel=test
+// POST /api/{{name}}/{{name}}-stream/1  (body: { channel: "test" })
+
+// SSE output per yield:
+// event: {{Name}}Stream
+// id: 0
+// data: {"type":"update","payload":{...},"timestamp":1234567890}
+```
+
+## Test — `{{Name}}.stream-rpc.test.ts`
+
+```typescript
+import { describe, test, expect } from 'vitest'
+import { {{name}}StreamApp } from './{{Name}}.stream-rpc'
+
+describe('{{Name}} Stream RPC', () => {
+  test('GET returns SSE stream', async () => {
+    const res = await {{name}}StreamApp.request(
+      '/api/{{name}}/{{name}}-stream/1?channel=test'
+    )
+
+    expect(res.status).toBe(200)
+    expect(res.headers.get('content-type')).toContain('text/event-stream')
+  })
+
+  test('POST returns SSE stream', async () => {
+    const res = await {{name}}StreamApp.request(
+      '/api/{{name}}/{{name}}-stream/1',
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ channel: 'test' }),
+      }
+    )
+
+    expect(res.status).toBe(200)
+    expect(res.headers.get('content-type')).toContain('text/event-stream')
+  })
+
+  test('returns 400 for invalid params', async () => {
+    const res = await {{name}}StreamApp.request(
+      '/api/{{name}}/{{name}}-stream/1',
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({}),
+      }
+    )
+
+    expect(res.status).toBe(400)
+  })
+})
+```

package/agent_config/claude-code/skills/scaffold/templates/procedure.md

@@ -0,0 +1,77 @@
+# Procedure Template: {{Name}}
+
+## Implementation — `{{Name}}.procedure.ts`
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { Type } from 'typebox'
+
+// Define context type (adjust to match your app's context)
+type AppContext = {
+  userId: string
+  signal?: AbortSignal
+}
+
+const { Create } = Procedures<AppContext>()
+
+export const { {{Name}}, procedure: {{Name}}Procedure, info: {{Name}}Info } = Create(
+  '{{Name}}',
+  {
+    description: 'TODO: describe what {{Name}} does',
+    schema: {
+      params: Type.Object({
+        // TODO: define input parameters
+        id: Type.String(),
+      }),
+      returnType: Type.Object({
+        // TODO: define return shape (documentation only, not validated at runtime)
+        id: Type.String(),
+        // ...fields
+      }),
+    },
+  },
+  async (ctx, params) => {
+    // params.id is guaranteed to be a string (validated by AJV)
+
+    // Use ctx.error() for business logic errors
+    // throw ctx.error('Not found', { code: 'NOT_FOUND', id: params.id })
+
+    // Pass ctx.signal to downstream async calls
+    // const data = await fetch(url, { signal: ctx.signal })
+
+    // TODO: implement handler logic
+    return { id: params.id }
+  }
+)
+```
+
+## Test — `{{Name}}.procedure.test.ts`
+
+```typescript
+import { describe, test, expect } from 'vitest'
+import { ProcedureError, ProcedureValidationError } from 'ts-procedures'
+import { {{Name}} } from './{{Name}}.procedure'
+
+const mockContext = { userId: 'test-user' }
+
+describe('{{Name}}', () => {
+  test('returns expected result for valid params', async () => {
+    const result = await {{Name}}(mockContext, { id: 'test-id' })
+    expect(result).toBeDefined()
+    expect(result.id).toBe('test-id')
+  })
+
+  test('throws ProcedureValidationError for invalid params', async () => {
+    await expect(
+      {{Name}}(mockContext, {} as any)
+    ).rejects.toThrow(ProcedureValidationError)
+  })
+
+  test('throws ProcedureError for business logic failures', async () => {
+    // TODO: test ctx.error() scenarios
+    // await expect(
+    //   {{Name}}(mockContext, { id: 'invalid' })
+    // ).rejects.toThrow(ProcedureError)
+  })
+})
+```