@hominis/fireforge 0.13.2 → 0.15.1

package/dist/src/core/signal-critical.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function runInSignalCriticalSection<T>(label: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * 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 declare function hasActiveCriticalSection(): boolean;
+/**
+ * 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 declare function waitForActiveCriticalSections(timeoutMs: number): Promise<void>;
+/**
+ * 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 declare function resetCriticalSectionsForTests(): void;

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/dist/src/types/commands/options.d.ts

@@ -178,6 +178,12 @@ export interface TestOptions {
     headless?: boolean;
     /** Run incremental UI build before testing */
     build?: boolean;
+    /**
+     * Run a marionette preflight before tests. Reports PASS/FAIL in under a
+     * minute. When test paths are supplied, a FAIL aborts before mach test is
+     * spawned. When no paths are supplied, runs the preflight only and exits.
+     */
+    doctor?: boolean;
 }
 /**
  * Options for the furnace apply command.

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

@@ -44,6 +44,13 @@ export interface FireForgeConfig {
     wire?: WireConfig;
     /** Patch lint configuration */
     patchLint?: PatchLintConfig;
+    /**
+     * Project marker prefix appended to lines FireForge writes into
+     * upstream Firefox source files (e.g. the `customElements.js` tag list).
+     * `"HOMINIS"` emits a trailing `  // HOMINIS:` on each inserted line.
+     * Keeps modifications discoverable and re-applies idempotent.
+     */
+    markerComment?: string;
 }
 /**
  * Wire command configuration.

package/dist/src/types/furnace.d.ts

@@ -63,6 +63,14 @@ export interface FurnaceConfig {
     tokenPrefix?: string;
     /** Custom properties allowed even though they don't match tokenPrefix (e.g. ["--background-color-box"]) */
     tokenAllowlist?: string[];
+    /**
+     * Chrome documents scanned by the `missing-token-link` validator to confirm
+     * the tokens CSS file is `<link>`ed. Forks with multiple chrome host
+     * documents (e.g. `hominis.xhtml` beside the stock `browser.xhtml`) should
+     * list every document that may own the link. When omitted, defaults to
+     * `['browser/base/content/browser.xhtml']` — the upstream Firefox path.
+     */
+    tokenHostDocuments?: string[];
     /**
      * Override the default Fluent (.ftl) base path within the engine.
      * Defaults to `toolkit/locales/en-US/toolkit/global` when not set.

package/dist/src/utils/process.d.ts

@@ -51,12 +51,23 @@ export interface StreamOptions extends ExecOptions {
 export declare function execStream(command: string, args: string[], options?: StreamOptions): Promise<number>;
 /**
  * Executes a command and inherits stdio (shows output directly).
+ *
+ * Graceful shutdown: when the FireForge process receives SIGINT/SIGTERM, the
+ * signal is forwarded to the child as SIGTERM and a short grace timer (default
+ * 1500ms) runs before escalating to SIGKILL. A second matching signal during
+ * the grace period triggers an immediate SIGKILL — matching the usual
+ * "hit Ctrl-C again to force-quit" UX. Without this, Firefox's AsyncShutdown
+ * / profileBeforeChange blockers (which flush in-memory state to disk) can be
+ * racing the OS child-exit path, losing the last few seconds of edits.
+ *
  * @param command - Command to execute
  * @param args - Command arguments
  * @param options - Execution options
  * @returns Exit code of the process
  */
-export declare function execInherit(command: string, args: string[], options?: ExecOptions): Promise<number>;
+export declare function execInherit(command: string, args: string[], options?: ExecOptions & {
+    shutdownGraceMs?: number;
+}): Promise<number>;
 /**
  * Executes a command while inheriting stdin, streaming stdout/stderr live,
  * and capturing the emitted output for diagnostics.
@@ -65,7 +76,9 @@ export declare function execInherit(command: string, args: string[], options?: E
  * @param options - Execution options
  * @returns Execution result with stdout, stderr, and exit code
  */
-export declare function execInheritCapture(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+export declare function execInheritCapture(command: string, args: string[], options?: ExecOptions & {
+    shutdownGraceMs?: number;
+}): Promise<ExecResult>;
 /**
  * Finds an executable in the system PATH.
  * @param name - Name of the executable

package/dist/src/utils/process.js

@@ -108,6 +108,15 @@ export async function execStream(command, args, options = {}) {
 }
 /**
  * Executes a command and inherits stdio (shows output directly).
+ *
+ * Graceful shutdown: when the FireForge process receives SIGINT/SIGTERM, the
+ * signal is forwarded to the child as SIGTERM and a short grace timer (default
+ * 1500ms) runs before escalating to SIGKILL. A second matching signal during
+ * the grace period triggers an immediate SIGKILL — matching the usual
+ * "hit Ctrl-C again to force-quit" UX. Without this, Firefox's AsyncShutdown
+ * / profileBeforeChange blockers (which flush in-memory state to disk) can be
+ * racing the OS child-exit path, losing the last few seconds of edits.
+ *
  * @param command - Command to execute
  * @param args - Command arguments
  * @param options - Execution options
@@ -121,14 +130,74 @@ export async function execInherit(command, args, options = {}) {
             stdio: 'inherit',
             signal: buildSignalFromTimeout(options.timeout),
         });
+        const graceMs = options.shutdownGraceMs ?? 1500;
+        const { dispose } = installGracefulShutdownForwarder(child, graceMs);
         child.on('error', (error) => {
+            dispose();
             reject(error);
         });
         child.on('close', (code, signal) => {
+            dispose();
             resolve(exitCodeFromClose(code, signal));
         });
     });
 }
+/**
+ * Wires parent-process SIGINT/SIGTERM to a child: first signal → child.kill
+ * (SIGTERM) + grace timer; second matching signal → immediate SIGKILL; grace
+ * timer expiry → SIGKILL. Returns a `dispose()` that clears the listeners and
+ * any outstanding timer. Callers must invoke `dispose()` from both the child's
+ * `close` and `error` handlers so the process does not accumulate signal
+ * listeners across repeated spawns.
+ */
+function installGracefulShutdownForwarder(child, graceMs) {
+    let graceTimer;
+    const forwarded = new Set();
+    const escalate = () => {
+        if (child.exitCode !== null || child.signalCode !== null)
+            return;
+        try {
+            child.kill('SIGKILL');
+        }
+        catch {
+            // Child is already gone — nothing to do.
+        }
+    };
+    const handleSignal = (signal) => {
+        if (forwarded.has(signal)) {
+            // Second receipt of the same signal while still running: escalate now.
+            escalate();
+            return;
+        }
+        forwarded.add(signal);
+        try {
+            child.kill('SIGTERM');
+        }
+        catch {
+            // If the child can't accept SIGTERM (already dead), nothing to do.
+            return;
+        }
+        graceTimer = setTimeout(escalate, graceMs);
+        graceTimer.unref();
+    };
+    const onSigint = () => {
+        handleSignal('SIGINT');
+    };
+    const onSigterm = () => {
+        handleSignal('SIGTERM');
+    };
+    process.on('SIGINT', onSigint);
+    process.on('SIGTERM', onSigterm);
+    const dispose = () => {
+        process.off('SIGINT', onSigint);
+        process.off('SIGTERM', onSigterm);
+        if (graceTimer) {
+            clearTimeout(graceTimer);
+            graceTimer = undefined;
+        }
+    };
+    return { dispose };
+}
 /**
  * Executes a command while inheriting stdin, streaming stdout/stderr live,
  * and capturing the emitted output for diagnostics.
@@ -149,10 +218,14 @@ export async function execInheritCapture(command, args, options = {}) {
         const err = createStreamCollector(process.stderr);
         child.stdout.on('data', out.onData);
         child.stderr.on('data', err.onData);
+        const graceMs = options.shutdownGraceMs ?? 1500;
+        const { dispose } = installGracefulShutdownForwarder(child, graceMs);
         child.on('error', (error) => {
+            dispose();
             reject(error);
         });
         child.on('close', (code, signal) => {
+            dispose();
             resolve({
                 stdout: out.getText(),
                 stderr: err.getText(),

package/package.json

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