@hominis/fireforge 0.39.0 → 0.41.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/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-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, 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 {};