@hominis/fireforge 0.9.0

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

@@ -0,0 +1,88 @@
+import type * as estree from 'estree';
+import { type AcornESTreeNode } from './ast-utils.js';
+/**
+ * Validates a name for safe interpolation into generated JavaScript string literals.
+ * Rejects strings containing characters that could break out of JS strings or inject code.
+ */
+export declare function validateWireName(value: string, label: string): void;
+/**
+ * Counts net brace depth change in a single line, ignoring braces inside
+ * string literals (single, double, template), line comments (`//`), and
+ * block comments.
+ *
+ * Tracks multi-line block comment state across calls via the `inBlockComment`
+ * parameter, allowing callers to iterate over lines while preserving context.
+ *
+ * **Regex literal heuristic:** When a `/` follows an operator or keyword-boundary
+ * character (one of `= ( : , ! | & ? ; ~ ^ { [ \n + - * % < >`), it is treated
+ * as a regex literal opener and characters are skipped until the closing `/`.
+ * This heuristic can misfire on:
+ *   - Division operators where the left operand is an identifier (`x / y / z`
+ *     would incorrectly treat ` y ` as regex content).
+ *   - Tagged template literals or unusual formatting.
+ *
+ * For Firefox source files this heuristic is sufficient because the AST-based
+ * parser (via `withParserFallback`) is tried first; this function is only
+ * used in the regex-based fallback path.
+ *
+ * @param line - A single line of source text
+ * @param inBlockComment - Whether the previous line ended inside a block comment
+ * @returns The net brace depth change and updated block comment state
+ */
+export declare function countBraceDepth(line: string, inBlockComment: boolean): {
+    depth: number;
+    inBlockComment: boolean;
+};
+/**
+ * Extracts the class/object name from an expression like "MyComponent.init()".
+ */
+export declare function extractNameFromExpression(expression: string): string;
+/** Token types for XHTML/preprocessor files */
+export interface XhtmlToken {
+    type: 'xml' | 'macro' | 'empty';
+    raw: string;
+}
+/**
+ * Tokenize an XHTML file with Mozilla preprocessor `#include` directives
+ * into a structured array.
+ */
+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.
+ */
+export declare function findMethodBraceIndex(lines: string[], pattern: RegExp): {
+    methodLine: number;
+    braceIndex: number;
+} | null;
+/**
+ * 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).
+ */
+export declare function walkToTryBlockEnd(lines: string[], startLine: number): number;
+/**
+ * Looks backward from `fromLine` (exclusive) to find the nearest `try {`
+ * line.  If nothing is found searching backward, also searches forward.
+ *
+ * @returns The line index of `try {`, or -1 if not found.
+ */
+export declare function findNearestTryLine(lines: string[], fromLine: number, lowerBound: number): number;
+/**
+ * Scans lines starting from `startLine` for consecutive fireforge try-catch
+ * blocks (identified by init comments or typeof guards) and returns the
+ * line index just after the last such block — i.e., where a new block should
+ * be inserted.
+ *
+ * Non-fireforge, non-blank, non-comment lines terminate the scan.
+ */
+export declare function findInsertionAfterFireforgeBlocks(lines: string[], startLine: number, lowerBound: number): number;
+/**
+ * Find the `Property` node for a method name like `onLoad` or `onUnload`
+ * inside the AST. Returns the function body's `BlockStatement`.
+ */
+export declare function findMethodBody(ast: AcornESTreeNode<estree.Program>, methodName: string | string[]): AcornESTreeNode<estree.BlockStatement> | null;

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

@@ -0,0 +1,279 @@
+import { GeneralError } from '../errors/base.js';
+import { walkAST } from './ast-utils.js';
+/**
+ * Validates a name for safe interpolation into generated JavaScript string literals.
+ * Rejects strings containing characters that could break out of JS strings or inject code.
+ */
+export function validateWireName(value, label) {
+    if (!/^[a-zA-Z0-9_$][\w$.-]*(?:\(\))?$/.test(value)) {
+        throw new GeneralError(`Invalid ${label} "${value}": must contain only letters, digits, hyphens, underscores, dots, and $ signs`);
+    }
+    // Reject property chains that could reach dangerous built-in properties
+    const segments = value.replace(/\(\)$/, '').split('.');
+    const dangerous = new Set(['__proto__', 'constructor', 'prototype']);
+    for (const seg of segments) {
+        if (dangerous.has(seg)) {
+            throw new GeneralError(`Invalid ${label} "${value}": must not contain "${seg}" as a property segment`);
+        }
+    }
+}
+/**
+ * Counts net brace depth change in a single line, ignoring braces inside
+ * string literals (single, double, template), line comments (`//`), and
+ * block comments.
+ *
+ * Tracks multi-line block comment state across calls via the `inBlockComment`
+ * parameter, allowing callers to iterate over lines while preserving context.
+ *
+ * **Regex literal heuristic:** When a `/` follows an operator or keyword-boundary
+ * character (one of `= ( : , ! | & ? ; ~ ^ { [ \n + - * % < >`), it is treated
+ * as a regex literal opener and characters are skipped until the closing `/`.
+ * This heuristic can misfire on:
+ *   - Division operators where the left operand is an identifier (`x / y / z`
+ *     would incorrectly treat ` y ` as regex content).
+ *   - Tagged template literals or unusual formatting.
+ *
+ * For Firefox source files this heuristic is sufficient because the AST-based
+ * parser (via `withParserFallback`) is tried first; this function is only
+ * used in the regex-based fallback path.
+ *
+ * @param line - A single line of source text
+ * @param inBlockComment - Whether the previous line ended inside a block comment
+ * @returns The net brace depth change and updated block comment state
+ */
+export function countBraceDepth(line, inBlockComment) {
+    let depth = 0;
+    let inSingle = false;
+    let inDouble = false;
+    let inTemplate = false;
+    let inLine = false;
+    let inBlock = inBlockComment;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        const next = line[i + 1];
+        if (inLine)
+            continue;
+        if (inBlock) {
+            if (ch === '*' && next === '/') {
+                inBlock = false;
+                i++;
+            }
+            continue;
+        }
+        if (ch === '\\' && (inSingle || inDouble || inTemplate)) {
+            i++;
+            continue;
+        }
+        if (inSingle) {
+            if (ch === "'")
+                inSingle = false;
+            continue;
+        }
+        if (inDouble) {
+            if (ch === '"')
+                inDouble = false;
+            continue;
+        }
+        if (inTemplate) {
+            if (ch === '`')
+                inTemplate = false;
+            continue;
+        }
+        if (ch === '/' && next === '/') {
+            inLine = true;
+            continue;
+        }
+        if (ch === '/' && next === '*') {
+            inBlock = true;
+            i++;
+            continue;
+        }
+        // Heuristic for regex literals: if / follows an operator or keyword boundary,
+        // treat it as a regex start and skip to the closing /
+        if (ch === '/' && next !== undefined) {
+            const prev = i > 0 ? line[i - 1] : undefined;
+            if (prev === undefined || /[=(:,!|&?;~^{[\n+\-*%<>]/.test(prev)) {
+                // Skip to closing /
+                i++;
+                while (i < line.length) {
+                    if (line[i] === '\\') {
+                        i++; // skip escaped character
+                    }
+                    else if (line[i] === '/') {
+                        break;
+                    }
+                    i++;
+                }
+                continue;
+            }
+        }
+        if (ch === "'") {
+            inSingle = true;
+            continue;
+        }
+        if (ch === '"') {
+            inDouble = true;
+            continue;
+        }
+        if (ch === '`') {
+            inTemplate = true;
+            continue;
+        }
+        if (ch === '{')
+            depth++;
+        if (ch === '}')
+            depth--;
+    }
+    return { depth, inBlockComment: inBlock };
+}
+/**
+ * Extracts the class/object name from an expression like "MyComponent.init()".
+ */
+export function extractNameFromExpression(expression) {
+    const match = /^(\w+)/.exec(expression);
+    return match?.[1] ?? expression;
+}
+/**
+ * Tokenize an XHTML file with Mozilla preprocessor `#include` directives
+ * into a structured array.
+ */
+export function tokenizeXhtml(lines) {
+    return lines.map((raw) => {
+        const trimmed = raw.trim();
+        if (trimmed === '') {
+            return { type: 'empty', raw };
+        }
+        if (trimmed.startsWith('#include ')) {
+            return { type: 'macro', raw };
+        }
+        return { type: 'xml', raw };
+    });
+}
+// ---------------------------------------------------------------------------
+// Legacy (line-based) helpers — shared by fallback implementations in
+// wire-targets.ts.  Extracted to reduce duplication and make the brace-
+// walking logic independently testable.
+// ---------------------------------------------------------------------------
+/**
+ * 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.
+ */
+export function findMethodBraceIndex(lines, pattern) {
+    let methodLine = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (pattern.test(lines[i] ?? '')) {
+            methodLine = i;
+            break;
+        }
+    }
+    if (methodLine === -1)
+        return null;
+    let braceIndex = methodLine;
+    for (let i = methodLine; i < lines.length; i++) {
+        if (lines[i]?.includes('{')) {
+            braceIndex = i;
+            break;
+        }
+    }
+    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).
+ */
+export function walkToTryBlockEnd(lines, startLine) {
+    let depth = 0;
+    let inBlock = false;
+    for (let j = startLine; j < lines.length; j++) {
+        const r = countBraceDepth(lines[j] ?? '', inBlock);
+        depth += r.depth;
+        inBlock = r.inBlockComment;
+        if (depth <= 0 && j > startLine) {
+            return j + 1;
+        }
+    }
+    return startLine + 1;
+}
+/**
+ * Looks backward from `fromLine` (exclusive) to find the nearest `try {`
+ * line.  If nothing is found searching backward, also searches forward.
+ *
+ * @returns The line index of `try {`, or -1 if not found.
+ */
+export function findNearestTryLine(lines, fromLine, lowerBound) {
+    // Backward search
+    for (let k = fromLine; k > lowerBound; k--) {
+        if (/\btry\s*\{/.test(lines[k] ?? ''))
+            return k;
+    }
+    // Forward search
+    for (let k = fromLine; k < lines.length; k++) {
+        if (/\btry\s*\{/.test(lines[k] ?? ''))
+            return k;
+    }
+    return -1;
+}
+/** Patterns that identify a fireforge init/destroy try-catch block. */
+const FIREFORGE_BLOCK_PATTERN = /\/\/\s*.*init\s*—|typeof\s+\w+\s*!==\s*"undefined"/;
+/**
+ * Scans lines starting from `startLine` for consecutive fireforge try-catch
+ * blocks (identified by init comments or typeof guards) and returns the
+ * line index just after the last such block — i.e., where a new block should
+ * be inserted.
+ *
+ * Non-fireforge, non-blank, non-comment lines terminate the scan.
+ */
+export function findInsertionAfterFireforgeBlocks(lines, startLine, lowerBound) {
+    let insertIndex = startLine;
+    for (let i = startLine; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (FIREFORGE_BLOCK_PATTERN.test(line)) {
+            const tryLine = findNearestTryLine(lines, i, lowerBound);
+            if (tryLine !== -1) {
+                const end = walkToTryBlockEnd(lines, tryLine);
+                insertIndex = end;
+                i = end - 1; // continue after this block
+            }
+            continue;
+        }
+        if (line.trim() && !line.trim().startsWith('//')) {
+            insertIndex = i;
+            break;
+        }
+    }
+    return insertIndex;
+}
+// ---------------------------------------------------------------------------
+// AST-based helpers
+// ---------------------------------------------------------------------------
+/**
+ * Find the `Property` node for a method name like `onLoad` or `onUnload`
+ * inside the AST. Returns the function body's `BlockStatement`.
+ */
+export function findMethodBody(ast, methodName) {
+    const names = Array.isArray(methodName) ? methodName : [methodName];
+    let found = null;
+    walkAST(ast, {
+        enter(node) {
+            if (found)
+                return;
+            if (node.type === 'Property') {
+                const prop = node;
+                if (prop.key.type === 'Identifier' &&
+                    names.includes(prop.key.name) &&
+                    (prop.value.type === 'FunctionExpression' ||
+                        prop.value.type === 'ArrowFunctionExpression')) {
+                    const fn = prop.value;
+                    found = fn.body;
+                }
+            }
+        },
+    });
+    return found;
+}
+//# sourceMappingURL=wire-utils.js.map

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

@@ -0,0 +1,60 @@
+import { ExitCode } from './codes.js';
+/**
+ * Base error class for all FireForge errors.
+ * Provides structured error information with exit codes and user-friendly messages.
+ */
+export declare abstract class FireForgeError extends Error {
+    /** Exit code to use when this error causes process termination */
+    abstract readonly code: ExitCode;
+    /**
+     * Creates a new FireForgeError.
+     * @param message - Technical error message for logging
+     * @param cause - The underlying error that caused this error
+     */
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+    /**
+     * User-friendly error message with context and suggested fixes.
+     * Override in subclasses to provide specific guidance.
+     */
+    get userMessage(): string;
+}
+/**
+ * General error for unexpected failures.
+ */
+export declare class GeneralError extends FireForgeError {
+    readonly code: 1;
+}
+/**
+ * Error thrown when a command-line argument is invalid.
+ */
+export declare class InvalidArgumentError extends FireForgeError {
+    readonly argument?: string | undefined;
+    readonly code: 8;
+    constructor(message: string, argument?: string | undefined, cause?: Error);
+    get userMessage(): string;
+}
+/**
+ * Error thrown when the user cancels an interactive prompt.
+ */
+export declare class CancellationError extends FireForgeError {
+    readonly code: 1;
+    constructor();
+}
+/**
+ * Error thrown when patch resolution fails.
+ */
+export declare class ResolutionError extends FireForgeError {
+    readonly code: 10;
+}
+/**
+ * Sentinel error used to propagate an exit code to the CLI entrypoint
+ * without calling process.exit() from shared library code.
+ *
+ * The user-visible error message has already been logged by the time this
+ * is thrown — the entrypoint only needs to read `.exitCode` and terminate.
+ */
+export declare class CommandError extends Error {
+    readonly exitCode: ExitCode;
+    constructor(exitCode: ExitCode);
+}

package/dist/src/errors/base.js

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { ExitCode } from './codes.js';
+/**
+ * Base error class for all FireForge errors.
+ * Provides structured error information with exit codes and user-friendly messages.
+ */
+export class FireForgeError extends Error {
+    /**
+     * Creates a new FireForgeError.
+     * @param message - Technical error message for logging
+     * @param cause - The underlying error that caused this error
+     */
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = this.constructor.name;
+        if (cause !== undefined) {
+            this.cause = cause;
+        }
+        // Maintains proper stack trace in V8 environments
+        if (typeof Error.captureStackTrace === 'function') {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * User-friendly error message with context and suggested fixes.
+     * Override in subclasses to provide specific guidance.
+     */
+    get userMessage() {
+        return this.message;
+    }
+}
+/**
+ * General error for unexpected failures.
+ */
+export class GeneralError extends FireForgeError {
+    code = ExitCode.GENERAL_ERROR;
+}
+/**
+ * Error thrown when a command-line argument is invalid.
+ */
+export class InvalidArgumentError extends FireForgeError {
+    argument;
+    code = ExitCode.INVALID_ARGUMENT;
+    constructor(message, argument, cause) {
+        super(message, cause);
+        this.argument = argument;
+    }
+    get userMessage() {
+        let msg = `Invalid Argument: ${this.message}`;
+        if (this.argument) {
+            msg += `\n\nArgument: ${this.argument}`;
+        }
+        return msg;
+    }
+}
+/**
+ * Error thrown when the user cancels an interactive prompt.
+ */
+export class CancellationError extends FireForgeError {
+    code = ExitCode.GENERAL_ERROR;
+    constructor() {
+        super('cancelled');
+    }
+}
+/**
+ * Error thrown when patch resolution fails.
+ */
+export class ResolutionError extends FireForgeError {
+    code = ExitCode.RESOLUTION_ERROR;
+}
+/**
+ * Sentinel error used to propagate an exit code to the CLI entrypoint
+ * without calling process.exit() from shared library code.
+ *
+ * The user-visible error message has already been logged by the time this
+ * is thrown — the entrypoint only needs to read `.exitCode` and terminate.
+ */
+export class CommandError extends Error {
+    exitCode;
+    constructor(exitCode) {
+        super(`Command failed with exit code ${exitCode}`);
+        this.exitCode = exitCode;
+        this.name = 'CommandError';
+    }
+}
+//# sourceMappingURL=base.js.map

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

@@ -0,0 +1,52 @@
+import { FireForgeError } from './base.js';
+import { ExitCode } from './codes.js';
+/**
+ * Error thrown when a build operation fails.
+ */
+export declare class BuildError extends FireForgeError {
+    readonly command?: string | undefined;
+    readonly code: ExitCode;
+    constructor(message: string, command?: string | undefined, cause?: Error);
+    get userMessage(): string;
+}
+/**
+ * Error thrown when mach is not available.
+ */
+export declare class MachNotFoundError extends BuildError {
+    readonly engineDir: string;
+    readonly code: 7;
+    constructor(engineDir: string);
+    get userMessage(): string;
+}
+/**
+ * Error thrown when python is not available.
+ */
+export declare class PythonNotFoundError extends BuildError {
+    readonly minVersion: string;
+    readonly maxVersion: string;
+    readonly code: 7;
+    constructor(minVersion?: string, maxVersion?: string);
+    get userMessage(): string;
+}
+/**
+ * Error thrown when bootstrap fails.
+ */
+export declare class BootstrapError extends BuildError {
+    constructor(cause?: Error);
+    get userMessage(): string;
+}
+/**
+ * Error thrown when mozconfig generation fails.
+ */
+export declare class MozconfigError extends BuildError {
+    get userMessage(): string;
+}
+/**
+ * Error thrown when multiple build output directories exist and FireForge cannot
+ * safely choose one.
+ */
+export declare class AmbiguousBuildArtifactsError extends BuildError {
+    readonly objDirs: string[];
+    constructor(objDirs: string[]);
+    get userMessage(): string;
+}

package/dist/src/errors/build.js

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { FireForgeError } from './base.js';
+import { ExitCode } from './codes.js';
+/**
+ * Error thrown when a build operation fails.
+ */
+export class BuildError extends FireForgeError {
+    command;
+    code = ExitCode.BUILD_ERROR;
+    constructor(message, command, cause) {
+        super(message, cause);
+        this.command = command;
+    }
+    get userMessage() {
+        let msg = `Build Error: ${this.message}`;
+        if (this.command) {
+            msg += `\n\nCommand: ${this.command}`;
+        }
+        msg += '\n\nTo fix this:\n';
+        msg += '  1. Check the build output above for specific errors\n';
+        msg += '  2. Ensure all dependencies are installed with "fireforge bootstrap"\n';
+        msg += '  3. Try a clean build by deleting obj-* directories';
+        return msg;
+    }
+}
+/**
+ * Error thrown when mach is not available.
+ */
+export class MachNotFoundError extends BuildError {
+    engineDir;
+    code = ExitCode.MISSING_DEPENDENCY;
+    constructor(engineDir) {
+        super(`mach not found in ${engineDir}`);
+        this.engineDir = engineDir;
+    }
+    get userMessage() {
+        return ('Build Error: Firefox build system (mach) not found.\n\n' +
+            `Expected location: ${this.engineDir}/mach\n\n` +
+            'To fix this:\n' +
+            '  1. Run "fireforge download" to download Firefox source\n' +
+            '  2. Ensure the engine/ directory contains the Firefox source');
+    }
+}
+/**
+ * Error thrown when python is not available.
+ */
+export class PythonNotFoundError extends BuildError {
+    minVersion;
+    maxVersion;
+    code = ExitCode.MISSING_DEPENDENCY;
+    constructor(minVersion = '3.8', maxVersion = '3.12') {
+        super(`FireForge could not find a Python interpreter supported by Firefox mach (${minVersion}-${maxVersion}).`);
+        this.minVersion = minVersion;
+        this.maxVersion = maxVersion;
+    }
+    get userMessage() {
+        return (`Build Error: Python ${this.minVersion}-${this.maxVersion} is required but not found.\n\n` +
+            'Firefox mach declares the supported Python range in engine/mach, and FireForge could not find any interpreter in that range.\n\n' +
+            'To fix this:\n' +
+            `  1. Install a supported Python version (${this.minVersion}-${this.maxVersion}) from https://python.org/\n` +
+            '  2. Ensure that interpreter is in your PATH (for example as python3.12 or python3)\n' +
+            '  3. Re-run "fireforge doctor" to confirm FireForge can see it');
+    }
+}
+/**
+ * Error thrown when bootstrap fails.
+ */
+export class BootstrapError extends BuildError {
+    constructor(cause) {
+        super('Bootstrap failed', 'python3 mach bootstrap', cause);
+    }
+    get userMessage() {
+        return ('Build Error: Bootstrap failed.\n\n' +
+            'The Firefox build dependencies could not be installed. This often happens if the Python interpreter selected for mach is missing or misconfigured.\n\n' +
+            'To fix this:\n' +
+            '  1. Check the error output above\n' +
+            '  2. Ensure you have sufficient permissions\n' +
+            '  3. Try running bootstrap manually:\n' +
+            '     cd engine && python3 mach bootstrap');
+    }
+}
+/**
+ * Error thrown when mozconfig generation fails.
+ */
+export class MozconfigError extends BuildError {
+    get userMessage() {
+        return (`Build Error: ${this.message}\n\n` +
+            'To fix this:\n' +
+            '  1. Check that configs/ directory exists\n' +
+            '  2. Ensure platform-specific mozconfig exists\n' +
+            '  3. Run "fireforge setup" to regenerate configs');
+    }
+}
+/**
+ * Error thrown when multiple build output directories exist and FireForge cannot
+ * safely choose one.
+ */
+export class AmbiguousBuildArtifactsError extends BuildError {
+    objDirs;
+    constructor(objDirs) {
+        super(`Multiple build artifact directories found: ${objDirs.join(', ')}`);
+        this.objDirs = objDirs;
+    }
+    get userMessage() {
+        return ('Build Error: Multiple build artifact directories were found.\n\n' +
+            `Candidates: ${this.objDirs.join(', ')}\n\n` +
+            'FireForge will not guess which build output to use.\n\n' +
+            'To fix this:\n' +
+            '  1. Remove stale obj-* directories you no longer need\n' +
+            '  2. Keep only the active build output directory\n' +
+            '  3. Run the command again');
+    }
+}
+//# sourceMappingURL=build.js.map