@hominis/fireforge 0.10.1 → 0.11.0

package/dist/src/core/destructive.js

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Shared destructive-operation contract: interactive confirmation, non-TTY
+ * refusal, dry-run plumbing, hard-refusal on structural conflicts, and a
+ * JSONL audit log.
+ *
+ * This exists because the repair primitives (`patch delete`, `patch reorder`,
+ * `re-export --files`) and the new `export --dry-run`/`export --order` flags
+ * all share the same dance: build a change summary, gate it behind a prompt,
+ * accept a `--yes` bypass for CI, accept a `--dry-run` no-op, and refuse
+ * outright when the change would introduce a structural conflict (e.g. a
+ * forward-import that later-patch lint would then block). Without a single
+ * helper, every new destructive command would re-implement this and drift.
+ */
+import { appendFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { confirm } from '@clack/prompts';
+import { InvalidArgumentError } from '../errors/base.js';
+import { ensureDir } from '../utils/fs.js';
+import { info, isCancel, warn } from '../utils/logger.js';
+/** Filename of the audit log, relative to the patches directory. */
+export const HISTORY_LOG_FILENAME = '.fireforge-history.jsonl';
+/**
+ * Prints the change summary lines at warn-severity so the prompt stands out.
+ */
+function printSummary(title, summary) {
+    warn(title);
+    for (const line of summary) {
+        info(`  ${line}`);
+    }
+}
+/**
+ * Prints a conflict report at warn-severity. Used by both the refusal path
+ * and the dry-run-with-conflicts preview path.
+ */
+function printConflicts(conflicts) {
+    warn(`Refused: ${conflicts.reason}`);
+    for (const detail of conflicts.details) {
+        info(`  ${detail}`);
+    }
+}
+/**
+ * Executes the destructive-operation contract: summary → conflict refusal →
+ * dry-run / force / prompt / non-TTY refusal.
+ *
+ * Returns the decision for the caller to act on; callers must not execute the
+ * mutation when the result is `'dry-run'` or `'cancelled'`, and must call
+ * {@link appendHistory} only after the mutation succeeds (never on dry-run or
+ * cancellation).
+ *
+ * @param input - Operation description, flags, and optional conflict report
+ * @returns `'proceed'` to execute, `'dry-run'` to skip execution, or
+ *   `'cancelled'` when the user declined the prompt
+ */
+export async function confirmDestructive(input) {
+    const { operation, title, summary, yes, dryRun, unsafeOverride, conflicts } = input;
+    // Dry-run: print everything that would happen (including refusal notice if
+    // the real run would be refused), but never mutate and never prompt.
+    if (dryRun) {
+        printSummary(`[dry-run] ${title}`, summary);
+        if (conflicts) {
+            printConflicts(conflicts);
+            info('  The non-dry-run would be refused. Use --force-unsafe only if you accept the risk.');
+        }
+        return 'dry-run';
+    }
+    // Hard refusal: structural conflicts are only bypassable by --force-unsafe,
+    // never by plain --yes. The distinction exists so that `--yes` can
+    // remain a safe-for-CI bypass of interactive prompts without also being a
+    // lint-override.
+    if (conflicts && !unsafeOverride) {
+        printConflicts(conflicts);
+        throw new InvalidArgumentError(`Refusing to run "${operation}": ${conflicts.reason}. ` +
+            'Fix the underlying issue (usually re-export --files or a different target), ' +
+            'or pass --force-unsafe if you genuinely accept the risk.', `--force-unsafe`);
+    }
+    if (conflicts && unsafeOverride) {
+        printConflicts(conflicts);
+        info('  Proceeding because --force-unsafe was provided.');
+    }
+    // --yes bypasses confirmation but not the non-dry-run execution path.
+    // Still print the summary so the operator (or CI log) has a record of what
+    // happened even when no prompt was shown.
+    if (yes) {
+        printSummary(title, summary);
+        return 'proceed';
+    }
+    // Non-TTY without --yes: refuse with a clear message pointing at --yes.
+    // Never silently proceed.
+    // Node types `isTTY` as `boolean`, but at runtime it is `true | undefined`
+    // (absent when the handle is not a TTY). Unusual harnesses (vitest stdio
+    // capture, CI spawners, mocked pipes) can also leave it unset on only
+    // one handle. We cast to the real runtime type and compare against
+    // literal `true` so any falsy variant — false, undefined, or a
+    // null-patched mock — routes to the non-interactive path.
+    const stdinIsTTY = process.stdin.isTTY;
+    const stdoutIsTTY = process.stdout.isTTY;
+    const isInteractive = stdinIsTTY === true && stdoutIsTTY === true;
+    if (!isInteractive) {
+        printSummary(title, summary);
+        throw new InvalidArgumentError(`Interactive confirmation not available for "${operation}". ` +
+            'Use --yes to run non-interactively (required for CI).', '--yes');
+    }
+    // Interactive path: print the summary first so the user sees the full
+    // picture, then prompt. Cancellation and negative answer both map to
+    // 'cancelled' so the caller can return without running anything.
+    printSummary(title, summary);
+    const confirmed = await confirm({
+        message: `${title} — proceed?`,
+        initialValue: false,
+    });
+    if (isCancel(confirmed) || confirmed !== true) {
+        return 'cancelled';
+    }
+    return 'proceed';
+}
+/**
+ * Appends a single JSONL record to `patches/.fireforge-history.jsonl`.
+ *
+ * Call order matters: append only after the mutation succeeds, never
+ * pre-emptively, so rolled-back failures do not leave ghost entries. The log
+ * is append-only and advisory — no code path reads it back; it exists purely
+ * so operators have a post-hoc audit trail when something goes wrong.
+ *
+ * @param patchesDir - Path to the patches directory
+ * @param entry - Serializable history record
+ */
+export async function appendHistory(patchesDir, entry) {
+    await ensureDir(patchesDir);
+    const record = {
+        ts: new Date().toISOString(),
+        ...entry,
+    };
+    const line = `${JSON.stringify(record)}\n`;
+    await appendFile(join(patchesDir, HISTORY_LOG_FILENAME), line, 'utf-8');
+}
+//# sourceMappingURL=destructive.js.map

package/dist/src/core/diff-hunks.d.ts

@@ -0,0 +1,73 @@
+/**
+ * An edit op produced by {@link computeLineDiff}. Indices are 0-based into the
+ * source line arrays; `line` holds the verbatim text so callers do not have to
+ * keep the input arrays around while rendering.
+ */
+export interface LineDiffOp {
+    type: 'equal' | 'delete' | 'insert';
+    oldIndex?: number;
+    newIndex?: number;
+    line: string;
+}
+/**
+ * A single line inside a hunk, rendered as one of the three unified-diff
+ * markers. Content is the raw line text with no marker prefix so callers can
+ * apply their own coloring before the prefix is added.
+ */
+export interface HunkLine {
+    marker: ' ' | '-' | '+';
+    content: string;
+}
+/**
+ * A unified-diff hunk. Line numbers are 1-based to match `@@ -X,N +Y,M @@`
+ * convention.
+ */
+export interface DiffHunk {
+    oldStart: number;
+    oldLength: number;
+    newStart: number;
+    newLength: number;
+    lines: HunkLine[];
+}
+/**
+ * A pre-split line output ready for the caller to apply color and emit. Kept
+ * free of color codes so the same structure can be unit-tested without
+ * depending on the logger.
+ */
+export interface RenderedDiffLine {
+    kind: 'header' | 'context' | 'removed' | 'added';
+    text: string;
+}
+/**
+ * LCS-based line diff. Runs in O(m·n) time and memory using a single flat
+ * `Int32Array` for the DP table. Guarded by {@link LCS_LINE_LIMIT} so callers
+ * on very large files transparently get the coalesced fallback instead of
+ * allocating hundreds of megabytes.
+ *
+ * Behavior note: the backtrack walks diagonals in a deterministic order, so
+ * the same input always produces the same op sequence. This matters for
+ * snapshot tests and for UI stability when the user re-runs `furnace diff`.
+ */
+export declare function computeLineDiff(oldLines: readonly string[], newLines: readonly string[]): LineDiffOp[];
+/**
+ * Groups an op stream into unified-diff hunks with `context` lines of
+ * surrounding equal-line context. Adjacent edit runs whose expanded context
+ * regions overlap are merged into a single hunk, matching `diff -U N`.
+ *
+ * Returns an empty array when the two inputs were identical.
+ */
+export declare function buildHunks(ops: readonly LineDiffOp[], context: number): DiffHunk[];
+/**
+ * Computes a multi-hunk line diff between two strings. This is the public
+ * entry point that {@link furnaceDiffCommand} uses. On normal inputs this
+ * runs the exact LCS path and returns a proper multi-hunk diff; on inputs
+ * that exceed {@link LCS_LINE_LIMIT} it falls back to a single coalesced
+ * hunk so the command stays useful instead of OOMing.
+ */
+export declare function diffLines(oldText: string, newText: string, context?: number): DiffHunk[];
+/**
+ * Renders hunks into a flat list of lines the caller can emit one by one.
+ * Kept color-free so unit tests can assert exact output and so the caller
+ * can apply its own formatting (e.g. `formatErrorText` / `formatSuccessText`).
+ */
+export declare function renderHunks(hunks: readonly DiffHunk[]): RenderedDiffLine[];

package/dist/src/core/diff-hunks.js

@@ -0,0 +1,268 @@
+// SPDX-License-Identifier: EUPL-1.2
+/* eslint-disable @typescript-eslint/no-non-null-assertion --
+ * This module is a tight DP/backtrack line-diff whose bounds are checked
+ * structurally (every index into `ops`, `dp`, or the line arrays is either
+ * guarded by an explicit `k < range.end` / `i <= m` loop condition or sits
+ * inside an array built and consumed in the same function). Wrapping every
+ * access in an `if (value === undefined) throw` branch would bloat the hot
+ * path without catching a real class of bugs — the non-null assertions here
+ * encode the invariant the surrounding logic already guarantees.
+ */
+/**
+ * Maximum combined LCS table side-length before we bail out of the exact
+ * O(m·n) diff and fall back to the simpler single-region coalesce. Chosen so
+ * the worst-case Int32Array allocation stays under ~16 MB. Typical Firefox
+ * widget files are a few hundred lines, so the fast path handles the
+ * everyday case; the fallback exists purely to keep the command usable if
+ * someone overrides a very large file.
+ */
+const LCS_LINE_LIMIT = 2000;
+/** Splits a string on `\n`, discarding a single trailing empty line from a terminal newline. */
+function splitLines(text) {
+    const lines = text.split('\n');
+    if (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    return lines;
+}
+/**
+ * LCS-based line diff. Runs in O(m·n) time and memory using a single flat
+ * `Int32Array` for the DP table. Guarded by {@link LCS_LINE_LIMIT} so callers
+ * on very large files transparently get the coalesced fallback instead of
+ * allocating hundreds of megabytes.
+ *
+ * Behavior note: the backtrack walks diagonals in a deterministic order, so
+ * the same input always produces the same op sequence. This matters for
+ * snapshot tests and for UI stability when the user re-runs `furnace diff`.
+ */
+export function computeLineDiff(oldLines, newLines) {
+    const m = oldLines.length;
+    const n = newLines.length;
+    const dp = new Int32Array((m + 1) * (n + 1));
+    const stride = n + 1;
+    for (let i = 1; i <= m; i++) {
+        const oldLine = oldLines[i - 1];
+        const rowOffset = i * stride;
+        const prevRowOffset = (i - 1) * stride;
+        for (let j = 1; j <= n; j++) {
+            if (oldLine === newLines[j - 1]) {
+                dp[rowOffset + j] = dp[prevRowOffset + j - 1] + 1;
+            }
+            else {
+                const up = dp[prevRowOffset + j];
+                const left = dp[rowOffset + j - 1];
+                dp[rowOffset + j] = up >= left ? up : left;
+            }
+        }
+    }
+    const ops = [];
+    let i = m;
+    let j = n;
+    while (i > 0 && j > 0) {
+        if (oldLines[i - 1] === newLines[j - 1]) {
+            ops.push({ type: 'equal', oldIndex: i - 1, newIndex: j - 1, line: oldLines[i - 1] });
+            i--;
+            j--;
+            continue;
+        }
+        const up = dp[(i - 1) * stride + j];
+        const left = dp[i * stride + j - 1];
+        if (up >= left) {
+            ops.push({ type: 'delete', oldIndex: i - 1, line: oldLines[i - 1] });
+            i--;
+        }
+        else {
+            ops.push({ type: 'insert', newIndex: j - 1, line: newLines[j - 1] });
+            j--;
+        }
+    }
+    while (i > 0) {
+        ops.push({ type: 'delete', oldIndex: i - 1, line: oldLines[i - 1] });
+        i--;
+    }
+    while (j > 0) {
+        ops.push({ type: 'insert', newIndex: j - 1, line: newLines[j - 1] });
+        j--;
+    }
+    ops.reverse();
+    return ops;
+}
+/**
+ * Groups an op stream into unified-diff hunks with `context` lines of
+ * surrounding equal-line context. Adjacent edit runs whose expanded context
+ * regions overlap are merged into a single hunk, matching `diff -U N`.
+ *
+ * Returns an empty array when the two inputs were identical.
+ */
+export function buildHunks(ops, context) {
+    const editRanges = [];
+    let i = 0;
+    while (i < ops.length) {
+        if (ops[i].type !== 'equal') {
+            const start = i;
+            while (i < ops.length && ops[i].type !== 'equal')
+                i++;
+            editRanges.push({ start, end: i });
+        }
+        else {
+            i++;
+        }
+    }
+    if (editRanges.length === 0)
+        return [];
+    const expanded = [];
+    for (const range of editRanges) {
+        const start = Math.max(0, range.start - context);
+        const end = Math.min(ops.length, range.end + context);
+        const prev = expanded[expanded.length - 1];
+        if (prev && start <= prev.end) {
+            prev.end = Math.max(prev.end, end);
+        }
+        else {
+            expanded.push({ start, end });
+        }
+    }
+    const hunks = [];
+    for (const range of expanded) {
+        let oldLine = 1;
+        let newLine = 1;
+        for (let k = 0; k < range.start; k++) {
+            const op = ops[k];
+            if (op.type === 'equal') {
+                oldLine++;
+                newLine++;
+            }
+            else if (op.type === 'delete') {
+                oldLine++;
+            }
+            else {
+                newLine++;
+            }
+        }
+        const hunkLines = [];
+        let oldLength = 0;
+        let newLength = 0;
+        for (let k = range.start; k < range.end; k++) {
+            const op = ops[k];
+            if (op.type === 'equal') {
+                hunkLines.push({ marker: ' ', content: op.line });
+                oldLength++;
+                newLength++;
+            }
+            else if (op.type === 'delete') {
+                hunkLines.push({ marker: '-', content: op.line });
+                oldLength++;
+            }
+            else {
+                hunkLines.push({ marker: '+', content: op.line });
+                newLength++;
+            }
+        }
+        hunks.push({
+            oldStart: oldLength === 0 ? oldLine - 1 : oldLine,
+            oldLength,
+            newStart: newLength === 0 ? newLine - 1 : newLine,
+            newLength,
+            lines: hunkLines,
+        });
+    }
+    return hunks;
+}
+/**
+ * Fallback for inputs that exceed {@link LCS_LINE_LIMIT}. Reproduces the
+ * original single-region coalesce: match the common prefix and suffix, then
+ * emit one hunk containing the middle region plus `context` lines on each
+ * side. Intentionally dumb — the fast path handles normal files, and this
+ * only keeps the command usable on pathologically large inputs without
+ * allocating a huge DP table.
+ */
+function coalescedHunk(oldLines, newLines, context) {
+    let firstDiff = 0;
+    while (firstDiff < oldLines.length && firstDiff < newLines.length) {
+        if (oldLines[firstDiff] !== newLines[firstDiff])
+            break;
+        firstDiff++;
+    }
+    let lastOldDiff = oldLines.length - 1;
+    let lastNewDiff = newLines.length - 1;
+    while (lastOldDiff >= firstDiff && lastNewDiff >= firstDiff) {
+        if (oldLines[lastOldDiff] !== newLines[lastNewDiff])
+            break;
+        lastOldDiff--;
+        lastNewDiff--;
+    }
+    if (lastOldDiff < firstDiff && lastNewDiff < firstDiff) {
+        return [];
+    }
+    const contextStart = Math.max(0, firstDiff - context);
+    const contextEndOld = Math.min(oldLines.length - 1, lastOldDiff + context);
+    const contextEndNew = Math.min(newLines.length - 1, lastNewDiff + context);
+    const hunkLines = [];
+    for (let k = contextStart; k < firstDiff; k++) {
+        hunkLines.push({ marker: ' ', content: oldLines[k] });
+    }
+    for (let k = firstDiff; k <= lastOldDiff; k++) {
+        hunkLines.push({ marker: '-', content: oldLines[k] });
+    }
+    for (let k = firstDiff; k <= lastNewDiff; k++) {
+        hunkLines.push({ marker: '+', content: newLines[k] });
+    }
+    const trailingStart = Math.max(lastOldDiff + 1, lastNewDiff + 1);
+    const trailingEnd = Math.max(contextEndOld, contextEndNew);
+    for (let k = trailingStart; k <= trailingEnd && k < newLines.length; k++) {
+        hunkLines.push({ marker: ' ', content: newLines[k] });
+    }
+    const oldLength = lastOldDiff - firstDiff + 1 + (firstDiff - contextStart);
+    const newLength = lastNewDiff - firstDiff + 1 + (firstDiff - contextStart);
+    return [
+        {
+            oldStart: contextStart + 1,
+            oldLength,
+            newStart: contextStart + 1,
+            newLength,
+            lines: hunkLines,
+        },
+    ];
+}
+/**
+ * Computes a multi-hunk line diff between two strings. This is the public
+ * entry point that {@link furnaceDiffCommand} uses. On normal inputs this
+ * runs the exact LCS path and returns a proper multi-hunk diff; on inputs
+ * that exceed {@link LCS_LINE_LIMIT} it falls back to a single coalesced
+ * hunk so the command stays useful instead of OOMing.
+ */
+export function diffLines(oldText, newText, context = 3) {
+    const oldLines = splitLines(oldText);
+    const newLines = splitLines(newText);
+    if (oldLines.length > LCS_LINE_LIMIT || newLines.length > LCS_LINE_LIMIT) {
+        return coalescedHunk(oldLines, newLines, context);
+    }
+    const ops = computeLineDiff(oldLines, newLines);
+    return buildHunks(ops, context);
+}
+/**
+ * Renders hunks into a flat list of lines the caller can emit one by one.
+ * Kept color-free so unit tests can assert exact output and so the caller
+ * can apply its own formatting (e.g. `formatErrorText` / `formatSuccessText`).
+ */
+export function renderHunks(hunks) {
+    const out = [];
+    for (const hunk of hunks) {
+        out.push({
+            kind: 'header',
+            text: `@@ -${hunk.oldStart},${hunk.oldLength} +${hunk.newStart},${hunk.newLength} @@`,
+        });
+        for (const line of hunk.lines) {
+            if (line.marker === ' ') {
+                out.push({ kind: 'context', text: `  ${line.content}` });
+            }
+            else if (line.marker === '-') {
+                out.push({ kind: 'removed', text: `- ${line.content}` });
+            }
+            else {
+                out.push({ kind: 'added', text: `+ ${line.content}` });
+            }
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=diff-hunks.js.map

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

@@ -11,7 +11,7 @@ export type { ProgressCallback } from './firefox-download.js';
 export { formatBytes, getFirefoxVersion } from './firefox-extract.js';
 /**
  * Gets the download URL for a Firefox source tarball.
- * @param version - Firefox version (e.g., "140.0esr")
+ * @param version - Firefox version (e.g., "146.0esr")
  * @param product - Firefox product type
  * @returns Full URL to the source tarball
  */

package/dist/src/core/firefox.js

@@ -17,7 +17,7 @@ export { resolveArchive } from './firefox-archive.js';
 export { formatBytes, getFirefoxVersion } from './firefox-extract.js';
 /**
  * Gets the download URL for a Firefox source tarball.
- * @param version - Firefox version (e.g., "140.0esr")
+ * @param version - Firefox version (e.g., "146.0esr")
  * @param product - Firefox product type
  * @returns Full URL to the source tarball
  */

package/dist/src/core/furnace-apply-helpers.d.ts

@@ -1,21 +1,104 @@
 import type { CustomComponentConfig, DryRunAction, OverrideComponentConfig, StepError } from '../types/furnace.js';
 import { type RollbackJournal } from './furnace-rollback.js';
+/**
+ * Filter deciding which files in an override workspace directory are candidates
+ * for copying into the engine. Exported so `furnace remove` can invert apply
+ * using the exact same file set — the "files to restore" set is defined as the
+ * inverse of the "files apply would have written" set.
+ */
+export declare function isOverrideCopyCandidate(entryName: string, type: OverrideComponentConfig['type']): boolean;
+/** Resolves the engine destination path for a single override-managed file. */
+export declare function getOverrideEngineTargetPath(engineDir: string, config: OverrideComponentConfig, fileName: string, ftlDir: string): string;
+/**
+ * Restores a single override-deployed engine file to its pristine HEAD state,
+ * inverting whatever apply wrote into that path.
+ *
+ * Behaviour matches the per-file branch of `restoreOverrideEngineFiles` in
+ * `furnace remove`: snapshot first, then either `git restore` (if the file
+ * exists in HEAD) or hard-delete (if the override introduced the file). The
+ * caller MUST guarantee `engineDir` is a git repository — this helper does
+ * not re-check, because both `furnace remove` and `furnace apply` already
+ * own the precondition check at their entry points and re-checking on every
+ * file would balloon git invocations.
+ *
+ * Returns the action taken so the caller can produce accurate user-facing
+ * counts (`restored` vs `removed`). `noop` means the file was neither in HEAD
+ * nor on disk, which can happen when the engine was reset out-of-band — the
+ * caller should treat that as a successful no-op rather than an error.
+ */
+export declare function restoreOverrideFileToBaseline(engineDir: string, enginePath: string, journal: RollbackJournal): Promise<'restored' | 'removed' | 'noop'>;
 /** Computes stable checksums for the source files that define a component. */
 export declare function computeComponentChecksums(componentDir: string): Promise<Record<string, string>>;
+/**
+ * Returns the filenames present in `previous` that are absent from `current`
+ * — i.e. files we know we deployed last time but the workspace has since
+ * deleted. The order of returned names is intentionally stable
+ * (sorted alphabetically) so test snapshots and CLI output are deterministic.
+ */
+export declare function diffDeletedFiles(previous: Record<string, string>, current: Record<string, string>): string[];
+/**
+ * Removes engine copies of files that the developer has deleted from a custom
+ * component's workspace since the last apply. `.ftl` files live under the
+ * shared Fluent tree (`engine/${FTL_DIR}`); everything else lives under
+ * `engine/${config.targetPath}`. Snapshots each removal into the journal so a
+ * mid-apply failure can roll the engine back to its pre-undeploy state. Files
+ * that are already missing from the engine are silently no-op (the engine
+ * may have been reset out-of-band — refusing here would surface a confusing
+ * error in a recovery path).
+ *
+ * Does **not** touch jar.mn or customElements.js: registration churn is the
+ * caller's responsibility, since it must coordinate with the new file list
+ * computed by the regular apply step that follows.
+ */
+export declare function undeployCustomFiles(engineDir: string, config: CustomComponentConfig, deletedFiles: string[], ftlDir: string, rollbackJournal?: RollbackJournal): Promise<string[]>;
+/**
+ * Restores or removes engine copies of files that the developer has deleted
+ * from an override component's workspace since the last apply. Each file is
+ * routed through `restoreOverrideFileToBaseline`, which restores it from
+ * HEAD if it was a Firefox baseline file or hard-deletes it if the override
+ * had introduced it.
+ *
+ * Requires `engineDir` to be a git repository — overrides cannot be inverted
+ * without git HEAD as the source of truth. The caller is expected to have
+ * already validated this precondition for the apply path; we re-check here
+ * so unit tests that exercise this helper directly cannot accidentally
+ * silent-fail on a non-git fixture.
+ */
+export declare function undeployOverrideFiles(engineDir: string, config: OverrideComponentConfig, deletedFiles: string[], ftlDir: string, rollbackJournal?: RollbackJournal): Promise<{
+    restored: string[];
+    removed: string[];
+}>;
 /** Compares current component file checksums against the previously recorded state. */
 export declare function hasComponentChanged(componentDir: string, previousChecksums: Record<string, string>): Promise<boolean>;
+/**
+ * Detects whether an override component's deployed files are missing from the
+ * engine or differ from the source. Used as a guard before skipping apply on a
+ * checksum match, so that reset/download/manual engine edits do not leave the
+ * caller with a stale "up to date" report.
+ *
+ * When `cachedEngineChecksums` is provided (populated on last successful apply),
+ * the function computes a SHA-256 hash of the engine file and compares it
+ * against the cached value. This avoids reading the full workspace source for
+ * the comparison when the engine hash still matches, which is the common case
+ * for projects with many components.
+ */
+export declare function hasOverrideEngineDrift(engineDir: string, componentDir: string, config: OverrideComponentConfig, ftlDir: string, cachedEngineChecksums?: Record<string, string>): Promise<boolean>;
+/**
+ * Detects whether a custom component's deployed copies, jar.mn entries, or
+ * customElements.js registration are missing from the engine or out of sync.
+ * Delegates to `checkRegistrationConsistency` so the oracle stays aligned with
+ * the validate command.
+ */
+export declare function hasCustomEngineDrift(root: string, name: string, componentDir: string, config: CustomComponentConfig, ftlDir: string): Promise<boolean>;
 /** Applies a custom component into the engine tree and captures registration step errors. */
-export declare function applyCustomComponent(engineDir: string, name: string, componentDir: string, config: CustomComponentConfig, dryRun?: boolean, rollbackJournal?: RollbackJournal): Promise<{
+export declare function applyCustomComponent(engineDir: string, name: string, componentDir: string, config: CustomComponentConfig, ftlDir: string, dryRun?: boolean, rollbackJournal?: RollbackJournal): Promise<{
     affectedPaths: string[];
     stepErrors: StepError[];
     actions?: DryRunAction[];
 }>;
 /** Applies an override component by copying its matching files onto the engine tree. */
-export declare function applyOverrideComponent(engineDir: string, name: string, componentDir: string, config: OverrideComponentConfig, dryRun?: boolean, rollbackJournal?: RollbackJournal): Promise<{
+export declare function applyOverrideComponent(engineDir: string, name: string, componentDir: string, config: OverrideComponentConfig, ftlDir: string, dryRun?: boolean, rollbackJournal?: RollbackJournal): Promise<{
     affectedPaths: string[];
     actions?: DryRunAction[];
 }>;
-/** Extracts per-component checksums from the flattened state-file checksum map. */
-export declare function extractComponentChecksums(allChecksums: Record<string, string> | undefined, type: string, name: string): Record<string, string>;
-/** Prefixes component checksums so they can be stored in the flattened state format. */
-export declare function prefixChecksums(checksums: Record<string, string>, type: string, name: string): Record<string, string>;
+export { extractComponentChecksums, prefixChecksums } from './furnace-checksum-utils.js';