@hominis/fireforge 0.14.0 → 0.15.2

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # 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. `"MYBROWSER"`) is appended as a `  // MYBROWSER:` 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. `mybrowser.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.
+- `token-prefix-violation` stops flagging component-owned runtime CSS custom properties. Previously every `var(--foo)` that did not match `tokenPrefix` was rejected as a design-token escape, even when the property was a per-frame state channel (`--cam-x`, `--tile-z`) both written and read by the component. Two relaxations ship together: (a) a new optional `runtimeVariables: string[]` field in `furnace.json` explicitly allowlists cross-component runtime channels (e.g. set in JS, read in the child's CSS); (b) variables that are both declared (`--foo: value;`) and consumed (`var(--foo)`) inside the same CSS file are auto-exempted — no config entry required. The same relaxations apply to the patch-stack lint. The violation message now calls out `runtimeVariables` as the third escape hatch alongside `tokenPrefix` and `tokenAllowlist`.
+- `hardcoded-text` narrowed from a bare `>…<` scan to three context-aware probes: text inside Lit `` html`…` `` template literals, string literals assigned via `.textContent = "…"` / `.innerHTML = "…"`, and XUL-attribute values set via `setAttribute("label"|"title"|"tooltiptext", "…")`. Previously the rule also matched JS comparisons (`if (x > 0 && y < 100)`), long diagnostic strings (`console.error("…")`), and identifier literals passed to `querySelector`, producing noise that trained authors to ignore validator warnings. The file-wide `// furnace-ignore: hardcoded-text` escape hatch is preserved.
+
+### 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.
+- `fireforge test --doctor` is now a cascade of six layered probes (engine-present → mach-available → python-available → profile-creatable → browser-spawns → marionette-handshake) with tight per-layer budgets. Previously the single 30 s socket poll gave the same generic "socket did not respond" diagnostic whether mach was missing, Python was unavailable, `/tmp` was not writable, or the browser binary crashed at startup — so operators had no lead on where to start debugging. Each layer now short-circuits with a `[layer N/6: <name>]`-prefixed detail message so the first broken layer is surfaced immediately, and a crashing browser is caught by a short settle window at layer 5 instead of wasting the full budget waiting for bytes that never come.
+
+### Furnace build
+
+- `fireforge build` already auto-applies Furnace components (via `prepareBuildEnvironment`) before the mach build step, but the behaviour was undocumented and silent — operators who edited `components/custom/` and then ran `fireforge build` could not distinguish "auto-apply wrote files" from "nothing changed". A loud `Furnace: source → engine sync wrote N component(s) before build (...)` banner now fires whenever apply wrote files, naming every component that was synced. The `fireforge build --help` description and help footer now call out that apply runs before the build step.
+
+### Furnace create
+
+- New `furnace create --xpcshell` flag scaffolds an xpcshell test harness alongside (or instead of) the browser-chrome mochitest that `--with-tests` already produces. xpcshell runs headless without a `tabbrowser`, so storage-layer / observer-driven / module-loading code on forks that do not mount the upstream browser chrome (no `openLinkIn` → `URILoadingHelper`) can be covered without the harness complaining about a missing tab strip. Writes `test_<name>_module_loads.js` and an `xpcshell.toml` manifest into `engine/browser/base/content/test/<binary-name>-xpcshell/<component-name>/`. Registration in `XPCSHELL_TESTS_MANIFESTS` is left to the operator — the moz.build that should own the entry depends on where the component lives.
+
+### 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.
+- Repo-wide scrub of fork-example mentions (`hominis.xhtml`, `HOMINIS` marker-comment examples, fixture tag names) in favour of a generic `mybrowser` / `MYBROWSER` placeholder. FireForge reads as fork-agnostic in docs and fixtures; the npm identity (`@hominis/fireforge`) is unchanged.
+
 ## 0.14.0
 
 ### Concurrency and atomicity
@@ -218,7 +261,7 @@
 ### General improvements
 
 - getPackageRoot up to this point expected hardcoded `@hominis/fireforge`, was changed to just the package name for potential forks and more flexibility when changing project name.
-- Some test generators were derived from early Hominis Browser fork additions, the references to Hominis have been replaced with generic naming.
+- Some test generators were derived from an early downstream fork; the fork-specific names have been replaced with generic naming so the templates apply to any Firefox fork.
 
 ### Build and Git reliability
 

package/README.md

@@ -298,7 +298,7 @@ fireforge furnace status                           # workspace vs engine drift
 fireforge furnace diff moz-button                  # unified diff against baseline
 ```
 
-`furnace deploy` validates components before applying. As always, errors block, warnings are advisory. `fireforge build` and `fireforge test --build` run apply automatically. Use `fireforge doctor --repair-furnace` if the engine gets out of sync.
+`furnace deploy` validates components before applying. As always, errors block, warnings are advisory. `fireforge build` and `fireforge test --build` run apply automatically — when apply wrote files during a build, the build prints a `Furnace: source → engine sync wrote N component(s) …` banner naming every component that was synced, so it is obvious whether engine/ was freshly updated. Use `fireforge doctor --repair-furnace` if the engine gets out of sync.
 
 ## Additional Commands
 
@@ -367,11 +367,49 @@ fireforge token --name "--my-color" --value "light-dark(#fff, #000)"
   "wire": { "subscriptDir": "browser/components/mybrowser" },
   "patchLint": {
     "checkJs": true,
-    "rawColorAllowlist": ["hominis-tokens.css"]
-  }
+    "rawColorAllowlist": ["mybrowser-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. `mybrowser.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.
+
+The probe is a cascade of six layered checks — engine-present → mach-available → python-available → profile-creatable → browser-spawns → marionette-handshake. Each failure is tagged `[layer N/6: <name>]` so the first broken layer is surfaced immediately instead of the whole cascade blocking on the final socket poll. When the browser binary crashes at startup (missing dylib, wrong CPU arch, corrupt profile) the cascade fails at layer 5 within the settle window, not after the full socket timeout.
+
+### Runtime CSS variables in Furnace
+
+Design tokens imported from the fork's palette are enforced by `tokenPrefix`, but some components write and read CSS custom properties as runtime state channels (`--cam-x` per frame, `--tile-z` from a hit-test observer). Two escape hatches exist:
+
+- **Auto-exempt** — a variable that is both declared (`--foo: 0;`) and consumed (`var(--foo)`) inside the same component's CSS file is recognised as a component-local runtime channel. No config entry required.
+- **`furnace.json.runtimeVariables`** — explicit allowlist for names that are _written_ in JS and _read_ in a different file's CSS (cross-component runtime channels that the CSS-only auto-exempt cannot see). Entries must start with `--`.
+
+Both rules compose with the existing `tokenPrefix` / `tokenAllowlist` checks and apply to both component validation and patch-stack lint.
+
+### Test harness options
+
+`fireforge furnace create --with-tests` scaffolds a **browser-chrome mochitest**. Use this when the component renders UI that depends on the tab strip (`openLinkIn` → `URILoadingHelper`, `gBrowser`, etc.).
+
+`fireforge furnace create --xpcshell` scaffolds an **xpcshell test harness** instead. Use this when the component's code path is storage-only, observer-driven, or module-loading logic that does not touch a `tabbrowser`. xpcshell runs headless without browser chrome, so forks without an upstream tab strip can still cover these paths. The scaffolder writes `test_<name>_module_loads.js` + `xpcshell.toml` into `engine/browser/base/content/test/<binary-name>-xpcshell/<component-name>/` and prints a note: registration in `XPCSHELL_TESTS_MANIFESTS` is the operator's call (the moz.build that should own the entry depends on where the component actually lives).
+
+The two flags can be combined — `--with-tests --xpcshell` writes both harnesses.
+
 ## Roadmap
 
 Planned but not yet implemented:

package/dist/src/commands/build.js

@@ -96,10 +96,21 @@ export async function buildCommand(projectRoot, options) {
 export function registerBuild(program, { getProjectRoot, withErrorHandling }) {
     program
         .command('build')
-        .description('Build the browser')
+        .description('Build the browser (auto-applies Furnace components first)')
         .option('--ui', 'Fast UI-only rebuild')
         .option('-j, --jobs <n>', 'Number of parallel jobs', parseJobCount)
         .option('--brand <name>', 'Build specific brand')
+        .addHelpText('after', [
+        '',
+        'Furnace apply runs automatically before the build step, so edits in',
+        'components/custom/ and components/overrides/ are propagated to the',
+        'engine/ tree every time. The command prints a banner listing the',
+        'components synced during the current invocation.',
+        '',
+        'If you want to preview the engine state without triggering a build,',
+        'run `fireforge furnace apply` directly. For source-change-driven',
+        'rebuild loops during development, use `fireforge watch`.',
+    ].join('\n'))
         .action(withErrorHandling(async (options) => {
         await buildCommand(getProjectRoot(), pickDefined(options));
     }));

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

@@ -0,0 +1,47 @@
+/**
+ * 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;
+/** Returns the canonical xpcshell test file basename for a component. */
+export declare function xpcshellTestFileName(name: string): string;
+/**
+ * Generates an xpcshell test file for a custom component.
+ *
+ * xpcshell tests run headless without a `tabbrowser`, so they suit
+ * storage/observer/module-loading code in forks that do not mount the
+ * upstream browser chrome (and therefore lack `openLinkIn` →
+ * `URILoadingHelper`). The scaffold imports the component module via
+ * `ChromeUtils.importESModule` and asserts the module resolves — enough
+ * to catch registration regressions without touching DOM rendering paths
+ * that xpcshell cannot execute.
+ */
+export declare function generateXpcshellTestContent(name: string, header: string): string;
+/**
+ * Generates an `xpcshell.toml` manifest for a custom component's test
+ * directory. Kept minimal — adding prefs, head.js, and support-files is
+ * left to the operator because those decisions depend on what the
+ * component actually touches (Services.storage, observer topics, etc.).
+ */
+export declare function generateXpcshellManifestContent(name: string, header: string): string;

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

@@ -0,0 +1,135 @@
+// 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
+`;
+}
+/** Returns the canonical xpcshell test file basename for a component. */
+export function xpcshellTestFileName(name) {
+    return `test_${name.replace(/-/g, '_')}_module_loads.js`;
+}
+/**
+ * Generates an xpcshell test file for a custom component.
+ *
+ * xpcshell tests run headless without a `tabbrowser`, so they suit
+ * storage/observer/module-loading code in forks that do not mount the
+ * upstream browser chrome (and therefore lack `openLinkIn` →
+ * `URILoadingHelper`). The scaffold imports the component module via
+ * `ChromeUtils.importESModule` and asserts the module resolves — enough
+ * to catch registration regressions without touching DOM rendering paths
+ * that xpcshell cannot execute.
+ */
+export function generateXpcshellTestContent(name, header) {
+    return `${header}
+
+"use strict";
+
+add_task(async function test_${name.replace(/-/g, '_')}_module_loads() {
+  // Module-load smoke check: resolves the ESM at its registered chrome URI.
+  // Replace or extend with storage-layer assertions as the component grows
+  // (Services.storage, observer topics, JSONFile, etc. are all available
+  // here without a tabbrowser).
+  const moduleUri = "chrome://global/content/elements/${name}.mjs";
+  const module = await ChromeUtils.importESModule(moduleUri);
+  Assert.ok(
+    module,
+    "${name}.mjs should load under xpcshell (storage-layer code path).",
+  );
+});
+`;
+}
+/**
+ * Generates an `xpcshell.toml` manifest for a custom component's test
+ * directory. Kept minimal — adding prefs, head.js, and support-files is
+ * left to the operator because those decisions depend on what the
+ * component actually touches (Services.storage, observer topics, etc.).
+ */
+export function generateXpcshellManifestContent(name, header) {
+    return `${header}
+
+[DEFAULT]
+head = ""
+
+["${xpcshellTestFileName(name)}"]
+`;
+}
+//# sourceMappingURL=create-templates.js.map

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

@@ -0,0 +1,27 @@
+/**
+ * xpcshell test-harness scaffolder for `fireforge furnace create --xpcshell`.
+ * Extracted from `create.ts` so the command entrypoint stays under the
+ * per-file LOC budget and the scaffolder is unit-testable in isolation.
+ */
+import { type RollbackJournal } from '../../core/furnace-rollback.js';
+import type { ProjectLicense } from '../../types/config.js';
+/**
+ * Scaffolds an xpcshell test harness for a newly created custom component.
+ *
+ * xpcshell is the appropriate harness for storage-layer code on forks
+ * without a `tabbrowser` (no `openLinkIn` → `URILoadingHelper`). Browser
+ * chrome mochitests require tabbrowser; xpcshell does not, so storage,
+ * observers, and ESM-loading logic can be covered headless.
+ *
+ * Writes `test_<name>_module_loads.js` and an `xpcshell.toml` manifest
+ * into `engine/browser/base/content/test/<binary-name>-xpcshell/
+ * <component-name>/`. moz.build registration is intentionally left to the
+ * operator — wiring an `XPCSHELL_TESTS_MANIFESTS` entry requires a
+ * deliberate choice about which moz.build should own it, and an
+ * auto-insertion that guessed wrong would be worse than a note.
+ */
+export declare function scaffoldXpcshellTestFiles(componentName: string, license: ProjectLicense, forgeConfig: {
+    binaryName: string;
+}, paths: {
+    engine: string;
+}, journal?: RollbackJournal): Promise<string[]>;

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

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * xpcshell test-harness scaffolder for `fireforge furnace create --xpcshell`.
+ * Extracted from `create.ts` so the command entrypoint stays under the
+ * per-file LOC budget and the scaffolder is unit-testable in isolation.
+ */
+import { join } from 'node:path';
+import { recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
+import { getLicenseHeader } from '../../core/license-headers.js';
+import { ensureDir, pathExists, writeText } from '../../utils/fs.js';
+import { warn } from '../../utils/logger.js';
+import { generateXpcshellManifestContent, generateXpcshellTestContent, xpcshellTestFileName, } from './create-templates.js';
+/**
+ * Scaffolds an xpcshell test harness for a newly created custom component.
+ *
+ * xpcshell is the appropriate harness for storage-layer code on forks
+ * without a `tabbrowser` (no `openLinkIn` → `URILoadingHelper`). Browser
+ * chrome mochitests require tabbrowser; xpcshell does not, so storage,
+ * observers, and ESM-loading logic can be covered headless.
+ *
+ * Writes `test_<name>_module_loads.js` and an `xpcshell.toml` manifest
+ * into `engine/browser/base/content/test/<binary-name>-xpcshell/
+ * <component-name>/`. moz.build registration is intentionally left to the
+ * operator — wiring an `XPCSHELL_TESTS_MANIFESTS` entry requires a
+ * deliberate choice about which moz.build should own it, and an
+ * auto-insertion that guessed wrong would be worse than a note.
+ */
+export async function scaffoldXpcshellTestFiles(componentName, license, forgeConfig, paths, journal) {
+    const parentDirName = `${forgeConfig.binaryName}-xpcshell`;
+    const testDir = join(paths.engine, 'browser/base/content/test', parentDirName, componentName);
+    if (journal && !(await pathExists(testDir))) {
+        recordCreatedDir(journal, testDir);
+    }
+    await ensureDir(testDir);
+    const jsHeader = getLicenseHeader(license, 'js');
+    const hashHeader = getLicenseHeader(license, 'hash');
+    const testFiles = [];
+    const testFileName = xpcshellTestFileName(componentName);
+    const testFilePath = join(testDir, testFileName);
+    if (journal)
+        await snapshotFile(journal, testFilePath);
+    await writeText(testFilePath, generateXpcshellTestContent(componentName, jsHeader));
+    testFiles.push(testFileName);
+    const manifestPath = join(testDir, 'xpcshell.toml');
+    if (journal)
+        await snapshotFile(journal, manifestPath);
+    await writeText(manifestPath, generateXpcshellManifestContent(componentName, hashHeader));
+    testFiles.push('xpcshell.toml');
+    warn(`xpcshell scaffold written under browser/base/content/test/${parentDirName}/${componentName}/. ` +
+        'Add the directory to XPCSHELL_TESTS_MANIFESTS in the nearest moz.build to run it via "fireforge test".');
+    return testFiles;
+}
+//# sourceMappingURL=create-xpcshell.js.map