@hominis/fireforge 0.47.1 → 0.48.0

package/dist/src/types/commands/options.d.ts

@@ -85,6 +85,8 @@ export interface SetupOptions {
 export interface DownloadOptions {
     /** Force re-download, deleting existing engine/ */
     force?: boolean;
+    /** With `force`: skip the confirmation for an engine with changes to lose */
+    yes?: boolean;
 }
 /**
  * Options for the source command.
@@ -497,6 +499,13 @@ export interface RebaseOptions {
 export interface RunOptions {
     /** Additional arguments to pass to the browser */
     args?: string[];
+    /** Launch with this profile directory, passed to Firefox as `-profile`. */
+    profile?: string;
+    /**
+     * Launch with a fresh temporary profile, removed when the run ends.
+     * Implied by `smokeExit` unless `profile` is given.
+     */
+    tempProfile?: boolean;
     /**
      * Enable smoke-run mode. Launches the browser, streams the console,
      * sends SIGTERM to the whole process group after `smokeExit` seconds,
@@ -1115,4 +1124,10 @@ export interface LintCommandOptions {
      * {@link perPatch}.
      */
     report?: string;
+    /**
+     * With `--per-patch`: `'full'` (default) prints every NOTICE line;
+     * `'summary'` prints one line per check with its count and patch count.
+     * Errors and warnings always print in full.
+     */
+    notices?: 'summary' | 'full';
 }

package/dist/src/types/config.d.ts

@@ -355,6 +355,16 @@ export interface PatchLintConfig {
      * scope for the per-patch tier.
      */
     prettier?: PatchLintSeverityGate;
+    /**
+     * Which carriers the `forward-registration` queue rule checks for a line
+     * that names a file only a later patch creates. `'support-files'` (the
+     * default) checks test-manifest `support-files`. `'extended'` also checks
+     * jar.mn pair lines, moz.build path tokens, test-manifest sections and
+     * `head`, and customElements.js chrome URLs resolved through the queue's
+     * own jar.mn lines. Opt-in: a queue that predates the wider rule can carry
+     * such edges, and a new error on install would red its gate.
+     */
+    forwardRegistration?: 'support-files' | 'extended';
     /** Enforce JSDoc on class-method exports in patch-owned .sys.mjs files. Default: 'off'. */
     jsdocClassMethods?: PatchLintSeverityGate;
     /** Require ≥1 assertion in any patch-touched browser_*.js test file (new or modified). Default: 'off'. */

package/dist/src/utils/process-input.d.ts

@@ -0,0 +1,27 @@
+/** Options for {@link execWithInput}. */
+export interface ExecWithInputOptions {
+    /** Working directory for the command */
+    cwd?: string;
+    /** Environment variables merged over `process.env` */
+    env?: Record<string, string>;
+}
+/** Result of {@link execWithInput}: stdout stays raw bytes. */
+export interface ExecBufferResult {
+    /** Standard output, uncapped and undecoded */
+    stdout: Buffer;
+    /** Standard error, decoded as UTF-8 */
+    stderr: string;
+    /** Process exit code */
+    exitCode: number;
+}
+/**
+ * Runs a command, writes `input` to its stdin, and returns stdout as raw
+ * bytes. For batch protocols (`git cat-file --batch`) whose framing counts
+ * bytes: the decoded, 50 MB-capped collector `exec` uses would corrupt
+ * both. The caller bounds the input, and so the output.
+ * @param command - Command to execute
+ * @param args - Command arguments
+ * @param input - Bytes written to stdin, which is then closed
+ * @param options - Execution options
+ */
+export declare function execWithInput(command: string, args: string[], input: string | Buffer, options?: ExecWithInputOptions): Promise<ExecBufferResult>;

package/dist/src/utils/process-input.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Stdin-fed command execution with byte-exact stdout.
+ *
+ * Its own module rather than a function in `process.ts` only because that
+ * file sits on a 500-line budget. The logic belongs to the exec layer.
+ */
+import { spawn } from 'node:child_process';
+import { buildChildEnv } from './child-env.js';
+import { exitCodeFromClose } from './process.js';
+/**
+ * Runs a command, writes `input` to its stdin, and returns stdout as raw
+ * bytes. For batch protocols (`git cat-file --batch`) whose framing counts
+ * bytes: the decoded, 50 MB-capped collector `exec` uses would corrupt
+ * both. The caller bounds the input, and so the output.
+ * @param command - Command to execute
+ * @param args - Command arguments
+ * @param input - Bytes written to stdin, which is then closed
+ * @param options - Execution options
+ */
+export async function execWithInput(command, args, input, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: buildChildEnv(options),
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const out = [];
+        const err = [];
+        child.stdout.on('data', (chunk) => {
+            out.push(chunk);
+        });
+        child.stderr.on('data', (chunk) => {
+            err.push(chunk);
+        });
+        // A child that exits before reading all of stdin (a bad ref, say) makes
+        // the write fail with EPIPE. The close handler reports the real outcome.
+        child.stdin.on('error', () => undefined);
+        child.stdin.end(input);
+        child.on('error', reject);
+        child.on('close', (code, signal) => {
+            resolve({
+                stdout: Buffer.concat(out),
+                stderr: Buffer.concat(err).toString('utf8'),
+                exitCode: exitCodeFromClose(code, signal),
+            });
+        });
+    });
+}

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

@@ -104,6 +104,8 @@ export interface ProcessGroupOptions {
      */
     postCloseSweep?: () => Promise<void>;
 }
+/** A child's exit code, with a signal death mapped to 128 + its number. */
+export declare function exitCodeFromClose(code: number | null, signal: NodeJS.Signals | null): number;
 /**
  * Executes a command and returns its output.
  * @param command - Command to execute

package/dist/src/utils/process.js

@@ -77,7 +77,8 @@ function collectedOutput(out, err) {
         truncated: out.wasTruncated() || err.wasTruncated(),
     };
 }
-function exitCodeFromClose(code, signal) {
+/** A child's exit code, with a signal death mapped to 128 + its number. */
+export function exitCodeFromClose(code, signal) {
     if (code !== null) {
         return code;
     }

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

@@ -68,6 +68,17 @@ export declare function isJsonObject(value: JsonValue | undefined): value is Jso
  * Accepts formats like "140.9.0", "140.9.1", "140.9.0esr", "147.0b1"
  */
 export declare function isValidFirefoxVersion(version: string): boolean;
+/**
+ * Orders two Firefox version strings semantically: major, minor and patch
+ * numerically, with a beta (`153.0b7`) before the release it precedes
+ * (`153.0`). An `esr` suffix does not change the order: `153.3.0esr` and
+ * `153.3.0` compare equal, since the product says which line it is. A
+ * lexical sort, which this replaces in `rebase`, put `153.10.0esr` before
+ * `153.2.0esr` and `99.0` after `140.0esr`. A string that is not a Firefox
+ * version sorts after every one that is, then lexically.
+ * @returns Negative when `a` is older, positive when newer, 0 when equal
+ */
+export declare function compareFirefoxVersions(a: string, b: string): number;
 /**
  * Validates a release-candidate build directory name.
  * Accepts formats like "build1", "build2", "build12" (no leading zero).

package/dist/src/utils/validation.js

@@ -100,6 +100,49 @@ export function isValidFirefoxVersion(version) {
     // Beta: 147.0b1, 147.0b2
     return /^[1-9]\d{0,2}\.\d+(?:b[1-9]\d*|\.\d+(?:esr)?|esr)?$/.test(version);
 }
+/**
+ * Orders two Firefox version strings semantically: major, minor and patch
+ * numerically, with a beta (`153.0b7`) before the release it precedes
+ * (`153.0`). An `esr` suffix does not change the order: `153.3.0esr` and
+ * `153.3.0` compare equal, since the product says which line it is. A
+ * lexical sort, which this replaces in `rebase`, put `153.10.0esr` before
+ * `153.2.0esr` and `99.0` after `140.0esr`. A string that is not a Firefox
+ * version sorts after every one that is, then lexically.
+ * @returns Negative when `a` is older, positive when newer, 0 when equal
+ */
+export function compareFirefoxVersions(a, b) {
+    const left = parseFirefoxVersionOrder(a);
+    const right = parseFirefoxVersionOrder(b);
+    if (left === undefined || right === undefined) {
+        if (left !== undefined)
+            return -1;
+        if (right !== undefined)
+            return 1;
+        return a < b ? -1 : a > b ? 1 : 0;
+    }
+    for (let i = 0; i < left.length; i++) {
+        const delta = (left[i] ?? 0) - (right[i] ?? 0);
+        if (delta !== 0)
+            return delta;
+    }
+    return 0;
+}
+/**
+ * `[major, minor, patch, betaRank]`, where a release ranks above every beta
+ * of the same version.
+ */
+function parseFirefoxVersionOrder(version) {
+    const match = /^(\d+)\.(\d+)(?:\.(\d+))?(?:b(\d+))?(?:esr)?$/i.exec(version.trim());
+    if (!match)
+        return undefined;
+    const beta = match[4];
+    return [
+        Number(match[1]),
+        Number(match[2]),
+        Number(match[3] ?? 0),
+        beta === undefined ? Number.MAX_SAFE_INTEGER : Number(beta),
+    ];
+}
 /**
  * Validates a release-candidate build directory name.
  * Accepts formats like "build1", "build2", "build12" (no leading zero).

package/docs/configuration.md

@@ -59,6 +59,19 @@ tool at
 `/Applications/Xcode.app/Contents/Applications/Icon Composer.app/Contents/Executables/ictool`,
 plus `actool` via `xcrun`, `sips`, and `iconutil`.
 
+On macOS, `fireforge doctor` also checks that the bootstrapped clang
+(`~/.mozbuild/clang`, or under `MOZBUILD_STATE_PATH`) can link against the
+SDK the build will use. That is the SDK `engine/mozconfig` selects with
+`--with-macos-sdk`, resolved by sourcing the mozconfig the way mach does,
+or `xcrun --show-sdk-path` when it names none. The check links a trivial C
+program through the toolchain's lld in a temp directory. When that fails, it
+reports a warning with clang's first error and lists the SDKs installed
+under the mozbuild state directory, the Command Line Tools and the active
+Xcode. An Xcode update can ship an SDK the pinned toolchain cannot read, and
+`mach configure` then dies at its linker probe with nothing but `config.log`
+saying why. The check does nothing on other platforms and when no clang has
+been bootstrapped.
+
 ## `patchLint`
 
 Per-patch lint type-checks plain Firefox JS against a built-in
@@ -84,6 +97,28 @@ Firefox-globals shim that tracks upstream WebIDL additions per release.
   project's, then `npx --no-install`. Left at `'off'`, formatting is out of
   scope for the per-patch tier, and no other tier checks `.sys.mjs`
   formatting either.
+- `patchLint.forwardRegistration` (`'support-files'` or `'extended'`,
+  default `'support-files'`) picks which carriers the `forward-registration`
+  queue rule checks for a line naming a file that only a later patch
+  creates. The default checks test-manifest `support-files`. `'extended'`
+  also checks:
+  - jar.mn pair lines (the source in parentheses, relative to the jar.mn);
+  - moz.build path tokens (a quoted string with a `.` or `/`, relative to
+    the moz.build);
+  - test-manifest section headers and `head`;
+  - `customElements.js` `chrome://<pkg>/content/…` URLs, resolved through
+    the jar.mn lines the same queue adds.
+
+  A line whose target cannot be resolved without the build system is left
+  alone: a `%` or `@AB_CD@` substitution, `**`, `!`, a path that leaves the
+  tree, or a chrome URL no queue jar.mn line packages. Each finding prints
+  the same paste-and-run `patch staged-dependency --add --kind registration`
+  command as the `support-files` arm. The setting is opt-in because a queue
+  that predates it can carry many such edges, and a new error would red a
+  `--max-warnings 0` gate on install. The same census is on the public API as
+  `findForwardRegistrations(patchesDir, { scope })`, which defaults to
+  `'extended'`, for a consumer that keeps its own ratchet over these edges.
+
 - `patchLint.fileSizeThresholds` tunes the `file-too-large` line counts per
   file class:
 
@@ -105,6 +140,27 @@ Firefox-globals shim that tracks upstream WebIDL additions per release.
   is a hard failure rather than a soft limit, which is what these thresholds
   exist to let you move.
 
+## `typecheck`
+
+`typecheck.projects` lists the jsconfig files `fireforge typecheck` checks
+as whole projects. `typecheck.extraShim` and `typecheck.projectOverrides`
+add declarations to the Firefox-globals shim, for every project or for one.
+When `patchLint.checkJs` is on, the same command also runs the per-patch
+checkJs pass that `export` enforces, so a green `typecheck` means
+export-clean types.
+
+Each project keeps incremental build info in `.fireforge/typecheck/`, one
+file per project. A warm run re-checks only the files whose content changed
+since the last run. The file name carries a key over everything outside the
+program's own files that can change a verdict: the composed shim, the
+TypeScript version, the compiler options, `typecheck.undefinedIdentifiers`
+and the FireForge version. A change to any of them selects a new file, so a
+stale verdict is never replayed, and the project's other build-info files are
+deleted. `fireforge typecheck --no-cache` checks every project from scratch
+and neither reads nor writes the build info. A jsconfig's own `incremental`
+and `tsBuildInfoFile` are still ignored, so nothing is written under
+`engine/`.
+
 ## `patchPolicy`
 
 `patchPolicy.ranges` makes `patch compact` range-aware, so closing ordinal
@@ -225,6 +281,31 @@ non-CI launches print a warning saying so. Exit codes 12 and 13 separate a
 console regression from a launch failure. See
 [`exit-codes.md`](exit-codes.md).
 
+A smoke run starts on a fresh temporary profile by default (since 0.48.0).
+The step exists to prove what the build does on a clean start. The
+developer's `obj-*/tmp/profile-default` carries whatever the last session
+left (a pre-reset database, a restored hand-made applet), and those reds
+say nothing about the tree. FireForge creates the directory under the OS
+temp dir, seeds the two prefs `mach run` writes into profiles it makes
+itself (`browser.shell.checkDefaultBrowser` and
+`browser.aboutConfig.showWarning`), and passes it to Firefox as
+`-profile`. The directory is removed when the run ends. That includes a
+failed run and a SIGINT/SIGTERM, which the signal handler removes after
+the browser tree has shut down. A FireForge that was SIGKILLed cannot clean
+up after itself, so the next `run` removes any temporary profile whose
+owning process is gone.
+
+- `--profile <path>` launches with a named profile directory and leaves it
+  in place. Under `--smoke-exit` it replaces the fresh default.
+- `--temp-profile` gives a plain `run` the same fresh, removed-afterwards
+  profile.
+
+A plain `run` without either flag keeps mach's `profile-default`. `mach run`'s
+desktop parser has no `--profile` option (its `--profile/-P` belongs to the
+Android parser), so the profile is always passed as a program parameter.
+With an explicit profile, mach neither writes its `runprefs` from
+`~/.mozbuild/machrc` nor accepts `--setpref`.
+
 The allowlist (`--console-allow-file`) is count-blind by default: a line that
 matches an entry never counts, however often it fires. A `# max-hits: N`
 comment directly above an entry (other comments may sit between) caps how

package/docs/exit-codes.md

@@ -15,7 +15,7 @@ which error class produces each one.
 |    3 | `DOWNLOAD_ERROR`       | Could not download or extract Firefox source.                                                                                                 | `DownloadError` and subclasses                                                                    |
 |    4 | `GIT_ERROR`            | A git operation failed.                                                                                                                       | `GitError` and subclasses, except `GitNotFoundError`                                              |
 |    5 | `BUILD_ERROR`          | `mach build` failed, or a test suite went red.                                                                                                | `BuildError` and subclasses, `TestFailureError`                                                   |
-|    6 | `PATCH_ERROR`          | A patch failed to apply, or the patch queue could not be mutated.                                                                             | `PatchError`, `PatchManifestCorruptError`, `RebaseError` and subclasses                           |
+|    6 | `PATCH_ERROR`          | A patch failed to apply (including a patch `rebase --dry-run` predicts will reject), or the patch queue could not be mutated.                 | `PatchError`, `PatchManifestCorruptError`, `RebaseError` and subclasses                           |
 |    7 | `MISSING_DEPENDENCY`   | A required tool (python3, git, tar) was not found.                                                                                            | `PythonNotFoundError`, `GitNotFoundError`, `MachNotFoundError`                                    |
 |    8 | `INVALID_ARGUMENT`     | The flags were wrong. A usage problem, not an environment one.                                                                                | `InvalidArgumentError`, plus commander usage errors (unknown command or option, missing argument) |
 |    9 | `FURNACE_ERROR`        | A Furnace component operation failed.                                                                                                         | `FurnaceError`                                                                                    |

package/docs/lifecycle-invariants.md

@@ -190,9 +190,10 @@ command, read the decision table at the bottom first.
    stages and unstages for real. Each of those commands therefore runs its
    whole body inside `withPrivateGitIndex`, which seeds a temp
    `GIT_INDEX_FILE` from the repository's own index so that every refresh
-   lands there and is discarded. `typecheck` additionally forces
-   `incremental: false` and drops `tsBuildInfoFile`, so no sidecar is written
-   under `engine/`. The scope fails open, meaning an unresolvable git dir
+   lands there and is discarded. `typecheck` additionally ignores a
+   jsconfig's own `incremental` and `tsBuildInfoFile`, so no sidecar is
+   written under `engine/`. Its incremental build info (0.48.0) lives in the
+   project's `.fireforge/typecheck/`, outside the engine. The scope fails open, meaning an unresolvable git dir
    simply does not install it, and it is not reentrant. This exists so that
    invariant 8 stays evidential: a concurrent `fireforge test` must not be
    invalidated by FireForge's own read-only lane. Enforced by

package/docs/patch-workflow.md

@@ -81,11 +81,23 @@ slugs, and bare slugs.
 `lint --per-patch --max-warnings 0` is the warning-clean form for a release
 gate.
 
+`lint --per-patch --notices summary` prints one line per check in place of
+every NOTICE row, for example `NOTICE [large-patch-lines]: 180 across 172
+patch(es), 150 of them suppressed by lintIgnore (see --report)`. On a green
+queue those rows are reviewed waivers and under-threshold measurements, and
+there can be hundreds of them. The default, `--notices full`, prints them
+as before. Errors and warnings always print in full, and the `--report`
+JSON is the same in both modes.
+
 `lint --per-patch --report <path>` writes a machine-readable JSON report with
 each patch's line count, tier, active size thresholds, issues, and issues
 suppressed by `lintIgnore`. The size metrics (`countNonBinaryDiffLines`,
 `resolvePatchSizeTier`, `getPatchSizeThresholds`) are also exported on the
-programmatic API.
+programmatic API. So is `filesMeasuredByFileTooLarge(patchText)`, which
+returns the files `file-too-large` measures in a patch: the JS files it
+creates, and never a modified file or a new file of another kind. The rule
+selects its files through that same function, so an audit that uses it
+cannot drift from the rule.
 
 Per-patch lint type-checks plain Firefox JS against a built-in
 Firefox-globals shim that tracks upstream WebIDL additions per release. See
@@ -116,6 +128,28 @@ npx fireforge download --force
 npx fireforge rebase
 ```
 
+`download --force` is the destructive step of the three, not `rebase`. It
+replaces `engine/` wholesale, so applied patches, unexported edits and
+commits made in `engine/` are gone once the new tree is active. When the
+engine it is about to replace has changed paths against HEAD, or HEAD has
+moved off the recorded base commit, it names the loss (how many changed
+paths match the patch queue and how many do not) and asks first. A
+non-interactive run refuses unless `--yes` is given. A clean engine is
+replaced without a prompt.
+
+`npx fireforge rebase --dry-run` replays the queue onto the engine's HEAD
+without touching `engine/`. It seeds a private index from HEAD and applies
+each patch there with `git apply --cached`, in queue order, walking the same
+context-reduction ladder as the real run (exact, then `-C2`, `-C1`, `-C0`,
+bounded by `--max-fuzz`). Each patch is reported as `clean`, `reduced
+context` (with the step it needed) or `reject` (with the files git named).
+It exits 6 when anything rejects. A reject after an earlier one is marked
+as possibly cascading from it, since the replay continues without the
+rejected patch. Run it after the download, when HEAD is the new source. The
+header names the oldest patch stamp as "from", compared as versions rather
+than strings, prints the spread when the queue carries several stamps, and
+warns when `engine/` is not yet on the pinned version.
+
 If a patch fails, fix the reject inside `engine/`, then run
 `npx fireforge rebase --continue`. A rebase leaves the engine mutated on
 purpose, so its apply-and-persist pairs are held across a signal rather than

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.47.1",
+  "version": "0.48.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -75,9 +75,9 @@
     "eslint-plugin-simple-import-sort": "^14.0.0",
     "fast-check": "^4.6.0",
     "husky": "^9.1.7",
-    "knip": "6.35.1",
+    "knip": "6.37.0",
     "lint-staged": "^17.0.4",
-    "prettier": "3.9.6",
+    "prettier": "3.9.8",
     "tsx": "^4.7.0",
     "typescript": "~6.0.0",
     "typescript-eslint": "^8.0.0",
@@ -108,5 +108,9 @@
   "publishConfig": {
     "access": "public",
     "provenance": true
+  },
+  "allowScripts": {
+    "esbuild@0.28.1": true,
+    "fsevents@2.3.3": true
   }
 }