runspec-node 0.11.1 → 0.13.0

package/src/serve.ts

@@ -139,13 +139,26 @@ function handleToolsCall(
   const runspecEnv = argsToRunspecEnv(args, toolArgSpecs);
   const env = { ...process.env, RUNSPEC_AGENT: '1', ...runspecEnv };
 
+  const start = process.hrtime.bigint();
   const result = spawnSync(cmd, argv, { encoding: 'utf-8', env });
+  const durationMs = Number((process.hrtime.bigint() - start) / 1_000_000n);
+
+  // _meta is the MCP-standard extension point; clients that don't understand
+  // it ignore the block. Same envelope on success and failure so callers can
+  // rely on it being present.
+  const meta = {
+    runspec: { tool: name, duration_ms: durationMs, exit_code: result.status ?? null },
+  };
 
   if (result.status === 0) {
     return {
       jsonrpc: '2.0',
       id: reqId,
-      result: { content: [{ type: 'text', text: result.stdout ?? '' }], isError: false },
+      result: {
+        content: [{ type: 'text', text: result.stdout ?? '' }],
+        isError: false,
+        _meta: meta,
+      },
     };
   }
 
@@ -156,7 +169,11 @@ function handleToolsCall(
   return {
     jsonrpc: '2.0',
     id: reqId,
-    result: { content: [{ type: 'text', text: parts.join('\n') }], isError: true },
+    result: {
+      content: [{ type: 'text', text: parts.join('\n') }],
+      isError: true,
+      _meta: meta,
+    },
   };
 }
 
@@ -192,7 +209,7 @@ function argsToRunspecEnv(args: Record<string, unknown>, argSpecs: Record<string
     if (value === null || value === undefined) value = s['default'];
     if (value === null || value === undefined) continue;
 
-    const envKey = 'RUNSPEC_' + argName.toUpperCase().replace(/-/g, '_').replace(/\./g, '_');
+    const envKey = 'RUNSPEC_ARG_' + argName.toUpperCase().replace(/-/g, '_').replace(/\./g, '_');
     const argType = (s['type'] as string) ?? 'str';
 
     if (argType === 'flag' || argType === 'bool') {

package/tests/test_integration.test.ts

@@ -123,7 +123,7 @@ describe('complex.toml', () => {
     const raw = loadRaw(COMPLEX);
     const inferred = inferScript(raw.runnables['pipeline'], raw.config.autonomyDefault);
     const run = inferred.commands['run'];
-    expect(run.args['api-key'].env).toBe('PIPELINE_API_KEY');
+    expect(run.args['api-key'].env).toEqual(['PIPELINE_API_KEY']);
     expect(run.args['api-key'].autonomy).toBe('manual');
   });
 

package/tests/test_loader.test.ts

@@ -145,7 +145,7 @@ test('normalises [config.logging] with defaults', () => {
 description = "hi"
 `);
   const raw = loadRaw(file);
-  expect(raw.config.logging).toEqual({ rotate: 'midnight', keep: 7 });
+  expect(raw.config.logging).toEqual({ rotate: 'midnight', keep: 7, summary: true });
 });
 
 test('normalises [config.logging] all fields', () => {
@@ -153,14 +153,28 @@ test('normalises [config.logging] all fields', () => {
   const file = path.join(dir, 'runspec.toml');
   fs.writeFileSync(file, `
 [config.logging]
-rotate = "10 MB"
-keep   = 3
+rotate  = "10 MB"
+keep    = 3
+summary = false
 
 [greet]
 description = "hi"
 `);
   const raw = loadRaw(file);
-  expect(raw.config.logging).toEqual({ rotate: '10 MB', keep: 3 });
+  expect(raw.config.logging).toEqual({ rotate: '10 MB', keep: 3, summary: false });
+});
+
+test('[config.logging] summary defaults to true when omitted', () => {
+  const dir = tmpDir();
+  const file = path.join(dir, 'runspec.toml');
+  fs.writeFileSync(file, `
+[config.logging]
+rotate = "midnight"
+
+[greet]
+description = "hi"
+`);
+  expect(loadRaw(file).config.logging?.summary).toBe(true);
 });
 
 test('logging is undefined when section absent', () => {

package/tests/test_logging_setup.test.ts

@@ -10,13 +10,20 @@ import {
 } from '../src/logging_setup';
 
 function tmpDir(): string {
-  return fs.mkdtempSync(path.join(os.tmpdir(), 'runspec-log-test-'));
+  // Each test dir is its own project root so resolveLogDir lands inside it.
+  // Without a package.json the walk-up would escape to a real project root
+  // and write logs to a shared location — drop a marker file to anchor it.
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'runspec-log-test-'));
+  fs.writeFileSync(path.join(d, 'package.json'), '{"name":"test","version":"0.0.0"}');
+  return d;
 }
 
 function makeCfg(dir: string, overrides: Record<string, unknown> = {}): Parameters<typeof configureLogging>[0] {
   const { debug, ...logOverrides } = overrides as { debug?: boolean } & Record<string, unknown>;
   return {
-    logCfg: { rotate: 'midnight', keep: 7, ...logOverrides },
+    // summary defaults off in tests so we don't litter atexit emissions across
+    // unrelated assertions; the run-summary suite enables it explicitly.
+    logCfg: { rotate: 'midnight', keep: 7, summary: false, ...logOverrides },
     runnableName: 'myscript',
     configPath: path.join(dir, 'runspec.toml'),
     debug,
@@ -365,7 +372,7 @@ test('_periodForDate weekly: adjacent weeks differ', () => {
 
 // ── log dir fallback ──────────────────────────────────────────────────────────
 
-test('falls back to ~/logs when package dir is not writable', () => {
+test('falls back to ~/logs when the project root is not writable', () => {
   const dir = tmpDir();
   const logsDir = path.join(dir, 'logs');
   // Create logs dir as unwritable

package/tests/test_parser.test.ts

@@ -0,0 +1,67 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { parse } from '../src/parser';
+
+function makeTmpConfig(toml: string): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'runspec-parser-test-'));
+  const configPath = path.join(dir, 'runspec.toml');
+  fs.writeFileSync(configPath, toml);
+  return configPath;
+}
+
+const QUALITY_TOML = `
+[compress]
+[compress.args]
+quality = {default = 85, range = [1, 100]}
+`;
+
+const QUALITY_ALIAS_TOML = `
+[compress]
+[compress.args]
+quality = {default = 85, range = [1, 100], env = "CI_QUALITY"}
+`;
+
+// ── env resolution tier ───────────────────────────────────────────────────────
+
+describe('env resolution', () => {
+  afterEach(() => {
+    delete process.env['RUNSPEC_ARG_QUALITY'];
+    delete process.env['CI_QUALITY'];
+  });
+
+  test('RUNSPEC_ARG_* provides auto default when no CLI arg', () => {
+    const configPath = makeTmpConfig(QUALITY_TOML);
+    process.env['RUNSPEC_ARG_QUALITY'] = '95';
+    const args = parse({ scriptName: 'compress', argv: [], configPath });
+    expect(args['quality']).toBe(95);
+  });
+
+  test('CLI arg wins over RUNSPEC_ARG_*', () => {
+    const configPath = makeTmpConfig(QUALITY_TOML);
+    process.env['RUNSPEC_ARG_QUALITY'] = '95';
+    const args = parse({ scriptName: 'compress', argv: ['--quality', '80'], configPath });
+    expect(args['quality']).toBe(80);
+  });
+
+  test('developer alias fallback when RUNSPEC_ARG_* not set', () => {
+    const configPath = makeTmpConfig(QUALITY_ALIAS_TOML);
+    process.env['CI_QUALITY'] = '70';
+    const args = parse({ scriptName: 'compress', argv: [], configPath });
+    expect(args['quality']).toBe(70);
+  });
+
+  test('RUNSPEC_ARG_* wins over developer alias', () => {
+    const configPath = makeTmpConfig(QUALITY_ALIAS_TOML);
+    process.env['RUNSPEC_ARG_QUALITY'] = '95';
+    process.env['CI_QUALITY'] = '70';
+    const args = parse({ scriptName: 'compress', argv: [], configPath });
+    expect(args['quality']).toBe(95);
+  });
+
+  test('no env vars set falls back to spec default', () => {
+    const configPath = makeTmpConfig(QUALITY_TOML);
+    const args = parse({ scriptName: 'compress', argv: [], configPath });
+    expect(args['quality']).toBe(85);
+  });
+});

package/tests/test_run_summary.test.ts

@@ -0,0 +1,204 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import {
+  configureLogging,
+  getLogger,
+  emitRunSummary,
+  _resetForTest,
+  RUN_SUMMARY_LOGGER,
+} from '../src/logging_setup';
+
+function tmpDir(): string {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'runspec-summary-test-'));
+  fs.writeFileSync(path.join(d, 'package.json'), '{"name":"test","version":"0.0.0"}');
+  return d;
+}
+
+function makeCfg(dir: string, overrides: Record<string, unknown> = {}): Parameters<typeof configureLogging>[0] {
+  const { debug, noSummary, autonomy, agent, commandPath, ...logOverrides } = overrides as {
+    debug?: boolean; noSummary?: boolean; autonomy?: string; agent?: boolean; commandPath?: string[];
+  } & Record<string, unknown>;
+  return {
+    logCfg: { rotate: 'midnight', keep: 7, summary: true, ...logOverrides },
+    runnableName: 'myscript',
+    configPath: path.join(dir, 'runspec.toml'),
+    debug,
+    noSummary,
+    autonomy,
+    agent,
+    commandPath,
+  };
+}
+
+function captureStderr() {
+  const lines: string[] = [];
+  const spy = jest.spyOn(process.stderr, 'write').mockImplementation((chunk) => {
+    lines.push(String(chunk));
+    return true;
+  });
+  return { lines, restore() { spy.mockRestore(); } };
+}
+
+beforeEach(() => {
+  _resetForTest();
+  delete process.env['RUNSPEC_ARG_NO_SUMMARY'];
+});
+
+afterAll(() => {
+  // Final cleanup so jest's own process-exit doesn't trigger a summary
+  // emit against a stale state pointing at a tmp dir.
+  _resetForTest();
+});
+
+// ── counter ──────────────────────────────────────────────────────────────────
+
+test('counter increments per level', () => {
+  const dir = tmpDir();
+  configureLogging(makeCfg(dir));
+  const log = getLogger('test.counter');
+  log.info('one');
+  log.info('two');
+  log.warning('careful');
+  log.error('broke');
+  const cap = captureStderr();
+  emitRunSummary();
+  cap.restore();
+  const content = fs.readFileSync(path.join(dir, 'logs', 'myscript.log'), 'utf-8');
+  const summary = content.trim().split('\n').map(l => JSON.parse(l)).find(o => o.logger === RUN_SUMMARY_LOGGER);
+  expect(summary.extra.events).toEqual({ DEBUG: 0, INFO: 2, WARNING: 1, ERROR: 1, CRITICAL: 0 });
+});
+
+test('counter ignores the summary logger itself', () => {
+  const dir = tmpDir();
+  configureLogging(makeCfg(dir));
+  // Calling the summary logger directly must not inflate counts.
+  getLogger(RUN_SUMMARY_LOGGER).info('should not count');
+  const cap = captureStderr();
+  emitRunSummary();
+  cap.restore();
+  const content = fs.readFileSync(path.join(dir, 'logs', 'myscript.log'), 'utf-8');
+  const lines = content.trim().split('\n').map(l => JSON.parse(l));
+  const summary = lines.find(o => o.logger === RUN_SUMMARY_LOGGER && o.extra?.event === 'run_summary');
+  expect(summary.extra.events).toEqual({ DEBUG: 0, INFO: 0, WARNING: 0, ERROR: 0, CRITICAL: 0 });
+});
+
+// ── emit ─────────────────────────────────────────────────────────────────────
+
+test('summary writes one record to the audit file', () => {
+  const dir = tmpDir();
+  configureLogging(makeCfg(dir, { autonomy: 'confirm', agent: false }));
+  getLogger('test.emit').info('did work');
+  getLogger('test.emit').warning('a warning');
+  const cap = captureStderr();
+  emitRunSummary();
+  cap.restore();
+  const content = fs.readFileSync(path.join(dir, 'logs', 'myscript.log'), 'utf-8');
+  const summaries = content.trim().split('\n').map(l => JSON.parse(l)).filter(o => o.logger === RUN_SUMMARY_LOGGER);
+  expect(summaries).toHaveLength(1);
+  const s = summaries[0];
+  expect(s.message).toBe('run completed');
+  expect(s.extra.event).toBe('run_summary');
+  expect(s.extra.runnable).toBe('myscript');
+  expect(s.extra.events.INFO).toBe(1);
+  expect(s.extra.events.WARNING).toBe(1);
+  expect(s.extra.exit_code).toBe(0);
+  expect(s.extra.exception).toBeNull();
+  expect(typeof s.extra.duration_ms).toBe('number');
+});
+
+test('summary writes a one-line summary to stderr', () => {
+  const dir = tmpDir();
+  configureLogging(makeCfg(dir));
+  getLogger('test.stderr').info('ran');
+  const cap = captureStderr();
+  emitRunSummary();
+  cap.restore();
+  const joined = cap.lines.join('');
+  expect(joined).toContain('runspec: myscript completed');
+  expect(joined).toContain('events');
+});
+
+test('summary is not echoed to stdout or stderr via console handlers', () => {
+  const dir = tmpDir();
+  const stdoutLines: string[] = [];
+  const stderrLines: string[] = [];
+  const o = jest.spyOn(process.stdout, 'write').mockImplementation((chunk) => { stdoutLines.push(String(chunk)); return true; });
+  const e = jest.spyOn(process.stderr, 'write').mockImplementation((chunk) => { stderrLines.push(String(chunk)); return true; });
+  configureLogging(makeCfg(dir));
+  getLogger('test.console').info('hi');
+  emitRunSummary();
+  o.mockRestore();
+  e.mockRestore();
+  // The JSON form of the summary record must not appear on either stream.
+  expect(stdoutLines.join('')).not.toContain('"logger":"runspec.runsummary"');
+  expect(stderrLines.join('').match(/"logger":"runspec.runsummary"/)).toBeNull();
+});
+
+test('summary emit is idempotent', () => {
+  const dir = tmpDir();
+  configureLogging(makeCfg(dir));
+  const cap = captureStderr();
+  emitRunSummary();
+  emitRunSummary();
+  cap.restore();
+  const content = fs.readFileSync(path.join(dir, 'logs', 'myscript.log'), 'utf-8');
+  const summaries = content.trim().split('\n').map(l => JSON.parse(l)).filter(o => o.logger === RUN_SUMMARY_LOGGER);
+  expect(summaries).toHaveLength(1);
+});
+
+// ── disable switches ─────────────────────────────────────────────────────────
+
+test('noSummary option disables summary', () => {
+  const dir = tmpDir();
+  configureLogging(makeCfg(dir, { noSummary: true }));
+  const cap = captureStderr();
+  emitRunSummary(); // no-op because state is null
+  cap.restore();
+  expect(cap.lines.join('')).not.toContain('runspec: ');
+  expect(fs.existsSync(path.join(dir, 'logs', 'myscript.log'))).toBe(false);
+});
+
+test('summary=false in config disables summary', () => {
+  const dir = tmpDir();
+  configureLogging(makeCfg(dir, { summary: false }));
+  const cap = captureStderr();
+  emitRunSummary();
+  cap.restore();
+  expect(cap.lines.join('')).not.toContain('runspec: ');
+});
+
+test('RUNSPEC_ARG_NO_SUMMARY=1 disables summary', () => {
+  process.env['RUNSPEC_ARG_NO_SUMMARY'] = '1';
+  const dir = tmpDir();
+  configureLogging(makeCfg(dir));
+  const cap = captureStderr();
+  emitRunSummary();
+  cap.restore();
+  expect(cap.lines.join('')).not.toContain('runspec: ');
+});
+
+// ── stderr line shape ────────────────────────────────────────────────────────
+
+test('success line uses singular "warning" for 1 and plural "errors" for 0', () => {
+  const dir = tmpDir();
+  configureLogging(makeCfg(dir));
+  getLogger('t').warning('one');
+  const cap = captureStderr();
+  emitRunSummary();
+  cap.restore();
+  const joined = cap.lines.join('');
+  expect(joined).toContain('1 warning,');
+  expect(joined).toContain('0 errors)');
+});
+
+test('success line uses plural for 2 warnings', () => {
+  const dir = tmpDir();
+  configureLogging(makeCfg(dir));
+  getLogger('t').warning('a');
+  getLogger('t').warning('b');
+  const cap = captureStderr();
+  emitRunSummary();
+  cap.restore();
+  expect(cap.lines.join('')).toContain('2 warnings,');
+});

package/tsconfig.json

@@ -11,7 +11,8 @@
     "sourceMap": true,
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
-    "skipLibCheck": true
+    "skipLibCheck": true,
+    "types": ["node", "jest"]
   },
   "include": ["src"],
   "exclude": ["node_modules", "dist", "tests"]