@basein/runner 0.2.7 → 0.2.10

package/docs/loginWeb.md

@@ -395,7 +395,7 @@ with a TTY and no session no longer prompts; it logs
 
 ### 5.4 Installer scripts
 
-`scripts/install-runner.sh:144-145` and `install-runner.ps1:153-154` call
+`scripts/install.sh (via `bir setup`)` and `install.ps1 (via `bir setup`)` call
 `bir login` in the foreground and need **no code change** — the device flow
 prints its link and code on whatever terminal the script has, and works over
 SSH because the link can be opened anywhere. What changes is the prose around

package/docs/quickstart.md

@@ -1,234 +1,269 @@
 # Setting up a runner machine
 
-This guide takes one computer from nothing to recording. It assumes no prior
-knowledge of the project. It should take about ten minutes, most of which is
-waiting for downloads.
+One person, one computer: from nothing to a project whose every Claude Code
+session is recorded and whose calculated scenarios run. It takes a few minutes,
+most of them downloads. Nothing has to stay open afterwards.
 
-**What you are setting up.** BaseInstRunner sits quietly between your AI coding
-assistant and the tools it uses, watches what happens, and saves each session to
-the BaseIn service so it can be reviewed or re-run later. It does not change what
-the assistant does.
+**What you are setting up.** BaseInstRunner sits between Claude Code and the
+tools it uses, records each session to the BaseIn service, and — when a new
+prompt means the same thing as one it has seen — runs the calculated scenario
+instead of letting the model rediscover the plan. Otherwise it does not change
+what the model does.
 
 ---
 
 ## Before you start
 
-Three things:
-
-1. **Node 20 or newer.** Check by opening a terminal and typing `node -v`. If you
-   see something like `v20.11.0` or higher, you are fine. If you see an error or
-   a smaller number, install it from [nodejs.org](https://nodejs.org) first.
-2. **The BaseIn service address** — a URL like `https://basein.example.com`.
-   Whoever runs the service gives you this.
-3. **Your BaseIn email and password.** You will type these once.
+A BaseIn account. That is all: Node and Claude Code are installed for you if the
+machine has neither. On Windows use PowerShell or cmd, whichever your terminal
+is; the console shows a line for each.
 
 ---
 
-## Step 1 — run one command
-
-Open a terminal **in the folder where you unpacked this project's `scripts`
-folder**, and run the line for your machine. Replace the two placeholder values
-with your real service address and your real project folder.
+## Step 1 — paste the line
 
-### Windows
+Sign in to the console and open **Set up the runner**. The first thing on the
+page is one line with a one-time setup token filled in (valid for ten minutes,
+usable once). Open a terminal **in the project folder you start Claude Code in**
+and paste it:
 
 ```powershell
-.\scripts\install-runner.ps1 C:\path\to\your\project -AuthUrl https://basein.example.com
+$env:BIR_SETUP_TOKEN="<token>"; irm https://api.bi2202.com/install.ps1 | iex
 ```
 
-### macOS
+```cmd
+powershell -NoProfile -Command "$env:BIR_SETUP_TOKEN='<token>'; irm https://api.bi2202.com/install.ps1 | iex"
+```
 
 ```bash
-BIR_AUTH_URL=https://basein.example.com ./scripts/install-runner.sh ~/path/to/your/project
+curl -fsSL https://api.bi2202.com/install.sh | BIR_SETUP_TOKEN="<token>" sh
 ```
 
-> **"Running scripts is disabled on this system"** (Windows only) — Windows blocks
-> unsigned scripts by default. Allow them for your own account with:
-> `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`, then run the command
-> again.
-
----
-
-## Step 2 — watch what it does
-
-The script narrates each stage. A healthy run looks like this:
+Without a token — it expired, or you are not at the console — the same line
+without the `BIR_SETUP_TOKEN` part works: `bir setup` uses the sign-in already
+cached on this computer if there is one, and otherwise opens your browser to
+approve the sign-in and waits. Over SSH it prints the link and a short code
+instead; they work from any device, a phone included.
+
+The script prints a `==>` line per stage and never asks a question. Before it
+downloads anything it checks that this is not your home folder or a drive root;
+if it is, it stops and asks you to `cd` to the project and paste again. Then:
+
+1. **Node.** A Node 20+ on PATH is used when npm sits beside it and nothing
+   can move it: a Node from nvm, fnm, Volta, asdf, mise or nodenv changes path
+   per shell or per version, and so does one from Homebrew or snap (macOS and
+   Linux) or Scoop (Windows) — a `brew upgrade` moves the path the hook pins.
+   Any of those, or no Node at all, and a private copy goes under
+   `~/.baseinstrunner/node/v<version>/`. It is never put on your PATH.
+2. **The runner.** `@basein/runner` is installed under `~/.baseinstrunner/npm/`,
+   with `bir` and `bir-hooks` launchers in `~/.baseinstrunner/bin/`, which goes
+   first on your user PATH. No execution-policy change on Windows.
+3. **Claude Code.** Installed with its official installer if `claude` is not on
+   PATH. This can take a minute.
+4. **`bir setup`**, which prints:
 
 ```
-==> Checking Node
-    node v20.11.0
-==> Installing the runner
-    @basein/runner@0.1.0 from the registry
-    bir 0.1.0 -- all four binaries on PATH
-==> Configuring the BaseIn service
-    BIR_AUTH_URL=https://basein.example.com (persisted for this user)
-==> Signing in
-
-[bir] Sign in to https://basein.example.com
-
-  Open   https://basein.example.com/activate?code=BKQM-TXZR
-  Code   BKQM-TXZR
-
-  Opening your browser...
-  Waiting for approval...  (Ctrl-C to cancel)
-
-Signed in to https://basein.example.com as you@example.com.
-==> Wrapping MCP servers in C:\path\to\your\project
-  + chrome-devtools -> bir-proxy (project scope, upstream: npx)
-  + hooks -> ...\.claude\settings.json
+==> Setting up the runner (0.2.9)
+    service   https://api.bi2202.com
+    account   you@example.com
+==> Wiring the project
+  + chrome-devtools → bir-proxy (project scope, upstream: npx)
+  + bir → bir-scenario (calculated replay; project scope)
+  + hooks → C:\work\repo\.claude\settings.local.json (control server on http://127.0.0.1:53411; the recorder starts itself with each session)
+  + .claude/settings.local.json is listed in C:\work\repo\.git\info\exclude
 
 Wrapped 1 server.
+…
+==> Starting the recorder in the background
+
+Done. Recording and replay are on for C:\work\repo
+  account    you@example.com  (https://api.bi2202.com)
+  wrapped    chrome-devtools
+  replay     on — direct execution allowed for: all wrapped (narrow it with `bir replay allow chrome-devtools`)
+  recorder   started in the background (pid 1234) — it starts itself with every Claude Code session
+  log        C:\Users\you\.baseinstrunner\logs\3f9c1a2b7d4e5f60.log
+
+Now:  claude
+  first time in this folder: say Yes to "trust this folder"
+  just installed Claude Code? it asks you to sign in to Claude (it needs a Claude subscription)
+  give it a task that takes 4+ tool calls — it appears at https://bi2202.com/recordings within a minute of finishing
+Any time:  bir doctor     bir investigate     bir down (stop)     bir uninstall (undo)
 ```
 
-**Signing in happens in your browser, not the terminal.** The script prints a
-link and a short code, then waits. Open the link, check that the code matches
-and that it says it will sign you in as you, and press **Approve**. There is no
-password to type here, which is also why this works for an account that only
-ever signs in with Google.
-
-The link works from any device — a phone is fine — so this is also the answer on
-a machine with no browser. Add `--no-browser` to stop it trying to open one.
-
-If anything goes wrong the script stops immediately and says why — it checks
-everything it can *before* changing your machine, so a failed run leaves nothing
-half-installed.
+Line by line: *service* is the API address, now stored so no terminal needs
+`BIR_AUTH_URL`; *account* is who the recordings belong to; *wrapped* is the
+project's MCP servers, each now routed through `bir-proxy` under its old name;
+*replay* says which of them a calculated scenario may call unattended — narrow
+it with `bir replay allow <names>`, turn it off with `bir replay off`, and read
+[calculatedReplayGuide.md §5.1](calculatedReplayGuide.md) before leaving it wide
+anywhere that matters; *recorder* is the background process, and *log* is where
+its audit lines go.
+
+A project with no MCP servers in any scope — none in `.mcp.json`, and none for
+this project or your user in `~/.claude.json` — shows `wrapped (no MCP servers
+here)` and `replay steer mode only`: built-in tools and prompts are still
+recorded, and a scenario still steers the session, but there is nothing to
+execute directly.
+
+Pasted in the home folder anyway? The script stops before it downloads anything
+— `This is your home folder. Open a terminal in the project you start Claude
+Code in (cd there) and paste the line again.` Nothing was installed, nobody was
+signed in and the token is unused, so `cd` to the project and paste the same
+line. It is `bir setup` run by hand in the home folder, with the runner already
+installed, that keeps the sign-in and prints the two commands left:
+`cd <your project>` and `bir setup`. No token is needed then; the sign-in is
+kept on this computer.
+
+On macOS and Linux the script cannot change the terminal it was pasted into, so
+it ends with a line to paste — `export PATH="$HOME/.baseinstrunner/bin:$PATH"` —
+or open a new terminal. On Windows it ends with `bir works in every new terminal
+(and in this window when it is PowerShell)`: the PowerShell line puts `bir` on
+that window's PATH in place, but the cmd line runs the script in a child
+`powershell.exe`, so a cmd window has to be a new one.
 
 ---
 
-## Step 3 — start recording
-
-Two terminals, in the project folder you gave the script.
-
-**First terminal** — leave this one running the whole time:
-
-```
-bir-hooks
-```
+## Step 2 — start Claude Code
 
-**Second terminal** — your normal work:
+In the same folder:
 
 ```
 claude
 ```
 
-That is it. Everything you do in the second terminal is now recorded.
+The first time in a folder Claude Code asks whether to trust it: say Yes, or the
+hooks do not run. If the script just installed Claude Code, it asks you to sign
+in to Claude; that is Claude's own subscription, separate from BaseIn.
 
-When you are finished for the day, press `Ctrl+C` in the first terminal.
+Then give it a task that takes four or more tool calls. It appears on the
+console's Recordings page within a minute of finishing.
 
----
+Nothing else to start. The SessionStart hook (`bir-hooks ensure`) starts the
+recorder in the background whenever this folder has none, so a session started
+tomorrow, or after a reboot, records the same way.
 
-## Step 4 — check it actually worked
+---
 
-With `bir-hooks` running, in another terminal:
+## Step 3 — check it
 
 ```
-bir doctor
+bir doctor     # is it working right now? exits non-zero if not
+bir status     # what is installed for this folder; needs nothing running
 ```
 
-This is the one command worth remembering. It does not read a settings file and
-tell you what *should* happen — it asks the running system what is *actually*
-happening, and it fails loudly when something is wrong.
-
-To see what is set up without needing anything running:
+`bir doctor` asks the running recorder rather than reading a settings file: it
+says which service it records to, that the recorder runs in the background
+(with its pid and log file), and what replay is set to and where that setting
+came from. `bir status` prints the service address, the wrapped servers and the
+control server's address and log.
 
-```
-bir status
-```
+Then open https://bi2202.com/recordings. The run from Step 2 is there, with
+its prompt, its tool calls and its final answer.
 
 ---
 
-## When something is wrong
+## What it changed on your machine
 
-### "It says nothing is recorded"
+| Path | What it holds |
+|---|---|
+| `~/.baseinstrunner/config.json` | the service address; `BIR_AUTH_URL` in the environment overrides it, and `bir setup` warns when the two differ |
+| `~/.baseinstrunner/credentials.json` | the cached session, bound to the service that issued it |
+| `~/.baseinstrunner/installed.json` | the original text of every file it rewrote, and each project's port, token and replay switches |
+| `~/.baseinstrunner/logs/<key>.log` | the recorder's audit log, one file per project |
+| `~/.baseinstrunner/node/` | a private Node, only if the machine had no usable one; not on PATH |
+| `~/.baseinstrunner/npm/` | the runner package |
+| `~/.baseinstrunner/bin/` | the `bir` and `bir-hooks` launchers, first on your user PATH |
+| `<project>/.claude/settings.local.json` | Claude Code's hooks for this project and the pre-approved `bir` scenario server. Yours, not the team's: it carries this project's token and an absolute Node path |
+| `<project>/.mcp.json` (or `~/.claude.json`, whichever scope an entry lives in) | each MCP entry rewritten to run through `bir-proxy`, same keys; plus the `bir` scenario entry, which always goes in `.mcp.json` (project scope), never in `~/.claude.json` |
+| `<project>/.git/info/exclude` | one line, `.claude/settings.local.json`, so it never shows in `git status` |
 
-`bir status` will show `BaseIn: (BIR_AUTH_URL not set — nothing is recorded)`.
-The service address did not stick. Close the terminal, open a new one, and check
-`echo $env:BIR_AUTH_URL` (Windows) or `echo $BIR_AUTH_URL` (macOS). If it is
-empty, run the install script again with the `-AuthUrl` / `BIR_AUTH_URL` value.
+Each project gets its own control port (from 53411 up) and its own token, so one
+project's settings file cannot reach another project's recorder.
 
-### "The browser never opened"
-
-Not a problem: the link and the code are printed either way, and the link works
-from any device. Open it on your phone and approve there. `bir login` skips
-opening a browser on purpose over SSH, and `--no-browser` skips it always.
-
-### "The code expired before I approved it"
-
-Codes last ten minutes. Run `bir login` again for a fresh one.
-
-### "bir login says … is not a BaseIn service" (or `HTTP 405 Method Not Allowed`)
-
-`BIR_AUTH_URL` points at a website — the docs or app address — instead of the
-API. It must be the service address, normally `https://api.<your-domain>`. Fix
-the value, then **open a fresh terminal**: an existing one keeps the value it
-started with, even after the install script or a settings change updates it.
-`bir doctor` prints what the current terminal has on its `BaseIn (shell)` line.
-
-### "bir is not recognised as a command"
+---
 
-The install worked but your terminal has not noticed yet. **Close the terminal
-and open a new one.** This fixes it almost every time.
+## Another project
 
-### "It records the tools but not what I typed"
+```
+cd the-other-project
+bir setup
+```
 
-`bir-hooks` is not running, or it is running in a different folder. It has to be
-started **in the same folder** as your session — that is how the two find each
-other. Stop it, `cd` to the project folder, and start it again.
+No token: the sign-in is kept. The project gets its own port, token and log.
 
-### "invalid JSON at ...\.mcp.json"
+---
 
-Something has edited that file into a shape that is no longer valid JSON —
-usually a missing comma or a stray bracket. Open it and check. (A file saved by
-Notepad is fine; that case is handled.)
+## Updating
 
-### Anything else
+Paste the line from the console again — the very same line is fine, used token
+and all: `bir setup` says `the setup token was already used; keeping the sign-in
+from before (you@example.com)` and goes on. It installs the newest version and
+runs `bir setup`, which re-wraps any entry whose runner moved. If you installed
+by hand with `npm i -g @basein/runner`, upgrade the same way and then run
+`bir setup` in each project.
 
-Run `bir doctor` and keep the output. It says which part of the chain is broken,
-which is most of the way to an answer.
+A recorder of the older version is replaced only at the moments that look for
+one — the SessionStart hook, `bir up`, `bir setup` — and only when no session
+is mid-run right then; nothing watches for a session to end. `bir setup` says
+so when one is open (`recorder 0.2.8 is still serving an open Claude Code
+session; it restarts to 0.2.9 with the next session`). `bir up --restart` does
+it now.
 
 ---
 
-## Updating to a newer version
-
-Run the same install script again with the new version number:
+## Undoing
 
-```powershell
-.\scripts\install-runner.ps1 C:\path\to\your\project -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 ~/path/to/your/project
+bir down          # stop this project's recorder
+bir uninstall     # put every file back byte-for-byte; remove hooks and the bir entry
 ```
 
-It is safe to re-run: it will not ask you to sign in again, and it will not
-double-wrap anything.
+`bir uninstall` also forgets the project's port and token and takes the
+`.claude/settings.local.json` line back out of `.git/info/exclude`.
+Byte-for-byte holds for a file nothing else edited since the install; one you
+edited is repaired entry by entry instead, and it says so. A file the install
+created — usually `.claude/settings.local.json` — stays behind, empty of our
+entries.
 
-**One thing you must do by hand: stop `bir-hooks` and start it again.** A running
-process keeps using the old version until it is restarted. If you forget, the
-next session logs a `version.skew` warning telling you exactly that.
+To remove the software: `bir logout` first, so the session is revoked on the
+service rather than only forgotten here. Then `npm rm -g @basein/runner` if
+you installed by hand, or delete `~/.baseinstrunner` (the runner, its private
+Node, the launchers, the session and the logs) and remove
+`~/.baseinstrunner/bin` from your PATH.
 
 ---
 
-## Undoing it
-
-In the project folder:
-
-```
-bir uninstall
-```
-
-This puts every file it touched back exactly as it found it, byte for byte.
-
-To remove the software entirely as well:
+## When something is wrong
 
-```
-npm rm -g @basein/runner
-```
+`bir doctor` first. It names the broken link in the chain, which is most of the
+answer. Then:
+
+| You see | Why | Do |
+|---|---|---|
+| `This is your home folder…` from the script | a terminal opened from the Start menu begins in the home folder; the script stopped before downloading anything, so nothing is installed, nobody is signed in and the token is unused | `cd` to the project and paste the same line again |
+| `Signed in as … This is your home folder, so nothing was wired here` from `bir setup` | the same folder, but `bir setup` run by hand with the runner already installed; the sign-in is kept | `cd` to the project and run `bir setup` — no token needed |
+| `… is not a BaseIn service` | the address is the website (docs or app), not the API; or a stale `BIR_AUTH_URL` in a shell profile — `bir setup` warns when the two disagree | `bir setup --auth-url https://api.bi2202.com`; remove the variable from the profile |
+| `control.port_busy` in the log (`port N is held by another program or excluded by the system`); the recorder did not start | another program holds this project's port, or the system reserves the range it falls in — on Windows, Hyper-V and WSL exclude blocks that 53411 sits inside | `bir setup --port <n>` (by hand: `bir install --replay --port <n>` — a flag-less install keeps the way the project was installed — then `bir up --restart`) |
+| `recorder.disabled … no BaseIn session` in the log; `bir doctor` says the recorder has nowhere to send steps; or `bir setup` ends with ``not signed in — run `bir setup` again (or `bir login`)`` | not signed in, or signed in to another service | `bir setup`, then `bir up --restart` |
+| `that is not a valid setup token`, or `this setup token has expired or was already used` from `bir setup` | the token was cut short in the paste; or it is older than ten minutes or already redeemed, with no cached sign-in to fall back on | make a new one on the console's *Set up the runner* page and paste the whole line within ten minutes |
+| the tools were recorded but not the prompt | no recorder was running for this folder, so the proxies recorded on their own (Tier 2) | `bir doctor` says whether a recorder runs for this folder; `bir up` starts one now — the next session starts it anyway |
+| the run is not in Recordings | fewer than four tool calls; or the runner is signed in as a different account than the console | give a bigger task; compare the *account* line of `bir setup` with the console |
+| `bir doctor`: `the SessionStart hook … points at a Node that is gone` | the Node the hook names was removed or moved by a version manager | `bir setup` — it rewires the hook to the current Node |
+| Claude Code asks you to sign in | Claude Code was just installed; it needs a Claude subscription | sign in; nothing to do on the runner side |
+| `bir` is not recognised in the terminal the line was pasted into | on macOS and Linux the script cannot change that terminal's PATH; on Windows the cmd line runs the script in a child `powershell.exe`, whose PATH dies with it (the PowerShell line changes its own window) | macOS / Linux: `export PATH="$HOME/.baseinstrunner/bin:$PATH"`, or open a new terminal; Windows cmd: open a new window |
+| `invalid JSON at …/.mcp.json` | something edited the file into a shape that no longer parses | open it and fix the comma or bracket |
+
+For a turn that did not do what you expected — a scenario that did not run, a
+saving that was not made — `bir investigate` reads the journal and the service
+and says why.
 
 ---
 
 ## Where to go next
 
-- [installRun.md](installRun.md) — the fleet version of this: packaging, release
-  process, offline installs, keeping `bir-hooks` alive across reboots.
+- [installRun.md](installRun.md) — the fleet version: packaging, releases,
+  offline installs, updates.
+- [calculatedReplayGuide.md](calculatedReplayGuide.md) — record, calculate,
+  check, enable, and read the audit lines.
 - [../README.md](../README.md) — what is recorded, what cannot be, and every
   configuration switch.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basein/runner",
-  "version": "0.2.7",
+  "version": "0.2.10",
   "description": "A recording MCP proxy: sits between any MCP client and its MCP servers, executes each call on the client's behalf, and records the run as a reusable BaseIn scenario.",
   "type": "module",
   "license": "MIT",
@@ -27,6 +27,7 @@
     "!dist/**/*.map",
     "README.md",
     "LICENSE",
+    "scripts",
     "docs",
     "!docs/next.md"
   ],