@hominis/fireforge 0.45.0 → 0.46.0

package/dist/src/core/wire-dom-fragment.js

@@ -12,6 +12,7 @@ import { dirname, join, relative } from 'node:path';
 import { GeneralError } from '../errors/base.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { toRootRelativePath } from '../utils/paths.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { escapeRegex } from '../utils/regex.js';
 import { tokenizeXhtml } from './wire-utils.js';
 export const DEFAULT_DOM_TARGET = 'browser/base/content/browser.xhtml';
@@ -22,23 +23,11 @@ export function addDomFragmentTokenized(content, includeDirective) {
     const lines = content.split('\n');
     const tokens = tokenizeXhtml(lines);
     // Find the #include browser-sets.inc token
-    let insertIndex = -1;
-    for (let i = 0; i < tokens.length; i++) {
-        const token = tokens[i];
-        if (token && token.type === 'macro' && token.raw.includes('browser-sets.inc')) {
-            insertIndex = i;
-            break;
-        }
-    }
+    let insertIndex = tokens.findIndex((token) => token.type === 'macro' && token.raw.includes('browser-sets.inc'));
     if (insertIndex === -1) {
         // Fallback: after <html:body>
-        for (let i = 0; i < tokens.length; i++) {
-            const token = tokens[i];
-            if (token && token.type === 'xml' && /<html:body/.test(token.raw)) {
-                insertIndex = i + 1;
-                break;
-            }
-        }
+        const bodyIndex = tokens.findIndex((token) => token.type === 'xml' && /<html:body/.test(token.raw));
+        insertIndex = bodyIndex === -1 ? -1 : bodyIndex + 1;
     }
     if (insertIndex === -1) {
         throw new GeneralError('Could not find insertion point in chrome document');
@@ -69,7 +58,7 @@ export async function probeDomFragmentInsertionPoint(engineDir, domFilePath, tar
     }
     const safeDomFilePath = toRootRelativePath(engineDir, domFilePath);
     const targetDir = dirname(targetPath);
-    const includePath = relative(targetDir, safeDomFilePath).replace(/\\/g, '/');
+    const includePath = normalizePathSlashes(relative(targetDir, safeDomFilePath));
     const includeDirective = `#include ${includePath}`;
     const content = await readText(targetAbsPath);
     if (new RegExp(`^${escapeRegex(includeDirective)}$`, 'm').test(content)) {
@@ -109,7 +98,7 @@ export async function addDomFragment(engineDir, domFilePath, targetPath = DEFAUL
     // contains it, so this must track the chrome doc's location, not a
     // hardcoded `browser/base/content/`.
     const targetDir = dirname(targetPath);
-    const includePath = relative(targetDir, safeDomFilePath).replace(/\\/g, '/');
+    const includePath = normalizePathSlashes(relative(targetDir, safeDomFilePath));
     const includeDirective = `#include ${includePath}`;
     let content = await readText(targetAbsPath);
     // Idempotency: check if the #include directive already exists (line-anchored to avoid substring matches)

package/dist/src/core/wire-utils.js

@@ -160,7 +160,7 @@ export function tokenizeXhtml(lines) {
 }
 // ---------------------------------------------------------------------------
 // Legacy (line-based) helpers — shared by fallback implementations in
-// wire-targets.ts.  Extracted to reduce duplication and make the brace-
+// the wire target modules.  Extracted to reduce duplication and make the brace-
 // walking logic independently testable.
 // ---------------------------------------------------------------------------
 /**
@@ -179,24 +179,12 @@ export function tokenizeXhtml(lines) {
  *   found (or, under `requireBrace`, no brace follows the signature).
  */
 export function findMethodBraceIndex(lines, pattern, options) {
-    let methodLine = -1;
-    for (let i = 0; i < lines.length; i++) {
-        if (pattern.test(lines[i] ?? '')) {
-            methodLine = i;
-            break;
-        }
-    }
+    const methodLine = lines.findIndex((line) => pattern.test(line));
     if (methodLine === -1)
         return null;
-    let braceIndex = methodLine;
-    let braceFound = false;
-    for (let i = methodLine; i < lines.length; i++) {
-        if (lines[i]?.includes('{')) {
-            braceIndex = i;
-            braceFound = true;
-            break;
-        }
-    }
+    const braceOffset = lines.slice(methodLine).findIndex((line) => line.includes('{'));
+    const braceFound = braceOffset !== -1;
+    const braceIndex = braceFound ? methodLine + braceOffset : methodLine;
     if (!braceFound && options?.requireBrace) {
         return null;
     }

package/dist/src/core/xpcshell-appdir.js

@@ -64,8 +64,7 @@ export function parseAppdirFromToml(tomlText, key) {
     // comment further along the file is not mistaken for the directive.
     const escapedKey = escapeRegex(key);
     const keyPattern = new RegExp('^\\s*' + escapedKey + '\\s*=\\s*(.+?)\\s*(?:[#;].*)?$');
-    for (let i = 0; i < lines.length; i += 1) {
-        const line = lines[i] ?? '';
+    for (const [i, line] of lines.entries()) {
         const sectionMatch = /^\s*\[([^\]]+)\]\s*$/.exec(line);
         if (sectionMatch) {
             sectionSeen = true;
@@ -290,8 +289,7 @@ export async function resolveXpcshellAppdirArg(engineDir, testPaths, objDirName)
  * wins.
  */
 export function operatorAlreadySetAppPath(extraArgs) {
-    for (let i = 0; i < extraArgs.length; i += 1) {
-        const arg = extraArgs[i] ?? '';
+    for (const [i, arg] of extraArgs.entries()) {
         if (arg === '--app-path' && i + 1 < extraArgs.length)
             return true;
         if (arg.startsWith('--app-path='))

package/dist/src/errors/base.d.ts

@@ -19,12 +19,45 @@ export declare abstract class FireForgeError extends Error {
      */
     get userMessage(): string;
 }
+/**
+ * Renders the trailing "To fix this:" block shared by every FireForge error
+ * that offers remedies.
+ *
+ * Numbering is derived from the array rather than written into each string.
+ * Several classes vary their advice by context (`FurnaceError` drops the
+ * validate step, `ChecksumMismatchError` adds a Developer Edition note), and
+ * hand-numbered branches had to renumber every later step by hand — one
+ * conditional away from printing "2." twice.
+ *
+ * @param steps - The remedy lines, in order, without their numbers
+ * @returns The block, starting with the blank-line separator
+ */
+export declare function remedies(steps: readonly string[]): string;
 /**
  * General error for unexpected failures.
  */
 export declare class GeneralError extends FireForgeError {
     readonly code: 1;
 }
+/**
+ * A `fireforge test` preflight gate that refused before any harness ran.
+ *
+ * Exists to carry a `note`, not to change behaviour: it keeps
+ * {@link ExitCode.GENERAL_ERROR}, so `docs/exit-codes.md` and every CI
+ * consumer keying on the exit status are untouched. The note is a stable
+ * kebab-case refusal class that the `FIREFORGE-VERDICT:` line reports as an
+ * additive `note=` key. Without it every preflight refusal reached an
+ * unattended reader as the single token `reason=preflight`, which covers
+ * everything from a missing build to a peer's packaging record — so the one
+ * line that survives a truncating pipe could not say WHICH gate fired.
+ */
+export declare class PreflightRefusalError extends GeneralError {
+    /** Stable refusal class, e.g. `stale-browser`. */
+    readonly note: string;
+    constructor(message: string, 
+    /** Stable refusal class, e.g. `stale-browser`. */
+    note: string);
+}
 /**
  * Raised when one of FireForge's own internal invariants did not hold —
  * the failure of a runtime assertion from `src/utils/assert.ts`.
@@ -92,14 +125,33 @@ export declare class ExecTimeoutError extends FireForgeError {
     /** Timeout that elapsed, in milliseconds. */
     readonly timeoutMs: number;
     readonly code: 1;
+    /** Standard output captured before the deadline fired (empty when the exec path does not capture). */
+    readonly stdout: string;
+    /** Standard error captured before the deadline fired (empty when the exec path does not capture). */
+    readonly stderr: string;
+    /** True when either captured stream was cut off at the exec layer's collector cap. */
+    readonly outputTruncated: boolean;
     constructor(
     /** Executable that was spawned (argv[0]). */
     command: string, 
     /** Arguments the executable was spawned with. */
     args: readonly string[], 
     /** Timeout that elapsed, in milliseconds. */
-    timeoutMs: number, cause?: unknown);
+    timeoutMs: number, cause?: unknown, output?: ExecTimeoutOutput);
     get userMessage(): string;
+    /**
+     * The last few lines the command printed before it was killed, so an
+     * operator can see what it was doing (a `git add -A` stuck on one path,
+     * a build step that hung) instead of a bare budget number. Prefers
+     * stderr; falls back to stdout when stderr is silent.
+     */
+    private outputTailForUser;
+}
+/** Output captured before an exec timeout fired; see {@link ExecTimeoutError}. */
+export interface ExecTimeoutOutput {
+    stdout: string;
+    stderr: string;
+    truncated: boolean;
 }
 /**
  * Error thrown when a file-lock wait times out because another process holds

package/dist/src/errors/base.js

@@ -17,10 +17,11 @@ export class FireForgeError extends Error {
         if (cause !== undefined) {
             this.cause = cause;
         }
-        // Maintains proper stack trace in V8 environments
-        if (typeof Error.captureStackTrace === 'function') {
-            Error.captureStackTrace(this, this.constructor);
-        }
+        // Trims the constructor frames off the stack. `engines` pins Node >= 22,
+        // so the V8-only `captureStackTrace` is always present — the former
+        // `typeof === 'function'` guard was an unreachable branch that coverage
+        // could never close.
+        Error.captureStackTrace(this, this.constructor);
     }
     /**
      * User-friendly error message with context and suggested fixes.
@@ -30,12 +31,49 @@ export class FireForgeError extends Error {
         return this.message;
     }
 }
+/**
+ * Renders the trailing "To fix this:" block shared by every FireForge error
+ * that offers remedies.
+ *
+ * Numbering is derived from the array rather than written into each string.
+ * Several classes vary their advice by context (`FurnaceError` drops the
+ * validate step, `ChecksumMismatchError` adds a Developer Edition note), and
+ * hand-numbered branches had to renumber every later step by hand — one
+ * conditional away from printing "2." twice.
+ *
+ * @param steps - The remedy lines, in order, without their numbers
+ * @returns The block, starting with the blank-line separator
+ */
+export function remedies(steps) {
+    return `\n\nTo fix this:\n${steps.map((step, index) => `  ${index + 1}. ${step}`).join('\n')}`;
+}
 /**
  * General error for unexpected failures.
  */
 export class GeneralError extends FireForgeError {
     code = ExitCode.GENERAL_ERROR;
 }
+/**
+ * A `fireforge test` preflight gate that refused before any harness ran.
+ *
+ * Exists to carry a `note`, not to change behaviour: it keeps
+ * {@link ExitCode.GENERAL_ERROR}, so `docs/exit-codes.md` and every CI
+ * consumer keying on the exit status are untouched. The note is a stable
+ * kebab-case refusal class that the `FIREFORGE-VERDICT:` line reports as an
+ * additive `note=` key. Without it every preflight refusal reached an
+ * unattended reader as the single token `reason=preflight`, which covers
+ * everything from a missing build to a peer's packaging record — so the one
+ * line that survives a truncating pipe could not say WHICH gate fired.
+ */
+export class PreflightRefusalError extends GeneralError {
+    note;
+    constructor(message, 
+    /** Stable refusal class, e.g. `stale-browser`. */
+    note) {
+        super(message);
+        this.note = note;
+    }
+}
 /**
  * Raised when one of FireForge's own internal invariants did not hold —
  * the failure of a runtime assertion from `src/utils/assert.ts`.
@@ -102,11 +140,9 @@ export class InvalidArgumentError extends FireForgeError {
         this.argument = argument;
     }
     get userMessage() {
-        let msg = `Invalid Argument: ${this.message}`;
-        if (this.argument) {
-            msg += `\n\nArgument: ${this.argument}`;
-        }
-        return msg;
+        return this.argument
+            ? `Invalid Argument: ${this.message}\n\nArgument: ${this.argument}`
+            : `Invalid Argument: ${this.message}`;
     }
 }
 /**
@@ -123,24 +159,56 @@ export class ExecTimeoutError extends FireForgeError {
     args;
     timeoutMs;
     code = ExitCode.GENERAL_ERROR;
+    /** Standard output captured before the deadline fired (empty when the exec path does not capture). */
+    stdout;
+    /** Standard error captured before the deadline fired (empty when the exec path does not capture). */
+    stderr;
+    /** True when either captured stream was cut off at the exec layer's collector cap. */
+    outputTruncated;
     constructor(
     /** Executable that was spawned (argv[0]). */
     command, 
     /** Arguments the executable was spawned with. */
     args, 
     /** Timeout that elapsed, in milliseconds. */
-    timeoutMs, cause) {
+    timeoutMs, cause, output) {
         super(`Command timed out after ${Math.round(timeoutMs / 1000)}s: ${[command, ...args].join(' ')}`, cause);
         this.command = command;
         this.args = args;
         this.timeoutMs = timeoutMs;
+        this.stdout = output?.stdout ?? '';
+        this.stderr = output?.stderr ?? '';
+        this.outputTruncated = output?.truncated ?? false;
     }
     get userMessage() {
         return (`${this.message}\n\n` +
             'The command was killed because it exceeded its time budget, not because it failed on its own. ' +
-            'If the host is just slow or loaded, re-running may succeed.');
+            'If the host is just slow or loaded, re-running may succeed.' +
+            this.outputTailForUser());
+    }
+    /**
+     * The last few lines the command printed before it was killed, so an
+     * operator can see what it was doing (a `git add -A` stuck on one path,
+     * a build step that hung) instead of a bare budget number. Prefers
+     * stderr; falls back to stdout when stderr is silent.
+     */
+    outputTailForUser() {
+        const source = this.stderr.trim().length > 0 ? this.stderr : this.stdout;
+        const lines = source
+            .trimEnd()
+            .split(/\r?\n/)
+            .filter((line) => line.length > 0);
+        if (lines.length === 0)
+            return '';
+        const tail = lines.slice(-EXEC_TIMEOUT_TAIL_LINES);
+        const label = this.stderr.trim().length > 0 ? 'stderr' : 'stdout';
+        const omitted = lines.length > tail.length ? ` (last ${tail.length} of ${lines.length} lines)` : '';
+        const truncatedNote = this.outputTruncated ? ' [captured output was truncated]' : '';
+        return `\n\nOutput before the timeout (${label}${omitted})${truncatedNote}:\n${tail.map((line) => `  ${line}`).join('\n')}`;
     }
 }
+/** How many trailing output lines {@link ExecTimeoutError.userMessage} shows. */
+const EXEC_TIMEOUT_TAIL_LINES = 20;
 /**
  * Error thrown when a file-lock wait times out because another process holds
  * the lock.

package/dist/src/errors/build.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { FireForgeError } from './base.js';
+import { FireForgeError, remedies } from './base.js';
 import { ExitCode } from './codes.js';
 /**
  * Error thrown when a build operation fails.
@@ -12,15 +12,13 @@ export class BuildError extends FireForgeError {
         this.command = command;
     }
     get userMessage() {
-        let msg = `Build Error: ${this.message}`;
-        if (this.command) {
-            msg += `\n\nCommand: ${this.command}`;
-        }
-        msg += '\n\nTo fix this:\n';
-        msg += '  1. Check the build output above for specific errors\n';
-        msg += '  2. Ensure all dependencies are installed with "fireforge bootstrap"\n';
-        msg += '  3. Try a clean build by deleting obj-* directories';
-        return msg;
+        return (`Build Error: ${this.message}` +
+            (this.command ? `\n\nCommand: ${this.command}` : '') +
+            remedies([
+                'Check the build output above for specific errors',
+                'Ensure all dependencies are installed with "fireforge bootstrap"',
+                'Try a clean build by deleting obj-* directories',
+            ]));
     }
 }
 /**
@@ -52,24 +50,18 @@ export class TestFailureError extends BuildError {
         this.logPath = logPath;
     }
     get userMessage() {
-        let msg = `Test Failure: ${this.message}`;
-        if (this.command) {
-            msg += `\n\nCommand: ${this.command}`;
-        }
-        if (this.failureBlocks) {
-            msg += `\n\n${this.failureBlocks}`;
-        }
-        msg += '\n\nTo fix this:\n';
-        msg += this.failureBlocks
-            ? '  1. Fix the failing assertions listed above, then re-run just those test paths\n'
-            : '  1. Find the TEST-UNEXPECTED-FAIL lines in the output above — they name what broke\n';
-        msg +=
-            '  2. Read the "FIREFORGE-VERDICT:" line for the run\'s ground truth (checks, unexpected)\n';
-        msg +=
-            this.logPath !== undefined
-                ? `  3. The complete raw output is at ${this.logPath} — it survives a piped/tailed terminal`
-                : '  3. Re-run without piping the output, so the failure lines are not cut off by "tail"';
-        return msg;
+        return (`Test Failure: ${this.message}` +
+            (this.command ? `\n\nCommand: ${this.command}` : '') +
+            (this.failureBlocks ? `\n\n${this.failureBlocks}` : '') +
+            remedies([
+                this.failureBlocks
+                    ? 'Fix the failing assertions listed above, then re-run just those test paths'
+                    : 'Find the TEST-UNEXPECTED-FAIL lines in the output above — they name what broke',
+                'Read the "FIREFORGE-VERDICT:" line for the run\'s ground truth (checks, unexpected)',
+                this.logPath !== undefined
+                    ? `The complete raw output is at ${this.logPath} — it survives a piped/tailed terminal`
+                    : 'Re-run without piping the output, so the failure lines are not cut off by "tail"',
+            ]));
     }
 }
 /**

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

@@ -15,17 +15,3 @@ export declare class ConfigNotFoundError extends ConfigError {
     constructor(configPath: string);
     get userMessage(): string;
 }
-/**
- * Error thrown when a required field is missing from config.
- */
-export declare class MissingFieldError extends ConfigError {
-    constructor(field: string);
-}
-/**
- * Error thrown when a field has an invalid value.
- */
-export declare class InvalidFieldError extends ConfigError {
-    readonly expectedType: string;
-    readonly actualValue: unknown;
-    constructor(field: string, expectedType: string, actualValue: unknown);
-}

package/dist/src/errors/config.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { FireForgeError } from './base.js';
+import { FireForgeError, remedies } from './base.js';
 import { ExitCode } from './codes.js';
 /**
  * Error thrown when configuration is missing or invalid.
@@ -12,15 +12,13 @@ export class ConfigError extends FireForgeError {
         this.field = field;
     }
     get userMessage() {
-        let msg = `Configuration Error: ${this.message}`;
-        if (this.field) {
-            msg += `\n\nField: ${this.field}`;
-        }
-        msg += '\n\nTo fix this:\n';
-        msg += '  1. Check your fireforge.json file for errors\n';
-        msg += '  2. Run "fireforge setup" to create a new configuration\n';
-        msg += '  3. See the documentation for the expected format';
-        return msg;
+        return (`Configuration Error: ${this.message}` +
+            (this.field ? `\n\nField: ${this.field}` : '') +
+            remedies([
+                'Check your fireforge.json file for errors',
+                'Run "fireforge setup" to create a new configuration',
+                'See the documentation for the expected format',
+            ]));
     }
 }
 /**
@@ -32,29 +30,10 @@ export class ConfigNotFoundError extends ConfigError {
     }
     get userMessage() {
         return (`Configuration Error: ${this.message}\n\n` +
-            'This directory does not appear to be a FireForge project.\n\n' +
-            'To fix this:\n' +
-            '  1. Navigate to your project root directory\n' +
-            '  2. Run "fireforge setup" to initialize a new project');
-    }
-}
-/**
- * Error thrown when a required field is missing from config.
- */
-export class MissingFieldError extends ConfigError {
-    constructor(field) {
-        super(`Required field "${field}" is missing from fireforge.json`, field);
-    }
-}
-/**
- * Error thrown when a field has an invalid value.
- */
-export class InvalidFieldError extends ConfigError {
-    expectedType;
-    actualValue;
-    constructor(field, expectedType, actualValue) {
-        super(`Field "${field}" has invalid value. Expected ${expectedType}, got ${typeof actualValue}`, field);
-        this.expectedType = expectedType;
-        this.actualValue = actualValue;
+            'This directory does not appear to be a FireForge project.' +
+            remedies([
+                'Navigate to your project root directory',
+                'Run "fireforge setup" to initialize a new project',
+            ]));
     }
 }

package/dist/src/errors/download.d.ts

@@ -19,6 +19,19 @@ export declare class ChecksumMismatchError extends DownloadError {
     constructor(product: FirefoxProduct, expectedSha256: string, actualSha256: string, url: string);
     get userMessage(): string;
 }
+/**
+ * Error thrown when the default integrity check cannot obtain Mozilla's
+ * published SHA-256 for a freshly downloaded archive (checksum file
+ * unreachable, malformed, or not listing the archive) and no operator pin
+ * or explicit opt-out allows the download to be trusted on TLS alone.
+ */
+export declare class ChecksumUnavailableError extends DownloadError {
+    readonly product: FirefoxProduct;
+    readonly checksumsUrl: string;
+    readonly reason: string;
+    constructor(product: FirefoxProduct, checksumsUrl: string, reason: string, url: string);
+    get userMessage(): string;
+}
 /**
  * Error thrown when extraction of the downloaded archive fails.
  */

package/dist/src/errors/download.js

@@ -1,4 +1,4 @@
-import { FireForgeError } from './base.js';
+import { FireForgeError, remedies } from './base.js';
 import { ExitCode } from './codes.js';
 /**
  * Error thrown when Firefox source download fails.
@@ -11,15 +11,13 @@ export class DownloadError extends FireForgeError {
         this.url = url;
     }
     get userMessage() {
-        let msg = `Download Error: ${this.message}`;
-        if (this.url) {
-            msg += `\n\nURL: ${this.url}`;
-        }
-        msg += '\n\nTo fix this:\n';
-        msg += '  1. Check your internet connection\n';
-        msg += '  2. Verify the Firefox version in fireforge.json is valid\n';
-        msg += '  3. Try again with "fireforge download --force"';
-        return msg;
+        return (`Download Error: ${this.message}` +
+            (this.url ? `\n\nURL: ${this.url}` : '') +
+            remedies([
+                'Check your internet connection',
+                'Verify the Firefox version in fireforge.json is valid',
+                'Try again with "fireforge download --force"',
+            ]));
     }
 }
 /**
@@ -36,23 +34,54 @@ export class ChecksumMismatchError extends DownloadError {
         this.actualSha256 = actualSha256;
     }
     get userMessage() {
-        let msg = `Download Error: Firefox source archive checksum mismatch.\n\n` +
+        return (`Download Error: Firefox source archive checksum mismatch.\n\n` +
             `Product: ${this.product}\n` +
             `URL: ${this.url}\n` +
             `Expected SHA-256: ${this.expectedSha256}\n` +
-            `Actual SHA-256: ${this.actualSha256}`;
-        msg += '\n\nTo fix this:\n';
-        msg += '  1. Verify firefox.product, firefox.version, and firefox.sha256 in fireforge.json\n';
-        msg += '  2. Compare the pinned hash with Mozilla SHA256SUMMARY for the resolved archive\n';
-        if (this.product === 'firefox-devedition') {
-            msg +=
-                '  3. Developer Edition archives should resolve under https://archive.mozilla.org/pub/devedition/releases/\n';
-            msg += '  4. Re-run "fireforge download --force" after correcting the source settings';
-        }
-        else {
-            msg += '  3. Re-run "fireforge download --force" after correcting the source settings';
-        }
-        return msg;
+            `Actual SHA-256: ${this.actualSha256}` +
+            remedies([
+                'Verify firefox.product, firefox.version, and firefox.sha256 in fireforge.json',
+                'Compare the pinned hash with Mozilla SHA256SUMMARY for the resolved archive',
+                ...(this.product === 'firefox-devedition'
+                    ? [
+                        'Developer Edition archives should resolve under https://archive.mozilla.org/pub/devedition/releases/',
+                    ]
+                    : []),
+                'Re-run "fireforge download --force" after correcting the source settings',
+            ]));
+    }
+}
+/**
+ * Error thrown when the default integrity check cannot obtain Mozilla's
+ * published SHA-256 for a freshly downloaded archive (checksum file
+ * unreachable, malformed, or not listing the archive) and no operator pin
+ * or explicit opt-out allows the download to be trusted on TLS alone.
+ */
+export class ChecksumUnavailableError extends DownloadError {
+    product;
+    checksumsUrl;
+    reason;
+    constructor(product, checksumsUrl, reason, url) {
+        super(`Could not verify archive against published SHA256SUMS: ${reason}`, url);
+        this.product = product;
+        this.checksumsUrl = checksumsUrl;
+        this.reason = reason;
+    }
+    get userMessage() {
+        return (`Download Error: Firefox source archive integrity could not be verified.\n\n` +
+            `Product: ${this.product}\n` +
+            `Archive: ${this.url ?? ''}\n` +
+            `Checksums: ${this.checksumsUrl}\n` +
+            `Reason: ${this.reason}\n\n` +
+            'The archive was downloaded but discarded: without the published digest it would be ' +
+            'trusted on TLS alone, and it becomes the git baseline every patch is built on.\n\n' +
+            'To fix this:\n' +
+            '  1. Check connectivity to archive.mozilla.org (a captive portal or proxy may be ' +
+            'answering the SHA256SUMS request) and retry\n' +
+            '  2. Or pin the archive digest: set firefox.sha256 in fireforge.json ' +
+            '(from the release SHA256SUMS, obtained out of band)\n' +
+            '  3. Or, for an offline mirror you trust, set firefox.allowUnverifiedDownload: true ' +
+            'in fireforge.json to accept the download with a warning');
     }
 }
 /**

package/dist/src/errors/furnace.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { FireForgeError } from './base.js';
+import { FireForgeError, remedies } from './base.js';
 import { ExitCode } from './codes.js';
 /**
  * Error thrown when a furnace component operation fails.
@@ -15,15 +15,14 @@ export class FurnaceError extends FireForgeError {
     }
     omitValidateAdvice;
     get userMessage() {
-        let msg = this.component
+        const head = this.component
             ? `Furnace Error (${this.component}): ${this.message}`
             : `Furnace Error: ${this.message}`;
-        msg += '\n\nTo fix this:\n';
-        msg += '  1. Check the error message above for specifics\n';
-        if (!this.omitValidateAdvice) {
-            msg += '  2. Run "fireforge furnace validate" to diagnose issues\n';
-        }
-        msg += `  ${this.omitValidateAdvice ? '2' : '3'}. Use "fireforge doctor --repair-furnace" if state is inconsistent`;
-        return msg;
+        return (head +
+            remedies([
+                'Check the error message above for specifics',
+                ...(this.omitValidateAdvice ? [] : ['Run "fireforge furnace validate" to diagnose issues']),
+                'Use "fireforge doctor --repair-furnace" if state is inconsistent',
+            ]));
     }
 }