@bensandee/tooling 0.75.0 → 0.77.0

package/README.md

@@ -67,6 +67,12 @@ Explicit flags always win, regardless of branch:
 
 If both are passed, `--no-coverage` wins.
 
+Set `.tooling.json#coverage.gateOnPullRequests: true` to turn coverage collection on for every
+branch, including refs that resolve to no branch at all (a detached HEAD, a tag, a
+`refs/pull/N/merge` build) -- `auto` mode then always runs `pnpm run test:coverage`, regardless of
+branch. An explicit `--no-coverage` still wins. This changes collection only: coverage **recording**
+and history stay default-branch-only either way.
+
 Because the decision is branch-aware, the generated CI workflow runs plain `pnpm ci:check` (no coverage flag) and lets `checks:run` decide -- except when coverage is disabled in `.tooling.json`, where it passes `--no-coverage` to force it off everywhere.
 
 **Extend the `check` script with `--add`, never a shell chain.** `repo:sync` generates `check` as a single rooted command (`bst checks:run`) and `ci:check` as `pnpm check --skip 'docker:*'`. When CI runs `pnpm ci:check`, pnpm appends the resolved `--skip 'docker:*'` (and any flags you add, e.g. `--no-coverage`) to the _end_ of the resolved script -- so they reach `bst checks:run` only if that is the last command. Adding extra checks via an `&&` chain silently drops `--skip 'docker:*'` and any forwarded flag:
@@ -258,6 +264,37 @@ Convention and overrides coexist -- a repo can use both.
 
 Works for both `changesets` and `simple` release strategies, on Forgejo (via API upload) and GitHub (via `gh release upload --clobber`). The asset step in the workflow is gated on the release itself having published/pushed, so failed releases never upload stale artifacts.
 
+#### Version stamping
+
+For a repo whose released artifact carries its version somewhere other than `package.json` -- a WordPress theme's `style.css` header, a plugin banner, a template file -- declare where the version goes and let `release:assets` write it in:
+
+```json
+{
+  "versionStamp": [{ "file": "style.css", "prefix": "Version: " }]
+}
+```
+
+| Field    | Description                                                                          |
+| -------- | ------------------------------------------------------------------------------------- |
+| `file`   | Path to the file whose version line gets stamped, relative to the project root (required). |
+| `prefix` | Literal string (never a pattern) the target line must start with (required).          |
+| `suffix` | Literal string (never a pattern) the target line must end with (optional; default: none). |
+
+`prefix` and `suffix` are literal strings, not regexes -- the target line is read straight off `prefix + version + suffix`:
+
+| Target                              | `prefix`                    | `suffix`       |
+| ------------------------------------ | ---------------------------- | -------------- |
+| `Version: 1.2.3` (WordPress theme)  | `"Version: "`                | --             |
+| ` * Version: 1.2.3` (plugin header) | `" * Version: "`             | --             |
+| `Version: v1.2.3`                   | `"Version: v"`               | --             |
+| `__version__ = "1.2.3"`              | `"__version__ = \""`         | `"\""`         |
+| `<version>1.2.3</version>`          | `"<version>"`                | `"</version>"` |
+| `define('FOO_VERSION', '1.2.3');`   | `"define('FOO_VERSION', '"`  | `"');"`        |
+
+`release:assets` stamps every configured file before building assets, then verifies the stamp survived the build. Exactly one line in the file must match `prefix`/`suffix` or the release fails loudly -- zero matches means the config is broken, and more than one is an ambiguous config that needs a more specific `prefix` or a second entry. The stamp is never committed: the tracked copy of the file keeps its placeholder version on purpose, so there is only ever one source of truth (`package.json#version`) and nothing to drift. Run `bst release:assets --dry-run` to rehearse a `versionStamp` config locally, with no forge access and no release -- the rehearsal does still write the stamp, so it leaves the tracked file modified in your working tree. Discard it with `git checkout -- <file>`; committing it is exactly the drift this design exists to prevent.
+
+`repo:sync --check` validates that every `versionStamp[].file` exists and still has exactly one matching line -- it never compares the stamped value to `package.json#version`, since the tracked value is deliberately stale.
+
 ### Coverage tracking
 
 | Command                    | Description                                                                                   |
@@ -321,12 +358,12 @@ Or keep the local ratchet but skip the CI history append:
 { "coverage": { "history": "none" } }
 ```
 
-| Override field       | Default                  | Description                                                             |
-| -------------------- | ------------------------ | ----------------------------------------------------------------------- |
-| `history`            | `"orphan-branch"`        | `"none"` disables CI history; the local ratchet still works             |
-| `historyBranch`      | `"bst/coverage-metrics"` | Override the orphan branch name                                         |
-| `tolerancePp`        | `0.1`                    | Tolerance in percentage points before `coverage:check` flags a drop     |
-| `gateOnPullRequests` | `false`                  | Run coverage on PR builds too (deferred follow-up -- currently a no-op) |
+| Override field       | Default                  | Description                                                                                                                 |
+| -------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
+| `history`            | `"orphan-branch"`        | `"none"` disables CI history; the local ratchet still works                                                                 |
+| `historyBranch`      | `"bst/coverage-metrics"` | Override the orphan branch name                                                                                             |
+| `tolerancePp`        | `0.1`                    | Tolerance in percentage points before `coverage:check` flags a drop                                                         |
+| `gateOnPullRequests` | `false`                  | `true` makes `checks:run`'s `auto` mode collect coverage on every branch, not only the default one; recording is unaffected |
 
 #### Per-package re-sum
 
@@ -464,6 +501,17 @@ Available override fields:
 | `detectPackageTypes` | boolean | `true`                                                                           |
 | `pnpmWorkspace`      | `false` | Set to `false` to opt out of `pnpm-workspace.yaml` management                    |
 
+## Environment file
+
+Set `BST_ENV_FILE` to the path of an env file and every `bst` command loads it before anything else runs -- a way to feed tokens to the tools from one annotated file without exporting them into your shell:
+
+```bash
+# in your shell profile
+export BST_ENV_FILE=/home/you/.secrets.env
+```
+
+The file takes `KEY=value` lines, `#` comments, blank lines, and an optional `export ` prefix. A variable already set in the environment always wins over the file, so a container's `-e` or a shell export is never overridden. Unset, no file is touched; set to a file that cannot be read, the command fails before it starts (under `--json`, as the usual `{ok: false}` document). Name the file so it ends in `.env`: the bst-hook then keeps an agent session from reading or writing it while the tools still load it. This is a development convenience -- a production container should receive every variable through `docker run -e` and leave `BST_ENV_FILE` unset.
+
 ## Debug logging
 
 All CLI commands support a `--verbose` flag for detailed debug output. Alternatively, set `TOOLING_DEBUG=true` as an environment variable -- useful in CI workflows: