@hominis/fireforge 0.36.0 → 0.37.0

package/dist/src/core/test-stale-check.d.ts

@@ -1,4 +1,4 @@
-import type { BuildBaseline } from './build-baseline-types.js';
+import type { BuildBaseline, TestPackagingCoverage } from './build-baseline-types.js';
 /** Result of the stale-build preflight probe. */
 export interface StaleBuildResult {
     /** True when at least one packageable engine file changed since the baseline. */
@@ -40,3 +40,31 @@ export declare function checkStaleBuildForTest(projectRoot: string, engineDir: s
  * result without matching the rendered copy.
  */
 export declare function formatStaleBuildWarning(result: StaleBuildResult): string;
+/**
+ * Sentinel returned by {@link findUncoveredRequestPaths} when a full-suite
+ * request (no paths) is checked against a scoped coverage record.
+ */
+export declare const FULL_SUITE_REQUEST = "(entire suite)";
+/**
+ * Compares the requested test paths against the packaged runtime's coverage
+ * claim recorded in the baseline. Returns the requested paths the recorded
+ * packaging does NOT cover — the runs that would dispatch against missing
+ * `_tests/` support fixtures and hang rather than fail.
+ *
+ * Coverage semantics: `undefined` (pre-0.37.0 baseline) and `'full'` cover
+ * everything. A scoped list covers a request path when the request equals a
+ * covered entry or sits beneath a covered directory entry. Both sides are
+ * normalized to forward slashes so Windows-style CLI input cannot defeat
+ * the prefix rule (baseline paths are POSIX by convention). A request with
+ * no paths is a full-suite run and is never covered by a scoped list — the
+ * {@link FULL_SUITE_REQUEST} sentinel is returned so the refusal can name it.
+ */
+export declare function findUncoveredRequestPaths(coverage: TestPackagingCoverage | undefined, requestedPaths: readonly string[]): string[];
+/**
+ * Formats the refusal shown when a non-`--build` run requests paths the
+ * packaged runtime's scoped `test --build` coverage does not include —
+ * enforced on every such run, with or without `--allow-stale-build`. Kept
+ * separate from the matcher so tests can pin structure and copy
+ * independently (same split as {@link formatStaleBuildWarning}).
+ */
+export declare function formatTestCoverageRefusal(uncovered: string[], coverage: string[]): string;

package/dist/src/core/test-stale-check.js

@@ -112,3 +112,62 @@ export function formatStaleBuildWarning(result) {
         'packaged chrome / jar.mn resources, rerun with "fireforge test --build" (or ' +
         '"fireforge build --ui") first. Passing --build skips this check.');
 }
+/**
+ * Sentinel returned by {@link findUncoveredRequestPaths} when a full-suite
+ * request (no paths) is checked against a scoped coverage record.
+ */
+export const FULL_SUITE_REQUEST = '(entire suite)';
+/**
+ * Compares the requested test paths against the packaged runtime's coverage
+ * claim recorded in the baseline. Returns the requested paths the recorded
+ * packaging does NOT cover — the runs that would dispatch against missing
+ * `_tests/` support fixtures and hang rather than fail.
+ *
+ * Coverage semantics: `undefined` (pre-0.37.0 baseline) and `'full'` cover
+ * everything. A scoped list covers a request path when the request equals a
+ * covered entry or sits beneath a covered directory entry. Both sides are
+ * normalized to forward slashes so Windows-style CLI input cannot defeat
+ * the prefix rule (baseline paths are POSIX by convention). A request with
+ * no paths is a full-suite run and is never covered by a scoped list — the
+ * {@link FULL_SUITE_REQUEST} sentinel is returned so the refusal can name it.
+ */
+export function findUncoveredRequestPaths(coverage, requestedPaths) {
+    if (coverage === undefined || coverage === 'full') {
+        return [];
+    }
+    const covered = coverage.map(normalizeCoveragePath).filter((p) => p.length > 0);
+    if (requestedPaths.length === 0) {
+        return [FULL_SUITE_REQUEST];
+    }
+    return requestedPaths.filter((requested) => {
+        const path = normalizeCoveragePath(requested);
+        return !covered.some((c) => path === c || path.startsWith(`${c}/`));
+    });
+}
+/** Normalizes a path for coverage comparison: forward slashes, no trailing slash. */
+function normalizeCoveragePath(path) {
+    return path.trim().replace(/\\/g, '/').replace(/\/+$/, '');
+}
+/**
+ * Formats the refusal shown when a non-`--build` run requests paths the
+ * packaged runtime's scoped `test --build` coverage does not include —
+ * enforced on every such run, with or without `--allow-stale-build`. Kept
+ * separate from the matcher so tests can pin structure and copy
+ * independently (same split as {@link formatStaleBuildWarning}).
+ */
+export function formatTestCoverageRefusal(uncovered, coverage) {
+    const cap = (paths) => {
+        const head = paths.slice(0, STALE_PATHS_LIMIT);
+        const truncated = paths.length - head.length;
+        return head.join(', ') + (truncated > 0 ? `, … (+${truncated} more)` : '');
+    };
+    const rebuildTargets = uncovered.filter((p) => p !== FULL_SUITE_REQUEST);
+    const rebuildHint = rebuildTargets.length > 0
+        ? `Rerun "fireforge test --build ${rebuildTargets.slice(0, STALE_PATHS_LIMIT).join(' ')}" to package them, or run "fireforge build" for full coverage.`
+        : 'Run "fireforge build" (or a path-less "fireforge test --build") for full coverage first.';
+    return (`The packaged test runtime was produced by a scoped "fireforge test --build" covering only: ${cap(coverage)}.\n` +
+        `The requested run needs ${cap(uncovered)}, which that packaging does not cover — support ` +
+        'fixtures for those manifests may be missing from obj-*/_tests/, and the run can hang ' +
+        `rather than fail. ${rebuildHint} ` +
+        '(--allow-stale-build does not bypass this check — it accepts stale content, not missing coverage.)');
+}

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

@@ -2,5 +2,5 @@
  * Re-exports all command-related types from focused sub-modules.
  */
 export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceSyncOptions, FurnaceValidateOptions, GlobalOptions, ImportOptions, LintCommandOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchLintIgnoreOptions, PatchMoveFilesOptions, PatchRenameOptions, PatchReorderOptions, PatchSplitOptions, PatchStagedDependencyOptions, PatchTierOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, SourceSetOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
-export type { ImportSummary, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchMetadata, PatchResult, PatchStagedDependencies, PatchStagedForwardImport, } from './patches.js';
+export type { ImportSummary, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchMetadata, PatchResult, PatchStagedDependencies, PatchStagedForwardImport, PatchStagedRegistration, } from './patches.js';
 export type { DoctorCheck, ProjectStatus, TokenCoverageFileEntry, TokenCoverageReport, } from './project.js';

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

@@ -99,6 +99,12 @@ export interface ExportOptions {
     forceUnsafe?: boolean;
     /** Exclude furnace-managed file paths from the export. */
     excludeFurnace?: boolean;
+    /**
+     * Export the deployed engine copy even when the `components/` source
+     * changed since the last furnace apply. Without this flag the export is
+     * refused so a stale deployed copy cannot silently land in the patch.
+     */
+    allowStaleFurnace?: boolean;
     /**
      * Acknowledge that the export will create cross-patch ownership overlap
      * with existing non-superseded patches. Without this flag, `export`
@@ -210,6 +216,12 @@ export interface ReExportOptions {
      * before the interactive/`--yes` confirmation path.
      */
     allowShrink?: boolean;
+    /**
+     * Export the deployed engine copy even when the `components/` source
+     * changed since the last furnace apply. Without this flag the re-export
+     * is refused so a stale deployed copy cannot silently land in the patch.
+     */
+    allowStaleFurnace?: boolean;
     /** Bypass cross-patch lint refusal on projected shrink state */
     forceUnsafe?: boolean;
     /**
@@ -278,16 +290,27 @@ export interface PatchLintIgnoreOptions {
  * declarations, or clear all staged dependencies from the patch.
  */
 export interface PatchStagedDependencyOptions {
-    /** Add a forward-import staged dependency. */
+    /** Add a staged dependency declaration. */
     add?: boolean;
-    /** Remove matching forward-import staged dependency declarations. */
+    /** Remove matching staged dependency declarations. */
     remove?: boolean;
     /** Drop the stagedDependencies field entirely. */
     clear?: boolean;
-    /** Importing file path relative to engine/. */
+    /**
+     * Declaration shape: `import` (forward import, the default when unset) or
+     * `registration` (jar.mn packaging line, customElements or actor
+     * registration). Registration entries use `line` instead of `specifier`.
+     */
+    kind?: string;
+    /** Declaring file path relative to engine/. */
     file?: string;
-    /** Exact import specifier as it appears in source. */
+    /** Exact import specifier as it appears in source (`kind: import`). */
     specifier?: string;
+    /**
+     * Registration/packaging line as the patch adds it, compared
+     * whitespace-trimmed (`kind: registration`).
+     */
+    line?: string;
     /** Later-created file path relative to engine/. */
     creates?: string;
     /** Optional exact patch filename expected to create `creates`. */

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

@@ -127,6 +127,15 @@ export interface PatchMetadata {
 export interface PatchStagedDependencies {
     /** Exact forward-import declarations allowed for this patch. */
     forwardImports?: PatchStagedForwardImport[];
+    /**
+     * Registration-shaped forward dependencies: packaging or registration
+     * LINES (a jar.mn entry, a customElements registration, an actor
+     * registration) this patch adds that reference a file a later patch
+     * creates. Unlike `forwardImports`, these are validated by matching the
+     * declared line against the patch's added content, not by finding an
+     * import specifier — packaging lines have no import to match.
+     */
+    registrations?: PatchStagedRegistration[];
 }
 /** A single intentional forward import to a later-created file. */
 export interface PatchStagedForwardImport {
@@ -141,6 +150,26 @@ export interface PatchStagedForwardImport {
     /** Optional human-readable rationale for the staged dependency. */
     reason?: string;
 }
+/**
+ * A single intentional registration/packaging line referencing a
+ * later-created file.
+ */
+export interface PatchStagedRegistration {
+    /** Declaring file path relative to engine/ (e.g. `toolkit/content/jar.mn`). */
+    file: string;
+    /**
+     * The registration/packaging line exactly as the patch adds it. Compared
+     * whitespace-trimmed against the patch's added lines in `file`, so
+     * indentation differences do not break the match.
+     */
+    line: string;
+    /** Later-created file path relative to engine/. */
+    creates: string;
+    /** Optional exact patch filename expected to create `creates`. */
+    owner?: string;
+    /** Optional human-readable rationale for the staged dependency. */
+    reason?: string;
+}
 /**
  * Schema for patches/patches.json file.
  */

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

@@ -46,6 +46,19 @@ export interface CustomComponentConfig {
     targetPath: string;
     /** Whether to register in customElements.js */
     register: boolean;
+    /**
+     * What the component IS. `'element'` (the default when unset) is a custom
+     * element with its own tag. `'library'` is a base class + helpers module
+     * that defines no element of its own (e.g. a shared MozLitElement
+     * subclass other components extend): `furnace validate` skips the
+     * `no-custom-element-define` / `not-moz-lit-element` compatibility checks
+     * and the `missing-css` structural advisory for it, while headers, module
+     * shape, `relative-import`, and (when a `.css` exists) the CSS
+     * compatibility rules still apply. A library exports no element, so
+     * `kind: "library"` requires `register: false` — the combination with
+     * `register: true` is rejected at config parse time.
+     */
+    kind?: 'element' | 'library';
     /** Whether this component uses Fluent l10n */
     localized: boolean;
     /** Stock component tag names composed internally by this component */

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

@@ -0,0 +1,33 @@
+/**
+ * Process-group kill and post-run sweep helpers for the exec layer
+ * (0.37.0 item 9a). Split out of `process.ts` to keep that file within the
+ * per-file line budget; deliberately spawn-based (not `exec`-based) so the
+ * two modules do not import each other cyclically.
+ */
+import { type ChildProcess } from 'node:child_process';
+/**
+ * Sends `signal` to the child's whole tree: the process GROUP on POSIX
+ * (negative-PID kill — reaches mach → python → firefox → content-process
+ * chains), or a `taskkill /T /F` tree kill plus a direct `child.kill`
+ * fallback on Windows. No-ops once the direct child has exited (group
+ * survivors after exit are the post-run sweep's job, not this function's).
+ */
+export declare function killProcessTree(child: ChildProcess, signal: NodeJS.Signals, usesProcessGroup: boolean): void;
+/** One process still alive in a swept group. */
+export interface ProcessGroupSurvivor {
+    /** PID, or -1 when pgrep was unavailable and only a liveness probe ran. */
+    pid: number;
+    /** Command line (pgrep -lf output), best-effort. */
+    command: string;
+}
+/**
+ * Post-run reaper for a process group FireForge itself spawned (`pgid` is
+ * the PID of a child started with `detached: true`): lists survivors,
+ * SIGTERMs the group, waits a short grace, escalates to SIGKILL, and warns
+ * about anything that still refuses to die. POSIX only (no-op on win32).
+ * The only kill target is `-pgid` — never anything outside the group.
+ * A healthy run costs exactly one `pgrep`.
+ */
+export declare function sweepProcessGroup(pgid: number, graceMs?: number): Promise<{
+    survivors: ProcessGroupSurvivor[];
+}>;

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

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Process-group kill and post-run sweep helpers for the exec layer
+ * (0.37.0 item 9a). Split out of `process.ts` to keep that file within the
+ * per-file line budget; deliberately spawn-based (not `exec`-based) so the
+ * two modules do not import each other cyclically.
+ */
+import { spawn } from 'node:child_process';
+import { verbose, warn } from './logger.js';
+/**
+ * Sends `signal` to the child's whole tree: the process GROUP on POSIX
+ * (negative-PID kill — reaches mach → python → firefox → content-process
+ * chains), or a `taskkill /T /F` tree kill plus a direct `child.kill`
+ * fallback on Windows. No-ops once the direct child has exited (group
+ * survivors after exit are the post-run sweep's job, not this function's).
+ */
+export function killProcessTree(child, signal, usesProcessGroup) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    const targetPid = child.pid;
+    if (targetPid === undefined)
+        return;
+    try {
+        if (usesProcessGroup) {
+            // Negative PID routes to the process group, killing the Python
+            // wrapper, the firefox it forked, and every content process
+            // that inherited the group.
+            process.kill(-targetPid, signal);
+        }
+        else {
+            // No process group on Windows — taskkill /T walks the descendant
+            // tree instead. Always forced (/F): there is no SIGTERM analogue,
+            // so the grace window only exists on POSIX.
+            spawn('taskkill', ['/pid', String(targetPid), '/T', '/F'], {
+                stdio: 'ignore',
+            }).on('error', () => {
+                // taskkill unavailable — nothing more we can do beyond the
+                // direct-child kill below.
+            });
+            child.kill(signal);
+        }
+    }
+    catch {
+        // Already gone. Nothing to do.
+    }
+}
+const SWEEP_GRACE_MS = 2000;
+const MULTIPROCESSING_WORKER_PATTERN = /multiprocessing\.(?:spawn|forkserver)|resource_tracker/;
+function sweepDelay(ms) {
+    // Deliberately ref'd (no unref()): this promise is AWAITED between the
+    // group SIGTERM and the post-grace re-list/SIGKILL escalation, from a
+    // child 'close' handler after the signal forwarder is disposed — with an
+    // unref'd timer nothing kept the event loop alive, so Node could exit
+    // mid-grace and skip the escalation entirely. Healthy runs never reach
+    // this function (sweepProcessGroup early-returns on zero survivors), so
+    // the ref never holds a clean exit open.
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * Minimal spawn-based pgrep runner. exitCode -1 means pgrep itself was
+ * unavailable or errored (distinct from exit 1 = "no matches").
+ */
+async function runPgrep(args) {
+    return new Promise((resolve) => {
+        const child = spawn('pgrep', args, { stdio: ['ignore', 'pipe', 'ignore'] });
+        let stdout = '';
+        child.stdout.on('data', (data) => {
+            stdout += data.toString('utf8');
+        });
+        child.on('error', () => {
+            resolve({ exitCode: -1, stdout: '' });
+        });
+        child.on('close', (code) => {
+            resolve({ exitCode: code ?? -1, stdout });
+        });
+    });
+}
+/** Lists processes still in `pgid` via `pgrep -g -lf`, with a kill(0) fallback. */
+async function listGroupSurvivors(pgid) {
+    const result = await runPgrep(['-g', String(pgid), '-lf']);
+    if (result.exitCode === 0) {
+        return result.stdout
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .map((line) => {
+            const match = /^(\d+)\s+(.*)$/.exec(line);
+            return match
+                ? { pid: Number(match[1]), command: match[2] ?? '' }
+                : { pid: -1, command: line };
+        });
+    }
+    if (result.exitCode === 1)
+        return []; // no matches
+    // pgrep unavailable/broken: fall back to a group liveness probe.
+    try {
+        process.kill(-pgid, 0);
+        return [{ pid: -1, command: 'unknown (pgrep unavailable; group still has live members)' }];
+    }
+    catch {
+        return [];
+    }
+}
+function describeSurvivors(list) {
+    return list
+        .map((s) => {
+        const tag = MULTIPROCESSING_WORKER_PATTERN.test(s.command)
+            ? ' [multiprocessing worker — the known busy-spin orphan shape]'
+            : '';
+        return `PID ${String(s.pid)}: ${s.command}${tag}`;
+    })
+        .join('; ');
+}
+/**
+ * Post-run reaper for a process group FireForge itself spawned (`pgid` is
+ * the PID of a child started with `detached: true`): lists survivors,
+ * SIGTERMs the group, waits a short grace, escalates to SIGKILL, and warns
+ * about anything that still refuses to die. POSIX only (no-op on win32).
+ * The only kill target is `-pgid` — never anything outside the group.
+ * A healthy run costs exactly one `pgrep`.
+ */
+export async function sweepProcessGroup(pgid, graceMs = SWEEP_GRACE_MS) {
+    if (process.platform === 'win32')
+        return { survivors: [] };
+    const survivors = await listGroupSurvivors(pgid);
+    if (survivors.length === 0)
+        return { survivors };
+    warn(`Harness process group ${String(pgid)} left ${String(survivors.length)} surviving ` +
+        `process(es) after exit — reaping the group. ${describeSurvivors(survivors)}`);
+    try {
+        process.kill(-pgid, 'SIGTERM');
+    }
+    catch {
+        return { survivors };
+    }
+    await sweepDelay(graceMs);
+    let remaining = await listGroupSurvivors(pgid);
+    if (remaining.length > 0) {
+        try {
+            process.kill(-pgid, 'SIGKILL');
+        }
+        catch {
+            return { survivors };
+        }
+        await sweepDelay(Math.min(200, graceMs));
+        remaining = await listGroupSurvivors(pgid);
+        if (remaining.length > 0) {
+            warn(`Process group ${String(pgid)} still has survivors after SIGKILL: ${describeSurvivors(remaining)}. ` +
+                'Inspect manually (ps -axo pid,ppid,time,command) and kill by PID.');
+        }
+        else {
+            verbose(`Process group ${String(pgid)} reaped after SIGKILL escalation.`);
+        }
+    }
+    else {
+        verbose(`Process group ${String(pgid)} reaped cleanly with SIGTERM.`);
+    }
+    return { survivors };
+}

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

@@ -29,6 +29,21 @@ export interface ExecOptions {
     env?: Record<string, string>;
     /** Timeout in milliseconds */
     timeout?: number;
+    /**
+     * POSIX: spawn the child as a process-group leader and route every kill
+     * (parent-signal forwarding, abort, escalation) to the whole GROUP, then
+     * sweep the group for survivors after close — so a harness that dies at
+     * startup cannot strand spinning `multiprocessing` workers (field
+     * incident: an orphaned Python spawn worker reparented to launchd and
+     * busy-spun at 100% CPU for ~26 days). Win32: tree-kill via
+     * `taskkill /T /F` on abort/signals only, no post-run sweep
+     * (best-effort). Default false — non-mach consumers are unaffected.
+     *
+     * NOTE for callers: a detached group leader does NOT receive terminal
+     * Ctrl+C; the exec layer installs its own group-aware signal forwarder
+     * whenever this option is set.
+     */
+    processGroup?: boolean;
 }
 /**
  * Executes a command and returns its output.