@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/core/harness-port-fallback.d.ts

@@ -1,60 +0,0 @@
-/**
- * `fireforge test --auto-ports` (or `test.mochitestPorts: "auto"`): let two
- * checkouts run browser suites at the same time.
- *
- * Desktop `mach mochitest` has no `--http-port`/`--ssl-port` options; those
- * exist only in the Android and iOS argument sets. What recent engines do
- * have is a fallback inside `testing/mochitest/runtests.py`: before starting
- * its servers the harness bind-probes the HTTP server, ssltunnel and
- * WebSocket ports, and before launching the browser the Marionette port,
- * and moves any that is busy to a free port, routing `mochi.test:8888`
- * through its proxy to wherever the server actually landed. FireForge's
- * own preflight refused before that fallback could run. In auto mode it
- * steps aside for a holder that is not this checkout's own (a sibling
- * checkout's live suite, or an unrelated listener), and keeps refusing for
- * this checkout's own leftovers, exactly as in the default mode.
- *
- * Auto mode is opt-in, and it only takes effect when the engine's harness
- * is seen to carry the fallback: on an engine without it, a busy port would
- * still collide, so the default refusal stays in force there.
- */
-import type { TestOptions } from '../types/commands/index.js';
-import type { FireForgeConfig } from '../types/config.js';
-import { type MarionettePortHolder } from './marionette-port.js';
-/** Which busy-port fallbacks the engine's mochitest harness carries. */
-export interface HarnessPortFallback {
-    /** HTTP server, ssltunnel and WebSocket ports (`startServers`). */
-    serverPorts: boolean;
-    /** The Marionette port (before the browser launch). */
-    marionettePort: boolean;
-}
-/**
- * Reads the engine's `runtests.py` for the busy-port fallbacks. An
- * unreadable file reports neither, which keeps the default refusal.
- */
-export declare function detectHarnessPortFallback(engineDir: string): Promise<HarnessPortFallback>;
-/** True when the operator asked for auto ports, by flag or by config. */
-export declare function autoPortsRequested(options: TestOptions, config: FireForgeConfig): boolean;
-/**
- * True when the holder's command line points into THIS checkout's engine
- * directory: our own leftover, which auto mode never steps aside for.
- */
-export declare function isThisCheckoutsHolder(holder: MarionettePortHolder, engineDir: string): boolean;
-/**
- * Resolves the effective auto-ports posture for a browser run: what the
- * engine's harness can fall back from, or `undefined` when auto mode is
- * off or the engine cannot honour it (in which case the default refusal
- * stays, and an explicit request says why).
- */
-export declare function resolveAutoPorts(engineDir: string, options: TestOptions, config: FireForgeConfig): Promise<HarnessPortFallback | undefined>;
-/**
- * Steps aside for a busy port the harness will fall back from. Returns true
- * (after a notice naming the holder) when the port is held by anything that
- * is not this checkout's own process, false when the port is free or the
- * holder is ours, so the caller's normal preflight runs.
- *
- * @param port - The default port the harness would use
- * @param label - Human name of the port for the notice
- * @param engineDir - This checkout's engine directory
- */
-export declare function deferBusyPortToHarness(port: number, label: string, engineDir: string): Promise<boolean>;

package/dist/src/core/harness-port-fallback.js

@@ -1,96 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * `fireforge test --auto-ports` (or `test.mochitestPorts: "auto"`): let two
- * checkouts run browser suites at the same time.
- *
- * Desktop `mach mochitest` has no `--http-port`/`--ssl-port` options; those
- * exist only in the Android and iOS argument sets. What recent engines do
- * have is a fallback inside `testing/mochitest/runtests.py`: before starting
- * its servers the harness bind-probes the HTTP server, ssltunnel and
- * WebSocket ports, and before launching the browser the Marionette port,
- * and moves any that is busy to a free port, routing `mochi.test:8888`
- * through its proxy to wherever the server actually landed. FireForge's
- * own preflight refused before that fallback could run. In auto mode it
- * steps aside for a holder that is not this checkout's own (a sibling
- * checkout's live suite, or an unrelated listener), and keeps refusing for
- * this checkout's own leftovers, exactly as in the default mode.
- *
- * Auto mode is opt-in, and it only takes effect when the engine's harness
- * is seen to carry the fallback: on an engine without it, a busy port would
- * still collide, so the default refusal stays in force there.
- */
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { notice } from '../utils/logger.js';
-import { isExplicitAbsolutePath, isPathInsideRoot } from '../utils/paths.js';
-import { probeMarionettePort } from './marionette-port.js';
-const RUNTESTS_PATH = 'testing/mochitest/runtests.py';
-/**
- * Reads the engine's `runtests.py` for the busy-port fallbacks. An
- * unreadable file reports neither, which keeps the default refusal.
- */
-export async function detectHarnessPortFallback(engineDir) {
-    let source;
-    try {
-        source = await readFile(join(engineDir, RUNTESTS_PATH), 'utf8');
-    }
-    catch {
-        return { serverPorts: false, marionettePort: false };
-    }
-    const fallsBack = /falling back to port/.test(source);
-    return {
-        serverPorts: fallsBack && /\("httpPort",/.test(source) && /_port_in_use\(port\)/.test(source),
-        marionettePort: fallsBack && /_port_in_use\(marionette_port\)/.test(source),
-    };
-}
-/** True when the operator asked for auto ports, by flag or by config. */
-export function autoPortsRequested(options, config) {
-    return options.autoPorts === true || config.test?.mochitestPorts === 'auto';
-}
-/**
- * True when the holder's command line points into THIS checkout's engine
- * directory: our own leftover, which auto mode never steps aside for.
- */
-export function isThisCheckoutsHolder(holder, engineDir) {
-    return holder.commandLine
-        .split(/\s+/)
-        .filter(isExplicitAbsolutePath)
-        .some((token) => isPathInsideRoot(engineDir, token));
-}
-/**
- * Resolves the effective auto-ports posture for a browser run: what the
- * engine's harness can fall back from, or `undefined` when auto mode is
- * off or the engine cannot honour it (in which case the default refusal
- * stays, and an explicit request says why).
- */
-export async function resolveAutoPorts(engineDir, options, config) {
-    if (!autoPortsRequested(options, config))
-        return undefined;
-    const fallback = await detectHarnessPortFallback(engineDir);
-    if (!fallback.serverPorts && !fallback.marionettePort) {
-        notice(`Auto ports requested, but engine/${RUNTESTS_PATH} has no busy-port fallback, so a busy ` +
-            'mochitest or Marionette port is still refused as in the default mode.');
-        return undefined;
-    }
-    return fallback;
-}
-/**
- * Steps aside for a busy port the harness will fall back from. Returns true
- * (after a notice naming the holder) when the port is held by anything that
- * is not this checkout's own process, false when the port is free or the
- * holder is ours, so the caller's normal preflight runs.
- *
- * @param port - The default port the harness would use
- * @param label - Human name of the port for the notice
- * @param engineDir - This checkout's engine directory
- */
-export async function deferBusyPortToHarness(port, label, engineDir) {
-    const probe = await probeMarionettePort(port);
-    if (!probe.inUse || !probe.holder)
-        return false;
-    if (isThisCheckoutsHolder(probe.holder, engineDir))
-        return false;
-    notice(`${label} port ${port} is held by ${probe.holder.command} (PID ${probe.holder.pid}), which is ` +
-        "not this checkout's. Auto ports: the harness moves this run to a free port instead.");
-    return true;
-}

package/dist/src/core/harness-port-reservation.d.ts

@@ -1,60 +0,0 @@
-/**
- * Mochitest server ports for `fireforge test --jobs <n>`: placeholder
- * listeners that push every parallel harness instance onto its own ports,
- * and the parse of the ports each instance actually took.
- *
- * Desktop `mach mochitest` has no `--http-port`, `--ssl-port` or
- * `--websocket-port`. Its `startServers` (`testing/mochitest/runtests.py`)
- * bind-probes the HTTP server, ssltunnel and WebSocket ports (8888, 4443,
- * 9988) and moves only a busy one to a free port; see
- * `harness-port-fallback.ts`. Instances started at the same moment all
- * pass that probe on a free 8888, then race to bind it: the losers die with
- * `could not start server on port 8888` before any test runs. Holding the
- * three ports for the whole parallel run makes every instance's probe fail,
- * so each one falls back to an OS-assigned port of its own.
- */
-/** Which mochitest server a port belongs to, as the verdict line names it. */
-export type HarnessServerPortKey = 'http' | 'ssl' | 'ws';
-/** Placeholder listeners held for a parallel run. */
-export interface HarnessPortReservation {
-    /** Ports this process now holds. A port that was already busy is not listed. */
-    held: number[];
-    /** Closes every placeholder. Safe to call more than once. */
-    release(): Promise<void>;
-}
-/**
- * Holds a placeholder listener on `127.0.0.1` on each mochitest server
- * port, so the harness's busy-port probe moves every instance elsewhere.
- * A port that cannot be bound is skipped, not refused: whatever holds it
- * already makes the probe fail, which is all the placeholder is for (the
- * preflight has already ruled out this checkout's own stale httpd).
- *
- * @param ports - Ports to hold (default: {@link HARNESS_SERVER_PORTS})
- */
-export declare function reserveHarnessServerPorts(ports?: readonly number[]): Promise<HarnessPortReservation>;
-/** The server ports one harness invocation reported, by server. */
-export type HarnessServerPorts = Partial<Record<HarnessServerPortKey, number>>;
-/**
- * Records the port one output line reports, if it reports one: the
- * fallback port of a "falling back" line, or the port itself otherwise.
- *
- * @param line - One line of harness output
- * @param into - Collected ports; a later line for the same server wins
- */
-export declare function recordHarnessServerPortLine(line: string, into: HarnessServerPorts): void;
-/** Collects server ports from streamed output chunks. */
-export interface HarnessPortTracker {
-    onChunk(stream: 'stdout' | 'stderr', chunk: string): void;
-    /** The ports seen so far, including an unterminated last line. */
-    ports(): HarnessServerPorts;
-}
-/**
- * A tracker over the full output stream. The ports are printed at harness
- * start, so the capped capture tail a long run keeps would lose them.
- */
-export declare function createHarnessPortTracker(): HarnessPortTracker;
-/**
- * The `http:N,ssl:N,ws:N` value of a `ports=` key, in probe order, or
- * undefined when no port is known.
- */
-export declare function formatHarnessServerPorts(ports: HarnessServerPorts | undefined): string | undefined;

package/dist/src/core/harness-port-reservation.js

@@ -1,122 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Mochitest server ports for `fireforge test --jobs <n>`: placeholder
- * listeners that push every parallel harness instance onto its own ports,
- * and the parse of the ports each instance actually took.
- *
- * Desktop `mach mochitest` has no `--http-port`, `--ssl-port` or
- * `--websocket-port`. Its `startServers` (`testing/mochitest/runtests.py`)
- * bind-probes the HTTP server, ssltunnel and WebSocket ports (8888, 4443,
- * 9988) and moves only a busy one to a free port; see
- * `harness-port-fallback.ts`. Instances started at the same moment all
- * pass that probe on a free 8888, then race to bind it: the losers die with
- * `could not start server on port 8888` before any test runs. Holding the
- * three ports for the whole parallel run makes every instance's probe fail,
- * so each one falls back to an OS-assigned port of its own.
- */
-import { createServer } from 'node:net';
-/**
- * The ports `startServers` probes, in the order it probes them. Desktop
- * mochitest cannot configure them, so the engine defaults are the ports.
- */
-const HARNESS_SERVER_PORTS = [
-    { key: 'http', port: 8888, label: 'HTTP test server' },
-    { key: 'ssl', port: 4443, label: 'ssltunnel' },
-    { key: 'ws', port: 9988, label: 'WebSocket server' },
-];
-/** Listens on `127.0.0.1:port`, or resolves undefined when the bind fails. */
-async function holdPort(port) {
-    return new Promise((resolve) => {
-        const server = createServer((socket) => {
-            // Nothing should connect: the harness only probes with a bind. Anyone
-            // who does gets a closed socket instead of a hang.
-            socket.destroy();
-        });
-        server.once('error', () => {
-            resolve(undefined);
-        });
-        server.listen({ port, host: '127.0.0.1', exclusive: true }, () => {
-            server.unref();
-            resolve(server);
-        });
-    });
-}
-/**
- * Holds a placeholder listener on `127.0.0.1` on each mochitest server
- * port, so the harness's busy-port probe moves every instance elsewhere.
- * A port that cannot be bound is skipped, not refused: whatever holds it
- * already makes the probe fail, which is all the placeholder is for (the
- * preflight has already ruled out this checkout's own stale httpd).
- *
- * @param ports - Ports to hold (default: {@link HARNESS_SERVER_PORTS})
- */
-export async function reserveHarnessServerPorts(ports = HARNESS_SERVER_PORTS.map((spec) => spec.port)) {
-    const servers = (await Promise.all(ports.map(holdPort))).filter((server) => server !== undefined);
-    const held = servers.map((server) => {
-        const address = server.address();
-        return typeof address === 'object' && address !== null ? address.port : 0;
-    });
-    let released = false;
-    return {
-        held,
-        async release() {
-            if (released)
-                return;
-            released = true;
-            await Promise.all(servers.map((server) => new Promise((resolve) => {
-                server.close(() => {
-                    resolve();
-                });
-            })));
-        },
-    };
-}
-const PORT_LINE_PATTERN = /\b(HTTP test server|ssltunnel|WebSocket server) port (\d+)(?: already in use, falling back to port (\d+))?/;
-/**
- * Records the port one output line reports, if it reports one: the
- * fallback port of a "falling back" line, or the port itself otherwise.
- *
- * @param line - One line of harness output
- * @param into - Collected ports; a later line for the same server wins
- */
-export function recordHarnessServerPortLine(line, into) {
-    const match = PORT_LINE_PATTERN.exec(line);
-    if (match === null)
-        return;
-    const spec = HARNESS_SERVER_PORTS.find((entry) => entry.label === match[1]);
-    const port = Number.parseInt(match[3] ?? match[2] ?? '', 10);
-    if (spec !== undefined && Number.isInteger(port))
-        into[spec.key] = port;
-}
-/**
- * A tracker over the full output stream. The ports are printed at harness
- * start, so the capped capture tail a long run keeps would lose them.
- */
-export function createHarnessPortTracker() {
-    const collected = {};
-    const pending = { stdout: '', stderr: '' };
-    return {
-        onChunk(stream, chunk) {
-            const lines = `${pending[stream]}${chunk}`.split(/\r?\n/);
-            pending[stream] = lines.pop() ?? '';
-            for (const line of lines)
-                recordHarnessServerPortLine(line, collected);
-        },
-        ports() {
-            const result = { ...collected };
-            recordHarnessServerPortLine(pending.stdout, result);
-            recordHarnessServerPortLine(pending.stderr, result);
-            return result;
-        },
-    };
-}
-/**
- * The `http:N,ssl:N,ws:N` value of a `ports=` key, in probe order, or
- * undefined when no port is known.
- */
-export function formatHarnessServerPorts(ports) {
-    if (ports === undefined)
-        return undefined;
-    const parts = HARNESS_SERVER_PORTS.flatMap(({ key }) => ports[key] === undefined ? [] : [`${key}:${ports[key]}`]);
-    return parts.length > 0 ? parts.join(',') : undefined;
-}

package/dist/src/core/history-log-file.d.ts

@@ -1,61 +0,0 @@
-/** Filename of a history log inside `patches/`, which is moved out of the queue. */
-export declare const LEGACY_HISTORY_LOG_FILENAME = ".fireforge-history.jsonl";
-/** Default history log location, relative to the project root. */
-export declare const DEFAULT_HISTORY_LOG_PATH: string;
-/** Environment variable a caller sets to tag every record of its session. */
-export declare const HISTORY_SESSION_ENV = "FIREFORGE_SESSION_ID";
-/** Who wrote a history record. */
-export interface HistoryRecordIdentity {
-    /** One id per FireForge process: every record one command writes shares it. */
-    invocationId: string;
-    /** The caller's `FIREFORGE_SESSION_ID`, when set. */
-    sessionId?: string;
-    pid: number;
-    ppid: number;
-}
-/**
- * Identity fields stamped on every history record: one id per FireForge
- * process (every record one command writes shares it), the process and its
- * parent, and the caller's `FIREFORGE_SESSION_ID` when set. The parent PID
- * is a weak hint (usually the shell); the environment variable is the
- * reliable way for a session to tag its own lines.
- */
-export declare function historyRecordIdentity(): HistoryRecordIdentity;
-/**
- * Resolves the history log path for a project.
- *
- * @param projectRoot - Project root containing `fireforge.json`
- * @returns Absolute path of the history log
- */
-export declare function resolveHistoryLogPath(projectRoot: string): Promise<string>;
-/**
- * Moves a history log found at the `patches/` path to `target`.
- *
- * Records are never dropped, whatever else is happening:
- * - The in-queue file is first claimed by renaming it aside, so of two
- *   commands migrating at once exactly one does the work and neither
- *   duplicates it.
- * - When `target` does not exist yet (the first run), the claimed file is
- *   hard-linked into place, which cannot overwrite a log another command
- *   created in the meantime, and keeps a large log a constant-time move.
- * - When both exist (a log reappeared at the `patches/` path after a
- *   migration, or `history.path` changed), the in-queue records are
- *   appended to the target in one write. They then follow newer records;
- *   every record carries its own `ts`.
- *
- * A crash between the claim and the move leaves the records in a
- * `.migrating-*` file next to the in-queue path, never deleted.
- *
- * @param patchesDir - The patches directory that may hold an in-queue log
- * @param target - Absolute path of the history log
- */
-export declare function migrateLegacyHistoryLog(patchesDir: string, target: string): Promise<void>;
-/**
- * Appends one serialized record to the project's history log, first moving
- * a log found inside `patches/`.
- *
- * @param patchesDir - The project's `patches/` directory; the project root is
- *   its parent, as every caller derives it from `getProjectPaths`
- * @param line - One JSON record, without the trailing newline
- */
-export declare function appendHistoryLine(patchesDir: string, line: string): Promise<void>;

package/dist/src/core/history-log-file.js

@@ -1,164 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Where the patch history log lives, and who wrote each record.
- *
- * The log defaults to `.fireforge/history.jsonl` (FireForge's own untracked
- * data directory), or `fireforge.json#history.path` when a project sets one.
- * It stays out of the tracked patch queue because it grows to tens of
- * megabytes and would otherwise be committed with every export. A log found
- * at `patches/.fireforge-history.jsonl`, inside the queue, is moved on the
- * first append.
- *
- * Several sessions sharing one checkout all append to the same log, so each
- * record carries the invocation that wrote it, plus a session hint, letting
- * a session select its own lines mechanically.
- */
-import { randomUUID } from 'node:crypto';
-import { appendFile, link, readFile, rename, rm, stat } from 'node:fs/promises';
-import { dirname, join, resolve } from 'node:path';
-import { getNodeErrorCode, toError } from '../utils/errors.js';
-import { ensureDir, pathExists } from '../utils/fs.js';
-import { info, verbose } from '../utils/logger.js';
-import { FIREFORGE_DIR } from './config-paths.js';
-import { isValidHistoryPath } from './config-validate-history.js';
-/** Filename of a history log inside `patches/`, which is moved out of the queue. */
-export const LEGACY_HISTORY_LOG_FILENAME = '.fireforge-history.jsonl';
-/** Default history log location, relative to the project root. */
-export const DEFAULT_HISTORY_LOG_PATH = join(FIREFORGE_DIR, 'history.jsonl');
-/** Environment variable a caller sets to tag every record of its session. */
-export const HISTORY_SESSION_ENV = 'FIREFORGE_SESSION_ID';
-let invocationId;
-/**
- * Identity fields stamped on every history record: one id per FireForge
- * process (every record one command writes shares it), the process and its
- * parent, and the caller's `FIREFORGE_SESSION_ID` when set. The parent PID
- * is a weak hint (usually the shell); the environment variable is the
- * reliable way for a session to tag its own lines.
- */
-export function historyRecordIdentity() {
-    invocationId ??= randomUUID();
-    const session = process.env[HISTORY_SESSION_ENV]?.trim();
-    return {
-        invocationId,
-        ...(session !== undefined && session !== '' ? { sessionId: session } : {}),
-        pid: process.pid,
-        ppid: process.ppid,
-    };
-}
-/**
- * Reads `history.path` from the project's raw `fireforge.json`.
- *
- * Fail-open: the writer runs after a mutation has already committed, so a
- * missing or unreadable config means "use the default", never an error. An
- * invalid value is refused by config validation when the command loads its
- * config; here it also falls back to the default rather than writing
- * somewhere validation would not allow.
- */
-async function readConfiguredHistoryPath(projectRoot) {
-    let data;
-    try {
-        data = JSON.parse(await readFile(join(projectRoot, 'fireforge.json'), 'utf-8'));
-    }
-    catch {
-        return undefined;
-    }
-    if (typeof data !== 'object' || data === null)
-        return undefined;
-    const history = data['history'];
-    if (typeof history !== 'object' || history === null)
-        return undefined;
-    const path = history['path'];
-    if (path === undefined)
-        return undefined;
-    if (!isValidHistoryPath(path)) {
-        verbose(`Ignoring invalid history.path in fireforge.json; using ${DEFAULT_HISTORY_LOG_PATH}`);
-        return undefined;
-    }
-    return path;
-}
-/**
- * Resolves the history log path for a project.
- *
- * @param projectRoot - Project root containing `fireforge.json`
- * @returns Absolute path of the history log
- */
-export async function resolveHistoryLogPath(projectRoot) {
-    const configured = await readConfiguredHistoryPath(projectRoot);
-    return resolve(projectRoot, configured ?? DEFAULT_HISTORY_LOG_PATH);
-}
-/**
- * Moves a history log found at the `patches/` path to `target`.
- *
- * Records are never dropped, whatever else is happening:
- * - The in-queue file is first claimed by renaming it aside, so of two
- *   commands migrating at once exactly one does the work and neither
- *   duplicates it.
- * - When `target` does not exist yet (the first run), the claimed file is
- *   hard-linked into place, which cannot overwrite a log another command
- *   created in the meantime, and keeps a large log a constant-time move.
- * - When both exist (a log reappeared at the `patches/` path after a
- *   migration, or `history.path` changed), the in-queue records are
- *   appended to the target in one write. They then follow newer records;
- *   every record carries its own `ts`.
- *
- * A crash between the claim and the move leaves the records in a
- * `.migrating-*` file next to the in-queue path, never deleted.
- *
- * @param patchesDir - The patches directory that may hold an in-queue log
- * @param target - Absolute path of the history log
- */
-export async function migrateLegacyHistoryLog(patchesDir, target) {
-    const legacy = join(patchesDir, LEGACY_HISTORY_LOG_FILENAME);
-    if (resolve(legacy) === resolve(target))
-        return;
-    try {
-        await stat(legacy);
-    }
-    catch {
-        return;
-    }
-    const claimed = `${legacy}.migrating-${process.pid}-${randomUUID()}`;
-    try {
-        await rename(legacy, claimed);
-    }
-    catch (error) {
-        if (getNodeErrorCode(error) === 'ENOENT')
-            return;
-        throw error;
-    }
-    await ensureDir(dirname(target));
-    try {
-        await link(claimed, target);
-    }
-    catch (error) {
-        // Windows can report two racing renames of one file as both
-        // succeeding, the file ending under the other claimant's name. That
-        // claimant holds the records and moves them, so this one stands down.
-        if (getNodeErrorCode(error) === 'ENOENT' && !(await pathExists(claimed))) {
-            verbose('History log migration lost the claim to a concurrent command');
-            return;
-        }
-        // EEXIST: both logs exist. Anything else (a filesystem without hard
-        // links, a target on another device): the append below creates the
-        // target when it is missing, so it covers that case too.
-        verbose(`History log migration falls back to appending (${toError(error).message})`);
-        await appendFile(target, await readFile(claimed));
-    }
-    await rm(claimed, { force: true });
-    info(`Moved the patch history log from ${legacy} to ${target}. ` +
-        'Nothing reads it back; it is an audit trail only.');
-}
-/**
- * Appends one serialized record to the project's history log, first moving
- * a log found inside `patches/`.
- *
- * @param patchesDir - The project's `patches/` directory; the project root is
- *   its parent, as every caller derives it from `getProjectPaths`
- * @param line - One JSON record, without the trailing newline
- */
-export async function appendHistoryLine(patchesDir, line) {
-    const target = await resolveHistoryLogPath(dirname(resolve(patchesDir)));
-    await migrateLegacyHistoryLog(patchesDir, target);
-    await ensureDir(dirname(target));
-    await appendFile(target, `${line}\n`, 'utf-8');
-}

package/dist/src/core/history-log.d.ts

@@ -1,20 +0,0 @@
-import type { HistoryEntry } from './destructive.js';
-/**
- * Appends a history entry for a mutation that has already committed, degrading
- * to a warning when the log cannot be written.
- *
- * This is the one `try { await appendHistory(...) } catch { warn(...) }`
- * block for every call site across `export-flow` and the `patch` subcommands.
- * The swallow is intentional: the patch files and the manifest
- * are already on disk by the time this runs, so letting a failed log write
- * reject would report a completed, irreversible mutation as a failure and send
- * the operator looking for damage that is not there. Because that reasoning is
- * easy to lose in a copy, it lives in one place.
- * @param patchesDir - The project's `patches/` directory (the log itself lives
- *   under `.fireforge/` or `history.path`; see `history-log-file.ts`).
- * @param entry - The entry to append.
- * @param context - What just committed, rendered into
- *   `History log append failed after <context>: <reason>`, e.g.
- *   `patch tier committed (007-foo.patch)`.
- */
-export declare function appendHistoryBestEffort(patchesDir: string, entry: HistoryEntry, context: string): Promise<void>;

package/dist/src/core/history-log.js

@@ -1,30 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { toError } from '../utils/errors.js';
-import { warn } from '../utils/logger.js';
-import { appendHistory } from './destructive.js';
-/**
- * Appends a history entry for a mutation that has already committed, degrading
- * to a warning when the log cannot be written.
- *
- * This is the one `try { await appendHistory(...) } catch { warn(...) }`
- * block for every call site across `export-flow` and the `patch` subcommands.
- * The swallow is intentional: the patch files and the manifest
- * are already on disk by the time this runs, so letting a failed log write
- * reject would report a completed, irreversible mutation as a failure and send
- * the operator looking for damage that is not there. Because that reasoning is
- * easy to lose in a copy, it lives in one place.
- * @param patchesDir - The project's `patches/` directory (the log itself lives
- *   under `.fireforge/` or `history.path`; see `history-log-file.ts`).
- * @param entry - The entry to append.
- * @param context - What just committed, rendered into
- *   `History log append failed after <context>: <reason>`, e.g.
- *   `patch tier committed (007-foo.patch)`.
- */
-export async function appendHistoryBestEffort(patchesDir, entry, context) {
-    try {
-        await appendHistory(patchesDir, entry);
-    }
-    catch (historyError) {
-        warn(`History log append failed after ${context}: ${toError(historyError).message}`);
-    }
-}

package/dist/src/core/json-preserving-edit.d.ts

@@ -1,22 +0,0 @@
-/**
- * Format-preserving rewrites of a JSON document.
- *
- * `fireforge source set`, `fireforge config` and `furnace init` change a
- * few keys of `fireforge.json`. Re-serializing the whole document with
- * `JSON.stringify` expands every compact object and array the project keeps
- * on one line, so a one-key change becomes a diff across unrelated policy
- * sections. This module diffs the document on disk against the wanted one
- * and edits only the values that differ, in place, keeping every other byte
- * (indentation, compact containers, key order, trailing newline).
- *
- * Inserted values follow the style of the container they land in: one line
- * inside a one-line container, the container's own indentation otherwise.
- */
-import type { JsonObject } from '../types/json.js';
-/**
- * Rewrites `text` so it parses to `next`, editing only the values that
- * differ. Returns `undefined` when `text` is not a JSON object or the edit
- * cannot be proven equivalent, so the caller can fall back to a full
- * re-serialization.
- */
-export declare function rewriteJsonPreservingFormat(text: string, next: JsonObject): string | undefined;