@verirun/cli 0.1.0 → 0.2.0

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
 
@@ -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.
 
 ---
 
@@ -128,6 +131,34 @@ 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"
+```
+
+Create that profile once, by hand, and sign in there — identity providers block
+sign-in in an automation-launched browser:
+
+```bash
+google-chrome --user-data-dir="$HOME/.verirun-profile" --password-store=basic
+```
+
+`--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. That is also why you can't reuse your everyday Chrome profile, whose
+cookies are keyring-encrypted; 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 +171,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 +297,148 @@ 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_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 +453,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 +524,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 +546,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 +555,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 +570,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 +606,33 @@ 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.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`.