@runalabs/rill-cli 0.1.19 → 0.1.21

package/README.md

@@ -1,5 +1,24 @@
 # @runalabs/rill-cli
 
+## Runtime security requirement
+
+Use Node.js **24.22.1 LTS or newer on a patched release line**. The minimum
+supported versions are **22.23.4**, **24.22.1**, and **26.12.1**; Node 23, Node 25,
+and prerelease builds are not supported. These releases address the October 2026
+[eMudhra certificate compromise](https://emudhra.we-have-a-problem.com/).
+
+Rill 0.1.20 checks Node before command actions, authentication, or telemetry.
+An unsupported runtime receives `unsupported_node_version` and an upgrade step.
+`rill doctor` reports that failure without contacting the API or reading saved
+credentials. `rill --help` and `rill --version` remain available.
+
+The CLI uses your installed Node and Chrome/Chromium. Updating Rill alone does
+not replace their certificate stores. Keep Chrome/Chromium updated, and restart
+long-running recorder processes after saving active recordings when updating
+their runtimes. Doctor's browser version check confirms availability, not that
+every certificate revocation is enforced. Rill does not disable TLS validation
+or accept a custom CA workaround in place of the patched Node requirement.
+
 Record a browser flow, keep its video and runtime evidence together, and return an inspectable share link. Use Rill to reproduce a bug, verify a change, or hand a browser run to another developer or agent.
 
 Rill starts a local Chromium recorder. Your browser tool drives the returned CDP endpoint; Rill captures the selected page and uploads the result when you stop.
@@ -8,7 +27,7 @@ Rill starts a local Chromium recorder. Your browser tool drives the returned CDP
 
 ## Cloud agent runs
 
-Invited workspaces can supply a URL and prompt. Cloud runs need Node.js 22+ and a Rill login; Chrome and ffmpeg run on Rill's server.
+Invited workspaces can supply a URL and prompt. Cloud runs need a patched Node.js version listed above and a Rill login; Chrome and ffmpeg run on Rill's server.
 
 ```sh
 rill record https://example.com -p "Open pricing and describe the plans."
@@ -29,7 +48,7 @@ Check `node --version`, `node -p "process.platform"`, and `rill --version` befor
 
 If the CLI is missing, check npm with `npm ping --fetch-timeout=5000 --fetch-retries=0` before installation. See the [canonical skill](https://userill.dev/skill.md) for the bounded Rill connectivity check and Windows Terminal fallback. Report blocked network access instead of repeating installation attempts.
 
-Browser recording runs on macOS, Linux, and Windows. Install Node.js 22+ and Google Chrome or Chromium. Rill encodes recordings remotely by default; local FFmpeg is optional. Chrome stays on your machine and can access localhost. Raw frames upload after recording stops.
+Browser recording runs on macOS, Linux, and Windows. Install a patched Node.js version listed above and up-to-date Google Chrome or Chromium. Rill encodes recordings remotely by default; local FFmpeg is optional. Chrome stays on your machine and can access localhost. Raw frames upload after recording stops.
 
 Then install the scoped package:
 
@@ -68,18 +87,33 @@ The default API is `https://userill.dev`. `RILL_API_URL` changes it; the global
 ## First recording
 
 ```sh
-rill record start --url https://example.com --title "Checkout verification"
-# Save recordingId and connect your browser tool to the returned cdpUrl.
-# Perform the flow in the existing recorded page.
+rill browser connect
+# Open the connection link in Chrome, then choose your app tab in Rill.
+rill --human record start --title "Checkout verification"
+# Perform the steps yourself in that tab; see the agent-operated example below.
 rill record stop <recording-id>
 rill inspect https://userill.dev/s/<share-secret>
 ```
 
-Start returns `recordingId`, `cdpUrl`, `status`, `bodyCaptureEnabled`, and `maxDurationSeconds`. Stop finalizes capture, uploads frames and diagnostics for remote encoding, and waits for playback. Confirm `status: "ready"` and a non-null `shareUrl` before returning the evidence link. Local capture finishing does not establish remote readiness.
+Start returns `recordingId`, `browserAttachment`, `status`, `bodyCaptureEnabled`, and `maxDurationSeconds`. A managed or direct CDP recording also returns `cdpUrl`. Stop finalizes capture, uploads frames and diagnostics for remote encoding, and waits for playback. Confirm `status: "ready"` and a non-null `shareUrl` before returning the evidence link. Local capture finishing does not establish remote readiness.
 
 New browser recordings include a visible cursor and click pulses by default. In Rill Settings → Cursor appearance, workspace members can turn them off or choose an accent color. The CLI reads this preference when starting a recording; it is baked into the video and does not change existing recordings. Use an updated CLI and recorder daemon to capture the overlay.
 
-### Connect Playwright
+### Record the browser you already use
+
+This branch includes a private Chrome pilot; build the CLI from this checkout. The CLI packages its matching extension download. Install it once, run `rill browser connect`, open the returned link in Chrome and click **Connect Chrome**. Rill opens beside your page. Switch to your website and click **Connect this tab**. HTTP and HTTPS sites are supported, including localhost. Setup is remembered and multiple takes reuse the approved tab.
+
+`record start` keeps its normal managed-browser behavior and does not require an extension. Choose `--browser existing` to record the tab connected through Rill for Chrome; that explicit mode fails with connection guidance when no tab is selected. Capture does not click, type, evaluate scripts, intercept navigation, or change the viewport. Sign-in state stays in Chrome; site credentials are never extracted or exported. Request bodies and headers are not captured. Console text is bounded and heuristically redacted; visible page content remains in the video.
+
+For an agent-operated recording, first establish that its existing controller is on the selected target. Inspect `rill --json browser status` and match the returned Chrome tab/target ID with the controller's own selected tab. Then use `rill record start --browser existing --operator agent --controller-target <target-id>`. This matches target identity; it does not certify that an arbitrary agent can drive the browser. If the host cannot expose that identity or control the tab, explain the limitation and offer human operation instead. Rill supplies capture rather than a second controller.
+
+Capture starts only after a frame has been saved. Stopping leaves the tab connected for the next take. A lost connection saves the captured part and marks interruption; upload retry reuses those bytes. New tabs/popups are outside capture and produce a coverage note. DevTools or tab closure can interrupt capture. Inactivity disconnects tab access after an hour; device setup remains saved. Use `rill browser disconnect` to end access. Chrome can still require its own permissions.
+
+Choose a fresh browser explicitly with `rill record start --browser new --url <url>`. Local encoding is available on that managed/CDP path; the Chrome pilot uses remote encoding. Existing CLI limits, workspace access, recording lifecycle, recovery, and player still apply. Native extension/controller coexistence and provider playback must be verified separately from protocol tests.
+
+### Connect Playwright to an explicitly created browser
+
+Use `rill record start --browser new --url <url>` only when the task calls for a fresh browser and your controller supports its connection.
 
 Start also returns `browserAttachment` with the CDP endpoint, protocol, Playwright method, and attachment instructions. Browser tools must explicitly support attaching to that endpoint; Rill does not automatically expose its browser to every tool.
 
@@ -235,7 +269,7 @@ Explicit `--json` or `--pretty` takes precedence over `--human`. Use `--pretty`
 rill whoami
 rill whoami --json
 rill --human doctor
-rill --human record start --url https://example.com --title "Smoke test" --headed
+rill --human record start --browser new --url https://example.com --title "Smoke test" --headed
 rill --human record stop <recording-id>
 rill --human record status <recording-id>
 ```