@hominis/fireforge 0.9.0

package/dist/src/commands/export-shared.js

@@ -0,0 +1,208 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { confirm, select, text } from '@clack/prompts';
+import { addLicenseHeaderToFile, getLicenseHeader } from '../core/license-headers.js';
+import { findAllPatchesForFiles } from '../core/patch-export.js';
+import { commentStyleForFile, detectNewFilesInDiff, lintExportedPatch, } from '../core/patch-lint.js';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
+import { pathExists, readText } from '../utils/fs.js';
+import { cancel, info, isCancel, warn } from '../utils/logger.js';
+import { isValidPatchCategory, PATCH_CATEGORIES, validatePatchName } from '../utils/validation.js';
+/**
+ * Runs the full patch lint pipeline and reports results.
+ * Warnings are always displayed. Errors block the export unless skipLint is true.
+ *
+ * @param engineDir - Engine root directory
+ * @param filesAffected - Files touched by the patch
+ * @param diffContent - Raw unified diff string
+ * @param config - Project configuration
+ * @param skipLint - If true, downgrade errors to warnings
+ */
+export async function runPatchLint(engineDir, filesAffected, diffContent, config, skipLint) {
+    const issues = await lintExportedPatch(engineDir, filesAffected, diffContent, config);
+    if (issues.length === 0)
+        return;
+    const errors = issues.filter((i) => i.severity === 'error');
+    const warnings = issues.filter((i) => i.severity === 'warning');
+    for (const issue of warnings) {
+        warn(`[${issue.check}] ${issue.file}: ${issue.message}`);
+    }
+    if (errors.length > 0) {
+        for (const issue of errors) {
+            if (skipLint) {
+                warn(`[${issue.check}] ${issue.file}: ${issue.message}`);
+            }
+            else {
+                warn(`ERROR [${issue.check}] ${issue.file}: ${issue.message}`);
+            }
+        }
+        if (!skipLint) {
+            throw new GeneralError(`Patch lint found ${errors.length} error(s) that must be fixed before exporting.\n` +
+                'Use --skip-lint to bypass this check.');
+        }
+        info(`Lint: ${errors.length} error(s) downgraded to warnings (--skip-lint)`);
+    }
+    const warnCount = warnings.length + (skipLint ? errors.length : 0);
+    if (warnCount > 0) {
+        info(`Patch lint: ${warnCount} warning(s)`);
+    }
+}
+/**
+ * Resolves patch metadata interactively or from flags, with shared validation.
+ * @param options - Export command options
+ * @param isInteractive - Whether interactive prompts are allowed
+ * @param commandName - Command name for error/help text
+ */
+export async function promptExportPatchMetadata(options, isInteractive, commandName) {
+    let patchName = options.name;
+    if (patchName) {
+        const validationError = validatePatchName(patchName);
+        if (validationError) {
+            throw new InvalidArgumentError(validationError, '--name');
+        }
+    }
+    if (!patchName && !isInteractive) {
+        throw new InvalidArgumentError('The --name flag is required in non-interactive mode', `Use: fireforge ${commandName} ${commandName === 'export' ? '<paths...> ' : ''}--name "my-patch-name" --category ui`);
+    }
+    if (!patchName) {
+        const nameResult = await text({
+            message: 'Enter a name for this patch:',
+            placeholder: commandName === 'export' ? 'my-change' : 'my-changes',
+            validate: (value) => validatePatchName((value ?? '').trim()),
+        });
+        if (isCancel(nameResult)) {
+            cancel('Export cancelled');
+            return null;
+        }
+        patchName = String(nameResult).trim();
+    }
+    let category = options.category;
+    if (category) {
+        if (!isValidPatchCategory(category)) {
+            throw new InvalidArgumentError(`Invalid category. Must be one of: ${PATCH_CATEGORIES.join(', ')}`, '--category');
+        }
+    }
+    else if (!isInteractive) {
+        throw new InvalidArgumentError('The --category flag is required in non-interactive mode', `Use: fireforge ${commandName} ${commandName === 'export' ? '<paths...> ' : ''}--name "name" --category <${PATCH_CATEGORIES.join('|')}>`);
+    }
+    else {
+        const categoryResult = await select({
+            message: 'Select a category for this patch:',
+            options: [
+                { value: 'branding', label: 'branding - Logo, icons, names, about pages' },
+                { value: 'ui', label: 'ui - User interface changes' },
+                { value: 'privacy', label: 'privacy - Telemetry, tracking, data collection' },
+                { value: 'security', label: 'security - Security hardening, policies' },
+                { value: 'infra', label: 'infra - Build system, tooling, CI, configuration' },
+            ],
+        });
+        if (isCancel(categoryResult)) {
+            cancel('Export cancelled');
+            return null;
+        }
+        category = categoryResult;
+    }
+    let description = options.description ?? '';
+    if (!description && isInteractive) {
+        const descResult = await text({
+            message: 'Enter a description (optional):',
+            placeholder: 'Brief description of what this patch does',
+        });
+        if (!isCancel(descResult)) {
+            description = String(descResult);
+        }
+    }
+    return {
+        patchName,
+        selectedCategory: category,
+        description,
+    };
+}
+/**
+ * Confirms whether an export may supersede existing patches.
+ * @param patchesDir - Patches directory
+ * @param filesAffected - Files touched by the pending export
+ * @param supersede - Explicit supersede flag from CLI options
+ * @param isInteractive - Whether interactive prompts are allowed
+ * @param s - Active spinner handle to stop before prompting
+ */
+export async function confirmSupersedePatches(patchesDir, filesAffected, supersede, isInteractive, s) {
+    const wouldSupersede = await findAllPatchesForFiles(patchesDir, filesAffected);
+    if (wouldSupersede.length === 0 || supersede) {
+        return true;
+    }
+    s.stop();
+    const count = wouldSupersede.length;
+    warn(`This export would supersede ${count} existing patch${count === 1 ? '' : 'es'}:`);
+    for (const patch of wouldSupersede) {
+        warn(`  - ${patch.filename}`);
+    }
+    if (!isInteractive) {
+        throw new GeneralError(`Refusing to supersede ${count} patch${count === 1 ? '' : 'es'} in non-interactive mode. ` +
+            'Use --supersede to confirm, or use "fireforge re-export" to update existing patches in place.');
+    }
+    const confirmed = await confirm({
+        message: `Supersede ${count} patch${count === 1 ? '' : 'es'}? This cannot be undone.`,
+        initialValue: false,
+    });
+    if (isCancel(confirmed) || !confirmed) {
+        cancel('Export cancelled');
+        return false;
+    }
+    return true;
+}
+/**
+ * Detects new files missing license headers and offers to add them.
+ *
+ * In interactive mode the user is prompted before any files are modified.
+ * In non-interactive mode the function is a no-op — the existing lint error
+ * will block the export instead.
+ *
+ * @param engineDir - Absolute path to engine directory
+ * @param diffContent - Current unified diff
+ * @param config - Project configuration
+ * @param isInteractive - Whether interactive prompts are available
+ * @returns true if files were modified on disk (caller must regenerate diff)
+ */
+export async function autoFixLicenseHeaders(engineDir, diffContent, config, isInteractive) {
+    const license = config.license ?? 'MPL-2.0';
+    const newFiles = detectNewFilesInDiff(diffContent);
+    if (newFiles.size === 0)
+        return false;
+    const filesToFix = [];
+    for (const file of newFiles) {
+        const style = commentStyleForFile(file);
+        if (!style)
+            continue;
+        const filePath = join(engineDir, file);
+        if (!(await pathExists(filePath)))
+            continue;
+        const content = await readText(filePath);
+        const expectedHeader = getLicenseHeader(license, style);
+        if (!content.startsWith(expectedHeader)) {
+            filesToFix.push(file);
+        }
+    }
+    if (filesToFix.length === 0)
+        return false;
+    if (!isInteractive)
+        return false;
+    const fileList = filesToFix.map((f) => `  - ${f}`).join('\n');
+    info(`${filesToFix.length} new file(s) missing the ${license} license header:\n${fileList}`);
+    const confirmed = await confirm({
+        message: `Add ${license} headers to ${filesToFix.length} file(s)?`,
+        initialValue: true,
+    });
+    if (isCancel(confirmed) || !confirmed)
+        return false;
+    for (const file of filesToFix) {
+        const style = commentStyleForFile(file);
+        if (!style)
+            continue;
+        const filePath = join(engineDir, file);
+        await addLicenseHeaderToFile(filePath, license, style);
+        info(`Added ${license} header to ${file}`);
+    }
+    return true;
+}
+//# sourceMappingURL=export-shared.js.map

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

@@ -0,0 +1,13 @@
+import { Command } from 'commander';
+import type { CommandContext } from '../types/cli.js';
+import type { ExportOptions } from '../types/commands/index.js';
+/**
+ * Runs the export command to export file changes as a patch.
+ * Accepts one or more file/directory paths and bundles them into a single patch.
+ * @param projectRoot - Root directory of the project
+ * @param files - File or directory paths to export (relative to engine/)
+ * @param options - Export options
+ */
+export declare function exportCommand(projectRoot: string, files: string[], options: ExportOptions): Promise<void>;
+/** Registers the export command on the CLI program. */
+export declare function registerExport(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/export.js

@@ -0,0 +1,178 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Option } from 'commander';
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { getStatusWithCodes, isGitRepository } from '../core/git.js';
+import { generateBinaryFilePatch, generateFullFilePatch } from '../core/git-diff.js';
+import { isBinaryFile } from '../core/git-file-ops.js';
+import { getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, } from '../core/git-status.js';
+import { extractAffectedFiles } from '../core/patch-apply.js';
+import { commitExportedPatch } from '../core/patch-export.js';
+import { GeneralError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { ensureDir, pathExists } from '../utils/fs.js';
+import { info, intro, outro, spinner, verbose, warn } from '../utils/logger.js';
+import { pickDefined } from '../utils/options.js';
+import { PATCH_CATEGORIES } from '../utils/validation.js';
+import { autoFixLicenseHeaders, confirmSupersedePatches, promptExportPatchMetadata, runPatchLint, } from './export-shared.js';
+async function collectExportFiles(paths, files) {
+    const collectedFiles = new Set();
+    let fileStatuses;
+    let untrackedFiles;
+    for (const inputPath of files) {
+        const fullInputPath = join(paths.engine, inputPath);
+        let isDirectory = false;
+        try {
+            const fileStat = await stat(fullInputPath);
+            isDirectory = fileStat.isDirectory();
+        }
+        catch (error) {
+            verbose(`Treating ${inputPath} as a file because directory stat failed: ${toError(error).message}`);
+        }
+        if (isDirectory) {
+            const dirPath = inputPath.endsWith('/') ? inputPath.slice(0, -1) : inputPath;
+            const modifiedFiles = await getModifiedFilesInDir(paths.engine, dirPath);
+            const dirUntrackedFiles = await getUntrackedFilesInDir(paths.engine, dirPath);
+            for (const f of modifiedFiles)
+                collectedFiles.add(f);
+            for (const f of dirUntrackedFiles)
+                collectedFiles.add(f);
+        }
+        else {
+            if (inputPath.endsWith('/')) {
+                throw new GeneralError(`"${inputPath}" is not a valid file or directory.`);
+            }
+            if (!fileStatuses) {
+                fileStatuses = await getStatusWithCodes(paths.engine);
+            }
+            const fileStatus = fileStatuses.find((s) => s.file === inputPath);
+            if (!fileStatus) {
+                if (!untrackedFiles) {
+                    untrackedFiles = await getUntrackedFiles(paths.engine);
+                }
+                if (!untrackedFiles.includes(inputPath)) {
+                    throw new GeneralError(`File "${inputPath}" has no changes to export.\n\n` +
+                        'Run "fireforge status" to see modified files.');
+                }
+            }
+            collectedFiles.add(inputPath);
+        }
+    }
+    return [...collectedFiles].sort();
+}
+async function generatePatchDiff(engineDir, allFiles) {
+    const diffs = [];
+    for (const file of allFiles) {
+        const fullPath = join(engineDir, file);
+        const isExistingBinary = (await pathExists(fullPath)) && (await isBinaryFile(engineDir, file));
+        const diff = isExistingBinary
+            ? await generateBinaryFilePatch(engineDir, file)
+            : await generateFullFilePatch(engineDir, file);
+        if (isExistingBinary) {
+            if (diff.trim()) {
+                info(`Including binary file: ${file}`);
+            }
+            else {
+                warn(`Skipping binary file with no diff: ${file}`);
+            }
+        }
+        if (diff.trim()) {
+            diffs.push(diff);
+        }
+    }
+    return diffs.join('\n');
+}
+/**
+ * Runs the export command to export file changes as a patch.
+ * Accepts one or more file/directory paths and bundles them into a single patch.
+ * @param projectRoot - Root directory of the project
+ * @param files - File or directory paths to export (relative to engine/)
+ * @param options - Export options
+ */
+export async function exportCommand(projectRoot, files, options) {
+    intro('FireForge Export');
+    const paths = getProjectPaths(projectRoot);
+    // Check if engine exists
+    if (!(await pathExists(paths.engine))) {
+        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
+    }
+    // Check if it's a git repository
+    if (!(await isGitRepository(paths.engine))) {
+        throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
+    }
+    const allFiles = await collectExportFiles(paths, files);
+    if (allFiles.length === 0) {
+        const pathList = files.join(', ');
+        throw new GeneralError(`Paths "${pathList}" have no changes to export.\n\n` +
+            'Run "fireforge status" to see modified files.');
+    }
+    let diff = await generatePatchDiff(paths.engine, allFiles);
+    if (!diff.trim()) {
+        throw new GeneralError('The specified paths have no diff content to export.');
+    }
+    // Ensure patches directory exists
+    await ensureDir(paths.patches);
+    const config = await loadConfig(projectRoot);
+    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+    // Auto-fix missing license headers on new files (interactive only)
+    const headersAdded = await autoFixLicenseHeaders(paths.engine, diff, config, isInteractive);
+    if (headersAdded) {
+        diff = await generatePatchDiff(paths.engine, allFiles);
+    }
+    const metadata = await promptExportPatchMetadata(options, isInteractive, 'export');
+    if (!metadata)
+        return;
+    const { patchName, selectedCategory, description } = metadata;
+    const s = spinner('Exporting patch...');
+    try {
+        // Extract affected files from diff
+        const filesAffected = extractAffectedFiles(diff);
+        await runPatchLint(paths.engine, filesAffected, diff, config, options.skipLint);
+        // Check how many existing patches would be superseded
+        const shouldProceed = await confirmSupersedePatches(paths.patches, filesAffected, options.supersede, isInteractive, s);
+        if (!shouldProceed)
+            return;
+        const { patchFilename, superseded } = await commitExportedPatch({
+            patchesDir: paths.patches,
+            category: selectedCategory,
+            name: patchName,
+            description,
+            diff,
+            filesAffected,
+            sourceEsrVersion: config.firefox.version,
+        });
+        for (const oldPatch of superseded) {
+            info(`Superseded: ${oldPatch.filename}`);
+        }
+        s.stop(`Exported to ${patchFilename}`);
+        info(`\nPatch saved to: patches/${patchFilename}`);
+        if (filesAffected.length > 0) {
+            info(`Files affected: ${filesAffected.join(', ')}`);
+        }
+        outro('Export complete');
+    }
+    catch (error) {
+        s.error('Export failed');
+        throw error;
+    }
+}
+/** Registers the export command on the CLI program. */
+export function registerExport(program, { getProjectRoot, withErrorHandling }) {
+    program
+        .command('export <paths...>')
+        .description('Export new changes as a patch (use re-export to update existing patches)')
+        .option('-n, --name <name>', 'Name for the patch')
+        .addOption(new Option('-c, --category <category>', 'Patch category').choices([...PATCH_CATEGORIES]))
+        .option('-d, --description <desc>', 'Description of the patch')
+        .option('--supersede', 'Allow superseding multiple existing patches')
+        .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
+        .action(withErrorHandling(async (paths, options) => {
+        const { category, ...rest } = options;
+        await exportCommand(getProjectRoot(), paths, {
+            ...pickDefined(rest),
+            ...(category !== undefined ? { category: category } : {}),
+        });
+    }));
+}
+//# sourceMappingURL=export.js.map

package/dist/src/commands/furnace/apply.d.ts

@@ -0,0 +1,7 @@
+import type { FurnaceApplyOptions } from '../../types/commands/index.js';
+/**
+ * Runs the furnace apply command to apply all components to the engine.
+ * @param projectRoot - Root directory of the project
+ * @param options - Apply options
+ */
+export declare function furnaceApplyCommand(projectRoot: string, options?: FurnaceApplyOptions): Promise<void>;

package/dist/src/commands/furnace/apply.js

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { getProjectPaths } from '../../core/config.js';
+import { applyAllComponents } from '../../core/furnace-apply.js';
+import { furnaceConfigExists, loadFurnaceConfig } from '../../core/furnace-config.js';
+import { FurnaceError } from '../../errors/furnace.js';
+import { pathExists } from '../../utils/fs.js';
+import { error, info, intro, outro, spinner, success, warn } from '../../utils/logger.js';
+/**
+ * Runs the furnace apply command to apply all components to the engine.
+ * @param projectRoot - Root directory of the project
+ * @param options - Apply options
+ */
+export async function furnaceApplyCommand(projectRoot, options = {}) {
+    intro('Furnace Apply');
+    // Verify engine exists
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.engine))) {
+        throw new FurnaceError('Engine directory not found. Run "fireforge download" first.');
+    }
+    // Load furnace config
+    if (!(await furnaceConfigExists(projectRoot))) {
+        throw new FurnaceError('No furnace.json found. Run "fireforge furnace create" or "fireforge furnace override" to get started.');
+    }
+    const config = await loadFurnaceConfig(projectRoot);
+    const overrideCount = Object.keys(config.overrides).length;
+    const customCount = Object.keys(config.custom).length;
+    if (overrideCount === 0 && customCount === 0) {
+        info('No components to apply.');
+        outro('Done');
+        return;
+    }
+    const dryRun = options.dryRun ?? false;
+    const applySpinner = dryRun ? undefined : spinner('Applying components to engine...');
+    const result = await applyAllComponents(projectRoot, dryRun);
+    if (applySpinner) {
+        applySpinner.stop('Components applied');
+    }
+    // Report applied
+    for (const applied of result.applied) {
+        const prefix = dryRun ? '[dry-run] Would apply' : '';
+        const label = dryRun
+            ? `${prefix} ${applied.name} (${applied.type}) → ${applied.filesAffected.length} files`
+            : `${applied.name} (${applied.type}) → ${applied.filesAffected.length} files`;
+        if (dryRun) {
+            info(label);
+        }
+        else {
+            success(label);
+        }
+        if (applied.stepErrors && applied.stepErrors.length > 0) {
+            for (const stepErr of applied.stepErrors) {
+                warn(`${applied.name}: [${stepErr.step}] ${stepErr.error}`);
+            }
+        }
+    }
+    // Report skipped
+    for (const skipped of result.skipped) {
+        info(`${skipped.name} — ${skipped.reason}`);
+    }
+    // Report errors
+    for (const err of result.errors) {
+        error(`${err.name} — ${err.error}`);
+    }
+    const stepFailureCount = dryRun
+        ? 0
+        : result.applied.filter((entry) => (entry.stepErrors?.length ?? 0) > 0).length;
+    const totalApplyFailures = result.errors.length + stepFailureCount;
+    if (totalApplyFailures > 0) {
+        throw new FurnaceError(`${totalApplyFailures} component${totalApplyFailures === 1 ? '' : 's'} failed to apply cleanly`);
+    }
+    const appliedCount = result.applied.length;
+    const skippedCount = result.skipped.length;
+    if (dryRun) {
+        outro(`Dry run complete — would apply ${appliedCount}, skip ${skippedCount}`);
+    }
+    else {
+        outro(`Applied ${appliedCount}, skipped ${skippedCount}`);
+    }
+}
+//# sourceMappingURL=apply.js.map

package/dist/src/commands/furnace/create.d.ts

@@ -0,0 +1,8 @@
+import type { FurnaceCreateOptions } from '../../types/commands/index.js';
+/**
+ * Runs the furnace create command to scaffold a new custom component.
+ * @param projectRoot - Root directory of the project
+ * @param name - Optional component tag name (prompted if not provided)
+ * @param options - CLI options for non-interactive mode
+ */
+export declare function furnaceCreateCommand(projectRoot: string, name?: string, options?: FurnaceCreateOptions): Promise<void>;