runspec-node 0.7.0 → 0.9.0

package/src/loader.ts

@@ -1,6 +1,6 @@
 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, LoggingConfig } from './models';
 
 export function loadRaw(configPath: string): RawSpec {
   const content = fs.readFileSync(configPath, 'utf-8');
@@ -20,10 +20,45 @@ export function loadRaw(configPath: string): RawSpec {
 }
 
 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,
+    logging: normaliseLogging(raw['logging'] as Record<string, unknown> | undefined),
+  };
+}
+
+const VALID_LOG_LEVELS = new Set(['debug', 'info', 'warning', 'error', 'critical']);
+
+function normaliseLogging(raw: Record<string, unknown> | undefined): LoggingConfig | undefined {
+  if (raw === undefined) return undefined;
+  const level = String(raw['level'] ?? 'info').toLowerCase();
+  if (!VALID_LOG_LEVELS.has(level)) {
+    const sorted = [...VALID_LOG_LEVELS].sort().join(', ');
+    throw new Error(`✗  [config.logging] level must be one of: ${sorted}. Got: ${JSON.stringify(level)}`);
+  }
+  return {
+    level,
+    rotate: String(raw['rotate'] ?? 'midnight'),
+    keep: Number(raw['keep'] ?? 7),
+  };
+}
+
+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,
   };
 }
 
@@ -67,6 +102,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,

package/src/logging_setup.ts

@@ -0,0 +1,291 @@
+/**
+ * Configure a lightweight logger from [config.logging]. Zero new deps — uses
+ * only Node stdlib (fs, path, os). Call configureLogging() once from parse();
+ * runnables call getLogger(name) to obtain a named Logger.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import type { LoggingConfig } from './models';
+
+// ── internal state ────────────────────────────────────────────────────────────
+
+let _configured = false;
+const _loggers = new Map<string, Logger>();
+const _handlers: Handler[] = [];
+
+// ── level map ─────────────────────────────────────────────────────────────────
+
+const LEVEL_NUM: Record<string, number> = {
+  debug: 10, info: 20, warning: 30, error: 40, critical: 50,
+};
+
+const LEVEL_LABEL: Record<number, string> = {
+  10: 'DEBUG', 20: 'INFO', 30: 'WARNING', 40: 'ERROR', 50: 'CRITICAL',
+};
+
+// ── sensitive data redaction ──────────────────────────────────────────────────
+
+const SENSITIVE: Array<[RegExp, string]> = [
+  [/(password|passwd|pwd)\s*[=:]\s*\S+/gi, '$1=[REDACTED]'],
+  [/(token|api[_-]?key|secret)\s*[=:]\s*\S+/gi, '$1=[REDACTED]'],
+  [/Authorization:\s*(Bearer|Basic)\s+\S+/gi, 'Authorization: $1 [REDACTED]'],
+  [/https?:\/\/[^:@\s]+:[^@\s]+@/g, 'https://[REDACTED]@'],
+  [/"(password|token|api_key|secret)"\s*:\s*"[^"]*"/gi, '"$1": "[REDACTED]"'],
+  [/(password|passwd|token)=([^&\s"]+)/gi, '$1=[REDACTED]'],
+];
+
+function redact(msg: string): string {
+  try {
+    for (const [pattern, replacement] of SENSITIVE) {
+      msg = msg.replace(pattern, replacement);
+    }
+  } catch {
+    // never disrupt logging on redaction errors
+  }
+  return msg;
+}
+
+// ── log record & handler ──────────────────────────────────────────────────────
+
+interface LogRecord {
+  ts: Date;
+  levelNum: number;
+  loggerName: string;
+  message: string;
+  error?: Error;
+}
+
+interface Handler {
+  level: number;
+  emit(record: LogRecord): void;
+}
+
+// ── Logger ────────────────────────────────────────────────────────────────────
+
+export class Logger {
+  constructor(private readonly name: string) {}
+
+  debug(msg: string, error?: Error): void { this._emit(10, msg, error); }
+  info(msg: string, error?: Error): void { this._emit(20, msg, error); }
+  warning(msg: string, error?: Error): void { this._emit(30, msg, error); }
+  warn(msg: string, error?: Error): void { this._emit(30, msg, error); }
+  error(msg: string, error?: Error): void { this._emit(40, msg, error); }
+  critical(msg: string, error?: Error): void { this._emit(50, msg, error); }
+
+  private _emit(levelNum: number, message: string, error?: Error): void {
+    if (_handlers.length === 0) return;
+    const record: LogRecord = { ts: new Date(), levelNum, loggerName: this.name, message: redact(message), error };
+    for (const h of _handlers) {
+      if (levelNum >= h.level) h.emit(record);
+    }
+  }
+}
+
+export function getLogger(name: string): Logger {
+  let logger = _loggers.get(name);
+  if (!logger) {
+    logger = new Logger(name);
+    _loggers.set(name, logger);
+  }
+  return logger;
+}
+
+// ── formatters ────────────────────────────────────────────────────────────────
+
+function formatJson(record: LogRecord): string {
+  const obj: Record<string, unknown> = {
+    ts: record.ts.toISOString(),
+    level: LEVEL_LABEL[record.levelNum] ?? String(record.levelNum),
+    logger: record.loggerName,
+    message: record.message,
+  };
+  if (record.error) obj['exc'] = record.error.stack ?? record.error.message;
+  return JSON.stringify(obj);
+}
+
+function formatHuman(record: LogRecord, showTracebacks: boolean): string {
+  const hh = String(record.ts.getHours()).padStart(2, '0');
+  const mm = String(record.ts.getMinutes()).padStart(2, '0');
+  const ss = String(record.ts.getSeconds()).padStart(2, '0');
+  const time = `${hh}:${mm}:${ss}`;
+  const label = (LEVEL_LABEL[record.levelNum] ?? String(record.levelNum)).padEnd(8);
+  let line = `${time} ${label} ${record.loggerName}: ${record.message}`;
+  if (showTracebacks && record.error) line += `\n${record.error.stack ?? record.error.message}`;
+  return line;
+}
+
+// ── console handler ───────────────────────────────────────────────────────────
+
+class ConsoleHandler implements Handler {
+  constructor(public readonly level: number, private readonly showTracebacks: boolean) {}
+
+  emit(record: LogRecord): void {
+    try {
+      process.stderr.write(formatHuman(record, this.showTracebacks) + '\n');
+    } catch {
+      // never disrupt
+    }
+  }
+}
+
+// ── rotating file handlers ────────────────────────────────────────────────────
+
+function doRotate(logPath: string, keep: number): void {
+  for (let i = keep; i >= 1; i--) {
+    const src = `${logPath}.${i}`;
+    if (i === keep) {
+      try { fs.unlinkSync(src); } catch { /* already gone */ }
+    } else {
+      try { fs.renameSync(src, `${logPath}.${i + 1}`); } catch { /* missing backup */ }
+    }
+  }
+  try { fs.renameSync(logPath, `${logPath}.1`); } catch { /* current file missing */ }
+}
+
+class SizeRotatingFileHandler implements Handler {
+  readonly level = 10; // always DEBUG
+
+  constructor(
+    private readonly logPath: string,
+    private readonly maxBytes: number,
+    private readonly keep: number,
+  ) {}
+
+  emit(record: LogRecord): void {
+    try {
+      this._rotateIfNeeded();
+      fs.appendFileSync(this.logPath, formatJson(record) + '\n', 'utf-8');
+    } catch {
+      // never disrupt
+    }
+  }
+
+  private _rotateIfNeeded(): void {
+    try {
+      if (fs.statSync(this.logPath).size < this.maxBytes) return;
+    } catch {
+      return; // file doesn't exist yet
+    }
+    doRotate(this.logPath, this.keep);
+  }
+}
+
+function _periodForDate(d: Date, when: 'daily' | 'midnight' | 'weekly'): string {
+  if (when === 'weekly') {
+    const tmp = new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()));
+    const day = tmp.getUTCDay() || 7;
+    tmp.setUTCDate(tmp.getUTCDate() + 4 - day);
+    const yearStart = new Date(Date.UTC(tmp.getUTCFullYear(), 0, 1));
+    const week = Math.ceil(((tmp.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
+    return `${tmp.getUTCFullYear()}-W${week}`;
+  }
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
+class TimedRotatingFileHandler implements Handler {
+  readonly level = 10;
+
+  constructor(
+    private readonly logPath: string,
+    private readonly when: 'daily' | 'midnight' | 'weekly',
+    private readonly keep: number,
+  ) {}
+
+  emit(record: LogRecord): void {
+    try {
+      this._rotateIfNeeded();
+      fs.appendFileSync(this.logPath, formatJson(record) + '\n', 'utf-8');
+    } catch {
+      // never disrupt
+    }
+  }
+
+  private _rotateIfNeeded(): void {
+    let filePeriod: string;
+    try {
+      filePeriod = _periodForDate(fs.statSync(this.logPath).mtime, this.when);
+    } catch {
+      return; // file doesn't exist yet
+    }
+    if (filePeriod === _periodForDate(new Date(), this.when)) return;
+    doRotate(this.logPath, this.keep);
+  }
+}
+
+// ── size/rotate parser ────────────────────────────────────────────────────────
+
+const SIZE_RE = /^(\d+(?:\.\d+)?)\s*(KB|MB|GB)$/i;
+const SIZE_MULT: Record<string, number> = { KB: 1024, MB: 1024 ** 2, GB: 1024 ** 3 };
+const TIMED_KEYS = new Set(['daily', 'midnight', 'weekly']);
+
+function makeFileHandler(logPath: string, rotate: string, keep: number): Handler {
+  const sizeMatch = SIZE_RE.exec(rotate);
+  if (sizeMatch) {
+    const maxBytes = Math.round(parseFloat(sizeMatch[1]) * SIZE_MULT[sizeMatch[2].toUpperCase()]);
+    return new SizeRotatingFileHandler(logPath, maxBytes, keep);
+  }
+  const when = rotate.toLowerCase();
+  if (TIMED_KEYS.has(when)) {
+    return new TimedRotatingFileHandler(logPath, when as 'daily' | 'midnight' | 'weekly', keep);
+  }
+  throw new Error(
+    `✗  [config.logging] rotate ${JSON.stringify(rotate)} not recognised.\n` +
+    `   Valid: '10 MB', '100 KB', '1 GB', 'daily', 'midnight', 'weekly'`,
+  );
+}
+
+// ── log dir resolution ────────────────────────────────────────────────────────
+
+function resolveLogDir(configPath: string): string {
+  const candidate = path.join(path.dirname(configPath), 'logs');
+  try {
+    fs.mkdirSync(candidate, { recursive: true });
+    const probe = path.join(candidate, '.wtest');
+    fs.writeFileSync(probe, '');
+    fs.unlinkSync(probe);
+    return candidate;
+  } catch {
+    const fallback = path.join(os.homedir(), 'logs');
+    fs.mkdirSync(fallback, { recursive: true });
+    return fallback;
+  }
+}
+
+// ── public: configureLogging ──────────────────────────────────────────────────
+
+export interface ConfigureLoggingOptions {
+  logCfg: LoggingConfig | undefined;
+  agent: boolean;
+  runnableName: string;
+  configPath: string;
+  logLevelOverride?: string;
+}
+
+export function configureLogging(opts: ConfigureLoggingOptions): void {
+  if (!opts.logCfg || _configured) return;
+
+  const effectiveLevelName = opts.logLevelOverride ?? opts.logCfg.level;
+  const effectiveLevel = LEVEL_NUM[effectiveLevelName] ?? LEVEL_NUM['info'];
+
+  if (!opts.agent) {
+    _handlers.push(new ConsoleHandler(effectiveLevel, effectiveLevelName === 'debug'));
+  }
+
+  const logDir = resolveLogDir(opts.configPath);
+  const logPath = path.join(logDir, `${opts.runnableName}.log`);
+  _handlers.push(makeFileHandler(logPath, opts.logCfg.rotate, opts.logCfg.keep));
+
+  _configured = true;
+}
+
+// ── test helper ───────────────────────────────────────────────────────────────
+
+export function _resetForTest(): void {
+  _configured = false;
+  _loggers.clear();
+  _handlers.length = 0;
+}
+
+export { _periodForDate };

package/src/models.ts

@@ -1,7 +1,25 @@
+export interface JumpHostConfig {
+  host: string;
+  user?: string;
+  port?: number;
+  sshKey?: string;
+  bin?: string;
+  useSshConfig?: boolean;
+  sshOptions?: string[];
+}
+
+export interface LoggingConfig {
+  level: string;
+  rotate: string;
+  keep: number;
+}
+
 export interface RawConfig {
   autonomyDefault: string;
   lang?: string;
   version: string;
+  jumpHosts: Record<string, JumpHostConfig>;
+  logging?: LoggingConfig;
 }
 
 export interface ArgSpec {
@@ -15,6 +33,7 @@ export interface ArgSpec {
   multiple?: boolean;
   delimiter?: string;
   short?: string;
+  position?: number;
   env?: string;
   deprecated?: string;
   autonomy?: string;
@@ -51,10 +70,13 @@ export interface RawSpec {
 
 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[];
+  readonly runspec_prefix: string;
 }

package/src/parser.ts

@@ -5,18 +5,20 @@ import { inferScript, effectiveAutonomy } from './inference';
 import { coerce } from './types';
 import { validateArgs, validateGroups, raiseIfErrors } from './validator';
 import { RunSpecError } from './errors';
+import { configureLogging } from './logging_setup';
 import type { ParsedArgs, ScriptSpec, ArgSpec } from './models';
 
 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 } = findConfig(cwd);
+  const { configPath } = configPathOverride ? { configPath: configPathOverride } : findConfig(cwd);
   const raw = loadRaw(configPath);
   const config = raw.config;
 
@@ -29,21 +31,41 @@ export function parse(opts: ParseOptions = {}): ParsedArgs {
     throw new RunSpecError(`✗  Runnable '${name}' not found.\n   Available: ${available}\n   Config: ${configPath}`);
   }
 
-  const rawScript = inferScript(raw.runnables[name], config.autonomyDefault);
+  let rawScript = inferScript(raw.runnables[name], config.autonomyDefault);
+
+  // Auto-inject --log-level when [config.logging] is present
+  if (config.logging && !('log-level' in rawScript.args)) {
+    rawScript = {
+      ...rawScript,
+      args: {
+        ...rawScript.args,
+        'log-level': {
+          name: 'log-level',
+          type: 'choice',
+          options: ['debug', 'info', 'warning', 'error', 'critical'],
+          default: config.logging.level,
+          required: false,
+          description: 'Override the console log level for this invocation.',
+          multiple: false,
+          env: 'RUNSPEC_LOG_LEVEL',
+        },
+      },
+    };
+  }
 
   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);
   }
 
@@ -64,14 +86,33 @@ export function parse(opts: ParseOptions = {}): ParsedArgs {
 
   const agent = ['1', 'true', 'yes'].includes((process.env['RUNSPEC_AGENT'] ?? '').toLowerCase());
 
+  const logLevelOverride = config.logging
+    ? (coercedValues['log_level'] as string | undefined) ?? undefined
+    : undefined;
+
+  try {
+    configureLogging({
+      logCfg: config.logging,
+      agent,
+      runnableName: name,
+      configPath,
+      logLevelOverride,
+    });
+  } catch (e) {
+    throw new RunSpecError((e as Error).message);
+  }
+
   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; },
+    get runspec_prefix() { return path.dirname(configPath); },
   } as ParsedArgs;
 }
 
@@ -95,15 +136,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 +195,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"}

package/src/types.ts

@@ -94,3 +94,4 @@ registerType('bool', coerceBool);
 registerType('flag', coerceFlag);
 registerType('path', coercePath);
 registerType('choice', coerceChoice);
+registerType('rest', (v) => (Array.isArray(v) ? v : []));

package/tests/test_cli_init.test.ts

@@ -107,11 +107,11 @@ test('--example creates clean.ts and scan.ts by default', () => {
   expect(fs.existsSync(path.join(dir, 'scan.ts'))).toBe(true);
 });
 
-test('--example clean stub uses __agent__ check', () => {
+test('--example clean stub uses __runspec_agent__ check', () => {
   const dir = tmpDir();
   runInit(dir, ['--example']);
   const ts = fs.readFileSync(path.join(dir, 'clean.ts'), 'utf-8');
-  expect(ts).toContain('__agent__');
+  expect(ts).toContain('__runspec_agent__');
   expect(ts).toContain('delete');
 });
 
@@ -186,10 +186,10 @@ test('emit command is no longer available', () => {
   expect(stdout).toContain('Unknown command');
 });
 
-test('jump command is recognized', () => {
+test('jump command requires a host name', () => {
   const dir = tmpDir();
-  const { stdout } = runCLI(dir, ['jump']);
-  expect(stdout).toContain('not yet implemented');
+  const { stderr } = runCLI(dir, ['jump']);
+  expect(stderr).toContain('jump host name is required');
 });
 
 // ── help ──────────────────────────────────────────────────────────────────────