@hominis/fireforge 0.39.0 → 0.41.0

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

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Read-only guard for verification trees (FORGE G15).
+ *
+ * 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 — a newly added
+ * command is refused inside trees until its author classifies it (the
+ * drift test in `tree-guard.test.ts` fails otherwise) — and 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, 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, 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',
+    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',
+    furnace: 'refused',
+    // No nesting; `tree list` inside a tree is pointless but harmless — 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 — 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
+ * 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 readTreeMarkerState(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 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,
+        args: actionCommand.args,
+    });
+}

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

@@ -0,0 +1,129 @@
+import { type CowCapability } from './tree-cow.js';
+/** `.fireforge/tree.json` — identifies a directory as a verification tree. */
+export interface TreeMarker {
+    schemaVersion: 1;
+    name: string;
+    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 (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>;
+/**
+ * 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>;
+/**
+ * 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. */
+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 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;
+    treeRoot: string;
+    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 — 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, options?: {
+    force?: boolean;
+}): Promise<void>;