@bensandee/tooling 0.76.0 → 0.78.0

package/README.md

@@ -137,6 +137,26 @@ All other keys -- `allowBuilds`, custom entries -- are preserved verbatim throug
 
 Opt out entirely with `"pnpmWorkspace": false` in `.tooling.json`; the generator then never inspects or writes the file.
 
+### mise.toml
+
+`repo:sync` manages `mise.toml` with the same narrow contract: it owns `tools.node` and `tools.pnpm` by key and carries every other key, table, and comment through untouched, editing the file textually rather than reserializing it.
+
+**On a fresh file**, it writes the spec's two-key form: `[tools]`, `node` seeded from the `engines.node` floor, `pnpm` copied from `packageManager` with the `pnpm@` prefix stripped.
+
+**On an existing file**, `tools.node` is written only when the key is absent -- once present, it is Renovate's `mise` manager that moves it, in-major only (see the Renovate rule below). `tools.pnpm` is rewritten whenever it differs from `packageManager`; that difference is exactly the drift `repo:sync --check` reports.
+
+**Refused, not silently repaired:**
+
+- `tools.node` or `tools.pnpm` written as a table (e.g. `node = { version = "..." }`) -- `repo:sync` owns these two keys as plain string pins only.
+- `tools.node` pinned below `engines.node`'s floor.
+- A file that fails to parse as TOML.
+
+Any other key -- `java`, `[env]`, `[tasks.*]`, an `http:*` archive-tool table -- is left exactly as found.
+
+`tooling:check` (part of `pnpm check`) additionally asserts the declared toolchain is actually installed and active: it warns (does not fail) when `mise` is not on `PATH`, and fails when a declared tool is not installed, or when the live `node`/`pnpm` on `PATH` (or `JAVA_HOME`, when `java` is declared) disagrees with the pin -- the fix in every failing case is to activate mise (`eval "$(mise activate bash)"` or `mise exec`) before running checks.
+
+Renovate moves the pinned `node` version, but only within its current major -- a `packageRules` entry in the shared `default.json` preset disables major-version updates for `matchManagers: ["mise"], matchPackageNames: ["node"]`, since an exact pin with no upper bound in `engines.node` would otherwise be offered every new major.
+
 ### packageManager force-bump
 
 `repo:sync` rewrites `package.json#packageManager` when an existing value is `pnpm@<N>.x` with `N < 11`, setting it to the tooling's pinned pnpm version (currently `11.1.1`). This is delivered through `repo:sync` rather than Renovate because the mandated `pnpm-workspace.yaml` keys (`blockExoticSubdeps`) require pnpm 11+. Within-major bumps (`pnpm@11.x -> 11.y`) remain Renovate's job; non-pnpm package managers (yarn, npm) are out of scope.
@@ -501,6 +521,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: