ts-procedures 5.2.0 → 5.3.0

package/README.md

@@ -771,6 +771,66 @@ import {
 } from 'ts-procedures'
 ```
 
+## 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.
+
+### Quick Setup
+
+```bash
+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
+```
+
+### What Gets Installed
+
+| Tool | Files | Auto-updates? |
+|------|-------|---------------|
+| **Claude Code** | `.claude/rules/ts-procedures.md`, `.claude/commands/ts-procedures-scaffold.md`, `.claude/commands/ts-procedures-review.md`, `.claude/agents/ts-procedures-architect.md` | Yes |
+| **Cursor** | `.cursorrules` (marker-based section) | Yes |
+| **GitHub Copilot** | `.github/copilot-instructions.md` (marker-based section) | Yes |
+
+### 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.
+
+### Claude Code Features
+
+Once installed, Claude Code gets:
+
+- **Framework reference** — auto-loaded rules with core API, schema system, error handling, and decision framework
+- **Scaffold command** — `/project:ts-procedures-scaffold <type> <Name>` generates procedures, streams, and HTTP setups with correct patterns
+- **Review command** — `/project: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
+
+### 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`:
+
+```gitignore
+# Auto-generated AI agent rules (regenerated on npm install)
+.claude/rules/ts-procedures.md
+.claude/commands/ts-procedures-*.md
+.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.
+
 ## License
 
 MIT

package/agent_config/bin/postinstall.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const AGENT_CONFIG_DIR = resolve(__dirname, '..');
+
+const MARKER_BEGIN = '<!-- BEGIN ts-procedures -->';
+const MARKER_END = '<!-- END ts-procedures -->';
+
+// INIT_CWD is set by npm/yarn/pnpm during lifecycle scripts — points to the project root
+const projectRoot = process.env.INIT_CWD;
+
+if (!projectRoot) {
+  process.exit(0);
+}
+
+// Detect self-install (developing ts-procedures itself) — skip
+const ownPackageRoot = resolve(__dirname, '../..');
+if (resolve(projectRoot) === ownPackageRoot) {
+  process.exit(0);
+}
+
+// ─── Helpers ──────────────────────────────────────────────
+
+function readSourceFile(relativePath) {
+  return readFileSync(join(AGENT_CONFIG_DIR, relativePath), 'utf-8');
+}
+
+function wrapWithMarkers(content) {
+  return `${MARKER_BEGIN}\n${content.trim()}\n${MARKER_END}`;
+}
+
+function replaceMarkerSection(existingContent, newContent) {
+  const beginIdx = existingContent.indexOf(MARKER_BEGIN);
+  const endIdx = existingContent.indexOf(MARKER_END);
+
+  if (beginIdx !== -1 && endIdx !== -1) {
+    const before = existingContent.slice(0, beginIdx);
+    const after = existingContent.slice(endIdx + MARKER_END.length);
+    return before + wrapWithMarkers(newContent) + after;
+  }
+
+  return null; // No existing markers — don't modify
+}
+
+function updateMarkedFile(targetPath, sourceRelativePath) {
+  if (!existsSync(targetPath)) return false;
+
+  const existing = readFileSync(targetPath, 'utf-8');
+  if (!existing.includes(MARKER_BEGIN)) return false;
+
+  const sourceContent = readSourceFile(sourceRelativePath);
+  const updated = replaceMarkerSection(existing, sourceContent);
+  if (updated) {
+    writeFileSync(targetPath, updated, 'utf-8');
+    return true;
+  }
+  return false;
+}
+
+// ─── Auto-update ──────────────────────────────────────────
+
+const rulesFile = join(projectRoot, '.claude', 'rules', 'ts-procedures.md');
+const cursorFile = join(projectRoot, '.cursorrules');
+const copilotFile = join(projectRoot, '.github', 'copilot-instructions.md');
+
+// Check if any target was previously set up
+const hasAnySetup = existsSync(rulesFile) || existsSync(cursorFile) || existsSync(copilotFile);
+
+if (hasAnySetup) {
+  try {
+    const updated = [];
+
+    // Auto-update Claude Code files
+    if (existsSync(rulesFile)) {
+      const { installClaude } = await import('../lib/install-claude.mjs');
+      installClaude(projectRoot);
+      updated.push('Claude Code');
+    }
+
+    // Auto-update Cursor rules (only if markers present)
+    if (updateMarkedFile(cursorFile, 'cursor/cursorrules')) {
+      updated.push('Cursor');
+    }
+
+    // Auto-update Copilot instructions (only if markers present)
+    if (updateMarkedFile(copilotFile, 'copilot/copilot-instructions.md')) {
+      updated.push('Copilot');
+    }
+
+    if (updated.length > 0) {
+      console.log('');
+      console.log(`  ts-procedures — AI agent rules updated (${updated.join(', ')})`);
+      console.log('');
+    }
+  } catch {
+    // Never break npm install
+  }
+}
+
+// No invitation message if not opted in — rely on README / npx ts-procedures-setup --help

package/agent_config/bin/setup.mjs

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
+import { installClaude } from '../lib/install-claude.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const AGENT_CONFIG_DIR = resolve(__dirname, '..');
+const PROJECT_DIR = process.cwd();
+
+const MARKER_BEGIN = '<!-- BEGIN ts-procedures -->';
+const MARKER_END = '<!-- END ts-procedures -->';
+
+const VALID_TARGETS = ['claude', 'cursor', 'copilot', 'all'];
+
+// ─── Helpers ──────────────────────────────────────────────
+
+function printUsage() {
+  console.log(`
+Usage: npx ts-procedures-setup [targets...] [options]
+
+Targets:
+  claude     Install Claude Code rules and commands into .claude/
+  cursor     Copy ts-procedures rules to .cursorrules
+  copilot    Copy ts-procedures instructions to .github/copilot-instructions.md
+  all        Set up all targets (default)
+
+Options:
+  --help      Show this help message
+  --force     Overwrite existing files without prompting
+  --dry-run   Show what would be created/updated without writing files
+  --check     Exit with code 1 if any files are outdated (useful in CI)
+
+Examples:
+  npx ts-procedures-setup              # Set up all targets
+  npx ts-procedures-setup cursor       # Set up Cursor only
+  npx ts-procedures-setup cursor copilot  # Set up Cursor and Copilot
+  npx ts-procedures-setup --force      # Overwrite without prompting
+  npx ts-procedures-setup --dry-run    # Preview changes
+  npx ts-procedures-setup --check      # Verify files are up to date
+`);
+}
+
+function readSourceFile(relativePath) {
+  const fullPath = join(AGENT_CONFIG_DIR, relativePath);
+  return readFileSync(fullPath, 'utf-8');
+}
+
+function wrapWithMarkers(content) {
+  return `${MARKER_BEGIN}\n${content.trim()}\n${MARKER_END}`;
+}
+
+function replaceMarkerSection(existingContent, newContent) {
+  const beginIdx = existingContent.indexOf(MARKER_BEGIN);
+  const endIdx = existingContent.indexOf(MARKER_END);
+
+  if (beginIdx !== -1 && endIdx !== -1) {
+    const before = existingContent.slice(0, beginIdx);
+    const after = existingContent.slice(endIdx + MARKER_END.length);
+    return before + wrapWithMarkers(newContent) + after;
+  }
+
+  const separator = existingContent.trim() ? '\n\n' : '';
+  return existingContent.trim() + separator + wrapWithMarkers(newContent) + '\n';
+}
+
+async function confirm(message) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`${message} (y/N) `, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y');
+    });
+  });
+}
+
+// ─── Check Mode ───────────────────────────────────────────
+
+function isFileOutdated(targetPath, expectedContent) {
+  if (!existsSync(targetPath)) return true;
+  const current = readFileSync(targetPath, 'utf-8');
+  return current !== expectedContent;
+}
+
+// ─── Target Handlers ──────────────────────────────────────
+
+function setupClaude({ dryRun, check } = {}) {
+  if (dryRun) {
+    const claudeFiles = [
+      '.claude/rules/ts-procedures.md',
+      '.claude/commands/ts-procedures-scaffold.md',
+      '.claude/commands/ts-procedures-review.md',
+      '.claude/agents/ts-procedures-architect.md',
+    ];
+    console.log('\n  Claude Code (dry run)');
+    console.log('  ─────────────────────');
+    for (const f of claudeFiles) {
+      const status = existsSync(join(PROJECT_DIR, f)) ? 'update' : 'create';
+      console.log(`    [${status}] ${f}`);
+    }
+    console.log('');
+    return false;
+  }
+
+  const { files } = installClaude(PROJECT_DIR);
+
+  if (check) return false; // installClaude always writes — check mode handled at main level
+
+  console.log('\n  Claude Code');
+  console.log('  ───────────');
+  console.log('  Installed (updates automatically on npm install/update):\n');
+  for (const f of files) {
+    console.log(`    ${f}`);
+  }
+  console.log('');
+  console.log('  Commands:  /project:ts-procedures-scaffold, /project:ts-procedures-review');
+  console.log('  Agent:     ts-procedures-architect (architecture planning)');
+  console.log('  Reference: Auto-loaded via .claude/rules/ts-procedures.md\n');
+  return false;
+}
+
+async function setupCursor(force, { dryRun, check } = {}) {
+  const targetPath = join(PROJECT_DIR, '.cursorrules');
+  const sourceContent = readSourceFile('cursor/cursorrules');
+
+  if (dryRun || check) {
+    const exists = existsSync(targetPath);
+    const hasMarkers = exists && readFileSync(targetPath, 'utf-8').includes(MARKER_BEGIN);
+    const label = dryRun ? 'dry run' : 'check';
+    const status = !exists ? 'create' : hasMarkers ? 'update' : 'append';
+    console.log(`\n  Cursor (${label})`);
+    console.log(`  ──────`);
+    console.log(`    [${status}] .cursorrules\n`);
+    return check && (status === 'create' || status === 'update');
+  }
+
+  console.log('\n  Cursor');
+  console.log('  ──────');
+
+  if (existsSync(targetPath)) {
+    const existing = readFileSync(targetPath, 'utf-8');
+
+    if (existing.includes(MARKER_BEGIN)) {
+      const updated = replaceMarkerSection(existing, sourceContent);
+      writeFileSync(targetPath, updated, 'utf-8');
+      console.log('  Updated ts-procedures section in .cursorrules\n');
+      return false;
+    }
+
+    if (!force) {
+      const ok = await confirm('  .cursorrules already exists. Append ts-procedures rules?');
+      if (!ok) {
+        console.log('  Skipped.\n');
+        return false;
+      }
+    }
+
+    const updated = replaceMarkerSection(existing, sourceContent);
+    writeFileSync(targetPath, updated, 'utf-8');
+    console.log('  Appended ts-procedures rules to .cursorrules\n');
+  } else {
+    writeFileSync(targetPath, wrapWithMarkers(sourceContent) + '\n', 'utf-8');
+    console.log('  Created .cursorrules\n');
+  }
+  return false;
+}
+
+async function setupCopilot(force, { dryRun, check } = {}) {
+  const githubDir = join(PROJECT_DIR, '.github');
+  const targetPath = join(githubDir, 'copilot-instructions.md');
+  const sourceContent = readSourceFile('copilot/copilot-instructions.md');
+
+  if (dryRun || check) {
+    const exists = existsSync(targetPath);
+    const hasMarkers = exists && readFileSync(targetPath, 'utf-8').includes(MARKER_BEGIN);
+    const label = dryRun ? 'dry run' : 'check';
+    const status = !exists ? 'create' : hasMarkers ? 'update' : 'append';
+    console.log(`\n  GitHub Copilot (${label})`);
+    console.log(`  ──────────────`);
+    console.log(`    [${status}] .github/copilot-instructions.md\n`);
+    return check && (status === 'create' || status === 'update');
+  }
+
+  console.log('\n  GitHub Copilot');
+  console.log('  ──────────────');
+
+  if (!existsSync(githubDir)) {
+    mkdirSync(githubDir, { recursive: true });
+  }
+
+  if (existsSync(targetPath)) {
+    const existing = readFileSync(targetPath, 'utf-8');
+
+    if (existing.includes(MARKER_BEGIN)) {
+      const updated = replaceMarkerSection(existing, sourceContent);
+      writeFileSync(targetPath, updated, 'utf-8');
+      console.log('  Updated ts-procedures section in .github/copilot-instructions.md\n');
+      return false;
+    }
+
+    if (!force) {
+      const ok = await confirm('  .github/copilot-instructions.md already exists. Append ts-procedures instructions?');
+      if (!ok) {
+        console.log('  Skipped.\n');
+        return false;
+      }
+    }
+
+    const updated = replaceMarkerSection(existing, sourceContent);
+    writeFileSync(targetPath, updated, 'utf-8');
+    console.log('  Appended ts-procedures instructions to .github/copilot-instructions.md\n');
+  } else {
+    writeFileSync(targetPath, wrapWithMarkers(sourceContent) + '\n', 'utf-8');
+    console.log('  Created .github/copilot-instructions.md\n');
+  }
+  return false;
+}
+
+// ─── Main ─────────────────────────────────────────────────
+
+async function main() {
+  const args = process.argv.slice(2);
+  const force = args.includes('--force');
+  const dryRun = args.includes('--dry-run');
+  const check = args.includes('--check');
+  const help = args.includes('--help') || args.includes('-h');
+  const targets = args.filter(a => !a.startsWith('--') && !a.startsWith('-'));
+
+  if (help) {
+    printUsage();
+    process.exit(0);
+  }
+
+  for (const t of targets) {
+    if (!VALID_TARGETS.includes(t)) {
+      console.error(`Unknown target: "${t}". Valid targets: ${VALID_TARGETS.join(', ')}`);
+      process.exit(1);
+    }
+  }
+
+  const selectedTargets = targets.length === 0 || targets.includes('all')
+    ? ['claude', 'cursor', 'copilot']
+    : targets;
+
+  const mode = dryRun ? ' (dry run)' : check ? ' (check)' : '';
+  console.log(`\nts-procedures AI Agent Setup${mode}`);
+  console.log('════════════════════════════');
+
+  const opts = { dryRun, check };
+  let outdated = false;
+
+  if (selectedTargets.includes('claude')) {
+    outdated = setupClaude(opts) || outdated;
+  }
+
+  if (selectedTargets.includes('cursor')) {
+    outdated = (await setupCursor(force, opts)) || outdated;
+  }
+
+  if (selectedTargets.includes('copilot')) {
+    outdated = (await setupCopilot(force, opts)) || outdated;
+  }
+
+  if (check) {
+    if (outdated) {
+      console.log('  Files are outdated. Run: npx ts-procedures-setup\n');
+      process.exit(1);
+    } else {
+      console.log('  All files are up to date.\n');
+    }
+  } else if (dryRun) {
+    console.log('  No files were modified (dry run).\n');
+  } else {
+    console.log('  Tip: Auto-generated .claude/ files can be added to .gitignore');
+    console.log('  (they are regenerated on npm install).\n');
+    console.log('Done!\n');
+  }
+}
+
+main().catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

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

@@ -0,0 +1,5 @@
+{
+  "name": "ts-procedures",
+  "version": "1.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

@@ -0,0 +1,173 @@
+---
+name: ts-procedures-architect
+description: "Architecture planning agent for ts-procedures RPC applications. Decides procedure structure, schema design, context shape, HTTP implementation choice, error handling strategy, and streaming architecture. Use when planning APIs, designing procedure sets, or choosing between Express/Hono implementations."
+model: sonnet
+---
+
+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.
+
+## Core Concepts
+
+| Concept | Role |
+|---------|------|
+| `Procedures<TContext, TExtendedConfig>(builder?)` | Factory that creates `Create` and `CreateStream` functions scoped to a shared context type |
+| `Create(name, config, handler)` | Registers a standard async procedure with optional schema validation |
+| `CreateStream(name, config, handler)` | Registers a streaming procedure (async generator) with AbortSignal support |
+| `TContext` | Base context type injected into all handlers (auth, request info, services) |
+| `TExtendedConfig` | Additional config fields on every procedure (scope, version, permissions, etc.) |
+| `schema.params` | TypeBox schema — validated at runtime via AJV |
+| `schema.returnType` | Documentation only — NOT validated at runtime |
+| `schema.yieldType` | Schema for each streamed value — validated only if `validateYields: true` |
+
+## Decision Framework
+
+### Which procedure type?
+
+1. Request → single response? → **Create** (standard async procedure)
+2. Request → multiple values over time? → **CreateStream** (async generator)
+3. Long-running task with progress? → **CreateStream** with progress yields
+4. Real-time data feed? → **CreateStream** with SSE mode
+
+### Which schema library?
+
+- Use **TypeBox** (`import { Type } from 'typebox'`)
+- TypeBox schemas are valid JSON Schema — they work directly with AJV
+- Define schemas with `Type.Object({ ... })`, `Type.String()`, `Type.Number()`, etc.
+- Use `Type.Optional(...)` for optional fields
+
+### Which HTTP implementation?
+
+| Implementation | Use When |
+|----------------|----------|
+| `ExpressRPCAppBuilder` | Existing Express app, need RPC endpoints alongside REST |
+| `HonoRPCAppBuilder` | Existing Hono app, edge/serverless, need RPC endpoints |
+| `HonoStreamAppBuilder` | Need streaming (SSE or text), Hono-based |
+| Multiple builders | Combine RPC + streaming on the same Hono app |
+
+### Stream mode?
+
+- **SSE** (`'sse'`) — Browser EventSource API, automatic reconnection, event types. Default.
+- **Text** (`'text'`) — Newline-delimited JSON. Simpler, works with any HTTP client.
+
+### How to structure context?
+
+```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.
+
+### How to structure extended config?
+
+```typescript
+// API versioning + scoping (required for HTTP builders)
+interface AppConfig extends RPCConfig {
+  scope: string | string[]   // URL path segments
+  version: number            // API version
+}
+
+// With authorization
+interface AppConfig extends RPCConfig {
+  permissions?: string[]     // Required permissions
+  rateLimit?: number         // Requests per minute
+}
+```
+
+### How to group procedures?
+
+- **By domain**: `UserProcedures`, `OrderProcedures`, `PaymentProcedures`
+- **By access level**: `PublicRPC`, `AuthenticatedRPC`, `AdminRPC`
+- **By transport**: `StandardRPC` (Create), `StreamRPC` (CreateStream)
+- Each group gets its own `Procedures<Context, Config>()` factory
+
+### Error handling strategy?
+
+| Layer | Mechanism |
+|-------|-----------|
+| Input validation | Automatic via `schema.params` — throws `ProcedureValidationError` |
+| Business logic errors | `ctx.error(message, meta?)` — throws `ProcedureError` |
+| Unexpected errors | Automatically wrapped in `ProcedureError` with stack enhancement |
+| HTTP error responses | `onError` callback in HTTP builder config |
+| Mid-stream errors | `onMidStreamError` callback in `HonoStreamAppBuilder` |
+
+## 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** — Express, Hono, or both
+7. **Plan error handling** — which layer for each error type
+8. **Map route structure** — scope + version → URL paths
+
+## 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.
+- `getProcedures()` returns all registered procedures for introspection (OpenAPI generation, testing, etc.).
+- AJV is configured with `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`.
+
+## 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
+- ExpressRPCAppBuilder for standard RPC
+- HonoStreamAppBuilder for streaming (SSE mode)
+- Path prefix: /api
+
+### Route Map
+- POST /api/health/health-check/1
+- POST /api/users/get-user/1
+- GET|POST /api/activity/stream-activity/1
+
+### Error Handling
+- Input validation: automatic (schema.params)
+- Auth failures: ctx.error('Unauthorized', { code: 401 })
+- Not found: ctx.error('User not found', { code: 404 })
+- Stream errors: onMidStreamError → yield error event, close stream
+```