@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/core/furnace-apply-ftl.d.ts

@@ -1,49 +0,0 @@
-/**
- * `.ftl` apply/undeploy helpers for custom components. Extracted from
- * `furnace-apply-helpers.ts` so the main helper module stays under the
- * per-file LOC budget.
- *
- * Every helper here degrades gracefully: if the locale jar.mn is missing or
- * the FTL tree is non-standard, apply logs an advisory `stepError`
- * (`advisory: true`) rather than aborting the whole command. Advisory step
- * errors are reported as warnings and never trigger rollback: a missing
- * jar.mn on a fork without a locale package must not block a working
- * `.mjs`/`.css` from shipping.
- */
-import type { ComponentApplyContext, CustomComponentConfig, DryRunAction, StepError } from '../types/furnace.js';
-import { type RollbackJournal } from './furnace-rollback.js';
-/**
- * Apply-path wrapper around {@link pruneSharedFtlPerWidgetLocaleEntry} that
- * records the affected path / step error in the caller's collectors, mirroring
- * {@link applyCustomFtlFile}'s contract so the main apply helper stays terse.
- */
-export declare function applySharedFtlPrune(ctx: Pick<ComponentApplyContext, 'engineDir' | 'name' | 'ftlDir'>, config: CustomComponentConfig, affectedPaths: string[], stepErrors: StepError[], rollbackJournal?: RollbackJournal): Promise<void>;
-/**
- * Read-only dry-run describer for {@link pruneSharedFtlPerWidgetLocaleEntry}:
- * returns an action when a dangling per-widget locale entry exists for a
- * `sharedFtl` widget, else `undefined`.
- */
-export declare function describeSharedFtlPrune(ctx: Pick<ComponentApplyContext, 'engineDir' | 'name' | 'ftlDir'>, config: CustomComponentConfig): Promise<DryRunAction | undefined>;
-/**
- * Copies a component's `.ftl` into the FTL tree and registers the chrome URI
- * in the locale jar.mn.
- *
- * Failure modes (missing jar.mn, regex write error) are captured as
- * stepErrors rather than thrown, since a well-formed `.mjs`/`.css` must
- * never be blocked by a broken locale path.
- */
-export declare function applyCustomFtlFile(ctx: Pick<ComponentApplyContext, 'engineDir' | 'name' | 'componentDir' | 'ftlDir'>, affectedPaths: string[], stepErrors: StepError[], rollbackJournal?: RollbackJournal): Promise<void>;
-/**
- * Returns a dry-run action for registering a locale jar.mn entry for the
- * `.ftl` that `applyCustomFtlFile` would write. `undefined` when the FTL
- * tree does not expose a locale jar.mn we can confidently name.
- */
-export declare function describeLocaleFtlJarMnRegistration(name: string, ftlDir: string, ftlFile: string): DryRunAction | undefined;
-/**
- * Drops the locale jar.mn entry for `fileName` when it's a `.ftl` whose
- * source workspace file has been deleted. Idempotent: absent entries are a
- * no-op. Early-returns for `sharedFtl` components: the shared bundle is
- * owned elsewhere, and dropping its jar.mn line on our component's delete
- * would orphan every other participant.
- */
-export declare function removeCustomFtlJarMnEntry(engineDir: string, fileName: string, ftlDir: string, config: CustomComponentConfig, rollbackJournal?: RollbackJournal): Promise<void>;

package/dist/src/core/furnace-apply-ftl.js

@@ -1,210 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * `.ftl` apply/undeploy helpers for custom components. Extracted from
- * `furnace-apply-helpers.ts` so the main helper module stays under the
- * per-file LOC budget.
- *
- * Every helper here degrades gracefully: if the locale jar.mn is missing or
- * the FTL tree is non-standard, apply logs an advisory `stepError`
- * (`advisory: true`) rather than aborting the whole command. Advisory step
- * errors are reported as warnings and never trigger rollback: a missing
- * jar.mn on a fork without a locale package must not block a working
- * `.mjs`/`.css` from shipping.
- */
-import { join, relative } from 'node:path';
-import { toError } from '../utils/errors.js';
-import { copyFile, pathExists, readText } from '../utils/fs.js';
-import { normalizePathSlashes } from '../utils/paths.js';
-import { escapeRegex } from '../utils/regex.js';
-import { resolveFtlChromeSubPath, resolveFtlLocaleJarMnPath } from './furnace-constants.js';
-import { addLocaleFtlJarMnEntry, removeLocaleFtlJarMnEntry } from './furnace-registration.js';
-import { snapshotFile } from './furnace-rollback.js';
-/**
- * Builds the presence regex for a per-widget locale jar.mn line
- * (`locale/@AB_CD@/<chromeSubPath>/<tagName>.ftl`). Shared by the prune
- * helper and its dry-run describer so both agree on what "dangling" means.
- */
-function perWidgetLocaleEntryPattern(chromeSubPath, tagName) {
-    return new RegExp(`locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapeRegex(chromeSubPath)}\\/${escapeRegex(tagName)}\\.ftl`, 'm');
-}
-/**
- * Resolves the engine-relative locale jar.mn and the per-widget entry regex
- * for a `sharedFtl` widget, or `undefined` when the FTL tree exposes no
- * locale jar.mn we can confidently name.
- */
-function resolveSharedFtlPruneTarget(name, ftlDir) {
-    const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
-    const localeJarRel = resolveFtlLocaleJarMnPath(ftlDir);
-    if (chromeSubPath === undefined || localeJarRel === undefined)
-        return undefined;
-    return { localeJarRel, pattern: perWidgetLocaleEntryPattern(chromeSubPath, name) };
-}
-/**
- * Removes a dangling per-widget locale jar.mn entry for a `sharedFtl` widget.
- *
- * A `localized: true` widget that opts into a feature-scoped `sharedFtl`
- * bundle (its strings live under `browser/...` and load via
- * `insertFTLIfNeeded`) must not carry a per-widget
- * `locale/@AB_CD@/<chromeSubPath>/<name>.ftl` line. Such a line points at a
- * `.ftl` that does not exist, so `mach build` fails hard (`Cannot find
- * <chromeSubPath>/<name>.ftl`) and blocks every build.
- *
- * The pruned line is the per-widget toolkit entry only. The shared bundle's
- * own line (a different chrome sub-path / base name) is never matched, so
- * pruning one widget cannot orphan the shared bundle. Idempotent: when no
- * dangling entry exists the file is left untouched (no journal churn).
- * Returns the engine-relative jar.mn path when a line was removed, else
- * `undefined`.
- */
-async function pruneSharedFtlPerWidgetLocaleEntry(engineDir, name, ftlDir, config, rollbackJournal) {
-    if (!config.sharedFtl)
-        return undefined;
-    const target = resolveSharedFtlPruneTarget(name, ftlDir);
-    if (!target)
-        return undefined;
-    const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
-    if (chromeSubPath === undefined)
-        return undefined;
-    const localeJarAbs = join(engineDir, target.localeJarRel);
-    if (!(await pathExists(localeJarAbs)))
-        return undefined;
-    if (!target.pattern.test(await readText(localeJarAbs)))
-        return undefined;
-    if (rollbackJournal) {
-        await snapshotFile(rollbackJournal, localeJarAbs);
-    }
-    await removeLocaleFtlJarMnEntry(engineDir, target.localeJarRel, name, chromeSubPath);
-    return target.localeJarRel;
-}
-/**
- * Apply-path wrapper around {@link pruneSharedFtlPerWidgetLocaleEntry} that
- * records the affected path / step error in the caller's collectors, mirroring
- * {@link applyCustomFtlFile}'s contract so the main apply helper stays terse.
- */
-export async function applySharedFtlPrune(ctx, config, affectedPaths, stepErrors, rollbackJournal) {
-    const { engineDir, name, ftlDir } = ctx;
-    try {
-        const prunedPath = await pruneSharedFtlPerWidgetLocaleEntry(engineDir, name, ftlDir, config, rollbackJournal);
-        if (prunedPath)
-            affectedPaths.push(prunedPath);
-    }
-    catch (error) {
-        stepErrors.push({ step: 'locale jar.mn prune', error: toError(error).message, advisory: true });
-    }
-}
-/**
- * Read-only dry-run describer for {@link pruneSharedFtlPerWidgetLocaleEntry}:
- * returns an action when a dangling per-widget locale entry exists for a
- * `sharedFtl` widget, else `undefined`.
- */
-export async function describeSharedFtlPrune(ctx, config) {
-    const { engineDir, name, ftlDir } = ctx;
-    if (!config.sharedFtl)
-        return undefined;
-    const target = resolveSharedFtlPruneTarget(name, ftlDir);
-    if (!target)
-        return undefined;
-    const localeJarAbs = join(engineDir, target.localeJarRel);
-    if (!(await pathExists(localeJarAbs)))
-        return undefined;
-    if (!target.pattern.test(await readText(localeJarAbs)))
-        return undefined;
-    return {
-        component: name,
-        action: 'register-jar',
-        description: `Remove dangling per-widget locale entry for ${name} from ${target.localeJarRel} (sharedFtl bundle owns its strings)`,
-    };
-}
-/**
- * Copies a component's `.ftl` into the FTL tree and registers the chrome URI
- * in the locale jar.mn.
- *
- * Failure modes (missing jar.mn, regex write error) are captured as
- * stepErrors rather than thrown, since a well-formed `.mjs`/`.css` must
- * never be blocked by a broken locale path.
- */
-export async function applyCustomFtlFile(ctx, affectedPaths, stepErrors, rollbackJournal) {
-    const { engineDir, name, componentDir, ftlDir } = ctx;
-    const ftlFile = `${name}.ftl`;
-    const ftlSrc = join(componentDir, ftlFile);
-    if (!(await pathExists(ftlSrc)))
-        return;
-    const ftlDest = join(engineDir, ftlDir, ftlFile);
-    if (rollbackJournal) {
-        await snapshotFile(rollbackJournal, ftlDest);
-    }
-    await copyFile(ftlSrc, ftlDest);
-    // Sibling pushes on this list are POSIX literals (`localeJarRel`). Keep
-    // the computed one in the same spelling.
-    affectedPaths.push(normalizePathSlashes(relative(engineDir, ftlDest)));
-    const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
-    const localeJarRel = resolveFtlLocaleJarMnPath(ftlDir);
-    if (chromeSubPath === undefined || localeJarRel === undefined)
-        return;
-    const localeJarAbs = join(engineDir, localeJarRel);
-    if (!(await pathExists(localeJarAbs))) {
-        stepErrors.push({
-            step: 'locale jar.mn registration',
-            error: `Locale jar.mn not found at ${localeJarRel}; component "${name}" ships without a chrome URI for ${ftlFile}. Add the file manually or set furnace.json "ftlBasePath" to a tree that owns a jar.mn.`,
-            advisory: true,
-        });
-        return;
-    }
-    try {
-        if (rollbackJournal) {
-            await snapshotFile(rollbackJournal, localeJarAbs);
-        }
-        const inserted = await addLocaleFtlJarMnEntry(engineDir, localeJarRel, name, chromeSubPath);
-        if (inserted > 0) {
-            affectedPaths.push(localeJarRel);
-        }
-    }
-    catch (error) {
-        stepErrors.push({
-            step: 'locale jar.mn registration',
-            error: toError(error).message,
-            advisory: true,
-        });
-    }
-}
-/**
- * Returns a dry-run action for registering a locale jar.mn entry for the
- * `.ftl` that `applyCustomFtlFile` would write. `undefined` when the FTL
- * tree does not expose a locale jar.mn we can confidently name.
- */
-export function describeLocaleFtlJarMnRegistration(name, ftlDir, ftlFile) {
-    const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
-    const localeJarRel = resolveFtlLocaleJarMnPath(ftlDir);
-    if (chromeSubPath === undefined || localeJarRel === undefined)
-        return undefined;
-    return {
-        component: name,
-        action: 'register-jar',
-        description: `Register ${chromeSubPath}/${ftlFile} in ${localeJarRel}`,
-    };
-}
-/**
- * Drops the locale jar.mn entry for `fileName` when it's a `.ftl` whose
- * source workspace file has been deleted. Idempotent: absent entries are a
- * no-op. Early-returns for `sharedFtl` components: the shared bundle is
- * owned elsewhere, and dropping its jar.mn line on our component's delete
- * would orphan every other participant.
- */
-export async function removeCustomFtlJarMnEntry(engineDir, fileName, ftlDir, config, rollbackJournal) {
-    if (config.sharedFtl)
-        return;
-    if (!fileName.endsWith('.ftl'))
-        return;
-    const tagName = fileName.slice(0, -'.ftl'.length);
-    const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
-    const localeJarRel = resolveFtlLocaleJarMnPath(ftlDir);
-    if (chromeSubPath === undefined || localeJarRel === undefined)
-        return;
-    const localeJarAbs = join(engineDir, localeJarRel);
-    if (!(await pathExists(localeJarAbs)))
-        return;
-    if (rollbackJournal) {
-        await snapshotFile(rollbackJournal, localeJarAbs);
-    }
-    await removeLocaleFtlJarMnEntry(engineDir, localeJarRel, tagName, chromeSubPath);
-}

package/dist/src/core/furnace-apply-helpers.d.ts

@@ -1,106 +0,0 @@
-import type { ComponentApplyContext, CustomComponentConfig, DryRunAction, OverrideComponentConfig, StepError } from '../types/furnace.js';
-import { type RollbackJournal } from './furnace-rollback.js';
-/**
- * Filter deciding which files in an override workspace directory are candidates
- * for copying into the engine. Exported so `furnace remove` can invert apply
- * using the same file set: the "files to restore" set is defined as the
- * inverse of the "files apply would have written" set.
- */
-export declare function isOverrideCopyCandidate(entryName: string, type: OverrideComponentConfig['type']): boolean;
-/** Resolves the engine destination path for a single override-managed file. */
-export declare function getOverrideEngineTargetPath(engineDir: string, config: OverrideComponentConfig, fileName: string, ftlDir: string): string;
-/**
- * Restores a single override-deployed engine file to its pristine HEAD state,
- * inverting whatever apply wrote into that path.
- *
- * Behaviour matches the per-file branch of `restoreOverrideEngineFiles` in
- * `furnace remove`: snapshot first, then either `git restore` (if the file
- * exists in HEAD) or hard-delete (if the override introduced the file). The
- * caller must guarantee `engineDir` is a git repository. This helper does
- * not re-check, because both `furnace remove` and `furnace apply` already
- * own the precondition check at their entry points and re-checking on every
- * file would balloon git invocations.
- *
- * Returns the action taken so the caller can produce accurate user-facing
- * counts (`restored` vs `removed`). `noop` means the file was neither in HEAD
- * nor on disk, which can happen when the engine was reset out-of-band. The
- * caller should treat that as a successful no-op rather than an error.
- */
-export declare function restoreOverrideFileToBaseline(engineDir: string, enginePath: string, journal: RollbackJournal): Promise<'restored' | 'removed' | 'noop'>;
-/** Computes stable checksums for the source files that define a component. */
-export declare function computeComponentChecksums(componentDir: string): Promise<Record<string, string>>;
-/**
- * Removes engine copies of files that the developer has deleted from a custom
- * component's workspace since the last apply. `.ftl` files live under the
- * shared Fluent tree (`engine/${FTL_DIR}`). Everything else lives under
- * `engine/${config.targetPath}`. Snapshots each removal into the journal so a
- * mid-apply failure can roll the engine back to its pre-undeploy state. Files
- * that are already missing from the engine are silently no-op (the engine
- * may have been reset out-of-band, and refusing here would surface a
- * confusing error in a recovery path).
- *
- * Does not touch jar.mn or customElements.js: registration churn is the
- * caller's responsibility, since it must coordinate with the new file list
- * computed by the regular apply step that follows.
- */
-export declare function undeployCustomFiles(engineDir: string, config: CustomComponentConfig, deletedFiles: string[], ftlDir: string, rollbackJournal?: RollbackJournal): Promise<string[]>;
-/**
- * Restores or removes engine copies of files that the developer has deleted
- * from an override component's workspace since the last apply. Each file is
- * routed through `restoreOverrideFileToBaseline`, which restores it from
- * HEAD if it was a Firefox baseline file or hard-deletes it if the override
- * had introduced it.
- *
- * Requires `engineDir` to be a git repository: overrides cannot be inverted
- * without git HEAD as the source of truth. The caller is expected to have
- * already validated this precondition for the apply path. We re-check here
- * so unit tests that exercise this helper directly cannot accidentally
- * silent-fail on a non-git fixture.
- */
-export declare function undeployOverrideFiles(engineDir: string, config: OverrideComponentConfig, deletedFiles: string[], ftlDir: string, rollbackJournal?: RollbackJournal): Promise<{
-    restored: string[];
-    removed: string[];
-}>;
-/** Compares current component file checksums against the previously recorded state. */
-export declare function hasComponentChanged(componentDir: string, previousChecksums: Record<string, string>, currentChecksums?: Record<string, string>): Promise<boolean>;
-/**
- * Detects whether an override component's deployed files are missing from the
- * engine or differ from the source. Used as a guard before skipping apply on a
- * checksum match, so that reset/download/manual engine edits do not leave the
- * caller with a stale "up to date" report.
- *
- * When `cachedEngineChecksums` is provided (populated on last successful apply),
- * the function computes a SHA-256 hash of the engine file and compares it
- * against the cached value. This avoids reading the full workspace source for
- * the comparison when the engine hash still matches, which is the common case
- * for projects with many components.
- */
-export declare function hasOverrideEngineDrift(ctx: Pick<ComponentApplyContext, 'engineDir' | 'componentDir' | 'ftlDir'>, config: OverrideComponentConfig, cachedEngineChecksums?: Record<string, string>): Promise<boolean>;
-/**
- * Detects whether a custom component's deployed copies, jar.mn entries, or
- * customElements.js registration are missing from the engine or out of sync.
- * Delegates to `checkRegistrationConsistency` so the oracle stays aligned with
- * the validate command.
- */
-export declare function hasCustomEngineDrift(ctx: Pick<ComponentApplyContext, 'root' | 'name' | 'componentDir' | 'ftlDir'>, config: CustomComponentConfig): Promise<boolean>;
-/** Extra knobs threaded into `applyCustomComponent` from the project config. */
-export interface CustomApplyOptions {
-    /**
-     * Trailing project marker appended to inserted `customElements.js` entries
-     * (e.g. `"MYBROWSER"` emits `  // MYBROWSER:` on each line). Mirrors the
-     * `markerComment` field in fireforge.json.
-     */
-    markerComment?: string;
-}
-/** Applies a custom component into the engine tree and captures registration step errors. */
-export declare function applyCustomComponent(ctx: Pick<ComponentApplyContext, 'engineDir' | 'name' | 'componentDir' | 'ftlDir'>, config: CustomComponentConfig, dryRun?: boolean, rollbackJournal?: RollbackJournal, applyOptions?: CustomApplyOptions): Promise<{
-    affectedPaths: string[];
-    stepErrors: StepError[];
-    actions?: DryRunAction[];
-}>;
-/** Applies an override component by copying its matching files onto the engine tree. */
-export declare function applyOverrideComponent(ctx: Pick<ComponentApplyContext, 'engineDir' | 'name' | 'componentDir' | 'ftlDir'>, config: OverrideComponentConfig, dryRun?: boolean, rollbackJournal?: RollbackJournal): Promise<{
-    affectedPaths: string[];
-    actions?: DryRunAction[];
-}>;
-export { diffDeletedFiles, extractComponentChecksums, prefixChecksums, } from './furnace-checksum-utils.js';