runspec-node 0.23.0 → 0.25.0

package/src/cli.ts

@@ -2,6 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as readline from 'readline';
 import { findConfig } from './finder';
+import * as logs from './logs';
 import { loadRaw } from './loader';
 import { inferScript } from './inference';
 import { parse } from './parser';
@@ -32,6 +33,8 @@ export function main(): void {
   const commands: Record<string, (args: string[]) => void | Promise<void>> = {
     init: cmdInit,
     local: cmdLocal,
+    bin: cmdBin,
+    logs: cmdLogs,
     jump: cmdJump,
     serve: cmdServe,
   };
@@ -112,6 +115,186 @@ function cmdLocal(args: string[]): void {
   }
 }
 
+function cmdBin(_args: string[]): void {
+  let configPath: string;
+  try {
+    configPath = findConfig(process.cwd()).configPath;
+  } catch {
+    console.log("✗  No runspec.toml found. Run 'runspec init' first.");
+    process.exit(1);
+  }
+  const projectRoot = path.dirname(configPath);
+  const result = scaffoldBin(projectRoot);
+
+  console.log(`Wrote ${result.written.length} shim(s) to ${path.join(projectRoot, 'bin')}/:\n`);
+  for (const w of result.written) console.log(`  ✓  bin/${w.name}${w.target ? `  →  ${w.target}` : ''}`);
+  if (result.warnings.length) {
+    console.log('\nIssues:\n');
+    for (const msg of result.warnings) console.log(`  ✗  ${msg}`);
+  }
+  console.log('\nThis folder is now venv-shaped — a controller can invoke bin/<runnable> and');
+  console.log('discover/manage it via bin/runspec, from any working directory.');
+  if (result.warnings.length) process.exit(1);
+}
+
+/**
+ * Generate a venv-shaped `bin/` for the runnables declared in `{projectRoot}/
+ * runspec.toml`: a `bin/runspec` shim plus one `bin/<runnable>` per runnable.
+ * The shims resolve their own location, so the folder stays relocatable and
+ * works from any cwd (paired with caller-relative findConfig). Returns a
+ * summary; performs the filesystem writes. Exported for testing.
+ */
+export function scaffoldBin(projectRoot: string): { written: Array<{ name: string; target: string }>; warnings: string[] } {
+  const raw = loadRaw(configPathOf(projectRoot));
+  const runnables = Object.keys(raw.runnables);
+  const binMap = readBinMap(projectRoot);
+  const binDir = path.join(projectRoot, 'bin');
+  fs.mkdirSync(binDir, { recursive: true });
+  // The venv shape includes a logs/ dir (created lazily on first run anyway).
+  fs.mkdirSync(path.join(projectRoot, 'logs'), { recursive: true });
+
+  const written: Array<{ name: string; target: string }> = [];
+  const warnings: string[] = [];
+
+  // bin/runspec — the CLI a controller shells for discovery + log management.
+  const cliTarget = resolveRunspecCli(projectRoot);
+  if (cliTarget) {
+    writeShim(path.join(binDir, 'runspec'), toPosix(path.relative(projectRoot, cliTarget)));
+    written.push({ name: 'runspec', target: toPosix(path.relative(projectRoot, cliTarget)) });
+  } else {
+    warnings.push("runspec-node is not installed — run 'npm install runspec-node', then 'runspec bin' again (bin/runspec skipped)");
+  }
+
+  // bin/<runnable> — one per declared runnable.
+  for (const name of runnables) {
+    const script = resolveScript(projectRoot, name, binMap);
+    if (!script) {
+      warnings.push(`${name}: no script found — add package.json bin["${name}"] or create ./${name}.js`);
+      continue;
+    }
+    const rel = toPosix(path.relative(projectRoot, script));
+    writeShim(path.join(binDir, name), rel);
+    written.push({ name, target: rel });
+  }
+  return { written, warnings };
+}
+
+const SCRIPT_EXTS = ['.js', '.cjs', '.mjs'];
+
+function configPathOf(projectRoot: string): string {
+  return path.join(projectRoot, 'runspec.toml');
+}
+
+/** Resolve a runnable's script: package.json bin first, then ./<name>.{js,cjs,mjs}. */
+export function resolveScript(projectRoot: string, name: string, binMap: Record<string, string>): string | null {
+  if (binMap[name]) {
+    const p = path.resolve(projectRoot, binMap[name]);
+    return fs.existsSync(p) ? p : null;
+  }
+  for (const ext of SCRIPT_EXTS) {
+    const p = path.join(projectRoot, name + ext);
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+/** package.json `bin` as a {name: relPath} map. A string bin maps the package name. */
+export function readBinMap(projectRoot: string): Record<string, string> {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf-8'));
+    if (typeof pkg.bin === 'string') return pkg.name ? { [pkg.name]: pkg.bin } : {};
+    if (pkg.bin && typeof pkg.bin === 'object') return pkg.bin as Record<string, string>;
+  } catch {
+    // no package.json / unparseable — fall back to the file-name convention
+  }
+  return {};
+}
+
+function resolveRunspecCli(projectRoot: string): string | null {
+  const candidates = [
+    path.join(projectRoot, 'node_modules', 'runspec-node', 'bin', 'runspec.js'),
+    path.join(projectRoot, 'node_modules', '.bin', 'runspec'),
+  ];
+  return candidates.find((c) => fs.existsSync(c)) ?? null;
+}
+
+/** POSIX shim that resolves the project root relative to itself, then execs node. */
+export function shimContent(relPath: string): string {
+  return ['#!/bin/sh', '# Generated by `runspec bin` — do not edit.', 'DIR=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)', `exec node "$DIR/${relPath}" "$@"`, ''].join('\n');
+}
+
+function writeShim(shimPath: string, relPath: string): void {
+  fs.writeFileSync(shimPath, shimContent(relPath), 'utf-8');
+  fs.chmodSync(shimPath, 0o755);
+}
+
+function toPosix(p: string): string {
+  return p.split(path.sep).join('/');
+}
+
+function cmdLogs(args: string[]): void {
+  const has = (name: string): boolean => args.includes(name);
+  const valueFlags = new Set(['--since', '--user', '--run', '--older-than', '--max-files', '--max-total-size']);
+  const val = (name: string): string | undefined => {
+    const i = args.indexOf(name);
+    return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
+  };
+  // Positionals are tokens that aren't flags or flag-values.
+  const positionals: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('-')) {
+      if (valueFlags.has(a)) i++; // skip its value
+      continue;
+    }
+    positionals.push(a);
+  }
+
+  // `runspec logs status|prune|compact [runnable]` vs `runspec logs <runnable>`.
+  const target = positionals[0];
+  const verb = target === 'status' || target === 'prune' || target === 'compact' ? target : 'view';
+  const runnable = verb === 'view' ? target : positionals[1] ?? null;
+
+  try {
+    if (verb === 'view') {
+      if (!runnable) {
+        console.log('✗  A runnable is required: runspec logs <runnable>');
+        process.exit(1);
+      }
+      logs.view(runnable, {
+        since: val('--since') ? logs.parseDuration(val('--since')!) : null,
+        run: val('--run') ?? null,
+        user: val('--user') ?? null,
+        asJson: has('--json'),
+        follow: has('--follow'),
+      });
+    } else if (verb === 'status') {
+      logs.status(runnable, { asJson: has('--json') });
+    } else if (verb === 'prune') {
+      logs.prune(runnable, {
+        olderThan: val('--older-than') ? logs.parseDuration(val('--older-than')!) : null,
+        maxFiles: val('--max-files') ? parseInt(val('--max-files')!, 10) : null,
+        maxTotalSize: val('--max-total-size') ? logs.parseSize(val('--max-total-size')!) : null,
+        dryRun: has('--dry-run'),
+        asJson: has('--json'),
+      });
+    } else if (verb === 'compact') {
+      if (!val('--older-than')) {
+        console.log('✗  compact requires --older-than (e.g. --older-than 7d)');
+        process.exit(1);
+      }
+      logs.compact(runnable, logs.parseDuration(val('--older-than')!), {
+        gzip: has('--gzip'),
+        dryRun: has('--dry-run'),
+        asJson: has('--json'),
+      });
+    }
+  } catch (err) {
+    console.log(`✗  ${(err as Error).message}`);
+    process.exit(1);
+  }
+}
+
 async function cmdJump(args: string[]): Promise<void> {
   const parsed = parse({ scriptName: 'runspec', argv: ['jump', ...args], configPath: _CLI_CONFIG });
   const fmt = String(parsed['format'] ?? 'text');
@@ -632,6 +815,8 @@ Usage:
 Commands:
   init        Create runspec.toml and a code stub
   local       List runnables and emit tool schemas
+  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
   serve       Start the MCP stdio server for local runnables
 
@@ -642,6 +827,8 @@ Examples:
   runspec init --example
   runspec local
   runspec local --format mcp
+  runspec bin
+  runspec logs deploy
   runspec serve`);
 }
 
@@ -672,6 +859,39 @@ Examples:
   runspec local --format mcp --script deploy
   runspec local --format json`,
 
+    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,
+  so a controller (e.g. runspec-console) can invoke bin/<runnable> and discover
+  the folder via bin/runspec — from any working directory, including over SSH.
+
+  Each runnable's script is resolved from package.json "bin", falling back to
+  ./<runnable>.js | .cjs | .mjs next to runspec.toml. Re-run after adding a
+  runnable or 'npm install'. (POSIX shims; Windows support is a follow-up.)
+
+  Examples:
+    npm install runspec-node
+    runspec bin`,
+
+    logs: `runspec logs — View, status, prune, or compact per-invocation audit logs
+
+  For runnables using [config.logging] store = "per-run" (one file per
+  invocation, no in-process rotation). Reads/maintains the project's logs/.
+
+  View (default):
+    runspec logs <runnable>                 merged, timestamp-sorted stream
+    runspec logs <runnable> --follow         live tail across invocations
+    runspec logs <runnable> --since 1h --user alice --run <id>
+    runspec logs <runnable> --json           raw JSON lines
+
+  Status / retention (default to all runnables):
+    runspec logs status [runnable] [--json]  per-runnable file + disk inventory
+    runspec logs compact [runnable] --older-than 7d [--gzip] [--dry-run]
+    runspec logs prune [runnable] --older-than 90d | --max-files N | --max-total-size 5GB [--dry-run]
+
+  prune/compact never touch a single-mode {runnable}.log — only per-run files
+  and archives. Add --json to any verb for machine-readable output.`,
+
     jump: `runspec jump — Execute a runnable on a remote host via SSH
 
   Not yet implemented in the Node package.

package/src/logging_setup.ts

@@ -22,6 +22,16 @@ const _handlers: Handler[] = [];
 let _runId: string | null = null;
 
 const RUN_SUMMARY_LOGGER = 'runspec.runsummary';
+// Captured-stdout records are logged under this name (mirrors Python's
+// `runspec.print`). Used only for clarity in the audit file.
+const PRINT_LOGGER = 'runspec.print';
+
+// The real `process.stdout.write`, captured before we tee it. The stdout
+// handler writes through this so its own output isn't re-captured (mirrors
+// Python capturing the real sys.stdout reference before the tee swap).
+let _rawStdoutWrite: typeof process.stdout.write | null = null;
+let _stdoutBuf = '';
+let _captureInstalled = false;
 // Uncaught exceptions are emitted on this dedicated logger so the file handler
 // records them while the console handlers drop them by name — console display is
 // handled explicitly in _handleUncaught (debug-gated).
@@ -114,6 +124,10 @@ interface LogRecord {
   error?: Error;
   extra?: Record<string, unknown>;
   excStructured?: Record<string, unknown>;
+  // Set on records synthesised from captured stdout (print-capture). Console +
+  // counter handlers skip these (the real stdout write already happened, and
+  // printed lines aren't log "events"); only file handlers persist them.
+  fromPrint?: boolean;
 }
 
 interface Handler {
@@ -220,8 +234,11 @@ class StdoutHandler implements Handler {
   emit(record: LogRecord): void {
     if (record.levelNum >= 30) return; // WARNING+ belongs on stderr
     if (record.loggerName === RUN_SUMMARY_LOGGER || record.loggerName === EXCEPTION_LOGGER) return;
+    if (record.fromPrint) return; // the real stdout write already emitted this
     try {
-      process.stdout.write(formatConsole(record, this.showTracebacks) + '\n');
+      // Write through the *raw* stream so this output isn't re-captured by the
+      // print-capture tee (would double it in the audit file).
+      (_rawStdoutWrite ?? process.stdout.write.bind(process.stdout))(formatConsole(record, this.showTracebacks) + '\n');
     } catch {
       // never disrupt
     }
@@ -262,8 +279,9 @@ class RunSummaryCounter implements Handler {
   };
 
   emit(record: LogRecord): void {
-    // Don't count runspec's own bookkeeping records (summary + uncaught-exception).
-    if (record.loggerName === RUN_SUMMARY_LOGGER || record.loggerName === EXCEPTION_LOGGER) return;
+    // Don't count runspec's own bookkeeping records (summary + uncaught-exception)
+    // or captured stdout lines — only genuine logger events.
+    if (record.loggerName === RUN_SUMMARY_LOGGER || record.loggerName === EXCEPTION_LOGGER || record.fromPrint) return;
     const label = LEVEL_LABEL[record.levelNum];
     if (label && label in this.counts) {
       this.counts[label]++;
@@ -617,6 +635,61 @@ export function _handleUncaught(err: Error): void {
   }
 }
 
+// ── stdout capture (print → audit log) ─────────────────────────────────────────
+
+/** Emit one captured stdout line as a file-only record (skipped by console + counter). */
+function emitPrintLine(line: string): void {
+  if (_handlers.length === 0) return;
+  const record: LogRecord = { ts: new Date(), levelNum: 20, loggerName: PRINT_LOGGER, message: redact(line), fromPrint: true };
+  for (const h of _handlers) {
+    try {
+      if (record.levelNum >= h.level) h.emit(record);
+    } catch {
+      // never disrupt
+    }
+  }
+}
+
+/**
+ * Tee `process.stdout.write`: output still reaches the real stream unchanged
+ * (so pipes / `runspec serve` capture are untouched), and each complete line is
+ * also written to the audit file as a `fromPrint` record. Mirrors Python's
+ * `_StdoutTee`, so a runnable's `console.log` output is preserved in the
+ * per-invocation log — not just the run summary.
+ */
+function installStdoutCapture(): void {
+  if (_captureInstalled) return;
+  _captureInstalled = true;
+  _rawStdoutWrite = process.stdout.write.bind(process.stdout);
+  const patched = function (chunk: unknown, encoding?: unknown, cb?: unknown): boolean {
+    const result = (_rawStdoutWrite as (...a: unknown[]) => boolean)(chunk, encoding, cb);
+    try {
+      const s = typeof chunk === 'string' ? chunk : Buffer.isBuffer(chunk) ? chunk.toString(typeof encoding === 'string' ? (encoding as BufferEncoding) : 'utf8') : '';
+      if (s) {
+        _stdoutBuf += s;
+        let idx: number;
+        while ((idx = _stdoutBuf.indexOf('\n')) !== -1) {
+          const line = _stdoutBuf.slice(0, idx);
+          _stdoutBuf = _stdoutBuf.slice(idx + 1);
+          if (line) emitPrintLine(line);
+        }
+      }
+    } catch {
+      // never disrupt
+    }
+    return result;
+  };
+  process.stdout.write = patched as typeof process.stdout.write;
+  // Flush a trailing partial line at exit. Registered before installExitHooks so
+  // it runs before the run-summary record (FIFO exit handlers).
+  process.on('exit', () => {
+    if (_stdoutBuf) {
+      emitPrintLine(_stdoutBuf);
+      _stdoutBuf = '';
+    }
+  });
+}
+
 function installExitHooks(): void {
   if (_exitHooksInstalled) return;
   _exitHooksInstalled = true;
@@ -740,6 +813,10 @@ export function configureLogging(opts: ConfigureLoggingOptions): void {
     };
   }
 
+  // Tee stdout into the audit log so printed output (not just the run summary)
+  // is preserved. Installed before the exit hooks so its flush runs first.
+  installStdoutCapture();
+
   // Uncaught-exception handling is always installed (independent of the summary
   // toggle) so the structured exception record reaches the audit file even when
   // summary is off. The exit hook only flushes a summary when _summaryState is set.
@@ -757,8 +834,15 @@ export function _resetForTest(): void {
   _loggers.clear();
   _handlers.length = 0;
   _summaryState = null;
+  // Un-tee stdout so the patch doesn't leak across tests.
+  if (_rawStdoutWrite) {
+    process.stdout.write = _rawStdoutWrite;
+    _rawStdoutWrite = null;
+  }
+  _stdoutBuf = '';
+  _captureInstalled = false;
   // Note: process event listeners installed by installExitHooks() stay —
   // they no-op when _summaryState is null, which is the test-time state.
 }
 
-export { _periodForDate, RUN_SUMMARY_LOGGER, EXCEPTION_LOGGER, buildExcStructured, formatCompactTrace };
+export { _periodForDate, RUN_SUMMARY_LOGGER, EXCEPTION_LOGGER, buildExcStructured, formatCompactTrace, findProjectRoot };