patchrome 0.1.0

package/dist/engine.js

@@ -0,0 +1,257 @@
+import { randomUUID } from "node:crypto";
+import { readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { setTimeout as sleep } from "node:timers/promises";
+import { chromium } from "patchright";
+import { keepFocusDuring } from "./focus.js";
+import { readOriginStorageInPage } from "./origin-storage.js";
+const pageOpenTimeoutMs = 15_000;
+// Chrome can raise its window shortly after launch resolves.
+const focusGraceMs = 3_000;
+const devToolsPortWaitMs = 10_000;
+const extensionWorkerWaitMs = 10_000;
+// src/ and dist/ both sit one level below the package root, next to extension/.
+const tabGroupsExtensionDir = fileURLToPath(new URL("../extension/tab-groups", import.meta.url));
+export class PatchrightEngine {
+    #context;
+    #browserCdp;
+    #closedListeners = [];
+    #endpoint;
+    #tabGroupsExtensionId;
+    #targetIdByPage = new WeakMap();
+    async launch(chromeProfileDir, mode) {
+        // A port file left by an earlier Chrome would point at a dead port.
+        await rm(join(chromeProfileDir, "DevToolsActivePort"), { force: true });
+        const context = await keepFocusDuring(chromium.launchPersistentContext(chromeProfileDir, {
+            channel: "chrome",
+            headless: false,
+            viewport: null,
+            // Without this Playwright passes --no-sandbox, which weakens Chrome and shows a warning bar.
+            chromiumSandbox: true,
+            args: launchArgsFor(mode),
+        }), focusGraceMs);
+        context.on("close", () => {
+            for (const listener of this.#closedListeners)
+                listener();
+        });
+        const browser = context.browser();
+        if (!browser)
+            throw new Error("persistent context exposed no browser for a browser-level CDP session");
+        this.#browserCdp = await browser.newBrowserCDPSession();
+        this.#context = context;
+        const { id } = await this.#browserCdp.send("Extensions.loadUnpacked", { path: tabGroupsExtensionDir });
+        this.#tabGroupsExtensionId = id;
+        switch (mode) {
+            case "stealth":
+                break;
+            case "debug":
+                this.#endpoint = await readDevToolsEndpoint(chromeProfileDir);
+                break;
+        }
+    }
+    async openBackgroundPage(browserContextId) {
+        return this.#openTarget(true, browserContextId);
+    }
+    async openForegroundPage(browserContextId) {
+        if (browserContextId === undefined)
+            return this.#requireContext().newPage();
+        return this.#openTarget(false, browserContextId);
+    }
+    // Playwright does not know isolated contexts and files their pages under the persistent one, so
+    // context.cookies() would read the wrong jar. CDP Storage takes the context id.
+    async cookies(urls, browserContextId) {
+        if (browserContextId === undefined)
+            return this.#requireContext().cookies(urls);
+        const { cookies } = await this.#requireBrowserCdp().send("Storage.getCookies", { browserContextId });
+        return cookies
+            .map(playwrightCookieOf)
+            .filter((cookie) => urls === undefined || urls.some((url) => cookieAppliesTo(cookie, url)));
+    }
+    async addCookies(cookies, browserContextId) {
+        if (browserContextId === undefined)
+            return this.#requireContext().addCookies(cookies);
+        await this.#requireBrowserCdp().send("Storage.setCookies", {
+            browserContextId,
+            cookies: cookies.map((cookie) => ({
+                name: cookie.name,
+                value: cookie.value,
+                domain: cookie.domain,
+                path: cookie.path,
+                secure: cookie.secure,
+                httpOnly: cookie.httpOnly,
+                sameSite: cookie.sameSite,
+                ...(cookie.expires > 0 ? { expires: cookie.expires } : {}),
+            })),
+        });
+    }
+    async createIsolatedContext() {
+        const { browserContextId } = await this.#requireBrowserCdp().send("Target.createBrowserContext", {});
+        return browserContextId;
+    }
+    async disposeIsolatedContext(browserContextId) {
+        await this.#requireBrowserCdp().send("Target.disposeBrowserContext", { browserContextId });
+    }
+    async groupTabs(pages, title, color) {
+        const targetIds = await Promise.all(pages.map((page) => this.#targetIdOf(page)));
+        const worker = await this.#tabGroupsWorker();
+        await evaluateInWorker(worker, (request) => globalThis.patchromeGroupTabs(request), { targetIds, title, color });
+    }
+    async describeTabGroups(pages) {
+        const targetIds = await Promise.all(pages.map((page) => this.#targetIdOf(page)));
+        const worker = await this.#tabGroupsWorker();
+        return evaluateInWorker(worker, (request) => globalThis.patchromeDescribeTabGroups(request), { targetIds });
+    }
+    async readProfileCopy(copyUserDataDir, origins) {
+        const reader = await chromium.launchPersistentContext(copyUserDataDir, {
+            channel: "chrome",
+            headless: true,
+            // The everyday profile encrypts cookies with the OS keychain key. Under Playwright's mock keychain Chrome
+            // cannot decrypt them and deletes them from the copy.
+            ignoreDefaultArgs: ["--use-mock-keychain", "--password-store=basic"],
+        });
+        try {
+            await reader.route("**/*", (route) => route.fulfill({
+                status: 200,
+                contentType: "text/html",
+                body: "<!doctype html><title>patchrome import</title>",
+            }));
+            const cookies = await reader.cookies();
+            const page = await reader.newPage();
+            const storage = [];
+            for (const origin of origins) {
+                await page.goto(`${origin}/`, { waitUntil: "commit" });
+                storage.push({ origin, ...(await page.evaluate(readOriginStorageInPage, undefined, undefined, true)) });
+            }
+            return { cookies, origins: storage };
+        }
+        finally {
+            await reader.close();
+        }
+    }
+    debuggingEndpoint() {
+        return this.#endpoint;
+    }
+    async openCdpSession(page) {
+        return this.#requireContext().newCDPSession(page);
+    }
+    async startTrace() {
+        await this.#requireContext().tracing.start({ screenshots: true, snapshots: true });
+    }
+    async stopTrace(path) {
+        await this.#requireContext().tracing.stop({ path });
+    }
+    onClosed(listener) {
+        this.#closedListeners.push(listener);
+    }
+    async close() {
+        await this.#context?.close();
+    }
+    // context.newPage() activates Chrome on macOS; a background CDP target does not. The unique about:blank
+    // fragment ties the `page` event back to this call when several sessions open tabs at once.
+    async #openTarget(isBackground, browserContextId) {
+        const context = this.#requireContext();
+        const marker = `about:blank#patchrome-${randomUUID()}`;
+        const pagePromise = context.waitForEvent("page", {
+            predicate: (page) => page.url() === marker,
+            timeout: pageOpenTimeoutMs,
+        });
+        await this.#requireBrowserCdp().send("Target.createTarget", {
+            url: marker,
+            background: isBackground,
+            ...(browserContextId === undefined ? {} : { browserContextId }),
+        });
+        return pagePromise;
+    }
+    // The extension API names tabs by its own ids; CDP target ids are the only id both sides share.
+    #targetIdOf(page) {
+        let targetId = this.#targetIdByPage.get(page);
+        if (targetId === undefined) {
+            targetId = this.openCdpSession(page).then(async (cdp) => {
+                try {
+                    return (await cdp.send("Target.getTargetInfo")).targetInfo.targetId;
+                }
+                finally {
+                    await cdp.detach().catch(() => { });
+                }
+            });
+            this.#targetIdByPage.set(page, targetId);
+        }
+        return targetId;
+    }
+    async #tabGroupsWorker() {
+        const context = this.#requireContext();
+        const prefix = `chrome-extension://${this.#tabGroupsExtensionId}/`;
+        const isTabGroupsWorker = (worker) => worker.url().startsWith(prefix);
+        return (context.serviceWorkers().find(isTabGroupsWorker) ??
+            context.waitForEvent("serviceworker", { predicate: isTabGroupsWorker, timeout: extensionWorkerWaitMs }));
+    }
+    #requireContext() {
+        if (!this.#context)
+            throw new Error("engine not launched");
+        return this.#context;
+    }
+    #requireBrowserCdp() {
+        if (!this.#browserCdp)
+            throw new Error("engine not launched");
+        return this.#browserCdp;
+    }
+}
+// Port 0 lets Chrome pick a free port, so two debug profiles never collide. Chrome binds it to 127.0.0.1.
+// The extension flag lets Extensions.loadUnpacked load the tab groups extension over the launch pipe; it
+// opens no port.
+function launchArgsFor(mode) {
+    const extensionLoading = "--enable-unsafe-extension-debugging";
+    switch (mode) {
+        case "stealth":
+            return [extensionLoading];
+        case "debug":
+            return [extensionLoading, "--remote-debugging-port=0"];
+    }
+}
+// Patchright evaluates in an isolated world by default, where the extension's globals do not exist.
+function evaluateInWorker(worker, fn, arg) {
+    // oxlint-disable-next-line typescript/unbound-method -- called with worker as this on the next line
+    const evaluate = worker.evaluate;
+    return evaluate.call(worker, fn, arg, false);
+}
+// Chrome writes the chosen port and the browser target path to DevToolsActivePort once it listens.
+async function readDevToolsEndpoint(chromeProfileDir) {
+    const deadlineMs = Date.now() + devToolsPortWaitMs;
+    while (Date.now() < deadlineMs) {
+        const content = await readFile(join(chromeProfileDir, "DevToolsActivePort"), "utf8").catch(() => "");
+        const [port, browserPath] = content.split("\n");
+        if (port && browserPath)
+            return { httpUrl: `http://127.0.0.1:${port}`, browserWsUrl: `ws://127.0.0.1:${port}${browserPath}` };
+        await sleep(100);
+    }
+    throw new Error(`Chrome wrote no DevToolsActivePort in ${chromeProfileDir} within ${devToolsPortWaitMs} ms`);
+}
+function playwrightCookieOf(cookie) {
+    return {
+        name: cookie.name,
+        value: cookie.value,
+        domain: cookie.domain,
+        path: cookie.path,
+        expires: cookie.session ? -1 : cookie.expires,
+        httpOnly: cookie.httpOnly,
+        secure: cookie.secure,
+        sameSite: cookie.sameSite ?? "Lax",
+    };
+}
+// The same match context.cookies(urls) applies: host within the cookie domain, path prefix, https for secure.
+function cookieAppliesTo(cookie, url) {
+    const parsed = new URL(url);
+    const domain = cookie.domain.replace(/^\./, "");
+    const isHostMatch = parsed.hostname === domain || (cookie.domain.startsWith(".") && parsed.hostname.endsWith(`.${domain}`));
+    const path = parsed.pathname || "/";
+    const isPathMatch = path === cookie.path ||
+        path.startsWith(cookie.path.endsWith("/") ? cookie.path : `${cookie.path}/`) ||
+        cookie.path === "/";
+    return (isHostMatch &&
+        isPathMatch &&
+        (!cookie.secure ||
+            parsed.protocol === "https:" ||
+            parsed.hostname === "127.0.0.1" ||
+            parsed.hostname === "localhost"));
+}

package/dist/events.d.ts

@@ -0,0 +1,41 @@
+import { type ConsoleMessage, type PageError } from "./diagnostics.ts";
+import type { NetworkEntry } from "./network.ts";
+import type { ProfileMode } from "./profile-mode.ts";
+export declare const watchEventKinds: readonly ["navigation", "load", "response", "console", "error"];
+export type WatchEventKind = (typeof watchEventKinds)[number];
+export type WatchEvent = {
+    kind: "navigation";
+    tabId: string;
+    url: string;
+    atMs: number;
+} | {
+    kind: "load";
+    tabId: string;
+    url: string;
+    atMs: number;
+} | {
+    kind: "response";
+    tabId: string;
+    entry: NetworkEntry;
+    atMs: number;
+} | {
+    kind: "console";
+    tabId: string;
+    message: ConsoleMessage;
+    atMs: number;
+} | {
+    kind: "error";
+    tabId: string;
+    pageError: PageError;
+    atMs: number;
+};
+export declare function eventKindsFor(mode: ProfileMode): readonly WatchEventKind[];
+export declare function parseWatchEventKinds(raw: string | undefined, mode: ProfileMode): WatchEventKind[];
+export declare function urlOfEvent(event: WatchEvent): string | undefined;
+export declare function watchEventLine(event: WatchEvent): string;
+export declare function watchEventFields(event: WatchEvent): Record<string, unknown>;
+export declare class SessionEvents {
+    #private;
+    publish(session: string, event: WatchEvent): void;
+    subscribe(session: string, listener: (event: WatchEvent) => void): () => void;
+}

package/dist/events.js

@@ -0,0 +1,106 @@
+import { consoleLine } from "./diagnostics.js";
+import { CommandError } from "./protocol.js";
+export const watchEventKinds = ["navigation", "load", "response", "console", "error"];
+// Console and page errors come from the Runtime domain, which only a debug profile turns on.
+export function eventKindsFor(mode) {
+    switch (mode) {
+        case "stealth":
+            return ["navigation", "load", "response"];
+        case "debug":
+            return watchEventKinds;
+    }
+}
+export function parseWatchEventKinds(raw, mode) {
+    const available = eventKindsFor(mode);
+    if (raw === undefined)
+        return [...available];
+    const kinds = raw.split(",").map((part) => part.trim());
+    for (const kind of kinds) {
+        if (!watchEventKinds.includes(kind)) {
+            throw new CommandError("bad_args", `--events ${kind} is not an event`, `use any of ${watchEventKinds.join(", ")}`);
+        }
+        if (!available.includes(kind)) {
+            throw new CommandError("unsupported_in_stealth", `watch --events ${kind} needs a debug profile`, "stealth profiles keep Runtime off so sites cannot detect them; run with --profile debug");
+        }
+    }
+    return kinds;
+}
+// The URL an event is about, which `watch --url` filters on.
+export function urlOfEvent(event) {
+    switch (event.kind) {
+        case "navigation":
+        case "load":
+            return event.url;
+        case "response":
+            return event.entry.url;
+        case "console":
+            return event.message.url;
+        case "error":
+            return event.pageError.url;
+    }
+}
+export function watchEventLine(event) {
+    switch (event.kind) {
+        case "navigation":
+            return `navigation ${event.tabId} ${event.url}`;
+        case "load":
+            return `load ${event.tabId} ${event.url}`;
+        case "response": {
+            const { entry } = event;
+            const status = entry.state === "failed" ? `failed(${entry.failure})` : String(entry.status ?? "pending");
+            return `response ${entry.id} ${entry.tabId} ${status} ${entry.resourceType} ${entry.method} ${entry.url}${entry.durationMs === undefined ? "" : ` ${entry.durationMs}ms`}`;
+        }
+        case "console":
+            return `console ${consoleLine(event.message)}`;
+        case "error":
+            return `error ${event.pageError.id} ${event.tabId} ${event.pageError.message}`;
+    }
+}
+export function watchEventFields(event) {
+    switch (event.kind) {
+        case "navigation":
+        case "load":
+            return { kind: event.kind, tab: event.tabId, url: event.url, atMs: event.atMs };
+        case "response": {
+            const { entry } = event;
+            return {
+                kind: event.kind,
+                tab: event.tabId,
+                id: entry.id,
+                method: entry.method,
+                url: entry.url,
+                type: entry.resourceType,
+                state: entry.state,
+                status: entry.status,
+                durationMs: entry.durationMs,
+                failure: entry.failure,
+                atMs: event.atMs,
+            };
+        }
+        case "console":
+            return { kind: event.kind, tab: event.tabId, ...event.message };
+        case "error":
+            return { kind: event.kind, tab: event.tabId, ...event.pageError };
+    }
+}
+// Fans page events out to the `watch` streams of the session that owns the tab.
+export class SessionEvents {
+    #listeners = new Map();
+    publish(session, event) {
+        for (const listener of this.#listeners.get(session) ?? [])
+            listener(event);
+    }
+    subscribe(session, listener) {
+        let listeners = this.#listeners.get(session);
+        if (!listeners) {
+            listeners = new Set();
+            this.#listeners.set(session, listeners);
+        }
+        listeners.add(listener);
+        return () => {
+            listeners.delete(listener);
+            if (listeners.size === 0 && this.#listeners.get(session) === listeners)
+                this.#listeners.delete(session);
+        };
+    }
+}

package/dist/extract.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+declare const extractSchemaSchema: z.ZodObject<{
+    rows: z.ZodOptional<z.ZodString>;
+    fields: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<{
+        selector: string;
+        attr: undefined;
+        all: boolean;
+    }, string>>, z.ZodPipe<z.ZodObject<{
+        selector: z.ZodOptional<z.ZodString>;
+        attr: z.ZodOptional<z.ZodString>;
+        all: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodTransform<{
+        selector: string | undefined;
+        attr: string | undefined;
+        all: boolean;
+    }, {
+        selector?: string | undefined;
+        attr?: string | undefined;
+        all?: boolean | undefined;
+    }>>]>>;
+    limit: z.ZodOptional<z.ZodInt>;
+}, z.core.$strict>;
+export type ExtractSchema = z.infer<typeof extractSchemaSchema>;
+export type FieldSpec = ExtractSchema["fields"][string];
+export declare function parseExtractSchema(raw: string): ExtractSchema;
+export declare function extractRowsInPage(root: Element, schema: ExtractSchema): Array<Record<string, unknown>>;
+export {};

package/dist/extract.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { parseJsonInput } from "./validate.js";
+const fieldSpecSchema = z.union([
+    z.string().transform((selector) => ({ selector, attr: undefined, all: false })),
+    z
+        .strictObject({
+        selector: z.string().optional(),
+        attr: z.string().optional(),
+        all: z.boolean().optional(),
+    })
+        .transform(({ selector, attr, all }) => ({ selector, attr, all: all === true })),
+], { error: "must be a selector string or an object with selector, attr, all" });
+const extractSchemaSchema = z.strictObject({
+    rows: z.string().min(1, "must be a CSS selector string").optional(),
+    fields: z
+        .record(z.string(), fieldSpecSchema)
+        .refine((fields) => Object.keys(fields).length > 0, "needs at least one field"),
+    limit: z.int().positive().optional(),
+});
+const schemaHint = `{"rows": "li.item", "fields": {"title": "h2", "link": {"selector": "a", "attr": "href"}, "tags": {"selector": ".tag", "all": true}}}`;
+// Validated in the daemon before it touches the page, so a typo names the field instead of returning nulls.
+export function parseExtractSchema(raw) {
+    return parseJsonInput(extractSchemaSchema, raw, "extract schema", schemaHint);
+}
+// Runs inside the page, so it can only use what it is passed. A missing element gives null; href and src
+// resolve against the document so rows carry absolute URLs.
+export function extractRowsInPage(root, schema) {
+    const rowElements = schema.rows === undefined ? [root] : [...root.querySelectorAll(schema.rows)];
+    const limited = schema.limit === undefined ? rowElements : rowElements.slice(0, schema.limit);
+    const valueOf = (element, spec) => {
+        if (spec.attr === undefined) {
+            const text = element instanceof HTMLElement ? element.innerText : element.textContent;
+            return (text ?? "").replace(/\s+/g, " ").trim();
+        }
+        const attribute = element.getAttribute(spec.attr);
+        if (attribute === null)
+            return null;
+        if (spec.attr === "href" || spec.attr === "src") {
+            try {
+                return new URL(attribute, element.ownerDocument.baseURI).href;
+            }
+            catch {
+                return attribute;
+            }
+        }
+        return attribute;
+    };
+    return limited.map((row) => {
+        const record = {};
+        for (const [name, spec] of Object.entries(schema.fields)) {
+            if (spec.all) {
+                const matches = spec.selector === undefined ? [row] : [...row.querySelectorAll(spec.selector)];
+                record[name] = matches.map((element) => valueOf(element, spec)).filter((value) => value !== null);
+            }
+            else {
+                const element = spec.selector === undefined ? row : row.querySelector(spec.selector);
+                record[name] = element === null ? null : valueOf(element, spec);
+            }
+        }
+        return record;
+    });
+}

package/dist/focus.d.ts

@@ -0,0 +1 @@
+export declare function keepFocusDuring<T>(launch: Promise<T>, graceMs: number): Promise<T>;

package/dist/focus.js

@@ -0,0 +1,44 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+const chromeBundleId = "com.google.Chrome";
+const pollIntervalMs = 50;
+async function frontmostBundleId() {
+    try {
+        const { stdout } = await run("/bin/zsh", ["-c", "lsappinfo info -only bundleid $(lsappinfo front)"]);
+        return stdout.match(/="([^"]+)"/)?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
+// macOS activates Chrome when its first window appears, so keystrokes meant for the user's editor land in
+// the address bar. Chrome has no flag to launch in the background, and --no-startup-window stalls Playwright,
+// so this watches the launch and reactivates whichever app was in front. Chrome can activate more than once
+// while its first window settles, so the watch keeps going until the grace period ends. `open -b` needs no Apple Events
+// permission, unlike osascript.
+export async function keepFocusDuring(launch, graceMs) {
+    if (process.platform !== "darwin")
+        return launch;
+    const previous = await frontmostBundleId();
+    if (previous === undefined || previous === chromeBundleId)
+        return launch;
+    let isWatching = true;
+    void (async () => {
+        // oxlint-disable-next-line eslint/no-unmodified-loop-condition -- the grace timer in the finally below clears it
+        while (isWatching) {
+            if ((await frontmostBundleId()) === chromeBundleId) {
+                await run("open", ["-b", previous]).catch(() => undefined);
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        }
+    })();
+    try {
+        return await launch;
+    }
+    finally {
+        setTimeout(() => {
+            isWatching = false;
+        }, graceMs);
+    }
+}

package/dist/glob.d.ts

@@ -0,0 +1,4 @@
+export declare function urlGlobMatches(glob: string, url: string): boolean;
+export declare function isNamePattern(input: string): boolean;
+export declare function nameGlobMatches(pattern: string, name: string): boolean;
+export declare function parseStatusFilter(raw: string): (status: number | undefined) => boolean;

package/dist/glob.js

@@ -0,0 +1,63 @@
+import { CommandError } from "./protocol.js";
+// One glob dialect for `network list --url` and `route`: `*` matches any run of characters, `?` one
+// character, and the glob must match the whole URL. Playwright's own globs treat `/` specially, which
+// surprises agents writing `*api*`.
+export function urlGlobMatches(glob, url) {
+    return globToRegExp(glob).test(url);
+}
+const compiled = new Map();
+function globToRegExp(glob) {
+    let pattern = compiled.get(glob);
+    if (!pattern) {
+        // oxlint-disable-next-line typescript/no-misused-spread -- code points are the unit a glob's ? matches
+        const source = [...glob]
+            .map((char) => (char === "*" ? ".*" : char === "?" ? "." : char.replace(/[.+^${}()|[\]\\]/g, "\\$&")))
+            .join("");
+        pattern = new RegExp(`^${source}$`, "s");
+        compiled.set(glob, pattern);
+    }
+    return pattern;
+}
+// Session names take shell-style patterns: `*`, `?` and `[abc]`. A name without those characters is
+// literal, so `session close work-1` never closes `work-10`.
+export function isNamePattern(input) {
+    return /[*?[]/.test(input);
+}
+export function nameGlobMatches(pattern, name) {
+    if (!isNamePattern(pattern))
+        return pattern === name;
+    let source = "";
+    for (let index = 0; index < pattern.length; index++) {
+        const char = pattern[index] ?? "";
+        const classEnd = char === "[" ? pattern.indexOf("]", index + 2) : -1;
+        if (char === "*")
+            source += ".*";
+        else if (char === "?")
+            source += ".";
+        else if (classEnd !== -1) {
+            const members = pattern.slice(index + 1, classEnd);
+            source += members.startsWith("!") ? `[^${escapeClass(members.slice(1))}]` : `[${escapeClass(members)}]`;
+            index = classEnd;
+        }
+        else
+            source += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${source}$`, "s").test(name);
+}
+function escapeClass(members) {
+    return members.replace(/[\\\]^]/g, "\\$&");
+}
+// `--status 404`, `--status 4xx`, `--status 2xx,304`.
+export function parseStatusFilter(raw) {
+    const parts = raw.split(",").map((part) => part.trim().toLowerCase());
+    const checks = parts.map((part) => {
+        if (/^[1-5]xx$/.test(part)) {
+            const hundred = Number(part[0]) * 100;
+            return (status) => status >= hundred && status < hundred + 100;
+        }
+        if (/^[1-5]\d\d$/.test(part))
+            return (status) => status === Number(part);
+        throw new CommandError("bad_args", `--status takes codes like 404, 4xx or 2xx,304, got ${raw}`);
+    });
+    return (status) => status !== undefined && checks.some((check) => check(status));
+}