runspec-node 0.27.0 → 0.28.0

package/dist/testing.js

@@ -0,0 +1,324 @@
+"use strict";
+/**
+ * runspec-node/testing — test helpers for runspec runnables.
+ *
+ * The Node port of Python's `runspec.testing`. Import it from the subpath
+ * export so it stays out of the main entry:
+ *
+ *     import { ParseHarness } from 'runspec-node/testing';
+ *
+ * `parse()` already takes `argv` and `configPath`, so testing a runnable never
+ * requires monkeypatching `process.argv` or mocking the parser. `ParseHarness`
+ * removes the remaining boilerplate — pointing `parse()` at a spec, asserting on
+ * clean exits without the process actually exiting, and walking the subcommand
+ * tree to auto-cover every command.
+ *
+ * Node specifics this handles for you: `parse()` calls `process.exit(0)` on
+ * `--help` and *throws* `RunSpecError` on validation/require-command errors. The
+ * harness intercepts `process.exit` (so `--help` doesn't kill your test runner)
+ * and maps a thrown `RunSpecError` to a non-zero "exit", unifying both under one
+ * exit-code abstraction that mirrors Python's `SystemExit`-based helpers.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParseHarness = void 0;
+exports.harness = harness;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const parser_1 = require("./parser");
+const loader_1 = require("./loader");
+const inference_1 = require("./inference");
+const errors_1 = require("./errors");
+/** Thrown in place of `process.exit()` so a parse that exits can be caught. */
+class ExitSignal extends Error {
+    exitCode;
+    constructor(exitCode) {
+        super(`process.exit(${exitCode})`);
+        this.exitCode = exitCode;
+    }
+}
+class ParseHarness {
+    scriptName;
+    configPath;
+    suppressSummary;
+    tmpDir = null;
+    spec;
+    constructor(opts) {
+        const { scriptName, configPath, toml, suppressSummary = true } = opts;
+        if ((configPath == null) === (toml == null)) {
+            throw new Error('pass exactly one of configPath or toml');
+        }
+        this.scriptName = scriptName;
+        this.suppressSummary = suppressSummary;
+        let cfgPath = configPath;
+        if (toml != null) {
+            this.tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'runspec-test-'));
+            cfgPath = path.join(this.tmpDir, 'runspec.toml');
+            fs.writeFileSync(cfgPath, toml, 'utf-8');
+        }
+        this.configPath = path.resolve(cfgPath);
+        try {
+            const raw = (0, loader_1.loadRaw)(this.configPath);
+            if (!(scriptName in raw.runnables)) {
+                const have = Object.keys(raw.runnables).sort().join(', ') || '(none)';
+                throw new Error(`runnable '${scriptName}' not in ${this.configPath} (have: ${have})`);
+            }
+            // Infer so `required` is resolved from defaults/types (raw leaves it unset).
+            this.spec = (0, inference_1.inferScript)(raw.runnables[scriptName], raw.config.autonomyDefault);
+        }
+        catch (e) {
+            // Tear down the temp dir synchronously on a failed construction.
+            this.close();
+            throw e;
+        }
+    }
+    // ── lifecycle ─────────────────────────────────────────────────────────────
+    close() {
+        if (this.tmpDir != null) {
+            fs.rmSync(this.tmpDir, { recursive: true, force: true });
+            this.tmpDir = null;
+        }
+    }
+    // ── core parse entry points ───────────────────────────────────────────────
+    parse(argv) {
+        const { code, output, parsed } = this.runParse(argv);
+        if (parsed === null) {
+            throw new Error(`expected \`${this.scriptName} ${argv.join(' ')}\` to parse, but it exited ${code}:\n${output}`);
+        }
+        return parsed;
+    }
+    expectOk(argv) {
+        return this.parse(argv);
+    }
+    expectExit(argv, opts = {}) {
+        const { code = 1, contains } = opts;
+        const res = this.runParse(argv);
+        if (res.code === null) {
+            throw new Error(`expected \`${this.scriptName} ${argv.join(' ')}\` to exit, but it parsed cleanly`);
+        }
+        if (code !== null && res.code !== code) {
+            throw new Error(`\`${this.scriptName} ${argv.join(' ')}\`: expected exit ${code}, got ${res.code}:\n${res.output}`);
+        }
+        if (contains != null) {
+            const needles = Array.isArray(contains) ? contains : [contains];
+            for (const needle of needles) {
+                if (!res.output.includes(needle)) {
+                    throw new Error(`\`${this.scriptName} ${argv.join(' ')}\`: ${JSON.stringify(needle)} not found in output:\n${res.output}`);
+                }
+            }
+        }
+        return res.output;
+    }
+    // ── spec introspection ────────────────────────────────────────────────────
+    commandPaths() {
+        const paths = [];
+        const walk = (node, prefix) => {
+            for (const [name, sub] of Object.entries(node.commands ?? {})) {
+                const here = [...prefix, name];
+                paths.push(here);
+                walk(sub, here);
+            }
+        };
+        walk(this.spec, []);
+        return paths;
+    }
+    leafCommandPaths() {
+        return this.commandPaths().filter((p) => Object.keys(this.node(p).commands ?? {}).length === 0);
+    }
+    argsFor(p = []) {
+        return this.node(p).args ?? {};
+    }
+    requiredArgs(p = []) {
+        return Object.entries(this.argsFor(p))
+            .filter(([, a]) => a.required)
+            .map(([name]) => name);
+    }
+    requiresCommand(p = []) {
+        return Boolean(this.node(p).requireCommand);
+    }
+    // ── auto coverage ─────────────────────────────────────────────────────────
+    smoke(opts = {}) {
+        const { values = {}, checkHelp = true } = opts;
+        const done = [];
+        if (checkHelp) {
+            this.expectExit(['--help'], { code: 0 });
+            done.push('--help');
+        }
+        if (this.requiresCommand()) {
+            this.expectExit([]);
+            done.push('(no command) -> require-command');
+        }
+        for (const p of this.commandPaths()) {
+            const label = p.join(' ');
+            const node = this.node(p);
+            if (checkHelp) {
+                this.expectExit([...p, '--help'], { code: 0 });
+                done.push(`${label} --help`);
+            }
+            if (node.requireCommand) {
+                this.expectExit(p);
+                done.push(`${label} -> require-command`);
+                continue;
+            }
+            if (Object.keys(node.commands ?? {}).length > 0) {
+                continue; // intermediate group without require-command
+            }
+            if (this.requiredArgs(p).length > 0) {
+                this.expectExit(p);
+                done.push(`${label} -> missing required`);
+            }
+            const built = this.buildValidArgv(p, values);
+            if (built !== null) {
+                this.expectOk([...p, ...built]);
+                done.push(`${label} (valid)`);
+            }
+        }
+        return done;
+    }
+    // ── internals ─────────────────────────────────────────────────────────────
+    runParse(argv) {
+        // Capture the *original* (unbound) handles so restoration preserves identity.
+        const realExit = process.exit;
+        const realOut = process.stdout.write;
+        const realErr = process.stderr.write;
+        const realLog = console.log;
+        const realErrLog = console.error;
+        let captured = '';
+        process.exit = (c) => {
+            throw new ExitSignal(c ?? 0);
+        };
+        process.stdout.write = ((chunk) => {
+            captured += String(chunk);
+            return true;
+        });
+        process.stderr.write = ((chunk) => {
+            captured += String(chunk);
+            return true;
+        });
+        console.log = (...a) => {
+            captured += a.map(String).join(' ') + '\n';
+        };
+        console.error = (...a) => {
+            captured += a.map(String).join(' ') + '\n';
+        };
+        return this.withSummaryPinned(() => {
+            try {
+                const parsed = (0, parser_1.parse)({
+                    scriptName: this.scriptName,
+                    argv,
+                    configPath: this.configPath,
+                    _promptSecrets: false,
+                });
+                return { code: null, output: captured, parsed };
+            }
+            catch (e) {
+                if (e instanceof ExitSignal) {
+                    return { code: e.exitCode, output: captured, parsed: null };
+                }
+                if (e instanceof errors_1.RunSpecError) {
+                    // Validation / require-command throw rather than exit; fold the
+                    // message into the captured output so `contains:` can match on it.
+                    return { code: 1, output: `${captured}${e.message}\n`, parsed: null };
+                }
+                throw e;
+            }
+            finally {
+                process.exit = realExit;
+                process.stdout.write = realOut;
+                process.stderr.write = realErr;
+                console.log = realLog;
+                console.error = realErrLog;
+            }
+        });
+    }
+    node(p) {
+        let node = this.spec;
+        for (const part of p)
+            node = (node.commands ?? {})[part];
+        return node;
+    }
+    mergedArgs(p) {
+        const merged = { ...this.argsFor([]) };
+        const acc = [];
+        for (const part of p) {
+            acc.push(part);
+            Object.assign(merged, this.argsFor(acc));
+        }
+        return merged;
+    }
+    buildValidArgv(p, values) {
+        const argv = [];
+        for (const [name, a] of Object.entries(this.mergedArgs(p))) {
+            const supplied = values[name];
+            if (supplied === undefined || supplied === null) {
+                if (a.required)
+                    return null;
+                continue;
+            }
+            const flag = `--${name}`;
+            if (a.type === 'flag') {
+                if (supplied)
+                    argv.push(flag);
+            }
+            else {
+                argv.push(flag, String(supplied));
+            }
+        }
+        return argv;
+    }
+    withSummaryPinned(fn) {
+        if (!this.suppressSummary)
+            return fn();
+        const prefix = this.scriptName.toUpperCase().replace(/-/g, '_');
+        const key = `RUNSPEC_${prefix}_ARG_NO_SUMMARY`;
+        const prev = process.env[key];
+        process.env[key] = '1';
+        try {
+            return fn();
+        }
+        finally {
+            if (prev === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = prev;
+        }
+    }
+}
+exports.ParseHarness = ParseHarness;
+function harness(scriptName, opts = {}) {
+    return new ParseHarness({ scriptName, ...opts });
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "runspec-node",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Node/TypeScript language pack for runspec",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
   "bin": {
     "runspec": "./bin/runspec.js"
   },

package/src/cli.ts

@@ -1,6 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as readline from 'readline';
+import { spawnSync } from 'child_process';
 import { findConfig } from './finder';
 import * as logs from './logs';
 import { loadRaw } from './loader';
@@ -33,6 +34,7 @@ export function main(): void {
   const commands: Record<string, (args: string[]) => void | Promise<void>> = {
     init: cmdInit,
     local: cmdLocal,
+    test: cmdTest,
     bin: cmdBin,
     logs: cmdLogs,
     jump: cmdJump,
@@ -359,6 +361,145 @@ function cmdServe(_args: string[]): void {
   serve();
 }
 
+// Hard cap on the entry-point `--help` subprocess so a runnable that hangs on
+// import can't wedge a CI run. A timeout is treated as a failure.
+const TEST_SUBPROCESS_TIMEOUT_MS = 30000;
+
+interface TestCheck {
+  ok: boolean;
+  checks?: string[];
+  error?: string;
+  stderr?: string;
+}
+
+interface TestResult {
+  runnable: string;
+  source: string;
+  ok: boolean;
+  checks: { spec_smoke: TestCheck; entry_point: TestCheck };
+}
+
+export function cmdTest(args: string[]): void {
+  const fmt = getFlag(args, '--format') ?? 'text';
+  const runnableFilter = getFlag(args, '--runnable');
+
+  let discovered = discoverLocal();
+  if (runnableFilter) discovered = discovered.filter((d) => d.runnable === runnableFilter);
+
+  if (!discovered.length) {
+    console.log('No runspec-aware runnables found in this environment.');
+    console.log("Run from a folder with a runspec.toml, or 'runspec init' to create one.");
+    return;
+  }
+
+  const results = discovered.map((d) => testOne(d));
+  const failed = results.filter((r) => !r.ok).length;
+
+  if (fmt === 'json') {
+    const summary = { total: results.length, passed: results.length - failed, failed };
+    console.log(JSON.stringify({ results, summary }, null, 2));
+  } else {
+    printTestText(results);
+  }
+
+  if (failed) process.exit(1);
+}
+
+// Run both checks against one discovered runnable; never throws. Each phase is
+// isolated so a single broken runnable cannot abort the run.
+export function testOne(item: { source: string; runnable: string; spec: ScriptSpec }): TestResult {
+  const { runnable: name, source } = item;
+
+  // ── phase 1: spec smoke (in-process) ──────────────────────────────────────
+  let specSmoke: TestCheck;
+  try {
+    const { ParseHarness } = require('./testing') as typeof import('./testing');
+    const h = new ParseHarness({ scriptName: name, configPath: source, suppressSummary: true });
+    try {
+      specSmoke = { ok: true, checks: h.smoke({ checkHelp: true }) };
+    } finally {
+      h.close();
+    }
+  } catch (e) {
+    specSmoke = { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+
+  // ── phase 2: entry-point --help (subprocess) ──────────────────────────────
+  const { findScript } = require('./serve') as typeof import('./serve');
+  const binDir = path.join(path.dirname(source), 'node_modules', '.bin');
+  const cmd = findScript(name, binDir);
+
+  let entryPoint: TestCheck;
+  if (cmd === null) {
+    entryPoint = { ok: false, error: 'entry point not found — run `runspec bin` or check package.json "bin"' };
+  } else {
+    const res = spawnSync(cmd, ['--help'], {
+      encoding: 'utf-8',
+      timeout: TEST_SUBPROCESS_TIMEOUT_MS,
+      env: { ...process.env, RUNSPEC_AGENT: '1' },
+    });
+    if (res.error) {
+      const code = (res.error as NodeJS.ErrnoException).code;
+      const msg = code === 'ETIMEDOUT' ? `timed out after ${TEST_SUBPROCESS_TIMEOUT_MS / 1000}s` : res.error.message;
+      entryPoint = { ok: false, error: msg };
+    } else if (res.status !== 0) {
+      entryPoint = {
+        ok: false,
+        error: `exit ${res.status}`,
+        stderr: (res.stderr || res.stdout || '').trim().slice(0, 2000),
+      };
+    } else {
+      entryPoint = { ok: true };
+    }
+  }
+
+  return {
+    runnable: name,
+    source,
+    ok: specSmoke.ok && entryPoint.ok,
+    checks: { spec_smoke: specSmoke, entry_point: entryPoint },
+  };
+}
+
+// Pick the most informative single line from captured stderr: the last line
+// mentioning an error/exception (the "Error: ..." line for a Node crash, the
+// exception for a Python traceback), falling back to the last non-empty line.
+function summariseStderr(stderr: string): string {
+  const lines = stderr
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l);
+  if (!lines.length) return '';
+  const errLines = lines.filter((l) => /error|exception/i.test(l));
+  return (errLines.length ? errLines : lines)[(errLines.length ? errLines : lines).length - 1];
+}
+
+function printTestText(results: TestResult[]): void {
+  const total = results.length;
+  const passed = results.filter((r) => r.ok).length;
+  const failed = total - passed;
+
+  console.log(`Tested ${total} runnable(s):\n`);
+  for (const r of results) {
+    const spec = r.checks.spec_smoke;
+    const ep = r.checks.entry_point;
+    const mark = r.ok ? '✓' : '✗';
+    const specNote = spec.ok ? 'spec ok' : 'spec failed';
+    const epNote = ep.ok ? '--help exit 0' : '--help failed';
+    console.log(`  ${mark}  ${r.runnable.padEnd(24)} ${specNote}, ${epNote}`);
+    if (!spec.ok) console.log(`         spec: ${spec.error}`);
+    if (!ep.ok) {
+      console.log(`         entry point: ${ep.error}`);
+      if (ep.stderr) {
+        const summary = summariseStderr(ep.stderr);
+        if (summary) console.log(`         stderr: ${summary}`);
+      }
+    }
+  }
+  console.log();
+  console.log(`Summary: ${passed} passed, ${failed} failed (${total} total)`);
+}
+
 // ── Schema builder ────────────────────────────────────────────────────────────
 
 export function buildSchema(name: string, script: ScriptSpec, fmt: string): Record<string, unknown> {
@@ -830,6 +971,7 @@ Usage:
 Commands:
   init        Create runspec.toml and a code stub
   local       List runnables and emit tool schemas
+  test        Smoke-test every runnable: spec smoke + entry-point --help (CI gate)
   bin         Generate a venv-shaped bin/ so a controller can run this folder
   logs        View, status, prune, or compact per-invocation audit logs
   jump        Execute a runnable on a remote host via SSH
@@ -842,6 +984,7 @@ Examples:
   runspec init --example
   runspec local
   runspec local --format mcp
+  runspec test
   runspec bin
   runspec logs deploy
   runspec serve`);
@@ -874,6 +1017,23 @@ Examples:
   runspec local --format mcp --script deploy
   runspec local --format json`,
 
+    test: `runspec test — Smoke-test every runnable in this folder (CI gate)
+
+  For each runnable in runspec.toml runs two checks: an in-process spec smoke
+  (--help works for every command, require-command is enforced, required args
+  are validated) and a subprocess that executes the entry point with --help
+  (proves the runnable's own code imports and is wired to the right spec).
+  Exits 1 if any runnable fails either check.
+
+Options:
+  --format    Output format: text (default) or json
+  --runnable  Filter to a single runnable by name
+
+Examples:
+  runspec test
+  runspec test --format json
+  runspec test --runnable deploy`,
+
     bin: `runspec bin — Generate a venv-shaped bin/ for this folder's runnables
 
   Writes bin/runspec plus one bin/<runnable> shim per runnable in runspec.toml,

package/src/runspec.toml

@@ -53,6 +53,21 @@ examples = [
 format   = {type = "choice", description = "Output format", options = ["text", "json", "mcp", "openai", "anthropic"], short = "-f", default = "text"}
 runnable = {type = "str",    description = "Filter output to a single runnable by name", short = "-r", required = false}
 
+[runspec.commands.test]
+description = "Smoke-test runnables: spec smoke + entry-point --help"
+autonomy    = "autonomous"
+output      = "json"
+
+examples = [
+  {cmd = "runspec test",                   description = "Test every runnable in this folder (CI gate)"},
+  {cmd = "runspec test --format json",     description = "Machine-readable results for CI"},
+  {cmd = "runspec test --runnable deploy", description = "Test a single runnable"},
+]
+
+[runspec.commands.test.args]
+format   = {type = "choice", description = "Output format", options = ["text", "json"], short = "-f", default = "text"}
+runnable = {type = "str",    description = "Filter to a single runnable by name", short = "-r", required = false}
+
 [runspec.commands.serve]
 description = "Start an MCP stdio server exposing all installed runnables as tools"
 

package/src/serve.ts

@@ -258,7 +258,7 @@ function argsToRunspecEnv(args: Record<string, unknown>, argSpecs: Record<string
   return env;
 }
 
-function findScript(name: string, binDir: string): string | null {
+export function findScript(name: string, binDir: string): string | null {
   // 1. node_modules/.bin (Node entry points; also .exe on Windows)
   for (const ext of [...SHELL_EXTS, '.exe']) {
     const candidate = path.join(binDir, name + ext);