@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -12,7 +12,7 @@
  */
 import { findBlockCloseIndex, stripBlockCommentsInLines } from './token-dark-mode.js';
 /**
- * ONE attribute selector fragment: `[data-private]` (boolean attribute) or
+ * One attribute selector fragment: `[data-private]` (boolean attribute) or
  * `[data-skin=precision]` / `[data-skin="precision"]` (attribute with
  * value). The name and value halves are restricted to identifier-safe
  * characters so the fragment can be spliced into CSS verbatim without
@@ -26,35 +26,35 @@ import { findBlockCloseIndex, stripBlockCommentsInLines } from './token-dark-mod
 const ATTRIBUTE_FRAGMENT_PATTERN = /^\[[a-zA-Z][a-zA-Z0-9_-]*(?:=(?:"[a-zA-Z0-9_-]+"|'[a-zA-Z0-9_-]+'|[a-zA-Z0-9_-]+))?\]$/;
 /**
  * A pseudo-class tail: `:not(…)`, `:hover`, and friends. The parenthesised
- * argument is captured rather than validated here — it is a fragment run of
+ * argument is captured rather than validated here. It is a fragment run of
  * its own and goes through the same per-group check.
  */
 const QUALIFIER_PATTERN = /^:[a-zA-Z][a-zA-Z0-9-]*(?:\(([^()]*)\))?$/;
 /**
  * Splits a run of consecutive attribute fragments into its groups, or
- * returns `null` when the run is not exactly that — a group that does not
- * open with `[`, an unclosed group, an empty run, or a group whose name or
- * value is not identifier-safe.
+ * returns `undefined` when the run is not exactly that: a group that does
+ * not open with `[`, an unclosed group, an empty run, or a group whose name
+ * or value is not identifier-safe.
  *
  * @param run - The `[…][…]` text with no `:root` prefix
- * @returns The individual fragments, or null when the run is not valid
+ * @returns The individual fragments, or undefined when the run is not valid
  */
 function splitAttributeGroups(run) {
     const groups = [];
     let cursor = 0;
     while (cursor < run.length) {
         if (run[cursor] !== '[')
-            return null;
+            return undefined;
         const close = run.indexOf(']', cursor);
         if (close === -1)
-            return null;
+            return undefined;
         const group = run.slice(cursor, close + 1);
         if (!ATTRIBUTE_FRAGMENT_PATTERN.test(group))
-            return null;
+            return undefined;
         groups.push(group);
         cursor = close + 1;
     }
-    return groups.length > 0 ? groups : null;
+    return groups.length > 0 ? groups : undefined;
 }
 /** Rewrites `=value` / `='value'` to the double-quoted Mozilla convention. */
 function normalizeAttributeFragment(group) {
@@ -67,12 +67,12 @@ function normalizeAttributeFragment(group) {
  * form to the double-quoted `="value"` shape (Mozilla convention).
  * Boolean-attribute fragments are returned unchanged.
  *
- * Structure is decided by {@link rootAttributeSelector} — the matcher's own
- * parse — rather than by a second regex. That is the point: 0.44.2 widened
+ * Structure is decided by {@link rootAttributeSelector}, the matcher's own
+ * parse, rather than by a second regex. 0.44.2 widened
  * the matcher to consume consecutive `[…]` groups and stop at a pseudo-class
  * tail, and the validator did not move with it, so
  * `:root[data-skin="humanist"]:not([data-private])` was a block the tool
- * could FIND but would not let you NAME. Running both halves off one parse
+ * could find but would not let you name. Running both halves off one parse
  * is what stops them drifting apart again. Character-level safety stays a
  * separate, per-group check, because the matcher finds bracket boundaries
  * and validates no characters at all.
@@ -93,13 +93,13 @@ export function validateVariantSelector(raw) {
     if (value === '')
         return reject;
     const parts = rootAttributeSelector(`:root${value} {`);
-    // The parse must have consumed the WHOLE fragment: anything it declined to
+    // The parse must have consumed the whole fragment: anything it declined to
     // read (a stray space, a trailing combinator) is text the matcher would
     // not see either, so accepting it would author a block nothing can find.
-    if (parts === null || `${parts.attributes}${parts.qualifier}` !== `:root${value}`)
+    if (parts === undefined || `${parts.attributes}${parts.qualifier}` !== `:root${value}`)
         return reject;
     const groups = splitAttributeGroups(parts.attributes.slice(':root'.length));
-    if (groups === null)
+    if (groups === undefined)
         return reject;
     let qualifier = '';
     if (parts.qualifier !== '') {
@@ -112,7 +112,7 @@ export function validateVariantSelector(raw) {
         }
         else {
             const innerGroups = splitAttributeGroups(inner);
-            if (innerGroups === null)
+            if (innerGroups === undefined)
                 return reject;
             const name = parts.qualifier.slice(0, parts.qualifier.indexOf('('));
             qualifier = `${name}(${innerGroups.map(normalizeAttributeFragment).join('')})`;
@@ -131,31 +131,31 @@ function canonicalSelector(selector) {
 }
 /**
  * Splits the `:root[…]` selector on `line` into its attribute run and any
- * trailing qualifier, or `null` when the line carries none.
+ * trailing qualifier, or `undefined` when the line carries none.
  *
  * Index arithmetic rather than `/:root\[[^{]*\]/`: `[^{]` also matches `]`,
  * so that pattern backtracks quadratically on a line repeating `:root[`
  * (CodeQL `js/polynomial-redos`). This walk is linear and allocation-free
  * per group.
  *
- * It consumes CONSECUTIVE `[…]` groups and stops at the first character that
- * is not `[`. The previous implementation instead sliced to the LAST `]`
+ * It consumes consecutive `[…]` groups and stops at the first character that
+ * is not `[`. The previous implementation instead sliced to the last `]`
  * before the brace, which kept multi-attribute selectors comparing as a
- * whole — that property is preserved here, since consecutive groups are all
- * consumed — but it also swallowed a pseudo-class tail. On
+ * whole (that property is preserved here, since consecutive groups are all
+ * consumed) but it also swallowed a pseudo-class tail. On
  * `:root[data-theme="light"]:not([data-private]) {` the last `]` is the one
  * inside `:not(…)`, so the computed fragment was
  * `:root[data-theme="light"]:not([data-private]` and the canonical
  * comparison could never match. The unqualified
  * `:root[data-theme="dark"] { }` beside it matched fine, and that asymmetry
- * WAS the bug: an override add mirrored itself into the dark block and
- * silently skipped the light one, which is precisely the half-finished
- * themed edit `THEME_ATTRIBUTE_VARIANTS` exists to prevent.
+ * was the bug: an override add mirrored itself into the dark block and
+ * silently skipped the light one, the half-finished themed edit
+ * `THEME_ATTRIBUTE_VARIANTS` exists to prevent.
  */
 function rootAttributeSelector(line) {
     const start = line.indexOf(':root[');
     if (start === -1)
-        return null;
+        return undefined;
     const brace = line.indexOf('{', start);
     const limit = brace === -1 ? line.length : brace;
     let cursor = start + ':root'.length;
@@ -168,36 +168,35 @@ function rootAttributeSelector(line) {
         end = cursor;
     }
     if (end === start + ':root'.length)
-        return null;
+        return undefined;
     return { attributes: line.slice(start, end), qualifier: line.slice(end, limit).trim() };
 }
 /**
  * Finds the top-level `:root<variant>` block whose attribute selector
  * matches `variant` (compared canonically). Returns the opening-brace and
- * closing-brace line indices, or `null` when no such block exists.
+ * closing-brace line indices, or `undefined` when no such block exists.
  *
  * Scans a comment-stripped mirror of `lines` so braces inside comments do
- * not offset the depth counter; the returned indices line up with the
+ * not offset the depth counter. The returned indices line up with the
  * original array.
  */
 function findVariantBlock(lines, variant) {
     const stripped = stripBlockCommentsInLines(lines);
     // The request goes through the same parse as the candidate lines, so a
     // variant carrying its own `:not(…)` tail is compared tail-to-tail rather
-    // than being folded into the attribute run — where it would match nothing
+    // than being folded into the attribute run, where it would match nothing
     // and every add would splice a fresh duplicate block.
     const requested = rootAttributeSelector(`:root${variant} {`);
     const want = canonicalSelector(requested?.attributes ?? `:root${variant}`);
     const wantQualifier = canonicalSelector(requested?.qualifier ?? '');
-    for (let i = 0; i < stripped.length; i++) {
-        const line = stripped[i] ?? '';
+    for (const [i, line] of stripped.entries()) {
         const selector = rootAttributeSelector(line);
-        if (selector === null || canonicalSelector(selector.attributes) !== want)
+        if (selector === undefined || canonicalSelector(selector.attributes) !== want)
             continue;
-        // An UNqualified request still matches a qualified block: that is the
+        // An unqualified request still matches a qualified block: that is the
         // 0.44.2 behaviour `variantBlockQualifier` exists to report, since
         // silently skipping the block is the worse failure. A request that names
-        // a qualifier, though, means it — so it must match.
+        // a qualifier, though, means it, so it must match.
         if (wantQualifier !== '' && canonicalSelector(selector.qualifier) !== wantQualifier)
             continue;
         let openLine = /\{/.test(line) ? i : -1;
@@ -219,7 +218,7 @@ function findVariantBlock(lines, variant) {
             continue;
         return { open: openLine, close, qualifier: selector.qualifier };
     }
-    return null;
+    return undefined;
 }
 /**
  * Returns the line index at which a brand-new `:root<variant>` block should
@@ -229,8 +228,8 @@ function findVariantBlock(lines, variant) {
  */
 function findVariantBlockInsertionPoint(lines) {
     const stripped = stripBlockCommentsInLines(lines);
-    for (let i = 0; i < stripped.length; i++) {
-        if (/^\s*:root\s*\{/.test(stripped[i] ?? '')) {
+    for (const [i, line] of stripped.entries()) {
+        if (/^\s*:root\s*\{/.test(line)) {
             const close = findBlockCloseIndex(stripped, i);
             if (close !== -1)
                 return close + 1;
@@ -241,23 +240,23 @@ function findVariantBlockInsertionPoint(lines) {
 /**
  * True when a top-level `:root<variant>` block exists in `lines`. Used by
  * the override path to write theme-attribute blocks only when the scaffold
- * already declares them — `insertVariantDeclaration` would otherwise create
+ * already declares them. `insertVariantDeclaration` would otherwise create
  * the block, which is only wanted for the explicit `--variant` flow.
  */
 export function variantBlockExists(lines, variant) {
-    return findVariantBlock(lines, variant) !== null;
+    return findVariantBlock(lines, variant) !== undefined;
 }
 /**
  * The pseudo-class qualifier on the matched `:root<variant>` block, or
  * `undefined` when no block matched. `''` for an unqualified block.
  *
- * A qualifier such as `:not([data-private])` is semantically LOAD-BEARING:
- * writing into that block scopes the declaration to the qualified case, and
- * that may not be what the operator meant. Matching it is still the right
- * call — silently skipping it is the worse failure, and the one that
- * shipped — but the override path uses this to say out loud which selector
- * it wrote through, so the narrowing is a visible decision rather than a
- * theme bug discovered later.
+ * A qualifier such as `:not([data-private])` is load-bearing: writing into
+ * that block scopes the declaration to the qualified case, and that may not
+ * be what the operator meant. Matching it is still the right call, since
+ * silently skipping it is the worse failure and the one that shipped, but
+ * the override path uses this to say out loud which selector it wrote
+ * through, so the narrowing is a visible decision rather than a theme bug
+ * discovered later.
  *
  * @param lines - Tokens CSS split into lines
  * @param variant - Attribute selector fragment, e.g. `[data-theme="light"]`
@@ -276,8 +275,8 @@ export function variantBlockHasToken(lines, variant, tokenName) {
  * not exist).
  *
  * The located form of {@link variantBlockHasToken}: the variant add path
- * reports a skip the way the base path does — naming the block and the
- * line — instead of returning a bare boolean that leaves a no-op re-run
+ * reports a skip the way the base path does, naming the block and the
+ * line, instead of returning a bare boolean that leaves a no-op re-run
  * indistinguishable from a write.
  *
  * @param lines - Tokens CSS split into lines
@@ -289,19 +288,19 @@ export function findVariantBlockDeclaration(lines, variant, tokenName) {
     const block = findVariantBlock(lines, variant);
     if (!block)
         return undefined;
-    // Comments are stripped across the WHOLE block before scanning, matching
+    // Comments are stripped across the whole block before scanning, matching
     // what the boolean form always did: a `/* … */` spanning several lines
     // must not leave its tail looking like a declaration.
     const blockLines = lines.slice(block.open, block.close + 1);
-    // Blank the comment's CHARACTERS rather than deleting it: removing a
+    // Blank the comment's characters rather than deleting it: removing a
     // multi-line comment outright collapses its lines and shifts every line
     // number after it, which is the one thing this function exists to report.
     const stripped = blockLines
         .join('\n')
         .replace(/\/\*[\s\S]*?\*\//g, (match) => match.replace(/[^\n]/g, ' '))
         .split('\n');
-    for (let i = 0; i < stripped.length; i++) {
-        if ((stripped[i] ?? '').includes(`${tokenName}:`))
+    for (const [i, line] of stripped.entries()) {
+        if (line.includes(`${tokenName}:`))
             return { line: block.open + i + 1 };
     }
     return undefined;

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

@@ -1,27 +1,27 @@
 /**
  * Toolchain-minimum awareness for Firefox source hops.
  *
- * When `fireforge download --force` moves the engine to a new Firefox MAJOR
+ * 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
+ * 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
+ *  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
+ *  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.
- *     Deliberately FAIL-SOFT: it reports a mismatch only when a minimum was
- *     positively parsed AND 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
+ *     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.
  */
@@ -41,16 +41,16 @@ export interface ToolchainMismatch {
     /** Engine-relative file the minimum was parsed from. */
     declaredIn: string;
     /**
-     * Every candidate that resolved — all of them below the minimum
+     * 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 — an unparseable version
- * must not spam every download with a false hint).
+ * 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
@@ -59,14 +59,14 @@ export declare function formatMajorVersionHopNotice(previousVersion: string | un
 /**
  * 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.
+ * 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
+ * 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).

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

@@ -2,27 +2,27 @@
 /**
  * Toolchain-minimum awareness for Firefox source hops.
  *
- * When `fireforge download --force` moves the engine to a new Firefox MAJOR
+ * 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
+ * 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
+ *  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
+ *  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.
- *     Deliberately FAIL-SOFT: it reports a mismatch only when a minimum was
- *     positively parsed AND 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
+ *     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.
  */
@@ -62,16 +62,16 @@ const MINIMUM_DECLARATIONS = {
  *
  * `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
+ * 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 — rustup owns it — so its list is empty.
+ * 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
+    // `option(env="CBINDGEN", ...)`), so the probe must too. Otherwise the
     // preflight could veto a build configure would have accepted.
     cbindgen: {
         envVar: 'CBINDGEN',
@@ -82,7 +82,7 @@ const HOST_PROBES = {
 };
 /**
  * Parses a dotted version string into numeric components. Trailing
- * non-numeric suffixes are ignored; returns undefined when the string
+ * 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.)
  */
@@ -92,7 +92,7 @@ function parseVersionComponents(version) {
         return undefined;
     return match[1].split('.').map(Number);
 }
-/** Component-wise comparison; missing components count as 0. */
+/** 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) {
@@ -105,9 +105,9 @@ function isVersionLower(candidate, minimum) {
 }
 /**
  * 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 — an unparseable version
- * must not spam every download with a false hint).
+ * 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
@@ -121,14 +121,14 @@ export function formatMajorVersionHopNotice(previousVersion, newVersion) {
         return undefined;
     if (previousMajor === newMajor)
         return undefined;
-    return (`Firefox major version changed (${String(previousMajor)} → ${String(newMajor)}): ` +
+    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.
+ * yields undefined for that tool, never an error.
  */
 export async function readDeclaredToolchainMinimums(engineDir) {
     const entries = Object.entries(MINIMUM_DECLARATIONS);
@@ -173,7 +173,7 @@ async function probeBinaryVersion(binary, versionPattern) {
 }
 /**
  * Probes every candidate binary for a tool in mach's resolution order:
- * the env override (which, when set, is the ONLY candidate — configure
+ * 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.
@@ -196,8 +196,8 @@ async function probeHostToolCandidates(tool) {
 /**
  * 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
+ * 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).

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

@@ -1,9 +1,7 @@
-/** Runs a clone command; throws on non-zero exit. */
+/** 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.
@@ -11,8 +9,8 @@ export declare function cowCopyArgs(capability: Exclude<CowCapability, 'none'>):
 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 —
+ * `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).
+ * '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

@@ -2,10 +2,10 @@
 /**
  * Copy-on-write cloning for `fireforge tree`.
  *
- * 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
+ * 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).
  *
@@ -20,11 +20,11 @@ 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}`);
+        throw new Error(`${command} ${args.join(' ')} failed (exit ${result.exitCode}): ${result.stderr}`);
     }
 };
 /** Per-platform `cp` argv prefix for a CoW copy of one entry. */
-export function cowCopyArgs(capability) {
+function cowCopyArgs(capability) {
     return capability === 'clonefile' ? ['-c', '-R', '-p'] : ['--reflink=always', '-a'];
 }
 /**
@@ -57,9 +57,9 @@ export async function detectCowSupport(dir, platform = process.platform, executo
 }
 /**
  * Copies one directory entry (file or directory, recursively) from
- * `sourcePath` to `destinationPath` using the given capability —
+ * `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).
+ * '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'

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

@@ -1,14 +1,14 @@
 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
+ * 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). */
+    /** Merged options of the action command (leaf). */
     options: Readonly<Record<string, unknown>>;
     /** Positional args of the action command. */
     args: readonly unknown[];