@magnusekdahl/parallix 1.2.0 → 1.3.0

package/lib/core/verification.ts

@@ -0,0 +1,200 @@
+import { git, run } from './git.js';
+import type { SpawnSyncOptions } from 'node:child_process';
+import { loadAdapterConfig } from './product-config.js';
+import { log } from './fmt.js';
+import * as fsMod from 'node:fs';
+
+interface GitOptions {
+  encoding?: BufferEncoding;
+  stdio?: SpawnSyncOptions['stdio'];
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  maxBuffer?: number;
+  [key: string]: unknown;
+}
+
+interface GitResult {
+  status: number | null;
+  signal: string | null;
+  stdout: string;
+  stderr: string;
+  error?: Error | null;
+}
+
+export type GitFn = (args: string[], options?: GitOptions) => GitResult;
+
+export interface VerificationAdapterConfig {
+  command: string | null;
+  defaultArea: string;
+}
+
+export interface VerificationProof {
+  rootDir: string;
+  area: string;
+  command: string | null;
+  commit: string;
+  tree: string;
+  verifiedAt: string;
+}
+
+export interface PublishedTreeStateOk {
+  ok: true;
+  rootDir: string;
+  commit: string;
+  tree: string;
+}
+
+export interface PublishedTreeStateFail {
+  ok: false;
+  error: string;
+}
+
+export type PublishedTreeState = PublishedTreeStateOk | PublishedTreeStateFail;
+
+// 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.
+export 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.
+export const NO_GATE_NOTICE = ': # no verification gate configured (set adapters.verification.command)';
+
+export function resolveVerificationAdapter(rootDir: string = process.cwd()): VerificationAdapterConfig {
+  const config = loadAdapterConfig(rootDir);
+  const verification = (config.verification as { command?: unknown; defaultArea?: unknown }) || {};
+  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 };
+}
+
+/** @param {string} [area] @param {string} [rootDir] */
+export function formatVerificationCommand(area: string | undefined, rootDir: string = process.cwd()): string {
+  const { command, defaultArea } = resolveVerificationAdapter(rootDir);
+  const effectiveArea = area || defaultArea;
+  if (!command) {
+    return NO_GATE_NOTICE;
+  }
+  return command.replaceAll('{{area}}', effectiveArea || DEFAULT_AREA);
+}
+
+/** @param {string} [area] @param {{rootDir?: string, log?: Function, stdio?: string, runFn?: Function}} [options] */
+export function runVerificationGate(area: string | undefined, options: { rootDir?: string; log?: Function; stdio?: string; runFn?: Function } = {}): import('child_process').SpawnSyncReturns<string> {
+  const opts = options;
+  const rootDir = opts.rootDir || process.cwd();
+  const { command, defaultArea } = resolveVerificationAdapter(rootDir);
+  const effectiveArea = area || defaultArea;
+
+  if (!command) {
+    const info = opts.log || 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 } as import('child_process').SpawnSyncReturns<string>;
+  }
+
+  const stdio = opts.stdio || 'inherit';
+  const runFn = opts.runFn || run;
+  return runFn('bash', ['-lc', command.replaceAll('{{area}}', effectiveArea)], { cwd: rootDir, stdio });
+}
+
+/** @param {string} rootDir @param {{gitRunner?: GitFn}} [options] */
+export function readPublishedTreeState(rootDir: string, options: { gitRunner?: GitFn } = {}): PublishedTreeState {
+  const gitRunner = options.gitRunner || git;
+  const resolvedRoot = fsMod.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 };
+}
+
+/** @param {string} [area] @param {string} [rootDir] @param {{gitRunner?: GitFn, runFn?: Function, stdio?: string}} [options] */
+export function captureVerifiedTreeProof(area: string | undefined, rootDir: string = process.cwd(), options: { gitRunner?: GitFn; runFn?: Function; stdio?: string } = {}): { ok: boolean; proof?: VerificationProof; error?: string } {
+  const {
+    gitRunner = git,
+    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()
+    }
+  };
+}
+
+/** @param {{rootDir?: string, commit?: string, tree?: string}} proof @param {string} [rootDir] @param {{gitRunner?: GitFn}} [opts] */
+export function assertVerifiedTreeProof(proof: { rootDir?: string; commit?: string; tree?: string }, rootDir: string = process.cwd(), opts: { gitRunner?: GitFn } = {}): { ok: boolean; proof?: PublishedTreeState; error?: string } {
+  if (!proof || typeof proof !== 'object') {
+    return { ok: false, error: 'missing verification proof' };
+  }
+
+  const o = opts;
+  const gitRunner = o.gitRunner || git;
+  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 };
+}
+
+/** @param {string[]} args @param {{log?: Function}} [options] */
+export default function runWorkflow(args: string[], options: { log?: Function } = {}): import('child_process').SpawnSyncReturns<string> {
+  const opts = options;
+  const logFn = opts.log || log.plain;
+  const area = args[0] || process.env.VERIFY_AREA || DEFAULT_AREA;
+  logFn(`Running verification gate for area: ${area}...`);
+  return runVerificationGate(area, { stdio: 'inherit' });
+}

package/lib/index.js

@@ -1,3 +1,4 @@
+"use strict";
 /**
  * Barrel re-export for parallix/lib/.
  *
@@ -14,64 +15,146 @@
  *   review/   — Review subsystem (artifacts, commands, loop, polling, prompts, state)
  *   tools/    — External integrations and supporting workflow libraries
  */
-
-'use strict';
-
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessions = exports.setupReview = exports.gatekeeper = exports.forgejo = exports.backlog = exports.reviewState = exports.reviewPrompts = exports.reviewPolling = exports.reviewLoop = exports.reviewEvents = exports.reviewCommands = exports.reviewArtifacts = exports.review = exports.verification = exports.storage = exports.stateMap = exports.spawnTee = exports.runtimeMatrix = exports.productConfig = exports.persistentDataMigration = exports.missionUtils = exports.gitignore = exports.git = exports.fmt = exports.verify = exports.status = exports.statsBackfill = exports.stats = exports.setup = exports.resolveConflict = exports.repairHandoff = exports.rebase = exports.missionStart = exports.integrate = exports.handoff = exports.draft = exports.diff = exports.coverageGate = exports.config = exports.checkpoint = exports.active = exports.opencode = exports.mistral = exports.limitHit = exports.codexTelemetry = exports.codex = exports.claudeTelemetry = exports.claude = exports.agents = void 0;
+// agents/ — all use named exports
+const agentsMod = __importStar(require("./agents/agents.js"));
+const claudeMod = __importStar(require("./agents/claude.js"));
+const claudeTelemetryMod = __importStar(require("./agents/claude-telemetry.js"));
+const codexMod = __importStar(require("./agents/codex.js"));
+const codexTelemetryMod = __importStar(require("./agents/codex-telemetry.js"));
+const limitHitMod = __importStar(require("./agents/limit-hit.js"));
+const mistralMod = __importStar(require("./agents/mistral.js"));
+const opencodeMod = __importStar(require("./agents/opencode.js"));
+// commands/ — mixed export styles
+const active = require("./commands/active.js");
+exports.active = active;
+const checkpoint_js_1 = __importDefault(require("./commands/checkpoint.js"));
+exports.checkpoint = checkpoint_js_1.default;
+const config = require("./commands/config.js");
+exports.config = config;
+const coverageGate = require("./commands/coverage-gate.js");
+exports.coverageGate = coverageGate;
+const diff = require("./commands/diff.js");
+exports.diff = diff;
+const draft = require("./commands/draft.js");
+exports.draft = draft;
+const handoff = require("./commands/handoff.js");
+exports.handoff = handoff;
+const integrate = require("./commands/integrate.js");
+exports.integrate = integrate;
+const missionStart = require("./commands/mission-start.js");
+exports.missionStart = missionStart;
+const rebase = require("./commands/rebase.js");
+exports.rebase = rebase;
+const repairHandoff = require("./commands/repair-handoff.js");
+exports.repairHandoff = repairHandoff;
+const resolveConflict = require("./commands/resolve-conflict.js");
+exports.resolveConflict = resolveConflict;
+const setup = require("./commands/setup.js");
+exports.setup = setup;
+const stats = require("./commands/stats.js");
+exports.stats = stats;
+const statsBackfill = require("./commands/stats-backfill.js");
+exports.statsBackfill = statsBackfill;
+const status = require("./commands/status.js");
+exports.status = status;
+const verify = require("./commands/verify.js");
+exports.verify = verify;
+// core/ — mixed export styles
+const fmtMod = __importStar(require("./core/fmt.js"));
+exports.fmt = fmtMod;
+const gitMod = __importStar(require("./core/git.js"));
+const gitignore = require("./core/gitignore.js");
+exports.gitignore = gitignore;
+const missionUtilsMod = __importStar(require("./core/mission-utils.js"));
+const persistentDataMigrationMod = __importStar(require("./core/persistent-data-migration.js"));
+const productConfigMod = __importStar(require("./core/product-config.js"));
+const runtimeMatrixMod = __importStar(require("./core/runtime-matrix.js"));
+const spawnTeeMod = __importStar(require("./core/spawn-tee.js"));
+const stateMapMod = __importStar(require("./core/state-map.js"));
+const storageMod = __importStar(require("./core/storage.js"));
+const verificationMod = __importStar(require("./core/verification.js"));
+// review/ — mixed export styles
+const review = require("./review/review.js");
+exports.review = review;
+const reviewArtifactsMod = __importStar(require("./review/review-artifacts.js"));
+const reviewCommandsMod = __importStar(require("./review/review-commands.js"));
+const reviewEventsMod = __importStar(require("./review/review-events.js"));
+const reviewLoopMod = __importStar(require("./review/review-loop.js"));
+const reviewPollingMod = __importStar(require("./review/review-polling.js"));
+const reviewPromptsMod = __importStar(require("./review/review-prompts.js"));
+const reviewStateMod = __importStar(require("./review/review-state.js"));
+// tools/ — all use named exports
+const backlogMod = __importStar(require("./tools/backlog.js"));
+const forgejoMod = __importStar(require("./tools/forgejo.js"));
+const gatekeeperMod = __importStar(require("./tools/gatekeeper.js"));
+const setupReviewMod = __importStar(require("./tools/setup-review.js"));
+const sessionsMod = __importStar(require("./tools/sessions.js"));
 // agents/
-module.exports.agents = require('./agents/agents');
-module.exports.claude = require('./agents/claude');
-module.exports.claudeTelemetry = require('./agents/claude-telemetry');
-module.exports.codex = require('./agents/codex');
-module.exports.codexTelemetry = require('./agents/codex-telemetry');
-module.exports.limitHit = require('./agents/limit-hit');
-module.exports.mistral = require('./agents/mistral');
-module.exports.opencode = require('./agents/opencode');
-
-// commands/
-module.exports.active = require('./commands/active');
-module.exports.checkpoint = require('./commands/checkpoint');
-module.exports.config = require('./commands/config');
-module.exports.coverageGate = require('./commands/coverage-gate');
-module.exports.diff = require('./commands/diff');
-module.exports.draft = require('./commands/draft');
-module.exports.handoff = require('./commands/handoff');
-module.exports.integrate = require('./commands/integrate');
-module.exports.missionStart = require('./commands/mission-start');
-module.exports.rebase = require('./commands/rebase');
-module.exports.repairHandoff = require('./commands/repair-handoff');
-module.exports.resolveConflict = require('./commands/resolve-conflict');
-module.exports.setup = require('./commands/setup');
-module.exports.stats = require('./commands/stats');
-module.exports.statsBackfill = require('./commands/stats-backfill');
-module.exports.status = require('./commands/status');
-module.exports.verify = require('./commands/verify');
-
-// core/
-module.exports.fmt = require('./core/fmt');
-module.exports.git = require('./core/git');
-module.exports.gitignore = require('./core/gitignore');
-module.exports.missionUtils = require('./core/mission-utils');
-module.exports.persistentDataMigration = require('./core/persistent-data-migration');
-module.exports.productConfig = require('./core/product-config');
-module.exports.runtimeMatrix = require('./core/runtime-matrix');
-module.exports.spawnTee = require('./core/spawn-tee');
-module.exports.stateMap = require('./core/state-map');
-module.exports.storage = require('./core/storage');
-module.exports.verification = require('./core/verification');
-
-// review/
-module.exports.review = require('./review/review');
-module.exports.reviewArtifacts = require('./review/review-artifacts');
-module.exports.reviewCommands = require('./review/review-commands');
-module.exports.reviewEvents = require('./review/review-events');
-module.exports.reviewLoop = require('./review/review-loop');
-module.exports.reviewPolling = require('./review/review-polling');
-module.exports.reviewPrompts = require('./review/review-prompts');
-module.exports.reviewState = require('./review/review-state');
-
+exports.agents = agentsMod;
+exports.claude = claudeMod;
+exports.claudeTelemetry = claudeTelemetryMod;
+exports.codex = codexMod;
+exports.codexTelemetry = codexTelemetryMod;
+exports.limitHit = limitHitMod;
+exports.mistral = mistralMod;
+exports.opencode = opencodeMod;
+exports.git = gitMod;
+exports.missionUtils = missionUtilsMod;
+exports.persistentDataMigration = persistentDataMigrationMod;
+exports.productConfig = productConfigMod;
+exports.runtimeMatrix = runtimeMatrixMod;
+exports.spawnTee = spawnTeeMod;
+exports.stateMap = stateMapMod;
+exports.storage = storageMod;
+exports.verification = verificationMod;
+exports.reviewArtifacts = reviewArtifactsMod;
+exports.reviewCommands = reviewCommandsMod;
+exports.reviewEvents = reviewEventsMod;
+exports.reviewLoop = reviewLoopMod;
+exports.reviewPolling = reviewPollingMod;
+exports.reviewPrompts = reviewPromptsMod;
+exports.reviewState = reviewStateMod;
 // tools/
-module.exports.backlog = require('./tools/backlog');
-module.exports.forgejo = require('./tools/forgejo');
-module.exports.gatekeeper = require('./tools/gatekeeper');
-module.exports.setupReview = require('./tools/setup-review');
-module.exports.sessions = require('./tools/sessions');
+exports.backlog = backlogMod;
+exports.forgejo = forgejoMod;
+exports.gatekeeper = gatekeeperMod;
+exports.setupReview = setupReviewMod;
+exports.sessions = sessionsMod;

package/lib/index.ts

@@ -0,0 +1,134 @@
+/**
+ * Barrel re-export for parallix/lib/.
+ *
+ * Re-exports all grouped modules under named properties (e.g.
+ * `require('../lib').commands.setup`). This file does NOT restore
+ * flat subpath imports (e.g. `require('../lib/setup')`) — those
+ * entrypoints were removed during the restructure and any remaining
+ * consumers should be updated to use the new grouped paths.
+ *
+ * Directory layout:
+ *   agents/   — AI agent launchers and session management
+ *   commands/ — Workflow command handlers (dispatcher entry points)
+ *   core/     — Shared infrastructure (no command-handler imports)
+ *   review/   — Review subsystem (artifacts, commands, loop, polling, prompts, state)
+ *   tools/    — External integrations and supporting workflow libraries
+ */
+
+// agents/ — all use named exports
+import * as agentsMod from './agents/agents.js';
+import * as claudeMod from './agents/claude.js';
+import * as claudeTelemetryMod from './agents/claude-telemetry.js';
+import * as codexMod from './agents/codex.js';
+import * as codexTelemetryMod from './agents/codex-telemetry.js';
+import * as limitHitMod from './agents/limit-hit.js';
+import * as mistralMod from './agents/mistral.js';
+import * as opencodeMod from './agents/opencode.js';
+
+// commands/ — mixed export styles
+import active = require('./commands/active.js');
+import checkpoint from './commands/checkpoint.js';
+import config = require('./commands/config.js');
+import coverageGate = require('./commands/coverage-gate.js');
+import diff = require('./commands/diff.js');
+import draft = require('./commands/draft.js');
+import handoff = require('./commands/handoff.js');
+import integrate = require('./commands/integrate.js');
+import missionStart = require('./commands/mission-start.js');
+import rebase = require('./commands/rebase.js');
+import repairHandoff = require('./commands/repair-handoff.js');
+import resolveConflict = require('./commands/resolve-conflict.js');
+import setup = require('./commands/setup.js');
+import stats = require('./commands/stats.js');
+import statsBackfill = require('./commands/stats-backfill.js');
+import status = require('./commands/status.js');
+import verify = require('./commands/verify.js');
+
+// core/ — mixed export styles
+import * as fmtMod from './core/fmt.js';
+import * as gitMod from './core/git.js';
+import gitignore = require('./core/gitignore.js');
+import * as missionUtilsMod from './core/mission-utils.js';
+import * as persistentDataMigrationMod from './core/persistent-data-migration.js';
+import * as productConfigMod from './core/product-config.js';
+import * as runtimeMatrixMod from './core/runtime-matrix.js';
+import * as spawnTeeMod from './core/spawn-tee.js';
+import * as stateMapMod from './core/state-map.js';
+import * as storageMod from './core/storage.js';
+import * as verificationMod from './core/verification.js';
+
+// review/ — mixed export styles
+import review = require('./review/review.js');
+import * as reviewArtifactsMod from './review/review-artifacts.js';
+import * as reviewCommandsMod from './review/review-commands.js';
+import * as reviewEventsMod from './review/review-events.js';
+import * as reviewLoopMod from './review/review-loop.js';
+import * as reviewPollingMod from './review/review-polling.js';
+import * as reviewPromptsMod from './review/review-prompts.js';
+import * as reviewStateMod from './review/review-state.js';
+
+// tools/ — all use named exports
+import * as backlogMod from './tools/backlog.js';
+import * as forgejoMod from './tools/forgejo.js';
+import * as gatekeeperMod from './tools/gatekeeper.js';
+import * as setupReviewMod from './tools/setup-review.js';
+import * as sessionsMod from './tools/sessions.js';
+
+// agents/
+export const agents = agentsMod;
+export const claude = claudeMod;
+export const claudeTelemetry = claudeTelemetryMod;
+export const codex = codexMod;
+export const codexTelemetry = codexTelemetryMod;
+export const limitHit = limitHitMod;
+export const mistral = mistralMod;
+export const opencode = opencodeMod;
+
+// commands/
+export { active };
+export { checkpoint };
+export { config };
+export { coverageGate };
+export { diff };
+export { draft };
+export { handoff };
+export { integrate };
+export { missionStart };
+export { rebase };
+export { repairHandoff };
+export { resolveConflict };
+export { setup };
+export { stats };
+export { statsBackfill };
+export { status };
+export { verify };
+
+// core/
+export { fmtMod as fmt };
+export const git = gitMod;
+export { gitignore };
+export const missionUtils = missionUtilsMod;
+export const persistentDataMigration = persistentDataMigrationMod;
+export const productConfig = productConfigMod;
+export const runtimeMatrix = runtimeMatrixMod;
+export const spawnTee = spawnTeeMod;
+export const stateMap = stateMapMod;
+export const storage = storageMod;
+export const verification = verificationMod;
+
+// review/
+export { review };
+export const reviewArtifacts = reviewArtifactsMod;
+export const reviewCommands = reviewCommandsMod;
+export const reviewEvents = reviewEventsMod;
+export const reviewLoop = reviewLoopMod;
+export const reviewPolling = reviewPollingMod;
+export const reviewPrompts = reviewPromptsMod;
+export const reviewState = reviewStateMod;
+
+// tools/
+export const backlog = backlogMod;
+export const forgejo = forgejoMod;
+export const gatekeeper = gatekeeperMod;
+export const setupReview = setupReviewMod;
+export const sessions = sessionsMod;