@magnusekdahl/parallix 1.2.0 → 1.2.1

package/lib/core/storage.ts

@@ -0,0 +1,182 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export interface ResolveParallixHomeOptions {
+  ensureDir?: boolean;
+  platform?: string;
+  env?: Record<string, string>;
+  homedir?: () => string;
+}
+
+export interface ReadJsonResult<T = unknown> {
+  ok: boolean;
+  error: unknown;
+  data: T | null;
+}
+
+export interface IsInitializedResult {
+  isInitialized: boolean;
+}
+
+/**
+ * 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.
+ */
+export function resolveParallixHome(
+  options: ResolveParallixHomeOptions | boolean | string = {}
+): string {
+  if (typeof options === 'boolean' || typeof options === 'string') {
+    // Legacy shim: resolveParallixHome(true) === { ensureDir: true }
+    options = { ensureDir: Boolean(options) };
+  }
+
+  const opts = options as ResolveParallixHomeOptions;
+  const {
+    ensureDir = false,
+    platform = process.platform,
+    env = process.env,
+    homedir = os.homedir
+  } = opts;
+
+  let home: string;
+
+  // --- 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.
+ */
+export interface ResolveStatsOptions {
+  ensureDir?: boolean;
+  warn?: (...args: unknown[]) => void;
+}
+
+export function resolveStatsPath(options: ResolveStatsOptions = {}): string {
+  const opts = options as ResolveStatsOptions;
+  const home = resolveParallixHome({ ensureDir: opts.ensureDir !== false });
+  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.
+ */
+export function resolveAgentsLocalPath(options?: ResolveParallixHomeOptions | string): string {
+  if (typeof options === 'string') {
+    return path.resolve(options);
+  }
+  const opts = options as ResolveParallixHomeOptions | undefined;
+  const home = resolveParallixHome({ ensureDir: opts?.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.
+ */
+export function readJson<T = unknown>(pathOrResolution: string | (() => string)): ReadJsonResult<T> {
+  let filePath: string;
+  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) as T;
+    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.
+ */
+export function writeJson(filePath: string | (() => string), data: unknown): string {
+  if (typeof filePath === 'function') {
+    filePath = filePath();
+  }
+  writeFileAtomic(filePath, `${JSON.stringify(data, null, 2)}\n`);
+  return filePath;
+}
+
+export function writeFileAtomic(filePath: string, content: string): void {
+  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.
+ */
+export function isInitialized(): boolean {
+  const home = resolveParallixHome({ ensureDir: false });
+  try {
+    return fs.statSync(home).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/lib/core/verification.js

@@ -1,166 +1,176 @@
-const { git, run } = require('./git');
-
-/** @typedef {(args: string[], options?: object) => import('child_process').SpawnSyncReturns<string>} GitFn */
-const { loadAdapterConfig } = require('./product-config');
-const fs = require('fs');
-
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_GATE_NOTICE = exports.DEFAULT_AREA = void 0;
+exports.resolveVerificationAdapter = resolveVerificationAdapter;
+exports.formatVerificationCommand = formatVerificationCommand;
+exports.runVerificationGate = runVerificationGate;
+exports.readPublishedTreeState = readPublishedTreeState;
+exports.captureVerifiedTreeProof = captureVerifiedTreeProof;
+exports.assertVerifiedTreeProof = assertVerifiedTreeProof;
+exports.default = runWorkflow;
+const git_js_1 = require("./git.js");
+const product_config_js_1 = require("./product-config.js");
+const fmt_js_1 = require("./fmt.js");
+const fsMod = __importStar(require("node: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';
+exports.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)';
-
+exports.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 };
+    const config = (0, product_config_js_1.loadAdapterConfig)(rootDir);
+    const verification = config.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()
+        : exports.DEFAULT_AREA;
+    return { command, defaultArea };
 }
-
 /** @param {string} [area] @param {string} [rootDir] */
 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 || DEFAULT_AREA);
+    const { command, defaultArea } = resolveVerificationAdapter(rootDir);
+    const effectiveArea = area || defaultArea;
+    if (!command) {
+        return exports.NO_GATE_NOTICE;
+    }
+    return command.replaceAll('{{area}}', effectiveArea || exports.DEFAULT_AREA);
 }
-
 /** @param {string} [area] @param {{rootDir?: string, log?: Function, stdio?: string, runFn?: Function}} [options] */
 function runVerificationGate(area, options = {}) {
-  /** @type {{rootDir?: string, log?: Function, stdio?: string, runFn?: Function}} */
-  const opts = options;
-  const rootDir = opts.rootDir || process.cwd();
-  const { command, defaultArea } = resolveVerificationAdapter(rootDir);
-  const effectiveArea = area || defaultArea;
-
-  if (!command) {
-    const info = opts.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 = opts.stdio || 'inherit';
-  const runFn = opts.runFn || run;
-  return runFn('bash', ['-lc', command.replaceAll('{{area}}', effectiveArea)], { cwd: rootDir, stdio });
+    const opts = options;
+    const rootDir = opts.rootDir || process.cwd();
+    const { command, defaultArea } = resolveVerificationAdapter(rootDir);
+    const effectiveArea = area || defaultArea;
+    if (!command) {
+        const info = opts.log || fmt_js_1.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 = opts.stdio || 'inherit';
+    const runFn = opts.runFn || git_js_1.run;
+    return runFn('bash', ['-lc', command.replaceAll('{{area}}', effectiveArea)], { cwd: rootDir, stdio });
 }
-
 /** @param {string} rootDir @param {{gitRunner?: GitFn}} [options] */
 function readPublishedTreeState(rootDir, options = {}) {
-  /** @type {GitFn} */
-  const gitRunner = options.gitRunner || git;
-  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 };
+    const gitRunner = options.gitRunner || git_js_1.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] */
 function captureVerifiedTreeProof(area, rootDir = process.cwd(), options = {}) {
-  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(/** @type {string} */(before.rootDir), { gitRunner });
-  if (!after.ok) {return after;}
-  if (after.commit !== before.commit || after.tree !== before.tree) {
+    const { gitRunner = git_js_1.git, runFn = git_js_1.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: false,
-      error: `verification proof became stale while publishing ${before.rootDir}`
+        ok: true,
+        proof: {
+            rootDir: before.rootDir,
+            area: effectiveArea,
+            command: command || null,
+            commit: after.commit,
+            tree: after.tree,
+            verifiedAt: new Date().toISOString()
+        }
     };
-  }
-
-  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] */
 function assertVerifiedTreeProof(proof, rootDir = process.cwd(), opts = {}) {
-  if (!proof || typeof proof !== 'object') {
-    return { ok: false, error: 'missing verification proof' };
-  }
-
-  /** @type {{gitRunner?: GitFn}} */
-  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 };
+    if (!proof || typeof proof !== 'object') {
+        return { ok: false, error: 'missing verification proof' };
+    }
+    const o = opts;
+    const gitRunner = o.gitRunner || git_js_1.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] */
 function runWorkflow(args, options = {}) {
-  /** @type {{log?: Function}} */
-  const opts = options;
-  const log = opts.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' });
+    const opts = options;
+    const logFn = opts.log || fmt_js_1.log.plain;
+    const area = args[0] || process.env.VERIFY_AREA || exports.DEFAULT_AREA;
+    logFn(`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;