@hominis/fireforge 0.39.0 → 0.40.0

package/dist/src/core/token-manager.js

@@ -5,10 +5,10 @@ import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { info, warn } from '../utils/logger.js';
-import { escapeRegex } from '../utils/regex.js';
 import { validateTokenName } from '../utils/validation.js';
 import { getProjectPaths, loadConfig } from './config.js';
 import { loadFurnaceConfig } from './furnace-config.js';
+import { assertTokenCategoryExists, categoryHeaderExists, declareCategoryBanner, findCategorySection, findTokenDeclarationInRoot, } from './token-category.js';
 import { findDarkMediaCloseIndex, findDarkRootInsertionIndex } from './token-dark-mode.js';
 import { addTokenToDocs } from './token-docs.js';
 import { insertVariantDeclaration, validateVariantSelector, variantBlockExists, variantBlockHasToken, } from './token-variant.js';
@@ -83,6 +83,10 @@ function normalizeVariantOption(options) {
         throw new InvalidArgumentError('Cannot combine --variant with --mode override; author the variant declaration with ' +
             '--mode auto/static instead.', 'variant');
     }
+    if (options.createCategory === true) {
+        throw new InvalidArgumentError('--create-category cannot be combined with --variant; variant declarations are routed ' +
+            'into a :root<selector> block, not a category section.', 'variant');
+    }
     const result = validateVariantSelector(options.variant);
     if (!result.ok) {
         throw new InvalidArgumentError(`--variant ${result.reason}.`, 'variant');
@@ -113,95 +117,26 @@ async function addVariantTokenToCSS(engineDir, options, tokensCssPath, variant)
     return { added: true };
 }
 /**
- * True when `lines` contain a category header (single-line or multi-line
- * banner shape) naming `category`. Shared by the pre-add assertion and the
- * in-memory banner creation path so both agree on what "exists" means.
+ * Evaluates base-`:root` idempotency for one add (FORGE G3): a token
+ * already declared in the TARGET category skips; a token declared
+ * anywhere else in the base block refuses loud — the pre-0.40.0
+ * whole-file substring check silently skipped (and discarded
+ * `--create-category`) in that case, exit 0.
  */
-function categoryHeaderExists(lines, category) {
-    const escapedCategory = escapeRegex(category);
-    const singleLinePattern = new RegExp(`\\/\\*\\s*=.*${escapedCategory}.*=\\s*\\*\\/`);
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        if (singleLinePattern.test(line)) {
-            return true;
-        }
-        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
-            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
-                const blockLine = lines[j] ?? '';
-                if (new RegExp(escapedCategory).test(blockLine)) {
-                    return true;
-                }
-                if (/\*\//.test(blockLine))
-                    break;
-            }
-        }
+function evaluateBaseTokenIdempotency(lines, options, tokensCssPath) {
+    const existing = findTokenDeclarationInRoot(lines, options.tokenName);
+    if (!existing)
+        return { skipped: false };
+    if (existing.category === options.category) {
+        return { skipped: true, existing };
     }
-    return false;
-}
-async function assertTokenCategoryExists(engineDir, tokensCssPath, category, createCategory = false) {
-    const filePath = join(engineDir, tokensCssPath);
-    if (!(await pathExists(filePath))) {
-        throw new GeneralError(`Token CSS file not found: ${tokensCssPath}`);
-    }
-    const content = await readText(filePath);
-    const lines = content.split('\n');
-    if (categoryHeaderExists(lines, category))
-        return;
-    // The write path declares the banner in the same edit as the token
-    // insertion, so a missing category is fine when creation was requested.
-    if (createCategory)
-        return;
-    const discoveredCategories = discoverCategoryHeaders(lines);
-    const available = discoveredCategories.length > 0
-        ? `Available categories in the file: ${discoveredCategories.map((name) => `"${name}"`).join(', ')}.`
-        : 'The file currently has no category headers.';
-    throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}.\n\n` +
-        `${available}\n\n` +
-        'Categories are declared by comment headers. Single-line shape: /* = My Category = */. ' +
-        'Multi-line shape: /* =============\\n * My Category\\n * ============= */.\n\n' +
-        'Re-run with --create-category to declare the banner and insert the token in one step.');
-}
-/**
- * Scans a tokens CSS file for category header comments and returns the
- * category names in document order. Used to enrich the "category not
- * found" error body with concrete alternatives the operator can copy.
- *
- * Mirrors the shapes `findCategorySection` already recognises:
- * - Single-line: `/* = Foo = *\/`
- * - Multi-line: `/* =====` opening, `Foo` on any of the next ~5 lines,
- *   closing `*\/`.
- *
- * This helper exists as a pure inspector; it never throws on malformed
- * headers and silently skips shapes it cannot parse.
- */
-function discoverCategoryHeaders(lines) {
-    const categories = new Set();
-    const singleLinePattern = /\/\*\s*=+\s*(.+?)\s*=+\s*\*\//;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        const singleMatch = singleLinePattern.exec(line);
-        if (singleMatch?.[1]) {
-            const extracted = singleMatch[1].trim();
-            if (extracted.length > 0)
-                categories.add(extracted);
-            continue;
-        }
-        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
-            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
-                const blockLine = lines[j] ?? '';
-                if (/\*\//.test(blockLine))
-                    break;
-                const trimmed = blockLine.replace(/^\s*\*\s*/, '').trim();
-                if (trimmed.length === 0)
-                    continue;
-                if (/^=+$/.test(trimmed))
-                    continue;
-                categories.add(trimmed);
-                break;
-            }
-        }
-    }
-    return [...categories];
+    const sectionSuffix = existing.category === undefined ? '' : `, section "${existing.category}"`;
+    const remedy = existing.category === undefined
+        ? 'remove the stray declaration first'
+        : `pass --category "${existing.category}" to target the existing declaration, or remove it first`;
+    throw new GeneralError(`Token "${options.tokenName}" is already declared outside category "${options.category}" ` +
+        `(${tokensCssPath}:${String(existing.line)}${sectionSuffix}). ` +
+        `A token belongs to exactly one category — ${remedy}.`);
 }
 /**
  * Validates token-add inputs without mutating files.
@@ -214,10 +149,11 @@ export async function validateTokenAdd(root, options) {
     validateTokenNameSyntax(options.tokenName);
     await validateTokenPrefix(root, options);
     validateDarkValue(options);
-    // Variant mode targets a `:root<attr>` block, not a category section, so it
-    // only needs the tokens CSS file to exist — category checks do not apply.
+    // Variant mode targets a `:root<attr>` block, not a category section —
+    // but the required --category must still name a REAL category rather
+    // than being silently discarded (FORGE G3 bypass 2).
     if (normalizeVariantOption(options) !== undefined) {
-        await assertTokensCssExists(engineDir, tokensCssPath);
+        await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, false);
         return;
     }
     await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, options.createCategory === true);
@@ -249,14 +185,14 @@ export async function addToken(root, options) {
                 skipped,
             };
         }
-        const stripped = content.replace(/\/\*[\s\S]*?\*\//g, '');
-        const skipped = stripped.includes(options.tokenName + ':');
+        const { skipped, existing } = evaluateBaseTokenIdempotency(content.split('\n'), options, tokensCssPath);
         return {
             cssAdded: !skipped,
             docsAdded: !skipped,
             unmappedAdded: !skipped && !options.value.startsWith('var('),
             countUpdated: !skipped,
             skipped,
+            ...(existing !== undefined ? { skippedExisting: existing } : {}),
         };
     }
     // Variant overrides are CSS-only: route the declaration into the
@@ -264,6 +200,9 @@ export async function addToken(root, options) {
     // docs row). Done before the base-CSS path so an override of an existing
     // base token is not short-circuited by the global idempotency check.
     if (normalizedVariant !== undefined) {
+        // The required --category must name a real category even though the
+        // declaration routes into the variant block (FORGE G3 bypass 2).
+        await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, false);
         const { added } = await addVariantTokenToCSS(engineDir, options, tokensCssPath, normalizedVariant);
         return {
             cssAdded: added,
@@ -274,7 +213,7 @@ export async function addToken(root, options) {
         };
     }
     // --- CSS file ---
-    const { added: cssAdded, categoryCreated } = await addTokenToCSS(engineDir, options, tokensCssPath);
+    const { added: cssAdded, categoryCreated, existing, } = await addTokenToCSS(engineDir, options, tokensCssPath);
     if (!cssAdded) {
         return {
             cssAdded: false,
@@ -282,6 +221,7 @@ export async function addToken(root, options) {
             unmappedAdded: false,
             countUpdated: false,
             skipped: true,
+            ...(existing !== undefined ? { skippedExisting: existing } : {}),
         };
     }
     // --- Documentation ---
@@ -295,100 +235,6 @@ export async function addToken(root, options) {
         categoryCreated,
     };
 }
-/**
- * Splices a new single-line category banner ("= Name =" comment shape, the
- * same format `discoverCategoryHeaders` recognises) just before the closing
- * brace of the `:root` block, making the new category the last section.
- * Mutates `lines` in place.
- */
-function declareCategoryBanner(lines, category, tokensCssPath) {
-    let rootOpen = -1;
-    for (let i = 0; i < lines.length; i++) {
-        if (/:root\s*\{/.test(lines[i] ?? '')) {
-            rootOpen = i;
-            break;
-        }
-    }
-    if (rootOpen === -1) {
-        throw new GeneralError(`Cannot create category "${category}": no :root block found in ${tokensCssPath}. ` +
-            'Run "fireforge furnace init --force" to re-scaffold the tokens CSS file.');
-    }
-    let rootClose = -1;
-    for (let i = rootOpen + 1; i < lines.length; i++) {
-        if (/^\s*\}/.test(lines[i] ?? '')) {
-            rootClose = i;
-            break;
-        }
-    }
-    if (rootClose === -1) {
-        throw new GeneralError(`Cannot create category "${category}": the :root block in ${tokensCssPath} never closes.`);
-    }
-    lines.splice(rootClose, 0, '', `  /* = ${category} = */`);
-}
-function findCategorySection(lines, category, tokensCssPath) {
-    const escapedCategory = escapeRegex(category);
-    const singleLinePattern = new RegExp(`\\/\\*\\s*=.*${escapedCategory}.*=\\s*\\*\\/`);
-    let categoryLine = -1;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        // Check single-line format: /* = Category = */
-        if (singleLinePattern.test(line)) {
-            categoryLine = i;
-            break;
-        }
-        // Check multi-line format: line opens a block comment with === but does NOT close it
-        // e.g., "/* ================================================================"
-        // (NOT "/* ================================================= */" which closes on the same line)
-        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
-            // Look ahead within the comment block (up to 5 lines) for the category text
-            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
-                const blockLine = lines[j] ?? '';
-                if (new RegExp(escapedCategory).test(blockLine)) {
-                    categoryLine = i;
-                    break;
-                }
-                // Stop if we've exited the comment block
-                if (/\*\//.test(blockLine))
-                    break;
-            }
-            if (categoryLine !== -1)
-                break;
-        }
-    }
-    if (categoryLine === -1) {
-        const discoveredCategories = discoverCategoryHeaders(lines);
-        const available = discoveredCategories.length > 0
-            ? `Available categories in the file: ${discoveredCategories.map((name) => `"${name}"`).join(', ')}.`
-            : 'The file currently has no category headers.';
-        throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}.\n\n` +
-            `${available}\n\n` +
-            'Add a header by hand inside the :root block (format: "/* = My Category = */") or re-run "fireforge furnace init --force" to re-seed the default categories.');
-    }
-    // Find the end of this category section (next section header or closing })
-    // Handles both single-line (/* =...= */) and multi-line (/* ===...) section delimiters
-    // Skip past the current header block first
-    let scanStart = categoryLine + 1;
-    for (let i = categoryLine + 1; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        // Skip lines that are part of the current header comment block
-        if (/^\s*\/\*\s*=/.test(line) || /^\s*\*\s*=/.test(line) || /^\s*\*\//.test(line)) {
-            scanStart = i + 1;
-            continue;
-        }
-        break;
-    }
-    let sectionEnd = lines.length;
-    for (let i = scanStart; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        if (/\/\*\s*=.*=\s*\*\//.test(line) ||
-            (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) ||
-            /^\s*\}/.test(line)) {
-            sectionEnd = i;
-            break;
-        }
-    }
-    return { categoryLine, sectionEnd };
-}
 /**
  * Explicit theme-attribute selectors the override path keeps in sync with
  * the `@media (prefers-color-scheme: dark)` block. Consumer scaffolds that
@@ -450,13 +296,20 @@ function insertDarkModeOverride(lines, options) {
 async function addTokenToCSS(engineDir, options, tokensCssPath) {
     const filePath = join(engineDir, tokensCssPath);
     await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, options.createCategory === true);
-    let content = await readText(filePath);
-    // Idempotency check — strip CSS block comments so we don't match inside them
-    const stripped = content.replace(/\/\*[\s\S]*?\*\//g, '');
-    if (stripped.includes(options.tokenName + ':')) {
-        return { added: false, categoryCreated: false };
-    }
+    const content = await readText(filePath);
     const lines = content.split('\n');
+    // Per-category idempotency (FORGE G3): a declaration in the TARGET
+    // category skips; a declaration elsewhere in the base :root block
+    // throws instead of silently skipping (and silently discarding
+    // --create-category).
+    const idempotency = evaluateBaseTokenIdempotency(lines, options, tokensCssPath);
+    if (idempotency.skipped) {
+        return {
+            added: false,
+            categoryCreated: false,
+            ...(idempotency.existing !== undefined ? { existing: idempotency.existing } : {}),
+        };
+    }
     const annotation = getModeAnnotation(options.mode, options.value);
     // Declare a missing category banner in the same in-memory edit as the
     // token insertion — the file is written exactly once, so a failure
@@ -488,7 +341,6 @@ async function addTokenToCSS(engineDir, options, tokensCssPath) {
     if (themeBlocksWritten.length > 0) {
         info(`Override also written to ${themeBlocksWritten.join(' and ')}.`);
     }
-    content = lines.join('\n');
-    await writeText(filePath, content);
+    await writeText(filePath, lines.join('\n'));
     return { added: true, categoryCreated };
 }

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

@@ -0,0 +1,18 @@
+/** 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';
+/** Per-platform `cp` argv prefix for a CoW copy of one entry. */
+export declare function cowCopyArgs(capability: Exclude<CowCapability, 'none'>): string[];
+/**
+ * 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; 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

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Copy-on-write cloning for `fireforge tree` (FORGE G15).
+ *
+ * Capability is probed BY DOING — a tiny `cp -c` (APFS clonefile) or
+ * `cp --reflink=always` (btrfs/XFS) 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 ${String(result.exitCode)}): ${result.stderr}`);
+    }
+};
+/** Per-platform `cp` argv prefix for a CoW copy of one entry. */
+export 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; 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

@@ -0,0 +1,35 @@
+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.
+ */
+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

@@ -0,0 +1,124 @@
+// 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 { 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 and parsed options.
+ */
+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': 'refused',
+    patch: 'refused',
+    rebase: 'refused',
+    package: 'refused',
+    watch: 'refused',
+    // Deferred with the objdir clone: obj-* embeds absolute primary paths.
+    test: 'refused',
+    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, and export-all --dry-run.';
+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,
+    // `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,
+    // No tree lifecycle inside a tree; `tree list` is the only read.
+    tree: ({ subcommands }) => subcommands[0] === 'list',
+};
+/**
+ * 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))
+        return;
+    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. ` +
+        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 marker = await (async () => {
+        let current = resolve(process.cwd());
+        for (let depth = 0; depth < 50; depth++) {
+            if (existsSync(join(current, 'fireforge.json'))) {
+                return readTreeMarker(current);
+            }
+            const parent = dirname(current);
+            if (parent === current)
+                break;
+            current = parent;
+        }
+        return undefined;
+    })();
+    if (!marker)
+        return;
+    enforceTreeGuard(marker, commandName, {
+        subcommands,
+        options: actionCommand.optsWithGlobals(),
+        args: actionCommand.args,
+    });
+}

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

@@ -0,0 +1,53 @@
+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;
+    patchesFingerprint: string | null;
+}
+/** One row of `tree list`. */
+export interface TreeListEntry {
+    name: string;
+    path: string;
+    createdAt: string;
+    staleness: 'fresh' | 'stale (engine advanced)' | '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. */
+export declare function readTreeMarker(root: string): Promise<TreeMarker | undefined>;
+/** Current primary-side snapshot identity (engine HEAD + patches.json hash). */
+export declare function computePrimaryFingerprint(primaryRoot: string): Promise<{
+    engineHead: 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 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.
+ */
+export declare function cloneTree(args: {
+    primaryRoot: string;
+    treeRoot: string;
+    name: string;
+    capability: CowCapability;
+    createdAt: string;
+}): 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`).
+ */
+export declare function removeTree(primaryRoot: string, name: string): Promise<void>;