@oomfware/cbr 0.1.0

package/src/lib/commands/tab.ts

@@ -0,0 +1,102 @@
+import {
+	argument,
+	command,
+	constant,
+	type InferValue,
+	integer,
+	message,
+	object,
+	or,
+	string,
+} from '@optique/core';
+import { optional } from '@optique/core/modifiers';
+
+import { type BrowserState, CommandError } from './_types.ts';
+
+export const schema = object({
+	command: constant('tab'),
+	subcommand: or(
+		command(
+			'list',
+			object({
+				kind: constant('list'),
+			}),
+			{ description: message`list open tabs` },
+		),
+		command(
+			'new',
+			object({
+				kind: constant('new'),
+				url: optional(
+					argument(string({ metavar: 'URL' }), { description: message`URL to open in the new tab` }),
+				),
+			}),
+			{ description: message`open a new tab and switch to it` },
+		),
+		command(
+			'close',
+			object({
+				kind: constant('close'),
+				index: optional(argument(integer({ min: 0 }), { description: message`tab index to close` })),
+			}),
+			{ description: message`close a tab` },
+		),
+		// `tab <n>` — switch to tab by index (positional, no subcommand keyword)
+		object({
+			kind: constant('switch'),
+			index: argument(integer({ min: 0 }), { description: message`tab index to switch to` }),
+		}),
+	),
+});
+
+export type Args = InferValue<typeof schema>;
+
+export const handler = async (state: BrowserState, args: Args): Promise<string> => {
+	const sub = args.subcommand;
+
+	switch (sub.kind) {
+		case 'list': {
+			const pages = state.context.pages();
+			const lines = pages.map((p, i) => {
+				const marker = p === state.page ? '* ' : '  ';
+				return `${marker}${i}: ${p.url()}`;
+			});
+			return lines.join('\n');
+		}
+		case 'new': {
+			const newPage = await state.context.newPage();
+			if (sub.url) {
+				await newPage.goto(sub.url, { waitUntil: 'domcontentloaded' });
+			}
+			state.page = newPage;
+			return `opened new tab${sub.url ? ` at ${sub.url}` : ''}`;
+		}
+		case 'close': {
+			const pages = state.context.pages();
+
+			if (sub.index !== undefined) {
+				if (sub.index >= pages.length) {
+					throw new CommandError(`invalid tab index: ${sub.index}`);
+				}
+				await pages[sub.index]!.close();
+				// if we closed the current tab, switch to the first available
+				if (!state.context.pages().includes(state.page)) {
+					state.page = state.context.pages()[0]!;
+				}
+			} else {
+				await state.page.close();
+				state.page = state.context.pages()[0]!;
+			}
+			return 'tab closed';
+		}
+		case 'switch': {
+			const pages = state.context.pages();
+			if (sub.index < 0 || sub.index >= pages.length) {
+				throw new CommandError(`tab index out of range: ${sub.index} (${pages.length} tabs open)`);
+			}
+			state.page = pages[sub.index]!;
+			await state.page.bringToFront();
+			return `switched to tab ${sub.index}: ${state.page.url()}`;
+		}
+	}
+};

package/src/lib/commands/type-text.ts

@@ -0,0 +1,18 @@
+import { argument, constant, message, object, string } from '@optique/core';
+
+import type { BrowserState } from './_types.ts';
+import { getLocator } from './_utils.ts';
+
+export const schema = object({
+	command: constant('type'),
+	selector: argument(string({ metavar: 'SELECTOR' }), { description: message`element to type into` }),
+	text: argument(string({ metavar: 'TEXT' }), { description: message`text to type` }),
+});
+
+export const handler = async (
+	state: BrowserState,
+	args: { selector: string; text: string },
+): Promise<string> => {
+	await getLocator(state, args.selector).pressSequentially(args.text);
+	return 'typed';
+};

package/src/lib/commands/uncheck.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('uncheck'),
+	selector: argument(string({ metavar: 'SELECTOR' })),
+});
+
+export const handler = async (state: BrowserState, args: { selector: string }): Promise<string> => {
+	await getLocator(state, args.selector).uncheck();
+	return 'unchecked';
+};

package/src/lib/commands/wait.ts

@@ -0,0 +1,93 @@
+import {
+	argument,
+	command,
+	constant,
+	type InferValue,
+	integer,
+	message,
+	object,
+	option,
+	or,
+	string,
+} from '@optique/core';
+import { withDefault } from '@optique/core/modifiers';
+
+import type { BrowserState } from './_types.ts';
+import { getLocator } from './_utils.ts';
+
+export const schema = object({
+	command: constant('wait'),
+	subcommand: or(
+		command(
+			'for',
+			object({
+				kind: constant('for'),
+				selector: argument(string({ metavar: 'SELECTOR' })),
+				timeout: withDefault(
+					option('--timeout', integer({ min: 0 }), { description: message`milliseconds to wait` }),
+					5000,
+				),
+				hidden: withDefault(
+					option('--hidden', { description: message`wait for the element to disappear` }),
+					false,
+				),
+			}),
+			{ description: message`wait for an element to appear` },
+		),
+		command(
+			'for-text',
+			object({
+				kind: constant('for-text'),
+				text: argument(string({ metavar: 'TEXT' })),
+				timeout: withDefault(
+					option('--timeout', integer({ min: 0 }), { description: message`milliseconds to wait` }),
+					5000,
+				),
+				hidden: withDefault(
+					option('--hidden', { description: message`wait for the text to disappear` }),
+					false,
+				),
+			}),
+			{ description: message`wait for text content to appear` },
+		),
+		command(
+			'for-url',
+			object({
+				kind: constant('for-url'),
+				pattern: argument(string({ metavar: 'URL_PATTERN' })),
+				timeout: withDefault(
+					option('--timeout', integer({ min: 0 }), { description: message`milliseconds to wait` }),
+					5000,
+				),
+			}),
+			{ description: message`wait for the URL to match a pattern` },
+		),
+	),
+});
+
+export type Args = InferValue<typeof schema>;
+
+export const handler = async (state: BrowserState, args: Args): Promise<string> => {
+	const start = performance.now();
+	const sub = args.subcommand;
+
+	switch (sub.kind) {
+		case 'for': {
+			const waitState = sub.hidden ? 'hidden' : 'visible';
+			await getLocator(state, sub.selector).waitFor({ state: waitState, timeout: sub.timeout });
+			const elapsed = ((performance.now() - start) / 1000).toFixed(1);
+			return `element ${sub.selector} is ${waitState} (${elapsed}s)`;
+		}
+		case 'for-text': {
+			const waitState = sub.hidden ? 'hidden' : 'visible';
+			await state.page.getByText(sub.text).waitFor({ state: waitState, timeout: sub.timeout });
+			const elapsed = ((performance.now() - start) / 1000).toFixed(1);
+			return `text "${sub.text}" is ${waitState} (${elapsed}s)`;
+		}
+		case 'for-url': {
+			await state.page.waitForURL(sub.pattern, { timeout: sub.timeout });
+			const elapsed = ((performance.now() - start) / 1000).toFixed(1);
+			return `url matched ${sub.pattern} (${elapsed}s)`;
+		}
+	}
+};

package/src/lib/commands.ts

@@ -0,0 +1,202 @@
+import { command, formatDocPage, formatMessage, getDocPage, group, message, or, parse } from '@optique/core';
+
+import { type BrowserState, CommandError } from './commands/_types.ts';
+import * as back from './commands/back.ts';
+import * as check from './commands/check.ts';
+import * as click from './commands/click.ts';
+import * as close from './commands/close.ts';
+import * as dblclick from './commands/dblclick.ts';
+import * as download from './commands/download.ts';
+import * as eval_ from './commands/eval.ts';
+import * as fill from './commands/fill.ts';
+import * as forward from './commands/forward.ts';
+import * as frame from './commands/frame.ts';
+import * as get from './commands/get.ts';
+import * as hover from './commands/hover.ts';
+import * as is_ from './commands/is.ts';
+import * as open from './commands/open.ts';
+import * as press from './commands/press.ts';
+import * as reload from './commands/reload.ts';
+import * as resources from './commands/resources.ts';
+import * as screenshot from './commands/screenshot.ts';
+import * as scroll from './commands/scroll.ts';
+import * as select from './commands/select.ts';
+import * as snapshot from './commands/snapshot.ts';
+import * as source from './commands/source.ts';
+import * as styles from './commands/styles.ts';
+import * as tab from './commands/tab.ts';
+import * as typeText from './commands/type-text.ts';
+import * as uncheck from './commands/uncheck.ts';
+import * as wait from './commands/wait.ts';
+import type { CommandHandler } from './server.ts';
+
+// grouped to stay within or()'s typed overloads (max 10 per call)
+const navigation = group(
+	'navigation',
+	or(
+		command('open', open.schema, { description: message`navigate to a URL` }),
+		command('back', back.schema, { description: message`go back in history` }),
+		command('forward', forward.schema, { description: message`go forward in history` }),
+		command('reload', reload.schema, { description: message`reload the current page` }),
+		command('click', click.schema, { description: message`click an element` }),
+		command('dblclick', dblclick.schema, { description: message`double-click an element` }),
+		command('fill', fill.schema, { description: message`clear and fill an input field` }),
+		command('type', typeText.schema, { description: message`type text character by character` }),
+		command('press', press.schema, { description: message`press a keyboard key` }),
+	),
+);
+
+const querying = group(
+	'querying',
+	or(
+		command('hover', hover.schema, { description: message`hover over an element` }),
+		command('select', select.schema, { description: message`select a dropdown option` }),
+		command('check', check.schema, { description: message`check a checkbox` }),
+		command('uncheck', uncheck.schema, { description: message`uncheck a checkbox` }),
+		command('get', get.schema, { description: message`get page or element data` }),
+		command('is', is_.schema, { description: message`check element state` }),
+		command('snapshot', snapshot.schema, { description: message`get the accessibility tree` }),
+		command('screenshot', screenshot.schema, { description: message`take a screenshot` }),
+		command('wait', wait.schema, { description: message`wait for an element, text, or URL` }),
+	),
+);
+
+const inspection = group(
+	'inspection',
+	or(
+		command('scroll', scroll.schema, { description: message`scroll the page or a container` }),
+		command('frame', frame.schema, { description: message`list or switch frames` }),
+		command('tab', tab.schema, { description: message`list, open, switch, or close tabs` }),
+		command('eval', eval_.schema, { description: message`evaluate JavaScript in the page` }),
+		command('source', source.schema, { description: message`get page or element HTML source` }),
+		command('resources', resources.schema, { description: message`list loaded resources` }),
+		command('styles', styles.schema, { description: message`get computed styles for an element` }),
+		command('download', download.schema, { description: message`download a resource to assets/` }),
+		command('close', close.schema, { description: message`close the current tab` }),
+	),
+);
+
+export const parser = or(navigation, querying, inspection);
+
+/**
+ * creates a command handler that parses args and dispatches to the matching command.
+ * @param state mutable browser state shared across commands
+ * @returns a command handler compatible with the server
+ */
+export const createCommandHandler =
+	(state: BrowserState): CommandHandler =>
+	async (args) => {
+		if (args[0] === 'help' || args[0] === '--help') {
+			const helpArgs = args.slice(1);
+			const page = getDocPage(parser, helpArgs);
+			if (page) {
+				return { ok: true, data: formatDocPage('browser', page) };
+			}
+			return { ok: false, error: `no help available` };
+		}
+
+		if (state.spinner.isSpinning) {
+			state.spinner.text = ['browser', ...args].join(' ').replace(/\s+/g, ' ');
+		}
+
+		const parsed = parse(parser, args);
+		if (!parsed.success) {
+			return { ok: false, error: formatMessage(parsed.error) };
+		}
+
+		try {
+			let data: string | undefined;
+
+			switch (parsed.value.command) {
+				case 'open':
+					data = await open.handler(state, parsed.value);
+					break;
+				case 'back':
+					data = await back.handler(state);
+					break;
+				case 'forward':
+					data = await forward.handler(state);
+					break;
+				case 'reload':
+					data = await reload.handler(state);
+					break;
+				case 'click':
+					data = await click.handler(state, parsed.value);
+					break;
+				case 'dblclick':
+					data = await dblclick.handler(state, parsed.value);
+					break;
+				case 'fill':
+					data = await fill.handler(state, parsed.value);
+					break;
+				case 'type':
+					data = await typeText.handler(state, parsed.value);
+					break;
+				case 'press':
+					data = await press.handler(state, parsed.value);
+					break;
+				case 'hover':
+					data = await hover.handler(state, parsed.value);
+					break;
+				case 'select':
+					data = await select.handler(state, parsed.value);
+					break;
+				case 'check':
+					data = await check.handler(state, parsed.value);
+					break;
+				case 'uncheck':
+					data = await uncheck.handler(state, parsed.value);
+					break;
+				case 'get':
+					data = await get.handler(state, parsed.value);
+					break;
+				case 'is':
+					data = await is_.handler(state, parsed.value);
+					break;
+				case 'snapshot':
+					data = await snapshot.handler(state, parsed.value);
+					break;
+				case 'screenshot':
+					data = await screenshot.handler(state, parsed.value);
+					break;
+				case 'wait':
+					data = await wait.handler(state, parsed.value);
+					break;
+				case 'scroll':
+					data = await scroll.handler(state, parsed.value);
+					break;
+				case 'frame':
+					data = await frame.handler(state, parsed.value);
+					break;
+				case 'tab':
+					data = await tab.handler(state, parsed.value);
+					break;
+				case 'eval':
+					data = await eval_.handler(state, parsed.value);
+					break;
+				case 'source':
+					data = await source.handler(state, parsed.value);
+					break;
+				case 'resources':
+					data = await resources.handler(state, parsed.value);
+					break;
+				case 'styles':
+					data = await styles.handler(state, parsed.value);
+					break;
+				case 'download':
+					data = await download.handler(state, parsed.value);
+					break;
+				case 'close':
+					data = await close.handler(state);
+					break;
+			}
+
+			return { ok: true, data };
+		} catch (e) {
+			if (e instanceof CommandError) {
+				return { ok: false, error: e.message };
+			}
+			const message = e instanceof Error ? e.message : String(e);
+			return { ok: false, error: message };
+		}
+	};

package/src/lib/debug.ts

@@ -0,0 +1,11 @@
+export const debugEnabled = process.env.DEBUG === '1' || process.env.CBR_DEBUG === '1';
+
+/**
+ * logs a debug message to stderr if DEBUG=1 or CBR_DEBUG=1.
+ * @param message the message to log
+ */
+export const debug = (message: string): void => {
+	if (debugEnabled) {
+		console.error(`[debug] ${message}`);
+	}
+};

package/src/lib/paths.ts

@@ -0,0 +1,118 @@
+import { randomUUID } from 'node:crypto';
+import type { Dirent } from 'node:fs';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import * as v from 'valibot';
+
+/**
+ * returns the cache directory for cbr.
+ * uses `$XDG_CACHE_HOME/cbr` if set, otherwise falls back to:
+ * - `~/.cache/cbr` on linux
+ * - `~/Library/Caches/cbr` on macos
+ * @returns the cache directory path
+ */
+export const getCacheDir = (): string => {
+	const xdgCache = process.env['XDG_CACHE_HOME'];
+	if (xdgCache) {
+		return join(xdgCache, 'cbr');
+	}
+	const home = homedir();
+	if (process.platform === 'darwin') {
+		return join(home, 'Library', 'Caches', 'cbr');
+	}
+	return join(home, '.cache', 'cbr');
+};
+
+/**
+ * returns the sessions directory within the cache.
+ * @returns the sessions directory path
+ */
+export const getSessionsDir = (): string => join(getCacheDir(), 'sessions');
+
+const PID_FILE = '.pid';
+
+// linux PID limits: 1 to 2^22 (4194304) by default, configurable up to 2^22
+const PidSchema = v.pipe(v.string(), v.trim(), v.toNumber(), v.integer(), v.minValue(1));
+
+/**
+ * creates a new session directory with a random UUID, PID lockfile, and subdirectories.
+ * @returns the path to the created session directory
+ */
+export const createSessionDir = async (): Promise<string> => {
+	const sessionPath = join(getSessionsDir(), randomUUID());
+	await mkdir(sessionPath, { recursive: true });
+	await writeFile(join(sessionPath, PID_FILE), process.pid.toString());
+
+	// create subdirectories
+	await Promise.all([
+		mkdir(join(sessionPath, '.claude'), { recursive: true }),
+		mkdir(join(sessionPath, 'bin'), { recursive: true }),
+		mkdir(join(sessionPath, 'assets'), { recursive: true }),
+		mkdir(join(sessionPath, 'screenshots'), { recursive: true }),
+		mkdir(join(sessionPath, 'scratch'), { recursive: true }),
+	]);
+
+	return sessionPath;
+};
+
+/**
+ * removes a session directory.
+ * @param sessionPath the session directory path
+ */
+export const cleanupSessionDir = async (sessionPath: string): Promise<void> => {
+	await rm(sessionPath, { recursive: true, force: true });
+};
+
+/**
+ * checks if a process with the given PID is running.
+ * @param pid the process ID to check
+ * @returns true if the process is running
+ */
+export const isProcessRunning = (pid: number): boolean => {
+	try {
+		// signal 0 doesn't send a signal but checks if process exists
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+};
+
+/**
+ * garbage collects orphaned session directories.
+ * a session is orphaned if its PID file is missing or the process is no longer running.
+ * this function is meant to be called fire-and-forget (errors are silently ignored).
+ */
+export const gcSessions = async (): Promise<void> => {
+	const sessionsDir = getSessionsDir();
+
+	let entries: Dirent[];
+	try {
+		entries = await readdir(sessionsDir, { withFileTypes: true });
+	} catch {
+		// sessions dir doesn't exist or can't be read
+		return;
+	}
+
+	for (const entry of entries) {
+		if (!entry.isDirectory()) {
+			continue;
+		}
+		const sessionPath = join(sessionsDir, entry.name);
+		const pidPath = join(sessionPath, PID_FILE);
+
+		try {
+			const pidContent = await readFile(pidPath, 'utf-8');
+			const result = v.safeParse(PidSchema, pidContent);
+
+			if (!result.success || !isProcessRunning(result.output)) {
+				await rm(sessionPath, { recursive: true, force: true });
+			}
+		} catch {
+			// no PID file or can't read it - orphaned session
+			await rm(sessionPath, { recursive: true, force: true }).catch(() => {});
+		}
+	}
+};

package/src/lib/server.ts

@@ -0,0 +1,94 @@
+import { createServer, type Server, type Socket } from 'node:net';
+
+import * as v from 'valibot';
+
+import { debug } from './debug.ts';
+
+const RequestSchema = v.object({
+	id: v.string(),
+	args: v.array(v.string()),
+});
+
+export type CommandHandler = (
+	args: readonly string[],
+) => Promise<{ ok: boolean; data?: string; error?: string }>;
+
+/**
+ * starts a JSON-over-Unix-socket server.
+ * each connection handles a single newline-delimited JSON request,
+ * dispatches to the handler, writes the response, and closes.
+ * @param socketPath path to the Unix domain socket
+ * @param handler function that processes commands and returns responses
+ * @returns promise that resolves with the server instance once listening
+ */
+export const startServer = (socketPath: string, handler: CommandHandler): Promise<Server> => {
+	return new Promise((resolve, reject) => {
+		const server = createServer((socket: Socket) => {
+			let data = '';
+
+			socket.on('data', (chunk: Buffer) => {
+				data += chunk.toString();
+
+				// process on first newline
+				const newlineIndex = data.indexOf('\n');
+				if (newlineIndex === -1) {
+					return;
+				}
+
+				const line = data.slice(0, newlineIndex).trim();
+				// ignore any further data on this connection
+				data = '';
+
+				handleRequest(line, socket, handler);
+			});
+
+			socket.on('error', (err) => {
+				debug(`socket error: ${err.message}`);
+			});
+		});
+
+		server.on('error', reject);
+
+		server.listen(socketPath, () => {
+			debug(`server listening on ${socketPath}`);
+			resolve(server);
+		});
+	});
+};
+
+const handleRequest = async (line: string, socket: Socket, handler: CommandHandler): Promise<void> => {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(line);
+	} catch {
+		debug(`ignoring malformed JSON: ${line}`);
+		socket.end();
+		return;
+	}
+
+	const result = v.safeParse(RequestSchema, parsed);
+	if (!result.success) {
+		debug(`ignoring invalid request: ${line}`);
+		socket.end();
+		return;
+	}
+
+	const { id, args } = result.output;
+
+	try {
+		debug(`request: ${line}`);
+
+		const result = await handler(args);
+		const response = JSON.stringify({ id, ...result });
+
+		debug(`response: ${response}`);
+
+		socket.end(response + '\n');
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		const response = JSON.stringify({ id, ok: false, error: message });
+
+		debug(`handler error: ${message}`);
+		socket.end(response + '\n');
+	}
+};