ts-procedures 5.2.0 → 5.4.0

package/README.md

@@ -71,6 +71,41 @@ Create(name, config, handler)
 - `procedure` - Generic reference to the handler
 - `info` - Procedure meta (name, description, schema, `TExtendedConfig` properties, etc.)
 
+### Structured Input with schema.input
+
+For HTTP APIs and other multi-channel transports, `schema.input` provides per-channel type safety. Each key is an independently validated input channel:
+
+```typescript
+const { Create } = Procedures<AppContext, APIConfig>()
+
+const { UpdateUser } = Create(
+  'UpdateUser',
+  {
+    path: '/users/:id',
+    method: 'put',
+    schema: {
+      input: {
+        pathParams: Type.Object({ id: Type.String() }),
+        query: Type.Object({ notify: Type.Optional(Type.Boolean()) }),
+        body: Type.Object({ name: Type.String(), email: Type.String() }),
+      },
+      returnType: Type.Object({ ok: Type.Boolean() }),
+    },
+  },
+  async (ctx, { pathParams, query, body }) => {
+    // Each channel is independently typed and validated
+    await updateUser(pathParams.id, body)
+    if (query.notify) await sendNotification(pathParams.id)
+    return { ok: true }
+  }
+)
+```
+
+**Rules:**
+- `schema.input` and `schema.params` are **mutually exclusive** — defining both throws `ProcedureRegistrationError`
+- Each channel is validated independently with per-channel error messages
+- Works with both `Create` and `CreateStream`
+
 ### CreateStream Function
 
 The `CreateStream` function defines streaming procedures that yield values over time using async generators:
@@ -625,6 +660,54 @@ app.listen(3000)
 
 See [Express RPC Integration Guide](src/implementations/http/express-rpc/README.md) for complete setup instructions including lifecycle hooks, error handling, and route documentation.
 
+### Hono API Integration
+
+`ts-procedures` includes a REST-style HTTP integration for Hono that routes by HTTP method with per-channel input validation via `schema.input`.
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import type { APIConfig } from 'ts-procedures/http'
+import { Type } from 'typebox'
+
+const API = Procedures<{ userId: string }, APIConfig>()
+
+API.Create('GetUser', {
+  path: '/users/:id',
+  method: 'get',
+  schema: {
+    input: {
+      pathParams: Type.Object({ id: Type.String() }),
+    },
+    returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+  },
+}, async (ctx, { pathParams }) => {
+  return await fetchUser(pathParams.id)
+})
+
+API.Create('CreateUser', {
+  path: '/users',
+  method: 'post',
+  schema: {
+    input: {
+      body: Type.Object({ name: Type.String(), email: Type.String() }),
+    },
+  },
+}, async (ctx, { body }) => {
+  return await createUser(body)
+})
+
+const app = await new HonoAPIAppBuilder({ pathPrefix: '/api' })
+  .register(API, (c) => ({ userId: c.req.header('x-user-id') || 'anonymous' }))
+  .build()
+
+// Routes:
+// GET  /api/users/:id  → 200
+// POST /api/users      → 201
+```
+
+See [Hono API Integration Guide](src/implementations/http/hono-api/) for complete setup.
+
 ### Introspection with getProcedures()
 
 Access all registered procedures for documentation or routing:
@@ -769,8 +852,75 @@ import {
   TSchemaValidationError,
   Prettify,
 } from 'ts-procedures'
+
+// HTTP types
+import type { RPCConfig, RPCHttpRouteDoc, StreamHttpRouteDoc, StreamMode, APIConfig, APIHttpRouteDoc, APIInput, HttpMethod } from 'ts-procedures/http'
+
+// Hono API (REST-style)
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import type { APIConfig, APIHttpRouteDoc, APIInput, HttpMethod, QueryParser } from 'ts-procedures/hono-api'
+```
+
+## 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."
+}