@hominis/fireforge 0.49.1 → 0.50.0

package/dist/src/core/json-preserving-edit.js

@@ -0,0 +1,199 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Format-preserving rewrites of a JSON document.
+ *
+ * `fireforge source set`, `fireforge config` and `furnace init` change a
+ * few keys of `fireforge.json`. Re-serializing the whole document with
+ * `JSON.stringify` expands every compact object and array the project keeps
+ * on one line, so a one-key change becomes a diff across unrelated policy
+ * sections. This module diffs the document on disk against the wanted one
+ * and edits only the values that differ, in place, keeping every other byte
+ * (indentation, compact containers, key order, trailing newline).
+ *
+ * Inserted values follow the style of the container they land in: one line
+ * inside a one-line container, the container's own indentation otherwise.
+ */
+import { applyEdits, findNodeAtLocation, modify, parseTree } from 'jsonc-parser';
+import { isJsonObject } from '../utils/validation.js';
+/** The same reviver `readJson` uses, so both sides of the diff agree. */
+function parseJsonDocument(text) {
+    return JSON.parse(text, (key, value) => key === '__proto__' || key === 'constructor' || key === 'prototype' ? undefined : value);
+}
+function jsonEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((value, index) => jsonEqual(value, b[index]));
+    }
+    if (!isJsonObject(a) || !isJsonObject(b))
+        return false;
+    const keysA = definedKeys(a);
+    const keysB = definedKeys(b);
+    return keysA.length === keysB.length && keysA.every((key) => jsonEqual(a[key], b[key]));
+}
+/** Keys whose value survives `JSON.stringify` (an `undefined` value is an absent key). */
+function definedKeys(object) {
+    return Object.keys(object).filter((key) => object[key] !== undefined);
+}
+function collectChanges(path, before, after, changes) {
+    if (jsonEqual(before, after))
+        return;
+    if (isJsonObject(before) && isJsonObject(after)) {
+        for (const key of definedKeys(before)) {
+            if (after[key] === undefined)
+                changes.push({ kind: 'remove', path: [...path, key] });
+        }
+        for (const key of definedKeys(after)) {
+            const next = after[key];
+            const previous = before[key];
+            if (previous === undefined) {
+                changes.push({ kind: 'set', path: [...path, key], value: next });
+            }
+            else {
+                collectChanges([...path, key], previous, next, changes);
+            }
+        }
+        return;
+    }
+    if (Array.isArray(before) && Array.isArray(after)) {
+        const isAppend = after.length > before.length &&
+            before.every((value, index) => jsonEqual(value, after[index]));
+        if (isAppend) {
+            for (const value of after.slice(before.length))
+                changes.push({ kind: 'append', path, value });
+            return;
+        }
+        if (after.length === before.length) {
+            before.forEach((value, index) => {
+                collectChanges([...path, index], value, after[index], changes);
+            });
+            return;
+        }
+    }
+    changes.push({ kind: 'set', path, value: after });
+}
+function detectStyle(text) {
+    const indent = /^([ \t]+)\S/m.exec(text)?.[1];
+    return {
+        eol: text.includes('\r\n') ? '\r\n' : '\n',
+        indentUnit: indent === undefined ? '  ' : indent.startsWith('\t') ? '\t' : indent,
+    };
+}
+function isMultiline(text, node) {
+    return node !== undefined && text.slice(node.offset, node.offset + node.length).includes('\n');
+}
+/** The object or array holding `node` (skipping the property node of an object member). */
+function containerOf(node) {
+    const parent = node.parent;
+    return parent?.type === 'property' ? parent.parent : parent;
+}
+/** Leading whitespace of the line `offset` sits on. */
+function lineIndent(text, offset) {
+    const lineStart = text.lastIndexOf('\n', offset - 1) + 1;
+    return /^[ \t]*/.exec(text.slice(lineStart))?.[0] ?? '';
+}
+function renderCompact(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(renderCompact).join(', ')}]`;
+    }
+    if (isJsonObject(value)) {
+        const entries = definedKeys(value).map((key) => `${JSON.stringify(key)}: ${renderCompact(value[key])}`);
+        return entries.length === 0 ? '{}' : `{ ${entries.join(', ')} }`;
+    }
+    return JSON.stringify(value);
+}
+function renderValue(value, multiline, indent, style) {
+    if (!multiline)
+        return renderCompact(value);
+    return JSON.stringify(value, null, style.indentUnit)
+        .split('\n')
+        .join(style.eol + indent);
+}
+function replaceRange(text, offset, length, content) {
+    return text.slice(0, offset) + content + text.slice(offset + length);
+}
+/** Replaces an existing value, keeping a container's one-line or multi-line shape. */
+function replaceNode(text, node, value, style) {
+    const isContainer = node.type === 'object' || node.type === 'array';
+    const multiline = isContainer ? isMultiline(text, node) : isMultiline(text, containerOf(node));
+    const rendered = renderValue(value, multiline, lineIndent(text, node.offset), style);
+    return replaceRange(text, node.offset, node.length, rendered);
+}
+/** Appends `entry` (a property or an array element) after the container's last child. */
+function appendEntry(text, container, renderEntry, style) {
+    const children = container.children ?? [];
+    const last = children[children.length - 1];
+    const containerIndent = lineIndent(text, container.offset);
+    if (last === undefined) {
+        // Empty container: open it up the way its parent is laid out.
+        const multiline = isMultiline(text, containerOf(container));
+        const [open, close] = container.type === 'array' ? ['[', ']'] : ['{', '}'];
+        const childIndent = containerIndent + style.indentUnit;
+        const body = multiline
+            ? `${open}${style.eol}${childIndent}${renderEntry(true, childIndent)}${style.eol}${containerIndent}${close}`
+            : container.type === 'array'
+                ? `${open}${renderEntry(false, childIndent)}${close}`
+                : `${open} ${renderEntry(false, childIndent)} ${close}`;
+        return replaceRange(text, container.offset, container.length, body);
+    }
+    const multiline = isMultiline(text, container);
+    const indent = multiline ? lineIndent(text, last.offset) : containerIndent;
+    const separator = multiline ? `,${style.eol}${indent}` : ', ';
+    return replaceRange(text, last.offset + last.length, 0, separator + renderEntry(multiline, indent));
+}
+function applyChange(text, change, style) {
+    const root = parseTree(text);
+    if (root === undefined) {
+        throw new Error('document is not valid JSON');
+    }
+    if (change.kind === 'remove') {
+        return applyEdits(text, modify(text, change.path, undefined, {}));
+    }
+    const target = findNodeAtLocation(root, change.path);
+    if (change.kind === 'append') {
+        if (target?.type !== 'array')
+            throw new Error('append target is not an array');
+        return appendEntry(text, target, (multiline, indent) => renderValue(change.value, multiline, indent, style), style);
+    }
+    if (target !== undefined) {
+        return replaceNode(text, target, change.value, style);
+    }
+    const parent = findNodeAtLocation(root, change.path.slice(0, -1));
+    const key = change.path[change.path.length - 1];
+    if (parent?.type !== 'object' || typeof key !== 'string') {
+        throw new Error('insertion parent is not an object');
+    }
+    return appendEntry(text, parent, (multiline, indent) => `${JSON.stringify(key)}: ${renderValue(change.value, multiline, indent, style)}`, style);
+}
+/**
+ * Rewrites `text` so it parses to `next`, editing only the values that
+ * differ. Returns `undefined` when `text` is not a JSON object or the edit
+ * cannot be proven equivalent, so the caller can fall back to a full
+ * re-serialization.
+ */
+export function rewriteJsonPreservingFormat(text, next) {
+    let current;
+    try {
+        current = parseJsonDocument(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isJsonObject(current))
+        return undefined;
+    const changes = [];
+    collectChanges([], current, next, changes);
+    const style = detectStyle(text);
+    try {
+        let edited = text;
+        for (const change of changes)
+            edited = applyChange(edited, change, style);
+        // The edits are structural; prove the result before trusting it.
+        return jsonEqual(parseJsonDocument(edited), next) ? edited : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/src/core/mach.js

@@ -1,9 +1,10 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { basename, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { MachNotFoundError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
 import { info, warn } from '../utils/logger.js';
 import { exec, execInherit, execInheritCapture, execSmokeRun, execStream, } from '../utils/process.js';
+import { withBuildRunRecord } from './build-run-record.js';
 import { createSiblingLockPath, withFileLock } from './file-lock.js';
 import { ensureFirefoxIgnorefileCompatibility } from './firefox-ignorefile.js';
 import { explainMachError } from './mach-error-hints.js';
@@ -227,6 +228,12 @@ export async function runProtectedMachBuild(kind, engineDir, options = {}) {
     if (kind === 'full' && options.jobs !== undefined) {
         args.push('-j', String(options.jobs));
     }
+    // The run record lets any session see why a bundle is missing after this
+    // build dies part-way (see build-run-record.ts). The engine directory is
+    // always `<projectRoot>/engine`.
+    return withBuildRunRecord(dirname(engineDir), `mach ${args.join(' ')}`, () => runProtectedMachBuildAttempts(args, kind, engineDir, options));
+}
+async function runProtectedMachBuildAttempts(args, kind, engineDir, options) {
     const maxAttempts = Math.max(1, (options.retries ?? DEFAULT_BUILD_CRASH_RETRIES) + 1);
     for (let attempt = 1;; attempt += 1) {
         const { env } = await installMachResourceGuard(engineDir);

package/dist/src/core/negative-control-diff.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Parsing and strict application of a `fireforge test --negative-control`
+ * diff.
+ *
+ * A control is a reviewed mutation, so the applier is deliberately strict:
+ * every context and removed line must match exactly, the only tolerance is
+ * a line offset (the same one `git apply` allows, never fuzz), and a hunk
+ * that does not apply refuses the whole control before any file is
+ * written. Only plain text modifications of existing files are accepted: a
+ * created, deleted, renamed or binary file has no byte-exact restore story
+ * that is worth its risk for a neuter.
+ */
+import { type ParsedHunk } from './patch-parse.js';
+/** One file of a control diff. */
+export interface ControlDiffFile {
+    /** The path the diff names, without git's `a/`/`b/` prefix. */
+    path: string;
+    /** The hunks to apply, in file order. */
+    hunks: ParsedHunk[];
+}
+/**
+ * Parses a control diff. Accepts `git diff` output (a `diff --git` header
+ * per file), which is what `git -C engine diff -- <file>` or a project-root
+ * `git diff` writes.
+ *
+ * @param content - The diff file's text
+ * @returns One entry per file, in diff order
+ */
+export declare function parseControlDiff(content: string): ControlDiffFile[];
+/**
+ * Applies `hunks` to `original`, strictly.
+ *
+ * @param original - The file's current text
+ * @param hunks - Hunks parsed from the control diff
+ * @param label - File label for refusal messages
+ * @returns The mutated text
+ * @throws GeneralError when any hunk does not apply
+ */
+export declare function applyControlHunks(original: string, hunks: readonly ParsedHunk[], label: string): string;

package/dist/src/core/negative-control-diff.js

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Parsing and strict application of a `fireforge test --negative-control`
+ * diff.
+ *
+ * A control is a reviewed mutation, so the applier is deliberately strict:
+ * every context and removed line must match exactly, the only tolerance is
+ * a line offset (the same one `git apply` allows, never fuzz), and a hunk
+ * that does not apply refuses the whole control before any file is
+ * written. Only plain text modifications of existing files are accepted: a
+ * created, deleted, renamed or binary file has no byte-exact restore story
+ * that is worth its risk for a neuter.
+ */
+import { GeneralError } from '../errors/base.js';
+import { isContainedRelativePath, normalizePathSlashes } from '../utils/paths.js';
+import { parseDiffSections } from './patch-parse.js';
+function refuse(message) {
+    throw new GeneralError(`Negative control diff refused: ${message}`);
+}
+/**
+ * Parses a control diff. Accepts `git diff` output (a `diff --git` header
+ * per file), which is what `git -C engine diff -- <file>` or a project-root
+ * `git diff` writes.
+ *
+ * @param content - The diff file's text
+ * @returns One entry per file, in diff order
+ */
+export function parseControlDiff(content) {
+    const sections = parseDiffSections(content);
+    if (sections.length === 0) {
+        refuse('no `diff --git` sections found. Write the control with git, e.g. ' +
+            '`git -C engine diff -- <file> > control.diff` after making the edit, then revert the edit.');
+    }
+    const seen = new Set();
+    return sections.map((section) => {
+        const path = normalizePathSlashes(section.targetPath);
+        if (section.isBinary)
+            refuse(`${path} is a binary section.`);
+        if (section.isNewFile || section.isDeletedFile) {
+            refuse(`${path} creates or deletes a file; a control may only modify existing text files.`);
+        }
+        if (section.sourcePath !== section.targetPath) {
+            refuse(`${section.sourcePath} -> ${path} is a rename; a control may only modify files.`);
+        }
+        if (!isContainedRelativePath(path)) {
+            refuse(`${path} is not a contained relative path.`);
+        }
+        if (section.hunks.length === 0)
+            refuse(`${path} has no hunks.`);
+        if (seen.has(path))
+            refuse(`${path} appears in more than one section.`);
+        seen.add(path);
+        return { path, hunks: section.hunks };
+    });
+}
+function hunkSides(hunk, label, index) {
+    const oldLines = [];
+    const newLines = [];
+    for (const line of hunk.lines) {
+        const body = line.slice(1);
+        if (line.startsWith(' ') || line.startsWith('-'))
+            oldLines.push(body);
+        if (line.startsWith(' ') || line.startsWith('+'))
+            newLines.push(body);
+    }
+    if (oldLines.length !== hunk.oldCount || newLines.length !== hunk.newCount) {
+        refuse(`hunk ${index + 1} of ${label} is malformed: its header counts ` +
+            `(-${hunk.oldCount} +${hunk.newCount}) do not match its body ` +
+            `(-${oldLines.length} +${newLines.length}).`);
+    }
+    return { oldLines, newLines };
+}
+function matchesAt(lines, block, position) {
+    if (position < 0 || position + block.length > lines.length)
+        return false;
+    return block.every((line, offset) => lines[position + offset] === line);
+}
+/**
+ * The position nearest `anchor`, at or after `floor`, where `block`
+ * matches, or -1.
+ */
+function findBlock(lines, block, anchor, floor) {
+    const start = Math.max(anchor, floor);
+    for (let delta = 0; delta <= lines.length; delta += 1) {
+        if (matchesAt(lines, block, start + delta))
+            return start + delta;
+        const below = anchor - delta;
+        if (delta > 0 && below >= floor && matchesAt(lines, block, below))
+            return below;
+    }
+    return -1;
+}
+/**
+ * Applies `hunks` to `original`, strictly.
+ *
+ * @param original - The file's current text
+ * @param hunks - Hunks parsed from the control diff
+ * @param label - File label for refusal messages
+ * @returns The mutated text
+ * @throws GeneralError when any hunk does not apply
+ */
+export function applyControlHunks(original, hunks, label) {
+    const hasFinalNewline = original.endsWith('\n');
+    const lines = original === '' ? [] : (hasFinalNewline ? original.slice(0, -1) : original).split('\n');
+    const result = [];
+    let cursor = 0;
+    let finalNewline = hasFinalNewline;
+    hunks.forEach((hunk, index) => {
+        const { oldLines, newLines } = hunkSides(hunk, label, index);
+        const anchor = hunk.oldCount === 0 ? hunk.oldStart : hunk.oldStart - 1;
+        const position = oldLines.length === 0
+            ? anchor >= cursor && anchor <= lines.length
+                ? anchor
+                : -1
+            : findBlock(lines, oldLines, anchor, cursor);
+        const reachesEnd = position + oldLines.length === lines.length;
+        const endMatches = position >= 0 &&
+            (reachesEnd && oldLines.length > 0
+                ? hunk.noNewlineAtEndOld === !hasFinalNewline
+                : !hunk.noNewlineAtEndOld);
+        if (position < 0 || !endMatches) {
+            const alreadyApplied = newLines.length > 0 && findBlock(lines, newLines, Math.max(0, hunk.newStart - 1), 0) >= 0;
+            refuse(`hunk ${index + 1} of ${label} (@@ -${hunk.oldStart},${hunk.oldCount} ` +
+                `+${hunk.newStart},${hunk.newCount} @@) does not apply to the current file.` +
+                (alreadyApplied
+                    ? ' Its new side is already present: the mutation looks applied already (an earlier control that was not restored?).'
+                    : ' The file changed since the diff was written; regenerate the control against it.'));
+        }
+        result.push(...lines.slice(cursor, position), ...newLines);
+        cursor = position + oldLines.length;
+        if (reachesEnd)
+            finalNewline = !hunk.noNewlineAtEndNew;
+    });
+    result.push(...lines.slice(cursor));
+    return result.join('\n') + (finalNewline && result.length > 0 ? '\n' : '');
+}

package/dist/src/core/negative-control.d.ts

@@ -0,0 +1,138 @@
+/**
+ * `fireforge test --negative-control <diff>`: apply a reviewed mutation to
+ * engine sources for exactly one harness dispatch, then put every byte back.
+ *
+ * Safety model (also stated in docs/testing.md):
+ *
+ *  - The control is applied and restored only while the caller holds the
+ *    engine-session lock, after the pre-test build has packaged and before
+ *    the harness spawns, so no peer build or test can observe it and a
+ *    Furnace deploy cannot overwrite it.
+ *  - Before the first mutated byte is written, the original bytes of every
+ *    target go to `.fireforge/negative-control/` together with a journal
+ *    recording each file's original and mutated SHA-256, mode and
+ *    timestamps. A killed FireForge therefore leaves enough on disk to undo
+ *    the control, and the next `fireforge test` does so before anything else.
+ *  - Restore writes the original bytes back atomically, re-applies the
+ *    original mode and timestamps, and reads the file back to prove the
+ *    bytes match. It only overwrites a file that still holds exactly the
+ *    bytes the control wrote: anything else means someone edited the file
+ *    while the control ran, and that edit is kept, never clobbered, with the
+ *    original left in the journal directory and the conflict reported.
+ *  - A SIGINT or SIGTERM restores through {@link restoreActiveNegativeControlsForSignal},
+ *    which the entry point runs after the harness has shut down and before
+ *    it releases the held locks.
+ */
+import type { ParsedHunk } from './patch-parse.js';
+/** One file a control mutates. */
+export interface NegativeControlTarget {
+    /** The path as the diff names it. */
+    diffPath: string;
+    /** The engine-relative file the control mutates. */
+    enginePath: string;
+    /** Hunks to apply to the engine file. */
+    hunks: ParsedHunk[];
+    /** True when the diff named a `components/` source mapped to its deployed copy. */
+    fromComponents: boolean;
+}
+/** A parsed, resolved control, ready to apply. */
+export interface NegativeControlPlan {
+    /** The diff file, as the operator passed it. */
+    diffFile: string;
+    targets: NegativeControlTarget[];
+}
+/** Locations a control works against. */
+export interface NegativeControlPaths {
+    engineDir: string;
+    /** The project's `.fireforge/` directory. */
+    fireforgeDir: string;
+}
+interface JournalEntry {
+    enginePath: string;
+    backup: string;
+    originalSha256: string;
+    mutatedSha256: string;
+    mode: number;
+    atimeMs: number;
+    mtimeMs: number;
+}
+interface Journal {
+    version: 1;
+    diffFile: string;
+    appliedAt: string;
+    entries: JournalEntry[];
+}
+/** A control currently applied to the engine. */
+export interface ActiveNegativeControl {
+    paths: NegativeControlPaths;
+    journal: Journal;
+    /**
+     * The one restore in flight, set synchronously by whichever path (the
+     * run's own `finally`, or the signal handler) gets there first, so the
+     * other awaits the same restore instead of racing or skipping it.
+     */
+    restoring?: Promise<NegativeControlRestoreResult>;
+}
+/**
+ * Reads, parses and resolves a control diff, and (unless `deferApplyCheck`)
+ * proves every hunk applies to the current engine file, so a broken control
+ * is refused before any build time is spent.
+ *
+ * `deferApplyCheck` is for a run that builds first: Furnace redeploys a
+ * component's engine copy during the build, so a `components/` control can
+ * only be checked against what the build left behind.
+ *
+ * @param projectRoot - Project root; the diff path resolves against it
+ * @param engineDir - Absolute engine directory
+ * @param diffFile - The `--negative-control` argument
+ * @param options - `deferApplyCheck` skips the up-front apply check for
+ *   `components/` targets
+ */
+export declare function planNegativeControl(projectRoot: string, engineDir: string, diffFile: string, options?: {
+    deferApplyCheck?: boolean;
+}): Promise<NegativeControlPlan>;
+/**
+ * Applies the control: every target is computed first (a hunk that does
+ * not apply refuses with nothing written), the originals and the journal
+ * are persisted, then the mutated bytes are written. Runs as a signal
+ * critical section, so a Ctrl+C mid-apply waits for the apply to finish
+ * and the signal path then restores a complete journal.
+ *
+ * @returns The handle {@link restoreNegativeControl} takes
+ */
+export declare function applyNegativeControl(paths: NegativeControlPaths, plan: NegativeControlPlan): Promise<ActiveNegativeControl>;
+/** What happened to each file of a restored control. */
+export interface NegativeControlRestoreResult {
+    /** Engine-relative files put back to their original bytes. */
+    restored: string[];
+    /** Engine-relative files that held neither the control's bytes nor the original. */
+    conflicts: string[];
+}
+/**
+ * Restores a control applied by {@link applyNegativeControl}. Idempotent:
+ * a second caller (the signal handler racing the run's own `finally`)
+ * receives the restore already in flight.
+ *
+ * @throws GeneralError when a file changed under the control (the edit is
+ *   kept and the original stays in the journal directory) or did not read
+ *   back byte-exact
+ */
+export declare function restoreNegativeControl(control: ActiveNegativeControl): Promise<NegativeControlRestoreResult>;
+/**
+ * Restores every applied control on the way out of a SIGINT/SIGTERM. Called
+ * by the entry point after child shutdown and before the held locks are
+ * force-released. Never throws: a failure is reported on stderr and the
+ * journal stays for the next run's recovery.
+ */
+export declare function restoreActiveNegativeControlsForSignal(): Promise<void>;
+/**
+ * Undoes a control a killed FireForge left applied. Called at the start of
+ * every `fireforge test`, under the engine-session lock. A file that still
+ * holds the control's bytes is restored; a file somebody changed since is
+ * refused rather than overwritten.
+ *
+ * @throws PreflightRefusalError (`note=negative-control-pending`) when a
+ *   journal entry cannot be restored safely
+ */
+export declare function recoverPendingNegativeControl(paths: NegativeControlPaths): Promise<void>;
+export {};