amicus 1.0.0

package/src/utils/result-schema.js

@@ -0,0 +1,261 @@
+// src/utils/result-schema.js
+'use strict';
+
+/**
+ * @module result-schema
+ * Versioned, machine-parseable result documents for `--json` output (F4).
+ *
+ * Stability contract: fields are only ADDED within a SCHEMA_VERSION;
+ * any rename/removal bumps SCHEMA_VERSION.
+ */
+
+const SCHEMA_VERSION = 1;
+
+/** Leg/run statuses that count as terminal for wave aggregation. */
+const TERMINAL_STATUSES = ['complete', 'error', 'timeout', 'aborted', 'crashed', 'idle-timeout'];
+
+/**
+ * Map a runHeadless-style result object to a run status.
+ * Precedence: aborted > timeout > error > complete.
+ * @param {{aborted?: boolean, timedOut?: boolean, error?: string}} result
+ * @returns {string}
+ */
+function statusFromResult(result) {
+  if (result.aborted) { return 'aborted'; }
+  if (result.timedOut) { return 'timeout'; }
+  if (result.error) { return 'error'; }
+  return 'complete';
+}
+
+/** Millisecond delta between two ISO timestamps, or null if either is missing/malformed. */
+function durationBetween(createdAt, completedAt) {
+  if (!createdAt || !completedAt) { return null; }
+  const ms = new Date(completedAt).getTime() - new Date(createdAt).getTime();
+  return Number.isNaN(ms) ? null : ms;
+}
+
+/**
+ * Build a run document (single session result).
+ * Used by `start --json`, `read <taskId> --json`, and every wave leg.
+ *
+ * @param {object} opts
+ * @param {string} opts.taskId
+ * @param {object} [opts.metadata] - Session metadata (model, agent, timestamps, status…)
+ * @param {object|null} [opts.result] - Live runHeadless result (flags win over metadata.status)
+ * @param {string|null} [opts.summary]
+ * @param {string|null} [opts.modelInput] - What the caller typed (alias), if known
+ * @param {string|null} [opts.sessionDir]
+ * @param {string|null} [opts.waveId] - Explicit wave id (falls back to metadata.parentWave)
+ * @returns {object} run document
+ */
+function buildRunResult({ taskId, metadata = {}, result = null, summary = null, modelInput = null, sessionDir = null, waveId = null }) {
+  const status = result ? statusFromResult(result) : (metadata.status || 'unknown');
+  const createdAt = metadata.createdAt || null;
+  const completedAt = metadata.completedAt || metadata.abortedAt || null;
+  const durationMs = durationBetween(createdAt, completedAt);
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    type: 'run',
+    taskId,
+    waveId: waveId !== null ? waveId : (metadata.parentWave || null),
+    model: metadata.model || null,
+    modelInput: modelInput !== null ? modelInput : (metadata.modelInput || null),
+    agent: metadata.agent || null,
+    status,
+    summary,
+    error: status === 'complete' ? null : ((result && result.error) || metadata.reason || null),
+    createdAt,
+    completedAt,
+    durationMs,
+    sessionDir,
+    opencodeSessionId: metadata.opencodeSessionId || null,
+  };
+}
+
+/**
+ * Aggregate wave status from leg documents.
+ * any leg running → 'running' (live rebuild of an in-flight wave);
+ * all complete → 'complete'; ≥1 complete → 'partial';
+ * 0 complete + ≥1 aborted → 'aborted'; else 'error'.
+ * @param {Array<{status: string}>} legs
+ * @returns {string}
+ */
+function waveStatusFromLegs(legs) {
+  if (legs.some(l => l.status === 'running')) { return 'running'; }
+  const complete = legs.filter(l => l.status === 'complete').length;
+  if (complete === legs.length && legs.length > 0) { return 'complete'; }
+  if (complete > 0) { return 'partial'; }
+  if (legs.some(l => l.status === 'aborted')) { return 'aborted'; }
+  return 'error';
+}
+
+/**
+ * Map a wave status to a CLI exit code: complete=0, partial=2, error/aborted=1.
+ * @param {string} waveStatus
+ * @returns {number}
+ */
+function waveExitCode(waveStatus) {
+  if (waveStatus === 'complete') { return 0; }
+  if (waveStatus === 'partial') { return 2; }
+  return 1;
+}
+
+/**
+ * Build a wave document from leg run documents.
+ * @param {object} opts
+ * @param {string} opts.waveId
+ * @param {Array<object>} opts.legs - run documents (in --models order)
+ * Counts track the four primary terminal statuses (complete/error/timeout/aborted);
+ * legs with other statuses (e.g. 'crashed', 'running' in a rebuilt wave) count toward
+ * `total` only, so total may exceed the sum of the named buckets.
+ * @param {{source: string, file: string|null, chars: number}|null} [opts.promptMeta]
+ * @param {string|null} [opts.createdAt]
+ * @param {string|null} [opts.completedAt]
+ * @param {string|null} [opts.status] - Override (e.g. 'aborted' on signal); default aggregates legs
+ * @returns {object} wave document
+ */
+function buildWaveResult({ waveId, legs = [], promptMeta = null, createdAt = null, completedAt = null, status = null }) {
+  const counts = {
+    total: legs.length,
+    complete: legs.filter(l => l.status === 'complete').length,
+    error: legs.filter(l => l.status === 'error').length,
+    timeout: legs.filter(l => l.status === 'timeout').length,
+    aborted: legs.filter(l => l.status === 'aborted').length,
+  };
+  const durationMs = durationBetween(createdAt, completedAt);
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    type: 'wave',
+    waveId,
+    status: (status !== null && status !== undefined) ? status : waveStatusFromLegs(legs),
+    error: null,
+    counts,
+    legs,
+    prompt: promptMeta,
+    createdAt,
+    completedAt,
+    durationMs,
+  };
+}
+
+/**
+ * Rebuild a run document from a persisted session directory.
+ * @param {string} project - Project dir
+ * @param {string} taskId
+ * @returns {object} run document
+ * @throws {Error} if the session does not exist
+ * @throws {Error} if metadata.json is missing or corrupt
+ */
+function buildRunResultFromSession(project, taskId) {
+  const fs = require('fs');
+  const path = require('path');
+  const { resolveExistingSessionDir } = require('../session-manager');
+  const sessionDir = resolveExistingSessionDir(project, taskId);
+  const metaPath = path.join(sessionDir, 'metadata.json');
+  if (!fs.existsSync(metaPath)) {
+    throw new Error(`Session ${taskId} not found`);
+  }
+  let metadata;
+  try {
+    metadata = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+  } catch (err) {
+    throw new Error(`Session ${taskId}: metadata is corrupt (${err.message})`);
+  }
+  const summaryPath = path.join(sessionDir, 'summary.md');
+  const summary = fs.existsSync(summaryPath) ? fs.readFileSync(summaryPath, 'utf-8') : null;
+  return buildRunResult({ taskId, metadata, summary, sessionDir });
+}
+
+/**
+ * Rebuild a wave document. Prefers the stored wave.json (written atomically at
+ * fanout exit); falls back to a live rebuild from leg sessions (e.g. after a
+ * hard kill of the fanout process).
+ * @param {string} project
+ * @param {string} waveId
+ * @returns {object} wave document
+ * @throws {Error} if the wave session does not exist
+ * @throws {Error} if metadata.json is missing or corrupt
+ */
+function buildWaveResultFromSession(project, waveId) {
+  const fs = require('fs');
+  const path = require('path');
+  const { resolveExistingSessionDir } = require('../session-manager');
+  const waveDir = resolveExistingSessionDir(project, waveId);
+  const wavePath = path.join(waveDir, 'wave.json');
+  if (fs.existsSync(wavePath)) {
+    try {
+      return JSON.parse(fs.readFileSync(wavePath, 'utf-8'));
+    } catch {
+      // Corrupt wave.json (e.g. hard-kill mid-write) — fall through to live rebuild
+    }
+  }
+  const metaPath = path.join(waveDir, 'metadata.json');
+  if (!fs.existsSync(metaPath)) {
+    throw new Error(`Wave ${waveId} not found`);
+  }
+  let meta;
+  try {
+    meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+  } catch (err) {
+    throw new Error(`Wave ${waveId}: metadata is corrupt (${err.message})`);
+  }
+  const legs = (meta.legs || []).map((legId) => {
+    try { return buildRunResultFromSession(project, legId); }
+    catch (err) {
+      const { logger } = require('./logger');
+      logger.warn('Failed to rebuild leg session; using unknown stub', { legId, error: err.message });
+      return buildRunResult({ taskId: legId, metadata: { status: 'unknown', parentWave: waveId } });
+    }
+  });
+  return buildWaveResult({
+    waveId,
+    legs,
+    promptMeta: meta.promptMeta || null,
+    createdAt: meta.createdAt || null,
+    completedAt: meta.completedAt || null,
+  });
+}
+
+/**
+ * Build a model-catalog document (`models [--search] [--refresh] --json`).
+ * @param {{models: Array, fetchedAt: number|null, refreshed?: boolean, search?: string|null}} opts
+ */
+function buildCatalogDoc({ models, fetchedAt, refreshed = false, search = null }) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    type: 'model-catalog',
+    fetchedAt: fetchedAt || null,
+    refreshed,
+    search,
+    count: models.length,
+    models,
+  };
+}
+
+/**
+ * Build an alias-audit document (`models --check --json`).
+ * @param {{stale: Array<{alias,model,source,suggestions}>, catalogAvailable: boolean}} opts
+ */
+function buildAuditDoc({ stale, catalogAvailable }) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    type: 'alias-audit',
+    catalogAvailable,
+    staleCount: stale.length,
+    stale,
+  };
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  TERMINAL_STATUSES,
+  statusFromResult,
+  buildRunResult,
+  buildWaveResult,
+  waveStatusFromLegs,
+  waveExitCode,
+  buildRunResultFromSession,
+  buildWaveResultFromSession,
+  buildCatalogDoc,
+  buildAuditDoc,
+};

package/src/utils/server-setup.js

@@ -0,0 +1,93 @@
+/**
+ * Server Setup Utilities
+ *
+ * Handles port management and cleanup for the OpenCode server.
+ */
+
+const { execFileSync } = require('child_process');
+const { logger } = require('./logger');
+
+const DEFAULT_PORT = 4096;
+
+/**
+ * Check if a port is in use and get PID
+ * @param {number} port - Port to check
+ * @returns {number|null} PID or null if not in use
+ */
+function getPortPid(port) {
+  try {
+    // Use execFileSync with arguments array (safe from injection)
+    const result = execFileSync('lsof', ['-ti', `:${port}`], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    const pid = parseInt(result.trim(), 10);
+    return isNaN(pid) ? null : pid;
+  } catch {
+    // lsof returns non-zero if no process found
+    return null;
+  }
+}
+
+/**
+ * Check if a port is in use
+ * @param {number} port - Port to check
+ * @returns {boolean} True if port is in use
+ */
+function isPortInUse(port) {
+  return getPortPid(port) !== null;
+}
+
+/**
+ * Kill process using a port
+ * @param {number} port - Port to free
+ * @returns {boolean} True if process was killed or port was already free
+ */
+function killPortProcess(port) {
+  const pid = getPortPid(port);
+  if (!pid) {
+    return true; // Port already free
+  }
+
+  try {
+    process.kill(pid, 'SIGTERM');
+    logger.debug('Killed stale process', { port, pid });
+    return true;
+  } catch (error) {
+    logger.warn('Failed to kill process', { port, pid, error: error.message });
+    return false;
+  }
+}
+
+/**
+ * Ensure the OpenCode server port is available
+ * Kills any stale process using the port
+ * @param {number} [port=4440] - Port to ensure is available
+ * @returns {boolean} True if port is now available
+ */
+function ensurePortAvailable(port = DEFAULT_PORT) {
+  if (!isPortInUse(port)) {
+    return true;
+  }
+
+  logger.info('Port in use, cleaning up stale process', { port });
+
+  if (killPortProcess(port)) {
+    // Give the OS a moment to release the port
+    const start = Date.now();
+    while (isPortInUse(port) && Date.now() - start < 2000) {
+      // Busy wait for up to 2 seconds
+    }
+    return !isPortInUse(port);
+  }
+
+  return false;
+}
+
+module.exports = {
+  DEFAULT_PORT,
+  isPortInUse,
+  getPortPid,
+  killPortProcess,
+  ensurePortAvailable
+};

package/src/utils/session-abort.js

@@ -0,0 +1,53 @@
+/**
+ * Session abort on process signals (F3 #20).
+ *
+ * When the parent process is killed (SIGTERM/SIGINT/SIGBREAK), the running
+ * headless session must be aborted so no orphaned OpenCode session keeps
+ * burning API credits. `markAborted` is the synchronous metadata write that
+ * guarantees `amicus list` won't show an orphan afterward.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Synchronously mark a session's metadata as aborted. Best-effort: never throws.
+ * @param {string} sessionDir
+ * @param {string} reason - e.g. a signal name
+ * @returns {boolean} true if the session was marked aborted
+ */
+function markAborted(sessionDir, reason) {
+  try {
+    const metaPath = path.join(sessionDir, 'metadata.json');
+    if (!fs.existsSync(metaPath)) { return false; }
+    const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+    meta.status = 'aborted';
+    meta.reason = `Aborted (${reason})`;
+    meta.abortedAt = new Date().toISOString();
+    fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Register signal handlers that call onAbort(signal). Returns an uninstall fn.
+ * @param {{onAbort: (signal: string) => void, signals?: string[]}} opts
+ * @returns {() => void} uninstall
+ */
+function installSignalAbort({ onAbort, signals = ['SIGINT', 'SIGTERM', 'SIGBREAK'] }) {
+  const registered = [];
+  for (const sig of signals) {
+    try {
+      const sigHandler = () => { try { onAbort(sig); } catch { /* best-effort */ } };
+      process.on(sig, sigHandler);
+      registered.push({ sig, sigHandler });
+    } catch { /* unsupported signal */ }
+  }
+  return function uninstall() {
+    for (const { sig, sigHandler } of registered) { process.removeListener(sig, sigHandler); }
+  };
+}
+
+module.exports = { markAborted, installSignalAbort };

package/src/utils/session-lock.js

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * @module session-lock
+ * Atomic session lock files to prevent concurrent resume/continue.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const LOCK_FILENAME = 'session.lock';
+
+const MODE_TIMEOUTS = {
+  headless: 15 * 60 * 1000,
+  interactive: 60 * 60 * 1000,
+  mcp: 15 * 60 * 1000,
+};
+
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isLockStale(lockData) {
+  if (!isPidAlive(lockData.pid)) {
+    return true;
+  }
+  const modeTimeout = MODE_TIMEOUTS[lockData.mode] || MODE_TIMEOUTS.headless;
+  const ageMs = Date.now() - new Date(lockData.timestamp).getTime();
+  if (ageMs > modeTimeout * 2) {
+    return true;
+  }
+  return false;
+}
+
+function acquireLock(sessionDir, mode) {
+  const lockPath = path.join(sessionDir, LOCK_FILENAME);
+  const lockData = {
+    pid: process.pid,
+    timestamp: new Date().toISOString(),
+    hostname: os.hostname(),
+    mode,
+  };
+
+  // First attempt: atomic create
+  try {
+    fs.writeFileSync(lockPath, JSON.stringify(lockData, null, 2), { flag: 'wx', mode: 0o600 });
+    return;
+  } catch (err) {
+    if (err.code !== 'EEXIST') { throw err; }
+  }
+
+  // Lock file exists - check if stale
+  let existingLock;
+  try {
+    existingLock = JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+  } catch {
+    try { fs.unlinkSync(lockPath); } catch { /* already gone */ }
+    fs.writeFileSync(lockPath, JSON.stringify(lockData, null, 2), { flag: 'wx', mode: 0o600 });
+    return;
+  }
+
+  if (isLockStale(existingLock)) {
+    try { fs.unlinkSync(lockPath); } catch { /* race */ }
+    try {
+      fs.writeFileSync(lockPath, JSON.stringify(lockData, null, 2), { flag: 'wx', mode: 0o600 });
+      return;
+    } catch (retryErr) {
+      if (retryErr.code === 'EEXIST') {
+        throw new Error('Session already active (concurrent lock acquisition)');
+      }
+      throw retryErr;
+    }
+  }
+
+  throw new Error(
+    `Session already active (PID ${existingLock.pid}, started ${existingLock.timestamp})`
+  );
+}
+
+function releaseLock(sessionDir) {
+  const lockPath = path.join(sessionDir, LOCK_FILENAME);
+  try {
+    fs.unlinkSync(lockPath);
+  } catch {
+    // Lock may not exist
+  }
+}
+
+module.exports = { acquireLock, releaseLock, isLockStale, isPidAlive };