ts-procedures 5.1.0 → 5.3.0

package/README.md

@@ -90,9 +90,11 @@ CreateStream(name, config, handler)
 async function* (ctx, params) => AsyncGenerator<TYield, TReturn | void>
 ```
 
-**Context Extensions:**
+**Context Extensions (all handlers):**
 - `ctx.error(message, meta?)` - Create a ProcedureError
-- `ctx.signal` - AbortSignal for cancellation support
+- `ctx.signal?` - AbortSignal for cancellation support (optional for `Create`, always present for `CreateStream`)
+
+When using the built-in HTTP implementations (Hono, Express), `ctx.signal` is automatically injected from the HTTP request, so handlers can detect client disconnection. For direct usage without a server, `signal` is `undefined` unless you pass one in context.
 
 **Returns:**
 - `{ [name]: handler }` - Named generator export
@@ -366,7 +368,9 @@ const { ValidatedStream } = CreateStream(
 
 ### Abort Signal Integration
 
-The `ctx.signal` allows handlers to detect when consumers stop iterating:
+#### Streaming Procedures
+
+The `ctx.signal` allows stream handlers to detect when consumers stop iterating. After completion, `signal.reason` indicates why the stream ended:
 
 ```typescript
 const { CancellableStream } = CreateStream(
@@ -378,7 +382,12 @@ const { CancellableStream } = CreateStream(
         yield await fetchNextItem()
       }
     } finally {
-      // Cleanup when stream ends (consumer stopped or completed)
+      // Distinguish normal completion from client disconnect
+      if (ctx.signal.reason === 'stream-completed') {
+        // Stream finished normally
+      } else {
+        // Client disconnected or external abort
+      }
       await cleanup()
     }
   },
@@ -390,6 +399,28 @@ for await (const item of CancellableStream({}, {})) {
 }
 ```
 
+#### Regular Procedures
+
+For regular procedures, `ctx.signal` is available when the server implementation provides it. The built-in HTTP integrations (Hono RPC, Express RPC) inject the request's abort signal automatically:
+
+```typescript
+const { Create } = Procedures<{ signal: AbortSignal }>()
+
+const { LongQuery } = Create(
+  'LongQuery',
+  {},
+  async (ctx, params) => {
+    // Pass signal to downstream operations
+    const result = await fetch('https://api.example.com/data', {
+      signal: ctx.signal,
+    })
+    return result.json()
+  },
+)
+```
+
+When using the Hono or Express implementations, `ctx.signal` aborts when the client disconnects, automatically cancelling in-flight `fetch()` calls, database queries, or any other signal-aware operation.
+
 ### SSE Integration Example
 
 ```typescript
@@ -719,7 +750,7 @@ import {
 
   // Types
   TLocalContext,
-  TStreamContext,               // Streaming context with AbortSignal
+  TStreamContext,               // Streaming context (AbortSignal always present)
   TProcedureRegistration,
   TStreamProcedureRegistration, // Streaming procedure registration
   TNoContextProvided,
@@ -740,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."
+}