@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/core/toolchain-preflight.d.ts

@@ -1,90 +0,0 @@
-/**
- * Toolchain-minimum awareness for Firefox source hops.
- *
- * When `fireforge download --force` moves the engine to a new Firefox major
- * version, the tree's declared toolchain minimums (cbindgen, Rust)
- * frequently move with it, and the first `fireforge build` then dies a few
- * seconds into `mach configure` with a message whose remediation text names
- * `./mach bootstrap`, the wrong tool for a FireForge-managed repo (e.g.
- * `ERROR: cbindgen version 0.29.1 is too old. At least version 0.29.4 is
- * required.`).
- *
- * Two layers:
- *  1. {@link formatMajorVersionHopNotice}, a post-download nudge when the
- *     downloaded major differs from the previously downloaded one.
- *  2. {@link runToolchainPreflight}, a cheap pre-build probe comparing the
- *     minimums the tree itself declares against the host binaries
- *     `mach configure` will resolve, probing configure's own candidate
- *     order: env override first, then the `~/.mozbuild` state-directory copy
- *     bootstrap installs, then PATH. Probing env-or-PATH alone blocks builds
- *     whose current tool lives in the state dir behind a stale PATH copy.
- *     Fail-soft: it reports a mismatch only when a minimum was positively
- *     parsed, at least one candidate resolved, and every resolved candidate
- *     is definitively lower. Any uncertainty (file moved upstream,
- *     unparseable output, no candidate found) skips silently. The
- *     mach-error-hints translator still catches the real configure failure
- *     downstream.
- */
-/** Tools the preflight knows how to probe. */
-export type ToolchainTool = 'cbindgen' | 'rustc';
-/**
- * Resolves the mach state directory the same way mach itself does:
- * `$MOZBUILD_STATE_PATH`, else `~/.mozbuild` (same resolution as
- * `mach-resource-shim.ts`).
- */
-export declare function mozbuildStateDir(): string;
-/** One probed candidate binary for a tool. */
-export interface ToolchainCandidate {
-    /** Binary path (or bare name for the PATH candidate). */
-    binary: string;
-    /** Parsed version of the candidate. */
-    version: string;
-}
-/** One definitive host-vs-tree mismatch found by the preflight. */
-export interface ToolchainMismatch {
-    tool: ToolchainTool;
-    minimumVersion: string;
-    /** Engine-relative file the minimum was parsed from. */
-    declaredIn: string;
-    /**
-     * Every candidate that resolved, all of them below the minimum
-     * (mach-resolution order: env override, mozbuild state dir, PATH).
-     */
-    candidates: ToolchainCandidate[];
-}
-/**
- * Returns the one-line notice to print after a download that hopped the
- * Firefox major version, or undefined when no notice is warranted (first
- * download, same major, or unparseable versions, since an unparseable
- * version must not spam every download with a false hint).
- *
- * @param previousVersion - `downloadedVersion` recorded in state before this download
- * @param newVersion - Version that was just downloaded
- */
-export declare function formatMajorVersionHopNotice(previousVersion: string | undefined, newVersion: string): string | undefined;
-/**
- * Reads the toolchain minimums the engine tree itself declares. Any file
- * that is missing or no longer matches the expected declaration shape
- * yields undefined for that tool, never an error.
- */
-export declare function readDeclaredToolchainMinimums(engineDir: string): Promise<Partial<Record<ToolchainTool, string>>>;
-/**
- * Compares the tree-declared toolchain minimums against the host binaries
- * `mach configure` will resolve, in configure's own candidate order (env
- * override, mozbuild state dir, PATH). A tool fails only when at least
- * one candidate resolved and none of them meets the minimum. Any single
- * passing candidate passes the tool (configure will find it), and a tool
- * with no resolvable candidate skips silently (see module header for the
- * fail-soft rationale).
- *
- * @param engineDir - Path to the engine directory
- */
-export declare function runToolchainPreflight(engineDir: string): Promise<ToolchainMismatch[]>;
-/**
- * Formats the fail-fast message for definitive preflight mismatches,
- * listing every candidate probed (in mach's resolution order) and naming
- * `fireforge bootstrap` as the remedy (mach's own configure error
- * suggests `./mach bootstrap`, which is the wrong entry point for a
- * FireForge-managed repo).
- */
-export declare function formatToolchainMismatchMessage(mismatches: ToolchainMismatch[]): string;

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

@@ -1,251 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Toolchain-minimum awareness for Firefox source hops.
- *
- * When `fireforge download --force` moves the engine to a new Firefox major
- * version, the tree's declared toolchain minimums (cbindgen, Rust)
- * frequently move with it, and the first `fireforge build` then dies a few
- * seconds into `mach configure` with a message whose remediation text names
- * `./mach bootstrap`, the wrong tool for a FireForge-managed repo (e.g.
- * `ERROR: cbindgen version 0.29.1 is too old. At least version 0.29.4 is
- * required.`).
- *
- * Two layers:
- *  1. {@link formatMajorVersionHopNotice}, a post-download nudge when the
- *     downloaded major differs from the previously downloaded one.
- *  2. {@link runToolchainPreflight}, a cheap pre-build probe comparing the
- *     minimums the tree itself declares against the host binaries
- *     `mach configure` will resolve, probing configure's own candidate
- *     order: env override first, then the `~/.mozbuild` state-directory copy
- *     bootstrap installs, then PATH. Probing env-or-PATH alone blocks builds
- *     whose current tool lives in the state dir behind a stale PATH copy.
- *     Fail-soft: it reports a mismatch only when a minimum was positively
- *     parsed, at least one candidate resolved, and every resolved candidate
- *     is definitively lower. Any uncertainty (file moved upstream,
- *     unparseable output, no candidate found) skips silently. The
- *     mach-error-hints translator still catches the real configure failure
- *     downstream.
- */
-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';
-/**
- * Resolves the mach state directory the same way mach itself does:
- * `$MOZBUILD_STATE_PATH`, else `~/.mozbuild` (same resolution as
- * `mach-resource-shim.ts`).
- */
-export function mozbuildStateDir() {
-    return process.env['MOZBUILD_STATE_PATH'] ?? join(homedir(), '.mozbuild');
-}
-/** Where each tool's minimum is declared inside the Firefox tree. */
-const MINIMUM_DECLARATIONS = {
-    // build/moz.configure/bindgen.configure:
-    //   cbindgen_min_version = Version("0.27.0")
-    cbindgen: {
-        relPath: 'build/moz.configure/bindgen.configure',
-        pattern: /cbindgen_min_version\s*=\s*Version\(\s*["']([\d.]+)["']\s*\)/,
-    },
-    // python/mozboot/mozboot/util.py:
-    //   MINIMUM_RUST_VERSION = "1.82.0"
-    // (build/moz.configure/rust.configure imports this constant, so the
-    // mozboot file is the single authority in the tree.)
-    rustc: {
-        relPath: 'python/mozboot/mozboot/util.py',
-        pattern: /MINIMUM_RUST_VERSION\s*=\s*["']([\d.]+)["']/,
-    },
-};
-/**
- * How each tool's host binary is resolved and its version parsed.
- *
- * `stateDirRelPaths` are the mach-state-directory locations
- * `fireforge bootstrap` (via mozboot) installs the tool to. mach's configure
- * tries the state directory before the PATH candidates (bindgen.configure's
- * toolchain search path lists `~/.mozbuild/cbindgen/cbindgen` first), so the
- * probe must too. Probing only env-or-PATH fails a
- * build configure would have accepted whenever an old `~/.cargo/bin/
- * cbindgen` shadows a current bootstrap-installed copy. Rust has no
- * state-dir install, since rustup owns it, so its list is empty.
- */
-const HOST_PROBES = {
-    // `mach configure` honours the CBINDGEN env option (bindgen.configure's
-    // `option(env="CBINDGEN", ...)`), so the probe must too. Otherwise the
-    // preflight could veto a build configure would have accepted.
-    cbindgen: {
-        envVar: 'CBINDGEN',
-        versionPattern: /cbindgen\s+(\d+(?:\.\d+)*)/,
-        stateDirRelPaths: ['cbindgen/cbindgen'],
-    },
-    rustc: { envVar: 'RUSTC', versionPattern: /rustc\s+(\d+(?:\.\d+)*)/, stateDirRelPaths: [] },
-};
-/**
- * Parses a dotted version string into numeric components. Trailing
- * non-numeric suffixes are ignored. Returns undefined when the string
- * does not start with a number. (Same posture as the furnace version
- * drift classifier, kept local so the two modules stay decoupled.)
- */
-function parseVersionComponents(version) {
-    const match = /^(\d+(?:\.\d+)*)/.exec(version.trim());
-    if (!match?.[1])
-        return undefined;
-    return match[1].split('.').map(Number);
-}
-/** Component-wise comparison. Missing components count as 0. */
-function isVersionLower(candidate, minimum) {
-    const length = Math.max(candidate.length, minimum.length);
-    for (let i = 0; i < length; i += 1) {
-        const a = candidate[i] ?? 0;
-        const b = minimum[i] ?? 0;
-        if (a !== b)
-            return a < b;
-    }
-    return false;
-}
-/**
- * Returns the one-line notice to print after a download that hopped the
- * Firefox major version, or undefined when no notice is warranted (first
- * download, same major, or unparseable versions, since an unparseable
- * version must not spam every download with a false hint).
- *
- * @param previousVersion - `downloadedVersion` recorded in state before this download
- * @param newVersion - Version that was just downloaded
- */
-export function formatMajorVersionHopNotice(previousVersion, newVersion) {
-    if (!previousVersion)
-        return undefined;
-    const previousMajor = parseVersionComponents(previousVersion)?.[0];
-    const newMajor = parseVersionComponents(newVersion)?.[0];
-    if (previousMajor === undefined || newMajor === undefined)
-        return undefined;
-    if (previousMajor === newMajor)
-        return undefined;
-    return (`Firefox major version changed (${previousMajor} → ${newMajor}): ` +
-        'upstream toolchain minimums (cbindgen, Rust, …) may have moved with it. ' +
-        'Consider running "fireforge bootstrap" before the next build.');
-}
-/**
- * Reads the toolchain minimums the engine tree itself declares. Any file
- * that is missing or no longer matches the expected declaration shape
- * yields undefined for that tool, never an error.
- */
-export async function readDeclaredToolchainMinimums(engineDir) {
-    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}.`);
-            return undefined;
-        }
-        try {
-            const content = await readText(filePath);
-            const match = declaration.pattern.exec(content);
-            if (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} (${toError(error).message}); skipping ${tool}.`);
-        }
-        return undefined;
-    }));
-    return Object.fromEntries(resolved.filter((entry) => entry !== undefined));
-}
-/** Runs `<binary> --version` and parses the leading version number. */
-async function probeBinaryVersion(binary, versionPattern) {
-    const output = await new Promise((resolvePromise) => {
-        execFile(binary, ['--version'], { timeout: 10_000 }, (err, stdout) => {
-            resolvePromise(err ? undefined : stdout);
-        });
-    });
-    if (output === undefined)
-        return undefined;
-    const match = versionPattern.exec(output);
-    if (!match?.[1]) {
-        verbose(`Toolchain preflight: could not parse a version from "${output.trim()}" (${binary}).`);
-        return undefined;
-    }
-    return match[1];
-}
-/**
- * Probes every candidate binary for a tool in mach's resolution order:
- * the env override (which, when set, is the only candidate, since configure
- * uses it even when a better binary exists elsewhere), then the mozbuild
- * state-directory copy bootstrap installs, then PATH. Candidates that
- * fail to run or to parse are dropped silently.
- */
-async function probeHostToolCandidates(tool) {
-    const probe = HOST_PROBES[tool];
-    const envOverride = process.env[probe.envVar];
-    const binaries = envOverride
-        ? [envOverride]
-        : [...probe.stateDirRelPaths.map((rel) => join(mozbuildStateDir(), rel)), tool];
-    const candidates = await Promise.all(binaries.map(async (binary) => {
-        const version = await probeBinaryVersion(binary, probe.versionPattern);
-        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
- * `mach configure` will resolve, in configure's own candidate order (env
- * override, mozbuild state dir, PATH). A tool fails only when at least
- * one candidate resolved and none of them meets the minimum. Any single
- * passing candidate passes the tool (configure will find it), and a tool
- * with no resolvable candidate skips silently (see module header for the
- * fail-soft rationale).
- *
- * @param engineDir - Path to the engine directory
- */
-export async function runToolchainPreflight(engineDir) {
-    const minimums = await readDeclaredToolchainMinimums(engineDir);
-    const results = await Promise.all(Object.entries(minimums).map(async ([tool, minimumVersion]) => {
-        const minimum = parseVersionComponents(minimumVersion);
-        if (!minimum)
-            return undefined;
-        const candidates = await probeHostToolCandidates(tool);
-        const parsed = candidates.filter((c) => parseVersionComponents(c.version) !== undefined);
-        if (parsed.length === 0)
-            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}.`);
-            return undefined;
-        }
-        return {
-            tool,
-            minimumVersion,
-            declaredIn: MINIMUM_DECLARATIONS[tool].relPath,
-            candidates: parsed,
-        };
-    }));
-    return results.filter((mismatch) => mismatch !== undefined);
-}
-/**
- * Formats the fail-fast message for definitive preflight mismatches,
- * listing every candidate probed (in mach's resolution order) and naming
- * `fireforge bootstrap` as the remedy (mach's own configure error
- * suggests `./mach bootstrap`, which is the wrong entry point for a
- * FireForge-managed repo).
- */
-export function formatToolchainMismatchMessage(mismatches) {
-    const lines = mismatches.map((m) => {
-        const probed = m.candidates.map((c) => `${c.version} (${c.binary})`).join(', ');
-        return (`  - ${m.tool}: no resolvable candidate meets the minimum ${m.minimumVersion} declared by ` +
-            `this Firefox source (engine/${m.declaredIn}); probed in mach's resolution order: ${probed}`);
-    });
-    return ('Toolchain preflight found host tools older than what this Firefox source requires:\n' +
-        `${lines.join('\n')}\n\n` +
-        'This typically happens after "fireforge download --force" moved the engine to a new ' +
-        'Firefox major version. Run "fireforge bootstrap" to update the toolchain, then retry the build.');
-}

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

@@ -1,16 +0,0 @@
-/** Runs a clone command. Throws on non-zero exit. */
-export type CloneExecutor = (command: string, args: string[]) => Promise<void>;
-/** How this host can materialise a tree. */
-export type CowCapability = 'clonefile' | 'reflink' | 'none';
-/**
- * Probes CoW support in `dir` by cloning a tiny probe file there.
- * Non-darwin/linux platforms report 'none' without probing.
- */
-export declare function detectCowSupport(dir: string, platform?: NodeJS.Platform, executor?: CloneExecutor): Promise<CowCapability>;
-/**
- * Copies one directory entry (file or directory, recursively) from
- * `sourcePath` to `destinationPath` using the given capability:
- * clonefile/reflink when available, a plain physical copy under
- * 'none' (the `--force-copy` path, and the caller gates on the flag).
- */
-export declare function cloneEntry(capability: CowCapability, sourcePath: string, destinationPath: string, platform?: NodeJS.Platform, executor?: CloneExecutor): Promise<void>;

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

@@ -1,71 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Copy-on-write cloning for `fireforge tree`.
- *
- * Capability is probed by doing it: a tiny `cp -c` (APFS clonefile) or
- * `cp --reflink=always` (btrfs/XFS) runs in the actual destination
- * directory, so the verdict is truthful for the volume the trees will live
- * on. A filesystem without CoW support refuses honestly. `--force-copy` opts
- * into a full physical copy but is never implied (a Firefox tree can be
- * tens of gigabytes).
- *
- * The exec layer is injected so unit tests assert the exact `cp` argv per
- * platform without touching the filesystem.
- */
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { toError } from '../utils/errors.js';
-import { verbose } from '../utils/logger.js';
-import { exec } from '../utils/process.js';
-const defaultExecutor = async (command, args) => {
-    const result = await exec(command, args);
-    if (result.exitCode !== 0) {
-        throw new Error(`${command} ${args.join(' ')} failed (exit ${result.exitCode}): ${result.stderr}`);
-    }
-};
-/** Per-platform `cp` argv prefix for a CoW copy of one entry. */
-function cowCopyArgs(capability) {
-    return capability === 'clonefile' ? ['-c', '-R', '-p'] : ['--reflink=always', '-a'];
-}
-/**
- * Probes CoW support in `dir` by cloning a tiny probe file there.
- * Non-darwin/linux platforms report 'none' without probing.
- */
-export async function detectCowSupport(dir, platform = process.platform, executor = defaultExecutor) {
-    if (platform !== 'darwin' && platform !== 'linux')
-        return 'none';
-    const capability = platform === 'darwin' ? 'clonefile' : 'reflink';
-    let probeDir;
-    try {
-        probeDir = await mkdtemp(join(dir, '.fireforge-cow-probe-'));
-        const src = join(probeDir, 'src');
-        const dst = join(probeDir, 'dst');
-        await writeFile(src, 'probe');
-        const flag = capability === 'clonefile' ? '-c' : '--reflink=always';
-        await executor('cp', [flag, src, dst]);
-        return capability;
-    }
-    catch (error) {
-        verbose(`CoW probe in ${dir} failed: ${toError(error).message}`);
-        return 'none';
-    }
-    finally {
-        if (probeDir !== undefined) {
-            await rm(probeDir, { recursive: true, force: true }).catch(() => undefined);
-        }
-    }
-}
-/**
- * Copies one directory entry (file or directory, recursively) from
- * `sourcePath` to `destinationPath` using the given capability:
- * clonefile/reflink when available, a plain physical copy under
- * 'none' (the `--force-copy` path, and the caller gates on the flag).
- */
-export async function cloneEntry(capability, sourcePath, destinationPath, platform = process.platform, executor = defaultExecutor) {
-    const args = capability === 'none'
-        ? platform === 'darwin'
-            ? ['-R', '-p']
-            : ['-a']
-        : cowCopyArgs(capability);
-    await executor('cp', [...args, sourcePath, destinationPath]);
-}

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

@@ -1,35 +0,0 @@
-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, parsed options, and the tree marker.
- */
-export declare const TREE_COMMAND_VERDICTS: Readonly<Record<string, 'allowed' | 'refused' | 'conditional'>>;
-interface ConditionalInput {
-    /** Subcommand chain below the top-level command (e.g. ['staged-dependency']). */
-    subcommands: readonly string[];
-    /** Merged options of the action command (leaf). */
-    options: Readonly<Record<string, unknown>>;
-    /** Positional args of the action command. */
-    args: readonly unknown[];
-}
-/**
- * Throws when `commandName` (with its subcommand chain and options) must
- * not run inside the tree described by `marker`. Exported for the
- * preAction hook in cli.ts and for the guard tests.
- */
-export declare function enforceTreeGuard(marker: TreeMarker, commandName: string, input: ConditionalInput): void;
-/**
- * Commander preAction hook body: locates the enclosing tree (if any) and
- * enforces the verdict table for the invoked command chain.
- */
-export declare function runTreeGuardHook(rootCommandName: string | undefined, actionCommand: {
-    name: () => string;
-    optsWithGlobals: () => Record<string, unknown>;
-    args: unknown[];
-    parent: {
-        name: () => string;
-        parent: unknown;
-    } | null;
-}): Promise<void>;
-export {};

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

@@ -1,194 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Read-only guard for verification trees.
- *
- * A tree is a snapshot: its `patches/` and `components/` are copies with
- * no merge-back model, so any command that mutates project or engine
- * state must run in the primary tree. Enforcement is default-deny via an
- * explicit verdict table over every top-level command, so a newly added
- * command is refused inside trees until its author classifies it (the
- * drift test in `tree-guard.test.ts` fails otherwise). It lives in one
- * commander `preAction` hook installed by `createProgram()`, so the
- * guard fires no matter how the cwd ended up inside a tree (`tree exec`
- * or a plain `cd`).
- */
-import { existsSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
-import { GeneralError } from '../errors/base.js';
-import { getTreeMarkerPath, readTreeMarker, } 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, parsed options, and the tree marker.
- */
-export const TREE_COMMAND_VERDICTS = {
-    setup: 'refused',
-    source: 'refused',
-    download: 'refused',
-    bootstrap: 'refused',
-    import: 'refused',
-    resolve: 'refused',
-    build: 'refused',
-    run: 'refused',
-    status: 'allowed',
-    reset: 'refused',
-    discard: 'refused',
-    export: 'conditional',
-    'export-all': 'conditional',
-    're-export': 'conditional',
-    // Parks live in the primary tree's .fireforge/ and rewrite engine files.
-    park: 'refused',
-    patch: 'refused',
-    rebase: 'refused',
-    package: 'refused',
-    watch: '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',
-    wire: 'refused',
-    token: 'refused',
-    lint: 'allowed',
-    typecheck: 'allowed',
-    verify: 'allowed',
-    // Its furnace-validate and token-coverage steps are commands a tree
-    // refuses. Run the allowed gates one by one in a tree.
-    check: 'refused',
-    furnace: 'refused',
-    // No nesting. `tree list` inside a tree is pointless but harmless, and
-    // the subcommand check below allows only `list`.
-    tree: 'conditional',
-};
-/** 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, 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). 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
- * preAction hook in cli.ts and for the guard tests.
- */
-export function enforceTreeGuard(marker, commandName, input) {
-    const verdict = TREE_COMMAND_VERDICTS[commandName] ?? 'refused';
-    if (verdict === 'allowed')
-        return;
-    const conditional = TREE_CONDITIONAL_CHECKS[commandName];
-    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);
-}
-/**
- * Commander preAction hook body: locates the enclosing tree (if any) and
- * enforces the verdict table for the invoked command chain.
- */
-export async function runTreeGuardHook(rootCommandName, actionCommand) {
-    // Resolve the top-level command and subcommand chain from the action
-    // command's parent links (commander nests subcommands).
-    const chain = [];
-    let node = actionCommand;
-    while (node && node.parent) {
-        chain.unshift(node.name());
-        node = node.parent;
-    }
-    const [commandName, ...subcommands] = chain;
-    if (commandName === undefined || commandName === rootCommandName)
-        return;
-    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 { root: current, state: await readTreeMarker(current) };
-            }
-            const parent = dirname(current);
-            if (parent === current)
-                break;
-            current = parent;
-        }
-        return undefined;
-    })();
-    if (located === undefined)
-        return;
-    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 backwards for a default-deny guard.
-    // A marker from a newer FireForge is not damaged, so the corrupt branch's
-    // remedies (recreate the tree, delete the stray marker) are actively
-    // wrong for it. Refuse with the upgrade instruction instead, and do not
-    // offer --ignore-corrupt-tree-marker: proceeding would mean acting on a
-    // marker whose fields this build does not understand.
-    if (state.kind === 'unsupported') {
-        if (TREE_COMMAND_VERDICTS[commandName] === 'allowed')
-            return;
-        throw new GeneralError(`Refusing "${[commandName, ...subcommands].join(' ')}": ${state.reason}`);
-    }
-    if (state.kind === 'corrupt') {
-        if (options['ignoreCorruptTreeMarker'] === true)
-            return;
-        // Unconditionally-allowed commands never consult marker fields, and
-        // 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,
-        args: actionCommand.args,
-    });
-}