@burdenoff/toolchain 0.0.0-stage → 2026.1107.1

package/README.md

@@ -1,3 +1,501 @@
-# Temporary Holding Version
+# @burdenoff/toolchain
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The shared build toolchain for every Burdenoff repository: TypeScript 7-clean
+tsconfig bases, ESLint profiles, the bunfig and lefthook managed blocks, a
+knip base, and the `boff` CLI (`sanity`, `gate`, `coverage-gate`, `doctor`,
+`sync`, `deps-mode`, `workflow-policy`).
+
+It exists so that a lint-rule tweak or a sanity fix ships once, through one
+exact-pinned devDependency, instead of through ~700 drifted copies of
+`check-coverage.sh`, `deps-mode.ts`, `build-limits.sh`, Prettier and ESLint
+configs (plan: `infra-specs/engineering/toolchain/00-bun-native-toolchain-migration-plan.md`,
+sections 5, 7 and 9; ticket BOFF-10675).
+
+- Source: `algoshred/toolchain` (private). Package: `@burdenoff/toolchain` on
+  npmjs (public, so PR jobs need no token).
+- Bun: **1.4.4** (`.bun-version`, `packageManager: bun@1.4.4`, `engines.bun: >=1.4.4`).
+- Versioning: CalVer `YYYY.MDD.PATCH`, published by `build-publish.yml` on every
+  push to `main`, tagged `v<version>`.
+
+## Install
+
+Pin the exact version (the fleet installs with `--frozen-lockfile`, so a caret
+range would never move anyway):
+
+```bash
+bun add -d --exact @burdenoff/toolchain@<version>
+```
+
+```json
+{
+  "devDependencies": {
+    "@burdenoff/toolchain": "<version>",
+    "eslint": "^9.39.0",
+    "@types/bun": "^1.4.4"
+  }
+}
+```
+
+The ESLint plugins (`typescript-eslint`, `eslint-plugin-sonarjs`,
+`eslint-plugin-security`, `eslint-plugin-import`, `eslint-plugin-eslint-comments`,
+`eslint-plugin-react`, `eslint-plugin-react-hooks`, `@eslint/js`, `globals`)
+are dependencies of the toolchain. Consumers keep only `eslint` itself (and
+`typescript` where typed linting or `.d.ts` emit runs) and remove their own
+copies of those plugins plus `prettier`, `@trivago/prettier-plugin-sort-imports`,
+`eslint-plugin-prettier` and `eslint-config-prettier`.
+
+Then:
+
+```bash
+bunx boff sync --type <type> --scripts   # bunfig + lefthook blocks, scripts, boff.type
+bunx boff doctor                          # what still needs attention
+bun run sanity
+```
+
+## Consumer contract
+
+### Repo types
+
+`boff` keys its defaults off `package.json` → `boff.type`:
+
+`svc`, `gateway`, `be-sdk`, `mfe`, `fe-libs`, `app`, `website`, `docs`, `cli`,
+`mcp`, `sdk-node`, `browser-ext`, `vscode-ext`, `plugin`, `doctor`, `lib`.
+
+When `boff.type` is absent the type is inferred from fleet naming
+(`wspace-*-svc`, `*-gateway`, `microfe-*`, `*-app`, `*-website`, ...), falling
+back to `lib`. Declare it explicitly.
+
+### tsconfig
+
+Every base is TypeScript 7 clean: no `baseUrl` (a hard error in `bun check`),
+an explicit `types` array (TypeScript 7 defaults it to `[]`), bundler or Node16
+resolution, and no `composite`/`declaration` except `backend-library.json`.
+
+| Base                              | For                        | Notes                                                                                             |
+| --------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------- |
+| `tsconfig/base.json`              | anything                   | strict, ES2022, bundler resolution, `types: []`, `noEmit`                                         |
+| `tsconfig/backend.json`           | svc                        | `types: ["bun"]`, decorators + metadata, `noUncheckedIndexedAccess`, unused locals left to ESLint |
+| `tsconfig/backend-library.json`   | be-sdk                     | backend + `composite`, `declaration`, `declarationMap` for `.d.ts` emit                           |
+| `tsconfig/gateway.json`           | gateways                   | `types: ["bun"]`, unused locals/parameters as errors                                              |
+| `tsconfig/react-lib.json`         | fe-libs, MFEs              | DOM libs, `jsx: react-jsx`, `customConditions: ["types"]`, `types: ["vite/client"]`               |
+| `tsconfig/react-app.json`         | app shells, websites       | react-lib + `noUncheckedSideEffectImports`, `useDefineForClassFields`                             |
+| `tsconfig/node-lib.json`          | cli, mcp, sdk-node, plugin | `types: ["bun"]`, isolated modules                                                                |
+| `tsconfig/browser-extension.json` | browser extensions         | DOM libs, `types: ["chrome"]`, emits for ts-loader                                                |
+| `tsconfig/vscode-extension.json`  | code extensions            | CommonJS through `Node16`, `types: ["node", "vscode"]`, emits for mocha                           |
+
+`baseUrl` is forbidden (`boff doctor` fails on it). Write `paths` values
+relative to the tsconfig with a leading `./`. `types` in your tsconfig
+**replaces** the base's array; repeat the base entries you still need (for
+example `["vite/client", "bun"]` in an MFE whose tests run on `bun test`).
+`extends` resolves relative paths (`include`, `outDir`, `paths`) against the
+file that declares them, so keep those in your own tsconfig.
+
+```jsonc
+// svc
+{
+  "extends": "@burdenoff/toolchain/tsconfig/backend.json",
+  "compilerOptions": {
+    // Repeat these two: Bun's transpiler reads decorator options from the nearest
+    // tsconfig only, not through `extends` (oven-sh/bun#6326).
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "paths": { "#/*": ["./src/*"], "#generated/*": ["./src/generated/*"] },
+  },
+  "include": ["src"],
+  "exclude": ["**/*.test.ts"],
+}
+```
+
+```jsonc
+// mfe (bun check -b follows the reference into tsconfig.node.json)
+{
+  "extends": "@burdenoff/toolchain/tsconfig/react-lib.json",
+  "compilerOptions": { "types": ["vite/client", "bun"], "paths": { "#src/*": ["./src/*"] } },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }],
+}
+```
+
+```jsonc
+// app shell / website
+{ "extends": "@burdenoff/toolchain/tsconfig/react-app.json", "include": ["src"] }
+// gateway
+{ "extends": "@burdenoff/toolchain/tsconfig/gateway.json", "include": ["src"] }
+// cli / mcp / sdk-node / plugin
+{ "extends": "@burdenoff/toolchain/tsconfig/node-lib.json", "include": ["src"] }
+// browser extension
+{
+  "extends": "@burdenoff/toolchain/tsconfig/browser-extension.json",
+  "compilerOptions": { "outDir": "dist", "types": ["chrome", "bun"], "paths": { "@/*": ["./src/*"] } },
+  "include": ["src"]
+}
+// code extension
+{
+  "extends": "@burdenoff/toolchain/tsconfig/vscode-extension.json",
+  "compilerOptions": { "outDir": "out", "rootDir": "src" },
+  "include": ["src"]
+}
+```
+
+### ESLint (`eslint.config.js`)
+
+```js
+// svc (be-sdk's factory, same rules and per-path overrides)
+import backend from '@burdenoff/toolchain/eslint/backend';
+export default backend(import.meta.dirname, { project: './tsconfig.json', ignores: ['scripts/**'] });
+
+// gateway (typescript-eslint strictTypeChecked + stylisticTypeChecked, projectService)
+import gateway from '@burdenoff/toolchain/eslint/gateway';
+export default gateway(import.meta.dirname);
+
+// mfe / fe-libs / app / website (raw-colour guard, Dialog restriction, react-hooks v7)
+import { createEslintConfig } from '@burdenoff/toolchain/eslint/react';
+export default createEslintConfig({ ignores: ['src/generated/**'], rawColors: 'error' });
+
+// cli / mcp / sdk-node / plugin / code extension (no Prettier plugin)
+import node from '@burdenoff/toolchain/eslint/node';
+export default node({ ignores: ['out/**'] });
+
+// browser extension (node + browser and webextension globals, chrome)
+import browser from '@burdenoff/toolchain/eslint/browser';
+export default browser();
+```
+
+`@burdenoff/toolchain/eslint/react` also exports `rawColorRestrictedSyntax`,
+`RAW_COLOR_PATTERN` and `PALETTE_CLASS_PATTERN` for repos with a standalone
+config. Typings ship in `eslint/*.d.ts` (`eslint/index.d.ts` holds the shared
+option types).
+
+### bunfig.toml managed block
+
+`boff sync` writes these keys between the marker lines
+`# >>> boff managed (do not edit)` and `# <<< boff managed`:
+
+```toml
+[install]
+minimumReleaseAge = "3d"
+minimumReleaseAgeExcludes = [ ...every @burdenoff, @fluidgrids and @vibecontrols package... ]
+
+[test]
+coverageReporter = ["text", "lcov"]
+```
+
+TOML forbids defining a table twice, so when the repo already has `[install]`
+or `[test]`, the managed keys go **inside** that table between the markers;
+otherwise the table is created (before any `[install.*]` sub-table). Everything
+outside the markers (`[install.scopes]`, `[test] preload`, ...) is the repo's
+and is never touched; an unmarked copy of a managed key is replaced (it would
+be a duplicate key). The result is validated with `Bun.TOML.parse`, and the
+test suite runs `bun install --frozen-lockfile --dry-run` against a synced file.
+
+`minimumReleaseAge = "3d"` is a duration string, which **Bun 1.4+ only**
+understands: Bun 1.3.x rejects the whole file ("Invalid Bunfig"). Run `boff
+sync` in the same commit that sets `.bun-version` to 1.4.4 (`boff sync` prints
+a note when the pin is older or missing).
+
+`minimumReleaseAge` has no scope wildcard, so the excludes list names every
+package the fleet publishes; it ships as `bunfig/release-age-excludes.json`
+(regenerated from the registry with `bun run gen:excludes`). `boff sync
+--refresh-excludes` merges the live list from the registry (`NPM_TOKEN` adds
+private packages). A sync never removes entries already present.
+
+CI must use the committed `bunfig.toml`: no `cat > bunfig.toml` heredocs and no
+`--mount=type=secret,...,target=/app/bunfig.toml` in Dockerfiles. `boff doctor
+--ci` fails on both and on a `bunfig.toml` that differs from `HEAD` after
+install.
+
+### lefthook
+
+`boff sync` manages the `pre-push` block of `lefthook.yml` (when the repo uses
+lefthook):
+
+```yaml
+# >>> boff managed (do not edit)
+pre-push:
+  commands:
+    sanity:
+      run: ./node_modules/.bin/boff sanity --pre-push
+# <<< boff managed
+```
+
+`lefthook/base.yml` holds the whole recommended set (pre-commit deps-guard,
+pre-push sanity, post-commit deps-restore) for `extends:`.
+
+### knip
+
+```ts
+// knip.config.ts
+import { knipConfig } from '@burdenoff/toolchain/knip/base';
+export default knipConfig({ entry: ['src/index.ts'], project: ['src/**/*.ts'] });
+```
+
+### package.json
+
+```jsonc
+{
+  "packageManager": "bun@1.4.4",
+  "engines": { "bun": ">=1.4.4" },
+  "boff": {
+    "type": "svc", // repo type (see above)
+    "sanity": {
+      "steps": ["format", "lint", "typecheck"], // optional: replaces the type's default step list
+      "extra": ["check:migration"], // optional: package.json scripts run as extra steps
+      "formatPaths": ["src", "tests"], // optional: limit bun fmt (default: whole repo)
+      "codegenCommitted": [".hive-schema.graphql"], // optional: files codegen must leave unchanged
+    },
+    "coverage": {
+      "global": 70, // aggregate lines + functions floor (%)
+      "diff": 80, // changed-lines floor (%)
+      "exclude": ["src/legacy/**"], // extra lcov excludes
+    },
+    "scripts": { "unmanaged": ["test"] }, // keys boff sync --scripts must leave alone
+    "depsMode": {
+      // optional, for boff deps-mode
+      "paths": { "@burdenoff/be-sdk": "../../../burdenoff-be-sdk-node" },
+      "stateFile": ".vibe-env.json",
+    },
+  },
+}
+```
+
+Unknown keys under `boff` are rejected, so a typo never passes silently.
+
+`boff sync --scripts` writes these scripts (per type):
+
+| Script                    | Value                                                                                                                            |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `type:check`              | `boff gate -- bun check --no-pretty` (`-b` for mfe, fe-libs, website; `-p tsconfig.typecheck.json` for app shells that have one) |
+| `format` / `format:check` | `bun fmt` / `bun fmt --check` (plus `formatPaths`)                                                                               |
+| `lint`                    | `eslint .`                                                                                                                       |
+| `test`                    | `bun test` (not for vscode-ext and docs)                                                                                         |
+| `sanity` / `sanity:force` | `boff sanity` / `boff sanity --force`                                                                                            |
+| `audit`                   | `bun audit --audit-level=high`                                                                                                   |
+
+docs repos get only `sanity`, `sanity:force` and `audit`.
+
+## CLI
+
+```
+boff <command> [options]
+```
+
+### `boff sanity`
+
+The hash-stamped sanity runner (plan section 9).
+
+```
+boff sanity [--force] [--only step,...] [--print-keys] [--pre-push]
+```
+
+- Steps, in order: `format`, `codegen`, `gendb`, `migrate`, `lint`,
+  `typecheck`, `build`, `test`, `knip`, `audit`, then `boff.sanity.extra`
+  scripts. Default lists per type:
+
+  | Type                                                                                        | Steps                                                               |
+  | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+  | svc                                                                                         | format, codegen, gendb, migrate, lint, typecheck, build, test, knip |
+  | mfe, app                                                                                    | format, codegen, lint, typecheck, build, test                       |
+  | gateway, be-sdk, fe-libs, website, cli, mcp, sdk-node, browser-ext, vscode-ext, plugin, lib | format, lint, typecheck, build, test                                |
+  | doctor                                                                                      | format, lint, typecheck, test                                       |
+  | docs                                                                                        | build                                                               |
+
+  A step that does not apply (no `codegen` script, no eslint config, no test
+  files, no `DATABASE_URL` for `migrate`, ...) is skipped with the reason
+  printed. With an explicit `boff.sanity.steps` list a step that cannot run is
+  a configuration error (exit 2), except `migrate` without a database.
+
+- Commands: `bun fmt --check`; `bun run codegen` plus `git diff --exit-code`
+  on committed outputs (`.hive-schema.graphql` for svc); `bun run gendb`;
+  `bun run migrate:deploy`; `bun run lint --cache` (or `eslint . --cache`);
+  `bun run type:check` (or `bun check --no-pretty [-b]`); `bun run build:bundle`
+  (svc) / `bun run build`; `bun test --coverage --reporter=junit` followed by
+  `boff coverage-gate` (svc, gateway, be-sdk, or any repo with
+  `boff.coverage.global`), or `bun run test` when the test script is not
+  `bun test`; `knip --cache`; `bun audit --audit-level=high`. A script named
+  `sanity:<step>` overrides any built-in command.
+- Keys: sha256 over a base (package.json, bun.lock, bunfig.toml,
+  .bun-version, toolchain version, Bun version, `CI` flag, repo type), the
+  step's commands, the contents of its input files (from
+  `git ls-files -co --exclude-standard`, so untracked-but-not-ignored files
+  count) and the keys of the steps it depends on (lint/typecheck/test fold in
+  codegen and gendb; build folds in typecheck). `migrate` also folds in a hash
+  of `host:port/db` of the local `DATABASE_URL` (never the URL) and expires
+  after 24 hours.
+- Stamps: an empty file `node_modules/.cache/sanity/<step>.<key>`, written
+  only when the step exits 0; `timings.jsonl` beside them records
+  `{step,key,ms,rc,ts}` for every executed step. Output is teed to
+  `sanity.log`. Each step is spawned directly and its own exit code is used;
+  the runner exits with the first failing step's code. SIGINT/SIGTERM kill the
+  running step, remove partial state and exit 130/143.
+- Gate: keys are computed **before** a build slot is taken. A full cache hit
+  exits immediately; otherwise one slot is held for all missed steps and
+  `BOFF_BUILD_SLOT_HELD=1` is exported so nested `boff gate`,
+  `with-buildslot.sh` and `build-limits.sh --gate` calls do not re-gate.
+  Generators (`codegen`, `gendb`) re-run whenever a step that reads their
+  gitignored output runs.
+- `--force` / `SANITY_FORCE=1` ignore stamps (use on `main` and releases).
+  `--only a,b` runs a subset. `--pre-push` (and `BOFF_GATE_STRICT=1`) fail
+  with exit 75 instead of running ungated when no slot frees in time.
+- `--print-keys` (alias: `boff print-keys`) prints `step=key` lines and
+  `all=<key>` without running anything.
+
+### `boff gate -- <command>`
+
+```
+boff gate [--pre-push] -- <command> [args...]
+```
+
+The machine-wide build semaphore with thread caps (plan section 5 item 7).
+
+| Variable               | Default                | Meaning                                                              |
+| ---------------------- | ---------------------- | -------------------------------------------------------------------- |
+| `BOFF_BUILD_SLOTS`     | `clamp(cores/8, 1, 4)` | concurrent heavy commands per machine                                |
+| `BOFF_BUILD_THREADS`   | `clamp(cores/4, 2, 8)` | thread cap exported to children                                      |
+| `BOFF_BUILD_WAIT`      | `900`                  | seconds to wait for a slot                                           |
+| `BOFF_GATE_STRICT`     | unset                  | `1`: fail (exit 75) on timeout instead of running ungated            |
+| `BOFF_BUILD_SLOT_HELD` | unset                  | `1`: an ancestor holds a slot; run directly (set by the gate itself) |
+| `BUILDSLOT_HELD`       | unset                  | legacy re-entrancy flag from `with-buildslot.sh`, honoured too       |
+| `BOFF_BUILD_SLOT_DIR`  | see below              | override the lock root                                               |
+| `BOFF_GATE_IN_CI`      | unset                  | `1`: take slots even when `CI=true`                                  |
+
+- Lock root: `/run/user/$UID/boff-build-slots`, falling back to
+  `$HOME/.cache/boff/build-slots`. Never `/tmp` and never derived from
+  `TMPDIR`, so every session, container build and agent on the machine shares
+  one pool. Locks are `flock(2)` (released by the kernel when the holder dies).
+- The command runs under `nice -n 10` and `ionice -c3` when available.
+- Exported to the command: `BOFF_BUILD_THREADS`, `RAYON_NUM_THREADS`,
+  `ROLLDOWN_WORKER_THREADS`, `ROLLDOWN_MAX_BLOCKING_THREADS`, and the held flags.
+- Injected flags when absent: `--threads=N` into `bun check` and `bun fmt`,
+  `--parallel=N` into `bun test --parallel`, `--maxWorkers=N` into vitest.
+- `CI=true`: the runner is a dedicated machine, so no slot is taken; thread
+  caps still apply. Inside a Docker build without `/run/user`, the
+  `$HOME/.cache` fallback is used.
+
+### `boff coverage-gate`
+
+```
+boff coverage-gate [--lcov coverage/lcov.info] [--global N] [--diff N]
+                   [--compare-branch REF] [--no-diff] [--run-tests]
+```
+
+Replaces every `scripts/check-coverage.sh` (no python, no diff-cover).
+
+- Reads `coverage/lcov.info`; drops generated code, tests and node_modules
+  (`**/generated/**`, `**/*.generated.ts`, `**/__tests__/**`, `**/*.test.*`,
+  `**/*.spec.*`, `src/test/**`, `test/**`, `tests/**`) plus
+  `boff.coverage.exclude`.
+- Aggregate: summed lines and functions must each reach the global threshold
+  (`--global`, else `GLOBAL_THRESHOLD`, else `boff.coverage.global`, else 80).
+- Diff: lines added since the merge base with `COMPARE_BRANCH` (default
+  `origin/main`, `git diff -U0`) that lcov instruments must reach the diff
+  threshold (`--diff`, `DIFF_THRESHOLD`, `boff.coverage.diff`, else 80).
+  When the base ref is missing the diff check is skipped locally and **fails
+  in CI** (use `fetch-depth: 0`).
+- Prints a table plus the uncovered changed lines, exits 1 on failure.
+  `--run-tests` runs `bun [--env-file=.env.local] test --coverage` first, as a
+  drop-in for the old script.
+
+Never lower an existing threshold when migrating; copy the repo's current
+`GLOBAL_THRESHOLD`/`DIFF_THRESHOLD` defaults into `boff.coverage`.
+
+### `boff doctor [--ci]`
+
+Checks: `.bun-version` is 1.4.4; `packageManager` and `engines.bun`; no
+`baseUrl` in any tsconfig; managed blocks present and unmodified (`sync
+--check`, including scripts when `boff.type` is set); no `cat > bunfig.toml`
+in workflows or composite actions and no bunfig secret mount in Dockerfiles;
+no literal `bun-version:` and no `oven/bun:<other>` base; `oven-sh/setup-bun`
+pinned by full SHA; a `pull_request` workflow with a job named exactly
+`PR Gate`; `bunfig.toml` unchanged versus `HEAD`. Without `--ci` failures are
+warnings (exit 0); with `--ci` any failure exits 1.
+
+### `boff sync`
+
+```
+boff sync [--check] [--type <type>] [--scripts] [--refresh-excludes]
+```
+
+Writes the bunfig and lefthook managed blocks; `--scripts` also writes the
+per-type scripts; `--type` records `boff.type`. Idempotent. `--check` writes
+nothing and exits 1 on drift.
+
+### `boff deps-mode`
+
+```
+boff deps-mode <status|remote|local|check> [--silent] [--skip-install]
+boff deps-mode guard <pre-commit|post-commit>
+```
+
+Replaces the `scripts/deps-mode.ts` and `scripts/deps-guard.sh` copies.
+`remote` (alias `npm`) restores `@burdenoff/*` values from `git HEAD` (falling
+back to the installed or published version); `local` (alias `workspace`)
+rewrites them to `workspace:*` for an MFE inside a Bun workspace root,
+`file:` paths for app shells, and relative paths for svc/gateway/sdk repos
+(found from `boff.depsMode.paths`, `deps-local-paths.json`, or the fleet's
+directory conventions). `check` fails on any local reference in package.json
+or bun.lock (CI gate). The `guard` hooks keep commits registry-only and
+restore local mode afterwards (python-free).
+
+### `boff workflow-policy [root]`
+
+The TypeScript port of `check-workflow-policy.sh`: `pinned-uses`,
+`floating-latest`, `remote-script`, `exact-exec`, `frozen-install`,
+`unsafe-interpolation`, `hashed-pip`. Prints GitHub error annotations; exit 0
+clean, 1 violations, 2 usage error.
+
+### `boff version`
+
+Prints the toolchain version (`boff --version`).
+
+## CI usage
+
+Restore the sanity stamps with keys from `print-keys`, then run sanity:
+
+```yaml
+- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+  with:
+    bun-version-file: .bun-version
+- run: bun install --frozen-lockfile
+- run: bunx boff doctor --ci
+- id: keys
+  run: bunx boff print-keys >> "$GITHUB_OUTPUT"
+- uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+  with:
+    path: |
+      node_modules/.cache/sanity
+      node_modules/.cache/eslint
+      node_modules/.cache/tsc
+    key: sanity-${{ runner.os }}-${{ steps.keys.outputs.all }}
+    restore-keys: sanity-${{ runner.os }}-
+- run: bunx boff sanity
+```
+
+On `main` and release runs use `boff sanity --force`. Keep the required
+`PR Gate` job in the caller workflow (`if: always()`, failing unless every
+needed job succeeded).
+
+## Developing the toolchain
+
+```bash
+bun install --frozen-lockfile
+bun check --no-pretty
+bun fmt --check
+bun run lint
+bun run test:coverage     # unit tests + boff coverage-gate on itself (>= 80%)
+bun run selftest          # every fixture through boff sanity
+bun run build             # dist/cli.js (+ dist/knip/base.js)
+```
+
+`fixtures/<type>` holds one minimal repo per type (svc, gateway, be-sdk, mfe,
+app, website, cli, mcp, sdk-node, browser-ext, vscode-ext, plugin, lib). The
+selftest copies each into `.selftest/`, links this checkout as
+`node_modules/@burdenoff/toolchain`, runs `boff sync`, `boff doctor --ci` and
+`boff sanity` cold and warm, introduces a type error (must fail and leave no
+stamp) and a formatting-only change (must invalidate only the format key).
+
+**Rule: a toolchain change must keep every fixture green.** If a change needs
+consumer-side edits, change the fixture in the same commit so the selftest
+shows exactly what consumers must do. The PR workflow runs static checks,
+unit tests with the coverage gate, the build smoke test and the selftest, and
+`PR Gate` fails unless all of them pass. A published version that breaks a
+consumer is rolled back by re-pinning the previous version (never unpublish).

package/bunfig/fragment.toml.tmpl

@@ -0,0 +1,23 @@
+# Template for the block `boff sync` manages inside a consumer's bunfig.toml.
+#
+# Each [table] below lists the keys boff owns in that table. In the consumer
+# file they are written between the marker lines
+#   # >>> boff managed (do not edit)
+#   # <<< boff managed
+# inside the existing table when the repo already has one (TOML forbids a
+# second [install] or [test] table), or as a new table otherwise. Everything
+# outside the markers ([install.scopes], [test] preload, ...) belongs to the
+# repo and is never touched.
+#
+# {{RELEASE_AGE_EXCLUDES}} expands to bunfig/release-age-excludes.json (every
+# package the fleet publishes), merged with any entries already present.
+#
+# trustedDependencies is deliberately not managed: lifecycle scripts stay
+# blocked unless a repo lists the package in its own package.json.
+
+[install]
+minimumReleaseAge = "3d"
+minimumReleaseAgeExcludes = {{RELEASE_AGE_EXCLUDES}}
+
+[test]
+coverageReporter = ["text", "lcov"]