@hominis/fireforge 0.14.0 → 0.15.1

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.15.0
+
+### Furnace registration
+
+- `furnace apply` idempotency check is marker-comment-tolerant. Previously the single-line substring match (`content.includes('["tag",')`) missed multi-line entries, and the standalone-line regex anchored on `\s*$`, which did not allow trailing `// <marker>:` comments an operator may have appended to a previously-written entry. A duplicate tag was then inserted on every re-apply, and the second `setElementCreationCallback` invocation threw `NotSupportedError: Operation is not supported` at every window-load. The idempotency check now matches on tag-name column 0 (both single- and multi-line array shapes) and tolerates trailing `//` comments on the line.
+- New optional fireforge.json field `markerComment` (e.g. `"HOMINIS"`) is appended as a `  // HOMINIS:` suffix to every line FireForge writes into `customElements.js`. Keeps fork modifications discoverable and re-applies idempotent without hand-tagging after each apply. The field is threaded through `applyCustomComponent` and `furnace deploy`, not just `furnace create`.
+- `addCustomElementRegistration` and its regex fallback both accept the new marker as an optional parameter; the AST idempotency check and the regex-fallback idempotency check share a single helper (`isTagAlreadyRegistered`).
+
+### Furnace `--localized`
+
+- `furnace create --localized` now emits the Mozilla-idiomatic `MozLitElement` l10n pattern: a module-level `window.MozXULElement?.insertFTLIfNeeded("<chrome-uri>")` call and `this.ownerDocument.l10n?.connectRoot(this.shadowRoot)` / `disconnectRoot` in `connectedCallback` / `disconnectedCallback`. Previously the template called `this.insertFTLIfNeeded(...)` directly on a `MozLitElement` instance, which throws `TypeError: this.insertFTLIfNeeded is not a function` at every connect because that method lives on `MozXULElement`, not `MozLitElement`. The `--localized` path was silently non-functional.
+- `furnace apply` now registers the scaffolded `.ftl` in the locale jar.mn (default `toolkit/locales/jar.mn`) so the chrome URI `insertFTLIfNeeded` expects actually resolves at runtime. Previously only the `.ftl` file itself was copied into the FTL tree, with no chrome registration. `furnace remove` and the workspace-delete codepath (`undeployCustomFiles`) drop the jar.mn entry symmetrically.
+- The locale jar.mn write degrades gracefully — a missing target (non-standard fork tree) surfaces a structured step error rather than aborting apply, so a well-formed `.mjs`/`.css` is never blocked by a broken locale path.
+- FTL chrome URIs are now derived from `furnace.json.ftlBasePath` via a pair of helpers (`resolveFtlChromeSubPath`, `resolveFtlLocaleJarMnPath`) so forks that customise the FTL tree get matching `insertFTLIfNeeded` and jar.mn output.
+
+### Furnace validate
+
+- `missing-token-link` now reads `tokenHostDocuments` from furnace.json and scans every configured chrome document for the tokens CSS link. Warning fires only when NONE of them link the tokens CSS; the warning enumerates the documents it actually checked. Previously the check was hardcoded to `browser/base/content/browser.xhtml`, which false-positived on forks that mount components in a different chrome document (e.g. `hominis.xhtml`). Defaults to `["browser/base/content/browser.xhtml"]` when omitted — behaviour is unchanged for projects that never set the field.
+- `no-keyboard-handler` no longer warns when `@click` sits on a native interactive element (`<button>`, `<a href>`, `<input>`, `<select>`, `<textarea>`, `<summary>`, `<details>`, or the Firefox `moz-button`/`moz-toggle`/`moz-checkbox`/`moz-radio`/`moz-menulist` widgets). Those elements dispatch `click` on Enter and Space via the platform, so a duplicate `@keydown`/`@keypress` handler would double-fire. The rule still fires for synthetic interactive markup (e.g. `<div @click>`) and for bare `<a>` without an `href` attribute, which are the real keyboard-a11y hazards.
+
+### Run / test
+
+- `fireforge run`, `fireforge watch`, `fireforge build`, and every other `mach` invocation launched with inherited stdio now forward parent `SIGINT`/`SIGTERM` to the child as `SIGTERM` and wait ~1.5 s before escalating to `SIGKILL`. A second Ctrl-C during the grace window escalates immediately (matches the usual "hit Ctrl-C twice to force-quit" UX). Previously the parent could exit before Gecko's `AsyncShutdown` / `profileBeforeChange` blockers finished flushing in-memory state, losing the last few seconds of edits. The grace window is configurable via a new `shutdownGraceMs` option on `execInherit` / `execInheritCapture`.
+- New `fireforge test --doctor` runs a short marionette handshake preflight before (optionally) invoking `mach test`. Spawns the built browser headless, opens a TCP socket to `127.0.0.1:2828`, waits for the handshake bytes, and reports PASS/FAIL with the tail of stderr on FAIL. When `--doctor` is supplied with no test paths, it exits after the preflight — a sub-minute way to tell "marionette wedged" apart from "test failed to discover" when `mach test` hangs for the full 360 s marionette timeout. When supplied with test paths, a FAIL preflight short-circuits before `mach test` runs.
+
+### Internal
+
+- Extracted `furnace-apply-ftl.ts`, `furnace-config-tokens.ts`, and `create-templates.ts` to keep apply / config / scaffolding files under the per-file LOC budget after the new features landed. `parseStringArray` is now exported from `furnace-config.ts` for cross-module reuse.
+- New `src/core/marionette-preflight.ts` owns the `--doctor` probe and its teardown semantics.
+- Test mocks for `furnace-registration.js` now cover the new `addLocaleFtlJarMnEntry` / `removeLocaleFtlJarMnEntry` exports; `config.js` mocks in apply-batch tests now cover `loadConfig` because the apply path reads `markerComment` from fireforge.json.
+
 ## 0.14.0
 
 ### Concurrency and atomicity

package/README.md

@@ -368,10 +368,29 @@ fireforge token --name "--my-color" --value "light-dark(#fff, #000)"
   "patchLint": {
     "checkJs": true,
     "rawColorAllowlist": ["hominis-tokens.css"]
-  }
+  },
+  "markerComment": "MYBROWSER"
 }
 ```
 
+**`markerComment`** (optional). Appended as a `  // <marker>:` suffix to every line FireForge writes into upstream Firefox source files (starting with `customElements.js`). Keeps fork modifications discoverable and makes re-apply idempotent without hand-tagging entries after each `furnace apply`. Reject list: empty strings, leading/trailing whitespace, newlines, `*/` (would close an enclosing block comment), control characters.
+
+**`furnace.json.tokenHostDocuments`** (optional). List of chrome XHTML documents the `missing-token-link` validator scans for the tokens CSS link. Forks with a second chrome host (e.g. `hominis.xhtml` alongside `browser.xhtml`) should list every document that may own the link — the rule fires only when NONE of them link the tokens CSS. Defaults to `["browser/base/content/browser.xhtml"]` when omitted.
+
+### `furnace create --localized` for `MozLitElement`
+
+`fireforge furnace create <tag> --localized` scaffolds a Fluent-ready component. The generated `.mjs` uses the Mozilla-idiomatic `MozLitElement` pattern: a module-level `window.MozXULElement?.insertFTLIfNeeded("<chrome-uri>")` plus `this.ownerDocument.l10n?.connectRoot(this.shadowRoot)` / `disconnectRoot` in `connectedCallback` / `disconnectedCallback`. The chrome URI derives from `furnace.json.ftlBasePath` (default `toolkit/locales/en-US/toolkit/global` → `toolkit/global/<tag>.ftl`). `furnace apply` registers the `.ftl` in the matching locale jar.mn (default `toolkit/locales/jar.mn`) so the chrome URI resolves at runtime. If the locale jar.mn is missing in your fork (non-standard tree), apply surfaces a structured step error instead of aborting — the `.mjs`/`.css` still ship.
+
+### `fireforge test --doctor`
+
+```bash
+# Sub-minute marionette handshake probe; bails out of mach test on FAIL
+fireforge test --doctor
+fireforge test --doctor browser/base/content/test/foo/browser_bar.js
+```
+
+Spawns the built browser headless, waits for a marionette handshake on `127.0.0.1:2828`, and reports PASS/FAIL with the tail of the browser's stderr on FAIL. Distinguishes "marionette wedged" (socket silent) from "mach test discovery failed" — both otherwise surface as a silent 360-second hang followed by `Passed: 0, Failed: 0`. Useful as a prefix on routine `fireforge test` invocations when marionette has been flaky.
+
 ## Roadmap
 
 Planned but not yet implemented:

package/dist/src/commands/furnace/create-templates.d.ts

@@ -0,0 +1,26 @@
+/**
+ * File-content templates for `fireforge furnace create`. Extracted from the
+ * command entrypoint so the generator is unit-testable in isolation and the
+ * command file stays under the per-file LOC budget.
+ */
+/**
+ * Generates the .mjs file content for a custom component.
+ *
+ * `MozLitElement` does NOT expose `insertFTLIfNeeded` — that method lives on
+ * `MozXULElement`. Calling it from `connectedCallback` on a Lit-based
+ * component throws `TypeError: this.insertFTLIfNeeded is not a function` at
+ * every connect. Upstream Firefox components (e.g. `moz-input-folder.mjs`)
+ * solve this with a module-level guarded call on `window.MozXULElement` and
+ * per-instance shadow-DOM Fluent attachment via `l10n.connectRoot`. We mirror
+ * that pattern here so `--localized` produces functional code.
+ *
+ * The FTL path mirrors the locale jar.mn entry that `furnace apply` writes:
+ * `<ftlChromeSubPath>/<name>.ftl`. For the default `toolkit/global` tree this
+ * yields `toolkit/global/<name>.ftl`, which matches the URI upstream toolkit
+ * widgets ship.
+ */
+export declare function generateMjsContent(name: string, className: string, description: string, localized: boolean, header: string, ftlChromeSubPath: string | undefined): string;
+/** Generates the .css file content for a custom component. */
+export declare function generateCssContent(header: string): string;
+/** Generates the .ftl file content for a custom component. */
+export declare function generateFtlContent(name: string, header: string): string;

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

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * File-content templates for `fireforge furnace create`. Extracted from the
+ * command entrypoint so the generator is unit-testable in isolation and the
+ * command file stays under the per-file LOC budget.
+ */
+/**
+ * Generates the .mjs file content for a custom component.
+ *
+ * `MozLitElement` does NOT expose `insertFTLIfNeeded` — that method lives on
+ * `MozXULElement`. Calling it from `connectedCallback` on a Lit-based
+ * component throws `TypeError: this.insertFTLIfNeeded is not a function` at
+ * every connect. Upstream Firefox components (e.g. `moz-input-folder.mjs`)
+ * solve this with a module-level guarded call on `window.MozXULElement` and
+ * per-instance shadow-DOM Fluent attachment via `l10n.connectRoot`. We mirror
+ * that pattern here so `--localized` produces functional code.
+ *
+ * The FTL path mirrors the locale jar.mn entry that `furnace apply` writes:
+ * `<ftlChromeSubPath>/<name>.ftl`. For the default `toolkit/global` tree this
+ * yields `toolkit/global/<name>.ftl`, which matches the URI upstream toolkit
+ * widgets ship.
+ */
+export function generateMjsContent(name, className, description, localized, header, ftlChromeSubPath) {
+    const ftlPath = ftlChromeSubPath !== undefined ? `${ftlChromeSubPath}/${name}.ftl` : `${name}.ftl`;
+    const ftlModulePreamble = localized
+        ? `
+window.MozXULElement?.insertFTLIfNeeded("${ftlPath}");
+`
+        : '';
+    const lifecycleHooks = localized
+        ? `
+  connectedCallback() {
+    super.connectedCallback();
+    this.ownerDocument.l10n?.connectRoot(this.shadowRoot);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.ownerDocument.l10n?.disconnectRoot(this.shadowRoot);
+  }
+`
+        : '';
+    return `${header}
+
+import { html } from "chrome://global/content/vendor/lit.all.mjs";
+import { MozLitElement } from "chrome://global/content/lit-utils.mjs";
+${ftlModulePreamble}
+/**
+ * ${description || name}
+ *
+ * @tagname ${name}
+ */
+class ${className} extends MozLitElement {
+  static properties = {};
+
+  constructor() {
+    super();
+  }
+${lifecycleHooks}
+  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. */
+export function generateCssContent(header) {
+    return `${header}
+
+:host {
+  display: block;
+}
+`;
+}
+/** Generates the .ftl file content for a custom component. */
+export function generateFtlContent(name, header) {
+    return `${header}
+
+## Strings for the ${name} component
+`;
+}
+//# sourceMappingURL=create-templates.js.map

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,7 @@ 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';
 async function loadAuthoringFurnaceConfig(projectRoot) {
     if (await furnaceConfigExists(projectRoot)) {
         return loadFurnaceConfig(projectRoot);
@@ -46,65 +47,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 +200,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 +245,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}`,
@@ -333,6 +275,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 +388,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) {
@@ -428,39 +413,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,6 +438,7 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
         paths,
         license,
         withTests,
+        ftlChromeSubPath,
         operationContext: ctx,
     }));
     // --- Success ---

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/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/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>;