@hominis/fireforge 0.9.0

package/dist/src/core/manifest-helpers.js

@@ -0,0 +1,96 @@
+/**
+ * Inserts a line into an array of lines in alphabetical order within a
+ * specified range. The comparison key is extracted from each line.
+ *
+ * @returns Object with insertIndex and previousEntry
+ */
+export function findAlphabeticalPosition(lines, startLine, endLine, newKey, extractKey) {
+    // Check if existing entries are actually sorted; if not, append at end
+    const existingKeys = [];
+    for (let i = startLine; i < endLine; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        const key = extractKey(line);
+        if (key !== undefined) {
+            existingKeys.push(key);
+        }
+    }
+    const isSorted = existingKeys.every((k, idx) => idx === 0 || k.localeCompare(existingKeys[idx - 1] ?? '') >= 0);
+    if (!isSorted) {
+        return { insertIndex: endLine, previousEntry: undefined };
+    }
+    let insertIndex = endLine;
+    let previousEntry;
+    for (let i = startLine; i < endLine; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        const key = extractKey(line);
+        if (key === undefined)
+            continue;
+        if (key > newKey) {
+            insertIndex = i;
+            break;
+        }
+        insertIndex = i + 1;
+        previousEntry = line.trim();
+    }
+    return { insertIndex, previousEntry };
+}
+/**
+ * Find alphabetical position within a tokenized jar.mn section.
+ */
+export function findAlphabeticalTokenPosition(tokens, sectionTargetPattern, newKey) {
+    // Find entry tokens in the section matching the pattern
+    const sectionEntries = tokens.filter((t) => t.type === 'entry' && t.parsed && sectionTargetPattern.test(t.parsed.target));
+    let insertLineIndex;
+    let previousEntry;
+    if (sectionEntries.length === 0) {
+        // Empty section: find the section header and insert after it
+        const headerToken = tokens.find((t) => t.type === 'header' || (t.type === 'directive' && sectionTargetPattern.test(t.raw)));
+        if (headerToken) {
+            return { insertIndex: headerToken.lineIndex + 1, previousEntry: undefined };
+        }
+        return { insertIndex: -1, previousEntry: undefined };
+    }
+    // Default: after the last section entry
+    insertLineIndex = (sectionEntries[sectionEntries.length - 1]?.lineIndex ?? 0) + 1;
+    for (const entry of sectionEntries) {
+        if (!entry.parsed)
+            continue;
+        const match = sectionTargetPattern.exec(entry.parsed.target);
+        const key = match?.[1] ?? entry.parsed.target;
+        if (key > newKey) {
+            insertLineIndex = entry.lineIndex;
+            break;
+        }
+        insertLineIndex = entry.lineIndex + 1;
+        previousEntry = entry.raw.trim();
+    }
+    return { insertIndex: insertLineIndex, previousEntry };
+}
+/**
+ * Find alphabetical position within tokenized moz.build list items.
+ */
+export function findAlphabeticalMozBuildPosition(tokens, newKey) {
+    const items = tokens.filter((t) => t.type === 'list-item');
+    if (items.length === 0) {
+        // Insert after list-open
+        const openToken = tokens.find((t) => t.type === 'list-open');
+        return { insertIndex: (openToken?.lineIndex ?? 0) + 1, previousEntry: undefined };
+    }
+    let insertLineIndex = (items[items.length - 1]?.lineIndex ?? 0) + 1;
+    let previousEntry;
+    for (const item of items) {
+        const key = item.parsed?.value ?? '';
+        if (key > newKey) {
+            insertLineIndex = item.lineIndex;
+            break;
+        }
+        insertLineIndex = item.lineIndex + 1;
+        previousEntry = item.raw.trim();
+    }
+    return { insertIndex: insertLineIndex, previousEntry };
+}
+//# sourceMappingURL=manifest-helpers.js.map

package/dist/src/core/manifest-register.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Manifest registration barrel — re-exports all registration targets
+ * and provides the shared RegisterResult interface.
+ */
+/**
+ * Result of a manifest registration operation.
+ */
+export interface RegisterResult {
+    /** The manifest file that was modified */
+    manifest: string;
+    /** The entry that was inserted */
+    entry: string;
+    /** The entry after which the new entry was inserted (for user display) */
+    previousEntry?: string | undefined;
+    /** Whether the entry already existed (skipped) */
+    skipped: boolean;
+    /** Whether --after target was not found and fell back to alphabetical */
+    afterFallback?: boolean | undefined;
+}
+export { registerBrowserContent } from './register-browser-content.js';
+export { registerFireForgeModule } from './register-module.js';
+export { registerSharedCSS } from './register-shared-css.js';
+export { deregisterTestManifest, registerTestManifest } from './register-test-manifest.js';
+/**
+ * Registers a widget file (mjs or css) in toolkit/content/jar.mn.
+ *
+ * Entry format (3-space indent):
+ *    content/global/elements/{file}  (widgets/{tagName}/{file})
+ */
+export declare function registerToolkitWidget(engineDir: string, tagName: string, fileName: string, dryRun?: boolean): Promise<RegisterResult>;

package/dist/src/core/manifest-register.js

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Manifest registration barrel — re-exports all registration targets
+ * and provides the shared RegisterResult interface.
+ */
+import { join } from 'node:path';
+import { GeneralError } from '../errors/base.js';
+import { pathExists, readText, writeText } from '../utils/fs.js';
+import { findAlphabeticalPosition } from './manifest-helpers.js';
+// Re-export from split modules so existing import sites continue working
+export { registerBrowserContent } from './register-browser-content.js';
+export { registerFireForgeModule } from './register-module.js';
+export { registerSharedCSS } from './register-shared-css.js';
+export { deregisterTestManifest, registerTestManifest } from './register-test-manifest.js';
+// ---------------------------------------------------------------------------
+// toolkit/content/jar.mn — widget registration
+// ---------------------------------------------------------------------------
+/**
+ * Registers a widget file (mjs or css) in toolkit/content/jar.mn.
+ *
+ * Entry format (3-space indent):
+ *    content/global/elements/{file}  (widgets/{tagName}/{file})
+ */
+export async function registerToolkitWidget(engineDir, tagName, fileName, dryRun = false) {
+    const manifest = 'toolkit/content/jar.mn';
+    const manifestPath = join(engineDir, manifest);
+    if (!(await pathExists(manifestPath))) {
+        throw new GeneralError(`Manifest not found: ${manifest}`);
+    }
+    const entry = `   content/global/elements/${fileName}  (widgets/${tagName}/${fileName})`.replace(/\\/g, '/');
+    let content = await readText(manifestPath);
+    // Idempotency check
+    if (content.includes(`content/global/elements/${fileName}`)) {
+        return { manifest, entry, skipped: true };
+    }
+    const lines = content.split('\n');
+    // Find insertion point among existing content/global/elements/ lines
+    const extractKey = (line) => {
+        const match = /^\s+content\/global\/elements\/([^\s]+)/.exec(line);
+        return match?.[1];
+    };
+    let sectionStart = -1;
+    let sectionEnd = lines.length;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        if (/^\s+content\/global\/elements\//.test(line)) {
+            if (sectionStart === -1)
+                sectionStart = i;
+            sectionEnd = i + 1;
+        }
+    }
+    if (sectionStart === -1) {
+        throw new GeneralError('Could not find content/global/elements/ section in toolkit/content/jar.mn');
+    }
+    const { insertIndex, previousEntry } = findAlphabeticalPosition(lines, sectionStart, sectionEnd, fileName, extractKey);
+    lines.splice(insertIndex, 0, entry);
+    content = lines.join('\n');
+    if (!dryRun) {
+        await writeText(manifestPath, content);
+    }
+    return { manifest, entry, previousEntry, skipped: false };
+}
+//# sourceMappingURL=manifest-register.js.map

package/dist/src/core/manifest-rules.d.ts

@@ -0,0 +1,39 @@
+import type { RegisterResult } from './manifest-register.js';
+/** Pattern rules mapping file paths to manifest types */
+export interface PatternRule {
+    /** Regex to match the file path (relative to engine/) */
+    pattern: RegExp;
+    /** Checks whether the file is already registered in its manifest */
+    isRegistered: (engineDir: string, ...args: string[]) => Promise<boolean>;
+    /** Register function */
+    register: (engineDir: string, after: string | undefined, dryRun: boolean, ...args: string[]) => Promise<RegisterResult>;
+    /** Extract arguments from the regex match */
+    extractArgs: (match: RegExpMatchArray) => string[];
+}
+/** Returns manifest registration rules for the supported engine file patterns. */
+export declare function getRules(binaryName: string): PatternRule[];
+/**
+ * Checks if a file path matches any known registrable pattern.
+ * @param filePath - Path relative to engine/
+ * @param binaryName - Binary name from fireforge.json (used for module directory)
+ * @returns True if the file matches a known registration pattern
+ */
+export declare function matchesRegistrablePattern(filePath: string, binaryName: string): boolean;
+/**
+ * Checks whether a supported registrable file is already present in its manifest.
+ *
+ * @param root - Project root directory
+ * @param filePath - Path relative to engine/
+ * @returns True if the file is already registered in its manifest
+ */
+export declare function isFileRegistered(root: string, filePath: string): Promise<boolean>;
+/**
+ * Registers a file in the appropriate build manifest.
+ *
+ * @param root - Project root directory
+ * @param filePath - Path relative to engine/
+ * @param dryRun - If true, return what would be done without writing
+ * @param after - Optional substring to place entry after (instead of alphabetical)
+ * @returns Registration result
+ */
+export declare function registerFile(root: string, filePath: string, dryRun?: boolean, after?: string): Promise<RegisterResult>;

package/dist/src/core/manifest-rules.js

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { basename, join } from 'node:path';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
+import { pathExists, readText } from '../utils/fs.js';
+import { escapeRegex } from '../utils/regex.js';
+import { getProjectPaths, loadConfig } from './config.js';
+import { registerBrowserContent, registerFireForgeModule, registerSharedCSS, registerTestManifest, registerToolkitWidget, } from './manifest-register.js';
+/** Returns manifest registration rules for the supported engine file patterns. */
+export function getRules(binaryName) {
+    const moduleDir = `browser/modules/${binaryName}`;
+    return [
+        {
+            pattern: /^browser\/themes\/shared\/(.+\.css)$/,
+            isRegistered: (engineDir, fileName) => isSharedCSSRegistered(engineDir, fileName),
+            register: (engineDir, after, dryRun, fileName) => registerSharedCSS(engineDir, fileName, after, dryRun),
+            extractArgs: (m) => [m[1] ?? ''],
+        },
+        {
+            pattern: /^browser\/base\/content\/(.+\.(?:js|mjs))$/,
+            isRegistered: (engineDir, fileName) => isBrowserContentRegistered(engineDir, fileName),
+            register: (engineDir, after, dryRun, fileName) => registerBrowserContent(engineDir, fileName, after, undefined, dryRun),
+            extractArgs: (m) => [m[1] ?? ''],
+        },
+        {
+            pattern: /^browser\/base\/content\/test\/([^/]+)\/browser\.toml$/,
+            isRegistered: (_engineDir, testDir) => isTestManifestRegistered(_engineDir, testDir),
+            register: (_engineDir, _after, dryRun, testDir) => registerTestManifest(_engineDir, testDir, dryRun),
+            extractArgs: (m) => [m[1] ?? ''],
+        },
+        {
+            pattern: new RegExp(`^browser/modules/${escapeRegex(binaryName)}/(.+\\.sys\\.mjs)$`),
+            isRegistered: (_engineDir, fileName) => isFireForgeModuleRegistered(_engineDir, fileName, moduleDir),
+            register: (_engineDir, _after, dryRun, fileName) => registerFireForgeModule(_engineDir, fileName, moduleDir, dryRun),
+            extractArgs: (m) => [m[1] ?? ''],
+        },
+        {
+            pattern: /^toolkit\/content\/widgets\/([^/]+)\/(.+\.(?:mjs|css))$/,
+            isRegistered: (_engineDir, tagName, fileName) => isToolkitWidgetRegistered(_engineDir, tagName, fileName),
+            register: (_engineDir, _after, dryRun, tagName, fileName) => registerToolkitWidget(_engineDir, tagName, fileName, dryRun),
+            extractArgs: (m) => [m[1] ?? '', m[2] ?? ''],
+        },
+    ];
+}
+async function isSharedCSSRegistered(engineDir, fileName) {
+    const manifestPath = join(engineDir, 'browser/themes/shared/jar.inc.mn');
+    if (!(await pathExists(manifestPath))) {
+        throw new GeneralError('Manifest not found: browser/themes/shared/jar.inc.mn');
+    }
+    const name = basename(fileName, '.css');
+    const content = await readText(manifestPath);
+    return content.includes(`skin/classic/browser/${name}.css`);
+}
+async function isBrowserContentRegistered(engineDir, fileName) {
+    const manifestPath = join(engineDir, 'browser/base/jar.mn');
+    if (!(await pathExists(manifestPath))) {
+        throw new GeneralError('Manifest not found: browser/base/jar.mn');
+    }
+    const content = await readText(manifestPath);
+    return content.includes(`content/browser/${fileName}`);
+}
+async function isTestManifestRegistered(engineDir, testDir) {
+    const manifestPath = join(engineDir, 'browser/base/moz.build');
+    if (!(await pathExists(manifestPath))) {
+        throw new GeneralError('Manifest not found: browser/base/moz.build');
+    }
+    const content = await readText(manifestPath);
+    return content.includes(`content/test/${testDir}/browser.toml`);
+}
+async function isFireForgeModuleRegistered(engineDir, fileName, moduleDir) {
+    const manifestPath = join(engineDir, moduleDir, 'moz.build');
+    if (!(await pathExists(manifestPath))) {
+        throw new GeneralError(`Manifest not found: ${moduleDir}/moz.build`);
+    }
+    const content = await readText(manifestPath);
+    return content.includes(`"${fileName}"`);
+}
+async function isToolkitWidgetRegistered(engineDir, _tagName, fileName) {
+    const manifestPath = join(engineDir, 'toolkit/content/jar.mn');
+    if (!(await pathExists(manifestPath))) {
+        throw new GeneralError('Manifest not found: toolkit/content/jar.mn');
+    }
+    const content = await readText(manifestPath);
+    return content.includes(`content/global/elements/${fileName}`);
+}
+/**
+ * Checks if a file path matches any known registrable pattern.
+ * @param filePath - Path relative to engine/
+ * @param binaryName - Binary name from fireforge.json (used for module directory)
+ * @returns True if the file matches a known registration pattern
+ */
+export function matchesRegistrablePattern(filePath, binaryName) {
+    const normalized = filePath.replace(/\\/g, '/');
+    const rules = getRules(binaryName);
+    return rules.some((rule) => rule.pattern.test(normalized));
+}
+/**
+ * Checks whether a supported registrable file is already present in its manifest.
+ *
+ * @param root - Project root directory
+ * @param filePath - Path relative to engine/
+ * @returns True if the file is already registered in its manifest
+ */
+export async function isFileRegistered(root, filePath) {
+    const { engine: engineDir } = getProjectPaths(root);
+    const config = await loadConfig(root);
+    const rules = getRules(config.binaryName);
+    const normalizedPath = filePath.replace(/\\/g, '/');
+    for (const rule of rules) {
+        const match = normalizedPath.match(rule.pattern);
+        if (match) {
+            const args = rule.extractArgs(match);
+            return rule.isRegistered(engineDir, ...args);
+        }
+    }
+    throw new InvalidArgumentError(`Unknown file pattern: "${normalizedPath}". Supported patterns:\n` +
+        '  browser/themes/shared/*.css\n' +
+        '  browser/base/content/*.js\n' +
+        '  browser/base/content/test/*/browser.toml\n' +
+        `  browser/modules/${config.binaryName}/*.sys.mjs\n` +
+        '  toolkit/content/widgets/*/*.{mjs,css}', 'path');
+}
+/**
+ * Registers a file in the appropriate build manifest.
+ *
+ * @param root - Project root directory
+ * @param filePath - Path relative to engine/
+ * @param dryRun - If true, return what would be done without writing
+ * @param after - Optional substring to place entry after (instead of alphabetical)
+ * @returns Registration result
+ */
+export async function registerFile(root, filePath, dryRun = false, after) {
+    const { engine: engineDir } = getProjectPaths(root);
+    const config = await loadConfig(root);
+    const rules = getRules(config.binaryName);
+    // Normalize path separators
+    const normalizedPath = filePath.replace(/\\/g, '/');
+    for (const rule of rules) {
+        const match = normalizedPath.match(rule.pattern);
+        if (match) {
+            const args = rule.extractArgs(match);
+            return rule.register(engineDir, after, dryRun, ...args);
+        }
+    }
+    throw new InvalidArgumentError(`Unknown file pattern: "${normalizedPath}". Supported patterns:\n` +
+        '  browser/themes/shared/*.css\n' +
+        '  browser/base/content/*.js\n' +
+        '  browser/base/content/test/*/browser.toml\n' +
+        `  browser/modules/${config.binaryName}/*.sys.mjs\n` +
+        '  toolkit/content/widgets/*/*.{mjs,css}', 'path');
+}
+//# sourceMappingURL=manifest-rules.js.map

package/dist/src/core/manifest-tokenizers.d.ts

@@ -0,0 +1,34 @@
+/** Token for jar.mn / jar.inc.mn files */
+export interface JarMnToken {
+    type: 'header' | 'directive' | 'entry' | 'empty' | 'comment';
+    raw: string;
+    lineIndex: number;
+    parsed?: {
+        target: string;
+        source: string;
+    } | undefined;
+}
+/** Token for moz.build Python-style list blocks */
+export interface MozBuildToken {
+    type: 'list-open' | 'list-item' | 'list-close' | 'other';
+    raw: string;
+    lineIndex: number;
+    parsed?: {
+        value: string;
+    } | undefined;
+}
+/**
+ * Tokenizes a jar.mn file into structured tokens.
+ * Recognizes headers, `%` directives, entries with (source) paths,
+ * comments, and blank lines.
+ */
+export declare function tokenizeJarMn(lines: string[]): JarMnToken[];
+/**
+ * Tokenizes a moz.build Python list block, returning the tokens and their
+ * line range within the file.
+ */
+export declare function tokenizeMozBuildList(lines: string[], listPattern: RegExp): {
+    tokens: MozBuildToken[];
+    startLine: number;
+    endLine: number;
+} | null;

package/dist/src/core/manifest-tokenizers.js

@@ -0,0 +1,84 @@
+/**
+ * Tokenizes a jar.mn file into structured tokens.
+ * Recognizes headers, `%` directives, entries with (source) paths,
+ * comments, and blank lines.
+ */
+export function tokenizeJarMn(lines) {
+    const tokens = [];
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i] ?? '';
+        const trimmed = raw.trim();
+        if (trimmed === '') {
+            tokens.push({ type: 'empty', raw, lineIndex: i });
+            continue;
+        }
+        if (trimmed.startsWith('#')) {
+            tokens.push({ type: 'comment', raw, lineIndex: i });
+            continue;
+        }
+        if (trimmed.startsWith('%')) {
+            tokens.push({ type: 'directive', raw, lineIndex: i });
+            continue;
+        }
+        // Entries with source paths: "  target/path  (source/path)" or "target/path  (source/path)"
+        const entryMatch = /^(\s*)(\S+)\s+\(([^)]+)\)/.exec(raw);
+        if (entryMatch) {
+            tokens.push({
+                type: 'entry',
+                raw,
+                lineIndex: i,
+                parsed: { target: entryMatch[2] ?? '', source: entryMatch[3] ?? '' },
+            });
+            continue;
+        }
+        // Non-indented lines without (source) are headers (e.g., "browser.jar:" or Python assignment)
+        if (/^\S.*[:+=]/.test(raw)) {
+            tokens.push({ type: 'header', raw, lineIndex: i });
+            continue;
+        }
+        // Fallback: treat indented lines without (source) as entries
+        tokens.push({ type: 'entry', raw, lineIndex: i });
+    }
+    return tokens;
+}
+/**
+ * Tokenizes a moz.build Python list block, returning the tokens and their
+ * line range within the file.
+ */
+export function tokenizeMozBuildList(lines, listPattern) {
+    const tokens = [];
+    let startLine = -1;
+    let endLine = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i] ?? '';
+        if (startLine === -1) {
+            if (listPattern.test(raw)) {
+                startLine = i;
+                tokens.push({ type: 'list-open', raw, lineIndex: i });
+            }
+            continue;
+        }
+        // Inside the list block
+        if (/^\s*\]/.test(raw)) {
+            endLine = i;
+            tokens.push({ type: 'list-close', raw, lineIndex: i });
+            break;
+        }
+        const itemMatch = /^\s+["']([^"']+)["']/.exec(raw);
+        if (itemMatch) {
+            tokens.push({
+                type: 'list-item',
+                raw,
+                lineIndex: i,
+                parsed: { value: itemMatch[1] ?? '' },
+            });
+        }
+        else {
+            tokens.push({ type: 'other', raw, lineIndex: i });
+        }
+    }
+    if (startLine === -1 || endLine === -1)
+        return null;
+    return { tokens, startLine, endLine };
+}
+//# sourceMappingURL=manifest-tokenizers.js.map

package/dist/src/core/parser-fallback.d.ts

@@ -0,0 +1,36 @@
+export interface ParserFallbackEvent {
+    context: string;
+    reason: string;
+}
+/** Returns recorded parser fallback events without clearing the event buffer. */
+export declare function peekParserFallbackEvents(): ParserFallbackEvent[];
+/** Returns and clears the recorded parser fallback events. */
+export declare function consumeParserFallbackEvents(): ParserFallbackEvent[];
+/**
+ * Result of a parser-with-fallback invocation, carrying both the computed
+ * value and metadata about which code path produced it.
+ */
+export interface ParserResult<T> {
+    /** The computed value (from either the primary or fallback path). */
+    value: T;
+    /** True when the primary parser failed and the fallback was used. */
+    usedFallback: boolean;
+    /** The error that caused the primary parser to fail (undefined when primary succeeded). */
+    fallbackReason?: string;
+}
+/**
+ * Wraps a primary (AST/tokenizer) parser with a legacy (regex/line-based)
+ * fallback. If the primary throws, a warning is logged and the fallback is
+ * used instead.
+ *
+ * Returns a {@link ParserResult} so callers (and tests) can detect which
+ * code path was taken and surface it in logs or assertions.
+ *
+ * @param primary - The modern parser implementation
+ * @param fallback - The legacy fallback implementation
+ * @param context - File/context name used in the warning message
+ * @param rethrowIf - Optional predicate; if it returns true for the caught
+ *   error the error is re-thrown instead of falling back (useful for
+ *   domain-specific errors that should not be swallowed).
+ */
+export declare function withParserFallback<T>(primary: () => T, fallback: () => T, context: string, rethrowIf?: (error: unknown) => boolean): ParserResult<T>;

package/dist/src/core/parser-fallback.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { toError } from '../utils/errors.js';
+import { warn } from '../utils/logger.js';
+const parserFallbackEvents = [];
+/** Returns recorded parser fallback events without clearing the event buffer. */
+export function peekParserFallbackEvents() {
+    return [...parserFallbackEvents];
+}
+/** Returns and clears the recorded parser fallback events. */
+export function consumeParserFallbackEvents() {
+    const events = [...parserFallbackEvents];
+    parserFallbackEvents.length = 0;
+    return events;
+}
+/**
+ * Wraps a primary (AST/tokenizer) parser with a legacy (regex/line-based)
+ * fallback. If the primary throws, a warning is logged and the fallback is
+ * used instead.
+ *
+ * Returns a {@link ParserResult} so callers (and tests) can detect which
+ * code path was taken and surface it in logs or assertions.
+ *
+ * @param primary - The modern parser implementation
+ * @param fallback - The legacy fallback implementation
+ * @param context - File/context name used in the warning message
+ * @param rethrowIf - Optional predicate; if it returns true for the caught
+ *   error the error is re-thrown instead of falling back (useful for
+ *   domain-specific errors that should not be swallowed).
+ */
+export function withParserFallback(primary, fallback, context, rethrowIf) {
+    try {
+        return { value: primary(), usedFallback: false };
+    }
+    catch (error) {
+        if (rethrowIf?.(error))
+            throw error;
+        const reason = toError(error).message;
+        parserFallbackEvents.push({ context, reason });
+        warn(`AST/tokenizer parsing failed for ${context}, falling back to legacy. Error: ${reason}`);
+        return { value: fallback(), usedFallback: true, fallbackReason: reason };
+    }
+}
+//# sourceMappingURL=parser-fallback.js.map

package/dist/src/core/patch-apply-fuzz.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Fuzzy patch application with escalating fuzz factors.
+ *
+ * Tries an exact `git apply` first, then retries with increasing `--fuzz=N`
+ * values.  If all fuzz levels fail, falls through to `git apply --reject`
+ * so the user gets `.rej` files for manual resolution.
+ */
+export interface FuzzyApplyResult {
+    /** Whether the patch was applied successfully. */
+    success: boolean;
+    /** Fuzz factor that succeeded (0 = exact match). */
+    fuzzFactor: number;
+    /** Error description when `success` is false. */
+    error?: string;
+    /** List of `.rej` files created (when falling through to --reject). */
+    rejectFiles?: string[];
+}
+/**
+ * Attempts to apply a patch with escalating fuzz factors.
+ *
+ * 1. `git apply --check` at fuzz 0 … maxFuzz
+ * 2. `git apply --fuzz=N` at the first passing level
+ * 3. Fall through to `git apply --reject` if nothing succeeds
+ *
+ * @param patchPath - Absolute path to the `.patch` file
+ * @param engineDir - Working directory (engine/)
+ * @param maxFuzz   - Maximum fuzz factor to try (default 3)
+ */
+export declare function applyPatchWithFuzz(patchPath: string, engineDir: string, maxFuzz?: number): Promise<FuzzyApplyResult>;