@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/core/engine-session-lock.d.ts

@@ -1,119 +0,0 @@
-import type { LockMode } from './file-lock.js';
-import { type LockStatusSnapshot } from './file-lock.js';
-export interface EngineSessionLockOptions {
-    /**
-     * Wait up to this many seconds for the engine session lock instead of the
-     * ~1 s fail-fast. Enables exponential poll backoff (100 ms → 2 s) and a
-     * holder-identified progress line roughly every 5 s. `undefined` keeps the
-     * fail-fast behaviour.
-     */
-    waitLockSeconds?: number | undefined;
-    /**
-     * `shared` lets build-less test runs overlap each other; see
-     * `file-lock-shared.ts`. Every other caller holds the lock exclusively.
-     */
-    mode?: LockMode | undefined;
-}
-/**
- * Formats the notice printed when the wait budget is extended because the
- * queue advanced.
- *
- * Exported for direct unit testing. It names both figures, the requested
- * budget and the one now in force, because they have diverged and an
- * operator comparing the elapsed time against the number they typed would
- * otherwise conclude the timeout is broken.
- */
-export declare function formatWaitExtendedLine(ahead: number, budgetMs: number, requestedMs: number): string;
-/**
- * Runs `operation` while holding the project's engine-session lock, so only
- * one engine-mutating FireForge command touches `engine/` at a time.
- */
-export declare function withEngineSessionLock<T>(projectRoot: string, command: string, operation: () => Promise<T>, options?: EngineSessionLockOptions): Promise<T>;
-/**
- * Inspects the project's engine-session lock without acquiring it, backing
- * `fireforge status --lock`.
- *
- * @param projectRoot - Project root containing `.fireforge/`
- * @returns Holder identity, hold duration, and queue depth
- */
-export declare function readEngineSessionLockStatus(projectRoot: string): Promise<LockStatusSnapshot>;
-/**
- * Renders the engine-session lock snapshot as operator-facing lines.
- * Pure, so the wording is unit-testable without a lock on disk.
- */
-export declare function formatEngineSessionLockStatus(snapshot: LockStatusSnapshot, holderCpuSeconds?: number): string[];
-/**
- * Captures an opaque token describing the engine's current commit and working
- * tree, for comparison by {@link assertEngineGenerationUnchanged}.
- *
- * A failed probe yields a failure token. Callers must branch on
- * {@link isUnavailableGenerationToken} rather than comparing the token,
- * because a probe failure means "nothing was measured", not "nothing changed".
- */
-export declare function snapshotEngineGeneration(engineDir: string): Promise<string>;
-/**
- * True when a git failure is the transient index-lock contention shape
- * (`Unable to create '…/.git/index.lock': File exists`) rather than a
- * durable problem with the checkout. Exported for direct unit testing.
- */
-export declare function isIndexLockError(error: unknown): boolean;
-/**
- * True when a generation token records a failed probe, i.e. nothing was
- * measured, so the token must never be compared (or hashed) as if it
- * described the engine's state.
- */
-export declare function isUnavailableGenerationToken(token: string): boolean;
-/** Strips the marker prefix off an unavailable token for display. */
-export declare function unavailableGenerationReason(token: string): string;
-/**
- * Engine-relative paths whose working-tree status differs between two
- * generation tokens (both sides of a rename), and whether HEAD moved. An
- * untracked directory keeps git's trailing `/`.
- */
-export declare function generationDeltaPaths(before: string, after: string): {
-    headMoved: boolean;
-    paths: string[];
-};
-/**
- * Describes what moved between two generation tokens, in operator terms.
- *
- * A refusal that said only that the engine changed would leave the
- * operator to reconstruct the writer by hand: `find -newermt` against the
- * run window, minus the objdir, minus git's own bookkeeping. Everything
- * needed to answer it is already in the two tokens, so the refusal answers
- * it. Pure and total: an unparseable token yields an empty list rather than
- * an exception, because a diagnostic must never convert a refusal into a
- * crash.
- *
- * @param before - Token captured before the run
- * @param after - Token captured after the run
- * @returns Human-readable lines describing the delta. Empty when nothing
- *   could be attributed
- */
-export declare function describeEngineGenerationDelta(before: string, after: string): string[];
-/**
- * Throws when the engine's generation token differs from `before`, i.e. the
- * engine was mutated by another writer while a test run was in flight.
- *
- * An unmeasurable engine warns rather than throws. `engine/` is not
- * always a git checkout (`fireforge download` extracts a source tarball),
- * so a failed probe is a legitimate state and must not fail the run.
- *
- * It must also not pass silently. A failure token compared for
- * equality like any other would let a git failure that reproduces across
- * both probes (unreadable `.git`, a permissions problem, a corrupt index)
- * take the `after === before` early return and bless a verdict the guard
- * never verified. Two differing failure messages are worse still: they
- * fall through to the mutation branch and report a spurious
- * "engine/ changed". Hence the prefix comparison rather than a token
- * comparison: the token embeds the error message, and two genuine failures
- * rarely phrase it identically.
- *
- * The tolerance is limited to a probe that failed both times:
- * that is the steady state of a non-git `engine/`, and it warns. A one-sided
- * transition is not that state. An `engine/` that was measurable and then
- * was not means the second probe measured nothing about a checkout that
- * demonstrably had something to measure. The reverse means there was never a
- * baseline to compare against. Neither verdict can be trusted, so both throw.
- */
-export declare function assertEngineGenerationUnchanged(engineDir: string, before: string, tolerateDelta?: (before: string, after: string) => Promise<boolean>): Promise<void>;

package/dist/src/core/engine-session-lock.js

@@ -1,374 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
-import { InconclusiveVerdictError } from '../errors/base.js';
-import { toError } from '../utils/errors.js';
-import { info, warn } from '../utils/logger.js';
-import { MAX_WAIT_LOCK_SECONDS } from '../utils/options.js';
-import { sleep } from '../utils/sleep.js';
-import { formatLockQueuePosition, readLockStatus, withFileLock, } from './file-lock.js';
-import { git } from './git-base.js';
-const ENGINE_SESSION_LOCK_PATH = join('.fireforge', 'engine-session.lock');
-/**
- * How much longer than the requested budget a wait may run while its queue
- * position keeps improving, and the absolute ceiling on that. The ceiling
- * matches `--wait-lock`'s own upper bound: an operator who asked for a wait
- * never gets one longer than the largest wait they could have asked for.
- */
-const WAIT_EXTENSION_FACTOR = 4;
-const MAX_WAIT_LOCK_MS = MAX_WAIT_LOCK_SECONDS * 1000;
-/**
- * Formats the periodic operator-facing waiting line printed while `--wait-lock`
- * polls a contended engine session lock. The holder identification comes from
- * the lock's owner-metadata lines (`command=…`, `started=…`). An unreadable
- * owner file degrades to the anonymous form.
- */
-function formatWaitProgressLine(waitedMs, timeoutMs, holder, queue) {
-    const progress = `${Math.round(waitedMs / 1000)}s of up to ${Math.round(timeoutMs / 1000)}s`;
-    // Queue position: under several concurrent sessions the wait
-    // line alone left operators inferring their place from `ps`. It names the
-    // ordering rule, because the count is only useful if the grant honours it.
-    const position = formatLockQueuePosition(queue);
-    if (holder === undefined) {
-        return `Waiting for the FireForge engine lock — ${progress}.${position}`;
-    }
-    const details = holder.metadata.length > 0 ? ` (${holder.metadata.join(', ')})` : '';
-    return `Waiting for the FireForge engine lock held by PID ${holder.pid}${details} — ${progress}.${position}`;
-}
-/**
- * Formats the notice printed when the wait budget is extended because the
- * queue advanced.
- *
- * Exported for direct unit testing. It names both figures, the requested
- * budget and the one now in force, because they have diverged and an
- * operator comparing the elapsed time against the number they typed would
- * otherwise conclude the timeout is broken.
- */
-export function formatWaitExtendedLine(ahead, budgetMs, requestedMs) {
-    const position = ahead === 0 ? 'you are now next' : `${ahead} still ahead of you`;
-    return (`The queue advanced (${position}), so the engine-lock wait was extended to ` +
-        `${Math.round(budgetMs / 1000)}s total (you asked for ` +
-        `${Math.round(requestedMs / 1000)}s). A queue that stops moving still ` +
-        `gives up on the budget you asked for.`);
-}
-/**
- * Runs `operation` while holding the project's engine-session lock, so only
- * one engine-mutating FireForge command touches `engine/` at a time.
- */
-export async function withEngineSessionLock(projectRoot, command, operation, options = {}) {
-    // The lock is bypassed under test by default, on purpose: the
-    // suite runs many engine-mutating commands in-process, which would either
-    // serialise on this lock or deadlock outright.
-    // `FIREFORGE_ENABLE_ENGINE_SESSION_LOCK_IN_TEST=1` lets the lock's own
-    // tests opt back in. Do not delete this branch. It is the reason the
-    // suite completes.
-    if (process.env['FIREFORGE_ENABLE_ENGINE_SESSION_LOCK_IN_TEST'] !== '1' &&
-        (process.env['NODE_ENV'] === 'test' || process.env['VITEST'] !== undefined)) {
-        return operation();
-    }
-    const { waitLockSeconds } = options;
-    return withFileLock(join(projectRoot, ENGINE_SESSION_LOCK_PATH), operation, {
-        ...(options.mode === 'shared' ? { mode: 'shared' } : {}),
-        timeoutMs: waitLockSeconds !== undefined ? waitLockSeconds * 1000 : 1000,
-        ...(waitLockSeconds !== undefined
-            ? {
-                pollMs: 100,
-                pollMaxMs: 2000,
-                waitProgressMs: 5000,
-                onWaitProgress: ({ waitedMs, timeoutMs, holder, queue }) => {
-                    info(formatWaitProgressLine(waitedMs, timeoutMs, holder, queue));
-                },
-                // Announce it. An extension is the moment the budget the
-                // operator asked for stops being the budget in force, and a wait
-                // that silently outlives its own stated timeout is
-                // indistinguishable from a broken one, which is how a downstream
-                // fork read it.
-                onWaitExtended: ({ ahead, budgetMs }) => {
-                    info(formatWaitExtendedLine(ahead, budgetMs, waitLockSeconds * 1000));
-                },
-                // A budget that expires one position from the head pays the whole
-                // wait for nothing. While the queue is still moving the wait is
-                // working, so each advance renews the budget, up to a hard
-                // ceiling so a pathological queue cannot wait forever. The
-                // no-flag fail-fast path gets none of this.
-                extendWhileAdvancing: {
-                    maxWaitMs: Math.min(waitLockSeconds * 1000 * WAIT_EXTENSION_FACTOR, MAX_WAIT_LOCK_MS),
-                },
-            }
-            : {}),
-        ownerMetadata: [`command=${command}`, `started=${new Date().toISOString()}`],
-        // Reason first, remedy second: the no-flag default waits
-        // only ~1 s, so contention is the common case and `--wait-lock` is the
-        // genuine remedy. withFileLock appends the holder identification from
-        // the lock's owner metadata. The leading sentence is a message contract
-        // (pinned by engine-session-lock tests). Extend, don't reword.
-        onTimeoutMessage: `Another FireForge engine-mutating command is already running. ` +
-            `Wait for it to finish, then retry \`${command}\` — or pass --wait-lock [seconds] ` +
-            `to wait for the lock (bare --wait-lock waits up to 60 seconds). ` +
-            `Set FIREFORGE_WAIT_LOCK=<seconds> to apply a budget to every command in a session.`,
-        onStaleLockMessage: (ageMs) => `Removed stale FireForge engine session lock (${Math.round(ageMs / 1000)}s old).`,
-    });
-}
-/**
- * Inspects the project's engine-session lock without acquiring it, backing
- * `fireforge status --lock`.
- *
- * @param projectRoot - Project root containing `.fireforge/`
- * @returns Holder identity, hold duration, and queue depth
- */
-export async function readEngineSessionLockStatus(projectRoot) {
-    return readLockStatus(join(projectRoot, ENGINE_SESSION_LOCK_PATH));
-}
-/**
- * Renders the engine-session lock snapshot as operator-facing lines.
- * Pure, so the wording is unit-testable without a lock on disk.
- */
-export function formatEngineSessionLockStatus(snapshot, holderCpuSeconds) {
-    const shared = snapshot.sharedHolders !== undefined && snapshot.sharedHolders > 0
-        ? `Shared holders: ${snapshot.sharedHolders} build-less test run(s) under a shared lock.`
-        : undefined;
-    if (!snapshot.held) {
-        return shared === undefined
-            ? ['Engine session lock: free (no FireForge engine-mutating command is running).']
-            : ['Engine session lock: no exclusive holder.', shared];
-    }
-    const elapsed = snapshot.heldForMs === undefined
-        ? 'unknown duration'
-        : `${Math.round(snapshot.heldForMs / 1000)}s`;
-    const holder = snapshot.holder;
-    const identity = holder === undefined
-        ? 'held by an unidentified process (no readable owner record)'
-        : `held by PID ${holder.pid}${holder.alive ? '' : ' (NOT RUNNING — stale lock)'}` +
-            (holder.metadata.length > 0 ? ` (${holder.metadata.join(', ')})` : '');
-    const lines = [
-        `Engine session lock: ${identity}, for ${elapsed}.`,
-        `Queue depth: ${snapshot.queueDepth} waiter(s).`,
-        ...(shared === undefined ? [] : [shared]),
-    ];
-    // Liveness answers "does the process exist". It does not answer "is it
-    // getting anywhere". A holder alive for minutes having used a fraction of
-    // a second of CPU is the shape of a wedged command, and every waiter
-    // behind it inherits the stall. Stated as an observation with its own
-    // caveat: a holder blocked on I/O is also idle, and this must not be read
-    // as licence to kill anything.
-    if (holder?.alive === true && holderCpuSeconds !== undefined) {
-        const cpu = `${holderCpuSeconds.toFixed(1)}s`;
-        const idle = snapshot.heldForMs !== undefined && snapshot.heldForMs > 60_000 && holderCpuSeconds < 2
-            ? ' — near-zero CPU over a long hold, which is what a WEDGED command looks like; ' +
-                'a holder blocked on I/O looks the same, so confirm before acting'
-            : '';
-        lines.push(`Holder CPU time: ${cpu}${idle}.`);
-    }
-    return lines;
-}
-/** Prefix marking a generation token whose probe failed. */
-const UNAVAILABLE_PREFIX = 'unavailable:';
-/**
- * Captures an opaque token describing the engine's current commit and working
- * tree, for comparison by {@link assertEngineGenerationUnchanged}.
- *
- * A failed probe yields a failure token. Callers must branch on
- * {@link isUnavailableGenerationToken} rather than comparing the token,
- * because a probe failure means "nothing was measured", not "nothing changed".
- */
-export async function snapshotEngineGeneration(engineDir) {
-    let lastError;
-    for (let attempt = 0; attempt < GENERATION_PROBE_ATTEMPTS; attempt += 1) {
-        try {
-            const head = (await git(['rev-parse', 'HEAD'], engineDir)).trim();
-            const status = await git(['status', '--porcelain=v1', '-z'], engineDir);
-            return `${head}\0${status}`;
-        }
-        catch (error) {
-            lastError = error;
-            // A contended `.git/index.lock` is transient, not a state: some other
-            // writer held the index for the instant we looked. Treating it as
-            // "unmeasurable" turns a perfectly good suite into
-            // `FAIL reason=inconclusive` on a one-sided probe failure. Anything
-            // else (an unreadable `.git`, a non-git `engine/`) is a real state
-            // and is reported immediately.
-            if (!isIndexLockError(error) || attempt === GENERATION_PROBE_ATTEMPTS - 1)
-                break;
-            await sleep(GENERATION_PROBE_RETRY_MS);
-        }
-    }
-    return `${UNAVAILABLE_PREFIX}${toError(lastError).message}`;
-}
-/** Probe attempts before an engine generation is declared unmeasurable. */
-const GENERATION_PROBE_ATTEMPTS = 3;
-/** Pause between generation-probe attempts. */
-const GENERATION_PROBE_RETRY_MS = 250;
-/**
- * True when a git failure is the transient index-lock contention shape
- * (`Unable to create '…/.git/index.lock': File exists`) rather than a
- * durable problem with the checkout. Exported for direct unit testing.
- */
-export function isIndexLockError(error) {
-    const message = toError(error).message;
-    return /index\.lock/i.test(message);
-}
-/**
- * True when a generation token records a failed probe, i.e. nothing was
- * measured, so the token must never be compared (or hashed) as if it
- * described the engine's state.
- */
-export function isUnavailableGenerationToken(token) {
-    return token.startsWith(UNAVAILABLE_PREFIX);
-}
-/** Strips the marker prefix off an unavailable token for display. */
-export function unavailableGenerationReason(token) {
-    return token.slice(UNAVAILABLE_PREFIX.length);
-}
-/** How many changed entries the delta names before truncating. */
-const DELTA_ENTRY_LIMIT = 5;
-/**
- * Splits a generation token into its HEAD and porcelain halves. The porcelain
- * body is `-z` output, so it is NUL-separated and never quoted.
- */
-function splitGenerationToken(token) {
-    const separator = token.indexOf('\0');
-    if (separator < 0)
-        return { head: token, body: '' };
-    return { head: token.slice(0, separator), body: token.slice(separator + 1) };
-}
-/**
- * Parses `git status --porcelain=v1 -z` into `XY path` records.
- *
- * The rename/copy shape needs care: `R`/`C` entries are followed by a
- * second NUL-separated field carrying the original path, and consuming only
- * one desynchronises every record after it, turning a one-file rename into
- * a report that the whole tree moved. Both fields are consumed and the
- * record renders as `orig -> new`.
- */
-function parsePorcelainRecords(body) {
-    const fields = body.split('\0').filter((field) => field.length > 0);
-    const records = [];
-    for (let i = 0; i < fields.length; i++) {
-        const field = fields[i] ?? '';
-        // `XY `, two status characters and a space, then the path.
-        if (field.length < 4)
-            continue;
-        const status = field.slice(0, 2);
-        const path = field.slice(3);
-        if (status.includes('R') || status.includes('C')) {
-            const origin = fields[i + 1];
-            i += 1;
-            records.push(`${status} ${origin ?? '?'} -> ${path}`);
-            continue;
-        }
-        records.push(`${status} ${path}`);
-    }
-    return records;
-}
-/**
- * Engine-relative paths whose working-tree status differs between two
- * generation tokens (both sides of a rename), and whether HEAD moved. An
- * untracked directory keeps git's trailing `/`.
- */
-export function generationDeltaPaths(before, after) {
-    const from = splitGenerationToken(before);
-    const to = splitGenerationToken(after);
-    const beforeRecords = new Set(parsePorcelainRecords(from.body));
-    const afterRecords = new Set(parsePorcelainRecords(to.body));
-    const paths = new Set();
-    for (const record of [...afterRecords, ...beforeRecords]) {
-        if (beforeRecords.has(record) && afterRecords.has(record))
-            continue;
-        for (const path of record.slice(3).split(' -> '))
-            paths.add(path);
-    }
-    return { headMoved: from.head !== to.head, paths: [...paths].sort() };
-}
-/**
- * Describes what moved between two generation tokens, in operator terms.
- *
- * A refusal that said only that the engine changed would leave the
- * operator to reconstruct the writer by hand: `find -newermt` against the
- * run window, minus the objdir, minus git's own bookkeeping. Everything
- * needed to answer it is already in the two tokens, so the refusal answers
- * it. Pure and total: an unparseable token yields an empty list rather than
- * an exception, because a diagnostic must never convert a refusal into a
- * crash.
- *
- * @param before - Token captured before the run
- * @param after - Token captured after the run
- * @returns Human-readable lines describing the delta. Empty when nothing
- *   could be attributed
- */
-export function describeEngineGenerationDelta(before, after) {
-    const lines = [];
-    const from = splitGenerationToken(before);
-    const to = splitGenerationToken(after);
-    if (from.head !== to.head) {
-        lines.push(`HEAD moved: ${from.head} -> ${to.head}`);
-    }
-    const beforeRecords = new Set(parsePorcelainRecords(from.body));
-    const afterRecords = new Set(parsePorcelainRecords(to.body));
-    const appeared = [...afterRecords].filter((record) => !beforeRecords.has(record)).sort();
-    const disappeared = [...beforeRecords].filter((record) => !afterRecords.has(record)).sort();
-    const render = (label, records) => {
-        if (records.length === 0)
-            return;
-        const head = records.slice(0, DELTA_ENTRY_LIMIT);
-        const truncated = records.length - head.length;
-        lines.push(`${label}: ${head.join(', ')}${truncated > 0 ? `, … (+${truncated} more)` : ''}`);
-    };
-    render('Working-tree entries that appeared', appeared);
-    render('Working-tree entries that went away', disappeared);
-    return lines;
-}
-/**
- * Throws when the engine's generation token differs from `before`, i.e. the
- * engine was mutated by another writer while a test run was in flight.
- *
- * An unmeasurable engine warns rather than throws. `engine/` is not
- * always a git checkout (`fireforge download` extracts a source tarball),
- * so a failed probe is a legitimate state and must not fail the run.
- *
- * It must also not pass silently. A failure token compared for
- * equality like any other would let a git failure that reproduces across
- * both probes (unreadable `.git`, a permissions problem, a corrupt index)
- * take the `after === before` early return and bless a verdict the guard
- * never verified. Two differing failure messages are worse still: they
- * fall through to the mutation branch and report a spurious
- * "engine/ changed". Hence the prefix comparison rather than a token
- * comparison: the token embeds the error message, and two genuine failures
- * rarely phrase it identically.
- *
- * The tolerance is limited to a probe that failed both times:
- * that is the steady state of a non-git `engine/`, and it warns. A one-sided
- * transition is not that state. An `engine/` that was measurable and then
- * was not means the second probe measured nothing about a checkout that
- * demonstrably had something to measure. The reverse means there was never a
- * baseline to compare against. Neither verdict can be trusted, so both throw.
- */
-export async function assertEngineGenerationUnchanged(engineDir, before, tolerateDelta) {
-    const after = await snapshotEngineGeneration(engineDir);
-    const beforeUnavailable = isUnavailableGenerationToken(before);
-    const afterUnavailable = isUnavailableGenerationToken(after);
-    if (beforeUnavailable && afterUnavailable) {
-        warn('Could not verify that engine/ stayed unchanged while the tests ran ' +
-            `(${unavailableGenerationReason(after)}). If another writer touched engine/ during the run, ` +
-            'this verdict is stale.');
-        return;
-    }
-    if (beforeUnavailable || afterUnavailable) {
-        const detail = beforeUnavailable
-            ? `engine/ could not be probed before the run (${unavailableGenerationReason(before)}) but could be ` +
-                'probed afterwards, so there is no baseline to compare against.'
-            : `engine/ was probed before the run but could not be probed afterwards ` +
-                `(${unavailableGenerationReason(after)}), so nothing was measured to compare against.`;
-        throw new InconclusiveVerdictError(`${detail}\n\n` +
-            'This test verdict is inconclusive. Restore engine/ to a readable state, then rebuild ' +
-            'and rerun the affected tests.');
-    }
-    if (after === before)
-        return;
-    // A caller that can prove the delta never reached the runtime under test
-    // (a perf sample, see `test-perf-scope.ts`) keeps its verdict.
-    if (tolerateDelta !== undefined && (await tolerateDelta(before, after)))
-        return;
-    const delta = describeEngineGenerationDelta(before, after);
-    throw new InconclusiveVerdictError('engine/ changed while `fireforge test` was running, so this test verdict is invalid/inconclusive.\n\n' +
-        (delta.length > 0 ? `What moved:\n${delta.map((line) => `  ${line}`).join('\n')}\n\n` : '') +
-        'Use one writer per engine checkout, then rebuild and rerun the affected tests.');
-}

package/dist/src/core/engine-write-boundary.d.ts

@@ -1,5 +0,0 @@
-import type { FurnaceConfig } from '../types/furnace.js';
-/** Checks all component destinations before an apply starts writing. */
-export declare function assertComponentWriteBoundaries(engineDir: string, config: FurnaceConfig, ftlDir: string): Promise<void>;
-/** Resolves the nearest existing parent before any mkdir/copy can write through an alias. */
-export declare function assertEngineWriteBoundary(engineDir: string, directory: string): Promise<void>;

package/dist/src/core/engine-write-boundary.js

@@ -1,41 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { realpath } from 'node:fs/promises';
-import { dirname, join, resolve, sep } from 'node:path';
-import { FurnaceError } from '../errors/furnace.js';
-import { getNodeErrorCode } from '../utils/errors.js';
-import { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
-/** Checks all component destinations before an apply starts writing. */
-export async function assertComponentWriteBoundaries(engineDir, config, ftlDir) {
-    const destinations = new Set([
-        ftlDir,
-        dirname(JAR_MN),
-        dirname(CUSTOM_ELEMENTS_JS),
-        ...Object.values(config.custom).map((entry) => entry.targetPath),
-        ...Object.values(config.overrides).map((entry) => entry.basePath),
-    ]);
-    for (const destination of destinations) {
-        await assertEngineWriteBoundary(engineDir, join(engineDir, destination));
-    }
-}
-/** Resolves the nearest existing parent before any mkdir/copy can write through an alias. */
-export async function assertEngineWriteBoundary(engineDir, directory) {
-    const root = await realpath(engineDir);
-    let parent = resolve(directory);
-    for (;;) {
-        try {
-            const canonical = await realpath(parent);
-            if (canonical !== root && !canonical.startsWith(root + sep)) {
-                throw new FurnaceError(`Engine destination ${directory} resolves outside engine/ (${canonical}). Refusing to write through into component sources or another checkout.`);
-            }
-            return;
-        }
-        catch (error) {
-            if (getNodeErrorCode(error) !== 'ENOENT')
-                throw error;
-            const next = dirname(parent);
-            if (next === parent)
-                throw error;
-            parent = next;
-        }
-    }
-}

package/dist/src/core/export-moved-code-shape.d.ts

@@ -1,98 +0,0 @@
-/**
- * Detects the new-file-plus-moved-code slice shape and names the working
- * sequence through it.
- *
- * A slice that adds new files and moves lines into them from an existing
- * patch has no path through the two refusal flags:
- *
- *  - `re-export --refuse-adjacent-unmanaged` refuses while the new files are
- *    still unmanaged, and
- *  - exporting the new files as their own patch fails cross-patch lint,
- *    because at the projected placement the old patch still contains the
- *    moved code.
- *
- * Each guard is individually correct. Together they dead-end, and the way out
- * is non-obvious: adopt the new files into the old patch first
- * (`re-export --scan --scan-file`), then split them out into a patch of their
- * own (`patch move-files --create --order N`).
- *
- * This module recognises the shape from evidence FireForge already has (the
- * pending diff's new-file content versus the added lines the existing patches
- * carry), so the refusal can name the sequence instead of leaving the
- * operator to derive it.
- */
-/** One run of consecutive lines a new file shares with an existing patch. */
-export interface MovedCodeBlock {
-    /** New-file path in the pending diff. */
-    file: string;
-    /** File in the source patch that carries the same run. */
-    sourceFile: string;
-    /** The matched substantive lines, trimmed, in order. */
-    lines: string[];
-}
-/** One existing patch that already carries lines the new files would add. */
-export interface MovedCodeOverlap {
-    /** Filename of the patch that still contains the moved lines. */
-    sourcePatch: string;
-    /** New-file paths in the pending diff whose lines it overlaps. */
-    files: string[];
-    /** Count of substantive lines inside the matched blocks. */
-    sharedLines: number;
-    /** The matched blocks, so the claim can be checked line by line. */
-    blocks: MovedCodeBlock[];
-}
-/** Minimal queue view this detector needs. */
-export interface MovedCodeQueueEntry {
-    filename: string;
-    diff: string;
-}
-/**
- * Finds existing patches that still carry a block of substantive lines the
- * pending diff's new files would add, the fingerprint of code moved out of
- * an existing patch into a new file.
- *
- * Pure. Overlaps are returned strongest-first so the message names the
- * most likely source patch.
- *
- * @param pendingDiff - The diff the export would write
- * @param entries - The existing queue's patches
- * @returns Overlaps, or an empty list when the shape is not present
- */
-export declare function detectMovedCodeOverlaps(pendingDiff: string, entries: readonly MovedCodeQueueEntry[]): MovedCodeOverlap[];
-/** What the placement projection learned about the pending export. */
-export interface MovedCodeAdviceInput {
-    /** Result of {@link detectMovedCodeOverlaps}. */
-    overlaps: readonly MovedCodeOverlap[];
-    /** The filename the pending export would take. */
-    newPatchName: string;
-    /** The order the pending export would take. */
-    insertionOrder: number;
-    /**
-     * New system modules in the pending diff that no patch registers
-     * (`unregistered-system-module` findings on the new patch).
-     */
-    unregisteredModules?: readonly string[];
-    /**
-     * True when every error in the exported content is a missing
-     * registration: registering is then the whole fix, and adopt-then-split
-     * is not offered at all.
-     */
-    registrationResolvesAll?: boolean;
-    /**
-     * Why adopting the new files into the strongest overlap's source patch
-     * would itself be refused (forward imports, size limit). Empty when the
-     * adopt is clean.
-     */
-    adoptBlockers?: readonly string[];
-}
-/**
- * Renders the remedy lines appended to a placement refusal: "register
- * first" when new modules lack their moz.build registration, then the
- * adopt-then-split sequence for a real moved-code block, but only when the
- * adopt itself would pass. Each claim names its evidence (the matched
- * lines, the blocking findings) so it can be checked.
- *
- * @param input - See {@link MovedCodeAdviceInput}
- * @returns Detail lines, or an empty list when neither shape is present
- */
-export declare function formatMovedCodeAdvice(input: MovedCodeAdviceInput): string[];