patchrome 0.1.0

package/dist/daemon.js

@@ -0,0 +1,313 @@
+import { chmod, mkdir, rm } from "node:fs/promises";
+import { createServer } from "node:net";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { z } from "zod";
+import { currentBuildId } from "./build-id.js";
+import { CopyGuard } from "./copy-guard.js";
+import { detectHostPlatform } from "./host-platform.js";
+import { hostPromptsFor } from "./host-prompts.js";
+import { restoreSession, runCommand } from "./commands.js";
+import { PatchrightEngine } from "./engine.js";
+import { PageDiagnostics } from "./diagnostics.js";
+import { SessionEvents } from "./events.js";
+import { NetworkLog } from "./network.js";
+import { appendHistoryStep, historyFileName, isReplayable, replayStep } from "./history.js";
+import { approvalBundlesDirFrom, auditLogPathFrom, idleMsFrom, profilePaths, sessionFolderName } from "./paths.js";
+import { fixProfileMode } from "./profile-mode.js";
+import { CommandError, isCommandName, } from "./protocol.js";
+import { RouteTable } from "./routes.js";
+import { loadSavedSessions, pruneSessionFolders, saveSessions } from "./session-store.js";
+import { SessionRegistry } from "./sessions.js";
+import { tabGroupColorFor, tabGroupTitleFor } from "./tab-groups.js";
+import { parseJsonInput } from "./validate.js";
+export async function runDaemon(profile, env = process.env, options = {}) {
+    const paths = profilePaths(profile, env);
+    const idleMs = idleMsFrom(env);
+    const log = (message) => process.stdout.write(`${new Date().toISOString()} ${message}\n`);
+    await mkdir(paths.chromeProfileDir, { recursive: true });
+    await rm(paths.socketPath, { force: true });
+    const { mode } = await fixProfileMode(paths, profile, undefined);
+    const pruned = await pruneSessionFolders(paths.sessionsDir, Date.now());
+    if (pruned.length > 0)
+        log(`pruned ${pruned.length} session folders older than 7 days`);
+    // Sessions wait here until their first command, so a restart does not reload every site at once.
+    const awaitingRestore = new Map((await loadSavedSessions(paths.savedSessionsPath, Date.now())).map((saved) => [saved.name, saved]));
+    let isSavingSessions = true;
+    let saveTimer;
+    const saveSessionsNow = async () => {
+        clearTimeout(saveTimer);
+        saveTimer = undefined;
+        // A session mid-restore stays saved as it was, so a crash during the restore cannot save its first few tabs over it.
+        const live = registry.savedSessions().filter((saved) => !awaitingRestore.has(saved.name));
+        await saveSessions(paths.savedSessionsPath, [...live, ...awaitingRestore.values()], Date.now()).catch((err) => log(`saving sessions.json failed: ${String(err)}`));
+    };
+    const scheduleSessionsSave = () => {
+        if (!isSavingSessions || saveTimer !== undefined)
+            return;
+        saveTimer = setTimeout(() => void saveSessionsNow(), 100);
+    };
+    const engine = new PatchrightEngine();
+    const events = new SessionEvents();
+    const network = new NetworkLog((entry) => events.publish(entry.session, { kind: "response", tabId: entry.tabId, entry, atMs: Date.now() }));
+    const routes = new RouteTable();
+    const diagnostics = new PageDiagnostics((tab, pageError) => events.publish(tab.session, { kind: "error", tabId: tab.id, pageError, atMs: Date.now() }));
+    const consoleCaptureByTab = new WeakMap();
+    // One regroup at a time per session, so two tabs opened together join one group instead of starting two.
+    // A tab group is a label for people watching the browser, so a failure is logged and never fails a command.
+    // Isolated sessions stay ungrouped: Chrome keeps each CDP browser context out of reach of extensions, and
+    // chrome.tabs.get answers "No tab with id" for their tabs.
+    const regroupQueues = new Map();
+    const regroupTabs = (session) => {
+        const regrouped = (regroupQueues.get(session) ?? Promise.resolve())
+            .then(async () => {
+            await launched;
+            const pages = registry.openTabsOf(session).map((tab) => tab.page);
+            if (pages.length === 0 || registry.browserContextOf(session) !== undefined)
+                return;
+            await engine.groupTabs(pages, tabGroupTitleFor(session, registry.labelOf(session)), tabGroupColorFor(session));
+        })
+            .catch((err) => {
+            log(`${session} tab grouping failed: ${String(err).split("\n")[0]}`);
+        });
+        regroupQueues.set(session, regrouped);
+        void regrouped.then(() => {
+            if (regroupQueues.get(session) === regrouped)
+                regroupQueues.delete(session);
+        });
+        return regrouped;
+    };
+    const registry = new SessionRegistry((tab) => {
+        network.record(tab);
+        routes.track(tab);
+        tab.page.on("framenavigated", (frame) => {
+            if (frame === tab.page.mainFrame())
+                events.publish(tab.session, { kind: "navigation", tabId: tab.id, url: frame.url(), atMs: Date.now() });
+        });
+        tab.page.on("load", () => events.publish(tab.session, { kind: "load", tabId: tab.id, url: tab.page.url(), atMs: Date.now() }));
+        void regroupTabs(tab.session);
+        switch (mode) {
+            case "stealth":
+                break;
+            case "debug":
+                consoleCaptureByTab.set(tab, engine
+                    .openCdpSession(tab.page)
+                    .then((cdp) => diagnostics.record(tab, cdp))
+                    .catch((err) => {
+                    log(`console capture failed for ${tab.id}: ${String(err)}`);
+                }));
+                break;
+        }
+    }, scheduleSessionsSave);
+    registry.reserveTabIds([...awaitingRestore.values()].flatMap((saved) => saved.tabs.map((tab) => tab.id)));
+    const buildId = currentBuildId();
+    const version = buildId.split("+")[0] ?? buildId;
+    const sessionQueues = new Map();
+    let idleTimer;
+    // The idle clock runs only while no request is in flight, so a slow Chrome launch or a long wait is never cut off.
+    let inFlightRequests = 0;
+    let isShuttingDown = false;
+    const server = createServer((socket) => handleConnection(socket));
+    const shutdown = async (reason) => {
+        if (isShuttingDown)
+            return;
+        isShuttingDown = true;
+        log(`shutting down: ${reason}`);
+        clearTimeout(idleTimer);
+        server.close();
+        await rm(paths.socketPath, { force: true });
+        // Closing Chrome closes every page, which would save empty sessions over the ones to restore.
+        await saveSessionsNow();
+        isSavingSessions = false;
+        await engine.close().catch((err) => log(`engine close failed: ${String(err)}`));
+        if (options.exitProcess)
+            options.exitProcess(0);
+        else
+            process.exit(0);
+    };
+    const resetIdleTimer = () => {
+        clearTimeout(idleTimer);
+        // A request can arrive while startup is still awaiting after listen, before startup arms the timer.
+        if (inFlightRequests > 0)
+            return;
+        idleTimer = setTimeout(() => void shutdown(`idle for ${idleMs} ms`), idleMs);
+    };
+    const ctx = {
+        engine,
+        registry,
+        network,
+        routes,
+        diagnostics,
+        events,
+        mode,
+        trace: { owner: undefined },
+        consoleCaptureReady: (tab) => consoleCaptureByTab.get(tab) ?? Promise.resolve(),
+        version,
+        buildId,
+        sessionsDir: paths.sessionsDir,
+        profile,
+        startedAtMs: Date.now(),
+        requestShutdown: () => setImmediate(() => void shutdown("daemon stop")),
+        regroupTabs,
+        savedSessionNames: () => [...awaitingRestore.keys()].filter((name) => !registry.hasSession(name)),
+        forgetSavedSession: (name) => {
+            awaitingRestore.delete(name);
+            scheduleSessionsSave();
+        },
+        copyGuard: new CopyGuard({
+            prompts: options.prompts ?? hostPromptsFor(detectHostPlatform(), log, approvalBundlesDirFrom(env)),
+            auditLogPath: auditLogPathFrom(env),
+            profile,
+            log,
+        }),
+    };
+    // Listening before Chrome is up lets concurrent starters connect at once; requests wait on launch.
+    const launched = engine.launch(paths.chromeProfileDir, mode);
+    engine.onClosed(() => void shutdown("browser closed"));
+    launched.catch((err) => {
+        log(`browser launch failed: ${String(err)}`);
+        void shutdown("launch failure");
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(paths.socketPath, () => resolve());
+    });
+    await chmod(paths.socketPath, 0o600);
+    // The starter's lock is released once the socket answers, so later starters connect instead of spawning.
+    await rm(paths.lockDir, { recursive: true, force: true });
+    log(`listening on ${paths.socketPath}, pid ${process.pid}, ${mode} profile`);
+    resetIdleTimer();
+    for (const signal of ["SIGTERM", "SIGINT"])
+        process.on(signal, () => void shutdown(signal));
+    // A connection carries one request from the CLI, or many from `pipe` and the library.
+    function handleConnection(socket) {
+        const disconnected = new AbortController();
+        socket.once("close", () => disconnected.abort());
+        const lines = createInterface({ input: socket });
+        lines.on("line", (line) => {
+            inFlightRequests += 1;
+            clearTimeout(idleTimer);
+            void respond(socket, line, disconnected.signal).finally(() => {
+                inFlightRequests -= 1;
+                resetIdleTimer();
+            });
+        });
+        socket.on("error", () => { });
+    }
+    async function recordHistory(request, data) {
+        if (request.argv === undefined || !isReplayable(request.command, request.args))
+            return;
+        const path = join(paths.sessionsDir, sessionFolderName(request.session), historyFileName);
+        await appendHistoryStep(path, replayStep(request.command, request.argv, data.replay, Date.now())).catch((err) => log(`${request.session} history write failed: ${String(err)}`));
+    }
+    // A follow runs until its timeout or until the client disconnects, and outside the session queue, so
+    // the same session can keep browsing while it streams.
+    function isStreaming(request) {
+        return (request.command === "console" && request.args.follow === true) || request.command === "watch";
+    }
+    async function restoreIfSaved(request) {
+        const saved = awaitingRestore.get(request.session);
+        if (saved === undefined)
+            return;
+        if (request.command === "daemon-status" || request.command === "daemon-stop")
+            return;
+        if (request.command === "session-close" && request.args.pattern === undefined) {
+            awaitingRestore.delete(request.session);
+            scheduleSessionsSave();
+            return;
+        }
+        const { restored, dropped } = await restoreSession(ctx, saved, request.timeoutMs);
+        awaitingRestore.delete(request.session);
+        log(`${request.session} restored tabs ${restored.join(" ") || "none"}${dropped.length > 0 ? `, dropped ${dropped.join(" ")}` : ""}`);
+    }
+    async function respond(socket, line, disconnected) {
+        let request;
+        try {
+            request = parseRequest(line);
+        }
+        catch (err) {
+            return send(socket, { id: -1, ok: false, error: toCommandError(err).toBody() });
+        }
+        // status and stop still work, so an outdated daemon can be inspected and replaced.
+        if (request.buildId !== buildId && request.command !== "daemon-status" && request.command !== "daemon-stop") {
+            return send(socket, {
+                id: request.id,
+                ok: false,
+                error: new CommandError("daemon_outdated", `the running daemon is patchrome build ${buildId}, this CLI is ${request.buildId}`, "run `patchrome daemon stop` once no other session is browsing; the next command starts a current daemon").toBody(),
+            });
+        }
+        const call = {
+            ...request,
+            emit: (stream) => send(socket, { id: request.id, stream }),
+            disconnected,
+        };
+        if (isStreaming(request)) {
+            try {
+                await launched;
+                const { lines, fields } = await runCommand(ctx, call);
+                return send(socket, { id: request.id, ok: true, data: { lines, fields } });
+            }
+            catch (err) {
+                return send(socket, { id: request.id, ok: false, error: toCommandError(err).toBody() });
+            }
+        }
+        // Commands from one session run in order; different sessions run concurrently.
+        const previous = sessionQueues.get(request.session) ?? Promise.resolve();
+        const current = previous.then(async () => {
+            try {
+                await launched;
+                await restoreIfSaved(request);
+                const { lines, fields, replay } = await runCommand(ctx, call);
+                await recordHistory(request, { lines, fields, replay });
+                return { id: request.id, ok: true, data: { lines, fields } };
+            }
+            catch (err) {
+                const error = toCommandError(err);
+                log(`${request.session} ${request.command} failed: ${error.code} ${error.message}`);
+                return { id: request.id, ok: false, error: error.toBody() };
+            }
+        });
+        const settled = current.catch(() => { });
+        sessionQueues.set(request.session, settled);
+        void settled.then(() => {
+            if (sessionQueues.get(request.session) === settled)
+                sessionQueues.delete(request.session);
+        });
+        send(socket, await current);
+    }
+}
+// Patchright 1.63 starts request interception from the CRPage constructor without awaiting or catching it.
+// A page that closes before that CDP call answers rejects with a closed-session ProtocolError nobody holds,
+// which would otherwise crash the daemon and every session in it.
+export function isClosedTargetRejection(reason) {
+    // The class leaves `name` as "Error"; only its constructor carries the ProtocolError name.
+    return (reason instanceof Error &&
+        reason.constructor.name === "ProtocolError" &&
+        reason.type === "closed");
+}
+function send(socket, response) {
+    if (!socket.destroyed)
+        socket.write(`${JSON.stringify(response)}\n`);
+}
+const requestSchema = z.object({
+    id: z.number(),
+    session: z.string().min(1),
+    command: z.string().refine(isCommandName, { error: (issue) => `unknown command ${String(issue.input)}` }),
+    args: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.undefined()])),
+    timeoutMs: z.number().positive(),
+    argv: z.array(z.string()).optional(),
+    buildId: z.string(),
+});
+function parseRequest(line) {
+    return parseJsonInput(requestSchema, line, "request");
+}
+function toCommandError(err) {
+    if (err instanceof CommandError)
+        return err;
+    if (err instanceof SyntaxError)
+        return new CommandError("bad_args", `malformed request: ${err.message}`);
+    const message = err instanceof Error ? (err.message.split("\n")[0] ?? err.message) : String(err);
+    if (err instanceof Error && err.name === "TimeoutError")
+        return new CommandError("timeout", message);
+    return new CommandError("bad_args", message);
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,44 @@
+import type { CDPSession } from "patchright";
+import type { Tab } from "./sessions.ts";
+export declare const consoleLevels: readonly ["debug", "info", "warning", "error"];
+export type ConsoleLevel = (typeof consoleLevels)[number];
+export interface ConsoleMessage {
+    id: string;
+    tabId: string;
+    level: ConsoleLevel;
+    text: string;
+    url: string | undefined;
+    line: number | undefined;
+    atMs: number;
+}
+export interface PageError {
+    id: string;
+    tabId: string;
+    message: string;
+    stack: string | undefined;
+    url: string | undefined;
+    line: number | undefined;
+    atMs: number;
+}
+interface RemoteObject {
+    type: string;
+    subtype?: string;
+    value?: unknown;
+    unserializableValue?: string;
+    description?: string;
+}
+export declare class PageDiagnostics {
+    #private;
+    constructor(onPageError?: (tab: Tab, pageError: PageError) => void);
+    record(tab: Tab, cdp: CDPSession): Promise<void>;
+    messages(session: string, minimumLevel: ConsoleLevel): ConsoleMessage[];
+    errors(session: string): PageError[];
+    follow(session: string, listener: (message: ConsoleMessage) => void): () => void;
+    forget(session: string): void;
+}
+export declare function parseConsoleLevel(raw: string): ConsoleLevel;
+export declare function consoleLevelOf(cdpType: string): ConsoleLevel;
+export declare function isAtLeast(level: ConsoleLevel, minimum: ConsoleLevel): boolean;
+export declare function renderRemoteObject(object: RemoteObject): string;
+export declare function consoleLine(message: ConsoleMessage): string;
+export {};

package/dist/diagnostics.js

@@ -0,0 +1,117 @@
+import { CommandError } from "./protocol.js";
+export const consoleLevels = ["debug", "info", "warning", "error"];
+const consoleLimitPerSession = 1000;
+const errorLimitPerSession = 200;
+// Debug profile only. Patchright disables Playwright's console and pageerror events, so capture goes
+// through a CDP session with Runtime enabled, which is exactly the signal a stealth profile must not send.
+export class PageDiagnostics {
+    #sessions = new Map();
+    #nextMessageId = 1;
+    #nextErrorId = 1;
+    #onPageError;
+    constructor(onPageError = () => { }) {
+        this.#onPageError = onPageError;
+    }
+    async record(tab, cdp) {
+        cdp.on("Runtime.consoleAPICalled", (event) => {
+            const frame = event.stackTrace?.callFrames[0];
+            const message = {
+                id: `c${this.#nextMessageId++}`,
+                tabId: tab.id,
+                level: consoleLevelOf(event.type),
+                text: event.args.map(renderRemoteObject).join(" "),
+                url: frame?.url || undefined,
+                line: frame === undefined ? undefined : frame.lineNumber + 1,
+                atMs: Date.now(),
+            };
+            const diagnostics = this.#sessionFor(tab.session);
+            pushCapped(diagnostics.messages, message, consoleLimitPerSession);
+            for (const follower of diagnostics.followers)
+                follower(message);
+        });
+        cdp.on("Runtime.exceptionThrown", (event) => {
+            const details = event.exceptionDetails;
+            const description = details.exception?.description;
+            const pageError = {
+                id: `x${this.#nextErrorId++}`,
+                tabId: tab.id,
+                message: (description ?? details.text).split("\n")[0] ?? details.text,
+                stack: description ?? formatStack(details.stackTrace),
+                url: details.url,
+                line: details.lineNumber + 1,
+                atMs: Date.now(),
+            };
+            pushCapped(this.#sessionFor(tab.session).errors, pageError, errorLimitPerSession);
+            this.#onPageError(tab, pageError);
+        });
+        await cdp.send("Runtime.enable");
+    }
+    messages(session, minimumLevel) {
+        return (this.#sessions.get(session)?.messages ?? []).filter((message) => isAtLeast(message.level, minimumLevel));
+    }
+    errors(session) {
+        return this.#sessions.get(session)?.errors ?? [];
+    }
+    follow(session, listener) {
+        const followers = this.#sessionFor(session).followers;
+        followers.add(listener);
+        return () => followers.delete(listener);
+    }
+    forget(session) {
+        this.#sessions.delete(session);
+    }
+    #sessionFor(session) {
+        let diagnostics = this.#sessions.get(session);
+        if (!diagnostics) {
+            diagnostics = { messages: [], errors: [], followers: new Set() };
+            this.#sessions.set(session, diagnostics);
+        }
+        return diagnostics;
+    }
+}
+export function parseConsoleLevel(raw) {
+    if (!consoleLevels.includes(raw)) {
+        throw new CommandError("bad_args", `--level ${raw} is not a console level`, `use one of ${consoleLevels.join(", ")}; each includes the levels above it`);
+    }
+    return raw;
+}
+// CDP reports the console method called; agents filter by severity.
+export function consoleLevelOf(cdpType) {
+    if (cdpType === "error" || cdpType === "assert")
+        return "error";
+    if (cdpType === "warning")
+        return "warning";
+    if (cdpType === "debug")
+        return "debug";
+    return "info";
+}
+export function isAtLeast(level, minimum) {
+    return consoleLevels.indexOf(level) >= consoleLevels.indexOf(minimum);
+}
+export function renderRemoteObject(object) {
+    if (object.unserializableValue !== undefined)
+        return object.unserializableValue;
+    if (object.type === "string")
+        return String(object.value);
+    if (object.value !== undefined)
+        return JSON.stringify(object.value);
+    if (object.type === "undefined")
+        return "undefined";
+    return object.description ?? object.subtype ?? object.type;
+}
+function formatStack(stackTrace) {
+    if (!stackTrace)
+        return undefined;
+    return stackTrace.callFrames
+        .map((frame) => `    at ${frame.functionName || "<anonymous>"} (${frame.url}:${frame.lineNumber + 1}:${frame.columnNumber + 1})`)
+        .join("\n");
+}
+function pushCapped(items, item, limit) {
+    items.push(item);
+    if (items.length > limit)
+        items.shift();
+}
+export function consoleLine(message) {
+    const where = message.url === undefined ? "" : ` (${message.url}:${message.line})`;
+    return `${message.id} ${message.tabId} ${message.level} ${message.text}${where}`;
+}

package/dist/engine.d.ts

@@ -0,0 +1,51 @@
+import { type CDPSession, type Cookie, type Page } from "patchright";
+import { type OriginStorage } from "./origin-storage.ts";
+import type { ProfileMode } from "./profile-mode.ts";
+import type { TabGroupColor, TabGroupSummary } from "./tab-groups.ts";
+export interface DebuggingEndpoint {
+    httpUrl: string;
+    browserWsUrl: string;
+}
+export interface BrowserEngine {
+    launch(chromeProfileDir: string, mode: ProfileMode): Promise<void>;
+    openBackgroundPage(browserContextId?: string): Promise<Page>;
+    openForegroundPage(browserContextId?: string): Promise<Page>;
+    cookies(urls: string[] | undefined, browserContextId?: string): Promise<Cookie[]>;
+    addCookies(cookies: Cookie[], browserContextId?: string): Promise<void>;
+    createIsolatedContext(): Promise<string>;
+    disposeIsolatedContext(browserContextId: string): Promise<void>;
+    groupTabs(pages: Page[], title: string, color: TabGroupColor): Promise<void>;
+    describeTabGroups(pages: Page[]): Promise<TabGroupSummary[]>;
+    readProfileCopy(copyUserDataDir: string, origins: string[]): Promise<{
+        cookies: Cookie[];
+        origins: OriginStorage[];
+    }>;
+    debuggingEndpoint(): DebuggingEndpoint | undefined;
+    openCdpSession(page: Page): Promise<CDPSession>;
+    startTrace(): Promise<void>;
+    stopTrace(path: string): Promise<void>;
+    onClosed(listener: () => void): void;
+    close(): Promise<void>;
+}
+export declare class PatchrightEngine implements BrowserEngine {
+    #private;
+    launch(chromeProfileDir: string, mode: ProfileMode): Promise<void>;
+    openBackgroundPage(browserContextId?: string): Promise<Page>;
+    openForegroundPage(browserContextId?: string): Promise<Page>;
+    cookies(urls: string[] | undefined, browserContextId?: string): Promise<Cookie[]>;
+    addCookies(cookies: Cookie[], browserContextId?: string): Promise<void>;
+    createIsolatedContext(): Promise<string>;
+    disposeIsolatedContext(browserContextId: string): Promise<void>;
+    groupTabs(pages: Page[], title: string, color: TabGroupColor): Promise<void>;
+    describeTabGroups(pages: Page[]): Promise<TabGroupSummary[]>;
+    readProfileCopy(copyUserDataDir: string, origins: string[]): Promise<{
+        cookies: Cookie[];
+        origins: OriginStorage[];
+    }>;
+    debuggingEndpoint(): DebuggingEndpoint | undefined;
+    openCdpSession(page: Page): Promise<CDPSession>;
+    startTrace(): Promise<void>;
+    stopTrace(path: string): Promise<void>;
+    onClosed(listener: () => void): void;
+    close(): Promise<void>;
+}