@hominis/fireforge 0.49.2 → 0.50.0

package/dist/src/core/furnace-validate-accessibility.d.ts

@@ -1,4 +1,4 @@
-import type { CustomComponentConfig, ValidationIssue } from '../types/furnace.js';
+import type { CustomComponentConfig, FurnaceOptInCheck, ValidationIssue } from '../types/furnace.js';
 /**
  * Validates accessibility patterns in a component's .mjs file.
  * Checks for ARIA roles, keyboard handlers, l10n, and focus delegation.
@@ -11,8 +11,10 @@ import type { CustomComponentConfig, ValidationIssue } from '../types/furnace.js
  *   (`keyboardCovered: true`) or via `composes` naming a native-interactive
  *   inner element. Optional so stock/override callers and test fixtures
  *   without config in scope can continue to call without changes.
+ * @param optInChecks - `furnace.json#optInChecks`. `icon-button-label`
+ *   adds the icon-only `<moz-button>` naming check.
  */
-export declare function validateAccessibility(componentDir: string, tagName: string, customConfig?: CustomComponentConfig): Promise<ValidationIssue[]>;
+export declare function validateAccessibility(componentDir: string, tagName: string, customConfig?: CustomComponentConfig, optInChecks?: readonly FurnaceOptInCheck[]): Promise<ValidationIssue[]>;
 /**
  * Detects hardcoded user-visible template text that should usually be
  * localized.

package/dist/src/core/furnace-validate-accessibility.js

@@ -2,6 +2,7 @@
 import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
 import { createIssue } from './furnace-validate-helpers.js';
+import { countUnlabelledIconButtons } from './furnace-validate-icon-button.js';
 import { collectLitTemplateRegions, parseTemplateAttributes } from './lit-template-regions.js';
 /**
  * Validates accessibility patterns in a component's .mjs file.
@@ -15,8 +16,10 @@ import { collectLitTemplateRegions, parseTemplateAttributes } from './lit-templa
  *   (`keyboardCovered: true`) or via `composes` naming a native-interactive
  *   inner element. Optional so stock/override callers and test fixtures
  *   without config in scope can continue to call without changes.
+ * @param optInChecks - `furnace.json#optInChecks`. `icon-button-label`
+ *   adds the icon-only `<moz-button>` naming check.
  */
-export async function validateAccessibility(componentDir, tagName, customConfig) {
+export async function validateAccessibility(componentDir, tagName, customConfig, optInChecks = []) {
     const mjsPath = join(componentDir, `${tagName}.mjs`);
     if (!(await pathExists(mjsPath)))
         return [];
@@ -56,6 +59,12 @@ export async function validateAccessibility(componentDir, tagName, customConfig)
     if (hasUnlabelledFormInput(content)) {
         issues.push(createIssue(tagName, 'warning', 'unlabelled-form-input', 'Form input without an accessible label. Add aria-label, aria-labelledby, or an associated <label> element.'));
     }
+    if (optInChecks.includes('icon-button-label')) {
+        const unlabelled = countUnlabelledIconButtons(content);
+        if (unlabelled > 0) {
+            issues.push(createIssue(tagName, 'warning', 'icon-button-label', `${unlabelled} icon-only <moz-button> without an accessible name. Add data-l10n-id (with the label in its Fluent message) or aria-label.`));
+        }
+    }
     return issues;
 }
 /** Detects whether template or script content assigns an ARIA role. */

package/dist/src/core/furnace-validate-exceptions.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Applies `furnace.json#validationExceptions[]` to a `furnace validate`
+ * result. An exception suppresses every finding of its check on its
+ * component. One that suppresses nothing is stale: the finding was fixed
+ * (or renamed) and the review record outlived it, so it is reported as a
+ * warning naming the entry to delete, which keeps the list honest under
+ * `--max-warnings 0`.
+ */
+import type { FurnaceValidationException, ValidationIssue } from '../types/furnace.js';
+/** The check name of the warning a stale exception produces. */
+export declare const STALE_VALIDATION_EXCEPTION_CHECK = "stale-validation-exception";
+/** A finding an exception suppressed, with the exception's reason. */
+export interface ExceptedValidationIssue extends ValidationIssue {
+    reason: string;
+}
+/** {@link applyValidationExceptions}'s result. */
+export interface ValidationExceptionOutcome {
+    /** Findings that still count, stale-exception warnings included. */
+    issues: ValidationIssue[];
+    /** Findings an exception suppressed. */
+    excepted: ExceptedValidationIssue[];
+    /** Exceptions that matched no finding of a component this run judged. */
+    stale: FurnaceValidationException[];
+}
+/**
+ * Splits findings into counted and excepted, and reports stale exceptions.
+ *
+ * @param issues - Every finding of the run
+ * @param exceptions - `furnace.json#validationExceptions`
+ * @param judged - Whether the run judged an exception's component. A run
+ *   scoped to one component cannot call another component's exception
+ *   stale, while the full run judges them all (including components
+ *   furnace.json no longer declares)
+ */
+export declare function applyValidationExceptions(issues: readonly ValidationIssue[], exceptions: readonly FurnaceValidationException[] | undefined, judged: (component: string) => boolean): ValidationExceptionOutcome;
+/** Counts error- and warning-severity findings. */
+export declare function countValidationSeverities(issues: readonly ValidationIssue[]): {
+    errors: number;
+    warnings: number;
+};

package/dist/src/core/furnace-validate-exceptions.js

@@ -0,0 +1,43 @@
+import { createIssue } from './furnace-validate-helpers.js';
+/** The check name of the warning a stale exception produces. */
+export const STALE_VALIDATION_EXCEPTION_CHECK = 'stale-validation-exception';
+function matches(exception, issue) {
+    return exception.component === issue.component && exception.check === issue.check;
+}
+/**
+ * Splits findings into counted and excepted, and reports stale exceptions.
+ *
+ * @param issues - Every finding of the run
+ * @param exceptions - `furnace.json#validationExceptions`
+ * @param judged - Whether the run judged an exception's component. A run
+ *   scoped to one component cannot call another component's exception
+ *   stale, while the full run judges them all (including components
+ *   furnace.json no longer declares)
+ */
+export function applyValidationExceptions(issues, exceptions, judged) {
+    const outcome = { issues: [], excepted: [], stale: [] };
+    const list = exceptions ?? [];
+    const used = new Set();
+    for (const issue of issues) {
+        const exception = list.find((entry) => matches(entry, issue));
+        if (exception === undefined) {
+            outcome.issues.push(issue);
+            continue;
+        }
+        used.add(exception);
+        outcome.excepted.push({ ...issue, reason: exception.reason });
+    }
+    for (const exception of list) {
+        if (used.has(exception) || !judged(exception.component))
+            continue;
+        outcome.stale.push(exception);
+        outcome.issues.push(createIssue(exception.component, 'warning', STALE_VALIDATION_EXCEPTION_CHECK, `furnace.json validationExceptions entry for [${exception.check}] matches no finding. ` +
+            'Delete the entry: the finding it records is gone.'));
+    }
+    return outcome;
+}
+/** Counts error- and warning-severity findings. */
+export function countValidationSeverities(issues) {
+    const errors = issues.filter((issue) => issue.severity === 'error').length;
+    return { errors, warnings: issues.length - errors };
+}

package/dist/src/core/furnace-validate-icon-button.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Counts icon-only `<moz-button>` elements in the module's Lit templates
+ * that carry neither `data-l10n-id` nor `aria-label`.
+ *
+ * @param content - The component module's source
+ */
+export declare function countUnlabelledIconButtons(content: string): number;

package/dist/src/core/furnace-validate-icon-button.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The opt-in `icon-button-label` check (`furnace.json#optInChecks`): an
+ * icon-only `<moz-button>` has no visible text, so its accessible name has
+ * to come from `data-l10n-id` (whose FTL message carries the label or
+ * `.aria-label`) or from `aria-label`. Without one, screen readers announce
+ * just "button".
+ *
+ * Scans the Lit `html` templates of the component module only. A button
+ * built with `document.createElement` is not seen.
+ */
+import { collectLitTemplateRegions, parseTemplateAttributes } from './lit-template-regions.js';
+/**
+ * Attributes (and their Lit property-binding spellings) that give the
+ * button an accessible name. `parseTemplateAttributes` lowercases names,
+ * so `.ariaLabel=${…}` arrives as `.arialabel`.
+ */
+const NAMING_ATTRIBUTES = ['data-l10n-id', 'aria-label', '.arialabel'];
+/** Attributes that give the button a visible label, so it is not icon-only. */
+const LABEL_ATTRIBUTES = ['label', '.label'];
+function isIconOnly(attrs, innerText) {
+    if (LABEL_ATTRIBUTES.some((name) => attrs.has(name)))
+        return false;
+    if (innerText.replace(/<[^>]*>/g, '').trim().length > 0)
+        return false;
+    const type = attrs.get('type') ?? '';
+    return attrs.has('iconsrc') || attrs.has('.iconsrc') || /(^|\s)icon(\s|$)/.test(type);
+}
+/**
+ * Counts icon-only `<moz-button>` elements in the module's Lit templates
+ * that carry neither `data-l10n-id` nor `aria-label`.
+ *
+ * @param content - The component module's source
+ */
+export function countUnlabelledIconButtons(content) {
+    let count = 0;
+    for (const region of collectLitTemplateRegions(content)) {
+        const pattern = /<moz-button\b((?:"[^"]*"|'[^']*'|[^'">])*)>([\s\S]*?)<\/moz-button>/gi;
+        for (const match of region.matchAll(pattern)) {
+            const attrs = parseTemplateAttributes(match[1] ?? '');
+            if (!isIconOnly(attrs, match[2] ?? ''))
+                continue;
+            if (NAMING_ATTRIBUTES.some((name) => attrs.has(name)))
+                continue;
+            count++;
+        }
+    }
+    return count;
+}

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

@@ -49,7 +49,7 @@ export async function validateComponent(componentDir, tagName, type, config, roo
     // parameter, so this is a no-op for stock and override components.
     const customConfigForTag = type === 'custom' ? config?.custom[tagName] : undefined;
     issues.push(...(await validateStructure(componentDir, tagName, type, customConfigForTag)));
-    issues.push(...(await validateAccessibility(componentDir, tagName, customConfigForTag)));
+    issues.push(...(await validateAccessibility(componentDir, tagName, customConfigForTag, config?.optInChecks)));
     issues.push(...(await validateCompatibility(componentDir, tagName, type, config, root)));
     if (root && config && type === 'override') {
         const forgeConfig = await loadConfig(root);

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

@@ -0,0 +1,60 @@
+/**
+ * `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

@@ -0,0 +1,96 @@
+// 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/history-log-file.d.ts

@@ -0,0 +1,61 @@
+/** Filename of the history log at its pre-0.50 location, inside `patches/`. */
+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 left at the legacy `patches/` path to `target`.
+ *
+ * Records are never dropped, whatever else is happening:
+ * - The legacy 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 (an older FireForge appended to the legacy path after
+ *   a migration, or `history.path` changed), the legacy 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 legacy path, never deleted.
+ *
+ * @param patchesDir - The patches directory that may hold a legacy 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, migrating a
+ * legacy log first.
+ *
+ * @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

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Where the patch history log lives, and who wrote each record.
+ *
+ * The log used to be `patches/.fireforge-history.jsonl`, inside the tracked
+ * patch queue, so it was committed with every export until consumers
+ * gitignored it, and it grew to tens of megabytes. It now defaults to
+ * `.fireforge/history.jsonl` (FireForge's own untracked data directory), or
+ * `fireforge.json#history.path` when a project sets one. A log left at the
+ * old path 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 } 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 the history log at its pre-0.50 location, inside `patches/`. */
+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 left at the legacy `patches/` path to `target`.
+ *
+ * Records are never dropped, whatever else is happening:
+ * - The legacy 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 (an older FireForge appended to the legacy path after
+ *   a migration, or `history.path` changed), the legacy 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 legacy path, never deleted.
+ *
+ * @param patchesDir - The patches directory that may hold a legacy 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) {
+        // 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, migrating a
+ * legacy log first.
+ *
+ * @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

@@ -10,7 +10,8 @@ import type { HistoryEntry } from './destructive.js';
  * 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 now lives in one place.
- * @param patchesDir - The `patches/` directory holding the history log.
+ * @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.

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

@@ -13,7 +13,8 @@ import { appendHistory } from './destructive.js';
  * 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 now lives in one place.
- * @param patchesDir - The `patches/` directory holding the history log.
+ * @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.

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

@@ -0,0 +1,22 @@
+/**
+ * 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;