@hominis/fireforge 0.45.0 → 0.46.1

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.d.ts

@@ -8,10 +8,10 @@ export declare class FurnaceError extends FireForgeError {
     constructor(message: string, component?: string | undefined, cause?: Error, options?: {
         /**
          * Suppresses the "run furnace validate" advice line. Set by callers
-         * whose message already tells the user to run validate, or that ARE
+         * whose message already tells the user to run validate, or that are
          * the validate command. An explicit flag rather than sniffing the
          * message for `furnace validate`, which drops the advice from any
-         * error that merely MENTIONS the command.
+         * error that merely mentions the command.
          */
         omitValidateAdvice?: boolean;
     });

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.
  */
@@ -40,7 +40,7 @@ export declare class GitIndexLockError extends GitError {
     get userMessage(): string;
 }
 /**
- * Detects transient git `index.lock` contention — an external git process
+ * Detects transient git `index.lock` contention: an external git process
  * holding `.git/index.lock` while we stage or diff. Mirrors the message
  * heuristics `core/git.ts` uses when wrapping stale-lock failures during
  * download, but lives here so command modules can consult it without

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',
+            ]));
     }
 }
 /**
@@ -97,7 +87,7 @@ export class GitIndexLockError extends GitError {
     }
 }
 /**
- * Detects transient git `index.lock` contention — an external git process
+ * Detects transient git `index.lock` contention: an external git process
  * holding `.git/index.lock` while we stage or diff. Mirrors the message
  * heuristics `core/git.ts` uses when wrapping stale-lock failures during
  * download, but lives here so command modules can consult it without

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

@@ -2,11 +2,11 @@ import { FireForgeError } from './base.js';
 /**
  * Error thrown when `patches.json` exists but cannot be parsed or validated.
  *
- * This must be a HARD error on every mutating path. Collapsing "corrupt"
- * into "absent" — a `loadPatchesManifest` that returns null for both — makes
+ * This must be a hard error on every mutating path. Collapsing "corrupt"
+ * into "absent" (a `loadPatchesManifest` that returns null for both) makes
  * the next `fireforge export` rebuild the manifest containing only the new
  * patch, silently destroying every other patch's metadata (tiers,
- * descriptions, lintIgnore, staged dependencies); a failed export's rollback
+ * descriptions, lintIgnore, staged dependencies). A failed export's rollback
  * then deletes `patches.json` outright, because the "before" state looked
  * absent.
  */

package/dist/src/errors/patch.js

@@ -1,14 +1,14 @@
 // 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.
  *
- * This must be a HARD error on every mutating path. Collapsing "corrupt"
- * into "absent" — a `loadPatchesManifest` that returns null for both — makes
+ * This must be a hard error on every mutating path. Collapsing "corrupt"
+ * into "absent" (a `loadPatchesManifest` that returns null for both) makes
  * the next `fireforge export` rebuild the manifest containing only the new
  * patch, silently destroying every other patch's metadata (tiers,
- * descriptions, lintIgnore, staged dependencies); a failed export's rollback
+ * descriptions, lintIgnore, staged dependencies). A failed export's rollback
  * then deletes `patches.json` outright, because the "before" state looked
  * absent.
  */
@@ -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.d.ts

@@ -23,7 +23,7 @@ export declare class NoRebaseSessionError extends RebaseError {
  *
  * Without an error of its own, this case is reported as
  * {@link NoRebaseSessionError} by `--continue`/`--abort` while `rebase`
- * reports {@link RebaseSessionExistsError} — a closed cycle in which each
+ * reports {@link RebaseSessionExistsError}, a closed cycle in which each
  * command points at the other two. The message names the file so an operator
  * always has a way out, and `--abort` clears a corrupt session rather than
  * refusing to run against one.

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',
+            ]));
     }
 }
 /**
@@ -37,7 +37,7 @@ export class NoRebaseSessionError extends RebaseError {
  *
  * Without an error of its own, this case is reported as
  * {@link NoRebaseSessionError} by `--continue`/`--abort` while `rebase`
- * reports {@link RebaseSessionExistsError} — a closed cycle in which each
+ * reports {@link RebaseSessionExistsError}, a closed cycle in which each
  * command points at the other two. The message names the file so an operator
  * always has a way out, and `--abort` clears a corrupt session rather than
  * refusing to run against one.

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

@@ -2,7 +2,7 @@ import { FireForgeError } from './base.js';
 import { ExitCode } from './codes.js';
 /**
  * Error raised by `fireforge run --smoke-exit` when the captured console
- * stream produced one or more error lines that did NOT match the
+ * stream produced one or more error lines that did not match the
  * configured allowlist.
  *
  * Distinct from `BuildError` so CI pipelines can route smoke failures

package/dist/src/errors/run.js

@@ -3,7 +3,7 @@ import { FireForgeError } from './base.js';
 import { ExitCode } from './codes.js';
 /**
  * Error raised by `fireforge run --smoke-exit` when the captured console
- * stream produced one or more error lines that did NOT match the
+ * stream produced one or more error lines that did not match the
  * configured allowlist.
  *
  * Distinct from `BuildError` so CI pipelines can route smoke failures

package/dist/src/index.d.ts

@@ -1,15 +1,15 @@
 /**
- * FireForge — a toolkit for building and maintaining Firefox-based browsers.
+ * FireForge: a toolkit for building and maintaining Firefox-based browsers.
  *
  * This module re-exports the public API surface used by downstream consumers.
  * For CLI usage, see `bin/fireforge.ts`.
  *
- * **Stability:** Pre-1.0. The exports listed here are functional and tested,
+ * Stability: pre-1.0. The exports listed here are functional and tested,
  * but may change between minor versions until 1.0 is released. Pin to an
  * exact version if you depend on the programmatic API.
  *
- * **What belongs here:** a type earns a place on this surface only if it is
- * reachable from the signature of an exported VALUE — i.e. a consumer needs
+ * What belongs here: a type earns a place on this surface only if it is
+ * reachable from the signature of an exported value, i.e. a consumer needs
  * it to name an argument or a return. Everything else stays internal to
  * `src/types/`.
  *

package/dist/src/index.js

@@ -1,16 +1,16 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * FireForge — a toolkit for building and maintaining Firefox-based browsers.
+ * FireForge: a toolkit for building and maintaining Firefox-based browsers.
  *
  * This module re-exports the public API surface used by downstream consumers.
  * For CLI usage, see `bin/fireforge.ts`.
  *
- * **Stability:** Pre-1.0. The exports listed here are functional and tested,
+ * Stability: pre-1.0. The exports listed here are functional and tested,
  * but may change between minor versions until 1.0 is released. Pin to an
  * exact version if you depend on the programmatic API.
  *
- * **What belongs here:** a type earns a place on this surface only if it is
- * reachable from the signature of an exported VALUE — i.e. a consumer needs
+ * What belongs here: a type earns a place on this surface only if it is
+ * reachable from the signature of an exported value, i.e. a consumer needs
  * it to name an argument or a return. Everything else stays internal to
  * `src/types/`.
  *