@hominis/fireforge 0.15.1 → 0.15.3

package/dist/src/commands/furnace/chrome-doc.js

@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge furnace chrome-doc create <name>` — scaffolds a top-level
+ * chrome document (xhtml + js + css + ftl + jar.mn registrations).
+ *
+ * Motivation: `furnace create` covers custom elements under
+ * `toolkit/content/widgets/`, but top-level chrome documents (the
+ * `mybrowser.xhtml`-class entry points a fork adds alongside or instead
+ * of `browser.xhtml`) are today hand-authored with error-prone jar.mn +
+ * jar.inc.mn + locales/jar.mn glue. The `*` preprocessor flag, the
+ * macOS titlebar-button carve-out, the startup-topic observer, and the
+ * Fluent linkage each have silent-break failure modes.
+ *
+ * This command writes the four source files and appends three jar.mn
+ * entries under a rollback journal identical in shape to `furnace create`.
+ * A SIGINT mid-scaffold restores every touched file; a successful run
+ * leaves the tree ready for `fireforge build`.
+ */
+import { join } from 'node:path';
+import { loadConfig } from '../../core/config.js';
+import { runFurnaceMutation } from '../../core/furnace-operation.js';
+import { createRollbackJournal, recordCreatedDir, restoreRollbackJournalOrThrow, snapshotFile, } from '../../core/furnace-rollback.js';
+import { DEFAULT_LICENSE, getLicenseHeader } from '../../core/license-headers.js';
+import { InvalidArgumentError } from '../../errors/base.js';
+import { FurnaceError } from '../../errors/furnace.js';
+import { pathExists, readText, writeText } from '../../utils/fs.js';
+import { intro, note, outro } from '../../utils/logger.js';
+import { generateChromeDocCss, generateChromeDocFtl, generateChromeDocJs, generateChromeDocXhtml, jarIncMnEntryForChromeDoc, jarMnEntriesForChromeDoc, localeJarMnEntryForChromeDoc, } from './chrome-doc-templates.js';
+/** Chrome-doc name shape: lowercase ASCII, optional hyphens, no leading digit. */
+const CHROME_DOC_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+/**
+ * Validates a chrome-doc name. Lowercase ASCII, optional hyphens, no
+ * leading digit — the name is used verbatim in CSS selectors, jar.mn
+ * entries, FTL keys, and file basenames, so anything outside that
+ * character set would break at least one downstream consumer.
+ * @param name Chrome-doc name (file basename without extension).
+ * @throws InvalidArgumentError when the name is unusable.
+ */
+function validateChromeDocName(name) {
+    if (!name.trim()) {
+        throw new InvalidArgumentError('Chrome-doc name is required', 'name');
+    }
+    if (!CHROME_DOC_NAME_PATTERN.test(name)) {
+        throw new InvalidArgumentError('Chrome-doc name must be lowercase ASCII, may contain hyphens, and must not start with a digit (e.g. mybrowser, about-onboarding).', 'name');
+    }
+}
+/**
+ * Appends a line to a jar.mn-style file when that exact line is not
+ * already present. Captures the pre-write contents in the journal so a
+ * mid-run interruption restores the file to its original state.
+ */
+async function appendJarEntryIfAbsent(filePath, entry, journal) {
+    if (!(await pathExists(filePath))) {
+        // Target jar.mn doesn't exist in this tree layout. We do NOT create it
+        // — a fork that moved the jar file needs the operator to choose a
+        // placement. The command surfaces this as a FurnaceError so the user
+        // can investigate rather than silently writing to a non-canonical path.
+        throw new FurnaceError(`Required jar file ${filePath} does not exist; cannot register chrome-doc entry. Check that the fork's engine layout matches the expected browser/ and locales/ tree.`);
+    }
+    const existing = await readText(filePath);
+    if (existing.includes(entry)) {
+        return;
+    }
+    await snapshotFile(journal, filePath);
+    const withEntry = existing.trimEnd() + '\n' + entry + '\n';
+    await writeText(filePath, withEntry);
+}
+/**
+ * Writes the xhtml/js/css/ftl source files plus the three jar.mn
+ * registrations under a rollback journal. Any interruption leaves the
+ * tree in its pre-command state.
+ */
+async function performChromeDocMutations(args) {
+    const journal = createRollbackJournal();
+    args.operationContext.registerJournal(journal);
+    // XHTML uses an inline XML comment since getLicenseHeader has no XML
+    // style — the SPDX convention is a single-line comment at the top.
+    const jsHeader = getLicenseHeader(args.license, 'js');
+    const cssHeader = getLicenseHeader(args.license, 'css');
+    const ftlHeader = getLicenseHeader(args.license, 'hash');
+    const written = [];
+    try {
+        const contentDir = join(args.engineDir, 'browser/base/content');
+        const sharedThemeDir = join(args.engineDir, 'browser/themes/shared');
+        const localeDir = join(args.engineDir, 'browser/locales/en-US/browser');
+        for (const dir of [contentDir, sharedThemeDir, localeDir]) {
+            if (!(await pathExists(dir))) {
+                recordCreatedDir(journal, dir);
+                const { ensureDir } = await import('../../utils/fs.js');
+                await ensureDir(dir);
+            }
+        }
+        const xhtmlPath = join(contentDir, `${args.name}.xhtml`);
+        if (await pathExists(xhtmlPath)) {
+            throw new FurnaceError(`${args.name}.xhtml already exists at ${xhtmlPath}. Remove it or choose a different name.`);
+        }
+        await snapshotFile(journal, xhtmlPath);
+        await writeText(xhtmlPath, generateChromeDocXhtml(args.name, args.withTitlebar, args.license));
+        written.push(`browser/base/content/${args.name}.xhtml`);
+        const jsPath = join(contentDir, `${args.name}.js`);
+        await snapshotFile(journal, jsPath);
+        await writeText(jsPath, generateChromeDocJs(args.name, jsHeader));
+        written.push(`browser/base/content/${args.name}.js`);
+        const cssPath = join(sharedThemeDir, `${args.name}-chrome.css`);
+        await snapshotFile(journal, cssPath);
+        await writeText(cssPath, generateChromeDocCss(args.name, args.withTitlebar, cssHeader));
+        written.push(`browser/themes/shared/${args.name}-chrome.css`);
+        const ftlPath = join(localeDir, `${args.name}.ftl`);
+        await snapshotFile(journal, ftlPath);
+        await writeText(ftlPath, generateChromeDocFtl(args.name, ftlHeader));
+        written.push(`browser/locales/en-US/browser/${args.name}.ftl`);
+        // jar.mn registrations — XHTML + JS go through the `*` preprocessor
+        // for brand substitution, CSS goes through jar.inc.mn, FTL through
+        // the locale jar.
+        const jarMnPath = join(args.engineDir, 'browser/base/jar.mn');
+        for (const entry of jarMnEntriesForChromeDoc(args.name)) {
+            await appendJarEntryIfAbsent(jarMnPath, entry, journal);
+        }
+        written.push('browser/base/jar.mn');
+        const jarIncMnPath = join(args.engineDir, 'browser/themes/shared/jar.inc.mn');
+        await appendJarEntryIfAbsent(jarIncMnPath, jarIncMnEntryForChromeDoc(args.name), journal);
+        written.push('browser/themes/shared/jar.inc.mn');
+        const localeJarMnPath = join(args.engineDir, 'browser/locales/jar.mn');
+        await appendJarEntryIfAbsent(localeJarMnPath, localeJarMnEntryForChromeDoc(args.name), journal);
+        written.push('browser/locales/jar.mn');
+    }
+    catch (error) {
+        await restoreRollbackJournalOrThrow(journal, `Failed to scaffold chrome-doc "${args.name}"`);
+        throw error;
+    }
+    return written;
+}
+/**
+ * Runs `furnace chrome-doc create <name>`.
+ * @param projectRoot Root directory of the project.
+ * @param name Chrome-doc name (e.g. `mybrowser`, `aboutonboarding`).
+ * @param options CLI-provided options.
+ */
+export async function furnaceChromeDocCreateCommand(projectRoot, name, options = {}) {
+    intro('Furnace chrome-doc create');
+    validateChromeDocName(name);
+    const forgeConfig = await loadConfig(projectRoot);
+    const license = forgeConfig.license ?? DEFAULT_LICENSE;
+    const engineDir = join(projectRoot, 'engine');
+    if (!(await pathExists(engineDir))) {
+        throw new FurnaceError('Engine directory not found. Run "fireforge download" first to scaffold a chrome-doc.');
+    }
+    const withTitlebar = options.titlebar ?? true;
+    const written = await runFurnaceMutation(projectRoot, 'chrome-doc-rollback', (ctx) => performChromeDocMutations({
+        name,
+        license,
+        engineDir,
+        withTitlebar,
+        operationContext: ctx,
+    }));
+    note([
+        `Chrome document "${name}" scaffolded:`,
+        ...written.map((f) => `  engine/${f}`),
+        '',
+        'Next steps:',
+        `  1. Edit engine/browser/base/content/${name}.xhtml and fill in the body.`,
+        `  2. Localize strings in engine/browser/locales/en-US/browser/${name}.ftl.`,
+        `  3. Run "fireforge build" to validate packaging (post-build audit will flag`,
+        '     any entry whose file does not land in the dist bundle).',
+    ].join('\n'), name);
+    outro('Chrome document created');
+}
+//# sourceMappingURL=chrome-doc.js.map

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

@@ -0,0 +1,30 @@
+/**
+ * MochiKit (chrome://mochikit) test-harness scaffolder for
+ * `fireforge furnace create --test-style=mochikit`.
+ *
+ * Motivation: browser-chrome mochitests require a `tabbrowser` to exist in
+ * the top-level chrome document. Forks with a bespoke chrome document
+ * (e.g. `mybrowser.xhtml`) that deliberately omits tabbrowser cannot run
+ * browser-chrome tests today. MochiKit tests load the component module
+ * directly via `chrome://global/` and assert against `customElements`, so
+ * they work against any fork that registers the upstream toolkit test
+ * manifest tree — including those without a tabbrowser.
+ */
+import { type RollbackJournal } from '../../core/furnace-rollback.js';
+import type { ProjectLicense } from '../../types/config.js';
+/**
+ * Scaffolds a MochiKit test for a newly created custom component under
+ * `engine/toolkit/content/tests/widgets/`. Mirrors the layout stock
+ * Firefox widgets (moz-button, moz-toggle, etc.) use, so an operator who
+ * already added the `widgets/` tree to their test-manifest registration
+ * picks the new test up automatically.
+ *
+ * Appends a per-test entry to the existing `chrome.toml` when present,
+ * writes a fresh `[DEFAULT]`-headed one otherwise. The caller is still
+ * responsible for ensuring the `toolkit/content/tests/widgets/chrome.toml`
+ * path is registered somewhere in the moz.build tree; most forks inherit
+ * this from upstream via `TEST_HARNESS_FILES += [...]`.
+ */
+export declare function scaffoldMochikitTestFiles(componentName: string, license: ProjectLicense, paths: {
+    engine: string;
+}, journal?: RollbackJournal): Promise<string[]>;

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

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * MochiKit (chrome://mochikit) test-harness scaffolder for
+ * `fireforge furnace create --test-style=mochikit`.
+ *
+ * Motivation: browser-chrome mochitests require a `tabbrowser` to exist in
+ * the top-level chrome document. Forks with a bespoke chrome document
+ * (e.g. `mybrowser.xhtml`) that deliberately omits tabbrowser cannot run
+ * browser-chrome tests today. MochiKit tests load the component module
+ * directly via `chrome://global/` and assert against `customElements`, so
+ * they work against any fork that registers the upstream toolkit test
+ * manifest tree — including those without a tabbrowser.
+ */
+import { join } from 'node:path';
+import { recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
+import { getLicenseHeader } from '../../core/license-headers.js';
+import { ensureDir, pathExists, readText, writeText } from '../../utils/fs.js';
+import { warn } from '../../utils/logger.js';
+import { generateMochikitChromeTomlEntry, generateMochikitChromeTomlSkeleton, generateMochikitTestContent, mochikitTestFileName, } from './create-templates.js';
+/**
+ * Scaffolds a MochiKit test for a newly created custom component under
+ * `engine/toolkit/content/tests/widgets/`. Mirrors the layout stock
+ * Firefox widgets (moz-button, moz-toggle, etc.) use, so an operator who
+ * already added the `widgets/` tree to their test-manifest registration
+ * picks the new test up automatically.
+ *
+ * Appends a per-test entry to the existing `chrome.toml` when present,
+ * writes a fresh `[DEFAULT]`-headed one otherwise. The caller is still
+ * responsible for ensuring the `toolkit/content/tests/widgets/chrome.toml`
+ * path is registered somewhere in the moz.build tree; most forks inherit
+ * this from upstream via `TEST_HARNESS_FILES += [...]`.
+ */
+export async function scaffoldMochikitTestFiles(componentName, license, paths, journal) {
+    const testDir = join(paths.engine, 'toolkit/content/tests/widgets');
+    if (journal && !(await pathExists(testDir))) {
+        recordCreatedDir(journal, testDir);
+    }
+    await ensureDir(testDir);
+    const hashHeader = getLicenseHeader(license, 'hash');
+    const writtenFiles = [];
+    const testFileName = mochikitTestFileName(componentName);
+    const testFilePath = join(testDir, testFileName);
+    if (journal)
+        await snapshotFile(journal, testFilePath);
+    await writeText(testFilePath, generateMochikitTestContent(componentName));
+    writtenFiles.push(testFileName);
+    // chrome.toml — append entry if the file already exists, otherwise write
+    // a fresh skeleton + entry. Idempotency: if the entry is already present
+    // the manifest is left untouched so re-runs don't double-register.
+    const manifestPath = join(testDir, 'chrome.toml');
+    const entry = generateMochikitChromeTomlEntry(componentName);
+    if (await pathExists(manifestPath)) {
+        const existing = await readText(manifestPath);
+        if (!existing.includes(`["${testFileName}"]`)) {
+            if (journal)
+                await snapshotFile(journal, manifestPath);
+            await writeText(manifestPath, existing.trimEnd() + '\n\n' + entry);
+        }
+    }
+    else {
+        if (journal)
+            await snapshotFile(journal, manifestPath);
+        await writeText(manifestPath, generateMochikitChromeTomlSkeleton(hashHeader) + entry);
+        writtenFiles.push('chrome.toml');
+    }
+    warn(`MochiKit scaffold written under toolkit/content/tests/widgets/. ` +
+        'Ensure `toolkit/content/tests/widgets/chrome.toml` is reachable from an existing test-harness registration (upstream TEST_HARNESS_FILES entries handle this by default).');
+    return writtenFiles;
+}
+//# sourceMappingURL=create-mochikit.js.map

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

@@ -24,3 +24,56 @@ export declare function generateMjsContent(name: string, className: string, desc
 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;
+/** Returns the canonical mochikit test file basename for a component. */
+export declare function mochikitTestFileName(name: string): string;
+/**
+ * Generates a MochiKit (chrome://mochikit) test for a custom component.
+ *
+ * MochiKit tests load the component module directly via the global chrome
+ * URI and assert that `customElements.get(<tag>)` returns a constructor.
+ * They run on forks whose top-level chrome document lacks a `tabbrowser`
+ * (the class of bug that forces `--xpcshell` for storage code) because
+ * they do not traverse `URILoadingHelper.openLinkIn`.
+ *
+ * The scaffold here is a smoke test — the component is defined and the
+ * constructor is a function. Real UI assertions (render output, l10n
+ * wiring, keyboard interactions) are intentionally left out because they
+ * depend on the component's shape; operators can extend the test using
+ * the same SimpleTest APIs upstream toolkit widgets (moz-button, etc.)
+ * rely on.
+ */
+export declare function generateMochikitTestContent(name: string): string;
+/**
+ * Generates the `chrome.toml` entry block to append for a newly scaffolded
+ * mochikit test. When the manifest already exists the caller appends this
+ * snippet; when absent, the caller writes a file that starts with a
+ * `[DEFAULT]` stanza followed by this block.
+ */
+export declare function generateMochikitChromeTomlEntry(name: string): string;
+/**
+ * Generates the minimal `chrome.toml` used when the file does not yet
+ * exist in the tree. Keeps the `[DEFAULT]` stanza empty so each scaffold
+ * adds its own per-test entry, matching the stock Firefox convention.
+ */
+export declare function generateMochikitChromeTomlSkeleton(header: string): string;

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

@@ -81,6 +81,124 @@ 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)}"]
+`;
+}
+/** Returns the canonical mochikit test file basename for a component. */
+export function mochikitTestFileName(name) {
+    return `test_${name}.html`;
+}
+/**
+ * Generates a MochiKit (chrome://mochikit) test for a custom component.
+ *
+ * MochiKit tests load the component module directly via the global chrome
+ * URI and assert that `customElements.get(<tag>)` returns a constructor.
+ * They run on forks whose top-level chrome document lacks a `tabbrowser`
+ * (the class of bug that forces `--xpcshell` for storage code) because
+ * they do not traverse `URILoadingHelper.openLinkIn`.
+ *
+ * The scaffold here is a smoke test — the component is defined and the
+ * constructor is a function. Real UI assertions (render output, l10n
+ * wiring, keyboard interactions) are intentionally left out because they
+ * depend on the component's shape; operators can extend the test using
+ * the same SimpleTest APIs upstream toolkit widgets (moz-button, etc.)
+ * rely on.
+ */
+export function generateMochikitTestContent(name) {
+    return `<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>Test the ${name} custom element</title>
+    <script src="chrome://mochikit/content/tests/SimpleTest/SimpleTest.js"></script>
+    <link rel="stylesheet" href="chrome://mochikit/content/tests/SimpleTest/test.css" />
+  </head>
+  <body>
+    <p id="display"></p>
+    <div id="content" style="display: none"></div>
+    <pre id="test"></pre>
+    <script type="module">
+      import "chrome://global/content/elements/${name}.mjs";
+
+      SimpleTest.waitForExplicitFinish();
+
+      add_task(async function test_${name.replace(/-/g, '_')}_defined() {
+        const ctor = await customElements.whenDefined("${name}");
+        ok(ctor, "${name} custom element should be defined");
+        is(typeof ctor, "function", "Constructor should be a function");
+      });
+    </script>
+  </body>
+</html>
+`;
+}
+/**
+ * Generates the `chrome.toml` entry block to append for a newly scaffolded
+ * mochikit test. When the manifest already exists the caller appends this
+ * snippet; when absent, the caller writes a file that starts with a
+ * `[DEFAULT]` stanza followed by this block.
+ */
+export function generateMochikitChromeTomlEntry(name) {
+    return `["${mochikitTestFileName(name)}"]\n`;
+}
+/**
+ * Generates the minimal `chrome.toml` used when the file does not yet
+ * exist in the tree. Keeps the `[DEFAULT]` stanza empty so each scaffold
+ * adds its own per-test entry, matching the stock Firefox convention.
+ */
+export function generateMochikitChromeTomlSkeleton(header) {
+    return `${header}
+
+[DEFAULT]
+
 `;
 }
 //# 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

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

@@ -1,4 +1,21 @@
 import type { FurnaceCreateOptions } from '../../types/commands/index.js';
+/** Resolved test-harness selection for a `furnace create` run. */
+export type ResolvedTestStyle = 'mochikit' | 'browser-chrome' | 'xpcshell' | 'none';
+/**
+ * Collapses `--with-tests`, `--xpcshell`, and `--test-style` into the single
+ * scaffold dispatch used inside the mutation phase.
+ *
+ * Backwards-compat invariants:
+ * - `--xpcshell` alone is equivalent to `--test-style=xpcshell`.
+ * - `--with-tests` alone (no `--test-style`) now defaults to `mochikit`
+ *   (previously it defaulted to browser-chrome; the dogfooding pass
+ *   flagged browser-chrome as unrunnable against non-tabbrowser chrome).
+ *   Operators who need the old behavior can pass
+ *   `--with-tests --test-style=browser-chrome`.
+ * - `--xpcshell --with-tests` is rejected as ambiguous.
+ * @throws InvalidArgumentError when flags conflict.
+ */
+export declare function resolveTestStyle(options: FurnaceCreateOptions): ResolvedTestStyle;
 /**
  * Runs the furnace create command to scaffold a new custom component.
  * @param projectRoot - Root directory of the project