@opice/browser 0.1.0

package/dist/builtins.d.ts

@@ -0,0 +1,9 @@
+import { type Command } from '@opice/harness';
+export declare const builtins: Command[];
+/**
+ * Positional-argument hints for built-ins, so the ergonomic
+ * `opice-browser click add` works alongside `--selector add`. User verbs from
+ * browser-tools.ts are flag-only.
+ */
+export declare const positionalHints: Record<string, string[]>;
+//# sourceMappingURL=builtins.d.ts.map

package/dist/builtins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,OAAO,EAAmB,MAAM,gBAAgB,CAAA;AA0C1E,eAAO,MAAM,QAAQ,EAAE,OAAO,EA8E7B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAcpD,CAAA"}

package/dist/builtins.js

@@ -0,0 +1,117 @@
+import { command, z } from '@opice/harness';
+/**
+ * Built-in browser verbs for the authoring CLI, defined with the same
+ * `command()` primitive a repo's `browser-tools.ts` uses. The agent drives the
+ * app through these during the dry-run; the test it writes uses the matching
+ * harness DSL — same vocabulary, same Playwright backing.
+ */
+/** Apply an action to a resolved locator (shared by byRole/byLabel/byText). */
+async function applyAction(locator, action, opts) {
+    switch (action) {
+        case 'click':
+            return locator.click();
+        case 'fill':
+            return locator.fill(opts.value ?? '');
+        case 'focus':
+            return locator.focus();
+        case 'hover':
+            return locator.hover();
+        case 'press':
+            return locator.press(opts.key ?? 'Enter');
+        case 'text':
+            return locator.textContent();
+        case 'count':
+            return locator.count();
+        default:
+            throw new Error(`Unknown action "${action}" (click|fill|focus|hover|press|text|count)`);
+    }
+}
+const actionFields = {
+    action: z.string().default('click'),
+    value: z.string().optional(),
+    key: z.string().optional(),
+};
+export const builtins = [
+    command('open', z.object({ url: z.string() }), async ({ page }, { url }) => {
+        await page.goto(url);
+        return page.url();
+    }, 'Navigate to a URL'),
+    command('reload', z.object({}), async ({ page }) => {
+        await page.reload();
+        return page.url();
+    }, 'Reload the current page'),
+    command('back', z.object({}), async ({ page }) => {
+        await page.goBack();
+        return page.url();
+    }, 'Go back in history'),
+    command('forward', z.object({}), async ({ page }) => {
+        await page.goForward();
+        return page.url();
+    }, 'Go forward in history'),
+    command('click', z.object({ selector: z.string() }), async ({ el }, { selector }) => {
+        await el(selector).click();
+    }, 'Click an element (test-id or CSS selector)'),
+    command('fill', z.object({ selector: z.string(), value: z.string() }), async ({ el }, { selector, value }) => {
+        await el(selector).fill(value);
+    }, 'Fill an input/textarea'),
+    command('press', z.object({ key: z.string(), selector: z.string().optional() }), async ({ el, page }, { key, selector }) => {
+        if (selector)
+            await el(selector).press(key);
+        else
+            await page.keyboard.press(key);
+    }, 'Press a key (optionally focusing a selector first)'),
+    command('hover', z.object({ selector: z.string() }), async ({ el }, { selector }) => {
+        await el(selector).hover();
+    }, 'Hover an element'),
+    command('text', z.object({ selector: z.string() }), async ({ el }, { selector }) => {
+        return el(selector).textContent();
+    }, 'Read an element\'s textContent'),
+    command('value', z.object({ selector: z.string() }), async ({ el }, { selector }) => {
+        return el(selector).inputValue();
+    }, 'Read an input\'s value'),
+    command('count', z.object({ selector: z.string() }), async ({ el }, { selector }) => {
+        return el(selector).count();
+    }, 'Count elements matching a selector'),
+    command('byRole', z.object({ role: z.string(), name: z.string().optional(), ...actionFields }), async (ctx, { role, name, action, value, key }) => {
+        return applyAction(ctx.byRole(role, name), action, { value, key });
+    }, 'Resolve by ARIA role (+optional --name) and run --action (default click)'),
+    command('byLabel', z.object({ label: z.string(), ...actionFields }), async (ctx, { label, action, value, key }) => {
+        return applyAction(ctx.byLabel(label), action, { value, key });
+    }, 'Resolve a form control by its <label> and run --action'),
+    command('byText', z.object({ text: z.string(), ...actionFields }), async (ctx, { text, action, value, key }) => {
+        return applyAction(ctx.byText(text), action, { value, key });
+    }, 'Resolve by visible text and run --action'),
+    command('aria-snapshot', z.object({ selector: z.string().optional() }), async ({ page }, { selector }) => {
+        const root = selector ? page.locator(selector) : page.locator('body');
+        return root.ariaSnapshot();
+    }, 'Print the ARIA accessibility tree (YAML) — the agent\'s view of the page'),
+    command('screenshot', z.object({ path: z.string().optional() }), async ({ page }, { path }) => {
+        const target = path ?? `/tmp/opice-browser-${Date.now()}.png`;
+        await page.screenshot({ path: target });
+        return target;
+    }, 'Capture a screenshot'),
+    command('title', z.object({}), async ({ page }) => page.title(), 'Read the document title'),
+    command('url', z.object({}), async ({ page }) => page.url(), 'Read the current URL'),
+    command('eval', z.object({ js: z.string() }), async ({ page }, { js }) => page.evaluate(js), 'Evaluate JS in the page'),
+];
+/**
+ * Positional-argument hints for built-ins, so the ergonomic
+ * `opice-browser click add` works alongside `--selector add`. User verbs from
+ * browser-tools.ts are flag-only.
+ */
+export const positionalHints = {
+    open: ['url'],
+    click: ['selector'],
+    fill: ['selector', 'value'],
+    press: ['key'],
+    hover: ['selector'],
+    text: ['selector'],
+    value: ['selector'],
+    count: ['selector'],
+    byRole: ['role', 'action'],
+    byLabel: ['label', 'action'],
+    byText: ['text', 'action'],
+    'aria-snapshot': ['selector'],
+    eval: ['js'],
+};
+//# sourceMappingURL=builtins.js.map

package/dist/builtins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtins.js","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { loadUserCommands, runCommand, z } from '@opice/harness';
+import { builtins, positionalHints } from './builtins.js';
+import { launch, quit, sessionAlive, setSessionName, withPage } from './session.js';
+// opice-browser must run under Node: Playwright's `connectOverCDP` websocket
+// can't complete its handshake under Bun. However it gets launched (bunx, a
+// bun-created bin shim, `bun run`), re-exec under Node so the verb always works.
+function reexecUnderNodeIfBun() {
+    if (!process.versions['bun'])
+        return;
+    const result = spawnSync('node', [fileURLToPath(import.meta.url), ...process.argv.slice(2)], { stdio: 'inherit' });
+    if (result.error) {
+        console.error('[opice-browser] requires Node on PATH (Playwright CDP does not work under Bun):', result.error.message);
+        process.exit(127);
+    }
+    process.exit(result.status ?? 1);
+}
+const HELP = `opice-browser — stateful Playwright browser for opice authoring
+
+Usage: opice-browser [--session NAME] <command> [positionals] [--flag value]
+
+Sessions: each named session is its own browser (default: "default", or
+$OPICE_BROWSER_SESSION). opice-batch gives each parallel author its own.
+
+Lifecycle:
+  launch [url] [--headed]   Start the persistent browser (idempotent).
+  status                    Show whether a session is alive.
+  quit                      Close the browser and clear the session.
+
+Inspect:
+  commands                  List all verbs (built-in + browser-tools.ts).
+  aria-snapshot [selector]  Print the ARIA tree (the agent's view).
+
+Verbs (examples):
+  open <url>
+  click <selector>                 fill <selector> <value>
+  byRole <role> [action] --name X  byLabel <label> [action]
+  text <selector>                  press <key> [--selector s]
+
+Selectors: a bare word is a data-testid; anything with CSS chars is raw CSS.
+Verbs from <repo>/browser-tools.ts are available too (flag or positional args).
+`;
+function parseArgs(tokens) {
+    const flags = {};
+    const positionals = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.startsWith('--')) {
+            const eq = token.indexOf('=');
+            if (eq >= 0) {
+                flags[token.slice(2, eq)] = token.slice(eq + 1);
+            }
+            else {
+                const key = token.slice(2);
+                const next = tokens[i + 1];
+                if (next !== undefined && !next.startsWith('--')) {
+                    flags[key] = next;
+                    i++;
+                }
+                else {
+                    flags[key] = true;
+                }
+            }
+        }
+        else {
+            positionals.push(token);
+        }
+    }
+    return { flags, positionals };
+}
+/** Field names for positional mapping: explicit hint, else object-schema keys. */
+function positionalNames(name, cmd) {
+    if (positionalHints[name])
+        return positionalHints[name];
+    if (cmd.params instanceof z.ZodObject)
+        return Object.keys(cmd.params.shape);
+    return [];
+}
+function paramSummary(cmd) {
+    if (cmd.params instanceof z.ZodObject) {
+        const keys = Object.keys(cmd.params.shape);
+        return keys.length ? keys.map((k) => `<${k}>`).join(' ') : '(no args)';
+    }
+    return '';
+}
+async function buildRegistry() {
+    const registry = new Map();
+    for (const cmd of builtins)
+        registry.set(cmd.name, cmd);
+    const user = await loadUserCommands();
+    for (const [name, cmd] of user)
+        registry.set(name, cmd); // user verbs override built-ins
+    return registry;
+}
+function printResult(result) {
+    if (result === undefined || result === null) {
+        console.log('ok');
+    }
+    else if (typeof result === 'string') {
+        console.log(result);
+    }
+    else {
+        console.log(JSON.stringify(result));
+    }
+}
+/** Consume a leading `--session NAME` / `--session=NAME` (else env / default). */
+function takeSession(argv) {
+    const first = argv[0];
+    if (first === '--session' && argv[1] !== undefined) {
+        setSessionName(argv[1]);
+        return argv.slice(2);
+    }
+    if (first?.startsWith('--session=')) {
+        setSessionName(first.slice('--session='.length));
+        return argv.slice(1);
+    }
+    return argv;
+}
+async function main(rawArgv) {
+    reexecUnderNodeIfBun();
+    const [name, ...rest] = takeSession(rawArgv);
+    const { flags, positionals } = parseArgs(rest);
+    switch (name) {
+        case undefined:
+        case 'help':
+        case '--help':
+        case '-h':
+            console.log(HELP);
+            return 0;
+        case 'launch': {
+            const session = await launch({ headed: !!flags['headed'], url: positionals[0] });
+            console.error(`[opice-browser] session up (pid ${session.pid}, port ${session.port})`);
+            return 0;
+        }
+        case 'status': {
+            const session = sessionAlive();
+            console.log(session ? `alive (pid ${session.pid}, port ${session.port})` : 'no session');
+            return session ? 0 : 1;
+        }
+        case 'quit':
+        case 'close': {
+            quit();
+            console.error('[opice-browser] session closed');
+            return 0;
+        }
+        case 'commands': {
+            const registry = await buildRegistry();
+            for (const cmd of registry.values()) {
+                const builtin = builtins.some((b) => b.name === cmd.name);
+                const tag = builtin ? '' : ' (user)';
+                console.log(`${cmd.name} ${paramSummary(cmd)}${tag}\n    ${cmd.description ?? ''}`.trimEnd());
+            }
+            return 0;
+        }
+        default: {
+            const registry = await buildRegistry();
+            const cmd = registry.get(name);
+            if (!cmd) {
+                console.error(`Unknown command: ${name}\n`);
+                console.error(HELP);
+                return 1;
+            }
+            const names = positionalNames(name, cmd);
+            const args = { ...flags };
+            positionals.forEach((val, i) => {
+                const key = names[i];
+                if (key && !(key in args))
+                    args[key] = val;
+            });
+            try {
+                const result = await withPage((page) => runCommand(page, cmd, args));
+                printResult(result);
+                return 0;
+            }
+            catch (err) {
+                console.error(`[opice-browser] ${name} failed: ${err instanceof Error ? err.message : String(err)}`);
+                return 1;
+            }
+        }
+    }
+}
+process.exit(await main(process.argv.slice(2)));
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/session.d.ts

@@ -0,0 +1,26 @@
+import { type Page } from 'playwright';
+export declare function setSessionName(name: string): void;
+export interface Session {
+    pid: number;
+    port: number;
+    wsEndpoint: string;
+    userDataDir: string;
+}
+export declare function readSession(): Session;
+/** Is there a live session whose browser process is still running? */
+export declare function sessionAlive(): Session | null;
+export interface LaunchOptions {
+    headed?: boolean;
+    url?: string;
+}
+/** Launch the persistent browser and record the session. Returns the session. */
+export declare function launch(opts?: LaunchOptions): Promise<Session>;
+/** Kill the persistent browser and clear the session. */
+export declare function quit(): void;
+/**
+ * Connect to the live browser, hand its current page to `fn`, then disconnect.
+ * Disconnecting (`browser.close()` on a CDP connection) does NOT terminate the
+ * browser process — the page state persists for the next verb.
+ */
+export declare function withPage<T>(fn: (page: Page) => Promise<T>): Promise<T>;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAKA,OAAO,EAA0B,KAAK,IAAI,EAAE,MAAM,YAAY,CAAA;AAwB9D,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEjD;AAUD,MAAM,WAAW,OAAO;IACvB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;CACnB;AAED,wBAAgB,WAAW,IAAI,OAAO,CAMrC;AAWD,sEAAsE;AACtE,wBAAgB,YAAY,IAAI,OAAO,GAAG,IAAI,CAU7C;AA+BD,MAAM,WAAW,aAAa;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,MAAM,CAAA;CACZ;AAED,iFAAiF;AACjF,wBAAsB,MAAM,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAwBvE;AAED,yDAAyD;AACzD,wBAAgB,IAAI,IAAI,IAAI,CAU3B;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAW5E"}

package/dist/session.js

@@ -0,0 +1,148 @@
+import { spawn } from 'node:child_process';
+import { createServer } from 'node:net';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { chromium } from 'playwright';
+/**
+ * Persistent-browser session for CLI-over-CDP authoring.
+ *
+ * `launch` spawns a real Chrome (the Playwright-managed binary) with a
+ * remote-debugging port, **detached** so it outlives the launching command,
+ * and records the CDP endpoint in a session file. Each subsequent verb
+ * (`open`, `click`, …) connects over CDP, drives the live page, and
+ * disconnects — statefulness lives in the browser process, not in a
+ * long-running Node daemon. `connectOverCDP` is why the CLI runs on Node and
+ * not Bun (Bun's websocket client can't complete the CDP handshake).
+ */
+const SESSION_DIR = path.join(tmpdir(), 'opice-browser');
+/**
+ * Active session name. Multiple named sessions can run side by side, each its
+ * own browser — `opice-batch` gives every parallel author its own so they
+ * don't share a page. Set via `--session NAME` or `OPICE_BROWSER_SESSION`;
+ * defaults to `default`.
+ */
+let sessionName = process.env['OPICE_BROWSER_SESSION'] ?? 'default';
+export function setSessionName(name) {
+    sessionName = name;
+}
+function sessionFile() {
+    return path.join(SESSION_DIR, `${sessionName}.json`);
+}
+function profileDir() {
+    return path.join(SESSION_DIR, `profile-${sessionName}`);
+}
+export function readSession() {
+    const file = sessionFile();
+    if (!existsSync(file)) {
+        throw new Error(`No browser session "${sessionName}". Run \`opice-browser launch\` first.`);
+    }
+    return JSON.parse(readFileSync(file, 'utf-8'));
+}
+function writeSession(session) {
+    mkdirSync(SESSION_DIR, { recursive: true });
+    writeFileSync(sessionFile(), JSON.stringify(session), 'utf-8');
+}
+function clearSession() {
+    rmSync(sessionFile(), { force: true });
+}
+/** Is there a live session whose browser process is still running? */
+export function sessionAlive() {
+    if (!existsSync(sessionFile()))
+        return null;
+    const session = readSession();
+    try {
+        process.kill(session.pid, 0);
+        return session;
+    }
+    catch {
+        clearSession();
+        return null;
+    }
+}
+async function freePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.once('error', reject);
+        srv.listen(0, '127.0.0.1', () => {
+            const addr = srv.address();
+            const port = typeof addr === 'object' && addr ? addr.port : 0;
+            srv.close(() => resolve(port));
+        });
+    });
+}
+async function waitForEndpoint(port, timeoutMs = 15_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetch(`http://127.0.0.1:${port}/json/version`);
+            if (res.ok) {
+                const body = (await res.json());
+                if (body.webSocketDebuggerUrl)
+                    return body.webSocketDebuggerUrl;
+            }
+        }
+        catch {
+            // not up yet
+        }
+        await new Promise((r) => setTimeout(r, 100));
+    }
+    throw new Error(`Chrome did not expose a CDP endpoint on port ${port} within ${timeoutMs}ms`);
+}
+/** Launch the persistent browser and record the session. Returns the session. */
+export async function launch(opts = {}) {
+    const existing = sessionAlive();
+    if (existing)
+        return existing;
+    const port = await freePort();
+    const userDataDir = profileDir();
+    mkdirSync(userDataDir, { recursive: true });
+    const args = [
+        `--remote-debugging-port=${port}`,
+        `--user-data-dir=${userDataDir}`,
+        '--no-first-run',
+        '--no-default-browser-check',
+        ...(opts.headed ? [] : ['--headless=new']),
+        opts.url ?? 'about:blank',
+    ];
+    const child = spawn(chromium.executablePath(), args, { detached: true, stdio: 'ignore' });
+    child.unref();
+    if (child.pid == null)
+        throw new Error('Failed to spawn Chrome');
+    const wsEndpoint = await waitForEndpoint(port);
+    const session = { pid: child.pid, port, wsEndpoint, userDataDir };
+    writeSession(session);
+    return session;
+}
+/** Kill the persistent browser and clear the session. */
+export function quit() {
+    const session = sessionAlive();
+    if (session) {
+        try {
+            process.kill(session.pid);
+        }
+        catch {
+            // already gone
+        }
+    }
+    clearSession();
+}
+/**
+ * Connect to the live browser, hand its current page to `fn`, then disconnect.
+ * Disconnecting (`browser.close()` on a CDP connection) does NOT terminate the
+ * browser process — the page state persists for the next verb.
+ */
+export async function withPage(fn) {
+    const session = readSession();
+    let browser = null;
+    try {
+        browser = await chromium.connectOverCDP(session.wsEndpoint);
+        const context = browser.contexts()[0] ?? (await browser.newContext());
+        const page = context.pages()[0] ?? (await context.newPage());
+        return await fn(page);
+    }
+    finally {
+        await browser?.close();
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "@opice/browser",
+	"version": "0.1.0",
+	"description": "opice-browser — stateful Playwright browser for opice test authoring (CLI over CDP)",
+	"type": "module",
+	"bin": {
+		"opice-browser": "dist/cli.js"
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsc --build",
+		"typecheck": "tsc --build"
+	},
+	"dependencies": {
+		"@opice/harness": "^0.1.0",
+		"playwright": "^1.60.0",
+		"zod": "^4.4.3"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/contember/opice.git",
+		"directory": "packages/browser"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"devDependencies": {
+		"@types/node": "^25.9.1"
+	}
+}