@hominis/fireforge 0.43.1 → 0.44.1

package/dist/src/core/build-baseline.js

@@ -70,6 +70,7 @@ export async function readBuildBaseline(projectRoot) {
  * engine HEAD SHA (or an empty string when the engine has no HEAD yet) and
  * the current binaryName. Caller is responsible for only invoking this
  * after the build exit code was zero.
+ *
  * @param projectRoot - Root directory of the project
  * @param engineDir - Path to the engine directory
  * @param binaryName - Current `binaryName` from fireforge.json
@@ -85,10 +86,10 @@ export async function readBuildBaseline(projectRoot) {
  * @param staticComponentsHandling - `'auto'` (default) refreshes the
  *   static-components anchor whenever the coverage claim is `'full'` or
  *   absent. `'refresh'` records it even for a scoped coverage claim whose
- *   implementation escalated to a full build. `'carry-forward'` always keeps the previous anchor: needed by
- * `--extend-coverage`, whose union can EVALUATE to `'full'`
- *   while the build that produced it was still a scoped `mach build
- *   faster` that did not rebake the compiled table.
+ *   implementation escalated to a full build. `'carry-forward'` always
+ *   keeps the previous anchor: needed by `--extend-coverage`, whose union
+ *   can EVALUATE to `'full'` while the build that produced it was still a
+ *   scoped `mach build faster` that did not rebake the compiled table.
  */
 export async function writeBuildBaseline(projectRoot, engineDir, binaryName, testPackagingCoverage, previousBaseline, recordedBy, staticComponentsHandling = 'auto') {
     let engineHeadSha = '';
@@ -128,17 +129,16 @@ export async function writeBuildBaseline(projectRoot, engineDir, binaryName, tes
     await writeJson(getBuildBaselinePath(projectRoot), baseline);
 }
 /**
- * Reads the current engine workdir and computes a SHA-256 fingerprint
- * for every packageable path that is either modified against HEAD or
- * untracked. The stale-build preflight (`checkStaleBuildForTest`)
- * compares the live fingerprint for each packageable-dirty file to
- * the baseline's entry — paths where the hash matches are "the build
- * already saw this exact content", paths where it differs (or that
- * are new since the baseline) are genuinely stale.
+ * Reads the current engine workdir and computes a SHA-256 fingerprint for
+ * every packageable path that is either modified against HEAD or untracked.
+ * The stale-build preflight (`checkStaleBuildForTest`) compares the live
+ * fingerprint for each packageable-dirty file to the baseline's entry: a
+ * matching hash means the build already saw this exact content, a differing
+ * or new one means the file is genuinely stale.
  *
- * Returns `undefined` on any git failure so a broken probe never
- * corrupts the on-disk baseline with `{}`; the stale-check then falls
- * back to the pre-0.16.0 "path-only" behavior on the next test run.
+ * Returns `undefined` on any git failure so a broken probe never corrupts
+ * the on-disk baseline with `{}`; the stale-check then falls back to a
+ * path-only comparison.
  */
 async function collectPackageableFingerprints(engineDir) {
     return collectDirtyFingerprints(engineDir, isPackageablePath, 'packageable fingerprint');

package/dist/src/core/build-overwrite-guard.d.ts

@@ -1,20 +1,13 @@
 /**
  * Loud guard against silently reverting UNEXPORTED engine drift.
  *
- * `build-prepare` rewrites engine files from FireForge-owned sources
- * before every build: the branding tree, every Furnace-managed component,
- * and `mozconfig`. On a multi-session checkout that is a silent
- * destructive write. The recorded incident: one session edited a file in
- * `engine/` while another held the engine lock; the lock-holder's build
- * rewrote the file back to its patch baseline; the editing session's later
- * `re-export --wait-lock` then captured a HYBRID file — and every gate
- * passed on the hybrid capture. Only a hand-run grep of the patch body
- * caught it.
- *
- * The `setupBranding` half of this class was closed in `31fdf744` (the
- * branding writer preserves unmanaged lines). The general shape — any
- * build-prepare overwrite destroying local drift that no patch records —
- * stayed silent, and silence is what made the hybrid capture possible.
+ * `build-prepare` rewrites engine files from FireForge-owned sources before
+ * every build: the branding tree, every Furnace-managed component, and
+ * `mozconfig`. On a multi-session checkout that is a silent destructive
+ * write — one session edits a file in `engine/` while another holds the
+ * engine lock, the lock-holder's build rewrites it back to its patch
+ * baseline, and the editing session's later `re-export --wait-lock`
+ * captures a HYBRID file that every gate then passes.
  *
  * This guard runs BEFORE the writes, classifies the engine's dirty files
  * with the same classifier `fireforge status` uses, and reports the ones

package/dist/src/core/build-overwrite-guard.js

@@ -2,20 +2,13 @@
 /**
  * Loud guard against silently reverting UNEXPORTED engine drift.
  *
- * `build-prepare` rewrites engine files from FireForge-owned sources
- * before every build: the branding tree, every Furnace-managed component,
- * and `mozconfig`. On a multi-session checkout that is a silent
- * destructive write. The recorded incident: one session edited a file in
- * `engine/` while another held the engine lock; the lock-holder's build
- * rewrote the file back to its patch baseline; the editing session's later
- * `re-export --wait-lock` then captured a HYBRID file — and every gate
- * passed on the hybrid capture. Only a hand-run grep of the patch body
- * caught it.
- *
- * The `setupBranding` half of this class was closed in `31fdf744` (the
- * branding writer preserves unmanaged lines). The general shape — any
- * build-prepare overwrite destroying local drift that no patch records —
- * stayed silent, and silence is what made the hybrid capture possible.
+ * `build-prepare` rewrites engine files from FireForge-owned sources before
+ * every build: the branding tree, every Furnace-managed component, and
+ * `mozconfig`. On a multi-session checkout that is a silent destructive
+ * write — one session edits a file in `engine/` while another holds the
+ * engine lock, the lock-holder's build rewrites it back to its patch
+ * baseline, and the editing session's later `re-export --wait-lock`
+ * captures a HYBRID file that every gate then passes.
  *
  * This guard runs BEFORE the writes, classifies the engine's dirty files
  * with the same classifier `fireforge status` uses, and reports the ones
@@ -66,20 +59,17 @@ function isOverwrittenByBuildPrepare(file, binaryName, furnacePrefixes) {
  * expanding collapsed untracked directories on the way.
  *
  * Git reports a WHOLLY untracked directory as a single `?? dir/` entry
- * rather than listing the files under it. A directory entry has no
- * content to compare, so `classifyFiles` matched it against neither a
- * patch body nor the pristine baseline and bucketed it `unmanaged` — an
- * at-risk classification. 0.43.0 shipped the guard on the raw status and
- * so warned about every untracked branding subdirectory on every build,
- * while `status --unmanaged` (which expands) reported the same tree
- * clean. Expanding here is what makes the two agree by construction.
+ * rather than listing the files under it. A directory entry has no content
+ * to compare, so `classifyFiles` matches it against neither a patch body nor
+ * the pristine baseline and buckets it `unmanaged` — an at-risk
+ * classification. Expanding here is what keeps this guard and
+ * `status --unmanaged`, which expands, agreeing by construction.
  *
- * Expansion is scoped to build-prepare-owned prefixes on both sides of
- * the walk: a collapsed directory that merely CONTAINS an owned prefix
- * (`components/` when `components/custom/` is Furnace-managed) is
- * rewritten to the owned prefixes beneath it, so the enumeration never
- * walks an unrelated subtree — and never trips the per-directory
- * expansion cap on a tree whose owned prefixes are small.
+ * Expansion is scoped to build-prepare-owned prefixes on both sides of the
+ * walk: a collapsed directory that merely CONTAINS an owned prefix
+ * (`components/` when `components/custom/` is Furnace-managed) is rewritten
+ * to the owned prefixes beneath it, so the enumeration never walks an
+ * unrelated subtree and never trips the per-directory expansion cap.
  */
 async function collectOverwrittenEntries(engineDir, status, binaryName, furnacePrefixes) {
     const ownedPrefixes = buildPrepareOwnedPrefixes(binaryName, furnacePrefixes);

package/dist/src/core/build-prepare.d.ts

@@ -37,8 +37,8 @@ export declare function requiresFullBuildForIncrementalTest(path: string): boole
  * Describes an exit code in the shell's 128+N signal convention. Truncated
  * configure/build logs with a signal-shaped exit (e.g. 144 = 128+16, SIGURG
  * on macOS) are environmental interruptions, not compiler failures — naming
- * that in the failure text saves the operator a fruitless log hunt
- *. Returns undefined for codes <= 128 (regular failures) and
+ * that in the failure text saves the operator a fruitless log hunt.
+ * Returns undefined for codes <= 128 (regular failures) and
  * for codes past the conventional signal range, so callers append nothing.
  */
 export declare function describeSignalShapedExit(exitCode: number): string | undefined;

package/dist/src/core/build-prepare.js

@@ -44,8 +44,8 @@ function extractMachConfigureError(result) {
  * Describes an exit code in the shell's 128+N signal convention. Truncated
  * configure/build logs with a signal-shaped exit (e.g. 144 = 128+16, SIGURG
  * on macOS) are environmental interruptions, not compiler failures — naming
- * that in the failure text saves the operator a fruitless log hunt
- *. Returns undefined for codes <= 128 (regular failures) and
+ * that in the failure text saves the operator a fruitless log hunt.
+ * Returns undefined for codes <= 128 (regular failures) and
  * for codes past the conventional signal range, so callers append nothing.
  */
 export function describeSignalShapedExit(exitCode) {
@@ -94,10 +94,10 @@ export function isBackendInvalidatingFile(path) {
  *
  * Every write `prepareBuildEnvironment` performs — branding, Furnace
  * components, `mozconfig` — rewrites engine files from a FireForge-owned
- * source. Content recorded in neither a patch body nor the pristine
- * baseline is destroyed by that, and on a multi-session checkout the
- * destruction is what lets a later re-export capture a half-reverted
- * hybrid that every gate then passes.
+ * source. Content recorded in neither a patch body nor the pristine baseline
+ * is destroyed by that, and on a multi-session checkout the destruction is
+ * what lets a later re-export capture a half-reverted hybrid that every gate
+ * then passes.
  *
  * @param projectRoot - Project root
  * @param config - Loaded FireForge config
@@ -190,9 +190,8 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
     // project license through so `buildConfigureScriptContent` /
     // `buildBrandPropertiesContent` / `buildBrandFtlContent` stamp the
     // generated files with a matching SPDX header — otherwise `patch-lint`
-    // flags them with `missing-license-header` on every subsequent export
-    // when the project is not MPL-2.0 (the eval finding: a 0BSD-licensed
-    // fork's first export failed `lint` on its own generated branding).
+    // flags them with `missing-license-header` on every subsequent export when
+    // the project is not MPL-2.0.
     const brandingConfig = {
         name: config.name,
         vendor: config.vendor,

package/dist/src/core/config-mutate.js

@@ -18,21 +18,16 @@ function cloneConfigDocument(config) {
     return cloned;
 }
 /**
- * Key segments that would walk into or rewrite the object prototype chain
- * if used as plain property names. Blocked up-front so the descent in
- * {@link mutateConfig} cannot be weaponized to mutate `Object.prototype`
- * process-wide — e.g. `fireforge config __proto__.polluted 1 --force`
- * would otherwise land in `getOrCreateChildRecord(raw, "__proto__")`.
+ * The error every sentinel-segment refusal raises. Only the MESSAGE lives
+ * here: the comparison itself is spelled inline at each write site, because
+ * that is what both a reader and CodeQL's `js/prototype-pollution-utility`
+ * barrier detection need — the latter is not interprocedural, so a check
+ * hidden behind a helper leaves the descent below looking unguarded.
  */
-const SENTINEL_KEY_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
-function assertNoSentinelSegments(key, parts) {
-    for (const part of parts) {
-        if (SENTINEL_KEY_SEGMENTS.has(part)) {
-            throw new ConfigError(`Config key "${key}" contains a reserved segment "${part}". ` +
-                'Segments "__proto__", "constructor", and "prototype" are not permitted ' +
-                'because they would mutate the object prototype chain.');
-        }
-    }
+function sentinelSegmentError(key, part) {
+    return new ConfigError(`Config key "${key}" contains a reserved segment "${part}". ` +
+        'Segments "__proto__", "constructor", and "prototype" are not permitted ' +
+        'because they would mutate the object prototype chain.');
 }
 function getOrCreateChildRecord(parent, key) {
     const existing = parent[key];
@@ -45,21 +40,27 @@ function getOrCreateChildRecord(parent, key) {
 }
 export function mutateConfig(config, key, value, skipValidation = false) {
     const parts = key.split('.');
-    // Reject prototype-chain sentinel segments before any write so
-    // `--force` cannot be used to mutate Object.prototype. This guard must
-    // run against the original key parts, not any subset — the final leaf
-    // assignment `current[lastPart] = value` would otherwise stay vulnerable.
-    assertNoSentinelSegments(key, parts);
     const raw = cloneConfigDocument(config);
+    // Every segment is checked at the point it is USED as a property name —
+    // the descent below and the leaf assignment — rather than once up front,
+    // so `--force` cannot be used to mutate Object.prototype and neither write
+    // can drift out from behind the guard. `raw` is a private clone, so a
+    // refusal here has mutated nothing the caller can observe.
     let current = raw;
     for (let i = 0; i < parts.length - 1; i++) {
         const part = parts[i];
         if (part === undefined)
             continue;
+        if (part === '__proto__' || part === 'constructor' || part === 'prototype') {
+            throw sentinelSegmentError(key, part);
+        }
         current = getOrCreateChildRecord(current, part);
     }
     const lastPart = parts[parts.length - 1];
     if (lastPart !== undefined) {
+        if (lastPart === '__proto__' || lastPart === 'constructor' || lastPart === 'prototype') {
+            throw sentinelSegmentError(key, lastPart);
+        }
         current[lastPart] = value;
     }
     if (!skipValidation) {

package/dist/src/core/config-state.js

@@ -3,10 +3,14 @@
  * Project state file management (.fireforge/state.json).
  */
 import { ConfigError } from '../errors/config.js';
+import { BUILD_MODES } from '../types/config.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
 import { isObject, isString } from '../utils/validation.js';
+import { makeEnumGuard } from '../utils/validation.js';
+/** Narrows an arbitrary string to a {@link BuildMode}. */
+const isBuildMode = makeEnumGuard(BUILD_MODES);
 import { getProjectPaths } from './config-paths.js';
 import { quarantineStateFile, withStateFileLock } from './state-file.js';
 function sanitizeProjectState(data) {
@@ -36,11 +40,15 @@ function sanitizeProjectState(data) {
             issues.push(`field "${key}" must be a string`);
             continue;
         }
-        if (key === 'buildMode' && !['dev', 'debug', 'release'].includes(value)) {
-            issues.push('field "buildMode" must be one of: dev, debug, release');
-            continue;
-        }
         if (key === 'buildMode') {
+            // Validate and assign in ONE block so the predicate's narrowing reaches
+            // the assignment. Split across two `key === 'buildMode'` guards,
+            // TypeScript cannot correlate them and the assignment needed a cast —
+            // which is what let the untyped allowlist drift from the union.
+            if (!isBuildMode(value)) {
+                issues.push(`field "buildMode" must be one of: ${BUILD_MODES.join(', ')}`);
+                continue;
+            }
             state.buildMode = value;
         }
         else {

package/dist/src/core/config-validate.js

@@ -6,7 +6,7 @@ import { ConfigError } from '../errors/config.js';
 import { verbose } from '../utils/logger.js';
 import { parseObject } from '../utils/parse.js';
 import { isContainedRelativePath, isExplicitAbsolutePath } from '../utils/paths.js';
-import { isObject, isValidAppId, isValidFirefoxCandidate, isValidFirefoxVersion, isValidProjectLicense, PROJECT_LICENSES, validateFirefoxProductVersionCompatibility, } from '../utils/validation.js';
+import { describeProductVersionIncompatibility, FIREFOX_PRODUCTS, isObject, isValidAppId, isValidFirefoxCandidate, isValidFirefoxProduct, isValidFirefoxVersion, isValidProjectLicense, PROJECT_LICENSES, } from '../utils/validation.js';
 import { SUPPORTED_CONFIG_ROOT_KEYS } from './config-paths.js';
 import { parsePatchPolicyBlock } from './config-validate-patch-policy.js';
 import { parseExternalToolchainsBlock, parseTestBlock } from './config-validate-test-toolchains.js';
@@ -68,12 +68,15 @@ function parseFirefoxBlock(rec) {
         throw new ConfigError('Config field "firefox.version" must be a valid Firefox version (e.g., "145.0")');
     }
     const firefoxProduct = requireConfigString(firefoxRec, 'product', 'firefox.product');
-    const validProducts = ['firefox', 'firefox-esr', 'firefox-beta', 'firefox-devedition'];
-    if (!validProducts.includes(firefoxProduct)) {
-        throw new ConfigError(`Config field "firefox.product" must be one of: ${validProducts.join(', ')}`);
+    // Uses the shared guard rather than a fourth copy of the member list. This
+    // is the fireforge.json READ path: a product added to the union but not to
+    // the copy that used to live here would have been silently rejected from
+    // every project config.
+    if (!isValidFirefoxProduct(firefoxProduct)) {
+        throw new ConfigError(`Config field "firefox.product" must be one of: ${FIREFOX_PRODUCTS.join(', ')}`);
     }
     // Cross-field validation: product and version must be compatible
-    const compatError = validateFirefoxProductVersionCompatibility(firefoxVersion, firefoxProduct);
+    const compatError = describeProductVersionIncompatibility(firefoxVersion, firefoxProduct);
     if (compatError) {
         throw new ConfigError(compatError);
     }

package/dist/src/core/config.d.ts

@@ -66,13 +66,10 @@ export declare function writeConfigDocument(root: string, config: FireForgeConfi
 /**
  * Runs an operation while holding a sidecar lock on `fireforge.json`.
  *
- * Motivating case (2026-04-21 eval): two concurrent `fireforge config
- * <key> <value>` invocations each ran load → mutate → writeJson against
- * the same on-disk fireforge.json. The second rename landed after the
- * first, silently dropping the first writer's key — both commands exited
- * `0`, but only one change survived. This helper turns the same
- * read-modify-write sequence into a serialised operation so a concurrent
- * writer now waits for the lock rather than racing on the document.
+ * Two concurrent `fireforge config <key> <value>` invocations each run
+ * load → mutate → writeJson against the same document; without this lock the
+ * second rename lands after the first and silently drops the first writer's
+ * key, with both commands exiting 0.
  *
  * Reads (`loadConfig`, `loadRawConfigDocument`) stay lock-free: writers
  * always use `writeJson`'s atomic temp-file + rename, so a reader observes
@@ -81,7 +78,7 @@ export declare function writeConfigDocument(root: string, config: FireForgeConfi
  *
  * The lock is a sidecar directory `${config}.fireforge-config.lock`, and
  * `withFileLock` handles stale-lock recovery (PID-alive probe, age-based
- * fallback) — a crashed writer does not permanently block future writes.
+ * fallback), so a crashed writer does not permanently block future writes.
  *
  * @param root - Root directory of the project
  * @param operation - Async function to run while holding the lock

package/dist/src/core/config.js

@@ -26,14 +26,8 @@ export { validateConfig } from './config-validate.js';
  * Config-file existence probe.
  *
  * Uses {@link pathExistsStrict} deliberately: a permission error probing
- * `fireforge.json` must propagate rather than read as "no config here", which
- * is what plain `pathExists` would report.
- *
- * The `fsUtils as typeof fsUtils & { pathExistsStrict?: … }` cast this
- * replaced re-declared a real, non-optional export as optional so a partial
- * `vi.mock` of `utils/fs.js` would fall back to `pathExists` — production code
- * shaped around a test double, and shaped around the *wrong* function, since
- * the two differ precisely on whether EACCES propagates.
+ * `fireforge.json` must propagate rather than read as "no config here",
+ * which is what plain `pathExists` would report.
  */
 async function configPathExists(path) {
     return fsUtils.pathExistsStrict(path);
@@ -134,13 +128,10 @@ export async function writeConfigDocument(root, config) {
 /**
  * Runs an operation while holding a sidecar lock on `fireforge.json`.
  *
- * Motivating case (2026-04-21 eval): two concurrent `fireforge config
- * <key> <value>` invocations each ran load → mutate → writeJson against
- * the same on-disk fireforge.json. The second rename landed after the
- * first, silently dropping the first writer's key — both commands exited
- * `0`, but only one change survived. This helper turns the same
- * read-modify-write sequence into a serialised operation so a concurrent
- * writer now waits for the lock rather than racing on the document.
+ * Two concurrent `fireforge config <key> <value>` invocations each run
+ * load → mutate → writeJson against the same document; without this lock the
+ * second rename lands after the first and silently drops the first writer's
+ * key, with both commands exiting 0.
  *
  * Reads (`loadConfig`, `loadRawConfigDocument`) stay lock-free: writers
  * always use `writeJson`'s atomic temp-file + rename, so a reader observes
@@ -149,7 +140,7 @@ export async function writeConfigDocument(root, config) {
  *
  * The lock is a sidecar directory `${config}.fireforge-config.lock`, and
  * `withFileLock` handles stale-lock recovery (PID-alive probe, age-based
- * fallback) — a crashed writer does not permanently block future writes.
+ * fallback), so a crashed writer does not permanently block future writes.
  *
  * @param root - Root directory of the project
  * @param operation - Async function to run while holding the lock

package/dist/src/core/coverage-extend.d.ts

@@ -1,10 +1,10 @@
 /**
- * `test --build/--build-only --extend-coverage`: unions the
- * requested paths into the recorded `testPackagingCoverage` instead of
- * replacing it, under an anchor guard.
+ * `test --build/--build-only --extend-coverage`: unions the requested paths
+ * into the recorded `testPackagingCoverage` instead of replacing it, under
+ * an anchor guard.
  *
- * Coverage REPLACES by default for a documented reason
- * (`build-baseline-types.ts`): every baseline write refreshes
+ * Coverage REPLACES by default for a reason documented in
+ * `build-baseline-types.ts`: every baseline write refreshes
  * `packageableFingerprints` for ALL dirty packageable paths, so a blind
  * union would whitewash an earlier scope's edited fixtures while
  * `obj-*`/`_tests/` still holds that scope's stale staging. Extending is
@@ -14,9 +14,10 @@
  *
  *   1. engine HEAD is unchanged — every committed edit is excluded;
  *   2. every path the previous baseline fingerprinted still hashes to the
- *      recorded digest — the earlier scope's staging inputs are byte-identical.
- *      Files that became dirty SINCE that build are fine: the current
- *      whole-tree `mach build faster` repackages `dist/` and vouches for them;
+ *      recorded digest, so the earlier scope's staging inputs are
+ *      byte-identical. Files that became dirty SINCE that build are fine:
+ *      the current whole-tree `mach build faster` repackages `dist/` and
+ *      vouches for them;
  *   3. the generated `engine/mozconfig` is unchanged. Engine HEAD does not
  *      cover this — the mozconfig is regenerated from project-side
  *      `configs/*.mozconfig` templates plus `fireforge.json` on every build,
@@ -29,8 +30,8 @@
  * fixtures under previously covered paths (plain test files, manifests
  * `isPackageablePath` rejects) are invisible to check 2. Editing one
  * uncommitted between two builds leaves the earlier scope's `_tests/`
- * staging stale while extend still vouches for it. Plain REPLACE has no
- * such window, because the earlier scope simply stops being covered.
+ * staging stale while extend still vouches for it. Plain REPLACE has no such
+ * window, because the earlier scope simply stops being covered.
  */
 import { type BuildBaseline, type TestPackagingCoverage } from './build-baseline-types.js';
 /** Why `--extend-coverage` could not union onto the recorded claim. */
@@ -62,9 +63,10 @@ export declare function checkExtendCoverageAnchor(engineDir: string, previousBas
  */
 export declare function checkExtendMozconfigAnchor(engineDir: string, previousBaseline: BuildBaseline | undefined): Promise<ExtendAnchorResult>;
 /**
- * Unions the newly built paths onto the recorded claim. A `'full'` claim
- * (or a pre-0.37.0 absent one, which means full historically) stays
- * `'full'` — it already covers everything.
+ * Unions the newly built paths onto the recorded claim. A `'full'` claim, or
+ * an absent one (which means full), stays `'full'` — it already covers
+ * everything.
+ *
  * @param previous - Coverage recorded by the previous build
  * @param requested - Normalized request paths this build packaged
  */

package/dist/src/core/coverage-extend.js

@@ -1,11 +1,11 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `test --build/--build-only --extend-coverage`: unions the
- * requested paths into the recorded `testPackagingCoverage` instead of
- * replacing it, under an anchor guard.
+ * `test --build/--build-only --extend-coverage`: unions the requested paths
+ * into the recorded `testPackagingCoverage` instead of replacing it, under
+ * an anchor guard.
  *
- * Coverage REPLACES by default for a documented reason
- * (`build-baseline-types.ts`): every baseline write refreshes
+ * Coverage REPLACES by default for a reason documented in
+ * `build-baseline-types.ts`: every baseline write refreshes
  * `packageableFingerprints` for ALL dirty packageable paths, so a blind
  * union would whitewash an earlier scope's edited fixtures while
  * `obj-*`/`_tests/` still holds that scope's stale staging. Extending is
@@ -15,9 +15,10 @@
  *
  *   1. engine HEAD is unchanged — every committed edit is excluded;
  *   2. every path the previous baseline fingerprinted still hashes to the
- *      recorded digest — the earlier scope's staging inputs are byte-identical.
- *      Files that became dirty SINCE that build are fine: the current
- *      whole-tree `mach build faster` repackages `dist/` and vouches for them;
+ *      recorded digest, so the earlier scope's staging inputs are
+ *      byte-identical. Files that became dirty SINCE that build are fine:
+ *      the current whole-tree `mach build faster` repackages `dist/` and
+ *      vouches for them;
  *   3. the generated `engine/mozconfig` is unchanged. Engine HEAD does not
  *      cover this — the mozconfig is regenerated from project-side
  *      `configs/*.mozconfig` templates plus `fireforge.json` on every build,
@@ -30,8 +31,8 @@
  * fixtures under previously covered paths (plain test files, manifests
  * `isPackageablePath` rejects) are invisible to check 2. Editing one
  * uncommitted between two builds leaves the earlier scope's `_tests/`
- * staging stale while extend still vouches for it. Plain REPLACE has no
- * such window, because the earlier scope simply stops being covered.
+ * staging stale while extend still vouches for it. Plain REPLACE has no such
+ * window, because the earlier scope simply stops being covered.
  */
 import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
@@ -106,9 +107,10 @@ export async function checkExtendMozconfigAnchor(engineDir, previousBaseline) {
     return { ok: true };
 }
 /**
- * Unions the newly built paths onto the recorded claim. A `'full'` claim
- * (or a pre-0.37.0 absent one, which means full historically) stays
- * `'full'` — it already covers everything.
+ * Unions the newly built paths onto the recorded claim. A `'full'` claim, or
+ * an absent one (which means full), stays `'full'` — it already covers
+ * everything.
+ *
  * @param previous - Coverage recorded by the previous build
  * @param requested - Normalized request paths this build packaged
  */

package/dist/src/core/destructive.d.ts

@@ -49,8 +49,16 @@ export interface DestructiveOpInput {
     /** Structural conflicts that should block the operation unless `unsafeOverride`. */
     conflicts?: ConflictReport | null;
 }
-/** Outcome of {@link confirmDestructive}. */
-export type DestructiveOpResult = 'proceed' | 'dry-run' | 'cancelled';
+/**
+ * Outcome of the destructive-operation contract.
+ *
+ * `'declined'` means the operator answered "no" — a successful run that
+ * chose not to proceed, so callers return normally and the process exits 0.
+ * An INTERRUPT (Esc / Ctrl+C) is not represented here: it throws
+ * {@link CancellationError} and exits 130. Collapsing the two would make an
+ * interrupted prompt indistinguishable from a declined one.
+ */
+export type DestructiveOpResult = 'proceed' | 'dry-run' | 'declined';
 /**
  * Inputs to {@link appendHistory}. Entries are appended as one JSON record
  * per line. Callers should only append after a mutation succeeds so
@@ -68,6 +76,21 @@ export interface HistoryEntry {
     /** Result: `'ok'` on success; other strings describe failure. */
     result: string;
 }
+/**
+ * True when BOTH standard handles are real TTYs, i.e. an interactive prompt
+ * can actually be answered.
+ *
+ * Named for the condition rather than for confirmation specifically: many
+ * call sites gate a `text()` / `multiselect()` input prompt or a mode
+ * switch, not a destructive confirmation.
+ *
+ * Node types `isTTY` as `boolean`, but at runtime it is `true | undefined`
+ * (absent when the handle is not a TTY). Unusual harnesses (vitest stdio
+ * capture, CI spawners, mocked pipes) can also leave it unset on only one
+ * handle, so every falsy variant — false, undefined, a null-patched mock —
+ * must route to the non-interactive path.
+ */
+export declare function stdioIsInteractive(): boolean;
 /**
  * UP-FRONT non-interactive refusal for a command that will end at
  * {@link confirmDestructive}.
@@ -78,8 +101,7 @@ export interface HistoryEntry {
  * --create` that is minutes of work before a scripted run learns it needed
  * `--yes`, and the failure reads as an obscure late error rather than a
  * usage problem. Calling this at command entry turns it into a usage
- * refusal that names the flag, in the same shape as the 0.41.0
- * `move-files --create` / `--description` refusal.
+ * refusal that names the flag.
  *
  * A `--yes` or `--dry-run` run never prompts, so neither is refused.
  *
@@ -95,14 +117,14 @@ export declare function assertConfirmationAvailable(operation: string, options:
  * Executes the destructive-operation contract: summary → conflict refusal →
  * dry-run / force / prompt / non-TTY refusal.
  *
- * Returns the decision for the caller to act on; callers must not execute the
- * mutation when the result is `'dry-run'` or `'cancelled'`, and must call
- * {@link appendHistory} only after the mutation succeeds (never on dry-run or
- * cancellation).
+ * Returns the decision for the caller to act on; callers must not execute
+ * the mutation when the result is `'dry-run'` or `'declined'`, and must call
+ * {@link appendHistory} only after the mutation succeeds (never on dry-run
+ * or decline).
  *
  * @param input - Operation description, flags, and optional conflict report
  * @returns `'proceed'` to execute, `'dry-run'` to skip execution, or
- *   `'cancelled'` when the user declined the prompt
+ *   `'declined'` when the user declined the prompt
  */
 export declare function confirmDestructive(input: DestructiveOpInput): Promise<DestructiveOpResult>;
 /**