@hominis/fireforge 0.13.2 → 0.14.0

package/dist/src/core/signal-critical.js

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Signal-deferred critical sections.
+ *
+ * Commands that perform a compound mutation (e.g. "apply a patch to the
+ * engine, then persist progress to a session file on disk") need to finish
+ * the pair atomically with respect to SIGINT / SIGTERM. The furnace rollback
+ * mechanism is not the right tool here: rebase-style operations intentionally
+ * leave the engine mutated and only need the on-disk bookkeeping write to
+ * complete before the process exits.
+ *
+ * `runInSignalCriticalSection(fn)` wraps a short body in a registry slot.
+ * While the body runs, the CLI entry point's SIGINT / SIGTERM handlers wait
+ * for the slot to clear before calling `process.exit`, so a signal that
+ * lands mid-body is held until the body's state write finishes.
+ *
+ * This module is a pure runtime registry — it installs no signal handlers
+ * itself. The bin entry point is responsible for awaiting
+ * `waitForActiveCriticalSections` before terminating.
+ */
+const activeSections = new Set();
+/**
+ * Runs `fn` inside a signal-deferred critical section. The CLI entry point's
+ * signal handlers `await` every active section before exiting, so a SIGINT or
+ * SIGTERM that arrives during `fn` will hold exit until `fn` returns (or
+ * rejects).
+ *
+ * `fn` should be short — anything that takes longer than the bounded wait in
+ * the bin handler (`SIGNAL_CRITICAL_SECTION_TIMEOUT_MS`) will time out and
+ * the handler will exit anyway. The intent is "guard the apply + state
+ * persist pair," not "postpone exit indefinitely."
+ */
+export async function runInSignalCriticalSection(label, fn) {
+    let resolver = () => undefined;
+    const section = {
+        label,
+        promise: new Promise((resolve) => {
+            resolver = resolve;
+        }),
+    };
+    activeSections.add(section);
+    try {
+        return await fn();
+    }
+    finally {
+        activeSections.delete(section);
+        resolver();
+    }
+}
+/**
+ * Returns true while any critical section is currently running. Used by the
+ * bin entry point's signal handler to decide whether to await before exit.
+ */
+export function hasActiveCriticalSection() {
+    return activeSections.size > 0;
+}
+/**
+ * Waits for every active critical section to complete or for `timeoutMs` to
+ * elapse, whichever comes first. Never rejects: a section that throws still
+ * resolves from the registry's perspective because `runInSignalCriticalSection`
+ * cleans up in `finally`.
+ */
+export async function waitForActiveCriticalSections(timeoutMs) {
+    if (activeSections.size === 0)
+        return;
+    const snapshot = [...activeSections].map((s) => s.promise);
+    await Promise.race([
+        Promise.allSettled(snapshot).then(() => undefined),
+        new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+    ]);
+}
+/**
+ * Test-only helper: clears the critical-section registry. Production code
+ * must never call this — it voids the exit-ordering guarantee for any
+ * section still in flight.
+ */
+export function resetCriticalSectionsForTests() {
+    activeSections.clear();
+}
+//# sourceMappingURL=signal-critical.js.map

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

@@ -37,6 +37,6 @@ export declare class EngineExistsError extends DownloadError {
  */
 export declare class PartialEngineExistsError extends DownloadError {
     readonly enginePath: string;
-    constructor(enginePath: string);
+    constructor(enginePath: string, cause?: Error);
     get userMessage(): string;
 }

package/dist/src/errors/download.js

@@ -80,16 +80,19 @@ export class EngineExistsError extends DownloadError {
  */
 export class PartialEngineExistsError extends DownloadError {
     enginePath;
-    constructor(enginePath) {
-        super(`Engine directory contains a partially initialized checkout: ${enginePath}`);
+    constructor(enginePath, cause) {
+        super(`Engine directory contains a partially initialized checkout: ${enginePath}`, undefined, cause);
         this.enginePath = enginePath;
     }
     get userMessage() {
+        const causeMessage = this.cause instanceof Error && this.cause.message ? this.cause.message : undefined;
         return (`Download Error: Firefox source exists, but the baseline git repository was not fully initialized.\n\n` +
             `Path: ${this.enginePath}\n\n` +
+            (causeMessage ? `Underlying cause: ${causeMessage}\n\n` : '') +
             'To fix this:\n' +
             '  1. Re-run "fireforge download --force" to recreate the baseline repository\n' +
-            '  2. Or manually delete the engine/ directory before downloading again');
+            '  2. Or manually delete the engine/ directory before downloading again\n' +
+            '  3. Re-run with --verbose for the full underlying error and stack trace');
     }
 }
 //# sourceMappingURL=download.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",