runspec-node 0.3.0 → 0.8.0

package/src/finder.ts

@@ -1,19 +1,13 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { parse as parseTOML } from 'smol-toml';
 
-export function findConfig(start?: string): { configPath: string; format: 'pyproject' | 'runspec' } {
+export function findConfig(start?: string): { configPath: string } {
   let dir = path.resolve(start ?? process.cwd());
 
   while (true) {
-    const pyproject = path.join(dir, 'pyproject.toml');
-    if (fs.existsSync(pyproject) && hasRunspecSection(pyproject)) {
-      return { configPath: pyproject, format: 'pyproject' };
-    }
-
     const runspecToml = path.join(dir, 'runspec.toml');
     if (fs.existsSync(runspecToml)) {
-      return { configPath: runspecToml, format: 'runspec' };
+      return { configPath: runspecToml };
     }
 
     const parent = path.dirname(dir);
@@ -22,38 +16,6 @@ export function findConfig(start?: string): { configPath: string; format: 'pypro
   }
 
   throw new Error(
-    "No runspec configuration found.\nExpected one of:\n  - pyproject.toml with [tool.runspec] section\n  - runspec.toml\n\nRun 'runspec check' to validate your project setup.",
+    "No runspec configuration found.\nExpected runspec.toml inside your package directory.\n\nRun 'runspec init' to create one.",
   );
 }
-
-export function findScriptName(configPath: string, format: 'pyproject' | 'runspec'): string | undefined {
-  if (format !== 'pyproject') return undefined;
-
-  try {
-    const content = fs.readFileSync(configPath, 'utf-8');
-    const data = parseTOML(content) as Record<string, unknown>;
-    const argv1 = process.argv[1] ?? '';
-    const caller = path.basename(argv1, path.extname(argv1));
-    if (!caller) return undefined;
-
-    const projectScripts = (data as any)?.project?.scripts ?? {};
-    if (caller in projectScripts) return caller;
-
-    const poetryScripts = (data as any)?.tool?.poetry?.scripts ?? {};
-    if (caller in poetryScripts) return caller;
-
-    return caller;
-  } catch {
-    return undefined;
-  }
-}
-
-function hasRunspecSection(pyprojectPath: string): boolean {
-  try {
-    const content = fs.readFileSync(pyprojectPath, 'utf-8');
-    const data = parseTOML(content) as Record<string, unknown>;
-    return 'runspec' in ((data as any)?.tool ?? {});
-  } catch {
-    return false;
-  }
-}

package/src/inference.ts

@@ -25,7 +25,10 @@ export function inferArg(raw: ArgSpec): ArgSpec {
     }
   }
 
-  if (result.required === undefined) {
+  if (result.type === 'rest') {
+    if (result.default === undefined || result.default === null) result.default = [];
+    if (result.required === undefined) result.required = false;
+  } else if (result.required === undefined) {
     const hasNoDefault = def === undefined || def === null;
     result.required = hasNoDefault && result.type !== 'flag';
   }

package/src/jump.ts

@@ -0,0 +1,243 @@
+import { spawn } from 'child_process';
+import type { ChildProcess } from 'child_process';
+import * as readline from 'readline';
+import * as path from 'path';
+import type { JumpHostConfig } from './models';
+
+const VALID_BIN_NAMES = new Set(['runspec', 'runspec.exe']);
+
+export function resolveBinRaw(hostCfg: JumpHostConfig): string {
+  return hostCfg.bin ?? process.env['RUNSPEC_JUMP_BIN'] ?? 'runspec';
+}
+
+function resolveBin(hostCfg: JumpHostConfig): string {
+  const binPath = resolveBinRaw(hostCfg);
+  validateBinPath(binPath);
+  return binPath;
+}
+
+function validateBinPath(binPath: string): void {
+  const name = path.basename(binPath);
+  if (!VALID_BIN_NAMES.has(name)) {
+    process.stderr.write(
+      `✗  Jump-host \`bin\` must point at a runspec executable.\n` +
+        `   Got: ${JSON.stringify(binPath)} (basename ${JSON.stringify(name)})\n` +
+        `   Expected basename: 'runspec' (or 'runspec.exe' on Windows).\n` +
+        `   This field is locked to the runspec CLI; it cannot be redirected.\n`,
+    );
+    process.exit(1);
+  }
+}
+
+export function sshCmd(hostCfg: JumpHostConfig, binPath: string): string[] {
+  const cmd = ['ssh', '-o', 'BatchMode=yes'];
+
+  if (hostCfg.useSshConfig === false) {
+    cmd.push('-F', '/dev/null');
+  }
+
+  if (hostCfg.port && hostCfg.port !== 22) {
+    cmd.push('-p', String(hostCfg.port));
+  }
+  if (hostCfg.sshKey) {
+    cmd.push('-i', hostCfg.sshKey);
+  }
+
+  for (const opt of hostCfg.sshOptions ?? []) {
+    cmd.push('-o', String(opt));
+  }
+
+  const target = hostCfg.user ? `${hostCfg.user}@${hostCfg.host}` : hostCfg.host;
+  cmd.push(target, binPath, 'serve');
+  return cmd;
+}
+
+interface Session {
+  send: (msg: Record<string, unknown>) => void;
+  recv: () => Promise<Record<string, unknown>>;
+  close: () => void;
+  proc: ChildProcess;
+  binPath: string;
+}
+
+function openSession(hostCfg: JumpHostConfig, binPath: string): Session {
+  const cmd = sshCmd(hostCfg, binPath);
+  const proc = spawn(cmd[0], cmd.slice(1), { stdio: ['pipe', 'pipe', 'inherit'] });
+
+  proc.on('error', (err: NodeJS.ErrnoException) => {
+    if (err.code === 'ENOENT') {
+      process.stderr.write('✗  ssh not found — install OpenSSH\n');
+    } else {
+      process.stderr.write(`✗  Failed to launch ssh: ${err.message}\n`);
+    }
+    process.exit(1);
+  });
+
+  const rl = readline.createInterface({ input: proc.stdout!, crlfDelay: Infinity });
+  const iter = rl[Symbol.asyncIterator]();
+
+  const send = (msg: Record<string, unknown>): void => {
+    proc.stdin!.write(JSON.stringify(msg) + '\n');
+  };
+
+  const recv = async (): Promise<Record<string, unknown>> => {
+    const { value, done } = await iter.next();
+    if (done) {
+      await reportRemoteFailure(proc, binPath);
+      throw new Error('unreachable');
+    }
+    return JSON.parse(value as string) as Record<string, unknown>;
+  };
+
+  const close = (): void => {
+    rl.close();
+    if (proc.stdin) proc.stdin.destroy();
+  };
+
+  return { send, recv, close, proc, binPath };
+}
+
+async function reportRemoteFailure(proc: ChildProcess, binPath: string): Promise<never> {
+  const exitCode =
+    proc.exitCode ??
+    (await new Promise<number | null>((resolve) => {
+      const timer = setTimeout(() => resolve(null), 1000);
+      proc.once('exit', (code) => {
+        clearTimeout(timer);
+        resolve(code);
+      });
+    }));
+
+  if (exitCode === 255) {
+    process.stderr.write('✗  SSH connection failed (see error above for details).\n');
+  } else if (exitCode !== null && exitCode !== 0) {
+    const prefix = `✗  Remote command failed (exit ${exitCode}) before the MCP handshake completed.\n`;
+    if (binPath.includes('/')) {
+      process.stderr.write(
+        prefix +
+          '   If the error above doesn\'t explain it, verify the path exists on the remote:\n' +
+          `     ${binPath}\n` +
+          '   Common causes:\n' +
+          '     - the venv path differs between local and remote\n' +
+          "     - runspec isn't installed in that venv on the remote\n" +
+          '     - typo in the bin / RUNSPEC_JUMP_BIN value\n',
+      );
+    } else {
+      process.stderr.write(
+        prefix +
+          `   \`${binPath}\` is not on the remote shell's PATH.\n` +
+          '   Fix: set `bin = "/full/path/to/runspec"` in [config.jump-hosts.<alias>],\n' +
+          '   or export RUNSPEC_JUMP_BIN in your local shell.\n' +
+          "   (SSH commands run in a non-login shell and don't source ~/.bashrc / ~/.profile.)\n",
+      );
+    }
+  } else {
+    process.stderr.write('✗  Remote MCP server closed stdout unexpectedly\n');
+  }
+  process.exit(1);
+}
+
+async function initialize(session: Session): Promise<void> {
+  session.send({
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'initialize',
+    params: {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: { name: 'runspec-jump', version: '1.0' },
+    },
+  });
+  await session.recv();
+  session.send({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} });
+}
+
+export async function listTools(hostCfg: JumpHostConfig): Promise<Array<Record<string, unknown>>> {
+  const binPath = resolveBin(hostCfg);
+  const session = openSession(hostCfg, binPath);
+  try {
+    await initialize(session);
+    session.send({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} });
+    const resp = await session.recv();
+    return ((resp['result'] as Record<string, unknown>)?.['tools'] as Array<Record<string, unknown>>) ?? [];
+  } finally {
+    session.close();
+  }
+}
+
+export async function callTool(hostCfg: JumpHostConfig, toolName: string, toolArgv: string[]): Promise<void> {
+  const binPath = resolveBin(hostCfg);
+  const session = openSession(hostCfg, binPath);
+  try {
+    await initialize(session);
+    session.send({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} });
+    const toolsResp = await session.recv();
+    const tools =
+      ((toolsResp['result'] as Record<string, unknown>)?.['tools'] as Array<Record<string, unknown>>) ?? [];
+    const schema = tools.find((t) => t['name'] === toolName);
+    if (!schema) {
+      process.stderr.write(`✗  Tool '${toolName}' not found on remote\n`);
+      process.exit(1);
+    }
+
+    const arguments_ = parseToolArgv(toolArgv, schema);
+    session.send({
+      jsonrpc: '2.0',
+      id: 3,
+      method: 'tools/call',
+      params: { name: toolName, arguments: arguments_ },
+    });
+    const callResp = await session.recv();
+
+    if ('error' in callResp) {
+      const err = callResp['error'] as Record<string, unknown>;
+      process.stderr.write(`✗  ${(err['message'] as string | undefined) ?? 'Remote error'}\n`);
+      process.exit(1);
+    }
+
+    const result = (callResp['result'] as Record<string, unknown>) ?? {};
+    for (const block of (result['content'] as Array<Record<string, unknown>>) ?? []) {
+      if (block['type'] === 'text') {
+        const text = block['text'] as string;
+        process.stdout.write(text);
+        if (!text.endsWith('\n')) process.stdout.write('\n');
+      }
+    }
+
+    if (result['isError']) {
+      process.exit(1);
+    }
+  } finally {
+    session.close();
+  }
+}
+
+export function parseToolArgv(argv: string[], schema: Record<string, unknown>): Record<string, unknown> {
+  const props =
+    ((schema['inputSchema'] as Record<string, unknown>)?.['properties'] as Record<
+      string,
+      Record<string, unknown>
+    >) ?? {};
+  const result: Record<string, unknown> = {};
+  let i = 0;
+  while (i < argv.length) {
+    const token = argv[i];
+    if (!token.startsWith('--')) {
+      i++;
+      continue;
+    }
+    const argName = token.slice(2);
+    const prop = props[argName] ?? {};
+    if (prop['type'] === 'boolean') {
+      result[argName] = true;
+      i++;
+    } else if (i + 1 < argv.length) {
+      result[argName] = argv[i + 1];
+      i += 2;
+    } else {
+      process.stderr.write(`✗  --${argName} requires a value\n`);
+      process.exit(1);
+    }
+  }
+  return result;
+}

package/src/loader.ts

@@ -1,20 +1,10 @@
 import * as fs from 'fs';
 import { parse as parseTOML } from 'smol-toml';
-import type { RawConfig, RawSpec, ScriptSpec, ArgSpec, GroupSpec } from './models';
+import type { RawConfig, RawSpec, ScriptSpec, ArgSpec, GroupSpec, JumpHostConfig } from './models';
 
-export function loadRaw(configPath: string, format: 'pyproject' | 'runspec'): RawSpec {
+export function loadRaw(configPath: string): RawSpec {
   const content = fs.readFileSync(configPath, 'utf-8');
-  const data = parseTOML(content) as Record<string, unknown>;
-
-  let raw: Record<string, unknown>;
-  let entryPoints: Record<string, string> = {};
-
-  if (format === 'pyproject') {
-    raw = ((data as any)?.tool?.runspec ?? {}) as Record<string, unknown>;
-    entryPoints = readEntryPoints(data);
-  } else {
-    raw = data;
-  }
+  const raw = parseTOML(content) as Record<string, unknown>;
 
   const runnablesRaw: Record<string, Record<string, unknown>> = {};
   for (const [key, value] of Object.entries(raw)) {
@@ -26,15 +16,32 @@ export function loadRaw(configPath: string, format: 'pyproject' | 'runspec'): Ra
   return {
     config: normaliseConfig((raw['config'] ?? {}) as Record<string, unknown>),
     runnables: normaliseRunnables(runnablesRaw),
-    entryPoints,
   };
 }
 
 function normaliseConfig(raw: Record<string, unknown>): RawConfig {
+  const rawHosts = (raw['jump-hosts'] ?? {}) as Record<string, Record<string, unknown>>;
+  const jumpHosts: Record<string, JumpHostConfig> = {};
+  for (const [name, cfg] of Object.entries(rawHosts)) {
+    jumpHosts[name] = normaliseJumpHost(cfg);
+  }
   return {
     autonomyDefault: (raw['autonomy-default'] as string | undefined) ?? 'confirm',
     lang: raw['lang'] as string | undefined,
     version: String(raw['version'] ?? '1'),
+    jumpHosts,
+  };
+}
+
+function normaliseJumpHost(raw: Record<string, unknown>): JumpHostConfig {
+  return {
+    host: raw['host'] as string,
+    user: raw['user'] as string | undefined,
+    port: raw['port'] as number | undefined,
+    sshKey: raw['ssh-key'] as string | undefined,
+    bin: raw['bin'] as string | undefined,
+    useSshConfig: raw['use-ssh-config'] as boolean | undefined,
+    sshOptions: raw['ssh-options'] as string[] | undefined,
   };
 }
 
@@ -78,6 +85,7 @@ function normaliseArg(name: string, raw: Record<string, unknown>): ArgSpec {
     multiple: (raw['multiple'] as boolean | undefined) ?? false,
     delimiter: raw['delimiter'] as string | undefined,
     short: raw['short'] as string | undefined,
+    position: raw['position'] as number | undefined,
     env: raw['env'] as string | undefined,
     deprecated: raw['deprecated'] as string | undefined,
     autonomy: raw['autonomy'] as string | undefined,
@@ -111,10 +119,3 @@ function normaliseCommands(raw: Record<string, Record<string, unknown>>): Record
   return Object.fromEntries(Object.entries(raw).map(([name, data]) => [name, normaliseScript(name, data)]));
 }
 
-function readEntryPoints(data: Record<string, unknown>): Record<string, string> {
-  const projectScripts = (data as any)?.project?.scripts;
-  if (projectScripts && typeof projectScripts === 'object') return projectScripts as Record<string, string>;
-  const poetryScripts = (data as any)?.tool?.poetry?.scripts;
-  if (poetryScripts && typeof poetryScripts === 'object') return poetryScripts as Record<string, string>;
-  return {};
-}

package/src/models.ts

@@ -1,7 +1,18 @@
+export interface JumpHostConfig {
+  host: string;
+  user?: string;
+  port?: number;
+  sshKey?: string;
+  bin?: string;
+  useSshConfig?: boolean;
+  sshOptions?: string[];
+}
+
 export interface RawConfig {
   autonomyDefault: string;
   lang?: string;
   version: string;
+  jumpHosts: Record<string, JumpHostConfig>;
 }
 
 export interface ArgSpec {
@@ -15,6 +26,7 @@ export interface ArgSpec {
   multiple?: boolean;
   delimiter?: string;
   short?: string;
+  position?: number;
   env?: string;
   deprecated?: string;
   autonomy?: string;
@@ -47,15 +59,16 @@ export interface ScriptSpec {
 export interface RawSpec {
   config: RawConfig;
   runnables: Record<string, ScriptSpec>;
-  entryPoints: Record<string, string>;
 }
 
 export interface ParsedArgs {
   [key: string]: unknown;
-  readonly __agent__: boolean;
-  readonly __script__: string;
-  readonly __command__: string | undefined;
-  readonly __autonomy__: string;
-  readonly __source__: string;
-  readonly __spec__: ScriptSpec;
+  readonly __runspec_agent__: boolean;
+  readonly __runspec_script__: string;
+  readonly __runspec_command_path__: string[];
+  readonly __runspec_autonomy__: string;
+  readonly __runspec_source__: string;
+  readonly __runspec_spec__: ScriptSpec;
+  readonly runspec_command: string | undefined;
+  readonly runspec_command_path: string[];
 }

package/src/parser.ts

@@ -1,5 +1,5 @@
 import * as path from 'path';
-import { findConfig, findScriptName } from './finder';
+import { findConfig } from './finder';
 import { loadRaw } from './loader';
 import { inferScript, effectiveAutonomy } from './inference';
 import { coerce } from './types';
@@ -11,16 +11,17 @@ export interface ParseOptions {
   scriptName?: string;
   argv?: string[];
   cwd?: string;
+  configPath?: string;
 }
 
 export function parse(opts: ParseOptions = {}): ParsedArgs {
-  const { scriptName, argv: argvOverride, cwd } = opts;
+  const { scriptName, argv: argvOverride, cwd, configPath: configPathOverride } = opts;
 
-  const { configPath, format } = findConfig(cwd);
-  const raw = loadRaw(configPath, format);
+  const { configPath } = configPathOverride ? { configPath: configPathOverride } : findConfig(cwd);
+  const raw = loadRaw(configPath);
   const config = raw.config;
 
-  const name = scriptName ?? findScriptName(configPath, format) ?? inferFromArgv();
+  const name = scriptName ?? inferFromArgv();
   if (!name) throw new RunSpecError('✗  Could not determine runnable name. Pass scriptName option.');
   if (name === 'config') throw new RunSpecError("✗  'config' is a reserved name in runspec.\n   Rename your runnable.");
 
@@ -33,17 +34,17 @@ export function parse(opts: ParseOptions = {}): ParsedArgs {
 
   let argv = argvOverride ?? process.argv.slice(2);
   let activeScript = rawScript;
-  let activeCommand: string | undefined;
+  let commandPath: string[] = [];
 
   const commands = rawScript.commands ?? {};
   if (Object.keys(commands).length > 0 && argv.length > 0 && argv[0] in commands) {
-    activeCommand = argv[0];
+    commandPath = [argv[0]];
     activeScript = commands[argv[0]];
     argv = argv.slice(1);
   }
 
   if (argv.includes('--help') || argv.includes('-h')) {
-    printHelp(name, activeScript, activeCommand);
+    printHelp(name, activeScript, commandPath.length > 0 ? commandPath[commandPath.length - 1] : undefined);
     process.exit(0);
   }
 
@@ -66,12 +67,14 @@ export function parse(opts: ParseOptions = {}): ParsedArgs {
 
   return {
     ...coercedValues,
-    __agent__: agent,
-    __script__: name,
-    __command__: activeCommand,
-    __autonomy__: autonomy,
-    __source__: configPath,
-    __spec__: activeScript,
+    __runspec_agent__: agent,
+    __runspec_script__: name,
+    __runspec_command_path__: commandPath,
+    __runspec_autonomy__: autonomy,
+    __runspec_source__: configPath,
+    __runspec_spec__: activeScript,
+    get runspec_command() { return commandPath.length > 0 ? commandPath[commandPath.length - 1] : undefined; },
+    get runspec_command_path() { return commandPath; },
   } as ParsedArgs;
 }
 
@@ -95,15 +98,29 @@ function parseArgv(argv: string[], argSpecs: Record<string, ArgSpec>): Record<st
     if (spec.short) shortMap[spec.short] = norm;
   }
 
+  // Positional args sorted by position index; rest arg (type='rest') collects post-'--' tokens
+  const positionalArgs = Object.entries(argSpecs)
+    .filter(([, s]) => s.position !== undefined)
+    .sort(([, a], [, b]) => (a.position ?? 0) - (b.position ?? 0))
+    .map(([name]) => name.replace(/-/g, '_'));
+  const restArgNorm = Object.entries(argSpecs).find(([, s]) => s.type === 'rest')?.[0]?.replace(/-/g, '_');
+
   const result: Record<string, unknown> = {};
   for (const name of Object.keys(argSpecs)) {
     result[name.replace(/-/g, '_')] = undefined;
   }
 
+  let positionalIndex = 0;
   let i = 0;
   while (i < argv.length) {
     const token = argv[i];
 
+    // '--' separator: remaining tokens go to the rest arg
+    if (token === '--') {
+      if (restArgNorm !== undefined) result[restArgNorm] = argv.slice(i + 1);
+      break;
+    }
+
     if (token.startsWith('--') && token.includes('=')) {
       const eqIdx = token.indexOf('=');
       const key = token.slice(0, eqIdx);
@@ -140,6 +157,12 @@ function parseArgv(argv: string[], argSpecs: Record<string, ArgSpec>): Record<st
       continue;
     }
 
+    // Unrecognized non-flag token: assign to next positional arg
+    if (!token.startsWith('-') && positionalIndex < positionalArgs.length) {
+      result[positionalArgs[positionalIndex]] = token;
+      positionalIndex++;
+    }
+
     i++;
   }
 

package/src/runspec.toml

@@ -0,0 +1,81 @@
+#:schema https://raw.githubusercontent.com/JasonFinestone/runspec/main/schema/runspec.schema.json
+
+# runspec itself is a developer CLI, not an agent tool. Suppress autonomy
+# inference so --help doesn't display a meaningless autonomy level on the
+# top-level menu or on `serve` (which is a server, not an action).
+[config]
+autonomy-default = ""
+
+[runspec]
+description = "Interface specification for anything runnable"
+
+examples = [
+  {cmd = "runspec init",                   description = "Scaffold a new runnable in this directory"},
+  {cmd = "runspec local",                  description = "Discover and validate runnables"},
+  {cmd = "runspec serve",                  description = "Start the MCP stdio server"},
+  {cmd = "runspec jump --list-jump-hosts", description = "List configured jump hosts"},
+]
+
+[runspec.commands.init]
+description = "Scaffold a new runnable — creates runspec.toml and a code stub"
+autonomy    = "confirm"
+
+examples = [
+  {cmd = "runspec init",                                              description = "Scaffold using current directory name"},
+  {cmd = "runspec init --name deploy",                                description = "Scaffold a runnable called 'deploy'"},
+  {cmd = "runspec init --example",                                    description = "Generate worked example (clean + scan)"},
+  {cmd = "runspec init --example --write-project",                    description = "Also generate pyproject.toml in parent dir"},
+  {cmd = "runspec init --write-project --project-dir /tmp/myproject", description = "Write project files to a specific path"},
+  {cmd = "runspec init --name myapp --lang typescript",               description = "Use TypeScript code stub"},
+]
+
+[runspec.commands.init.args]
+name          = {type = "str",    description = "Runnable name (defaults to package directory name)", short = "-n", required = false}
+lang          = {type = "choice", description = "Language for the generated code stub", options = ["python", "typescript", "javascript"], default = "python"}
+example       = {type = "flag",   description = "Generate a worked example (clean + scan runnables)", short = "-e", default = false}
+write-project = {type = "flag",   description = "Generate pyproject.toml, __init__.py, .gitignore, and CLAUDE.md", short = "-w", default = false}
+project-dir   = {type = "str",    description = "Where to write project files (default: parent directory)", short = "-d", required = false}
+force         = {type = "flag",   description = "Override the cwd safety check (don't refuse when pyproject.toml is present in cwd)", default = false}
+
+[runspec.commands.local]
+description = "List installed runnables or emit their tool schemas"
+autonomy    = "autonomous"
+output      = "json"
+
+examples = [
+  {cmd = "runspec local",                                description = "Discover runnables and validate setup"},
+  {cmd = "runspec local --format mcp",                   description = "Emit MCP tool schemas"},
+  {cmd = "runspec local --format mcp --runnable deploy", description = "Emit schema for one runnable"},
+  {cmd = "runspec local --format json",                  description = "Full spec as JSON"},
+]
+
+[runspec.commands.local.args]
+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.serve]
+description = "Start an MCP stdio server exposing all installed runnables as tools"
+
+examples = [
+  {cmd = "runspec serve", description = "Serve all runspec-aware runnables installed in this venv"},
+]
+
+# No args — runnables are discovered via importlib.metadata. Install with
+# `pip install -e .` to make a package visible.
+
+[runspec.commands.jump]
+description = "List jump hosts, list tools on a jump host, or run a tool via SSH+MCP"
+autonomy    = "confirm"
+
+examples = [
+  {cmd = "runspec jump --list-jump-hosts",             description = "List configured jump hosts"},
+  {cmd = "runspec jump myserver",                      description = "List tools available on myserver"},
+  {cmd = "runspec jump myserver deploy -- --env prod", description = "Run 'deploy' on myserver with --env prod"},
+]
+
+[runspec.commands.jump.args]
+list-jump-hosts = {type = "flag",   description = "List configured jump hosts from runspec.toml", short = "-l", default = false}
+format          = {type = "choice", description = "Output format when listing", options = ["text", "json"], short = "-f", default = "text"}
+jump-host       = {type = "str",    description = "Jump host alias from [config.jump-hosts]",  position = 1, required = false}
+tool            = {type = "str",    description = "Tool to run on the jump host",              position = 2, required = false}
+tool-args       = {type = "rest",   description = "Args passed to the remote tool"}