@hominis/fireforge 0.31.0 → 0.33.0

package/dist/src/core/furnace-apply-dry-run.js

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Dry-run action planning for custom-component apply. Extracted from
+ * `furnace-apply-helpers.ts` so the apply path and its dry-run mirror each
+ * stay within the per-file line budget. Consumed only by that module.
+ */
+import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { pathExists } from '../utils/fs.js';
+import { describeLocaleFtlJarMnRegistration, describeSharedFtlPrune } from './furnace-apply-ftl.js';
+import { describeFragmentExpansion } from './furnace-css-fragments.js';
+import { validateCustomElementRegistration, validateJarMnInsertionForFiles, } from './furnace-registration.js';
+function isRegularFile(entry) {
+    if (!entry.isFile())
+        return false;
+    if (typeof entry.isSymbolicLink === 'function' && entry.isSymbolicLink())
+        return false;
+    return true;
+}
+/** Computes the planned dry-run actions (and pre-flight step errors) for a custom component. */
+export async function buildCustomDryRunActions(name, componentDir, engineDir, config, targetDir, entries, ftlDir) {
+    const actions = [];
+    const stepErrors = [];
+    for (const entry of entries) {
+        if (!isRegularFile(entry))
+            continue;
+        if (!entry.name.endsWith('.mjs') && !entry.name.endsWith('.css'))
+            continue;
+        const fragmentNote = await describeFragmentExpansion(join(componentDir, entry.name));
+        actions.push({
+            component: name,
+            action: fragmentNote ? 'expand-fragments' : 'copy',
+            source: join(componentDir, entry.name),
+            target: join(targetDir, entry.name),
+            description: `Copy ${entry.name} to ${config.targetPath}${fragmentNote}`,
+        });
+    }
+    // Per-component .ftl handling is skipped when the component opts into a
+    // shared feature-scoped bundle via `sharedFtl`. The shared file is
+    // registered (and copied) by whoever owns the feature bundle, so
+    // emitting a copy-ftl / register-jar action here would duplicate (or
+    // later orphan) the entry.
+    if (config.localized && !config.sharedFtl) {
+        const ftlFile = `${name}.ftl`;
+        const ftlSrc = join(componentDir, ftlFile);
+        if (await pathExists(ftlSrc)) {
+            actions.push({
+                component: name,
+                action: 'copy-ftl',
+                source: ftlSrc,
+                target: join(engineDir, ftlDir, ftlFile),
+                description: `Copy ${ftlFile} to ${ftlDir}`,
+            });
+            const localeAction = describeLocaleFtlJarMnRegistration(name, ftlDir, ftlFile);
+            if (localeAction) {
+                actions.push(localeAction);
+            }
+        }
+    }
+    // A sharedFtl widget owns its strings via the shared bundle; surface the
+    // removal of any dangling per-widget locale jar.mn entry so the dry-run
+    // plan matches what apply will do (and explains the unblocked build).
+    const pruneAction = await describeSharedFtlPrune(engineDir, name, ftlDir, config);
+    if (pruneAction) {
+        actions.push(pruneAction);
+    }
+    if (config.register) {
+        try {
+            const modulePath = `chrome://global/content/elements/${name}.mjs`;
+            await validateCustomElementRegistration(engineDir, name, modulePath);
+        }
+        catch (error) {
+            stepErrors.push({
+                step: 'customElements.js registration',
+                error: toError(error).message,
+            });
+        }
+        actions.push({
+            component: name,
+            action: 'register-ce',
+            description: `Register ${name} in customElements.js (DOMContentLoaded block)`,
+        });
+    }
+    const copiedFileNames = entries
+        .filter((entry) => isRegularFile(entry) && (entry.name.endsWith('.mjs') || entry.name.endsWith('.css')))
+        .map((entry) => entry.name);
+    if (copiedFileNames.length > 0) {
+        try {
+            await validateJarMnInsertionForFiles(engineDir, name, copiedFileNames);
+        }
+        catch (error) {
+            stepErrors.push({
+                step: 'jar.mn registration',
+                error: toError(error).message,
+            });
+        }
+        actions.push({
+            component: name,
+            action: 'register-jar',
+            description: `Add ${copiedFileNames.join(', ')} to jar.mn`,
+        });
+    }
+    return { actions, stepErrors };
+}
+//# sourceMappingURL=furnace-apply-dry-run.js.map

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

@@ -10,6 +10,18 @@
  */
 import type { 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(engineDir: string, name: string, ftlDir: string, 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(engineDir: string, name: string, ftlDir: string, config: CustomComponentConfig): Promise<DryRunAction | undefined>;
 /**
  * Copies a component's `.ftl` into the FTL tree and registers the chrome URI
  * in the locale jar.mn.

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

@@ -11,10 +11,106 @@
  */
 import { join, relative } from 'node:path';
 import { toError } from '../utils/errors.js';
-import { copyFile, pathExists } from '../utils/fs.js';
+import { copyFile, pathExists, readText } from '../utils/fs.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 — written by
+ * an older FireForge before the sharedFtl apply guard, or by a layout
+ * migration — 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(engineDir, name, ftlDir, config, affectedPaths, stepErrors, rollbackJournal) {
+    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 });
+    }
+}
+/**
+ * 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(engineDir, name, ftlDir, config) {
+    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.

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

@@ -6,10 +6,11 @@ import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { copyFile, ensureDir, pathExists, readText, removeFile } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
-import { applyCustomFtlFile, describeLocaleFtlJarMnRegistration, removeCustomFtlJarMnEntry, } from './furnace-apply-ftl.js';
+import { buildCustomDryRunActions } from './furnace-apply-dry-run.js';
+import { applyCustomFtlFile, applySharedFtlPrune, removeCustomFtlJarMnEntry, } from './furnace-apply-ftl.js';
 import { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
-import { deployFileWithFragments, describeFragmentExpansion, SHARED_FRAGMENTS_DIR, } from './furnace-css-fragments.js';
-import { addCustomElementRegistration, addJarMnEntries, validateCustomElementRegistration, validateJarMnInsertionForFiles, } from './furnace-registration.js';
+import { deployFileWithFragments, SHARED_FRAGMENTS_DIR } from './furnace-css-fragments.js';
+import { addCustomElementRegistration, addJarMnEntries } from './furnace-registration.js';
 import { recordCreatedDir, snapshotFile } from './furnace-rollback.js';
 import { checkRegistrationConsistency } from './furnace-validate-registration.js';
 import { isGitRepository } from './git.js';
@@ -278,83 +279,6 @@ export async function hasCustomEngineDrift(root, name, componentDir, config, ftl
     }
     return false;
 }
-async function buildCustomDryRunActions(name, componentDir, engineDir, config, targetDir, entries, ftlDir) {
-    const actions = [];
-    const stepErrors = [];
-    for (const entry of entries) {
-        if (!isRegularFile(entry))
-            continue;
-        if (!entry.name.endsWith('.mjs') && !entry.name.endsWith('.css'))
-            continue;
-        const fragmentNote = await describeFragmentExpansion(join(componentDir, entry.name));
-        actions.push({
-            component: name,
-            action: fragmentNote ? 'expand-fragments' : 'copy',
-            source: join(componentDir, entry.name),
-            target: join(targetDir, entry.name),
-            description: `Copy ${entry.name} to ${config.targetPath}${fragmentNote}`,
-        });
-    }
-    // Per-component .ftl handling is skipped when the component opts into a
-    // shared feature-scoped bundle via `sharedFtl`. The shared file is
-    // registered (and copied) by whoever owns the feature bundle, so
-    // emitting a copy-ftl / register-jar action here would duplicate (or
-    // later orphan) the entry.
-    if (config.localized && !config.sharedFtl) {
-        const ftlFile = `${name}.ftl`;
-        const ftlSrc = join(componentDir, ftlFile);
-        if (await pathExists(ftlSrc)) {
-            actions.push({
-                component: name,
-                action: 'copy-ftl',
-                source: ftlSrc,
-                target: join(engineDir, ftlDir, ftlFile),
-                description: `Copy ${ftlFile} to ${ftlDir}`,
-            });
-            const localeAction = describeLocaleFtlJarMnRegistration(name, ftlDir, ftlFile);
-            if (localeAction) {
-                actions.push(localeAction);
-            }
-        }
-    }
-    if (config.register) {
-        try {
-            const modulePath = `chrome://global/content/elements/${name}.mjs`;
-            await validateCustomElementRegistration(engineDir, name, modulePath);
-        }
-        catch (error) {
-            stepErrors.push({
-                step: 'customElements.js registration',
-                error: toError(error).message,
-            });
-        }
-        actions.push({
-            component: name,
-            action: 'register-ce',
-            description: `Register ${name} in customElements.js (DOMContentLoaded block)`,
-        });
-    }
-    const copiedFileNames = entries
-        .filter((entry) => isRegularFile(entry) && (entry.name.endsWith('.mjs') || entry.name.endsWith('.css')))
-        .map((entry) => entry.name);
-    if (copiedFileNames.length > 0) {
-        try {
-            await validateJarMnInsertionForFiles(engineDir, name, copiedFileNames);
-        }
-        catch (error) {
-            stepErrors.push({
-                step: 'jar.mn registration',
-                error: toError(error).message,
-            });
-        }
-        actions.push({
-            component: name,
-            action: 'register-jar',
-            description: `Add ${copiedFileNames.join(', ')} to jar.mn`,
-        });
-    }
-    return { actions, stepErrors };
-}
 /** Applies a custom component into the engine tree and captures registration step errors. */
 export async function applyCustomComponent(engineDir, name, componentDir, config, ftlDir, dryRun = false, rollbackJournal, applyOptions = {}) {
     if (!/^[a-z][a-z0-9-]*$/.test(name)) {
@@ -406,6 +330,12 @@ export async function applyCustomComponent(engineDir, name, componentDir, config
     if (config.localized && !config.sharedFtl) {
         await applyCustomFtlFile(engineDir, name, componentDir, ftlDir, affectedPaths, stepErrors, rollbackJournal);
     }
+    else if (config.localized && config.sharedFtl) {
+        // Drop any dangling per-widget locale jar.mn entry that would point at a
+        // non-existent `<chromeSubPath>/<name>.ftl` and fail `mach build`. The
+        // shared bundle (a different chrome path/base name) is never touched.
+        await applySharedFtlPrune(engineDir, name, ftlDir, config, affectedPaths, stepErrors, rollbackJournal);
+    }
     if (config.register) {
         try {
             const modulePath = `chrome://global/content/elements/${name}.mjs`;

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

@@ -51,12 +51,28 @@ async function computeDesiredChromePathEntries(config, customDir, jsconfigAbsPat
         for (const file of files.sort()) {
             if (!file.endsWith('.mjs'))
                 continue;
-            const sourcePath = normalizePathSlashes(relative(jsconfigDir, join(componentDir, file)));
+            // Emit a `./`-prefixed relative value. TypeScript treats a bare
+            // `paths` value (`moz-widget/moz-widget.mjs`) as non-relative and
+            // rejects it without `baseUrl` (TS5090); a `./`-prefixed value
+            // resolves against the jsconfig directory with no `baseUrl` (which
+            // TS6 deprecates, TS5101). `../`-prefixed paths are already relative
+            // and left untouched.
+            const rel = normalizePathSlashes(relative(jsconfigDir, join(componentDir, file)));
+            const sourcePath = rel.startsWith('.') ? rel : `./${rel}`;
             entries[`${CHROME_ELEMENTS_URL_PREFIX}${file}`] = [sourcePath];
         }
     }
     return entries;
 }
+/**
+ * Compares two `paths` values treating a leading `./` as insignificant, so
+ * the reconciler does not churn between `./x` and bare `x` forms (either
+ * direction). Used to decide whether a managed entry is stale.
+ */
+function samePathValue(a, b) {
+    const strip = (p) => (p.startsWith('./') ? p.slice(2) : p);
+    return strip(a) === strip(b);
+}
 /** True when `key`/`value` is a Furnace-managed chrome-elements mapping. */
 function isManagedEntry(key, value, jsconfigDir, customDir) {
     if (!key.startsWith(CHROME_ELEMENTS_URL_PREFIX))
@@ -119,7 +135,11 @@ export async function syncFurnaceJsconfigPaths(root, config, options) {
             result.pruned.push(key);
             continue;
         }
-        if (value[0] !== want[0]) {
+        // Treat `./x` and bare `x` as equal so a previously-synced bare value (or
+        // a hand-written `./` prefix) is not rewritten as "stale" on every run.
+        // The existing value is kept verbatim when equivalent — no churn either
+        // way; only a genuinely different target updates (to the `./` form).
+        if (!samePathValue(value[0] ?? '', want[0] ?? '')) {
             result.updated.push(key);
             nextPaths[key] = want;
         }

package/dist/src/core/git-base.d.ts

@@ -63,6 +63,21 @@ export declare function git(args: string[], cwd: string, options?: {
     timeout?: number;
     env?: Record<string, string>;
 }): Promise<string>;
+/**
+ * Splits a pathspec list into chunks whose joined byte length stays well under
+ * the OS `ARG_MAX` limit, so a single batched `git` invocation over hundreds of
+ * Mozilla-length paths cannot fail with `E2BIG`. The 96 KB budget is
+ * deliberately conservative — even the smallest historical `ARG_MAX` (256 KB)
+ * leaves room for the fixed git arguments plus the inherited environment.
+ *
+ * Chunk boundaries are output-neutral for every batched caller here: each
+ * caller merges the per-chunk results into a single Set/Map keyed by path, so
+ * how the paths are grouped across invocations never affects the result.
+ * @param paths - Pathspecs to chunk
+ * @param budgetBytes - Maximum joined byte length per chunk
+ * @returns Path chunks, each safe to pass as a single argv tail
+ */
+export declare function chunkPathspecs(paths: string[], budgetBytes?: number): string[][];
 /**
  * Configures git performance settings for large trees.
  * Enables index preloading, untracked cache, and the manyFiles feature

package/dist/src/core/git-base.js

@@ -72,6 +72,38 @@ export async function git(args, cwd, options) {
     }
     return result.stdout;
 }
+/**
+ * Splits a pathspec list into chunks whose joined byte length stays well under
+ * the OS `ARG_MAX` limit, so a single batched `git` invocation over hundreds of
+ * Mozilla-length paths cannot fail with `E2BIG`. The 96 KB budget is
+ * deliberately conservative — even the smallest historical `ARG_MAX` (256 KB)
+ * leaves room for the fixed git arguments plus the inherited environment.
+ *
+ * Chunk boundaries are output-neutral for every batched caller here: each
+ * caller merges the per-chunk results into a single Set/Map keyed by path, so
+ * how the paths are grouped across invocations never affects the result.
+ * @param paths - Pathspecs to chunk
+ * @param budgetBytes - Maximum joined byte length per chunk
+ * @returns Path chunks, each safe to pass as a single argv tail
+ */
+export function chunkPathspecs(paths, budgetBytes = 96_000) {
+    const chunks = [];
+    let current = [];
+    let used = 0;
+    for (const path of paths) {
+        const cost = Buffer.byteLength(path) + 1;
+        if (current.length > 0 && used + cost > budgetBytes) {
+            chunks.push(current);
+            current = [];
+            used = 0;
+        }
+        current.push(path);
+        used += cost;
+    }
+    if (current.length > 0)
+        chunks.push(current);
+    return chunks;
+}
 /**
  * Configures git performance settings for large trees.
  * Enables index preloading, untracked cache, and the manyFiles feature

package/dist/src/core/git-diff.d.ts

@@ -40,6 +40,14 @@ export declare function getAllDiff(repoDir: string): Promise<string>;
  * Builds a combined diff against HEAD for the provided files without touching
  * the real git index. Tracked files use `git diff HEAD`; untracked files use
  * synthesized new-file diffs.
+ *
+ * Performance: the work is batched into a handful of `git` invocations
+ * (one `ls-tree` to classify, one `diff` over all tracked files, one
+ * `hash-object` over all new text files) rather than the ~2 spawns per file the
+ * previous per-file loop issued — that fan-out dominated the cold-run cost on a
+ * Firefox-sized checkout (~700 serial spawns, ~99s). Binary, directory, and
+ * recursion paths stay per-file because they are rare and (for binary) mutate
+ * the index.
  * @param repoDir - Repository directory
  * @param files - File paths to diff (relative to repo root)
  * @returns Combined diff content