@hominis/fireforge 0.48.0 → 0.49.1

package/dist/src/utils/process.js

@@ -4,6 +4,7 @@ import { constants as osConstants } from 'node:os';
 import { StringDecoder } from 'node:string_decoder';
 import { ExecTimeoutError } from '../errors/base.js';
 import { buildChildEnv } from './child-env.js';
+import { toError } from './errors.js';
 import { dispatchCompleteLines } from './line-dispatch.js';
 import { killProcessTree, sweepProcessGroup } from './process-group.js';
 // 50 MB cap per stream to prevent OOM. Large toolchain builds (e.g. Firefox, Chromium)
@@ -169,6 +170,7 @@ async function spawnTracked(spec) {
             ? installGracefulShutdownForwarder(child, spec.graceMs, killTarget)
             : undefined;
         const closure = trackChildClosure();
+        let rejection;
         child.on('error', (error) => {
             // Abort/startup failure: make sure a partially-started tree does not
             // outlive the dispatch (a mach dying at startup used to strand
@@ -176,15 +178,24 @@ async function spawnTracked(spec) {
             if (options.processGroup === true) {
                 killProcessTree(child, 'SIGKILL', usesProcessGroup);
             }
-            forwarder?.dispose();
-            closure.settle();
-            reject(toExecRejection(error, command, args, options.timeout, spec.rejectionOutput?.()));
+            // An abort emits error before close. Keep the dispatch tracked until
+            // the child closes and both teardown sweeps finish, including on timeout.
+            rejection = toExecRejection(error, command, args, options.timeout, spec.rejectionOutput?.());
         });
         child.on('close', (code, signal) => {
             forwarder?.dispose();
             const finish = () => {
                 closure.settle();
-                resolve(spec.result(code, signal));
+                if (rejection)
+                    reject(rejection);
+                else {
+                    try {
+                        resolve(spec.result(code, signal));
+                    }
+                    catch (error) {
+                        reject(toError(error));
+                    }
+                }
             };
             // Group sweep first (it takes the helpers that stayed in the group),
             // then the caller's own sweep (the ones that did not), then settle.
@@ -194,7 +205,7 @@ async function spawnTracked(spec) {
                     finish();
                     return;
                 }
-                sweep().then(finish, finish);
+                Promise.resolve().then(sweep).then(finish, finish);
             };
             if (groupPid !== undefined) {
                 sweepProcessGroup(groupPid).then(callerSweep, callerSweep);
@@ -265,8 +276,9 @@ const activeChildClosures = new Set();
  * Registers a child whose shutdown {@link waitForActiveChildShutdown} must
  * wait for, and returns the handle that deregisters it.
  *
- * @returns `settle()`. Call from both the child's `close` and `error`
- *   handlers so a dead child never holds the shutdown wait open
+ * @returns `settle()`. Call after child closure and required teardown finish.
+ *   An abort's `error` event does not prove closure; do not settle there.
+ *   A failed start may settle when no live child or teardown remains.
  */
 export function trackChildClosure() {
     let resolveClosed;

package/docs/configuration.md

@@ -149,17 +149,18 @@ 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/`.
+Project build info is written in `.fireforge/typecheck/`, outside `engine/`,
+with a key covering the shim, TypeScript version, compiler options and
+FireForge version. Diagnostics always use a fresh project
+program: prior incremental diagnostic state is never restored. Cached and
+`--no-cache` runs therefore check the same complete file set. `--no-cache`
+also disables build-info writes. A jsconfig's own `incremental` and
+`tsBuildInfoFile` remain ignored.
+
+Both project and per-patch checkJs provide Gecko DOM constructor
+`isInstance(value)` predicates with instance narrowing, plus
+`MouseEvent.MOZ_SOURCE_PEN`. These declarations retain normal DOM member
+checking; they do not turn constructors or instances into `any`.
 
 ## `patchPolicy`
 

package/docs/lifecycle-invariants.md

@@ -113,11 +113,15 @@ command, read the decision table at the bottom first.
    carry primary shebangs, and mach rebuilds them in-tree), and runs
    `mach configure` inside the tree so the configure-generated root files are
    regenerated against the tree's paths rather than keeping the primary's. It
-   then verifies exactly that set afterwards (config.status, backend.mk,
-   Makefile, config/autoconf.mk, via `findObjdirRelocationViolation`, pinned
-   by `mach-objdir-relocation.test.ts`). Nested Makefiles are products of the
-   verified config.status, and `.deps` build products are out of scope as
-   read-only staleness that the first in-tree rebuild corrects. Finally it
+   Before configure, relocation rewrites old-source symlinks, `.pp`/`.d`,
+   FasterMake and Cargo fingerprint metadata, and removes copied
+   `config.statusd/*/config.track` inventories. Those inventories contain
+   absolute WRITE destinations and must never be consumed from a clone.
+   Aliased objdirs or partial-config directories are refused. Afterwards
+   `findObjdirRelocationViolation` verifies config.status, backend.mk,
+   Makefile, config/autoconf.mk and every remaining objdir symlink for the
+   old source prefix. External toolchain links are allowed; source links
+   must no longer consult the old checkout. Finally it
    copies `last-build.json` so the in-tree stale-build gates anchor
    correctly.
 

package/docs/machine-output.md

@@ -86,15 +86,16 @@ moved.
 `FIREFORGE-VERDICT: FAIL reason=<reason>` uses a closed set
 (`FireforgeVerdictReason`, `src/commands/test-verdict.ts`):
 
-| Reason          | Meaning                                                                                                                                                                                                                                                                                                                                                           |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `crash`         | The harness or the browser died, so there is no trustworthy suite result.                                                                                                                                                                                                                                                                                         |
-| `no-tests`      | The run dispatched but nothing ran.                                                                                                                                                                                                                                                                                                                               |
-| `test-failures` | The suite ran and reported unexpected results.                                                                                                                                                                                                                                                                                                                    |
-| `preflight`     | The run was refused before the harness was reached.                                                                                                                                                                                                                                                                                                               |
-| `inconclusive`  | A result exists, but `engine/` moved under it, so the result was discarded.                                                                                                                                                                                                                                                                                       |
-| `lock-timeout`  | The run never started: the engine session lock stayed contended.                                                                                                                                                                                                                                                                                                  |
-| `killed`        | A signal terminated the run, or FireForge ended it because its parent process vanished. Written from the signal handler (or the parent-exit watchdog) so that a log tail always describes itself. A killed run must never be silent, or "killed", "still running" and "never started" all look alike. `signal=` names the cause: a signal name, or `parent-exit`. |
+| Reason              | Meaning                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `crash`             | The harness or the browser died, so there is no trustworthy suite result.                                                                                                                                                                                                                                                                                         |
+| `harness-arguments` | Profile or other harness argument setup failed before any tests could run; a rebuild is not the repair.                                                                                                                                                                                                                                                           |
+| `no-tests`          | The run dispatched but nothing ran.                                                                                                                                                                                                                                                                                                                               |
+| `test-failures`     | The suite ran and reported unexpected results.                                                                                                                                                                                                                                                                                                                    |
+| `preflight`         | The run was refused before the harness was reached.                                                                                                                                                                                                                                                                                                               |
+| `inconclusive`      | A result exists, but `engine/` moved under it or a perf run changed power source, so the result was discarded.                                                                                                                                                                                                                                                    |
+| `lock-timeout`      | The run never started: the engine session lock stayed contended.                                                                                                                                                                                                                                                                                                  |
+| `killed`            | A signal terminated the run, or FireForge ended it because its parent process vanished. Written from the signal handler (or the parent-exit watchdog) so that a log tail always describes itself. A killed run must never be silent, or "killed", "still running" and "never started" all look alike. `signal=` names the cause: a signal name, or `parent-exit`. |
 
 ### The additive `note=` key
 
@@ -109,20 +110,19 @@ unchanged and still comes from the closed set above, so a consumer that
 tokenises `key=value` pairs is unaffected, and a gate that names no class
 emits no `note=` at all. The classes are not a closed set and may grow, so
 consumers should treat an unrecognised one as opaque. Current values:
-`stale-browser`, `stale-browser-kill-failed`, `marionette-port-busy`,
+`browser-busy`, `stale-browser`, `stale-browser-kill-failed`, `marionette-port-busy`, `mochitest-port-busy`,
 `coverage-replaced`, `stale-build`, `stale-components`.
 
 ### The additive `shuffle=` key
 
-A `fireforge test --shuffle [seed]` run forwards mach's `--shuffle` (an
-unseeded shuffle of file order in the harness) and exports the seed FireForge
-drew or was given as `FIREFORGE_SHUFFLE_SEED` in the harness environment. The
-seed is appended to the verdict line as `shuffle=<seed>` on every emission
-form, so a red found by shuffling carries its own reproduction
-(`fireforge test --shuffle=<seed> …`) on the one line a pipe keeps. Reordering
-tasks _inside_ a file is harness code that reads the exported seed; FireForge
-owns the seed, the plumbing and the record. Absent when the run did not
-shuffle.
+A `fireforge test --shuffle [seed]` run records the seed used to permute
+FireForge's isolated path-argument shards. Repeating the seed and selection
+repeats that shard order. It also forwards native mach `--shuffle`, which
+randomizes files within an invocation without using this seed. `--no-shard`
+disables FireForge's seeded argument permutation. The seed is exported as
+`FIREFORGE_SHUFFLE_SEED` for custom in-file task code and appended as
+`shuffle=<seed>` to every verdict form. This field does not claim replayable
+native harness file order. Absent when shuffle was not requested.
 
 ### The additive `orphans-reaped=` key
 
@@ -141,3 +141,20 @@ A preflight refusal's own text is written to stdout before the verdict line,
 and into the run log, so the verdict stays the last stdout write while the
 reason survives both a redirect and a `tail`. See
 [`run-logs.md`](run-logs.md).
+
+### Additive host and perf keys
+
+`host-load=<number>` records the one-minute load at suite startup. Each suite
+also samples the highest CPU process before and after dispatch. A contention
+warning appends `host-cpu-warning=true`; the diagnostic names the process
+and measured CPU. These diagnostics annotate a test failure without changing
+its classifier reason.
+
+Perf runs append `power-source=ac|battery|unknown`. On macOS the source is
+read from `pmset -g ps`, so charging on AC is correctly `ac`. A known source
+transition appends `power-changed=true` and refuses the run as
+`reason=inconclusive`. The producer's sample JSON retains its fields and
+gains `fireforgeHost: { start, end, powerSourceChanged }`, where each host
+state includes `load`, `power` and an optional `topProcess` with CPU and
+command. Consumers should tolerate this additive object. Unknown power
+state is visible but never treated as a proven transition.

package/docs/patch-workflow.md

@@ -56,6 +56,21 @@ requested path produces no hunk. That is checked against the full requested
 list rather than the subset left after filtering, so nothing dropped upstream
 can pass as a silent success.
 
+An absent file originally created by a selected patch can be retired with
+repeatable `--expect-removed <path>` on scan-less re-export:
+
+```sh
+fireforge re-export 202 --refuse-adjacent-unmanaged --refuse-foreign-drift --expect browser/themes/shared/hominis/widgets.css --expect-removed browser/themes/shared/hominis/stop.svg
+```
+
+The removal must have exactly one selected owner, be absent from disk and
+engine HEAD, and have a `new file mode` section in that owner's patch.
+Every removal is validated before writes, in dry-run too. Other paths keep
+both refusal checks; retirement grants no unmanaged or foreign-drift
+exception. Removing every file would empty the patch and requires `patch
+drop` instead. `--expect-removed` cannot combine with `--scan`, `--files` or
+`--all`.
+
 ## Queue maintenance
 
 Under `fireforge patch`:

package/docs/testing.md

@@ -34,9 +34,59 @@ build, `test` fails before launching stale artifacts. Use `--build` to
 refresh, or `--allow-stale-build` only for intentional out-of-band rebuilds.
 
 `--build-only` packages mixed-harness paths once, and then each harness half
-can run without `--build`. `--extend-coverage` retains prior scoped coverage
-instead of replacing it. It is refused when the build anchor moved (engine
-HEAD, `engine/mozconfig`, or a previously fingerprinted packageable file).
+can run without `--build`. Scoped builds retain prior coverage automatically
+when engine HEAD, `engine/mozconfig` and recorded staging inputs outside the
+rebuilt scope are unchanged. Changed files explicitly included in this
+build are allowed. The fingerprints include test scripts and support files,
+not only packageable chrome sources. A failed anchor narrows the claim and
+prints the dropped paths; `--extend-coverage` instead refuses. Baselines
+without complete staging-input fingerprints require a new build before they
+can retain prior coverage.
+New dirty inputs outside the rebuilt scope invalidate retention conservatively,
+including shared fixtures outside test directories.
+
+When `patchLint.checkJs` and `patchLint.checkJsTestFiles` are enabled, named
+pre-test builds check the selected test scripts before deployment or mach.
+This includes new scripts not yet owned by an exported patch.
+
+### Shared browsers, ports and host state
+
+Browser ownership is checked before a pre-test deployment and before full
+or UI builds. A live or unreadable parent means busy, with its owner named
+when available. `--kill-stale-marionette` requires a dead parent plus harness
+arguments; a profile argument alone does not prove abandonment. A plain
+launchd-parented app remains unattributed and is not automatically killed.
+
+`test --wait-browser [seconds]` waits for this objdir's browser to exit;
+`test --wait-port [seconds]` waits for mochitest and Marionette listeners.
+`build --wait-browser [seconds]` queues a full or UI build behind the browser.
+Bare flags wait 60 seconds; explicit values accept 1–3600 seconds. They are
+independent of the FireForge lock budget. On expiry the normal preflight
+refusal and its remedy are preserved.
+
+Every suite samples host load and the highest CPU process before and after
+dispatch. Load at least 4 or a process at least 90% CPU produces a warning;
+verdicts include `host-load` and, when needed, `host-cpu-warning=true`.
+Perf runs include `power-source=ac|battery|unknown`; on macOS this comes from
+`pmset -g ps`, including charging on AC. Sample JSON gains a `fireforgeHost`
+object with start/end states and `powerSourceChanged`. A known power-source
+transition produces `FAIL reason=inconclusive power-changed=true`.
+Unknown power state is reported without inventing a transition.
+
+### Profile overlays
+
+Use repeatable `--profile-file source=relative/destination` to add files to
+the test profile, for example:
+
+```sh
+fireforge test --perf-samples sample.json --profile-file arm.css=chrome/userChrome.css browser/base/content/test/perf/browser_perf.js
+```
+
+The source resolves from the project root. Destinations must stay relative
+with no traversal. FireForge stages copies and merges only those staged
+directories into the harness profile, preserving existing chrome files.
+A raw `--extra-profile-file` directory collision is classified as
+`reason=harness-arguments` and names this remedy rather than a rebuild.
 
 ### What a pre-test build costs
 
@@ -183,15 +233,16 @@ redirected run keeps the reason as well as the verdict. See
 
 ## Seeded shuffle
 
-`fireforge test --shuffle` runs a mochitest selection in a seeded random file
-order and prints the seed; `--shuffle=<seed>` replays it. FireForge forwards
-mach's own `--shuffle`, exports `FIREFORGE_SHUFFLE_SEED=<seed>` to the harness
-so in-file task reordering (harness `head.js` code, not FireForge) can key off
-the same number, and stamps `shuffle=<seed>` on the verdict line. It is
-mochitest-only: the xpcshell harness has no shuffle, and generic `mach test`
-dispatch would hand the flag to every suite. Write the flag as
-`--shuffle=<seed>` or after the paths, because a bare `--shuffle <path>` reads
-the path as the seed.
+`fireforge test --shuffle` deterministically permutes isolated mochitest path
+arguments and prints the seed; `--shuffle=<seed>` replays that shard order for
+the same input selection. A directory remains one invocation. `--no-shard`
+disables this argument permutation. FireForge also forwards native mach
+`--shuffle` within each invocation, whose file order remains unseeded and is
+not replayed by the FireForge seed. `FIREFORGE_SHUFFLE_SEED=<seed>` is available
+to custom harness `head.js` code for in-file task ordering, and `shuffle=<seed>`
+is recorded on the verdict. The option is mochitest-only. Write
+`--shuffle=<seed>` or place it after the paths because a bare
+`--shuffle <path>` consumes the path as its optional seed.
 
 Exit code 14 (`INCONCLUSIVE`) is not red: it means `engine/` moved while the
 harness ran and the result was thrown away. Exit 15 (`LOCK_TIMEOUT`) means
@@ -256,3 +307,17 @@ instead, use a [verification tree](verification-trees.md).
 In dev builds, files under `obj-*/dist/bin` may be symlinks back into the
 source tree (prefs especially), so edit source prefs directly and keep a
 backup before bisection experiments.
+
+## Repository release gate
+
+Run `npm run release:check` with the exact Node version in `.nvmrc` and npm
+version in `package.json`'s `packageManager`. The gate verifies these pins
+before formatting, whitespace, zero-warning lint, strict typecheck, development
+and production dead-code checks, import cycles, coverage floors, and installed
+package smoke tests. `prepublishOnly` and the CI quality job run the same gate.
+Supported Node-version and OS matrices continue to run ordinary tests separately.
+
+The full-Firefox integration runner is opt-in. It snapshots project files,
+engine changes and the index before arming recovery; a refusal cannot erase an
+existing workspace. Failed recovery fails the run, preserves affected paths and
+writes recovery evidence for manual repair.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.48.0",
+  "version": "0.49.1",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -39,8 +39,9 @@
     "format:check": "prettier --check --ignore-unknown \"src/**/*.ts\" \"bin/**/*.ts\" \"scripts/**/*.mjs\" \"eslint-rules/**/*.js\" \"package.json\" \"eslint.config.js\" \"vitest.config.ts\" \"vitest.pack.config.ts\" \"tsconfig.json\" \"tsconfig.build.json\" \".lintstagedrc.json\" \".prettierignore\" \".prettierrc\" \".gitignore\" \"README.md\" \"CHANGELOG.md\" \"docs/**/*.md\" \"knip.json\" \"knip.production.json\"",
     "prepare": "node -e \"import('./scripts/prepare.mjs').catch((error) => { if (error && typeof error === 'object' && 'code' in error && error.code === 'ERR_MODULE_NOT_FOUND') process.exit(0); throw error; })\"",
     "prepack": "npm run build && node ./scripts/generate-build-info.mjs --loud",
-    "release:check": "npm run format:check && npm run whitespace:check && npm run lint:ci && npm run typecheck && npm run deadcode:check && npm run deadcode:check:production && npm run cycles:check && npm run test:coverage && npm run pack:verify",
-    "prepublishOnly": "npm run release:check"
+    "release:check": "npm run toolchain:check && npm run format:check && npm run whitespace:check && npm run lint:ci && npm run typecheck && npm run deadcode:check && npm run deadcode:check:production && npm run cycles:check && npm run test:coverage && npm run pack:verify",
+    "prepublishOnly": "npm run release:check",
+    "toolchain:check": "node ./scripts/check-release-toolchain.mjs"
   },
   "files": [
     "dist/",
@@ -75,9 +76,9 @@
     "eslint-plugin-simple-import-sort": "^14.0.0",
     "fast-check": "^4.6.0",
     "husky": "^9.1.7",
-    "knip": "6.37.0",
+    "knip": "6.39.0",
     "lint-staged": "^17.0.4",
-    "prettier": "3.9.8",
+    "prettier": "3.9.9",
     "tsx": "^4.7.0",
     "typescript": "~6.0.0",
     "typescript-eslint": "^8.0.0",