@verirun/cli 0.1.0 → 0.2.1

package/README.md

@@ -1,7 +1,9 @@
 # verirun
 
 Record a browser workflow, replay it, and capture the Supabase, Vercel + Railway logs
-your backend produced during the replay.
+your backend produced during the replay. Plus `verirun map`: a static
+interaction graph of your React/TypeScript app — every page, what you can click
+on it, and which backend calls those clicks make — without running anything.
 
 ## Install
 
@@ -49,7 +51,7 @@ verirun logout     # disconnect this machine
 
 | | |
 | --- | --- |
-| `~/.verirun/config.json` | Holds the device token. Per user, not per project. |
+| `~/.verirun/config.json` | Holds the device token. Per user, not per project. Restricted to your account (0600, or an `icacls` ACL on Windows). |
 | `~/.verirun/state.json` | The last **server-signed lease** (Ed25519) plus a local tamper check. Editing it, or a lease not signed by Verirun's key, is ignored and forces a fresh online check. |
 | `$VERIRUN_LICENSE_KEY` | A raw key for CI, used instead of `verirun login`. |
 | `$VERIRUN_LICENSE_SERVER` | Point the CLI at a different server. |
@@ -72,6 +74,7 @@ machine past that is blocked until you release one from
 fingerprint and use a seat; release the stale one to fix it.
 
 `verirun --help`, `verirun --version`, `verirun log` and `verirun agent` do not require an account.
+`verirun map` does.
 
 ---
 
@@ -96,8 +99,12 @@ Opens a headed browser. Perform the workflow by hand — click, type, navigate.
 | `-f, --force` | Overwrite an existing workflow of the same name. Without it, recording onto an existing name errors. |
 
 **Name rules.** `<name>` becomes a filename: letters, digits, dot, dash,
-underscore; must start with a letter or digit; 64 chars max. It is not
-sanitised — an invalid name errors rather than being rewritten.
+underscore; must start with a letter or digit; 64 chars max. Two Windows rules
+are enforced on every platform, so a workflow you record stays usable for a
+teammate who checks the repo out on Windows: no trailing dot (Windows drops it,
+colliding with the bare name), and no reserved device stem — `con`, `prn`, `aux`,
+`nul`, `com1`–`com9`, `lpt1`–`lpt9`, at any extension. Names are not sanitised —
+an invalid name errors rather than being rewritten.
 
 **Selectors.** Recording goes through Playwright's codegen engine, so each step
 gets its stable selector — `getByTestId`, then `getByRole` with an accessible
@@ -128,6 +135,52 @@ is saved and the command says so.
 
 ---
 
+### Recording or replaying as a signed-in user
+
+Point both commands at a Chrome profile that is already logged in:
+
+```bash
+verirun record checkout --channel chrome --user-data-dir "$HOME/.verirun-profile"
+verirun run    checkout --channel chrome --user-data-dir "$HOME/.verirun-profile"
+```
+
+On Windows pass an absolute path instead — cmd and PowerShell don't expand `~`
+inside an argument like this, and verirun never expands it either, so a literal
+`~` just creates a directory called `~` and the run starts logged out:
+
+```powershell
+verirun run checkout --channel chrome --user-data-dir "$env:USERPROFILE\.verirun-profile"
+```
+
+Create that profile once, by hand, and sign in there — identity providers block
+sign-in in an automation-launched browser:
+
+```bash
+# macOS / Linux
+google-chrome --user-data-dir="$HOME/.verirun-profile" --password-store=basic
+```
+
+```powershell
+# Windows (PowerShell)
+& "$env:ProgramFiles\Google\Chrome\Application\chrome.exe" `
+  --user-data-dir="$env:USERPROFILE\.verirun-profile"
+```
+
+`--password-store=basic` (plus `--use-mock-keychain` on macOS) is not optional:
+Playwright always launches Chrome with those flags, and cookies written under
+your OS keyring can't be decrypted without them — the run starts logged out with
+no error. Both switches are Unix-only, so on Windows they're ignored — there just
+create the profile as the same Windows user that runs verirun. **The Windows path
+is untested:** if a run starts logged out despite a signed-in profile, that's the
+first thing to suspect. On every platform, don't reuse your everyday Chrome
+profile; use a dedicated one. Close the profile before recording or running, since
+Chrome locks it.
+
+To check it took, reopen the profile on its own — if that window is signed in,
+verirun will be too.
+
+---
+
 ## `verirun run <name>`
 
 ```bash
@@ -140,6 +193,7 @@ and writes `.verirun/runs/<name>-<timestamp>/logs.json`.
 
 | Flag | Meaning |
 | --- | --- |
+| `--slow-mo <ms>` | Pause before each action. Defaults to **500 ms when `--headed`** so you can follow the run by eye, and to 0 otherwise. `--slow-mo 0` watches at full speed; a bigger number follows a fast form more easily. |
 | `--headed` | Show the browser window instead of running headless. |
 | `--timeout <ms>` | Per-action timeout, milliseconds. Non-negative. Defaults to Playwright's 30000. |
 | `--channel <name>` | Replay in an installed browser: `chrome`, `msedge`, … Overrides the channel saved in the workflow. Chromium family only. |
@@ -265,28 +319,151 @@ with `railway.deploymentId` in config.) Logs are already scoped to that service
 + environment, so there's no separate project filter. Already connected →
 one-line status.
 
-**`verirun log vercel`** — Vercel only *pushes* runtime logs (no pull API), so
-the listener needs a public tunnel and a Log Drain pointed at it, which the CLI
-can't create. It prints a 4-step checklist (tunnel → `--listen` → add the drain
-with **Sources: Edge + Serverless, Format: JSON, Endpoint: `<tunnel>/drain`** →
-copy the signing secret), opens the Log Drains page, then prompts for the secret
-(refusing to save silently without one) and an optional **project** name/ID to
-scope deliveries. Already connected → one-line status. Change the listener port
-via `vercel.listenerPort` in config, not a prompt.
+**`verirun log vercel`** — same shape as the other two: it opens
+`https://vercel.com/account/settings/tokens`, you paste a token, and it picks
+the project. If the repo has a `.vercel/project.json` (i.e. you have run
+`vercel link`), the project and team are read from it and **you are asked
+nothing else**; otherwise it lists your teams and projects and you choose. It
+then resolves the newest ready production deployment and reads its runtime logs
+to confirm the token works. No tunnel, no drain, no second terminal.
+
+On each run it re-resolves the newest ready deployment, so a redeploy doesn't
+break the config. Pin one with `vercel.deploymentId`, or read preview
+deployments instead with `vercel.environment: "preview"`.
+
+<details>
+<summary><b>Drain mode</b> (<code>--drain</code>) — the old push-based setup</summary>
+
+Vercel's runtime-log API is the easy path, but if it isn't available to you, the
+original Log Drain flow is still there under `verirun log vercel --drain`: a
+tunnel, a local listener, and a drain pointed at it (4-step checklist → tunnel →
+`--listen` → add the drain with **Sources: Edge + Serverless, Format: JSON,
+Endpoint: `<tunnel>/drain`** → paste the signing secret). Config keys
+`listenerPort`, `listenerPath`, `drainSecret`, `drainGraceMs`, `project` belong
+to this mode only. verirun uses drain mode whenever `vercel.token` is absent,
+so the two never collide.
+
+</details>
 
 Non-interactive shells get the env/config values to set instead of a prompt.
 
 | Flag | Meaning |
 | --- | --- |
 | `--reconnect` | Run the connect flow again and replace what was saved. Any source. |
-| `--test` | **`supabase` / `railway`.** Query the last 5 minutes and print `<source> <row count>` or the error. Needs a connected source. Non-zero exit if it errored. |
-| `--listen` | **`vercel` only.** Start the Log Drain listener now and keep it running until Ctrl+C, printing each delivery as `timestamp level stream message`. Use it for the dashboard's endpoint-verification step and for live tailing. Binds `listenerPort` + `listenerPath` from config (defaults `4319` / `/drain`). |
+| `--test` | Query the last 5 minutes and print what came back, or the error. Needs a connected source. Non-zero exit if it errored. |
+| `--drain` | **`vercel` only.** Set up the old push-based Log Drain instead of the API. |
+| `--listen` | **`vercel` drain mode only.** Start the Log Drain listener now and keep it running until Ctrl+C, printing each delivery as `timestamp level stream message`. Binds `listenerPort` + `listenerPath` from config (defaults `4319` / `/drain`). |
 
 An unknown `<source>` errors. A flag meant for another source is ignored.
 Each `verirun log <source>` connect flow *writes* its own block of
-`.verirun/config.json` (0600); the overview is read-only. A secret supplied via
-`$VERIRUN_SUPABASE_ACCESS_TOKEN` / `$VERIRUN_VERCEL_DRAIN_SECRET` /
-`$VERIRUN_RAILWAY_TOKEN` is never written to the file.
+`.verirun/config.json`, restricted to your user account — mode 0600 on macOS and
+Linux, and an `icacls` ACL granting only you on Windows, since mode bits mean
+nothing there. If that cannot be applied the flow warns rather than leaving you
+to assume the token is protected. The overview is read-only. A secret supplied via
+`$VERIRUN_SUPABASE_ACCESS_TOKEN` / `$VERIRUN_VERCEL_TOKEN` /
+`$VERIRUN_VERCEL_DRAIN_SECRET` / `$VERIRUN_RAILWAY_TOKEN` is never written to
+the file.
+
+---
+
+## `verirun map`
+
+Reads this repository's React/TypeScript source and builds an **interaction
+graph**: one node per page, the interactive elements on it, the pages each one
+navigates to, and the backend calls each one makes. Nothing is executed — no
+browser, no server, no recording.
+
+```bash
+verirun map                          # per-page summary
+verirun map --json                   # the whole graph
+verirun map --report                 # graph + coverage.md into .verirun/map
+verirun map --bfs /account --depth 2 # what is reachable from one page
+verirun map --reach                  # how much of each page was captured
+```
+
+Routes come from a react-router `<Routes>` declaration **or** a Next.js App
+Router `app/**/page.tsx` tree (`[id]` → `:id`, route groups dropped, `layout.tsx`
+applied to its subtree). Components a page renders from another file are
+followed, so a page whose real UI lives in a client component is not reported
+empty. Import aliases are read from `tsconfig.json`; add more with
+`--alias @/=src`.
+
+```
+$ verirun map
+6 pages · 6 backend effects · 31 edges (40 files)
+
+  / — Page, 0 element(s), 10 nav, 0 effect
+  /account — AccountPage, 5 element(s), 1 nav, 4 effect
+  /login — LoginPage, 2 element(s), 2 nav, 3 effect
+```
+
+`--bfs` takes a route path (`/account`), a page id (`page:/account`) or a page
+component name, and reports each node once at its shortest distance, with the
+element that gets you there:
+
+```
+$ verirun map --bfs /account --depth 2
+page:/account
+  └─ nav "verirun" → page:/
+  └─ effect "revoke" [if !(tokens.length === 0)] → effect:POST ?
+    └─ nav "Log in" → page:/login
+# frontier at depth 2: page:/login, page:/signup
+```
+
+**Limits, honestly.** It is static analysis: a target computed at runtime shows
+as `unresolved`, an endpoint passed through a variable as `?`, and Supabase
+`.auth.*` / `.storage.*` calls are not yet classified as effects. `--reach`
+tells you what fraction of each page it actually attached, so you can see when
+it is missing something rather than guessing.
+
+---
+
+## `verirun workflow check <name>`
+
+Validates a workflow file without running it — JSON shape, schema version, known
+actions, a `selector` where one is needed, the required `params` per action, and
+warnings for the things that replay tolerates but you probably didn't mean
+(a bare `role=button` that matches five elements, an `assert*` step that replay
+skips, a first step that isn't `navigate`, and a `navigate` *after* the first
+step — walking the app by URL skips the UI, so a dead link or a button that
+stopped submitting still passes).
+
+```bash
+verirun workflow check login
+verirun workflow check login --json     # machine-readable findings
+verirun workflow check ./some/file.json
+```
+
+Static only: it never opens a browser, so it cannot tell you whether a selector
+matches the live page. Only `verirun run` can. Non-zero exit if anything is an
+error.
+
+This exists because a workflow doesn't have to come from `record`. `verirun map
+--json` gives every element a `selector`, a `selectorConfidence`
+(`high`/`medium`/`low`) and a suggested `action`, which is enough for you — or
+an agent — to write `.verirun/workflows/<name>.json` directly:
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "name": "login",
+  "createdAt": "2026-09-20T00:00:00.000Z",
+  "browser": "chromium",
+  "steps": [
+    { "index": 0, "action": "navigate", "params": { "url": "https://app.example.com/login" }, "signals": [] },
+    { "index": 1, "action": "fill", "selector": "role=textbox[name=\"Email\"i]", "params": { "text": "ada@example.com" }, "signals": [] },
+    { "index": 2, "action": "click", "selector": "role=button[name=\"Log in\"i]", "params": {}, "signals": [] }
+  ]
+}
+```
+
+Actions and required `params`: `navigate` (`url`, absolute), `click` /
+`dblclick`, `fill` (`text`), `press` (`key`), `check` / `uncheck`, `select`
+(`values`), `setInputFiles` (`files`). Everything but `navigate` needs a
+`selector`, which is handed to `page.locator()` verbatim.
+
+A recorded workflow is ground truth; a written one is a guess until `run`
+confirms it. Don't overwrite a recording with a generated file — use a new name.
 
 ---
 
@@ -301,8 +478,16 @@ workflows, recent runs.
 ```bash
 verirun agent > .verirun/AGENT.md      # save it as context for your agent
 verirun agent --json                   # machine-readable form
+verirun agent --skill --install        # .claude/skills/verirun/SKILL.md
 ```
 
+`--skill` emits the same knowledge as a **Claude Code skill** — YAML frontmatter
+with a `description` that tells Claude when to load it, then a shorter body
+aimed at deciding *which* command to reach for. With `--install` it writes
+`.claude/skills/verirun/SKILL.md` in the repo, and Claude Code loads it on its
+own whenever a task looks like app testing. Re-run it after upgrading verirun;
+the file is generated, not hand-maintained.
+
 Paste the output into `CLAUDE.md`, `.cursorrules`, an `AGENTS.md`, or pipe it
 straight into a prompt. No account needed. The agent then knows to run
 `verirun run <name>`, read exit code + `.verirun/runs/<name>-<newest>/logs.json`,
@@ -364,11 +549,18 @@ it are sent only to the respective provider's own API.
 | `supabase.projectRef` | — | Supabase project ref. Required for Supabase capture. |
 | `supabase.accessToken` | — | Personal access token. Required for Supabase capture. |
 | `supabase.sources` | `postgres_logs`, `edge_logs`, `auth_logs` | Log sources to query, one request each. |
-| `vercel.listenerPort` | `4319` | Port the local Log Drain listener binds during a run. |
-| `vercel.listenerPath` | `/drain` | Path the listener accepts POSTs on. |
-| `vercel.drainSecret` | — | If set, deliveries with a missing or wrong `x-vercel-signature` (HMAC-SHA1 of the body) are rejected. |
-| `vercel.drainGraceMs` | `3000` | How long collection waits after replay for trailing drain batches. |
-| `vercel.project` | — | Keep only deliveries whose `projectName` or `projectId` equals this (a drain carries the whole team's logs). Unset = keep all. If every delivery is filtered out, `run` warns. |
+| `vercel.token` | — | Vercel API token (vercel.com/account/settings/tokens). Its presence is what selects API mode over drain mode. |
+| `vercel.projectId` | — | `prj_…` id of the project to read logs from. Required in API mode. |
+| `vercel.teamId` | — | `team_…` id, when the project belongs to a team. |
+| `vercel.deploymentId` | — | Pin log capture to one deployment instead of the newest ready one. |
+| `vercel.environment` | `production` | Which target to resolve the newest deployment from: `production` or `preview`. |
+| `vercel.readMs` | `8000` | How long to read the runtime-log stream before giving up. |
+| `vercel.tailGraceMs` | `3000` | Extra window past the run's end to keep, for lines Vercel flushes late. |
+| `vercel.listenerPort` | `4319` | *Drain mode.* Port the local Log Drain listener binds during a run. |
+| `vercel.listenerPath` | `/drain` | *Drain mode.* Path the listener accepts POSTs on. |
+| `vercel.drainSecret` | — | *Drain mode.* If set, deliveries with a missing or wrong `x-vercel-signature` (HMAC-SHA1 of the body) are rejected. |
+| `vercel.drainGraceMs` | `3000` | *Drain mode.* How long collection waits after replay for trailing drain batches. |
+| `vercel.project` | — | *Drain mode.* Keep only deliveries whose `projectName` or `projectId` equals this (a drain carries the whole team's logs). Unset = keep all. If every delivery is filtered out, `run` warns. |
 | `railway.token` | — | Railway API token (Account/Workspace, from railway.com/account/tokens). Required for Railway capture. |
 | `railway.deploymentId` | — | Pin log capture to one deployment. Overrides the project/environment/service trio. |
 | `railway.projectId` / `railway.environmentId` / `railway.serviceId` | — | Together, the target for which the newest deployment is resolved each run (so a redeploy doesn't need a config change). |
@@ -379,7 +571,8 @@ it are sent only to the respective provider's own API.
 | Variable | Replaces |
 | --- | --- |
 | `VERIRUN_SUPABASE_ACCESS_TOKEN` | `supabase.accessToken` |
-| `VERIRUN_VERCEL_DRAIN_SECRET` | `vercel.drainSecret` |
+| `VERIRUN_VERCEL_TOKEN` | `vercel.token` |
+| `VERIRUN_VERCEL_DRAIN_SECRET` | `vercel.drainSecret` (drain mode) |
 | `VERIRUN_RAILWAY_TOKEN` | `railway.token` |
 
 ---
@@ -387,8 +580,8 @@ it are sent only to the respective provider's own API.
 ## Log capture
 
 A source appears only when its config block is present. Run `verirun log
-<source>` for guided setup, `verirun log supabase --test` to check the Supabase
-token, and `verirun log vercel --listen` to bring the listener up on its own.
+<source>` for guided setup and `verirun log <source> --test` to check a
+connected one against the last 5 minutes.
 
 **Supabase (pull).** After replay, one query per configured source goes to the
 Management API's `analytics/endpoints/logs.all` endpoint, scoped to the run
@@ -402,17 +595,27 @@ either `deploymentId` or `projectId` + `environmentId` + `serviceId` (the newest
 deployment of that trio is resolved first). Errors are warned about; the run
 continues. Logs are already scoped to one service + environment.
 
-**Vercel (push).** Vercel has no pull API for runtime logs. During a run,
-verirun runs a local HTTP listener on `listenerPort` + `listenerPath`; whatever
-the Log Drain POSTs while it is up is kept. It accepts both JSON-array and
-NDJSON bodies, echoes the `x-vercel-verify` challenge (so Vercel can confirm the
-endpoint), and — if `drainSecret` is set — rejects unsigned or wrongly signed
-deliveries. After replay, collection waits `drainGraceMs` for late batches, then
-stops the listener.
+**Vercel (pull).** After replay, verirun resolves the project's newest ready
+deployment (or `vercel.deploymentId`) and reads
+`/v1/projects/<projectId>/deployments/<deploymentId>/runtime-logs`, keeping the
+lines whose timestamp falls in the run window plus `tailGraceMs`. Needs `token`
+and `projectId`. The endpoint streams and stays open to tail live lines, so the
+read stops once the stream has been quiet for a moment, or after `readMs`.
+Errors are warned about; the run continues. Retention is Vercel's, not ours —
+on Hobby, runtime logs are short-lived, which is fine because collection happens
+seconds after the run.
 
-### One-time Vercel Log Drain setup
+<details>
+<summary><b>Vercel drain mode</b> (only when <code>vercel.token</code> is unset)</summary>
 
-Vercel must be able to reach your listener, so this is manual:
+During a run, verirun runs a local HTTP listener on `listenerPort` +
+`listenerPath`; whatever the Log Drain POSTs while it is up is kept. It accepts
+both JSON-array and NDJSON bodies, echoes the `x-vercel-verify` challenge (so
+Vercel can confirm the endpoint), and — if `drainSecret` is set — rejects
+unsigned or wrongly signed deliveries. After replay, collection waits
+`drainGraceMs` for late batches, then stops the listener.
+
+One-time setup (`verirun log vercel --drain` walks you through it):
 
 1. Expose the listener port to the internet — `ngrok http 4319`, a Cloudflare
    Tunnel, etc. Note the public URL.
@@ -428,3 +631,62 @@ Vercel must be able to reach your listener, so this is manual:
 
 A free ngrok URL changes each session; a reserved hostname is worth it if you
 run this often.
+
+</details>
+
+---
+
+## Changelog
+
+### 0.2.1
+
+Windows support pass. Nothing in the CLI was Unix-only by design, but several
+paths had never been exercised on Windows.
+
+- **Workflow names** reject the two spellings Windows cannot store: a trailing
+  dot (Windows drops it, colliding with the bare name) and a reserved device
+  stem — `con`, `prn`, `aux`, `nul`, `com1`–`com9`, `lpt1`–`lpt9`, at any
+  extension. Enforced on every platform, so a workflow recorded on macOS or
+  Linux stays usable for a teammate on Windows.
+- **Config permissions on Windows** — `.verirun/config.json`, `~/.verirun/` and
+  the files in it are now restricted with an `icacls` ACL granting only the
+  current user. Mode bits are not an access control on Windows, so these held
+  provider tokens and the device token on whatever ACL they inherited. A
+  connect flow that cannot lock the file down now warns instead of implying
+  protection it did not get.
+- **`verirun log supabase`** can find the `supabase` CLI on Windows, where it
+  is a `.cmd` shim that needs a shell to launch. It previously always fell
+  through to the manual project-ref prompt.
+- **Hardware fingerprint** filters Windows virtual adapters (Hyper-V, WSL,
+  VMware, VirtualBox, VPN and loopback), which were being counted as physical
+  and could shift the machine id — consuming an extra seat against the license.
+- Docs: `--user-data-dir` needs an absolute path on Windows, since neither cmd,
+  PowerShell nor verirun expands `~`.
+
+**Not verified on Windows.** These fixes are from reading the code and the
+platform rules, not from a Windows test run. The signed-in Chrome profile path
+in particular is untested there.
+
+### 0.2.0
+
+- **`verirun map`** — static interaction graph of a React/TypeScript app:
+  every page, the interactive elements on it, where they navigate, and the
+  backend calls they make. No browser, no recording. `--json`, `--report`,
+  `--reach`, `--bfs <node> --depth N`. Routes come from react-router
+  `<Routes>` or a Next.js `app/**/page.tsx` tree.
+- **`verirun workflow check`** — validate a workflow file without running it.
+  Together with the selectors `map` emits, a workflow can now be written by
+  hand (or by an agent) instead of recorded.
+- **Vercel logs without a tunnel** — `verirun log vercel` is now a token and a
+  project, pulled from Vercel's runtime-log API. The old Log Drain flow
+  remains under `--drain` and is still used automatically for existing configs.
+- **`verirun agent --skill --install`** — writes `.claude/skills/verirun/SKILL.md`
+  so Claude Code picks the tool up on its own.
+- **Watchable replays** — `--headed` now paces actions (500ms), tunable with
+  `--slow-mo <ms>`.
+- `verirun record`/`run` document how to use a signed-in Chrome profile.
+
+### 0.1.0
+
+- `record`, `run`, `log` (Supabase / Vercel drain / Railway), `agent`, and the
+  account commands `login` / `logout` / `whoami`.