@hominis/fireforge 0.45.0 → 0.46.0

package/dist/src/commands/setup.js

@@ -8,7 +8,7 @@ import { ConfigError } from '../errors/config.js';
 import { cancel, intro, isCancel, note, outro, spinner } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { FIREFOX_PRODUCTS, PROJECT_LICENSES } from '../utils/validation.js';
-import { buildSetupConfig, parseFirefoxProductOption, parseProjectLicenseOption, resolveSetupInputs, validateSetupOptions, writeSetupProjectFiles, } from './setup-support.js';
+import { buildSetupConfig, resolveFirefoxProduct, resolveProjectLicense, resolveSetupInputs, validateSetupOptions, writeSetupProjectFiles, } from './setup-support.js';
 /**
  * Runs the setup command.
  * @param projectRoot - Root directory for the project
@@ -83,16 +83,10 @@ export function registerSetup(program, { withErrorHandling }) {
         if (yes === true)
             setupOptions.force = true;
         if (product !== undefined) {
-            const parsedProduct = parseFirefoxProductOption(product);
-            if (parsedProduct !== undefined) {
-                setupOptions.product = parsedProduct;
-            }
+            setupOptions.product = resolveFirefoxProduct(product, '--product');
         }
         if (license !== undefined) {
-            const parsedLicense = parseProjectLicenseOption(license);
-            if (parsedLicense !== undefined) {
-                setupOptions.license = parsedLicense;
-            }
+            setupOptions.license = resolveProjectLicense(license, '--license');
         }
         await setupCommand(resolve(process.cwd()), setupOptions);
     }));

package/dist/src/commands/source.js

@@ -87,7 +87,14 @@ export async function sourceSetCommand(projectRoot, options) {
 }
 /** Registers the source command on the CLI program. */
 export function registerSource(program, { getProjectRoot, withErrorHandling }) {
-    const source = program.command('source').description('Manage Firefox source configuration');
+    const source = program
+        .command('source')
+        .description('Manage Firefox source configuration')
+        // No-subcommand contract shared with `patch`/`token`/`furnace`: help on
+        // stdout, exit 0 (see `handleParseError` for the groups without an action).
+        .action(() => {
+        source.outputHelp();
+    });
     source
         .command('set')
         .description('Atomically set Firefox source version, product, and optional checksum')

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

@@ -95,9 +95,9 @@ export function runStatusCheck(classified, policy) {
     const offending = collectStatusCheckOffenders(classified, policy).map((offender) => {
         const preview = offender.files.slice(0, CHECK_FILE_PREVIEW_MAX).join(', ');
         const more = offender.count > CHECK_FILE_PREVIEW_MAX
-            ? `, +${String(offender.count - CHECK_FILE_PREVIEW_MAX)} more`
+            ? `, +${offender.count - CHECK_FILE_PREVIEW_MAX} more`
             : '';
-        return `${String(offender.count)} ${offender.classification} (${preview}${more})`;
+        return `${offender.count} ${offender.classification} (${preview}${more})`;
     });
     if (offending.length === 0)
         return;

package/dist/src/commands/status-output.js

@@ -219,7 +219,7 @@ export function renderTestCoverageStatus(baseline) {
         return;
     }
     const list = coverage.map((path) => `  - ${path}`).join('\n');
-    info(`Test packaging coverage: scoped to ${String(coverage.length)} path(s):\n${list}\n` +
+    info(`Test packaging coverage: scoped to ${coverage.length} path(s):\n${list}\n` +
         'A "fireforge test" over paths outside this list will be refused as uncovered.');
-    outro(`Coverage: scoped (${String(coverage.length)} paths)`);
+    outro(`Coverage: scoped (${coverage.length} paths)`);
 }

package/dist/src/commands/status.js

@@ -15,7 +15,7 @@ import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { FIREFORGE_TMP_PATH_PATTERN, pathExists } from '../utils/fs.js';
 import { info, intro, isMachineOutputMode, outro, setMachineOutputMode, warn, } from '../utils/logger.js';
 import { emitMachineError } from '../utils/machine-output.js';
-import { resolveStatusCheckPolicy, runStatusCheck } from './status-check.js';
+import { resolveStatusCheckPolicy, runStatusCheck, } from './status-check.js';
 import { renderJsonStatus, renderJsonSummaryStatus } from './status-json.js';
 import { renderDefaultStatus, renderTestCoverageStatus, renderUnmanagedOnly, } from './status-output.js';
 import { buildOwnershipJsonBlock, collectOwnershipRows, summarizeOwnership, } from './status-ownership.js';
@@ -253,7 +253,6 @@ async function runStatusCommandBody(projectRoot, options) {
     const config = await loadConfig(projectRoot);
     // Shared envelope: see src/utils/machine-output.ts and
     // docs/machine-output.md. `status` was the only command that had one.
-    const emitJsonError = emitMachineError;
     // Ownership mode is a flat file→patch table; sources are the manifest's
     // filesAffected, any worktree drift, and the cross-patch
     // duplicate-new-file-creation map produced by walking each patch body. The
@@ -292,14 +291,14 @@ async function runStatusCommandBody(projectRoot, options) {
     // message is kept identical to the helper's on purpose.
     if (!(await pathExists(paths.engine))) {
         if (options.json) {
-            emitJsonError('engine-missing', 'Firefox source not found. Run "fireforge download" first.');
+            emitMachineError('engine-missing', 'Firefox source not found. Run "fireforge download" first.');
         }
         throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
     }
     // Check if it's a git repository
     if (!(await isGitRepository(paths.engine))) {
         if (options.json) {
-            emitJsonError('engine-not-git', 'Engine directory is not a git repository. Run "fireforge download" to initialize.');
+            emitMachineError('engine-not-git', 'Engine directory is not a git repository. Run "fireforge download" to initialize.');
         }
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }

package/dist/src/commands/test-build-phase.d.ts

@@ -3,8 +3,8 @@
  * the per-file line budget): the incremental protected mach build with
  * its baseline write, and the `--build-only` union-build shape.
  */
-import type { getProjectPaths, loadConfig } from '../core/config.js';
 import type { TestOptions } from '../types/commands/index.js';
+import type { FireForgeConfig, ProjectPaths } from '../types/config.js';
 import type { HarnessClassification } from './test-modes.js';
 /**
  * Runs the pre-test build (or the stale-build gate when no build was
@@ -13,7 +13,7 @@ import type { HarnessClassification } from './test-modes.js';
  * (mixed harnesses legal, nothing dispatches), prints the per-harness
  * next steps, and emits the run's single `PASS` verdict.
  */
-export declare function runTestBuildPhase(projectRoot: string, paths: ReturnType<typeof getProjectPaths>, projectConfig: Awaited<ReturnType<typeof loadConfig>>, harnessRetries: number, options: TestOptions, request: {
+export declare function runTestBuildPhase(projectRoot: string, paths: ProjectPaths, projectConfig: FireForgeConfig, harnessRetries: number, options: TestOptions, request: {
     classification: HarnessClassification;
     normalizedPaths: string[];
 }): Promise<boolean>;

package/dist/src/commands/test-build-phase.js

@@ -16,7 +16,14 @@ import { info, notice, spinner, verbose } from '../utils/logger.js';
 import { reportBuildOnlyCompletion } from './test-modes.js';
 import { enforceStaleBuildGate, enforceStaticComponentsGate } from './test-stale-gate.js';
 import { emitPassVerdict } from './test-verdict.js';
-async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries, testPackagingCoverage, refuseUnexportedDrift, extend) {
+/**
+ * Runs the incremental pre-test build under the build lock and records the
+ * baseline it produced.
+ *
+ * @param options - See {@link RunPreTestBuildOptions}
+ */
+async function runPreTestBuild(options) {
+    const { projectRoot, paths, projectConfig, harnessRetries, testPackagingCoverage, refuseUnexportedDrift, extend, } = options;
     await withBuildLock(projectRoot, async () => {
         // Pass the previous baseline exactly like `fireforge build` does, so
         // auto-configure runs under the same conditions on both paths. The
@@ -81,11 +88,20 @@ async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries
                 const recordedCoverage = extend !== undefined
                     ? unionTestPackagingCoverage(previousBaseline?.testPackagingCoverage, extend.requestedPaths)
                     : testPackagingCoverage;
-                await writeBuildBaseline(projectRoot, paths.engine, projectConfig.binaryName, recordedCoverage, previousBaseline, describeBuildInvocation(extend !== undefined, testPackagingCoverage), preparation.fullBuildRequired
-                    ? 'refresh'
-                    : extend !== undefined
-                        ? 'carry-forward'
-                        : 'auto', buildKind);
+                await writeBuildBaseline({
+                    projectRoot,
+                    engineDir: paths.engine,
+                    binaryName: projectConfig.binaryName,
+                    testPackagingCoverage: recordedCoverage,
+                    previousBaseline,
+                    recordedBy: describeBuildInvocation(extend !== undefined, testPackagingCoverage),
+                    staticComponentsHandling: preparation.fullBuildRequired
+                        ? 'refresh'
+                        : extend !== undefined
+                            ? 'carry-forward'
+                            : 'auto',
+                    buildKind,
+                });
             }
             catch (baselineError) {
                 verbose(`Could not persist build baseline: ${toError(baselineError).message}`);
@@ -166,7 +182,15 @@ export async function runTestBuildPhase(projectRoot, paths, projectConfig, harne
                 }
             }
         }
-        await runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries, coverage, options.refuseUnexportedDrift === true, extending ? { requestedPaths: normalizedPaths } : undefined);
+        await runPreTestBuild({
+            projectRoot,
+            paths,
+            projectConfig,
+            harnessRetries,
+            testPackagingCoverage: coverage,
+            refuseUnexportedDrift: options.refuseUnexportedDrift === true,
+            extend: extending ? { requestedPaths: normalizedPaths } : undefined,
+        });
         info('');
         if (options.buildOnly) {
             // Union build for mixed harnesses: the coverage claim

package/dist/src/commands/test-modes.d.ts

@@ -1,7 +1,7 @@
-import { loadConfig } from '../core/config.js';
 import type { TestOptions } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
 import type { TestRunOutcome } from './test-run.js';
-type ProjectConfig = Awaited<ReturnType<typeof loadConfig>>;
+type ProjectConfig = FireForgeConfig;
 /** Rejects pathless `fireforge test` unless the operator selected a pathless mode. */
 export declare function assertPathlessTestMode(testPaths: readonly string[], options: TestOptions): void;
 /** Rejects invalid combinations for mode-like `fireforge test` options. */

package/dist/src/commands/test-modes.js

@@ -1,5 +1,4 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { loadConfig } from '../core/config.js';
 import { findNearestXpcshellManifest } from '../core/xpcshell-appdir.js';
 import { GeneralError } from '../errors/base.js';
 import { info, success } from '../utils/logger.js';

package/dist/src/commands/test-register.js

@@ -28,7 +28,7 @@ const TEST_HELP_TEXT = [
     'Machine-readable verdict: every run (single, sharded, --canary,',
     '--doctor) ends with exactly one raw stdout line',
     '  FIREFORGE-VERDICT: PASS|FAIL [reason=crash|test-failures|',
-    '  no-tests|preflight|inconclusive|lock-timeout] [checks=<n>]',
+    '  no-tests|preflight|inconclusive|lock-timeout|killed] [checks=<n>]',
     '  [unexpected=<n>] [shards=<p>/<t>] [(<note>)] [log=<path>]',
     "log=<path> names this run's complete output, written to",
     '.fireforge/logs/ as the run streams, so a piped or truncated run',
@@ -41,7 +41,9 @@ const TEST_HELP_TEXT = [
     'errors); reason=inconclusive means engine/ changed while the',
     'tests ran, so the harness result cannot be trusted;',
     'reason=lock-timeout means the run never started because another',
-    'engine-mutating command held the lock past the wait budget. A sharded',
+    'engine-mutating command held the lock past the wait budget;',
+    'reason=killed means a signal terminated the run before it reached',
+    'any other outcome (written from the signal handler). A sharded',
     'aggregate reason is the most structural failing shard (crash,',
     'then no-tests, then test-failures). Count keys are omitted when',
     'the embedded summary did not print them. A trailing parenthetical',
@@ -71,7 +73,7 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         .option('--canary [path]', 'Run one short browser-chrome harness canary. Uses test.canaryPath from fireforge.json when no path is supplied.')
         .option('--doctor', 'Run a marionette handshake preflight before tests (exit 1 on FAIL). With no paths, runs the preflight only.')
         .option('--mach-arg <arg>', 'Forward this argument verbatim to `mach test` (repeatable). Escape valve for upstream xpcshell/mochitest flags FireForge does not model.', ...stringListOption())
-        .option('--harness-retries <n>', `Retry budget for recognized harness crashes (resource-monitor tracebacks, pre-test hangs, post-green shutdown re-entry). 0 disables retries. Default: ${String(DEFAULT_HARNESS_RETRIES)}.`, commanderArgParser((raw) => {
+        .option('--harness-retries <n>', `Retry budget for recognized harness crashes (resource-monitor tracebacks, pre-test hangs, post-green shutdown re-entry). 0 disables retries. Default: ${DEFAULT_HARNESS_RETRIES}.`, commanderArgParser((raw) => {
         const n = Number.parseInt(raw, 10);
         if (!Number.isFinite(n) || n < 0 || n > 10) {
             throw new GeneralError(`--harness-retries must be an integer in 0..10 (got "${raw}")`);

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

@@ -11,7 +11,7 @@
  * stays available via `--no-shard`.
  */
 import { probeDisplaySleepState } from '../core/display-state.js';
-import { mochitestWithOutput, testWithOutput, xpcshellTestWithOutput, } from '../core/mach.js';
+import { runMachTestSuite } from '../core/mach.js';
 import { getActiveRunLogPath } from '../core/run-log.js';
 import { changedPrefNoiseVerdictNote } from '../core/test-changed-prefs.js';
 import { buildHarnessCrashMessage, classifyHarnessRun, headedDisplayAsleepVerdictNote, headedNoOutputTimeoutHint, } from '../core/test-harness-crash.js';
@@ -24,13 +24,13 @@ import { maybeInjectAppdirArg } from './test-appdir.js';
 import { emitHarnessVerdict } from './test-verdict.js';
 /** Default bounded retry budget for recognized harness crashes. */
 export const DEFAULT_HARNESS_RETRIES = 2;
-/** Resolves the capturing mach dispatcher for a suite. */
-function dispatchForSuite(suite) {
+/** Resolves the mach test command a suite dispatches to. */
+function machKindForSuite(suite) {
     if (suite === 'xpcshell')
-        return xpcshellTestWithOutput;
+        return 'xpcshell-test';
     if (suite === 'mochitest')
-        return mochitestWithOutput;
-    return testWithOutput;
+        return 'mochitest';
+    return 'test';
 }
 /**
  * Runs one mach test invocation for `paths`, retrying recognized harness
@@ -54,24 +54,31 @@ export async function runTestsWithRetries(ctx, paths) {
 async function runTestsWithRetriesInner(ctx, paths, env) {
     const extraArgs = [...ctx.baseExtraArgs];
     const appdirInjectionAttempted = await maybeInjectAppdirArg(ctx.engineDir, paths, ctx.objDir, extraArgs);
-    const dispatch = dispatchForSuite(ctx.suite);
+    const kind = machKindForSuite(ctx.suite);
     const maxAttempts = Math.max(1, ctx.harnessRetries + 1);
     let attempts = 0;
     let result;
     let verdict;
     for (;;) {
         attempts += 1;
-        // Arity is kept minimal when there is nothing extra to pass: the
-        // dispatchers' trailing parameters are optional, and appending explicit
-        // `undefined`s would only make every call site's shape depend on
-        // features the run is not using.
-        result =
-            ctx.fullOutput === true
-                ? await dispatch(ctx.engineDir, paths, extraArgs, env, true)
-                : env
-                    ? await dispatch(ctx.engineDir, paths, extraArgs, env)
-                    : await dispatch(ctx.engineDir, paths, extraArgs);
-        result = await retryAfterXpcshellSymlinkRepair(ctx.engineDir, ctx.objDir, result, ctx.classification, paths, extraArgs, env, dispatch, ctx.fullOutput);
+        result = await runMachTestSuite(kind, {
+            engineDir: ctx.engineDir,
+            testPaths: paths,
+            args: extraArgs,
+            env,
+            fullOutput: ctx.fullOutput,
+        });
+        result = await retryAfterXpcshellSymlinkRepair({
+            engineDir: ctx.engineDir,
+            objDir: ctx.objDir,
+            result,
+            classification: ctx.classification,
+            normalizedPaths: paths,
+            extraArgs,
+            env,
+            kind,
+            fullOutput: ctx.fullOutput,
+        });
         const combined = `${result.stdout}\n${result.stderr}`;
         verdict = classifyHarnessRun(result.exitCode, combined, paths);
         if (verdict.kind !== 'harness-crash' || attempts >= maxAttempts)

package/dist/src/commands/test-stale-gate.js

@@ -8,7 +8,7 @@
  * `src/core/test-stale-check.ts`.
  */
 import { checkStaleBuildForTest, checkStaticComponentsStale, findChangedTestManifestsForPaths, findUncoveredRequestPaths, formatStaleBuildWarning, formatStaticComponentsRefusal, formatTestCoverageRefusal, } from '../core/test-stale-check.js';
-import { GeneralError } from '../errors/base.js';
+import { PreflightRefusalError } from '../errors/base.js';
 import { warn } from '../utils/logger.js';
 /**
  * Stale-build preflight — when `--build` was NOT requested, detect packageable
@@ -40,7 +40,7 @@ export async function enforceStaleBuildGate(projectRoot, engineDir, options, nor
             // The refusal is correct on its own; naming the manifest that gained
             // an entry is the triage step it otherwise leaves to the reader.
             const changedManifests = await findChangedTestManifestsForPaths(engineDir, stale.baseline, uncovered);
-            throw new GeneralError(formatTestCoverageRefusal(uncovered, Array.isArray(recordedCoverage) ? recordedCoverage : [], changedManifests));
+            throw new PreflightRefusalError(formatTestCoverageRefusal(uncovered, Array.isArray(recordedCoverage) ? recordedCoverage : [], changedManifests), 'coverage-replaced');
         }
     }
     await enforceStaticComponentsGate(engineDir, stale.baseline, options);
@@ -59,7 +59,7 @@ export async function enforceStaleBuildGate(projectRoot, engineDir, options, nor
             warn(staleMessage);
         }
         else {
-            throw new GeneralError(staleMessage);
+            throw new PreflightRefusalError(staleMessage, 'stale-build');
         }
     }
 }
@@ -84,5 +84,5 @@ export async function enforceStaticComponentsGate(engineDir, baseline, options)
         warn(message);
         return;
     }
-    throw new GeneralError(message);
+    throw new PreflightRefusalError(message, 'stale-components');
 }

package/dist/src/commands/test-verdict.d.ts

@@ -30,8 +30,22 @@ export declare function emitHarnessVerdict(verdict: HarnessRunVerdict, shards?:
 }): void;
 /** Emits the pathless `--doctor` PASS verdict. */
 export declare function emitPassVerdict(): void;
-/** Emits a FAIL verdict carrying an emission-layer reason code. */
-export declare function emitFailVerdict(reason: FireforgeVerdictReason): void;
+/**
+ * Emits a FAIL verdict carrying an emission-layer reason code, and
+ * optionally the refusal class that produced it.
+ *
+ * `note=` is ADDITIVE, like the `log=`, `signal=` and `shards=` keys already
+ * on this line: `reason=` is unchanged and still comes from the closed set
+ * in `docs/machine-output.md`, so a consumer that tokenises `key=value`
+ * pairs is unaffected. It exists because `reason=preflight` covers every
+ * gate before the harness — a missing build, a peer's packaging record, a
+ * developer browser holding the objdir — and an unattended reader whose
+ * pipe kept only the verdict line could not tell those apart.
+ *
+ * @param reason - Closed-set verdict reason
+ * @param note - Stable refusal class, when the thrower named one
+ */
+export declare function emitFailVerdict(reason: FireforgeVerdictReason, note?: string): void;
 /**
  * Emits the terminal verdict for a run killed by a signal.
  *

package/dist/src/commands/test-verdict.js

@@ -61,9 +61,24 @@ export function emitHarnessVerdict(verdict, shards) {
 export function emitPassVerdict() {
     writeVerdictLine('FIREFORGE-VERDICT: PASS');
 }
-/** Emits a FAIL verdict carrying an emission-layer reason code. */
-export function emitFailVerdict(reason) {
-    writeVerdictLine(`FIREFORGE-VERDICT: FAIL reason=${reason}`);
+/**
+ * Emits a FAIL verdict carrying an emission-layer reason code, and
+ * optionally the refusal class that produced it.
+ *
+ * `note=` is ADDITIVE, like the `log=`, `signal=` and `shards=` keys already
+ * on this line: `reason=` is unchanged and still comes from the closed set
+ * in `docs/machine-output.md`, so a consumer that tokenises `key=value`
+ * pairs is unaffected. It exists because `reason=preflight` covers every
+ * gate before the harness — a missing build, a peer's packaging record, a
+ * developer browser holding the objdir — and an unattended reader whose
+ * pipe kept only the verdict line could not tell those apart.
+ *
+ * @param reason - Closed-set verdict reason
+ * @param note - Stable refusal class, when the thrower named one
+ */
+export function emitFailVerdict(reason, note) {
+    const suffix = note === undefined ? '' : ` note=${note}`;
+    writeVerdictLine(`FIREFORGE-VERDICT: FAIL reason=${reason}${suffix}`);
 }
 /**
  * Emits the terminal verdict for a run killed by a signal.

package/dist/src/commands/test.js

@@ -9,12 +9,13 @@ import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
 import { assertMarionettePortAvailable, ensureLaunchableBrowserNotRunning, ensureMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
 import { ensureMochitestServerPortAvailable } from '../core/mochitest-server-port.js';
-import { closeActiveRunLog, openRunLog, setActiveRunLog } from '../core/run-log.js';
+import { closeActiveRunLog, openRunLog, setActiveRunLog, writeToActiveRunLog, } from '../core/run-log.js';
 import { createPostRebuildFailureContext } from '../core/test-harness-output.js';
 import { analyzeTestPathScopes, formatScopeNotice, } from '../core/test-path-scope.js';
 import { assertObjdirMatchesTreeMarker } from '../core/tree-store.js';
-import { GeneralError } from '../errors/base.js';
+import { FireForgeError, GeneralError, PreflightRefusalError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, notice, outro, verbose } from '../utils/logger.js';
 import { stripEnginePrefix } from '../utils/paths.js';
@@ -292,14 +293,50 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         await runTestCommandBody(projectRoot, testPaths, options);
     }
     catch (error) {
-        if (!verdictEmitted())
-            emitFailVerdict('preflight');
+        if (!verdictEmitted()) {
+            renderPreflightRefusal(error);
+            emitFailVerdict('preflight', refusalNote(error));
+        }
         throw error;
     }
     finally {
         await closeActiveRunLog();
     }
 }
+/** The refusal class a preflight gate named, when it named one. */
+function refusalNote(error) {
+    return error instanceof PreflightRefusalError ? error.note : undefined;
+}
+/**
+ * Puts a preflight refusal's own text on the operator's channel BEFORE the
+ * verdict line, and into the run log.
+ *
+ * Both halves are load-bearing, and neither happened before:
+ *
+ *  - `withErrorHandling` renders `error.userMessage` back in `cli.ts`, but
+ *    by then `emitFailVerdict` has called `setStdoutSealed(true)` — the seal
+ *    that keeps the verdict the LAST stdout write — so `logError` routes to
+ *    stderr. A run captured with `> file` therefore kept the verdict and
+ *    dropped the reason.
+ *  - That same rendering happens after this function's caller returns, and
+ *    the `finally` below has already closed the run log. So the artifact the
+ *    verdict's own `log=` key points at did not contain the refusal either,
+ *    which is what left `.fireforge/logs/test-*.log` holding only the
+ *    pre-test build.
+ *
+ * Writing here, before the seal, fixes both without trading away the
+ * contract: the refusal lands on stdout and in the log, and the verdict
+ * line still comes last.
+ */
+function renderPreflightRefusal(error) {
+    const text = error instanceof FireForgeError ? error.userMessage : toError(error).message;
+    const block = `Preflight refused:\n${text}\n`;
+    // Raw stdout rather than the clack logger: this must land on the captured
+    // stream verbatim, and clack's renderer can drop output under non-TTY
+    // capture — the same reason the verdict line is written this way.
+    process.stdout.write(block);
+    writeToActiveRunLog(block);
+}
 /**
  * Verifies `engine/` did not change under the run before any PASS verdict
  * may print. On failure the run's verdict is `FAIL reason=inconclusive` —
@@ -392,7 +429,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
         extraArgs.push('--auto');
     }
     if (canaryPath !== undefined) {
-        extraArgs.push(`--timeout=${String(canaryTimeoutSeconds(projectConfig))}`);
+        extraArgs.push(`--timeout=${canaryTimeoutSeconds(projectConfig)}`);
     }
     // --mach-arg is a verbatim passthrough for upstream mach/xpcshell/mochitest
     // flags FireForge does not model directly (see the xpcshell appdir hint

package/dist/src/commands/token-list.d.ts

@@ -0,0 +1,26 @@
+/** Options accepted by {@link tokenListCommand}. */
+export interface TokenListOptions {
+    /** Restrict the report to one category. */
+    category?: string;
+    /** Emit the machine-readable envelope instead of the human report. */
+    json?: boolean;
+}
+/**
+ * Lists the categories declared in the tokens CSS with their token names,
+ * in file order.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param options - Filter and output-mode options
+ */
+export declare function tokenListCommand(projectRoot: string, options?: TokenListOptions): Promise<void>;
+/**
+ * Reports one token: the category that owns it and the value it takes in
+ * every block that declares it.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param tokenName - Custom-property name, with or without the leading `--`
+ * @param options - Output-mode options
+ */
+export declare function tokenShowCommand(projectRoot: string, tokenName: string, options?: {
+    json?: boolean;
+}): Promise<void>;