@oomfware/cbr 0.1.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@oomfware/cbr",
+  "version": "0.1.0",
+  "description": "ask questions by browsing the web using Claude Code",
+  "license": "0BSD",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/oomfware/cbr"
+  },
+  "bin": {
+    "cbr": "./dist/index.mjs"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "!src/**/*.bench.ts",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@optique/core": "^0.10.6",
+    "@optique/run": "^0.10.6",
+    "playwright": "^1.58.2",
+    "valibot": "^1.2.0",
+    "yocto-spinner": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "bumpp": "^10.4.1",
+    "oxfmt": "^0.35.0",
+    "oxlint": "^1.50.0",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "fmt": "oxfmt",
+    "lint": "oxlint"
+  }
+}

package/src/assets/system-prompt.md

@@ -0,0 +1,147 @@
+You are a browser automation assistant controlling a Chromium browser through the `browser` command
+to accomplish tasks on the web. Your job is to find real, current information — don't rely on your
+built-in knowledge. Go to the source, read what's there, and report what you find.
+
+You also have access to `WebSearch`. Use it to discover relevant web pages, then use the browser to
+visit pages, read content, and interact with them.
+
+## Available commands
+
+Run commands with `browser <command> [args...] [--flags]`.
+
+**Navigation** (blocking — waits for the DOM to be ready before returning):
+
+- `browser open <url>` — navigate to a URL
+- `browser back` / `browser forward` — history navigation
+- `browser reload` — reload the current page
+
+**Observation:**
+
+- `browser snapshot` — get the accessibility tree with element refs (`@e1`, `@e2`, ...)
+  - `--interactive` — only show interactive elements (buttons, links, inputs, etc.)
+  - `--compact` — strip empty structural elements for a shorter tree
+  - `--depth <n>` — limit tree depth
+  - `--selector <css>` — scope to a specific element
+- `browser screenshot [name]` — take a screenshot, saved to `screenshots/[name].png`. read the file
+  to view it.
+  - `--full` — capture full page
+- `browser get url` / `browser get title` — page info
+- `browser get text <sel>` / `browser get html <sel>` / `browser get value <sel>` — element content
+- `browser get attr <sel> <attr>` — element attribute
+- `browser get count <sel>` — count matching elements
+
+**Interaction:**
+
+- `browser click <sel>` / `browser dblclick <sel>` — click elements
+- `browser fill <sel> <text>` — clear and fill an input
+- `browser type <sel> <text>` — type character by character (for autocomplete, search-as-you-type)
+- `browser press <key>` — press a keyboard key (e.g. `Enter`, `Tab`, `Escape`, `ArrowDown`)
+- `browser hover <sel>` — hover over an element
+- `browser select <sel> <value>` — select a dropdown option
+- `browser check <sel>` / `browser uncheck <sel>` — toggle checkboxes
+
+**State checks:**
+
+- `browser is visible <sel>` / `browser is enabled <sel>` / `browser is checked <sel>`
+
+**Waiting** (default timeout: 5s):
+
+- `browser wait for <sel>` — wait for an element to become visible
+- `browser wait for-text "..."` — wait for text to appear on the page
+- `browser wait for-url "..."` — wait for the URL to match a pattern
+- `--hidden` — wait for the element/text to disappear instead
+- `--timeout <ms>` — override the default 5s timeout
+
+**Scrolling:**
+
+- `browser scroll down` / `browser scroll up` — scroll the page
+- `browser scroll down <sel>` — scroll within a specific container
+
+**Frames and tabs:**
+
+- `browser frame list` — list all frames with IDs (`f1`, `f2`, ...), URLs, and parent info
+- `browser frame <id>` — switch into a frame by ID (e.g. `browser frame f2`)
+- `browser frame main` — switch back to main frame
+- `browser tab list` — list open tabs
+- `browser tab new [url]` — open a new tab and switch to it
+- `browser tab <n>` — switch to tab by index
+- `browser tab close [n]` — close a tab
+
+**Source inspection:**
+
+- `browser source [selector]` — get the full page HTML, or a specific element's outer HTML
+- `browser resources [type]` — list all loaded resources (scripts, stylesheets, images, fonts) with
+  URLs and sizes. filter by type: `script`, `link`, `css`, `img`, `font`, `fetch`, `xmlhttprequest`
+- `browser styles <sel> [property]` — get computed styles for an element. without a property,
+  returns a curated set (color, font, layout, spacing). with a property, returns that specific value
+- `browser download <url> [filename]` — download a resource to `assets/`. uses the page's cookies
+  and auth context. filename is inferred from the URL if not provided
+
+**JavaScript:**
+
+- `browser eval <code>` — evaluate JavaScript in the page and print the result (objects are
+  JSON-stringified). useful for extracting structured data that's hard to read from the
+  accessibility tree
+
+**Lifecycle:**
+
+- `browser close` — close the current tab
+
+**Selectors:**
+
+- **Refs** from snapshot: `@e1`, `@e3` — assigned by `browser snapshot`, refer to specific elements
+  in the accessibility tree
+- **CSS selectors**: `#login-form`, `.submit-btn`, `input[name="email"]`
+
+Prefer refs — they're more robust than CSS selectors. Always snapshot first to get fresh refs.
+
+## Guidelines
+
+**Be direct**: Do the task, don't narrate your process. Skip preamble like "I now have everything I
+need." or "Let me compile the full summary for you."
+
+**Observe first**: Don't guess what's on the page. Run `browser snapshot` to see what's there before
+interacting — the full tree includes both content and interactive elements. Use `--interactive` when
+you already understand the page and just need actionable elements. After any action that changes the
+page, snapshot again as elements can shift and result in refs going stale.
+
+**Deliver useful results**: Include URLs, page titles, and relevant data so the user can pick up
+where you left off. Explain why your findings matter and how they connect to the question — Don't
+just describe what's on the page. briefly mention related pages, alternative sources, or context
+that could change the answer, so the user can ask informed follow-ups.
+
+**Admit uncertainty**: If you can't find something, a page is confusing, or you're unsure whether an
+action succeeded, say so. Explain what you tried and what you observed.
+
+**Prefer snapshots over screenshots**: Snapshots are faster and more informative for most tasks.
+save screenshots for when you specifically need visual layout or content that isn't represented in
+the accessibility tree.
+
+**Navigation is blocking**: `open`, `back`, `forward`, and `reload` wait for the DOM to load before
+returning. Use `wait` commands only for dynamic content that loads after the initial page. the 5s
+default timeout is usually enough — try it before increasing, and re-snapshot on timeout to
+understand what happened.
+
+**Fill vs type**: use `fill` to set input values (clears first), `type` for character-by-character
+input (autocomplete, search-as-you-type).
+
+**Handle CAPTCHAs**: Attempt simple "click to confirm" challenges. If a CAPTCHA fails or requires
+more complex interaction, say so and move on.
+
+**Use `scratch/` for notes**: Save extracted data, intermediate results, or working notes to the
+`scratch/` directory.
+
+**Use `assets/` for downloads**: Downloaded resources (images, scripts, stylesheets, etc.) are saved
+to the `assets/` directory via `browser download`.
+
+**Process data with CLI tools**: You have access to standard text processing utilities for working
+with downloaded assets and extracted data. Use them to filter, transform, and analyze content:
+
+- Text processing: `awk`, `cut`, `grep`, `sed`, `sort`, `tr`, `uniq`, `paste`, `column`, `diff`,
+  `jq`
+- File inspection: `cat`, `head`, `tail`, `wc`, `file`, `stat`, `du`
+- Filesystem: `ls`, `find`, `tree`, `mkdir`, `basename`, `dirname`, `realpath`
+- Composition: `xargs`, `tee`
+
+Combine these with `browser eval` and `browser download` to extract structured data from pages and
+process it locally — e.g. download a CSV, then use `awk`/`sort`/`uniq` to summarize it.

package/src/client.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+import { randomUUID } from 'node:crypto';
+import { connect } from 'node:net';
+
+const args = process.argv.slice(2);
+
+// extract --socket flag
+let socketPath: string | undefined;
+const rest: string[] = [];
+
+for (let i = 0; i < args.length; i++) {
+	if (args[i] === '--socket' && i + 1 < args.length) {
+		socketPath = args[++i];
+	} else {
+		rest.push(args[i]!);
+	}
+}
+
+if (!socketPath) {
+	console.error(`error: --socket is required`);
+	process.exit(1);
+}
+
+if (rest.length === 0) {
+	console.error(`usage: browser <command> [args...]`);
+	process.exit(1);
+}
+
+const request = JSON.stringify({
+	id: randomUUID(),
+	args: rest,
+});
+
+const socket = connect(socketPath);
+let data = '';
+
+socket.on('connect', () => {
+	socket.write(request + '\n');
+});
+
+socket.on('data', (chunk: Buffer) => {
+	data += chunk.toString();
+});
+
+socket.on('end', () => {
+	try {
+		const response = JSON.parse(data.trim());
+		if (response.ok) {
+			if (response.data) {
+				process.stdout.write(response.data);
+				// ensure trailing newline
+				if (!response.data.endsWith('\n')) {
+					process.stdout.write('\n');
+				}
+			}
+		} else {
+			console.error(response.error ?? 'unknown error');
+			process.exit(1);
+		}
+	} catch {
+		console.error(`error: invalid response from server`);
+		process.exit(1);
+	}
+});
+
+socket.on('error', (err: Error) => {
+	console.error(`error: could not connect to browser server: ${err.message}`);
+	process.exit(1);
+});

package/src/commands/ask.ts

@@ -0,0 +1,202 @@
+import { type ChildProcess, spawn } from 'node:child_process';
+import { join } from 'node:path';
+
+import {
+	argument,
+	choice,
+	constant,
+	flag,
+	type InferValue,
+	message,
+	object,
+	option,
+	string,
+} from '@optique/core';
+import { optional, withDefault } from '@optique/core/modifiers';
+import { type Browser, chromium } from 'playwright';
+import yoctoSpinner from 'yocto-spinner';
+
+import { createCommandHandler } from '../lib/commands.ts';
+import type { BrowserState } from '../lib/commands/_types.ts';
+import { cleanupSessionDir, createSessionDir, gcSessions } from '../lib/paths.ts';
+import { startServer } from '../lib/server.ts';
+import { writeBrowserShim, writeSessionSettings } from '../lib/session.ts';
+
+// resolve asset paths relative to the bundle (dist/index.mjs -> dist/assets/)
+const assetsDir = join(import.meta.dirname, 'assets');
+const systemPromptPath = join(assetsDir, 'system-prompt.md');
+
+// client script lives next to index.mjs in dist/
+const clientScriptPath = join(import.meta.dirname, 'client.mjs');
+
+export const schema = object({
+	command: constant('ask'),
+	model: withDefault(
+		option('-m', '--model', choice(['opus', 'sonnet', 'haiku']), {
+			description: message`model to use`,
+		}),
+		'sonnet',
+	),
+	headful: withDefault(
+		flag('--headful', {
+			description: message`show browser window (default: headless)`,
+		}),
+		false,
+	),
+	url: optional(
+		option('--url', string(), {
+			description: message`starting URL to navigate to`,
+		}),
+	),
+	task: argument(string({ metavar: 'TASK' }), {
+		description: message`what to accomplish in the browser`,
+	}),
+});
+
+export type Args = InferValue<typeof schema>;
+
+/**
+ * spawns Claude Code as a child process.
+ * @param cwd working directory
+ * @param args command arguments
+ * @param contextPrompt additional context to append to the system prompt
+ * @returns the child process
+ */
+const spawnClaude = (cwd: string, args: Args, contextPrompt: string): ChildProcess => {
+	const claudeArgs = [
+		'-p',
+		args.task,
+		'--no-session-persistence',
+		'--model',
+		args.model,
+		'--system-prompt-file',
+		systemPromptPath,
+		'--append-system-prompt',
+		contextPrompt,
+	];
+
+	return spawn('claude', claudeArgs, {
+		cwd,
+		stdio: ['ignore', 'pipe', 'inherit'],
+		env: { ...process.env, CLAUDECODE: '' },
+	});
+};
+
+/**
+ * waits for a child process to exit, collecting its stdout.
+ * @param child the child process
+ * @returns promise that resolves with exit code and collected stdout
+ */
+const waitForExit = (child: ChildProcess): Promise<{ code: number; stdout: string }> => {
+	return new Promise((resolve, reject) => {
+		const chunks: Buffer[] = [];
+		child.stdout?.on('data', (chunk: Buffer) => {
+			chunks.push(chunk);
+		});
+		child.on('close', (code) => resolve({ code: code ?? 0, stdout: Buffer.concat(chunks).toString() }));
+		child.on('error', (err) => reject(new Error(`failed to summon claude: ${err}`)));
+	});
+};
+
+/**
+ * handles the ask command.
+ * launches a browser, starts the IPC server, and spawns Claude Code.
+ * @param args parsed command arguments
+ */
+export const handler = async (args: Args): Promise<void> => {
+	// fire-and-forget cleanup of orphaned sessions
+	gcSessions();
+
+	// create session directory with subdirectories
+	const sessionPath = await createSessionDir();
+	const socketPath = join(sessionPath, '.sock');
+	let exitCode = 1;
+	let claudeOutput = '';
+	let browser: Browser | undefined;
+	let claude: ChildProcess | undefined;
+
+	// handle Ctrl+C — kill child, clean up, and exit
+	const onSignal = () => {
+		if (claude) {
+			claude.kill('SIGTERM');
+		}
+		spin.stop('interrupted');
+		if (browser) {
+			browser.close().catch(() => {});
+		}
+		cleanupSessionDir(sessionPath).finally(() => {
+			process.exit(130);
+		});
+	};
+	process.on('SIGINT', onSignal);
+	process.on('SIGTERM', onSignal);
+
+	const spin = yoctoSpinner({
+		text: args.headful ? 'launching browser (headful)' : 'launching browser',
+	}).start();
+
+	try {
+		browser = await chromium.launch({ headless: !args.headful });
+		const context = await browser.newContext();
+		const page = await context.newPage();
+
+		// navigate to starting URL if provided
+		if (args.url) {
+			spin.text = `navigating to ${args.url}`;
+			await page.goto(args.url, { waitUntil: 'domcontentloaded' });
+		}
+
+		// set up browser state — spinner is shared so commands can update it
+		const state: BrowserState = {
+			context,
+			page,
+			refs: {},
+			frameRefs: {},
+			assetsDir: join(sessionPath, 'assets'),
+			screenshotDir: join(sessionPath, 'screenshots'),
+			screenshotCounter: 0,
+			spinner: spin,
+		};
+
+		// start IPC server
+		spin.text = 'starting session';
+		const cmdHandler = createCommandHandler(state);
+		const server = await startServer(socketPath, cmdHandler);
+
+		// write session files
+		await writeBrowserShim(sessionPath, clientScriptPath, socketPath);
+		await writeSessionSettings(sessionPath);
+
+		// build context prompt
+		const contextParts: string[] = [];
+		if (args.url) {
+			contextParts.push(`The browser is already open at: ${args.url}`);
+		}
+		const contextPrompt = contextParts.length > 0 ? contextParts.join('\n') : '';
+
+		spin.text = 'summoning claude';
+
+		// spawn Claude Code — stdout is piped and printed after cleanup
+		claude = spawnClaude(sessionPath, args, contextPrompt);
+		const result = await waitForExit(claude);
+		exitCode = result.code;
+		claudeOutput = result.stdout;
+
+		// teardown
+		server.close();
+	} finally {
+		process.off('SIGINT', onSignal);
+		process.off('SIGTERM', onSignal);
+		spin.stop();
+
+		if (browser) {
+			await browser.close().catch(() => {});
+		}
+		await cleanupSessionDir(sessionPath);
+	}
+
+	if (claudeOutput) {
+		process.stdout.write(claudeOutput);
+	}
+	process.exit(exitCode);
+};

package/src/commands/clean.ts

@@ -0,0 +1,18 @@
+import { constant, type InferValue, object } from '@optique/core';
+
+import { gcSessions } from '../lib/paths.ts';
+
+export const schema = object({
+	command: constant('clean'),
+});
+
+export type Args = InferValue<typeof schema>;
+
+/**
+ * handles the clean command.
+ * garbage collects orphaned session directories.
+ * @param _args parsed command arguments
+ */
+export const handler = async (_args: Args): Promise<void> => {
+	await gcSessions();
+};

package/src/index.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import { command, message, or } from '@optique/core';
+import { run } from '@optique/run';
+
+import manifest from '../package.json' with { type: 'json' };
+
+import * as ask from './commands/ask.ts';
+import * as clean from './commands/clean.ts';
+
+const parser = or(
+	command('ask', ask.schema, {
+		description: message`ask a question by browsing the web with Claude Code`,
+	}),
+	command('clean', clean.schema, {
+		description: message`remove cached session data`,
+	}),
+);
+
+const result = run(parser, {
+	programName: 'cbr',
+	help: 'both',
+	version: { value: manifest.version, mode: 'both' },
+	brief: message`ask questions by browsing the web using Claude Code`,
+});
+
+switch (result.command) {
+	case 'ask':
+		await ask.handler(result);
+		break;
+	case 'clean':
+		await clean.handler(result);
+		break;
+}

package/src/lib/commands/_types.ts

@@ -0,0 +1,24 @@
+import type { BrowserContext, Frame, Page } from 'playwright';
+import type { Spinner } from 'yocto-spinner';
+
+import type { RefMap } from '../snapshot.ts';
+
+/** mutable state shared across commands within a session */
+export interface BrowserState {
+	context: BrowserContext;
+	page: Page;
+	refs: RefMap;
+	frameRefs: Record<string, Frame>;
+	assetsDir: string;
+	screenshotDir: string;
+	screenshotCounter: number;
+	spinner: Spinner;
+}
+
+/** intentional, user-facing error thrown by command handlers */
+export class CommandError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'CommandError';
+	}
+}

package/src/lib/commands/_utils.ts

@@ -0,0 +1,38 @@
+import { basename } from 'node:path';
+
+import type { Locator } from 'playwright';
+
+import { resolveLocator } from '../snapshot.ts';
+
+import type { BrowserState } from './_types.ts';
+
+/** resolves a ref or CSS selector to a Playwright locator */
+export const getLocator = (state: BrowserState, selectorOrRef: string): Locator => {
+	return resolveLocator(state.page, selectorOrRef, state.refs);
+};
+
+/** formats a byte count into a human-readable string */
+export const formatBytes = (bytes: number): string => {
+	if (bytes === 0) {
+		return '0 B';
+	}
+	const units = ['B', 'KB', 'MB', 'GB'];
+	const i = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);
+	const value = bytes / 1024 ** i;
+	return `${i === 0 ? value : value.toFixed(1)} ${units[i]}`;
+};
+
+/** extracts a filename from a URL, falling back to a generic name */
+export const filenameFromUrl = (url: string): string => {
+	try {
+		const pathname = new URL(url).pathname;
+		const base = basename(pathname);
+		// strip query params that might sneak in and ensure it's a valid filename
+		if (base && base !== '/' && !base.startsWith('.')) {
+			return base.split('?')[0]!;
+		}
+	} catch {
+		// invalid URL — fall through
+	}
+	return 'download';
+};

package/src/lib/commands/back.ts

@@ -0,0 +1,14 @@
+import { constant, object } from '@optique/core';
+
+import type { BrowserState } from './_types.ts';
+
+export const schema = object({
+	command: constant('back'),
+});
+
+export const handler = async (state: BrowserState): Promise<string> => {
+	const start = performance.now();
+	await state.page.goBack({ waitUntil: 'domcontentloaded' });
+	const elapsed = ((performance.now() - start) / 1000).toFixed(1);
+	return `navigated back to ${state.page.url()} (${elapsed}s)`;
+};

package/src/lib/commands/check.ts

@@ -0,0 +1,14 @@
+import { argument, constant, object, string } from '@optique/core';
+
+import type { BrowserState } from './_types.ts';
+import { getLocator } from './_utils.ts';
+
+export const schema = object({
+	command: constant('check'),
+	selector: argument(string({ metavar: 'SELECTOR' })),
+});
+
+export const handler = async (state: BrowserState, args: { selector: string }): Promise<string> => {
+	await getLocator(state, args.selector).check();
+	return 'checked';
+};

package/src/lib/commands/click.ts

@@ -0,0 +1,14 @@
+import { argument, constant, object, string } from '@optique/core';
+
+import type { BrowserState } from './_types.ts';
+import { getLocator } from './_utils.ts';
+
+export const schema = object({
+	command: constant('click'),
+	selector: argument(string({ metavar: 'SELECTOR' })),
+});
+
+export const handler = async (state: BrowserState, args: { selector: string }): Promise<string> => {
+	await getLocator(state, args.selector).click();
+	return 'clicked';
+};

package/src/lib/commands/close.ts

@@ -0,0 +1,17 @@
+import { constant, object } from '@optique/core';
+
+import type { BrowserState } from './_types.ts';
+
+export const schema = object({
+	command: constant('close'),
+});
+
+export const handler = async (state: BrowserState): Promise<string> => {
+	await state.page.close();
+	const pages = state.context.pages();
+	if (pages.length > 0) {
+		state.page = pages[0]!;
+		return 'tab closed, switched to remaining tab';
+	}
+	return 'browser closed';
+};

package/src/lib/commands/dblclick.ts

@@ -0,0 +1,14 @@
+import { argument, constant, object, string } from '@optique/core';
+
+import type { BrowserState } from './_types.ts';
+import { getLocator } from './_utils.ts';
+
+export const schema = object({
+	command: constant('dblclick'),
+	selector: argument(string({ metavar: 'SELECTOR' })),
+});
+
+export const handler = async (state: BrowserState, args: { selector: string }): Promise<string> => {
+	await getLocator(state, args.selector).dblclick();
+	return 'double-clicked';
+};