@hominis/fireforge 0.55.0 → 0.60.0

package/docs/workspaces.md

@@ -0,0 +1,187 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# Workspaces and parallel work
+
+A **workspace** is a Firefox engine with its object directory (the build output), at a stable path, that commands build, run and test in. This page explains where workspaces live, how parallel sessions share a host, and what the host keeps under `~/.fireforge`.
+
+- In **patch mode** the project's `engine/` is its one workspace. Commands that use it take the engine lock (`.fireforge/locks/engine`) exclusively; `check` and dry runs take it shared, so they overlap each other but not a writer. One patch-mode project is one session at a time.
+- In **source mode** workspaces live in a per-host pool. A command leases one for its duration, brings it to its checkout's `src/` (materialization, see [source-workflow.md](source-workflow.md#materialization)) and gives it back when it ends. Parallel sessions are separate git worktrees, each leasing its own workspace.
+
+The rest of this page is about source mode, except the host locks, which apply in both.
+
+## Parallel sessions are git worktrees
+
+A session is a checkout of the project. Make one per line of work with `git worktree`:
+
+```sh
+git worktree add ../mybrowser-sidebar -b sidebar
+git worktree add ../mybrowser-toolbar -b toolbar
+```
+
+Each worktree has its own `src/`, its own `.fireforge/` state and its own branch, and shares the repository's refs and git config (so the merge driver and `refs/fireforge/verified` are shared). Run FireForge commands inside the worktree you are working in.
+
+## The pool
+
+```sh
+npx fireforge workspace list
+```
+
+```
+w1  firefox-esr-140.9.0esr  built  leased by PID 41822  last used by /Users/me/mybrowser-sidebar
+w2  firefox-esr-140.9.0esr  built  free  last used by /Users/me/mybrowser-toolbar
+```
+
+Each workspace is `~/.fireforge/workspaces/<name>/`, holding `engine/` (a checkout of the pin's pristine commit with the object directory `obj-fireforge` inside) and `workspace.json` (the pin, the last lessee, the build baseline), plus what FireForge records about the engine's content: the materialization ledger, the component deployment record, test run logs.
+
+The first command that needs a workspace for a pin creates `w1`. Further workspaces are your decision, because each costs tens of gigabytes once built:
+
+```sh
+npx fireforge workspace add w2
+npx fireforge workspace add w3 --from w1
+```
+
+- `workspace add <name>` checks the pinned Firefox out of the pristine repository.
+- `--from <name>` clones the engine of another workspace copy-on-write instead, with everything recorded about its content (the materialization ledger, the component deployment record), so the clone takes no disk space until it diverges. Its object directory and release build are not copied. Cloning needs a file system with copy-on-write clones (APFS on macOS, Btrfs or XFS with reflinks on Linux) and a source workspace that nobody leases.
+- Either way the new workspace needs a full build before it is useful (see [A build stays where it was configured](#a-build-stays-where-it-was-configured)).
+- `workspace add` runs inside a project, since the project names the pin.
+
+```sh
+npx fireforge workspace repair w2
+npx fireforge workspace remove w3
+```
+
+- `workspace repair <name>` restores every engine file to the pristine commit, removes added files, and forgets what was recorded about the engine's content, so the next lease materializes the checkout afresh. The object directory and the release build stay.
+- `workspace remove <name>` deletes the workspace and its build. It refuses while a command leases it, or while a process started from inside it (a browser left running) is alive.
+
+Both refuse a workspace that is leased.
+
+### A build stays where it was configured
+
+An object directory belongs to the absolute path it was configured at. FireForge never copies or moves a build to another path, and there is no command that brings an engine built elsewhere into the pool: add a workspace and build it.
+
+The reason is what a built object directory holds. `mach configure` at a new path regenerates its own output (`config.status`, the make backend, the install manifests), and nothing makes the build regenerate the rest, which keeps naming the old source:
+
+- `.cargo/config.toml` points cargo at the vendored crates of the old source, and the recorded output of Rust build scripts names the old object directory as a link search path.
+- Some of cargo's dependency records hold absolute source paths in a binary format.
+- Generated sources embed the paths, some in an escaped spelling that a search for the path does not find.
+- The dependency files of every compiled object, and the install tracking files, list old absolute paths. While the old directory exists, make judges staleness by its files, not by the ones being built.
+
+A build continued from such a directory would read, link and judge staleness against another workspace without saying so. So when `fireforge build` finds an object directory configured for another path (a project directory that was moved or renamed, a pool under a `FIREFORGE_HOME` that changed, an engine copied by hand), it warns, removes that object directory and builds from nothing. Moving the directory back before building keeps the build.
+
+## Leasing
+
+A command that works in a workspace (`bootstrap`, `build`, `run`, `test`, `typecheck`, `check`, `watch`, `package`, `gate`, and the `furnace` commands that deploy or compare) leases one for exactly as long as it runs:
+
+1. It takes a free workspace on the project's pin, preferring the one this checkout used last (its object directory is warm for this source, so builds are incremental), then the least recently used.
+2. It materializes the checkout into it.
+3. It runs. `watch` holds its workspace until you stop it.
+4. It releases the workspace. The lease is a lock under `~/.fireforge/locks/`, so a command that dies gives its workspace back by dying.
+
+`--workspace <name>` picks a specific workspace. A workspace on another pin is refused; a patch-mode project refuses `--workspace`.
+
+Commands that only read owned changes (`status`, `verify`, `lint`, `export`) take no workspace: they read `src/` and the pristine repository directly.
+
+## Waiting
+
+When every workspace on the pin is leased, the command waits, naming the holders:
+
+```
+Waiting for a free workspace ("w1" by PID 41822 (checkout=/Users/me/mybrowser-sidebar, command=build)): 5s of up to 2h 00m.
+```
+
+The same applies to every other lock a command needs (the engine lock in patch mode, the display, a build slot). The default wait is two hours, long enough for the build holding it to finish. Change it per command or per shell:
+
+```sh
+npx fireforge build --wait-lock 600
+export FIREFORGE_WAIT_LOCK=0
+```
+
+`--wait-lock 0` fails at once instead of waiting. A wait that expires exits 15 (`lock-timeout`) and the work never started. Ctrl+C stops a wait.
+
+## Host locks
+
+Two locks are shared by every project and checkout on the host, in both modes:
+
+- **display**: one browser window at a time. `run` without `--headless`, `test --headed`, and headed gate lanes and smoke starts hold it, so two sessions do not fight over focus.
+- **build**: a counting lock on compiles. By default one `mach build` runs at a time on the host; raise it in `~/.fireforge/host.json`:
+
+```json
+{ "buildSlots": 2 }
+```
+
+`host.json` also takes `releaseSecrets`, an absolute directory holding the secret files a release build reads ([configuration.md](configuration.md#build)).
+
+## Host state
+
+Everything FireForge keeps per host lives under `~/.fireforge`, or under `$FIREFORGE_HOME` when that is set:
+
+| Path          | Holds                                                                                                |
+| ------------- | ---------------------------------------------------------------------------------------------------- |
+| `pristine/`   | One bare repository per pin (`pristine/firefox-esr-140.9.0esr/`), the archive imported as one commit |
+| `workspaces/` | The pool                                                                                             |
+| `locks/`      | The display, build and workspace locks                                                               |
+| `cache/`      | Downloaded and verified source archives                                                              |
+| `host.json`   | `buildSlots` and `releaseSecrets`                                                                    |
+
+Project state lives under `.fireforge/` in each checkout and is never committed: `state.json`, the gate's results and artifacts, the type-check cache, and in patch mode the engine lock, the build baseline and the test run logs.
+
+### Disk use
+
+A built workspace takes tens of gigabytes; the pool is usually the largest thing on the disk. To reclaim space:
+
+- `fireforge workspace remove <name>` for workspaces you do not need, including those on a pin no project uses after a rebase (`workspace list` shows each workspace's pin).
+- A pin's pristine repository and its cached archive are needed only while a project builds on that pin; `fireforge download` recreates them.
+- `fireforge doctor` reports free disk space.
+
+## When a workspace reports drift
+
+A workspace belongs to FireForge. When a file inside one was changed by something else, materialization stops with `materialize-drift`, lists the files, and names the repair:
+
+```
+error[materialize-drift]: Engine files changed outside FireForge; materialization would overwrite them:
+  browser/base/content/browser.js
+hint: Save anything you need from /Users/me/.fireforge/workspaces/w1/engine, then run "fireforge workspace repair w1" and retry.
+```
+
+Copy anything you want to keep into `src/`, then:
+
+```sh
+npx fireforge workspace repair w1
+```
+
+The build stays, so the next build is incremental. The same repair answers `journal-conflict` and `materialize-pin-mismatch`.
+
+## Worked example: two sessions
+
+Two pieces of work on one host with two workspaces.
+
+```sh
+cd ~/mybrowser
+npx fireforge build                    # creates and builds w1
+npx fireforge workspace add w2         # the first build in w2 is a full build
+git worktree add ../mybrowser-sidebar -b sidebar
+git worktree add ../mybrowser-toolbar -b toolbar
+```
+
+Terminal 1:
+
+```sh
+cd ~/mybrowser-sidebar
+npx fireforge override browser/base/content/browser-sidebar.js
+$EDITOR src/browser/base/content/browser-sidebar.js
+npx fireforge build --ui               # leases w1 or w2, materializes, builds
+npx fireforge test browser/base/content/test/sidebar/
+```
+
+Terminal 2, at the same time:
+
+```sh
+cd ~/mybrowser-toolbar
+$EDITOR src/browser/themes/shared/mybrowser-toolbar.css
+npx fireforge build --ui               # leases the other workspace
+npx fireforge run                      # waits for the display while terminal 1's headed test holds it
+```
+
+Each command leases whichever workspace is free and prefers the one its checkout used last, so each worktree keeps returning to its own warm object directory. With `buildSlots` at 1 the two compiles take turns; the rest runs side by side. A third worktree would wait for a free workspace, naming who holds them, until one is released or you add `w3`.
+
+When both branches are merged, the merge driver resolves two first touches of the same upstream file against its pristine blob ([source-workflow.md](source-workflow.md#the-merge-driver)).

package/package.json

@@ -1,54 +1,45 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.55.0",
-  "description": "FireForge — a build tool for customizing Firefox",
+  "version": "0.60.0",
+  "description": "FireForge \u2014 a build tool for customizing Firefox",
   "type": "module",
-  "main": "./dist/src/index.js",
-  "types": "./dist/src/index.d.ts",
   "exports": {
-    ".": {
-      "types": "./dist/src/index.d.ts",
-      "import": "./dist/src/index.js"
-    },
-    "./package.json": "./package.json",
-    "./*": null
+    "./package.json": "./package.json"
   },
   "bin": {
     "fireforge": "./dist/bin/fireforge.js"
   },
   "scripts": {
     "fireforge": "tsx bin/fireforge.ts",
-    "build": "npm run clean && tsc -p tsconfig.build.json && node ./scripts/generate-build-info.mjs",
+    "build": "npm run clean && node ./node_modules/@typescript/native/bin/tsc -p tsconfig.build.json && node ./scripts/generate-build-info.mjs",
     "clean": "node ./scripts/clean.mjs",
     "lint": "eslint src/ bin/ scripts/ eslint-rules/ eslint.config.js vitest.config.ts vitest.pack.config.ts",
     "lint:ci": "eslint src/ bin/ scripts/ eslint-rules/ eslint.config.js vitest.config.ts vitest.pack.config.ts --max-warnings 0",
     "lint:fix": "eslint src/ bin/ scripts/ eslint-rules/ eslint.config.js vitest.config.ts vitest.pack.config.ts --fix",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "typecheck": "node ./node_modules/@typescript/native/bin/tsc --noEmit -p tsconfig.json",
     "deadcode:check": "knip",
-    "deadcode:check:production": "knip --production --config knip.production.json",
-    "cycles:check": "dpdm --no-output --no-tree --no-warning --exit-code circular:1 src/index.ts bin/fireforge.ts",
+    "cycles:check": "dpdm --no-output --no-tree --no-warning --exit-code circular:1 bin/fireforge.ts",
     "test": "vitest run",
-    "test:package": "npm run pack:verify",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage && node ./scripts/check-coverage-thresholds.mjs",
+    "test:coverage": "vitest run --coverage",
     "test:firefox-full": "node ./scripts/run-full-firefox-integration.mjs",
     "whitespace:check": "node ./scripts/check-worktree-whitespace.mjs",
-    "pack:verify": "vitest run --config vitest.pack.config.ts",
     "pack:dry-run": "npm pack --dry-run --json --silent",
-    "format": "prettier --write --ignore-unknown \"src/**/*.ts\" \"bin/**/*.ts\" \"scripts/**/*.mjs\" \"eslint-rules/**/*.js\" \"package.json\" \"eslint.config.js\" \"vitest.config.ts\" \"vitest.pack.config.ts\" \"tsconfig.json\" \"tsconfig.build.json\" \".lintstagedrc.json\" \".prettierignore\" \".prettierrc\" \".gitignore\" \"README.md\" \"CHANGELOG.md\" \"docs/**/*.md\" \"knip.json\" \"knip.production.json\"",
-    "format:check": "prettier --check --ignore-unknown \"src/**/*.ts\" \"bin/**/*.ts\" \"scripts/**/*.mjs\" \"eslint-rules/**/*.js\" \"package.json\" \"eslint.config.js\" \"vitest.config.ts\" \"vitest.pack.config.ts\" \"tsconfig.json\" \"tsconfig.build.json\" \".lintstagedrc.json\" \".prettierignore\" \".prettierrc\" \".gitignore\" \"README.md\" \"CHANGELOG.md\" \"docs/**/*.md\" \"knip.json\" \"knip.production.json\"",
+    "pack:verify": "vitest run --config vitest.pack.config.ts",
+    "format": "prettier --write --ignore-unknown \"src/**/*.ts\" \"bin/**/*.ts\" \"scripts/**/*.mjs\" \"eslint-rules/**/*.js\" \"package.json\" \"eslint.config.js\" \"vitest.config.ts\" \"vitest.pack.config.ts\" \"tsconfig.json\" \"tsconfig.build.json\" \".lintstagedrc.json\" \".prettierignore\" \".prettierrc\" \".gitignore\" \"README.md\" \"CHANGELOG.md\" \"docs/**/*.md\" \"contributing/**/*.md\" \"knip.json\"",
+    "format:check": "prettier --check --ignore-unknown \"src/**/*.ts\" \"bin/**/*.ts\" \"scripts/**/*.mjs\" \"eslint-rules/**/*.js\" \"package.json\" \"eslint.config.js\" \"vitest.config.ts\" \"vitest.pack.config.ts\" \"tsconfig.json\" \"tsconfig.build.json\" \".lintstagedrc.json\" \".prettierignore\" \".prettierrc\" \".gitignore\" \"README.md\" \"CHANGELOG.md\" \"docs/**/*.md\" \"contributing/**/*.md\" \"knip.json\"",
     "prepare": "node -e \"import('./scripts/prepare.mjs').catch((error) => { if (error && typeof error === 'object' && 'code' in error && error.code === 'ERR_MODULE_NOT_FOUND') process.exit(0); throw error; })\"",
     "prepack": "npm run build && node ./scripts/generate-build-info.mjs --loud",
-    "release:check": "npm run toolchain:check && npm run format:check && npm run whitespace:check && npm run lint:ci && npm run typecheck && npm run deadcode:check && npm run deadcode:check:production && npm run cycles:check && npm run test:coverage && npm run pack:verify",
-    "prepublishOnly": "npm run release:check",
+    "release:check": "npm run toolchain:check && npm run format:check && npm run whitespace:check && npm run lint:ci && npm run typecheck && npm run deadcode:check && npm run cycles:check && npm run test:coverage && npm run build && npm run pack:verify",
+    "prepublishOnly": "node ./scripts/prepublish-gate.mjs",
     "toolchain:check": "node ./scripts/check-release-toolchain.mjs"
   },
   "files": [
     "dist/",
     "!dist/**/*.test.*",
-    "!dist/**/__tests__/",
-    "!dist/**/test-utils/",
+    "!dist/src/testing/",
     "!dist/**/*.js.map",
+    "!dist/**/*.d.ts",
     "templates/",
     "docs/",
     "README.md",
@@ -61,27 +52,28 @@
     "commander": "^15.0.0",
     "estree-walker": "^3.0.3",
     "jsonc-parser": "^3.3.1",
-    "magic-string": "^1.1.0",
+    "magic-string": "^1.4.5",
     "picocolors": "^1.1.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.0",
-    "@types/estree": "^1.0.8",
-    "@types/node": "^26.4.1",
+    "@types/estree": "^1.0.10",
+    "@types/node": "^26.6.6",
+    "@typescript/native": "npm:typescript@~7.0.2",
     "@vitest/coverage-v8": "^5.0.0",
     "dpdm": "4.3.0",
     "eslint": "^10.0.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-jsdoc": "^65.0.1",
+    "eslint-plugin-jsdoc": "^65.4.5",
     "eslint-plugin-simple-import-sort": "^14.0.0",
     "fast-check": "^4.6.0",
     "husky": "^9.1.7",
-    "knip": "6.42.1",
+    "knip": "6.44.1",
     "lint-staged": "^17.0.4",
     "prettier": "3.9.10",
     "tsx": "^4.7.0",
-    "typescript": "~6.0.0",
-    "typescript-eslint": "^8.0.0",
+    "typescript": "npm:@typescript/typescript6@~6.0.2",
+    "typescript-eslint": "^8.72.1",
     "vite": "^8.0.7",
     "vitest": "^5.0.0"
   },

package/templates/configs/common.mozconfig

@@ -1,11 +1,17 @@
 # Common mozconfig for ${name}
-# This file is merged with platform-specific configs
+# FireForge joins this file with the platform's into engine/mozconfig and
+# substitutes the project's name, vendor, appId and binaryName placeholders.
+# FireForge places the object directory itself: a template that sets
+# MOZ_OBJDIR is refused.
 
 # Application identity
 ac_add_options --with-app-name=${binaryName}
-ac_add_options --with-branding=browser/branding/${binaryName}
 export MOZ_APP_BASENAME=${binaryName}
 
+# Branding: uncomment once the engine holds browser/branding/${binaryName}
+# (with its moz.build). A build refuses a branding directory the engine lacks.
+# ac_add_options --with-branding=browser/branding/${binaryName}
+
 # Build options
 ac_add_options --enable-application=browser
 ac_add_options --enable-bootstrap

package/templates/configs/darwin.mozconfig

@@ -1,10 +1,9 @@
 # macOS-specific mozconfig for ${name}
 
-# Note: MOZ_MACBUNDLE_ID must be set via branding/configure.sh, not mozconfig.
-# It is automatically set when using --with-branding.
+# MOZ_MACBUNDLE_ID comes from the branding directory's configure.sh, not from
+# this file; FireForge passes the rest of the application ID as
+# --with-distribution-id.
 
-# Use system toolchain
-ac_add_options --with-macos-sdk=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk
-
-# Code signing (disabled for development)
-# ac_add_options --enable-apple-silicon (uncomment for ARM builds)
+# --enable-bootstrap (common.mozconfig) provides the macOS SDK. To build
+# against a local one instead:
+# ac_add_options --with-macos-sdk=/path/to/MacOSX.sdk

package/templates/configs/linux.mozconfig

@@ -1,12 +1,9 @@
 # Linux-specific mozconfig for ${name}
 
-# Use system libraries where available
-ac_add_options --with-system-zlib
-ac_add_options --with-system-jpeg
+# System libraries instead of the bundled ones (needs their development
+# packages installed):
+# ac_add_options --with-system-zlib
+# ac_add_options --with-system-jpeg
 
-# PGO disabled by default (can enable for release builds)
+# Link-time optimization, for release builds:
 # ac_add_options --enable-lto=cross
-# ac_add_options --enable-profile-generate
-
-# Wayland support
-ac_add_options --enable-default-toolkit=cairo-gtk3-wayland

package/templates/configs/win32.mozconfig

@@ -1,14 +1,8 @@
 # Windows-specific mozconfig for ${name}
 
-# Use Visual Studio toolchain
-ac_add_options --host=x86_64-pc-mingw32
-ac_add_options --target=x86_64-pc-mingw32
-
-# Windows SDK
-# ac_add_options --with-windows-version=10.0.19041.0
-
-# Clang-cl
-ac_add_options --enable-clang-cl
+# The default target is x86_64 Windows with clang-cl, provided by
+# --enable-bootstrap (common.mozconfig). For ARM64:
+# ac_add_options --target=aarch64-pc-windows-msvc
 
 # Disable maintenance service
 ac_add_options --disable-maintenance-service

package/dist/bin/fireforge.d.ts

@@ -1,9 +0,0 @@
-#!/usr/bin/env node
-/**
- * FireForge CLI entry point, and the only file that may call process.exit().
- * Library code propagates errors via CommandError or FireForgeError instead.
- *
- * The signal pipeline below composes several lifecycle modules. See
- * docs/lifecycle-invariants.md for who owns what.
- */
-export {};

package/dist/src/cli-usage-error.d.ts

@@ -1,46 +0,0 @@
-import { FireForgeError } from './errors/base.js';
-/**
- * Stable machine-readable tag for an error class, for the `--json` envelope.
- *
- * Derived from the class name rather than hand-mapped: a new error class gets
- * a sensible tag automatically, and the mapping cannot drift out of sync with
- * the taxonomy. `ConfigNotFoundError` becomes `config-not-found`.
- *
- * @param error - The error being rendered
- * @returns A kebab-case tag with the `Error` suffix stripped
- */
-export declare function machineErrorCode(error: FireForgeError): string;
-/**
- * Whether the invocation asked for machine-readable output.
- *
- * Reading the flag from argv is blunt but exact: if the invocation asked for
- * machine output, stdout belongs to the payload from the first byte, before
- * commander has parsed anything.
- *
- * @param argv - Process argv (defaults to `process.argv`)
- * @returns True when `--json` or `--raw` is present
- */
-export declare function wantsMachineOutput(argv?: readonly string[]): boolean;
-/**
- * Converts a `CommanderError` thrown out of `parseAsync` into the exit
- * contract, and rethrows anything else untouched.
- *
- * `--help` and `--version` also travel through `exitOverride()` (codes
- * `commander.helpDisplayed` / `commander.version`, exit 0): commander has
- * already written their output, so those simply return. So does
- * `commander.help`: a command group invoked with no subcommand (`fireforge`,
- * `fireforge tree`), for which commander prints the group's help and would
- * exit 1. That is an informational invocation rather than a wrong flag.
- * `patch`, `token` and `furnace` already answer it with help and exit 0
- * through an explicit action, and the groups without one must not exit 8 (or
- * leak commander's `(outputHelp)` placeholder into a `--json` envelope)
- * merely for lacking it. A genuine usage error has already had its message
- * written to stderr by commander. It becomes exit 8, and under `--json` it
- * also gets the standard refusal envelope on stdout so a scripted consumer
- * sees a parseable failure.
- *
- * @param error - Whatever `parseAsync` rejected with
- * @param machineOutput - Whether the invocation asked for `--json`/`--raw`
- * @throws CommandError carrying `INVALID_ARGUMENT` for a usage error
- */
-export declare function handleParseError(error: unknown, machineOutput: boolean): void;

package/dist/src/cli-usage-error.js

@@ -1,81 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Maps commander's own parse failures onto the FireForge exit-code contract.
- *
- * Commander terminates the process itself on a usage error (unknown option,
- * missing argument, unknown command) with exit 1, which contradicts the
- * documented `INVALID_ARGUMENT` (8) in `docs/exit-codes.md` and bypasses the
- * `--json` refusal envelope because no action (and therefore no
- * `withErrorHandling` wrapper) ever runs. `createProgram` installs
- * `exitOverride()` so those failures surface as a thrown `CommanderError`,
- * and `main` routes them through here.
- */
-import { CommanderError } from 'commander';
-import { CommandError, FireForgeError, InvalidArgumentError } from './errors/base.js';
-import { emitMachineError } from './utils/machine-output.js';
-/**
- * Stable machine-readable tag for an error class, for the `--json` envelope.
- *
- * Derived from the class name rather than hand-mapped: a new error class gets
- * a sensible tag automatically, and the mapping cannot drift out of sync with
- * the taxonomy. `ConfigNotFoundError` becomes `config-not-found`.
- *
- * @param error - The error being rendered
- * @returns A kebab-case tag with the `Error` suffix stripped
- */
-export function machineErrorCode(error) {
-    return error.name
-        .replace(/Error$/, '')
-        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
-        .toLowerCase();
-}
-/**
- * Whether the invocation asked for machine-readable output.
- *
- * Reading the flag from argv is blunt but exact: if the invocation asked for
- * machine output, stdout belongs to the payload from the first byte, before
- * commander has parsed anything.
- *
- * @param argv - Process argv (defaults to `process.argv`)
- * @returns True when `--json` or `--raw` is present
- */
-export function wantsMachineOutput(argv = process.argv) {
-    return argv.includes('--json') || argv.includes('--raw');
-}
-/**
- * Converts a `CommanderError` thrown out of `parseAsync` into the exit
- * contract, and rethrows anything else untouched.
- *
- * `--help` and `--version` also travel through `exitOverride()` (codes
- * `commander.helpDisplayed` / `commander.version`, exit 0): commander has
- * already written their output, so those simply return. So does
- * `commander.help`: a command group invoked with no subcommand (`fireforge`,
- * `fireforge tree`), for which commander prints the group's help and would
- * exit 1. That is an informational invocation rather than a wrong flag.
- * `patch`, `token` and `furnace` already answer it with help and exit 0
- * through an explicit action, and the groups without one must not exit 8 (or
- * leak commander's `(outputHelp)` placeholder into a `--json` envelope)
- * merely for lacking it. A genuine usage error has already had its message
- * written to stderr by commander. It becomes exit 8, and under `--json` it
- * also gets the standard refusal envelope on stdout so a scripted consumer
- * sees a parseable failure.
- *
- * @param error - Whatever `parseAsync` rejected with
- * @param machineOutput - Whether the invocation asked for `--json`/`--raw`
- * @throws CommandError carrying `INVALID_ARGUMENT` for a usage error
- */
-export function handleParseError(error, machineOutput) {
-    if (!(error instanceof CommanderError)) {
-        throw error;
-    }
-    if (error.exitCode === 0 || error.code === 'commander.help') {
-        return;
-    }
-    // Commander's message carries its own `error: ` prefix. Strip it so the
-    // envelope text matches how every other refusal reads.
-    const usage = new InvalidArgumentError(error.message.replace(/^error:\s*/, ''));
-    if (machineOutput) {
-        emitMachineError(machineErrorCode(usage), usage.message, usage.code);
-    }
-    throw new CommandError(usage.code);
-}

package/dist/src/cli.d.ts

@@ -1,41 +0,0 @@
-import { Command } from 'commander';
-/**
- * Installs a handler for broken-pipe (EPIPE) errors on stdout/stderr.
- * This is a process-level concern: when output is piped to a process that
- * closes early (e.g. `fireforge status | head`), Node emits EPIPE.
- * We treat this as a clean exit.
- */
-export declare function installBrokenPipeHandler(): void;
-/**
- * Removes the broken-pipe handler installed for CLI tests.
- *
- * @internal Exported only so tests can reach it. It is not part of the
- * public surface.
- */
-export declare function resetBrokenPipeHandlerForTests(): void;
-/**
- * Gets the project root directory.
- * Walks up from the current working directory until a fireforge.json is found.
- * Throws a {@link ConfigNotFoundError} (code: CONFIG_ERROR) when no
- * fireforge.json is found within the walk depth limit. The error is
- * user-facing so `withErrorHandling` can print the guidance without
- * the stack dump that a plain `Error` would trigger.
- */
-export declare function getProjectRoot(): string;
-/**
- * Wraps a command handler with error handling.
- *
- * Logs the user-visible error message and throws a {@link CommandError}
- * carrying the appropriate exit code. The actual `process.exit()` call
- * lives in the CLI entrypoint (`bin/fireforge.ts`), keeping shared library
- * code free of process-terminating side effects.
- */
-export declare function withErrorHandling<T extends unknown[]>(handler: (...args: T) => Promise<void>): (...args: T) => Promise<void>;
-/**
- * Creates and configures the CLI program.
- */
-export declare function createProgram(): Command;
-/**
- * Main CLI entry point.
- */
-export declare function main(): Promise<void>;