@verirun/cli 0.2.4 → 0.3.0

package/man/verirun.1

@@ -1,8 +1,8 @@
 .\" Manpage for verirun.
-.TH VERIRUN 1 "2026-09-21" "verirun 0.2.4" "User Commands"
+.TH VERIRUN 1 "2026-11-15" "verirun 0.3.0" "User Commands"
 .\" -------------------------------------------------------------------
 .SH NAME
-verirun \- record a browser workflow, replay it, and capture the backend logs it produced
+verirun \- record a browser workflow, replay it, capture the backend logs it produced, and scan a live site
 .\" -------------------------------------------------------------------
 .SH SYNOPSIS
 .B verirun
@@ -31,6 +31,22 @@ verirun \- record a browser workflow, replay it, and capture the backend logs it
 .IR channel ]
 .RB [ \-\-cdp
 .IR url ]
+.RB [ \-\-dialog
+.IR answer ]
+.RB [ \-\-json ]
+.RB [ \-\-verbose ]
+.br
+.B verirun scan
+.I url
+.RB [ \-\-max\-pages
+.IR n ]
+.RB [ \-\-depth
+.IR n ]
+.RB [ \-\-delay
+.IR ms ]
+.RB [ \-\-no\-browser ]
+.RB [ \-\-json | \-\-md ]
+.RB [ \-\-verbose ]
 .br
 .B verirun map
 .RB [ \-\-json ]
@@ -55,12 +71,16 @@ verirun \- record a browser workflow, replay it, and capture the backend logs it
 .B verirun logout
 .br
 .B verirun whoami
+.RB [ \-\-json ]
 .br
 .B verirun workflow check
 .I name
 .RB [ \-\-json ]
 .br
 .B verirun agent
+.RB [ \-\-topic
+.IR name ]
+.RB [ \-\-full ]
 .RB [ \-\-json ]
 .RB [ \-\-skill
 .RB [ \-\-install ]]
@@ -83,11 +103,22 @@ or failing that a
 .IR package.json ,
 otherwise the current directory).
 .PP
-.BR record " and " run
+.BR record ", " run ", " map " and " scan
 require a connected Verirun account (see
 .BR login ).
-.BR "\-\-help" ", " "\-\-version" ", " "verirun log" ", and " "verirun agent"
+.BR "\-\-help" ", " "\-\-version" ", " "verirun log" ", " "verirun workflow check" ", and " "verirun agent"
 do not.
+.PP
+Output is compact by default: a verdict on the first line, then only the
+evidence for it. Commands that report something take
+.B \-\-json
+(one object on one line, carrying a
+.BR schemaVersion )
+and
+.B \-\-verbose
+for the full detail. See
+.B EXIT STATUS
+for the codes a script or an agent can branch on.
 .\" -------------------------------------------------------------------
 .SH COMMANDS
 .TP
@@ -98,7 +129,12 @@ click, type, navigate \(em then
 to save the sequence to
 .IR .verirun/workflows/ name .json .
 Closing without doing anything saves nothing. A text field is only captured
-when it loses focus, so tab out of the last field before closing.
+when it loses focus, so tab out of the last field before closing. Answer any
+alert, confirm or prompt dialog as usual; afterwards
+.B record
+asks, for each step that opened one, whether you pressed OK or Cancel, and
+saves the answer on the step as
+.BR \(dqdialog\(dq .
 .TP
 .BI "run " name
 Replay a recorded workflow headless (in the browser kind it was recorded in),
@@ -110,6 +146,45 @@ with the merged, time-sorted entries, a per-source summary, and an
 or
 .B failed
 status. A replay failure still writes the file and sets exit status 1.
+.IP
+It prints a short summary:
+.B PASS
+or
+.B FAIL
+first, on a failure the step that failed with its error and selector, then the
+error-level log entries (and any carrying an HTTP 5xx status) from the run
+window, with repeated lines folded into one and a count. The full entries stay
+in
+.IR logs.json ,
+whose path is the last line.
+.TP
+.BI "scan " url
+Crawl a live site from outside and report what is broken on it. No source, no
+recording and no log source is needed. It follows same-origin links breadth
+first (20 pages and 2 hops by default, up to 4 pages at a time with a pause
+before each request), plus the same-origin pages the site's sitemap lists
+(robots.txt
+.B Sitemap:
+lines, else /sitemap.xml). A request that gets no response is retried once
+before it is reported; a 429 (rate limiting) is counted, not reported. It
+reports, per page: JavaScript exceptions, console errors, failed requests and HTTP 4xx /
+5xx responses that belong to the site (its own origin, or an API it calls;
+analytics, ad and chat-widget traffic is dropped), dead internal links,
+in-page
+.B #anchor
+and skip-link targets that do not exist, and a missing main landmark.
+.IP
+The scan is strictly read-only. It only navigates: it sends GET and HEAD
+requests, never clicks a button or submits a form, and never requests a link
+that looks destructive (logout, sign out, delete, unsubscribe and similar). It
+identifies itself as
+.B VerirunScan/1.0
+with a URL describing the scanner, and obeys
+.IR robots.txt ,
+including
+.BR Crawl\-delay .
+Exit status 0 when nothing was found, 1 when there are findings, 2 when the
+scan could not run (unreachable, disallowed by robots.txt, not HTML).
 .TP
 .B map
 Read this repository's React/TypeScript source and build an
@@ -130,6 +205,15 @@ writes it next to a coverage report, and
 .B \-\-bfs
 walks outward from one page. Import aliases are read from
 .IR tsconfig.json .
+An element whose handler calls the native
+.BR alert() ", " confirm() " or " prompt()
+carries a
+.B dialogs
+list in the graph, printed under its edge by
+.B \-\-bfs
+and listed in the coverage report;
+.B gates
+marks one whose answer changes what the click does.
 .TP
 .BR "log " [ \fIsource\fR ]
 With no source, print which log sources are configured. With
@@ -146,14 +230,16 @@ when the repo is linked, in which case it asks nothing after the token.
 .TP
 .B login
 Connect this machine to your Verirun account. Prints a short code and a link;
-open the link, sign in (a 7 day trial starts automatically if you are new),
-and enter the code. A 7 day trial needs no card.
+open the link, sign in (a 3-day trial starts automatically if you are new),
+and enter the code. The trial needs no card.
 .TP
 .B logout
 Disconnect this machine and revoke its device token on the server.
 .TP
 .B whoami
-Show the connected account, plan, seat use, and subscription status.
+Show the connected account, plan, seat use, and subscription status. Exits 0
+when the gated commands would run and 1 when they would not, so a script can
+check the license without parsing anything.
 .TP
 .BR "workflow check " \fIname\fR
 Validate a workflow file without running it: JSON shape, schema version, known
@@ -164,30 +250,49 @@ where the action needs one, and the required
 per action. It also warns when a
 .B navigate
 appears after the first step: walking the app by URL skips the UI, so a dead
-link or a button that stopped submitting still passes. Static only \(em it
+link or a button that stopped submitting still passes. When
+.I .verirun/map/interaction-tree.json
+exists (from
+.BR "map \-\-report" ),
+it also warns about a step that clicks an element known to open a browser
+dialog but has no
+.B dialog
+answer. Static only \(em it
 never opens a browser, so it cannot tell you a selector matches the live page. Use it after writing a workflow by hand or from
 .BR "verirun map" ,
-then run it for the real answer. Non-zero exit if anything is an error.
+then run it for the real answer. Exit status 1 if anything is an error.
 .TP
 .B agent
-Print a compact, self-contained reference for an AI coding agent: every
-command and flag (read from the CLI itself, so it never drifts), the
-.B .verirun/
-layout, the
-.I logs.json
-schema, and the recommended record-then-run loop. It also reports what
+Print a compact reference for an AI coding agent: what the tool does, the
+loop to follow, how to read a result, the exit codes, and the commands an
+agent drives with their flags (read from the CLI itself, so they never
+drift). It also reports what
 .B this
 checkout has \(em resolved repo root, configured log sources, recorded
-workflows, recent runs. Markdown by default;
+workflows, recent runs. Three longer sections are left out of the default and
+printed on request with
+.BR \-\-topic :
+.B authoring
+(writing a workflow file from the map),
+.B signed\-in
+(running behind a login) and
+.B schemas
+(the
+.BR "run \-\-json" ,
+.I logs.json
+and scan report shapes).
+.B \-\-full
+prints everything in one document. Markdown by default;
 .B \-\-json
 for a machine-readable form. Pipe it into your agent's context, e.g.
 .RS
 .nf
 
-verirun agent > .verirun/AGENT.md
+verirun agent --full > .verirun/AGENT.md
 verirun agent --skill --install          # Claude Code: .claude/skills/verirun/SKILL.md
 verirun agent --skill --install cursor   # Cursor: .cursor/rules/verirun.mdc
-verirun agent --skill --install all      # both
+verirun agent --skill --install codex    # Codex: .agents/skills/verirun/SKILL.md + AGENTS.md section
+verirun agent --skill --install all      # all three
 
 .fi
 .RE
@@ -272,6 +377,89 @@ as
 .RB \(dq filter \(dq .
 For Supabase and Railway the filter is pushed to the query when it is a plain
 identifier; for Vercel it is applied after delivery.
+.TP
+.BI \-\-dialog " answer"
+How to answer a browser dialog (alert, confirm, prompt, beforeunload) opened by
+a step that has no saved
+.B dialog
+answer:
+.B accept
+(OK, the default) or
+.B dismiss
+(Cancel). A step's own answer always wins. Every dialog answered is listed in
+.I logs.json
+under
+.RB \(dq dialogs \(dq .
+.TP
+.B \-\-json
+Print the run summary as one JSON object (schemaVersion 1) instead of text:
+.BR status ,
+.BR steps ,
+.B failedStep
+and
+.B error
+on a failure, per-source counts, and
+.B logs
+with the error-level entries grouped and counted. Progress goes to stderr. The
+.I logs.json
+file is written either way and its schema is unchanged.
+.TP
+.B \-\-verbose
+Also print each step as it replays, every distinct error line (the default
+shows the 8 most frequent), and the full error text.
+.SS "scan"
+.TP
+.BI "\-\-max\-pages " n
+Stop after this many pages. Default 20.
+.TP
+.BI "\-\-depth " n
+Follow same-origin links this many hops from the start URL. Default 2.
+.TP
+.BI "\-\-delay " ms
+Pause before each page load, on each of the 4 parallel connections. Default
+500. A larger
+.B Crawl\-delay
+in robots.txt wins, and also drops the scan to one connection.
+.TP
+.BI "\-\-timeout " ms
+Per-page load timeout. Default 20000.
+.TP
+.B \-\-no\-browser
+Use plain HTTP instead of headless Chromium. Nothing is executed, so
+JavaScript exceptions and console errors are not checked, and a page that
+renders entirely client-side shows little; the report says so.
+.TP
+.B \-\-json
+Print the report as one JSON object (schemaVersion 1):
+.BR status ,
+.BR summary ,
+.B pages
+and
+.BR findings ,
+each finding with its
+.BR kind ,
+.BR message ,
+.BR evidence ,
+the pages it was seen on and a count.
+.TP
+.B \-\-md
+Print the report as Markdown, ready to paste into a reply or an issue.
+.TP
+.B \-\-verbose
+List every finding with its evidence, and every page scanned.
+.SS "record"
+.TP
+.B \-\-json
+Print the result as JSON (schemaVersion 1); everything else goes to stderr.
+.TP
+.B \-\-verbose
+List every recorded step after saving.
+.SS "whoami"
+.TP
+.B \-\-json
+Print the status as JSON (schemaVersion 1), including a
+.B licensed
+boolean.
 .SS "log"
 .TP
 .B \-\-reconnect
@@ -308,7 +496,16 @@ Also settable with
 Analyze this directory instead of the repo root.
 .TP
 .B \-\-json
-Print the full interaction graph as JSON on stdout.
+Print the interaction graph as JSON on stdout, on one line. With
+.B \-\-bfs
+or
+.B \-\-reach
+it prints that result as JSON instead.
+.TP
+.B \-\-verbose
+Indent the
+.B \-\-json
+output.
 .TP
 .B \-\-report
 Write
@@ -365,19 +562,45 @@ for a react-router app. Auto-detected by default.
 Emit the findings as JSON instead of a report.
 .SS "agent"
 .TP
+.BI "\-\-topic " name
+Print one on-request section:
+.BR authoring ,
+.B signed\-in
+or
+.BR schemas .
+.TP
+.B \-\-full
+Print the reference with every on-request section included.
+.TP
 .B \-\-json
 Emit JSON instead of Markdown.
 .TP
 .B \-\-skill
-Emit the reference as a Claude Code skill file (YAML frontmatter plus body)
+Emit the reference as an agent skill file (YAML frontmatter plus body)
 rather than plain Markdown.
 .TP
-.B \-\-install
+.BI "\-\-install " "\fR[\fPagent\fR]\fP"
 With
 .BR \-\-skill ,
-write it to
-.I .claude/skills/verirun/SKILL.md
-in the repo instead of standard output.
+write it into the repo where the agent looks instead of standard output.
+.I agent
+is
+.B claude
+(the default):
+.IR .claude/skills/verirun/SKILL.md ;
+.BR cursor :
+.IR .cursor/rules/verirun.mdc ;
+.BR codex :
+.I .agents/skills/verirun/SKILL.md
+plus a section of
+.I AGENTS.md
+between
+.B "<!\-\- verirun:start \-\->"
+and
+.B "<!\-\- verirun:end \-\->"
+(the rest of that file is left alone, and a re-run replaces only that section); or
+.B all
+for every one.
 .\" -------------------------------------------------------------------
 .SH FILES
 .TP
@@ -492,23 +715,66 @@ verirun log            # what is configured
 .fi
 .RE
 .PP
+Scan a deployed site and paste the result into an issue:
+.PP
+.RS
+.nf
+verirun scan https://example.com \-\-md
+.fi
+.RE
+.PP
+Branch on a run in a script, reading the summary as JSON:
+.PP
+.RS
+.nf
+verirun run checkout \-\-json > run.json || echo "failed with $?"
+.fi
+.RE
+.PP
 Hand your AI coding agent the full command + layout reference:
 .PP
 .RS
 .nf
-verirun agent > .verirun/AGENT.md
+verirun agent \-\-full > .verirun/AGENT.md
 .fi
 .RE
 .\" -------------------------------------------------------------------
 .SH EXIT STATUS
 .TP
 .B 0
-Success.
+The command did what it was asked and the check, if any, passed.
 .TP
 .B 1
-A replay step failed, a subscription check failed, or the command errored.
+It ran, and what it checks failed: a replay step
+.RB ( run ),
+findings
+.RB ( scan ),
+errors in a workflow file
+.RB ( "workflow check" ),
+no usable license
+.RB ( whoami ),
+or a recording with no actions
+.RB ( record ).
+.TP
+.B 2
+It could not run: bad usage, missing setup (no such workflow, a log source
+that failed to start), no license, or an unreachable target. With
+.B \-\-json
+the message is also printed on stdout as
+.BR {"status":"error","error":{"message":...}} .
+.PP
+Before 0.3.0 every failure exited 1. A script that only tests for non-zero is
+unaffected.
 .\" -------------------------------------------------------------------
 .SH NOTES
+A workflow step can carry
+.B \(dqdialog\(dq: { \(dqaction\(dq: \(dqaccept\(dq | \(dqdismiss\(dq, \(dqpromptText\(dq: \(dq...\(dq }
+to fix how replay answers a dialog that step opens.
+.B promptText
+is what an accepted
+.B prompt()
+receives; without it, the prompt's default value is submitted.
+.PP
 Native Windows (cmd, PowerShell) has no
 .BR man ;
 use

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verirun/cli",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public"
   },