@hominis/fireforge 0.10.1 → 0.11.1

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

@@ -7,16 +7,18 @@ import { PatchError } from '../errors/patch.js';
 import { readText } from '../utils/fs.js';
 import { isNewFileInPatch, parseHunksForFile } from './patch-parse.js';
 /**
- * Extracts the complete file content from a "new file" patch.
- * When targetFile is provided, only extracts content for that file
- * (required for multi-file patches).
- * @param patchPath - Path to the patch file
+ * Extracts the complete file content from a "new file" patch given a raw
+ * diff string already in memory. Callers with a patch file path should
+ * prefer {@link extractNewFileContent}; this helper exists for code paths
+ * that already hold the diff (e.g. the in-flight export planner) and do
+ * not want to round-trip through the filesystem.
+ *
+ * @param diff - Raw unified-diff content
  * @param targetFile - Optional target file to scope extraction to
  * @returns The file content that the patch would create
  */
-export async function extractNewFileContent(patchPath, targetFile) {
-    const content = await readText(patchPath);
-    const lines = content.split('\n');
+export function extractNewFileContentFromDiff(diff, targetFile) {
+    const lines = diff.split('\n');
     const contentLines = [];
     let inHunk = false;
     let inTargetFile = !targetFile; // If no targetFile, accept all sections
@@ -60,6 +62,18 @@ export async function extractNewFileContent(patchPath, targetFile) {
     const result = contentLines.join('\n');
     return hasNoNewlineMarker ? result : result + '\n';
 }
+/**
+ * Extracts the complete file content from a "new file" patch.
+ * When targetFile is provided, only extracts content for that file
+ * (required for multi-file patches).
+ * @param patchPath - Path to the patch file
+ * @param targetFile - Optional target file to scope extraction to
+ * @returns The file content that the patch would create
+ */
+export async function extractNewFileContent(patchPath, targetFile) {
+    const content = await readText(patchPath);
+    return extractNewFileContentFromDiff(content, targetFile);
+}
 /**
  * Applies a patch's changes to content.
  * @param content - Original content (null for new files)

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

@@ -9,6 +9,7 @@ import { escapeRegex } from '../utils/regex.js';
 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';
 /** 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`;
@@ -290,7 +291,27 @@ async function addTokenToCSS(engineDir, options, tokensCssPath) {
     return true;
 }
 /**
- * Adds a token to the documentation markdown file.
+ * Strips surrounding backticks from a cell, if present. Token cells are
+ * usually wrapped in inline code fences (`` `--foo` ``) and the parser
+ * returns them verbatim.
+ */
+function stripInlineCode(cell) {
+    const trimmed = cell.trim();
+    if (trimmed.startsWith('`') && trimmed.endsWith('`') && trimmed.length >= 2) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+/**
+ * Adds a token row to the main token table, the unmapped table (for
+ * literal values), and bumps the mode count table. Each sub-update runs
+ * against a freshly parsed view of the document so that splice indices
+ * stay valid as rewrites are layered.
+ *
+ * The old implementation walked `split('\n')` by hand, detected rows by
+ * literal `|`-prefix, and used a whitespace-sensitive regex to increment
+ * the mode count. Switching to {@link findTableByColumns} and
+ * {@link updateCellByKey} removes those formatting traps.
  */
 async function addTokenToDocs(engineDir, options) {
     const filePath = join(engineDir, '..', TOKENS_DOC);
@@ -298,90 +319,67 @@ async function addTokenToDocs(engineDir, options) {
         // Docs file is optional
         return { docsAdded: false, unmappedAdded: false, countUpdated: false };
     }
-    let content = await readText(filePath);
-    const lines = content.split('\n');
+    const originalContent = await readText(filePath);
+    let lines = originalContent.split('\n');
     let docsAdded = false;
     let unmappedAdded = false;
     let countUpdated = false;
     const annotation = getModeAnnotation(options.mode, options.value);
     const isLiteral = !options.value.startsWith('var(');
-    // Find the category group in the token table
-    // Look for a row containing the category name, then find the last row in that group
-    let categoryRowStart = -1;
-    let lastRowInCategory = -1;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        // Table rows start with |
-        if (line.startsWith('|') && line.includes(options.category)) {
-            categoryRowStart = i;
-            lastRowInCategory = i;
-        }
-        else if (categoryRowStart !== -1 &&
-            line.startsWith('|') &&
-            !line.startsWith('|--') &&
-            !line.startsWith('| Token')) {
-            // Check if this row still belongs to the same category (no category cell or empty category)
-            const cells = line.split('|').map((c) => c.trim());
-            // If the first data cell (after leading empty) is empty, it belongs to same category
-            if (cells[1] === '' || !cells[1]) {
-                lastRowInCategory = i;
+    const mapsTo = isLiteral ? '—' : options.value.replace(/var\(([^)]+)\)/, '$1');
+    const tokenCell = `\`${options.tokenName}\``;
+    const valueCell = `\`${options.value}\``;
+    // --- Main token table: Category | Token | Value | Maps to | Mode ---
+    const mainTable = findTableByColumns(lines, ['Category', 'Token', 'Value', 'Mode']);
+    if (mainTable) {
+        // The doc convention allows the Category cell to be blank on
+        // continuation rows that belong to the previous category. Group rows
+        // by carrying the last non-empty Category value forward.
+        let lastGroupRowIndex = -1;
+        let currentCategory = '';
+        for (let i = 0; i < mainTable.rows.length; i++) {
+            const row = mainTable.rows[i];
+            if (!row)
+                continue;
+            const cell = row[0]?.trim() ?? '';
+            if (cell) {
+                currentCategory = cell;
             }
-            else {
-                break;
+            if (currentCategory === options.category) {
+                lastGroupRowIndex = i;
             }
         }
-        else if (categoryRowStart !== -1 && !line.startsWith('|')) {
-            break;
+        if (lastGroupRowIndex !== -1) {
+            insertRow(mainTable, ['', tokenCell, valueCell, mapsTo, annotation], lastGroupRowIndex + 1);
+            lines = rewriteTableRows(lines, mainTable);
+            docsAdded = true;
         }
     }
-    if (lastRowInCategory !== -1) {
-        // Insert a new row after the last row in this category
-        const mapsTo = isLiteral ? '—' : options.value.replace(/var\(([^)]+)\)/, '$1');
-        const newRow = `| | \`${options.tokenName}\` | \`${options.value}\` | ${mapsTo} | ${annotation} |`;
-        lines.splice(lastRowInCategory + 1, 0, newRow);
-        docsAdded = true;
-    }
-    // If the value is a literal (not a var() reference), add to unmapped table
+    // --- Unmapped table: populated for literal (non-var()) values only ---
     if (isLiteral) {
-        let unmappedTableStart = -1;
-        for (let i = 0; i < lines.length; i++) {
-            const line = lines[i] ?? '';
-            if (/not yet mapped/i.test(line) || /unmapped/i.test(line)) {
-                unmappedTableStart = i;
-                break;
-            }
-        }
-        if (unmappedTableStart !== -1) {
-            // Find the last row of the unmapped table
-            let lastUnmappedRow = unmappedTableStart;
-            for (let i = unmappedTableStart + 1; i < lines.length; i++) {
-                const line = lines[i] ?? '';
-                if (line.startsWith('|') && !line.startsWith('|--') && !line.startsWith('| Token')) {
-                    lastUnmappedRow = i;
-                }
-                else if (!line.startsWith('|')) {
-                    break;
-                }
-            }
-            const unmappedRow = `| \`${options.tokenName}\` | \`${options.value}\` | ${options.description ?? ''} |`;
-            lines.splice(lastUnmappedRow + 1, 0, unmappedRow);
+        const unmappedTable = findTableAfterHeading(lines, /not yet mapped|unmapped/i);
+        if (unmappedTable) {
+            insertRow(unmappedTable, [tokenCell, valueCell, options.description ?? ''], unmappedTable.rows.length);
+            lines = rewriteTableRows(lines, unmappedTable);
             unmappedAdded = true;
         }
     }
-    // Update dark/light mode behavior count table
-    const modeCountPattern = new RegExp(`\\|\\s*${options.mode}\\s*\\|\\s*(\\d+)\\s*\\|`);
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        const match = modeCountPattern.exec(line);
-        if (match) {
-            const oldCount = parseInt(match[1] ?? '0', 10);
-            lines[i] = line.replace(modeCountPattern, `| ${options.mode} | ${oldCount + 1} |`);
-            countUpdated = true;
-            break;
+    // --- Mode behavior count table: Mode | Count ---
+    const modeTable = findTableByColumns(lines, ['Mode', 'Count']);
+    if (modeTable) {
+        const modeIndex = modeTable.headers.indexOf('Mode');
+        const countIndex = modeTable.headers.indexOf('Count');
+        const existing = modeTable.rows.find((row) => stripInlineCode(row[modeIndex] ?? '') === options.mode);
+        if (existing) {
+            const oldCount = parseInt(existing[countIndex] ?? '0', 10);
+            const updated = updateCellByKey(modeTable, 'Mode', existing[modeIndex] ?? options.mode, 'Count', String((Number.isNaN(oldCount) ? 0 : oldCount) + 1));
+            if (updated) {
+                lines = rewriteTableRows(lines, modeTable);
+                countUpdated = true;
+            }
         }
     }
-    content = lines.join('\n');
-    await writeText(filePath, content);
+    await writeText(filePath, lines.join('\n'));
     return { docsAdded, unmappedAdded, countUpdated };
 }
 //# sourceMappingURL=token-manager.js.map

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 { extractNameFromExpression, findMethodBody, findMethodBraceIndex, validateWireName, } from './wire-utils.js';
+import { assertBraceBalancePreserved, 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
@@ -57,7 +57,7 @@ export function legacyAddDestroy(content, expression) {
     const name = extractNameFromExpression(expression);
     const lines = content.split('\n');
     const destroyRegex = /\b(?:async\s+)?(onUnload|uninit)\s*[(:]/;
-    const found = findMethodBraceIndex(lines, destroyRegex);
+    const found = findMethodBraceIndex(lines, destroyRegex, { requireBrace: true });
     if (!found) {
         throw new GeneralError('Could not find "onUnload" or "uninit" method in browser-init.js.\n' +
             'FireForge was looking for a signature matching: \\b(?:async\\s+)?(onUnload|uninit)\\s*[(:]');
@@ -96,7 +96,10 @@ export async function addDestroyToBrowserInit(engineDir, expression) {
     if (destroyPattern.test(content)) {
         return false;
     }
-    const { value } = withParserFallback(() => addDestroyAST(content, expression), () => legacyAddDestroy(content, expression), BROWSER_INIT_JS);
+    const { value, usedFallback } = withParserFallback(() => addDestroyAST(content, expression), () => legacyAddDestroy(content, expression), BROWSER_INIT_JS);
+    if (usedFallback) {
+        assertBraceBalancePreserved(content, value, BROWSER_INIT_JS);
+    }
     await writeText(filePath, value);
     return true;
 }

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 { extractNameFromExpression, findInsertionAfterFireforgeBlocks, findMethodBody, findMethodBraceIndex, validateWireName, walkToTryBlockEnd, } from './wire-utils.js';
+import { assertBraceBalancePreserved, 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
@@ -113,7 +113,7 @@ export function legacyAddInit(content, expression, after) {
     const name = extractNameFromExpression(expression);
     const lines = content.split('\n');
     const onLoadRegex = /\b(?:async\s+)?onLoad\s*[(:]/;
-    const found = findMethodBraceIndex(lines, onLoadRegex);
+    const found = findMethodBraceIndex(lines, onLoadRegex, { requireBrace: true });
     if (!found) {
         throw new GeneralError('Could not find "onLoad" method in browser-init.js.\n' +
             'FireForge was looking for a signature matching: \\b(?:async\\s+)?onLoad\\s*[(:]');
@@ -138,7 +138,10 @@ export function legacyAddInit(content, expression, after) {
                         break;
                     }
                 }
-                insertIndex = walkToTryBlockEnd(lines, tryStart);
+                insertIndex = walkToTryBlockEnd(lines, tryStart, {
+                    strict: true,
+                    context: BROWSER_INIT_JS,
+                });
                 located = true;
                 break;
             }
@@ -194,7 +197,10 @@ export async function addInitToBrowserInit(engineDir, expression, after) {
     if (initPattern.test(content)) {
         return false;
     }
-    const { value } = withParserFallback(() => addInitAST(content, expression, after), () => legacyAddInit(content, expression, after), BROWSER_INIT_JS);
+    const { value, usedFallback } = withParserFallback(() => addInitAST(content, expression, after), () => legacyAddInit(content, expression, after), BROWSER_INIT_JS);
+    if (usedFallback) {
+        assertBraceBalancePreserved(content, value, BROWSER_INIT_JS);
+    }
     await writeText(filePath, value);
     return true;
 }

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

@@ -9,7 +9,7 @@ import { BuildError } from '../errors/build.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { detectIndent, getNodeSource, parseScript, walkAST, } from './ast-utils.js';
 import { withParserFallback } from './parser-fallback.js';
-import { findNearestTryLine, validateWireName, walkToTryBlockEnd } from './wire-utils.js';
+import { assertBraceBalancePreserved, findNearestTryLine, validateWireName, walkToTryBlockEnd, } from './wire-utils.js';
 const BROWSER_MAIN_JS = 'browser/base/content/browser-main.js';
 /**
  * AST-based implementation: finds the last try/catch containing
@@ -81,7 +81,10 @@ export function legacyAddSubscript(content, name) {
     let insertIndex;
     if (lastSubScriptLine !== -1) {
         const tryStart = findNearestTryLine(lines, lastSubScriptLine - 1, -1);
-        insertIndex = tryStart !== -1 ? walkToTryBlockEnd(lines, tryStart) : lastSubScriptLine + 1;
+        insertIndex =
+            tryStart !== -1
+                ? walkToTryBlockEnd(lines, tryStart, { strict: true, context: BROWSER_MAIN_JS })
+                : lastSubScriptLine + 1;
     }
     else {
         insertIndex = lines.length;
@@ -127,7 +130,10 @@ export async function addSubscriptToBrowserMain(engineDir, name) {
     if (content.includes(`content/${name}.js"`)) {
         return false;
     }
-    const { value } = withParserFallback(() => addSubscriptAST(content, name), () => legacyAddSubscript(content, name), BROWSER_MAIN_JS);
+    const { value, usedFallback } = withParserFallback(() => addSubscriptAST(content, name), () => legacyAddSubscript(content, name), BROWSER_MAIN_JS);
+    if (usedFallback) {
+        assertBraceBalancePreserved(content, value, BROWSER_MAIN_JS);
+    }
     await writeText(filePath, value);
     return true;
 }

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

@@ -51,9 +51,20 @@ export declare function tokenizeXhtml(lines: string[]): XhtmlToken[];
  * Finds the line index of a method signature matching `pattern`, then
  * advances to the line containing the opening brace.
  *
- * @returns `{ methodLine, braceIndex }`, or `null` if the pattern is not found.
+ * By default this helper is tolerant: when no `{` is found anywhere after
+ * the signature, it still returns `braceIndex: methodLine` — which is the
+ * correct answer when the signature and body brace live on the same line,
+ * but is ambiguous when the method is abstract or truncated. Opt into
+ * stricter behaviour by passing `requireBrace: true`; the function will
+ * return `null` instead of guessing, letting the caller surface a clean
+ * {@link ParserFallbackError} rather than inserting into a wrong offset.
+ *
+ * @returns `{ methodLine, braceIndex }`, or `null` if the pattern is not
+ *   found (or, under `requireBrace`, no brace follows the signature).
  */
-export declare function findMethodBraceIndex(lines: string[], pattern: RegExp): {
+export declare function findMethodBraceIndex(lines: string[], pattern: RegExp, options?: {
+    requireBrace?: boolean;
+}): {
     methodLine: number;
     braceIndex: number;
 } | null;
@@ -61,10 +72,46 @@ export declare function findMethodBraceIndex(lines: string[], pattern: RegExp):
  * Starting from `startLine`, walks lines using {@link countBraceDepth}
  * until the brace depth returns to zero (i.e., the enclosing block closes).
  *
- * @returns The line index *after* the closing brace, or `startLine + 1` if
- *   the block never closes (defensive).
+ * Default behaviour is defensive — if the block never closes, the helper
+ * returns `startLine + 1` so a single malformed file does not stop the
+ * entire fallback path. Pass `{ strict: true }` to opt into failing loudly
+ * with a {@link ParserFallbackError} instead; new callers should prefer
+ * strict mode so silent mis-insertions surface as the fallback refusing
+ * to touch the file.
+ *
+ * @param lines - The full file split by newline
+ * @param startLine - Line index of the `try {` (or other block opener) to walk
+ * @param options - Pass `{ strict: true }` to throw when the block never closes
+ * @returns The line index *after* the closing brace
+ */
+export declare function walkToTryBlockEnd(lines: string[], startLine: number, options?: {
+    strict?: boolean;
+    context?: string;
+}): number;
+/**
+ * Scans the entire file and returns the net brace balance so callers can
+ * assert that a legacy fallback mutation did not silently introduce or
+ * drop a `{` / `}`. The helper reuses {@link countBraceDepth} so strings,
+ * comments, and regex literals are handled consistently with the walker.
+ *
+ * @param content - Full file contents (will be split by newline)
+ * @returns The net depth across the file (`opens - closes`) and a
+ *   convenience `balanced` flag equal to `depth === 0`.
+ */
+export declare function computeFileBraceBalance(content: string): {
+    depth: number;
+    balanced: boolean;
+};
+/**
+ * Round-trip guard used after a legacy fallback mutation: if the file's
+ * net brace balance drifts between `before` and `after`, something went
+ * wrong and the fallback is refusing to write a corrupted file. Expects
+ * the delta to be exactly zero — wire fallbacks only insert whole
+ * try/catch blocks, which always contribute equal opens and closes.
+ *
+ * @throws {@link ParserFallbackError} when the balance delta is non-zero.
  */
-export declare function walkToTryBlockEnd(lines: string[], startLine: number): number;
+export declare function assertBraceBalancePreserved(before: string, after: string, context: string): void;
 /**
  * Looks backward from `fromLine` (exclusive) to find the nearest `try {`
  * line.  If nothing is found searching backward, also searches forward.

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

@@ -1,4 +1,4 @@
-import { GeneralError } from '../errors/base.js';
+import { GeneralError, ParserFallbackError } from '../errors/base.js';
 import { walkAST } from './ast-utils.js';
 /**
  * Validates a name for safe interpolation into generated JavaScript string literals.
@@ -158,9 +158,18 @@ export function tokenizeXhtml(lines) {
  * Finds the line index of a method signature matching `pattern`, then
  * advances to the line containing the opening brace.
  *
- * @returns `{ methodLine, braceIndex }`, or `null` if the pattern is not found.
+ * By default this helper is tolerant: when no `{` is found anywhere after
+ * the signature, it still returns `braceIndex: methodLine` — which is the
+ * correct answer when the signature and body brace live on the same line,
+ * but is ambiguous when the method is abstract or truncated. Opt into
+ * stricter behaviour by passing `requireBrace: true`; the function will
+ * return `null` instead of guessing, letting the caller surface a clean
+ * {@link ParserFallbackError} rather than inserting into a wrong offset.
+ *
+ * @returns `{ methodLine, braceIndex }`, or `null` if the pattern is not
+ *   found (or, under `requireBrace`, no brace follows the signature).
  */
-export function findMethodBraceIndex(lines, pattern) {
+export function findMethodBraceIndex(lines, pattern, options) {
     let methodLine = -1;
     for (let i = 0; i < lines.length; i++) {
         if (pattern.test(lines[i] ?? '')) {
@@ -171,22 +180,36 @@ export function findMethodBraceIndex(lines, pattern) {
     if (methodLine === -1)
         return null;
     let braceIndex = methodLine;
+    let braceFound = false;
     for (let i = methodLine; i < lines.length; i++) {
         if (lines[i]?.includes('{')) {
             braceIndex = i;
+            braceFound = true;
             break;
         }
     }
+    if (!braceFound && options?.requireBrace) {
+        return null;
+    }
     return { methodLine, braceIndex };
 }
 /**
  * Starting from `startLine`, walks lines using {@link countBraceDepth}
  * until the brace depth returns to zero (i.e., the enclosing block closes).
  *
- * @returns The line index *after* the closing brace, or `startLine + 1` if
- *   the block never closes (defensive).
+ * Default behaviour is defensive — if the block never closes, the helper
+ * returns `startLine + 1` so a single malformed file does not stop the
+ * entire fallback path. Pass `{ strict: true }` to opt into failing loudly
+ * with a {@link ParserFallbackError} instead; new callers should prefer
+ * strict mode so silent mis-insertions surface as the fallback refusing
+ * to touch the file.
+ *
+ * @param lines - The full file split by newline
+ * @param startLine - Line index of the `try {` (or other block opener) to walk
+ * @param options - Pass `{ strict: true }` to throw when the block never closes
+ * @returns The line index *after* the closing brace
  */
-export function walkToTryBlockEnd(lines, startLine) {
+export function walkToTryBlockEnd(lines, startLine, options) {
     let depth = 0;
     let inBlock = false;
     for (let j = startLine; j < lines.length; j++) {
@@ -197,8 +220,48 @@ export function walkToTryBlockEnd(lines, startLine) {
             return j + 1;
         }
     }
+    if (options?.strict) {
+        throw new ParserFallbackError(`Block starting at line ${startLine + 1} never closes — fallback parser refuses to insert`, options.context);
+    }
     return startLine + 1;
 }
+/**
+ * Scans the entire file and returns the net brace balance so callers can
+ * assert that a legacy fallback mutation did not silently introduce or
+ * drop a `{` / `}`. The helper reuses {@link countBraceDepth} so strings,
+ * comments, and regex literals are handled consistently with the walker.
+ *
+ * @param content - Full file contents (will be split by newline)
+ * @returns The net depth across the file (`opens - closes`) and a
+ *   convenience `balanced` flag equal to `depth === 0`.
+ */
+export function computeFileBraceBalance(content) {
+    const lines = content.split('\n');
+    let depth = 0;
+    let inBlock = false;
+    for (const line of lines) {
+        const r = countBraceDepth(line, inBlock);
+        depth += r.depth;
+        inBlock = r.inBlockComment;
+    }
+    return { depth, balanced: depth === 0 };
+}
+/**
+ * Round-trip guard used after a legacy fallback mutation: if the file's
+ * net brace balance drifts between `before` and `after`, something went
+ * wrong and the fallback is refusing to write a corrupted file. Expects
+ * the delta to be exactly zero — wire fallbacks only insert whole
+ * try/catch blocks, which always contribute equal opens and closes.
+ *
+ * @throws {@link ParserFallbackError} when the balance delta is non-zero.
+ */
+export function assertBraceBalancePreserved(before, after, context) {
+    const beforeDepth = computeFileBraceBalance(before).depth;
+    const afterDepth = computeFileBraceBalance(after).depth;
+    if (beforeDepth !== afterDepth) {
+        throw new ParserFallbackError(`Brace balance drifted from ${beforeDepth} to ${afterDepth} after fallback mutation; refusing to write`, context);
+    }
+}
 /**
  * Looks backward from `fromLine` (exclusive) to find the nearest `try {`
  * line.  If nothing is found searching backward, also searches forward.

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

@@ -25,6 +25,26 @@ export declare abstract class FireForgeError extends Error {
 export declare class GeneralError extends FireForgeError {
     readonly code: 1;
 }
+/**
+ * Raised when a legacy regex/brace-depth fallback parser decides it
+ * cannot safely perform its mutation — e.g. because a block it expected
+ * to walk never closes, because the inserted result fails a round-trip
+ * brace balance check, or because an expected pattern is missing.
+ *
+ * Dedicated subclass (rather than raw GeneralError) so callers and tests
+ * can distinguish "the fallback refused to corrupt this file" from other
+ * failure modes, and so {@link withParserFallback} callers can opt into
+ * re-throwing fallback refusals instead of silently swallowing them.
+ */
+export declare class ParserFallbackError extends FireForgeError {
+    /** Filename or logical context where the fallback ran (e.g. `browser-init.js`). */
+    readonly context?: string | undefined;
+    readonly code: 1;
+    constructor(message: string, 
+    /** Filename or logical context where the fallback ran (e.g. `browser-init.js`). */
+    context?: string | undefined, cause?: unknown);
+    get userMessage(): string;
+}
 /**
  * Error thrown when a command-line argument is invalid.
  */

package/dist/src/errors/base.js

@@ -36,6 +36,30 @@ export class FireForgeError extends Error {
 export class GeneralError extends FireForgeError {
     code = ExitCode.GENERAL_ERROR;
 }
+/**
+ * Raised when a legacy regex/brace-depth fallback parser decides it
+ * cannot safely perform its mutation — e.g. because a block it expected
+ * to walk never closes, because the inserted result fails a round-trip
+ * brace balance check, or because an expected pattern is missing.
+ *
+ * Dedicated subclass (rather than raw GeneralError) so callers and tests
+ * can distinguish "the fallback refused to corrupt this file" from other
+ * failure modes, and so {@link withParserFallback} callers can opt into
+ * re-throwing fallback refusals instead of silently swallowing them.
+ */
+export class ParserFallbackError extends FireForgeError {
+    context;
+    code = ExitCode.GENERAL_ERROR;
+    constructor(message, 
+    /** Filename or logical context where the fallback ran (e.g. `browser-init.js`). */
+    context, cause) {
+        super(message, cause);
+        this.context = context;
+    }
+    get userMessage() {
+        return this.context ? `${this.message} (in ${this.context})` : this.message;
+    }
+}
 /**
  * Error thrown when a command-line argument is invalid.
  */

package/dist/src/errors/furnace.js

@@ -15,7 +15,13 @@ export class FurnaceError extends FireForgeError {
         let msg = this.component
             ? `Furnace Error (${this.component}): ${this.message}`
             : `Furnace Error: ${this.message}`;
-        msg += '\n\nRun "fireforge furnace validate" to diagnose issues.';
+        msg += '\n\nTo fix this:\n';
+        msg += '  1. Check the error message above for specifics\n';
+        // Avoid circular advice when the error is thrown during validation itself.
+        if (!this.message.includes('furnace validate')) {
+            msg += '  2. Run "fireforge furnace validate" to diagnose issues\n';
+        }
+        msg += `  ${this.message.includes('furnace validate') ? '2' : '3'}. Use "fireforge doctor --repair-furnace" if state is inconsistent`;
         return msg;
     }
 }

package/dist/src/errors/rebase.js

@@ -7,7 +7,12 @@ import { ExitCode } from './codes.js';
 export class RebaseError extends FireForgeError {
     code = ExitCode.PATCH_ERROR;
     get userMessage() {
-        return `Rebase Error: ${this.message}`;
+        let msg = `Rebase Error: ${this.message}`;
+        msg += '\n\nTo fix this:\n';
+        msg += '  1. Check the error message above for specifics\n';
+        msg += '  2. Use "fireforge rebase --continue" to resume an interrupted rebase\n';
+        msg += '  3. Use "fireforge rebase --abort" to cancel and restore engine state';
+        return msg;
     }
 }
 /**

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

@@ -1,6 +1,6 @@
 /**
  * Re-exports all command-related types from focused sub-modules.
  */
-export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRemoveOptions, GlobalOptions, ImportOptions, PackageOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
+export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceSyncOptions, FurnaceValidateOptions, GlobalOptions, ImportOptions, PackageOptions, PatchDeleteOptions, PatchReorderOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
 export type { ImportSummary, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchMetadata, PatchResult, } from './patches.js';
 export type { DoctorCheck, ProjectStatus, TokenCoverageFileEntry, TokenCoverageReport, } from './project.js';