@hominis/fireforge 0.14.0 → 0.15.2

package/dist/src/commands/furnace/create.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { multiselect, text } from '@clack/prompts';
 import { getProjectPaths, loadConfig } from '../../core/config.js';
 import { createDefaultFurnaceConfig, detectComposesCycles, furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig, } from '../../core/furnace-config.js';
-import { tagNameToClassName } from '../../core/furnace-constants.js';
+import { resolveFtlChromeSubPath, tagNameToClassName } from '../../core/furnace-constants.js';
 import { recordFurnaceRollbackFailure, runFurnaceMutation, } from '../../core/furnace-operation.js';
 import { CUSTOM_ELEMENT_TAG_PATTERN, CUSTOM_ELEMENT_TAG_RULES, } from '../../core/furnace-registration-validate.js';
 import { createRollbackJournal, recordCreatedDir, restoreRollbackJournalOrThrow, snapshotFile, } from '../../core/furnace-rollback.js';
@@ -15,6 +15,8 @@ import { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
 import { ensureDir, pathExists, readText, writeText } from '../../utils/fs.js';
 import { cancel, intro, isCancel, note, outro, success, warn } from '../../utils/logger.js';
+import { generateCssContent, generateFtlContent, generateMjsContent } from './create-templates.js';
+import { scaffoldXpcshellTestFiles } from './create-xpcshell.js';
 async function loadAuthoringFurnaceConfig(projectRoot) {
     if (await furnaceConfigExists(projectRoot)) {
         return loadFurnaceConfig(projectRoot);
@@ -46,65 +48,6 @@ function checkNameConflict(config, name) {
     }
     return undefined;
 }
-/**
- * Generates the .mjs file content for a custom component.
- */
-function generateMjsContent(name, className, description, localized, header) {
-    const connectedCallback = localized
-        ? `
-  connectedCallback() {
-    super.connectedCallback();
-    this.insertFTLIfNeeded("${name}.ftl");
-  }
-`
-        : '';
-    return `${header}
-
-import { html } from "chrome://global/content/vendor/lit.all.mjs";
-import { MozLitElement } from "chrome://global/content/lit-utils.mjs";
-
-/**
- * ${description || name}
- *
- * @tagname ${name}
- */
-class ${className} extends MozLitElement {
-  static properties = {};
-
-  constructor() {
-    super();
-  }
-${connectedCallback}
-  render() {
-    return html\`
-      <link rel="stylesheet" href="chrome://global/content/elements/${name}.css" />
-      <slot></slot>
-    \`;
-  }
-}
-customElements.define("${name}", ${className});
-`;
-}
-/**
- * Generates the .css file content for a custom component.
- */
-function generateCssContent(header) {
-    return `${header}
-
-:host {
-  display: block;
-}
-`;
-}
-/**
- * Generates the .ftl file content for a custom component.
- */
-function generateFtlContent(name, header) {
-    return `${header}
-
-## Strings for the ${name} component
-`;
-}
 /**
  * Scaffolds browser mochitest files for a newly created custom component.
  * @param componentName - Custom element tag name
@@ -258,13 +201,13 @@ async function resolveCreateFeatures(isInteractive, options) {
  * @param journal - Optional rollback journal that snapshots files before writes
  * @returns Relative filenames written for the component
  */
-async function writeComponentFiles(componentDir, componentName, className, description, localized, license, journal) {
+async function writeComponentFiles(componentDir, componentName, className, description, localized, license, ftlChromeSubPath, journal) {
     await ensureDir(componentDir);
     const files = [`${componentName}.mjs`, `${componentName}.css`];
     const mjsPath = join(componentDir, `${componentName}.mjs`);
     if (journal)
         await snapshotFile(journal, mjsPath);
-    const mjsContent = generateMjsContent(componentName, className, description, localized, getLicenseHeader(license, 'js'));
+    const mjsContent = generateMjsContent(componentName, className, description, localized, getLicenseHeader(license, 'js'), ftlChromeSubPath);
     await writeText(mjsPath, mjsContent);
     const cssPath = join(componentDir, `${componentName}.css`);
     if (journal)
@@ -303,7 +246,7 @@ async function performCreateMutations(args) {
         // so signal-driven rollback can clean it up even if writeComponentFiles
         // is interrupted mid-ensureDir.
         recordCreatedDir(journal, args.componentDir);
-        files = await writeComponentFiles(args.componentDir, args.componentName, args.className, args.description, args.localized, args.license, journal);
+        files = await writeComponentFiles(args.componentDir, args.componentName, args.className, args.description, args.localized, args.license, args.ftlChromeSubPath, journal);
         const customEntry = {
             description: args.description,
             targetPath: `toolkit/content/widgets/${args.componentName}`,
@@ -320,6 +263,10 @@ async function performCreateMutations(args) {
             const scafFiles = await scaffoldTestFiles(args.componentName, args.license, args.forgeConfig, args.paths, journal);
             testFiles.push(...scafFiles);
         }
+        if (args.xpcshellTests) {
+            const xpcshellFiles = await scaffoldXpcshellTestFiles(args.componentName, args.license, args.forgeConfig, args.paths, journal);
+            testFiles.push(...xpcshellFiles);
+        }
     }
     catch (error) {
         try {
@@ -333,6 +280,58 @@ async function performCreateMutations(args) {
     }
     return { files, testFiles };
 }
+/**
+ * Prompts the operator for a description when the command is interactive and
+ * the operator did not pass `-d`. Returns the resolved description string.
+ */
+async function resolveDescription(isInteractive, options) {
+    let description = options.description ?? '';
+    if (!description && isInteractive) {
+        const descResult = await text({
+            message: 'Description (optional):',
+            placeholder: 'A brief description of the component',
+        });
+        if (!isCancel(descResult)) {
+            description = String(descResult);
+        }
+    }
+    return description;
+}
+/**
+ * Validates the `--compose` targets against registered components and runs
+ * cycle detection if the new component is introduced into the graph. Throws
+ * on any failure; returns when the graph is clean.
+ */
+function validateComposesTargets(config, componentName, composes) {
+    if (!composes || composes.length === 0)
+        return;
+    const known = new Set([
+        ...config.stock,
+        ...Object.keys(config.overrides),
+        ...Object.keys(config.custom),
+    ]);
+    for (const tag of composes) {
+        if (tag === componentName) {
+            throw new FurnaceError(`Component "${componentName}" cannot compose itself.`);
+        }
+        if (!known.has(tag)) {
+            throw new FurnaceError(`Cannot compose unknown component "${tag}". ` +
+                'The referenced component must be registered as stock, override, or custom.');
+        }
+    }
+    // Check for cycles that would be introduced by adding this component.
+    const tempCustom = {
+        ...config.custom,
+        [componentName]: {
+            description: '',
+            targetPath: `toolkit/content/widgets/${componentName}`,
+            register: true,
+            localized: false,
+            composes,
+        },
+    };
+    detectComposesCycles(tempCustom);
+}
 /**
  * Runs the furnace create command to scaffold a new custom component.
  * @param projectRoot - Root directory of the project
@@ -394,16 +393,7 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
         warn(`Name "${componentName}" does not start with the configured prefix "${config.componentPrefix}".`);
     }
     // --- Resolve description ---
-    let description = options.description ?? '';
-    if (!description && isInteractive) {
-        const descResult = await text({
-            message: 'Description (optional):',
-            placeholder: 'A brief description of the component',
-        });
-        if (!isCancel(descResult)) {
-            description = String(descResult);
-        }
-    }
+    const description = await resolveDescription(isInteractive, options);
     // --- Resolve features ---
     const featureSelection = await resolveCreateFeatures(isInteractive, options);
     if (!featureSelection) {
@@ -411,12 +401,14 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
     }
     const { localized, register } = featureSelection;
     // --with-tests writes files under engine/browser/base/content/test/ and
-    // registers them in moz.build. Guard against a missing engine now rather
-    // than letting scaffoldTestFiles fabricate a partial engine tree with
-    // ensureDir.
+    // registers them in moz.build. --xpcshell is the equivalent for forks
+    // without a tabbrowser (storage-layer code). Guard against a missing
+    // engine now rather than letting the scaffolders fabricate a partial
+    // engine tree with ensureDir.
     const withTests = options.withTests ?? false;
-    if (withTests && !(await pathExists(paths.engine))) {
-        throw new FurnaceError('Engine directory not found. Run "fireforge download" first to use --with-tests.', componentName);
+    const xpcshellTests = options.xpcshell ?? false;
+    if ((withTests || xpcshellTests) && !(await pathExists(paths.engine))) {
+        throw new FurnaceError('Engine directory not found. Run "fireforge download" first to use --with-tests or --xpcshell.', componentName);
     }
     // --- Generate component files ---
     const className = tagNameToClassName(componentName);
@@ -428,39 +420,16 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
     // --- Validate --compose targets BEFORE any writes so a failed validation
     // does not strand component files behind.
     const composes = options.compose;
-    if (composes && composes.length > 0) {
-        const known = new Set([
-            ...config.stock,
-            ...Object.keys(config.overrides),
-            ...Object.keys(config.custom),
-        ]);
-        for (const tag of composes) {
-            if (tag === componentName) {
-                throw new FurnaceError(`Component "${componentName}" cannot compose itself.`);
-            }
-            if (!known.has(tag)) {
-                throw new FurnaceError(`Cannot compose unknown component "${tag}". ` +
-                    'The referenced component must be registered as stock, override, or custom.');
-            }
-        }
-        // Check for cycles that would be introduced by adding this component.
-        const tempCustom = {
-            ...config.custom,
-            [componentName]: {
-                description: '',
-                targetPath: `toolkit/content/widgets/${componentName}`,
-                register: true,
-                localized: false,
-                composes,
-            },
-        };
-        detectComposesCycles(tempCustom);
-    }
+    validateComposesTargets(config, componentName, composes);
     // All validation is done. Hand off to the transactional mutation helper
     // so any failure restores the workspace and engine to their pre-command
     // state via the shared rollback journal. The mutation runs under the
     // furnace-wide lock and is registered with the global SIGINT/SIGTERM
     // rollback pathway.
+    // Derive the FTL chrome sub-path from the configured ftlBasePath so the
+    // generated `.mjs` calls `insertFTLIfNeeded` at a URI that actually matches
+    // the locale jar.mn entry `furnace apply` will write.
+    const ftlChromeSubPath = resolveFtlChromeSubPath(config.ftlBasePath);
     const { files, testFiles } = await runFurnaceMutation(projectRoot, 'create-rollback', (ctx) => performCreateMutations({
         projectRoot,
         componentName,
@@ -476,15 +445,18 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
         paths,
         license,
         withTests,
+        xpcshellTests,
+        ftlChromeSubPath,
         operationContext: ctx,
     }));
     // --- Success ---
     let noteParts = `Files created in components/custom/${componentName}/:\n` +
         files.map((f) => `  ${f}`).join('\n');
     if (testFiles.length > 0) {
-        noteParts +=
-            `\n\nTest files in engine/browser/base/content/test/${forgeConfig.binaryName}/:\n` +
-                testFiles.map((f) => `  ${f}`).join('\n');
+        const testRoot = xpcshellTests
+            ? `engine/browser/base/content/test/${forgeConfig.binaryName}-xpcshell/${componentName}/`
+            : `engine/browser/base/content/test/${forgeConfig.binaryName}/`;
+        noteParts += `\n\nTest files in ${testRoot}:\n` + testFiles.map((f) => `  ${f}`).join('\n');
     }
     noteParts +=
         '\n\n' +

package/dist/src/commands/furnace/deploy.js

@@ -162,7 +162,7 @@ async function restoreNamedDeployRollback(rollbackJournal, name, projectRoot) {
  * @param isDryRun - Whether file writes should be skipped
  * @returns Apply result for the named component, or `stock` for stock-only entries
  */
-async function applyNamedComponent(name, engineDir, furnacePaths, config, ftlDir, isDryRun, operationContext, projectRoot) {
+async function applyNamedComponent(name, engineDir, furnacePaths, config, ftlDir, isDryRun, operationContext, projectRoot, markerComment) {
     const rollbackJournal = isDryRun ? undefined : createRollbackJournal();
     if (rollbackJournal && operationContext) {
         operationContext.registerJournal(rollbackJournal);
@@ -201,7 +201,7 @@ async function applyNamedComponent(name, engineDir, furnacePaths, config, ftlDir
             throw new FurnaceError(`Component directory not found: components/custom/${name}`, name);
         }
         try {
-            const { affectedPaths: filesAffected, stepErrors, actions, } = await applyCustomComponent(engineDir, name, componentDir, customConfig, ftlDir, isDryRun, rollbackJournal);
+            const { affectedPaths: filesAffected, stepErrors, actions, } = await applyCustomComponent(engineDir, name, componentDir, customConfig, ftlDir, isDryRun, rollbackJournal, markerComment !== undefined ? { markerComment } : {});
             if (isDryRun && actions) {
                 result.actions = actions;
             }
@@ -317,7 +317,7 @@ export async function furnaceDeployCommand(projectRoot, name, options = {}) {
     // `furnace deploy` runs only contend on the actual mutation.
     const applyOutcome = await runFurnaceMutation(projectRoot, 'deploy-rollback', async (ctx) => {
         if (name) {
-            const namedApplyResult = await applyNamedComponent(name, paths.engine, furnacePaths, config, ftlDir, isDryRun, ctx, projectRoot);
+            const namedApplyResult = await applyNamedComponent(name, paths.engine, furnacePaths, config, ftlDir, isDryRun, ctx, projectRoot, forgeConfig.markerComment);
             if (namedApplyResult === 'stock') {
                 return { kind: 'stock' };
             }

package/dist/src/commands/furnace/index.js

@@ -72,6 +72,7 @@ function registerFurnaceInfoCommands(furnace, context) {
         .option('--localized', 'Include Fluent l10n support')
         .option('--no-register', 'Skip customElements.js registration')
         .option('--with-tests', 'Scaffold Mochitest directory and register in moz.build')
+        .option('--xpcshell', 'Scaffold an xpcshell test harness (for storage-layer code on forks without tabbrowser)')
         .option('--compose <tags>', 'Record stock tags composed internally (metadata only, comma-separated)', (val) => val.split(',').map((s) => s.trim()))
         .action(withErrorHandling(async (name, options) => {
         await furnaceCreateCommand(getProjectRoot(), name, options);

package/dist/src/commands/setup.d.ts

@@ -8,4 +8,4 @@ import type { SetupOptions } from '../types/commands/index.js';
  */
 export declare function setupCommand(projectRoot: string, options?: SetupOptions): Promise<void>;
 /** Registers the setup command on the CLI program. */
-export declare function registerSetup(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;
+export declare function registerSetup(program: Command, { withErrorHandling }: CommandContext): void;

package/dist/src/commands/setup.js

@@ -1,4 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
+import { resolve } from 'node:path';
 import { confirm } from '@clack/prompts';
 import { Option } from 'commander';
 import { configExists } from '../core/config.js';
@@ -57,7 +58,7 @@ export async function setupCommand(projectRoot, options = {}) {
     }
 }
 /** Registers the setup command on the CLI program. */
-export function registerSetup(program, { getProjectRoot, withErrorHandling }) {
+export function registerSetup(program, { withErrorHandling }) {
     program
         .command('setup')
         .description('Initialize a new FireForge project')
@@ -88,7 +89,7 @@ export function registerSetup(program, { getProjectRoot, withErrorHandling }) {
                 setupOptions.license = parsedLicense;
             }
         }
-        await setupCommand(getProjectRoot(), setupOptions);
+        await setupCommand(resolve(process.cwd()), setupOptions);
     }));
 }
 //# sourceMappingURL=setup.js.map

package/dist/src/commands/test.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, testWithOutput, } from '../core/mach.js';
+import { reportMarionettePreflight, runMarionettePreflight } from '../core/marionette-preflight.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
@@ -117,6 +118,24 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         s.stop('Build complete');
         info('');
     }
+    // `--doctor` runs a short marionette handshake probe. When test paths are
+    // supplied the probe gates the mach test invocation (a FAIL bails out). When
+    // no paths are supplied this is the only step — it's the fastest way to tell
+    // marionette-wedged apart from test-discovery-failure.
+    if (options.doctor) {
+        info('Running marionette preflight...');
+        const preflight = await runMarionettePreflight(paths.engine);
+        reportMarionettePreflight(preflight);
+        if (testPaths.length === 0) {
+            if (!preflight.ok) {
+                throw new GeneralError('Marionette preflight reported FAIL — see output above.');
+            }
+            return;
+        }
+        if (!preflight.ok) {
+            throw new GeneralError('Marionette preflight reported FAIL — see output above. Aborting before mach test runs.');
+        }
+    }
     // Normalize test paths (strip engine/ prefix if present)
     const normalizedPaths = testPaths.map(normalizeTestPath);
     await assertTestPathsExist(paths.engine, normalizedPaths);
@@ -149,6 +168,7 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         .description('Run tests via mach test')
         .option('--headless', 'Run tests in headless mode')
         .option('--build', 'Run incremental UI build before testing')
+        .option('--doctor', 'Run a marionette handshake preflight before tests (exit 1 on FAIL). With no paths, runs the preflight only.')
         .action(withErrorHandling(async (paths, options) => {
         await testCommand(getProjectRoot(), paths, pickDefined(options));
     }));

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

@@ -5,7 +5,7 @@
  */
 import { FurnaceError } from '../errors/furnace.js';
 import { pathExists } from '../utils/fs.js';
-import { spinner, warn } from '../utils/logger.js';
+import { info, spinner, warn } from '../utils/logger.js';
 import { isBrandingSetup, setupBranding } from './branding.js';
 import { applyAllComponents } from './furnace-apply.js';
 import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from './furnace-config.js';
@@ -95,7 +95,12 @@ export async function prepareBuildEnvironment(projectRoot, paths, config) {
                 throw new FurnaceError(`${totalApplyFailures} component${totalApplyFailures === 1 ? '' : 's'} failed to apply cleanly`);
             }
             if (furnaceApplied > 0) {
+                const appliedNames = result.applied.map((entry) => entry.name).join(', ');
                 furnaceSpinner.stop(`Applied ${furnaceApplied} component${furnaceApplied === 1 ? '' : 's'}`);
+                // Loud banner: the build operator needs to see that engine/ was
+                // updated before this build, otherwise a silent re-apply is
+                // indistinguishable from a build that shipped stale components.
+                info(`Furnace: source → engine sync wrote ${furnaceApplied} component${furnaceApplied === 1 ? '' : 's'} before build (${appliedNames}). engine/ now matches components/.`);
             }
             else {
                 furnaceSpinner.stop('Components up to date');

package/dist/src/core/config-paths.d.ts

@@ -17,9 +17,9 @@ export declare const CONFIGS_DIR = "configs";
 /** Name of the source directory */
 export declare const SRC_DIR = "src";
 /** Supported top-level fireforge.json keys backed by the current schema. */
-export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "license", "wire", "patchLint"];
+export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "license", "wire", "patchLint", "markerComment"];
 /** Supported config paths that can be read or set without --force. */
-export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "build", "build.jobs", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.rawColorAllowlist"];
+export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "build", "build.jobs", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.rawColorAllowlist", "markerComment"];
 /**
  * Gets all project paths based on a root directory.
  * @param root - Root directory of the project

package/dist/src/core/config-paths.js

@@ -28,6 +28,7 @@ export const SUPPORTED_CONFIG_ROOT_KEYS = [
     'license',
     'wire',
     'patchLint',
+    'markerComment',
 ];
 /** Supported config paths that can be read or set without --force. */
 export const SUPPORTED_CONFIG_PATHS = [
@@ -46,6 +47,7 @@ export const SUPPORTED_CONFIG_PATHS = [
     'patchLint',
     'patchLint.checkJs',
     'patchLint.rawColorAllowlist',
+    'markerComment',
 ];
 /**
  * Gets all project paths based on a root directory.

package/dist/src/core/config-validate.js

@@ -121,6 +121,11 @@ export function validateConfig(data) {
         }
         config.license = licenseRaw;
     }
+    // Marker comment — appended to lines FireForge writes into upstream files.
+    const markerComment = parseMarkerComment(rec.raw('markerComment'));
+    if (markerComment !== undefined) {
+        config.markerComment = markerComment;
+    }
     // PatchLint
     const patchLintRec = optionalConfigObject(rec, 'patchLint');
     if (patchLintRec) {
@@ -167,6 +172,33 @@ function optionalConfigString(rec, key, label) {
     }
     return value;
 }
+/**
+ * Validates a raw `markerComment` value. Rejected values: non-strings, empty
+ * strings, surrounding whitespace (ambiguous format), newlines (would break
+ * source formatting), and `*/` (would terminate an enclosing block comment
+ * downstream). Control characters are rejected for the same reason.
+ */
+function parseMarkerComment(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'string') {
+        throw new ConfigError('Config field "markerComment" must be a string');
+    }
+    if (raw.trim() === '') {
+        throw new ConfigError('Config field "markerComment" must not be empty');
+    }
+    if (raw !== raw.trim()) {
+        throw new ConfigError('Config field "markerComment" must not have leading or trailing whitespace');
+    }
+    if (/[\n\r]/.test(raw) || raw.includes('*/')) {
+        throw new ConfigError('Config field "markerComment" must not contain newlines or "*/"');
+    }
+    // eslint-disable-next-line no-control-regex -- intentionally rejecting control chars
+    if (/[\x00-\x1f]/.test(raw)) {
+        throw new ConfigError('Config field "markerComment" must not contain control characters');
+    }
+    return raw;
+}
 function optionalConfigObject(rec, key) {
     const value = rec.raw(key);
     if (value === undefined)

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

@@ -0,0 +1,33 @@
+/**
+ * `.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 a `stepError` rather than
+ * 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 RollbackJournal } from './furnace-rollback.js';
+/**
+ * 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 — a well-formed `.mjs`/`.css` must never be
+ * blocked by a broken locale path.
+ */
+export declare function applyCustomFtlFile(engineDir: string, name: string, componentDir: string, ftlDir: string, 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.
+ */
+export declare function removeCustomFtlJarMnEntry(engineDir: string, fileName: string, ftlDir: string, rollbackJournal?: RollbackJournal): Promise<void>;

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

@@ -0,0 +1,102 @@
+// 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 a `stepError` rather than
+ * aborting the whole command. Missing jar.mn on a fork without a locale
+ * package should not block a working `.mjs`/`.css` from shipping.
+ */
+import { join, relative } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { copyFile, pathExists } from '../utils/fs.js';
+import { resolveFtlChromeSubPath, resolveFtlLocaleJarMnPath } from './furnace-constants.js';
+import { addLocaleFtlJarMnEntry, removeLocaleFtlJarMnEntry } from './furnace-registration.js';
+import { snapshotFile } from './furnace-rollback.js';
+/**
+ * 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 — a well-formed `.mjs`/`.css` must never be
+ * blocked by a broken locale path.
+ */
+export async function applyCustomFtlFile(engineDir, name, componentDir, ftlDir, affectedPaths, stepErrors, rollbackJournal) {
+    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);
+    affectedPaths.push(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.`,
+        });
+        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,
+        });
+    }
+}
+/**
+ * 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.
+ */
+export async function removeCustomFtlJarMnEntry(engineDir, fileName, ftlDir, rollbackJournal) {
+    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);
+}
+//# sourceMappingURL=furnace-apply-ftl.js.map

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

@@ -90,8 +90,17 @@ export declare function hasOverrideEngineDrift(engineDir: string, componentDir:
  * the validate command.
  */
 export declare function hasCustomEngineDrift(root: string, name: string, componentDir: string, config: CustomComponentConfig, ftlDir: string): 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(engineDir: string, name: string, componentDir: string, config: CustomComponentConfig, ftlDir: string, dryRun?: boolean, rollbackJournal?: RollbackJournal): Promise<{
+export declare function applyCustomComponent(engineDir: string, name: string, componentDir: string, config: CustomComponentConfig, ftlDir: string, dryRun?: boolean, rollbackJournal?: RollbackJournal, applyOptions?: CustomApplyOptions): Promise<{
     affectedPaths: string[];
     stepErrors: StepError[];
     actions?: DryRunAction[];