@hominis/fireforge 0.45.0 → 0.46.0

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

@@ -8,12 +8,6 @@ import type { FireForgeState } from '../types/config.js';
  * @returns FireForge state
  */
 export declare function loadState(root: string): Promise<FireForgeState>;
-/**
- * Saves the fireforge state.
- * @param root - Root directory of the project
- * @param state - State to save
- */
-export declare function saveState(root: string, state: FireForgeState): Promise<void>;
 /**
  * Updates specific fields in the fireforge state.
  * @param root - Root directory of the project

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

@@ -24,13 +24,7 @@ function sanitizeProjectState(data) {
     const state = {};
     const issues = [];
     const recoveredFields = [];
-    const stringFields = [
-        'brand',
-        'buildMode',
-        'lastBuild',
-        'downloadedVersion',
-        'baseCommit',
-    ];
+    const stringFields = ['brand', 'buildMode', 'downloadedVersion', 'baseCommit'];
     for (const key of stringFields) {
         const value = data[key];
         if (value === undefined) {
@@ -132,18 +126,6 @@ export async function loadState(root) {
     const paths = getProjectPaths(root);
     return loadStateFromPath(paths.state);
 }
-/**
- * Saves the fireforge state.
- * @param root - Root directory of the project
- * @param state - State to save
- */
-export async function saveState(root, state) {
-    const paths = getProjectPaths(root);
-    const validatedState = validateFireForgeState(state);
-    await withStateFileLock(paths.state, async () => {
-        await writeJson(paths.state, validatedState);
-    });
-}
 /**
  * Updates specific fields in the fireforge state.
  * @param root - Root directory of the project

package/dist/src/core/config-validate-build-audit.d.ts

@@ -0,0 +1,8 @@
+import type { BuildAuditConfig } from '../types/config.js';
+/**
+ * Parses the `buildAudit` block.
+ *
+ * @param raw - The raw `buildAudit` value from fireforge.json
+ * @returns The validated block
+ */
+export declare function parseBuildAuditConfig(raw: unknown): BuildAuditConfig;

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

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Validation for the `buildAudit` block.
+ *
+ * Split out of `config-validate.ts`, which is at its per-file line budget,
+ * following the `config-validate-file-size.ts` precedent.
+ *
+ * The rules here are stricter than the schema strictly needs, and
+ * deliberately so: every entry is a standing suppression of a warning the
+ * audit would otherwise raise. A malformed one must fail loudly at config
+ * load rather than quietly admit nothing (leaving the operator believing a
+ * path is carved out) or quietly admit everything.
+ */
+import { ConfigError } from '../errors/config.js';
+import { isContainedRelativePath } from '../utils/paths.js';
+import { isObject } from '../utils/validation.js';
+/** Parses one `buildAudit.unpackaged[]` entry. */
+function parseUnpackagedEntry(raw, field) {
+    if (!isObject(raw)) {
+        throw new ConfigError(`Config field "${field}" must be a plain object with "path" and "reason"`);
+    }
+    for (const key of Object.keys(raw)) {
+        if (key !== 'path' && key !== 'reason') {
+            throw new ConfigError(`Config field "${field}" has unknown key "${key}"`);
+        }
+    }
+    const path = raw['path'];
+    if (typeof path !== 'string' || path.trim().length === 0) {
+        throw new ConfigError(`Config field "${field}.path" must be a non-empty string`);
+    }
+    if (!isContainedRelativePath(path)) {
+        throw new ConfigError(`Config field "${field}.path" must be an engine-relative path`);
+    }
+    if (path.includes('**')) {
+        // A `**` carve-out admits an entire subtree, which is how a reviewed
+        // exception quietly becomes a blanket one. `*` inside a single segment
+        // is enough for the shapes this exists for.
+        throw new ConfigError(`Config field "${field}.path" must not use "**" — a carve-out may glob within one path segment only`);
+    }
+    const reason = raw['reason'];
+    if (typeof reason !== 'string' || reason.trim().length === 0) {
+        // Required on purpose: this is the one audit class FireForge cannot
+        // derive from the tree, so the declaration IS the evidence.
+        throw new ConfigError(`Config field "${field}.reason" must be a non-empty string explaining why the file is never packaged`);
+    }
+    return { path, reason };
+}
+/**
+ * Parses the `buildAudit` block.
+ *
+ * @param raw - The raw `buildAudit` value from fireforge.json
+ * @returns The validated block
+ */
+export function parseBuildAuditConfig(raw) {
+    if (!isObject(raw)) {
+        throw new ConfigError('Config field "buildAudit" must be a plain object');
+    }
+    for (const key of Object.keys(raw)) {
+        if (key !== 'unpackaged') {
+            throw new ConfigError(`Config field "buildAudit" has unknown key "${key}"`);
+        }
+    }
+    const unpackaged = raw['unpackaged'];
+    if (unpackaged === undefined)
+        return {};
+    if (!Array.isArray(unpackaged)) {
+        throw new ConfigError('Config field "buildAudit.unpackaged" must be an array');
+    }
+    const entries = unpackaged.map((entry, index) => parseUnpackagedEntry(entry, `buildAudit.unpackaged[${String(index)}]`));
+    const seen = new Set();
+    for (const entry of entries) {
+        if (seen.has(entry.path)) {
+            // Two rows for one path means one of the two reasons is not the
+            // operative one, and nothing says which.
+            throw new ConfigError(`Config field "buildAudit.unpackaged" declares "${entry.path}" more than once`);
+        }
+        seen.add(entry.path);
+    }
+    return { unpackaged: entries };
+}

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

@@ -52,7 +52,7 @@ export function parsePatchLintFileSizeThresholds(raw) {
         const merged = { ...DEFAULT_FILE_SIZE_THRESHOLDS[tier], ...parsed };
         if (merged.notice > merged.warning || merged.warning > merged.error) {
             throw new ConfigError(`Config field "patchLint.fileSizeThresholds.${tier}" must satisfy notice <= warning <= error ` +
-                `(resolved: ${String(merged.notice)}/${String(merged.warning)}/${String(merged.error)})`);
+                `(resolved: ${merged.notice}/${merged.warning}/${merged.error})`);
         }
         out[tier] = parsed;
     }

package/dist/src/core/config-validate-patch-policy.d.ts

@@ -2,6 +2,6 @@
  * Validation helpers for `fireforge.json#patchPolicy`.
  */
 import type { PatchPolicyConfig } from '../types/config.js';
-import { parseObject } from '../utils/parse.js';
+import { type ParsedRecord } from '../utils/parse.js';
 /** Parses and validates the optional patch policy config block. */
-export declare function parsePatchPolicyBlock(rec: ReturnType<typeof parseObject>): PatchPolicyConfig;
+export declare function parsePatchPolicyBlock(rec: ParsedRecord): PatchPolicyConfig;

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

@@ -108,7 +108,7 @@ function parsePatchPolicyReservedRange(raw, label) {
     return {
         from,
         to,
-        allowed: allowedRaw.map((entry, index) => parseReservedAllowedPatch(entry, `${label}.allowed[${String(index)}]`)),
+        allowed: allowedRaw.map((entry, index) => parseReservedAllowedPatch(entry, `${label}.allowed[${index}]`)),
     };
 }
 function assertPolicyRangesDoNotOverlap(ranges, label) {
@@ -160,14 +160,14 @@ export function parsePatchPolicyBlock(rec) {
     if (!Array.isArray(rangesRaw) || rangesRaw.length === 0) {
         throw new ConfigError('Config field "patchPolicy.ranges" must be a non-empty array');
     }
-    out.ranges = rangesRaw.map((entry, index) => parsePatchPolicyRange(entry, `patchPolicy.ranges[${String(index)}]`));
+    out.ranges = rangesRaw.map((entry, index) => parsePatchPolicyRange(entry, `patchPolicy.ranges[${index}]`));
     assertPolicyRangesDoNotOverlap(out.ranges, 'patchPolicy.ranges');
     const reservedRangesRaw = rec.raw('reservedRanges');
     if (reservedRangesRaw !== undefined) {
         if (!Array.isArray(reservedRangesRaw)) {
             throw new ConfigError('Config field "patchPolicy.reservedRanges" must be an array');
         }
-        out.reservedRanges = reservedRangesRaw.map((entry, index) => parsePatchPolicyReservedRange(entry, `patchPolicy.reservedRanges[${String(index)}]`));
+        out.reservedRanges = reservedRangesRaw.map((entry, index) => parsePatchPolicyReservedRange(entry, `patchPolicy.reservedRanges[${index}]`));
         assertPolicyRangesDoNotOverlap(out.reservedRanges, 'patchPolicy.reservedRanges');
     }
     return out;

package/dist/src/core/config-validate-test-toolchains.d.ts

@@ -1,6 +1,6 @@
 import type { FireForgeConfig } from '../types/config.js';
-import { parseObject } from '../utils/parse.js';
-type ConfigRecord = ReturnType<typeof parseObject>;
+import type { ParsedRecord } from '../utils/parse.js';
+type ConfigRecord = ParsedRecord;
 /** Parses the optional `test` block. */
 export declare function parseTestBlock(rec: ConfigRecord, config: FireForgeConfig): void;
 /** Parses optional project-specific external toolchain doctor probes. */

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

@@ -1,6 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { ConfigError } from '../errors/config.js';
-import { parseObject } from '../utils/parse.js';
 import { isContainedRelativePath } from '../utils/paths.js';
 import { isObject } from '../utils/validation.js';
 function optionalConfigString(rec, key, label) {
@@ -58,16 +57,16 @@ export function parseExternalToolchainsBlock(rec, config) {
     }
     config.externalToolchains = raw.map((entry, index) => {
         if (!isObject(entry)) {
-            throw new ConfigError(`Config field "externalToolchains[${String(index)}]" must be an object`);
+            throw new ConfigError(`Config field "externalToolchains[${index}]" must be an object`);
         }
         const item = entry;
         const name = item['name'];
         if (typeof name !== 'string' || name.trim() === '') {
-            throw new ConfigError(`Config field "externalToolchains[${String(index)}].name" must be a non-empty string`);
+            throw new ConfigError(`Config field "externalToolchains[${index}].name" must be a non-empty string`);
         }
         const tools = item['tools'];
         if (!Array.isArray(tools) || tools.length === 0) {
-            throw new ConfigError(`Config field "externalToolchains[${String(index)}].tools" must be a non-empty array`);
+            throw new ConfigError(`Config field "externalToolchains[${index}].tools" must be a non-empty array`);
         }
         return {
             name,
@@ -76,7 +75,7 @@ export function parseExternalToolchainsBlock(rec, config) {
     });
 }
 function parseExternalToolRequirement(tool, index, toolIndex) {
-    const label = `externalToolchains[${String(index)}].tools[${String(toolIndex)}]`;
+    const label = `externalToolchains[${index}].tools[${toolIndex}]`;
     if (!isObject(tool)) {
         throw new ConfigError(`Config field "${label}" must be an object`);
     }

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

@@ -8,6 +8,7 @@ import { parseObject } from '../utils/parse.js';
 import { isContainedRelativePath, isExplicitAbsolutePath } from '../utils/paths.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 { parseBuildAuditConfig } from './config-validate-build-audit.js';
 import { parsePatchLintFileSizeThresholds } from './config-validate-file-size.js';
 import { parsePatchPolicyBlock } from './config-validate-patch-policy.js';
 import { parseExternalToolchainsBlock, parseTestBlock } from './config-validate-test-toolchains.js';
@@ -54,7 +55,8 @@ function parseIdentityFields(rec) {
 /**
  * Parses and validates the required `firefox` block: version shape,
  * product allowlist, product/version cross-compatibility, and the
- * optional sha256 digest (normalized to lowercase).
+ * optional sha256 digest (normalized to lowercase), optional
+ * `allowUnverifiedDownload` opt-out, optional candidate directory.
  */
 function parseFirefoxBlock(rec) {
     let firefoxRec;
@@ -85,6 +87,10 @@ function parseFirefoxBlock(rec) {
     if (firefoxSha256 !== undefined && !/^[a-f0-9]{64}$/i.test(firefoxSha256)) {
         throw new ConfigError('Config field "firefox.sha256" must be a 64-character SHA-256 hex digest');
     }
+    const allowUnverifiedDownload = firefoxRec.raw('allowUnverifiedDownload');
+    if (allowUnverifiedDownload !== undefined && typeof allowUnverifiedDownload !== 'boolean') {
+        throw new ConfigError('Config field "firefox.allowUnverifiedDownload" must be a boolean');
+    }
     const firefoxCandidate = optionalConfigString(firefoxRec, 'candidate', 'firefox.candidate');
     if (firefoxCandidate !== undefined && !isValidFirefoxCandidate(firefoxCandidate)) {
         throw new ConfigError('Config field "firefox.candidate" must look like "buildN" (e.g. "build2")');
@@ -93,6 +99,7 @@ function parseFirefoxBlock(rec) {
         version: firefoxVersion,
         product: firefoxProduct,
         ...(firefoxSha256 !== undefined ? { sha256: firefoxSha256.toLowerCase() } : {}),
+        ...(allowUnverifiedDownload !== undefined ? { allowUnverifiedDownload } : {}),
         ...(firefoxCandidate !== undefined ? { candidate: firefoxCandidate } : {}),
     };
 }
@@ -155,6 +162,10 @@ export function validateConfig(data) {
     const firefox = parseFirefoxBlock(rec);
     const config = { ...identity, firefox };
     parseBuildBlock(rec, config);
+    const buildAuditRaw = rec.raw('buildAudit');
+    if (buildAuditRaw !== undefined) {
+        config.buildAudit = parseBuildAuditConfig(buildAuditRaw);
+    }
     parseTestBlock(rec, config);
     parseExternalToolchainsBlock(rec, config);
     parseWireBlock(rec, config);
@@ -425,10 +436,10 @@ function parseTypecheckBlock(rec) {
     for (let i = 0; i < projectsRaw.length; i++) {
         const entry = projectsRaw[i];
         if (typeof entry !== 'string' || entry.trim() === '') {
-            throw new ConfigError(`Config field "typecheck.projects[${String(i)}]" must be a non-empty string`);
+            throw new ConfigError(`Config field "typecheck.projects[${i}]" must be a non-empty string`);
         }
         if (!isContainedRelativePath(entry)) {
-            throw new ConfigError(`Config field "typecheck.projects[${String(i)}]" must be a project-relative path`);
+            throw new ConfigError(`Config field "typecheck.projects[${i}]" must be a project-relative path`);
         }
         projects.push(entry);
     }

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

@@ -10,8 +10,8 @@
 import type { FireForgeConfig } from '../types/config.js';
 import type { JsonObject } from '../types/json.js';
 export { mutateConfig } from './config-mutate.js';
-export { CONFIG_FILENAME, FIREFORGE_DIR, getProjectPaths, STATE_FILENAME, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
-export { loadState, saveState, updateState } from './config-state.js';
+export { FIREFORGE_DIR, getProjectPaths, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
+export { loadState, updateState } from './config-state.js';
 export { validateConfig } from './config-validate.js';
 /**
  * Checks if a fireforge.json exists in the given directory.

package/dist/src/core/config.js

@@ -18,20 +18,10 @@ import { validateConfig } from './config-validate.js';
 import { createSiblingLockPath, withFileLock } from './file-lock.js';
 // ---- re-exports ----
 export { mutateConfig } from './config-mutate.js';
-export { CONFIG_FILENAME, FIREFORGE_DIR, getProjectPaths, STATE_FILENAME, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
-export { loadState, saveState, updateState } from './config-state.js';
+export { FIREFORGE_DIR, getProjectPaths, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
+export { loadState, updateState } from './config-state.js';
 export { validateConfig } from './config-validate.js';
 // ---- config I/O (stays here because it bridges paths + validation) ----
-/**
- * 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.
- */
-async function configPathExists(path) {
-    return fsUtils.pathExistsStrict(path);
-}
 /**
  * Checks if a fireforge.json exists in the given directory.
  * @param root - Root directory to check
@@ -39,7 +29,9 @@ async function configPathExists(path) {
  */
 export async function configExists(root) {
     const paths = getProjectPaths(root);
-    return configPathExists(paths.config);
+    // Strict probe: a permission error on `fireforge.json` must propagate
+    // rather than read as "no config here", which plain `pathExists` reports.
+    return fsUtils.pathExistsStrict(paths.config);
 }
 /**
  * Loads and validates the fireforge.json configuration.
@@ -49,7 +41,9 @@ export async function configExists(root) {
  */
 export async function loadConfig(root) {
     const paths = getProjectPaths(root);
-    if (!(await configPathExists(paths.config))) {
+    // Strict probe: a permission error on `fireforge.json` must propagate
+    // rather than read as "no config here", which plain `pathExists` reports.
+    if (!(await fsUtils.pathExistsStrict(paths.config))) {
         throw new ConfigNotFoundError(paths.config);
     }
     try {
@@ -81,7 +75,9 @@ export async function loadConfig(root) {
  */
 export async function loadRawConfigDocument(root) {
     const paths = getProjectPaths(root);
-    if (!(await configPathExists(paths.config))) {
+    // Strict probe: a permission error on `fireforge.json` must propagate
+    // rather than read as "no config here", which plain `pathExists` reports.
+    if (!(await fsUtils.pathExistsStrict(paths.config))) {
         throw new ConfigNotFoundError(paths.config);
     }
     try {

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

@@ -34,10 +34,10 @@
  * 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';
 import { join } from 'node:path';
 import { getNodeErrorCode, toError } from '../utils/errors.js';
+import { sha256Hex } from '../utils/hash.js';
 import { verbose } from '../utils/logger.js';
 import { DELETED_FILE_FINGERPRINT, } from './build-baseline-types.js';
 import { getHead, isMissingHeadError } from './git.js';
@@ -144,7 +144,7 @@ export function formatExtendCoverageRefusal(result) {
                 `longer anchored. ${remedy}`);
         case 'fingerprint-diverged':
             return ('--extend-coverage refused: ' +
-                `${String(result.detail.length)} packageable file(s) the recorded build staged have changed ` +
+                `${result.detail.length} packageable file(s) the recorded build staged have changed ` +
                 `since (${formatDivergedPaths(result.detail)}). Extending would vouch for the earlier scope ` +
                 `while obj-*/_tests/ still holds its stale staging. ${remedy}`);
         case 'mozconfig-changed':
@@ -156,7 +156,7 @@ export function formatExtendCoverageRefusal(result) {
 function formatDivergedPaths(paths) {
     const head = paths.slice(0, MAX_DIVERGED_REPORTED).join(', ');
     const extra = paths.length - Math.min(paths.length, MAX_DIVERGED_REPORTED);
-    return extra > 0 ? `${head}, … (+${String(extra)} more)` : head;
+    return extra > 0 ? `${head}, … (+${extra} more)` : head;
 }
 /**
  * Hex-encoded SHA-256 of an engine-relative file, matching the digest the
@@ -168,7 +168,7 @@ function formatDivergedPaths(paths) {
 export async function hashEngineFile(engineDir, relPath) {
     try {
         const buffer = await readFile(join(engineDir, relPath));
-        return createHash('sha256').update(buffer).digest('hex');
+        return sha256Hex(buffer);
     }
     catch (error) {
         if (getNodeErrorCode(error) === 'ENOENT') {

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

@@ -226,22 +226,22 @@ export function summarizeDiscardBaselines(plans, succeeded) {
     const deleted = plans.filter((p) => p.kind === 'patch-deleted').length;
     const unmanaged = plans.filter((p) => p.kind === 'unmanaged').length;
     if (patchBacked + created + deleted === 0) {
-        return `${String(succeeded)} file(s) restored to upstream state`;
+        return `${succeeded} file(s) restored to upstream state`;
     }
     const parts = [];
     if (patchBacked > 0)
-        parts.push(`${String(patchBacked)} to patch baseline`);
+        parts.push(`${patchBacked} to patch baseline`);
     if (created > 0)
-        parts.push(`${String(created)} re-materialized`);
+        parts.push(`${created} re-materialized`);
     if (deleted > 0)
-        parts.push(`${String(deleted)} removed per patch baseline`);
+        parts.push(`${deleted} removed per patch baseline`);
     if (unmanaged > 0)
-        parts.push(`${String(unmanaged)} to upstream state`);
-    return `${String(succeeded)} file(s) restored: ${parts.join(', ')}`;
+        parts.push(`${unmanaged} to upstream state`);
+    return `${succeeded} file(s) restored: ${parts.join(', ')}`;
 }
 /** Warn text for a multi-owner (conflicted) restore. */
 export function describeConflictWarning(plan) {
-    return (`${plan.entry.file} is claimed by ${String(plan.owners.length)} patches ` +
+    return (`${plan.entry.file} is claimed by ${plan.owners.length} patches ` +
         `(${plan.owners.join(', ')}). Restored the cumulative baseline; run ` +
         '"fireforge status --ownership" to resolve ownership.');
 }

package/dist/src/core/engine-precondition.d.ts

@@ -19,13 +19,6 @@ export interface EngineGitReadyOptions {
      */
     unbornHeadSuffix?: string;
 }
-/**
- * Error factory for callers whose domain uses a class other than
- * `GeneralError`. The furnace family raises `FurnaceError`, which carries
- * its own `userMessage` and exit code 9, so a helper hardcoding
- * `GeneralError` would silently change both.
- */
-export type PreconditionErrorFactory = (message: string) => Error;
 /**
  * Asserts only that the engine checkout EXISTS.
  *
@@ -36,9 +29,8 @@ export type PreconditionErrorFactory = (message: string) => Error;
  * would refuse runs that work today.
  *
  * @param engineDir - Absolute path to the engine checkout
- * @param errorFactory - Optional domain-specific error constructor
  */
-export declare function assertEngineExists(engineDir: string, errorFactory?: PreconditionErrorFactory): Promise<void>;
+export declare function assertEngineExists(engineDir: string): Promise<void>;
 /**
  * Asserts that `engineDir` exists, is a git repository, and has a baseline
  * commit — in that order, so the operator gets the most specific applicable

package/dist/src/core/engine-precondition.js

@@ -20,8 +20,6 @@ const UNBORN_HEAD_REMEDIATION = 'Engine repository has no baseline commit yet
     // No terminating period: the suffix below supplies its own punctuation, and
     // hardcoding one here rendered as "…cleanly., then retry the rebase."
     'Re-run "fireforge download --force" to recreate the baseline repository cleanly';
-/** Default factory: the message every non-furnace command already used. */
-const defaultErrorFactory = (message) => new GeneralError(message);
 /**
  * Asserts only that the engine checkout EXISTS.
  *
@@ -32,11 +30,10 @@ const defaultErrorFactory = (message) => new GeneralError(message);
  * would refuse runs that work today.
  *
  * @param engineDir - Absolute path to the engine checkout
- * @param errorFactory - Optional domain-specific error constructor
  */
-export async function assertEngineExists(engineDir, errorFactory = defaultErrorFactory) {
+export async function assertEngineExists(engineDir) {
     if (!(await pathExists(engineDir))) {
-        throw errorFactory('Firefox source not found. Run "fireforge download" first.');
+        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
     }
 }
 /**
@@ -48,9 +45,7 @@ export async function assertEngineExists(engineDir, errorFactory = defaultErrorF
  * @param options - Optional per-command message tailoring
  */
 export async function assertEngineGitReady(engineDir, options = {}) {
-    if (!(await pathExists(engineDir))) {
-        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
-    }
+    await assertEngineExists(engineDir);
     if (!(await isGitRepository(engineDir))) {
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }

package/dist/src/core/engine-session-lock.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { InconclusiveVerdictError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { info, warn } from '../utils/logger.js';
+import { sleep } from '../utils/sleep.js';
 import { readLockStatus, withFileLock } from './file-lock.js';
 import { git } from './git-base.js';
 const ENGINE_SESSION_LOCK_PATH = join('.fireforge', 'engine-session.lock');
@@ -21,19 +22,19 @@ const MAX_WAIT_LOCK_MS = 3600 * 1000;
  * owner file degrades to the anonymous form.
  */
 function formatWaitProgressLine(waitedMs, timeoutMs, holder, queue) {
-    const progress = `${String(Math.round(waitedMs / 1000))}s of up to ${String(Math.round(timeoutMs / 1000))}s`;
+    const progress = `${Math.round(waitedMs / 1000)}s of up to ${Math.round(timeoutMs / 1000)}s`;
     // Queue position: under several concurrent sessions the wait
     // line alone left operators inferring their place from `ps`.
     const position = queue === undefined || queue.depth === 0
         ? ''
         : queue.ahead === 0
-            ? ` You are next in a queue of ${String(queue.depth)}.`
-            : ` ${String(queue.ahead)} ahead of you (queue of ${String(queue.depth)}).`;
+            ? ` You are next in a queue of ${queue.depth}.`
+            : ` ${queue.ahead} ahead of you (queue of ${queue.depth}).`;
     if (holder === undefined) {
         return `Waiting for the FireForge engine lock — ${progress}.${position}`;
     }
     const details = holder.metadata.length > 0 ? ` (${holder.metadata.join(', ')})` : '';
-    return `Waiting for the FireForge engine lock held by PID ${String(holder.pid)}${details} — ${progress}.${position}`;
+    return `Waiting for the FireForge engine lock held by PID ${holder.pid}${details} — ${progress}.${position}`;
 }
 /**
  * Formats the notice printed when the wait budget is EXTENDED because the
@@ -45,10 +46,10 @@ function formatWaitProgressLine(waitedMs, timeoutMs, holder, queue) {
  * number they typed would otherwise conclude the timeout is broken.
  */
 export function formatWaitExtendedLine(ahead, budgetMs, requestedMs) {
-    const position = ahead === 0 ? 'you are now next' : `${String(ahead)} still ahead of you`;
+    const position = ahead === 0 ? 'you are now next' : `${ahead} still ahead of you`;
     return (`The queue advanced (${position}), so the engine-lock wait was extended to ` +
-        `${String(Math.round(budgetMs / 1000))}s total (you asked for ` +
-        `${String(Math.round(requestedMs / 1000))}s). A queue that stops moving still ` +
+        `${Math.round(budgetMs / 1000)}s total (you asked for ` +
+        `${Math.round(requestedMs / 1000)}s). A queue that stops moving still ` +
         `gives up on the budget you asked for.`);
 }
 /**
@@ -128,15 +129,15 @@ export function formatEngineSessionLockStatus(snapshot, holderCpuSeconds) {
     }
     const elapsed = snapshot.heldForMs === undefined
         ? 'unknown duration'
-        : `${String(Math.round(snapshot.heldForMs / 1000))}s`;
+        : `${Math.round(snapshot.heldForMs / 1000)}s`;
     const holder = snapshot.holder;
     const identity = holder === undefined
         ? 'held by an unidentified process (no readable owner record)'
-        : `held by PID ${String(holder.pid)}${holder.alive ? '' : ' (NOT RUNNING — stale lock)'}` +
+        : `held by PID ${holder.pid}${holder.alive ? '' : ' (NOT RUNNING — stale lock)'}` +
             (holder.metadata.length > 0 ? ` (${holder.metadata.join(', ')})` : '');
     const lines = [
         `Engine session lock: ${identity}, for ${elapsed}.`,
-        `Queue depth: ${String(snapshot.queueDepth)} waiter(s).`,
+        `Queue depth: ${snapshot.queueDepth} waiter(s).`,
     ];
     // Liveness answers "does the process exist"; it does not answer "is it
     // getting anywhere". A holder alive for minutes having used a fraction of
@@ -182,7 +183,7 @@ export async function snapshotEngineGeneration(engineDir) {
             // and is reported immediately.
             if (!isIndexLockError(error) || attempt === GENERATION_PROBE_ATTEMPTS - 1)
                 break;
-            await delay(GENERATION_PROBE_RETRY_MS);
+            await sleep(GENERATION_PROBE_RETRY_MS);
         }
     }
     return `${UNAVAILABLE_PREFIX}${toError(lastError).message}`;
@@ -191,11 +192,6 @@ export async function snapshotEngineGeneration(engineDir) {
 const GENERATION_PROBE_ATTEMPTS = 3;
 /** Pause between generation-probe attempts. */
 const GENERATION_PROBE_RETRY_MS = 250;
-function delay(ms) {
-    return new Promise((resolveDelay) => {
-        setTimeout(resolveDelay, ms);
-    });
-}
 /**
  * True when a git failure is the transient index-lock contention shape
  * (`Unable to create '…/.git/index.lock': File exists`) rather than a
@@ -290,7 +286,7 @@ export function describeEngineGenerationDelta(before, after) {
             return;
         const head = records.slice(0, DELTA_ENTRY_LIMIT);
         const truncated = records.length - head.length;
-        lines.push(`${label}: ${head.join(', ')}${truncated > 0 ? `, … (+${String(truncated)} more)` : ''}`);
+        lines.push(`${label}: ${head.join(', ')}${truncated > 0 ? `, … (+${truncated} more)` : ''}`);
     };
     render('Working-tree entries that appeared', appeared);
     render('Working-tree entries that went away', disappeared);

package/dist/src/core/export-moved-code-shape.js

@@ -114,14 +114,14 @@ export function formatAdoptThenSplitRemedy(overlaps, newPatchName, insertionOrde
     const suggestedName = newPatchName.replace(/^\d+-/, '').replace(/\.patch$/, '');
     return [
         '',
-        `This looks like a new-file + moved-code slice: ${String(strongest.sharedLines)} substantive ` +
+        `This looks like a new-file + moved-code slice: ${strongest.sharedLines} substantive ` +
             `line(s) the new file(s) would add are still carried by ${strongest.sourcePatch}. ` +
             'Exporting them as their own patch cannot pass cross-patch lint while the source patch ' +
             'still owns the same code, and re-exporting cannot adopt them while they are unmanaged — ' +
             'each guard is right, and together they dead-end.',
         'Working sequence (adopt, then split):',
         `  1. fireforge re-export ${strongest.sourcePatch} --scan ${fileArgs}`,
-        `  2. fireforge patch move-files ${strongest.sourcePatch} ${suggestedName} --create --order ${String(insertionOrder)} ${moveArgs}`,
+        `  2. fireforge patch move-files ${strongest.sourcePatch} ${suggestedName} --create --order ${insertionOrder} ${moveArgs}`,
         'Step 1 adopts the new files into the patch that already owns the moved lines; step 2 ' +
             'splits them back out as one transaction, so the queue is never in a state where two ' +
             'patches own the same code.',