@hominis/fireforge 0.49.2 → 0.51.0

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 0.51.0
+
+### Test harness
+
+- `started=` counts start lines as the output streams, or reads the mozlog raw log when the run wrote one. A suite printing more than 2 MB, or any `--full-output` run, no longer reports files that ran as unstarted. A refusal names its evidence with `started-source=`.
+- Sharded runs print a `FIREFORGE-SHARD:` line per shard and `failed-shards=` on the verdict. New `--shard-size <n>` runs n files per mach invocation, judged per file. New `--results <path>` writes per-file JSON (status, expected, duration, log offset) from mozlog and adds `results=` to the verdict.
+- Negative controls accept a plain unified diff, and a `git diff --no-index` against an edited copy. A control on compiled source is refused without `--build`. With `--build` it goes in before the build and is restored afterwards (`control-build=compiled`). A build-less control on stale packaging is refused before the lock.
+- Mid-run engine edits the running browser cannot see no longer make a run inconclusive (`drift-tolerated=<n>`). A scoped `--build` of one file keeps its manifest siblings' coverage, and packaging refusals arrive before the lock.
+- `--furnace-apply all|reached|none` and `test.furnaceApply` scope the pre-test Furnace apply; components left out are named in `furnace-skipped=`. The default stays `all`.
+
+### Locks
+
+- New opt-in `--shared-lock` and `test.lockMode: "shared"` let build-less test runs with auto ports overlap on one objdir; builds, re-exports and every other writer stay exclusive. New `test --jobs <n>` runs a request's shards on n harness instances inside one hold, each on its own ports, with `[job i]`-prefixed output.
+- `--wait-lock` and `FIREFORGE_WAIT_LOCK` accept up to 86400 seconds.
+
+### Patch queue
+
+- Added `patch reserve <order>`, which holds a claimed order under `allowGaps: false`; default allocation skips it, and the export that takes it fills it. Added `patch stage <name>...`, which stages only the named patches' rows of `patches.json` (validated) and their patch files. Every writer emits one canonical `patches.json` key order, so the first full save may reorder keys once.
+- Added `re-export --hunks-from <diff>` and `--exclude-hunks <diff>`, which export a shared file hunk by hunk. Added `fireforge park`, which sets a session's edits to a patch's files aside and merges them back three-way, warning about Fluent ids and files still referenced outside the patch.
+- `re-export --dry-run` takes no engine lock and runs on a private git index. Its purity guard covers only the selected patches, their rows and the engine files they own, and names a concurrent writer instead of calling a peer's write a FireForge bug.
+- Refused `re-export --scan`, `patch move-files` and `patch split` write one `--from`-ready declaration report (`--declarations-out`) and name one `staged-dependency --add --from` call per holding patch. `--refuse-adjacent-unmanaged` combines with `--scan`.
+- `staged-dependency --remove` accepts `--creates` alone, matches registration lines regardless of whitespace, and exits 8 when nothing matches. Re-export drops a staged registration whose `creates` path no patch owns. An `--expect-removed` path owned by an unselected patch names that owner.
+- `patch delete` and `retire` name created files still on disk and gain `--delete-created`. A description-only `patch rename` needs no `--yes`.
+- An unscoped `verify`, and so `fireforge check`, also reads unexported engine files for imports of unregistered `resource:///modules` modules.
+
+### Lint and tokens
+
+- `lintIgnore` ceilings take a free-form `meta` object and `share: "test"|"product"`, and a notice no longer exceeds a ceiling. `lint --report` adds `lintIgnoreWaivers` for bare waivers. `patch lint-ignore` gains `--add <rule>=<max>`, `--share` and `--from <json|report>`.
+- `patchLint.tokenScales` skips `@font-face` and other descriptor at-rules. Each scale also takes a `prefix` list, `allowInCalc`, `offsetCap`, `exclude` globs and a `minFiles` floor (`token-scale-vacuous`). `token lint` treats a `var()` with a fallback as optional and resolves tokens declared by sibling sheets: from document links, from `@import`, or from `furnace.json#tokenSiblingSheets`.
+- A test script's per-patch checkJs resolves modules created by earlier patches. Opt-in `typecheck.litTypes` types `LitElement` and `MozLitElement`. A scoped `lint --per-patch --patches` keeps stale staged declarations. `discoverPatches` follows symlinked patch files.
+- The API exports `measurePatchSize`, `isPatchSizeRegistrationFile`, `codeLineMask` and `evaluatePatchPolicyContentForQueue`.
+
+### Gates
+
+- `fireforge check` gains `check.timeout` and `check.timeouts.<step>` for built-in steps, `check.failOnSkipped`, `check.lintReport` (passed to extra steps as `FIREFORGE_CHECK_LINT_REPORT`), and `extraSteps[].after`. The verdict line names `skipped-steps=`.
+
+### Furnace
+
+- `furnace validate`: an exception no longer suppresses an error (`validation-exception-on-error`), and an exception can name a `tag`. `minComponents` sets a floor (`component-floor`). `panel-item` counts as natively interactive, and the accessibility checks judge the host module together with its companion modules.
+- `furnace deploy` and `furnace rename` edit `jar.mn` lines in place instead of re-sorting the widget's block.
+- The `icon-button-label` check scans a button's content for text outside tags instead of stripping tags with a regex. A `>` inside a quoted attribute no longer ends the tag.
+
+### Other
+
+- Windows: when two commands race to migrate the legacy history log, the loser stands down instead of failing on a claim the other command holds. The `check` process test no longer assumes a POSIX shell, and the `build` and `test` pre-lock tests no longer assume POSIX paths.
+- Dev tooling: `@types/node` 26.6.5, `@vitest/coverage-v8` and `vitest` 5.0.5, `eslint-plugin-jsdoc` 65.3.6, `knip` 6.41.0, `prettier` 3.9.10, `typescript-eslint` 8.71.2 and `vite` 8.3.4. Runtime: `acorn` 8.19.0 and `magic-string` 1.4.3. CI: `actions/setup-node` 7.1.0 and `github/codeql-action` 4.38.3.
+
+## 0.50.0
+
+### Size budget
+
+- New `patchLint.fileSizeMetric` (`raw` or `code`), `patchSizeMetric` (`diff` or `addedCode`), per-tier `patchSizeThresholds` and `patchSizeRegistrationFiles`. Added code skips comments, blank lines and Furnace fragment copies. Defaults are unchanged. Size messages name their unit, and a notice no longer claims to fail `--max-warnings 0`.
+- `lintIgnore` entries can carry a size ceiling (`{ rule, max, reason }`). Size helpers are exported, and `lint --report` rows carry the metric.
+
+### Gates and policy
+
+- Added `fireforge check`, which runs status, verify, per-patch lint, typecheck, Furnace validation, token coverage and `check.extraSteps` with one verdict. `status` gains `--fail-on ownership-conflict`, `--allow`, `--fail-on-unknown` and `--patches`; `verify` gains `--patches`.
+- Opt-in `patchPolicy` rules (`upstreamAllowlist`, add-only marker mode, `scopeRules`, `verifyDocumentPaths`), `patchLint.tokenScales` and `fireforge token lint`. `furnace validate` gains `--json`, `--max-warnings` and `validationExceptions`.
+
+### Test harness
+
+- Packaging coverage is kept per staged path, so a peer's scoped build no longer replaces it. The stale-build check ignores edits the packaged runtime already serves.
+- Mixed xpcshell and browser paths, `--repeat <n>` and `--negative-control <diff>` run under one lock hold. A truncated exit-0 run is `FAIL`. The binary, checkJs and browser/port waits run before the engine lock.
+- Added `--keep-log`, `--auto-ports`, `--no-furnace-apply` and `--restart-between-tests`. A path after an optional-value flag such as `--wait-lock` is read as a test path.
+
+### Locks and history
+
+- File locks are granted in arrival order, and crashed or stopped waiters are skipped.
+- The patch history log moves to `.fireforge/history.jsonl` (configurable as `history.path`) and is migrated on first write. Records carry an invocation id, and staged-dependency records log only the delta.
+
+### Patch queue
+
+- `--refuse-foreign-drift` counts removed lines and combines with `--scan`. `--scan-file` accepts `<patch>:<path>`. `--refuse-adjacent-unmanaged` judges only files a re-export would capture, and gains `--expect-new` and `--adjacent-ignore`. Arguments are checked before the lock, and `--expect-from` is new.
+- Added `patch retire`, which keeps the retired patch's order as a slot. `staged-dependency --add --from` takes a lint report. `move-files --create` and `split` keep staged declarations in step. Refusals name the earliest legal order and the exact commands.
+
+### Furnace
+
+- `--wait-lock` works on every leaf. `deploy` takes several names, and `rename` rewrites registrations in place and gains `--dry-run`. `apply` no longer duplicates jar lines and says why it skipped. The unexported-drift belt and `furnace diff` compare against the fragment-expanded source.
+
+### Other
+
+- Config writes keep `fireforge.json`'s formatting. `rebase` labels the move from the committed pin. `doctor` tolerates the `esr` suffix and names `./mach npm ci`. `Cu` is typed in the shim. `run --profile` purges caches, and `--smoke-exit` fails a silent early exit.
+- Dev tooling: `eslint` 10.12.0 and `eslint-plugin-jsdoc` 65.0.2.
+
 ## 0.49.0
 
 ### Furnace and builds
@@ -7,6 +91,7 @@
 - Safer Furnace deployment and objdir cloning protect component sources and peer checkouts from shared files and directory aliases. Failed copies finish before rollback; cloned build metadata is relocated and verified.
 - `furnace create --localized` no longer scaffolds a `connectedCallback`/`disconnectedCallback` pair that calls `l10n.connectRoot(shadowRoot)` and `disconnectRoot`. `MozLitElement` already registers its shadow render root with `document.l10n`, so the generated pair registered the same root twice, which `DOMLocalization::ConnectRoot` asserts against in debug builds. The scaffold keeps the module-level `window.MozXULElement?.insertFTLIfNeeded(...)` call.
 - Build and test preflight detect broken partial configuration, stale artifacts and invalid build baselines. Scoped builds retain coverage only while their inputs remain unchanged, and builds remove dangling test links.
+- Objdir relocation on Windows rewrites both the backslash and the forward-slash spelling of the old root in dependency metadata (mozbuild writes both), and replaces a directory link that `rename` refuses with `EPERM` in two steps.
 
 ### Test harness
 
@@ -25,11 +110,12 @@
 ### Command reliability
 
 - Fixed leaf-command `--wait-lock` handling, JSON error reporting and watch retries. Process tracking and independent cleanup preserve the original run outcome through cancellation and cleanup failures.
+- Diff header parsing splits a rename/copy header with `indexOf` instead of a lazy regex, and token-category parsing strips CSS strings in one pass, so both run in linear time on pathological input.
 
 ### Tooling
 
 - Full-Firefox integration preserves existing workspace files and Git index state, and fails on incomplete recovery. Build identity includes untracked contents and binary changes. Release checks enforce the pinned toolchain and additional module coverage floors.
-- Dev tooling: `eslint-plugin-jsdoc` 65.0.1 and `@types/node` 26.6.4. Transitive `source-map-js` 1.2.2 (GHSA-68fv-2mgg-jv7q) and `smol-toml` 1.9.0 (GHSA-r4xh-jqrq-34v2) clear `npm audit`.
+- Dev tooling: `eslint-plugin-jsdoc` 65.0.1, `@types/node` 26.6.4, `knip` 6.39.0 and `prettier` 3.9.9. Transitive `source-map-js` 1.2.2 (GHSA-68fv-2mgg-jv7q) and `smol-toml` 1.9.0 (GHSA-r4xh-jqrq-34v2) clear `npm audit`.
 
 ## 0.48.0
 

package/README.md

@@ -15,7 +15,7 @@ Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon
 - **Firefox source and build helpers** Download, bootstrap, build, run, test, package, smoke-check, etc.
 - **Wiring and registration** Add chrome scripts, DOM fragments, modules, styles, tests and manifest entries through commands built by learning from existing Firefox conventions.
 - **Furnace components** Create or override `MozLitElement` widgets easily to add new or adapt existing UI components to your needs.
-- **Quality** `lint`, `typecheck`, `verify` and `doctor` catch common issues early.
+- **Quality** `lint`, `typecheck`, `verify` and `doctor` catch common issues early, and `check` runs the static gates together with one verdict.
 - **Tests** FireForge was built by taking apart and applying patches of all sorts to original Firefox source code across different versions and products, learning what works vs doesn't and creating some quite extensive tests based on that covering all manner of scenarios. Yes, we mock quite a bit, but when building a tool that modifies a separate code base, I think it's a solid compromise for the time being. Full end-to-end runs are currently run locally on my MacBook, as they require about 30 GB of disk and significant compute for multiple full builds. Full end-to-end via Actions will be added soonishlyTM but might need a different runner...
 
 ## Requirements

package/dist/bin/fireforge.js

@@ -12,6 +12,7 @@ import { removeActivePgidFile } from '../src/commands/test-harness-teardown.js';
 import { emitKilledVerdict } from '../src/commands/test-verdict.js';
 import { forceReleaseHeldLocksForSignal } from '../src/core/file-lock.js';
 import { forceReleaseFurnaceLocksForActiveOperations, isSignalRollbackInFlight, rollbackActiveOperationsForSignal, } from '../src/core/furnace-operation.js';
+import { restoreActiveNegativeControlsForSignal } from '../src/core/negative-control.js';
 import { closeActiveRunLog } from '../src/core/run-log.js';
 import { removeActiveRunProfiles } from '../src/core/run-profile.js';
 import { waitForActiveCriticalSections } from '../src/core/signal-critical.js';
@@ -97,6 +98,11 @@ function installFurnaceSignalHandler(signal, exitCode) {
             waitForActiveCriticalSections(SIGNAL_CRITICAL_SECTION_TIMEOUT_MS),
             waitForActiveChildShutdown(CHILD_SHUTDOWN_TIMEOUT_MS),
         ])
+            // A `test --negative-control` mutation must be undone while this
+            // process still holds the engine lock, or the next lock holder builds
+            // and tests the neuter. Runs after child shutdown, so the dying
+            // harness no longer reads the files. Never throws.
+            .then(() => restoreActiveNegativeControlsForSignal())
             // `withFileLock`'s `finally { rm }` never runs across `process.exit`,
             // so both sweeps exist for the same reason. The generic one covers
             // every lock this process holds (engine session, patch directory,

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "version": "0.49.2",
-  "commit": "c707978869b62aba07d1e8f0955be00c223d5ce0",
-  "shortCommit": "c707978869b6",
+  "version": "0.51.0",
+  "commit": "bd93338b037832fdcd69259a70a3a4b134b98906",
+  "shortCommit": "bd93338b0378",
   "dirty": false,
   "dirtyHash": null,
-  "buildTime": "2026-10-06T21:50:15.508Z"
+  "buildTime": "2026-10-19T12:33:48.474Z"
 }

package/dist/src/commands/build-prelock.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `fireforge build --wait-browser` spends its budget before the engine
+ * session lock, not while holding it.
+ *
+ * A build queued behind a running objdir browser (a demo batch, an
+ * end-to-end harness) used to wait inside `withEngineSessionLock`, so every
+ * peer's build, test and re-export queued behind a run that was doing
+ * nothing. The wait now happens first, and the in-lock objdir preflight
+ * re-checks once (the spent budget is stripped from the options it gets).
+ */
+import type { BuildOptions } from '../types/commands/index.js';
+/**
+ * Waits for this objdir's browser before the lock when `--wait-browser`
+ * was given and there is a launchable bundle to watch.
+ *
+ * @param projectRoot - Project root
+ * @param options - Parsed build options
+ * @returns The options the in-lock run should use
+ */
+export declare function waitForBuildBrowserBeforeLock(projectRoot: string, options: BuildOptions): Promise<BuildOptions>;

package/dist/src/commands/build-prelock.js

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge build --wait-browser` spends its budget before the engine
+ * session lock, not while holding it.
+ *
+ * A build queued behind a running objdir browser (a demo batch, an
+ * end-to-end harness) used to wait inside `withEngineSessionLock`, so every
+ * peer's build, test and re-export queued behind a run that was doing
+ * nothing. The wait now happens first, and the in-lock objdir preflight
+ * re-checks once (the spent budget is stripped from the options it gets).
+ */
+import { join } from 'node:path';
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { hasBuildArtifacts, hasRunnableBundle } from '../core/mach.js';
+import { ensureLaunchableBrowserNotRunning } from '../core/marionette-port.js';
+import { waitBeforeLock } from '../core/preflight-wait.js';
+import { pathExists } from '../utils/fs.js';
+import { resolveWaitLockSeconds } from '../utils/options.js';
+/**
+ * Waits for this objdir's browser before the lock when `--wait-browser`
+ * was given and there is a launchable bundle to watch.
+ *
+ * @param projectRoot - Project root
+ * @param options - Parsed build options
+ * @returns The options the in-lock run should use
+ */
+export async function waitForBuildBrowserBeforeLock(projectRoot, options) {
+    const { waitBrowser, ...rest } = options;
+    if (waitBrowser === undefined)
+        return options;
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.engine)))
+        return options;
+    const { objDir } = await hasBuildArtifacts(paths.engine);
+    if (objDir === undefined)
+        return options;
+    let binaryName;
+    try {
+        ({ binaryName } = await loadConfig(projectRoot));
+    }
+    catch {
+        return options;
+    }
+    const bundle = await hasRunnableBundle(paths.engine, binaryName, objDir);
+    const expectedPath = bundle.expectedPath;
+    if (!bundle.runnable || expectedPath === undefined)
+        return options;
+    await waitBeforeLock(() => ensureLaunchableBrowserNotRunning(join(paths.engine, expectedPath)), resolveWaitLockSeconds(waitBrowser));
+    return rest;
+}

package/dist/src/commands/build.d.ts

@@ -5,7 +5,9 @@ import type { BuildOptions } from '../types/commands/index.js';
  * Runs the build command.
  * @param projectRoot - Root directory of the project
  * @param options - Build options
+ * @param underLock - Runs the build under the engine session lock; a
+ *   `--wait-browser` budget is spent before it (see build-prelock.ts)
  */
-export declare function buildCommand(projectRoot: string, options: BuildOptions): Promise<void>;
+export declare function buildCommand(projectRoot: string, options: BuildOptions, underLock?: (body: () => Promise<void>) => Promise<void>): Promise<void>;
 /** Registers the build command on the CLI program. */
 export declare function registerBuild(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/build.js

@@ -13,7 +13,7 @@ import { findObjdirRelocationViolation } from '../core/mach-build-artifacts.js';
 import { ensureLaunchableBrowserNotRunning } from '../core/marionette-port.js';
 import { assertHealthyPartialConfig, pruneDanglingTestLinks } from '../core/objdir-maintenance.js';
 import { waitForPreflight } from '../core/preflight-wait.js';
-import { closeActiveRunLog, getActiveRunLogPath, openRunLog, setActiveRunLog, } from '../core/run-log.js';
+import { closeActiveRunLog, getActiveRunLogPath, keepRunLogCopy, openRunLog, setActiveRunLog, } from '../core/run-log.js';
 import { buildHarnessCrashMessage } from '../core/test-harness-crash.js';
 import { formatToolchainMismatchMessage, runToolchainPreflight, } from '../core/toolchain-preflight.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
@@ -24,6 +24,7 @@ import { checkDiskSpace } from '../utils/fs.js';
 import { error, info, intro, notice, outro, spinner, verbose, warn } from '../utils/logger.js';
 import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../utils/options.js';
 import { isPositiveInteger } from '../utils/validation.js';
+import { waitForBuildBrowserBeforeLock } from './build-prelock.js';
 function parseJobCount(value) {
     const parsed = Number(value);
     if (!Number.isSafeInteger(parsed) || parsed < 1) {
@@ -177,17 +178,20 @@ function buildFailureDiagnostics(result, engineDir, objDir, machCommand) {
  * Runs the build command.
  * @param projectRoot - Root directory of the project
  * @param options - Build options
+ * @param underLock - Runs the build under the engine session lock; a
+ *   `--wait-browser` budget is spent before it (see build-prelock.ts)
  */
-export async function buildCommand(projectRoot, options) {
+export async function buildCommand(projectRoot, options, underLock = (body) => body()) {
     const buildType = options.ui ? 'UI-only' : 'Full';
     const brandInfo = options.brand ? ` [${options.brand}]` : '';
     intro(`FireForge Build (${buildType}${brandInfo})`);
     // A build's own complete output, kept independently of whatever the
     // operator piped the run through. `build` prints no FIREFORGE-VERDICT
     // line, so the path is announced directly at the end of the run.
-    setActiveRunLog(await openRunLog(projectRoot, 'build'));
+    setActiveRunLog(await keepRunLogCopy(await openRunLog(projectRoot, 'build'), options.keepLog, 'build'));
     try {
-        await runBuildCommandBody(projectRoot, options);
+        const lockedOptions = await waitForBuildBrowserBeforeLock(projectRoot, options);
+        await underLock(() => runBuildCommandBody(projectRoot, lockedOptions));
     }
     finally {
         const logPath = getActiveRunLogPath();
@@ -400,11 +404,12 @@ export function registerBuild(program, { getProjectRoot, withErrorHandling }) {
         .command('build')
         .description('Build the browser (auto-applies Furnace components first)')
         .option('--wait-browser [seconds]', 'Wait for this objdir browser to exit before changing its build (default 60)', commanderArgParser((raw) => resolveWaitLockSeconds(raw)))
+        .option('--keep-log <path>', "Also write this run's log to <path> (a directory receives it under its own name), outside .fireforge/logs/ retention. FIREFORGE_LOG_KEEP sets a session default.")
         .option('--ui', 'Fast UI-only rebuild')
         .option('-j, --jobs <n>', 'Number of parallel jobs', parseJobCount)
         .option('--brand <name>', 'Build specific brand')
         .option('--rewrite-mozinfo', 'On a mozinfo path mismatch, patch mozinfo.json paths in place and run mach configure instead of aborting with a clean-rebuild instruction. Refuses anything that is not a pure prefix-move.')
-        .option('--refuse-unexported-drift', 'Refuse (instead of warning) when the build would overwrite engine content recorded in neither a patch body nor the pristine baseline — the multi-session hazard where an unexported edit is silently reverted and a later re-export captures a hybrid')
+        .option('--refuse-unexported-drift', 'Refuse (instead of warning) when the build would overwrite engine content recorded in neither a patch body nor the pristine baseline — the multi-session hazard where an unexported edit is silently reverted and a later re-export captures a hybrid. A deployed Furnace file that is a deployment of its own component source is allowed')
         .addHelpText('after', [
         '',
         'Furnace apply runs automatically before the build step, so edits in',
@@ -425,6 +430,8 @@ export function registerBuild(program, { getProjectRoot, withErrorHandling }) {
     ].join('\n'));
     addWaitLockOption(build).action(withErrorHandling(async (options) => {
         const projectRoot = getProjectRoot();
-        await withEngineSessionLock(projectRoot, 'build', () => buildCommand(projectRoot, pickDefined(options)), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
+        await buildCommand(projectRoot, pickDefined(options), (body) => withEngineSessionLock(projectRoot, 'build', body, {
+            waitLockSeconds: resolveWaitLockSeconds(options.waitLock),
+        }));
     }));
 }

package/dist/src/commands/check-report.d.ts

@@ -0,0 +1,41 @@
+import type { CheckStepResult } from './check-run.js';
+/**
+ * Why a check failed. `step-failures`: at least one step went red.
+ * `lock-timeout`: every failing step exited 15, so nothing was judged red,
+ * the steps just never got their locks. Re-queue rather than fix.
+ * `skipped-steps`: nothing went red, but `check.failOnSkipped` is set and a
+ * step had nothing to run.
+ */
+export type CheckVerdictReason = 'step-failures' | 'lock-timeout' | 'skipped-steps';
+/** How the verdict treats skipped steps. */
+export interface CheckJudgeOptions {
+    /** `check.failOnSkipped`: a step skipped for want of anything to run fails the check. */
+    failOnSkipped?: boolean | undefined;
+}
+/** The verdict over all steps. */
+export interface CheckVerdict {
+    passed: boolean;
+    reason?: CheckVerdictReason;
+    failed: string[];
+    skipped: string[];
+    steps: number;
+}
+/**
+ * Judges the results: any failing step fails the check. Under
+ * `failOnSkipped`, so does a step skipped because the project has nothing
+ * for it to run; it is then listed in `failed` too.
+ */
+export declare function judgeCheck(results: readonly CheckStepResult[], options?: CheckJudgeOptions): CheckVerdict;
+/**
+ * The verdict line: `FIREFORGE-VERDICT: PASS steps=<n> skipped=<n>` or
+ * `FIREFORGE-VERDICT: FAIL reason=<reason> failed=<a,b> steps=<n> skipped=<n>`,
+ * with an additive `skipped-steps=<a,b>` naming the skipped steps when
+ * there are any.
+ */
+export declare function formatCheckVerdictLine(verdict: CheckVerdict): string;
+/** The per-step table: one aligned row per step, with its detail. */
+export declare function formatCheckTable(results: readonly CheckStepResult[]): string;
+/** Writes the verdict line as the run's last stdout write, and seals stdout. */
+export declare function writeCheckVerdictLine(verdict: CheckVerdict): void;
+/** Writes the `--json` document (schemaVersion 1) and seals stdout. */
+export declare function writeCheckJson(results: readonly CheckStepResult[], verdict: CheckVerdict): void;

package/dist/src/commands/check-report.js

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge check` output: the per-step table, the single
+ * `FIREFORGE-VERDICT:` line, and the `--json` document. The verdict is
+ * computed once here and shared by all three, so the exit code, the line
+ * and the JSON can never disagree.
+ */
+import { setStdoutSealed } from '../utils/logger.js';
+/** Exit code a step reports when its lock wait expired. */
+const LOCK_TIMEOUT_EXIT = 15;
+/**
+ * Judges the results: any failing step fails the check. Under
+ * `failOnSkipped`, so does a step skipped because the project has nothing
+ * for it to run; it is then listed in `failed` too.
+ */
+export function judgeCheck(results, options = {}) {
+    const failedResults = results.filter((result) => result.status === 'fail');
+    const gaps = options.failOnSkipped === true
+        ? results.filter((result) => result.status === 'skipped' && result.skipKind !== 'config')
+        : [];
+    const verdict = {
+        passed: failedResults.length === 0 && gaps.length === 0,
+        failed: [...failedResults, ...gaps].map((result) => result.name),
+        skipped: results.filter((result) => result.status === 'skipped').map((result) => result.name),
+        steps: results.length,
+    };
+    if (failedResults.length > 0) {
+        verdict.reason = failedResults.every((result) => result.exitCode === LOCK_TIMEOUT_EXIT)
+            ? 'lock-timeout'
+            : 'step-failures';
+    }
+    else if (gaps.length > 0) {
+        verdict.reason = 'skipped-steps';
+    }
+    return verdict;
+}
+/**
+ * The verdict line: `FIREFORGE-VERDICT: PASS steps=<n> skipped=<n>` or
+ * `FIREFORGE-VERDICT: FAIL reason=<reason> failed=<a,b> steps=<n> skipped=<n>`,
+ * with an additive `skipped-steps=<a,b>` naming the skipped steps when
+ * there are any.
+ */
+export function formatCheckVerdictLine(verdict) {
+    const skippedNames = verdict.skipped.length > 0 ? ` skipped-steps=${verdict.skipped.join(',')}` : '';
+    const counts = `steps=${verdict.steps} skipped=${verdict.skipped.length}${skippedNames}`;
+    if (verdict.passed)
+        return `FIREFORGE-VERDICT: PASS ${counts}`;
+    return `FIREFORGE-VERDICT: FAIL reason=${verdict.reason ?? 'step-failures'} failed=${verdict.failed.join(',')} ${counts}`;
+}
+function formatDuration(ms) {
+    return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+/** The per-step table: one aligned row per step, with its detail. */
+export function formatCheckTable(results) {
+    const rows = results.map((result) => [
+        result.name,
+        result.status.toUpperCase(),
+        result.status === 'skipped' ? '-' : formatDuration(result.durationMs),
+        result.detail,
+    ]);
+    const header = ['STEP', 'RESULT', 'TIME', 'DETAIL'];
+    const widths = header.map((title, column) => Math.max(title.length, ...rows.map((row) => row[column]?.length ?? 0)));
+    return [header, ...rows]
+        .map((row) => row
+        .map((cell, column) => column === row.length - 1 ? cell : cell.padEnd(widths[column] ?? 0))
+        .join('  ')
+        .trimEnd())
+        .join('\n');
+}
+/** Writes the verdict line as the run's last stdout write, and seals stdout. */
+export function writeCheckVerdictLine(verdict) {
+    process.stdout.write(`${formatCheckVerdictLine(verdict)}\n`);
+    setStdoutSealed(true);
+}
+/** Writes the `--json` document (schemaVersion 1) and seals stdout. */
+export function writeCheckJson(results, verdict) {
+    const payload = {
+        schemaVersion: 1,
+        verdict: verdict.passed ? 'pass' : 'fail',
+        ...(verdict.reason !== undefined ? { reason: verdict.reason } : {}),
+        summary: {
+            steps: verdict.steps,
+            passed: results.filter((result) => result.status === 'pass').length,
+            failed: verdict.failed.length,
+            skipped: verdict.skipped.length,
+        },
+        steps: results,
+    };
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    setStdoutSealed(true);
+}

package/dist/src/commands/check-run.d.ts

@@ -0,0 +1,33 @@
+import type { CheckStepPlan } from './check-steps.js';
+/** What a step's table row and JSON entry report. */
+export interface CheckStepResult {
+    name: string;
+    kind: 'builtin' | 'extra';
+    /** The command line, as the table prints it. */
+    command: string;
+    status: 'pass' | 'fail' | 'skipped';
+    /**
+     * For a skipped step: `config` when `check.skip` names it, `unavailable`
+     * when the project has nothing for it to run.
+     */
+    skipKind?: 'config' | 'unavailable';
+    /** The child's exit code. Null when it never ran or was killed at its budget. */
+    exitCode: number | null;
+    durationMs: number;
+    /** One-line summary for the table. */
+    detail: string;
+    /** Set when the step was killed at its `timeout`. */
+    timedOut?: true;
+    /** The tail of the step's combined output, for a failed step. */
+    outputTail?: string;
+}
+/**
+ * Runs every step and returns the results in plan order. A step starts
+ * once a slot is free and every step it runs `after` has finished
+ * (whatever its outcome: the constraint is ordering, not success).
+ *
+ * @param plans - The plan from `buildCheckPlan`, already filtered
+ * @param jobs - How many steps may run at once (at least 1)
+ * @param now - Clock, injectable for tests
+ */
+export declare function runCheckSteps(plans: readonly CheckStepPlan[], jobs: number, now?: () => number): Promise<CheckStepResult[]>;

package/dist/src/commands/check-run.js

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Runs the `fireforge check` plan: up to `jobs` steps at once, each as a
+ * child process in its own process group (so a timeout or a Ctrl+C takes
+ * the step's whole tree), honouring each step's `after` ordering.
+ */
+import { ExecTimeoutError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { execStream } from '../utils/process.js';
+/** Combined output kept per step: enough for a tail, bounded for a chatty audit. */
+const COMBINED_OUTPUT_CAP = 256 * 1024;
+/** Lines of output a failed step carries in its result. */
+const OUTPUT_TAIL_LINES = 40;
+function tailLines(text) {
+    const lines = text.trimEnd().split(/\r?\n/);
+    return lines.slice(-OUTPUT_TAIL_LINES).join('\n');
+}
+/** Runs one planned step to completion. Never throws. */
+async function runStep(plan, now) {
+    const base = { name: plan.name, kind: plan.kind, command: plan.display };
+    if (plan.skipReason !== undefined) {
+        return {
+            ...base,
+            status: 'skipped',
+            skipKind: plan.skipKind ?? 'unavailable',
+            exitCode: null,
+            durationMs: 0,
+            detail: plan.skipReason,
+        };
+    }
+    let stdout = '';
+    let combined = '';
+    const append = (chunk) => {
+        combined += chunk;
+        if (combined.length > COMBINED_OUTPUT_CAP)
+            combined = combined.slice(-COMBINED_OUTPUT_CAP);
+    };
+    const started = now();
+    try {
+        const exitCode = await execStream(plan.command, plan.args, {
+            cwd: plan.cwd,
+            processGroup: true,
+            ...(plan.timeoutMs !== undefined ? { timeout: plan.timeoutMs } : {}),
+            ...(plan.env !== undefined ? { env: plan.env } : {}),
+            onStdout: (chunk) => {
+                stdout += chunk;
+                append(chunk);
+            },
+            onStderr: append,
+        });
+        const status = exitCode === 0 ? 'pass' : 'fail';
+        return {
+            ...base,
+            status,
+            exitCode,
+            durationMs: now() - started,
+            detail: plan.summarize({ stdout, combined, exitCode }),
+            ...(status === 'fail' ? { outputTail: tailLines(combined) } : {}),
+        };
+    }
+    catch (error) {
+        const timedOut = error instanceof ExecTimeoutError;
+        return {
+            ...base,
+            status: 'fail',
+            exitCode: null,
+            durationMs: now() - started,
+            detail: timedOut
+                ? `timed out after ${Math.round((plan.timeoutMs ?? 0) / 1000)}s`
+                : `could not start: ${toError(error).message}`,
+            ...(timedOut ? { timedOut: true } : {}),
+            outputTail: tailLines(combined),
+        };
+    }
+}
+/**
+ * Runs every step and returns the results in plan order. A step starts
+ * once a slot is free and every step it runs `after` has finished
+ * (whatever its outcome: the constraint is ordering, not success).
+ *
+ * @param plans - The plan from `buildCheckPlan`, already filtered
+ * @param jobs - How many steps may run at once (at least 1)
+ * @param now - Clock, injectable for tests
+ */
+export async function runCheckSteps(plans, jobs, now = Date.now) {
+    const names = new Set(plans.map((plan) => plan.name));
+    const results = new Map();
+    const pending = [...plans];
+    const running = new Map();
+    const isReady = (plan) => plan.after.every((dependency) => !names.has(dependency) || results.has(dependency));
+    while (pending.length > 0 || running.size > 0) {
+        for (let index = 0; index < pending.length && running.size < Math.max(1, jobs);) {
+            const plan = pending[index];
+            if (plan === undefined || !isReady(plan)) {
+                index++;
+                continue;
+            }
+            pending.splice(index, 1);
+            running.set(plan.name, runStep(plan, now).then((result) => {
+                results.set(plan.name, result);
+                running.delete(plan.name);
+            }));
+        }
+        if (running.size === 0)
+            break;
+        await Promise.race(running.values());
+    }
+    return plans.flatMap((plan) => {
+        const result = results.get(plan.name);
+        return result === undefined ? [] : [result];
+    });
+}