@hominis/fireforge 0.44.4 → 0.46.0

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,56 @@ 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',
+            ]));
+    }
+}
+/**
+ * A test SUITE went red — assertions failed, or sharded runs did not all
+ * pass. Distinct from its {@link BuildError} parent only in what it TELLS
+ * the operator, deliberately not in its exit code: `docs/exit-codes.md`
+ * documents 5 as "a suite that FAILED", and consumers key CI on it.
+ *
+ * The parent's remedies are all build remedies — "check the build output",
+ * "fireforge bootstrap", "delete obj-* directories" — and none of them apply
+ * to a failing assertion. Worse, the first points at the wrong half of the
+ * log, which is exactly the half a `tail` keeps. Ground truth for a test red
+ * is the harness's own output, so the remedies here name the failing tests,
+ * the `FIREFORGE-VERDICT:` line, and the run log that survives a pipe.
+ *
+ * Note that `machineErrorCode` derives the `--json` error code from the class
+ * name, so this reports as `test-failure` rather than `build`.
+ */
+export class TestFailureError extends BuildError {
+    failureBlocks;
+    logPath;
+    constructor(message, command, 
+    /** Rendered TEST-UNEXPECTED blocks, when the verdict carried any. */
+    failureBlocks, 
+    /** The run's complete raw log, when one was opened. */
+    logPath) {
+        super(message, command);
+        this.failureBlocks = failureBlocks;
+        this.logPath = logPath;
+    }
+    get userMessage() {
+        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',
+            ]));
     }
 }

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

@@ -1,17 +1,24 @@
 import { FireForgeError } from './base.js';
+import { ExitCode } from './codes.js';
 /**
  * Error thrown when a git operation fails.
  */
 export declare class GitError extends FireForgeError {
     readonly command?: string | undefined;
-    readonly code: 4;
+    readonly code: ExitCode;
     constructor(message: string, command?: string | undefined, cause?: Error);
     get userMessage(): string;
 }
 /**
  * Error thrown when git is not installed.
+ *
+ * MISSING_DEPENDENCY, not GIT_ERROR: the fact is "a required tool is
+ * absent", the same fact `PythonNotFoundError` and `MachNotFoundError`
+ * report, and a consumer should install something rather than inspect a
+ * repository.
  */
 export declare class GitNotFoundError extends GitError {
+    readonly code: 7;
     constructor();
     get userMessage(): string;
 }
@@ -23,13 +30,6 @@ export declare class PatchApplyError extends GitError {
     constructor(patchPath: string, cause?: Error);
     get userMessage(): string;
 }
-/**
- * Error thrown when the repository is in a dirty state.
- */
-export declare class DirtyRepositoryError extends GitError {
-    constructor();
-    get userMessage(): string;
-}
 /**
  * Error thrown when a stale git index lock blocks repository initialization.
  */

package/dist/src/errors/git.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 git operation fails.
@@ -12,21 +12,25 @@ export class GitError extends FireForgeError {
         this.command = command;
     }
     get userMessage() {
-        let msg = `Git Error: ${this.message}`;
-        if (this.command) {
-            msg += `\n\nCommand: git ${this.command}`;
-        }
-        msg += '\n\nTo fix this:\n';
-        msg += '  1. Ensure git is installed and in your PATH\n';
-        msg += '  2. Check if the repository is in a valid state\n';
-        msg += '  3. Try running "fireforge reset" to start fresh';
-        return msg;
+        return (`Git Error: ${this.message}` +
+            (this.command ? `\n\nCommand: git ${this.command}` : '') +
+            remedies([
+                'Ensure git is installed and in your PATH',
+                'Check if the repository is in a valid state',
+                'Try running "fireforge reset" to start fresh',
+            ]));
     }
 }
 /**
  * Error thrown when git is not installed.
+ *
+ * MISSING_DEPENDENCY, not GIT_ERROR: the fact is "a required tool is
+ * absent", the same fact `PythonNotFoundError` and `MachNotFoundError`
+ * report, and a consumer should install something rather than inspect a
+ * repository.
  */
 export class GitNotFoundError extends GitError {
+    code = ExitCode.MISSING_DEPENDENCY;
     constructor() {
         super('Git is not installed or not found in PATH');
     }
@@ -50,26 +54,12 @@ export class PatchApplyError extends GitError {
     get userMessage() {
         return (`Git Error: Failed to apply patch.\n\n` +
             `Patch: ${this.patchPath}\n\n` +
-            'This usually means the patch conflicts with existing changes.\n\n' +
-            'To fix this:\n' +
-            '  1. Check if the Firefox version matches the patch\n' +
-            '  2. Use "fireforge reset" to start with clean source\n' +
-            '  3. Update the patch to match the current Firefox version');
-    }
-}
-/**
- * Error thrown when the repository is in a dirty state.
- */
-export class DirtyRepositoryError extends GitError {
-    constructor() {
-        super('Repository has uncommitted changes');
-    }
-    get userMessage() {
-        return ('Git Error: The Firefox source has uncommitted changes.\n\n' +
-            'To fix this:\n' +
-            '  1. Export your changes with "fireforge export"\n' +
-            '  2. Use "fireforge reset" to restore clean state\n' +
-            '  3. Then run "fireforge import" to reapply patches');
+            'This usually means the patch conflicts with existing changes.' +
+            remedies([
+                'Check if the Firefox version matches the patch',
+                'Use "fireforge reset" to start with clean source',
+                'Update the patch to match the current Firefox version',
+            ]));
     }
 }
 /**

package/dist/src/errors/patch.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 `patches.json` exists but cannot be parsed or validated.
@@ -41,14 +41,12 @@ export class PatchError extends FireForgeError {
         this.patchName = patchName;
     }
     get userMessage() {
-        let msg = `Patch Error: ${this.message}`;
-        if (this.patchName) {
-            msg += `\n\nPatch: ${this.patchName}`;
-        }
-        msg += '\n\nTo fix this:\n';
-        msg += '  1. Check if the patch is compatible with the Firefox version\n';
-        msg += '  2. Use "fireforge reset" to start with clean source\n';
-        msg += '  3. Update the patch for the current Firefox version';
-        return msg;
+        return (`Patch Error: ${this.message}` +
+            (this.patchName ? `\n\nPatch: ${this.patchName}` : '') +
+            remedies([
+                'Check if the patch is compatible with the Firefox version',
+                'Use "fireforge reset" to start with clean source',
+                'Update the patch for the current Firefox version',
+            ]));
     }
 }

package/dist/src/errors/rebase.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';
 /**
  * Base error for rebase operations.
@@ -7,12 +7,12 @@ import { ExitCode } from './codes.js';
 export class RebaseError extends FireForgeError {
     code = ExitCode.PATCH_ERROR;
     get userMessage() {
-        let msg = `Rebase Error: ${this.message}`;
-        msg += '\n\nTo fix this:\n';
-        msg += '  1. Check the error message above for specifics\n';
-        msg += '  2. Use "fireforge rebase --continue" to resume an interrupted rebase\n';
-        msg += '  3. Use "fireforge rebase --abort" to cancel and restore engine state';
-        return msg;
+        return (`Rebase Error: ${this.message}` +
+            remedies([
+                'Check the error message above for specifics',
+                'Use "fireforge rebase --continue" to resume an interrupted rebase',
+                'Use "fireforge rebase --abort" to cancel and restore engine state',
+            ]));
     }
 }
 /**