@verirun/cli 0.2.5 → 0.3.0

package/README.md

@@ -4,6 +4,8 @@ Record a browser workflow, replay it, and capture the Supabase, Vercel + Railway
 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.
+And `verirun scan <url>`: a read-only scan of any live site for JS errors,
+failed requests, dead links and missing anchors, with no source or logs needed.
 
 ## Install
 
@@ -30,17 +32,34 @@ your `MANPATH` (`man verirun`) on macOS, Linux, and WSL / Git Bash. Native
 Windows (cmd, PowerShell) has no `man` — use `--help`, or `man -l` the file
 under a POSIX shell. From a `npm link` checkout: `man -l man/verirun.1`.
 
+### Output and exit codes
+
+Output is compact by default: a verdict on the first line (`PASS` / `FAIL`),
+then only the evidence for it. Commands that report something take `--json`
+(one object on one line, with a `schemaVersion`) and `--verbose` for the full
+detail. With `--json`, progress and warnings go to stderr, so stdout is the
+result and nothing else.
+
+| Exit code | Meaning |
+| --- | --- |
+| `0` | The command did what it was asked and the check, if any, passed. |
+| `1` | It ran, and what it checks failed: a replay step (`run`), findings (`scan`), errors in a workflow file (`workflow check`), no usable license (`whoami`), a recording with no actions (`record`). |
+| `2` | It could not run: bad usage, missing setup, no license, an unreachable target. With `--json` the message is also printed on stdout as `{"status":"error","error":{"message":"…"}}`. |
+
+Before 0.3.0 every failure exited `1`. A script that only tests for non-zero is
+unaffected.
+
 ---
 
 ## Account
 
-`record` and `run` need a connected Verirun account. First run on a machine:
+`record`, `run`, `map` and `scan` need a connected Verirun account. First run on a machine:
 
 ```bash
 verirun login
 ```
 
-This prints a short code and a link. Open the link, sign in (a 7 day free trial
+This prints a short code and a link. Open the link, sign in (a 3-day free trial
 starts automatically if you are new), and enter the code. The CLI then holds a
 device token for that machine.
 
@@ -49,6 +68,11 @@ verirun whoami     # account, plan, subscription status
 verirun logout     # disconnect this machine
 ```
 
+`verirun whoami` exits `0` when the gated commands would run and `1` when they
+would not, and `verirun whoami --json` prints the same status as JSON
+(`schemaVersion` 1, with a `licensed` boolean), so a script can check the
+license without parsing text.
+
 | | |
 | --- | --- |
 | `~/.verirun/config.json` | Holds the device token. Per user, not per project. Restricted to your account (0600, or an `icacls` ACL on Windows). |
@@ -114,6 +138,8 @@ Opens a headed browser. Perform the workflow by hand — click, type, navigate.
 | `--user-data-dir <dir>` | Record in a persistent profile directory, so the session is already logged in and stays logged in for later runs. The real browser using that profile must be closed first. |
 | `--test-id-attribute <attr>` | Attribute preferred for test-id selectors. Defaults to `data-testid`; also settable as `testIdAttribute` in config. |
 | `-f, --force` | Overwrite an existing workflow of the same name. Without it, recording onto an existing name errors. |
+| `--json` | Print the result as JSON (`schemaVersion` 1: `name`, `saved`, `steps`, `path`). Everything else goes to stderr. |
+| `--verbose` | List every recorded step after saving. By default `record` prints one line: how many steps it saved and where. |
 
 **Name rules.** `<name>` becomes a filename: letters, digits, dot, dash,
 underscore; must start with a letter or digit; 64 chars max. Two Windows rules
@@ -222,6 +248,26 @@ Replays the recorded steps — headless, in the same browser kind the workflow w
 recorded in — then captures logs for the wall-clock window the replay occupied
 and writes `.verirun/runs/<name>-<timestamp>/logs.json`.
 
+What it prints is a summary, verdict first:
+
+```text
+FAIL  checkout  step 2 failed: click button "Pay now" (2/4 steps replayed, 2.3s)
+  locator.click: Timeout 2000ms exceeded.
+  waiting for locator('role=button[name="Pay now"i]')
+  selector: role=button[name="Pay now"i]
+logs  90 entries, 34 errors, 6 warnings (Vercel 90)
+  x30 vercel/lambda error 500  Error: connect ECONNREFUSED 10.0.3.7:5432
+  x3  vercel/lambda error 500  TypeError: Cannot read properties of undefined (reading 'total')
+  x1  vercel/lambda error 500  Unhandled rejection: payment provider returned 402 for order ord_99812
+full log: .verirun/runs/checkout-2026-11-13T13-10-02-468Z/logs.json
+```
+
+The `logs` lines are the error-level entries (and any carrying an HTTP 5xx
+status) from the run window. Lines that differ only by ids or numbers are
+folded into one with a count, most frequent first, 8 groups at most. A `PASS`
+with error lines under `logs` is the case this tool exists for: the screen said
+done and the backend threw. Everything else is in `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. |
@@ -232,6 +278,24 @@ and writes `.verirun/runs/<name>-<timestamp>/logs.json`.
 | `--cdp <url>` | Attach to a browser already running with remote debugging and drive it. See below. |
 | `--user <id>` | Keep only log entries whose message or raw payload contains this string, case-insensitive — e.g. a user's email. Overrides `config.userFilter`. Recorded in `logs.json` as `"filter": { "user": … }`; `entries` and the per-source counts are post-filter. If everything is filtered out, `run` warns. |
 | `--dialog <answer>` | How to answer a browser dialog opened by a step with no saved `dialog` answer: `accept` (OK, the default) or `dismiss` (Cancel). A step's own `dialog` always wins. |
+| `--json` | Print the summary as one JSON object instead of text (below). `logs.json` is written either way. |
+| `--verbose` | Also print each step as it replays, every distinct error line, and the full error text. |
+
+`run --json` (`schemaVersion` 1) is the summary, not the entries:
+
+```jsonc
+{ "schemaVersion": 1, "tool": "verirun-run", "workflow": "checkout", "status": "ok" | "failed",
+  "durationMs": 2300, "window": { "startedAt": "<ISO>", "endedAt": "<ISO>" },
+  "steps": { "total": 4, "replayed": 2, "failedAt": 2 },
+  "failedStep": { "index": 2, "action": "click", "selector": "…", "description": "…" },  // on failure
+  "error": "<full message>",                                                              // on failure
+  "dialogs": 0,
+  "sources": [ { "id": "vercel", "name": "Vercel", "entries": 90 } ],
+  "logs": { "entries": 90, "problems": 34, "warnings": 6, "groupsOmitted": 0,
+    "groups": [ { "source": "vercel", "stream": "lambda", "level": "error", "status": 500,
+                  "message": "<first line>", "count": 30, "firstAt": "<ISO>", "lastAt": "<ISO>" } ] },
+  "logsPath": ".verirun/runs/checkout-<timestamp>/logs.json" }
+```
 
 **Where the user filter runs.** For **Supabase** it goes into the log query's
 `WHERE` (matched against the rendered message and the JSON of `metadata`), so
@@ -331,8 +395,92 @@ warned about and contributes no entries.
   sub-stream within a source (`lambda`, `edge`, `postgres_logs`, …). `raw` is
   the provider's untouched payload (for Supabase that now includes the row's
   `metadata`, so a `--user` filter can match a nested email field).
-- With no log sources configured, `run` still replays and warns; `entries` is
-  empty.
+- With no log sources configured, `run` still replays and says so in its
+  summary; `entries` is empty.
+- The file's schema is unchanged by the compact summary: `run` prints less, it
+  does not store less.
+
+---
+
+## `verirun scan <url>`
+
+```bash
+verirun scan https://example.com
+verirun scan https://example.com --md      # paste-ready Markdown
+verirun scan https://example.com --json    # the full report
+```
+
+An outside-in scan of a live site. It needs no source code, no recording and
+no log source: point it at a public URL. It crawls same-origin links breadth
+first (20 pages, 2 hops from the start URL by default) in headless Chromium,
+loading up to 4 pages at a time with a 500 ms pause before each request on
+each connection. Pages listed in the site's sitemap (the `Sitemap:` lines in
+`robots.txt`, else `/sitemap.xml`) join the crawl after the start page's own
+links, so a site whose navigation is JavaScript rather than `<a href>` is still
+covered. A request that gets no response at all (a reset connection, not a
+timeout) is asked once more before it is reported. A `429` means the site is
+rate-limiting the scanner, not that the URL is broken, so it is counted rather
+than reported; a link served as a download is treated as a file. It reports,
+per page:
+
+- JavaScript exceptions and console errors
+- failed requests and HTTP 4xx / 5xx responses
+- dead internal links
+- in-page `#anchor` and skip-link targets that do not exist
+- a missing main landmark
+
+Only the site's own problems are kept: its own origin, or an API it calls.
+Analytics, ad, chat-widget and other third-party noise is dropped. The same
+finding on several pages is reported once, with the pages and a count.
+
+```text
+FAIL  https://example.com/  5 findings on 6 pages (browser, 9.4s)
+  JS exception      TypeError: Cannot read properties of undefined (reading 'call')
+                    on /
+  HTTP error        500 GET /api/data
+                    on /
+  dead link         /broken-page returned 404
+                    on /
+  …
+14 internal links checked
+never requested: 2 destructive-looking links, 1 URL disallowed by robots.txt
+```
+
+**It is strictly read-only.**
+
+- It only navigates. It sends `GET` and `HEAD`, never clicks a button, never
+  submits a form.
+- It never requests a link that looks destructive: `logout`, `signout`,
+  `delete`, `remove`, `unsubscribe`, `cancel`, `deactivate`, `revoke` and
+  similar, in the URL or the link text.
+- It identifies itself honestly:
+  `Mozilla/5.0 (compatible; VerirunScan/1.0; +https://get-verirun.duely.in/scanner)`.
+  That page explains the scanner and how to block it.
+- It obeys `robots.txt` (the `VerirunScan` group, else `*`), including
+  `Crawl-delay`; a site that sets one gets one request at a time. If the start
+  URL is disallowed, the scan does not run.
+
+Scan sites you own or have permission to scan.
+
+| Flag | Meaning |
+| --- | --- |
+| `--max-pages <n>` | Stop after this many pages. Default 20. |
+| `--depth <n>` | Follow same-origin links this many hops from the start URL. Default 2. |
+| `--delay <ms>` | Pause before each page load, on each of the 4 parallel connections. Default 500; a larger `Crawl-delay` in robots.txt wins and also drops the scan to one connection. |
+| `--timeout <ms>` | Per-page load timeout. Default 20000. |
+| `--no-browser` | Plain HTTP instead of headless Chromium. Nothing is executed, so JS exceptions and console errors are not checked, and a page that renders entirely client-side shows little. The report says so. |
+| `--json` | The report as one JSON object, `schemaVersion` 1: `status` (`clean` / `findings` / `error`), `summary`, `pages`, and `findings` (`kind`, `message`, `evidence`, `pages`, `count`). |
+| `--md` | The report as Markdown, ready to paste into a reply or an issue. |
+| `--verbose` | Every finding with its evidence, and every page scanned. |
+
+Exit code `0` when nothing was found, `1` when there are findings, `2` when the
+scan could not run (unreachable, disallowed by robots.txt, not HTML).
+
+**What an outside scan cannot see.** It sees what a visitor's browser sees. It
+does not know which backend call a button makes (`verirun map` reads that from
+your source) and it cannot see your backend logs (`verirun run` captures those
+for a recorded flow). It does not log in, so anything behind a login is out of
+reach.
 
 ---
 
@@ -419,7 +567,7 @@ browser, no server, no recording.
 
 ```bash
 verirun map                          # per-page summary
-verirun map --json                   # the whole graph
+verirun map --json                   # the whole graph, on one line (--verbose indents it)
 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
@@ -474,6 +622,9 @@ as `unresolved`, an endpoint passed through a variable as `?`, and Supabase
 tells you what fraction of each page it actually attached, so you can see when
 it is missing something rather than guessing.
 
+`--bfs` and `--reach` also take `--json`, for the same result as one JSON
+object (`schemaVersion` 1).
+
 ---
 
 ## `verirun workflow check <name>`
@@ -538,18 +689,30 @@ confirms it. Don't overwrite a recording with a generated file — use a new nam
 
 ## `verirun agent`
 
-Prints a single self-contained reference for an AI coding agent: every command
-and flag (read from the CLI itself, so it can't drift), the `.verirun/` layout,
-the `logs.json` schema, the recommended record-then-run loop, and a snapshot of
-**this** checkout — resolved repo root, configured log sources, recorded
-workflows, recent runs.
+Prints a compact reference for an AI coding agent: what the tool does, the loop
+to follow, how to read a result, the exit codes, the commands an agent drives
+with their flags (read from the CLI itself, so they can't drift), and a
+snapshot of **this** checkout — resolved repo root, configured log sources,
+recorded workflows, recent runs.
+
+The default is deliberately short, because an agent reads it on every task.
+Three longer sections are printed only when asked for:
+
+| `--topic` | What it covers |
+| --- | --- |
+| `authoring` | Writing a workflow file yourself from `map --json`: format, actions, selectors, dialogs. |
+| `signed-in` | Testing a flow behind a login: the browser profile, Windows paths. |
+| `schemas` | The full shapes of `run --json`, `logs.json` and the scan report. |
 
 ```bash
-verirun agent > .verirun/AGENT.md      # save it as context for your agent
+verirun agent                          # the short reference
+verirun agent --topic authoring        # one section
+verirun agent --full > .verirun/AGENT.md   # everything, saved as context for your agent
 verirun agent --json                   # machine-readable form
 verirun agent --skill --install         # .claude/skills/verirun/SKILL.md
 verirun agent --skill --install cursor  # .cursor/rules/verirun.mdc
-verirun agent --skill --install all     # both
+verirun agent --skill --install codex   # .agents/skills/verirun/SKILL.md + an AGENTS.md section
+verirun agent --skill --install all     # all three
 ```
 
 `--skill` emits the same knowledge as an agent skill — frontmatter with a
@@ -561,14 +724,23 @@ looks:
 |---|---|---|
 | `claude` (default) | `.claude/skills/verirun/SKILL.md` | automatically, when a task looks like app testing |
 | `cursor` | `.cursor/rules/verirun.mdc` | when the task matches its description (an agent-requested rule, not always-on) |
-| `all` | both | |
+| `codex` | `.agents/skills/verirun/SKILL.md`, plus a short section in `AGENTS.md` | the skill when the task matches its description; the `AGENTS.md` section (a pointer to the skill) on every request |
+| `all` | all three | |
+
+Codex reads skills from `.agents/skills/` between the working directory and the
+repo root. `AGENTS.md` is shared with other tools and with people, so verirun only
+writes between `<!-- verirun:start -->` and `<!-- verirun:end -->`: it creates the
+file if there is none, appends the section if there is no marked one, and
+replaces just that section on a re-run. Everything outside the markers is left as
+it was.
 
 Re-run it after upgrading verirun; the file is generated, not hand-maintained.
 
 For any other agent, paste the output into `CLAUDE.md`, 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`,
-and act on `status` / `error` / `entries` without you explaining the tool.
+`verirun run <name>`, branch on the exit code, and act on the `PASS` / `FAIL`
+summary without you explaining the tool, opening `logs.json` only when it needs
+an entry the summary does not show.
 
 ---
 
@@ -715,6 +887,43 @@ run this often.
 
 ## Changelog
 
+### 0.3.0
+
+- **`verirun scan <url>`.** A read-only, outside-in scan of any live site: JS
+  exceptions, console errors, failed requests, HTTP 4xx / 5xx, dead internal
+  links, missing `#anchor` and skip-link targets, a missing main landmark. No
+  source and no logs needed. `--json`, `--md`, `--no-browser`. It never clicks
+  or submits, skips logout / delete style links, sends an honest user agent and
+  obeys `robots.txt`. Needs a connected account, like `record` and `run`.
+  It also crawls the pages a site's sitemap lists, so JavaScript-only
+  navigation is covered, and asks once more before reporting a request that
+  got no response, so one dropped connection does not fail the scan.
+  A rendered page bloated with inline base64 images no longer produces
+  missing-anchor findings past the read limit (data URIs are compacted, and a
+  page still too large skips its absence checks); `429`s and download links
+  are no longer reported as failures.
+- **Compact output.** `run` now prints a verdict first, then the failed step
+  and the error-level log lines from the run window with repeats folded into a
+  count, instead of a step list and a pointer to a file. On the same run, what
+  an agent has to read to learn why it failed drops from the whole `logs.json`
+  to a few lines. `workflow check`, `whoami` and `record` lead with their
+  result too. `--verbose` brings the detail back.
+- **`--json` everywhere it was missing**: `run`, `record`, `whoami`, `map --bfs`
+  and `map --reach`. Each is one object on one line with a `schemaVersion`.
+  `map --json` and `workflow check --json` are now one line too (`map
+  --verbose` indents); `workflow check --json` gained `schemaVersion`.
+- **Exit codes mean something.** `0` ok, `1` the check failed, `2` could not
+  run (usage, setup, license, unreachable). Before, every failure was `1`.
+  `whoami` now exits `1` when the gated commands would not run.
+- **`verirun agent --skill --install codex`.** Writes the skill to
+  `.agents/skills/verirun/SKILL.md`, where Codex looks for skills, and a short
+  marked section in `AGENTS.md` pointing at it, without touching the rest of
+  that file. `--install all` now covers Claude Code, Cursor and Codex.
+- **`verirun agent` is shorter.** The default reference carries what an agent
+  needs on every task; the workflow-authoring, signed-in and schema sections
+  moved behind `--topic`, and `--full` prints everything.
+- `logs.json` and workflow files are unchanged (both still `schemaVersion` 1).
+
 ### 0.2.5
 
 - **`verirun run` answers browser dialogs instead of cancelling them.** With no