@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/core/furnace-precondition.d.ts

@@ -1,61 +0,0 @@
-/**
- * Shared precondition ladder for the Furnace command family: engine exists,
- * `furnace.json` exists.
- *
- * Kept separate from the `GeneralError` ladder in `engine-precondition.ts`
- * because the error class matters here and is not merely cosmetic:
- * `FurnaceError` carries its own `userMessage` and exit code 9, so a helper
- * raising `GeneralError` would silently change both.
- *
- * Four sites are not routed through this helper: `furnace list`,
- * `furnace status`, `furnace init`, and `verify`. Each informs rather than
- * refuses, and each says so at its own site. `furnace validate` refusing is
- * the intended line between inspecting and validating.
- */
-import type { FurnaceConfig } from '../types/furnace.js';
-import type { ProjectPaths } from '../types/index.js';
-/** Options shared by the Furnace precondition assertions. */
-export interface FurnacePreconditionOptions {
-    /**
-     * Appended to the engine-missing refusal, e.g.
-     * `' to scaffold a chrome-doc.'`. The base message ends without
-     * punctuation so the suffix reads as one sentence. Callers passing nothing
-     * get a plain full stop.
-     */
-    engineMissingSuffix?: string;
-}
-/**
- * Asserts that a specific engine directory exists, raising a `FurnaceError`.
- *
- * The path-taking form, for core helpers that already hold `engineDir` and
- * have no project root to derive it from.
- *
- * @param engineDir - Absolute path to the engine checkout
- * @param options - Optional message tailoring
- */
-export declare function assertFurnaceEngineDirReady(engineDir: string, options?: FurnacePreconditionOptions): Promise<void>;
-/**
- * Asserts that the engine checkout exists, raising a `FurnaceError`.
- *
- * The engine rung on its own, for the Furnace commands that scaffold or
- * mutate component sources without needing `furnace.json` to exist yet.
- *
- * @param projectRoot - Project root directory
- * @param options - Optional message tailoring
- * @returns Resolved project paths, so callers do not re-derive them
- */
-export declare function assertFurnaceEngineReady(projectRoot: string, options?: FurnacePreconditionOptions): Promise<{
-    paths: ProjectPaths;
-}>;
-/**
- * Asserts the full Furnace ladder (engine checkout, then `furnace.json`)
- * and returns the loaded config so callers do not read it a second time.
- *
- * @param projectRoot - Project root directory
- * @param options - Optional message tailoring
- * @returns Resolved project paths and the loaded furnace config
- */
-export declare function assertFurnaceReady(projectRoot: string, options?: FurnacePreconditionOptions): Promise<{
-    paths: ProjectPaths;
-    config: FurnaceConfig;
-}>;

package/dist/src/core/furnace-precondition.js

@@ -1,67 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Shared precondition ladder for the Furnace command family: engine exists,
- * `furnace.json` exists.
- *
- * Kept separate from the `GeneralError` ladder in `engine-precondition.ts`
- * because the error class matters here and is not merely cosmetic:
- * `FurnaceError` carries its own `userMessage` and exit code 9, so a helper
- * raising `GeneralError` would silently change both.
- *
- * Four sites are not routed through this helper: `furnace list`,
- * `furnace status`, `furnace init`, and `verify`. Each informs rather than
- * refuses, and each says so at its own site. `furnace validate` refusing is
- * the intended line between inspecting and validating.
- */
-import { FurnaceError } from '../errors/furnace.js';
-import { pathExists } from '../utils/fs.js';
-import { getProjectPaths } from './config-paths.js';
-import { furnaceConfigExists, loadFurnaceConfig } from './furnace-config.js';
-/**
- * Asserts that a specific engine directory exists, raising a `FurnaceError`.
- *
- * The path-taking form, for core helpers that already hold `engineDir` and
- * have no project root to derive it from.
- *
- * @param engineDir - Absolute path to the engine checkout
- * @param options - Optional message tailoring
- */
-export async function assertFurnaceEngineDirReady(engineDir, options = {}) {
-    if (!(await pathExists(engineDir))) {
-        throw new FurnaceError(`Engine directory not found. Run "fireforge download" first${options.engineMissingSuffix ?? '.'}`);
-    }
-}
-/**
- * Asserts that the engine checkout exists, raising a `FurnaceError`.
- *
- * The engine rung on its own, for the Furnace commands that scaffold or
- * mutate component sources without needing `furnace.json` to exist yet.
- *
- * @param projectRoot - Project root directory
- * @param options - Optional message tailoring
- * @returns Resolved project paths, so callers do not re-derive them
- */
-export async function assertFurnaceEngineReady(projectRoot, options = {}) {
-    const paths = getProjectPaths(projectRoot);
-    await assertFurnaceEngineDirReady(paths.engine, options);
-    return { paths };
-}
-/**
- * Asserts the full Furnace ladder (engine checkout, then `furnace.json`)
- * and returns the loaded config so callers do not read it a second time.
- *
- * @param projectRoot - Project root directory
- * @param options - Optional message tailoring
- * @returns Resolved project paths and the loaded furnace config
- */
-export async function assertFurnaceReady(projectRoot, options = {}) {
-    const { paths } = await assertFurnaceEngineReady(projectRoot, options);
-    // `loadFurnaceConfig` refuses on its own with a fuller message, but the
-    // probe stays: it produces the shorter, action-first refusal the command
-    // layer has always shown for "you have not set Furnace up yet", which is a
-    // different situation from "your furnace.json is unreadable".
-    if (!(await furnaceConfigExists(projectRoot))) {
-        throw new FurnaceError('No furnace.json found. Run "fireforge furnace create" or "fireforge furnace override" to get started.');
-    }
-    return { paths, config: await loadFurnaceConfig(projectRoot) };
-}

package/dist/src/core/furnace-refresh.d.ts

@@ -1,28 +0,0 @@
-export interface RefreshFileResult {
-    fileName: string;
-    status: 'merged' | 'conflict' | 'unchanged' | 'new-file';
-    conflictMarkers?: number;
-}
-export interface RefreshOverrideFileOptions {
-    /** Path to the engine git repository. */
-    engineDir: string;
-    /** Path to the current override file in the workspace. */
-    overridePath: string;
-    /** Engine-relative path for git show. */
-    engineRelPath: string;
-    /** The git ref at which the override was originally created. */
-    baseCommit: string;
-    /** Display name for the file. */
-    fileName: string;
-    /** When true, compute the merge but write nothing. */
-    dryRun?: boolean | undefined;
-    /** Conflict resolution preference handed to `git merge-file`. */
-    strategy?: 'ours' | 'theirs' | undefined;
-}
-/**
- * Refreshes a single override file against the current engine HEAD.
- *
- * @param options - See {@link RefreshOverrideFileOptions}
- * @returns Merge result with the updated content written to the override file
- */
-export declare function refreshOverrideFile(options: RefreshOverrideFileOptions): Promise<RefreshFileResult>;

package/dist/src/core/furnace-refresh.js

@@ -1,125 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Three-way merge logic for refreshing overrides against a newer Firefox baseline.
- *
- * When Firefox moves forward and an override's `baseVersion` drifts, the user
- * needs a way to incorporate upstream changes into their override workspace
- * without losing local modifications. This module uses `git merge-file` to
- * perform a three-way merge between the old baseline, the current override,
- * and the new upstream content.
- */
-import { randomUUID } from 'node:crypto';
-import { unlink } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { FurnaceError } from '../errors/furnace.js';
-import { readText, writeText } from '../utils/fs.js';
-import { exec } from '../utils/process.js';
-import { ensureGit } from './git-base.js';
-import { getFileContentAtRef } from './git-file-ops.js';
-function isFatalMergeStderr(stderr) {
-    return /(?:^|\n)\s*(?:fatal|error):/i.test(stderr);
-}
-function classifyMergeFileResult(result) {
-    if (result.exitCode === 0 && !isFatalMergeStderr(result.stderr)) {
-        return 0;
-    }
-    if (result.exitCode >= 1 && result.exitCode <= 127 && !isFatalMergeStderr(result.stderr)) {
-        return result.exitCode;
-    }
-    const detail = result.stderr.trim() || `exit code ${result.exitCode}`;
-    throw new FurnaceError(`git merge-file failed: ${detail}`);
-}
-/**
- * Performs a three-way merge on a single file.
- *
- * Uses `git merge-file` with:
- *   - base: the original Firefox content at the override's recorded baseCommit
- *   - ours: the current override workspace content (local modifications)
- *   - theirs: the current Firefox content at HEAD
- *
- * @returns The merged content and the number of conflict markers (0 = clean merge)
- */
-async function threeWayMergeFile(base, ours, theirs, label, strategy) {
-    await ensureGit();
-    // Write all three versions to temp files for git merge-file.
-    // Use crypto.randomUUID() for unique, unpredictable temp file names.
-    const id = randomUUID();
-    const tempBase = join(tmpdir(), `fireforge-merge-base-${id}`);
-    const tempOurs = join(tmpdir(), `fireforge-merge-ours-${id}`);
-    const tempTheirs = join(tmpdir(), `fireforge-merge-theirs-${id}`);
-    try {
-        await writeText(tempBase, base);
-        await writeText(tempOurs, ours);
-        await writeText(tempTheirs, theirs);
-        // git merge-file writes the result to the first file (ours) in-place.
-        // Exit code 0 = clean merge, 1..127 = conflict count, shell-exposed
-        // fatal errors typically arrive as >=128 (for example, 255).
-        const mergeArgs = [
-            'merge-file',
-            ...(strategy ? [`--${strategy}`] : []),
-            '-L',
-            label.ours,
-            '-L',
-            label.base,
-            '-L',
-            label.theirs,
-            tempOurs,
-            tempBase,
-            tempTheirs,
-        ];
-        const result = await exec('git', mergeArgs);
-        const conflicts = classifyMergeFileResult(result);
-        const merged = await readText(tempOurs);
-        return { merged, conflicts };
-    }
-    finally {
-        // Clean up temp files (best-effort)
-        await Promise.allSettled([unlink(tempBase), unlink(tempOurs), unlink(tempTheirs)]);
-    }
-}
-/**
- * Refreshes a single override file against the current engine HEAD.
- *
- * @param options - See {@link RefreshOverrideFileOptions}
- * @returns Merge result with the updated content written to the override file
- */
-export async function refreshOverrideFile(options) {
-    const { engineDir, overridePath, engineRelPath, baseCommit, fileName, dryRun, strategy } = options;
-    // Read the three versions
-    const oursContent = await readText(overridePath);
-    const baseContent = await getFileContentAtRef(engineDir, engineRelPath, baseCommit);
-    if (baseContent === null) {
-        // File didn't exist at baseCommit: this is a new file introduced by the override
-        return { fileName, status: 'new-file' };
-    }
-    const theirsContent = await getFileContentAtRef(engineDir, engineRelPath, 'HEAD');
-    if (theirsContent === null) {
-        // File was removed upstream, so no merge is needed. Keep the override as-is
-        return { fileName, status: 'unchanged' };
-    }
-    // If upstream hasn't changed, nothing to merge
-    if (baseContent === theirsContent) {
-        return { fileName, status: 'unchanged' };
-    }
-    // If our override matches the base (no local changes), just take theirs
-    if (oursContent === baseContent) {
-        if (!dryRun) {
-            await writeText(overridePath, theirsContent);
-        }
-        return { fileName, status: 'merged' };
-    }
-    // Three-way merge
-    const { merged, conflicts } = await threeWayMergeFile(baseContent, oursContent, theirsContent, {
-        ours: `components/overrides/${fileName} (your changes)`,
-        base: `Firefox ${baseCommit.slice(0, 8)} (original)`,
-        theirs: `Firefox HEAD (upstream)`,
-    }, strategy);
-    if (!dryRun) {
-        await writeText(overridePath, merged);
-    }
-    if (conflicts > 0) {
-        return { fileName, status: 'conflict', conflictMarkers: conflicts };
-    }
-    return { fileName, status: 'merged' };
-}

package/dist/src/core/furnace-registration-ast.d.ts

@@ -1,53 +0,0 @@
-/**
- * AST-based custom element registration updates for customElements.js.
- * Removal logic is in furnace-registration-remove.ts.
- */
-/**
- * Returns true when `content` already contains a registration for `tagName`.
- *
- * Tolerates trailing line comments (e.g. a project marker like `// MYBROWSER:`)
- * that an operator may have appended to entries written by a previous apply.
- * Without this, a re-apply would insert a duplicate entry, and the second
- * `setElementCreationCallback` at window-load would throw `NotSupportedError`.
- *
- * Matches any of:
- *   1. `setElementCreationCallback("tag"` / `setElementCreationCallback('tag'`
- *   2. Single-line array entry: `["tag", "..."]` (column 0 only, comments allowed after)
- *   3. Multi-line array entry: `"tag",` on its own line, optional trailing `//` comment
- */
-export declare function isTagAlreadyRegistered(content: string, tagName: string): boolean;
-/**
- * Options that shape the lines `addCustomElementRegistration` writes into
- * `customElements.js`. Kept optional so existing call sites keep working.
- */
-export interface RegistrationWriteOptions {
-    /**
-     * Trailing project marker appended to every inserted line (e.g. `"MYBROWSER"`
-     * produces `  // MYBROWSER:` at end-of-line). Keeps modifications discoverable
-     * without requiring the operator to hand-tag them post-apply.
-     */
-    markerComment?: string;
-}
-/**
- * Adds a custom element registration entry to customElements.js.
- *
- * The entry is inserted into the array literal inside the `for...of` loop
- * that registers all custom elements:
- * ```js
- *   ["tag", "chrome://global/content/elements/tag.mjs"],
- * ```
- *
- * New entries are inserted in alphabetical order relative to existing entries.
- * This operation is idempotent: if the tag is already registered the file is
- * left unchanged.
- *
- * @param engineDir - Path to the Firefox engine source root
- * @param tagName - Custom element tag name
- * @param modulePath - chrome:// URI for the module
- */
-export declare function addCustomElementRegistration(engineDir: string, tagName: string, modulePath: string, options?: RegistrationWriteOptions): Promise<void>;
-/**
- * Validates that a custom element registration *would* succeed without
- * writing anything. Used by dry-run to surface registration errors early.
- */
-export declare function validateCustomElementRegistration(engineDir: string, tagName: string, modulePath: string): Promise<void>;