@hominis/fireforge 0.15.6 → 0.15.8

package/dist/src/core/build-audit-registration.js

@@ -0,0 +1,187 @@
+// SPDX-License-Identifier: EUPL-1.2
+/*
+ * Registration-aware artifact resolution for the post-build dist-tree audit.
+ *
+ * The basename-plus-similarity heuristic in `build-audit-resolve.ts` cannot
+ * distinguish two unrelated files that share a source basename. Motivating
+ * case: one fork registers `content/mybrowser.js` in `browser/base/jar.mn`
+ * (packaged under `chrome/browser/content/browser/mybrowser.js`) while an
+ * unrelated patch registers a `mybrowser.js` pref file under
+ * `browser/defaults/preferences/`. The basename walker surfaces both
+ * candidates, `scoreCandidate` awards them an equal trailing-overlap score
+ * (basename only, no meaningful mid-path match), and whichever the
+ * directory walk hits first wins — frequently the wrong one.
+ *
+ * This module anchors resolution to the `(source)` reference inside
+ * `jar.mn`. For a source under audit we walk its ancestor directories for
+ * an owning `jar.mn`, find the entry whose `(source)` resolves to our
+ * path, and expose both the target path recorded in the entry and the
+ * manifest that owns it. Callers in `build-audit.ts` prefer candidates
+ * whose absolute dist-tree path ends with the registered target, and
+ * report an unambiguous "registered but not packaged" miss when no such
+ * candidate exists — rather than falling through to the heuristic which
+ * would pick an unrelated same-basename file.
+ *
+ * Fallback semantics: when no jar.mn registration is found, the caller
+ * is expected to use the similarity heuristic. Registration wins when it
+ * exists; the heuristic fills the gap for sources registered through
+ * moz.build (`FINAL_TARGET_FILES`, `JS_PREFERENCE_FILES`, etc.) or
+ * `package-manifest.in` entries, which this module intentionally does
+ * not parse — supporting every Firefox registration surface would bloat
+ * the audit, and the heuristic's remaining weak case (unrelated same-
+ * basename hits) is surfaced to the operator in the warning copy.
+ */
+import { basename, dirname, join, relative, sep } from 'node:path';
+import { pathExists, readText } from '../utils/fs.js';
+import { findAllByBasename } from './build-audit-resolve.js';
+/** Ceiling on ancestor-directory hops when searching for an owning jar.mn. */
+const MAX_JAR_MN_SCAN_DEPTH = 8;
+/**
+ * Parses a single jar.mn line into `{ target, source }` when the line is a
+ * content entry with an explicit `(source)` reference. Returns undefined
+ * for comments, headers (`browser.jar:`), `%` manifest directives, blank
+ * lines, and entries without a source reference.
+ *
+ * Accepted entry shapes:
+ *   `        content/browser/foo.js     (content/foo.js)`   bare
+ *   `*       content/browser/foo.js     (content/foo.js)`   `*` = preprocessed
+ *   `en-US.jar:        content/foo.js  (content/foo.js)`    locale-prefixed
+ */
+export function parseJarMnEntry(line) {
+    if (!line)
+        return undefined;
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#') || trimmed.startsWith('%'))
+        return undefined;
+    // Leading `*` (preprocessed) and optional `locale.jar:` prefix are dropped
+    // before matching the target/(source) pair. Both are whitespace-separated
+    // from the target entry.
+    const stripped = trimmed.replace(/^\*\s+/, '').replace(/^[A-Za-z0-9.\-_]+\.jar:\s+/, '');
+    const match = /^(\S+)\s+\(([^)]+)\)\s*$/.exec(stripped);
+    if (!match)
+        return undefined;
+    const target = (match[1] ?? '').trim();
+    const source = (match[2] ?? '').trim();
+    if (!target || !source)
+        return undefined;
+    return { target, source };
+}
+/**
+ * Scans a jar.mn file's contents for an entry whose source reference
+ * matches `relativeSource` (POSIX, relative to the jar.mn directory).
+ * Returns the first match; jar.mn enforces uniqueness of `(source)` in
+ * practice, so a first-match wins behaviour is adequate.
+ */
+export function findJarMnEntryForSource(content, relativeSource) {
+    const normalized = relativeSource.replace(/\\/g, '/');
+    for (const line of content.split('\n')) {
+        const parsed = parseJarMnEntry(line);
+        if (!parsed)
+            continue;
+        if (parsed.source === normalized)
+            return parsed;
+    }
+    return undefined;
+}
+/**
+ * Walks from the source's directory upward to the engine root, returning
+ * the first jar.mn entry that registers the given source. Returns undefined
+ * when no ancestor jar.mn claims the source.
+ *
+ * @param engineDir Absolute engine root; walk halts here.
+ * @param source Engine-relative POSIX source path.
+ */
+export async function findRegisteredTarget(engineDir, source) {
+    const sourceAbs = join(engineDir, source);
+    const root = engineDir.replace(/[/\\]+$/, '');
+    let current = dirname(sourceAbs);
+    let depth = 0;
+    while (depth <= MAX_JAR_MN_SCAN_DEPTH &&
+        (current === root || current.startsWith(`${root}/`) || current.startsWith(`${root}\\`))) {
+        const jarMn = join(current, 'jar.mn');
+        if (await pathExists(jarMn)) {
+            let content;
+            try {
+                content = await readText(jarMn);
+            }
+            catch {
+                content = '';
+            }
+            const rel = relative(current, sourceAbs).split(sep).join('/');
+            const entry = findJarMnEntryForSource(content, rel);
+            if (entry) {
+                return { target: entry.target, source: entry.source, jarManifest: jarMn };
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+        depth += 1;
+    }
+    return undefined;
+}
+/**
+ * Normalises an absolute filesystem path to POSIX separators so the
+ * suffix comparison against a jar.mn target (always POSIX) is platform-
+ * independent.
+ */
+function toPosix(path) {
+    return path.split(sep).join('/');
+}
+/**
+ * Probes the dist tree for the artifact registered against the given
+ * source. Returns the matched candidate and the registration hit that
+ * anchored it; undefined when the source has no owning jar.mn or when
+ * no same-basename candidate under the search roots ends with the
+ * registered target path.
+ *
+ * Suffix-matching against the target path is intentional: jar.mn targets
+ * are relative to the jar root (`browser.jar:`, `toolkit.jar:`), but the
+ * dist tree prefixes every entry with a jar-specific directory
+ * (`.../chrome/browser/content/browser/…`). The source basename plus the
+ * target suffix are unambiguous across every packaging convention we
+ * care about.
+ *
+ * @param engineDir Absolute engine root.
+ * @param source Engine-relative POSIX source path.
+ * @param searchRoots Absolute roots to probe (dist/, _tests/).
+ */
+export async function resolveArtifactByRegistration(engineDir, source, searchRoots) {
+    const hit = await findRegisteredTarget(engineDir, source);
+    if (!hit)
+        return undefined;
+    const name = basename(source);
+    const targetSuffix = `/${hit.target.replace(/^\/+/, '')}`;
+    const candidates = [];
+    for (const root of searchRoots) {
+        const found = await findAllByBasename(root, name);
+        candidates.push(...found);
+    }
+    for (const candidate of candidates) {
+        if (toPosix(candidate).endsWith(targetSuffix)) {
+            return { artifact: candidate, hit };
+        }
+    }
+    return undefined;
+}
+/**
+ * Returns the absolute paths of every same-basename candidate under the
+ * given search roots. Used by the audit to enumerate ALL false-match
+ * candidates when the heuristic fallback downgrades to "missing" — the
+ * operator needs to see the full set, not just the scorer's pick, to
+ * distinguish a registration bug from a genuine packaging drop.
+ *
+ * @param source Engine-relative POSIX source path.
+ * @param searchRoots Absolute roots to scan.
+ */
+export async function collectSameBasenameCandidates(source, searchRoots) {
+    const name = basename(source);
+    const out = [];
+    for (const root of searchRoots) {
+        const found = await findAllByBasename(root, name);
+        out.push(...found);
+    }
+    return out;
+}
+//# sourceMappingURL=build-audit-registration.js.map

package/dist/src/core/build-audit-transforms.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Returns the expected chrome-tree suffix for an engine-relative POSIX
+ * source path when the path falls under a known transform prefix;
+ * undefined otherwise.
+ *
+ * @param source Engine-relative POSIX source path.
+ */
+export declare function expectedChromeSuffix(source: string): string | undefined;
+/**
+ * Probes the dist tree for the artifact implied by a known
+ * source→chrome transform. Returns the first absolute candidate whose
+ * POSIX path ends with the expected chrome suffix, or undefined when
+ * no transform applies or no candidate matches.
+ *
+ * The transform check is treated as high-confidence by `build-audit.ts`
+ * (callers pass `{ registered: true }` to `evaluateArtifactMtime`), so
+ * a match bypasses the structural-relation check that rejects generic
+ * basename collisions.
+ *
+ * @param source Engine-relative POSIX source path.
+ * @param searchRoots Absolute roots to probe (dist/, _tests/).
+ */
+export declare function resolveArtifactByKnownTransform(source: string, searchRoots: readonly string[]): Promise<string | undefined>;

package/dist/src/core/build-audit-transforms.js

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: EUPL-1.2
+/*
+ * Known source→packaging path transforms for the post-build dist-tree audit.
+ *
+ * Motivating case: a source at `engine/browser/base/content/foo.js` ships
+ * under `chrome/browser/content/browser/foo.js`. If an unrelated patch
+ * registers a different `foo.js` elsewhere in the tree (e.g. a pref file
+ * under `browser/defaults/preferences/foo.js`), the basename walker
+ * surfaces both candidates, `scoreCandidate` awards them an identical
+ * trailing-overlap score (basename only; every intermediate segment is
+ * in the generic list), and whichever the directory walk hits first wins.
+ * The heuristic then declares the chosen candidate "not structurally
+ * related" and reports the correctly-packaged chrome resource as missing.
+ *
+ * The transforms below anchor resolution to the well-known subtree→chrome
+ * conventions used by upstream mozilla-central jar.mn. When a source
+ * matches one of these prefixes, a candidate whose absolute path ends
+ * with the implied chrome suffix is treated as a confident match — the
+ * scorer never runs and the structural-relation check is bypassed.
+ *
+ * Scope is intentionally narrow: only subtrees whose packaging target is
+ * stable across every fork we know about. A fork that reroutes a known
+ * subtree can still win by adding `(source)` annotations in its own
+ * `jar.mn`, which `resolveArtifactByRegistration` consults first.
+ */
+import { basename, sep } from 'node:path';
+import { findAllByBasename } from './build-audit-resolve.js';
+/**
+ * Table of `prefix → chrome-suffix` transforms. Each rule names an
+ * engine-relative subtree prefix and produces the expected dist-tree
+ * suffix for a file under it. Rules are evaluated in array order and
+ * the first-matching prefix wins, so `toolkit/content/widgets/` must
+ * precede the looser `toolkit/content/`.
+ */
+const KNOWN_TRANSFORMS = [
+    {
+        prefix: 'browser/base/content/',
+        build: (rest) => `chrome/browser/content/browser/${rest}`,
+    },
+    {
+        prefix: 'toolkit/content/widgets/',
+        build: (rest) => `chrome/toolkit/content/global/elements/${rest}`,
+    },
+    {
+        prefix: 'toolkit/content/',
+        build: (rest) => `chrome/toolkit/content/global/${rest}`,
+    },
+];
+/**
+ * Returns the expected chrome-tree suffix for an engine-relative POSIX
+ * source path when the path falls under a known transform prefix;
+ * undefined otherwise.
+ *
+ * @param source Engine-relative POSIX source path.
+ */
+export function expectedChromeSuffix(source) {
+    for (const rule of KNOWN_TRANSFORMS) {
+        if (source.startsWith(rule.prefix)) {
+            return rule.build(source.slice(rule.prefix.length));
+        }
+    }
+    return undefined;
+}
+/**
+ * Probes the dist tree for the artifact implied by a known
+ * source→chrome transform. Returns the first absolute candidate whose
+ * POSIX path ends with the expected chrome suffix, or undefined when
+ * no transform applies or no candidate matches.
+ *
+ * The transform check is treated as high-confidence by `build-audit.ts`
+ * (callers pass `{ registered: true }` to `evaluateArtifactMtime`), so
+ * a match bypasses the structural-relation check that rejects generic
+ * basename collisions.
+ *
+ * @param source Engine-relative POSIX source path.
+ * @param searchRoots Absolute roots to probe (dist/, _tests/).
+ */
+export async function resolveArtifactByKnownTransform(source, searchRoots) {
+    const suffix = expectedChromeSuffix(source);
+    if (!suffix)
+        return undefined;
+    const name = basename(source);
+    const suffixWithSlash = `/${suffix}`;
+    for (const root of searchRoots) {
+        const candidates = await findAllByBasename(root, name);
+        for (const candidate of candidates) {
+            if (candidate.split(sep).join('/').endsWith(suffixWithSlash)) {
+                return candidate;
+            }
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=build-audit-transforms.js.map

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

@@ -39,7 +39,9 @@ import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, verbose, warn } from '../utils/logger.js';
 import { detectPlatformGate } from './build-audit-platform.js';
+import { collectSameBasenameCandidates, findRegisteredTarget, resolveArtifactByRegistration, } from './build-audit-registration.js';
 import { countTrailingSegmentMatches, isTestPath, resolveBestArtifact, } from './build-audit-resolve.js';
+import { resolveArtifactByKnownTransform } from './build-audit-transforms.js';
 import { hasChanges, isMissingHeadError } from './git.js';
 import { git } from './git-base.js';
 import { getUntrackedFiles } from './git-status.js';
@@ -317,6 +319,40 @@ async function auditSinglePath(source, ctx) {
         return { source, artifact: undefined, status: 'skipped' };
     }
     const roots = searchRootsFor(source, ctx.distRoot, ctx.testsRoot);
+    // Registration-aware resolution first: a `jar.mn` entry whose `(source)`
+    // references this file is authoritative over the basename-similarity
+    // heuristic. The motivating case is a fork that adds `content/foo.js`
+    // in `browser/base/jar.mn` while an unrelated patch registers a pref
+    // file of the same basename elsewhere — the heuristic cannot
+    // distinguish them, so the audit falsely reports "missing" against the
+    // correctly-packaged file.
+    const registered = await resolveArtifactByRegistration(ctx.engineDir, source, roots);
+    if (registered) {
+        return evaluateArtifactMtime(source, registered.artifact, sourceMtime, { registered: true });
+    }
+    // Registration exists but no matching dist entry: explicit miss,
+    // distinct from an unregistered source. This surfaces in the warning so
+    // the operator knows the jar.mn entry is intact and packaging is the
+    // bug, not the source registration.
+    const registrationMissed = await reportRegistrationMiss(ctx.engineDir, source, roots);
+    if (registrationMissed)
+        return registrationMissed;
+    // Known-transform resolution comes before the similarity heuristic so a
+    // source under `browser/base/content/` (or another prefix whose chrome
+    // target is stable across forks) is matched against its expected
+    // `chrome/...` suffix rather than whichever same-basename candidate the
+    // directory walk happened to hit first. Motivating case: a source at
+    // `engine/browser/base/content/foo.js` whose correctly-packaged artifact
+    // lives at `chrome/browser/content/browser/foo.js` but which an unrelated
+    // patch also placed under `browser/defaults/preferences/foo.js`; every
+    // intermediate segment of the source is in the scorer's generic list,
+    // so `resolveBestArtifact` picks whichever hit first and `isConfidentMatch`
+    // rejects every candidate, classifying the correctly-packaged file as
+    // "missing" even though packaging had landed it.
+    const byTransform = await resolveArtifactByKnownTransform(source, roots);
+    if (byTransform) {
+        return evaluateArtifactMtime(source, byTransform, sourceMtime, { registered: true });
+    }
     const artifact = await resolveBestArtifact(source, roots);
     if (!artifact) {
         const where = isTestPath(source) ? '_tests/' : 'dist/';
@@ -327,6 +363,42 @@ async function auditSinglePath(source, ctx) {
             warning: `Audit: engine/${source} was touched but no packaged artifact with basename "${basename(source)}" was found under ${where}. Missing moz.build / jar.mn / package-manifest.in registration?`,
         };
     }
+    return evaluateArtifactMtime(source, artifact, sourceMtime, { registered: false, roots });
+}
+/**
+ * Short-circuits the audit for sources that are registered in a jar.mn
+ * but whose target path is absent from every search root. Returns the
+ * miss entry when the registration lookup saw a `(source)` claim but
+ * no dist candidate endswith the target; undefined otherwise.
+ */
+async function reportRegistrationMiss(engineDir, source, roots) {
+    const hit = await findRegisteredTarget(engineDir, source);
+    if (!hit)
+        return undefined;
+    const where = isTestPath(source) ? '_tests/' : 'dist/';
+    // Name every same-basename hit so the operator sees what did land in
+    // dist, rather than guessing from a single "nearest" pick.
+    const candidates = await collectSameBasenameCandidates(source, roots);
+    const nearHits = describeCandidates(candidates);
+    const manifest = relativeManifestPath(engineDir, hit.jarManifest);
+    return {
+        source,
+        artifact: undefined,
+        status: 'missing',
+        warning: `Audit: engine/${source} is registered in ${manifest} as ` +
+            `"${hit.target}  (${hit.source})" but no packaged artifact ending in "/${hit.target}" ` +
+            `was found under ${where}. Build reported success but the file's path did not ` +
+            `flow through packaging${nearHits ? ` — same-basename hits: ${nearHits}` : ''}.`,
+    };
+}
+/**
+ * Renders packaged-artifact mtime classification (updated / stale / missing-
+ * via-disappearance) for a resolved candidate. Shared by the registration-
+ * anchored path (confident by construction) and the heuristic fallback
+ * (which still applies the structural-relatedness check before claiming
+ * `stale`).
+ */
+async function evaluateArtifactMtime(source, artifact, sourceMtime, mode) {
     let artifactMtime;
     try {
         const artifactStat = await stat(artifact);
@@ -341,18 +413,18 @@ async function auditSinglePath(source, ctx) {
         };
     }
     if (artifactMtime + 1 < sourceMtime) {
-        // Before claiming "stale", verify the match is structurally related.
-        // A same-basename hit in an unrelated subtree (e.g. `head.js` in a
-        // completely different upstream test helper) should be reported as
-        // missing — the operator needs to check registration, not puzzle
-        // over why an unrelated file appears "older than the source".
-        if (!isConfidentMatch(source, artifact)) {
+        if (!mode.registered && !isConfidentMatch(source, artifact)) {
             const where = isTestPath(source) ? '_tests/' : 'dist/';
+            const candidates = await collectSameBasenameCandidates(source, mode.roots);
+            const nearHits = describeCandidates(candidates);
             return {
                 source,
                 artifact: undefined,
                 status: 'missing',
-                warning: `Audit: engine/${source} was touched but no related packaged artifact with basename "${basename(source)}" was found under ${where} (nearest same-basename file ${artifact} lives in an unrelated subtree). Missing moz.build / jar.mn / package-manifest.in registration?`,
+                warning: `Audit: engine/${source} was touched but no related packaged artifact with ` +
+                    `basename "${basename(source)}" was found under ${where}` +
+                    (nearHits ? `. Same-basename hits in unrelated subtrees: ${nearHits}` : '') +
+                    `. Missing moz.build / jar.mn / package-manifest.in registration?`,
             };
         }
         return {
@@ -364,6 +436,34 @@ async function auditSinglePath(source, ctx) {
     }
     return { source, artifact, status: 'updated' };
 }
+/** Cap on candidate list rendering before truncating with `(+N more)`. */
+const CANDIDATE_LIST_LIMIT = 5;
+/**
+ * Renders a comma-separated list of same-basename hits for inclusion in a
+ * warning, truncated at {@link CANDIDATE_LIST_LIMIT} with a `(+N more)`
+ * tail. Returns the empty string when no candidates are supplied so
+ * callers can omit the parenthetical entirely rather than render a stub.
+ */
+function describeCandidates(candidates) {
+    if (candidates.length === 0)
+        return '';
+    const head = candidates.slice(0, CANDIDATE_LIST_LIMIT).join(', ');
+    if (candidates.length <= CANDIDATE_LIST_LIMIT)
+        return head;
+    return `${head}, … (+${candidates.length - CANDIDATE_LIST_LIMIT} more)`;
+}
+/**
+ * Formats a manifest path relative to the engine root when it lives
+ * underneath, falling back to the absolute path otherwise. Keeps warning
+ * text short and anchored to `engine/…` when the manifest is in-tree.
+ */
+function relativeManifestPath(engineDir, manifest) {
+    const root = engineDir.replace(/[/\\]+$/, '');
+    if (manifest.startsWith(`${root}/`)) {
+        return `engine/${manifest.slice(root.length + 1)}`;
+    }
+    return manifest;
+}
 /**
  * Runs the post-build audit. Emits per-file warnings for missing or
  * stale artifacts and a summary info line at the end. Always returns

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

@@ -8,7 +8,7 @@
  * aborting the whole command. Missing jar.mn on a fork without a locale
  * package should not block a working `.mjs`/`.css` from shipping.
  */
-import type { DryRunAction, StepError } from '../types/furnace.js';
+import type { CustomComponentConfig, DryRunAction, StepError } from '../types/furnace.js';
 import { type RollbackJournal } from './furnace-rollback.js';
 /**
  * Copies a component's `.ftl` into the FTL tree and registers the chrome URI
@@ -28,6 +28,8 @@ export declare function describeLocaleFtlJarMnRegistration(name: string, ftlDir:
 /**
  * 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.
+ * 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, rollbackJournal?: RollbackJournal): Promise<void>;
+export declare function removeCustomFtlJarMnEntry(engineDir: string, fileName: string, ftlDir: string, config: CustomComponentConfig, rollbackJournal?: RollbackJournal): Promise<void>;

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

@@ -81,9 +81,13 @@ export function describeLocaleFtlJarMnRegistration(name, ftlDir, ftlFile) {
 /**
  * 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.
+ * 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, rollbackJournal) {
+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);

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

@@ -139,10 +139,12 @@ export async function undeployCustomFiles(engineDir, config, deletedFiles, ftlDi
             await removeFile(enginePath);
             removed.push(relative(engineDir, enginePath));
         }
-        // When an `.ftl` is deleted from the workspace, the corresponding locale
+        // When an `.ftl` is deleted from the workspace the corresponding locale
         // jar.mn entry must also be dropped — otherwise the chrome URI points at
         // a missing file and runtime Fluent resolution breaks silently.
-        await removeCustomFtlJarMnEntry(engineDir, fileName, ftlDir, rollbackJournal);
+        // `removeCustomFtlJarMnEntry` early-returns for `sharedFtl` components
+        // (the shared bundle is owned elsewhere).
+        await removeCustomFtlJarMnEntry(engineDir, fileName, ftlDir, config, rollbackJournal);
     }
     return removed;
 }
@@ -306,7 +308,12 @@ async function buildCustomDryRunActions(name, componentDir, engineDir, config, t
             description: `Copy ${entry.name} to ${config.targetPath}`,
         });
     }
-    if (config.localized) {
+    // 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)) {
@@ -402,7 +409,10 @@ export async function applyCustomComponent(engineDir, name, componentDir, config
         affectedPaths.push(relative(engineDir, dest));
         copiedFileNames.push(entry.name);
     }));
-    if (config.localized) {
+    // See buildCustomDryRunActions for the rationale: when `sharedFtl` is set
+    // the shared bundle is owned elsewhere and FireForge must not copy or
+    // register a per-component `.ftl` on its behalf.
+    if (config.localized && !config.sharedFtl) {
         await applyCustomFtlFile(engineDir, name, componentDir, ftlDir, affectedPaths, stepErrors, rollbackJournal);
     }
     if (config.register) {

package/dist/src/core/furnace-config-custom.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parser for the `custom` entries in furnace.json. Extracted from
+ * `furnace-config.ts` so the main config module stays under the
+ * per-file LOC budget — the custom-component schema has grown to
+ * carry opt-in fields (`composes`, `keyboardCovered`, `sharedFtl`) that
+ * each add their own validation branch.
+ */
+import type { CustomComponentConfig } from '../types/furnace.js';
+/**
+ * Validates a custom component config object.
+ * @param data - Raw data to validate
+ * @param name - Component name for error messages
+ */
+export declare function parseCustomConfig(data: Record<string, unknown>, name: string): CustomComponentConfig;

package/dist/src/core/furnace-config-custom.js

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Parser for the `custom` entries in furnace.json. Extracted from
+ * `furnace-config.ts` so the main config module stays under the
+ * per-file LOC budget — the custom-component schema has grown to
+ * carry opt-in fields (`composes`, `keyboardCovered`, `sharedFtl`) that
+ * each add their own validation branch.
+ */
+import { FurnaceError } from '../errors/furnace.js';
+import { isExplicitAbsolutePath } from '../utils/paths.js';
+import { isBoolean, isString } from '../utils/validation.js';
+import { parseStringArray } from './furnace-config.js';
+import { validateSharedFtl } from './shared-ftl.js';
+/**
+ * Validates a custom component config object.
+ * @param data - Raw data to validate
+ * @param name - Component name for error messages
+ */
+export function parseCustomConfig(data, name) {
+    if (!isString(data['description'])) {
+        throw new FurnaceError(`Furnace config: custom "${name}.description" must be a string`);
+    }
+    if (!isString(data['targetPath'])) {
+        throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must be a string`);
+    }
+    if (data['targetPath'].includes('..') || data['targetPath'].includes('\0')) {
+        throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must not contain ".." or null bytes (path traversal)`);
+    }
+    if (isExplicitAbsolutePath(data['targetPath'])) {
+        throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must not be an absolute path`);
+    }
+    if (!isBoolean(data['register'])) {
+        throw new FurnaceError(`Furnace config: custom "${name}.register" must be a boolean`);
+    }
+    if (!isBoolean(data['localized'])) {
+        throw new FurnaceError(`Furnace config: custom "${name}.localized" must be a boolean`);
+    }
+    if (data['composes'] !== undefined) {
+        parseStringArray(data['composes'], `${name}.composes`);
+    }
+    if (data['keyboardCovered'] !== undefined && !isBoolean(data['keyboardCovered'])) {
+        throw new FurnaceError(`Furnace config: custom "${name}.keyboardCovered" must be a boolean when set`);
+    }
+    let sharedFtl;
+    if (data['sharedFtl'] !== undefined) {
+        const result = validateSharedFtl(data['sharedFtl'], { localized: data['localized'] });
+        if (!result.ok) {
+            throw new FurnaceError(`Furnace config: custom "${name}.sharedFtl" ${result.reason}`);
+        }
+        sharedFtl = result.value;
+    }
+    return {
+        description: data['description'],
+        targetPath: data['targetPath'],
+        register: data['register'],
+        localized: data['localized'],
+        ...(data['composes'] !== undefined
+            ? { composes: parseStringArray(data['composes'], `${name}.composes`) }
+            : {}),
+        ...(data['keyboardCovered'] === true ? { keyboardCovered: true } : {}),
+        ...(sharedFtl !== undefined ? { sharedFtl } : {}),
+    };
+}
+//# sourceMappingURL=furnace-config-custom.js.map