@magnusekdahl/parallix 1.0.0

package/lib/core/runtime-matrix.js

@@ -0,0 +1,82 @@
+const fs = require('fs');
+const path = require('path');
+const { eligibleAgentsForStep, workflowLauncherStatus } = require('../agents/agents');
+
+// Agent eligibility and selection are config-driven: parallix/config/agents.json
+// declares which agents are eligible per step, and each agent's launcher is
+// discovered by the RESOLVERS in agents.js (which resolve launchers as bare
+// executable names on PATH). This module no longer ships hardcoded
+// binary paths.
+const CONFIG_PATH = path.join(__dirname, '..', '..', 'config', 'agents.json');
+
+// Thin diagnostic wrapper over agents.js launcher discovery. Kept so the runtime
+// matrix reports exactly the discovery the launcher actually uses (RESOLVERS),
+// instead of a divergent default-path mechanism.
+function launcherStatus(agent, options = {}) {
+  const { workflowLauncherStatusFn = workflowLauncherStatus } = options;
+  return workflowLauncherStatusFn(agent);
+}
+
+function buildAutonomousReviewMatrix(options = {}) {
+  const {
+    step = 'review',
+    eligibleAgentsForStepFn = eligibleAgentsForStep,
+    workflowLauncherStatusFn = workflowLauncherStatus,
+    configPath = CONFIG_PATH,
+    existsSyncFn = fs.existsSync
+  } = options;
+
+  const agents = eligibleAgentsForStepFn(step);
+  const launchers = Object.fromEntries(
+    agents.map(agent => [agent, workflowLauncherStatusFn(agent)])
+  );
+
+  return {
+    step,
+    agents,
+    configPath,
+    configPresent: existsSyncFn(configPath),
+    launchers
+  };
+}
+
+function formatMatrixSummary(matrix) {
+  const lines = [];
+
+  lines.push(`Agent eligibility config: ${matrix.configPresent ? 'present' : 'missing'} (${matrix.configPath})`);
+  lines.push(`Launcher support matrix (step: ${matrix.step}):`);
+  for (const agent of matrix.agents) {
+    const launcher = matrix.launchers[agent];
+    const status = launcher.supported ? 'supported' : 'blocked';
+    const health = launcher.health ? `, ${launcher.health}` : '';
+    const reason = launcher.reason ? `; ${launcher.reason}` : '';
+    lines.push(`  - ${agent}: ${status} (${launcher.detail}${health}${reason})`);
+  }
+  lines.push(
+    'Reviewer is chosen at runtime from the eligible-and-supported pool, ' +
+    'excluding the implementer (config-driven via agents.json; no hardcoded routing).'
+  );
+
+  return lines;
+}
+
+/**
+ * Returns true if any eligible agent other than `implementer` has a supported launcher.
+ * Used by the review loop to decide whether single-family fallback is authorized.
+ */
+function runnableDifferentFamilyExists(implementer, options = {}) {
+  const {
+    step = 'review',
+    eligibleAgentsForStepFn = eligibleAgentsForStep,
+    workflowLauncherStatusFn = workflowLauncherStatus
+  } = options;
+  const agents = eligibleAgentsForStepFn(step);
+  return agents.some(a => a !== implementer && workflowLauncherStatusFn(a).supported);
+}
+
+module.exports = {
+  launcherStatus,
+  buildAutonomousReviewMatrix,
+  formatMatrixSummary,
+  runnableDifferentFamilyExists
+};

package/lib/core/spawn-tee.js

@@ -0,0 +1,173 @@
+'use strict';
+
+const childProcess = require('child_process');
+const path = require('path');
+
+// Bound the in-memory transcript so a noisy or long-running agent cannot
+// turn the harness into an O(total-output) memory hog. Detection only needs
+// a recent window to find limit-hit phrases (limit-hit.js clips ~200 chars
+// around the match), so a tail buffer is sufficient. The cap is generous
+// enough that a real limit-hit message and its surrounding reset-time
+// context land in the buffer even if the agent printed a lot before exiting.
+const DEFAULT_MAX_TAIL_BYTES = 64 * 1024;
+
+class TailBuffer {
+  constructor(maxBytes) {
+    this.maxBytes = maxBytes;
+    this.chunks = [];
+    this.size = 0;
+  }
+
+  push(chunk) {
+    this.chunks.push(chunk);
+    this.size += chunk.length;
+    while (this.size > this.maxBytes && this.chunks.length > 0) {
+      const head = this.chunks[0];
+      const overflow = this.size - this.maxBytes;
+      if (head.length <= overflow) {
+        this.chunks.shift();
+        this.size -= head.length;
+      } else {
+        this.chunks[0] = head.subarray(overflow);
+        this.size -= overflow;
+      }
+    }
+  }
+
+  toString() {
+    if (this.chunks.length === 0) return '';
+    return Buffer.concat(this.chunks).toString('utf8');
+  }
+}
+
+/**
+ * Spawn a child process and tee its stdout/stderr to the parent's streams
+ * while keeping a bounded tail of the output in memory. Returns a Promise
+ * resolving with a result shaped like `spawnSync` (status, signal, stdout,
+ * stderr, error) but with stdout/stderr as utf-8 strings populated even
+ * when stdio:'inherit' is requested. Forces stdio to ['inherit', 'pipe',
+ * 'pipe'] internally so the parent's stdin is preserved while child output
+ * remains capturable.
+ *
+ * Pure I/O wrapper: no policy, no retry, no agent knowledge.
+ */
+function spawnAndTee(command, args, options = {}) {
+  const {
+    stdoutSink = process.stdout,
+    stderrSink = process.stderr,
+    maxTailBytes = DEFAULT_MAX_TAIL_BYTES,
+    noOutputWatchdog = null,
+    ...spawnOptions
+  } = options;
+
+  return new Promise((resolve) => {
+    const stdoutTail = new TailBuffer(maxTailBytes);
+    const stderrTail = new TailBuffer(maxTailBytes);
+    let settled = false;
+    let sawOutput = false;
+    let watchdogTimer = null;
+    const startTime = Date.now();
+    const resolvedCwd = path.resolve(spawnOptions.cwd || process.cwd());
+    const env = {
+      ...process.env,
+      ...(spawnOptions.env || {}),
+      PWD: resolvedCwd
+    };
+
+    let child;
+    try {
+      child = childProcess.spawn(command, args, {
+        ...spawnOptions,
+        env,
+        stdio: ['inherit', 'pipe', 'pipe']
+      });
+    } catch (err) {
+      resolve({
+        status: null, signal: null, stdout: '', stderr: '', error: err,
+        startedAt: new Date(startTime).toISOString(), endedAt: new Date().toISOString()
+      });
+      return;
+    }
+
+    const clearWatchdog = () => {
+      if (watchdogTimer) {
+        clearTimeout(watchdogTimer);
+        watchdogTimer = null;
+      }
+    };
+
+    const finish = (payload) => {
+      if (settled) return;
+      settled = true;
+      clearWatchdog();
+      payload.startedAt = new Date(startTime).toISOString();
+      payload.endedAt = new Date().toISOString();
+      resolve(payload);
+    };
+
+    const scheduleWatchdog = (delayMs) => {
+      if (!noOutputWatchdog || typeof noOutputWatchdog.onNoOutput !== 'function') return;
+      const delay = Number.isFinite(delayMs) && delayMs >= 0 ? delayMs : 0;
+      watchdogTimer = setTimeout(() => {
+        watchdogTimer = null;
+        if (settled || sawOutput) return;
+        noOutputWatchdog.onNoOutput({
+          command,
+          args,
+          pid: child.pid,
+          elapsedMs: Date.now() - startTime
+        });
+        scheduleWatchdog(noOutputWatchdog.intervalMs);
+      }, delay);
+      if (typeof watchdogTimer.unref === 'function') {
+        watchdogTimer.unref();
+      }
+    };
+
+    const noteOutput = () => {
+      sawOutput = true;
+      clearWatchdog();
+    };
+
+    if (noOutputWatchdog) {
+      scheduleWatchdog(noOutputWatchdog.initialDelayMs);
+    }
+
+    child.stdout.on('data', (chunk) => {
+      noteOutput();
+      stdoutTail.push(chunk);
+      if (stdoutSink && typeof stdoutSink.write === 'function') {
+        stdoutSink.write(chunk);
+      }
+    });
+    child.stderr.on('data', (chunk) => {
+      noteOutput();
+      stderrTail.push(chunk);
+      if (stderrSink && typeof stderrSink.write === 'function') {
+        stderrSink.write(chunk);
+      }
+    });
+
+    child.on('error', (err) => {
+      finish({
+        status: null,
+        signal: null,
+        stdout: stdoutTail.toString(),
+        stderr: stderrTail.toString(),
+        error: err
+      });
+    });
+
+    child.on('close', (code, signal) => {
+      finish({
+        status: code,
+        signal,
+        stdout: stdoutTail.toString(),
+        stderr: stderrTail.toString(),
+        error: null
+      });
+    });
+  });
+}
+
+module.exports = { spawnAndTee, DEFAULT_MAX_TAIL_BYTES };

package/lib/core/state-map.js

@@ -0,0 +1,89 @@
+const fs = require('fs');
+const path = require('path');
+const { loadEffectiveConfig } = require('./product-config');
+
+const SHIPPED_STATE_MAP_PATH = path.join(__dirname, '..', '..', 'config', 'state-map.json');
+
+function resolveRepoRelativePath(rootDir, repoRelativePath) {
+  if (!repoRelativePath || typeof repoRelativePath !== 'string') return null;
+  return path.isAbsolute(repoRelativePath)
+    ? repoRelativePath
+    : path.join(rootDir, repoRelativePath);
+}
+
+function resolveStateMapPath(options = {}) {
+  if (typeof options === 'string') return options;
+
+  const rootDir = options.rootDir || process.cwd();
+  const config = options.config || loadEffectiveConfig(rootDir);
+  const configuredPath = config.adapters?.tasks?.stateMap;
+  const repoPath = resolveRepoRelativePath(rootDir, configuredPath);
+
+  if (repoPath && fs.existsSync(repoPath)) {
+    return repoPath;
+  }
+  return options.fallbackPath || SHIPPED_STATE_MAP_PATH;
+}
+
+function loadStateMap(options = {}) {
+  const stateMapPath = resolveStateMapPath(options);
+  try {
+    return JSON.parse(fs.readFileSync(stateMapPath, 'utf8'));
+  } catch (_) {
+    return {};
+  }
+}
+
+function normalizeState(value) {
+  if (typeof value !== 'string') return value;
+  return value.trim().toLowerCase();
+}
+
+// Virtual workflow state → actual backlog.md state name.
+// Returns null if the virtual state explicitly maps to null (no backlog.md write).
+// Returns the virtual name unchanged if it has no entry in the map (identity).
+function resolveMap(mapOrOptions) {
+  if (mapOrOptions && typeof mapOrOptions === 'object' && !Array.isArray(mapOrOptions)) {
+    if (Object.prototype.hasOwnProperty.call(mapOrOptions, 'rootDir')
+      || Object.prototype.hasOwnProperty.call(mapOrOptions, 'config')
+      || Object.prototype.hasOwnProperty.call(mapOrOptions, 'fallbackPath')) {
+      return loadStateMap(mapOrOptions);
+    }
+  }
+  return mapOrOptions || loadStateMap();
+}
+
+function toActual(virtualState, map = loadStateMap()) {
+  map = resolveMap(map);
+  if (Object.prototype.hasOwnProperty.call(map, virtualState)) {
+    return map[virtualState];
+  }
+  return virtualState;
+}
+
+// Actual backlog.md state name → virtual workflow state name.
+// Returns the actual name unchanged if no reverse mapping exists (identity).
+function toVirtual(actualState, map = loadStateMap()) {
+  map = resolveMap(map);
+  const normalizedActual = normalizeState(actualState);
+  for (const [virtual, actual] of Object.entries(map)) {
+    if (normalizeState(actual) === normalizedActual) return virtual;
+  }
+  return actualState;
+}
+
+// Wraps a transitionTask call: resolves virtual → actual, then delegates.
+// If the virtual state maps to null, logs an info line and returns true (no-op).
+function transitionVirtual(transitionTaskFn, slug, virtualState, options = {}, map = loadStateMap(options)) {
+  map = resolveMap(map);
+  const actual = toActual(virtualState, map);
+  if (actual === null) {
+    const fmt = require('./fmt');
+    const log = options.log || fmt.log.plain;
+    log(fmt.status('INFO', `Virtual state '${virtualState}' has no backlog.md mapping for this board; skipping status write.`));
+    return true;
+  }
+  return transitionTaskFn(slug, actual, options);
+}
+
+module.exports = { SHIPPED_STATE_MAP_PATH, loadStateMap, normalizeState, resolveStateMapPath, toActual, toVirtual, transitionVirtual };

package/lib/core/storage.js

@@ -0,0 +1,165 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+/**
+ * Resolve the parallix-owned persistent-data root.
+ *
+ * Precedence:
+ *   1. PARALLIX_HOME env var (highest priority)
+ *   2. Platform-specific base:
+ *      - Linux:      $HOME/.local/state/parallix
+ *      - macOS:      ~/Library/Application Support/parallix
+ *      - Windows:    %LOCALAPPDATA%/parallix
+ *      - Fallback:   $HOME/.parallix
+ *
+ * This function guarantees the directory exists (creates it + parents on first
+ * call with `ensureDir: true`). Read-side callers may omit ensureDir so they
+ * fail gracefully when PARALLIX_HOME has never been initialized.
+ */
+function resolveParallixHome(options = {}) {
+  if (typeof options === 'boolean' || typeof options === 'string') {
+    // Legacy shim: resolveParallixHome(true) === { ensureDir: true }
+    options = { ensureDir: options };
+  }
+
+  const {
+    ensureDir = false,
+    platform = process.platform,
+    env = process.env,
+    homedir = os.homedir
+  } = options;
+
+  let home;
+
+  // --- env override (highest precedence) ---
+  if (env.PARALLIX_HOME && typeof env.PARALLIX_HOME === 'string' && env.PARALLIX_HOME.trim().length > 0) {
+    home = path.resolve(env.PARALLIX_HOME);
+  } else if (platform === 'linux') {
+    home = path.join(homedir(), '.local', 'state', 'parallix');
+  } else if (platform === 'darwin') {
+    home = path.join(homedir(), 'Library', 'Application Support', 'parallix');
+  } else if (platform === 'win32') {
+    const localAppData = env.LOCALAPPDATA;
+    if (localAppData && typeof localAppData === 'string' && localAppData.trim().length > 0) {
+      home = path.join(localAppData.trim(), 'parallix');
+    } else {
+      home = path.join(homedir(), '.parallix');
+    }
+  } else {
+    // WSL, CI, other UNIX variants
+    home = path.join(homedir(), '.parallix');
+  }
+
+  home = path.resolve(home);
+
+  if (ensureDir) {
+    fs.mkdirSync(home, { recursive: true });
+  }
+
+  return home;
+}
+
+/**
+ * Resolve the effective stats CSV path.
+ *
+ * Returns `<PARALLIX_HOME>/stats.csv` (creating PARALLIX_HOME if `ensureDir`
+ * is true). Callers that pass an explicit `--csv-file` path bypass this
+ * resolver entirely — the caller supplies the path before calling here.
+ */
+function resolveStatsPath(options = {}) {
+  const home = resolveParallixHome({ ensureDir: options.ensureDir !== false, warn: options.warn });
+  return path.join(home, 'stats.csv');
+}
+
+/**
+ * Resolve the effective agent blocklist path.
+ *
+ * Returns `<PARALLIX_HOME>/agents.local.json`.  Callers that pass an
+ * explicit `targetPath` bypass this resolver.
+ */
+function resolveAgentsLocalPath(options = {}) {
+  if (typeof options === 'string') {
+    return path.resolve(options);
+  }
+  const home = resolveParallixHome({ ensureDir: options.ensureDir !== false });
+  return path.join(home, 'agents.local.json');
+}
+
+/**
+ * Read a JSON file that lives under PARALLIX_HOME.
+ *
+ * Returns `{ ok: false, error }` when the file does not exist or is not
+ * valid JSON — callers should treat absence as "no local overrides".
+ * Malformed JSON returns `{ ok: false, error }` rather than throwing so
+ * callers can decide whether this is a hard failure.
+ */
+function readJson(pathOrResolution) {
+  let filePath;
+  if (typeof pathOrResolution === 'function') {
+    filePath = pathOrResolution();
+  } else {
+    filePath = pathOrResolution;
+  }
+
+  if (!filePath || !fs.existsSync(filePath)) {
+    return { ok: false, error: null, data: null };
+  }
+
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const data = JSON.parse(raw);
+    return { ok: true, error: null, data };
+  } catch (err) {
+    return { ok: false, error: err, data: null };
+  }
+}
+
+/**
+ * Write JSON to a path under PARALLIX_HOME (or an explicit path).
+ * Creates parent directories as needed.
+ */
+function writeJson(filePath, data) {
+  if (typeof filePath === 'function') {
+    filePath = filePath();
+  }
+  writeFileAtomic(filePath, `${JSON.stringify(data, null, 2)}\n`);
+  return filePath;
+}
+
+function writeFileAtomic(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`
+  );
+  try {
+    fs.writeFileSync(tempPath, content, 'utf8');
+    fs.renameSync(tempPath, filePath);
+  } finally {
+    if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath);
+  }
+}
+
+/**
+ * Check whether PARALLIX_HOME has been initialized (directory exists).
+ * Does NOT create the directory.
+ */
+function isInitialized() {
+  const home = resolveParallixHome({ ensureDir: false });
+  try {
+    return fs.statSync(home).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  resolveParallixHome,
+  resolveStatsPath,
+  resolveAgentsLocalPath,
+  readJson,
+  writeJson,
+  writeFileAtomic,
+  isInitialized,
+};

package/lib/core/verification.js

@@ -0,0 +1,149 @@
+const { run } = require('./git');
+const { loadAdapterConfig } = require('./product-config');
+const fs = require('fs');
+
+// parallix targets arbitrary repositories, so there is no universal gate
+// command. When adapters.verification.command is not configured, verification
+// is a no-op pass ("no validation"). A repository opts into a real gate by
+// declaring the command in workflow.config.json.
+const DEFAULT_AREA = 'docs';
+// Shell-safe no-op so this is harmless if pasted into a command sequence: `:` is
+// the bash null command and `#` comments the explanation.
+const NO_GATE_NOTICE = ': # no verification gate configured (set adapters.verification.command)';
+
+function resolveVerificationAdapter(rootDir = process.cwd()) {
+  const verification = loadAdapterConfig(rootDir).verification || {};
+  const command = typeof verification.command === 'string' && verification.command.trim()
+    ? verification.command.trim()
+    : null;
+  const defaultArea = typeof verification.defaultArea === 'string' && verification.defaultArea.trim()
+    ? verification.defaultArea.trim()
+    : DEFAULT_AREA;
+
+  return { command, defaultArea };
+}
+
+function formatVerificationCommand(area, rootDir = process.cwd()) {
+  const { command, defaultArea } = resolveVerificationAdapter(rootDir);
+  const effectiveArea = area || defaultArea;
+  if (!command) {
+    return NO_GATE_NOTICE;
+  }
+  return command.replaceAll('{{area}}', effectiveArea);
+}
+
+function runVerificationGate(area, options = {}) {
+  const rootDir = options.rootDir || process.cwd();
+  const { command, defaultArea } = resolveVerificationAdapter(rootDir);
+  const effectiveArea = area || defaultArea;
+
+  if (!command) {
+    const info = options.log || require('./fmt').log.info;
+    info(`No verification gate configured for area: ${effectiveArea}; default is no validation. `
+      + 'Set adapters.verification.command in workflow.config.json to enforce one.');
+    return { status: 0 };
+  }
+
+  const stdio = options.stdio || 'inherit';
+  const runFn = options.runFn || run;
+  return runFn('bash', ['-lc', command.replaceAll('{{area}}', effectiveArea)], { cwd: rootDir, stdio });
+}
+
+function readPublishedTreeState(rootDir = process.cwd(), { gitRunner = run } = {}) {
+  const resolvedRoot = fs.realpathSync(rootDir);
+  const commitResult = gitRunner(['-C', resolvedRoot, 'rev-parse', 'HEAD']);
+  const treeResult = gitRunner(['-C', resolvedRoot, 'rev-parse', 'HEAD^{tree}']);
+
+  const commit = commitResult.stdout ? commitResult.stdout.trim() : '';
+  const tree = treeResult.stdout ? treeResult.stdout.trim() : '';
+  if (commitResult.status !== 0 || treeResult.status !== 0 || !commit || !tree) {
+    return {
+      ok: false,
+      error: `could not resolve current published tree for ${resolvedRoot}`
+    };
+  }
+
+  return { ok: true, rootDir: resolvedRoot, commit, tree };
+}
+
+function captureVerifiedTreeProof(area, rootDir = process.cwd(), options = {}) {
+  const {
+    gitRunner = run,
+    runFn = run,
+    stdio = 'inherit'
+  } = options;
+
+  const before = readPublishedTreeState(rootDir, { gitRunner });
+  if (!before.ok) return before;
+
+  const verification = runVerificationGate(area, {
+    rootDir: before.rootDir,
+    runFn,
+    stdio
+  });
+  if (verification.status !== 0) {
+    return {
+      ok: false,
+      error: `verification gate failed for ${before.rootDir} with exit code ${verification.status}`
+    };
+  }
+
+  const after = readPublishedTreeState(before.rootDir, { gitRunner });
+  if (!after.ok) return after;
+  if (after.commit !== before.commit || after.tree !== before.tree) {
+    return {
+      ok: false,
+      error: `verification proof became stale while publishing ${before.rootDir}`
+    };
+  }
+
+  const { command, defaultArea } = resolveVerificationAdapter(before.rootDir);
+  const effectiveArea = area || defaultArea;
+
+  return {
+    ok: true,
+    proof: {
+      rootDir: before.rootDir,
+      area: effectiveArea,
+      command: command || null,
+      commit: after.commit,
+      tree: after.tree,
+      verifiedAt: new Date().toISOString()
+    }
+  };
+}
+
+function assertVerifiedTreeProof(proof, rootDir = process.cwd(), { gitRunner = run } = {}) {
+  if (!proof || typeof proof !== 'object') {
+    return { ok: false, error: 'missing verification proof' };
+  }
+
+  const current = readPublishedTreeState(rootDir, { gitRunner });
+  if (!current.ok) return current;
+
+  if (proof.rootDir !== current.rootDir) {
+    return { ok: false, error: `verification proof was captured from a different checkout: ${proof.rootDir}` };
+  }
+  if (proof.commit !== current.commit || proof.tree !== current.tree) {
+    return { ok: false, error: 'verification proof does not match the tree being published' };
+  }
+
+  return { ok: true, proof: current };
+}
+
+function runWorkflow(args, options = {}) {
+  const log = options.log || require('./fmt').log.plain;
+  const area = args[0] || process.env.VERIFY_AREA || DEFAULT_AREA;
+  log(`Running verification gate for area: ${area}...`);
+  return runVerificationGate(area, { stdio: 'inherit' });
+}
+
+module.exports = runWorkflow;
+module.exports.DEFAULT_AREA = DEFAULT_AREA;
+module.exports.NO_GATE_NOTICE = NO_GATE_NOTICE;
+module.exports.formatVerificationCommand = formatVerificationCommand;
+module.exports.resolveVerificationAdapter = resolveVerificationAdapter;
+module.exports.runVerificationGate = runVerificationGate;
+module.exports.readPublishedTreeState = readPublishedTreeState;
+module.exports.captureVerifiedTreeProof = captureVerifiedTreeProof;
+module.exports.assertVerifiedTreeProof = assertVerifiedTreeProof;