@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/core/build-prepare.js

@@ -1,414 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Shared pre-flight logic for build and package commands:
- * story cleanup, branding setup, Furnace component application, and mozconfig generation.
- */
-import { constants as osConstants } from 'node:os';
-import { GeneralError } from '../errors/base.js';
-import { BuildError } from '../errors/build.js';
-import { FurnaceError } from '../errors/furnace.js';
-import { toError } from '../utils/errors.js';
-import { pathExists } from '../utils/fs.js';
-import { info, notice, spinner, verbose, warn } from '../utils/logger.js';
-import { isBrandingSetup, setupBranding } from './branding.js';
-import { isBuildInputPath, isJarManifestPath } from './build-audit.js';
-import { evaluateJarManifestEscalation, formatJarEscalationNotice, } from './build-jar-escalation.js';
-import { assessUnexportedDrift, formatDeployedUnexportedNote, formatUnexportedDriftWarning, } from './build-overwrite-guard.js';
-import { hashEngineFile } from './coverage-extend.js';
-import { collectChangedEnginePaths, dropPathsMatchingFingerprints } from './engine-changes.js';
-import { applyAllComponents } from './furnace-apply.js';
-import { logApplyWarnings } from './furnace-apply-output.js';
-import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from './furnace-config.js';
-import { runFurnaceMutation } from './furnace-operation.js';
-import { countEntriesWithBlockingStepErrors } from './furnace-step-errors.js';
-import { cleanStories } from './furnace-stories.js';
-import { generateMozconfig, runMachCapture } from './mach.js';
-import { explainMachError } from './mach-error-hints.js';
-/** Path fragments of files whose edits invalidate the recursive-make backend. */
-const BACKEND_INVALIDATING_SUFFIXES = ['moz.build', 'moz.configure', 'Makefile.in'];
-/**
- * Build-input manifests changed since the last successful build, not
- * merely dirty against HEAD. `collectChangedEnginePaths` unions the
- * baseline-to-HEAD diff with every worktree modification, and a fork's
- * worktree is permanently dirty (imported patches, Furnace-applied
- * components), so on its own it reports a patch-touched `jar.mn` or
- * `moz.build` as changed on every run: `mach configure` re-ran and the
- * pre-test build escalated to a full `mach build` after each full build
- * that had already consumed exactly this content. The baseline's
- * `buildInputFingerprints` say what the last successful build saw.
- * Anything byte-identical to that is dropped here. A baseline without the
- * field (written before it existed) keeps every dirty input, which is the
- * old behaviour.
- *
- * @param engineDir - Path to the engine directory
- * @param baseline - Last successful build's baseline
- * @returns Engine-relative build-input paths that still need acting on
- */
-async function collectChangedBuildInputs(engineDir, baseline) {
-    const changed = await collectChangedEnginePaths(engineDir, baseline, 'Auto-configure');
-    const dirtyInputs = changed.filter(isBuildInputPath);
-    const stillChanged = await dropPathsMatchingFingerprints(engineDir, dirtyInputs, baseline.buildInputFingerprints);
-    const unchangedSinceBuild = dirtyInputs.filter((path) => !stillChanged.includes(path));
-    if (unchangedSinceBuild.length > 0) {
-        verbose(`Auto-configure: ${unchangedSinceBuild.length} dirty build input(s) byte-identical to the last successful build, not treated as changed: ${unchangedSinceBuild.join(', ')}`);
-    }
-    return stillChanged;
-}
-/**
- * Extracts the tail of captured `mach configure` output so the underlying
- * mozbuild failure (e.g. `mozbuild.util.UnsortedError: ... is not in sorted
- * order`) is carried into the thrown `BuildError` instead of being reduced to
- * a bare exit code. mozbuild writes the error and its traceback to stderr,
- * and stdout is included as a fallback for shells that interleave the
- * streams.
- * Returns an empty string when nothing useful was captured.
- */
-function extractMachConfigureError(result) {
-    const combined = `${result.stderr}\n${result.stdout}`.trim();
-    if (!combined)
-        return '';
-    return combined.split('\n').slice(-40).join('\n').trim();
-}
-/**
- * Describes an exit code in the shell's 128+N signal convention. Truncated
- * configure/build logs with a signal-shaped exit (e.g. 144 = 128+16, SIGURG
- * on macOS) are environmental interruptions, not compiler failures. Naming
- * that in the failure text saves the operator a fruitless log hunt.
- * Returns undefined for codes <= 128 (regular failures) and
- * for codes past the conventional signal range, so callers append nothing.
- */
-export function describeSignalShapedExit(exitCode) {
-    if (exitCode <= 128 || exitCode > 192)
-        return undefined;
-    const signalNumber = exitCode - 128;
-    const names = Object.entries(osConstants.signals)
-        .filter(([, value]) => value === signalNumber)
-        .map(([name]) => name);
-    const label = names.length > 0 ? names.join('/') : `signal ${signalNumber}`;
-    return (`Exit ${exitCode} is signal-shaped (${exitCode} - 128 = ${signalNumber}, ${label} on this host): ` +
-        'the process was likely interrupted externally (OOM-killer, terminal disconnect, ' +
-        'display/session teardown) rather than failing on its own, and the log may be ' +
-        'truncated mid-step.');
-}
-/**
- * Builds the `BuildError` for a non-zero auto-configure exit: the output
- * tail (so the underlying mozbuild failure survives), any matched
- * mach-error hints (so e.g. a toolchain minimum that moved with a source
- * hop names `fireforge bootstrap` on this path too, just like the
- * protected build dispatch), and the stop rationale.
- */
-function buildConfigureFailureError(captured) {
-    const detail = extractMachConfigureError(captured);
-    const hints = explainMachError(`${captured.stderr}\n${captured.stdout}`);
-    const signalNote = describeSignalShapedExit(captured.exitCode);
-    return new BuildError(`Backend regeneration failed: mach configure exited with code ${captured.exitCode}.` +
-        (detail ? `\n\nmach configure output (tail):\n${detail}` : '') +
-        (signalNote ? `\n\n${signalNote}` : '') +
-        (hints.length > 0 ? `\n\n${hints.map((hint) => `Hint: ${hint}`).join('\n')}` : '') +
-        '\n\nBuild stopped because continuing would hide the real configure failure.', 'mach configure');
-}
-/**
- * Runs the narrowed `jar.mn` escalation rule over this run's changed build
- * inputs and returns the operator-facing reason when a full build is still
- * required, or undefined when the narrowing cleared every changed manifest.
- *
- * Extracted so `prepareBuildEnvironment` stays under the complexity budget.
- *
- * @param engineDir - Absolute engine directory
- * @param changed - Build inputs changed since the last successful build
- */
-async function decideJarEscalation(engineDir, changed) {
-    // Packaging manifests whose graph/destination directories may need a full
-    // build. Path-shape only: `evaluateJarManifestEscalation` decides whether a
-    // given changed manifest actually forces one (a new manifest, or one that
-    // redirects its install base directory), so an entry added to an existing
-    // `dist/bin` manifest does not cost a ~10-minute build.
-    const decision = await evaluateJarManifestEscalation(engineDir, changed.filter(isJarManifestPath));
-    if (decision.cleared.length > 0) {
-        verbose(`jar escalation: ${decision.cleared.length} changed jar.mn add entries to an existing dist/bin manifest; not escalating for ${decision.cleared.join(', ')}.`);
-    }
-    return decision.escalate ? formatJarEscalationNotice(decision) : undefined;
-}
-/**
- * Returns true when the file path matches a pattern that forces
- * `mach configure` to regenerate the backend. Exported for testing.
- */
-export function isBackendInvalidatingFile(path) {
-    for (const suffix of BACKEND_INVALIDATING_SUFFIXES) {
-        if (path === suffix || path.endsWith(`/${suffix}`))
-            return true;
-    }
-    return false;
-}
-/**
- * Warns before the overwrite rather than after it.
- *
- * Every write `prepareBuildEnvironment` performs (branding, Furnace
- * components, `mozconfig`) rewrites engine files from a FireForge-owned
- * source. Content recorded in neither a patch body nor the pristine baseline
- * is destroyed by that, and on a multi-session checkout the destruction is
- * what lets a later re-export capture a half-reverted hybrid that every gate
- * then passes.
- *
- * @param projectRoot - Project root
- * @param config - Loaded FireForge config
- * @param options - Build-prepare options (reads `refuseUnexportedDrift`)
- * @throws GeneralError under `--refuse-unexported-drift`
- */
-async function reportUnexportedDriftBeforeOverwrite(projectRoot, config, options) {
-    const { atRisk, deployedUnexported } = await assessUnexportedDrift(projectRoot, config);
-    // Deployed Furnace files that are their component source's own
-    // deployment never block: the overwrite loses nothing. Say so, since
-    // their patches still owe a re-export.
-    if (deployedUnexported.length > 0)
-        info(formatDeployedUnexportedNote(deployedUnexported));
-    if (atRisk.length === 0)
-        return;
-    const message = formatUnexportedDriftWarning(atRisk);
-    if (options.refuseUnexportedDrift === true) {
-        throw new GeneralError(message);
-    }
-    notice(message);
-}
-/**
- * Applies the named components one at a time, each under its own Furnace
- * mutation (one rollback journal per apply), and merges the results.
- */
-async function applySelectedComponents(projectRoot, names) {
-    const merged = {
-        applied: [],
-        skipped: [],
-        errors: [],
-        warnings: [],
-    };
-    for (const componentName of names) {
-        const result = await runFurnaceMutation(projectRoot, 'apply-rollback', (ctx) => applyAllComponents(projectRoot, false, { operationContext: ctx, componentName }));
-        merged.applied.push(...result.applied);
-        merged.skipped.push(...result.skipped);
-        merged.errors.push(...result.errors);
-        merged.warnings.push(...(result.warnings ?? []));
-    }
-    return merged;
-}
-/**
- * Applies Furnace components before the build when `furnace.json` exists.
- * Prints every warning the apply computed, then the loud sync banner.
- *
- * @param projectRoot - Project root
- * @param only - Apply just these components; every component when undefined
- * @returns Names of the components written to engine/
- */
-async function applyFurnaceBeforeBuild(projectRoot, only) {
-    if (!(await furnaceConfigExists(projectRoot)))
-        return [];
-    const furnaceConfig = await loadFurnaceConfig(projectRoot);
-    const hasComponents = Object.keys(furnaceConfig.overrides).length > 0 || Object.keys(furnaceConfig.custom).length > 0;
-    if (!hasComponents)
-        return [];
-    const furnaceSpinner = spinner('Applying Furnace components...');
-    let result;
-    try {
-        result =
-            only === undefined
-                ? await runFurnaceMutation(projectRoot, 'apply-rollback', (ctx) => applyAllComponents(projectRoot, false, { operationContext: ctx }))
-                : await applySelectedComponents(projectRoot, only);
-    }
-    catch (error) {
-        furnaceSpinner.error('Failed to apply Furnace components');
-        throw error;
-    }
-    const furnaceApplied = result.applied.length;
-    // Count entries that were "applied" but recorded step-level errors
-    // mid-apply (e.g. a post-step failure after file writes succeeded).
-    // These are distinct from `result.errors`, which captures
-    // components that failed before reaching the applied list at all.
-    // The sum of the two is the total count of failed components.
-    const appliedWithStepErrorsCount = countEntriesWithBlockingStepErrors(result.applied);
-    const totalApplyFailures = result.errors.length + appliedWithStepErrorsCount;
-    if (totalApplyFailures > 0) {
-        furnaceSpinner.error('Failed to apply Furnace components');
-        for (const err of result.errors) {
-            warn(`Furnace: ${err.name} — ${err.error}`);
-        }
-        for (const applied of result.applied) {
-            if (applied.stepErrors && applied.stepErrors.length > 0) {
-                for (const stepErr of applied.stepErrors) {
-                    warn(`Furnace: ${applied.name} [${stepErr.step}] ${stepErr.error}`);
-                }
-            }
-        }
-        throw new FurnaceError(`${totalApplyFailures} component${totalApplyFailures === 1 ? '' : 's'} failed to apply cleanly`);
-    }
-    // The apply computed these (patch-owned engine files whose content
-    // differed from components/ and were replaced). `furnace apply`
-    // prints them, and so does this path: dropped silently, a negative
-    // control that edited a deployed Furnace file would run against the
-    // shipped code with a green result and only a checksum could tell.
-    const overwriteCount = logApplyWarnings(result.warnings);
-    if (overwriteCount > 0) {
-        notice(`Furnace: ${overwriteCount} Furnace-managed engine file${overwriteCount === 1 ? '' : 's'} differed from components/ and ${overwriteCount === 1 ? 'was' : 'were'} REPLACED before this build. An engine-side edit to a Furnace-managed file (for example a negative control) did not run; edit the component source under components/ instead, or restore the edit after the build.`);
-    }
-    if (furnaceApplied > 0) {
-        const appliedNames = result.applied.map((entry) => entry.name).join(', ');
-        furnaceSpinner.stop(`Applied ${furnaceApplied} component${furnaceApplied === 1 ? '' : 's'}`);
-        // Loud banner: the build operator needs to see that engine/ was
-        // updated before this build, otherwise a silent re-apply is
-        // indistinguishable from a build that shipped stale components.
-        notice(`Furnace: source → engine sync wrote ${furnaceApplied} component${furnaceApplied === 1 ? '' : 's'} before build (${appliedNames}). engine/ now matches components/.`);
-    }
-    else {
-        furnaceSpinner.stop('Components up to date');
-    }
-    return result.applied.map((entry) => entry.name);
-}
-/**
- * Runs the auto-configure step (`mach configure`) against the freshly
- * generated mozconfig, surfacing the underlying mozbuild error on failure.
- * @param engineDir - Path to the engine directory
- * @param triggers - Why the backend is being regenerated, for the notice
- */
-async function runAutoConfigure(engineDir, triggers) {
-    // Warning severity: this is the "why is this run slow" explanation,
-    // and an info-level line does not survive an agent output filter that
-    // keeps only warnings and errors.
-    notice(`Backend config changed; running backend regeneration first (${triggers}). Backend command: mach configure.`);
-    const configureSpinner = spinner('Running mach configure...');
-    try {
-        const captured = await runMachCapture(['configure'], engineDir);
-        const exitCode = captured.exitCode;
-        if (exitCode !== 0) {
-            configureSpinner.error(`mach configure failed with exit code ${exitCode}`);
-            // Surface the underlying mozbuild error (e.g. UnsortedError)
-            // instead of a bare exit code, since the generic message hid the
-            // actual cause, plus any matched mach-error hints (see the helper).
-            throw buildConfigureFailureError(captured);
-        }
-        configureSpinner.stop('Backend regenerated successfully (mach configure exit code 0)');
-        info('Backend regeneration succeeded; continuing with build.');
-    }
-    catch (error) {
-        if (error instanceof BuildError) {
-            throw error;
-        }
-        configureSpinner.error('mach configure failed');
-        verbose(`Auto-configure error: ${toError(error).message}`);
-        throw new BuildError(`Backend regeneration failed while running mach configure: ${toError(error).message}. Build stopped because continuing would hide the real configure failure.`, 'mach configure', error instanceof Error ? error : undefined);
-    }
-}
-/**
- * Runs the shared pre-flight steps for build and package commands:
- * 1. Warns (or refuses) about unexported engine drift the writes below
- * would destroy
- * 2. Cleans Furnace stories from engine (prevents leaking into production)
- * 3. Sets up branding directory if not already done
- * 4. Applies Furnace components if furnace.json exists
- * 5. Generates mozconfig
- * 6. Runs `mach configure` when a backend-invalidating input, including
- * the mozconfig just generated, changed since the previous baseline
- *
- * @param projectRoot - Root directory of the project
- * @param paths - Resolved project paths
- * @param config - Loaded FireForge configuration
- * @param options - Baseline and drift-refusal options
- * @returns Preparation results
- */
-export async function prepareBuildEnvironment(projectRoot, paths, config, options = {}) {
-    // Block the build if Furnace has an unresolved repair marker. This prevents
-    // building against an engine that may be in an inconsistent state after a
-    // failed rollback.
-    const furnaceStatePath = getFurnacePaths(projectRoot).furnaceState;
-    if (await pathExists(furnaceStatePath)) {
-        const furnaceState = await loadFurnaceState(projectRoot);
-        if (furnaceState.pendingRepair) {
-            throw new FurnaceError(`Furnace has an unresolved repair marker (from ${furnaceState.pendingRepair.operation}). ` +
-                'Run "fireforge doctor --repair-furnace" to reconcile engine state before building.');
-        }
-    }
-    await reportUnexportedDriftBeforeOverwrite(projectRoot, config, options);
-    // Auto-configure census: if any backend-invalidating file (moz.build,
-    // moz.configure, Makefile.in) changed since the last successful build,
-    // `mach configure` runs before the build step. Prevents incremental builds
-    // from silently skipping work against a stale recursive-make backend. The
-    // configure itself waits until the mozconfig below has been regenerated:
-    // run earlier, it configured against the previous engine/mozconfig, and a
-    // configs/ fix for a failing configure (a pinned --with-macos-sdk) could
-    // never take effect because the failure stopped the build before the
-    // regeneration.
-    const configureTriggers = [];
-    let fullBuildRequired = false;
-    let fullBuildReason;
-    if (options.previousBaseline) {
-        const changed = await collectChangedBuildInputs(paths.engine, options.previousBaseline);
-        const invalidating = changed.filter(isBackendInvalidatingFile);
-        const jarEscalation = await decideJarEscalation(paths.engine, changed);
-        fullBuildRequired = jarEscalation !== undefined;
-        fullBuildReason = jarEscalation;
-        if (invalidating.length > 0) {
-            configureTriggers.push(`${invalidating.length} file${invalidating.length === 1 ? '' : 's'} touched`);
-        }
-    }
-    // Clean stories before build to ensure they don't leak into production binary
-    await cleanStories(paths.engine);
-    // Set up custom branding directory and patch moz.configure. Thread the
-    // project license through so `buildConfigureScriptContent` /
-    // `buildBrandPropertiesContent` / `buildBrandFtlContent` stamp the
-    // generated files with a matching SPDX header. Otherwise `patch-lint`
-    // flags them with `missing-license-header` on every subsequent export when
-    // the project is not MPL-2.0.
-    const brandingConfig = {
-        name: config.name,
-        vendor: config.vendor,
-        appId: config.appId,
-        binaryName: config.binaryName,
-        ...(config.license !== undefined ? { license: config.license } : {}),
-    };
-    if (!(await isBrandingSetup(paths.engine, brandingConfig))) {
-        const brandingSpinner = spinner('Setting up branding...');
-        try {
-            await setupBranding(paths.engine, brandingConfig);
-            brandingSpinner.stop('Branding configured');
-        }
-        catch (error) {
-            brandingSpinner.error('Failed to set up branding');
-            throw error;
-        }
-    }
-    const furnaceAppliedNames = options.skipFurnaceApply === true || options.furnaceComponents?.length === 0
-        ? []
-        : await applyFurnaceBeforeBuild(projectRoot, options.furnaceComponents);
-    // Generate mozconfig
-    const mozconfigSpinner = spinner('Generating mozconfig...');
-    let mozconfigWritten;
-    try {
-        mozconfigWritten = await generateMozconfig(paths.configs, paths.engine, config);
-        mozconfigSpinner.stop('mozconfig generated');
-    }
-    catch (error) {
-        mozconfigSpinner.error('Failed to generate mozconfig');
-        throw error;
-    }
-    // A changed mozconfig is itself backend-invalidating. Compare against the
-    // hash the last successful build recorded; a baseline from before that
-    // field existed falls back to whether this run rewrote the file.
-    if (options.previousBaseline) {
-        const recorded = options.previousBaseline.mozconfigHash;
-        const mozconfigChanged = recorded !== undefined
-            ? (await hashEngineFile(paths.engine, 'mozconfig')) !== recorded
-            : mozconfigWritten;
-        if (mozconfigChanged) {
-            configureTriggers.push('engine/mozconfig changed since the last build');
-        }
-    }
-    let reconfigured = false;
-    if (configureTriggers.length > 0) {
-        await runAutoConfigure(paths.engine, configureTriggers.join('; '));
-        reconfigured = true;
-    }
-    return {
-        furnaceApplied: furnaceAppliedNames.length,
-        furnaceAppliedNames,
-        reconfigured,
-        fullBuildRequired,
-        ...(fullBuildReason !== undefined ? { fullBuildReason } : {}),
-    };
-}

package/dist/src/core/build-run-record.d.ts

@@ -1,74 +0,0 @@
-/**
- * A record of the mach build in flight, kept in `.fireforge/build-run.json`
- * so any session on the checkout can see why the bundle is missing.
- *
- * An interrupted `fireforge build` (a killed peer session, a closed
- * terminal) can leave `dist/<App>.app/Contents/MacOS/` without its
- * executable. Every later `fireforge test`, in every session, then failed
- * at launch with nothing saying a build had died there, and the sessions
- * that had not run the build had no way to find out.
- *
- * The record is written when a protected mach build starts and removed when
- * it succeeds. A failed build leaves it with `status: "failed"` and the exit
- * code. A build that never reached either end, because its process died,
- * leaves `status: "running"` with a PID that no longer exists, which is how
- * an interrupted run is recognized. The next build that runs to the end
- * replaces whatever was there.
- *
- * Best-effort throughout: a build never fails because its record could not
- * be written, and an unreadable record reads as "no record".
- */
-/** The persisted record. */
-interface BuildRunRecord {
-    /** Whether the build is (or was last seen) running, or ended in failure. */
-    status: 'running' | 'failed';
-    /** PID of the FireForge process that ran the build. */
-    pid: number;
-    /** That process's boot-relative start tick, where procfs exposes one. */
-    startTick?: number;
-    /** The FireForge invocation, e.g. `fireforge build --ui`. */
-    command: string;
-    /** The mach command, e.g. `mach build faster`. */
-    machCommand: string;
-    /** ISO time the mach build started. */
-    startedAt: string;
-    /** ISO time a failed build ended. */
-    endedAt?: string;
-    /** Exit code of a failed build, when mach returned one. */
-    exitCode?: number;
-}
-/** What the record says about the last build. */
-export type BuildRunState = {
-    kind: 'none';
-} | {
-    kind: 'running' | 'interrupted' | 'failed';
-    record: BuildRunRecord;
-};
-/**
- * Runs a mach build with its run record maintained around it. The record
- * is removed on a zero exit and kept as `failed` on a non-zero exit or a
- * throw, so only a build whose process died mid-run is left `running`.
- *
- * @param projectRoot - Project root holding `.fireforge/`
- * @param machCommand - The mach command being run
- * @param build - The build itself
- * @returns Whatever the build returned
- */
-export declare function withBuildRunRecord<T extends {
-    exitCode: number;
-}>(projectRoot: string, machCommand: string, build: () => Promise<T>): Promise<T>;
-/**
- * Reads the last build's record and decides whether its process is still
- * running.
- *
- * @param projectRoot - Project root holding `.fireforge/`
- */
-export declare function readBuildRunState(projectRoot: string): Promise<BuildRunState>;
-/**
- * One sentence naming why the bundle may be missing, or undefined when
- * there is no record to go on.
- *
- * @param state - From {@link readBuildRunState}
- */
-export declare function describeBuildRunState(state: BuildRunState): string | undefined;
-export {};

package/dist/src/core/build-run-record.js

@@ -1,136 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * A record of the mach build in flight, kept in `.fireforge/build-run.json`
- * so any session on the checkout can see why the bundle is missing.
- *
- * An interrupted `fireforge build` (a killed peer session, a closed
- * terminal) can leave `dist/<App>.app/Contents/MacOS/` without its
- * executable. Every later `fireforge test`, in every session, then failed
- * at launch with nothing saying a build had died there, and the sessions
- * that had not run the build had no way to find out.
- *
- * The record is written when a protected mach build starts and removed when
- * it succeeds. A failed build leaves it with `status: "failed"` and the exit
- * code. A build that never reached either end, because its process died,
- * leaves `status: "running"` with a PID that no longer exists, which is how
- * an interrupted run is recognized. The next build that runs to the end
- * replaces whatever was there.
- *
- * Best-effort throughout: a build never fails because its record could not
- * be written, and an unreadable record reads as "no record".
- */
-import { readFile, rm } from 'node:fs/promises';
-import { join } from 'node:path';
-import { toError } from '../utils/errors.js';
-import { writeFileAtomic } from '../utils/fs.js';
-import { verbose } from '../utils/logger.js';
-import { FIREFORGE_DIR } from './config-paths.js';
-import { isLockOwnerAlive, readProcessStartTick } from './file-lock-owner.js';
-/** File name of the record under `.fireforge/`. */
-const BUILD_RUN_RECORD = 'build-run.json';
-function recordPath(projectRoot) {
-    return join(projectRoot, FIREFORGE_DIR, BUILD_RUN_RECORD);
-}
-async function writeRecord(projectRoot, record) {
-    try {
-        await writeFileAtomic(recordPath(projectRoot), `${JSON.stringify(record, null, 2)}\n`);
-    }
-    catch (error) {
-        verbose(`Build run record not written: ${toError(error).message}`);
-    }
-}
-/**
- * Runs a mach build with its run record maintained around it. The record
- * is removed on a zero exit and kept as `failed` on a non-zero exit or a
- * throw, so only a build whose process died mid-run is left `running`.
- *
- * @param projectRoot - Project root holding `.fireforge/`
- * @param machCommand - The mach command being run
- * @param build - The build itself
- * @returns Whatever the build returned
- */
-export async function withBuildRunRecord(projectRoot, machCommand, build) {
-    const startTick = readProcessStartTick(process.pid);
-    const started = {
-        status: 'running',
-        pid: process.pid,
-        ...(startTick !== undefined ? { startTick } : {}),
-        command: ['fireforge', ...process.argv.slice(2)].join(' '),
-        machCommand,
-        startedAt: new Date().toISOString(),
-    };
-    await writeRecord(projectRoot, started);
-    let result;
-    try {
-        result = await build();
-    }
-    catch (error) {
-        await writeRecord(projectRoot, {
-            ...started,
-            status: 'failed',
-            endedAt: new Date().toISOString(),
-        });
-        throw error;
-    }
-    if (result.exitCode === 0) {
-        await rm(recordPath(projectRoot), { force: true }).catch(() => undefined);
-    }
-    else {
-        await writeRecord(projectRoot, {
-            ...started,
-            status: 'failed',
-            endedAt: new Date().toISOString(),
-            exitCode: result.exitCode,
-        });
-    }
-    return result;
-}
-/**
- * Reads the last build's record and decides whether its process is still
- * running.
- *
- * @param projectRoot - Project root holding `.fireforge/`
- */
-export async function readBuildRunState(projectRoot) {
-    let record;
-    try {
-        record = JSON.parse(await readFile(recordPath(projectRoot), 'utf8'));
-    }
-    catch {
-        return { kind: 'none' };
-    }
-    if (typeof record.pid !== 'number' || typeof record.startedAt !== 'string') {
-        return { kind: 'none' };
-    }
-    if (record.status === 'failed')
-        return { kind: 'failed', record };
-    return {
-        kind: isLockOwnerAlive({ pid: record.pid, startTick: record.startTick })
-            ? 'running'
-            : 'interrupted',
-        record,
-    };
-}
-/**
- * One sentence naming why the bundle may be missing, or undefined when
- * there is no record to go on.
- *
- * @param state - From {@link readBuildRunState}
- */
-export function describeBuildRunState(state) {
-    if (state.kind === 'none')
-        return undefined;
-    const { record } = state;
-    const who = `"${record.command}" (${record.machCommand}, PID ${record.pid}, started ${record.startedAt})`;
-    switch (state.kind) {
-        case 'running':
-            return `A build is running right now: ${who}. The bundle is incomplete until it finishes.`;
-        case 'interrupted':
-            return (`The last build never finished: ${who} is gone without recording an end, so it was ` +
-                'interrupted (killed, or its terminal closed) part-way, which leaves the bundle without ' +
-                'its executable.');
-        case 'failed':
-            return (`The last build failed: ${who} ended ${record.endedAt ?? 'at an unrecorded time'}` +
-                `${record.exitCode !== undefined ? ` with exit code ${record.exitCode}` : ''}.`);
-    }
-}

package/dist/src/core/checkjs-support-heads.d.ts

@@ -1,41 +0,0 @@
-/**
- * Unowned support heads for the named-file checkJs pass of `test --build`.
- *
- * Each named test is checked as its own program: the test plus the
- * patch-owned `head*.js` beside it. A suite moved onto a NEW support head
- * (`head_world_page.js`, loaded with `loadSubScript`) cannot be proven
- * before that head is exported, because the head is in no patch: every kit
- * name reads as "Cannot find name" and the run is refused at preflight,
- * with the generic hint, which offers the shim as a remedy.
- *
- * So an unowned same-directory `head*.js` joins the pass when a named test
- * loads it with `loadSubScript` or a manifest beside it lists it in
- * `support-files`, which are the two ways the harness itself would bring
- * it into the test's scope. The operator is told it is unowned and how to
- * adopt it, as for the `head.js` companions in
- * `patch-lint-unmanaged-companion.ts`.
- */
-/** A same-directory head no patch owns, and why the pass includes it. */
-export interface UnownedSupportHead {
-    /** Engine-relative path of the head. */
-    file: string;
-    /** What brings it into the test's scope. */
-    reason: string;
-}
-/**
- * Finds the unowned same-directory `head*.js` files the named tests bring
- * into scope.
- *
- * @param engineDir - Absolute engine directory
- * @param selected - Engine-relative named test files
- * @param owned - Every file the pass already includes
- */
-export declare function findUnownedSupportHeads(engineDir: string, selected: Iterable<string>, owned: ReadonlySet<string>): Promise<UnownedSupportHead[]>;
-/**
- * The notice for an included unowned head: the ownership fact, the
- * adoption command, and an explicit "not the shim", for the same reason
- * `formatUnmanagedCompanionHint` gives.
- *
- * @param head - From {@link findUnownedSupportHeads}
- */
-export declare function formatUnownedSupportHeadNotice(head: UnownedSupportHead): string;