@hominis/fireforge 0.43.1 → 0.44.1

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

@@ -4,47 +4,18 @@
 /**
  * Result of a doctor check.
  *
- * Field precedence (consumers and producers must agree):
- *   1. `severity`, when present, is authoritative — `'error'` counts as a
- *      failure and `'warning'` as a warning REGARDLESS of `passed`.
- *   2. Without `severity`, `passed: false` is a failure unless
- *      `warning: true` downgrades it to a warning.
- * Producers should prefer setting `severity` explicitly; `warning` exists
- * for older checks that predate the field. Do not emit contradictory
- * combinations like `passed: true, severity: 'error'`.
+ * `severity` is the single source of truth; consumers that want a boolean
+ * derive it as `severity !== 'error'`.
  */
 export interface DoctorCheck {
     /** Name of the check */
     name: string;
-    /** Whether the check passed */
-    passed: boolean;
-    /** Severity of the result (authoritative when present — see above) */
-    severity?: 'ok' | 'warning' | 'error';
+    /** Outcome of the check. Authoritative and required. */
+    severity: 'ok' | 'warning' | 'error';
     /** Description of the result */
     message: string;
-    /** Suggested fix if check failed */
+    /** Suggested fix when the check did not pass */
     fix?: string;
-    /** Legacy warning flag for checks that predate `severity` */
-    warning?: boolean;
-}
-/**
- * Status of the project.
- */
-export interface ProjectStatus {
-    /** Whether fireforge.json exists */
-    hasConfig: boolean;
-    /** Whether engine/ exists */
-    hasEngine: boolean;
-    /** Whether patches/ exists */
-    hasPatches: boolean;
-    /** Number of patch files */
-    patchCount: number;
-    /** Whether build output exists */
-    hasBuild: boolean;
-    /** Firefox version from config */
-    firefoxVersion?: string;
-    /** Downloaded Firefox version */
-    downloadedVersion?: string;
 }
 /**
  * Per-file token coverage breakdown.

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

@@ -182,11 +182,10 @@ export interface TypecheckConfig {
      */
     projectOverrides?: Record<string, string | null>;
     /**
-     * How to report undefined free identifiers (TS2304/TS2552). These were
-     * historically suppressed as shim-gap noise, which also hid genuine
-     * missing imports until they crashed at runtime. Default
-     * `'warning'`: visible without failing the gate. `'error'` makes them
-     * blocking; `'off'` restores the historical suppression.
+     * How to report undefined free identifiers (TS2304/TS2552). Default
+     * `'warning'`: visible without failing the gate, since shim gaps produce
+     * the same diagnostic as a genuine missing import. `'error'` makes them
+     * blocking; `'off'` suppresses them.
      */
     undefinedIdentifiers?: PatchLintSeverityGate;
 }
@@ -235,9 +234,9 @@ export interface PatchLintConfig {
     checkJs?: boolean;
     /**
      * When true with `checkJs: true`, run checkJs with `strict` and
-     * `noImplicitAny` enabled (CI-style). Default false preserves the
-     * historical loose preset. Optional {@link checkJsCompilerOptions}
-     * can relax individual strict flags (e.g. `strictNullChecks: false`).
+     * `noImplicitAny` enabled (CI-style). Default false uses the loose preset.
+     * Optional {@link checkJsCompilerOptions} can relax individual strict
+     * flags (e.g. `strictNullChecks: false`).
      */
     checkJsStrict?: boolean;
     /**
@@ -249,27 +248,26 @@ export interface PatchLintConfig {
      * Project-relative path to an additional `.d.ts` file whose contents
      * are concatenated to the built-in `FIREFOX_GLOBALS_SHIM` for the
      * `patchLint.checkJs` pass. Same semantics as `typecheck.extraShim`
-     * but scoped to the patch-hygiene flow. Default unset = current
-     * behaviour (built-in shim only).
+     * but scoped to the patch-hygiene flow. Default unset: built-in shim only.
      */
     checkJsExtraShim?: string;
     /**
      * Extend the checkJs pass to patch-owned test `.js` files
      * (`browser_*` / `test_*` / `xpcshell_*` basenames and files under a
-     * `/test/` path), each checked as its own small script-scope program
-     * with same-directory patch-owned `head*.js` helpers included (FORGE
-     * G5 — a harness global that does not exist should fail at the patch
-     * boundary where the test was authored, not in a downstream
-     * jsconfig-project run). Opt-in: it is a new failure surface with
-     * nonzero compile cost. Requires `checkJs: true`.
+     * `/test/` path), each checked as its own small script-scope program with
+     * same-directory patch-owned `head*.js` helpers included, so a call to a
+     * harness global that does not exist fails at the patch boundary where the
+     * test was authored rather than in a downstream jsconfig-project run.
+     * Opt-in: it is a new failure surface with nonzero compile cost. Requires
+     * `checkJs: true`.
      */
     checkJsTestFiles?: boolean;
     /**
      * Project-relative `.d.ts` appended to the built-in test-harness shim
      * (loose `TestUtils`/`BrowserTestUtils`/`add_task`/… declarations) for
-     * the `checkJsTestFiles` pass — a consumer-typed `TestUtils` here is
-     * what turns a call to a nonexistent harness member into a TS2339 at
-     * export time. Requires `checkJsTestFiles: true`.
+     * the `checkJsTestFiles` pass. A consumer-typed `TestUtils` here is what
+     * turns a call to a nonexistent harness member into a TS2339 at export
+     * time. Requires `checkJsTestFiles: true`.
      */
     checkJsTestShim?: string;
     /** File paths exempt from the raw-color-value check (exact or basename match) */
@@ -291,16 +289,20 @@ export interface PatchLintConfig {
     chromeScriptJsDoc?: PatchLintSeverityGate;
     /**
      * How the checkJs pass reports undefined free identifiers
-     * (TS2304/TS2552). Same semantics as `typecheck.undefinedIdentifiers`
-     *; the two flows share the suppression policy so a patch
+     * (TS2304/TS2552). Same semantics as `typecheck.undefinedIdentifiers`;
+     * the two flows share the suppression policy so a patch
      * cannot pass one and fail the other. Default: 'warning'.
      */
     undefinedIdentifiers?: PatchLintSeverityGate;
 }
 /**
- * Build mode for mach.
+ * Build modes for mach.
+ *
+ * Derived from the list so the runtime allowlist cannot drift from the type.
  */
-export type BuildMode = 'dev' | 'debug' | 'release';
+export declare const BUILD_MODES: readonly ["dev", "debug", "release"];
+/** Build mode for mach. */
+export type BuildMode = (typeof BUILD_MODES)[number];
 /**
  * Runtime state stored in .fireforge/state.json.
  */

package/dist/src/types/config.js

@@ -1 +1,6 @@
-export {};
+/**
+ * Build modes for mach.
+ *
+ * Derived from the list so the runtime allowlist cannot drift from the type.
+ */
+export const BUILD_MODES = ['dev', 'debug', 'release'];

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

@@ -117,11 +117,10 @@ export interface FurnaceConfig {
     tokenAllowlist?: string[];
     /**
      * CSS custom-property prefixes that identify upstream / platform
-     * variables the fork does not own. `token coverage` counts matches
-     * as `allowlisted` rather than `unknown` so a copied upstream
-     * baseline doesn't drag fork-owned coverage percentages down.
-     * Defaults to `['--moz-']` when unset. Pass an explicit empty array
-     * to restore the pre-0.18.0 strict contract.
+     * variables the fork does not own. `token coverage` counts matches as
+     * `allowlisted` rather than `unknown` so a copied upstream baseline does
+     * not drag fork-owned coverage percentages down. Defaults to `['--moz-']`
+     * when unset; pass an explicit empty array to count every prefix.
      */
     platformPrefixes?: string[];
     /**
@@ -176,7 +175,13 @@ export interface FurnaceConfig {
  * state before clearing authoring markers. The string is surfaced in doctor's
  * failure message verbatim, so new entries should be self-explanatory.
  */
-export type FurnacePendingRepairOperation = 'preview-teardown' | 'apply-rollback' | 'deploy-rollback' | 'remove-rollback' | 'create-rollback' | 'override-rollback' | 'scan-rollback' | 'rename-rollback' | 'refresh-rollback' | 'chrome-doc-rollback';
+export declare const FURNACE_PENDING_REPAIR_OPERATIONS: readonly ["preview-teardown", "apply-rollback", "deploy-rollback", "remove-rollback", "create-rollback", "override-rollback", "scan-rollback", "rename-rollback", "refresh-rollback", "chrome-doc-rollback"];
+/**
+ * Operations that can leave a pending-repair marker when they fail to roll
+ * back cleanly. Derived from the list above so the runtime allowlist in
+ * `furnace-config.ts` cannot drift from the union.
+ */
+export type FurnacePendingRepairOperation = (typeof FURNACE_PENDING_REPAIR_OPERATIONS)[number];
 /**
  * Marker persisted into `.fireforge/furnace-state.json` when a furnace
  * mutation failed to roll back cleanly. Its presence tells the next
@@ -222,13 +227,10 @@ export interface StepError {
     step: string;
     error: string;
     /**
-     * Advisory step errors are reported as warnings and never trigger
-     * rollback or a non-zero exit. Used by the `.ftl` helpers, whose module
-     * contract is graceful degradation: a missing locale jar.mn on a fork
-     * without a locale package must not block a working `.mjs`/`.css` from
-     * shipping. Before this flag existed the contract was contradicted in
-     * practice — any FTL step error rolled back the entire apply, so a
-     * localized component on such a fork could never be applied at all.
+     * Advisory step errors are reported as warnings and never trigger rollback
+     * or a non-zero exit. Used by the `.ftl` helpers, whose module contract is
+     * graceful degradation: a missing locale jar.mn on a fork without a locale
+     * package must not block a working `.mjs`/`.css` from shipping.
      */
     advisory?: boolean;
 }
@@ -318,3 +320,25 @@ export interface ValidationIssue {
 }
 /** Resolved test-harness selection for a `furnace create` run. */
 export type ResolvedTestStyle = 'mochikit' | 'browser-chrome' | 'xpcshell' | 'none';
+/**
+ * The four paths and the name that every per-component apply, dry-run, FTL
+ * and drift helper needs some subset of.
+ *
+ * Passing these positionally is unsafe: they are all `string`, so any
+ * permutation typechecks against any other and a swap surfaces as a
+ * wrong-directory read at runtime. Helpers take
+ * `Pick<ComponentApplyContext, …>` of exactly the members they read, so a
+ * caller is never asked to invent a value it does not have.
+ */
+export interface ComponentApplyContext {
+    /** Project root — what registration consistency resolves against. */
+    root: string;
+    /** Firefox source directory the component deploys into. */
+    engineDir: string;
+    /** Component name as it appears in `furnace.json`. */
+    name: string;
+    /** Absolute path to the component's authoring directory. */
+    componentDir: string;
+    /** Engine-relative locale directory holding the component's `.ftl`. */
+    ftlDir: string;
+}

package/dist/src/types/furnace.js

@@ -1 +1,19 @@
-export {};
+/**
+ * Operations that can leave a pending-repair marker when they fail to roll
+ * back cleanly. The marker is consumed by `fireforge doctor`, which either
+ * re-runs apply for engine-side failures or validates the current authoring
+ * state before clearing authoring markers. The string is surfaced in doctor's
+ * failure message verbatim, so new entries should be self-explanatory.
+ */
+export const FURNACE_PENDING_REPAIR_OPERATIONS = [
+    'preview-teardown',
+    'apply-rollback',
+    'deploy-rollback',
+    'remove-rollback',
+    'create-rollback',
+    'override-rollback',
+    'scan-rollback',
+    'rename-rollback',
+    'refresh-rollback',
+    'chrome-doc-rollback',
+];

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

@@ -1,6 +1,6 @@
 /**
  * Re-exports all type definitions.
  */
-export type { BuildOptions, DiscardOptions, DoctorCheck, DownloadOptions, ExportOptions, FurnaceCreateOptions, FurnaceOverrideOptions, FurnaceRemoveOptions, GlobalOptions, ImportOptions, ImportSummary, PackageOptions, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchMetadata, PatchResult, ProjectStatus, ReExportOptions, ResetOptions, RunOptions, SetupOptions, TestOptions, TokenCoverageFileEntry, TokenCoverageReport, } from './commands/index.js';
-export type { BuildConfig, BuildMode, FireForgeConfig, FireForgeState, FirefoxConfig, FirefoxProduct, ProjectLicense, ProjectPaths, WireConfig, } from './config.js';
-export type { ApplyResult, ComponentType, CustomComponentConfig, DryRunAction, FurnaceConfig, FurnaceState, OverrideComponentConfig, OverrideType, RegistrationStatus, ScannedComponent, StepError, SyncResult, ValidationIssue, } from './furnace.js';
+export type {} from './commands/index.js';
+export type { BuildConfig, FireForgeConfig, FirefoxConfig, FirefoxProduct, ProjectLicense, ProjectPaths, WireConfig, } from './config.js';
+export type { ApplyResult, ComponentType, CustomComponentConfig, DryRunAction, FurnaceConfig, FurnaceState, OverrideComponentConfig, OverrideType, StepError, ValidationIssue, } from './furnace.js';

package/dist/src/utils/build-info.d.ts

@@ -3,14 +3,13 @@ export interface BuildIdentity {
     shortCommit: string;
     dirty: boolean;
     /**
-     * Content hash of the uncommitted diff, present only for a DIRTY
-     * installed build. Two packs from the same HEAD with
-     * different uncommitted content share `shortCommit` and the `.dirty`
-     * marker, so without this they report byte-identical `--version`
-     * strings — which is what made a field report against
-     * `0.41.0+g<sha>.dirty` impossible to trace back to a specific pack.
-     * Absent in a git checkout: identity there comes from live git, and
-     * hashing the full diff on every `--version` call is not worth it.
+     * Content hash of the uncommitted diff, present only for a DIRTY installed
+     * build. Two packs from the same HEAD with different uncommitted content
+     * share `shortCommit` and the `.dirty` marker, so without this they report
+     * byte-identical `--version` strings and a report against
+     * `<semver>+g<sha>.dirty` cannot be traced back to a specific pack. Absent
+     * in a git checkout: identity there comes from live git, and hashing the
+     * full diff on every `--version` call is not worth it.
      */
     dirtyHash?: string;
 }

package/dist/src/utils/build-info.js

@@ -1,20 +1,21 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Build identity for `--version`. Three distinct builds
- * shipped as plain "0.41.0" — consumers had to fingerprint tarballs by
- * sha256 to know which build a claim was verified against. `--version`
- * now reports `<semver>+g<short-sha>[.dirty[.<content-hash>]]`:
+ * Build identity for `--version`.
  *
- * - In a git checkout (dev runs via tsx), identity comes from live git —
- *   a stale `dist/build-info.json` from an old build must never win.
- * - In an installed package, it comes from `dist/build-info.json`,
- *   stamped by scripts/generate-build-info.mjs at build/pack time.
+ * Distinct builds shipping as the same plain semver leave consumers
+ * fingerprinting tarballs by sha256 to know which build a claim was verified
+ * against. `--version` reports `<semver>+g<short-sha>[.dirty[.<content-hash>]]`:
+ *
+ * - In a git checkout (dev runs via tsx), identity comes from live git — a
+ *   stale `dist/build-info.json` from an old build must never win.
+ * - In an installed package, it comes from `dist/build-info.json`, stamped
+ *   by scripts/generate-build-info.mjs at build/pack time.
  * - When neither yields an identity, `--version` degrades to the plain
  *   semver. Reading identity must never throw.
  *
- * Deliberately NOT wired into the per-patch lint cache key: identity
- * would churn the cache on every commit at the same semver for no
- * correctness gain (`getPackageVersion` stays the cache input).
+ * Deliberately NOT wired into the per-patch lint cache key: identity would
+ * churn the cache on every commit at the same semver for no correctness gain
+ * (`getPackageVersion` stays the cache input).
  */
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';

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

@@ -20,9 +20,8 @@ export declare function toError(error: unknown): Error;
  * The check is deliberately structural rather than `error instanceof Error`:
  * a plain object carrying `.code` — exactly the shape {@link toError} exists
  * to normalise — reaches errno consumers through rejected promises and
- * cross-realm throws. Nine hand-rolled copies of this predicate existed
- * before 0.41.0, four of them (in `utils/fs.ts`) gated on `instanceof Error`
- * and so misclassified that shape as "no code".
+ * cross-realm throws, and an `instanceof Error` gate misclassifies it as "no
+ * code".
  */
 export declare function getNodeErrorCode(error: unknown): string | undefined;
 /**
@@ -32,10 +31,9 @@ export declare function getNodeErrorCode(error: unknown): string | undefined;
  * Only `ESRCH` ("no such process") means dead. **`EPERM` means ALIVE**: the
  * process exists but is owned by another uid, which happens routinely with
  * root-owned builds, `sudo`, shared CI runners and container UID mismatches.
- * Two copies of this predicate (`tree-store.ts`, `doctor-furnace.ts`) read
- * EPERM as dead before 0.41.0, and both gated a recursive delete — a live
- * build's tree clone and a live furnace lock were removed out from under
- * their owner. Any other errno is treated as "unknown, assume alive", which
- * is the safe direction for every caller: it refuses rather than destroys.
+ * Reading EPERM as dead in a predicate that gates a recursive delete removes
+ * a live build's tree clone or a live furnace lock out from under its owner.
+ * Any other errno is treated as "unknown, assume alive", the safe direction
+ * for every caller: it refuses rather than destroys.
  */
 export declare function isProcessAlive(pid: number): boolean;

package/dist/src/utils/errors.js

@@ -32,9 +32,8 @@ export function toError(error) {
  * The check is deliberately structural rather than `error instanceof Error`:
  * a plain object carrying `.code` — exactly the shape {@link toError} exists
  * to normalise — reaches errno consumers through rejected promises and
- * cross-realm throws. Nine hand-rolled copies of this predicate existed
- * before 0.41.0, four of them (in `utils/fs.ts`) gated on `instanceof Error`
- * and so misclassified that shape as "no code".
+ * cross-realm throws, and an `instanceof Error` gate misclassifies it as "no
+ * code".
  */
 export function getNodeErrorCode(error) {
     if (typeof error === 'object' &&
@@ -52,11 +51,10 @@ export function getNodeErrorCode(error) {
  * Only `ESRCH` ("no such process") means dead. **`EPERM` means ALIVE**: the
  * process exists but is owned by another uid, which happens routinely with
  * root-owned builds, `sudo`, shared CI runners and container UID mismatches.
- * Two copies of this predicate (`tree-store.ts`, `doctor-furnace.ts`) read
- * EPERM as dead before 0.41.0, and both gated a recursive delete — a live
- * build's tree clone and a live furnace lock were removed out from under
- * their owner. Any other errno is treated as "unknown, assume alive", which
- * is the safe direction for every caller: it refuses rather than destroys.
+ * Reading EPERM as dead in a predicate that gates a recursive delete removes
+ * a live build's tree clone or a live furnace lock out from under its owner.
+ * Any other errno is treated as "unknown, assume alive", the safe direction
+ * for every caller: it refuses rather than destroys.
  */
 export function isProcessAlive(pid) {
     try {

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

@@ -12,6 +12,25 @@ export declare function setMachineOutputMode(enabled: boolean): void;
 export declare function isMachineOutputMode(): boolean;
 /** Seals (or unseals) stdout after a machine-readable final line. */
 export declare function setStdoutSealed(sealed: boolean): void;
+/**
+ * True when a machine-readable payload already owns stdout.
+ *
+ * The CLI error boundary consults this before emitting a `--json` error
+ * envelope: a command that wrote its payload and THEN refused (e.g.
+ * `status --json --fail-on`) must not have a second JSON document appended,
+ * which would break the "exactly one document" half of the contract in
+ * docs/machine-output.md.
+ */
+export declare function isStdoutSealed(): boolean;
+/**
+ * Checks if verbose mode is enabled.
+ *
+ * Exported so the CLI error boundary can decide whether to walk an error's
+ * `cause` chain.
+ *
+ * @returns True if verbose mode is enabled
+ */
+export declare function isVerbose(): boolean;
 /**
  * Displays a verbose/debug message (only shown if verbose mode is enabled).
  * @param message - Message to display
@@ -49,13 +68,13 @@ export declare const NOTICE_PREFIX = "[FireForge] NOTICE:";
  *
  * These lines are not warnings about the operator's code — they explain a
  * decision FireForge just made (escalating an incremental build to a full
- * one, sharding a run, skipping a step). Emitted through `info` they were
+ * one, sharding a run, skipping a step). Emitted through `info` they are
  * silently dropped by agent-facing output filters that keep only warnings
  * and errors, leaving a multi-minute build with no explanation and reading
  * as a hang. There are very few such lines and they are exactly the ones a
- * non-interactive operator needs, so they ride the warning channel and
- * carry {@link NOTICE_PREFIX} so a reader can still tell them apart from a
- * real warning.
+ * non-interactive operator needs, so they ride the warning channel and carry
+ * {@link NOTICE_PREFIX} so a reader can still tell them apart from a real
+ * warning.
  */
 export declare function notice(message: string): void;
 /** Logs an error message. */
@@ -80,12 +99,10 @@ export declare function cancel(message: string): void;
  * Checks whether a prompt result represents a user cancellation.
  *
  * Narrows to `symbol` — clack returns its cancel sentinel as a symbol and
- * `p.isCancel` is itself a type predicate. This wrapper erased that narrowing
- * by returning plain `boolean` until 0.41.0, which forced eleven `as string`
- * / `as PatchCategory` / `as OverrideType` casts across six command modules
- * on the *non*-cancelled branch, where the value is already known not to be
- * the sentinel. Keep the predicate form: it is the single highest-leverage
- * signature in the codebase for escape-hatch count.
+ * `p.isCancel` is itself a type predicate. Returning plain `boolean` erases
+ * that narrowing and forces `as string` / `as PatchCategory` casts across
+ * the command modules on the *non*-cancelled branch, where the value is
+ * already known not to be the sentinel. Keep the predicate form.
  */
 export declare function isCancel(value: unknown): value is symbol;
 /** Displays a titled note block for follow-up details. */

package/dist/src/utils/logger.js

@@ -9,11 +9,9 @@ let verboseMode = false;
  * In machine mode, stdout belongs EXCLUSIVELY to the machine-readable
  * payload: all human-facing diagnostics (intro/outro banners, info, warn,
  * error, steps, notes) are routed to stderr as plain unstyled lines.
- * Before this mode existed, clack's log helpers wrote styled warnings to
- * stdout *before* the JSON body — a truncated-directory warning during
- * `status --json` broke every `JSON.parse(stdout)` consumer, and error
- * objects on the machine contract were followed by a styled duplicate on
- * the same stream.
+ * Otherwise clack's log helpers write styled warnings to stdout *before* the
+ * JSON body — a truncated-directory warning during `status --json` breaks
+ * every `JSON.parse(stdout)` consumer.
  */
 let machineOutputMode = false;
 /**
@@ -50,6 +48,18 @@ let stdoutSealed = false;
 export function setStdoutSealed(sealed) {
     stdoutSealed = sealed;
 }
+/**
+ * True when a machine-readable payload already owns stdout.
+ *
+ * The CLI error boundary consults this before emitting a `--json` error
+ * envelope: a command that wrote its payload and THEN refused (e.g.
+ * `status --json --fail-on`) must not have a second JSON document appended,
+ * which would break the "exactly one document" half of the contract in
+ * docs/machine-output.md.
+ */
+export function isStdoutSealed() {
+    return stdoutSealed;
+}
 /** True when human output must avoid stdout. */
 function routeToStderr() {
     return machineOutputMode || stdoutSealed;
@@ -60,9 +70,13 @@ function writeDiagnostic(prefix, message) {
 }
 /**
  * Checks if verbose mode is enabled.
+ *
+ * Exported so the CLI error boundary can decide whether to walk an error's
+ * `cause` chain.
+ *
  * @returns True if verbose mode is enabled
  */
-function isVerbose() {
+export function isVerbose() {
     return verboseMode;
 }
 /**
@@ -128,13 +142,13 @@ export const NOTICE_PREFIX = '[FireForge] NOTICE:';
  *
  * These lines are not warnings about the operator's code — they explain a
  * decision FireForge just made (escalating an incremental build to a full
- * one, sharding a run, skipping a step). Emitted through `info` they were
+ * one, sharding a run, skipping a step). Emitted through `info` they are
  * silently dropped by agent-facing output filters that keep only warnings
  * and errors, leaving a multi-minute build with no explanation and reading
  * as a hang. There are very few such lines and they are exactly the ones a
- * non-interactive operator needs, so they ride the warning channel and
- * carry {@link NOTICE_PREFIX} so a reader can still tell them apart from a
- * real warning.
+ * non-interactive operator needs, so they ride the warning channel and carry
+ * {@link NOTICE_PREFIX} so a reader can still tell them apart from a real
+ * warning.
  */
 export function notice(message) {
     if (routeToStderr()) {
@@ -238,12 +252,10 @@ export function cancel(message) {
  * Checks whether a prompt result represents a user cancellation.
  *
  * Narrows to `symbol` — clack returns its cancel sentinel as a symbol and
- * `p.isCancel` is itself a type predicate. This wrapper erased that narrowing
- * by returning plain `boolean` until 0.41.0, which forced eleven `as string`
- * / `as PatchCategory` / `as OverrideType` casts across six command modules
- * on the *non*-cancelled branch, where the value is already known not to be
- * the sentinel. Keep the predicate form: it is the single highest-leverage
- * signature in the codebase for escape-hatch count.
+ * `p.isCancel` is itself a type predicate. Returning plain `boolean` erases
+ * that narrowing and forces `as string` / `as PatchCategory` casts across
+ * the command modules on the *non*-cancelled branch, where the value is
+ * already known not to be the sentinel. Keep the predicate form.
  */
 export function isCancel(value) {
     return p.isCancel(value);

package/dist/src/utils/machine-output.d.ts

@@ -0,0 +1,12 @@
+import { ExitCode } from '../errors/codes.js';
+/** Current envelope version. Bump only with a documented migration. */
+export declare const MACHINE_OUTPUT_SCHEMA_VERSION = 1;
+/**
+ * Writes the machine-readable error envelope to stdout and throws the
+ * sentinel that carries the exit code to the entrypoint. Never returns.
+ *
+ * @param code - Stable machine-readable reason tag, e.g. `engine-missing`
+ * @param message - Human-readable explanation, identical to the non-JSON text
+ * @param exitCode - Exit code to terminate with
+ */
+export declare function emitMachineError(code: string, message: string, exitCode?: ExitCode): never;

package/dist/src/utils/machine-output.js

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The `--json` envelope contract, in one place.
+ *
+ * Without a single owner, machine-readable output drifts into unrelated
+ * shapes: two commands sharing a `schemaVersion: 1` envelope can still
+ * disagree on failure, so a scripted consumer gets a parseable refusal from
+ * one and a bare non-zero exit from the other.
+ *
+ * The contract, documented in `docs/machine-output.md`:
+ *   1. Success writes exactly one JSON document to stdout.
+ *   2. Failure writes exactly one `{ schemaVersion, error, code }` document
+ *      to stdout, then exits non-zero.
+ *   3. Machine mode is engaged BEFORE any output, so every diagnostic —
+ *      including one rendered later by `withErrorHandling` — routes to
+ *      stderr and cannot corrupt the payload.
+ */
+import { CommandError } from '../errors/base.js';
+import { ExitCode } from '../errors/codes.js';
+/** Current envelope version. Bump only with a documented migration. */
+export const MACHINE_OUTPUT_SCHEMA_VERSION = 1;
+/**
+ * Writes the machine-readable error envelope to stdout and throws the
+ * sentinel that carries the exit code to the entrypoint. Never returns.
+ *
+ * @param code - Stable machine-readable reason tag, e.g. `engine-missing`
+ * @param message - Human-readable explanation, identical to the non-JSON text
+ * @param exitCode - Exit code to terminate with
+ */
+export function emitMachineError(code, message, exitCode = ExitCode.GENERAL_ERROR) {
+    process.stdout.write(`${JSON.stringify({ schemaVersion: MACHINE_OUTPUT_SCHEMA_VERSION, error: message, code })}\n`);
+    throw new CommandError(exitCode);
+}