@bensandee/tooling 0.104.0 → 0.106.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +87 -26
- package/bin/bst.mjs +12 -3
- package/dist/bin.mjs +1318 -347
- package/package.json +4 -4
- package/tooling.schema.json +50 -9
package/README.md
CHANGED
|
@@ -119,27 +119,36 @@ Custom blocks are anchored to the nearest preceding non-blank line. When `repo:s
|
|
|
119
119
|
|
|
120
120
|
To skip a workflow file entirely, add `# @bensandee/tooling:ignore` as the first line -- `repo:sync` will leave the file untouched.
|
|
121
121
|
|
|
122
|
-
###
|
|
122
|
+
### Runner labels
|
|
123
123
|
|
|
124
|
-
|
|
124
|
+
Every generated job reads the runner from the forge's Actions variables, so the deployment names
|
|
125
|
+
its runners once and `repo:sync` stays offline: the generated YAML holds an expression, and the
|
|
126
|
+
forge fills in the value when it schedules the job.
|
|
125
127
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
128
|
+
- `BST_RUNNER` is the shared pool. Every job falls back to it.
|
|
129
|
+
- `BST_TRUSTED_RUNNER` is the trusted runner. The default-branch-only jobs try it first, so a
|
|
130
|
+
deployment with one pool sets nothing.
|
|
131
|
+
|
|
132
|
+
| Job | File | `runs-on` |
|
|
133
|
+
| ------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
134
|
+
| `check` | `check.yml` (every strategy but `changesets`) / `ci.yml` (`changesets`) | the trusted label on the push run on the default branch; the shared pool on every pull request |
|
|
135
|
+
| `release` | `release.yml` | `${{ vars.BST_TRUSTED_RUNNER \|\| vars.BST_RUNNER \|\| 'ubuntu-latest' }}` |
|
|
136
|
+
| `post-release-hook` | `ci.yml` (`changesets`) / `release.yml` (`simple`) | `${{ vars.BST_TRUSTED_RUNNER \|\| vars.BST_RUNNER \|\| 'ubuntu-latest' }}` |
|
|
129
137
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
| `release` | `release.yml` | Yes -- it only ever runs on the default branch |
|
|
134
|
-
| `post-release-hook` | `ci.yml` (`changesets`) / `release.yml` (`simple`) | Yes -- it only ever runs on the default branch |
|
|
138
|
+
With neither variable set, an unset one is the empty string and every job runs on `ubuntu-latest`
|
|
139
|
+
-- no job waits on an empty label. The YAML is the same on GitHub, where a repository on hosted
|
|
140
|
+
runners simply sets nothing.
|
|
135
141
|
|
|
136
|
-
|
|
142
|
+
Set the variables at the user, org or repo level (`Settings -> Actions -> General -> Variables`);
|
|
143
|
+
a repo-level value overrides the org and user ones. A user-level and a repo-level variable were
|
|
144
|
+
measured reaching `runs-on` on Forgejo 16.0.7; an org-level one was not yet, so set that level
|
|
145
|
+
against a scratch repository first.
|
|
137
146
|
|
|
138
|
-
Three things to know before setting
|
|
147
|
+
Three things to know before setting them:
|
|
139
148
|
|
|
140
|
-
- **Scope the runner.** A job runs on any runner whose label it can name, so the runner must be scoped so no other repository on the forge can name its label. Until it is, setting the
|
|
141
|
-
- **A missing label hangs the job.** A job aimed at a label no runner serves waits forever. Set
|
|
142
|
-
- **
|
|
149
|
+
- **Scope the runner.** A job runs on any runner whose label it can name, so the runner must be scoped so no other repository on the forge can name its label. Until it is, setting the variable moves your secrets onto a machine other repos can claim.
|
|
150
|
+
- **A missing label hangs the job.** A job aimed at a label no runner serves waits forever. Set a variable only once a runner exists and is serving that label.
|
|
151
|
+
- **Writing a variable is an admin action.** Anyone who can write the repository's Actions variables can move every job with `BST_RUNNER`, pull request jobs included -- no workflow edit needed, and a repo-level value beats the org or user one. So the trusted runner must serve only its own label and be scoped to the repositories allowed to reach it; that registration is the guard, not the generated YAML. Read on 2026-11-02, the agent's forge token is a `write` collaborator on every agent-enabled repo, so a run cannot write these variables -- the admin action stays a person's.
|
|
143
152
|
|
|
144
153
|
### pnpm-workspace.yaml
|
|
145
154
|
|
|
@@ -197,6 +206,7 @@ Renovate moves the pinned `node` version, but only within its current major -- a
|
|
|
197
206
|
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
198
207
|
| `tooling release:changesets` | Changesets version/publish for Forgejo CI. A prerelease package moves only its own `<name>@<version>` tag; `<name>@latest`, `<name>@vX` and `<name>@vX.Y` move only for a release (see `release:simple`). Flags: `--dry-run`, `--verbose`. Env: `FORGEJO_SERVER_URL`, `FORGEJO_REPOSITORY`, `RELEASE_TOKEN`. |
|
|
199
208
|
| `tooling release:simple` | Streamlined release using commit-and-tag-version. Flags: `--release-as`, `--first-release`, `--prerelease`, `--verbose`. Env: `RELEASE_TOKEN` (required on every platform). |
|
|
209
|
+
| `tooling release:snapshot` | Cut the rolling prerelease for every package in `.tooling.json#snapshot`, on a push that cut no real release. Flags: `--build` (the run number outside CI), `--dry-run`, `--json`, `--verbose`. Env: `GITHUB_SHA`, `GITHUB_RUN_NUMBER`, `RELEASE_TOKEN`, `GITHUB_OUTPUT`. |
|
|
200
210
|
| `tooling release:trigger` | Trigger a release workflow. |
|
|
201
211
|
| `tooling workflow:dispatch` | Dispatch a `workflow_dispatch` event for any workflow in any repo on the same git host. Flags: `--repo`, `--workflow` (required), `--ref`, `--input key=value` (repeatable). |
|
|
202
212
|
| `tooling changesets:merge` | Merge a changesets version PR. Gated on a live read of the PR; refuses an empty version PR. On Forgejo, a first `mergeable: false` re-reads once after a short delay before refusing, since the forge reports `false` both for a conflict and while still checking. |
|
|
@@ -300,16 +310,29 @@ If the script runs but writes no files to `release-assets/`, `release:assets` fa
|
|
|
300
310
|
}
|
|
301
311
|
```
|
|
302
312
|
|
|
303
|
-
| Field | Description
|
|
304
|
-
| --------- |
|
|
305
|
-
| `file` | Path to the artifact, relative to the project root
|
|
306
|
-
| `
|
|
307
|
-
| `
|
|
313
|
+
| Field | Description |
|
|
314
|
+
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
315
|
+
| `file` | Path to the artifact, relative to the project root. Set exactly one of `file` and `files`. |
|
|
316
|
+
| `files` | Glob patterns relative to the project root, resolved after the build runs; every match uploads under its own basename. Set exactly one of `file` and `files`. |
|
|
317
|
+
| `command` | argv run before upload (optional; omit for pre-built files). Not interpreted by a shell. |
|
|
318
|
+
| `name` | Asset name in the release (optional; a `file` entry only -- a `files` match keeps its basename, since one name cannot serve many files). |
|
|
319
|
+
| `package` | The workspace package this asset belongs to (optional; required in a monorepo once `snapshot` is set). See "Which release a build serves" below. |
|
|
308
320
|
|
|
309
321
|
Convention and overrides coexist -- a repo can use both.
|
|
310
322
|
|
|
311
323
|
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.
|
|
312
324
|
|
|
325
|
+
**Which release a build serves.** A build that takes its version from outside `package.json` -- Gradle, a generated manifest -- needs to know what it is building, and a monorepo build needs to know which package it belongs to. Every build is handed four variables describing the release it serves, merged over its own environment:
|
|
326
|
+
|
|
327
|
+
| Variable | Value |
|
|
328
|
+
| ---------------------- | --------------------------------------- |
|
|
329
|
+
| `RELEASE_VERSION` | The version being released. |
|
|
330
|
+
| `RELEASE_TAG` | The tag that release carries. |
|
|
331
|
+
| `RELEASE_PRERELEASE` | `true` or `false`. |
|
|
332
|
+
| `RELEASE_BUILD_NUMBER` | The CI run number, or empty outside CI. |
|
|
333
|
+
|
|
334
|
+
An entry naming a `package`, and a `build:release-assets` script in a package directory, belong to that package: they run once per release of that package at HEAD, and upload to that release only. An entry with no `package` belongs to the root package in a single-package repo, which is the old behaviour; in a monorepo it belongs to no package, so it builds once and uploads to every release at HEAD, and gets the four variables only when exactly one release is at HEAD.
|
|
335
|
+
|
|
313
336
|
#### Version stamping
|
|
314
337
|
|
|
315
338
|
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:
|
|
@@ -320,11 +343,12 @@ For a repo whose released artifact carries its version somewhere other than `pac
|
|
|
320
343
|
}
|
|
321
344
|
```
|
|
322
345
|
|
|
323
|
-
| Field
|
|
324
|
-
|
|
|
325
|
-
| `file`
|
|
326
|
-
| `prefix`
|
|
327
|
-
| `suffix`
|
|
346
|
+
| Field | Description |
|
|
347
|
+
| --------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
348
|
+
| `file` | Path to the file whose version line gets stamped, relative to the project root (required). |
|
|
349
|
+
| `prefix` | Literal string (never a pattern) the target line must start with (required). |
|
|
350
|
+
| `suffix` | Literal string (never a pattern) the target line must end with (optional; default: none). |
|
|
351
|
+
| `package` | The workspace package whose release this stamp carries (optional; required in a monorepo once `snapshot` is set). |
|
|
328
352
|
|
|
329
353
|
`prefix` and `suffix` are literal strings, not regexes -- the target line is read straight off `prefix + version + suffix`:
|
|
330
354
|
|
|
@@ -337,10 +361,47 @@ For a repo whose released artifact carries its version somewhere other than `pac
|
|
|
337
361
|
| `<version>1.2.3</version>` | `"<version>"` | `"</version>"` |
|
|
338
362
|
| `define('FOO_VERSION', '1.2.3');` | `"define('FOO_VERSION', '"` | `"');"` |
|
|
339
363
|
|
|
340
|
-
`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.
|
|
364
|
+
`release:assets` stamps every configured file before building assets, then verifies the stamp survived the build; `release:snapshot` does the same for the package it cuts, stamping the snapshot version. 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.
|
|
341
365
|
|
|
342
366
|
`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.
|
|
343
367
|
|
|
368
|
+
#### Snapshot channel
|
|
369
|
+
|
|
370
|
+
A repo on the `changesets` strategy can ship a second, rolling kind of release: a prerelease from every push to the default branch, so testers get each change before anyone writes a changeset. Declare it in `.tooling.json`:
|
|
371
|
+
|
|
372
|
+
```json
|
|
373
|
+
{
|
|
374
|
+
"snapshot": { "preid": "alpha", "keep": 3, "packages": ["@acme/app"] }
|
|
375
|
+
}
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
| Field | Description |
|
|
379
|
+
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
380
|
+
| `preid` | The prerelease identifier, `[a-z][a-z0-9]*` (required). `alpha` gives `1.2.6-alpha.42`. |
|
|
381
|
+
| `keep` | How many snapshots to keep per package before the oldest are deleted (optional; default `3`). |
|
|
382
|
+
| `packages` | Which packages to snapshot, by name. Optional in a single-package repo, where it defaults to the root package; **required in a monorepo**. |
|
|
383
|
+
|
|
384
|
+
A monorepo asks you to name the list because most monorepos have packages nobody installs from a snapshot; bst never picks them for you, and `repo:sync` refuses a missing list or a name with no package behind it.
|
|
385
|
+
|
|
386
|
+
When the key is set, the generated `ci.yml` gains a `snapshot` job. It runs after `check`, on the default branch only, and only when `check` cut no real release -- a push whose Version Packages PR merged ships the version, never also a snapshot of it. It runs `bst release:snapshot`, and it triggers no deploy dispatch and no post-release hook: both belong to the stable channel.
|
|
387
|
+
|
|
388
|
+
The job exposes four outputs, in the same form `check` does, so a later job can treat the two channels alike:
|
|
389
|
+
|
|
390
|
+
| Output | Value |
|
|
391
|
+
| ----------- | ----------------------------------------------------------------------------------- |
|
|
392
|
+
| `published` | `true` once every listed package's prerelease exists. |
|
|
393
|
+
| `version` | The first listed package's version. |
|
|
394
|
+
| `tag` | The first listed package's tag. |
|
|
395
|
+
| `packages` | A JSON array of `{ "name": ..., "version": ..., "tag": ... }`, one per package cut. |
|
|
396
|
+
|
|
397
|
+
Each package's version is `<next>-<preid>.<build>`. `<next>` is the version the pending changesets would give that package, including a bump it gets as a dependent, or its current patch raised by one when none is pending -- so every listed package snapshots on every push. `<build>` is the CI run number, `GITHUB_RUN_NUMBER`, which both forges set; outside CI, pass `--build <n>`. The version goes into that package's `package.json` in the working tree only, and the release is created as a prerelease targeting the commit the job checked out. Nothing is committed, no tag is pushed by the command, and no floating tag moves.
|
|
398
|
+
|
|
399
|
+
Old snapshots are pruned per package: releases whose tags match that package's own snapshot pattern, sorted newest first, beyond `keep` are deleted with their tags. A stable release, another package's snapshot, or another `preid` never matches, so a prune cannot reach them.
|
|
400
|
+
|
|
401
|
+
One thing to know about the run number: it restarts at 1 for each workflow file, and a re-run reuses its number. A version built from it is unique per run of that file, not per commit -- if you renumber after renaming or moving the workflow, pick a new `preid` so the new series cannot collide with the old.
|
|
402
|
+
|
|
403
|
+
Run `bst release:snapshot --dry-run` to see the versions and tags with no forge access and no writes. `--json` prints one document, `{ published, packages }`, with the builds captured rather than inherited.
|
|
404
|
+
|
|
344
405
|
### Coverage tracking
|
|
345
406
|
|
|
346
407
|
| Command | Description |
|
package/bin/bst.mjs
CHANGED
|
@@ -12,8 +12,8 @@
|
|
|
12
12
|
*
|
|
13
13
|
* The indirection costs one module load and makes the bin link independent of build state: the
|
|
14
14
|
* link always exists, and `dist/bin.mjs` only has to be there by the time someone runs it. When
|
|
15
|
-
* it is not, the
|
|
16
|
-
*
|
|
15
|
+
* it is not, the shim says so in one line and names the command that builds it, rather than
|
|
16
|
+
* leaving Node's ERR_MODULE_NOT_FOUND stack trace.
|
|
17
17
|
*
|
|
18
18
|
* Consumers installing from the registry get both files (`files` ships `bin` and `dist`) and are
|
|
19
19
|
* unaffected either way, since a published tarball is always built.
|
|
@@ -23,4 +23,13 @@
|
|
|
23
23
|
* wrong trade for a file whose entire purpose is a side effect: the dynamic form says "run this"
|
|
24
24
|
* rather than "bring in these bindings", which is what is actually meant here.
|
|
25
25
|
*/
|
|
26
|
-
|
|
26
|
+
import { existsSync } from "node:fs";
|
|
27
|
+
import { fileURLToPath } from "node:url";
|
|
28
|
+
|
|
29
|
+
const entry = new URL("../dist/bin.mjs", import.meta.url);
|
|
30
|
+
if (existsSync(entry)) {
|
|
31
|
+
await import(entry.href);
|
|
32
|
+
} else {
|
|
33
|
+
process.stderr.write(`bst: ${fileURLToPath(entry)} is missing. Run \`pnpm build\` first.\n`);
|
|
34
|
+
process.exitCode = 1;
|
|
35
|
+
}
|