rpc-agent 0.3.1 → 0.5.0

package/dist/args.js

@@ -1,7 +1,8 @@
 import { parseArgs } from 'node:util';
+import { parseCookie, parseHeader, resolveAuth, toOrigin } from './auth.js';
 import { resolveDevices } from './devices.js';
-import { COLOR_SCHEMES, defaultShotOptions, } from './options.js';
-export const HELP_TOPICS = ['shot', '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 ?? '');
 }
@@ -15,10 +16,14 @@ 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
   rpc devices [--json]       list device ids and aliases
   rpc mcp                    run the MCP server on stdio
   rpc doctor [--json]        check that Playwright's Chromium is installed and launches
-  rpc install                download Playwright's Chromium (same version rpc uses)
+  rpc install [--headed]     download Playwright's Chromium (same version rpc uses)
 
 Shot options:
   -d, --devices <ids>        comma-separated device ids or aliases
@@ -39,14 +44,29 @@ Shot options:
       --json                 print the result as JSON
       --open                 open the output folder when done
 
+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
+      --storage-state <file> load a Playwright storageState JSON
+      --no-session           don't use the session saved by \`rpc login\`
+      --allow-origin <o>     also send headers/cookies to this origin, repeatable
+
 Run \`rpc help <command>\` for one command's options and examples.
 Run \`rpc\` with no arguments in a terminal for an interactive capture.
 
 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) {
+export function parseCli(argv, env = process.env) {
     const [cmd, ...rest] = argv;
     switch (cmd) {
         case undefined:
@@ -67,10 +87,16 @@ export function parseCli(argv) {
             if (wantsHelp(rest))
                 return { command: 'help', topic: 'mcp' };
             return { command: 'mcp' };
-        case 'install':
+        case 'install': {
             if (wantsHelp(rest))
                 return { command: 'help', topic: 'install' };
-            return { command: 'install' };
+            const { values } = parse(rest, { headed: { type: 'boolean' } }, false);
+            return values.headed ? { command: 'install', headed: true } : { command: 'install' };
+        }
+        case 'login':
+            return parseLogin(rest, env);
+        case 'sessions':
+            return parseSessions(rest);
         case 'doctor': {
             if (wantsHelp(rest))
                 return { command: 'help', topic: 'doctor' };
@@ -85,6 +111,8 @@ export function parseCli(argv) {
         }
         case 'shot':
             return parseShot(rest);
+        case 'check':
+            return parseCheck(rest);
         default:
             throw new ArgError(`Unknown command "${cmd}". Run \`rpc --help\`.`);
     }
@@ -108,6 +136,7 @@ function parseShot(args) {
         'reduced-motion': { type: 'boolean' },
         json: { type: 'boolean' },
         open: { type: 'boolean' },
+        ...AUTH_FLAGS,
     }, true);
     if (positionals.length === 0)
         throw new ArgError('Missing <url>. Usage: rpc shot <url> [options]');
@@ -120,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'])
@@ -143,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)
@@ -162,11 +177,185 @@ 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)
+            auth.cookies = values.cookie.map(parseCookie);
+        if (values.header?.length)
+            auth.headers = Object.fromEntries(values.header.map(parseHeader));
+        if (typeof values['storage-state'] === 'string')
+            auth.storageState = values['storage-state'];
+        if (values['no-session'])
+            auth.useSession = false;
+        if (values['allow-origin']?.length)
+            auth.allowOrigins = values['allow-origin'].flatMap(splitList).map(toOrigin);
+        if (!Object.keys(auth).length)
+            return undefined;
+        resolveAuth(url, auth);
+        return auth;
+    }
+    catch (err) {
+        throw new ArgError(err.message);
+    }
+}
+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))
+        return { command: 'help', topic: 'login' };
+    const { values, positionals } = parse(args, {
+        save: { type: 'string' },
+        form: { type: 'boolean' },
+        email: { type: 'string' },
+        password: { type: 'string' },
+        'email-selector': { type: 'string' },
+        'password-selector': { type: 'string' },
+        'submit-selector': { type: 'string' },
+        timeout: { type: 'string' },
+        json: { type: 'boolean' },
+    }, true);
+    if (positionals.length !== 1)
+        throw new ArgError('Usage: rpc login <url> [--form] [--save <file>]');
+    let url;
+    try {
+        url = normalizeUrl(positionals[0]);
+        toOrigin(url);
+    }
+    catch (err) {
+        throw new ArgError(err.message);
+    }
+    const cmd = {
+        command: 'login',
+        url,
+        timeoutMs: typeof values.timeout === 'string' ? parseMs('--timeout', values.timeout) : DEFAULT_TIMEOUT_MS,
+        json: Boolean(values.json),
+    };
+    if (typeof values.save === 'string')
+        cmd.save = values.save;
+    const formOnly = ['email', 'password', 'email-selector', 'password-selector', 'submit-selector'];
+    if (!values.form) {
+        const used = formOnly.filter(k => values[k] !== undefined);
+        if (used.length)
+            throw new ArgError(`--${used[0]} needs --form`);
+        return cmd;
+    }
+    const email = values.email ?? env.RPC_LOGIN_EMAIL;
+    const password = values.password ?? env.RPC_LOGIN_PASSWORD;
+    if (!email)
+        throw new ArgError('--form needs an email: set RPC_LOGIN_EMAIL (or pass --email)');
+    if (!password)
+        throw new ArgError('--form needs a password: set RPC_LOGIN_PASSWORD');
+    cmd.form = {
+        email,
+        password,
+        ...(values['email-selector'] ? { emailSelector: values['email-selector'] } : {}),
+        ...(values['password-selector'] ? { passwordSelector: values['password-selector'] } : {}),
+        ...(values['submit-selector'] ? { submitSelector: values['submit-selector'] } : {}),
+    };
+    if (values.password !== undefined)
+        cmd.passwordFromFlag = true;
+    return cmd;
+}
+function parseSessions(args) {
+    if (wantsHelp(args))
+        return { command: 'help', topic: 'sessions' };
+    const { values, positionals } = parse(args, { json: { type: 'boolean' } }, true);
+    const [action = 'list', origin, ...extra] = positionals;
+    if (action !== 'list' && action !== 'clear')
+        throw new ArgError(`Unknown sessions action "${action}". Use list or clear.`);
+    if (extra.length || (action === 'list' && origin))
+        throw new ArgError('Usage: rpc sessions list | rpc sessions clear [origin]');
+    if (origin) {
+        try {
+            toOrigin(origin);
+        }
+        catch (err) {
+            throw new ArgError(err.message);
+        }
+    }
+    return { command: 'sessions', action, ...(origin ? { origin } : {}), json: Boolean(values.json) };
+}
 function parse(args, options, allowPositionals) {
     try {
-        return parseArgs({ args, options: options, allowPositionals, strict: true });
+        return parseArgs({ args, options, allowPositionals, strict: true });
     }
     catch (err) {
         throw new ArgError(err.message);