@hominis/fireforge 0.16.5 → 0.18.0

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

@@ -5,12 +5,18 @@
  * AST-based implementation: finds onLoad() method body, locates existing
  * fireforge init blocks (TryStatements containing typeof guards), and inserts
  * after the correct position.
+ *
+ * `marker` is prepended (uppercased) to the generated comment line so the
+ * emitted block carries the patch-lint `// <MARKER>:` signature that
+ * `lintModificationComments` looks for. Otherwise the first export after
+ * `wire` trips `missing-modification-comment` on wire-generated edits —
+ * exactly the eval 1 Finding #9 regression.
  */
-export declare function addInitAST(content: string, expression: string, after?: string): string;
+export declare function addInitAST(content: string, expression: string, after?: string, marker?: string): string;
 /**
  * Legacy regex/line-based implementation preserved as fallback.
  */
-export declare function legacyAddInit(content: string, expression: string, after?: string): string;
+export declare function legacyAddInit(content: string, expression: string, after?: string, marker?: string): string;
 /**
  * Adds an init expression as the first statement(s) in gBrowserInit.onLoad()
  * in browser-init.js, after any previously-wired fireforge init blocks.
@@ -20,4 +26,4 @@ export declare function legacyAddInit(content: string, expression: string, after
  * @param after - Optional name to insert after (e.g., "MyComponent" to insert after its block)
  * @returns true if added, false if already present
  */
-export declare function addInitToBrowserInit(engineDir: string, expression: string, after?: string): Promise<boolean>;
+export declare function addInitToBrowserInit(engineDir: string, expression: string, after?: string, marker?: string): Promise<boolean>;

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

@@ -12,12 +12,24 @@ import { detectIndent, getNodeSource, parseScript } from './ast-utils.js';
 import { withParserFallback } from './parser-fallback.js';
 import { assertBraceBalancePreserved, coerceToCall, extractNameFromExpression, findInsertionAfterFireforgeBlocks, findMethodBody, findMethodBraceIndex, validateWireName, walkToTryBlockEnd, } from './wire-utils.js';
 const BROWSER_INIT_JS = 'browser/base/content/browser-init.js';
+/**
+ * Default patch-lint marker used when a caller does not supply a
+ * project-specific one. Kept as a constant so test fixtures and
+ * fallback code paths agree on the shape.
+ */
+const DEFAULT_MARKER = 'FIREFORGE:';
 /**
  * AST-based implementation: finds onLoad() method body, locates existing
  * fireforge init blocks (TryStatements containing typeof guards), and inserts
  * after the correct position.
+ *
+ * `marker` is prepended (uppercased) to the generated comment line so the
+ * emitted block carries the patch-lint `// <MARKER>:` signature that
+ * `lintModificationComments` looks for. Otherwise the first export after
+ * `wire` trips `missing-modification-comment` on wire-generated edits —
+ * exactly the eval 1 Finding #9 regression.
  */
-export function addInitAST(content, expression, after) {
+export function addInitAST(content, expression, after, marker = DEFAULT_MARKER) {
     const name = extractNameFromExpression(expression);
     // `validateWireName` accepts both `Foo.bar` and `Foo.bar()` shapes. The
     // template below interpolates the value verbatim, so a bare property
@@ -99,7 +111,7 @@ export function addInitAST(content, expression, after) {
         }
     }
     const block = [
-        `${indent}// ${name} init — must be first, before Firefox subsystem`,
+        `${indent}// ${marker} wire-init ${name} — must be first, before Firefox subsystem`,
         `${indent}// inits that reference native UI elements we hide.`,
         `${indent}try {`,
         `${indent}  if (typeof ${name} !== "undefined") {`,
@@ -115,7 +127,7 @@ export function addInitAST(content, expression, after) {
 /**
  * Legacy regex/line-based implementation preserved as fallback.
  */
-export function legacyAddInit(content, expression, after) {
+export function legacyAddInit(content, expression, after, marker = DEFAULT_MARKER) {
     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
@@ -174,7 +186,7 @@ export function legacyAddInit(content, expression, after) {
     const inner = baseIndent + '  ';
     const inner2 = inner + '  ';
     const block = [
-        `${baseIndent}// ${name} init — must be first, before Firefox subsystem`,
+        `${baseIndent}// ${marker} wire-init ${name} — must be first, before Firefox subsystem`,
         `${baseIndent}// inits that reference native UI elements we hide.`,
         `${baseIndent}try {`,
         `${inner}if (typeof ${name} !== "undefined") {`,
@@ -196,7 +208,7 @@ export function legacyAddInit(content, expression, after) {
  * @param after - Optional name to insert after (e.g., "MyComponent" to insert after its block)
  * @returns true if added, false if already present
  */
-export async function addInitToBrowserInit(engineDir, expression, after) {
+export async function addInitToBrowserInit(engineDir, expression, after, marker = DEFAULT_MARKER) {
     validateWireName(expression, 'init expression');
     const filePath = join(engineDir, BROWSER_INIT_JS);
     if (!(await pathExists(filePath))) {
@@ -212,7 +224,7 @@ export async function addInitToBrowserInit(engineDir, expression, after) {
     if (initPattern.test(content)) {
         return false;
     }
-    const { value, usedFallback } = withParserFallback(() => addInitAST(content, expression, after), () => legacyAddInit(content, expression, after), BROWSER_INIT_JS);
+    const { value, usedFallback } = withParserFallback(() => addInitAST(content, expression, after, marker), () => legacyAddInit(content, expression, after, marker), BROWSER_INIT_JS);
     if (usedFallback) {
         assertBraceBalancePreserved(content, value, BROWSER_INIT_JS);
     }

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

@@ -4,12 +4,16 @@
 /**
  * AST-based implementation: finds the last try/catch containing
  * `loadSubScript` and inserts a new try/catch block after it.
+ *
+ * The inserted block carries a `// <MARKER>: wire-subscript ...` comment
+ * so the emitted edit satisfies `lintModificationComments` (eval 1
+ * Finding #9).
  */
-export declare function addSubscriptAST(content: string, name: string): string;
+export declare function addSubscriptAST(content: string, name: string, marker?: string): string;
 /**
  * Legacy regex/line-based implementation preserved as fallback.
  */
-export declare function legacyAddSubscript(content: string, name: string): string;
+export declare function legacyAddSubscript(content: string, name: string, marker?: string): string;
 /**
  * Adds a loadSubScript entry to browser-main.js with try/catch error handling.
  *
@@ -17,4 +21,4 @@ export declare function legacyAddSubscript(content: string, name: string): strin
  * @param name - Subscript name (without .js extension)
  * @returns true if added, false if already present
  */
-export declare function addSubscriptToBrowserMain(engineDir: string, name: string): Promise<boolean>;
+export declare function addSubscriptToBrowserMain(engineDir: string, name: string, marker?: string): Promise<boolean>;

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

@@ -11,11 +11,16 @@ import { detectIndent, getNodeSource, parseScript, walkAST, } from './ast-utils.
 import { withParserFallback } from './parser-fallback.js';
 import { assertBraceBalancePreserved, findNearestTryLine, validateWireName, walkToTryBlockEnd, } from './wire-utils.js';
 const BROWSER_MAIN_JS = 'browser/base/content/browser-main.js';
+const DEFAULT_MARKER = 'FIREFORGE:';
 /**
  * AST-based implementation: finds the last try/catch containing
  * `loadSubScript` and inserts a new try/catch block after it.
+ *
+ * The inserted block carries a `// <MARKER>: wire-subscript ...` comment
+ * so the emitted edit satisfies `lintModificationComments` (eval 1
+ * Finding #9).
  */
-export function addSubscriptAST(content, name) {
+export function addSubscriptAST(content, name, marker = DEFAULT_MARKER) {
     const ast = parseScript(content);
     const ms = new MagicString(content);
     // Collect all TryStatements containing loadSubScript
@@ -58,6 +63,7 @@ export function addSubscriptAST(content, name) {
         indent = detectIndent(content, lastBrace);
     }
     const block = [
+        `${indent}// ${marker} wire-subscript ${name}`,
         `${indent}try {`,
         `${indent}  Services.scriptloader.loadSubScript("chrome://browser/content/${name}.js", this);`,
         `${indent}} catch (e) {`,
@@ -70,7 +76,7 @@ export function addSubscriptAST(content, name) {
 /**
  * Legacy regex/line-based implementation preserved as fallback.
  */
-export function legacyAddSubscript(content, name) {
+export function legacyAddSubscript(content, name, marker = DEFAULT_MARKER) {
     const lines = content.split('\n');
     let lastSubScriptLine = -1;
     for (let i = 0; i < lines.length; i++) {
@@ -103,6 +109,7 @@ export function legacyAddSubscript(content, name) {
     const ind = refLine?.match(/^(\s*)/)?.[1] ?? '  ';
     const inner = ind + '  ';
     const block = [
+        `${ind}// ${marker} wire-subscript ${name}`,
         `${ind}try {`,
         `${inner}Services.scriptloader.loadSubScript("chrome://browser/content/${name}.js", this);`,
         `${ind}} catch (e) {`,
@@ -119,7 +126,7 @@ export function legacyAddSubscript(content, name) {
  * @param name - Subscript name (without .js extension)
  * @returns true if added, false if already present
  */
-export async function addSubscriptToBrowserMain(engineDir, name) {
+export async function addSubscriptToBrowserMain(engineDir, name, marker = DEFAULT_MARKER) {
     validateWireName(name, 'subscript name');
     const filePath = join(engineDir, BROWSER_MAIN_JS);
     if (!(await pathExists(filePath))) {
@@ -130,7 +137,7 @@ export async function addSubscriptToBrowserMain(engineDir, name) {
     if (content.includes(`content/${name}.js"`)) {
         return false;
     }
-    const { value, usedFallback } = withParserFallback(() => addSubscriptAST(content, name), () => legacyAddSubscript(content, name), BROWSER_MAIN_JS);
+    const { value, usedFallback } = withParserFallback(() => addSubscriptAST(content, name, marker), () => legacyAddSubscript(content, name, marker), BROWSER_MAIN_JS);
     if (usedFallback) {
         assertBraceBalancePreserved(content, value, BROWSER_MAIN_JS);
     }

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

@@ -73,6 +73,29 @@ export interface PatchMetadata {
      * renamed or removed.
      */
     lintIgnore?: string[];
+    /**
+     * Optional per-patch threshold-tier override for the `large-patch-lines`
+     * rule. Exists for branding patches that must touch a small number of
+     * cross-cutting registration files alongside `browser/branding/<name>/`
+     * (notably `browser/moz.configure` to register the new branding flavor
+     * with the top-level configure). The narrow auto-detect allowlist in
+     * `isBrandingOnlyPatch` covers the canonical shape, but a fork whose
+     * branding patch also touches an unlisted sibling (for example a
+     * `browser/themes/<name>/` override or a vendor-specific icon
+     * resource) falls through to the general tier and trips the hard
+     * limit on what is legitimately one branding diff.
+     *
+     * Declaring `tier: "branding"` here forces the branding thresholds
+     * (notice 3000 / warning 8000 / error 20000) regardless of
+     * `filesAffected`. The tier is the weaker claim than test — a patch
+     * of all-tests still lands in the test tier even if this field is
+     * set, because the test-tier thresholds are already more permissive
+     * and a test that is also branding-shaped is vanishingly rare.
+     *
+     * Only `"branding"` is currently recognised. Unknown values are
+     * rejected by the manifest validator, not silently stripped.
+     */
+    tier?: 'branding';
 }
 /**
  * Schema for patches/patches.json file.

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

@@ -102,6 +102,15 @@ export interface FurnaceConfig {
     tokenPrefix?: string;
     /** Custom properties allowed even though they don't match tokenPrefix (e.g. ["--background-color-box"]) */
     tokenAllowlist?: string[];
+    /**
+     * CSS custom-property prefixes that identify upstream / platform
+     * variables the fork does not own. `token coverage` counts matches
+     * as `allowlisted` rather than `unknown` so a copied upstream
+     * baseline doesn't drag fork-owned coverage percentages down.
+     * Defaults to `['--moz-']` when unset. Pass an explicit empty array
+     * to restore the pre-0.18.0 strict contract.
+     */
+    platformPrefixes?: string[];
     /**
      * Custom properties used as runtime state channels — written and read by the
      * component itself (e.g. per-frame camera/tile positions) rather than

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

@@ -76,6 +76,13 @@ export declare class ParsedRecord {
      * @throws Error if the field is missing or not an array of strings
      */
     stringArray(key: string): string[];
+    /**
+     * Extracts an optional array-of-strings field.
+     * @param key - Field name
+     * @returns The string array (fresh copy) or undefined when absent
+     * @throws Error if the field is present but not an array of strings
+     */
+    optionalStringArray(key: string): string[] | undefined;
     /**
      * Extracts a required nested object field.
      * @param key - Field name

package/dist/src/utils/parse.js

@@ -142,6 +142,21 @@ export class ParsedRecord {
         }
         return [...value];
     }
+    /**
+     * Extracts an optional array-of-strings field.
+     * @param key - Field name
+     * @returns The string array (fresh copy) or undefined when absent
+     * @throws Error if the field is present but not an array of strings
+     */
+    optionalStringArray(key) {
+        const value = this.#data[key];
+        if (value === undefined)
+            return undefined;
+        if (!isArray(value) || !value.every(isString)) {
+            throw new Error(`${this.#label}.${key} must be an array of strings`);
+        }
+        return [...value];
+    }
     /**
      * Extracts a required nested object field.
      * @param key - Field name

package/package.json

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