rpc-agent 0.4.0 → 0.5.0

package/dist/cli.js

@@ -5,14 +5,19 @@ import { ArgError, parseCli, USAGE } from './args.js';
 import { clearSessions, describeAuth, listSessions, localTime, sessionsDir } from './auth.js';
 import { doctor, installChromium } from './browser.js';
 import { capture } from './capture.js';
+import { checkExitCode, runCheck, summaryLine } from './check.js';
+import { deviceLine, plainReport } from './check-format.js';
 import { CATEGORY_LABELS, CATEGORY_ORDER, DEVICE_ALIASES, DEVICES } from './devices.js';
 import { currentMode, openPath, waitForEnter } from './term.js';
 const NO_PAINT = { ok: s => s, bad: s => s, warn: s => s };
 let paint = NO_PAINT;
+/** The full palette for check output; identity functions unless FORCE_COLOR. */
+let colours;
 async function plainPaint() {
+    const { default: pc } = await import('picocolors');
+    colours = pc.createColors(currentMode().color);
     if (!currentMode().color)
         return NO_PAINT;
-    const { default: pc } = await import('picocolors');
     const c = pc.createColors(true);
     return { ok: c.green, bad: c.red, warn: c.yellow };
 }
@@ -102,6 +107,23 @@ async function main(argv) {
                 openPath(result.outDir);
             return result.shots.some(s => s.error) ? 1 : 0;
         }
+        case 'check': {
+            if (mode.rich) {
+                const { ui, c } = await loadUi();
+                return ui.runCheck(cmd.options, c);
+            }
+            const report = await runCheck(cmd.options, cmd.json
+                ? {}
+                : {
+                    onAuth: a => console.log(`auth: ${describeAuth(a)}`),
+                    onDevice: d => console.log(deviceLine(d, colours)),
+                });
+            if (cmd.json)
+                console.log(JSON.stringify(report, null, 2));
+            else
+                printCheck(report);
+            return checkExitCode(report, cmd.options.failOn);
+        }
         case 'login': {
             if (cmd.passwordFromFlag) {
                 console.error(`rpc: ${paint.warn('warning:')} --password is visible in shell history and the process list; set RPC_LOGIN_PASSWORD instead`);
@@ -187,6 +209,15 @@ function rel(p) {
     const r = relative(process.cwd(), p);
     return r.startsWith('..') ? p : r;
 }
+function printCheck(report) {
+    const body = plainReport(report, colours);
+    if (body)
+        console.log(body);
+    console.log('');
+    const s = report.summary;
+    const line = summaryLine(s);
+    console.log(s.errors ? paint.bad(line) : s.warnings ? paint.warn(line) : paint.ok(line));
+}
 function printDoctor(r) {
     console.log(`node        ${r.node}`);
     console.log(`playwright  ${r.playwright}`);

package/dist/help.js

@@ -22,6 +22,17 @@ const AUTH_OPTIONS = [
     ['    --no-session', "don't use the session saved by `rpc login` for this origin"],
     ['    --allow-origin <o>', 'also send headers and loaded cookies to this origin, repeatable'],
 ];
+const CHECK_OPTIONS = [
+    ['-d, --devices <ids>', 'comma-separated device ids or aliases (default: iphone-15-pro,desktop-1440)'],
+    ['    --fail-on <level>', 'error (default) or warn: also exit 1 on warnings'],
+    ['    --shots', 'screenshot the elements behind layout-shift and overflow findings'],
+    ['-o, --out <dir>', 'where --shots writes (default: ./.rpc-shots)'],
+    ['    --wait-for <selector>', 'wait for a CSS selector before checking'],
+    ['    --wait <ms>', 'extra settle delay after the scroll (default: 0)'],
+    ['    --color-scheme <s>', 'light | dark | no-preference'],
+    ['    --timeout <ms>', 'navigation timeout (default: 30000)'],
+    ['    --json', 'print the report as JSON (schema in the README)'],
+];
 const LOGIN_OPTIONS = [
     ['    --save <file>', 'write the storage state here instead of the per-origin session'],
     ['    --form', 'headless: fill an email + password form (CI, agents)'],
@@ -47,6 +58,18 @@ export const COMMANDS = {
             ["rpc shot api.example.com/admin --header 'Authorization: Bearer $TOKEN'", ''],
         ],
     },
+    check: {
+        usage: 'rpc check <url> [options]',
+        summary: 'Audit one page before launch: meta and social tags, layout shift (CLS), unlabelled controls, web fonts, ' +
+            'mobile viewport bugs and basics (status, mixed content, console errors). Exits 1 when there are errors.',
+        options: [...CHECK_OPTIONS, ...AUTH_OPTIONS],
+        examples: [
+            ['rpc check localhost:3000', 'phone + desktop'],
+            ['rpc check localhost:3000 --fail-on warn --json', 'CI: fail on warnings too'],
+            ['rpc check example.com -d pixel,iphone-se,desktop --shots', 'more devices, element screenshots'],
+            ['rpc check localhost:3000/billing', 'uses the session saved by rpc login'],
+        ],
+    },
     login: {
         usage: 'rpc login <url> [--form] [--save <file>]',
         summary: 'Open a browser window at the URL, sign in, then press Enter (or close the window). The session is saved for that ' +
@@ -94,12 +117,13 @@ export const COMMANDS = {
     },
     mcp: {
         usage: 'rpc mcp',
-        summary: 'Run the MCP server on stdio (tools: screenshot, list_devices, list_sessions).',
+        summary: 'Run the MCP server on stdio (tools: screenshot, check, list_devices, list_sessions).',
         examples: [['claude mcp add --scope user rpc -- node /abs/path/dist/cli.js mcp', 'add to Claude Code']],
     },
 };
 const TOP = [
     ['shot <url>', 'capture screenshots'],
+    ['check <url>', 'pre-launch audit: meta, layout shift, labels, fonts, mobile'],
     ['login <url>', 'sign in once; later shots of that origin use the session'],
     ['sessions', 'list or clear saved sessions'],
     ['devices', 'list device ids and aliases'],

package/dist/mcp.js

@@ -4,9 +4,11 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { describeAuth, listSessions, resolveAuth, sessionsDir, toOrigin } from './auth.js';
 import { capture, launchBrowser } from './capture.js';
+import { runCheck } from './check.js';
+import { textSummary } from './check-format.js';
 import { renderPreview } from './composite.js';
 import { CATEGORY_LABELS, CATEGORY_ORDER, DEFAULT_DEVICES, DEVICE_ALIASES, DEVICES, resolveDevices, } from './devices.js';
-import { COLOR_SCHEMES, DEFAULT_MAX_SLICES, DEFAULT_OUT_DIR, DEFAULT_SLICE_WIDTH, DEFAULT_TIMEOUT_MS, normalizeUrl, } from './options.js';
+import { COLOR_SCHEMES, DEFAULT_MAX_SLICES, DEFAULT_OUT_DIR, DEFAULT_SLICE_WIDTH, DEFAULT_TIMEOUT_MS, defaultCheckOptions, normalizeUrl, } from './options.js';
 import { DEFAULT_MAX_HEIGHT } from './slices.js';
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 const screenshotInput = {
@@ -65,6 +67,8 @@ const screenshotInput = {
         .boolean()
         .optional()
         .describe('Return JPEG previews inline: one per device, or the full-page slices when fullPage. Default true.'),
+};
+const authInput = {
     cookies: z
         .array(z.object({
         name: z.string().min(1),
@@ -93,6 +97,41 @@ const screenshotInput = {
         .optional()
         .describe('Extra origins (e.g. an API host) that also get the headers and loaded cookies.'),
 };
+const checkInput = {
+    url: z
+        .string()
+        .describe('Page to audit. http(s)://, file://, a bare host like localhost:3000, or a path to a local .html file.'),
+    devices: z
+        .array(z.string())
+        .min(1)
+        .max(8)
+        .optional()
+        .describe(`Device ids or aliases (see list_devices). Default: ${DEFAULT_DEVICES.join(', ')}. ` +
+        'The mobile viewport checks (100vh, sideways scroll, tap targets, input zoom) run on phones only.'),
+    shots: z
+        .boolean()
+        .optional()
+        .describe('Save PNGs of the elements behind layout-shift and horizontal-overflow findings (paths in the report). Default false.'),
+    outDir: z.string().optional().describe(`Where shots go, relative to the server's cwd. Default ${DEFAULT_OUT_DIR}.`),
+    waitFor: z.string().optional().describe('CSS selector to wait for (visible) before checking.'),
+    waitMs: z.number().int().min(0).max(30_000).optional().describe('Extra settle delay after the scroll, in ms.'),
+    colorScheme: z.enum(COLOR_SCHEMES).optional().describe('Emulate prefers-color-scheme.'),
+    timeoutMs: z.number().int().min(1000).max(120_000).optional().describe(`Navigation timeout. Default ${DEFAULT_TIMEOUT_MS}.`),
+};
+function authFrom(args) {
+    const auth = {};
+    if (args.cookies?.length)
+        auth.cookies = args.cookies;
+    if (args.headers && Object.keys(args.headers).length)
+        auth.headers = args.headers;
+    if (args.storageState)
+        auth.storageState = args.storageState;
+    if (args.useSession === false)
+        auth.useSession = false;
+    if (args.allowOrigins?.length)
+        auth.allowOrigins = args.allowOrigins.map(toOrigin);
+    return auth;
+}
 export function createServer() {
     const server = new McpServer({ name: 'rpc', version: pkg.version });
     server.registerTool('screenshot', {
@@ -100,22 +139,12 @@ export function createServer() {
         description: 'Load a URL in headless Chromium at one or more device viewports (with device pixel ratio, mobile user agent and touch) ' +
             'and save PNG screenshots, optionally framed in a device bezel. Use it to check responsive layout of a page you are building, ' +
             'including local dev servers. Returns file paths, page title, HTTP status and console errors, plus inline previews.',
-        inputSchema: screenshotInput,
+        inputSchema: { ...screenshotInput, ...authInput },
         annotations: { readOnlyHint: false, openWorldHint: true },
     }, async (args) => {
         let options;
         try {
-            const auth = {};
-            if (args.cookies?.length)
-                auth.cookies = args.cookies;
-            if (args.headers && Object.keys(args.headers).length)
-                auth.headers = args.headers;
-            if (args.storageState)
-                auth.storageState = args.storageState;
-            if (args.useSession === false)
-                auth.useSession = false;
-            if (args.allowOrigins?.length)
-                auth.allowOrigins = args.allowOrigins.map(toOrigin);
+            const auth = authFrom(args);
             options = {
                 url: normalizeUrl(args.url),
                 devices: resolveDevices(args.devices ?? DEFAULT_DEVICES).map(d => d.id),
@@ -183,9 +212,58 @@ export function createServer() {
             await browser.close();
         }
     });
+    server.registerTool('check', {
+        title: 'Pre-launch check of a page',
+        description: 'Audit one URL before calling the work done: meta and social tags (title, description, canonical, lang, viewport zoom, ' +
+            'favicon, Open Graph, twitter:card, and whether og:image loads and its size), layout shift (CLS with the elements that moved), ' +
+            'buttons/links/images/fields without an accessible name, web fonts (font-display, preloads), mobile viewport bugs on phones ' +
+            '(100vh, sideways scroll, tap targets under 44px, inputs under 16px) and basics (HTTP status, mixed content, console errors). ' +
+            'Returns a short summary, then the JSON report: each finding has id, severity (error|warn|info), message, selector or url, ' +
+            'devices and a fix. Fix the errors (and ideally warnings), then run it again.',
+        inputSchema: { ...checkInput, ...authInput },
+        annotations: { readOnlyHint: false, openWorldHint: true },
+    }, async (args) => {
+        let options;
+        try {
+            const auth = authFrom(args);
+            options = {
+                ...defaultCheckOptions(args.url),
+                devices: resolveDevices(args.devices ?? DEFAULT_DEVICES).map(d => d.id),
+                outDir: args.outDir ?? DEFAULT_OUT_DIR,
+                waitFor: args.waitFor,
+                waitMs: args.waitMs ?? 0,
+                colorScheme: args.colorScheme,
+                timeoutMs: args.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+                shots: args.shots ?? false,
+                ...(Object.keys(auth).length ? { auth } : {}),
+            };
+            resolveAuth(options.url, auth);
+        }
+        catch (err) {
+            return { isError: true, content: [{ type: 'text', text: err.message }] };
+        }
+        let browser;
+        try {
+            browser = await launchBrowser();
+        }
+        catch (err) {
+            return { isError: true, content: [{ type: 'text', text: `Could not start the browser: ${err.message}` }] };
+        }
+        try {
+            const report = await runCheck(options, { browser });
+            const content = [
+                { type: 'text', text: (report.auth ? `auth: ${describeAuth(report.auth)}\n` : '') + textSummary(report) },
+                { type: 'text', text: JSON.stringify(report, null, 2) },
+            ];
+            return report.devices.every(d => d.error) ? { isError: true, content } : { content };
+        }
+        finally {
+            await browser.close();
+        }
+    });
     server.registerTool('list_devices', {
         title: 'List device presets',
-        description: 'List device ids, CSS viewport sizes and pixel ratios usable in screenshot.devices, plus short aliases.',
+        description: 'List device ids, CSS viewport sizes and pixel ratios usable in screenshot.devices and check.devices, plus short aliases.',
         inputSchema: {
             category: z
                 .enum(CATEGORY_ORDER)

package/dist/options.js

@@ -24,6 +24,20 @@ export function defaultShotOptions(url) {
         sliceWidth: DEFAULT_SLICE_WIDTH,
     };
 }
+export const FAIL_ON = ['error', 'warn'];
+export function defaultCheckOptions(url) {
+    return {
+        url: normalizeUrl(url),
+        devices: [...DEFAULT_DEVICES],
+        outDir: DEFAULT_OUT_DIR,
+        waitMs: 0,
+        timeoutMs: DEFAULT_TIMEOUT_MS,
+        emulate: true,
+        reducedMotion: false,
+        shots: false,
+        failOn: 'error',
+    };
+}
 /**
  * Accept what an agent is likely to type:
  *   http(s)://…, file://…  -> unchanged

package/dist/png.js

@@ -8,6 +8,53 @@ export function pngSize(buf) {
     const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
     return { width: view.getUint32(16), height: view.getUint32(20) };
 }
+/** Width/height of a PNG, JPEG, GIF or WebP from its header; undefined for anything else. */
+export function imageSize(buf) {
+    const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    const ascii = (at, len) => String.fromCharCode(...buf.subarray(at, at + len));
+    try {
+        if (buf.length >= 24 && SIGNATURE.every((b, i) => buf[i] === b))
+            return pngSize(buf);
+        if (ascii(0, 4) === 'GIF8' && buf.length >= 10) {
+            return { width: view.getUint16(6, true), height: view.getUint16(8, true) };
+        }
+        if (ascii(0, 4) === 'RIFF' && ascii(8, 4) === 'WEBP') {
+            const kind = ascii(12, 4);
+            if (kind === 'VP8 ')
+                return { width: view.getUint16(26, true) & 0x3fff, height: view.getUint16(28, true) & 0x3fff };
+            if (kind === 'VP8L') {
+                const bits = view.getUint32(21, true);
+                return { width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1 };
+            }
+            if (kind === 'VP8X') {
+                const u24 = (at) => buf[at] | (buf[at + 1] << 8) | (buf[at + 2] << 16);
+                return { width: u24(24) + 1, height: u24(27) + 1 };
+            }
+            return undefined;
+        }
+        if (buf[0] === 0xff && buf[1] === 0xd8) {
+            // Walk the JPEG segments to the first start-of-frame marker.
+            for (let at = 2; at + 9 < buf.length;) {
+                if (buf[at] !== 0xff)
+                    return undefined;
+                const marker = buf[at + 1];
+                if (marker === 0xff) {
+                    at++;
+                    continue;
+                }
+                const len = view.getUint16(at + 2);
+                if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+                    return { width: view.getUint16(at + 7), height: view.getUint16(at + 5) };
+                }
+                at += 2 + len;
+            }
+        }
+    }
+    catch {
+        // Truncated header.
+    }
+    return undefined;
+}
 /**
  * Decode an 8-bit RGB/RGBA non-interlaced PNG, which is what Chromium
  * screenshots are. Anything else throws: this is not a general decoder.

package/dist/ui.js

@@ -9,6 +9,8 @@ import pc from 'picocolors';
 import { clearSessions, listSessions, localTime, MASK, resolveAuth, sessionsDir, } from './auth.js';
 import { BrowserMissingError, installHint, launchBrowser } from './browser.js';
 import { capture } from './capture.js';
+import { checkExitCode, runCheck as audit, summaryLine } from './check.js';
+import { countsPhrase, groupFindings, groupLines } from './check-format.js';
 import { CATEGORY_ORDER, DEVICE_ALIASES, DEVICES, } from './devices.js';
 import { defaultShotOptions, normalizeUrl } from './options.js';
 import { openCommand, openPath, waitForEnter } from './term.js';
@@ -389,6 +391,110 @@ export async function runShot(options, run, c) {
         p.outro(`${c.green('Done!')}  ${c.dim(advice)}`);
     return failed > 0 ? 1 : 0;
 }
+// ------------------------------------------------------------------ check
+/** Lines for the "Check Summary" box. */
+export function checkSummaryLines(o, c, auth) {
+    const rows = [
+        ['devices', formatList(o.devices.map(d => c.cyan(d)))],
+        ['fail on', o.failOn === 'warn' ? c.yellow('errors and warnings') : 'errors'],
+    ];
+    if (o.colorScheme)
+        rows.push(['colour scheme', o.colorScheme]);
+    if (o.waitFor)
+        rows.push(['wait for', o.waitFor]);
+    if (auth)
+        rows.push(...authRows(auth, c));
+    if (o.shots)
+        rows.push(['shots', `${rel(o.outDir)}/`]);
+    const w = Math.max(...rows.map(([k]) => k.length)) + 1;
+    return [c.cyan(o.url), ...rows.map(([k, v]) => `  ${c.dim(`${k}:`.padEnd(w))} ${v}`)];
+}
+/** The spinner line once a device is done: status, CLS, time. */
+function checkDeviceLine(d, ms, label, c) {
+    if (d.error)
+        return `${label}  ${c.red(d.code ?? 'error')}  ${c.dim(formatMs(ms))}`;
+    const status = d.status == null ? c.dim('--') : d.status >= 400 ? c.red(String(d.status)) : c.green(String(d.status));
+    const cls = d.cls === undefined ? '' : d.cls > 0.25 ? c.red(d.cls.toFixed(3)) : d.cls > 0.1 ? c.yellow(d.cls.toFixed(3)) : c.green(d.cls.toFixed(3));
+    return `${label}  ${status}  ${c.dim('CLS')} ${cls}  ${c.dim(formatMs(ms))}`;
+}
+/** One box per check that found something, titled with its counts. */
+export function checkBoxes(report, c) {
+    const all = report.devices.map(d => d.device);
+    return groupFindings(report).map(g => {
+        const counts = countsPhrase(g.findings);
+        const tint = g.findings.some(f => f.severity === 'error') ? c.red : g.findings.some(f => f.severity === 'warn') ? c.yellow : c.cyan;
+        return { title: `${g.title} ${c.dim('·')} ${tint(counts)}`, lines: groupLines(g, all, c, { icons: true, width: textWidth() }) };
+    });
+}
+export async function runCheck(options, c) {
+    const auth = resolveAuth(options.url, options.auth ?? {});
+    intro(c);
+    p.note(checkSummaryLines(options, c, auth.summary).join('\n'), 'Check Summary');
+    const s = p.spinner();
+    s.start('Starting Chromium');
+    let browser;
+    try {
+        browser = await launchBrowser();
+    }
+    catch (err) {
+        if (err instanceof BrowserMissingError) {
+            s.error(c.red("Playwright's Chromium is not installed"));
+            p.note(wrap(installHint().replace(/^Fix: /, ''), textWidth()).join('\n'), c.yellow('Fix'));
+            p.outro(`${c.red('Nothing checked.')}  ${c.dim('Run: rpc install')}`);
+            return 1;
+        }
+        s.error(c.red(`Chromium did not start: ${err.message.split('\n')[0]}`));
+        p.outro(c.red('Nothing checked.'));
+        return 1;
+    }
+    s.stop(`Chromium ${c.dim(browser.version())}`);
+    let current;
+    let started = 0;
+    let report;
+    const picked = options.devices.map(id => DEVICES.find(d => d.id === id)).filter((d) => Boolean(d));
+    const idW = Math.max(0, ...picked.map(d => d.id.length));
+    const vpW = Math.max(0, ...picked.map(d => viewport(d).length));
+    const label = (id, vp) => `${id.padEnd(idW)}  ${c.dim(vp.padEnd(vpW))}`;
+    try {
+        report = await audit(options, {
+            browser,
+            auth,
+            onDeviceStart: (d) => {
+                started = performance.now();
+                current = p.spinner();
+                current.start(label(d.id, viewport(d)));
+            },
+            onDevice: d => {
+                const line = checkDeviceLine(d, performance.now() - started, label(d.device, viewport({ ...d.viewport, dpr: d.dpr })), c);
+                if (d.error)
+                    current?.error(line);
+                else
+                    current?.stop(line);
+                current = undefined;
+            },
+        });
+    }
+    catch (err) {
+        current?.error(c.red(err.message));
+        p.outro(c.red('Check failed.'));
+        return 1;
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+    for (const box of checkBoxes(report, c))
+        p.note(box.lines.join('\n'), box.title);
+    const code = checkExitCode(report, options.failOn);
+    const line = summaryLine(report.summary);
+    const sum = report.summary;
+    if (sum.errors)
+        p.outro(`${c.red(line)}  ${c.dim('Exit code 1.')}`);
+    else if (sum.warnings)
+        p.outro(`${c.yellow(line)}  ${c.dim(code ? 'Exit code 1 (--fail-on warn).' : 'No errors.')}`);
+    else
+        p.outro(`${c.green(line)}  ${c.dim('Ready to ship.')}`);
+    return code;
+}
 // ------------------------------------------------------------------ interactive
 const PRESELECT = ['iphone-15-pro', 'ipad-air-11', 'desktop-1440'];
 const DEV_PORTS = [3000, 5173, 4321, 8080];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rpc-agent",
-  "version": "0.4.0",
-  "description": "Screenshot a URL at device viewports, optionally framed in device bezels, signed in or not. CLI and MCP server for AI coding agents.",
+  "version": "0.5.0",
+  "description": "Screenshot a URL at device viewports, optionally framed in device bezels, signed in or not, and audit it before launch. CLI and MCP server for AI coding agents.",
   "keywords": [
     "mcp",
     "mcp-server",