patchrome 0.1.0

package/dist/completions.d.ts

@@ -0,0 +1 @@
+export declare const zshCompletionScript = "#compdef patchrome\n\n_patchrome_profile_args() {\n  local index=${words[(i)--profile]}\n  (( index < CURRENT )) && print -r -- --profile \"${words[index+1]}\"\n}\n\n_patchrome_sessions() {\n  local -a names\n  names=(${(f)\"$(patchrome $(_patchrome_profile_args) sessions 2>/dev/null | awk '$0 != \"no sessions\" {print $1}')\"})\n  (( ${#names} )) && _describe -t sessions 'session' names\n}\n\n_patchrome_tabs() {\n  local -a ids\n  patchrome $(_patchrome_profile_args) sessions >/dev/null 2>&1 || return\n  ids=(${(f)\"$(patchrome $(_patchrome_profile_args) tabs 2>/dev/null | awk '$2 ~ /^t[0-9]+$/ {print $2 \":\" $3}')\"})\n  (( ${#ids} )) && _describe -t tabs 'tab' ids\n}\n\n_patchrome() {\n  local -a commands\n  commands=(\n    'open:new background tab, becomes current'\n    'tabs:list your tabs'\n    'switch:make a tab current'\n    'close:close a tab'\n    'goto:navigate the current tab'\n    'snapshot:accessibility tree with refs'\n    'screenshot:PNG of the current tab'\n    'text:visible text'\n    'eval:run a JS expression'\n    'extract:CSS selectors to JSON rows'\n    'wait:block until the page shows a condition'\n    'watch:stream page events'\n    'click:click a ref or locator'\n    'fill:fill a ref or locator'\n    'press:press a key'\n    'type:type text into the focused element'\n    'challenge:detect a CAPTCHA, or hand it to a person'\n    'network:list, get or record requests'\n    'route:block or mock requests'\n    'login:sign in by hand in a visible tab'\n    'cookies:list cookies'\n    'state:save, load or import login state'\n    'console:console messages (debug profile)'\n    'errors:page errors (debug profile)'\n    'trace:record a Playwright trace (debug profile)'\n    'cdp:raw CDP call or help (debug profile)'\n    'devtools-url:DevTools URL (debug profile)'\n    'profile:create a profile'\n    'session:show, label or close sessions'\n    'sessions:list sessions'\n    'daemon:status, stop or logs'\n    'audit:recent login copies and their approvals'\n    'pipe:run JSON requests from stdin'\n    'completions:print a shell completion script'\n  )\n\n  local -a locator_args\n  locator_args=(\n    '--role[ARIA role]:role:(button link textbox checkbox radio combobox option heading listitem row cell tab menuitem dialog img)'\n    '--name[accessible name, with --role]:name:'\n    '--text[visible text]:text:'\n    '--label[form label]:text:'\n    '--selector[CSS selector]:css:'\n    '--exact[match the whole name or text]'\n    '--nth[pick the nth match, from 0]:n:'\n    '--frame[iframe CSS selector]:css:'\n  )\n\n  _arguments -C \\\n    '--profile[browser profile]:profile:' \\\n    '--session[session name]:session:_patchrome_sessions' \\\n    '--json[print JSON]' \\\n    '--timeout-ms[timeout in ms]:ms:' \\\n    '1: :->command' \\\n    '*:: :->args' && return\n\n  case $state in\n    command) _describe -t commands 'patchrome command' commands ;;\n    args)\n      case $words[1] in\n        switch|close) _patchrome_tabs ;;\n        sessions) _patchrome_sessions ;;\n        session)\n          if (( CURRENT == 2 )); then _values 'action' label close history\n          elif [[ $words[2] == history ]]; then _arguments '--format[script format]:format:(sh jsonl)' '--out[write to a file]:file:_files'\n          elif [[ $words[2] == close ]]; then _patchrome_sessions\n          fi\n          ;;\n        network) (( CURRENT == 2 )) && _values 'action' list get har ;;\n        route) (( CURRENT == 2 )) && _values 'action' block mock list clear ;;\n        state) (( CURRENT == 2 )) && _values 'action' save load import ;;\n        trace) (( CURRENT == 2 )) && _values 'action' start stop ;;\n        daemon) (( CURRENT == 2 )) && _values 'action' status stop logs ;;\n        cdp) (( CURRENT == 2 )) && _values 'action' help ;;\n        completions) _values 'shell' zsh ;;\n        wait) _arguments $locator_args '--url[URL glob]:glob:' '--title[title text]:text:' '--gone[wait for it to go away]' '--load[load state]:state:(load domcontentloaded networkidle)' ;;\n        click) _arguments $locator_args '--at[viewport point]:x,y:' ;;\n        fill) _arguments $locator_args ;;\n        text|screenshot|extract|eval) _arguments $locator_args '--inline[print the value]' '--out[write to a file]:file:_files' ;;\n        pipe) _arguments '--bail[stop at the first failure]' ;;\n        challenge) _arguments '--handoff[raise the tab and wait for a person]' ;;\n        watch) _arguments '--events[event kinds]:events:_values -s , event navigation load response console error' '--url[URL glob]:glob:' '--count[stop after n events]:n:' ;;\n      esac\n      ;;\n  esac\n}\n\ncompdef _patchrome patchrome\n";

package/dist/completions.js

@@ -0,0 +1,114 @@
+// Printed by `patchrome completions zsh`. Session names and tab ids come from the running daemon as
+// you type; with no daemon running they are left out, and completion never starts Chrome.
+export const zshCompletionScript = `#compdef patchrome
+
+_patchrome_profile_args() {
+  local index=\${words[(i)--profile]}
+  (( index < CURRENT )) && print -r -- --profile "\${words[index+1]}"
+}
+
+_patchrome_sessions() {
+  local -a names
+  names=(\${(f)"$(patchrome $(_patchrome_profile_args) sessions 2>/dev/null | awk '$0 != "no sessions" {print $1}')"})
+  (( \${#names} )) && _describe -t sessions 'session' names
+}
+
+_patchrome_tabs() {
+  local -a ids
+  patchrome $(_patchrome_profile_args) sessions >/dev/null 2>&1 || return
+  ids=(\${(f)"$(patchrome $(_patchrome_profile_args) tabs 2>/dev/null | awk '$2 ~ /^t[0-9]+$/ {print $2 ":" $3}')"})
+  (( \${#ids} )) && _describe -t tabs 'tab' ids
+}
+
+_patchrome() {
+  local -a commands
+  commands=(
+    'open:new background tab, becomes current'
+    'tabs:list your tabs'
+    'switch:make a tab current'
+    'close:close a tab'
+    'goto:navigate the current tab'
+    'snapshot:accessibility tree with refs'
+    'screenshot:PNG of the current tab'
+    'text:visible text'
+    'eval:run a JS expression'
+    'extract:CSS selectors to JSON rows'
+    'wait:block until the page shows a condition'
+    'watch:stream page events'
+    'click:click a ref or locator'
+    'fill:fill a ref or locator'
+    'press:press a key'
+    'type:type text into the focused element'
+    'challenge:detect a CAPTCHA, or hand it to a person'
+    'network:list, get or record requests'
+    'route:block or mock requests'
+    'login:sign in by hand in a visible tab'
+    'cookies:list cookies'
+    'state:save, load or import login state'
+    'console:console messages (debug profile)'
+    'errors:page errors (debug profile)'
+    'trace:record a Playwright trace (debug profile)'
+    'cdp:raw CDP call or help (debug profile)'
+    'devtools-url:DevTools URL (debug profile)'
+    'profile:create a profile'
+    'session:show, label or close sessions'
+    'sessions:list sessions'
+    'daemon:status, stop or logs'
+    'audit:recent login copies and their approvals'
+    'pipe:run JSON requests from stdin'
+    'completions:print a shell completion script'
+  )
+
+  local -a locator_args
+  locator_args=(
+    '--role[ARIA role]:role:(button link textbox checkbox radio combobox option heading listitem row cell tab menuitem dialog img)'
+    '--name[accessible name, with --role]:name:'
+    '--text[visible text]:text:'
+    '--label[form label]:text:'
+    '--selector[CSS selector]:css:'
+    '--exact[match the whole name or text]'
+    '--nth[pick the nth match, from 0]:n:'
+    '--frame[iframe CSS selector]:css:'
+  )
+
+  _arguments -C \\
+    '--profile[browser profile]:profile:' \\
+    '--session[session name]:session:_patchrome_sessions' \\
+    '--json[print JSON]' \\
+    '--timeout-ms[timeout in ms]:ms:' \\
+    '1: :->command' \\
+    '*:: :->args' && return
+
+  case $state in
+    command) _describe -t commands 'patchrome command' commands ;;
+    args)
+      case $words[1] in
+        switch|close) _patchrome_tabs ;;
+        sessions) _patchrome_sessions ;;
+        session)
+          if (( CURRENT == 2 )); then _values 'action' label close history
+          elif [[ $words[2] == history ]]; then _arguments '--format[script format]:format:(sh jsonl)' '--out[write to a file]:file:_files'
+          elif [[ $words[2] == close ]]; then _patchrome_sessions
+          fi
+          ;;
+        network) (( CURRENT == 2 )) && _values 'action' list get har ;;
+        route) (( CURRENT == 2 )) && _values 'action' block mock list clear ;;
+        state) (( CURRENT == 2 )) && _values 'action' save load import ;;
+        trace) (( CURRENT == 2 )) && _values 'action' start stop ;;
+        daemon) (( CURRENT == 2 )) && _values 'action' status stop logs ;;
+        cdp) (( CURRENT == 2 )) && _values 'action' help ;;
+        completions) _values 'shell' zsh ;;
+        wait) _arguments $locator_args '--url[URL glob]:glob:' '--title[title text]:text:' '--gone[wait for it to go away]' '--load[load state]:state:(load domcontentloaded networkidle)' ;;
+        click) _arguments $locator_args '--at[viewport point]:x,y:' ;;
+        fill) _arguments $locator_args ;;
+        text|screenshot|extract|eval) _arguments $locator_args '--inline[print the value]' '--out[write to a file]:file:_files' ;;
+        pipe) _arguments '--bail[stop at the first failure]' ;;
+        challenge) _arguments '--handoff[raise the tab and wait for a person]' ;;
+        watch) _arguments '--events[event kinds]:events:_values -s , event navigation load response console error' '--url[URL glob]:glob:' '--count[stop after n events]:n:' ;;
+      esac
+      ;;
+  esac
+}
+
+compdef _patchrome patchrome
+`;

package/dist/copy-guard.d.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+export declare const copyKinds: readonly ["state-import", "state-load", "state-save"];
+export type CopyKind = (typeof copyKinds)[number];
+export declare const approvalAnswers: readonly ["approved", "denied", "timed_out", "unavailable"];
+export type ApprovalAnswer = (typeof approvalAnswers)[number];
+export declare const copyDecisions: readonly ["approved", "denied", "timed_out", "unavailable", "not_asked"];
+export type CopyDecision = (typeof copyDecisions)[number];
+export declare const approvalTimeoutMs = 60000;
+export interface CopyRequest {
+    kind: CopyKind;
+    session: string;
+    source: string;
+    target: string;
+    site: string | undefined;
+    cookies: number;
+    origins: string[];
+}
+export interface HostPrompts {
+    askApproval(reason: string, timeoutMs: number): Promise<{
+        answer: ApprovalAnswer;
+        detail: string | undefined;
+    }>;
+    notify(title: string, body: string): Promise<void>;
+}
+declare const auditEntrySchema: z.ZodObject<{
+    atUtc: z.ZodString;
+    profile: z.ZodString;
+    kind: z.ZodEnum<{
+        "state-import": "state-import";
+        "state-load": "state-load";
+        "state-save": "state-save";
+    }>;
+    session: z.ZodString;
+    source: z.ZodString;
+    target: z.ZodString;
+    site: z.ZodOptional<z.ZodString>;
+    cookies: z.ZodNumber;
+    origins: z.ZodArray<z.ZodString>;
+    decision: z.ZodEnum<{
+        approved: "approved";
+        denied: "denied";
+        not_asked: "not_asked";
+        timed_out: "timed_out";
+        unavailable: "unavailable";
+    }>;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AuditEntry = z.infer<typeof auditEntrySchema>;
+export interface CopyGuardOptions {
+    prompts: HostPrompts;
+    auditLogPath: string;
+    profile: string;
+    log: (message: string) => void;
+    nowMs?: () => number;
+}
+export declare class CopyGuard {
+    #private;
+    constructor(options: CopyGuardOptions);
+    requireApproval(request: CopyRequest): Promise<void>;
+    recordUnasked(request: CopyRequest): Promise<void>;
+}
+export declare function shouldNotify(decision: CopyDecision): boolean;
+export declare function describeCopy(request: CopyRequest): string;
+export declare function approvalReason(request: CopyRequest): string;
+export declare function helperFailure(helper: string, err: unknown): string;
+export declare function parseApprovalAnswer(stdout: string): {
+    answer: ApprovalAnswer;
+    detail: string | undefined;
+};
+export declare function readAuditLog(path: string): Promise<{
+    entries: AuditEntry[];
+    unreadableLines: number[];
+}>;
+export declare function auditLine(entry: AuditEntry): string;
+export {};

package/dist/copy-guard.js

@@ -0,0 +1,167 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname } from "node:path";
+import { z } from "zod";
+import { CommandError } from "./protocol.js";
+// Commands that move logins between a patchrome profile and somewhere else. Loading data in waits for a
+// person; saving it out only leaves a record, so an agent that saves often does not raise prompts.
+export const copyKinds = ["state-import", "state-load", "state-save"];
+// What the person answered, or why nobody could be asked.
+export const approvalAnswers = ["approved", "denied", "timed_out", "unavailable"];
+export const copyDecisions = [...approvalAnswers, "not_asked"];
+export const approvalTimeoutMs = 60_000;
+const auditEntrySchema = z.object({
+    atUtc: z.string(),
+    profile: z.string(),
+    kind: z.enum(copyKinds),
+    session: z.string(),
+    source: z.string(),
+    target: z.string(),
+    site: z.string().optional(),
+    cookies: z.number(),
+    origins: z.array(z.string()),
+    decision: z.enum(copyDecisions),
+    detail: z.string().optional(),
+});
+export class CopyGuard {
+    #options;
+    // One prompt at a time, so two agents importing together never stack two Touch ID dialogs.
+    #turns = Promise.resolve();
+    constructor(options) {
+        this.#options = options;
+    }
+    async requireApproval(request) {
+        const turn = this.#turns.then(() => this.#decide(request));
+        this.#turns = turn.catch(() => { });
+        const { decision, detail } = await turn;
+        switch (decision) {
+            case "approved":
+                return;
+            case "denied":
+            case "timed_out":
+            case "unavailable":
+                throw new CommandError("copy_denied", `${describeCopy(request)} was not approved: ${decision.replace("_", " ")}${detail === undefined ? "" : `, ${detail}`}`, "the user must approve this copy at the prompt; tell them, and do not retry or copy the data another way");
+            case "not_asked":
+                throw new Error(`a ${request.kind} approval cannot end as not_asked`);
+        }
+    }
+    async recordUnasked(request) {
+        await this.#record(request, "not_asked", undefined);
+        await this.#notify(request, "not_asked");
+    }
+    async #decide(request) {
+        const { answer: decision, detail } = await this.#options.prompts
+            .askApproval(approvalReason(request), approvalTimeoutMs)
+            .catch((err) => ({
+            answer: "unavailable",
+            detail: err instanceof Error ? err.message.split("\n")[0] : String(err),
+        }));
+        // Fails the command when the record cannot be written: an unrecorded copy is what the log exists to prevent.
+        await this.#record(request, decision, detail);
+        await this.#notify(request, decision);
+        return { decision, detail };
+    }
+    async #record(request, decision, detail) {
+        const entry = {
+            atUtc: new Date((this.#options.nowMs ?? Date.now)()).toISOString(),
+            profile: this.#options.profile,
+            kind: request.kind,
+            session: request.session,
+            source: request.source,
+            target: request.target,
+            ...(request.site === undefined ? {} : { site: request.site }),
+            cookies: request.cookies,
+            origins: request.origins,
+            decision,
+            ...(detail === undefined ? {} : { detail }),
+        };
+        await mkdir(dirname(this.#options.auditLogPath), { recursive: true });
+        await appendFile(this.#options.auditLogPath, `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+        this.#options.log(`copy ${decision}: ${describeCopy(request)} for ${request.session}`);
+    }
+    // A person who just answered the prompt already knows; everything else gets a notification.
+    async #notify(request, decision) {
+        if (!shouldNotify(decision))
+            return;
+        await this.#options.prompts
+            .notify(`patchrome copy ${decision.replace("_", " ")}`, `${request.session}: ${describeCopy(request)}`)
+            .catch((err) => this.#options.log(`copy notification failed: ${String(err).split("\n")[0]}`));
+    }
+}
+export function shouldNotify(decision) {
+    switch (decision) {
+        case "approved":
+        case "denied":
+            return false;
+        case "timed_out":
+        case "unavailable":
+        case "not_asked":
+            return true;
+    }
+}
+export function describeCopy(request) {
+    const counts = [
+        plural(request.cookies, "cookie"),
+        ...(request.origins.length === 0 ? [] : [`storage for ${plural(request.origins.length, "origin")}`]),
+    ].join(" and ");
+    const what = request.site === undefined ? counts : `the ${request.site} login (${counts})`;
+    switch (request.kind) {
+        case "state-import":
+            return `import ${what} from ${request.source} into ${request.target}`;
+        case "state-load":
+            return `load ${what} from ${request.source} into ${request.target}`;
+        case "state-save":
+            return `save ${what} from ${request.source} to ${request.target}`;
+    }
+}
+// macOS shows this after "patchrome is trying to", Windows Hello shows it as the dialog's message.
+export function approvalReason(request) {
+    const home = homedir();
+    const described = describeCopy(request).replaceAll(`${home}/`, "~/");
+    return `${described}. Asked by agent session ${request.session}.`;
+}
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+// A killed or missing helper says why in one line, without echoing the script it was given.
+export function helperFailure(helper, err) {
+    const failure = err;
+    if (failure.code === "ENOENT")
+        return `${helper} not found`;
+    if (failure.killed === true || failure.signal)
+        return `${helper} stopped by ${failure.signal ?? "timeout"}`;
+    const stderr = (err.stderr ?? "").toString().trim().split("\n")[0];
+    return `${helper} exited with ${String(failure.code)}${stderr ? `: ${stderr}` : ""}`;
+}
+// Platform helpers print one answer word, optionally followed by a detail.
+export function parseApprovalAnswer(stdout) {
+    const text = stdout.trim();
+    const [word = "", ...rest] = text.split(/\s+/);
+    const answer = approvalAnswers.find((candidate) => candidate === word);
+    if (answer === undefined)
+        return { answer: "unavailable", detail: `unreadable prompt answer: ${text.slice(0, 200)}` };
+    return { answer, detail: rest.length === 0 ? undefined : rest.join(" ") };
+}
+export async function readAuditLog(path) {
+    const raw = await readFile(path, "utf8").catch((err) => {
+        if (err.code === "ENOENT")
+            return "";
+        throw err;
+    });
+    const entries = [];
+    const unreadableLines = [];
+    raw.split("\n").forEach((line, index) => {
+        if (line.trim() === "")
+            return;
+        try {
+            entries.push(auditEntrySchema.parse(JSON.parse(line)));
+        }
+        catch {
+            unreadableLines.push(index + 1);
+        }
+    });
+    return { entries, unreadableLines };
+}
+export function auditLine(entry) {
+    return `${entry.atUtc} ${entry.decision} ${entry.session}: ${describeCopy({ ...entry, site: entry.site })}${entry.detail === undefined ? "" : ` (${entry.detail})`}`;
+}

package/dist/daemon.d.ts

@@ -0,0 +1,7 @@
+import { type HostPrompts } from "./copy-guard.ts";
+export interface DaemonOptions {
+    prompts?: HostPrompts;
+    exitProcess?: (code: number) => void;
+}
+export declare function runDaemon(profile: string, env?: NodeJS.ProcessEnv, options?: DaemonOptions): Promise<void>;
+export declare function isClosedTargetRejection(reason: unknown): boolean;