impulso 0.22.0 → 0.24.0

package/scripts/install-hub.js

@@ -72,13 +72,54 @@ export async function installHub({
   return { target, updated: true, destination, version: packageVersion };
 }
 
+/**
+ * Installs the scout dispatch bridge (shared/scout-dispatch.cjs) as an
+ * executable on PATH at ~/.local/bin/impulso-scout-dispatch. Uses the same
+ * atomic-temp-rename pattern as installHub. Idempotent: skips if the
+ * existing file is identical (checked by size + mtime heuristic).
+ */
+export async function installScoutDispatch({
+  packageRoot = PACKAGE_ROOT,
+  destination = path.join(os.homedir(), '.local', 'bin', 'impulso-scout-dispatch'),
+} = {}) {
+  const source = path.join(packageRoot, 'shared', 'scout-dispatch.cjs');
+  await stat(source);
+
+  // Simple idempotency check: if destination exists and has same size as source, skip
+  try {
+    const srcStat = await stat(source);
+    const dstStat = await stat(destination);
+    if (dstStat.size === srcStat.size) {
+      return { updated: false, destination };
+    }
+  } catch (_e) {
+    // destination absent — fall through to copy
+  }
+
+  await mkdir(path.dirname(destination), { recursive: true });
+  const tempDir = await mkdtemp(path.join(path.dirname(destination), '.impulso-scout-'));
+  const temporary = path.join(tempDir, 'impulso-scout-dispatch');
+  try {
+    await copyFile(source, temporary);
+    await chmod(temporary, 0o755);
+    await rename(temporary, destination);
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+  return { updated: true, destination };
+}
+
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
   try {
-    const result = await installHub();
-    const action = result.updated ? 'Installed' : 'Already installed';
+    const hubResult = await installHub();
+    const hubAction = hubResult.updated ? 'Installed' : 'Already installed';
     console.log(
-      `    ${action} impulso-hub ${result.version} (${result.target}) -> ${result.destination}`,
+      `    ${hubAction} impulso-hub ${hubResult.version} (${hubResult.target}) -> ${hubResult.destination}`,
     );
+
+    const scoutResult = await installScoutDispatch();
+    const scoutAction = scoutResult.updated ? 'Installed' : 'Already installed';
+    console.log(`    ${scoutAction} impulso-scout-dispatch -> ${scoutResult.destination}`);
   } catch (error) {
     console.error(`ERROR: ${error.message}`);
     process.exitCode = 1;

package/shared/scout-dispatch.cjs

@@ -0,0 +1,499 @@
+#!/usr/bin/env node
+/**
+ * impulso-scout-dispatch — harness-owned synchronous read-only scout bridge.
+ *
+ * Launched by impulso-hub init when static test detection fails. Uses the
+ * installed harness (opencode or claude) to dispatch the scout subagent
+ * synchronously, producing a validated ScoutReport.
+ *
+ * Usage:
+ *   impulso-scout-dispatch --slug <slug> --workspace <abs-path> --timeout-ms <n>
+ *   stdin: {"schemaVersion":1,"slug":"...","workspace":"..."}
+ *   stdout: ScoutReport JSON
+ *   exit 0 on success, nonzero on failure
+ *
+ * Report path: <workspace>/reports/scout.json
+ */
+
+const { spawnSync } = require('node:child_process');
+const { existsSync, mkdirSync, readFileSync, writeFileSync } = require('node:fs');
+const { resolve, join, dirname } = require('node:path');
+
+// --- CLI argument parsing ---
+
+function usage() {
+  process.stderr.write(
+    'Usage: impulso-scout-dispatch --slug <slug> --workspace <abs-path> [--timeout-ms <n>]\n',
+  );
+  process.exit(2);
+}
+
+let slug = '';
+let workspace = '';
+let timeoutMs = 180_000; // default 3 min
+
+// Manual arg parsing (node:util parseArgs needs node 18.3+)
+const args = process.argv.slice(2);
+for (let i = 0; i < args.length; i++) {
+  switch (args[i]) {
+    case '--slug':
+      slug = args[++i] || '';
+      break;
+    case '--workspace':
+      workspace = args[++i] || '';
+      break;
+    case '--timeout-ms':
+      timeoutMs = parseInt(args[++i] || '180000', 10);
+      break;
+    case '-h':
+    case '--help':
+      usage();
+      break;
+    default:
+      process.stderr.write(`Unknown flag: ${args[i]}\n`);
+      usage();
+  }
+}
+
+if (!slug || !workspace) {
+  usage();
+}
+
+const absWorkspace = resolve(workspace);
+const reportPath = join(absWorkspace, 'reports', 'scout.json');
+
+// --- Stdin payload (optional validation) ---
+
+let stdinPayload = null;
+try {
+  // Read synchronously from stdin if data is available
+  // For piped input, readFileSync('/dev/stdin') works on Linux
+  const stdinData = readFileSync('/dev/stdin', 'utf8').trim();
+  if (stdinData) {
+    stdinPayload = JSON.parse(stdinData);
+  }
+} catch {
+  // stdin may not be available — that's OK
+}
+void stdinPayload; // may be used in future for payload validation
+
+// --- Detect harness ---
+
+function detectHarness() {
+  // Prefer opencode (primary harness), fall back to claude
+  const opencodeCheck = spawnSync('which', ['opencode'], {
+    stdio: 'pipe',
+    timeout: 5000,
+  });
+  if (opencodeCheck.status === 0 && opencodeCheck.stdout.toString().trim()) {
+    return 'opencode';
+  }
+  const claudeCheck = spawnSync('which', ['claude'], {
+    stdio: 'pipe',
+    timeout: 5000,
+  });
+  if (claudeCheck.status === 0 && claudeCheck.stdout.toString().trim()) {
+    return 'claude';
+  }
+  return null;
+}
+
+// --- Dispatch via opencode ---
+
+function dispatchOpenCode() {
+  // Ensure reports dir exists
+  mkdirSync(dirname(reportPath), { recursive: true });
+
+  // Write the initial context file that scout will read
+  const contextPath = join(absWorkspace, 'context.md');
+  const contextContent = [
+    `# Scout reconnaissance context`,
+    `slug: ${slug}`,
+    `workspace: ${absWorkspace}`,
+    `task: Determine the test framework used in this project. Look for test files, test configuration (package.json scripts.test, Makefile test target, go.mod, Cargo.toml, pyproject.toml, etc.). Report each finding with path:line refs.`,
+    ``,
+  ].join('\n');
+  writeFileSync(contextPath, contextContent, 'utf8');
+
+  // Build scout prompt
+  const prompt = [
+    'You are the scout subagent (read-only).',
+    'Explore the project at the current directory.',
+    'Inspect manifests (package.json, Makefile, go.mod, Cargo.toml, pyproject.toml),',
+    'package scripts, .github/workflows, test configs, targeted source/test directories,',
+    'and monorepo boundaries.',
+    'Determine what test command to use (or conclude no tests are present).',
+    'Write a JSON scout report to ' + reportPath + ' with this exact v2 schema:',
+    '{ "schemaVersion": 2, "slug": "' +
+      slug +
+      '", "reportPath": "' +
+      reportPath +
+      '", "command": "the test command", "noTest": false, "noTestJustification": "", "workingDirectory": "relative/path", "confidence": "high|medium|low", "evidence": [ { "ref": "path/to/file:lineNumber", "finding": "description" } ], "concerns": [], "findings": [ { "ref": "path/to/file:lineNumber", "finding": "description" } ] }',
+    '- "command": exact test command string (e.g. "npm test", "go test ./..."). Empty ONLY if noTest is true.',
+    '- "noTest": true ONLY when no test framework can be detected. When true, "command" must be empty.',
+    '- "noTestJustification": required when noTest is true. Explain why no tests were found.',
+    '- "workingDirectory": relative path from project root where the command should run (e.g. "packages/web/", "."). Must be relative, no ".." traversal.',
+    '- "confidence": high, medium, or low.',
+    '- "evidence": array of path:line refs pointing to manifests/configs that support your conclusion.',
+    '- "concerns": array of strings noting any caveats or limitations.',
+    '- "findings": general path:line observations about the project structure.',
+    'The "ref" field MUST use path:line format (e.g. main.go:42).',
+    'Do NOT modify any source files. Only read and write the report.',
+  ].join('\n');
+
+  const result = spawnSync(
+    'opencode',
+    ['run', '--agent', 'scout', '--format', 'json', '--dir', dirname(absWorkspace), prompt],
+    {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: timeoutMs,
+      env: { ...process.env },
+      maxBuffer: 10 * 1024 * 1024, // 10MB
+    },
+  );
+
+  return {
+    exitCode: result.status ?? 1,
+    stderr: result.stderr?.toString() || '',
+    error: result.error,
+  };
+}
+
+// --- Dispatch via claude ---
+
+function dispatchClaude() {
+  mkdirSync(dirname(reportPath), { recursive: true });
+
+  const contextPath = join(absWorkspace, 'context.md');
+  const contextContent = [
+    `# Scout reconnaissance context`,
+    `slug: ${slug}`,
+    `workspace: ${absWorkspace}`,
+    `task: Determine the test framework used in this project. Look for test files, test configuration. Report each finding with path:line refs.`,
+    ``,
+  ].join('\n');
+  writeFileSync(contextPath, contextContent, 'utf8');
+
+  const prompt = [
+    'You are the scout subagent (read-only).',
+    'Explore the project at the current directory.',
+    'Inspect manifests (package.json, Makefile, go.mod, Cargo.toml, pyproject.toml),',
+    'package scripts, .github/workflows, test configs, targeted source/test directories,',
+    'and monorepo boundaries.',
+    'Determine what test command to use (or conclude no tests are present).',
+    'Write a JSON scout report to ' + reportPath + ' with this exact v2 schema:',
+    '{ "schemaVersion": 2, "slug": "' +
+      slug +
+      '", "reportPath": "' +
+      reportPath +
+      '", "command": "the test command", "noTest": false, "noTestJustification": "", "workingDirectory": "relative/path", "confidence": "high|medium|low", "evidence": [ { "ref": "path/to/file:lineNumber", "finding": "description" } ], "concerns": [], "findings": [ { "ref": "path/to/file:lineNumber", "finding": "description" } ] }',
+    '- "command": exact test command string (e.g. "npm test", "go test ./..."). Empty ONLY if noTest is true.',
+    '- "noTest": true ONLY when no test framework can be detected. When true, "command" must be empty.',
+    '- "noTestJustification": required when noTest is true.',
+    '- "workingDirectory": relative path from project root where command should run.',
+    '- "confidence": high, medium, or low.',
+    '- "evidence": array of path:line refs to manifests/configs.',
+    '- "concerns": array of caveats or limitations.',
+    '- "findings": general path:line observations.',
+    'The "ref" field MUST use path:line format (e.g. main.go:42).',
+    'Do NOT modify any source files. Only read and write the report.',
+  ].join('\n');
+
+  const result = spawnSync(
+    'claude',
+    ['--agent', 'scout', '-p', '--output-format', 'json', prompt],
+    {
+      cwd: dirname(absWorkspace),
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: timeoutMs,
+      env: { ...process.env },
+      maxBuffer: 10 * 1024 * 1024,
+    },
+  );
+
+  return {
+    exitCode: result.status ?? 1,
+    stderr: result.stderr?.toString() || '',
+    error: result.error,
+  };
+}
+
+// --- Output helpers ---
+
+function fail(message) {
+  process.stderr.write(`impulso-scout-dispatch: ${message}\n`);
+  process.exit(1);
+}
+
+function outputReport(report) {
+  process.stdout.write(JSON.stringify(report));
+  process.exit(0);
+}
+
+// --- Validate scout report ---
+
+function validateReport(raw) {
+  try {
+    const report = JSON.parse(raw);
+
+    if (!report || typeof report !== 'object') {
+      return { valid: false, error: 'report is not a JSON object' };
+    }
+
+    if (report.schemaVersion !== 2) {
+      return {
+        valid: false,
+        error: `invalid schemaVersion: ${report.schemaVersion} (must be 2)`,
+      };
+    }
+
+    if (!report.slug || report.slug !== slug) {
+      return {
+        valid: false,
+        error: `slug mismatch: ${report.slug || '(empty)'} vs ${slug}`,
+      };
+    }
+
+    if (!report.reportPath) {
+      return { valid: false, error: 'missing reportPath' };
+    }
+
+    // Validate that reportPath matches the expected workspace path
+    const resolvedReturned = resolve(report.reportPath);
+    const resolvedExpected = resolve(reportPath);
+    if (resolvedReturned !== resolvedExpected) {
+      return {
+        valid: false,
+        error: `reportPath mismatch: returned ${report.reportPath}, expected ${reportPath}`,
+      };
+    }
+
+    // v2: command/noTest exclusivity
+    if (report.noTest === true) {
+      if (report.command && report.command !== '') {
+        return { valid: false, error: 'noTest=true and command are mutually exclusive' };
+      }
+      if (!report.noTestJustification || report.noTestJustification.trim() === '') {
+        return { valid: false, error: 'noTestJustification is required when noTest=true' };
+      }
+    } else {
+      if (!report.command || report.command.trim() === '') {
+        return { valid: false, error: 'command is required when noTest is false or absent' };
+      }
+    }
+
+    // v2: workingDirectory
+    if (!report.workingDirectory || report.workingDirectory.trim() === '') {
+      return { valid: false, error: 'workingDirectory is required' };
+    }
+    const wd = report.workingDirectory;
+    if (require('node:path').isAbsolute(wd)) {
+      return { valid: false, error: `workingDirectory must be relative, got absolute: ${wd}` };
+    }
+    if (wd.includes('..')) {
+      return { valid: false, error: `workingDirectory contains path traversal: ${wd}` };
+    }
+
+    // v2: confidence enum
+    if (!['low', 'medium', 'high'].includes(report.confidence)) {
+      return {
+        valid: false,
+        error: `invalid confidence: ${report.confidence} (must be low, medium, or high)`,
+      };
+    }
+
+    // v2: evidence array (can be empty)
+    if (!Array.isArray(report.evidence)) {
+      return { valid: false, error: 'evidence must be an array' };
+    }
+    for (let i = 0; i < report.evidence.length; i++) {
+      const f = report.evidence[i];
+      if (!f.ref || !/^[^/].+:\d+$/.test(f.ref)) {
+        return {
+          valid: false,
+          error: `evidence[${i}] has invalid ref: ${JSON.stringify(f.ref)} — must be path:line format`,
+        };
+      }
+      if (!f.finding || typeof f.finding !== 'string' || f.finding.trim() === '') {
+        return {
+          valid: false,
+          error: `evidence[${i}] has empty finding text`,
+        };
+      }
+    }
+
+    // v2: concerns is optional (can be absent or array)
+    if (report.concerns !== undefined && !Array.isArray(report.concerns)) {
+      return { valid: false, error: 'concerns must be an array if present' };
+    }
+
+    // findings: non-empty array
+    if (!Array.isArray(report.findings) || report.findings.length === 0) {
+      return {
+        valid: false,
+        error: 'findings must be a non-empty array',
+      };
+    }
+
+    for (let i = 0; i < report.findings.length; i++) {
+      const f = report.findings[i];
+      if (!f.ref || !/^[^/].+:\d+$/.test(f.ref)) {
+        return {
+          valid: false,
+          error: `finding[${i}] has invalid ref: ${JSON.stringify(f.ref)} — must be path:line format`,
+        };
+      }
+      if (!f.finding || typeof f.finding !== 'string' || f.finding.trim() === '') {
+        return {
+          valid: false,
+          error: `finding[${i}] has empty finding text`,
+        };
+      }
+    }
+
+    return { valid: true, report };
+  } catch (e) {
+    return { valid: false, error: `invalid JSON: ${e.message}` };
+  }
+}
+
+// --- Main ---
+
+function main() {
+  // 1. Check for existing validated report
+  if (existsSync(reportPath)) {
+    try {
+      const raw = readFileSync(reportPath, 'utf8');
+      const { valid, report } = validateReport(raw);
+      if (valid) {
+        outputReport(report);
+      }
+      // Invalid existing report — fall through to dispatch
+    } catch {
+      // Unreadable — fall through
+    }
+  }
+
+  // 2. Detect and dispatch via harness
+  const harness = detectHarness();
+  if (!harness) {
+    fail('no harness found on PATH (opencode or claude required for scout dispatch)');
+  }
+
+  const maxAttempts = 2;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    // emit telematics if enabled
+    emitLifecycle('scout.dispatch', 'started', { attempt });
+
+    let result;
+    if (harness === 'opencode') {
+      result = dispatchOpenCode();
+    } else {
+      result = dispatchClaude();
+    }
+
+    if (result.error) {
+      const reason = result.error.message || String(result.error);
+      emitLifecycle('scout.dispatch', 'failed', { attempt, reason });
+      if (attempt < maxAttempts) {
+        emitLifecycle('scout.dispatch', 'retry', {
+          attempt,
+          nextAttempt: attempt + 1,
+        });
+      }
+      continue;
+    }
+
+    // Check if report was produced
+    if (existsSync(reportPath)) {
+      try {
+        const raw = readFileSync(reportPath, 'utf8');
+        const { valid, report, error } = validateReport(raw);
+        if (valid) {
+          emitLifecycle('scout.dispatch', 'completed', {
+            attempt,
+            findingCount: report.findings.length,
+          });
+          outputReport(report);
+        }
+        if (attempt < maxAttempts) {
+          emitLifecycle('scout.dispatch', 'retry', {
+            attempt,
+            reason: `invalid report: ${error}`,
+          });
+        }
+      } catch (e) {
+        if (attempt < maxAttempts) {
+          emitLifecycle('scout.dispatch', 'retry', {
+            attempt,
+            reason: `report read error: ${e.message}`,
+          });
+        }
+      }
+    } else {
+      if (attempt < maxAttempts) {
+        emitLifecycle('scout.dispatch', 'retry', {
+          attempt,
+          reason: 'no report produced',
+        });
+      }
+    }
+
+    // continue loop for retry
+  }
+
+  // All attempts exhausted
+  emitLifecycle('scout.dispatch', 'failed', {
+    attempt: maxAttempts,
+    reason: 'all dispatch attempts exhausted',
+    harness,
+  });
+  fail(`scout dispatch failed after ${maxAttempts} attempts (${harness})`);
+}
+
+// --- Telematics ---
+// Uses existing shared/telematics.cjs module — config-gated: only emits
+// when $HOME/.impulso/config.json has telematics.enabled = true.
+// Redacts sensitive keys and patterns. Fails silently — telematics must
+// never disrupt the scout dispatch.
+
+let _telemetry = null;
+
+function getTelemetry() {
+  if (_telemetry) return _telemetry;
+  try {
+    const { createTelematics } = require('./telematics.cjs');
+    const os = require('node:os');
+    const path = require('node:path');
+    const crypto = require('node:crypto');
+    const home = process.env.IMPULSO_HOME || path.join(os.homedir(), '.impulso');
+    _telemetry = createTelematics({
+      harness: 'scout-dispatch',
+      sessionId: 'scout-' + slug + '-' + Date.now(),
+      processId: process.pid,
+      cwd: absWorkspace,
+      home: home,
+      now: () => new Date().toISOString(),
+      uuid: () => crypto.randomUUID(),
+      fs: require('node:fs'),
+    });
+  } catch (_) {
+    // Module unavailable or config load failed — create no-op fallback
+    _telemetry = {
+      enabled: false,
+      sessionId: null,
+      emit: () => {},
+      close: () => {},
+    };
+  }
+  return _telemetry;
+}
+
+function emitLifecycle(eventType, phase, meta) {
+  const tm = getTelemetry();
+  if (!tm.enabled) return;
+  tm.emit(eventType + '.' + phase, meta || {});
+}
+
+main();