@hominis/fireforge 0.14.0 → 0.15.2

package/dist/src/core/marionette-preflight.js

@@ -0,0 +1,260 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Marionette handshake preflight for `fireforge test --doctor`.
+ *
+ * Answers a single question before tests run: "does marionette come up?" A
+ * silent 360-second mach-test hang is indistinguishable from "tests failed
+ * to discover"; this helper surfaces the failure in under a minute with a
+ * clear PASS/FAIL line and the tail of the browser's stderr.
+ *
+ * The probe is a cascade of layered checks (engine → mach → python →
+ * profile → spawn → handshake). Each layer has a tight per-attempt budget
+ * so a broken earlier layer fails fast with a specific diagnosis rather
+ * than blocking on the final socket poll for the full overall budget.
+ */
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import net from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathExists } from '../utils/fs.js';
+import { info, warn } from '../utils/logger.js';
+import { ensureMach } from './mach.js';
+import { getPython } from './mach-python.js';
+/** Marionette's default TCP port when the browser is launched with `--marionette`. */
+const MARIONETTE_PORT = 2828;
+/** Overall budget for the preflight (browser boot + socket handshake). */
+const DEFAULT_PREFLIGHT_TIMEOUT_MS = 30_000;
+/** Per-attempt socket connect timeout. Polling continues until the overall budget expires. */
+const SOCKET_ATTEMPT_TIMEOUT_MS = 2_000;
+/**
+ * Grace window after spawn() returns before we accept the child as
+ * "spawned OK". A browser binary that exits immediately (missing dylib,
+ * wrong CPU arch, corrupt profile) must be caught here — not 30 seconds
+ * later at the socket layer.
+ */
+const SPAWN_SETTLE_MS = 750;
+/** Tail of stderr preserved for FAIL diagnostics. */
+const STDERR_TAIL_LIMIT = 8 * 1024;
+/**
+ * Layer names, ordered by the probe sequence. Surfaced in `detail` so the
+ * operator sees which layer failed without having to guess.
+ */
+const LAYER_NAMES = [
+    'engine-present',
+    'mach-available',
+    'python-available',
+    'profile-creatable',
+    'browser-spawns',
+    'marionette-handshake',
+];
+function layerTag(name) {
+    const index = LAYER_NAMES.indexOf(name) + 1;
+    return `[layer ${index}/${LAYER_NAMES.length}: ${name}]`;
+}
+/**
+ * Runs the marionette preflight. Returns PASS on first byte read from the
+ * marionette socket within the budget; FAIL otherwise, with a diagnostic
+ * identifying which layer of the cascade broke. Always tears down the
+ * spawned browser before returning.
+ */
+export async function runMarionettePreflight(engineDir, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_PREFLIGHT_TIMEOUT_MS;
+    const spawnSettleMs = options.spawnSettleMs ?? SPAWN_SETTLE_MS;
+    const port = options.port ?? MARIONETTE_PORT;
+    const spawnerFn = options.spawner ?? spawn;
+    const connectFn = options.connect ?? net.createConnection;
+    const startedAt = Date.now();
+    const elapsed = () => Date.now() - startedAt;
+    // Layer 1: engine directory exists.
+    if (!(await pathExists(engineDir))) {
+        return fail('engine-present', 'Engine directory not found — run "fireforge download" first.', elapsed());
+    }
+    // Layer 2: mach binary resolves in the engine.
+    try {
+        await ensureMach(engineDir);
+    }
+    catch (error) {
+        return fail('mach-available', `mach not available in engine: ${error.message}`, elapsed());
+    }
+    // Layer 3: Python that mach requires is discoverable.
+    let python;
+    try {
+        python = await getPython(engineDir);
+    }
+    catch (error) {
+        return fail('python-available', `Python interpreter required by mach is not available: ${error.message}`, elapsed());
+    }
+    // Layer 4: throwaway browser profile directory is creatable.
+    let profileDir;
+    try {
+        profileDir = await mkdtemp(join(tmpdir(), 'fireforge-marionette-'));
+    }
+    catch (error) {
+        return fail('profile-creatable', `Could not create a throwaway browser profile in ${tmpdir()}: ${error.message}`, elapsed());
+    }
+    let child;
+    let stderrTail = '';
+    try {
+        // Layer 5: browser spawns and does not crash within the settle window.
+        try {
+            child = spawnerFn(python, [
+                join(engineDir, 'mach'),
+                'run',
+                '--marionette',
+                '--headless',
+                '--no-remote',
+                '-profile',
+                profileDir,
+            ], {
+                cwd: engineDir,
+                env: { ...process.env, MOZ_HEADLESS: '1' },
+                stdio: ['ignore', 'ignore', 'pipe'],
+            });
+        }
+        catch (error) {
+            return fail('browser-spawns', `Could not spawn mach run: ${error.message}`, elapsed());
+        }
+        const spawnedChild = child;
+        child.stderr?.on('data', (data) => {
+            const chunk = data.toString();
+            stderrTail = (stderrTail + chunk).slice(-STDERR_TAIL_LIMIT);
+        });
+        // Short settle window — catches "binary exits immediately" failures
+        // (missing dylib, wrong CPU arch, corrupt profile) before the socket
+        // poll swallows the full overall budget waiting for bytes that will
+        // never come.
+        const settleDeadline = Math.min(spawnSettleMs, Math.max(0, timeoutMs - elapsed()));
+        if (settleDeadline > 0) {
+            await delay(settleDeadline);
+        }
+        if (hasChildExited(spawnedChild)) {
+            return fail('browser-spawns', `Browser process exited during spawn (exit code ${String(spawnedChild.exitCode)}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
+                `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`, elapsed());
+        }
+        // Layer 6: marionette handshake within the remaining budget.
+        const socketResult = await waitForMarionetteSocket(port, connectFn, () => {
+            return elapsed() < timeoutMs && !hasChildExited(spawnedChild);
+        });
+        if (socketResult.ok) {
+            return {
+                ok: true,
+                durationMs: elapsed(),
+                detail: `Marionette handshake received on 127.0.0.1:${port} in ${Date.now() - startedAt}ms.`,
+            };
+        }
+        // Child may have exited before the socket was ever ready — surface that
+        // distinctly from "socket never answered" so the operator has a lead.
+        if (hasChildExited(spawnedChild)) {
+            return fail('marionette-handshake', `Browser process exited before marionette handshake (exit code ${String(spawnedChild.exitCode)}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
+                `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`, elapsed());
+        }
+        return fail('marionette-handshake', `Marionette socket on 127.0.0.1:${port} did not respond within ${timeoutMs}ms. ` +
+            `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`, elapsed());
+    }
+    finally {
+        if (child && !hasChildExited(child)) {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                // Already exited — nothing to do.
+            }
+            // Small escalation: if the child doesn't honour SIGTERM quickly, SIGKILL
+            // so we don't leave a ghost mach process around after a failed probe.
+            await delay(500);
+            if (!hasChildExited(child)) {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    // Already gone.
+                }
+            }
+        }
+        try {
+            await rm(profileDir, { recursive: true, force: true });
+        }
+        catch (error) {
+            warn(`Could not clean up marionette preflight profile: ${error.message}`);
+        }
+    }
+}
+function fail(layer, message, durationMs) {
+    return {
+        ok: false,
+        durationMs,
+        detail: `${layerTag(layer)} ${message}`,
+    };
+}
+/** Returns true when the child process has exited (normal or signaled). */
+function hasChildExited(child) {
+    return child.exitCode !== null || child.signalCode !== null;
+}
+async function waitForMarionetteSocket(port, connectFn, keepTrying) {
+    while (keepTrying()) {
+        const result = await attemptMarionetteConnect(port, connectFn);
+        if (result.ok) {
+            return { ok: true };
+        }
+        await delay(400);
+    }
+    return { ok: false };
+}
+function attemptMarionetteConnect(port, connectFn) {
+    return new Promise((resolve) => {
+        const socket = connectFn({ host: '127.0.0.1', port });
+        let settled = false;
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                socket.destroy();
+            }
+            catch {
+                // Ignore — already closed.
+            }
+            resolve({ ok });
+        };
+        const attemptTimer = setTimeout(() => {
+            finish(false);
+        }, SOCKET_ATTEMPT_TIMEOUT_MS);
+        attemptTimer.unref();
+        socket.once('connect', () => {
+            // Connect alone is insufficient — the marionette server performs a
+            // handshake send as soon as the socket opens, so wait for at least one
+            // byte to confirm the server is actually speaking marionette.
+            const readTimer = setTimeout(() => {
+                finish(false);
+            }, SOCKET_ATTEMPT_TIMEOUT_MS);
+            readTimer.unref();
+            socket.once('data', () => {
+                clearTimeout(readTimer);
+                finish(true);
+            });
+        });
+        socket.once('error', () => {
+            finish(false);
+        });
+        socket.once('close', () => {
+            finish(false);
+        });
+    });
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref();
+    });
+}
+/** Renders a PASS/FAIL banner to the CLI using the shared logger helpers. */
+export function reportMarionettePreflight(result) {
+    if (result.ok) {
+        info(`Marionette preflight: PASS (${result.durationMs}ms) — ${result.detail}`);
+    }
+    else {
+        warn(`Marionette preflight: FAIL (${result.durationMs}ms) — ${result.detail}`);
+    }
+}
+//# sourceMappingURL=marionette-preflight.js.map

package/dist/src/core/patch-lint-cross.d.ts

@@ -91,7 +91,7 @@ export declare function collectNewFileCreatorsByPath(ctx: PatchQueueContext): Ma
 /**
  * Cross-patch lint rule: the same path is newly created (`--- /dev/null →
  * +++ b/path`) by more than one patch. This is the failure mode that
- * motivated the rule — Hominis landed three patches each trying to create
+ * motivated the rule — a fork landed three patches each trying to create
  * the same file, and the error surfaced only when import rolled back
  * mid-apply.
  *

package/dist/src/core/patch-lint-cross.js

@@ -114,7 +114,7 @@ export function collectNewFileCreatorsByPath(ctx) {
 /**
  * Cross-patch lint rule: the same path is newly created (`--- /dev/null →
  * +++ b/path`) by more than one patch. This is the failure mode that
- * motivated the rule — Hominis landed three patches each trying to create
+ * motivated the rule — a fork landed three patches each trying to create
  * the same file, and the error surfaced only when import rolled back
  * mid-apply.
  *

package/dist/src/core/patch-lint.js

@@ -110,12 +110,14 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
     // Load furnace config gracefully — skip token-prefix check if unavailable
     let tokenPrefix;
     let tokenAllowlist;
+    let runtimeVariables;
     try {
         const root = join(repoDir, '..');
         const furnaceConfig = await loadFurnaceConfig(root);
         if (furnaceConfig.tokenPrefix) {
             tokenPrefix = furnaceConfig.tokenPrefix;
             tokenAllowlist = new Set(furnaceConfig.tokenAllowlist ?? []);
+            runtimeVariables = new Set(furnaceConfig.runtimeVariables ?? []);
         }
     }
     catch (error) {
@@ -154,20 +156,38 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
                 });
             }
         }
-        // Check for non-tokenized custom properties
+        // Check for non-tokenized custom properties. A variable that is both
+        // declared and consumed inside the same file is auto-exempted as a
+        // runtime state channel (see furnace.json → runtimeVariables).
         if (tokenPrefix) {
+            const declarationPattern = /(?:^|[{;,\s])(--[\w-]+)\s*:/g;
+            const localDeclarations = new Set();
+            let declMatch;
+            while ((declMatch = declarationPattern.exec(cssContent)) !== null) {
+                const name = declMatch[1];
+                if (name)
+                    localDeclarations.add(name);
+            }
             const varPattern = /var\(\s*(--[\w-]+)/g;
             let match;
             while ((match = varPattern.exec(cssContent)) !== null) {
                 const prop = match[1];
-                if (prop && !prop.startsWith(tokenPrefix) && !tokenAllowlist?.has(prop)) {
-                    issues.push({
-                        file,
-                        check: 'token-prefix-violation',
-                        message: `CSS references var(${prop}) which does not match the required token prefix "${tokenPrefix}". Use a design token or add to tokenAllowlist.`,
-                        severity: 'error',
-                    });
-                }
+                if (!prop)
+                    continue;
+                if (prop.startsWith(tokenPrefix))
+                    continue;
+                if (tokenAllowlist?.has(prop))
+                    continue;
+                if (runtimeVariables?.has(prop))
+                    continue;
+                if (localDeclarations.has(prop))
+                    continue;
+                issues.push({
+                    file,
+                    check: 'token-prefix-violation',
+                    message: `CSS references var(${prop}) which does not match the required token prefix "${tokenPrefix}". Use a design token, add to tokenAllowlist, or (for runtime state channels) list the variable in runtimeVariables.`,
+                    severity: 'error',
+                });
             }
         }
     }

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.
@@ -265,6 +271,16 @@ export interface FurnaceCreateOptions {
     register?: boolean;
     /** Scaffold Mochitest directory and register in moz.build */
     withTests?: boolean;
+    /**
+     * Scaffold an xpcshell test harness (headless, no tabbrowser) instead of
+     * browser-chrome. Required for forks without a `tabbrowser` (storage-only
+     * code, observer-driven modules). Implies `withTests` when set. Writes an
+     * `xpcshell.toml` + `test_<name>.js` under
+     * `engine/browser/base/content/test/<binary-name>-xpcshell/` and leaves
+     * moz.build registration to the operator (add the directory to
+     * `XPCSHELL_TESTS_MANIFESTS`).
+     */
+    xpcshell?: boolean;
     /** Stock component tag names composed internally by this component */
     compose?: string[];
 }

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).
+     * `"MYBROWSER"` emits a trailing `  // MYBROWSER:` 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,25 @@ export interface FurnaceConfig {
     tokenPrefix?: string;
     /** Custom properties allowed even though they don't match tokenPrefix (e.g. ["--background-color-box"]) */
     tokenAllowlist?: string[];
+    /**
+     * Custom properties used as runtime state channels — written and read by the
+     * component itself (e.g. per-frame camera/tile positions) rather than
+     * consumed as design tokens. Listed names are exempt from the
+     * `token-prefix-violation` check even when they do not match `tokenPrefix`
+     * and are not in `tokenAllowlist`. Use this for cross-component runtime
+     * variables (e.g. set in JS, read in CSS of a child). Component-local
+     * variables that are both declared and consumed inside the same component's
+     * own CSS file are auto-exempted and do not need an entry here.
+     */
+    runtimeVariables?: 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. `mybrowser.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.14.0",
+  "version": "0.15.2",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",