runspec-node 0.26.1 → 0.28.0

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "runspec-node",
-  "version": "0.26.1",
+  "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> {
@@ -366,6 +507,10 @@ export function buildSchema(name: string, script: ScriptSpec, fmt: string): Reco
   const requiredArgs: string[] = [];
 
   for (const [argName, arg] of Object.entries(script.args ?? {})) {
+    // Secret args are deliberately omitted from agent-facing schemas: a password
+    // can't be passed on the command line and must come from the environment /
+    // operator, never from an agent's tool call.
+    if (arg.type === 'password') continue;
     properties[argName] = argToJsonSchema(arg);
     if (arg.required) requiredArgs.push(argName);
   }
@@ -387,6 +532,7 @@ export function buildSchema(name: string, script: ScriptSpec, fmt: string): Reco
 function argToJsonSchema(arg: ArgSpec): Record<string, unknown> {
   const typeMap: Record<string, string> = {
     str: 'string',
+    password: 'string',
     int: 'integer',
     float: 'number',
     bool: 'boolean',
@@ -825,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
@@ -837,6 +984,7 @@ Examples:
   runspec init --example
   runspec local
   runspec local --format mcp
+  runspec test
   runspec bin
   runspec logs deploy
   runspec serve`);
@@ -869,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/loader.ts

@@ -101,6 +101,7 @@ function normaliseArg(name: string, raw: Record<string, unknown>): ArgSpec {
     deprecated: raw['deprecated'] as string | undefined,
     autonomy: raw['autonomy'] as string | undefined,
     ui: raw['ui'] as string | undefined,
+    hint: raw['hint'] as string | undefined,
     meta: raw['meta'] as Record<string, unknown> | undefined,
   };
 }

package/src/models.ts

@@ -33,6 +33,7 @@ export interface ArgSpec {
   deprecated?: string;
   autonomy?: string;
   ui?: string;
+  hint?: string; // UI placeholder/hint text (str/path/password types)
   meta?: Record<string, unknown>;
 }
 

package/src/parser.ts

@@ -1,4 +1,6 @@
 import * as path from 'path';
+import * as fs from 'fs';
+import { execSync } from 'child_process';
 import { findConfig } from './finder';
 import { loadRaw } from './loader';
 import { inferScript, effectiveAutonomy } from './inference';
@@ -15,10 +17,12 @@ export interface ParseOptions {
   configPath?: string;
   /** Internal: enforce `require-command` (real CLI parsing). loadSpec sets false. */
   _enforceRequiredCommand?: boolean;
+  /** Internal: prompt for missing required password args. loadSpec sets false. */
+  _promptSecrets?: boolean;
 }
 
 export function parse(opts: ParseOptions = {}): ParsedArgs {
-  const { scriptName, argv: argvOverride, cwd, configPath: configPathOverride, _enforceRequiredCommand = true } = opts;
+  const { scriptName, argv: argvOverride, cwd, configPath: configPathOverride, _enforceRequiredCommand = true, _promptSecrets = true } = opts;
 
   const { configPath } = configPathOverride ? { configPath: configPathOverride } : findConfig(cwd);
   const raw = loadRaw(configPath);
@@ -125,6 +129,15 @@ export function parse(opts: ParseOptions = {}): ParsedArgs {
   parsedValues = applyEnv(parsedValues, activeScript.args ?? {}, name);
   parsedValues = applyDefaults(parsedValues, activeScript.args ?? {});
 
+  // Prompt (no echo) for any still-unresolved required password arg when running
+  // interactively. Passwords are refused on the command line, so a terminal user
+  // supplies them here; agent / non-interactive runs (and loadSpec) fall through
+  // to the env-var value or the required-arg error.
+  const agentEarly = ['1', 'true', 'yes'].includes((process.env['RUNSPEC_AGENT'] ?? '').toLowerCase());
+  if (_promptSecrets) {
+    parsedValues = promptPasswords(parsedValues, activeScript.args ?? {}, agentEarly);
+  }
+
   raiseIfErrors(validateArgs(parsedValues, activeScript.args ?? {}));
   raiseIfErrors(validateGroups(parsedValues, activeScript.groups ?? {}));
 
@@ -175,7 +188,8 @@ export function parse(opts: ParseOptions = {}): ParsedArgs {
 }
 
 export function loadSpec(opts: ParseOptions = {}): ParsedArgs {
-  return parse({ ...opts, argv: [], _enforceRequiredCommand: false });
+  // Secret prompting is disabled — introspection must never block on a prompt.
+  return parse({ ...opts, argv: [], _enforceRequiredCommand: false, _promptSecrets: false });
 }
 
 function inferFromArgv(): string {
@@ -225,6 +239,7 @@ function parseArgv(argv: string[], argSpecs: Record<string, ArgSpec>): Record<st
       if (norm) {
         const hyphenName = norm.replace(/_/g, '-');
         const spec = argSpecs[hyphenName] ?? argSpecs[norm] ?? {};
+        if ((spec as ArgSpec).type === 'password') refusePasswordOnCli(norm);
         result[norm] = appendOrSet(result[norm], value, spec);
       }
       i++;
@@ -237,6 +252,8 @@ function parseArgv(argv: string[], argSpecs: Record<string, ArgSpec>): Record<st
       const spec = argSpecs[hyphenName] ?? argSpecs[norm] ?? {};
       const argType = spec.type ?? 'str';
 
+      if (argType === 'password') refusePasswordOnCli(norm);
+
       if (argType === 'flag') {
         result[norm] = true;
         i++;
@@ -273,6 +290,83 @@ function appendOrSet(current: unknown, value: unknown, spec: ArgSpec): unknown {
   return value;
 }
 
+// A `password` arg must never take its value from argv (it would leak into shell
+// history and `ps`). Resolve it from the environment instead — the automatic
+// RUNSPEC_<RUNNABLE>_ARG_<NAME> variable, a declared `env` alias — or let runspec
+// prompt for it when run interactively in a terminal.
+function refusePasswordOnCli(norm: string): never {
+  const flag = norm.replace(/_/g, '-');
+  const envHint = `RUNSPEC_<RUNNABLE>_ARG_${norm.toUpperCase()}`;
+  throw new RunSpecError(
+    `✗  --${flag} is a password and cannot be passed on the command line.\n` +
+      `   Set it via the environment (${envHint} or an 'env' alias),\n` +
+      `   or run the command interactively to be prompted.`,
+  );
+}
+
+// Interactively prompt (no echo) for any required password arg still unresolved
+// after env/defaults. Only when attached to a real terminal and not invoked by
+// an agent. POSIX only (uses `stty`); Windows / non-TTY runs fall through to the
+// normal required-arg error.
+function promptPasswords(
+  parsed: Record<string, unknown>,
+  argSpecs: Record<string, ArgSpec>,
+  agent: boolean,
+): Record<string, unknown> {
+  if (agent || process.platform === 'win32' || !(process.stdin.isTTY && process.stderr.isTTY)) {
+    return parsed;
+  }
+  const result = { ...parsed };
+  for (const [name, spec] of Object.entries(argSpecs)) {
+    if (spec.type !== 'password') continue;
+    const norm = name.replace(/-/g, '_');
+    if (result[norm] !== undefined && result[norm] !== null) continue;
+    if (!spec.required) continue;
+    const value = readLineNoEcho(`${name}: `);
+    if (value) result[norm] = value;
+  }
+  return result;
+}
+
+// Read one line from stdin with echo suppressed (getpass equivalent). Reads
+// bytes so multibyte UTF-8 secrets decode correctly; restores echo on exit.
+function readLineNoEcho(prompt: string): string {
+  process.stderr.write(prompt);
+  try {
+    try {
+      execSync('stty -echo', { stdio: 'inherit' });
+    } catch {
+      /* no stty available — proceed (input may echo) */
+    }
+    const bytes: number[] = [];
+    const buf = Buffer.alloc(1);
+    for (;;) {
+      let n: number;
+      try {
+        n = fs.readSync(0, buf, 0, 1, null);
+      } catch (e) {
+        if ((e as NodeJS.ErrnoException).code === 'EAGAIN') continue;
+        break;
+      }
+      if (n === 0) break;
+      const b = buf[0];
+      if (b === 0x0a) break; // \n
+      if (b === 0x0d) continue; // \r
+      bytes.push(b);
+    }
+    return Buffer.from(bytes).toString('utf8');
+  } catch {
+    return '';
+  } finally {
+    try {
+      execSync('stty echo', { stdio: 'inherit' });
+    } catch {
+      /* ignore */
+    }
+    process.stderr.write('\n');
+  }
+}
+
 function applyEnv(parsed: Record<string, unknown>, argSpecs: Record<string, ArgSpec>, runnableName: string): Record<string, unknown> {
   const runnablePrefix = runnableName.toUpperCase().replace(/-/g, '_');
   const result = { ...parsed };

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);