@hominis/fireforge 0.15.9 → 0.16.0

package/dist/src/core/mach-mozconfig.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { MozconfigError } from '../errors/build.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { getPlatform } from '../utils/platform.js';
+import { BrandingMozconfigMismatchError } from './branding.js';
 /**
  * Replaces template variables in a string.
  * @param content - Content with ${variable} placeholders
@@ -16,6 +17,66 @@ function replaceVariables(content, variables) {
         .replace(/\$\{appId\}/g, variables.appId)
         .replace(/\$\{binaryName\}/g, variables.binaryName);
 }
+/**
+ * Matches an `--with-branding=<path>` directive anywhere in a rendered
+ * mozconfig. The directive form is the one mach reads; an optional
+ * `ac_add_options` prefix is the on-disk convention. `m` flag anchors the
+ * search per-line so a multi-line mozconfig with older directives earlier
+ * in the file doesn't confuse the extractor. We pick the LAST match
+ * because mach itself takes the last-write-wins semantics of shell
+ * configuration for overlapping `ac_add_options` calls.
+ */
+const WITH_BRANDING_PATTERN = /^\s*(?:ac_add_options\s+)?--with-branding\s*=\s*(\S+)/gm;
+/**
+ * Extracts the `--with-branding=<path>` value from a rendered mozconfig
+ * body. Returns `undefined` when no directive is present — callers treat
+ * that as "mozconfig is missing branding", which is itself an actionable
+ * configuration error.
+ *
+ * Exported for testing.
+ */
+export function extractWithBrandingPath(mozconfigContent) {
+    const matches = [...mozconfigContent.matchAll(WITH_BRANDING_PATTERN)];
+    const last = matches.at(-1);
+    return last?.[1];
+}
+/**
+ * Preflights the just-written mozconfig against the branding tree FireForge
+ * set up. A drift between the two is silent-corruption territory — the
+ * build runs, `mach configure` reads the stale directory name out of
+ * mozconfig, and then the recursive make backend errors out with a "path
+ * does not exist" message that names the branding dir the mozconfig
+ * referenced. By parsing the mozconfig here and comparing to
+ * `config.binaryName`, we turn that into a single-line actionable error
+ * before `mach` runs.
+ *
+ * @param engineDir Path to the engine directory (the branding tree lives here)
+ * @param mozconfigPath Path to the mozconfig just written
+ * @param config FireForge configuration (reads `binaryName`)
+ * @throws BrandingMozconfigMismatchError on drift or missing directive
+ */
+export async function assertBrandingMozconfigAgreement(engineDir, mozconfigPath, config) {
+    const mozconfigContent = await readText(mozconfigPath);
+    const found = extractWithBrandingPath(mozconfigContent);
+    const expected = `browser/branding/${config.binaryName}`;
+    if (!found) {
+        throw new BrandingMozconfigMismatchError(expected, '(no --with-branding directive)', 'mozconfig-missing-branding');
+    }
+    // Normalise both sides to forward slashes before compare — Windows-edited
+    // configs can carry backslash path separators that the build would treat
+    // as literal characters in a repo-relative path.
+    const normalizedFound = found.replace(/\\/g, '/');
+    if (normalizedFound !== expected) {
+        throw new BrandingMozconfigMismatchError(expected, found, 'name-mismatch');
+    }
+    // Last line of defence: even with matching names, a missing branding tree
+    // means the scaffold step hasn't run. Preflight here so the operator
+    // doesn't pay for a configure-through-build cycle to discover it.
+    const brandingMozBuild = join(engineDir, expected, 'moz.build');
+    if (!(await pathExists(brandingMozBuild))) {
+        throw new BrandingMozconfigMismatchError(expected, found, 'branding-dir-missing');
+    }
+}
 /**
  * Generates a mozconfig file from templates.
  * @param configsDir - Path to the configs directory
@@ -46,5 +107,10 @@ export async function generateMozconfig(configsDir, engineDir, config) {
     const platformContent = await readText(platformPath);
     content += `# Platform configuration (${platform})\n${replaceVariables(platformContent, variables)}`;
     await writeText(outputPath, content);
+    // Preflight: the mozconfig we just wrote must reference the branding
+    // directory FireForge actually set up. Catching the drift here (after the
+    // write, before anything consumes mozconfig) keeps `generateMozconfig`
+    // the single source of truth for both the render and the sanity-check.
+    await assertBrandingMozconfigAgreement(engineDir, outputPath, config);
 }
 //# sourceMappingURL=mach-mozconfig.js.map

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

@@ -1,5 +1,5 @@
 import { type SmokeLineCallback, type SmokeRunResult } from '../utils/process.js';
-export { attemptMozinfoRewrite, type BuildArtifactCheck, buildArtifactMismatchMessage, hasBuildArtifacts, type MozinfoRewriteResult, } from './mach-build-artifacts.js';
+export { attemptMozinfoRewrite, type BuildArtifactCheck, buildArtifactMismatchMessage, hasBuildArtifacts, hasRunnableBundle, type MozinfoRewriteResult, type RunnableBundleCheck, } from './mach-build-artifacts.js';
 export { generateMozconfig, type MozconfigVariables } from './mach-mozconfig.js';
 export { ensurePython, resetResolvedPython } from './mach-python.js';
 /**
@@ -111,6 +111,17 @@ export declare function runMachSmoke(args: string[], engineDir: string, options:
  * @returns Exit code
  */
 export declare function machPackage(engineDir: string): Promise<number>;
+/**
+ * Creates a distribution package while streaming output to the terminal
+ * and capturing the stderr tail for post-run diagnostics. Callers that
+ * want to consult {@link explainMachError} on failure should use this
+ * variant; the inherit-only `machPackage` above remains for callers that
+ * just need an exit code.
+ *
+ * @param engineDir - Path to the engine directory
+ * @returns Captured mach result (stdout tail, stderr tail, exit code)
+ */
+export declare function machPackageCapture(engineDir: string): Promise<MachCommandResult>;
 /**
  * Runs mach watch for auto-rebuilding.
  * @param engineDir - Path to the engine directory

package/dist/src/core/mach.js

@@ -7,7 +7,7 @@ import { exec, execInherit, execInheritCapture, execSmokeRun, execStream, } from
 import { explainMachError } from './mach-error-hints.js';
 import { getPython } from './mach-python.js';
 // Re-export sub-modules so existing `from './mach.js'` imports keep working.
-export { attemptMozinfoRewrite, buildArtifactMismatchMessage, hasBuildArtifacts, } from './mach-build-artifacts.js';
+export { attemptMozinfoRewrite, buildArtifactMismatchMessage, hasBuildArtifacts, hasRunnableBundle, } from './mach-build-artifacts.js';
 export { generateMozconfig } from './mach-mozconfig.js';
 export { ensurePython, resetResolvedPython } from './mach-python.js';
 /**
@@ -197,6 +197,19 @@ export async function runMachSmoke(args, engineDir, options) {
 export async function machPackage(engineDir) {
     return runMach(['package'], engineDir, { inherit: true });
 }
+/**
+ * Creates a distribution package while streaming output to the terminal
+ * and capturing the stderr tail for post-run diagnostics. Callers that
+ * want to consult {@link explainMachError} on failure should use this
+ * variant; the inherit-only `machPackage` above remains for callers that
+ * just need an exit code.
+ *
+ * @param engineDir - Path to the engine directory
+ * @returns Captured mach result (stdout tail, stderr tail, exit code)
+ */
+export async function machPackageCapture(engineDir) {
+    return runMachCapture(['package'], engineDir);
+}
 /**
  * Runs mach watch for auto-rebuilding.
  * @param engineDir - Path to the engine directory

package/dist/src/core/manifest-rules.js

@@ -16,7 +16,15 @@ export function getRules(binaryName) {
             extractArgs: (m) => [m[1] ?? ''],
         },
         {
-            pattern: /^browser\/base\/content\/(.+\.(?:js|mjs|xhtml|css))$/,
+            // `.inc.xhtml` fragments under browser/base/content/ are deliberately
+            // excluded: they are consumed via `#include` from a registered chrome
+            // document (typically browser.xhtml) and do not get their own
+            // packaged chrome URI. Before this carve-out, `status` flagged every
+            // wired fragment as "potentially unregistered" and `register --dry-run`
+            // proposed a bogus jar.mn entry. The lookahead blocks the match so
+            // `getUnregistrableAdvice` gets a chance to emit the correct
+            // guidance for the `.inc.xhtml` case.
+            pattern: /^browser\/base\/content\/(?!.+\.inc\.xhtml$)(.+\.(?:js|mjs|xhtml|css))$/,
             isRegistered: (engineDir, fileName) => isBrowserContentRegistered(engineDir, fileName),
             register: (engineDir, after, dryRun, fileName) => registerBrowserContent(engineDir, fileName, after, undefined, dryRun),
             extractArgs: (m) => [m[1] ?? ''],
@@ -98,6 +106,19 @@ function getUnregistrableAdvice(filePath) {
     if (filePath.endsWith('.ftl')) {
         return "FTL locale files are auto-discovered via jar.mn glob patterns and don't need manual registration.";
     }
+    // `.inc.xhtml` fragments live under browser/base/content/ but are
+    // consumed via `#include` from a registered chrome document (browser.xhtml
+    // by default; a fork's custom top-level doc when `wire --dom-target` is
+    // set). The preprocessor resolves the include at packaging time, so the
+    // fragment never needs its own chrome URI entry in jar.mn. Give the
+    // operator the actionable `wire` path instead of letting the generic
+    // "unknown file pattern" message above fire.
+    if (/^browser\/base\/content\/.+\.inc\.xhtml$/.test(filePath)) {
+        return ('`.inc.xhtml` fragments are consumed via `#include` from a registered chrome document ' +
+            '(e.g. browser.xhtml). They do not need an independent jar.mn entry — run ' +
+            '"fireforge wire <name> --dom <path>" to insert the #include, or add the directive manually ' +
+            'in the top-level chrome document.');
+    }
     const testMatch = filePath.match(/^browser\/base\/content\/test\/([^/]+)\/(?!browser\.toml$).+$/);
     if (testMatch) {
         const dir = testMatch[1];

package/dist/src/utils/fs.d.ts

@@ -78,6 +78,18 @@ export declare function writeFileAtomic(path: string, content: string | Buffer):
  * @param dest - Destination directory path
  */
 export declare function copyDir(src: string, dest: string): Promise<void>;
+/**
+ * Matches the atomic-temp-file shape emitted by `createAtomicTempPath`
+ * anywhere in a normalised (forward-slash) path. The `.fireforge-tmp-`
+ * marker plus a PID/UUID tail is unique to our own rename-based atomic
+ * writes, so callers (notably `status`) can filter these mid-flight
+ * artefacts out of their listings without racing the rename.
+ *
+ * Intentionally anchored so a legitimately-named backup file like
+ * `.notes.fireforge-tmp-backup` (no PID+UUID continuation) is NOT treated
+ * as one of our temps. The full shape is `.<filename>.fireforge-tmp-<pid>-<uuid>`.
+ */
+export declare const FIREFORGE_TMP_PATH_PATTERN: RegExp;
 /**
  * Checks available disk space at a path and warns via the provided
  * callback when it falls below `minBytes`.

package/dist/src/utils/fs.js

@@ -180,6 +180,18 @@ export async function copyDir(src, dest) {
         }
     }
 }
+/**
+ * Matches the atomic-temp-file shape emitted by `createAtomicTempPath`
+ * anywhere in a normalised (forward-slash) path. The `.fireforge-tmp-`
+ * marker plus a PID/UUID tail is unique to our own rename-based atomic
+ * writes, so callers (notably `status`) can filter these mid-flight
+ * artefacts out of their listings without racing the rename.
+ *
+ * Intentionally anchored so a legitimately-named backup file like
+ * `.notes.fireforge-tmp-backup` (no PID+UUID continuation) is NOT treated
+ * as one of our temps. The full shape is `.<filename>.fireforge-tmp-<pid>-<uuid>`.
+ */
+export const FIREFORGE_TMP_PATH_PATTERN = /(^|\/)\.[^/]+\.fireforge-tmp-\d+-[0-9a-f-]{36}$/i;
 /**
  * Generates a unique temp file path for atomic writes.
  *

package/dist/src/utils/paths.d.ts

@@ -1,5 +1,24 @@
 /** Converts Windows path separators to forward slashes for stable comparisons. */
 export declare function normalizePathSlashes(path: string): string;
+/**
+ * Strips a leading `engine/` (or `engine\\`) segment from a user-supplied
+ * path so the same command invocation accepts both repo-root-relative paths
+ * (`engine/browser/base/content/foo.js`) and engine-relative paths
+ * (`browser/base/content/foo.js`). The match is case-insensitive because
+ * default macOS and Windows filesystems treat `Engine/` and `engine/` as
+ * the same directory; a literal lowercase-only check previously left `mach`
+ * / the manifest writers resolving against a wrongly-cased prefix. Leading
+ * whitespace is ignored so tab-completed inputs don't slip past the strip.
+ *
+ * The return value is trimmed of the same leading whitespace when the
+ * prefix matched, and otherwise passed through verbatim — callers that
+ * care about internal whitespace can trim on their side.
+ *
+ * @param filePath Path as provided by the user
+ * @returns Path relative to the engine directory (or the original when the
+ *          prefix was absent)
+ */
+export declare function stripEnginePrefix(filePath: string): string;
 /** Checks whether a path is explicitly absolute on either POSIX or Windows. */
 export declare function isExplicitAbsolutePath(path: string): boolean;
 /** Resolves a candidate path and returns whether it stays within the given root. */

package/dist/src/utils/paths.js

@@ -2,10 +2,43 @@
 import { isAbsolute, relative, resolve } from 'node:path';
 const WINDOWS_ABSOLUTE_PATH = /^[a-zA-Z]:[\\/]/;
 const RELATIVE_PATH_ROOT = resolve('/__fireforge_path_root__');
+/**
+ * Matches a leading `engine/` or `engine\\` segment (case-insensitive,
+ * tolerates leading whitespace). Shared between `register`, `test`, `lint`,
+ * and `export` so every command that takes an engine-relative path accepts
+ * both the repo-root form (`engine/browser/...`) and the engine-relative
+ * form (`browser/...`) without diverging.
+ */
+const ENGINE_PREFIX_PATTERN = /^\s*engine[/\\]/i;
 /** Converts Windows path separators to forward slashes for stable comparisons. */
 export function normalizePathSlashes(path) {
     return path.replace(/\\/g, '/');
 }
+/**
+ * Strips a leading `engine/` (or `engine\\`) segment from a user-supplied
+ * path so the same command invocation accepts both repo-root-relative paths
+ * (`engine/browser/base/content/foo.js`) and engine-relative paths
+ * (`browser/base/content/foo.js`). The match is case-insensitive because
+ * default macOS and Windows filesystems treat `Engine/` and `engine/` as
+ * the same directory; a literal lowercase-only check previously left `mach`
+ * / the manifest writers resolving against a wrongly-cased prefix. Leading
+ * whitespace is ignored so tab-completed inputs don't slip past the strip.
+ *
+ * The return value is trimmed of the same leading whitespace when the
+ * prefix matched, and otherwise passed through verbatim — callers that
+ * care about internal whitespace can trim on their side.
+ *
+ * @param filePath Path as provided by the user
+ * @returns Path relative to the engine directory (or the original when the
+ *          prefix was absent)
+ */
+export function stripEnginePrefix(filePath) {
+    const match = ENGINE_PREFIX_PATTERN.exec(filePath);
+    if (match) {
+        return filePath.slice(match[0].length);
+    }
+    return filePath;
+}
 /** Checks whether a path is explicitly absolute on either POSIX or Windows. */
 export function isExplicitAbsolutePath(path) {
     return isAbsolute(path) || WINDOWS_ABSOLUTE_PATH.test(path);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.15.9",
+  "version": "0.16.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",