@hominis/fireforge 0.55.0 → 0.60.0

package/docs/README.md

@@ -2,34 +2,29 @@
 
 # FireForge documentation
 
-[`../README.md`](../README.md) is the getting-started page. These files are
-the reference material behind it. `fireforge --help` (and
-`fireforge <command> --help`) is always the authority on flags. These docs
-cover the things a flag list cannot say.
+Start with [getting-started.md](getting-started.md). `fireforge <command> --help` lists every option; these pages cover what an option list cannot say.
 
 ## Using FireForge
 
-| File                                           | Covers                                                                               |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------ |
-| [patch-workflow.md](patch-workflow.md)         | Export, re-export, deletions, queue maintenance, per-patch lint, CI gating, rebasing |
-| [testing.md](testing.md)                       | `fireforge test`: scope, modes, build freshness, the verdict line, verbosity         |
-| [furnace.md](furnace.md)                       | Components: overrides, shared CSS fragments, typed cross-module imports              |
-| [verification-trees.md](verification-trees.md) | CoW snapshots for concurrent read-mostly verification                                |
-| [configuration.md](configuration.md)           | `fireforge.json` settings, design tokens, lock waits, environment variables          |
-
-## Contracts for scripts and CI
-
-| File                                   | Covers                                                                      |
-| -------------------------------------- | --------------------------------------------------------------------------- |
-| [exit-codes.md](exit-codes.md)         | Every exit code, which error class produces it, and how CI should branch    |
-| [machine-output.md](machine-output.md) | The `--json` / `--raw` / verdict-line output contract and its versioning    |
-| [run-logs.md](run-logs.md)             | `.fireforge/logs/`: what `test` and `build` write, and what survives a pipe |
-
-## Internals
-
-| File                                               | Covers                                                                       |
-| -------------------------------------------------- | ---------------------------------------------------------------------------- |
-| [lifecycle-invariants.md](lifecycle-invariants.md) | Locking, rollback, signal handling, and the decision table for new mutations |
-
-Release history and the reasoning behind individual changes live in
-[`../CHANGELOG.md`](../CHANGELOG.md).
+| Page                                     | Covers                                                                                       |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------- |
+| [getting-started.md](getting-started.md) | From an empty directory to a running fork in either mode, and the daily loop                 |
+| [patch-workflow.md](patch-workflow.md)   | Patch mode: the queue and manifest, import, export, re-export, queue operations, rebase      |
+| [source-workflow.md](source-workflow.md) | Source mode: `src/`, overrides, materialization, exporting a queue, the merge driver, rebase |
+| [workspaces.md](workspaces.md)           | Parallel sessions: git worktrees, the workspace pool, locks, host state and disk use         |
+| [quality.md](quality.md)                 | Lint rules and waivers, policy, typecheck, and `check`                                       |
+| [gate.md](gate.md)                       | `gate`: lanes, controls, smoke starts, acceptances, the verified ref and a pre-push hook     |
+| [testing.md](testing.md)                 | `test`: what runs, dispatch, build freshness, the verdict, host hygiene, negative controls   |
+| [furnace.md](furnace.md)                 | Components: create, override, deploy, validate, shared CSS fragments, typing files           |
+| [authoring.md](authoring.md)             | Design tokens, build-manifest registration, chrome script wiring                             |
+| [configuration.md](configuration.md)     | Every key of `fireforge.json`, `furnace.json` and `host.json`, and the environment variables |
+| [migrating.md](migrating.md)             | Upgrading a project from 0.56: removed commands, flags and keys, step by step                |
+
+## For scripts and CI
+
+| Page                                   | Covers                                                   |
+| -------------------------------------- | -------------------------------------------------------- |
+| [exit-codes.md](exit-codes.md)         | Every exit code, and what the judging commands exit with |
+| [machine-output.md](machine-output.md) | The `--json` document and the `FIREFORGE-VERDICT:` line  |
+
+Release history is in [`../CHANGELOG.md`](../CHANGELOG.md). Contributors read [`../contributing/architecture.md`](../contributing/architecture.md).

package/docs/authoring.md

@@ -0,0 +1,97 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# Authoring helpers: tokens, registration, wiring
+
+Three helpers edit Firefox's own files the way Firefox's conventions expect, so you do not hand-edit build manifests and chrome scripts. Each plans every edit before writing any, and `--dry-run` shows the plan.
+
+They write where the project keeps engine files: `engine/` in patch mode, `src/` in source mode. In source mode an upstream file needs an override record before it is edited ([source-workflow.md](source-workflow.md#declaring-an-upstream-file-override)). `register` and `wire`, whose edits are registrations by definition, declare that override themselves (classified `registration`) on their first edit of an upstream file. `token add` refuses an upstream file without one and names the `override` command.
+
+## Design tokens: `token`
+
+A design token is a CSS custom property the project declares in one token file and uses everywhere else. The token commands read two keys of `furnace.json`:
+
+- `tokenFile`: the engine path of the token file. Default `browser/themes/shared/<binaryName>-tokens.css`.
+- `tokenPrefix`: the prefix every project token starts with. Default `--<binaryName>-`.
+
+The token file's base `:root` block is divided into categories by banner comments, one line (`/* = Spacing = */`) or a boxed block whose first text line is the name. Themed blocks (the dark `@media (prefers-color-scheme: dark)` mirror, `:root[<variant>]` blocks) override values.
+
+```sh
+npx fireforge token list
+npx fireforge token show -- --mybrowser-gap
+npx fireforge token add --category Spacing --mode static -- --mybrowser-gap 8px
+npx fireforge token add --category Colors --mode override --dark-value '#1c1b22' -- --mybrowser-surface '#ffffff'
+npx fireforge token add --variant '[data-skin=compact]' -- --mybrowser-gap 4px
+```
+
+Token names start with `--`, which the option parser would read as a flag, so put `--` before the name. A bare name (`gap`) takes the project prefix.
+
+`token add <name> <value>`:
+
+- `--category <name>`: the banner to add the token under. `--create-category` declares the banner when the file has none by that name.
+- `--mode auto|static|override`: dark-mode behaviour. `auto` follows the platform, `static` never changes, `override` has its own dark value (`--dark-value`), written into the dark-mode and theme-attribute blocks.
+- `--description <text>`: a comment written above the declaration.
+- `--variant <selector>`: add the declaration to the `:root<selector>` block instead.
+
+`token list [--category <name>]` lists categories and tokens. `token show <name>` shows every value a token takes and where each is declared.
+
+### Checking token use
+
+```sh
+npx fireforge token lint
+npx fireforge token coverage --min 80
+```
+
+`token lint` runs two checks:
+
+- `token-lockstep`: a themed block declares only tokens the base `:root` declares; otherwise every other theme resolves the token to nothing.
+- `token-undeclared`: a `var(--<prefix>...)` in the token file or an owned stylesheet names a token nothing declares. Declarations in the same sheet or in a sibling sheet, a reference with a fallback, and the names in `tokenAllowlist` and `runtimeVariables` do not count.
+
+Sibling sheets are stylesheets that load together: linked from one document (`<link rel="stylesheet">`, `<?xml-stylesheet?>`), or one `@import`ing the other. `tokenSiblingSheets` adds pairings no link shows.
+
+`token coverage` measures how many values in the owned stylesheets come from a project token, against raw colours and custom properties nobody the project knows declares. `--min <percent>` fails below that share. Both run as steps of `fireforge check` (`token-lint`, `token-coverage`, with `check.minTokenCoverage`).
+
+Inside owned changes, the lint rules `raw-color-value`, `token-prefix-violation` and `token-scale` enforce token use line by line ([quality.md](quality.md#rules)).
+
+## Build-manifest registration: `register`
+
+A file Firefox should package or run must be listed in a build manifest. `register` works out which one from the path and adds the entry:
+
+```sh
+npx fireforge register browser/base/content/mybrowser/panel.js
+npx fireforge register browser/modules/Sidebar.sys.mjs
+npx fireforge register browser/base/content/test/sidebar/browser_focus.js
+npx fireforge register browser/base/content/test/sidebar/browser.toml --create-manifest
+```
+
+| The file is                          | It is registered in                       |
+| ------------------------------------ | ----------------------------------------- |
+| chrome content, skin or widget files | the `jar.mn` that packages that directory |
+| a JavaScript module                  | the `moz.build` of its directory          |
+| a test manifest                      | the `moz.build` above it                  |
+| a test file                          | the test manifest of its directory        |
+
+A file that is already registered is left alone.
+
+- `--after <entry>` places the entry after an existing one (`jar.mn` and test manifests).
+- `--create-manifest` creates a missing `moz.build` or test manifest and wires it into its parents.
+- `--dry-run` shows the planned edit.
+
+Lint's `dangling-registration` and `unregistered-system-module` rules catch registrations that name missing files and modules nothing installs.
+
+## Chrome script wiring: `wire`
+
+`wire <name>` wires a chrome subscript into the browser window:
+
+```sh
+npx fireforge wire mybrowser-sidebar --init MyBrowserSidebar.init --destroy MyBrowserSidebar.uninit --dom browser/base/content/mybrowser-sidebar.inc.xhtml
+```
+
+It makes these edits, all planned before any is written:
+
+- loads `<name>.js` from `browser-main.js`;
+- with `--init <expression>`, calls it from `onLoad` in `browser-init.js`, after the init block of `--after <name>` when given;
+- with `--destroy <expression>`, calls it from `onUnload`;
+- with `--dom <path>`, `#include`s that DOM fragment (`.inc.xhtml`) into the top-level chrome document;
+- registers the script in `browser/base/jar.mn`.
+
+The scripts live in `wire.subscriptDir` (default `browser/base/content`) and fragments are included into `wire.domTarget` (default `browser/base/content/browser.xhtml`). Every edit parses the file it changes, so a file that does not parse is refused rather than patched by guesswork. Lines FireForge writes into upstream files carry the `markerComment` comment.