@oomfware/cbr 0.1.0

package/src/lib/commands/download.ts

@@ -0,0 +1,36 @@
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { argument, constant, type InferValue, message, object, string } from '@optique/core';
+import { optional } from '@optique/core/modifiers';
+
+import { CommandError, type BrowserState } from './_types.ts';
+import { filenameFromUrl, formatBytes } from './_utils.ts';
+
+export const schema = object({
+	command: constant('download'),
+	url: argument(string({ metavar: 'URL' }), { description: message`URL of the resource to download` }),
+	filename: optional(
+		argument(string({ metavar: 'FILENAME' }), { description: message`save as this filename` }),
+	),
+});
+
+export type Args = InferValue<typeof schema>;
+
+export const handler = async (state: BrowserState, args: Args): Promise<string> => {
+	const filename = args.filename ?? filenameFromUrl(args.url);
+
+	const start = performance.now();
+	const response = await state.page.request.get(args.url);
+	if (!response.ok()) {
+		throw new CommandError(`download failed: ${response.status()} ${response.statusText()}`);
+	}
+
+	const buffer = await response.body();
+	const filepath = join(state.assetsDir, filename);
+	await writeFile(filepath, buffer);
+
+	const size = formatBytes(buffer.length);
+	const elapsed = ((performance.now() - start) / 1000).toFixed(1);
+	return `saved assets/${filename} (${size}, ${elapsed}s)`;
+};

package/src/lib/commands/eval.ts

@@ -0,0 +1,23 @@
+import { constant, type InferValue, message, object, passThrough } from '@optique/core';
+
+import { type BrowserState, CommandError } from './_types.ts';
+
+export const schema = object({
+	command: constant('eval'),
+	code: passThrough({ format: 'greedy', description: message`JavaScript code to evaluate` }),
+});
+
+export type Args = InferValue<typeof schema>;
+
+export const handler = async (state: BrowserState, args: Args): Promise<string | undefined> => {
+	const code = args.code.join(' ');
+	if (!code) {
+		throw new CommandError('missing code to evaluate');
+	}
+
+	const result = await state.page.evaluate(code);
+	if (result === undefined || result === null) {
+		return undefined;
+	}
+	return typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+};

package/src/lib/commands/fill.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('fill'),
+	selector: argument(string({ metavar: 'SELECTOR' }), { description: message`input element to fill` }),
+	text: argument(string({ metavar: 'TEXT' }), { description: message`text to fill in` }),
+});
+
+export const handler = async (
+	state: BrowserState,
+	args: { selector: string; text: string },
+): Promise<string> => {
+	await getLocator(state, args.selector).fill(args.text);
+	return 'filled';
+};

package/src/lib/commands/forward.ts

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

package/src/lib/commands/frame.ts

@@ -0,0 +1,106 @@
+import { argument, command, constant, type InferValue, message, object, or, string } from '@optique/core';
+import type { Frame, Page } from 'playwright';
+
+import { type BrowserState, CommandError } from './_types.ts';
+
+export const schema = object({
+	command: constant('frame'),
+	subcommand: or(
+		command(
+			'list',
+			object({
+				kind: constant('list'),
+			}),
+			{ description: message`list all frames with IDs, URLs, and parent info` },
+		),
+		command(
+			'main',
+			object({
+				kind: constant('main'),
+			}),
+			{ description: message`switch to the main frame` },
+		),
+		// `frame <id>` — switch by frame ref (positional, no subcommand keyword)
+		object({
+			kind: constant('switch'),
+			id: argument(string({ metavar: 'FRAME_ID' }), { description: message`frame ref to switch to` }),
+		}),
+	),
+});
+
+export type Args = InferValue<typeof schema>;
+
+/**
+ * collects child frames from the page, assigns IDs (`f1`, `f2`, ...), and
+ * stores them in `state.frameRefs`. the main frame is excluded since
+ * `frame main` handles switching back to it.
+ */
+const refreshFrameRefs = (state: BrowserState): Record<string, Frame> => {
+	const mainPage = state.context.pages()[0]!;
+	const mainFrame = mainPage.mainFrame();
+	const childFrames = mainPage.frames().filter((f) => f !== mainFrame);
+	const map: Record<string, Frame> = {};
+	for (let i = 0; i < childFrames.length; i++) {
+		map[`f${i + 1}`] = childFrames[i]!;
+	}
+	state.frameRefs = map;
+	return map;
+};
+
+const formatFrameList = (refs: Record<string, Frame>, currentPage: Page): string => {
+	const mainFrame = currentPage.mainFrame();
+	const currentFrame = currentPage as unknown as Frame;
+	const lines: string[] = [];
+
+	{
+		const marker = currentFrame === mainFrame ? '* ' : '  ';
+		lines.push(`${marker}main: ${mainFrame.url()}`);
+	}
+
+	for (const [id, frame] of Object.entries(refs)) {
+		const marker = frame === currentFrame ? '* ' : '  ';
+		const name = frame.name() ? ` name="${frame.name()}"` : '';
+
+		let parentTag = '';
+		{
+			const parent = frame.parentFrame();
+			if (parent === mainFrame) {
+				parentTag = ' (parent: main)';
+			} else if (parent) {
+				const parentId = Object.entries(refs).find(([, f]) => f === parent)?.[0];
+				if (parentId) {
+					parentTag = ` (parent: ${parentId})`;
+				}
+			}
+		}
+
+		lines.push(`${marker}${id}: ${frame.url()}${name}${parentTag}`);
+	}
+	return lines.join('\n');
+};
+
+export const handler = async (state: BrowserState, args: Args): Promise<string> => {
+	const sub = args.subcommand;
+
+	switch (sub.kind) {
+		case 'list': {
+			const refs = refreshFrameRefs(state);
+			return formatFrameList(refs, state.page);
+		}
+		case 'main': {
+			state.page = state.context.pages()[0]!;
+			return 'switched to main frame';
+		}
+		case 'switch': {
+			const frame = state.frameRefs[sub.id];
+			if (!frame) {
+				throw new CommandError(
+					`frame ${sub.id} not found — run \`browser frame list\` to list frames and get IDs`,
+				);
+			}
+			// Frame implements a subset of Page's API that we use
+			state.page = frame as unknown as Page;
+			return `switched to frame ${sub.id}: ${frame.url()}`;
+		}
+	}
+};

package/src/lib/commands/get.ts

@@ -0,0 +1,95 @@
+import { argument, command, constant, type InferValue, message, object, or, string } from '@optique/core';
+
+import type { BrowserState } from './_types.ts';
+import { getLocator } from './_utils.ts';
+
+export const schema = object({
+	command: constant('get'),
+	subcommand: or(
+		command(
+			'text',
+			object({
+				kind: constant('text'),
+				selector: argument(string({ metavar: 'SELECTOR' })),
+			}),
+			{ description: message`get inner text of an element` },
+		),
+		command(
+			'url',
+			object({
+				kind: constant('url'),
+			}),
+			{ description: message`get the current page URL` },
+		),
+		command(
+			'title',
+			object({
+				kind: constant('title'),
+			}),
+			{ description: message`get the current page title` },
+		),
+		command(
+			'html',
+			object({
+				kind: constant('html'),
+				selector: argument(string({ metavar: 'SELECTOR' })),
+			}),
+			{ description: message`get inner HTML of an element` },
+		),
+		command(
+			'value',
+			object({
+				kind: constant('value'),
+				selector: argument(string({ metavar: 'SELECTOR' })),
+			}),
+			{ description: message`get the value of an input field` },
+		),
+		command(
+			'attr',
+			object({
+				kind: constant('attr'),
+				selector: argument(string({ metavar: 'SELECTOR' })),
+				attribute: argument(string({ metavar: 'ATTR' })),
+			}),
+			{ description: message`get an attribute of an element` },
+		),
+		command(
+			'count',
+			object({
+				kind: constant('count'),
+				selector: argument(string({ metavar: 'SELECTOR' })),
+			}),
+			{ description: message`count matching elements` },
+		),
+	),
+});
+
+export type Args = InferValue<typeof schema>;
+
+export const handler = async (state: BrowserState, args: Args): Promise<string> => {
+	switch (args.subcommand.kind) {
+		case 'text': {
+			return await getLocator(state, args.subcommand.selector).innerText();
+		}
+		case 'url': {
+			return state.page.url();
+		}
+		case 'title': {
+			return await state.page.title();
+		}
+		case 'html': {
+			return await getLocator(state, args.subcommand.selector).innerHTML();
+		}
+		case 'value': {
+			return await getLocator(state, args.subcommand.selector).inputValue();
+		}
+		case 'attr': {
+			const value = await getLocator(state, args.subcommand.selector).getAttribute(args.subcommand.attribute);
+			return value ?? '';
+		}
+		case 'count': {
+			const count = await getLocator(state, args.subcommand.selector).count();
+			return String(count);
+		}
+	}
+};

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

package/src/lib/commands/is.ts

@@ -0,0 +1,53 @@
+import { argument, command, constant, type InferValue, message, object, or, string } from '@optique/core';
+
+import type { BrowserState } from './_types.ts';
+import { getLocator } from './_utils.ts';
+
+export const schema = object({
+	command: constant('is'),
+	subcommand: or(
+		command(
+			'visible',
+			object({
+				kind: constant('visible'),
+				selector: argument(string({ metavar: 'SELECTOR' })),
+			}),
+			{ description: message`check if an element is visible` },
+		),
+		command(
+			'enabled',
+			object({
+				kind: constant('enabled'),
+				selector: argument(string({ metavar: 'SELECTOR' })),
+			}),
+			{ description: message`check if an element is enabled` },
+		),
+		command(
+			'checked',
+			object({
+				kind: constant('checked'),
+				selector: argument(string({ metavar: 'SELECTOR' })),
+			}),
+			{ description: message`check if a checkbox is checked` },
+		),
+	),
+});
+
+export type Args = InferValue<typeof schema>;
+
+export const handler = async (state: BrowserState, args: Args): Promise<string> => {
+	switch (args.subcommand.kind) {
+		case 'visible': {
+			const visible = await getLocator(state, args.subcommand.selector).isVisible();
+			return String(visible);
+		}
+		case 'enabled': {
+			const enabled = await getLocator(state, args.subcommand.selector).isEnabled();
+			return String(enabled);
+		}
+		case 'checked': {
+			const checked = await getLocator(state, args.subcommand.selector).isChecked();
+			return String(checked);
+		}
+	}
+};

package/src/lib/commands/open.ts

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

package/src/lib/commands/press.ts

@@ -0,0 +1,13 @@
+import { argument, constant, object, string } from '@optique/core';
+
+import type { BrowserState } from './_types.ts';
+
+export const schema = object({
+	command: constant('press'),
+	key: argument(string({ metavar: 'KEY' })),
+});
+
+export const handler = async (state: BrowserState, args: { key: string }): Promise<string> => {
+	await state.page.keyboard.press(args.key);
+	return `pressed ${args.key}`;
+};

package/src/lib/commands/reload.ts

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

package/src/lib/commands/resources.ts

@@ -0,0 +1,37 @@
+import { argument, constant, type InferValue, message, object, string } from '@optique/core';
+import { optional } from '@optique/core/modifiers';
+
+import type { BrowserState } from './_types.ts';
+import { formatBytes } from './_utils.ts';
+
+export const schema = object({
+	command: constant('resources'),
+	typeFilter: optional(
+		argument(string({ metavar: 'TYPE' }), {
+			description: message`filter by resource type (e.g. script, img)`,
+		}),
+	),
+});
+
+export type Args = InferValue<typeof schema>;
+
+export const handler = async (state: BrowserState, args: Args): Promise<string> => {
+	const entries: Array<{ name: string; type: string; size: number }> = await state.page.evaluate(() =>
+		performance.getEntriesByType('resource').map((e) => {
+			const r = e as PerformanceResourceTiming;
+			return { name: r.name, type: r.initiatorType, size: r.transferSize };
+		}),
+	);
+
+	const filtered = args.typeFilter ? entries.filter((e) => e.type === args.typeFilter) : entries;
+
+	if (filtered.length === 0) {
+		return args.typeFilter ? `no resources of type "${args.typeFilter}"` : 'no resources recorded';
+	}
+
+	const lines = filtered.map((e) => {
+		const size = e.size > 0 ? ` (${formatBytes(e.size)})` : '';
+		return `[${e.type}] ${e.name}${size}`;
+	});
+	return lines.join('\n');
+};

package/src/lib/commands/screenshot.ts

@@ -0,0 +1,26 @@
+import { join } from 'node:path';
+
+import { argument, constant, type InferValue, message, object, option, string } from '@optique/core';
+import { optional, withDefault } from '@optique/core/modifiers';
+
+import type { BrowserState } from './_types.ts';
+
+export const schema = object({
+	command: constant('screenshot'),
+	name: optional(
+		argument(string({ metavar: 'NAME' }), { description: message`filename for the screenshot` }),
+	),
+	full: withDefault(option('--full', { description: message`capture the full scrollable page` }), false),
+});
+
+export type Args = InferValue<typeof schema>;
+
+export const handler = async (state: BrowserState, args: Args): Promise<string> => {
+	state.screenshotCounter++;
+	const name = args.name ?? `screenshot-${state.screenshotCounter}`;
+	const filename = name.endsWith('.png') ? name : `${name}.png`;
+	const filepath = join(state.screenshotDir, filename);
+
+	await state.page.screenshot({ path: filepath, fullPage: args.full });
+	return `screenshot saved to screenshots/${filename}`;
+};

package/src/lib/commands/scroll.ts

@@ -0,0 +1,30 @@
+import { argument, choice, constant, type InferValue, message, object, string } from '@optique/core';
+import { optional } from '@optique/core/modifiers';
+
+import type { BrowserState } from './_types.ts';
+import { getLocator } from './_utils.ts';
+
+export const schema = object({
+	command: constant('scroll'),
+	direction: argument(choice(['up', 'down']), { description: message`scroll direction` }),
+	selector: optional(
+		argument(string({ metavar: 'SELECTOR' }), {
+			description: message`element to scroll instead of the page`,
+		}),
+	),
+});
+
+export type Args = InferValue<typeof schema>;
+
+export const handler = async (state: BrowserState, args: Args): Promise<string> => {
+	const delta = args.direction === 'down' ? 500 : -500;
+
+	if (args.selector) {
+		const locator = getLocator(state, args.selector);
+		await locator.evaluate((el, d) => el.scrollBy(0, d), delta);
+	} else {
+		await state.page.mouse.wheel(0, delta);
+	}
+
+	return `scrolled ${args.direction}`;
+};

package/src/lib/commands/select.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('select'),
+	selector: argument(string({ metavar: 'SELECTOR' }), { description: message`select element to target` }),
+	value: argument(string({ metavar: 'VALUE' }), { description: message`option value to select` }),
+});
+
+export const handler = async (
+	state: BrowserState,
+	args: { selector: string; value: string },
+): Promise<string> => {
+	await getLocator(state, args.selector).selectOption(args.value);
+	return `selected ${args.value}`;
+};

package/src/lib/commands/snapshot.ts

@@ -0,0 +1,30 @@
+import { constant, type InferValue, integer, message, object, option, string } from '@optique/core';
+import { optional, withDefault } from '@optique/core/modifiers';
+
+import { takeSnapshot } from '../snapshot.ts';
+
+import type { BrowserState } from './_types.ts';
+
+export const schema = object({
+	command: constant('snapshot'),
+	interactive: withDefault(
+		option('--interactive', { description: message`only show interactive elements` }),
+		false,
+	),
+	compact: withDefault(option('--compact', { description: message`remove empty lines from output` }), false),
+	depth: optional(option('--depth', integer({ min: 0 }), { description: message`maximum tree depth` })),
+	selector: optional(option('--selector', string(), { description: message`scope to a subtree` })),
+});
+
+export type Args = InferValue<typeof schema>;
+
+export const handler = async (state: BrowserState, args: Args): Promise<string> => {
+	const result = await takeSnapshot(state.page, {
+		interactive: args.interactive || undefined,
+		compact: args.compact || undefined,
+		depth: args.depth ?? undefined,
+		selector: args.selector ?? undefined,
+	});
+	state.refs = result.refs;
+	return result.text;
+};

package/src/lib/commands/source.ts

@@ -0,0 +1,23 @@
+import { argument, constant, type InferValue, message, object, string } from '@optique/core';
+import { optional } from '@optique/core/modifiers';
+
+import type { BrowserState } from './_types.ts';
+import { getLocator } from './_utils.ts';
+
+export const schema = object({
+	command: constant('source'),
+	selector: optional(
+		argument(string({ metavar: 'SELECTOR' }), {
+			description: message`element to get HTML for, or full page if omitted`,
+		}),
+	),
+});
+
+export type Args = InferValue<typeof schema>;
+
+export const handler = async (state: BrowserState, args: Args): Promise<string> => {
+	if (args.selector) {
+		return await getLocator(state, args.selector).evaluate((el) => el.outerHTML);
+	}
+	return await state.page.content();
+};

package/src/lib/commands/styles.ts

@@ -0,0 +1,63 @@
+import { argument, constant, type InferValue, message, object, string } from '@optique/core';
+import { optional } from '@optique/core/modifiers';
+
+import type { BrowserState } from './_types.ts';
+import { getLocator } from './_utils.ts';
+
+// browser evaluate callbacks run in the browser context where getComputedStyle exists
+declare const getComputedStyle: (el: unknown) => { getPropertyValue(prop: string): string };
+
+export const schema = object({
+	command: constant('styles'),
+	selector: argument(string({ metavar: 'SELECTOR' }), { description: message`element to inspect` }),
+	property: optional(
+		argument(string({ metavar: 'PROPERTY' }), {
+			description: message`specific CSS property, or all if omitted`,
+		}),
+	),
+});
+
+export type Args = InferValue<typeof schema>;
+
+export const handler = async (state: BrowserState, args: Args): Promise<string> => {
+	if (args.property) {
+		const value = await getLocator(state, args.selector).evaluate(
+			(el, prop) => getComputedStyle(el).getPropertyValue(prop),
+			args.property,
+		);
+		return value || '(empty)';
+	}
+
+	// return a curated set of commonly useful properties
+	const styles = await getLocator(state, args.selector).evaluate((el) => {
+		const cs = getComputedStyle(el);
+		const props = [
+			'color',
+			'background-color',
+			'font-family',
+			'font-size',
+			'font-weight',
+			'line-height',
+			'display',
+			'position',
+			'width',
+			'height',
+			'margin',
+			'padding',
+			'border',
+			'opacity',
+			'z-index',
+		];
+		const result: Record<string, string> = {};
+		for (const p of props) {
+			const v = cs.getPropertyValue(p);
+			if (v) {
+				result[p] = v;
+			}
+		}
+		return result;
+	});
+
+	const lines = Object.entries(styles).map(([k, v]) => `${k}: ${v}`);
+	return lines.join('\n');
+};