@basein/runner 0.1.0

package/docs/installRun.md

@@ -0,0 +1,413 @@
+# Packaging BaseInstRunner for runner machines
+
+**The approach: publish to npm as `@basein/runner`, and install it globally at a
+pinned version.** The code already assumed this — the installer writes an `npx`
+invocation of its own package name into every wrapped MCP entry — so publishing
+was less a new distribution channel than closing a loop that was already there.
+
+This is the fleet-facing reference: what ships, how a runner machine goes from
+bare to recording, how it gets updated, and what to do when there is no registry
+to reach. For one person setting up one machine, [quickstart.md](quickstart.md)
+is shorter and assumes nothing.
+
+**Status.** Everything here is implemented and verified except §7: headless
+authentication is still a stopgap, and it is the one open item that needs a
+service-side decision rather than a change here.
+
+---
+
+## 1. Why this package is an easy case
+
+| Property | Value | Why it matters for packaging |
+|---|---|---|
+| Runtime dependencies | **none** | The tarball is self-contained. No lockfile resolution, no transitive CVEs, no native builds, and offline install just works. |
+| Module format | pure ESM (`"type": "module"`) | No dual-build gymnastics. |
+| Node floor | `>=20` | One prerequisite to check on a runner. |
+| Build | `tsc` → `dist/`, `prepublishOnly` wired | `npm publish` cannot ship a stale `dist/`. |
+| Bins | `bir`, `bir-proxy`, `bir-hooks`, `bir-scenario`, all with `#!/usr/bin/env node` | npm creates the shims, including `.cmd`/`.ps1` on Windows. |
+| Tarball | 97 files, 230 kB | `dist/` + types + docs. Sourcemaps and `docs/next.md` are excluded. |
+
+A zero-dependency, pure-JS, four-bin package is the best-behaved thing npm
+distributes. The delivery does not need to be clever.
+
+### What is excluded, and why
+
+`files` carries two negations:
+
+- `!dist/**/*.map` — 88 files, 287 kB. The maps carry no `sourcesContent`, and
+  `src/` is not published, so they cannot resolve a single stack frame. They were
+  bytes that did nothing on every install and every `npx` cold start.
+- `!docs/next.md` — a working scratchpad, not documentation.
+
+The rest of `docs/` **does** ship, and deliberately: the GitHub repository is
+private, so for anyone on a runner machine the tarball is the only place this
+documentation exists.
+
+---
+
+## 2. The options, and why this one
+
+| Approach | Runner install | Good for | Cost |
+|---|---|---|---|
+| **npm registry (public)** ← chosen | `npm i -g @basein/runner@0.1.0` | the default; makes the generated entries resolvable | the code is public |
+| npm registry (private, scoped) | same, plus an `.npmrc` token | code you cannot publish | every runner needs a read token, and so does `npx` |
+| GitHub Packages | same, `registry=https://npm.pkg.github.com` | no second account | GH tokens are clumsier to rotate across a fleet |
+| Tarball from a Release | `npm i -g ./basein-runner-0.1.0.tgz` | airgapped runners | no registry resolution — see §6 |
+| `npm i -g git+ssh://…#v0.1.0` | one line, no registry | a handful of machines | needs git and a toolchain on every runner; slowest and most fragile |
+| Node SEA / bundled binary | copy one file | machines where Node cannot be installed | you own a three-OS build matrix |
+| **Docker** | — | **not suitable** | The proxy spawns the host's own MCP servers as child processes, rewrites config in the user's home, and shares a cwd with the agent session. A container isolates exactly what this tool must reach. |
+
+The package is public; the repository is private. Those are separate decisions
+and this project makes them differently. Nothing operational leaks either way —
+the service is gated by `BIR_AUTH_URL` plus credentials.
+
+---
+
+## 3. Publishing
+
+### 3.1 Manifest — done
+
+`package.json` carries `repository` (npm requires it for provenance) and
+`publishConfig.access: public` (a scoped package is private by default, and
+`npm publish` on a scope you have no paid plan for otherwise fails).
+
+There is deliberately **no** `provenance`, and no `--provenance` in the workflow:
+npm's attestation requires a *public* repository. Turn both on the day that
+changes; nothing else has to move.
+
+`homepage` and `bugs` are also omitted, for the same reason — they would be dead
+links on a public package page.
+
+### 3.2 The name is load-bearing
+
+`PACKAGE_NAME` in [generate.ts](../src/config/generate.ts) is written into every
+config file the installer produces. Renaming after runners are deployed points
+every previously-installed project at a package that no longer resolves. It is
+settled now; treat it as fixed.
+
+### 3.3 The publishing credential
+
+The `basein` org exists on npmjs.com (free tier, public packages), and
+`NPM_TOKEN` is set as a repository secret in GitHub Actions.
+
+It is a **granular** token, not a classic automation one, because npm now steers
+you there:
+
+| Property | Value |
+|---|---|
+| Name | `github-actions-release` |
+| Scope | `basein`, read and write |
+| Organizations | no access — publishing needs the scope, not org administration |
+| 2FA | bypassed, which is what lets CI publish unattended |
+| **Expires** | **2026-10-05** |
+
+**Two dates to keep.**
+
+*2026-10-05 — the token dies.* Granular tokens must carry an expiry; npm offers
+no perpetual option. When a release starts failing with `ENEEDAUTH` around then,
+this is why. Regenerate with the same settings and overwrite the secret.
+
+*January 2027 — direct token publishing ends.* The token summary says so
+outright: "Publish new versions directly (deprecated — ends January 2027)". The
+replacement is **trusted publishing**, where the workflow authenticates to npm
+over OIDC and there is no stored credential at all — no secret to leak, and no
+expiry to forget. Migrating also removes the first date above, so doing it before
+2026-10-05 turns two chores into one.
+
+Releasing is then a tag:
+
+```bash
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+### 3.4 The workflows — done
+
+- [`.github/workflows/ci.yml`](../.github/workflows/ci.yml) — every push and PR
+  to main, on Ubuntu, Windows and macOS.
+- [`.github/workflows/release.yml`](../.github/workflows/release.yml) — on a
+  `v*` tag: the same three-platform suite, then publish, then attach the tarball
+  to a GitHub Release.
+
+Three platforms is not decoration. `resolveCommand` shells a `.cmd` upstream
+through `cmd.exe` with its own quoting, and `normalizePath` reconciles Claude
+Code's forward slashes with `process.cwd()`'s backslashes — the failure the code
+itself calls "the number one cause of *installed but never runs*". Neither is
+exercised on Linux.
+
+Both workflows run `npm run build` before the tests, because `test:smoke` spawns
+the real binaries out of `dist/` while `npm test` only builds `.test-build/`.
+
+The release job refuses to publish when the tag disagrees with `package.json` —
+npm has no undo past 72 hours, and a mismatched tag publishes a version nobody
+asked for.
+
+**One known flake.** `run_scenario finds the session whose plan is armed` loses
+an arming race roughly one run in three. It is unrelated to packaging, and the
+test steps retry once so it cannot redden a release at random. Remove the retry
+the day that test is made deterministic.
+
+---
+
+## 4. What `bir install` writes
+
+Three invocation modes, one flag each:
+
+| Mode | Flag | Entry |
+|---|---|---|
+| **npx** | *(default)* | `npx -y -p @basein/runner@0.1.0 bir-proxy …` |
+| **global** | `--global` | `<node> <prefix>/node_modules/@basein/runner/dist/bin/bir-proxy.js …` |
+| **local** | `--local` | `<node> <this checkout>/dist/bin/bir-proxy.js …` |
+
+**The npx spec is pinned.** It was not, and that was the one real defect in the
+original packaging story: two runners provisioned a week apart could run
+different proxy versions against the same service, with nothing in a recording to
+say which.
+
+**`--global` is what a fleet wants**, and it is what the bootstrap scripts pass.
+It removes the registry from the hot path entirely: no resolution before the MCP
+server can start, no dependence on the MCP host seeing the same `PATH` as the
+shell that installed things — which GUI-launched hosts on Windows do not — and
+it works with no network at all.
+
+It also survives upgrades. The path
+`<prefix>/node_modules/@basein/runner/dist/bin/bir-proxy.js` contains no version,
+so `npm i -g @basein/runner@0.2.0` changes what that path points at without
+changing the path. **A pinned-npx install, by contrast, must re-run `bir install`
+on every upgrade** to move the pin.
+
+`--global` refuses to run from a checkout: it asserts a path that outlives the
+shell, and a checkout's `dist/` moves with the checkout. Use `--local` when you
+mean the checkout on purpose.
+
+---
+
+## 5. Provisioning a runner
+
+Four scopes, and conflating them is the usual source of "installed but never
+runs":
+
+| Scope | How often | What it does |
+|---|---|---|
+| **machine** | once | Node ≥ 20, and the package installed globally |
+| **account** | once per user | `BIR_AUTH_URL`, then `bir login` → `~/.baseinstrunner/credentials.json` (0600) |
+| **project** | once per repo | `bir install --global` rewrites that project's MCP entries and wires the hooks |
+| **session** | while recording | `bir-hooks` running, discovered by `sha256(normalised cwd)` |
+
+That cwd keying is why `bir-hooks` must start in the *same directory* the agent
+session runs in. A control server started elsewhere is invisible, and the run
+silently degrades to Tier 2.
+
+### 5.1 One command
+
+[`scripts/install-runner.ps1`](../scripts/install-runner.ps1) and
+[`scripts/install-runner.sh`](../scripts/install-runner.sh) do machine, account
+and project scope together:
+
+```powershell
+.\scripts\install-runner.ps1 C:\work\repo -AuthUrl https://basein.example.com
+```
+
+```bash
+BIR_AUTH_URL=https://basein.example.com ./scripts/install-runner.sh ~/work/repo
+```
+
+Both are idempotent, both validate everything checkable **before** changing
+anything (a failed run leaves no half-provisioned machine), both skip `bir login`
+when a session is already cached, and both accept a local tarball
+(`-Tarball` / `BIR_TARBALL`) instead of the registry.
+
+Two things they deliberately do not do: supervise `bir-hooks`, and automate
+authentication. See §5.2 and §7.
+
+The PowerShell script is **pure ASCII** on purpose. Windows PowerShell 5.1
+decodes a BOM-less `.ps1` using the machine's ANSI codepage, and PowerShell
+accepts curly quotes as string delimiters — so a UTF-8 em-dash in a comment can
+decode into a quote and swallow the rest of the file. It parsed fine on one
+machine and failed on another before this was fixed. Keep it ASCII.
+
+### 5.2 Keeping `bir-hooks` alive
+
+One process per project cwd. On a headless runner, supervise it rather than
+leaving it in a shell.
+
+**Windows** — a Scheduled Task at logon, with *Start in* set to the project
+directory:
+
+```powershell
+$action  = New-ScheduledTaskAction -Execute 'bir-hooks' -WorkingDirectory 'C:\work\repo'
+$trigger = New-ScheduledTaskTrigger -AtLogOn
+Register-ScheduledTask -TaskName 'bir-hooks (repo)' -Action $action -Trigger $trigger
+```
+
+**macOS** — a launchd agent at `~/Library/LaunchAgents/com.basein.hooks.plist`,
+with `WorkingDirectory` set to the project and `StandardErrorPath` to a log file,
+then `launchctl load` it.
+
+**Linux** — a systemd user unit with `WorkingDirectory=`, plus
+`loginctl enable-linger "$USER"` so it survives logout.
+
+Whichever you use, redirect stderr to a file. Every decision is one `key=value`
+line on stderr and there is no file sink to configure, so the supervisor's
+redirection *is* the sink:
+
+```bash
+grep version.skew ~/.baseinstrunner/audit.log
+grep run.lossy   ~/.baseinstrunner/audit.log
+```
+
+### 5.3 Verify
+
+```bash
+bir doctor --json      # exits non-zero if it is not working right now
+```
+
+`bir doctor` asks the control server which proxies actually registered; it never
+reads the config file back. That makes it the right gate for a provisioning
+script. `bir status` only describes intent.
+
+---
+
+## 6. Machines with no registry
+
+Zero dependencies makes offline install trivial — no `npm ci --offline`, no
+vendored `node_modules`:
+
+```bash
+# on a connected machine
+npm pack @basein/runner@0.1.0        # or download the Release asset
+
+# on the runner
+BIR_TARBALL=./basein-runner-0.1.0.tgz ./scripts/install-runner.sh ~/work/repo
+```
+
+The bootstrap scripts already pass `--global`, so the resulting configs contain
+absolute paths and never reach for a registry. Nothing further is needed.
+
+Note that a private repository's Release assets require a GitHub token to fetch,
+so the tarball has to be carried to the runner by whatever means you already use.
+
+---
+
+## 7. Headless authentication — still a stopgap
+
+`bir login` prompts for email and password on a TTY and caches
+`{accessToken, refreshToken, accessExpiresAt, user}` at
+`~/.baseinstrunner/credentials.json`, mode 0600. For a fleet, in order of
+preference:
+
+1. **Pre-seed the credentials file.** Log in once as a dedicated service account,
+   copy `credentials.json` to each machine at 0600. The refresh token keeps it
+   alive and nothing prompts. Works today — but it is a shared long-lived secret,
+   so never a person's account.
+2. **`BIR_NO_AUTH` / `BIR_AUTH_DISABLE=1`** for runners that should record
+   nothing. Everything else still works.
+3. **Ask the service for a non-interactive grant** — client credentials, or a
+   long-lived runner token read from an env var. This is the right answer for a
+   fleet, and it is a service-side change. Worth raising before the fleet grows.
+
+`BIR_HOME` relocates all of this if state belongs somewhere other than
+`~/.baseinstrunner`.
+
+---
+
+## 8. Updating a runner
+
+Re-run the bootstrap script with the new version. It is idempotent, it will not
+prompt for a login it already has, and `bir install` will not double-wrap:
+
+```powershell
+.\scripts\install-runner.ps1 C:\work\repo -Version 0.2.0 -AuthUrl https://basein.example.com
+```
+
+```bash
+BIR_VERSION=0.2.0 BIR_AUTH_URL=https://basein.example.com ./scripts/install-runner.sh ~/work/repo
+```
+
+Then two rules:
+
+- **Restart `bir-hooks`.** A running process is still the old code. This is the
+  step people forget.
+- **Re-run `bir install` only if the entry shape changed** — or always, since it
+  is idempotent. With `--global` entries an upgrade needs no re-install at all
+  (§4). With pinned-npx entries it always does.
+
+Rolling back is the same command with the older version.
+
+### The half-upgraded machine
+
+This is the update failure that looks like success: the package is new, but a
+proxy is still the old code because a config points elsewhere or `bir-hooks` was
+never restarted. Everything keeps working, and quietly runs code you did not
+ship.
+
+A proxy now reports its version when it registers, the control server compares it
+with its own, and a mismatch is one line on the audit log:
+
+```
+[bir] … version.skew server=fleet proxy=0.0.9 hooks=0.1.0 fix="restart bir-hooks after upgrading, …"
+```
+
+`bir doctor --json` carries the same facts structurally — `hooksVersion` at the
+top and a `version` on each entry of `registeredProxies` — so a provisioning
+script can assert agreement rather than grep a log. A proxy too old to report a
+version is not treated as skewed: silence, not a false alarm.
+
+---
+
+## 9. Per-release verification
+
+CI does this on three platforms. To do it by hand on a clean machine:
+
+```bash
+npm run build && npm test          # 233 tests
+npm run test:smoke                 # real processes: hooks + proxy + scenario over stdio
+npm pack && npm i -g ./basein-runner-*.tgz
+cd /tmp/scratch && bir install --global && bir-hooks &
+bir doctor --json                  # must exit 0
+bir uninstall                      # must restore the config byte-for-byte
+```
+
+`test:smoke` is the one that matters for packaging: it is the only test that
+crosses process boundaries, which is exactly where a bad `files` list, a missing
+shebang, or a broken bin mapping shows up.
+
+Sandbox a manual run with `BIR_HOME` and `BIR_CLAUDE_JSON` so it cannot touch
+your real Claude Code configuration.
+
+---
+
+## 10. Where things stand
+
+| # | Item | State |
+|---|---|---|
+| 1 | Name settled; `PACKAGE_NAME` aligned | done |
+| 2 | `repository` + `publishConfig`; provenance deferred (private repo) | done |
+| 3 | Tarball trimmed — no dead sourcemaps, no scratchpad | done |
+| 4 | npx spec pinned; `--global` added | done |
+| 5 | CI and release workflows, three platforms | done |
+| 6 | `scripts/install-runner.{ps1,sh}` | done |
+| 7 | Version-skew detection on registration | done |
+| 8 | UTF-8 BOM tolerated in MCP configs | done |
+| 9 | npm org `basein`, `NPM_TOKEN` secret | done |
+| 10 | Tag `v0.1.0` to publish | ready |
+| 11 | Non-interactive auth grant for fleets | **needs the service** |
+| 12 | Migrate to trusted publishing before Jan 2027 (§3.3) | scheduled |
+
+Item 11 is the only one that needs somebody else.
+
+---
+
+## Appendix: the BOM
+
+`bir` used to reject any MCP config saved with a UTF-8 byte order mark. Notepad
+writes one, so does VS Code's "UTF-8 with BOM", and so does PowerShell's
+`Out-File -Encoding utf8`. `readFileSync(path, "utf8")` decodes the BOM to U+FEFF
+rather than consuming it, and `JSON.parse` then rejects the file.
+
+The failure mode was the bad part: `bir install` logged the parse error and
+**still reported success**, so an operator saw a green run and no wrapping. On
+Windows runners this was a matter of time.
+
+`parseJsonFile` now strips it, which covers every user-authored config read.
+Restoring is unaffected — the uninstall backup stashes raw text on a separate
+path, so a BOM'd file comes back with its BOM intact.