ts-procedures 5.2.0 → 5.4.0

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

@@ -0,0 +1,53 @@
+---
+name: review
+description: "Review code for ts-procedures pattern adherence. Usage: /ts-procedures:review <path>"
+invocable_by:
+  - user
+  - model
+user_instructions: |
+  Usage: /ts-procedures:review <path>
+
+  Reviews files at the given path for ts-procedures pattern adherence.
+  Accepts a file path or directory.
+
+  Examples:
+    /ts-procedures:review src/procedures/
+    /ts-procedures:review src/procedures/GetUser.procedure.ts
+---
+
+# Review ts-procedures Code
+
+Parse `$ARGUMENTS` as a file or directory path. If a directory, review all `.ts` and `.tsx` files within it.
+
+## Instructions
+
+1. Read the target file(s).
+2. Identify ts-procedures imports (`ts-procedures`, `ts-procedures/express-rpc`, `ts-procedures/hono-rpc`, `ts-procedures/hono-stream`, `ts-procedures/http`) to determine file types.
+3. Check each file against the categorized checklist in `checklist.md`.
+4. Output findings grouped by severity.
+
+## Output Format
+
+For each finding:
+
+```
+[SEVERITY] file:line — Violation
+  Problem: What's wrong
+  Fix: Concrete before/after code
+```
+
+Severity levels:
+- **CRITICAL** — Will cause bugs, silent failures, resource leaks, or runtime errors. Must fix.
+- **WARNING** — Anti-pattern that hurts maintainability or correctness. Should fix.
+- **SUGGESTION** — Improvement for readability, type safety, or DX. Nice to have.
+
+## Summary
+
+After individual findings, provide:
+- Total findings by severity
+- Overall assessment (healthy / needs attention / significant issues)
+- Top 3 priorities to address
+
+## Reference
+
+See `checklist.md` for the complete categorized checklist by file type.

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

@@ -0,0 +1,163 @@
+# 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(...)`
+- [ ] Does not define both `schema.params` and `schema.input` on the same procedure (mutually exclusive)
+
+### 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
+
+---
+
+## API Builder Checks (HonoAPIAppBuilder)
+
+### CRITICAL
+- [ ] `build()` is `await`ed — returns `Promise<Hono>`, not `Hono`
+- [ ] Path param names in route template match `schema.input.pathParams` property names exactly
+- [ ] Does not define both `schema.params` and `schema.input` on the same procedure
+- [ ] `onError` callback handles `ProcedureValidationError` and `ProcedureError` differently
+
+### WARNING
+- [ ] Uses `schema.input` channels appropriate for the HTTP method (no `body` on GET/HEAD)
+- [ ] `pathPrefix` set consistently
+- [ ] `successStatus` overridden only when default (POST→201, DELETE→204) is wrong
+- [ ] Uses `APIInput` type constraint (`satisfies APIInput`) to catch channel name typos
+
+### SUGGESTION
+- [ ] Route documentation accessed via `builder.docs` for OpenAPI generation
+- [ ] Custom `queryParser` provided if complex query string formats needed
+- [ ] Lifecycle hooks used for observability (logging, metrics)
+
+---
+
+## 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,56 @@
+---
+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, hono-api
+
+  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
+    /ts-procedures:scaffold hono-api ProductApi
+---
+
+# 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` |
+| `hono-api` | `templates/hono-api.md` | `{{Name}}.api.ts`, `{{Name}}.api.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-api.md

@@ -0,0 +1,169 @@
+# Hono API Template: {{Name}}
+
+## Implementation — `{{Name}}.api.ts`
+
+```typescript
+import { Procedures, ProcedureError, ProcedureValidationError } from 'ts-procedures'
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import type { APIConfig, APIInput } from 'ts-procedures/http'
+import { Type } from 'typebox'
+
+// ─── Context ──────────────────────────────────────────────
+
+type {{Name}}Context = {
+  userId: string
+  requestId: string
+}
+
+// ─── Procedures ───────────────────────────────────────────
+
+const API = Procedures<{{Name}}Context, APIConfig>()
+
+export const { GetItem } = API.Create(
+  'GetItem',
+  {
+    path: '/{{name}}/:id',  // TODO: set route path
+    method: 'get',
+    description: 'Fetch item by ID',
+    schema: {
+      input: {
+        pathParams: Type.Object({ id: Type.String() }),
+      } satisfies APIInput,
+      returnType: Type.Object({
+        id: Type.String(),
+        name: Type.String(),
+      }),
+    },
+  },
+  async (ctx, { pathParams }) => {
+    // TODO: implement
+    return { id: pathParams.id, name: 'Example' }
+  }
+)
+
+export const { CreateItem } = API.Create(
+  'CreateItem',
+  {
+    path: '/{{name}}',
+    method: 'post',
+    description: 'Create a new item',
+    schema: {
+      input: {
+        body: Type.Object({
+          name: Type.String(),
+        }),
+      } satisfies APIInput,
+      returnType: Type.Object({
+        id: Type.String(),
+        name: Type.String(),
+      }),
+    },
+  },
+  async (ctx, { body }) => {
+    // TODO: implement
+    return { id: 'new-id', name: body.name }
+  }
+)
+
+export const { DeleteItem } = API.Create(
+  'DeleteItem',
+  {
+    path: '/{{name}}/:id',
+    method: 'delete',
+    schema: {
+      input: {
+        pathParams: Type.Object({ id: Type.String() }),
+      } satisfies APIInput,
+    },
+  },
+  async (ctx, { pathParams }) => {
+    // TODO: implement deletion
+  }
+)
+
+// ─── Hono App Builder ─────────────────────────────────────
+
+export const {{name}}App = await new HonoAPIAppBuilder({
+  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(API, (c) => ({
+    userId: c.req.header('x-user-id') || 'anonymous',
+    requestId: c.req.header('x-request-id') || crypto.randomUUID(),
+  }))
+  .build()
+
+// Route map:
+// GET    /api/{{name}}/:id → 200
+// POST   /api/{{name}}     → 201
+// DELETE /api/{{name}}/:id → 204
+
+// Documentation: builder.docs (access before .build() resolves)
+```
+
+## Test — `{{Name}}.api.test.ts`
+
+```typescript
+import { describe, test, expect } from 'vitest'
+import { {{name}}App } from './{{Name}}.api'
+
+describe('{{Name}} API', () => {
+  test('GET item returns expected result', async () => {
+    const app = await {{name}}App
+    const res = await app.request('/api/{{name}}/item-1')
+
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body).toEqual({ id: 'item-1', name: 'Example' })
+  })
+
+  test('POST item returns 201', async () => {
+    const app = await {{name}}App
+    const res = await app.request('/api/{{name}}', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'New Item' }),
+    })
+
+    expect(res.status).toBe(201)
+    const body = await res.json()
+    expect(body).toHaveProperty('id')
+    expect(body.name).toBe('New Item')
+  })
+
+  test('DELETE item returns 204', async () => {
+    const app = await {{name}}App
+    const res = await app.request('/api/{{name}}/item-1', {
+      method: 'DELETE',
+    })
+
+    expect(res.status).toBe(204)
+  })
+
+  test('returns 400 for invalid POST body', async () => {
+    const app = await {{name}}App
+    const res = await app.request('/api/{{name}}', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    })
+
+    expect(res.status).toBe(400)
+  })
+})
+```