@hominis/fireforge 0.16.3 → 0.17.0

package/dist/src/core/token-dark-mode.js

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Dark-mode insertion helpers for the tokens CSS scaffold.
+ *
+ * The 2026-04-21 eval reproduced a bug where `fireforge token add
+ * --mode override --dark-value ...` landed the dark declaration
+ * AFTER the nested `:root { }` inside the
+ * `@media (prefers-color-scheme: dark)` block had already closed,
+ * producing a declaration outside any rule block. The helpers here
+ * scan the comment-stripped source lines to find the *inner* `:root`
+ * block's closing `}` and return a line index the caller can splice
+ * into. When the inner `:root` is missing (a scaffold that drifted
+ * from the default), the fallback helper returns the outer `@media`
+ * block's close so the caller can materialise a fresh `:root` wrapper
+ * rather than dropping the dark value.
+ */
+/**
+ * Strips the content of `/* ... *\/` block comments from an array of
+ * CSS source lines while preserving each line's length. Indexed scans
+ * over the returned mirror line up with the original, so callers that
+ * compute an insertion index against the stripped array can splice
+ * into the original array at the same index.
+ *
+ * We blank the comment body with spaces (rather than removing it) so
+ * any downstream consumer that indexes by column — or derives an
+ * insertion index as a line number in the original array — still
+ * agrees on line numbers.
+ */
+export function stripBlockCommentsInLines(lines) {
+    const out = [];
+    let inBlockComment = false;
+    for (const original of lines) {
+        let line = '';
+        for (let i = 0; i < original.length; i++) {
+            if (inBlockComment) {
+                if (original[i] === '*' && original[i + 1] === '/') {
+                    line += '  ';
+                    i += 1;
+                    inBlockComment = false;
+                }
+                else {
+                    line += ' ';
+                }
+            }
+            else if (original[i] === '/' && original[i + 1] === '*') {
+                line += '  ';
+                i += 1;
+                inBlockComment = true;
+            }
+            else {
+                // `original[i]` is provably defined here (the bounds check is
+                // the loop condition), but TS narrows it to `string | undefined`.
+                // Default to empty string so the concat stays well-typed.
+                line += original[i] ?? '';
+            }
+        }
+        out.push(line);
+    }
+    return out;
+}
+/**
+ * Finds the closing `}` line of the nested `:root { ... }` block inside
+ * a `@media (prefers-color-scheme: dark)` block. Returns `-1` when the
+ * media block exists but the nested `:root` block is missing; returns
+ * `null` when the `@media` block itself is absent.
+ *
+ * Runs the scan over a comment-stripped mirror of the source lines so
+ * braces inside CSS comments (`/* before { after *\/`) do not offset
+ * the depth counter. The scan is deliberately line-indexed so callers
+ * can splice into the original `lines` array at the returned index.
+ */
+export function findDarkRootInsertionIndex(lines) {
+    const stripped = stripBlockCommentsInLines(lines);
+    let darkMediaLine = -1;
+    for (let i = 0; i < stripped.length; i++) {
+        if (/prefers-color-scheme:\s*dark/.test(stripped[i] ?? '')) {
+            darkMediaLine = i;
+            break;
+        }
+    }
+    if (darkMediaLine === -1)
+        return null;
+    // Walk the comment-stripped lines after the @media header and find
+    // the first `:root {` opener inside the block. The opening brace of
+    // the selector may live on the same line as the selector name or on
+    // the following line; either shape is tolerated.
+    let rootOpenLine = -1;
+    for (let i = darkMediaLine; i < stripped.length; i++) {
+        const line = stripped[i] ?? '';
+        if (/(^|[\s,{])\s*:root\b/.test(line)) {
+            // Brace on the same line?
+            if (/:root[^{}]*\{/.test(line)) {
+                rootOpenLine = i;
+                break;
+            }
+            // Otherwise scan forward for the opening brace, stopping at the
+            // first `}` or second selector that would mean the `:root`
+            // declaration never opened a block.
+            for (let j = i + 1; j < stripped.length; j++) {
+                const next = stripped[j] ?? '';
+                if (/\{/.test(next)) {
+                    rootOpenLine = j;
+                    break;
+                }
+                if (/[};]/.test(next))
+                    break;
+            }
+            if (rootOpenLine !== -1)
+                break;
+        }
+    }
+    if (rootOpenLine === -1)
+        return -1;
+    // Depth-count starting from the `:root` opener. The first `{`
+    // encountered sets the entry depth to the initial counter value; the
+    // closing brace that returns to that depth terminates the block.
+    let depth = 0;
+    let entryDepth = 0;
+    let enteredBlock = false;
+    for (let i = rootOpenLine; i < stripped.length; i++) {
+        const line = stripped[i] ?? '';
+        for (const ch of line) {
+            if (ch === '{') {
+                depth++;
+                if (!enteredBlock) {
+                    entryDepth = depth - 1;
+                    enteredBlock = true;
+                }
+            }
+            else if (ch === '}') {
+                depth--;
+            }
+        }
+        if (enteredBlock && depth === entryDepth) {
+            return i;
+        }
+    }
+    return -1;
+}
+/**
+ * Finds the closing `}` of the outermost
+ * `@media (prefers-color-scheme: dark)` block. Used as the fallback
+ * landing site when the scaffold has no nested `:root { }` — the
+ * insertion helper uses this index to splice a brand-new `:root`
+ * wrapper containing the dark declaration, rather than dropping the
+ * value.
+ */
+export function findDarkMediaCloseIndex(lines) {
+    const stripped = stripBlockCommentsInLines(lines);
+    let darkMediaLine = -1;
+    for (let i = 0; i < stripped.length; i++) {
+        if (/prefers-color-scheme:\s*dark/.test(stripped[i] ?? '')) {
+            darkMediaLine = i;
+            break;
+        }
+    }
+    if (darkMediaLine === -1)
+        return -1;
+    let depth = 0;
+    let entryDepth = 0;
+    let enteredBlock = false;
+    for (let i = darkMediaLine; i < stripped.length; i++) {
+        const line = stripped[i] ?? '';
+        for (const ch of line) {
+            if (ch === '{') {
+                depth++;
+                if (!enteredBlock) {
+                    entryDepth = depth - 1;
+                    enteredBlock = true;
+                }
+            }
+            else if (ch === '}') {
+                depth--;
+            }
+        }
+        if (enteredBlock && depth === entryDepth) {
+            return i;
+        }
+    }
+    return -1;
+}
+//# sourceMappingURL=token-dark-mode.js.map

package/dist/src/core/token-manager.js

@@ -10,6 +10,7 @@ import { validateTokenName } from '../utils/validation.js';
 import { getProjectPaths, loadConfig } from './config.js';
 import { loadFurnaceConfig } from './furnace-config.js';
 import { findTableAfterHeading, findTableByColumns, insertRow, rewriteTableRows, updateCellByKey, } from './markdown-table.js';
+import { findDarkMediaCloseIndex, findDarkRootInsertionIndex } from './token-dark-mode.js';
 /** Returns the token CSS path relative to engine root for a given binary name. */
 export function getTokensCssPath(binaryName) {
     return `browser/themes/shared/${binaryName}-tokens.css`;
@@ -271,41 +272,24 @@ function findCategorySection(lines, category, tokensCssPath) {
 function insertDarkModeOverride(lines, options) {
     if (options.mode !== 'override' || !options.darkValue)
         return;
-    let darkMediaLine = -1;
-    for (let i = 0; i < lines.length; i++) {
-        if (/prefers-color-scheme:\s*dark/.test(lines[i] ?? '')) {
-            darkMediaLine = i;
-            break;
-        }
-    }
-    if (darkMediaLine === -1)
+    const insertionIndex = findDarkRootInsertionIndex(lines);
+    if (insertionIndex === null)
+        return; // No @media block at all.
+    const darkEntry = `    ${options.tokenName}: ${options.darkValue};`;
+    if (insertionIndex === -1) {
+        // @media block exists but has no nested :root { } — the scaffold
+        // drifted. Warn and fall back to appending a fresh nested :root
+        // block right before the @media block's closing brace so the
+        // generated CSS still parses, rather than dropping the dark value
+        // on the floor or producing a declaration outside any rule.
+        warn(`Dark-mode override block for "${options.tokenName}" could not find a nested ":root { }" inside @media (prefers-color-scheme: dark). Appending a fresh ":root { }" block — review the tokens CSS scaffold.`);
+        const outerCloseIndex = findDarkMediaCloseIndex(lines);
+        if (outerCloseIndex === -1)
+            return;
+        lines.splice(outerCloseIndex, 0, '  :root {', darkEntry, '  }');
         return;
-    // Find the closing } of the @media block
-    let darkBlockEnd = lines.length;
-    let depth = 0;
-    let entryDepth = 0;
-    let enteredBlock = false;
-    for (let i = darkMediaLine; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        for (const ch of line) {
-            if (ch === '{') {
-                depth++;
-                if (!enteredBlock) {
-                    entryDepth = depth - 1;
-                    enteredBlock = true;
-                }
-            }
-            if (ch === '}')
-                depth--;
-        }
-        if (enteredBlock && depth === entryDepth) {
-            darkBlockEnd = i;
-            break;
-        }
     }
-    // Insert the dark value before the closing }
-    const darkEntry = `    ${options.tokenName}: ${options.darkValue};`;
-    lines.splice(darkBlockEnd, 0, darkEntry);
+    lines.splice(insertionIndex, 0, darkEntry);
 }
 /**
  * Adds a token declaration to the CSS file in the correct category section.

package/dist/src/core/wire-destroy.js

@@ -10,7 +10,7 @@ import { pathExists, readText, writeText } from '../utils/fs.js';
 import { escapeRegex } from '../utils/regex.js';
 import { detectIndent, parseScript } from './ast-utils.js';
 import { withParserFallback } from './parser-fallback.js';
-import { assertBraceBalancePreserved, extractNameFromExpression, findMethodBody, findMethodBraceIndex, validateWireName, } from './wire-utils.js';
+import { assertBraceBalancePreserved, coerceToCall, extractNameFromExpression, findMethodBody, findMethodBraceIndex, validateWireName, } from './wire-utils.js';
 const BROWSER_INIT_JS = 'browser/base/content/browser-init.js';
 /**
  * AST-based implementation: finds onUnload()/uninit() method body and
@@ -18,6 +18,12 @@ const BROWSER_INIT_JS = 'browser/base/content/browser-init.js';
  */
 export function addDestroyAST(content, expression) {
     const name = extractNameFromExpression(expression);
+    // See wire-init.ts for the rationale: the template interpolates the
+    // expression verbatim, so a bare `Foo.bar` compiled to `Foo.bar;`
+    // (a property reference) instead of `Foo.bar();`. `coerceToCall`
+    // appends `()` when absent so the emitted block always invokes the
+    // teardown hook the operator asked for.
+    const callExpression = coerceToCall(expression);
     const ast = parseScript(content);
     const ms = new MagicString(content);
     const body = findMethodBody(ast, ['onUnload', 'uninit']);
@@ -41,7 +47,7 @@ export function addDestroyAST(content, expression) {
         `${indent}// ${name} destroy`,
         `${indent}try {`,
         `${indent}  if (typeof ${name} !== "undefined") {`,
-        `${indent}    ${expression};`,
+        `${indent}    ${callExpression};`,
         `${indent}  }`,
         `${indent}} catch (e) {`,
         `${indent}  console.error("${name} destroy failed:", e);`,
@@ -55,6 +61,9 @@ export function addDestroyAST(content, expression) {
  */
 export function legacyAddDestroy(content, expression) {
     const name = extractNameFromExpression(expression);
+    // Match the AST path on the call-coercion contract so fallback vs AST
+    // emits identical blocks (see wire-init.ts).
+    const callExpression = coerceToCall(expression);
     const lines = content.split('\n');
     const destroyRegex = /\b(?:async\s+)?(onUnload|uninit)\s*[(:]/;
     const found = findMethodBraceIndex(lines, destroyRegex, { requireBrace: true });
@@ -67,7 +76,7 @@ export function legacyAddDestroy(content, expression) {
         `    // ${name} destroy`,
         `    try {`,
         `      if (typeof ${name} !== "undefined") {`,
-        `        ${expression};`,
+        `        ${callExpression};`,
         `      }`,
         `    } catch (e) {`,
         `      console.error("${name} destroy failed:", e);`,
@@ -91,8 +100,12 @@ export async function addDestroyToBrowserInit(engineDir, expression) {
         throw new GeneralError(`${BROWSER_INIT_JS} not found in engine`);
     }
     const content = await readText(filePath);
-    // Idempotency check — use word-boundary regex to avoid substring false positives
-    const destroyPattern = new RegExp(`(?:^|\\W)${escapeRegex(expression)}\\s*;?\\s*$`, 'm');
+    // Idempotency check — look for the coerced (call) form because that is
+    // what the emitter writes. Matching against the raw input would miss a
+    // previous `EvalStartup.destroy` invocation that the 0.16.0 coercion
+    // already persisted as `EvalStartup.destroy()`.
+    const callExpression = coerceToCall(expression);
+    const destroyPattern = new RegExp(`(?:^|\\W)${escapeRegex(callExpression)}\\s*;?\\s*$`, 'm');
     if (destroyPattern.test(content)) {
         return false;
     }

package/dist/src/core/wire-dom-fragment.d.ts

@@ -16,6 +16,23 @@ export declare function addDomFragmentTokenized(content: string, includeDirectiv
  * Legacy line-based implementation preserved as fallback.
  */
 export declare function legacyAddDomFragment(content: string, includeDirective: string): string;
+/**
+ * Dry-run precheck for `addDomFragment`. Reads the resolved chrome
+ * document and verifies it either already contains the `#include`
+ * directive (the idempotent-skip case) OR offers a locatable insertion
+ * point via {@link addDomFragmentTokenized} / {@link legacyAddDomFragment}.
+ * Throws the same `Could not find insertion point in chrome document`
+ * error the real run would throw when neither condition holds.
+ *
+ * Motivating case (2026-04-21 eval, Finding #12): `fireforge wire ...
+ * --dry-run` previewed a plausible mutation plan against
+ * `tokenHostDocuments[0]`, then `fireforge wire ...` without
+ * `--dry-run` threw `Could not find insertion point in chrome document`
+ * on the same arguments. The real run had always called the insertion
+ * helpers; dry-run did not. This helper runs the same check in the
+ * preview pass so plan and execution disagree less.
+ */
+export declare function probeDomFragmentInsertionPoint(engineDir: string, domFilePath: string, targetPath?: string): Promise<void>;
 /**
  * Inserts a `#include` directive for an `.inc.xhtml` file into the top-level
  * chrome document (default: `browser/base/content/browser.xhtml`), before

package/dist/src/core/wire-dom-fragment.js

@@ -75,6 +75,46 @@ export function legacyAddDomFragment(content, includeDirective) {
     lines.splice(insertIndex, 0, includeDirective);
     return lines.join('\n');
 }
+/**
+ * Dry-run precheck for `addDomFragment`. Reads the resolved chrome
+ * document and verifies it either already contains the `#include`
+ * directive (the idempotent-skip case) OR offers a locatable insertion
+ * point via {@link addDomFragmentTokenized} / {@link legacyAddDomFragment}.
+ * Throws the same `Could not find insertion point in chrome document`
+ * error the real run would throw when neither condition holds.
+ *
+ * Motivating case (2026-04-21 eval, Finding #12): `fireforge wire ...
+ * --dry-run` previewed a plausible mutation plan against
+ * `tokenHostDocuments[0]`, then `fireforge wire ...` without
+ * `--dry-run` threw `Could not find insertion point in chrome document`
+ * on the same arguments. The real run had always called the insertion
+ * helpers; dry-run did not. This helper runs the same check in the
+ * preview pass so plan and execution disagree less.
+ */
+export async function probeDomFragmentInsertionPoint(engineDir, domFilePath, targetPath = DEFAULT_DOM_TARGET) {
+    const targetAbsPath = join(engineDir, targetPath);
+    if (!(await pathExists(targetAbsPath))) {
+        // The callers in `wire.ts` run their own existence probe before
+        // invoking this helper, but a well-behaved probe is paranoid — if
+        // something changed between the two checks, fail with the same
+        // error the real run would surface.
+        throw new GeneralError(`${targetPath} not found in engine`);
+    }
+    const safeDomFilePath = toRootRelativePath(engineDir, domFilePath);
+    const targetDir = dirname(targetPath);
+    const includePath = relative(targetDir, safeDomFilePath).replace(/\\/g, '/');
+    const includeDirective = `#include ${includePath}`;
+    const content = await readText(targetAbsPath);
+    if (new RegExp(`^${escapeRegex(includeDirective)}$`, 'm').test(content)) {
+        // Already wired — the real run would idempotent-skip here, so
+        // dry-run is allowed to proceed too.
+        return;
+    }
+    // Check the tokenised and legacy insertion paths symmetrically with
+    // the real run. Either helper returning without throwing is sufficient
+    // evidence that the real run can land the directive.
+    withParserFallback(() => addDomFragmentTokenized(content, includeDirective), () => legacyAddDomFragment(content, includeDirective), targetPath);
+}
 /**
  * Inserts a `#include` directive for an `.inc.xhtml` file into the top-level
  * chrome document (default: `browser/base/content/browser.xhtml`), before

package/dist/src/core/wire-init.js

@@ -10,7 +10,7 @@ import { pathExists, readText, writeText } from '../utils/fs.js';
 import { escapeRegex } from '../utils/regex.js';
 import { detectIndent, getNodeSource, parseScript } from './ast-utils.js';
 import { withParserFallback } from './parser-fallback.js';
-import { assertBraceBalancePreserved, extractNameFromExpression, findInsertionAfterFireforgeBlocks, findMethodBody, findMethodBraceIndex, validateWireName, walkToTryBlockEnd, } from './wire-utils.js';
+import { assertBraceBalancePreserved, coerceToCall, extractNameFromExpression, findInsertionAfterFireforgeBlocks, findMethodBody, findMethodBraceIndex, validateWireName, walkToTryBlockEnd, } from './wire-utils.js';
 const BROWSER_INIT_JS = 'browser/base/content/browser-init.js';
 /**
  * AST-based implementation: finds onLoad() method body, locates existing
@@ -19,6 +19,12 @@ const BROWSER_INIT_JS = 'browser/base/content/browser-init.js';
  */
 export function addInitAST(content, expression, after) {
     const name = extractNameFromExpression(expression);
+    // `validateWireName` accepts both `Foo.bar` and `Foo.bar()` shapes. The
+    // template below interpolates the value verbatim, so a bare property
+    // path compiles to `Foo.bar;` — a silent no-op, not a lifecycle
+    // invocation. `coerceToCall` normalises to the function-call form so
+    // the emitted block always invokes the hook the operator asked for.
+    const callExpression = coerceToCall(expression);
     const ast = parseScript(content);
     const ms = new MagicString(content);
     const body = findMethodBody(ast, 'onLoad');
@@ -97,7 +103,7 @@ export function addInitAST(content, expression, after) {
         `${indent}// inits that reference native UI elements we hide.`,
         `${indent}try {`,
         `${indent}  if (typeof ${name} !== "undefined") {`,
-        `${indent}    ${expression};`,
+        `${indent}    ${callExpression};`,
         `${indent}  }`,
         `${indent}} catch (e) {`,
         `${indent}  console.error("${name} init failed:", e);`,
@@ -111,6 +117,11 @@ export function addInitAST(content, expression, after) {
  */
 export function legacyAddInit(content, expression, after) {
     const name = extractNameFromExpression(expression);
+    // See `addInitAST` for the rationale — the AST and fallback paths must
+    // agree on whether the emitted block is a function call, otherwise
+    // operators would see different behaviour depending on which parser
+    // happened to handle their browser-init.js layout.
+    const callExpression = coerceToCall(expression);
     const lines = content.split('\n');
     const onLoadRegex = /\b(?:async\s+)?onLoad\s*[(:]/;
     const found = findMethodBraceIndex(lines, onLoadRegex, { requireBrace: true });
@@ -167,7 +178,7 @@ export function legacyAddInit(content, expression, after) {
         `${baseIndent}// inits that reference native UI elements we hide.`,
         `${baseIndent}try {`,
         `${inner}if (typeof ${name} !== "undefined") {`,
-        `${inner2}${expression};`,
+        `${inner2}${callExpression};`,
         `${inner}}`,
         `${baseIndent}} catch (e) {`,
         `${inner}console.error("${name} init failed:", e);`,
@@ -192,8 +203,12 @@ export async function addInitToBrowserInit(engineDir, expression, after) {
         throw new GeneralError(`${BROWSER_INIT_JS} not found in engine`);
     }
     const content = await readText(filePath);
-    // Idempotency check — use word-boundary regex to avoid substring false positives
-    const initPattern = new RegExp(`(?:^|\\W)${escapeRegex(expression)}\\s*;?\\s*$`, 'm');
+    // Idempotency check — look for the coerced (call) form because that is
+    // what the emitter writes. Matching against the raw input would miss a
+    // previous `EvalStartup.init` invocation that the 0.16.0 coercion
+    // already persisted as `EvalStartup.init()`.
+    const callExpression = coerceToCall(expression);
+    const initPattern = new RegExp(`(?:^|\\W)${escapeRegex(callExpression)}\\s*;?\\s*$`, 'm');
     if (initPattern.test(content)) {
         return false;
     }

package/dist/src/core/wire-utils.d.ts

@@ -5,6 +5,21 @@ import { type AcornESTreeNode } from './ast-utils.js';
  * Rejects strings containing characters that could break out of JS strings or inject code.
  */
 export declare function validateWireName(value: string, label: string): void;
+/**
+ * Coerces an init/destroy expression into a function call by appending `()`
+ * when the caller passed a bare property chain. Idempotent: an expression
+ * already ending in `()` is returned unchanged, so operators can pass either
+ * `EvalStartup.init` or `EvalStartup.init()` and get the same wired output.
+ *
+ * Motivation (eval finding 8): `validateWireName` accepts both shapes, but
+ * the generated block interpolated the expression verbatim inside
+ * `${expression};`. When a caller passed `EvalStartup.init`, the emitted
+ * code was `EvalStartup.init;` — a plain property reference that never
+ * invoked the lifecycle hook. The symptom was silent: `wire` reported
+ * success and the browser-init block looked plausible, but the hook
+ * never fired at runtime. Coercion at the template site closes that gap.
+ */
+export declare function coerceToCall(expression: string): string;
 /**
  * Counts net brace depth change in a single line, ignoring braces inside
  * string literals (single, double, template), line comments (`//`), and

package/dist/src/core/wire-utils.js

@@ -17,6 +17,23 @@ export function validateWireName(value, label) {
         }
     }
 }
+/**
+ * Coerces an init/destroy expression into a function call by appending `()`
+ * when the caller passed a bare property chain. Idempotent: an expression
+ * already ending in `()` is returned unchanged, so operators can pass either
+ * `EvalStartup.init` or `EvalStartup.init()` and get the same wired output.
+ *
+ * Motivation (eval finding 8): `validateWireName` accepts both shapes, but
+ * the generated block interpolated the expression verbatim inside
+ * `${expression};`. When a caller passed `EvalStartup.init`, the emitted
+ * code was `EvalStartup.init;` — a plain property reference that never
+ * invoked the lifecycle hook. The symptom was silent: `wire` reported
+ * success and the browser-init block looked plausible, but the hook
+ * never fired at runtime. Coercion at the template site closes that gap.
+ */
+export function coerceToCall(expression) {
+    return expression.endsWith('()') ? expression : `${expression}()`;
+}
 /**
  * Counts net brace depth change in a single line, ignoring braces inside
  * string literals (single, double, template), line comments (`//`), and

package/dist/src/types/commands/options.d.ts

@@ -86,6 +86,13 @@ export interface ExportOptions {
     forceUnsafe?: boolean;
     /** Exclude furnace-managed file paths from the export. */
     excludeFurnace?: boolean;
+    /**
+     * Acknowledge that the export will create cross-patch ownership overlap
+     * with existing non-superseded patches. Without this flag, `export`
+     * refuses when one or more `filesAffected` are already claimed by
+     * another patch, because the resulting queue fails `verify` immediately.
+     */
+    allowOverlap?: boolean;
 }
 /**
  * Options for the reset command.

package/package.json

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