rpc-agent 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.5.0
+
+Ship-check: `rpc check <url>` audits a page before launch, from the CLI, in
+CI or through MCP.
+
+### Added
+
+- `rpc check <url>` runs on a phone and a desktop width by default (`-d`
+  to change) and reports findings with an id, severity (`error`, `warn`,
+  `info`), message, selector or URL, devices and a fix. Checks:
+  - Basics: HTTP status, mixed content, uncaught exceptions, console errors,
+    `theme-color`.
+  - Meta and social: title, description, canonical, `lang`, viewport (and
+    zoom blocking), favicon, apple-touch-icon, `og:title`,
+    `og:description`, `og:image`, `og:url`, `twitter:card`. `og:image` is
+    fetched for its status, content type and pixel size.
+  - Layout shift: CLS (largest session window) after load and one scroll,
+    with the elements that moved. Warn above 0.1, error above 0.25.
+  - Unlabelled controls: buttons, links and `[role=button]` with no
+    accessible name, images without `alt`, form fields without a label.
+  - Fonts: missing or `block` `font-display`, above-the-fold fonts that
+    aren't preloaded, preloads without `crossorigin`, unused preloads,
+    font files that fail.
+  - Mobile viewport (phones): `100vh`, sideways scroll with the elements
+    that cause it, tap targets under 44x44, text fields under 16px.
+- Exit code 1 on errors; `--fail-on warn` fails on warnings too.
+  `--json` prints a versioned report (`schema: 1`, documented in the
+  README). `--shots` saves PNGs of the elements behind layout-shift and
+  overflow findings.
+- Auth works as for `rpc shot`: `--cookie`, `--header`,
+  `--storage-state`, `--allow-origin`, saved `rpc login` sessions and
+  `AUTH_REQUIRED` on a redirect to sign-in.
+- MCP `check` tool with the same options and the `screenshot` tool's auth
+  params. It returns a short text summary and the JSON report.
+
+### Unchanged
+
+- `rpc shot`, its output and the MCP `screenshot` tool. The MCP tool list
+  gains `check`.
+
 ## 0.4.0
 
 Authenticated captures: screenshot logged-in pages without a hand-written

package/README.md

@@ -63,6 +63,7 @@ these docs say `rpc`, or `pnpm rpc` from inside the repo.
 ```sh
 rpc                    # interactive: pick a URL, devices and options
 rpc shot <url> [options]
+rpc check <url> [options]  # pre-launch audit, see Ship-check below
 rpc login <url> [--form]   # sign in once; later shots of that origin use the session
 rpc sessions [list|clear [origin]]
 rpc devices [--json]
@@ -299,9 +300,231 @@ rpc shot localhost:3000/app --storage-state auth.json
 - **Use a test account.** Sign in as a user whose data you're happy for
   screenshots (and the agent reading them) to see.
 
+## Ship-check
+
+`rpc check <url>` audits one page before you call it done. It loads the page
+on a phone and a desktop width, the way `rpc shot` does, and lists what's
+wrong: missing or broken social tags, layout shift, buttons a screen reader
+can't name, fonts that hide text while they load, and the mobile viewport
+bugs that only show up on a phone.
+
+```sh
+rpc check localhost:3000
+rpc check localhost:3000 --fail-on warn --json     # CI
+rpc check example.com/pricing -d pixel,iphone-se,desktop --shots
+```
+
+<img alt="rpc check in a terminal on turbo-start-paystack.vercel.app: both devices load with HTTP 200 and CLS 0.000, then a Meta and social box (no canonical link, no og:url) and a Mobile viewport box (16 of 54 tap targets under 44x44 px, with selectors and sizes), each finding with a fix, and the line 0 errors, 3 warnings, 0 info" src="https://raw.githubusercontent.com/akintola4/rpc-agent/main/docs/media/terminal-check.png" width="720">
+
+URLs, devices and auth work as in `rpc shot`: `localhost:3000` needs no
+scheme, `-d` takes ids or aliases (default `iphone-15-pro,desktop-1440`),
+and `--cookie`, `--header`, `--storage-state` and the session saved by
+`rpc login` all apply. A page that redirects to a login URL fails with
+`AUTH_REQUIRED`. Each run checks one URL. It isn't Lighthouse: CLS is the
+only performance number it reports.
+
+| Option | Meaning |
+| --- | --- |
+| `-d, --devices <ids>` | Devices to check on. The mobile checks run on phones only |
+| `--fail-on <level>` | `error` (default) exits 1 on errors; `warn` exits 1 on warnings too |
+| `--shots` | Save PNGs of the elements behind layout-shift and overflow findings into `--out` |
+| `-o, --out <dir>` | Where `--shots` writes. Default `./.rpc-shots` |
+| `--json` | Print the report as JSON (see below) |
+| `--wait-for`, `--wait`, `--timeout`, `--color-scheme` | As in `rpc shot` |
+| `--cookie`, `--header`, `--storage-state`, `--no-session`, `--allow-origin` | As in `rpc shot` |
+
+The exit code is 0 when there are no errors (with `--fail-on warn`, no
+warnings either), 1 otherwise and 2 for a usage error.
+
+### How a check runs
+
+Each device gets a fresh browser context, the same one `rpc shot` uses.
+Before the page's own scripts run, rpc installs a `PerformanceObserver` for
+`layout-shift`. It loads the page and waits for network idle (up to 10 s),
+web fonts and pending images. Then it waits a fixed 500 ms, scrolls down one
+viewport and back with a 300 ms pause each way, and reads the page. Because
+the sequence is fixed, CLS comes out the same on every run; the tests check
+the same page twice and allow 0.005 of difference.
+
+When a finding is identical on several devices it's reported once, with
+every device listed, so a missing `lang` appears one time, not two.
+
+### What it checks
+
+Severity decides the exit code. `error` fails the run, `warn` fails it only
+with `--fail-on warn`, and `info` never does.
+
+#### Basics
+
+| id | Severity | When | Fix |
+| --- | --- | --- | --- |
+| `http-status` | error | The page answered 400 or above | Serve it with a 200 |
+| `page-load-failed`, `auth-required` | error | The page didn't load on a device (DNS, refused, timeout) or landed on a login page | The error's own hint, e.g. ``run `rpc login <origin>` `` |
+| `mixed-content` | error (warn if the browser upgraded every request) | `http://` requests on an https page | Load everything over https |
+| `uncaught-exception` | error | Exceptions thrown during load, first three listed | Fix the first one; the rest often follow from it |
+| `console-errors` | warn | `console.error` during load: the count and the first three | Fix or silence them |
+| `theme-color-missing` | info | No `<meta name="theme-color">` | Add one to tint the mobile browser bar |
+
+#### Meta and social
+
+| id | Severity | When | Fix |
+| --- | --- | --- | --- |
+| `title-missing`, `title-long` | error, warn | No `<title>`, or one over 60 characters | 50 to 60 characters, key words first |
+| `description-missing`, `description-long` | warn, info | No meta description, or one over 160 characters | One or two sentences |
+| `canonical-missing` | warn | No `<link rel="canonical">` | The absolute URL to index |
+| `lang-missing` | error | No `lang` on `<html>` | `<html lang="en">` |
+| `viewport-missing`, `viewport-no-zoom` | error | No viewport meta, or one with `user-scalable=no` or `maximum-scale` under 2 | `width=device-width, initial-scale=1` and nothing that blocks zoom |
+| `favicon-missing` | warn | No `<link rel="icon">`, and `/favicon.ico` doesn't load | Add an icon link |
+| `apple-touch-icon-missing` | info | No `apple-touch-icon` | A 180x180 PNG |
+| `og-title-missing`, `og-description-missing`, `og-image-missing`, `og-url-missing` | warn | That Open Graph tag is absent | Add it; link previews read it |
+| `twitter-card-missing` | warn | No `twitter:card` | `summary_large_image` |
+| `og-image-relative` | warn | `og:image` isn't an absolute URL | Make it absolute; most scrapers don't resolve relative URLs |
+| `og-image-broken`, `og-image-not-image` | error | `og:image` doesn't return 200, or isn't served as an image | Point it at the image file |
+| `og-image-small`, `og-image-ratio` | warn, info | Smaller than 600x315, or not the 1.91:1 shape of 1200x630 | Export it at 1200x630 |
+
+rpc fetches `og:image` once per run and reads its pixel size from the file
+header (PNG, JPEG, GIF or WebP). The result is in the report's `ogImage`.
+
+#### Layout shift
+
+| id | Severity | When | Fix |
+| --- | --- | --- | --- |
+| `layout-shift` | error above 0.25, warn above 0.1, info above 0 | CLS for the load and the scroll, with the three elements that moved most and each one's share | Reserve space for late content: `width`/`height` or `aspect-ratio` on media, `min-height` on async sections, nothing inserted above what's on screen |
+
+The score is computed the way Chrome computes it: the largest session
+window, meaning shifts less than 1 s apart and at most 5 s in total. Chrome
+marks shifts that follow input as `hadRecentInput`, including any in the
+first 500 ms after navigation, and those don't count. Totals under 0.001
+count as zero. Each device's score is also in `devices[].cls`.
+
+#### Unlabelled controls
+
+| id | Severity | When | Fix |
+| --- | --- | --- | --- |
+| `button-no-name`, `link-no-name` | error | A button, link or `[role=button]` with no accessible name, such as an icon-only button | `aria-label`, visually hidden text, or alt text on the image inside |
+| `img-no-alt` | error | An `<img>` with no `alt` attribute (`alt=""` is fine) | Describe the image, or `alt=""` if it's decorative |
+| `field-no-label` | error | An input, select or textarea with no label | `<label for>`, a wrapping `<label>`, or `aria-label` |
+| `field-placeholder-only` | warn | A field labelled only by its placeholder | Add a visible label |
+
+rpc works out accessible names in the page from `aria-labelledby`,
+`aria-label`, `<label>`, `alt`, the text inside (minus anything
+`aria-hidden`), an SVG `<title>` and `title`. It skips elements assistive
+tech can't reach: `display: none`, `visibility: hidden`, `aria-hidden` and
+`inert`.
+
+#### Fonts
+
+| id | Severity | When | Fix |
+| --- | --- | --- | --- |
+| `font-display-missing`, `font-display-block` | warn | A loaded `@font-face` has no `font-display` (Chrome then hides its text for up to 3 s) or uses `block`. The message says when it sets text above the fold (FOIT) | `font-display: swap` or `optional`; `&display=swap` for Google Fonts |
+| `font-not-preloaded` | warn | A font file that sets text in the first viewport isn't preloaded | `<link rel="preload" as="font" type="font/woff2" crossorigin>` |
+| `font-preload-no-crossorigin` | warn | A font preload without `crossorigin`, so the file downloads twice | Add `crossorigin` |
+| `font-preload-unused` | info | A preloaded font that no `@font-face` uses | Remove it, or match the URL exactly |
+| `font-failed` | error | A font file returned 400 or above | Fix the `src` URL |
+
+Every font finding names the file URL. The `@font-face` rules come from the
+page's stylesheets; the page can't read cross-origin ones (Google Fonts, a
+CDN), so rpc downloads and parses those itself. Faces with only `local()`
+sources, like next/font's size-adjusted fallbacks, never block text and are
+skipped.
+
+#### Mobile viewport
+
+These run on phone devices only.
+
+| id | Severity | When | Fix |
+| --- | --- | --- | --- |
+| `horizontal-overflow` | error | `scrollWidth` is wider than the layout viewport. Lists the outermost elements that stick out, furthest first | `max-width: 100%` on the element, or `overflow-x: auto` on its wrapper |
+| `vh-units` | warn | A rendered element sized with `100vh` in `height`, `min-height` or `max-height`, from a stylesheet rule that applies or an inline style | `100dvh` or `100svh`, with `100vh` before it as a fallback |
+| `tap-target-small` | warn | Links, buttons and form controls smaller than 44x44 CSS px. Links inside running text are exempt | Padding, `min-height`, or a bigger hit area |
+| `input-zoom` | warn | A text field with `font-size` under 16px; iOS Safari zooms the page when it gets focus | `font-size: 16px` or more |
+
+A headless phone has no browser bars, so `100vh` and `100dvh` measure the
+same there. That's why `vh-units` reads the CSS instead of measuring
+elements. The `height: 100vh; height: 100dvh` fallback pattern isn't
+flagged: the browser keeps only the last value it understands.
+
+### JSON report
+
+`--json` prints this object, and the MCP `check` tool returns the same one.
+`schema` goes up only when a field changes meaning or is removed; new fields
+can appear without it.
+
+```jsonc
+{
+  "schema": 1,
+  "url": "https://example.com/",
+  "devices": [
+    {
+      "device": "iphone-15-pro",
+      "name": "iPhone 15 Pro",
+      "viewport": { "width": 393, "height": 852 },
+      "dpr": 3,
+      "mobile": true,              // the phone-only checks ran here
+      "status": 200,
+      "finalUrl": "https://example.com/",
+      "title": "Example",
+      "cls": 0.012,
+      "layoutShifts": 2,
+      // only when the page didn't load on this device:
+      "error": "…", "code": "ERR_NAME_NOT_RESOLVED", "hint": "…"
+    }
+  ],
+  "summary": { "errors": 1, "warnings": 4, "info": 2 },
+  "findings": [
+    {
+      "id": "horizontal-overflow",      // stable; see the tables above
+      "check": "mobile",                // basics | meta | layout-shift | labels | fonts | mobile
+      "severity": "error",              // error | warn | info
+      "message": "The page scrolls sideways: 601px wide in a 393px viewport",
+      "fix": "Find the element that sticks out …",
+      "devices": ["iphone-15-pro"],
+      "selector": "div.pricing-table",  // when one element is the answer
+      "url": "…",                       // when a file is (a font, og:image)
+      "value": 208,                     // the number behind it, if there is one
+      "items": [                        // elements, files or log lines, when there are several
+        {
+          "selector": "div.pricing-table",
+          "text": "600px wide, 207px past the edge",
+          "value": 207,
+          "screenshot": "/abs/.rpc-shots/…-check-horizontal-overflow-1.png"  // with --shots
+        }
+      ]
+    }
+  ],
+  "ogImage": { "url": "…", "status": 200, "contentType": "image/png", "width": 1200, "height": 630 },
+  "auth": { … }                         // as in rpc shot, values masked
+}
+```
+
+Findings are sorted by check, in the order of the tables above, then by
+severity. `id`, `check`, `severity`, `message`, `fix` and `devices` are
+always there; the other fields appear when they apply.
+
+### In CI
+
+```sh
+npx rpc-agent install
+npx rpc-agent check https://staging.example.com --fail-on warn --json > ship-check.json
+```
+
+The exit code fails the job, and the JSON can go into a PR comment or a
+build artifact. For a page behind a login, sign in first with
+`rpc login <url> --form` (see [CI and agents](#ci-and-agents-rpc-login---form)).
+
+### With a coding agent
+
+Add the MCP server (below) and tell the agent to run `check` before it
+reports UI work as finished, for example in `CLAUDE.md` or `AGENTS.md`:
+
+```md
+Before you say UI work is done, run the rpc `check` tool on each page you
+changed and fix every error. Fix the warnings too, or say why one doesn't apply.
+```
+
 ## MCP server
 
-`rpc mcp` runs an MCP server on stdio with three tools.
+`rpc mcp` runs an MCP server on stdio with four tools.
 
 ### `screenshot`
 
@@ -355,6 +578,25 @@ session, cookies and headers (values masked), and the JSON summary gains an
 `AUTH_REQUIRED` and the `rpc login` hint. Signing in is something the user
 does in a terminal (`rpc login`); the agent then just calls `screenshot`.
 
+### `check`
+
+Runs [Ship-check](#ship-check) on one URL.
+
+| Param | Default | |
+| --- | --- | --- |
+| `url` | required | http(s), file, bare host or local path |
+| `devices` | `["iphone-15-pro", "desktop-1440"]` | ids or aliases; the mobile checks run on phones |
+| `shots` | false | save PNGs of the elements behind layout-shift and overflow findings |
+| `outDir`, `waitFor`, `waitMs`, `colorScheme`, `timeoutMs` | | as for `screenshot` |
+| `cookies`, `headers`, `storageState`, `useSession`, `allowOrigins` | | as for `screenshot` |
+
+The result is two text blocks. The first is a short summary: the counts,
+then one line per error and warning with its id and selector, like
+`ERROR [button-no-name] 2 buttons with no accessible name at button.icon-menu`.
+The second is the JSON report described under [JSON report](#json-report).
+The call is a tool error only when the page failed to load on every device;
+findings, even errors, come back as a normal result for the agent to act on.
+
 ### `list_devices`
 
 Takes an optional `category` (`apple-phone`, `android-phone`, `tablet`,
@@ -445,6 +687,13 @@ appear once, that the IntersectionObserver section rendered, and the slice
 count and labels, including through the MCP server. The missing-browser tests
 point `PLAYWRIGHT_BROWSERS_PATH` at an empty temp dir.
 
+The Ship-check tests serve `test/fixtures/check`: one page per check
+(`meta.html`, `shift.html`, `labels.html`, `fonts.html`, `mobile.html`,
+`basics.html`) and `clean.html`, which must produce no errors or warnings.
+`shift.html` inserts a 300 px banner 800 ms after load, so CLS is known in
+advance (300/852 on the phone, 300/1440 on desktop); the test runs it twice
+and compares.
+
 The README media are built from real captures by `scripts/media/build.ts`;
 `docs/media.md` explains how. The CLI's design notes, and what it borrows
 from the `skills` CLI, are in `docs/cli-design.md`.
@@ -466,6 +715,11 @@ from the `skills` CLI, are in `docs/cli-design.md`.
 - Login-page detection goes by the URL path. An app that shows its sign-in
   form at the requested URL without redirecting is captured as is.
 - Every MCP call launches a fresh Chromium, which adds about a second.
+- Ship-check reads `100vh` only from stylesheets the page can read and from
+  inline styles; a `100vh` rule in a cross-origin stylesheet is missed. Tap
+  targets are measured by their box, so a hit area enlarged with a
+  pseudo-element still counts as small. CLS covers the load and one scroll,
+  not shifts caused by clicking around.
 
 ## License
 

package/dist/args.js

@@ -1,8 +1,8 @@
 import { parseArgs } from 'node:util';
 import { parseCookie, parseHeader, resolveAuth, toOrigin } from './auth.js';
 import { resolveDevices } from './devices.js';
-import { COLOR_SCHEMES, DEFAULT_TIMEOUT_MS, defaultShotOptions, normalizeUrl, } from './options.js';
-export const HELP_TOPICS = ['shot', 'login', 'sessions', 'devices', 'doctor', 'install', 'mcp'];
+import { COLOR_SCHEMES, DEFAULT_TIMEOUT_MS, defaultCheckOptions, defaultShotOptions, FAIL_ON, normalizeUrl, } from './options.js';
+export const HELP_TOPICS = ['shot', 'check', 'login', 'sessions', 'devices', 'doctor', 'install', 'mcp'];
 function isTopic(s) {
     return HELP_TOPICS.includes(s ?? '');
 }
@@ -16,6 +16,7 @@ export const USAGE = `rpc - screenshot a URL at device viewports, optionally in
 
 Usage:
   rpc shot <url> [options]   capture screenshots
+  rpc check <url> [options]  pre-launch audit: meta, layout shift, labels, fonts, mobile
   rpc login <url> [--form]   sign in once and save the session for that origin
   rpc sessions [list|clear [origin]]
                              list or delete saved sessions
@@ -43,7 +44,12 @@ Shot options:
       --json                 print the result as JSON
       --open                 open the output folder when done
 
-Auth options (values are never printed):
+Check options (plus -d, --wait-for, --wait, --timeout, --color-scheme, -o, --json):
+      --fail-on <level>      error (default) | warn: exit 1 on warnings too
+      --shots                screenshot the elements behind layout-shift and
+                             overflow findings (into --out)
+
+Auth options (values are never printed, shot and check):
       --cookie <c>           "name=value[; Domain=…; Path=…]", repeatable;
                              sent to the target origin only
       --header <h>           "Name: value", repeatable; target origin only
@@ -58,6 +64,7 @@ Examples:
   rpc shot localhost:3000 -d iphone-15,ipad,desktop-1440 --bezels
   rpc shot https://example.com --full-page --color-scheme dark
   rpc login localhost:3000/sign-in && rpc shot localhost:3000/dashboard
+  rpc check localhost:3000 --fail-on warn
 `;
 export function parseCli(argv, env = process.env) {
     const [cmd, ...rest] = argv;
@@ -104,6 +111,8 @@ export function parseCli(argv, env = process.env) {
         }
         case 'shot':
             return parseShot(rest);
+        case 'check':
+            return parseCheck(rest);
         default:
             throw new ArgError(`Unknown command "${cmd}". Run \`rpc --help\`.`);
     }
@@ -127,11 +136,7 @@ function parseShot(args) {
         'reduced-motion': { type: 'boolean' },
         json: { type: 'boolean' },
         open: { type: 'boolean' },
-        cookie: { type: 'string', multiple: true },
-        header: { type: 'string', multiple: true },
-        'storage-state': { type: 'string' },
-        'no-session': { type: 'boolean' },
-        'allow-origin': { type: 'string', multiple: true },
+        ...AUTH_FLAGS,
     }, true);
     if (positionals.length === 0)
         throw new ArgError('Missing <url>. Usage: rpc shot <url> [options]');
@@ -144,17 +149,8 @@ function parseShot(args) {
     catch (err) {
         throw new ArgError(err.message);
     }
-    if (typeof values.devices === 'string') {
-        const list = splitList(values.devices);
-        if (list.length === 0)
-            throw new ArgError('--devices is empty');
-        try {
-            options.devices = resolveDevices(list).map(d => d.id);
-        }
-        catch (err) {
-            throw new ArgError(err.message);
-        }
-    }
+    if (typeof values.devices === 'string')
+        options.devices = parseDevices(values.devices);
     if (values.bezels)
         options.bezels = true;
     if (values['full-page'])
@@ -167,13 +163,8 @@ function parseShot(args) {
         options.waitMs = parseMs('--wait', values.wait);
     if (typeof values.timeout === 'string')
         options.timeoutMs = parseMs('--timeout', values.timeout);
-    if (typeof values['color-scheme'] === 'string') {
-        const s = values['color-scheme'];
-        if (!COLOR_SCHEMES.includes(s)) {
-            throw new ArgError(`--color-scheme must be one of ${COLOR_SCHEMES.join(', ')}`);
-        }
-        options.colorScheme = s;
-    }
+    if (typeof values['color-scheme'] === 'string')
+        options.colorScheme = parseColorScheme(values['color-scheme']);
     if (values['no-emulate'])
         options.emulate = false;
     if (values.slices)
@@ -186,6 +177,20 @@ function parseShot(args) {
     if (typeof values['max-height'] === 'string') {
         options.maxHeight = parseInt_('--max-height', values['max-height'], 500, 200_000);
     }
+    const auth = parseAuth(values, options.url);
+    if (auth)
+        options.auth = auth;
+    return { command: 'shot', options, json: Boolean(values.json), open: Boolean(values.open) };
+}
+const AUTH_FLAGS = {
+    cookie: { type: 'string', multiple: true },
+    header: { type: 'string', multiple: true },
+    'storage-state': { type: 'string' },
+    'no-session': { type: 'boolean' },
+    'allow-origin': { type: 'string', multiple: true },
+};
+/** Cookie/header/session flags, validated against the URL now: bad input is a usage error. */
+function parseAuth(values, url) {
     const auth = {};
     try {
         if (values.cookie?.length)
@@ -198,15 +203,80 @@ function parseShot(args) {
             auth.useSession = false;
         if (values['allow-origin']?.length)
             auth.allowOrigins = values['allow-origin'].flatMap(splitList).map(toOrigin);
-        if (Object.keys(auth).length) {
-            resolveAuth(options.url, auth); // validate now: bad input is a usage error
-            options.auth = auth;
-        }
+        if (!Object.keys(auth).length)
+            return undefined;
+        resolveAuth(url, auth);
+        return auth;
     }
     catch (err) {
         throw new ArgError(err.message);
     }
-    return { command: 'shot', options, json: Boolean(values.json), open: Boolean(values.open) };
+}
+function parseDevices(raw) {
+    const list = splitList(raw);
+    if (list.length === 0)
+        throw new ArgError('--devices is empty');
+    try {
+        return resolveDevices(list).map(d => d.id);
+    }
+    catch (err) {
+        throw new ArgError(err.message);
+    }
+}
+function parseCheck(args) {
+    if (wantsHelp(args))
+        return { command: 'help', topic: 'check' };
+    const { values, positionals } = parse(args, {
+        devices: { type: 'string', short: 'd' },
+        out: { type: 'string', short: 'o' },
+        'wait-for': { type: 'string' },
+        wait: { type: 'string' },
+        'color-scheme': { type: 'string' },
+        timeout: { type: 'string' },
+        'fail-on': { type: 'string' },
+        shots: { type: 'boolean' },
+        json: { type: 'boolean' },
+        ...AUTH_FLAGS,
+    }, true);
+    if (positionals.length === 0)
+        throw new ArgError('Missing <url>. Usage: rpc check <url> [options]');
+    if (positionals.length > 1)
+        throw new ArgError(`Expected one URL, got: ${positionals.join(' ')}`);
+    let options;
+    try {
+        options = defaultCheckOptions(positionals[0]);
+    }
+    catch (err) {
+        throw new ArgError(err.message);
+    }
+    if (typeof values.devices === 'string')
+        options.devices = parseDevices(values.devices);
+    if (typeof values.out === 'string')
+        options.outDir = values.out;
+    if (typeof values['wait-for'] === 'string')
+        options.waitFor = values['wait-for'];
+    if (typeof values.wait === 'string')
+        options.waitMs = parseMs('--wait', values.wait);
+    if (typeof values.timeout === 'string')
+        options.timeoutMs = parseMs('--timeout', values.timeout);
+    if (typeof values['color-scheme'] === 'string')
+        options.colorScheme = parseColorScheme(values['color-scheme']);
+    if (typeof values['fail-on'] === 'string') {
+        if (!FAIL_ON.includes(values['fail-on']))
+            throw new ArgError(`--fail-on must be one of ${FAIL_ON.join(', ')}`);
+        options.failOn = values['fail-on'];
+    }
+    if (values.shots)
+        options.shots = true;
+    const auth = parseAuth(values, options.url);
+    if (auth)
+        options.auth = auth;
+    return { command: 'check', options, json: Boolean(values.json) };
+}
+function parseColorScheme(s) {
+    if (!COLOR_SCHEMES.includes(s))
+        throw new ArgError(`--color-scheme must be one of ${COLOR_SCHEMES.join(', ')}`);
+    return s;
 }
 function parseLogin(args, env) {
     if (wantsHelp(args))

package/dist/capture.js

@@ -26,21 +26,7 @@ export async function capture(opts, hooks = {}) {
                 shot = await captureDevice(browser, device, opts, outDir, hooks, auth);
             }
             catch (err) {
-                shot = baseShot(device);
-                if (err instanceof AuthRequiredError) {
-                    shot.status = err.status;
-                    shot.finalUrl = err.finalUrl;
-                    shot.error = err.message;
-                    shot.code = err.code;
-                    shot.hint = err.hint;
-                }
-                else {
-                    const e = explainError(err, { url: opts.url, timeoutMs: opts.timeoutMs, waitFor: opts.waitFor });
-                    shot.error = redact(e.error, auth.secrets);
-                    shot.code = e.code;
-                    if (e.hint)
-                        shot.hint = redact(e.hint, auth.secrets);
-                }
+                shot = { ...baseShot(device), ...describeFailure(err, opts, auth) };
             }
             if (shot.consoleErrors?.length && auth.secrets.length) {
                 shot.consoleErrors = shot.consoleErrors.map(l => redact(l, auth.secrets));
@@ -57,6 +43,18 @@ export async function capture(opts, hooks = {}) {
             await browser.close();
     }
 }
+/** A device's navigation/capture failure as `{ error, code, hint }`, secrets scrubbed. */
+export function describeFailure(err, opts, auth) {
+    if (err instanceof AuthRequiredError) {
+        return { status: err.status, finalUrl: err.finalUrl, error: err.message, code: err.code, hint: err.hint };
+    }
+    const e = explainError(err, { url: opts.url, timeoutMs: opts.timeoutMs, waitFor: opts.waitFor });
+    return {
+        error: redact(e.error, auth.secrets),
+        code: e.code,
+        ...(e.hint ? { hint: redact(e.hint, auth.secrets) } : {}),
+    };
+}
 function baseShot(device) {
     return {
         device: device.id,
@@ -65,7 +63,8 @@ function baseShot(device) {
         dpr: device.dpr,
     };
 }
-async function captureDevice(browser, device, opts, outDir, hooks, auth) {
+/** A fresh context for one device: viewport, DPR, mobile emulation, media features and auth state. */
+export async function newDeviceContext(browser, device, opts, auth) {
     const emu = opts.emulate ? emulationFor(device) : undefined;
     const context = await browser.newContext({
         viewport: { width: device.width, height: device.height },
@@ -80,6 +79,10 @@ async function captureDevice(browser, device, opts, outDir, hooks, auth) {
     });
     if (auth.cookies.length)
         await context.addCookies(auth.cookies);
+    return context;
+}
+async function captureDevice(browser, device, opts, outDir, hooks, auth) {
+    const context = await newDeviceContext(browser, device, opts, auth);
     const result = baseShot(device);
     const errors = new Set();
     try {
@@ -244,7 +247,7 @@ const SCROLL_HEIGHT_JS = `Math.max(document.documentElement.scrollHeight, docume
  * Network idle (bounded: dev servers with HMR or analytics beacons may never
  * go idle), web fonts, and pending <img> loads.
  */
-async function settle(page, timeoutMs) {
+export async function settle(page, timeoutMs) {
     await page
         .waitForLoadState('networkidle', { timeout: Math.min(timeoutMs, 10_000) })
         .catch(() => { });