@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/mach-resource-shim.js

@@ -13,7 +13,7 @@
  *
  * The guard is installed as a `fireforge_mach_guard.pth` + module pair in
  * every discovered mach virtualenv site-packages directory. A PYTHONPATH
- * `sitecustomize.py` is NOT sufficient on its own: mach re-execs itself into
+ * `sitecustomize.py` is not sufficient on its own: mach re-execs itself into
  * its private virtualenv and drops PYTHONPATH, so that route never loads.
  * `.pth` files execute at interpreter startup from the venv's own
  * site-packages, which survives the re-exec. The PYTHONPATH copy is retained
@@ -22,12 +22,12 @@
  *
  * The guard covers the whole crash family:
  *  - wraps `psutil.virtual_memory` / `swap_memory` / `cpu_percent` /
- *    `cpu_times` / `disk_io_counters` module-wide, so every call site —
+ *    `cpu_times` / `disk_io_counters` module-wide, so every call site,
  *    including the direct `psutil.virtual_memory()` in
- *    `mozbuild.base._run_make` — degrades to a `UserWarning` and a zeroed
+ *    `mozbuild.base._run_make`, degrades to a `UserWarning` and a zeroed
  *    reading instead of aborting.
  *
- *    The fallback must be per-function ARITY-CORRECT and reconstructible:
+ *    The fallback must be per-function arity-correct and reconstructible:
  *    mozsystemmonitor captures reading types at `__init__`
  *    (`self._swap_type = type(psutil.swap_memory())`) and rebuilds each
  *    collector sample via `self._swap_type(*swap_mem)`. An svmem-shaped
@@ -37,39 +37,46 @@
  *    sentinel, and mach hangs forever in its atexit `waitpid`. Each wrapped
  *    function therefore degrades to a zeroed instance of psutil's own result
  *    namedtuple where resolvable, else a module-level guard-owned namedtuple
- *    with the exact field order and arity for THAT function (module-level so
+ *    with the exact field order and arity for that function (module-level so
  *    readings pickle by reference across the collector pipe).
  *    `_DegradedReading` remains only as a documented last resort and
  *    tolerates `type(reading)(*values)` reconstruction. Guard-owned fallback
  *    classes never depend on psutil internals resolving, which also makes
  *    them safe when two guard copies load (PYTHONPATH `sitecustomize` in the
- *    bootstrap phase plus the in-venv `.pth`), each with its own classes;
- *  - guards `SystemResourceMonitor` CONSTRUCTION via an import hook:
+ *    bootstrap phase plus the in-venv `.pth`), each with its own classes.
+ *  - guards `SystemResourceMonitor` construction via an import hook:
  *    `poll_interval` is pre-populated before the real `__init__` runs, a
  *    failing `__init__` marks the instance degraded instead of raising, and
- *    every monitor method no-ops on a degraded instance — so a
+ *    every monitor method no-ops on a degraded instance, so a
  *    partially-constructed monitor can never surface the
  *    `AttributeError: poll_interval` variant. Degraded aggregate methods
  *    return zeroed shapes (not `None`) where callers subscript the result
  *    (`aggregate_io` → zeroed io reading, so mozbuild's `log_resource_usage`
- *    does not die on `usage["io"].read_bytes` after a successful compile);
+ *    does not die on `usage["io"].read_bytes` after a successful compile).
  *  - suppresses the mozsystemmonitor collector child on degradation: once
  *    any psutil degradation is observed in the process, monitors are kept
  *    inert (`start` never spawns the collector), and a degraded transition
  *    or raising `stop` best-effort terminates a live collector child and
  *    drains the pipe, so a malformed sample stream cannot wedge mach's
- *    shutdown even if a future shape mismatch slips through;
+ *    shutdown even if a future shape mismatch slips through.
  *  - wraps `mozbuild.controller.building.BuildMonitor.log_resource_usage` to
  *    warn-and-continue on any exception, so end-of-build resource reporting
  *    can never fail a build whose artifacts are complete.
  */
-import { readdir } from 'node:fs/promises';
-import { homedir, tmpdir } from 'node:os';
+import { lstat, mkdir, readdir } from 'node:fs/promises';
+import { homedir, tmpdir, userInfo } from 'node:os';
 import { delimiter, join } from 'node:path';
+import { BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
-import { ensureDir, pathExists, writeText } from '../utils/fs.js';
+import { pathExists, writeText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
-/** Directory name (under the OS temp dir) holding the PYTHONPATH fallback. */
+/**
+ * Prefix of the per-user directory (under the OS temp dir) holding the
+ * PYTHONPATH fallback. The uid (or, on Windows, the username) is appended:
+ * a fixed name under a shared `/tmp` lets any other local account pre-create
+ * the directory and own the `sitecustomize.py` that every mach dispatch
+ * then imports.
+ */
 const RESOURCE_SHIM_DIRNAME = 'fireforge-mach-resource-shim';
 /** Basename (sans extension) of the in-venv guard module. */
 const GUARD_MODULE_NAME = 'fireforge_mach_guard';
@@ -89,6 +96,7 @@ export const GUARD_PYTHON_SOURCE = `# Generated by FireForge - do not edit.
 # (survives mach's venv re-exec, which drops PYTHONPATH).
 import builtins
 import collections
+import inspect
 import sys
 import warnings
 
@@ -369,7 +377,40 @@ def _patch_monitor_class(cls):
 
         return wrapper
 
+    def _wrap_unbound(name, func):
+        # Upstream declares record_event/record_marker as @staticmethods (and
+        # may declare others as @classmethods). Those take no receiver, so
+        # they cannot use the per-instance degraded flag and must not have one
+        # threaded in — see the descriptor dispatch below.
+        def wrapper(*args, **kwargs):
+            if _fireforge_host_degraded[0]:
+                return _monitor_degraded_result(name, args, kwargs)
+            try:
+                return func(*args, **kwargs)
+            except Exception as exc:  # noqa: BLE001
+                _fireforge_degraded_notice(exc)
+                return _monitor_degraded_result(name, args, kwargs)
+
+        return wrapper
+
     for _name in _MONITOR_METHOD_NAMES:
+        # getattr_static returns the raw class attribute, so a staticmethod
+        # is still a staticmethod object here. Plain getattr would hand back
+        # the underlying function, and re-setting THAT on the class rebinds
+        # it as an instance method: the receiver is then passed through as an
+        # extra leading positional and every call raises
+        # "takes N positional arguments but N+1 were given". Re-apply the
+        # descriptor the attribute actually had.
+        try:
+            _raw = inspect.getattr_static(cls, _name)
+        except AttributeError:
+            continue
+        if isinstance(_raw, staticmethod):
+            setattr(cls, _name, staticmethod(_wrap_unbound(_name, _raw.__func__)))
+            continue
+        if isinstance(_raw, classmethod):
+            setattr(cls, _name, classmethod(_wrap_unbound(_name, _raw.__func__)))
+            continue
         _orig = getattr(cls, _name, None)
         if _orig is not None:
             setattr(cls, _name, _wrap_method(_name, _orig))
@@ -488,13 +529,75 @@ async function discoverMachSitePackages(engineDir) {
     return found;
 }
 /**
- * Writes the PYTHONPATH `sitecustomize.py` fallback into a stable
- * FireForge-owned temp directory and returns that directory. Idempotent —
- * overwriting each call keeps it in sync with this source across upgrades.
+ * Per-user discriminator for the shim directory name. The numeric uid on
+ * POSIX, read via `process.getuid` rather than `os.userInfo()`: the latter
+ * resolves the passwd entry and throws (`ERR_SYSTEM_ERROR`) for a uid that
+ * has none (`docker --user 1001:1001`, OpenShift's random uids, many CI
+ * agents), which would take every build and test dispatch down with a raw
+ * system error. On Windows there is no uid. The username is the
+ * discriminator, with `userInfo()` still guarded because the same lookup
+ * can fail there for a service account, falling back to the environment.
+ */
+function shimDirOwner() {
+    const uid = process.getuid?.();
+    if (uid !== undefined)
+        return String(uid);
+    let username;
+    try {
+        username = userInfo().username;
+    }
+    catch {
+        username = process.env['USERNAME'] ?? process.env['USER'];
+    }
+    return (username ?? 'unknown-user').replace(/[^A-Za-z0-9_.-]/g, '_');
+}
+/** Per-user shim directory: `<tmpdir>/fireforge-mach-resource-shim-<uid>`. */
+function resourceShimDir() {
+    return join(tmpdir(), `${RESOURCE_SHIM_DIRNAME}-${shimDirOwner()}`);
+}
+/**
+ * Refuses a shim directory that is not a private directory of the current
+ * user. `lstat`, not `stat`: a symlink planted at the path would otherwise
+ * be followed and the check would describe its target. On Windows only the
+ * "is a real directory" half applies. There is no POSIX owner or mode bit
+ * to read, and the per-user name is the isolation.
+ *
+ * @param dir - Shim directory that {@link ensureSitecustomizeFallback} created
+ * @throws BuildError when the directory is a symlink/file, owned by another
+ *   uid, or group/world-writable
+ */
+export async function assertPrivateShimDir(dir) {
+    const stats = await lstat(dir);
+    const refuse = (reason) => {
+        throw new BuildError(`Refusing to use mach resource shim directory ${dir}: ${reason}. ` +
+            'Another local account may have planted it; remove or fix it and retry.');
+    };
+    if (!stats.isDirectory()) {
+        refuse('not a directory (symlink or file)');
+    }
+    if (process.platform === 'win32')
+        return;
+    const uid = process.getuid?.();
+    if (uid !== undefined && stats.uid !== uid) {
+        refuse(`owned by uid ${stats.uid}, not the current user (uid ${uid})`);
+    }
+    if ((stats.mode & 0o022) !== 0) {
+        refuse(`mode ${(stats.mode & 0o777).toString(8)} is group/world-writable`);
+    }
+}
+/**
+ * Writes the PYTHONPATH `sitecustomize.py` fallback into a per-user,
+ * mode-0700 FireForge-owned temp directory, verified private before the
+ * write, and returns that directory. Idempotent: overwriting each call
+ * keeps it in sync with this source across upgrades.
  */
 async function ensureSitecustomizeFallback() {
-    const dir = join(tmpdir(), RESOURCE_SHIM_DIRNAME);
-    await ensureDir(dir);
+    const dir = resourceShimDir();
+    // `mode` only applies when mkdir creates the directory (and is masked by
+    // the umask). A pre-existing one keeps whatever it had, which is exactly
+    // what the assertion below refuses if it is not private.
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await assertPrivateShimDir(dir);
     await writeText(join(dir, 'sitecustomize.py'), GUARD_PYTHON_SOURCE);
     return dir;
 }
@@ -512,7 +615,7 @@ function machResourceShimEnv(shimDir, baseEnv = process.env) {
  * `fireforge_mach_guard.pth` + `fireforge_mach_guard.py` into every
  * discovered mach virtualenv site-packages (survives mach's venv re-exec),
  * plus the PYTHONPATH sitecustomize fallback for the pre-venv bootstrap
- * phase. Idempotent and re-run before EVERY protected dispatch (including
+ * phase. Idempotent and re-run before every protected dispatch (including
  * each retry) so a venv created by a crashed first attempt is guarded on
  * the next one instead of re-dying on the same wedged state.
  */
@@ -524,7 +627,7 @@ export async function installMachResourceGuard(engineDir) {
             await writeText(join(sitePackages, `${GUARD_MODULE_NAME}.pth`), `import ${GUARD_MODULE_NAME}\n`);
         }
         catch (error) {
-            // A read-only or vanished venv must not block the dispatch; the
+            // A read-only or vanished venv must not block the dispatch. The
             // PYTHONPATH fallback still applies and other venvs may have taken
             // the guard.
             verbose(`Could not install mach resource guard into ${sitePackages}: ${toError(error).message}`);

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

@@ -2,7 +2,7 @@ import { type SmokeLineCallback, type SmokeRunResult } from '../utils/process.js
 import { type HarnessCrashSignature } from './test-harness-crash.js';
 export { attemptMozinfoRewrite, buildArtifactMismatchMessage, hasBuildArtifacts, hasRunnableBundle, } from './mach-build-artifacts.js';
 export { generateMozconfig } from './mach-mozconfig.js';
-export { ensurePython, resetResolvedPython } from './mach-python.js';
+export { ensurePython } from './mach-python.js';
 /**
  * Ensures mach is available in the engine directory.
  * @param engineDir - Path to the engine directory
@@ -18,17 +18,17 @@ export interface MachOptions {
     /** Whether to inherit stdio (show output directly) */
     inherit?: boolean;
     /**
-     * Collapse the KNOWN mozsystemmonitor teardown traceback to one labeled
-     * line in the terminal ECHO (capture-only option). The captured
-     * stdout/stderr stay raw — the harness classifier depends on the raw
+     * Collapse the known mozsystemmonitor teardown traceback to one labeled
+     * line in the terminal echo (capture-only option). The captured
+     * stdout/stderr stay raw, because the harness classifier depends on the raw
      * traceback. Unrecognized tracebacks always echo verbatim. Opted into by
      * the test dispatchers only.
      *
-     * Consumed by {@link runMachCapture} ALONE. `runMachInheritCapture` accepts
-     * it in the type and ignores it — the inherit path has no per-chunk hook,
+     * Consumed by {@link runMachCapture} alone. `runMachInheritCapture` accepts
+     * it in the type and ignores it: the inherit path has no per-chunk hook,
      * only a mirror stream that feeds the terminal and the run log the same
      * string, so filtering there would strip the traceback from the raw log
-     * too. The build path uses the recognition NOTE instead; see
+     * too. The build path uses the recognition note instead. See
      * `mach-known-noise-filter.ts`.
      */
     annotateKnownTeardownNoise?: boolean;
@@ -66,12 +66,6 @@ export declare function runMachCapture(args: string[], engineDir: string, option
  * capturing stdout/stderr for post-run diagnostics.
  */
 export declare function runMachInheritCapture(args: string[], engineDir: string, options?: Omit<MachOptions, 'inherit'>): Promise<MachCommandResult>;
-/**
- * Runs mach bootstrap to install build dependencies.
- * @param engineDir - Path to the engine directory
- * @returns Exit code
- */
-export declare function bootstrap(engineDir: string): Promise<number>;
 /**
  * Runs mach bootstrap while preserving stdin and capturing the emitted output.
  * @param engineDir - Path to the engine directory
@@ -98,20 +92,20 @@ export interface ProtectedMachBuildResult extends MachCommandResult {
 }
 /**
  * The single protected path every FireForge mach build dispatch routes
- * through — `build`, `build --ui`, and the pre-test `--build` step all use
+ * through. `build`, `build --ui`, and the pre-test `--build` step all use
  * it, so no entry point is left unprotected with a different retry budget:
  *
- *  1. installs the resource-monitor degrade guard IN the mach virtualenvs
- *     (plus the PYTHONPATH fallback) — re-installed before every attempt, so
+ *  1. installs the resource-monitor degrade guard in the mach virtualenvs
+ *     (plus the PYTHONPATH fallback), re-installed before every attempt, so
  *     a venv materialized by a crashed first attempt is guarded on the next
- *     one instead of every retry dying on the same wedged state;
- *  2. spawns a fresh mach process per attempt;
- *  3. retries ONLY the recognized harness-crash family (resource monitor /
- *     psutil startup tracebacks) up to the uniform budget — an ordinary
+ *     one instead of every retry dying on the same wedged state.
+ *  2. spawns a fresh mach process per attempt.
+ *  3. retries only the recognized harness-crash family (resource monitor /
+ *     psutil startup tracebacks) up to the uniform budget. An ordinary
  *     compile error is never retried.
  *
  * The protected path never runs `mach configure`, never clobbers, and never
- * widens the requested build kind — a `faster` dispatch retries as
+ * widens the requested build kind: a `faster` dispatch retries as
  * `mach build faster`, so it cannot invalidate more of the objdir than the
  * command the operator asked for.
  */
@@ -122,8 +116,8 @@ export declare function runProtectedMachBuild(kind: ProtectedBuildKind, engineDi
  * hints are surfaced on top of the raw mach output so operators get an
  * actionable nudge alongside the cryptic mozbuild traceback. Returns the
  * captured result so the caller (e.g. `fireforge build`) can inspect the
- * tail for post-build diagnostics that mach prints AFTER "Your build was
- * successful!" — notably the stale `config.status is out of date`
+ * tail for post-build diagnostics that mach prints after "Your build was
+ * successful!", notably the stale `config.status is out of date`
  * notice that mach emits when a tool-managed edit landed on
  * `moz.configure` before the build.
  * @param engineDir - Path to the engine directory
@@ -147,13 +141,13 @@ export declare function buildUI(engineDir: string): Promise<ProtectedMachBuildRe
  *
  * Without it, a `build --ui` started while a full `build` is still in flight
  * hands off to `mach build faster` and fails almost immediately with `No
- * rule to make target 'XUL'` — the real problem being that the first build
+ * rule to make target 'XUL'`, the real problem being that the first build
  * has not yet materialised the full backend, with nothing in the low-level
  * make error pointing at the concurrent run. The lock intercepts the second
  * invocation before it touches mach, and the refusal names the PID holding
  * the lock so the operator can decide whether to wait or investigate.
  *
- * Stale-lock recovery: the lock stores the owner PID; a crashed build
+ * Stale-lock recovery: the lock stores the owner PID. A crashed build
  * (SIGINT, SIGTERM, or a kernel kill) leaves the lock dir behind but not the
  * owning process, and `withFileLock` removes the lock on the next attempt
  * when `process.kill(pid, 0)` shows the owner is gone.
@@ -191,42 +185,28 @@ export interface RunMachSmokeOptions {
  * enforces a deadline by SIGTERMing the whole process group, and returns
  * the captured output alongside a `timedOut` flag.
  *
- * Unlike {@link run}, this variant does NOT inherit stdio. The child
+ * Unlike {@link run}, this variant does not inherit stdio. The child
  * stdout/stderr are piped back through the line callbacks so the caller
  * can scan for `JavaScript error:` / `console.error:` without coupling
  * the runner to chrome-specific pattern logic.
  */
 export declare function runMachSmoke(args: string[], engineDir: string, options: RunMachSmokeOptions): Promise<SmokeRunResult>;
-/**
- * Creates a distribution package.
- * @param engineDir - Path to the engine directory
- * @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.
+ * and capturing the stderr tail for post-run diagnostics, so callers can
+ * consult {@link explainMachError} on failure.
  *
  * @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
- * @returns Exit code
- */
-export declare function watch(engineDir: string): Promise<number>;
 /**
  * Runs mach watch while preserving stdin and capturing emitted output.
  *
  * `env` is threaded through so the caller can prepend the resolved watchman
  * directory to PATH in a way mach inherits: `fireforge watch` can locate
  * `watchman` via `which`, but the mach subprocess spawns with the parent's
- * PATH only — on macOS that typically omits `/opt/homebrew/bin`, so
+ * PATH only, and on macOS that typically omits `/opt/homebrew/bin`, so
  * `mach watch` fails at the `watch-project` subscription step.
  *
  * @param engineDir - Path to the engine directory
@@ -238,38 +218,44 @@ export declare function watchWithOutput(engineDir: string, options?: {
     env?: Record<string, string>;
 }): Promise<MachCommandResult>;
 /**
- * Runs mach test with the given test paths.
- * @param engineDir - Path to the engine directory
- * @param testPaths - Test file or directory paths (relative to engine)
- * @param args - Additional arguments to pass to mach test
- * @returns Exit code
- */
-export declare function test(engineDir: string, testPaths?: string[], args?: string[]): Promise<number>;
-/**
- * Runs mach test while capturing streamed output for better diagnostics.
+ * Which mach test command a capturing test dispatch runs.
  *
- * @param engineDir - Absolute path to the engine checkout
- * @param testPaths - Test paths to pass to `mach test`; empty runs the default set
- * @param args - Extra `mach test` arguments appended after the paths
- * @param env - Optional extra environment variables for the mach process
- *   (merged over `process.env` by the exec layer). Used by
- *   `fireforge test --perf-samples` to publish the artifact-path contract.
+ * - `test`: the generic `mach test` (mixed/all-tests runs, or the
+ *   `--generic-mach-test` opt-out).
+ * - `xpcshell-test` / `mochitest`: the suite-specific commands. Unlike the
+ *   generic `mach test`, these degrade a broken mozlog resource monitor to a
+ *   warning instead of crashing at startup, so `fireforge test` dispatches
+ *   single-suite runs to them to stay resilient to the host psutil failure.
  */
-export declare function testWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>, fullOutput?: boolean): Promise<MachCommandResult>;
+export type MachTestSuiteKind = 'test' | 'xpcshell-test' | 'mochitest';
+/** Options for {@link runMachTestSuite}. */
+export interface MachTestSuiteOptions {
+    /** Absolute path to the engine checkout. */
+    engineDir: string;
+    /** Test paths to pass to the mach command. Empty runs the default set. */
+    testPaths?: string[];
+    /** Extra mach arguments appended after the paths. */
+    args?: string[];
+    /**
+     * Extra environment variables for the mach process (merged over
+     * `process.env` by the exec layer). Used by `fireforge test
+     * --perf-samples` to publish the artifact-path contract.
+     */
+    env?: Record<string, string> | undefined;
+    /**
+     * Pass full mozbuild verbosity through by unsetting the coding-agent
+     * markers that quiet it. See {@link CODING_AGENT_ENV_MARKERS}.
+     */
+    fullOutput?: boolean | undefined;
+}
 /**
- * Runs `mach xpcshell-test` (the suite-specific xpcshell command) while
- * capturing output. Unlike the generic `mach test`, the suite-specific
- * commands degrade a broken mozlog resource monitor to a warning instead of
- * crashing at startup, so `fireforge test` dispatches single-suite runs here
- * to stay resilient to the host psutil failure.
+ * Runs one mach test command (`mach test` / `mach xpcshell-test` / `mach
+ * mochitest`) while capturing streamed output for better diagnostics. The
+ * three commands share every other detail of the dispatch (resource guard,
+ * verbosity env, teardown-noise annotation), so they share one entry point
+ * keyed by `kind` rather than three copies that drift.
  *
- * Signature mirrors {@link testWithOutput} so the two are interchangeable in
- * the dispatch path.
- */
-export declare function xpcshellTestWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>, fullOutput?: boolean): Promise<MachCommandResult>;
-/**
- * Runs `mach mochitest` (covers browser-chrome / mochitest flavors) while
- * capturing output. The suite-specific counterpart to {@link testWithOutput}
- * for non-xpcshell single-suite runs — see {@link xpcshellTestWithOutput}.
+ * @param kind - Which mach command to run
+ * @param options - Engine checkout, test paths, extra args, env, verbosity
  */
-export declare function mochitestWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>, fullOutput?: boolean): Promise<MachCommandResult>;
+export declare function runMachTestSuite(kind: MachTestSuiteKind, options: MachTestSuiteOptions): Promise<MachCommandResult>;