runspec-node 0.3.0 → 0.8.0

package/dist/cli.js

@@ -39,21 +39,27 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const finder_1 = require("./finder");
 const loader_1 = require("./loader");
-const inference_1 = require("./inference");
+const parser_1 = require("./parser");
+const _CLI_CONFIG = path.join(__dirname, 'runspec.toml');
 // ── Entry point ───────────────────────────────────────────────────────────────
 function main() {
     const args = process.argv.slice(2);
-    if (!args.length || args[0] === '-h' || args[0] === '--help') {
+    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;
+    }
+    if (!args.length || command === '-h' || command === '--help') {
         printHelp();
         return;
     }
-    const command = args[0];
-    const rest = args.slice(1);
     const commands = {
         init: cmdInit,
-        discover: cmdDiscover,
-        check: cmdCheck,
-        emit: cmdEmit,
+        local: cmdLocal,
+        jump: cmdJump,
         serve: cmdServe,
     };
     if (!(command in commands)) {
@@ -61,42 +67,60 @@ function main() {
         console.log(`   Available commands: ${Object.keys(commands).join(', ')}`);
         process.exit(1);
     }
-    commands[command](rest);
+    const result = commands[command](rest);
+    if (result instanceof Promise) {
+        result.catch((err) => {
+            process.stderr.write(`✗  ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        });
+    }
 }
 // ── Commands ──────────────────────────────────────────────────────────────────
 function cmdInit(args) {
     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) {
+function cmdLocal(args) {
     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}`);
@@ -104,94 +128,101 @@ function cmdDiscover(args) {
         process.exit(1);
     }
 }
-function cmdCheck(args) {
-    let configPath;
-    let format;
-    try {
-        ({ configPath, format } = (0, finder_1.findConfig)(process.cwd()));
+async function cmdJump(args) {
+    const parsed = (0, parser_1.parse)({ scriptName: 'runspec', argv: ['jump', ...args], configPath: _CLI_CONFIG });
+    const listHosts = Boolean(parsed['list_jump_hosts']);
+    const fmt = String(parsed['format'] ?? 'text');
+    if (listHosts) {
+        cmdListJumpHosts(fmt);
+        return;
     }
-    catch (e) {
-        console.log(e.message);
+    const hostName = parsed['jump_host'];
+    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 = (0, loader_1.loadRaw)(configPath, format);
-    const errors = [];
-    const warnings = [];
-    const ok = [];
-    ok.push(`Config found: ${configPath}`);
-    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)`);
+    const hostCfg = loadJumpHost(hostName);
+    const toolName = parsed['tool'];
+    const { listTools, callTool } = await Promise.resolve().then(() => __importStar(require('./jump')));
+    if (!toolName) {
+        const tools = await listTools(hostCfg);
+        if (!tools.length) {
+            console.log(`No tools found on ${hostName}.`);
+            return;
         }
-        else {
-            warnings.push('No [project.scripts] found — agents may not discover runnables automatically\n  Add entry points to pyproject.toml or use runspec.toml');
+        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");
-    }
-    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`);
-        }
-        if (!runnable.autonomy) {
-            warnings.push(`'${name}' autonomy not declared — will default to '${raw.config.autonomyDefault}'`);
-        }
-        else {
-            ok.push(`'${name}' — autonomy: ${runnable.autonomy}`);
-        }
-        for (const [argName, arg] of Object.entries(runnable.args ?? {})) {
-            if (!arg.description && arg.required) {
-                warnings.push(`'${name}.${argName}' is required but has no description`);
-            }
-        }
+    const toolArgv = parsed['tool_args'] ?? [];
+    await callTool(hostCfg, toolName, toolArgv);
+}
+function cmdListJumpHosts(fmt) {
+    let configPath;
+    try {
+        ({ configPath } = (0, finder_1.findConfig)(process.cwd()));
     }
-    for (const msg of ok)
-        console.log(`  ✓  ${msg}`);
-    for (const msg of warnings)
-        console.log(`  ℹ  ${msg}`);
-    for (const msg of errors)
-        console.log(`  ✗  ${msg}`);
-    if (errors.length)
+    catch {
+        process.stderr.write('✗  No runspec.toml found — cannot look up jump hosts\n');
         process.exit(1);
-    else if (!warnings.length)
-        console.log('\n  All checks passed.');
+    }
+    const raw = (0, loader_1.loadRaw)(configPath);
+    const hosts = raw.config.jumpHosts ?? {};
+    if (!Object.keys(hosts).length) {
+        console.log('No jump hosts configured.');
+        console.log('Add [config.jump-hosts.<name>] sections to your runspec.toml.');
+        return;
+    }
+    const { resolveBinRaw } = require('./jump');
+    if (fmt === 'json') {
+        const effective = Object.entries(hosts).map(([name, cfg]) => ({
+            name,
+            ...cfg,
+            bin: resolveBinRaw(cfg),
+        }));
+        console.log(JSON.stringify(effective, null, 2));
+        return;
+    }
+    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 cmdEmit(args) {
-    const scriptName = getFlag(args, '--script');
-    const fmt = getFlag(args, '--format') ?? 'mcp';
+function loadJumpHost(name) {
     let configPath;
-    let format;
     try {
-        ({ configPath, format } = (0, finder_1.findConfig)(process.cwd()));
+        ({ configPath } = (0, finder_1.findConfig)(process.cwd()));
     }
-    catch (e) {
-        console.log(e.message);
+    catch {
+        process.stderr.write(`✗  No runspec.toml found — cannot look up jump host '${name}'\n`);
         process.exit(1);
     }
-    const raw = (0, loader_1.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 schema = {};
-    for (const [name, runnable] of Object.entries(runnables)) {
-        const inferred = (0, inference_1.inferScript)(runnable, config.autonomyDefault);
-        schema[name] = buildSchema(name, inferred, fmt);
+    const raw = (0, loader_1.loadRaw)(configPath);
+    const hosts = raw.config.jumpHosts ?? {};
+    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) {
+    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');
     serve();
 }
@@ -245,8 +276,8 @@ function argToJsonSchema(arg) {
 // ── Discovery ─────────────────────────────────────────────────────────────────
 function discoverLocal() {
     try {
-        const { configPath, format } = (0, finder_1.findConfig)(process.cwd());
-        const raw = (0, loader_1.loadRaw)(configPath, format);
+        const { configPath } = (0, finder_1.findConfig)(process.cwd());
+        const raw = (0, loader_1.loadRaw)(configPath);
         return Object.entries(raw.runnables).map(([name, spec]) => ({ source: configPath, runnable: name, spec }));
     }
     catch {
@@ -259,70 +290,155 @@ function emitAll(discovered, fmt) {
         return { tools };
     return Object.fromEntries(tools.map((t) => [t['name'], t]));
 }
-function printDiscoverText(discovered) {
+function printLocalText(discovered) {
     const bySource = {};
     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 = [];
+    const errors = [];
+    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 ──────────────────────────────────────────────────────────────
 function sanitizeName(raw) {
     const s = raw.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
     return s || 'myscript';
 }
-function initPyproject(filePath, name) {
+function initRunspecToml(filePath, name) {
     if (fs.existsSync(filePath)) {
-        const original = fs.readFileSync(filePath, 'utf-8');
-        let data;
-        try {
-            const { parse } = require('smol-toml');
-            data = parse(original);
-        }
-        catch (e) {
-            console.log(`✗  Could not read ${path.basename(filePath)}: ${e.message}`);
-            process.exit(1);
-        }
-        if ('runspec' in (data?.tool ?? {})) {
-            const existing = Object.keys(data.tool.runspec).filter((k) => k !== 'config' && typeof data.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, name) {
+function initExampleToml(filePath) {
     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) {
-    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, lang) {
+    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 runspecTomlBlock(name) {
-    return `[${name}]\ndescription = "Describe what ${name} does"\nautonomy    = "confirm"\n\n[${name}.args]\n# example = {type = "str", description = "An example argument"}\n`;
+function writeStubIfMissing(filePath, content) {
+    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, name, lang) {
+    const templates = {
+        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 printNextSteps(cwd, example) {
+    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, content, original) {
     fs.writeFileSync(filePath, content, 'utf-8');
@@ -340,6 +456,203 @@ function writeAndVerify(filePath, content, original) {
         process.exit(1);
     }
 }
+// ── 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, flag) {
     const idx = args.indexOf(flag);
@@ -355,30 +668,63 @@ 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`);
+}
+function printCommandHelp(command) {
+    const help = {
+        init: `runspec init — Create runspec.toml and a code stub
 
-Options for emit:
-  --script    Runnable name to emit (all runnables if omitted)
-  --format    Output format: mcp (default), openai, anthropic
+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();
+    }
 }
 //# sourceMappingURL=cli.js.map