@hominis/fireforge 0.16.2 → 0.16.3

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

@@ -93,48 +93,102 @@ export function generateFtlContent(name, header) {
 }
 /** Returns the canonical xpcshell test file basename for a component. */
 export function xpcshellTestFileName(name) {
-    return `test_${name.replace(/-/g, '_')}_module_loads.js`;
+    return `test_${name.replace(/-/g, '_')}_packaged.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.
+ * xpcshell cannot execute a component module that imports
+ * `chrome://global/content/vendor/lit.all.mjs` — the Lit bundle touches
+ * `window` at module-load time and the xpcshell harness has no `window`
+ * global. Before 0.16.0 the scaffold called `ChromeUtils.importESModule`
+ * on the component's MJS, which reliably failed with
+ * `ReferenceError: window is not defined` for every Lit-based fork
+ * component. FireForge's diagnostics then misrouted the failure to the
+ * "stale build artifacts" branch, sending operators on a rebuild loop
+ * that couldn't fix a runtime-environment incompatibility.
+ *
+ * The rewrite here mirrors the chrome-doc packaging test: XCurProcD is
+ * probed at a pair of candidate layouts (dist/bin/browser and the macOS
+ * .app-bundle / ESR layout) to confirm the `.mjs` and `.css` files
+ * landed where jar.mn promised. That's the assertion xpcshell CAN make.
+ * Functional tests that need DOM/shadow-root/keyboard behaviour belong
+ * in a browser-chrome mochitest — scaffolded via
+ * `fireforge furnace create --test-style browser-chrome`.
  */
 export function generateXpcshellTestContent(name, header) {
+    const taskSuffix = name.replace(/-/g, '_');
     return `${header}
 
 "use strict";
 
-// Chrome-URI access from xpcshell:
-//   Toolkit chrome (chrome://global/*) IS registered and resolvable from
-//   this harness — that is what the smoke assertion below uses.
+// Packaging verification for the "${name}" custom component.
+//
+// Why this is not a module-load test:
+//   ChromeUtils.importESModule("chrome://global/content/elements/${name}.mjs")
+//   pulls in \`chrome://global/content/vendor/lit.all.mjs\`, which
+//   references \`window\` during its module body — there is no \`window\`
+//   global in xpcshell, so every attempt throws
+//   \`ReferenceError: window is not defined\`. For Lit-based components,
+//   xpcshell can only verify that the files reached the packaged tree;
+//   functional UI assertions belong in a browser-chrome mochitest
+//   (see \`fireforge furnace create --test-style browser-chrome\`).
 //
-//   Browser chrome (chrome://browser/*) is NOT registered unless the
-//   xpcshell.toml sets firefox-appdir = "browser" AND the built app bundle
-//   has landed every packaged chrome manifest. Even then, the set of
-//   manifests xpcshell loads lags what the real browser loads, so
-//   NetUtil.asyncFetch("chrome://browser/content/…") can still fail with
-//   NS_ERROR_FILE_NOT_FOUND against an artifact that IS present in
-//   obj-*/dist/. Assertions that need browser chrome URIs belong in a
-//   browser-chrome mochitest (fireforge furnace create --test-style=browser-chrome),
-//   not xpcshell.
-
-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).",
+// Out of scope: builds that pack omni.ja (MOZ_CHROME_MULTILOCALE, some
+// release configs). The probe 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);
+
+  // Two candidate layouts are probed per asset:
+  //   1) \`<AppDir>/chrome/global/elements/…\` — unpacked layout when
+  //      XCurProcD honours \`firefox-appdir = "browser"\` and resolves
+  //      into \`dist/bin/browser/\`.
+  //   2) \`<AppDir>/browser/chrome/global/elements/…\` — macOS .app
+  //      bundle and some ESR layouts where XCurProcD sits one level
+  //      above \`browser/\`.
+  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 the file IS present at one of those paths, xpcshell is probing a stale build tree.',
+    );
+    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", "global", "elements", "${name}.mjs"],
+    ["browser", "chrome", "global", "elements", "${name}.mjs"],
+    "${name}.mjs",
+  );
+  probeEither(
+    ["chrome", "global", "elements", "${name}.css"],
+    ["browser", "chrome", "global", "elements", "${name}.css"],
+    "${name}.css",
   );
 });
 `;

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

@@ -13,7 +13,7 @@ import type { ProjectLicense } from '../../types/config.js';
  * 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
+ * Writes `test_<name>_packaged.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

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

@@ -18,7 +18,7 @@ import { generateXpcshellManifestContent, generateXpcshellTestContent, xpcshellT
  * 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
+ * Writes `test_<name>_packaged.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

package/dist/src/commands/import.js

@@ -165,6 +165,32 @@ async function checkEngineDrift(engineDir, baseCommit, forceImport) {
     }
     return true;
 }
+/**
+ * Builds the set of patch filenames in scope when `--until <name>` is set.
+ * Accepts either the full filename (e.g. `001-foo.patch`) or the name
+ * without the `.patch` suffix (matching `applyPatchesWithContinue`'s
+ * `untilFilename` resolver).
+ *
+ * Returns an empty set when no match is found — the caller treats that as
+ * "no scope filter applies" so the import behaves identically to an
+ * unrecognised `--until` target (which `applyPatchesWithContinue` will
+ * later surface as a normal error).
+ */
+function buildUntilFilenameSet(patches, until) {
+    const set = new Set();
+    if (until === undefined)
+        return set;
+    const normalized = until.endsWith('.patch') ? until : `${until}.patch`;
+    const target = patches.find((p) => p.filename === until || p.filename === normalized);
+    if (!target)
+        return set;
+    for (const patch of patches) {
+        if (patch.order <= target.order) {
+            set.add(patch.filename);
+        }
+    }
+    return set;
+}
 /**
  * Runs the import command to apply patches.
  * @param projectRoot - Root directory of the project
@@ -200,20 +226,41 @@ export async function importCommand(projectRoot, options = {}) {
         outro('Import complete (no patches)');
         return;
     }
-    info(`Found ${patchCount} patch${patchCount === 1 ? '' : 'es'} to apply`);
+    // Load manifest early so we can scope the integrity / consistency checks to
+    // the `--until` subset. The manifest-consistency check stays global because
+    // structural manifest corruption (missing / duplicate rows) should block any
+    // import regardless of scope, but per-patch integrity and files-affected
+    // issues are legitimately skippable when the operator has asked to stop at
+    // an earlier patch.
+    const manifest = await loadPatchesManifest(paths.patches);
+    const untilFilenameSet = buildUntilFilenameSet(manifest?.patches ?? [], options.until);
+    const scopedPatchCount = options.until !== undefined ? untilFilenameSet.size : patchCount;
+    info(`Found ${scopedPatchCount} patch${scopedPatchCount === 1 ? '' : 'es'} to apply${options.until !== undefined ? ` (up to ${options.until})` : ''}`);
     const manifestConsistencyIssues = await validatePatchesManifestConsistency(paths.patches);
-    if (manifestConsistencyIssues.length > 0) {
-        const issueSummary = manifestConsistencyIssues.map((issue) => issue.message).join('\n  ');
+    const scopedManifestIssues = options.until !== undefined
+        ? manifestConsistencyIssues.filter((issue) => 
+        // Global (manifest-level) issues have no specific filename to scope
+        // against — a missing or unparseable patches.json blocks any
+        // import. Per-patch issues only block when the patch is in scope.
+        issue.code === 'manifest-missing' ||
+            issue.code === 'manifest-invalid' ||
+            untilFilenameSet.has(issue.filename))
+        : manifestConsistencyIssues;
+    if (scopedManifestIssues.length > 0) {
+        const issueSummary = scopedManifestIssues.map((issue) => issue.message).join('\n  ');
         throw new GeneralError('Patch manifest consistency check failed. Repair patches/patches.json before importing.\n' +
             `  ${issueSummary}\n\n` +
             'Run "fireforge doctor --repair-patches-manifest" to rebuild the manifest from on-disk patch files.');
     }
-    // Load manifest and check version compatibility
-    const manifest = await loadPatchesManifest(paths.patches);
+    // Version compatibility warnings (advisory only)
     if (manifest) {
         const config = await loadConfig(projectRoot);
         const currentVersion = config.firefox.version;
         for (const patch of manifest.patches) {
+            // Scope the advisory warnings too: an operator running with --until
+            // doesn't need to see version warnings for patches outside the range.
+            if (options.until !== undefined && !untilFilenameSet.has(patch.filename))
+                continue;
             const warning = checkVersionCompatibility(patch.sourceEsrVersion, currentVersion);
             if (warning) {
                 warn(`${patch.filename}: ${warning}`);
@@ -225,7 +272,15 @@ export async function importCommand(projectRoot, options = {}) {
     // warn-and-continue behaviour hid the real root cause because import
     // would later fail during patch application with a secondary, unrelated
     // error that made diagnosis harder.
-    const integrityIssues = await validatePatchIntegrity(paths.patches, paths.engine);
+    //
+    // Scope the surfaced issues to the `--until` range: a later patch with
+    // integrity problems should not block importing an earlier good subset,
+    // which is exactly what operators reach for when the tail of the queue
+    // is broken and they want to keep working against an earlier checkpoint.
+    const allIntegrityIssues = await validatePatchIntegrity(paths.patches, paths.engine);
+    const integrityIssues = options.until !== undefined
+        ? allIntegrityIssues.filter((issue) => untilFilenameSet.has(issue.filename))
+        : allIntegrityIssues;
     if (integrityIssues.length > 0) {
         warn('\nPatch integrity issues detected:');
         for (const issue of integrityIssues) {
@@ -253,11 +308,8 @@ export async function importCommand(projectRoot, options = {}) {
     // Dry-run: list patches that would be applied and exit
     if (isDryRun) {
         if (manifest) {
-            const patches = options.until
-                ? manifest.patches.filter((p) => {
-                    const untilPatch = manifest.patches.find((u) => u.filename === options.until || u.filename === `${options.until}.patch`);
-                    return untilPatch ? p.order <= untilPatch.order : true;
-                })
+            const patches = options.until !== undefined
+                ? manifest.patches.filter((p) => untilFilenameSet.has(p.filename))
                 : manifest.patches;
             info(`\n[dry-run] Would apply ${patches.length} patch(es) in order:`);
             for (const patch of patches) {

package/dist/src/commands/patch/delete.js

@@ -114,7 +114,16 @@ export async function patchDeleteCommand(projectRoot, identifier, options = {})
     }
     const conflicts = dependents.length > 0
         ? {
-            reason: `${dependents.length} later patch(es) depend on files created by ${target.filename}`,
+            // Wording deliberately clarifies the *runtime* impact: `git apply`
+            // doesn't resolve imports and will succeed even when a later patch
+            // imports a file the target created (the eval observed this
+            // directly — forcing the delete and re-importing the remaining
+            // 20-patch queue was clean). The breakage surfaces at browser
+            // startup when `ChromeUtils.importESModule` can't locate the
+            // deleted module. Operators who deliberately plan to re-introduce
+            // the imported files (rename, refactor) need to know this is the
+            // impact model, not a patch-application failure.
+            reason: `${dependents.length} later patch(es) contain import statements that reference files created by ${target.filename}. Patch application itself will still succeed, but runtime imports will fail at browser startup until those files are re-introduced.`,
             details: dependents,
         }
         : null;

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

@@ -263,6 +263,59 @@ export function buildSetupConfig(inputs) {
         },
     };
 }
+/**
+ * Creates or updates the root `package.json` so its `license` field matches
+ * the project license selected during setup. When the file already exists we
+ * ONLY touch the `license` field — preserving `name`, `description`,
+ * `dependencies`, `scripts`, and every other author-editorial field the
+ * operator may have added. Without this sync, a `fireforge setup --force`
+ * that picked a new license left the old license in `package.json`, which
+ * then disagreed with `fireforge.json` (the motivating eval finding:
+ * setup rewrote fireforge.json but left the original package.json
+ * untouched, so the two files described different projects).
+ *
+ * Preserves the file's trailing newline state so a hand-edited
+ * `package.json` with a specific EOL convention is not silently
+ * re-normalised.
+ */
+async function syncRootPackageJson(projectRoot, license) {
+    const rootPackageJsonPath = join(projectRoot, 'package.json');
+    if (!(await pathExists(rootPackageJsonPath))) {
+        const rootPackageJson = {
+            private: true,
+            license,
+        };
+        await writeText(rootPackageJsonPath, JSON.stringify(rootPackageJson, null, 2) + '\n');
+        return;
+    }
+    const raw = await readText(rootPackageJsonPath);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // Malformed package.json is the operator's editorial responsibility to
+        // repair; rewriting it would risk clobbering hand-authored content that
+        // the parser happens to reject. Leave the file alone and rely on the
+        // doctor / lint paths that already surface invalid JSON.
+        return;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return;
+    }
+    // Treat the object as a typed shape with only the one field we modify.
+    // Keeping it narrowly typed rather than `Record<string, unknown>` avoids
+    // eslint's `dot-notation` / `noPropertyAccessFromIndexSignature`
+    // friction, and the rest of the package.json body is preserved via
+    // object spread at the write site so we don't lose author-editorial
+    // fields.
+    const packageJson = parsed;
+    if (packageJson.license === license) {
+        return;
+    }
+    const trailingNewline = raw.endsWith('\n') ? '\n' : '';
+    await writeText(rootPackageJsonPath, JSON.stringify({ ...packageJson, license }, null, 2) + trailingNewline);
+}
 /** Writes the initial project files produced by the setup workflow. */
 export async function writeSetupProjectFiles(projectRoot, config) {
     const paths = getProjectPaths(projectRoot);
@@ -291,13 +344,13 @@ export async function writeSetupProjectFiles(projectRoot, config) {
     else {
         await writeText(gitignorePath, requiredIgnores.join('\n') + '\n');
     }
-    const rootPackageJsonPath = join(projectRoot, 'package.json');
-    if (!(await pathExists(rootPackageJsonPath))) {
-        const rootPackageJson = {
-            private: true,
-            license: config.license,
-        };
-        await writeText(rootPackageJsonPath, JSON.stringify(rootPackageJson, null, 2) + '\n');
+    // FireForgeConfig types license as optional, but `buildSetupConfig` always
+    // fills it from the resolved setup inputs (which default to `EUPL-1.2`).
+    // Narrow explicitly so the helper takes a concrete license rather than
+    // widening its own signature for a field that is always set at this call
+    // site.
+    if (config.license !== undefined) {
+        await syncRootPackageJson(projectRoot, config.license);
     }
     const templatesDir = getTemplatesDir();
     if (config.license !== undefined) {

package/dist/src/commands/status.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { isBrandingManagedPath } from '../core/branding.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
-import { getStatusWithCodes, isGitRepository } from '../core/git.js';
+import { getHead, getStatusWithCodes, isGitRepository, isMissingHeadError } from '../core/git.js';
 import { getUntrackedFilesInDir } from '../core/git-status.js';
 import { isFileRegistered, matchesRegistrablePattern } from '../core/manifest-rules.js';
 import { buildOwnershipTable, renderOwnershipTable } from '../core/ownership-table.js';
@@ -262,6 +262,32 @@ async function renderJsonStatus(files, paths, projectRoot, binaryName) {
     }));
     process.stdout.write(JSON.stringify(output, null, 2) + '\n');
 }
+/**
+ * Detects the "unborn HEAD" aftermath of an interrupted `fireforge download`
+ * — git init succeeded but the initial Firefox source commit was never
+ * created, so every file in engine/ reads as untracked. On a ~600 MB
+ * Firefox tree this would flood the output with hundreds of thousands of
+ * entries and a truncation warning, which is technically correct but not
+ * actionable. Throws a `GeneralError` with a single recovery banner
+ * pointing at `fireforge download --force`. `raw` / `json` modes skip the
+ * banner so their consumers see the structural failure in error form
+ * only.
+ */
+async function assertEngineHasBaselineCommit(engineDir, options) {
+    try {
+        await getHead(engineDir);
+    }
+    catch (err) {
+        if (!isMissingHeadError(err))
+            throw err;
+        const guidance = 'Engine repository has no baseline commit yet — a previous "fireforge download" was interrupted before git created the initial Firefox source commit. Re-run "fireforge download --force" to recreate the baseline repository cleanly.';
+        if (!options.raw && !options.json) {
+            warn(guidance);
+            outro('Engine baseline missing — re-run download --force');
+        }
+        throw new GeneralError(guidance);
+    }
+}
 /**
  * Runs the status command to show modified files.
  * @param projectRoot - Root directory of the project
@@ -331,6 +357,7 @@ export async function statusCommand(projectRoot, options = {}) {
     if (!(await isGitRepository(paths.engine))) {
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }
+    await assertEngineHasBaselineCommit(paths.engine, options);
     const rawFiles = await getStatusWithCodes(paths.engine);
     const { entries: expanded, truncations } = await expandDirectoryEntries(rawFiles, paths.engine);
     // Strip atomic-write temp files (Finding #18) before every mode

package/dist/src/commands/test.js

@@ -36,8 +36,14 @@ function buildStaleBuildMessage() {
         'Re-run "fireforge build --ui" or "fireforge test --build" and then retry.');
 }
 function hasStaleBuildArtifactsSignal(output) {
+    // Deliberately narrow: only fire on branding-specific resource paths
+    // that are always a stale-artifact symptom. The earlier pattern also
+    // matched `resource:///modules/distribution.sys.mjs`, which surfaced on
+    // real packaging / module-resolution failures too (e.g. a fork's
+    // `HominisStore.sys.mjs` missing from the installed app dir after a
+    // successful build). That false-positive pushed operators toward
+    // "rebuild" advice for what was actually a module-registration issue.
     return (/chrome:\/\/branding\/locale\/brand\.properties/i.test(output) ||
-        /resource:\/\/\/modules\/distribution\.sys\.mjs/i.test(output) ||
         /browser\/branding\/[^/\s]+\/moz\.build/i.test(output));
 }
 // Detects the broader xpcshell symptom where every `resource:///modules/...`
@@ -87,15 +93,25 @@ function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted
     if (/UNKNOWN TEST\b/i.test(combinedOutput)) {
         throw new GeneralError(buildUnknownTestMessage(normalizedPaths));
     }
+    // Branding-specific stale-build signals keep priority over the broader
+    // xpcshell-appdir hint: when `chrome://branding/locale/brand.properties`
+    // fails to resolve, the fix really is "rebuild", not "pass --app-path".
+    // But the stale-build check is now narrower — it no longer matches
+    // `resource:///modules/distribution.sys.mjs` alone, which was producing
+    // false-positive rebuild advice on fork-custom module-load failures
+    // (the eval saw this for `HominisStore.sys.mjs`). Cases that once
+    // landed on `distribution.sys.mjs` fall through to xpcshell-appdir,
+    // which is the more useful diagnosis in practice for `Failed to load
+    // resource:///modules/…`.
     if (hasStaleBuildArtifactsSignal(combinedOutput)) {
         throw new GeneralError(buildStaleBuildMessage());
     }
-    if (hasMochitestHttp3ServerSignal(combinedOutput)) {
-        throw new GeneralError(buildMochitestHttp3ServerMessage());
-    }
     if (hasXpcshellAppdirSignal(combinedOutput)) {
         throw new GeneralError(buildXpcshellAppdirMessage(appdirInjectionAttempted));
     }
+    if (hasMochitestHttp3ServerSignal(combinedOutput)) {
+        throw new GeneralError(buildMochitestHttp3ServerMessage());
+    }
     if (/invalid filename/i.test(combinedOutput) ||
         /chrome:\/\/mochitests.*not found/i.test(combinedOutput)) {
         info('Hint: The test file may not be registered in browser.toml or jar.mn.');

package/dist/src/commands/token.js

@@ -117,7 +117,13 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
     // valid choices up-front. The runtime check in tokenAddCommand remains
     // as a defence-in-depth guard for programmatic callers that bypass
     // Commander's argument parsing.
-    new Option('--mode <mode>', 'Dark mode behavior')
+    // Description ends with `(required)` because Commander's
+    // `makeOptionMandatory` does not render a required marker in `--help`
+    // output — only `.requiredOption` does that, and switching to
+    // `.requiredOption` would lose the `.choices()` enforcement. The
+    // explicit suffix keeps the runtime validation AND surfaces required
+    // status in help alongside the other options that use `.requiredOption`.
+    new Option('--mode <mode>', 'Dark mode behavior (required)')
         .choices(['auto', 'static', 'override'])
         .makeOptionMandatory(true))
         .option('--description <desc>', 'Comment description for the CSS file')

package/dist/src/core/branding.d.ts

@@ -1,4 +1,5 @@
 import { FireForgeError } from '../errors/base.js';
+import type { ProjectLicense } from '../types/config.js';
 /**
  * Error thrown when branding operations fail.
  */
@@ -41,6 +42,15 @@ export interface BrandingConfig {
     appId: string;
     /** Binary/branding directory name (e.g., "mybrowser") */
     binaryName: string;
+    /**
+     * Project license (from fireforge.json). Used to stamp the generated
+     * `configure.sh`, `brand.properties`, and `brand.ftl` files with the
+     * matching header so `patch-lint` does not flag them for
+     * `missing-license-header` when the project is not MPL-2.0. Optional for
+     * backwards compatibility with pre-0.16 callers that did not thread the
+     * license through — falls back to {@link DEFAULT_LICENSE}.
+     */
+    license?: ProjectLicense;
 }
 /**
  * Sets up the custom branding directory for the browser.

package/dist/src/core/branding.js

@@ -4,6 +4,7 @@ import { FireForgeError } from '../errors/base.js';
 import { ExitCode } from '../errors/codes.js';
 import { copyDir, pathExists, readText, writeTextIfChanged } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
+import { DEFAULT_LICENSE, getLicenseHeader } from './license-headers.js';
 /**
  * Error thrown when branding operations fail.
  */
@@ -91,9 +92,8 @@ async function createConfigureScript(brandingDir, config) {
     await writeTextIfChanged(configureShPath, buildConfigureScriptContent(config));
 }
 function buildConfigureScriptContent(config) {
-    return `# This Source Code Form is subject to the terms of the Mozilla Public
-# License, v. 2.0. If a copy of the MPL was not distributed with this
-# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+    const header = getLicenseHeader(config.license ?? DEFAULT_LICENSE, 'hash');
+    return `${header}
 
 MOZ_APP_DISPLAYNAME="${escapeShellValue(config.name)}"
 MOZ_MACBUNDLE_ID="${escapeShellValue(config.appId)}"
@@ -111,9 +111,8 @@ async function updateBrandProperties(brandingDir, config) {
     await writeTextIfChanged(propsPath, buildBrandPropertiesContent(config));
 }
 function buildBrandPropertiesContent(config) {
-    return `# This Source Code Form is subject to the terms of the Mozilla Public
-# License, v. 2.0. If a copy of the MPL was not distributed with this
-# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+    const header = getLicenseHeader(config.license ?? DEFAULT_LICENSE, 'hash');
+    return `${header}
 
 brandShorterName=${escapePropertiesValue(config.name)}
 brandShortName=${escapePropertiesValue(config.name)}
@@ -132,9 +131,8 @@ async function updateBrandFtl(brandingDir, config) {
     await writeTextIfChanged(ftlPath, buildBrandFtlContent(config));
 }
 function buildBrandFtlContent(config) {
-    return `# This Source Code Form is subject to the terms of the Mozilla Public
-# License, v. 2.0. If a copy of the MPL was not distributed with this
-# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+    const header = getLicenseHeader(config.license ?? DEFAULT_LICENSE, 'hash');
+    return `${header}
 
 ## Brand names
 ##

package/dist/src/core/build-prepare.js

@@ -123,12 +123,19 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
     }
     // Clean stories before build to ensure they don't leak into production binary
     await cleanStories(paths.engine);
-    // Set up custom branding directory and patch moz.configure
+    // Set up custom branding directory and patch moz.configure. Thread the
+    // project license through so `buildConfigureScriptContent` /
+    // `buildBrandPropertiesContent` / `buildBrandFtlContent` stamp the
+    // generated files with a matching SPDX header — otherwise `patch-lint`
+    // flags them with `missing-license-header` on every subsequent export
+    // when the project is not MPL-2.0 (the eval finding: a 0BSD-licensed
+    // fork's first export failed `lint` on its own generated branding).
     const brandingConfig = {
         name: config.name,
         vendor: config.vendor,
         appId: config.appId,
         binaryName: config.binaryName,
+        ...(config.license !== undefined ? { license: config.license } : {}),
     };
     if (!(await isBrandingSetup(paths.engine, brandingConfig))) {
         const brandingSpinner = spinner('Setting up branding...');