@hominis/fireforge 0.45.0 → 0.46.1

package/docs/machine-output.md

@@ -6,8 +6,8 @@ The `--json` surface is a contract with scripted consumers. Before 0.44.0 it
 was four unrelated shapes: `status --json` and `tree list --json` shared a
 `schemaVersion: 1` envelope but disagreed on failure, `test` emitted a
 `FIREFORGE-VERDICT:` line, and `lint --per-patch --report` wrote a versioned
-file nothing ever reads back. This file is the single statement of what a
-`--json` command must do, so the next one added does not invent a fifth.
+file that nothing ever reads back. This file states what a `--json` command
+has to do, so the next one added does not invent a fifth shape.
 
 ## The rules
 
@@ -16,22 +16,23 @@ file nothing ever reads back. This file is the single statement of what a
 2. **Failure writes exactly one error document to stdout**, of the shape
    `{ "schemaVersion": 1, "error": "<human message>", "code": "<tag>" }`,
    and then exits non-zero. The `error` text is the same sentence the
-   non-JSON mode would print; `code` is a stable machine-readable tag
-   (`engine-missing`, `engine-not-git`, `tree-list-failed`, …) that consumers
-   may branch on.
+   non-JSON mode would print. `code` is a stable machine-readable tag
+   (`engine-missing`, `engine-not-git`, `tree-list-failed`, and so on) that
+   consumers may branch on.
 3. **Machine mode is engaged before any output.** `setMachineOutputMode(true)`
-   must run before the first write, so every diagnostic — including one
-   rendered later by `withErrorHandling` — routes to stderr and cannot
+   has to run before the first write, so that every diagnostic, including one
+   rendered later by `withErrorHandling`, goes to stderr and cannot
    interleave with the payload.
 4. **stdout carries nothing else.** No banners, no progress, no warnings.
    `logger.ts` enforces this through a single `routeToStderr()` gate that all
-   its helpers consult, including `spinner()`, `note()` and `intro`/`outro`.
+   of its helpers consult, including `spinner()`, `note()` and
+   `intro`/`outro`.
 
 ## Implementation
 
 Use `emitMachineError` from `src/utils/machine-output.ts` for rule 2. It
 writes the envelope and throws `CommandError`, which the CLI boundary treats
-as already-rendered — so the boundary adds no second rendering on stderr.
+as already rendered, so the boundary adds no second rendering on stderr.
 
 ```ts
 if (options.json === true) {
@@ -52,22 +53,24 @@ if (options.json === true) {
 
 ## Current surfaces
 
-| Surface                            | Shape                                                 | Notes                                                                                                                                                                                                                              |
-| ---------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `status --json`                    | `{ schemaVersion: 1, … }`                             | Error envelope on three engine preconditions                                                                                                                                                                                       |
-| `tree list --json`                 | `{ schemaVersion: 1, trees }`                         | Error envelope added in 0.44.0                                                                                                                                                                                                     |
-| `test` verdict line                | `FIREFORGE-VERDICT: PASS\|FAIL reason=… [log=<path>]` | Not JSON. A single final stdout line, sealed by `setStdoutSealed` so nothing can displace it. `log=` names the run's own complete output under `.fireforge/logs/`, so a piped or truncated run still leaves a re-readable artifact |
-| `lint --per-patch --report <path>` | `{ schemaVersion: 1, … }`                             | Written to a file, never read back by FireForge                                                                                                                                                                                    |
-| `status --raw`                     | `git status --porcelain` lines                        | Not JSON, but a machine surface: it engages the same stdout discipline, so rules 3 and 4 apply and rules 1 and 2 do not. A clean tree prints nothing                                                                               |
-| `build` log announcement           | `Full build output: <path>`                           | Not JSON. `build` prints no verdict line, so it names its run log directly on the way out                                                                                                                                          |
-
-`--raw` is why `cli.ts` reads `process.argv` for `--json` **or** `--raw`
-before dispatching: rule 3 is about who owns stdout, and that question is
-settled the same way for a porcelain stream as for a JSON document.
+| Surface                            | Shape                                                                | Notes                                                                                                                                                                                                                              |
+| ---------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `status --json`                    | `{ schemaVersion: 1, … }`                                            | Error envelope on three engine preconditions                                                                                                                                                                                       |
+| `tree list --json`                 | `{ schemaVersion: 1, trees }`                                        | Error envelope added in 0.44.0                                                                                                                                                                                                     |
+| `token list --json`                | `{ schemaVersion: 1, tokensCssPath, categories }`                    | Categories in file order, each with its tokens (`name`, `line`, `value`)                                                                                                                                                           |
+| `token show --json`                | `{ schemaVersion: 1, name, category, declarations }`                 | One entry per declaring block, with its selector trail and line                                                                                                                                                                    |
+| `test` verdict line                | `FIREFORGE-VERDICT: PASS\|FAIL reason=… [note=<class>] [log=<path>]` | Not JSON. A single final stdout line, sealed by `setStdoutSealed` so nothing can displace it. `log=` names the run's own complete output under `.fireforge/logs/`, so a piped or truncated run still leaves a re-readable artifact |
+| `lint --per-patch --report <path>` | `{ schemaVersion: 1, … }`                                            | Written to a file, never read back by FireForge                                                                                                                                                                                    |
+| `status --raw`                     | `git status --porcelain` lines                                       | Not JSON, but still a machine surface: it engages the same stdout discipline, so rules 3 and 4 apply and rules 1 and 2 do not. A clean tree prints nothing                                                                         |
+| `build` log announcement           | `Full build output: <path>`                                          | Not JSON. `build` prints no verdict line, so it names its run log directly on the way out                                                                                                                                          |
+
+`--raw` is why `cli.ts` reads `process.argv` for `--json` or `--raw` before
+dispatching. Rule 3 is about who owns stdout, and that question is settled
+the same way for a porcelain stream as for a JSON document.
 
 `doctor` and `verify` have no `--json` mode. `doctor` already computes a
-serializable `DoctorCheck[]`, so adding one is cheap if a consumer asks —
-follow the rules above rather than inventing a shape.
+serializable `DoctorCheck[]`, so adding one is cheap if a consumer asks for
+it. Follow the rules above rather than inventing a shape.
 
 The run logs behind `log=` are specified in [`run-logs.md`](run-logs.md).
 
@@ -75,20 +78,41 @@ The run logs behind `log=` are specified in [`run-logs.md`](run-logs.md).
 
 `schemaVersion` is `MACHINE_OUTPUT_SCHEMA_VERSION` in
 `src/utils/machine-output.ts`. Additive changes (a new key) do not bump it.
-Removing or retyping a key does, and needs a note in the changelog naming
-what moved.
+Removing or retyping a key does, and needs a changelog note saying what
+moved.
 
 ## `test` verdict reasons
 
 `FIREFORGE-VERDICT: FAIL reason=<reason>` uses a closed set
 (`FireforgeVerdictReason`, `src/commands/test-verdict.ts`):
 
-| Reason          | Meaning                                                                                                                                                                                                              |
-| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `crash`         | The harness or the browser died; no trustworthy suite result.                                                                                                                                                        |
-| `no-tests`      | The run dispatched but nothing ran.                                                                                                                                                                                  |
-| `test-failures` | The suite ran and reported unexpected results.                                                                                                                                                                       |
-| `preflight`     | The run was refused before the harness was reached.                                                                                                                                                                  |
-| `inconclusive`  | A result exists but `engine/` moved under it, so it was discarded.                                                                                                                                                   |
-| `lock-timeout`  | The run never started: the engine session lock stayed contended.                                                                                                                                                     |
-| `killed`        | A signal terminated the run. Written from the signal handler so a log tail is always self-describing — a killed run must never be silent, or "killed", "still running" and "never started" become indistinguishable. |
+| Reason          | Meaning                                                                                                                                                                                                      |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `crash`         | The harness or the browser died, so there is no trustworthy suite result.                                                                                                                                    |
+| `no-tests`      | The run dispatched but nothing ran.                                                                                                                                                                          |
+| `test-failures` | The suite ran and reported unexpected results.                                                                                                                                                               |
+| `preflight`     | The run was refused before the harness was reached.                                                                                                                                                          |
+| `inconclusive`  | A result exists, but `engine/` moved under it, so the result was discarded.                                                                                                                                  |
+| `lock-timeout`  | The run never started: the engine session lock stayed contended.                                                                                                                                             |
+| `killed`        | A signal terminated the run. Written from the signal handler so that a log tail always describes itself. A killed run must never be silent, or "killed", "still running" and "never started" all look alike. |
+
+### The additive `note=` key
+
+A `FAIL reason=preflight` line covers every gate before the harness: a
+missing build, a peer's packaging record replacing this session's, a
+developer browser holding the objdir. An unattended reader whose pipe kept
+only the verdict line could not tell those apart, so a preflight refusal that
+can classify itself also emits `note=<class>`.
+
+`note=` is additive, like `log=`, `signal=` and `shards=`. `reason=` is
+unchanged and still comes from the closed set above, so a consumer that
+tokenises `key=value` pairs is unaffected, and a gate that names no class
+emits no `note=` at all. The classes are not a closed set and may grow, so
+consumers should treat an unrecognised one as opaque. Current values:
+`stale-browser`, `stale-browser-kill-failed`, `marionette-port-busy`,
+`coverage-replaced`, `stale-build`, `stale-components`.
+
+A preflight refusal's own text is written to stdout before the verdict line,
+and into the run log, so the verdict stays the last stdout write while the
+reason survives both a redirect and a `tail`. See
+[`run-logs.md`](run-logs.md).

package/docs/patch-workflow.md

@@ -2,9 +2,9 @@
 
 # Patch workflow
 
-The day-to-day loop: change code inside `engine/`, export it, keep the queue
-applying cleanly. `fireforge --help` remains the authority on flags; this file
-covers the behaviour that a flag list cannot state.
+The day-to-day loop: change code inside `engine/`, export it, and keep the
+queue applying cleanly. `fireforge --help` is the authority on flags. This
+file covers the behavior a flag list cannot state.
 
 ## The loop
 
@@ -18,13 +18,13 @@ npx fireforge verify
 
 ## Exporting
 
-Patch names are normalized on export and rename: `window-chrome-tests`,
+Patch names are normalized on export and rename, so `window-chrome-tests`,
 `ui-window-chrome-tests`, and `235-ui-window-chrome-tests` all resolve to the
 same `<order>-ui-window-chrome-tests.patch` shape.
 
-For large generated asset batches, `re-export --scan --scan-files <manifest>`
-assigns files to their owner patches without broad directory scanning. The
-manifest is JSON:
+For large batches of generated assets, `re-export --scan --scan-files
+<manifest>` assigns files to their owner patches without scanning whole
+directories. The manifest is JSON:
 
 ```json
 {
@@ -34,75 +34,79 @@ manifest is JSON:
 }
 ```
 
-The command is dry-runnable, refuses ambiguous ownership, and reports each
+The command can be dry-run, refuses ambiguous ownership, and reports each
 file-to-patch assignment before refreshing the patch.
 
-Scan-less `re-export` previews drift; `--refuse-foreign-drift --expect <path>`
-restricts it to intended files.
+`re-export` without a scan previews drift. `--refuse-foreign-drift --expect
+<path>` restricts it to the files you intended.
 
 ### Deletions
 
-A deleted upstream file is captured like any other change: a path that is
-tracked in HEAD but absent from disk stays in the diff scope, and the emitted
-patch carries a `deleted file mode` section. A captured deletion keeps its
-`filesAffected` entry — the patch is what performs the deletion, so pruning
-the entry would leave the body deleting a file the manifest says the patch has
-nothing to do with — and it still requires the confirmation, because the patch
-will remove those files wherever it is applied.
+A deleted upstream file is captured like any other change: a path tracked in
+HEAD but absent from disk stays in the diff scope, and the emitted patch
+carries a `deleted file mode` section. A captured deletion keeps its
+`filesAffected` entry, because the patch is what performs the deletion, and
+pruning the entry would leave the body deleting a file the manifest says the
+patch has nothing to do with. It also still requires the confirmation,
+because the patch will remove those files wherever it is applied.
 
-An **untracked** absent path is refused rather than warned about: a patch
+An untracked absent path is refused rather than warned about, because a patch
 cannot express it either way. The `--files` path also refuses when any
-requested path produces no hunk, checked against the full requested list
-rather than the post-filter subset, so nothing dropped upstream can pass as a
-silent success.
+requested path produces no hunk. That is checked against the full requested
+list rather than the subset left after filtering, so nothing dropped upstream
+can pass as a silent success.
 
 ## Queue maintenance
 
 Under `fireforge patch`:
 
-- `patch compact` closes ordinal gaps (range-aware when `patchPolicy.ranges`
-  is configured).
+- `patch compact` closes ordinal gaps, and is range-aware when
+  `patchPolicy.ranges` is configured.
 - `patch reorder` moves a patch.
 - `patch split <source> --files <paths...> --name <name>` carves files out of
-  a patch into a new one as a single transaction — including staged-dependency
-  owner rewrites — with `--dry-run` support.
+  a patch into a new one as a single transaction, including staged-dependency
+  owner rewrites, and supports `--dry-run`.
 - `patch rename` also supports `--category` and `--order`.
 
-Every queue-mutating patch command accepts `--wait-lock [seconds]`; see
-[`configuration.md`](configuration.md#lock-waits) for how the budget resolves.
+Every queue-mutating patch command accepts `--wait-lock [seconds]`. See
+[`configuration.md`](configuration.md#lock-waits) for how the budget
+resolves.
 
 ## Linting the queue
 
 `lint --per-patch --patches` accepts repeated flags, comma lists, full
-filenames/stems, manifest names, category-prefixed slugs, and bare slugs.
+filenames or stems, bare order numbers, manifest names, category-prefixed
+slugs, and bare slugs.
 
 `lint --per-patch --max-warnings 0` is the warning-clean form for a release
 gate.
 
 `lint --per-patch --report <path>` writes a machine-readable JSON report with
-each patch's line count, tier, active size thresholds, issues, and
-`lintIgnore`-suppressed issues. The size metrics
-(`countNonBinaryDiffLines`, `resolvePatchSizeTier`, `getPatchSizeThresholds`)
-are also exported on the programmatic API.
+each patch's line count, tier, active size thresholds, issues, and issues
+suppressed by `lintIgnore`. The size metrics (`countNonBinaryDiffLines`,
+`resolvePatchSizeTier`, `getPatchSizeThresholds`) are also exported on the
+programmatic API.
 
-Per-patch lint type-checks plain Firefox JS against a built-in Firefox-globals
-shim that tracks upstream WebIDL additions per release. See
+Per-patch lint type-checks plain Firefox JS against a built-in
+Firefox-globals shim that tracks upstream WebIDL additions per release. See
 [`configuration.md`](configuration.md#patchlint) for the project hooks
 (`checkJsExtraShim`, `checkJsTestFiles`, `checkJsTestShim`).
 
-For release whitespace checks, use `npm run whitespace:check`; it still checks
-source diffs while excluding generated `patches/*.patch` diff syntax.
+For release whitespace checks, use `npm run whitespace:check`. It still
+checks source diffs while excluding the diff syntax of generated
+`patches/*.patch` files.
 
 ## CI enforcement
 
 `fireforge status --check` exits non-zero when any unmanaged, drifted, or
 conflicted file exists. `--fail-on <class,...>` tunes the policy set, and
-`--json` composes — the JSON stays parseable and its `files[]` entries name
-the owning `patch`. `--include-ownership` adds ownership rows to JSON status
-output.
+`--json` composes with it: the JSON stays parseable and its `files[]` entries
+name the owning `patch`. `--include-ownership` adds ownership rows to JSON
+status output.
 
-The JSON shapes are specified in [`machine-output.md`](machine-output.md), and
-the codes a script should branch on in [`exit-codes.md`](exit-codes.md).
+The JSON shapes are specified in [`machine-output.md`](machine-output.md),
+and the codes a script should branch on in
+[`exit-codes.md`](exit-codes.md).
 
 ## Rebasing onto a new Firefox source release
 
@@ -113,7 +117,7 @@ npx fireforge rebase
 ```
 
 If a patch fails, fix the reject inside `engine/`, then run
-`npx fireforge rebase --continue`. A rebase deliberately leaves the engine
-mutated, so its apply-and-persist pairs are held across a signal rather than
-rolled back — see invariant 4 in
+`npx fireforge rebase --continue`. A rebase leaves the engine mutated on
+purpose, so its apply-and-persist pairs are held across a signal rather than
+rolled back. See invariant 4 in
 [`lifecycle-invariants.md`](lifecycle-invariants.md).

package/docs/run-logs.md

@@ -9,43 +9,87 @@
 ## Why the tool holds the log, not the operator
 
 A run's diagnosis used to exist in exactly one place: the terminal. The
-ergonomic default when output is long — `fireforge test … 2>&1 | tail -40` —
-keeps the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say WHAT
-broke, and it launders the exit code besides. Nothing else held the output:
-`runMachCapture` keeps a 2 MB in-memory tail that dies with the process, and
-the shard retry loop discards earlier attempts outright.
+convenient thing to do when output is long is
+`fireforge test … 2>&1 | tail -40`, which keeps the summary, discards the
+`TEST-UNEXPECTED-FAIL` lines that say what broke, and launders the exit code
+as well. Nothing else held the output: `runMachCapture` keeps a 2 MB
+in-memory tail that dies with the process, and the shard retry loop discards
+earlier attempts outright.
 
-The operator rule ("never pipe a run") was written down three times downstream
-and broken after each writing. That is the tell that it is not an operator
-problem — the tool is the only party that can make the log survive the
-mistake.
+The operator rule ("never pipe a run") was written down three times
+downstream and broken after each writing. That is a sign it is not an
+operator problem. The tool is the only party that can make the log survive
+the mistake.
 
 ## The contract
 
-- **Raw bytes, never the echo filter's collapsed form.** The artifact exists
-  to be re-read by whoever is diagnosing the run; shortening it would
-  reintroduce the loss it prevents.
+- **Complete output, never the echo filter's collapsed form.** The artifact
+  exists so that whoever is diagnosing the run can re-read it. Shortening it
+  would bring back the loss it prevents. The one transformation applied is
+  the secret-masking pass below, which changes values but never line
+  structure.
+- **Secret-shaped values are masked in the file, and only in the file.** The
+  terminal already showed every byte to the operator who ran the command. The
+  file is retained twenty deep and gets attached to bug reports, so it gets a
+  narrow redaction pass (`src/core/run-log-redact.ts`), applied per line
+  before the write. A line split across two chunks is held until its
+  terminator arrives (`\n`, or a lone `\r` from progress-bar repaints), or
+  until it exceeds 1 MiB, or until the log is closed. What gets redacted:
+  - The value of an env-style assignment `KEY=value` whose `KEY` matches
+    `/(TOKEN|SECRET|PASSWORD|PASSWD|API_KEY|AUTH)/i`. The value up to the
+    next whitespace, or a whole quoted string, is written as
+    `KEY=<redacted>`. The `--password=x` and `-DAUTH_TOKEN=x` spellings that
+    mach and configure echo from their argv have the same shape and are
+    masked too.
+  - The credential of an `Authorization:` header. `Bearer`, `Basic` and
+    `Token` keep the scheme word. Any other value is masked whole.
+
+  Nothing else is masked. A bare token in a URL, a space-separated
+  `--password foo` argument, a JSON `"token": "…"` field, or a cookie all
+  pass through unchanged. The pass is a seatbelt against the common
+  accidental leak (mach echoing its environment), not a guarantee that a log
+  is free of secrets. Review a log before sharing it.
+
 - **Opened before any preflight**, so a refusal is logged too. Those are
   exactly the runs whose only output a `tail` throws away.
-- **Retained 20 deep per command kind.** Per-kind, so a busy `test` loop
+- **Retained 20 deep per command kind.** Per kind, so that a busy `test` loop
   cannot evict the `build` log an operator needs to read beside it. Pruning
-  runs before the new file is opened, and orders by the filename's
-  timestamp rather than by stat-ing every entry.
-- **Timestamps are filesystem-safe**: the ISO form with `:` and `.` replaced
-  by `-`, which Windows accepts and which still sorts chronologically.
+  runs before the new file is opened, and orders by the timestamp in the
+  filename rather than by stat-ing every entry.
+- **Timestamps are filesystem-safe.** They use the ISO form with `:` and `.`
+  replaced by `-`, which Windows accepts and which still sorts
+  chronologically.
 - **Best-effort throughout.** A log that cannot be opened, written or pruned
-  degrades to no log. A run must never fail over a diagnostic, so `openRunLog`
-  returns `undefined` on failure, a post-open stream error latches `broken`
-  and drops every later write, and pruning failures are logged verbosely
-  only.
+  degrades to no log, because a run must never fail over a diagnostic.
+  `openRunLog` returns `undefined` on failure, a stream error after opening
+  latches `broken` and drops every later write, and pruning failures are
+  logged verbosely only. The entry point's SIGINT/SIGTERM path closes the
+  active log, also best-effort, before exiting, so the held partial line of a
+  killed run reaches disk.
+
+## Preflight refusals
+
+`fireforge test` opens its run log before any preflight, so a refusal is
+logged too. Those are exactly the runs whose only output a `tail` throws
+away. The refusal's own explanatory text is written into the log, and to
+stdout, before the verdict line seals stdout.
+
+Both halves matter. The verdict seal routes everything the CLI error boundary
+renders afterwards to stderr, so a run captured with `> file` used to keep
+`FIREFORGE-VERDICT: FAIL reason=preflight` and nothing else. That rendering
+also happens after the run log is closed, so the artifact the verdict's own
+`log=` key pointed at held only the pre-test build. Writing before the seal
+fixes both without giving up the contract: the reason lands on both channels,
+and the verdict is still the run's last stdout line.
 
 ## Where the path is announced
 
 `test` publishes it as an additive `log=<path>` key on the
-`FIREFORGE-VERDICT:` line. That is forced, not chosen: the verdict must stay
-the run's LAST stdout write ([`machine-output.md`](machine-output.md)), so a
-separate announcement after it would break the contract, and one before it is
-the first thing a `tail` cuts.
+`FIREFORGE-VERDICT:` line. That is forced rather than chosen: the verdict has
+to stay the run's last stdout write (see
+[`machine-output.md`](machine-output.md)), so a separate announcement after
+it would break the contract, and one before it is the first thing a `tail`
+cuts.
 
 `build` prints no verdict line, so it announces the path directly
 (`Full build output: <path>`).
@@ -54,7 +98,7 @@ the first thing a `tail` cuts.
 
 At the two mach capture funnels in `src/core/mach.ts`, not at the commands.
 That covers every dispatch: the three test dispatchers, `package`, and the
-stdio-inheriting path `mach build` uses — which rides the collectors' existing
+stdio-inheriting path `mach build` uses, which rides the collectors' existing
 `mirror` hook rather than growing a second one. A new dispatcher added at the
-funnels is logged by construction; one added beside them is not, which is the
-reason to keep going through them.
+funnels is logged automatically, and one added beside them is not, which is
+the reason to keep going through them.