@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/commands/doctor-furnace-config-sync.js

@@ -1,295 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * "Furnace config sync" doctor check.
- *
- * Surfaces orphaned component directories on disk whose names are missing
- * from `furnace.json`, typically the concurrent-override race, where two
- * parallel `furnace override` commands both leave their directory on disk
- * but only the second reaches `writeFurnaceConfig`. Under
- * `--repair-furnace`, override orphans are re-registered from the
- * `override.json` sidecar the command wrote during the copy phase. Custom
- * orphans are listed for the operator to either re-run `furnace create`
- * against or delete manually, because custom components have no similar
- * persisted metadata.
- *
- * Lives in a sibling module to keep `doctor-furnace.ts` under the per-file
- * LOC budget.
- */
-import { readdir, rmdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { withFileLock } from '../core/file-lock.js';
-import { getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig } from '../core/furnace-config.js';
-import { getFurnaceLockPath } from '../core/furnace-operation.js';
-import { toError } from '../utils/errors.js';
-import { pathExistsStrict, readJson } from '../utils/fs.js';
-import { failure, ok, warning } from './doctor-check-core.js';
-/**
- * Lists component directories, distinguishing "none" from "could not look".
- *
- * A missing directory is genuinely empty. A `readdir` failure is not: this
- * check exists to detect the concurrent-override orphan race, and swallowing
- * the error into `[]` made it report clean for the one condition it is here
- * to catch. The caller surfaces the failure instead.
- */
-async function listComponentDirs(dir) {
-    // `pathExistsStrict`, not `pathExists`: the latter answers `false` for every
-    // access error, so an unreadable components directory reported "no orphans",
-    // i.e. a clean check. That is the same fail-open the comment above rejects
-    // for `readdir`. Only ENOENT means genuinely absent.
-    if (!(await pathExistsStrict(dir)))
-        return [];
-    const entries = await readdir(dir, { withFileTypes: true });
-    return entries.filter((e) => e.isDirectory()).map((e) => e.name);
-}
-async function recoverOverrideConfig(overrideDir, name) {
-    // `furnace override` writes `override.json` alongside the copied files.
-    // That sidecar is enough to reconstruct the furnace.json entry lost to a
-    // concurrent-write race, where the second override writes back the
-    // outer-snapshot config and drops the sibling write's addition.
-    //
-    // No `pathExists` precheck: it collapses "absent" and "unreadable" into
-    // the same `false`, and both outcomes lead here anyway. A missing file
-    // lands in the catch below with the same `undefined` result.
-    const sidecarPath = join(overrideDir, name, 'override.json');
-    try {
-        const raw = await readJson(sidecarPath);
-        const type = raw.type;
-        const description = raw.description;
-        const basePath = raw.basePath;
-        const baseVersion = raw.baseVersion;
-        if ((type !== 'css-only' && type !== 'full') ||
-            typeof description !== 'string' ||
-            typeof basePath !== 'string' ||
-            typeof baseVersion !== 'string') {
-            return undefined;
-        }
-        const restored = {
-            type: type,
-            description,
-            basePath,
-            baseVersion,
-        };
-        if (typeof raw.baseCommit === 'string') {
-            // `baseCommit` is already declared optional on OverrideComponentConfig,
-            // so the intersection this replaced widened nothing.
-            restored.baseCommit = raw.baseCommit;
-        }
-        return restored;
-    }
-    catch {
-        // Unreadable or malformed sidecar. Returning `undefined` here is the same
-        // value as "no sidecar present", so the caller reports the override as
-        // unrecoverable. That is the safe direction (it never invents config),
-        // but the operator sees "no valid override.json" rather than "the
-        // override.json is corrupt". The remediation is identical either way.
-        return undefined;
-    }
-}
-async function collectOrphans(projectRoot, config) {
-    const furnacePaths = getFurnacePaths(projectRoot);
-    const overrideDirs = await listComponentDirs(furnacePaths.overridesDir);
-    const overrideOrphans = [];
-    for (const name of overrideDirs) {
-        if (name in config.overrides)
-            continue;
-        const recoveredConfig = await recoverOverrideConfig(furnacePaths.overridesDir, name);
-        overrideOrphans.push({ name, recoveredConfig });
-    }
-    const customDirs = await listComponentDirs(furnacePaths.customDir);
-    const customOrphans = customDirs.filter((name) => !(name in config.custom));
-    return { overrides: overrideOrphans, customNames: customOrphans };
-}
-function formatOrphanSummary(orphans) {
-    const overrideCount = orphans.overrides.length;
-    const customCount = orphans.customNames.length;
-    const overrideLabel = overrideCount > 0
-        ? `${overrideCount} override${overrideCount === 1 ? '' : 's'} ` +
-            `(${orphans.overrides.map((o) => o.name).join(', ')})`
-        : '';
-    const customLabel = customCount > 0
-        ? `${customCount} custom ${customCount === 1 ? 'directory' : 'directories'} ` +
-            `(${orphans.customNames.join(', ')})`
-        : '';
-    const description = [overrideLabel, customLabel].filter(Boolean).join(' and ');
-    return `Found orphaned component ${overrideCount + customCount === 1 ? 'directory' : 'directories'} on disk: ${description}. furnace.json does not list these — a previous mutation may have lost a concurrent write.`;
-}
-function emptyOutcome() {
-    return {
-        restored: [],
-        unrecoverable: [],
-        reconciled: [],
-        deleted: [],
-        retained: [],
-        errors: [],
-    };
-}
-/**
- * Re-registers override orphans and deletes empty custom orphan directories,
- * under one furnace lock held across both.
- *
- * Two things this must not do, both of which reproduce the lost-write race the
- * check exists to clean up after:
- *
- * 1. Write back a decision made before the lock. The orphan list is computed
- *    from a config snapshot loaded well before we hold anything, so by the
- *    time we can write, a concurrent `furnace override` may have registered
- *    the same name. Writing our sidecar-reconstructed entry over it discards
- *    a live write, and a concurrent `furnace create` registering the name
- *    under `custom` would leave it in both maps, a state nothing validates.
- *    Every orphan is therefore re-checked against `freshConfig` inside the
- *    lock and skipped when it is no longer orphaned.
- * 2. Delete custom directories outside the lock. `repairCustomOrphans` runs
- *    after the lock is released, so it must not delete the directory of a
- *    name a concurrent `furnace create` has registered but not yet
- *    populated.
- */
-async function repairOrphans(projectRoot, orphans) {
-    const outcome = emptyOutcome();
-    if (orphans.overrides.length === 0 && orphans.customNames.length === 0)
-        return outcome;
-    const lockPath = getFurnaceLockPath(projectRoot);
-    // One catch covers four distinct phases. Naming the one that failed keeps
-    // the report honest. A lock timeout otherwise renders as "failed while
-    // writing furnace.json", the phase least likely to have been reached.
-    // Held in an object rather than two `let`s: the lock callback mutates them
-    // from inside a closure, and TS's control-flow analysis does not propagate
-    // that through the call, so it would narrow both to their initial literals
-    // in the catch below.
-    const progress = { phase: 'waiting for the furnace lock', persisted: false };
-    try {
-        await withFileLock(lockPath, async () => {
-            progress.phase = 'loading furnace.json under the lock';
-            const freshConfig = await loadFurnaceConfig(projectRoot);
-            repairOverridesLocked(freshConfig, orphans.overrides, outcome);
-            if (outcome.restored.length > 0) {
-                progress.phase = 'writing furnace.json';
-                await writeFurnaceConfig(projectRoot, freshConfig);
-            }
-            // From here the restore (if any) is on disk. A later failure must not
-            // report the whole repair as if it never happened.
-            progress.persisted = true;
-            progress.phase = 'cleaning custom orphan directories';
-            await deleteEmptyCustomOrphans(projectRoot, freshConfig, orphans.customNames, outcome);
-        }, {
-            onTimeoutMessage: `Timed out waiting for the furnace lock at ${lockPath}. ` +
-                'Another fireforge furnace command may be running; retry the repair once it finishes.',
-        });
-    }
-    catch (err) {
-        if (progress.persisted) {
-            outcome.errors.push(`repair failed while ${progress.phase}: ${toError(err).message}`);
-            return outcome;
-        }
-        return {
-            ...emptyOutcome(),
-            unrecoverable: outcome.unrecoverable,
-            repairError: `while ${progress.phase}: ${toError(err).message}`,
-        };
-    }
-    return outcome;
-}
-/** Override half of {@link repairOrphans}. Mutates `freshConfig` in place. */
-function repairOverridesLocked(freshConfig, orphans, outcome) {
-    for (const orphan of orphans) {
-        if (orphan.name in freshConfig.overrides || orphan.name in freshConfig.custom) {
-            // Registered while we waited for the lock, so no longer an orphan, and
-            // writing over it would either discard that write or duplicate the name
-            // across `overrides` and `custom`.
-            outcome.reconciled.push(orphan.name);
-            continue;
-        }
-        if (orphan.recoveredConfig) {
-            freshConfig.overrides[orphan.name] = orphan.recoveredConfig;
-            outcome.restored.push(orphan.name);
-        }
-        else {
-            outcome.unrecoverable.push(orphan.name);
-        }
-    }
-}
-/** Custom half of {@link repairOrphans}. Must run under the same lock. */
-async function deleteEmptyCustomOrphans(projectRoot, freshConfig, customNames, outcome) {
-    if (customNames.length === 0)
-        return;
-    const furnacePaths = getFurnacePaths(projectRoot);
-    for (const name of customNames) {
-        if (name in freshConfig.custom || name in freshConfig.overrides) {
-            // A name orphaned in both trees is reconciled once rather than once
-            // per tree. The report reads "Skipped 2 names (x, x)" otherwise.
-            if (!outcome.reconciled.includes(name))
-                outcome.reconciled.push(name);
-            continue;
-        }
-        const dir = join(furnacePaths.customDir, name);
-        let entries;
-        try {
-            entries = await readdir(dir, { withFileTypes: true });
-        }
-        catch (err) {
-            outcome.errors.push(`${name}: ${toError(err).message}`);
-            continue;
-        }
-        if (entries.length > 0) {
-            outcome.retained.push(name);
-            continue;
-        }
-        try {
-            // `rmdir`, not `rm`: `rm` without `{ recursive: true }` throws EISDIR on
-            // a directory, so on a real filesystem this branch always failed and the
-            // "deleted N empty directories" report was unreachable. `rmdir` is also
-            // the exact semantics wanted here: it refuses a non-empty directory,
-            // which keeps the emptiness check above from being the only safeguard.
-            await rmdir(dir);
-            outcome.deleted.push(name);
-        }
-        catch (err) {
-            outcome.errors.push(`${name}: ${toError(err).message}`);
-        }
-    }
-}
-export const furnaceConfigSyncCheck = {
-    name: 'Furnace config sync',
-    dependsOn: ['Furnace configuration'],
-    skipIf: (ctx) => !ctx.furnaceConfigExists || !ctx.furnaceConfig,
-    run: async (ctx) => {
-        const config = ctx.furnaceConfig;
-        if (!config)
-            return [];
-        const orphans = await collectOrphans(ctx.projectRoot, config);
-        const overrideCount = orphans.overrides.length;
-        const customCount = orphans.customNames.length;
-        if (overrideCount === 0 && customCount === 0) {
-            return ok('Furnace config sync');
-        }
-        const summary = formatOrphanSummary(orphans);
-        if (!ctx.options.repairFurnace) {
-            return warning('Furnace config sync', summary, 'Run "fireforge doctor --repair-furnace" to re-register override orphans from their override.json sidecars (custom orphans are listed for manual follow-up).');
-        }
-        const repairResult = await repairOrphans(ctx.projectRoot, orphans);
-        if (repairResult.repairError) {
-            return failure('Furnace config sync', `Repair failed ${repairResult.repairError}`, 'Fix the underlying error and retry the doctor command.');
-        }
-        const customRepair = repairResult;
-        const { restored, unrecoverable, reconciled } = repairResult;
-        const reconciledDetail = reconciled.length > 0
-            ? ` Skipped ${reconciled.length} name${reconciled.length === 1 ? '' : 's'} (${reconciled.join(', ')}) that furnace.json already listed by the time the repair held the furnace lock — a concurrent furnace command registered ${reconciled.length === 1 ? 'it' : 'them'} first.`
-            : '';
-        const restoreDetail = restored.length > 0
-            ? `Re-registered ${restored.length} override${restored.length === 1 ? '' : 's'} (${restored.join(', ')}) from their override.json sidecars.`
-            : '';
-        const unrecoverableDetail = unrecoverable.length > 0
-            ? ` Could not recover ${unrecoverable.length} override${unrecoverable.length === 1 ? '' : 's'} without a valid override.json (${unrecoverable.join(', ')}) — delete components/overrides/<name> or re-run "fireforge furnace override" to restore the entry.`
-            : '';
-        const customDetail = customRepair.deleted.length > 0
-            ? ` Deleted ${customRepair.deleted.length} empty custom orphan ${customRepair.deleted.length === 1 ? 'directory' : 'directories'} (${customRepair.deleted.join(', ')}).`
-            : '';
-        const retainedCustomDetail = customRepair.retained.length > 0
-            ? ` ${customRepair.retained.length} non-empty custom orphan ${customRepair.retained.length === 1 ? 'directory requires' : 'directories require'} manual action (${customRepair.retained.join(', ')}): re-run "fireforge furnace create" or delete components/custom/<name>/ to reconcile.`
-            : '';
-        const customErrorDetail = customRepair.errors.length > 0
-            ? ` Could not inspect or delete ${customRepair.errors.length} custom orphan ${customRepair.errors.length === 1 ? 'directory' : 'directories'} (${customRepair.errors.join('; ')}).`
-            : '';
-        return warning('Furnace config sync', `${restoreDetail}${unrecoverableDetail}${customDetail}${retainedCustomDetail}${customErrorDetail}${reconciledDetail}`.trim() ||
-            'Nothing to repair (orphans surfaced but all were already recoverable).');
-    },
-};

package/dist/src/commands/doctor-furnace-jar.d.ts

@@ -1,14 +0,0 @@
-/**
- * `doctor` check for stale furnace jar.mn registrations: a component-file
- * rename can leave the old toolkit jar.mn line pointing at the deleted file,
- * failing every build at packaging. Split out of `doctor-furnace.ts` to keep
- * that file within the line budget.
- */
-import type { DoctorCheckDefinition } from './doctor-check-core.js';
-/**
- * "Furnace jar.mn registrations" check: detect widget registration lines
- * pointing at component files that no longer exist in the workspace,
- * typically left by a rename. These break `mach build` at packaging.
- * `--repair-furnace` prunes them.
- */
-export declare const furnaceStaleJarRegistrationCheck: DoctorCheckDefinition;

package/dist/src/commands/doctor-furnace-jar.js

@@ -1,44 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * `doctor` check for stale furnace jar.mn registrations: a component-file
- * rename can leave the old toolkit jar.mn line pointing at the deleted file,
- * failing every build at packaging. Split out of `doctor-furnace.ts` to keep
- * that file within the line budget.
- */
-import { getFurnacePaths } from '../core/furnace-config.js';
-import { findStaleJarMnEntries, pruneStaleJarMnEntries } from '../core/furnace-registration.js';
-import { toError } from '../utils/errors.js';
-import { failure, ok, warning } from './doctor-check-core.js';
-/**
- * "Furnace jar.mn registrations" check: detect widget registration lines
- * pointing at component files that no longer exist in the workspace,
- * typically left by a rename. These break `mach build` at packaging.
- * `--repair-furnace` prunes them.
- */
-export const furnaceStaleJarRegistrationCheck = {
-    name: 'Furnace jar.mn registrations',
-    dependsOn: ['Furnace configuration'],
-    skipIf: (ctx) => !ctx.furnaceConfigExists || !ctx.furnaceConfig || !ctx.engineExists,
-    run: async (ctx) => {
-        const config = ctx.furnaceConfig;
-        if (!config)
-            return [];
-        const furnacePaths = getFurnacePaths(ctx.projectRoot);
-        const managedTags = Object.keys(config.custom);
-        const stale = await findStaleJarMnEntries(ctx.paths.engine, furnacePaths.customDir, managedTags);
-        if (stale.length === 0) {
-            return ok('Furnace jar.mn registrations');
-        }
-        const staleList = stale.map((entry) => `${entry.tagName}/${entry.fileName}`).join(', ');
-        if (!ctx.options.repairFurnace) {
-            return warning('Furnace jar.mn registrations', `jar.mn carries ${stale.length} registration line${stale.length === 1 ? '' : 's'} pointing at removed component file${stale.length === 1 ? '' : 's'} (${staleList}). mach build will fail at packaging ("File ... not found").`, 'Run "fireforge doctor --repair-furnace" (or "fireforge furnace validate --fix") to prune the stale lines.');
-        }
-        try {
-            const pruned = await pruneStaleJarMnEntries(ctx.paths.engine, furnacePaths.customDir, managedTags);
-            return warning('Furnace jar.mn registrations', `Pruned ${pruned.length} stale jar.mn registration line${pruned.length === 1 ? '' : 's'} (${staleList}).`);
-        }
-        catch (err) {
-            return failure('Furnace jar.mn registrations', `Could not prune stale jar.mn lines: ${toError(err).message}`, 'Remove the stale lines from toolkit/content/jar.mn manually and retry.');
-        }
-    },
-};

package/dist/src/commands/doctor-furnace.d.ts

@@ -1,8 +0,0 @@
-import type { DoctorCheckDefinition } from './doctor-check-core.js';
-/**
- * The ordered furnace check group. Exported as an array so `doctor.ts`
- * can splice it into the main registry at the right position. The order
- * here matters: `Furnace configuration` must run before the consumers
- * that read `ctx.furnaceConfig`.
- */
-export declare const FURNACE_DOCTOR_CHECKS: readonly DoctorCheckDefinition[];