@hominis/fireforge 0.40.0 → 0.41.0

package/dist/src/core/test-stale-check.js

@@ -23,13 +23,11 @@
  * plugin, etc.) can legitimately have a fresh `dist/` with no
  * FireForge-recorded baseline update.
  */
-import { createHash } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { verbose, warn } from '../utils/logger.js';
 import { isPackageablePath, isXpcomManifestPath } from './build-audit.js';
 import { readBuildBaseline } from './build-baseline.js';
+import { hashEngineFile } from './coverage-extend.js';
 import { collectChangedEnginePaths } from './engine-changes.js';
 export { isXpcomManifestPath };
 /** Cap on the number of changed paths rendered inline. */
@@ -83,23 +81,6 @@ export async function checkStaleBuildForTest(projectRoot, engineDir) {
     const truncated = Math.max(0, packageable.length - head.length);
     return { stale: true, changedPaths: head, truncated, baseline };
 }
-/**
- * Reads a file under the engine directory and returns a hex-encoded
- * SHA-256 of its contents, matching the hash the baseline writer
- * produces. Returns `undefined` on any IO error (missing file,
- * permission denied, etc.) so the caller can treat the path as still
- * stale rather than crashing the preflight.
- */
-async function hashEngineFile(engineDir, relPath) {
-    try {
-        const buffer = await readFile(join(engineDir, relPath));
-        return createHash('sha256').update(buffer).digest('hex');
-    }
-    catch (error) {
-        verbose(`Stale-build preflight: could not hash ${relPath} for baseline comparison — ${toError(error).message}`);
-        return undefined;
-    }
-}
 /**
  * Formats a human-readable warning body from a {@link StaleBuildResult}.
  * Kept separate from the probe so test code can assert on the structured

package/dist/src/core/toolchain-preflight.js

@@ -30,6 +30,7 @@
 import { execFile } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 /**
@@ -133,28 +134,29 @@ export function formatMajorVersionHopNotice(previousVersion, newVersion) {
  * yields undefined for that tool — never an error.
  */
 export async function readDeclaredToolchainMinimums(engineDir) {
-    const minimums = {};
-    for (const [tool, declaration] of Object.entries(MINIMUM_DECLARATIONS)) {
+    const entries = Object.entries(MINIMUM_DECLARATIONS);
+    const resolved = await Promise.all(entries.map(async ([tool, declaration]) => {
         const filePath = join(engineDir, declaration.relPath);
         if (!(await pathExists(filePath))) {
             verbose(`Toolchain preflight: ${declaration.relPath} not found; skipping ${tool}.`);
-            continue;
+            return undefined;
         }
         try {
             const content = await readText(filePath);
             const match = declaration.pattern.exec(content);
             if (match?.[1]) {
-                minimums[tool] = match[1];
+                return [tool, match[1]];
             }
             else {
                 verbose(`Toolchain preflight: no ${tool} minimum declaration recognized in ${declaration.relPath}; skipping.`);
             }
         }
         catch (error) {
-            verbose(`Toolchain preflight: could not read ${declaration.relPath} (${error instanceof Error ? error.message : String(error)}); skipping ${tool}.`);
+            verbose(`Toolchain preflight: could not read ${declaration.relPath} (${toError(error).message}); skipping ${tool}.`);
         }
-    }
-    return minimums;
+        return undefined;
+    }));
+    return Object.fromEntries(resolved.filter((entry) => entry !== undefined));
 }
 /** Runs `<binary> --version` and parses the leading version number. */
 async function probeBinaryVersion(binary, versionPattern) {
@@ -185,17 +187,14 @@ async function probeHostToolCandidates(tool) {
     const binaries = envOverride
         ? [envOverride]
         : [...probe.stateDirRelPaths.map((rel) => join(mozbuildStateDir(), rel)), tool];
-    const candidates = [];
-    for (const binary of binaries) {
+    const candidates = await Promise.all(binaries.map(async (binary) => {
         const version = await probeBinaryVersion(binary, probe.versionPattern);
-        if (version !== undefined) {
-            candidates.push({ binary, version });
-        }
-        else {
-            verbose(`Toolchain preflight: "${binary} --version" failed or not found; skipping.`);
-        }
-    }
-    return candidates;
+        if (version !== undefined)
+            return { binary, version };
+        verbose(`Toolchain preflight: "${binary} --version" failed or not found; skipping.`);
+        return undefined;
+    }));
+    return candidates.filter((candidate) => candidate !== undefined);
 }
 /**
  * Compares the tree-declared toolchain minimums against the host binaries
@@ -210,31 +209,30 @@ async function probeHostToolCandidates(tool) {
  */
 export async function runToolchainPreflight(engineDir) {
     const minimums = await readDeclaredToolchainMinimums(engineDir);
-    const mismatches = [];
-    for (const [tool, minimumVersion] of Object.entries(minimums)) {
+    const results = await Promise.all(Object.entries(minimums).map(async ([tool, minimumVersion]) => {
         const minimum = parseVersionComponents(minimumVersion);
         if (!minimum)
-            continue;
+            return undefined;
         const candidates = await probeHostToolCandidates(tool);
         const parsed = candidates.filter((c) => parseVersionComponents(c.version) !== undefined);
         if (parsed.length === 0)
-            continue;
+            return undefined;
         const satisfying = parsed.find((c) => {
             const components = parseVersionComponents(c.version);
             return components !== undefined && !isVersionLower(components, minimum);
         });
         if (satisfying) {
             verbose(`Toolchain preflight: ${tool} ${satisfying.version} (${satisfying.binary}) satisfies minimum ${minimumVersion}.`);
-            continue;
+            return undefined;
         }
-        mismatches.push({
+        return {
             tool,
             minimumVersion,
             declaredIn: MINIMUM_DECLARATIONS[tool].relPath,
             candidates: parsed,
-        });
-    }
-    return mismatches;
+        };
+    }));
+    return results.filter((mismatch) => mismatch !== undefined);
 }
 /**
  * Formats the fail-fast message for definitive preflight mismatches,

package/dist/src/core/tree-guard.d.ts

@@ -2,7 +2,7 @@ import { type TreeMarker } from './tree-store.js';
 /**
  * Per-command verdicts. `allowed` runs unconditionally; `refused` never
  * runs in a tree; `conditional` consults `TREE_CONDITIONAL_CHECKS` with
- * the invoked subcommand chain and parsed options.
+ * the invoked subcommand chain, parsed options, and the tree marker.
  */
 export declare const TREE_COMMAND_VERDICTS: Readonly<Record<string, 'allowed' | 'refused' | 'conditional'>>;
 interface ConditionalInput {

package/dist/src/core/tree-guard.js

@@ -15,11 +15,11 @@
 import { existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { GeneralError } from '../errors/base.js';
-import { readTreeMarker } from './tree-store.js';
+import { getTreeMarkerPath, readTreeMarkerState, } from './tree-store.js';
 /**
  * Per-command verdicts. `allowed` runs unconditionally; `refused` never
  * runs in a tree; `conditional` consults `TREE_CONDITIONAL_CHECKS` with
- * the invoked subcommand chain and parsed options.
+ * the invoked subcommand chain, parsed options, and the tree marker.
  */
 export const TREE_COMMAND_VERDICTS = {
     setup: 'refused',
@@ -35,13 +35,14 @@ export const TREE_COMMAND_VERDICTS = {
     discard: 'refused',
     export: 'conditional',
     'export-all': 'conditional',
-    're-export': 'refused',
+    're-export': 'conditional',
     patch: 'refused',
     rebase: 'refused',
     package: 'refused',
     watch: 'refused',
-    // Deferred with the objdir clone: obj-* embeds absolute primary paths.
-    test: 'refused',
+    // Build-less runs only, and only in trees whose marker records a cloned
+    // (mozinfo-rewritten) objdir — see the conditional check below.
+    test: 'conditional',
     config: 'conditional',
     doctor: 'conditional',
     register: 'refused',
@@ -57,18 +58,44 @@ export const TREE_COMMAND_VERDICTS = {
 };
 /** The command set named in refusal messages. */
 const ALLOWED_SUMMARY = 'Verification trees support: status, lint, typecheck, verify, doctor (read-only), ' +
-    'config (read), export --dry-run, and export-all --dry-run.';
+    'config (read), export --dry-run, export-all --dry-run, re-export --dry-run, and — ' +
+    'in trees created with --with-objdir — build-less test.';
 const TREE_CONDITIONAL_CHECKS = {
     // Exports write patches/ + patches.json; only the dry-run preview is a read.
     export: ({ options }) => options['dryRun'] === true,
     'export-all': ({ options }) => options['dryRun'] === true,
+    // Same rule for refreshing existing patches: the dry-run projection is a
+    // read (proven side-effect free and runtime-enforced by
+    // withDryRunPurityGuard — FORGE H1/H3); a real re-export writes patches/.
+    're-export': ({ options }) => options['dryRun'] === true,
     // `config` with no positional value prints; with a value it writes.
     config: ({ args }) => args.filter((a) => typeof a === 'string').length <= 1,
     // Doctor reads unless a repair flag is set.
     doctor: ({ options }) => options['repairFurnace'] !== true && options['fix'] !== true,
+    // Build-less test needs the objdir the marker records as cloned,
+    // mozinfo-rewritten AND reconfigured in-tree; `test --build` rebuilds
+    // the engine and stays primary-only (a tree is a snapshot with no
+    // merge-back model, so build outputs mutated in-tree go nowhere).
+    test: ({ options }, marker) => marker.clonedObjdir !== undefined && options['build'] !== true,
     // No tree lifecycle inside a tree; `tree list` is the only read.
     tree: ({ subcommands }) => subcommands[0] === 'list',
 };
+/**
+ * Command-specific refusal hints appended after the generic sentence —
+ * for verdicts where "mutates project or engine state" alone would
+ * misdiagnose the actual reason.
+ */
+const TREE_REFUSAL_HINTS = {
+    test: ({ options }, marker) => {
+        if (options['build'] === true) {
+            return '"test --build" rebuilds the engine and must run in the primary tree; run build-less "fireforge test" here instead.';
+        }
+        if (marker.clonedObjdir === undefined) {
+            return 'In-tree test requires a tree created with "fireforge tree create <name> --with-objdir".';
+        }
+        return undefined;
+    },
+};
 /**
  * Throws when `commandName` (with its subcommand chain and options) must
  * not run inside the tree described by `marker`. Exported for the
@@ -79,10 +106,12 @@ export function enforceTreeGuard(marker, commandName, input) {
     if (verdict === 'allowed')
         return;
     const conditional = TREE_CONDITIONAL_CHECKS[commandName];
-    if (verdict === 'conditional' && conditional && conditional(input))
+    if (verdict === 'conditional' && conditional && conditional(input, marker))
         return;
+    const hint = TREE_REFUSAL_HINTS[commandName]?.(input, marker);
     throw new GeneralError(`This is a FireForge verification tree ("${marker.name}", created from ${marker.primaryRoot}). ` +
         `"${[commandName, ...input.subcommands].join(' ')}" mutates project or engine state and must run in the primary tree. ` +
+        (hint === undefined ? '' : `${hint} `) +
         ALLOWED_SUMMARY);
 }
 /**
@@ -101,11 +130,12 @@ export async function runTreeGuardHook(rootCommandName, actionCommand) {
     const [commandName, ...subcommands] = chain;
     if (commandName === undefined || commandName === rootCommandName)
         return;
-    const marker = await (async () => {
+    const options = actionCommand.optsWithGlobals();
+    const located = await (async () => {
         let current = resolve(process.cwd());
         for (let depth = 0; depth < 50; depth++) {
             if (existsSync(join(current, 'fireforge.json'))) {
-                return readTreeMarker(current);
+                return { root: current, state: await readTreeMarkerState(current) };
             }
             const parent = dirname(current);
             if (parent === current)
@@ -114,11 +144,36 @@ export async function runTreeGuardHook(rootCommandName, actionCommand) {
         }
         return undefined;
     })();
-    if (!marker)
+    if (located === undefined)
         return;
-    enforceTreeGuard(marker, commandName, {
+    const state = located.state;
+    if (state.kind === 'absent')
+        return;
+    // A marker we cannot read is not evidence that this is not a tree — it is
+    // evidence that we cannot tell. Treating it as "not a tree" would grant the
+    // full mutating command set to a snapshot on the strength of a file that
+    // failed to parse, which is exactly backwards for a default-deny guard.
+    if (state.kind === 'corrupt') {
+        if (options['ignoreCorruptTreeMarker'] === true)
+            return;
+        // Unconditionally-allowed commands never consult marker fields — their
+        // verdict is the same in every tree — so an unreadable marker cannot
+        // change their answer. Letting them through keeps read-only diagnostics
+        // (status, lint) usable on the very tree the operator needs to inspect.
+        // 'conditional' verdicts stay refused: their predicates can write.
+        if (TREE_COMMAND_VERDICTS[commandName] === 'allowed')
+            return;
+        const markerPath = getTreeMarkerPath(located.root);
+        throw new GeneralError(`${markerPath} identifies this directory as a FireForge verification tree, but ${state.reason}. ` +
+            `Refusing "${[commandName, ...subcommands].join(' ')}" because it cannot be established ` +
+            'whether this is a snapshot or the primary tree.\n\n' +
+            'Recreate the tree (fireforge tree remove <name> && fireforge tree create <name>), or — if ' +
+            'this really is the primary tree — delete the stray marker. ' +
+            'Pass --ignore-corrupt-tree-marker to proceed anyway.');
+    }
+    enforceTreeGuard(state.marker, commandName, {
         subcommands,
-        options: actionCommand.optsWithGlobals(),
+        options,
         args: actionCommand.args,
     });
 }

package/dist/src/core/tree-store.d.ts

@@ -6,24 +6,87 @@ export interface TreeMarker {
     primaryRoot: string;
     createdAt: string;
     engineHead: string | null;
+    /** Hash of the primary engine's tracked + untracked working-tree diff. */
+    engineFingerprint?: string | null;
     patchesFingerprint: string | null;
+    /**
+     * Name of the obj-* directory cloned into this tree, written only after
+     * its mozinfo.json was successfully rewritten to the tree's paths AND the
+     * caller's in-tree reconfigure regenerated the remaining configure output.
+     * Its presence is what lets the guard admit build-less `test` in-tree
+     * (`tree-guard.ts`); absent on trees created without `--with-objdir`.
+     */
+    clonedObjdir?: string;
 }
 /** One row of `tree list`. */
 export interface TreeListEntry {
     name: string;
     path: string;
     createdAt: string;
-    staleness: 'fresh' | 'stale (engine advanced)' | 'stale (patches changed)' | 'unknown';
+    staleness: 'fresh' | 'stale (engine advanced)' | 'stale (engine worktree changed)' | 'stale (patches changed)' | 'unknown';
 }
 /** Absolute trees directory for a primary root. */
 export declare function getTreesDir(primaryRoot: string): string;
 /** Serialises tree create/remove against each other (primary-side sidecar lock). */
 export declare function withTreeLifecycleLock<T>(primaryRoot: string, operation: () => Promise<T>): Promise<T>;
-/** Reads the tree marker for a project root, or undefined when not a tree. */
+/**
+ * Outcome of reading a tree marker.
+ *
+ * The three states must stay distinct because they carry opposite safety
+ * meanings. `absent` means "this directory is not a tree", which is what lets
+ * every mutating command run. `corrupt` means "this directory claims to be a
+ * tree but we cannot read the claim" — collapsing it into `absent` (as a bare
+ * `undefined` return does) hands a snapshot the full mutating command set on
+ * the strength of a file we failed to parse, inverting `tree-guard.ts`'s
+ * default-deny design. Deleting one field from a marker was enough to run
+ * `reset` inside a clone.
+ */
+export type TreeMarkerRead = {
+    kind: 'absent';
+} | {
+    kind: 'valid';
+    marker: TreeMarker;
+} | {
+    kind: 'corrupt';
+    reason: string;
+};
+/** Absolute path of a root's tree marker. */
+export declare function getTreeMarkerPath(root: string): string;
+/**
+ * Reads the tree marker for a project root, distinguishing "not a tree" from
+ * "a tree whose marker we could not read". Callers that make a safety decision
+ * (the guard hook, the no-nesting refusal) must use this rather than
+ * {@link readTreeMarker}.
+ *
+ * Only ENOENT/ENOTDIR mean `absent`: any other probe failure (EACCES on the
+ * `.fireforge` directory, EIO, …) reports `corrupt`, because "we cannot read
+ * the marker" is not evidence that there is no marker — a `pathExists`
+ * pre-check here classified a tree with an unreadable `.fireforge` as
+ * `absent` and handed it the full mutating command set.
+ */
+export declare function readTreeMarkerState(root: string): Promise<TreeMarkerRead>;
+/**
+ * Reads the tree marker for a project root, or undefined when it is absent
+ * OR unreadable.
+ *
+ * For display and best-effort paths only (`tree list` renders an unreadable
+ * marker as staleness 'unknown'). Anything that decides whether a mutation may
+ * proceed must call {@link readTreeMarkerState} and handle `corrupt`.
+ */
 export declare function readTreeMarker(root: string): Promise<TreeMarker | undefined>;
-/** Current primary-side snapshot identity (engine HEAD + patches.json hash). */
+/**
+ * Refuses a build-less in-tree `test` when the objdir preflight found is not
+ * the one this tree's marker vouched for as rewritten-and-reconfigured. A
+ * mismatch means an objdir appeared in the tree through some path other than
+ * `tree create --with-objdir` (manual copy, partial restore), so nothing
+ * proves it was relocated — running against it could consult primary paths.
+ * No-op outside a tree; a corrupt marker is already refused by the guard.
+ */
+export declare function assertObjdirMatchesTreeMarker(projectRoot: string, objDir: string | undefined): Promise<void>;
+/** Current primary-side snapshot identity, including dirty source and patch bodies. */
 export declare function computePrimaryFingerprint(primaryRoot: string): Promise<{
     engineHead: string | null;
+    engineFingerprint?: string | null;
     patchesFingerprint: string | null;
 }>;
 /** Validates a tree name: one path segment, no traversal. */
@@ -31,10 +94,16 @@ export declare function assertValidTreeName(name: string): void;
 /**
  * Materialises the tree at `treeRoot` from `primaryRoot` using
  * `capability` ('none' = plain copy, already gated on --force-copy by
- * the caller). The engine tree is cloned whole and its `obj-*` build
- * directories removed afterwards — CoW removal is cheap, and per-entry
- * recursion into a Firefox tree is fragile. A fresh `.fireforge/` is
- * created with only `state.json` (when present) and the tree marker.
+ * the caller). The engine is cloned one TOP-LEVEL entry at a time so unwanted
+ * `obj-*` directories are never traversed or materialised. That distinction
+ * is substantial on Firefox trees: even CoW-cloning and deleting an objdir
+ * touches metadata for millions of build outputs. With `withObjdir` exactly
+ * that objdir is included — after {@link assertCloneSafeObjdir}
+ * refuses symlinked or engine-escaping objdirs before any copying —
+ * rewritten to the tree (see below), and
+ * reconfigured in-tree via the caller-supplied `reconfigure` hook. A
+ * fresh `.fireforge/` is created with only `state.json` (when present),
+ * the last-build baseline (withObjdir only), and the tree marker.
  */
 export declare function cloneTree(args: {
     primaryRoot: string;
@@ -42,12 +111,19 @@ export declare function cloneTree(args: {
     name: string;
     capability: CowCapability;
     createdAt: string;
+    withObjdir?: {
+        objDir: string;
+        reconfigure: (treeEngineDir: string) => Promise<void>;
+    };
 }): Promise<TreeMarker>;
 /** Lists trees with staleness against the current primary state. */
 export declare function listTrees(primaryRoot: string): Promise<TreeListEntry[]>;
 /**
  * Removes one tree. Refuses when a live process holds the tree's build
- * or engine-session lock, and never deletes a path outside the trees
- * directory (containment check before `rm -rf`).
+ * or engine-session lock — or when a lock directory exists whose ownership
+ * cannot be established, which `--force` overrides — and never deletes a path
+ * outside the trees directory (containment check before `rm -rf`).
  */
-export declare function removeTree(primaryRoot: string, name: string): Promise<void>;
+export declare function removeTree(primaryRoot: string, name: string, options?: {
+    force?: boolean;
+}): Promise<void>;