@hominis/fireforge 0.13.2 → 0.15.1

package/dist/src/commands/run.js

@@ -2,14 +2,13 @@
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getProjectPaths } from '../core/config.js';
-import { extractComponentChecksums, hasComponentChanged } from '../core/furnace-apply-helpers.js';
-import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from '../core/furnace-config.js';
+import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
 import { buildArtifactMismatchMessage, hasBuildArtifacts, run } from '../core/mach.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, removeDir, removeFile } from '../utils/fs.js';
-import { info, intro, verbose, warn } from '../utils/logger.js';
+import { info, intro, verbose } from '../utils/logger.js';
 /**
  * Cleans the dev profile to prevent stale-state startup failures.
  *
@@ -47,47 +46,6 @@ async function cleanDevProfile(engineDir) {
         verbose(`Non-fatal dev profile cleanup failure: ${toError(error).message}`);
     }
 }
-/**
- * Checks whether any Furnace component has changed since the last apply
- * and warns the user. The build command auto-applies, but run does not,
- * so this advisory message prevents the common "forgot to apply" mistake.
- */
-async function warnIfFurnaceStale(projectRoot) {
-    try {
-        if (!(await furnaceConfigExists(projectRoot)))
-            return;
-        const config = await loadFurnaceConfig(projectRoot);
-        const state = await loadFurnaceState(projectRoot);
-        const furnacePaths = getFurnacePaths(projectRoot);
-        if (!state.appliedChecksums)
-            return;
-        const stale = [];
-        for (const name of Object.keys(config.overrides)) {
-            const dir = `${furnacePaths.overridesDir}/${name}`;
-            if (!(await pathExists(dir)))
-                continue;
-            const prev = extractComponentChecksums(state.appliedChecksums, 'override', name);
-            if (await hasComponentChanged(dir, prev))
-                stale.push(name);
-        }
-        for (const name of Object.keys(config.custom)) {
-            const dir = `${furnacePaths.customDir}/${name}`;
-            if (!(await pathExists(dir)))
-                continue;
-            const prev = extractComponentChecksums(state.appliedChecksums, 'custom', name);
-            if (await hasComponentChanged(dir, prev))
-                stale.push(name);
-        }
-        if (stale.length > 0) {
-            warn(`Furnace component${stale.length === 1 ? '' : 's'} modified since last apply: ${stale.join(', ')}. ` +
-                'Run "fireforge furnace apply" (or "fireforge build" which auto-applies) to update the engine.');
-        }
-    }
-    catch {
-        // Non-fatal: a broken furnace config should not block run.
-        verbose('Furnace staleness check skipped due to an error.');
-    }
-}
 /**
  * Runs the run command to launch the built browser.
  * @param projectRoot - Root directory of the project
@@ -120,6 +78,13 @@ export async function runCommand(projectRoot) {
     await cleanDevProfile(paths.engine);
     info('Launching browser...\n');
     const exitCode = await run(paths.engine);
+    // Exit-code whitelist:
+    //   0   — clean shutdown
+    //   130 — SIGINT (Ctrl+C), user-initiated termination
+    //   143 — SIGTERM, graceful-shutdown termination
+    // SIGKILL (137) and other signal-induced codes are intentionally NOT
+    // whitelisted: those indicate abnormal termination the operator should
+    // see surface as a build-time error.
     if (exitCode !== 0 && exitCode !== 130 && exitCode !== 143) {
         throw new BuildError(`Browser exited with code ${exitCode}`, 'mach run');
     }

package/dist/src/commands/setup-support.js

@@ -178,23 +178,41 @@ async function promptSetupInputs(options) {
             throw new CancellationError();
         },
     });
+    return finalizePromptedSetupInputs(project);
+}
+/**
+ * Validates the raw prompt result and resolves the canonical
+ * {@link ResolvedSetupInputs}. Extracted from {@link promptSetupInputs} so
+ * the prompt body stays under the per-function line limit.
+ */
+function finalizePromptedSetupInputs(project) {
     const sanitizedName = project.name.toLowerCase().replace(/[^a-z0-9]/g, '');
-    const finalName = project.name;
-    const finalVendor = project.vendor;
-    const finalAppId = (typeof project.appId === 'string' ? project.appId.trim() : '') ||
-        `org.${sanitizedName}.browser`;
-    const finalBinaryName = (typeof project.binaryName === 'string' ? project.binaryName.trim() : '') || sanitizedName;
+    // Project names that contain no ASCII alphanumerics (e.g. "----", "漢字",
+    // emoji-only) collapse to an empty sanitised slug, which would silently
+    // produce an invalid `appId` ("org..browser") and an empty `binaryName`.
+    // Refuse to derive defaults from such names — the user must supply
+    // explicit appId / binaryName values instead.
+    const explicitAppId = typeof project.appId === 'string' ? project.appId.trim() : '';
+    const explicitBinaryName = typeof project.binaryName === 'string' ? project.binaryName.trim() : '';
+    if (sanitizedName === '' && (explicitAppId === '' || explicitBinaryName === '')) {
+        throw new InvalidArgumentError(`Project name "${project.name}" contains no characters that can be used to derive default appId / binaryName values. Re-run setup and supply --app-id and --binary-name explicitly.`, 'name');
+    }
+    const finalAppId = explicitAppId || `org.${sanitizedName}.browser`;
+    const finalBinaryName = explicitBinaryName || sanitizedName;
     const finalFirefoxVersion = (typeof project.firefoxVersion === 'string' ? project.firefoxVersion.trim() : '') ||
         '140.9.0esr';
     if (!isValidAppId(finalAppId)) {
         throw new InvalidArgumentError(`Derived appId "${finalAppId}" is invalid.`, 'appId');
     }
+    if (finalBinaryName === '') {
+        throw new InvalidArgumentError('Derived binaryName is empty. Supply --binary-name explicitly.', 'binaryName');
+    }
     if (!isValidFirefoxVersion(finalFirefoxVersion)) {
         throw new InvalidArgumentError(`Default Firefox version "${finalFirefoxVersion}" is invalid.`, 'firefoxVersion');
     }
     return {
-        finalName,
-        finalVendor,
+        finalName: project.name,
+        finalVendor: project.vendor,
         finalAppId,
         finalBinaryName,
         finalFirefoxVersion,

package/dist/src/commands/status.js

@@ -97,16 +97,64 @@ function renderRawStatus(files) {
     }
 }
 /**
- * Expands collapsed untracked directory entries into individual file entries.
- * Git status may report an entire untracked directory as a single entry (e.g. "?? dir/").
- * This function expands those into individual file entries so each file can be classified.
+ * Default maximum number of files we will materialise from a single
+ * untracked directory. Pathological inputs (an accidental dump of build
+ * output, a symlink that resolves into a huge unrelated tree, etc.)
+ * should not be able to balloon `status` into multi-gigabyte memory or
+ * hang the CLI. Going over this cap surfaces a warning so the user knows
+ * the listing has been truncated, and it bounds the JSON / default
+ * rendering paths.
+ *
+ * Override via the `FIREFORGE_MAX_UNTRACKED_FILES` environment variable
+ * for monorepos or fixture-heavy projects with legitimately large
+ * untracked directories.
  */
+const DEFAULT_MAX_UNTRACKED_FILES_PER_DIR = 5000;
+function resolveMaxUntrackedFilesPerDir() {
+    const raw = process.env['FIREFORGE_MAX_UNTRACKED_FILES'];
+    if (raw === undefined || raw.length === 0)
+        return DEFAULT_MAX_UNTRACKED_FILES_PER_DIR;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        warn(`Ignoring FIREFORGE_MAX_UNTRACKED_FILES="${raw}" — expected a positive integer. Falling back to ${DEFAULT_MAX_UNTRACKED_FILES_PER_DIR}.`);
+        return DEFAULT_MAX_UNTRACKED_FILES_PER_DIR;
+    }
+    return parsed;
+}
+const MAX_UNTRACKED_FILES_PER_DIR = resolveMaxUntrackedFilesPerDir();
+/**
+ * Emits a prominent top-of-output warning when one or more untracked
+ * directories were truncated during expansion. Individual per-dir warnings
+ * already fired inside expandDirectoryEntries but are easily lost in
+ * scrollback for large status outputs; this banner summarises the total
+ * hidden count so the user doesn't miss that an export based on this
+ * status would be incomplete.
+ */
+function renderTruncationBanner(truncations) {
+    if (truncations.length === 0)
+        return;
+    const hidden = truncations.reduce((sum, rec) => sum + (rec.total - rec.shown), 0);
+    const dirList = truncations.map((r) => `${r.dir} (${r.total - r.shown} hidden)`).join(', ');
+    warn(`⚠ Status output is truncated: ${hidden.toLocaleString()} untracked file(s) across ${truncations.length} director(y/ies) are not shown. ` +
+        `Truncated: ${dirList}. ` +
+        `Add a .gitignore entry or clean the directory before exporting, otherwise the export will omit these files.`);
+}
 async function expandDirectoryEntries(files, engineDir) {
     const expanded = [];
+    const truncations = [];
     for (const entry of files) {
         if (entry.file.endsWith('/') && entry.status.includes('?')) {
             const individualFiles = await getUntrackedFilesInDir(engineDir, entry.file);
-            for (const f of individualFiles) {
+            if (individualFiles.length > MAX_UNTRACKED_FILES_PER_DIR) {
+                warn(`Untracked directory ${entry.file} contains ${individualFiles.length} files — only the first ${MAX_UNTRACKED_FILES_PER_DIR} will be classified. Consider adding a .gitignore entry.`);
+                truncations.push({
+                    dir: entry.file,
+                    total: individualFiles.length,
+                    shown: MAX_UNTRACKED_FILES_PER_DIR,
+                });
+            }
+            const limited = individualFiles.slice(0, MAX_UNTRACKED_FILES_PER_DIR);
+            for (const f of limited) {
                 expanded.push({ status: '??', file: f });
             }
         }
@@ -114,7 +162,7 @@ async function expandDirectoryEntries(files, engineDir) {
             expanded.push(entry);
         }
     }
-    return expanded;
+    return { entries: expanded, truncations };
 }
 /**
  * Classifies files into patch-backed, unmanaged, or branding buckets.
@@ -226,9 +274,11 @@ export async function statusCommand(projectRoot, options = {}) {
             throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
         }
         const manifest = await loadPatchesManifest(paths.patches);
-        const rawFilesOwnership = (await isGitRepository(paths.engine))
+        const ownershipExpansion = (await isGitRepository(paths.engine))
             ? await expandDirectoryEntries(await getStatusWithCodes(paths.engine), paths.engine)
-            : [];
+            : { entries: [], truncations: [] };
+        const rawFilesOwnership = ownershipExpansion.entries;
+        renderTruncationBanner(ownershipExpansion.truncations);
         // Only walk the patch bodies when the directory actually exists.
         // Fresh projects with no patch queue yet pass through with an empty
         // creators map, which degrades to the old filesAffected-only
@@ -263,7 +313,8 @@ export async function statusCommand(projectRoot, options = {}) {
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }
     const rawFiles = await getStatusWithCodes(paths.engine);
-    const files = await expandDirectoryEntries(rawFiles, paths.engine);
+    const { entries: files, truncations } = await expandDirectoryEntries(rawFiles, paths.engine);
+    renderTruncationBanner(truncations);
     if (files.length === 0) {
         info('No modified files');
         outro('Working tree clean');

package/dist/src/commands/test.js

@@ -3,26 +3,33 @@ 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';
 import { info, intro, spinner } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 /**
- * Strips the "engine/" prefix from a path if present.
+ * Strips a leading "engine/" or "engine\\" prefix from a path if present.
  * Users may specify paths like "engine/browser/modules/..." from the project
  * root, but mach test expects paths relative to the engine directory.
+ *
+ * The match is case-insensitive because case-insensitive filesystems
+ * (default macOS, Windows) treat "Engine/" and "engine/" as the same
+ * directory, and a literal lowercase-only check left mach with a
+ * non-stripped prefix that resolved to a different path under the engine
+ * tree. Tab and other whitespace before the prefix is also ignored.
+ *
  * @param testPath - Path as provided by the user
  * @returns Path relative to the engine directory
  */
 function normalizeTestPath(testPath) {
-    if (testPath.startsWith('engine/')) {
-        return testPath.slice('engine/'.length);
+    const trimmed = testPath.trim();
+    const match = /^engine[/\\]/i.exec(trimmed);
+    if (match) {
+        return trimmed.slice(match[0].length);
     }
-    if (testPath.startsWith('engine\\')) {
-        return testPath.slice('engine\\'.length);
-    }
-    return testPath;
+    return trimmed;
 }
 async function assertTestPathsExist(engineDir, testPaths) {
     const missingPaths = [];
@@ -111,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);
@@ -143,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/commands/token.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { Option } from 'commander';
 import { loadConfig } from '../core/config.js';
 import { loadFurnaceConfig } from '../core/furnace-config.js';
 import { addToken, getTokensCssPath, validateTokenAdd, } from '../core/token-manager.js';
@@ -96,7 +98,15 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
         .command('add <token-name> <value>')
         .description('Add a design token to CSS and documentation')
         .requiredOption('--category <cat>', 'Token category (e.g., "Colors — Canvas", "Spacing")')
-        .requiredOption('--mode <mode>', 'Dark mode behavior: auto, static, or override')
+        .addOption(
+    // Use Commander's .choices() so invalid --mode values are rejected with
+    // the built-in "argument must be one of …" message and --help lists the
+    // valid choices up-front. The runtime check in tokenAddCommand remains
+    // as a defence-in-depth guard for programmatic callers that bypass
+    // Commander's argument parsing.
+    new Option('--mode <mode>', 'Dark mode behavior')
+        .choices(['auto', 'static', 'override'])
+        .makeOptionMandatory(true))
         .option('--description <desc>', 'Comment description for the CSS file')
         .option('--dark-value <val>', 'Dark mode value (required if mode is "override")')
         .option('--dry-run', 'Show what would be changed without writing')

package/dist/src/commands/watch.js

@@ -1,10 +1,49 @@
 import { getProjectPaths, loadConfig } from '../core/config.js';
+import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
 import { buildArtifactMismatchMessage, generateMozconfig, hasBuildArtifacts, watchWithOutput, } from '../core/mach.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner } from '../utils/logger.js';
-import { executableExists } from '../utils/process.js';
+import { exec, executableExists } from '../utils/process.js';
+const WATCHMAN_PROBE_TIMEOUT_MS = 5000;
+/**
+ * Probes watchman by running `watchman --version`. A binary that exists
+ * in PATH but cannot respond (corrupt install, server crashed mid-session,
+ * permission denied on the state directory) would otherwise surface as a
+ * confusing mid-watch failure. Returns the trimmed version string when
+ * the probe succeeds; throws a {@link GeneralError} with actionable
+ * remediation when it does not.
+ */
+async function probeWatchman() {
+    try {
+        const result = await exec('watchman', ['--version'], {
+            timeout: WATCHMAN_PROBE_TIMEOUT_MS,
+        });
+        if (result.exitCode !== 0) {
+            throw new GeneralError(`Watchman is installed but "watchman --version" exited ${result.exitCode}.\n\n` +
+                (result.stderr.trim() ? `Output:\n${result.stderr.trim()}\n\n` : '') +
+                'Re-install or repair watchman, then rerun "fireforge watch".');
+        }
+        const version = result.stdout.trim();
+        if (!version) {
+            throw new GeneralError('Watchman is installed but "watchman --version" produced no output. ' +
+                'Re-install or repair watchman, then rerun "fireforge watch".');
+        }
+        return version;
+    }
+    catch (error) {
+        if (error instanceof GeneralError)
+            throw error;
+        throw new GeneralError(`Watchman is installed but did not respond within ${WATCHMAN_PROBE_TIMEOUT_MS}ms.\n\n` +
+            `Underlying cause: ${toError(error).message}\n\n` +
+            'Common fixes:\n' +
+            '  - Restart watchman: "watchman shutdown-server" then retry\n' +
+            "  - Check filesystem permissions on watchman's state directory\n" +
+            '  - Re-install watchman if the binary is corrupt');
+    }
+}
 /**
  * Builds remediation guidance for objdirs configured before watchman was available.
  * @returns User-facing configure-time watchman guidance
@@ -51,6 +90,11 @@ export async function watchCommand(projectRoot) {
         throw new GeneralError('Watch mode requires watchman to be installed and available in PATH.\n\n' +
             'Install watchman first, then rerun "fireforge watch".');
     }
+    // Verify watchman actually responds — a binary that is in PATH but
+    // unable to respond (broken install, crashed server, bad state dir
+    // permissions) would otherwise surface as a confusing mid-build failure
+    // instead of an actionable preflight error.
+    await probeWatchman();
     // Check for build artifacts before starting watch
     const buildCheck = await hasBuildArtifacts(paths.engine);
     if (buildCheck.ambiguous && buildCheck.objDirs && buildCheck.objDirs.length > 0) {
@@ -71,6 +115,12 @@ export async function watchCommand(projectRoot) {
             "Run 'fireforge build' first to create the initial build, then run 'fireforge watch'.");
     }
     info(`Using build artifacts from ${buildCheck.objDir}/`);
+    // Advisory: warn when Furnace components have drifted since the last
+    // apply so the user doesn't launch watch-mode builds with stale
+    // components baked in. Mirrors the check in `fireforge run` — without
+    // it, users editing a component then running `watch` would see their
+    // change never surface in the rebuilt browser.
+    await warnIfFurnaceStale(projectRoot);
     // Generate mozconfig (in case it's not up to date)
     const mozconfigSpinner = spinner('Generating mozconfig...');
     try {

package/dist/src/commands/wire.js

@@ -28,6 +28,21 @@ function printWireDryRun(engineDir, name, subscriptDir, domFilePath, options) {
     info(`  jar.mn: content/browser/${name}.js (${relPath}/${name}.js)`);
     outro('Dry run complete');
 }
+/**
+ * Validates a subscript name supplied on the command line. Subscripts are
+ * resolved into filenames under the subscript directory and registered in
+ * jar.mn by this name, so any path separator or `..` segment would let
+ * the caller write outside the intended directory or corrupt the manifest.
+ * Mirrors the validation already applied to setup's binaryName and furnace
+ * custom component targetPath.
+ */
+function validateWireName(name) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(name)) {
+        throw new InvalidArgumentError(`Subscript name "${name}" is invalid. ` +
+            'Names must start with a letter or underscore and contain only letters, digits, underscores, or hyphens. ' +
+            'Path separators and parent-directory segments are not permitted.', 'name');
+    }
+}
 /**
  * Wires a chrome subscript into the browser.
  *
@@ -37,6 +52,14 @@ function printWireDryRun(engineDir, name, subscriptDir, domFilePath, options) {
  */
 export async function wireCommand(projectRoot, name, options = {}) {
     intro('Wire');
+    validateWireName(name);
+    if (options.after !== undefined) {
+        // --after references an existing init block by its subscript name, so
+        // it must follow the same naming rules as `name` itself. Without this
+        // check, a caller could sneak a path-traversal segment in through
+        // --after and have it forwarded unchanged to the lookup layer.
+        validateWireName(options.after);
+    }
     consumeParserFallbackEvents();
     // Resolve subscript directory: CLI flag > fireforge.json > default
     let subscriptDir = DEFAULT_BROWSER_SUBSCRIPT_DIR;

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

@@ -22,11 +22,25 @@ export function validateConfig(data) {
     catch {
         throw new ConfigError('Config must be an object');
     }
-    // Required string fields
+    // Required string fields. Empty strings would technically pass the
+    // typeof-check below but are never valid for any of these identifier
+    // fields — rejecting them here prevents downstream code (Firefox build,
+    // launcher binary lookup, AppID assertions) from failing with confusing
+    // errors much later.
     const name = requireConfigString(rec, 'name');
     const vendor = requireConfigString(rec, 'vendor');
     const appId = requireConfigString(rec, 'appId');
     const binaryName = requireConfigString(rec, 'binaryName');
+    for (const [field, value] of [
+        ['name', name],
+        ['vendor', vendor],
+        ['appId', appId],
+        ['binaryName', binaryName],
+    ]) {
+        if (value.trim() === '') {
+            throw new ConfigError(`Config field "${field}" must not be empty`);
+        }
+    }
     if (binaryName.includes('..') ||
         binaryName.includes('/') ||
         binaryName.includes('\\') ||
@@ -107,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) {
@@ -153,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>;