@hominis/fireforge 0.9.0

package/dist/src/commands/watch.js

@@ -0,0 +1,112 @@
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { buildArtifactMismatchMessage, generateMozconfig, hasBuildArtifacts, watchWithOutput, } from '../core/mach.js';
+import { GeneralError } from '../errors/base.js';
+import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
+import { pathExists } from '../utils/fs.js';
+import { info, intro, outro, spinner } from '../utils/logger.js';
+import { executableExists } from '../utils/process.js';
+/**
+ * Builds remediation guidance for objdirs configured before watchman was available.
+ * @returns User-facing configure-time watchman guidance
+ */
+function buildWatchmanConfigureTimeMessage() {
+    return ('Watch mode cannot use the current obj-* build because watchman was not available when Firefox was configured.\n\n' +
+        'Install watchman, delete the current obj-* directory, run "fireforge build" again, then retry "fireforge watch".');
+}
+/**
+ * Builds the generic unsupported-watch failure message.
+ * @param exitCode - Exit code returned by `mach watch`
+ * @returns User-facing failure guidance
+ */
+function buildUnsupportedWatchMessage(exitCode) {
+    return (`Watch failed with exit code ${exitCode}. Check the output above for details.\n\n` +
+        'Common causes:\n' +
+        '  - watchman is not installed or not in PATH right now\n' +
+        '  - watchman was installed only after the current obj-* directory was configured; delete obj-* and rebuild\n' +
+        '  - mach watch is unsupported in the current objdir or build environment');
+}
+/**
+ * Detects the Firefox-side output produced when watchman was missing at configure time.
+ * @param output - Combined stdout and stderr from the watch run
+ * @returns True when the output matches the configure-time watchman failure mode
+ */
+function hasConfigureTimeWatchmanFailure(output) {
+    return (/watchman/i.test(output) &&
+        /(configure time|configured|configuration time|when (?:this|the current) build was configured)/i.test(output));
+}
+/**
+ * Runs the watch command for auto-rebuilding.
+ * @param projectRoot - Root directory of the project
+ */
+export async function watchCommand(projectRoot) {
+    intro('FireForge Watch');
+    // Load configuration
+    const config = await loadConfig(projectRoot);
+    const paths = getProjectPaths(projectRoot);
+    // Check if engine exists
+    if (!(await pathExists(paths.engine))) {
+        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
+    }
+    if (!(await executableExists('watchman'))) {
+        throw new GeneralError('Watch mode requires watchman to be installed and available in PATH.\n\n' +
+            'Install watchman first, then rerun "fireforge watch".');
+    }
+    // Check for build artifacts before starting watch
+    const buildCheck = await hasBuildArtifacts(paths.engine);
+    if (buildCheck.ambiguous && buildCheck.objDirs && buildCheck.objDirs.length > 0) {
+        throw new AmbiguousBuildArtifactsError(buildCheck.objDirs);
+    }
+    // Reject copied or relocated obj-* dirs whose mozinfo metadata (topsrcdir,
+    // topobjdir, mozconfig) still points at a different source tree. Running mach
+    // watch against stale metadata produces confusing build errors.
+    const mismatchMessage = buildArtifactMismatchMessage(paths.engine, buildCheck, 'Watch mode');
+    if (mismatchMessage) {
+        throw new GeneralError(mismatchMessage);
+    }
+    if (!buildCheck.exists) {
+        const detail = buildCheck.objDir
+            ? `Build artifacts incomplete in ${buildCheck.objDir}/`
+            : 'No build artifacts found (obj-*/ directory missing)';
+        throw new GeneralError(`Watch mode requires a completed build. ${detail}\n\n` +
+            "Run 'fireforge build' first to create the initial build, then run 'fireforge watch'.");
+    }
+    info(`Using build artifacts from ${buildCheck.objDir}/`);
+    // Generate mozconfig (in case it's not up to date)
+    const mozconfigSpinner = spinner('Generating mozconfig...');
+    try {
+        await generateMozconfig(paths.configs, paths.engine, config);
+        mozconfigSpinner.stop('mozconfig generated');
+    }
+    catch (error) {
+        mozconfigSpinner.error('Failed to generate mozconfig');
+        throw error;
+    }
+    info('Starting watch mode...');
+    info('Press Ctrl+C to stop\n');
+    let result;
+    try {
+        result = await watchWithOutput(paths.engine);
+    }
+    catch (error) {
+        throw new BuildError('Watch process failed to start', 'mach watch', error instanceof Error ? error : undefined);
+    }
+    if (result.exitCode !== 0 && result.exitCode !== 130) {
+        const combinedOutput = `${result.stdout}\n${result.stderr}`;
+        if (hasConfigureTimeWatchmanFailure(combinedOutput)) {
+            throw new GeneralError(buildWatchmanConfigureTimeMessage());
+        }
+        // 130 is SIGINT (Ctrl+C), which is expected
+        throw new BuildError(buildUnsupportedWatchMessage(result.exitCode), 'mach watch');
+    }
+    outro('Watch mode stopped');
+}
+/** Registers the watch command on the CLI program. */
+export function registerWatch(program, { getProjectRoot, withErrorHandling }) {
+    program
+        .command('watch')
+        .description('Watch for changes and auto-rebuild')
+        .action(withErrorHandling(async () => {
+        await watchCommand(getProjectRoot());
+    }));
+}
+//# sourceMappingURL=watch.js.map

package/dist/src/commands/wire.d.ts

@@ -0,0 +1,13 @@
+import { Command } from 'commander';
+import type { CommandContext } from '../types/cli.js';
+import type { WireOptions } from '../types/commands/index.js';
+/**
+ * Wires a chrome subscript into the browser.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param name - Subscript name (without .js extension)
+ * @param options - Command options
+ */
+export declare function wireCommand(projectRoot: string, name: string, options?: WireOptions): Promise<void>;
+/** Registers the wire command on the CLI program. */
+export declare function registerWire(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/wire.js

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join, relative } from 'node:path';
+import { DEFAULT_BROWSER_SUBSCRIPT_DIR, wireSubscript } from '../core/browser-wire.js';
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { consumeParserFallbackEvents } from '../core/parser-fallback.js';
+import { InvalidArgumentError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { pathExists } from '../utils/fs.js';
+import { info, intro, outro, success, warn } from '../utils/logger.js';
+import { pickDefined } from '../utils/options.js';
+import { isContainedRelativePath, isPathInsideRoot, toRootRelativePath } from '../utils/paths.js';
+const BROWSER_BASE_DIR = 'browser/base';
+function printWireDryRun(engineDir, name, subscriptDir, domFilePath, options) {
+    info('[dry-run] Would wire subscript:');
+    info(`  source: ${subscriptDir}/${name}.js`);
+    info(`  browser-main.js: loadSubScript("chrome://browser/content/${name}.js")`);
+    if (options.init) {
+        info(`  browser-init.js: ${options.init}`);
+    }
+    if (options.destroy) {
+        info(`  browser-init.js onUnload(): ${options.destroy}`);
+    }
+    if (domFilePath) {
+        const includePath = relative(join(engineDir, subscriptDir), join(engineDir, domFilePath)).replace(/\\/g, '/');
+        info(`  browser.xhtml: #include ${includePath}`);
+    }
+    const relPath = relative(join(engineDir, BROWSER_BASE_DIR), join(engineDir, subscriptDir)).replace(/\\/g, '/');
+    info(`  jar.mn: content/browser/${name}.js (${relPath}/${name}.js)`);
+    outro('Dry run complete');
+}
+/**
+ * Wires a chrome subscript into the browser.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param name - Subscript name (without .js extension)
+ * @param options - Command options
+ */
+export async function wireCommand(projectRoot, name, options = {}) {
+    intro('Wire');
+    consumeParserFallbackEvents();
+    // Resolve subscript directory: CLI flag > fireforge.json > default
+    let subscriptDir = DEFAULT_BROWSER_SUBSCRIPT_DIR;
+    try {
+        const config = await loadConfig(projectRoot);
+        if (config.wire?.subscriptDir) {
+            subscriptDir = config.wire.subscriptDir;
+        }
+    }
+    catch (error) {
+        warn(`Using default wire.subscriptDir because fireforge.json could not be loaded: ${toError(error).message}`);
+    }
+    if (options.subscriptDir) {
+        if (!isContainedRelativePath(options.subscriptDir)) {
+            throw new InvalidArgumentError(`Subscript directory must stay within engine/: ${options.subscriptDir}`, 'subscriptDir');
+        }
+        subscriptDir = options.subscriptDir;
+    }
+    // Validate DOM fragment file exists and compute path relative to engine root
+    let domFilePath;
+    if (options.dom) {
+        const paths = getProjectPaths(projectRoot);
+        if (!(await pathExists(options.dom))) {
+            throw new InvalidArgumentError(`DOM fragment file not found: ${options.dom}`, 'dom');
+        }
+        if (!isPathInsideRoot(paths.engine, options.dom)) {
+            throw new InvalidArgumentError(`DOM fragment file must stay within engine/: ${options.dom}`, 'dom');
+        }
+        domFilePath = toRootRelativePath(paths.engine, options.dom);
+    }
+    // Verify the subscript file exists in engine/ (skip for dry-run)
+    if (!options.dryRun) {
+        const paths = getProjectPaths(projectRoot);
+        const subscriptPath = join(paths.engine, subscriptDir, `${name}.js`);
+        if (!(await pathExists(subscriptPath))) {
+            throw new InvalidArgumentError(`Subscript file not found: ${subscriptDir}/${name}.js\n` +
+                'Create the file in engine/ before wiring.', 'name');
+        }
+    }
+    if (options.dryRun) {
+        printWireDryRun(getProjectPaths(projectRoot).engine, name, subscriptDir, domFilePath, options);
+        return;
+    }
+    const result = await wireSubscript(projectRoot, name, {
+        ...(options.init !== undefined ? { init: options.init } : {}),
+        ...(options.destroy !== undefined ? { destroy: options.destroy } : {}),
+        ...(domFilePath !== undefined ? { domFilePath } : {}),
+        ...(options.after !== undefined ? { after: options.after } : {}),
+        ...(subscriptDir !== DEFAULT_BROWSER_SUBSCRIPT_DIR ? { subscriptDir } : {}),
+        dryRun: false,
+    });
+    const parserFallbacks = consumeParserFallbackEvents();
+    if (parserFallbacks.length > 0) {
+        const contexts = [...new Set(parserFallbacks.map((event) => event.context))];
+        info(`Legacy parser fallback was used for ${contexts.length} file${contexts.length === 1 ? '' : 's'}: ${contexts.join(', ')}`);
+    }
+    if (result.subscriptAdded) {
+        success(`Added loadSubScript for ${name}.js to browser-main.js`);
+    }
+    else {
+        info(`${name}.js already registered in browser-main.js (skipped)`);
+    }
+    if (options.init) {
+        if (result.initAdded) {
+            success(`Added init expression to browser-init.js onLoad()`);
+        }
+        else {
+            info(`Init expression already present in browser-init.js (skipped)`);
+        }
+    }
+    if (options.destroy) {
+        if (result.destroyAdded) {
+            success(`Added destroy expression to browser-init.js onUnload()`);
+        }
+        else {
+            info(`Destroy expression already present in browser-init.js (skipped)`);
+        }
+    }
+    if (domFilePath) {
+        if (result.domInserted) {
+            success(`Inserted #include directive into browser.xhtml`);
+        }
+        else {
+            info(`#include directive already present in browser.xhtml (skipped)`);
+        }
+    }
+    if (result.jarMnResult.skipped) {
+        info(`${name}.js already registered in jar.mn (skipped)`);
+    }
+    else {
+        success(`Registered ${name}.js in ${result.jarMnResult.manifest}`);
+    }
+    outro('Wiring complete');
+}
+/** Registers the wire command on the CLI program. */
+export function registerWire(program, { getProjectRoot, withErrorHandling }) {
+    program
+        .command('wire <name>')
+        .description('Wire a chrome subscript into the browser')
+        .option('--init <expression>', 'Init expression for browser-init.js onLoad()')
+        .option('--destroy <expression>', 'Destroy expression for browser-init.js onUnload()')
+        .option('--dom <file>', 'XHTML fragment file to insert into browser.xhtml')
+        .option('--dry-run', 'Show what would be changed without writing')
+        .option('--after <name>', 'Insert init block after the block for this name')
+        .option('--subscript-dir <dir>', 'Subscript directory relative to engine/ (default: browser/base/content)')
+        .action(withErrorHandling(async (name, options) => {
+        await wireCommand(getProjectRoot(), name, pickDefined(options));
+    }));
+}
+//# sourceMappingURL=wire.js.map

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

@@ -0,0 +1,47 @@
+import type * as estree from 'estree';
+import { walk } from 'estree-walker';
+/**
+ * An ESTree node augmented with acorn's character-offset positions.
+ * At runtime `acorn.parse` produces objects that carry both the ESTree
+ * shape *and* `start`/`end` indices, but the type system doesn't know that.
+ * This intersection type bridges the gap so we can safely use both APIs.
+ */
+export type AcornESTreeNode<T extends estree.Node = estree.Node> = T & {
+    start: number;
+    end: number;
+};
+/**
+ * Parse JavaScript source as a **script** (not an ES module).
+ * All Mozilla chrome JS files (`browser-main.js`, `browser-init.js`,
+ * `customElements.js`, etc.) are scripts that run in a privileged scope.
+ */
+export declare function parseScript(content: string): AcornESTreeNode<estree.Program>;
+/**
+ * Convenience cast from `acorn.Node` (or the generic ESTree union returned
+ * by estree-walker callbacks) to a positioned, narrowly-typed node.
+ */
+export declare function asEstree<T extends estree.Node>(node: estree.Node): AcornESTreeNode<T>;
+/**
+ * Type-safe wrapper around estree-walker's `walk()` that bridges the
+ * acorn→estree type gap. Centralises the single `as unknown as` cast so
+ * callers don't need it.
+ */
+export declare function walkAST(ast: AcornESTreeNode<estree.Program>, visitors: Parameters<typeof walk>[1]): ReturnType<typeof walk>;
+/**
+ * Read backward from `position` to the preceding newline (or start of
+ * string) and return the leading whitespace.  This is the "visual indent"
+ * of whatever token begins at `position`.
+ *
+ * ```
+ * "  try {\n    foo();\n  }"
+ *                          ^  detectIndent(…, 26) → "  "
+ * ```
+ */
+export declare function detectIndent(content: string, position: number): string;
+/**
+ * Extract the raw source text for a node's range.
+ */
+export declare function getNodeSource(content: string, node: {
+    start: number;
+    end: number;
+}): string;

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

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: EUPL-1.2
+import * as acorn from 'acorn';
+import { walk } from 'estree-walker';
+/**
+ * Parse JavaScript source as a **script** (not an ES module).
+ * All Mozilla chrome JS files (`browser-main.js`, `browser-init.js`,
+ * `customElements.js`, etc.) are scripts that run in a privileged scope.
+ */
+export function parseScript(content) {
+    return acorn.parse(content, {
+        sourceType: 'script',
+        ecmaVersion: 'latest',
+    });
+}
+/**
+ * Convenience cast from `acorn.Node` (or the generic ESTree union returned
+ * by estree-walker callbacks) to a positioned, narrowly-typed node.
+ */
+export function asEstree(node) {
+    return node;
+}
+/**
+ * Type-safe wrapper around estree-walker's `walk()` that bridges the
+ * acorn→estree type gap. Centralises the single `as unknown as` cast so
+ * callers don't need it.
+ */
+export function walkAST(ast, visitors) {
+    return walk(ast, visitors);
+}
+/**
+ * Read backward from `position` to the preceding newline (or start of
+ * string) and return the leading whitespace.  This is the "visual indent"
+ * of whatever token begins at `position`.
+ *
+ * ```
+ * "  try {\n    foo();\n  }"
+ *                          ^  detectIndent(…, 26) → "  "
+ * ```
+ */
+export function detectIndent(content, position) {
+    let i = position - 1;
+    while (i >= 0 && content[i] !== '\n') {
+        i--;
+    }
+    // i is now at the newline (or -1 for start-of-string)
+    const lineStart = i + 1;
+    const slice = content.slice(lineStart, position);
+    const match = /^(\s*)/.exec(slice);
+    return match?.[1] ?? '';
+}
+/**
+ * Extract the raw source text for a node's range.
+ */
+export function getNodeSource(content, node) {
+    return content.slice(node.start, node.end);
+}
+//# sourceMappingURL=ast-utils.js.map

package/dist/src/core/brand-validation.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Validates that a brand override matches the configured brand.
+ * @param configuredBrand - The brand configured in fireforge.json
+ * @param requestedBrand - The brand requested via CLI flag
+ * @throws InvalidArgumentError if the brands don't match
+ */
+export declare function validateBrandOverride(configuredBrand: string, requestedBrand?: string): void;

package/dist/src/core/brand-validation.js

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { InvalidArgumentError } from '../errors/base.js';
+/**
+ * Validates that a brand override matches the configured brand.
+ * @param configuredBrand - The brand configured in fireforge.json
+ * @param requestedBrand - The brand requested via CLI flag
+ * @throws InvalidArgumentError if the brands don't match
+ */
+export function validateBrandOverride(configuredBrand, requestedBrand) {
+    if (!requestedBrand || requestedBrand === configuredBrand) {
+        return;
+    }
+    throw new InvalidArgumentError(`Brand override "${requestedBrand}" is not supported yet. FireForge currently operates only on the configured brand "${configuredBrand}".`, 'brand');
+}
+//# sourceMappingURL=brand-validation.js.map

package/dist/src/core/branding.d.ts

@@ -0,0 +1,49 @@
+import { FireForgeError } from '../errors/base.js';
+/**
+ * Error thrown when branding operations fail.
+ */
+export declare class BrandingError extends FireForgeError {
+    readonly code: 6;
+    get userMessage(): string;
+}
+/**
+ * Full branding configuration.
+ */
+export interface BrandingConfig {
+    /** Display name (e.g., "MyBrowser") */
+    name: string;
+    /** Vendor name (e.g., "My Company") */
+    vendor: string;
+    /** Application ID in reverse-domain format (e.g., "org.mybrowser.browser") */
+    appId: string;
+    /** Binary/branding directory name (e.g., "mybrowser") */
+    binaryName: string;
+}
+/**
+ * Sets up the custom branding directory for the browser.
+ *
+ * This creates a branding directory based on Firefox's unofficial branding,
+ * with customized values for:
+ * - configure.sh: MOZ_APP_DISPLAYNAME, MOZ_MACBUNDLE_ID
+ * - brand.properties: brandShorterName, brandShortName, brandFullName
+ * - brand.ftl: -brand-shorter-name, -brand-short-name, etc.
+ *
+ * @param engineDir - Path to the engine directory
+ * @param config - Branding configuration
+ */
+export declare function setupBranding(engineDir: string, config: BrandingConfig): Promise<void>;
+/**
+ * Checks if branding has been set up for the given configuration.
+ *
+ * @param engineDir - Path to the engine directory
+ * @param config - Branding configuration to check for
+ * @returns true if branding is already set up
+ */
+export declare function isBrandingSetup(engineDir: string, config: BrandingConfig): Promise<boolean>;
+/**
+ * Checks whether a file path belongs to the tool-managed branding directory.
+ * @param file - File path (relative to engine root)
+ * @param binaryName - The configured binary name (used as branding directory name)
+ * @returns true if the path is managed by branding tooling
+ */
+export declare function isBrandingManagedPath(file: string, binaryName: string): boolean;