@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,148 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/*
- * Packaging-verification test templates for
- * `fireforge furnace chrome-doc create --with-tests`.
- *
- * An operator who scaffolds a top-level chrome document wants to know "did
- * the file actually land in the packaged bundle?" before relying on it at
- * runtime. Both natural test harnesses have gaps for that question:
- *
- *   - xpcshell's `chrome://browser/*` URI registration lags what the real
- *     browser loads even with `firefox-appdir = "browser"` set, so
- *     `NetUtil.asyncFetch("chrome://browser/content/<name>.xhtml")` can fail
- *     with `NS_ERROR_FILE_NOT_FOUND` against a file that is correctly
- *     packaged.
- *   - Browser-chrome mochitests require a `tabbrowser`, which a
- *     fork-authored chrome doc that replaces `browser.xhtml` deliberately
- *     does not carry.
- *
- * This scaffold threads the needle by probing the filesystem directly:
- * `Services.dirsvc.get("XCurProcD", Ci.nsIFile)` returns the current process
- * directory (the browser app dir when `firefox-appdir = "browser"`), and the
- * packaged chrome layout for a jar.mn entry `content/browser/<name>.xhtml`
- * is stable across platforms at
- * `<AppDir>/chrome/browser/content/browser/<name>.xhtml` on an unpacked tree
- * (the default for `mach build` without `MOZ_CHROME_MULTILOCALE` / omnijar).
- * A tree that packs omni.ja would need a different probe. The scaffold notes
- * that out-of-scope case explicitly rather than silently producing a test
- * that fails on packed builds.
- */
-/**
- * Returns the canonical xpcshell test basename for a chrome doc packaging
- * check (`test_<name>_packaging.js`). Hyphens in `<name>` are preserved:
- * xpcshell permits them in file basenames even though the derived task
- * function names replace them with underscores.
- */
-export function chromeDocPackagingTestFileName(name) {
-    return `test_${name}_packaging.js`;
-}
-/**
- * Emits an xpcshell test that verifies the scaffolded chrome doc's
- * `.xhtml`, `-chrome.css`, and `.ftl` are all present under the packaged
- * app directory. Each assertion carries the exact probed path in its
- * failure message so an operator reading a red CI run knows which
- * jar.mn entry or build step dropped the file.
- */
-export function generateChromeDocPackagingTest(name, header) {
-    const taskSuffix = name.replace(/-/g, '_');
-    return `${header}
-
-"use strict";
-
-// Packaging verification for the "${name}" chrome document.
-//
-// Scope: reads the packaged tree under XCurProcD (the browser app dir
-// when firefox-appdir = "browser") and asserts that the three
-// scaffolded files landed where the jar.mn / jar.inc.mn / locales/jar.mn
-// entries promised. Does NOT go through chrome:// URI resolution —
-// xpcshell's chrome manifest set lags the real browser's even with
-// firefox-appdir = "browser", so NetUtil.asyncFetch on
-// chrome://browser/content/${name}.xhtml can fail with
-// NS_ERROR_FILE_NOT_FOUND against a file that IS packaged.
-//
-// Out of scope: builds that pack omni.ja (MOZ_CHROME_MULTILOCALE, some
-// release configs). The probe below assumes an unpacked tree, which is
-// what "mach build" produces by default. A packed build would need to
-// unzip omni.ja to verify the same files.
-
-add_task(async function test_${taskSuffix}_files_packaged() {
-  const appDir = Services.dirsvc.get("XCurProcD", Ci.nsIFile);
-
-  // Probes a pair of candidate layouts for the same packaged file:
-  //   1) \`<AppDir>/chrome/browser/…\` — the unpacked layout when XCurProcD
-  //      honours \`firefox-appdir = "browser"\` and resolves into
-  //      \`dist/bin/browser/\`.
-  //   2) \`<AppDir>/browser/chrome/browser/…\` — the macOS .app bundle layout
-  //      and some ESR configurations, where XCurProcD sits one level above
-  //      \`browser/\` even when the appdir directive is set.
-  // If either path exists the file is packaged; the assertion only fails
-  // when BOTH layouts miss, which is the actual stale-build / missing
-  // jar.mn entry case. A single-layout probe fails on macOS against layout
-  // (2) even though the file is packaged correctly.
-  function probeEither(primary, fallback, description) {
-    const primaryFile = appDir.clone();
-    for (const segment of primary) {
-      primaryFile.append(segment);
-    }
-    const fallbackFile = appDir.clone();
-    for (const segment of fallback) {
-      fallbackFile.append(segment);
-    }
-    const found = primaryFile.exists() ? primaryFile : fallbackFile.exists() ? fallbackFile : null;
-    Assert.ok(
-      found !== null,
-      description +
-        " missing at both " +
-        primaryFile.path +
-        " and " +
-        fallbackFile.path +
-        ' — run "fireforge build --ui" and retry. If one of those paths IS populated, the xpcshell harness is probing a stale build tree; the post-build audit should flag the same miss.',
-    );
-    if (found !== null) {
-      Assert.greater(
-        found.fileSize,
-        0,
-        description +
-          " is zero-length at " +
-          found.path +
-          " — packaging copied an empty file, check the source template.",
-      );
-    }
-  }
-
-  probeEither(
-    ["chrome", "browser", "content", "browser", "${name}.xhtml"],
-    ["browser", "chrome", "browser", "content", "browser", "${name}.xhtml"],
-    "${name}.xhtml",
-  );
-  // The scoped CSS is registered through jar.inc.mn under
-  // \`content/browser/<name>-chrome.css\` (see \`chromeDocJarIncMnCssEntry\`
-  // in \`src/commands/furnace/chrome-doc-templates.ts\`), so the packaged
-  // file lands under \`chrome/browser/content/browser/\`, not under
-  // \`skin/classic/browser/\`. Probing the skin layout reports a false
-  // failure on the first \`fireforge test --build\` after a scaffold.
-  probeEither(
-    ["chrome", "browser", "content", "browser", "${name}-chrome.css"],
-    ["browser", "chrome", "browser", "content", "browser", "${name}-chrome.css"],
-    "${name}-chrome.css",
-  );
-});
-`;
-}
-/**
- * Emits the `xpcshell.toml` manifest for the packaging test directory.
- * Sets `firefox-appdir = "browser"` so XCurProcD resolves to the browser
- * subdir rather than the generic gecko runtime dir. Without that, the
- * path probe walks the wrong tree on every fork whose app directory is
- * not the default.
- */
-export function generateChromeDocPackagingManifest(name, header) {
-    return `${header}
-
-[DEFAULT]
-head = ""
-firefox-appdir = "browser"
-
-["${chromeDocPackagingTestFileName(name)}"]
-`;
-}

package/dist/src/commands/furnace/chrome-doc.d.ts

@@ -1,87 +0,0 @@
-/**
- * `fireforge furnace chrome-doc create <name>` scaffolds a top-level
- * chrome document (xhtml + js + css + ftl + jar.mn registrations).
- *
- * `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 otherwise
- * 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 type { FurnaceLockWaitable } from '../../types/commands/index.js';
-/** Options for `furnace chrome-doc create`. */
-export interface FurnaceChromeDocCreateOptions extends FurnaceLockWaitable {
-    /**
-     * Emit the titlebar-buttonbox markup and leave platform window controls
-     * visible. Defaults to `true` because the common case is a full chrome
-     * document (not a frameless overlay). Frameless callers pass
-     * `--no-titlebar`.
-     */
-    titlebar?: boolean;
-    /**
-     * Scaffold an xpcshell packaging-verification test alongside the chrome
-     * document. The generated test probes `XCurProcD/chrome/browser/...` on
-     * disk rather than going through `chrome://` URI resolution, which
-     * bypasses xpcshell's limited browser-chrome manifest set, where
-     * `NetUtil.asyncFetch` returns `NS_ERROR_FILE_NOT_FOUND` against a file
-     * that is packaged. Registration in `XPCSHELL_TESTS_MANIFESTS` is left to
-     * the operator because the owning moz.build depends on the fork's layout.
-     */
-    withTests?: boolean;
-    /** Print the scaffold plan without writing files. */
-    dryRun?: boolean;
-    /**
-     * Emit the browser.xhtml-like main-window skeleton (`<html
-     * id="main-window">` with the `windowtype`/`chromehidden`/`persist`
-     * root attributes platform C++ reads before scripts run) instead of
-     * the generic dialog-shaped `<window>` document. Use for the document
-     * configured as the fork's main browser window
-     * (`tokenHostDocuments[0]` / the BROWSER_CHROME_URL target). Implies
-     * the titlebar markup.
-     */
-    browserWindow?: boolean;
-}
-/**
- * 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.
- */
-export declare function validateChromeDocName(name: string): void;
-export interface ChromeDocPlan {
-    files: string[];
-    dirs: string[];
-    jarEntries: Array<{
-        file: string;
-        entry: string;
-        present: boolean;
-    }>;
-    localeWildcardCapturesFtl: boolean;
-    testDir?: string;
-    testFiles: string[];
-}
-/** Builds the shared create/remove plan for a top-level chrome document. */
-export declare function buildChromeDocPlan(args: {
-    engineDir: string;
-    name: string;
-    withTests: boolean;
-    binaryName: string;
-    validateCreateConflicts?: boolean;
-    includeLocaleEntryWhenWildcard?: boolean;
-}): Promise<ChromeDocPlan>;
-/**
- * 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 declare function furnaceChromeDocCreateCommand(projectRoot: string, name: string, options?: FurnaceChromeDocCreateOptions): Promise<void>;

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

@@ -1,365 +0,0 @@
-// 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).
- *
- * `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 otherwise
- * 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 { furnaceConfigExists, loadFurnaceConfig } from '../../core/furnace-config.js';
-import { completeJournalRollback, runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
-import { assertFurnaceEngineReady } from '../../core/furnace-precondition.js';
-import { createRollbackJournal, recordCreatedDir, 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 { ensureDir, pathExists, readText, writeText } from '../../utils/fs.js';
-import { intro, note, outro, warn } from '../../utils/logger.js';
-import { generateBrowserWindowXhtml, generateChromeDocCss, generateChromeDocFtl, generateChromeDocJs, generateChromeDocXhtml, jarIncMnEntryForChromeDoc, jarMnEntriesForChromeDoc, localeJarMnEntryForChromeDoc, localesFtlWildcardCapturesScaffoldedName, } from './chrome-doc-templates.js';
-import { chromeDocPackagingTestFileName, generateChromeDocPackagingManifest, generateChromeDocPackagingTest, } from './chrome-doc-tests.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.
- */
-export 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');
-    }
-}
-/** Builds the shared create/remove plan for a top-level chrome document. */
-export async function buildChromeDocPlan(args) {
-    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');
-    const dirs = [contentDir, sharedThemeDir, localeDir];
-    const xhtmlPath = join(contentDir, `${args.name}.xhtml`);
-    if (args.validateCreateConflicts && (await pathExists(xhtmlPath))) {
-        throw new FurnaceError(`${args.name}.xhtml already exists at ${xhtmlPath}. Remove it or choose a different name.`);
-    }
-    const jarMnPath = join(args.engineDir, 'browser/base/jar.mn');
-    const jarIncMnPath = join(args.engineDir, 'browser/themes/shared/jar.inc.mn');
-    const localeJarMnPath = join(args.engineDir, 'browser/locales/jar.mn');
-    for (const requiredJarPath of [jarMnPath, jarIncMnPath, localeJarMnPath]) {
-        if (!(await pathExists(requiredJarPath))) {
-            throw new FurnaceError(`Required jar file ${requiredJarPath} does not exist; cannot register chrome-doc entry. Check that the fork's engine layout matches the expected browser/ and locales/ tree.`);
-        }
-    }
-    const [jarMn, jarIncMn, localeJarMn] = await Promise.all([
-        readText(jarMnPath),
-        readText(jarIncMnPath),
-        readText(localeJarMnPath),
-    ]);
-    const localeWildcardCapturesFtl = localesFtlWildcardCapturesScaffoldedName(localeJarMn);
-    const jarEntries = [];
-    for (const entry of jarMnEntriesForChromeDoc(args.name)) {
-        jarEntries.push({
-            file: 'browser/base/jar.mn',
-            entry,
-            present: jarMn.includes(entry),
-        });
-    }
-    const cssEntry = jarIncMnEntryForChromeDoc(args.name);
-    jarEntries.push({
-        file: 'browser/themes/shared/jar.inc.mn',
-        entry: cssEntry,
-        present: jarIncMn.includes(cssEntry),
-    });
-    if (!localeWildcardCapturesFtl || args.includeLocaleEntryWhenWildcard) {
-        const ftlEntry = localeJarMnEntryForChromeDoc(args.name);
-        jarEntries.push({
-            file: 'browser/locales/jar.mn',
-            entry: ftlEntry,
-            present: localeJarMn.includes(ftlEntry),
-        });
-    }
-    const files = [
-        `browser/base/content/${args.name}.xhtml`,
-        `browser/base/content/${args.name}.js`,
-        `browser/themes/shared/${args.name}-chrome.css`,
-        `browser/locales/en-US/browser/${args.name}.ftl`,
-    ];
-    const testFiles = [];
-    let testDir;
-    if (args.withTests) {
-        const testParentDir = `${args.binaryName}-xpcshell`;
-        testDir = `browser/base/content/test/${testParentDir}/${args.name}`;
-        testFiles.push(`${testDir}/${chromeDocPackagingTestFileName(args.name)}`, `${testDir}/xpcshell.toml`);
-    }
-    return {
-        files,
-        dirs,
-        jarEntries,
-        localeWildcardCapturesFtl,
-        ...(testDir ? { testDir } : {}),
-        testFiles,
-    };
-}
-function renderChromeDocCreateDryRun(name, plan) {
-    const dirLines = plan.dirs.map((dir) => `  ${dir}`);
-    const jarLines = plan.jarEntries.map(({ file, entry, present }) => `  engine/${file}: ${present ? 'already present' : 'would add'} ${entry.trim()}`);
-    const localeLine = plan.localeWildcardCapturesFtl
-        ? [
-            '',
-            'Locale jar.mn already has a [localization] wildcard that captures the FTL;',
-            'no per-file locale entry would be added.',
-        ]
-        : [];
-    const testLines = plan.testFiles.length > 0
-        ? [
-            '',
-            'Would create xpcshell packaging test files:',
-            ...plan.testFiles.map((f) => `  engine/${f}`),
-        ]
-        : [];
-    return [
-        `[dry-run] Chrome document "${name}" scaffold plan`,
-        '',
-        'Directories checked/created as needed:',
-        ...dirLines,
-        '',
-        'Would create source files:',
-        ...plan.files.map((f) => `  engine/${f}`),
-        ...testLines,
-        '',
-        'Jar registrations:',
-        ...jarLines,
-        ...localeLine,
-    ].join('\n');
-}
-/**
- * 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);
-                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, args.browserWindow
-            ? generateBrowserWindowXhtml(args.name, args.license)
-            : 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');
-        // Forks that have migrated to a `[localization] (%browser/**/*.ftl)`
-        // wildcard already pick up the scaffolded FTL automatically, so
-        // appending a per-file `locale/...` entry on top is at best dead weight
-        // and at worst a build error when the fork has dropped the
-        // `% locale browser` registration the per-file entry depends on. The
-        // wildcard predicate is narrow on purpose: only `%browser/`-rooted globs
-        // ending in `*.ftl` count as a capture.
-        if (await pathExists(localeJarMnPath)) {
-            const existingLocaleJar = await readText(localeJarMnPath);
-            if (localesFtlWildcardCapturesScaffoldedName(existingLocaleJar)) {
-                note(`Locale jar.mn already carries a [localization] wildcard that captures browser/${args.name}.ftl — skipping the per-file entry.`, args.name);
-            }
-            else {
-                await appendJarEntryIfAbsent(localeJarMnPath, localeJarMnEntryForChromeDoc(args.name), journal);
-            }
-        }
-        else {
-            // Preserve the existing "missing locale jar.mn" failure mode: pretend
-            // we still want to append so appendJarEntryIfAbsent surfaces the same
-            // FurnaceError it does for the other two jars. Forks that move the
-            // file deserve the same explicit complaint everywhere.
-            await appendJarEntryIfAbsent(localeJarMnPath, localeJarMnEntryForChromeDoc(args.name), journal);
-        }
-        written.push('browser/locales/jar.mn');
-        // --with-tests scaffolds an xpcshell packaging verification. All writes
-        // go through the same rollback journal so a SIGINT here restores the
-        // source files and jar.mn edits above alongside the test scaffold.
-        if (args.withTests) {
-            const testParentDir = `${args.binaryName}-xpcshell`;
-            const testDir = join(args.engineDir, 'browser/base/content/test', testParentDir, args.name);
-            if (!(await pathExists(testDir))) {
-                recordCreatedDir(journal, testDir);
-            }
-            await ensureDir(testDir);
-            const hashHeader = getLicenseHeader(args.license, 'hash');
-            const testFileName = chromeDocPackagingTestFileName(args.name);
-            const testFilePath = join(testDir, testFileName);
-            await snapshotFile(journal, testFilePath);
-            await writeText(testFilePath, generateChromeDocPackagingTest(args.name, jsHeader));
-            written.push(`browser/base/content/test/${testParentDir}/${args.name}/${testFileName}`);
-            const manifestPath = join(testDir, 'xpcshell.toml');
-            await snapshotFile(journal, manifestPath);
-            await writeText(manifestPath, generateChromeDocPackagingManifest(args.name, hashHeader));
-            written.push(`browser/base/content/test/${testParentDir}/${args.name}/xpcshell.toml`);
-        }
-    }
-    catch (error) {
-        return await completeJournalRollback(args.operationContext, journal, error, {
-            projectRoot: args.projectRoot,
-            operation: 'chrome-doc-rollback',
-            failureMessage: `Failed to scaffold chrome-doc "${args.name}"`,
-            subject: `chrome-doc "${args.name}"`,
-        });
-    }
-    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');
-    await assertFurnaceEngineReady(projectRoot, {
-        engineMissingSuffix: ' to scaffold a chrome-doc.',
-    });
-    const browserWindow = options.browserWindow ?? false;
-    // The browser-window skeleton always carries its own titlebar markup and
-    // chrome attributes. --no-titlebar only applies to the generic scaffold.
-    const withTitlebar = browserWindow ? true : (options.titlebar ?? true);
-    const withTests = options.withTests ?? false;
-    // Hint: when the scaffolded document is the configured token-host document
-    // (the fork's main browser window), the generic dialog-shaped scaffold is
-    // almost certainly wrong: correct jar.mn registrations, wrong document
-    // body.
-    if (!browserWindow && (await furnaceConfigExists(projectRoot))) {
-        try {
-            const furnaceConfig = await loadFurnaceConfig(projectRoot);
-            const targetDocPath = `browser/base/content/${name}.xhtml`;
-            if (furnaceConfig.tokenHostDocuments?.includes(targetDocPath)) {
-                warn(`${targetDocPath} is a configured token-host document (the fork's main browser window). ` +
-                    'The default scaffold emits a generic dialog-shaped <window> document; you probably ' +
-                    'want "fireforge furnace chrome-doc create --browser-window" for the ' +
-                    '<html id="main-window"> skeleton platform C++ expects.');
-            }
-        }
-        catch {
-            // A broken furnace.json must not block chrome-doc scaffolding. The
-            // hint is best-effort.
-        }
-    }
-    const plan = await buildChromeDocPlan({
-        engineDir,
-        name,
-        withTests,
-        binaryName: forgeConfig.binaryName,
-        validateCreateConflicts: true,
-    });
-    if (options.dryRun) {
-        note(renderChromeDocCreateDryRun(name, plan), name);
-        outro('Dry run complete');
-        return;
-    }
-    const written = await runFurnaceMutation(projectRoot, 'chrome-doc-rollback', (ctx) => performChromeDocMutations({
-        projectRoot,
-        name,
-        license,
-        engineDir,
-        withTitlebar,
-        withTests,
-        browserWindow,
-        binaryName: forgeConfig.binaryName,
-        operationContext: ctx,
-    }), waitLockMutationOptions(options.waitLockSeconds));
-    const nextSteps = [
-        `  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).',
-    ];
-    if (withTests) {
-        nextSteps.push(`  4. Register the xpcshell test directory in the nearest moz.build under`, `     XPCSHELL_TESTS_MANIFESTS, then run "fireforge test browser/base/content/test/${forgeConfig.binaryName}-xpcshell/${name}/xpcshell.toml".`);
-    }
-    nextSteps.push('', 'Platform-module compatibility: this chrome document carries the', `  data-furnace-chrome-doc="${name}" sentinel on its root element. Upstream`, '  platform modules (DevToolsStartup, PageActions, SessionStore, …) observe', '  "browser-delayed-startup-finished" and walk INTO the window assuming the', '  browser.xhtml DOM; use the sentinel attribute as a guard in fork-side', '  patches to those modules. See README "Platform module compatibility".');
-    note([
-        `Chrome document "${name}" scaffolded:`,
-        ...written.map((f) => `  engine/${f}`),
-        '',
-        'Next steps:',
-        ...nextSteps,
-    ].join('\n'), name);
-    outro('Chrome document created');
-}

package/dist/src/commands/furnace/create-browser-test.d.ts

@@ -1,44 +0,0 @@
-/**
- * Browser-chrome test scaffolding for `furnace create --with-tests`,
- * including the `--test-dir` redirect and collision safety (existing
- * manifests are appended to, and head.js and test implementations are never
- * overwritten). Split out of `create.ts` to keep that command file within
- * the per-file line budget.
- */
-import { type RollbackJournal } from '../../core/furnace-rollback.js';
-import type { ProjectLicense } from '../../types/config.js';
-import type { ResolvedTestStyle } from '../../types/furnace.js';
-/**
- * Validates the `--test-dir` option against the resolved test style before
- * any writes. Mochikit lives in the upstream toolkit/content/tests/widgets
- * tree, so a redirect makes no sense there.
- */
-export declare function resolveValidatedTestDir(rawTestDir: string | undefined, testStyle: ResolvedTestStyle): string | undefined;
-/**
- * Scaffolds browser mochitest files for a newly created custom component.
- * @param componentName - Custom element tag name
- * @param license - Project license used for generated headers
- * @param forgeConfig - Project config fields needed for test naming
- * @param paths - Resolved project paths used to place test files
- * @param journal - Optional rollback journal that snapshots files before writes
- * @returns Relative test filenames created or updated for the component
- */
-/**
- * Normalizes and validates a `--test-dir` override: engine-relative,
- * under `browser/base/content/test/` (so manifest registration keeps
- * working). Returns the normalized engine-relative directory.
- */
-export declare function resolveTestDirOverride(raw: string): string;
-/**
- * Writes the browser-mochitest scaffold for a component: the test file, its
- * `browser.toml` manifest entry, and the parent `moz.build` registration.
- *
- * Every write is recorded in `journal` when one is supplied, so a failure
- * partway through is rolled back rather than leaving a half-registered test
- * the harness will try to run.
- */
-export declare function scaffoldTestFiles(componentName: string, license: ProjectLicense, forgeConfig: {
-    binaryName: string;
-}, paths: {
-    engine: string;
-}, journal?: RollbackJournal, testDirOverride?: string): Promise<string[]>;