runspec-node 0.3.0 → 0.8.0

package/src/cli.ts

@@ -1,28 +1,38 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import * as readline from 'readline';
 import { findConfig } from './finder';
 import { loadRaw } from './loader';
 import { inferScript } from './inference';
-import type { ScriptSpec, ArgSpec } from './models';
+import { parse } from './parser';
+import type { ScriptSpec, ArgSpec, JumpHostConfig } from './models';
+
+const _CLI_CONFIG = path.join(__dirname, 'runspec.toml');
 
 // ── Entry point ───────────────────────────────────────────────────────────────
 
 export function main(): void {
   const args = process.argv.slice(2);
 
-  if (!args.length || args[0] === '-h' || args[0] === '--help') {
-    printHelp();
+  const command = args[0];
+  const rest = args.slice(1);
+
+  // Per-subcommand help
+  const preHelpArgs = args.includes('--') ? args.slice(0, args.indexOf('--')) : args;
+  if (command && command !== '-h' && command !== '--help' && (preHelpArgs.includes('-h') || preHelpArgs.includes('--help'))) {
+    printCommandHelp(command);
     return;
   }
 
-  const command = args[0];
-  const rest = args.slice(1);
+  if (!args.length || command === '-h' || command === '--help') {
+    printHelp();
+    return;
+  }
 
-  const commands: Record<string, (args: string[]) => void> = {
+  const commands: Record<string, (args: string[]) => void | Promise<void>> = {
     init: cmdInit,
-    discover: cmdDiscover,
-    check: cmdCheck,
-    emit: cmdEmit,
+    local: cmdLocal,
+    jump: cmdJump,
     serve: cmdServe,
   };
 
@@ -32,47 +42,69 @@ export function main(): void {
     process.exit(1);
   }
 
-  commands[command](rest);
+  const result = commands[command](rest);
+  if (result instanceof Promise) {
+    result.catch((err: unknown) => {
+      process.stderr.write(`✗  ${err instanceof Error ? err.message : String(err)}\n`);
+      process.exit(1);
+    });
+  }
 }
 
 // ── Commands ──────────────────────────────────────────────────────────────────
 
 function cmdInit(args: string[]): void {
   const nameFlag = getFlag(args, '--name');
-  const fileFlag = getFlag(args, '--file');
+  const langFlag = getFlag(args, '--lang') ?? 'typescript';
+  const example = args.includes('--example');
 
   const cwd = process.cwd();
-  const runnableName = nameFlag ?? sanitizeName(path.basename(cwd));
-
-  const pyproject = path.join(cwd, 'pyproject.toml');
   const runspecToml = path.join(cwd, 'runspec.toml');
 
-  if (fileFlag === 'runspec') {
-    initRunspecToml(runspecToml, runnableName);
-  } else if (fileFlag === 'pyproject' || fs.existsSync(pyproject)) {
-    initPyproject(pyproject, runnableName);
-  } else {
-    initRunspecToml(runspecToml, runnableName);
+  if (example) {
+    if (nameFlag) {
+      console.log('  ℹ  --name is ignored with --example (runnables are always clean and scan)');
+    }
+    initExampleToml(runspecToml);
+    initExampleStubs(cwd, langFlag);
+    printNextSteps(cwd, true);
+    return;
   }
+
+  const runnableName = nameFlag ?? sanitizeName(path.basename(cwd));
+  initRunspecToml(runspecToml, runnableName);
+  initCodeStub(cwd, runnableName, langFlag);
+  printNextSteps(cwd, false);
 }
 
-function cmdDiscover(args: string[]): void {
+function cmdLocal(args: string[]): void {
   const fmt = getFlag(args, '--format') ?? 'text';
+  const scriptName = getFlag(args, '--script');
 
   const discovered = discoverLocal();
 
   if (!discovered.length) {
     console.log('No runspec-aware runnables found in this environment.');
-    console.log('Add a [tool.runspec.yourname] section to pyproject.toml or create runspec.toml');
+    console.log("Create a runspec.toml inside your package directory and run 'runspec init' to get started.");
     return;
   }
 
+  // Filter to single runnable if --script given
+  const filtered = scriptName
+    ? discovered.filter((d) => d.runnable === scriptName)
+    : discovered;
+
+  if (scriptName && !filtered.length) {
+    console.log(`✗  Runnable '${scriptName}' not found`);
+    process.exit(1);
+  }
+
   if (fmt === 'text') {
-    printDiscoverText(discovered);
+    printLocalText(filtered);
   } else if (fmt === 'json') {
-    console.log(JSON.stringify(discovered, null, 2));
+    console.log(JSON.stringify(filtered, null, 2));
   } else if (['mcp', 'openai', 'anthropic'].includes(fmt)) {
-    console.log(JSON.stringify(emitAll(discovered, fmt), null, 2));
+    console.log(JSON.stringify(emitAll(filtered, fmt), null, 2));
   } else {
     console.log(`✗  Unknown format: ${fmt}`);
     console.log('   Available formats: text, json, mcp, openai, anthropic');
@@ -80,102 +112,116 @@ function cmdDiscover(args: string[]): void {
   }
 }
 
-function cmdCheck(args: string[]): void {
-  let configPath: string;
-  let format: 'pyproject' | 'runspec';
+async function cmdJump(args: string[]): Promise<void> {
+  const parsed = parse({ scriptName: 'runspec', argv: ['jump', ...args], configPath: _CLI_CONFIG });
+  const listHosts = Boolean(parsed['list_jump_hosts']);
+  const fmt = String(parsed['format'] ?? 'text');
 
-  try {
-    ({ configPath, format } = findConfig(process.cwd()));
-  } catch (e) {
-    console.log((e as Error).message);
+  if (listHosts) {
+    cmdListJumpHosts(fmt);
+    return;
+  }
+
+  const hostName = parsed['jump_host'] as string | undefined;
+  if (!hostName) {
+    process.stderr.write('✗  A jump host name is required\n');
+    process.stderr.write('   Usage: runspec jump <jump-host> [<tool>] [-- tool-args...]\n');
+    process.stderr.write("   Run 'runspec jump --list-jump-hosts' to see configured jump hosts\n");
     process.exit(1);
   }
 
-  const raw = loadRaw(configPath, format);
-  const errors: string[] = [];
-  const warnings: string[] = [];
-  const ok: string[] = [];
+  const hostCfg = loadJumpHost(hostName);
+  const toolName = parsed['tool'] as string | undefined;
 
-  ok.push(`Config found: ${configPath}`);
+  const { listTools, callTool } = await import('./jump');
 
-  if (format === 'pyproject') {
-    const eps = raw.entryPoints;
-    if (Object.keys(eps).length > 0) {
-      ok.push(`[project.scripts] found — ${Object.keys(eps).length} entry point(s)`);
-    } else {
-      warnings.push('No [project.scripts] found — agents may not discover runnables automatically\n  Add entry points to pyproject.toml or use runspec.toml');
+  if (!toolName) {
+    const tools = await listTools(hostCfg);
+    if (!tools.length) {
+      console.log(`No tools found on ${hostName}.`);
+      return;
+    }
+    console.log(`Tools on ${hostName}:\n`);
+    for (const tool of tools) {
+      const name = String(tool['name'] ?? '').padEnd(24);
+      const desc = String(tool['description'] ?? '');
+      console.log(`  ${name} ${desc}`);
     }
+    return;
   }
 
-  if ('config' in raw.runnables) {
-    errors.push("'config' is a reserved name — rename your runnable to something else");
-  }
+  const toolArgv = (parsed['tool_args'] as string[] | undefined) ?? [];
+  await callTool(hostCfg, toolName, toolArgv);
+}
 
-  for (const [name, runnable] of Object.entries(raw.runnables)) {
-    if (!runnable.description) {
-      warnings.push(`'${name}' has no description — agents won't know what it does`);
-    } else {
-      ok.push(`'${name}' — description present`);
-    }
+function cmdListJumpHosts(fmt: string): void {
+  let configPath: string;
+  try {
+    ({ configPath } = findConfig(process.cwd()));
+  } catch {
+    process.stderr.write('✗  No runspec.toml found — cannot look up jump hosts\n');
+    process.exit(1);
+  }
 
-    if (!runnable.autonomy) {
-      warnings.push(`'${name}' autonomy not declared — will default to '${raw.config.autonomyDefault}'`);
-    } else {
-      ok.push(`'${name}' — autonomy: ${runnable.autonomy}`);
-    }
+  const raw = loadRaw(configPath);
+  const hosts = raw.config.jumpHosts ?? {};
 
-    for (const [argName, arg] of Object.entries(runnable.args ?? {})) {
-      if (!arg.description && arg.required) {
-        warnings.push(`'${name}.${argName}' is required but has no description`);
-      }
-    }
+  if (!Object.keys(hosts).length) {
+    console.log('No jump hosts configured.');
+    console.log('Add [config.jump-hosts.<name>] sections to your runspec.toml.');
+    return;
   }
 
-  for (const msg of ok) console.log(`  ✓  ${msg}`);
-  for (const msg of warnings) console.log(`  ℹ  ${msg}`);
-  for (const msg of errors) console.log(`  ✗  ${msg}`);
+  const { resolveBinRaw } = require('./jump') as { resolveBinRaw: (h: JumpHostConfig) => string };
 
-  if (errors.length) process.exit(1);
-  else if (!warnings.length) console.log('\n  All checks passed.');
-}
+  if (fmt === 'json') {
+    const effective = Object.entries(hosts).map(([name, cfg]) => ({
+      name,
+      ...cfg,
+      bin: resolveBinRaw(cfg),
+    }));
+    console.log(JSON.stringify(effective, null, 2));
+    return;
+  }
 
-function cmdEmit(args: string[]): void {
-  const scriptName = getFlag(args, '--script');
-  const fmt = getFlag(args, '--format') ?? 'mcp';
+  console.log('Configured jump hosts:\n');
+  for (const [name, cfg] of Object.entries(hosts)) {
+    const effectiveBin = resolveBinRaw(cfg);
+    console.log(`  ${name.padEnd(20)} ${cfg.host}  (bin: ${effectiveBin})`);
+  }
+}
 
+function loadJumpHost(name: string): JumpHostConfig {
   let configPath: string;
-  let format: 'pyproject' | 'runspec';
-
   try {
-    ({ configPath, format } = findConfig(process.cwd()));
-  } catch (e) {
-    console.log((e as Error).message);
+    ({ configPath } = findConfig(process.cwd()));
+  } catch {
+    process.stderr.write(`✗  No runspec.toml found — cannot look up jump host '${name}'\n`);
     process.exit(1);
   }
 
-  const raw = loadRaw(configPath, format);
-  const config = raw.config;
-
-  let runnables = raw.runnables;
-  if (scriptName) {
-    if (!(scriptName in runnables)) {
-      console.log(`✗  Runnable '${scriptName}' not found`);
-      process.exit(1);
-    }
-    runnables = { [scriptName]: runnables[scriptName] };
-  }
+  const raw = loadRaw(configPath!);
+  const hosts = raw.config.jumpHosts ?? {};
 
-  const schema: Record<string, unknown> = {};
-  for (const [name, runnable] of Object.entries(runnables)) {
-    const inferred = inferScript(runnable, config.autonomyDefault);
-    schema[name] = buildSchema(name, inferred, fmt);
+  if (!(name in hosts)) {
+    const available = Object.keys(hosts).join(', ') || '(none)';
+    process.stderr.write(`✗  Jump host '${name}' not found in runspec.toml\n`);
+    process.stderr.write(`   Configured jump hosts: ${available}\n`);
+    process.exit(1);
   }
 
-  const output = fmt === 'mcp' ? { tools: Object.values(schema) } : schema;
-  console.log(JSON.stringify(output, null, 2));
+  return hosts[name]!;
 }
 
 function cmdServe(_args: string[]): void {
+  if (process.stdin.isTTY) {
+    console.log('runspec serve is an MCP stdio server — it is not run directly from a terminal.');
+    console.log('Configure it as an MCP server in your MCP host (Claude Desktop, VS Code, PyCharm, etc.)');
+    console.log();
+    console.log('To test manually:');
+    console.log('  echo \'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}\' | runspec serve');
+    return;
+  }
   const { serve } = require('./serve') as { serve: () => void };
   serve();
 }
@@ -233,8 +279,8 @@ function argToJsonSchema(arg: ArgSpec): Record<string, unknown> {
 
 function discoverLocal(): Array<{ source: string; runnable: string; spec: ScriptSpec }> {
   try {
-    const { configPath, format } = findConfig(process.cwd());
-    const raw = loadRaw(configPath, format);
+    const { configPath } = findConfig(process.cwd());
+    const raw = loadRaw(configPath);
     return Object.entries(raw.runnables).map(([name, spec]) => ({ source: configPath, runnable: name, spec }));
   } catch {
     return [];
@@ -247,18 +293,43 @@ function emitAll(discovered: Array<{ source: string; runnable: string; spec: Scr
   return Object.fromEntries(tools.map((t) => [t['name'], t]));
 }
 
-function printDiscoverText(discovered: Array<{ source: string; runnable: string; spec: ScriptSpec }>): void {
-  const bySource: Record<string, string[]> = {};
+function printLocalText(discovered: Array<{ source: string; runnable: string; spec: ScriptSpec }>): void {
+  const bySource: Record<string, Array<{ runnable: string; spec: ScriptSpec }>> = {};
   for (const item of discovered) {
-    (bySource[item.source] ??= []).push(item.runnable);
+    (bySource[item.source] ??= []).push({ runnable: item.runnable, spec: item.spec });
   }
-  console.log(`Found ${discovered.length} runspec-aware runnable(s):\n`);
-  for (const [source, runnables] of Object.entries(bySource)) {
+
+  const warnings: string[] = [];
+  const errors: string[] = [];
+
+  console.log(`Found ${discovered.length} runspec runnable(s):\n`);
+  for (const [source, items] of Object.entries(bySource)) {
     console.log(`  ${source}`);
-    for (const r of runnables) console.log(`    • ${r}`);
+    for (const { runnable: name, spec } of items) {
+      const desc = spec.description ?? '';
+      const autonomy = spec.autonomy ?? 'confirm';
+      const truncated = desc.length > 48 ? desc.slice(0, 48) : desc;
+      console.log(`    ${name.padEnd(24)} ${truncated.padEnd(50)}  [${autonomy}]`);
+
+      if (!spec.description) warnings.push(`'${name}' has no description — agents won't know what it does`);
+      if (!spec.autonomy) warnings.push(`'${name}' autonomy not declared — defaulting to 'confirm'`);
+      for (const [argName, arg] of Object.entries(spec.args ?? {})) {
+        if (!arg.description && arg.required) {
+          warnings.push(`'${name}.${argName}' is required but has no description`);
+        }
+      }
+    }
+    console.log();
   }
-  console.log();
-  console.log("Run 'runspec discover --format mcp' to emit MCP tool schemas.");
+
+  if (warnings.length || errors.length) {
+    console.log('Issues:\n');
+    for (const msg of warnings) console.log(`  ℹ  ${msg}`);
+    for (const msg of errors) console.log(`  ✗  ${msg}`);
+    console.log();
+  }
+
+  console.log("Run 'runspec local --format mcp' to emit MCP tool schemas.");
 }
 
 // ── Init helpers ──────────────────────────────────────────────────────────────
@@ -268,55 +339,117 @@ function sanitizeName(raw: string): string {
   return s || 'myscript';
 }
 
-function initPyproject(filePath: string, name: string): void {
+function initRunspecToml(filePath: string, name: string): void {
   if (fs.existsSync(filePath)) {
-    const original = fs.readFileSync(filePath, 'utf-8');
-    let data: Record<string, unknown>;
-    try {
-      const { parse } = require('smol-toml') as { parse: (s: string) => unknown };
-      data = parse(original) as Record<string, unknown>;
-    } catch (e) {
-      console.log(`✗  Could not read ${path.basename(filePath)}: ${(e as Error).message}`);
-      process.exit(1);
-    }
-
-    if ('runspec' in ((data as any)?.tool ?? {})) {
-      const existing = Object.keys((data as any).tool.runspec).filter(
-        (k) => k !== 'config' && typeof (data as any).tool.runspec[k] === 'object',
-      );
-      console.log(`✗  ${path.basename(filePath)} already has [tool.runspec] — already initialized`);
-      if (existing.length) console.log(`   Existing runnables: ${existing.join(', ')}`);
-      process.exit(1);
-    }
-
-    const content = original.trimEnd() + '\n\n' + pyprojectBlock(name);
-    writeAndVerify(filePath, content, original);
-    console.log(`  ✓  Updated ${path.basename(filePath)} with [${name}] runnable`);
-  } else {
-    const content = pyprojectBlock(name);
-    writeAndVerify(filePath, content, null);
-    console.log(`  ✓  Created ${path.basename(filePath)} with [${name}] runnable`);
+    console.log(`✗  ${path.basename(filePath)} already exists — already initialized`);
+    console.log(`   Edit ${path.basename(filePath)} directly to add more runnables.`);
+    process.exit(1);
   }
-  console.log("     Run 'runspec check' to validate.");
+  const content = `#:schema https://raw.githubusercontent.com/JasonFinestone/runspec/main/schema/runspec.schema.json\n\n[${name}]\ndescription = "Describe what ${name} does"\nautonomy    = "confirm"\n\n[${name}.args]\n# example = {type = "str", description = "An example argument"}\n`;
+  writeAndVerify(filePath, content, null);
+  console.log(`  ✓  Created runspec.toml with [${name}] runnable`);
 }
 
-function initRunspecToml(filePath: string, name: string): void {
+function initExampleToml(filePath: string): void {
   if (fs.existsSync(filePath)) {
     console.log(`✗  ${path.basename(filePath)} already exists — already initialized`);
     console.log(`   Edit ${path.basename(filePath)} directly to add more runnables.`);
     process.exit(1);
   }
-  writeAndVerify(filePath, runspecTomlBlock(name), null);
-  console.log(`  ✓  Created ${path.basename(filePath)} with [${name}] runnable`);
-  console.log("     Run 'runspec check' to validate.");
+  const content = [
+    '#:schema https://raw.githubusercontent.com/JasonFinestone/runspec/main/schema/runspec.schema.json',
+    '',
+    '[clean]',
+    'description = "Find and optionally delete stale temporary files in a directory"',
+    'autonomy    = "confirm"',
+    '',
+    '[clean.args]',
+    'directory  = {type = "path",   description = "Directory to scan",                            default = "."}',
+    'pattern    = {type = "str",    description = "Glob pattern to match",                        default = "*.tmp"}',
+    'older_than = {type = "int",    description = "Only match files older than N days",           default = 7}',
+    'format     = {type = "choice", description = "Output format", options = ["text", "json"],    default = "text"}',
+    'delete     = {type = "flag",   description = "Delete matched files (asks for confirmation)", default = false}',
+    '',
+    '[scan]',
+    'description = "Scan for stale temporary files and report what clean would delete"',
+    'autonomy    = "autonomous"',
+    'output      = "json"',
+    '',
+    '[scan.args]',
+    'directory  = {type = "path", description = "Directory to scan",                default = "."}',
+    'pattern    = {type = "str",  description = "Glob pattern to match",             default = "*.tmp"}',
+    'older_than = {type = "int",  description = "Only match files older than N days", default = 7}',
+    '',
+  ].join('\n');
+  writeAndVerify(filePath, content, null);
+  console.log('  ✓  Created runspec.toml with [clean] and [scan] runnables');
 }
 
-function pyprojectBlock(name: string): string {
-  return `[tool.runspec.${name}]\ndescription = "Describe what ${name} does"\nautonomy    = "confirm"\n\n[tool.runspec.${name}.args]\n# example = {type = "str", description = "An example argument"}\n`;
+function initExampleStubs(dir: string, lang: string): void {
+  if (lang === 'typescript') {
+    writeStubIfMissing(path.join(dir, 'clean.ts'), CLEAN_TS_STUB);
+    writeStubIfMissing(path.join(dir, 'scan.ts'), SCAN_TS_STUB);
+  } else if (lang === 'javascript') {
+    writeStubIfMissing(path.join(dir, 'clean.js'), CLEAN_JS_STUB);
+    writeStubIfMissing(path.join(dir, 'scan.js'), SCAN_JS_STUB);
+  } else if (lang === 'python') {
+    writeStubIfMissing(path.join(dir, 'clean.py'), CLEAN_PY_STUB);
+    writeStubIfMissing(path.join(dir, 'scan.py'), SCAN_PY_STUB);
+  } else {
+    console.log(`✗  Unknown --lang: ${lang}`);
+    console.log('   Supported: typescript (default), javascript, python');
+    process.exit(1);
+  }
+}
+
+function writeStubIfMissing(filePath: string, content: string): void {
+  if (fs.existsSync(filePath)) {
+    console.log(`  ℹ  ${path.basename(filePath)} already exists — skipped`);
+  } else {
+    fs.writeFileSync(filePath, content, 'utf-8');
+    console.log(`  ✓  Created ${path.basename(filePath)}`);
+  }
+}
+
+function initCodeStub(dir: string, name: string, lang: string): void {
+  const templates: Record<string, { ext: string; content: string }> = {
+    typescript: { ext: '.ts', content: `import { parse } from 'runspec-node';\n\nfunction main(): void {\n  const args = parse();\n  // your logic here\n}\n\nmain();\n` },
+    javascript: { ext: '.js', content: `const { parse } = require('runspec-node');\n\nfunction main() {\n  const args = parse();\n  // your logic here\n}\n\nmain();\n` },
+    python:     { ext: '.py', content: `from runspec import parse\n\n\ndef main():\n    args = parse()\n    # your logic here\n\n\nif __name__ == "__main__":\n    main()\n` },
+  };
+
+  const template = templates[lang];
+  if (!template) {
+    console.log(`✗  Unknown --lang: ${lang}`);
+    console.log('   Supported: typescript, javascript, python');
+    process.exit(1);
+  }
+
+  const filePath = path.join(dir, name + template.ext);
+  writeStubIfMissing(filePath, template.content);
 }
 
-function runspecTomlBlock(name: string): string {
-  return `[${name}]\ndescription = "Describe what ${name} does"\nautonomy    = "confirm"\n\n[${name}.args]\n# example = {type = "str", description = "An example argument"}\n`;
+function printNextSteps(cwd: string, example: boolean): void {
+  const pkgJson = path.join(cwd, 'package.json');
+  const hasPkg = fs.existsSync(pkgJson);
+
+  console.log('\nNext steps:\n');
+  if (!hasPkg) {
+    console.log('  1. npm init -y');
+    console.log('  2. npm install runspec-node');
+  } else {
+    console.log('  1. npm install runspec-node');
+  }
+  console.log(`  ${hasPkg ? '2' : '3'}. runspec local`);
+
+  if (example) {
+    console.log('\nDemo prep — pre-date some files to trigger the example:');
+    console.log('  touch -t 202401010000 report.tmp cache.tmp session.tmp');
+    console.log('\nThen try:');
+    console.log('  npx ts-node scan.ts                 # agent-ready JSON output');
+    console.log('  npx ts-node clean.ts --delete       # prompts for confirmation');
+    console.log('  npx ts-node clean.ts --format json  # structured output');
+  }
 }
 
 function writeAndVerify(filePath: string, content: string, original: string | null): void {
@@ -333,6 +466,210 @@ function writeAndVerify(filePath: string, content: string, original: string | nu
   }
 }
 
+// ── Example stubs ─────────────────────────────────────────────────────────────
+
+const CLEAN_TS_STUB = `import * as fs from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+import { parse } from 'runspec-node';
+
+async function main(): Promise<void> {
+  const args = parse();
+
+  const cutoff = Date.now() - Number(args.older_than) * 86400 * 1000;
+  const dir = String(args.directory);
+  const pattern = String(args.pattern).replace('*', '');
+  const matches = fs.readdirSync(dir)
+    .map((f) => path.join(dir, f))
+    .filter((f) => f.endsWith(pattern) && fs.statSync(f).isFile() && fs.statSync(f).mtimeMs < cutoff);
+
+  if (!matches.length) {
+    console.log(\`No '\${args.pattern}' files older than \${args.older_than} days found in \${args.directory}.\`);
+    return;
+  }
+
+  if (String(args.format) === 'json') {
+    const data = matches.map((f) => ({ path: f, size: fs.statSync(f).size, days_old: Math.floor((Date.now() - fs.statSync(f).mtimeMs) / 86400000) }));
+    console.log(JSON.stringify(data, null, 2));
+  } else {
+    console.log(\`Found \${matches.length} file(s) matching '\${args.pattern}' older than \${args.older_than} days:\`);
+    console.log();
+    for (const f of matches) {
+      const days = Math.floor((Date.now() - fs.statSync(f).mtimeMs) / 86400000);
+      console.log(\`  \${f}  (\${fs.statSync(f).size.toLocaleString()} bytes, \${days}d old)\`);
+    }
+  }
+
+  if (args.delete) {
+    if (!args.__runspec_agent__) {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await new Promise<string>((resolve) => rl.question(\`\\nDelete \${matches.length} file(s)? [y/N] \`, resolve));
+      rl.close();
+      if (answer.trim().toLowerCase() !== 'y') {
+        console.log('Aborted.');
+        return;
+      }
+    }
+    for (const f of matches) fs.unlinkSync(f);
+    console.log(\`\\nDeleted \${matches.length} file(s).\`);
+  }
+}
+
+main();
+`;
+
+const SCAN_TS_STUB = `import * as fs from 'fs';
+import * as path from 'path';
+import { parse } from 'runspec-node';
+
+function main(): void {
+  const args = parse();
+
+  const cutoff = Date.now() - Number(args.older_than) * 86400 * 1000;
+  const dir = String(args.directory);
+  const pattern = String(args.pattern).replace('*', '');
+  const matches = fs.readdirSync(dir)
+    .map((f) => path.join(dir, f))
+    .filter((f) => f.endsWith(pattern) && fs.statSync(f).isFile() && fs.statSync(f).mtimeMs < cutoff);
+
+  const data = matches.map((f) => ({ path: f, size: fs.statSync(f).size, days_old: Math.floor((Date.now() - fs.statSync(f).mtimeMs) / 86400000) }));
+  console.log(JSON.stringify(data, null, 2));
+}
+
+main();
+`;
+
+const CLEAN_JS_STUB = `const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { parse } = require('runspec-node');
+
+async function main() {
+  const args = parse();
+
+  const cutoff = Date.now() - Number(args.older_than) * 86400 * 1000;
+  const dir = String(args.directory);
+  const pattern = String(args.pattern).replace('*', '');
+  const matches = fs.readdirSync(dir)
+    .map((f) => path.join(dir, f))
+    .filter((f) => f.endsWith(pattern) && fs.statSync(f).isFile() && fs.statSync(f).mtimeMs < cutoff);
+
+  if (!matches.length) {
+    console.log(\`No '\${args.pattern}' files older than \${args.older_than} days found in \${args.directory}.\`);
+    return;
+  }
+
+  if (String(args.format) === 'json') {
+    const data = matches.map((f) => ({ path: f, size: fs.statSync(f).size, days_old: Math.floor((Date.now() - fs.statSync(f).mtimeMs) / 86400000) }));
+    console.log(JSON.stringify(data, null, 2));
+  } else {
+    console.log(\`Found \${matches.length} file(s) matching '\${args.pattern}' older than \${args.older_than} days:\`);
+    for (const f of matches) {
+      const days = Math.floor((Date.now() - fs.statSync(f).mtimeMs) / 86400000);
+      console.log(\`  \${f}  (\${fs.statSync(f).size.toLocaleString()} bytes, \${days}d old)\`);
+    }
+  }
+
+  if (args.delete) {
+    if (!args.__runspec_agent__) {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await new Promise((resolve) => rl.question(\`\\nDelete \${matches.length} file(s)? [y/N] \`, resolve));
+      rl.close();
+      if (answer.trim().toLowerCase() !== 'y') { console.log('Aborted.'); return; }
+    }
+    for (const f of matches) fs.unlinkSync(f);
+    console.log(\`\\nDeleted \${matches.length} file(s).\`);
+  }
+}
+
+main();
+`;
+
+const SCAN_JS_STUB = `const fs = require('fs');
+const path = require('path');
+const { parse } = require('runspec-node');
+
+function main() {
+  const args = parse();
+
+  const cutoff = Date.now() - Number(args.older_than) * 86400 * 1000;
+  const dir = String(args.directory);
+  const pattern = String(args.pattern).replace('*', '');
+  const matches = fs.readdirSync(dir)
+    .map((f) => path.join(dir, f))
+    .filter((f) => f.endsWith(pattern) && fs.statSync(f).isFile() && fs.statSync(f).mtimeMs < cutoff);
+
+  const data = matches.map((f) => ({ path: f, size: fs.statSync(f).size, days_old: Math.floor((Date.now() - fs.statSync(f).mtimeMs) / 86400000) }));
+  console.log(JSON.stringify(data, null, 2));
+}
+
+main();
+`;
+
+const CLEAN_PY_STUB = `import json
+import sys
+import time
+
+from runspec import parse
+
+
+def main():
+    args = parse()
+
+    cutoff = time.time() - args.older_than * 86400
+    matches = [p for p in args.directory.glob(args.pattern) if p.is_file() and p.stat().st_mtime < cutoff]
+
+    if not matches:
+        print(f"No '{args.pattern}' files older than {args.older_than} days found in {args.directory}.")
+        return
+
+    if args.format == "json":
+        data = [{"path": str(p), "size": p.stat().st_size, "days_old": int((time.time() - p.stat().st_mtime) / 86400)} for p in matches]
+        print(json.dumps(data, indent=2))
+    else:
+        print(f"Found {len(matches)} file(s) matching '{args.pattern}' older than {args.older_than} days:")
+        print()
+        for p in matches:
+            days = int((time.time() - p.stat().st_mtime) / 86400)
+            print(f"  {p}  ({p.stat().st_size:,} bytes, {days}d old)")
+
+    if args.delete:
+        if not args.__runspec_agent__:
+            print()
+            confirm = input(f"Delete {len(matches)} file(s)? [y/N] ")
+            if confirm.strip().lower() != "y":
+                print("Aborted.")
+                return
+        for p in matches:
+            p.unlink()
+        print()
+        print(f"Deleted {len(matches)} file(s).")
+
+
+if __name__ == "__main__":
+    main()
+`;
+
+const SCAN_PY_STUB = `import json
+import time
+
+from runspec import parse
+
+
+def main():
+    args = parse()
+
+    cutoff = time.time() - args.older_than * 86400
+    matches = [p for p in args.directory.glob(args.pattern) if p.is_file() and p.stat().st_mtime < cutoff]
+
+    data = [{"path": str(p), "size": p.stat().st_size, "days_old": int((time.time() - p.stat().st_mtime) / 86400)} for p in matches]
+    print(json.dumps(data, indent=2))
+
+
+if __name__ == "__main__":
+    main()
+`;
+
 // ── Arg parser helper ─────────────────────────────────────────────────────────
 
 function getFlag(args: string[], flag: string): string | undefined {
@@ -350,29 +687,66 @@ Usage:
   runspec <command> [options]
 
 Commands:
-  init        Create or update pyproject.toml or runspec.toml with a scaffold
-  discover    Find all runspec-aware runnables in this environment
-  check       Validate this project's runspec setup
-  emit        Emit tool schemas for agent frameworks
-  serve       Start the MCP stdio server for this environment
+  init        Create runspec.toml and a code stub
+  local       List runnables and emit tool schemas
+  jump        Execute a runnable on a remote host via SSH
+  serve       Start the MCP stdio server for local runnables
 
-Options for init:
-  --name      Runnable name (default: current directory name)
-  --file      Target file: pyproject or runspec (auto-detected if omitted)
+Run 'runspec <command> --help' for focused help on each command.
 
-Options for discover:
-  --format    Output format: text (default), json, mcp, openai, anthropic
+Examples:
+  runspec init
+  runspec init --example
+  runspec local
+  runspec local --format mcp
+  runspec serve`);
+}
 
-Options for emit:
-  --script    Runnable name to emit (all runnables if omitted)
-  --format    Output format: mcp (default), openai, anthropic
+function printCommandHelp(command: string): void {
+  const help: Record<string, string> = {
+    init: `runspec init — Create runspec.toml and a code stub
+
+Options:
+  --name      Runnable name (default: current directory name)
+  --lang      Language for stub: typescript (default), javascript, python
+  --example   Generate dual clean + scan example runnables
 
 Examples:
   runspec init
   runspec init --name myapp
-  runspec discover
-  runspec discover --format mcp
-  runspec check
-  runspec emit --script deploy --format mcp
-  runspec emit --format openai`);
+  runspec init --name myapp --lang javascript
+  runspec init --example`,
+
+    local: `runspec local — List runnables and emit tool schemas
+
+Options:
+  --format    Output format: text (default), json, mcp, openai, anthropic
+  --script    Target a single runnable by name (use with --format)
+
+Examples:
+  runspec local
+  runspec local --format mcp
+  runspec local --format mcp --script deploy
+  runspec local --format json`,
+
+    jump: `runspec jump — Execute a runnable on a remote host via SSH
+
+  Not yet implemented in the Node package.
+  Use the Python package (pip install runspec) for SSH execution.`,
+
+    serve: `runspec serve — Start the MCP stdio server for local runnables
+
+  Reads JSON-RPC messages from stdin, writes responses to stdout.
+  Configure as an MCP server in Claude Desktop, VS Code, PyCharm, etc.
+
+  To test manually:
+    echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}' | runspec serve`,
+  };
+
+  if (command in help) {
+    console.log(help[command]);
+  } else {
+    console.log(`No help available for '${command}'.`);
+    printHelp();
+  }
 }