runspec-node 0.24.0 → 0.26.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';
@@ -33,6 +34,7 @@ export function main(): void {
     init: cmdInit,
     local: cmdLocal,
     bin: cmdBin,
+    logs: cmdLogs,
     jump: cmdJump,
     serve: cmdServe,
   };
@@ -124,7 +126,7 @@ function cmdBin(_args: string[]): void {
   const projectRoot = path.dirname(configPath);
   const result = scaffoldBin(projectRoot);
 
-  console.log(`Wrote ${result.written.length} shim(s) to ${path.join(projectRoot, 'bin')}/:\n`);
+  console.log(`Wrote ${result.written.length} shim(s) (POSIX + .cmd) 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');
@@ -221,15 +223,88 @@ 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');
 }
 
+/** Windows batch shim. `%~dp0` is the bin/ dir (trailing `\`), so `%~dp0..\<rel>`
+ * resolves the target relative to the folder; `%*` forwards args and node's exit
+ * code propagates as the script's. CRLF line endings per Windows convention. */
+export function cmdShimContent(relPath: string): string {
+  const relWin = relPath.split('/').join('\\');
+  return ['@echo off', 'REM Generated by `runspec bin` — do not edit.', `node "%~dp0..\\${relWin}" %*`, ''].join('\r\n');
+}
+
+/** Write a POSIX shim plus a Windows `.cmd` alongside it, so one folder runs on both. */
 function writeShim(shimPath: string, relPath: string): void {
   fs.writeFileSync(shimPath, shimContent(relPath), 'utf-8');
   fs.chmodSync(shimPath, 0o755);
+  fs.writeFileSync(shimPath + '.cmd', cmdShimContent(relPath), 'utf-8');
 }
 
 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');
@@ -751,6 +826,7 @@ 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
 
@@ -762,6 +838,7 @@ Examples:
   runspec local
   runspec local --format mcp
   runspec bin
+  runspec logs deploy
   runspec serve`);
 }
 
@@ -800,12 +877,32 @@ Examples:
 
   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.)
+  runnable or 'npm install'. Writes both a POSIX shim and a Windows .cmd per
+  runnable, so one folder runs on either OS.
 
   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 };