@verirun/cli 0.1.0 → 0.2.1

package/man/verirun.1

@@ -1,5 +1,5 @@
 .\" Manpage for verirun.
-.TH VERIRUN 1 "2026-09-03" "verirun 0.1.0" "User Commands"
+.TH VERIRUN 1 "2026-09-20" "verirun 0.2.1" "User Commands"
 .\" -------------------------------------------------------------------
 .SH NAME
 verirun \- record a browser workflow, replay it, and capture the backend logs it produced
@@ -23,6 +23,8 @@ verirun \- record a browser workflow, replay it, and capture the backend logs it
 .B verirun run
 .I name
 .RB [ \-\-headed ]
+.RB [ \-\-slow\-mo
+.IR ms ]
 .RB [ \-\-user
 .IR id ]
 .RB [ \-\-channel
@@ -30,6 +32,15 @@ verirun \- record a browser workflow, replay it, and capture the backend logs it
 .RB [ \-\-cdp
 .IR url ]
 .br
+.B verirun map
+.RB [ \-\-json ]
+.RB [ \-\-report ]
+.RB [ \-\-reach ]
+.RB [ \-\-bfs
+.IR node ]
+.RB [ \-\-depth
+.IR n ]
+.br
 .B verirun log
 .RI [ vercel | supabase | railway ]
 .RB [ \-\-reconnect ]
@@ -45,8 +56,14 @@ verirun \- record a browser workflow, replay it, and capture the backend logs it
 .br
 .B verirun whoami
 .br
+.B verirun workflow check
+.I name
+.RB [ \-\-json ]
+.br
 .B verirun agent
 .RB [ \-\-json ]
+.RB [ \-\-skill
+.RB [ \-\-install ]]
 .\" -------------------------------------------------------------------
 .SH DESCRIPTION
 .B verirun
@@ -94,6 +111,26 @@ or
 .B failed
 status. A replay failure still writes the file and sets exit status 1.
 .TP
+.B map
+Read this repository's React/TypeScript source and build an
+.B interaction graph
+\(em one node per page (routes come from
+.B <Routes>
+or a Next.js
+.B app/**/page.tsx
+tree), the interactive elements on it, the pages each one navigates to, and
+the backend calls each one makes. Components a page renders from another file
+are followed, so a page whose real UI lives in a child component is not empty.
+Nothing is executed and no browser is started. With no flag it prints a
+per-page summary;
+.B \-\-json
+emits the whole graph,
+.B \-\-report
+writes it next to a coverage report, and
+.B \-\-bfs
+walks outward from one page. Import aliases are read from
+.IR tsconfig.json .
+.TP
 .BR "log " [ \fIsource\fR ]
 With no source, print which log sources are configured. With
 .BR vercel ,
@@ -102,6 +139,10 @@ or
 .BR railway ,
 run that source's interactive connect flow and write its block of
 .IR .verirun/config.json .
+Each flow is the same shape: paste an API token, pick the project, and the CLI
+checks it by pulling a few recent log lines. Vercel additionally reads
+.I .vercel/project.json
+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;
@@ -114,6 +155,20 @@ Disconnect this machine and revoke its device token on the server.
 .B whoami
 Show the connected account, plan, seat use, and subscription status.
 .TP
+.BR "workflow check " \fIname\fR
+Validate a workflow file without running it: JSON shape, schema version, known
+actions, a
+.I selector
+where the action needs one, and the required
+.I params
+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
+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.
+.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
@@ -130,6 +185,7 @@ for a machine-readable form. Pipe it into your agent's context, e.g.
 .nf
 
 verirun agent > .verirun/AGENT.md
+verirun agent --skill --install   # Claude Code picks it up automatically
 
 .fi
 .RE
@@ -175,6 +231,13 @@ in config.
 Overwrite an existing workflow of the same name.
 .SS run
 .TP
+.BI "\-\-slow\-mo " ms
+Pause this long before each action. Defaults to 500 ms with
+.BR \-\-headed ,
+so a watched run is followable, and to 0 otherwise. Pass
+.B \-\-slow\-mo 0
+to watch at full speed, or a larger value to follow a fast form more easily.
+.TP
 .B \-\-headed
 Show the browser window instead of running headless.
 .TP
@@ -213,12 +276,16 @@ identifier; for Vercel it is applied after delivery.
 Re-run the connect flow and replace what was saved. Any source.
 .TP
 .B \-\-test
-.RB ( supabase " / " railway )
-Query the last 5 minutes and print the row count per source, or the error.
-Non-zero exit if it errored.
+Query the last 5 minutes and print what came back, or the error. Non-zero exit
+if it errored.
 .TP
-.B \-\-listen
+.B \-\-drain
 .RB ( vercel )
+Set up the old push-based Log Drain \(em a tunnel plus a local listener \(em
+instead of the API. Only needed if the runtime-log API is unavailable to you.
+.TP
+.B \-\-listen
+.RB ( vercel ", drain mode)"
 Start the Log Drain listener now and keep it running until interrupted,
 printing each delivery. Use it for the dashboard's endpoint-verification step
 and for live tailing.
@@ -233,10 +300,82 @@ Account server base URL. Default
 .IR https://get\-verirun.duely.in .
 Also settable with
 .BR VERIRUN_LICENSE_SERVER .
+.SS "map"
+.TP
+.BR \-d ", " \-\-dir " " \fIdir\fR
+Analyze this directory instead of the repo root.
+.TP
+.B \-\-json
+Print the full interaction graph as JSON on stdout.
+.TP
+.B \-\-report
+Write
+.I interaction-tree.json
+and
+.I coverage.md
+to
+.I .verirun/map
+(or
+.BR \-\-out ).
+.TP
+.BI "\-\-out " dir
+Output directory for
+.BR \-\-report .
+.TP
+.B \-\-reach
+Print a per-route table of reachable versus attached elements \(em how much of
+each page's surface the graph actually captured.
+.TP
+.BI "\-\-bfs " node
+Walk the graph breadth-first from a node: a route path
+.RB ( /account ),
+a page id
+.RB ( page:/account ),
+or a page component name. Each node is reported once, at its shortest
+distance.
+.TP
+.BI "\-\-depth " n
+Steps to follow for
+.BR \-\-bfs .
+Default 2.
+.TP
+.BI "\-\-kind " "nav|effect"
+Follow only navigation edges, or only backend-effect edges.
+.TP
+.BI "\-\-alias " "prefix=dir"
+Extra import alias, e.g.
+.BR @/=src .
+Repeatable. Aliases in
+.I tsconfig.json
+are picked up automatically.
+.TP
+.B \-\-no\-follow\-children
+Do not follow child components out of a page file \(em only that file's own
+elements.
+.TP
+.BI "\-\-app\-file " file
+The file declaring
+.B <Routes>
+for a react-router app. Auto-detected by default.
+.SS "workflow"
+.TP
+.B \-\-json
+Emit the findings as JSON instead of a report.
 .SS "agent"
 .TP
 .B \-\-json
 Emit JSON instead of Markdown.
+.TP
+.B \-\-skill
+Emit the reference as a Claude Code skill file (YAML frontmatter plus body)
+rather than plain Markdown.
+.TP
+.B \-\-install
+With
+.BR \-\-skill ,
+write it to
+.I .claude/skills/verirun/SKILL.md
+in the repo instead of standard output.
 .\" -------------------------------------------------------------------
 .SH FILES
 .TP
@@ -244,7 +383,10 @@ Emit JSON instead of Markdown.
 Per-project config: log sources, the user filter, the test-id attribute.
 Written by the
 .B verirun log
-connect flows (mode 0600); read otherwise.
+connect flows, restricted to the current user \(em mode 0600 on macOS and Linux,
+an
+.BR icacls (1)
+ACL on Windows, where mode bits are not an access control. Read otherwise.
 .TP
 .I <repo>/.verirun/workflows/<name>.json
 A recorded workflow.
@@ -261,6 +403,12 @@ and the license server URL.
 .TP
 .I ~/.verirun/state.json
 The last server-signed license lease plus a local tamper check.
+.PP
+The
+.I ~/.verirun
+directory and both files in it are restricted to the current user by the same
+rule as
+.IR .verirun/config.json .
 .\" -------------------------------------------------------------------
 .SH ENVIRONMENT
 .TP
@@ -276,6 +424,11 @@ Supabase Management API token; overrides
 .B supabase.accessToken
 and is never written to the config file.
 .TP
+.B VERIRUN_VERCEL_TOKEN
+Vercel API token, replacing
+.IR vercel.token .
+Create one at vercel.com/account/settings/tokens.
+.TP
 .B VERIRUN_VERCEL_DRAIN_SECRET
 Vercel Log Drain signing secret; overrides
 .BR vercel.drainSecret .
@@ -352,6 +505,41 @@ use
 and
 .B verirun \fIcommand\fB \-\-help
 there, or read this page under WSL, Git Bash, or MSYS2.
+.PP
+A
+.B \-\-user\-data\-dir
+profile must be created by hand and signed in there once, because identity
+providers refuse an automation\-launched browser. On macOS and Linux launch
+Chrome with
+.B \-\-password\-store=basic
+(plus
+.B \-\-use\-mock\-keychain
+on macOS), which is what Playwright itself uses \(em without them the
+keyring\-encrypted cookies cannot be decrypted and the run silently starts
+logged out. Both switches are Unix\-only and are ignored on Windows; there,
+create the profile as the same Windows user that runs
+.BR verirun .
+The Windows path is untested. On every platform, use a dedicated profile rather
+than your everyday one.
+.PP
+.B \-\-user\-data\-dir
+is passed through to Playwright unchanged \(em
+.B verirun
+never expands a leading
+.BR ~ .
+On macOS and Linux the shell expands it first; cmd and PowerShell do not, so on
+Windows give an absolute path or you will get a directory named
+.BR ~ .
+.PP
+A workflow name becomes a filename, so two Windows restrictions are enforced on
+every platform: a name may not end in a dot (Windows drops it, colliding with
+the bare name), and its stem may not be a reserved device name
+.RB ( con ", " prn ", " aux ", " nul ", " com1
+to
+.BR com9 ", " lpt1
+to
+.BR lpt9 )
+at any extension. An invalid name is an error, never silently rewritten.
 .\" -------------------------------------------------------------------
 .SH SEE ALSO
 Full documentation in the bundled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verirun/cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "publishConfig": {
     "access": "public"
   },
@@ -14,6 +14,7 @@
   "files": [
     "dist/cli.js",
     "dist/gate.mjs",
+    "dist/graph.mjs",
     "man/verirun.1",
     "README.md",
     "LICENSE"
@@ -27,16 +28,22 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepack": "npm run build",
     "postinstall": "playwright install chromium",
-    "verirun": "node dist/cli.js"
+    "verirun": "node dist/cli.js",
+    "test": "node --import tsx --test \"test/**/*.test.ts\""
   },
   "dependencies": {
+    "@babel/parser": "^7.26.3",
+    "@babel/traverse": "^7.26.4",
+    "@babel/types": "^7.26.3",
     "commander": "^12.1.0",
     "playwright": "~1.62.0"
   },
   "devDependencies": {
+    "@types/babel__traverse": "^7.20.6",
     "@types/node": "^22.10.0",
     "esbuild": "^0.28.2",
     "javascript-obfuscator": "^5.6.0",
+    "tsx": "^4.19.2",
     "typescript": "^5.7.0"
   }
 }