@oomfware/cbr 0.1.0

package/src/lib/session.ts

@@ -0,0 +1,92 @@
+import { chmod, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * writes the per-session `.claude/settings.json` with permissions and hooks.
+ * paths are baked in at generation time so the settings work regardless of cwd.
+ * @param sessionPath the session directory path
+ */
+export const writeSessionSettings = async (sessionPath: string): Promise<void> => {
+	const settings = {
+		permissions: {
+			allow: [
+				'Read(assets/*)',
+				'Read(screenshots/*)',
+				'Read(scratch/*)',
+				'Write(scratch/*)',
+				'Glob(assets/*)',
+				'Glob(screenshots/*)',
+				'Glob(scratch/*)',
+				'Grep(assets/*)',
+				'Grep(screenshots/*)',
+				'Grep(scratch/*)',
+				'Bash(browser:*)',
+				// filesystem
+				'Bash(ls:*)',
+				'Bash(cat:*)',
+				'Bash(head:*)',
+				'Bash(tail:*)',
+				'Bash(wc:*)',
+				'Bash(file:*)',
+				'Bash(find:*)',
+				'Bash(tree:*)',
+				'Bash(stat:*)',
+				'Bash(du:*)',
+				'Bash(mkdir:*)',
+				'Bash(basename:*)',
+				'Bash(dirname:*)',
+				'Bash(realpath:*)',
+
+				// text processing
+				'Bash(awk:*)',
+				'Bash(cut:*)',
+				'Bash(diff:*)',
+				'Bash(grep:*)',
+				'Bash(jq:*)',
+				'Bash(sed:*)',
+				'Bash(sort:*)',
+				'Bash(tr:*)',
+				'Bash(uniq:*)',
+				'Bash(xargs:*)',
+				'Bash(paste:*)',
+				'Bash(tee:*)',
+				'Bash(column:*)',
+				'WebSearch',
+				'WebFetch',
+			],
+			deny: ['*'],
+		},
+		hooks: {
+			SessionStart: [
+				{
+					matcher: '',
+					hooks: [
+						{
+							type: 'command',
+							command: `sh -c 'echo "export PATH=\\"${sessionPath}/bin:\\$PATH\\"" >> "$CLAUDE_ENV_FILE"'`,
+						},
+					],
+				},
+			],
+		},
+	};
+
+	await writeFile(join(sessionPath, '.claude', 'settings.json'), JSON.stringify(settings, null, '\t') + '\n');
+};
+
+/**
+ * writes the `bin/browser` shim script that delegates to the bundled client.
+ * @param sessionPath the session directory path
+ * @param clientScriptPath absolute path to the bundled `dist/browser.mjs`
+ * @param socketPath absolute path to the Unix domain socket
+ */
+export const writeBrowserShim = async (
+	sessionPath: string,
+	clientScriptPath: string,
+	socketPath: string,
+): Promise<void> => {
+	const shimPath = join(sessionPath, 'bin', 'browser');
+	const content = `#!/bin/sh\nexec node ${clientScriptPath} --socket ${socketPath} "$@"\n`;
+	await writeFile(shimPath, content);
+	await chmod(shimPath, 0o755);
+};

package/src/lib/snapshot.ts

@@ -0,0 +1,351 @@
+import type { Locator, Page } from 'playwright';
+
+// #region role sets
+
+/** roles that represent interactive elements — always get refs */
+const INTERACTIVE_ROLES = new Set([
+	'button',
+	'link',
+	'textbox',
+	'checkbox',
+	'radio',
+	'combobox',
+	'listbox',
+	'menuitem',
+	'menuitemcheckbox',
+	'menuitemradio',
+	'option',
+	'searchbox',
+	'slider',
+	'spinbutton',
+	'switch',
+	'tab',
+	'treeitem',
+]);
+
+/** content roles — get refs only when they have a name */
+const CONTENT_ROLES = new Set([
+	'heading',
+	'cell',
+	'gridcell',
+	'columnheader',
+	'rowheader',
+	'listitem',
+	'article',
+	'region',
+	'main',
+	'navigation',
+]);
+
+/** structural roles — stripped in compact mode when unnamed */
+const STRUCTURAL_ROLES = new Set([
+	'generic',
+	'group',
+	'list',
+	'table',
+	'row',
+	'rowgroup',
+	'grid',
+	'treegrid',
+	'menu',
+	'menubar',
+	'toolbar',
+	'tablist',
+	'tree',
+	'directory',
+	'document',
+	'application',
+	'presentation',
+	'none',
+]);
+
+// #endregion
+
+// #region ref types
+
+export interface RefEntry {
+	role: string;
+	name: string | undefined;
+	nth: number | undefined;
+}
+
+/** mapping of ref id (e.g. "e1") to locator metadata */
+export type RefMap = Record<string, RefEntry>;
+
+// #endregion
+
+// #region role name tracker
+
+interface RoleNameTracker {
+	getNextIndex(role: string, name: string | undefined): number;
+	trackRef(role: string, name: string | undefined, ref: string): void;
+	getDuplicateKeys(): Set<string>;
+}
+
+const makeKey = (role: string, name: string | undefined): string => `${role}:${name ?? ''}`;
+
+const createRoleNameTracker = (): RoleNameTracker => {
+	const counts = new Map<string, number>();
+	const refsByKey = new Map<string, string[]>();
+
+	return {
+		getNextIndex(role, name) {
+			const key = makeKey(role, name);
+			const index = counts.get(key) ?? 0;
+			counts.set(key, index + 1);
+			return index;
+		},
+
+		trackRef(role, name, ref) {
+			const key = makeKey(role, name);
+			const existing = refsByKey.get(key);
+			if (existing) {
+				existing.push(ref);
+			} else {
+				refsByKey.set(key, [ref]);
+			}
+		},
+
+		getDuplicateKeys() {
+			const dupes = new Set<string>();
+			for (const [key, refs] of refsByKey) {
+				if (refs.length > 1) {
+					dupes.add(key);
+				}
+			}
+			return dupes;
+		},
+	};
+};
+
+// #endregion
+
+// #region snapshot options
+
+export interface SnapshotOptions {
+	/** only show interactive elements */
+	interactive?: boolean;
+	/** strip unnamed structural roles and prune empty branches */
+	compact?: boolean;
+	/** max depth of the tree */
+	depth?: number;
+	/** CSS selector to scope the snapshot to */
+	selector?: string;
+}
+
+// #endregion
+
+// #region aria tree line regex
+// matches: `  - role "name" [attr=val]` or `  - role:` etc.
+const LINE_RE = /^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/;
+// #endregion
+
+// #region snapshot parsing
+
+/**
+ * takes a snapshot of the page's accessibility tree and assigns element refs.
+ * @param page the Playwright page
+ * @param options snapshot options
+ * @returns object with the formatted snapshot text and the ref map
+ */
+export const takeSnapshot = async (
+	page: Page,
+	options: SnapshotOptions = {},
+): Promise<{ text: string; refs: RefMap }> => {
+	const locator: Locator = options.selector ? page.locator(options.selector) : page.locator('body');
+
+	const ariaTree = await locator.ariaSnapshot();
+
+	const refs: RefMap = {};
+	let refCounter = 0;
+	const tracker = createRoleNameTracker();
+
+	const nextRef = (): string => `e${++refCounter}`;
+
+	const lines = ariaTree.split('\n');
+	const output: Array<{ text: string; depth: number; hasRef: boolean; hasContent: boolean }> = [];
+
+	for (const line of lines) {
+		const match = line.match(LINE_RE);
+
+		if (!match) {
+			// non-role lines (plain text, metadata) — keep in full mode, skip in interactive
+			if (!options.interactive) {
+				const depth = Math.floor((line.search(/\S/) || 0) / 2);
+				output.push({ text: line, depth, hasRef: false, hasContent: line.trim().length > 0 });
+			}
+			continue;
+		}
+
+		const [, prefix, role, name, suffix] = match;
+		const roleLower = role!.toLowerCase();
+		const depth = Math.floor((prefix!.search(/\S/) === -1 ? prefix!.length : prefix!.search(/\S/)) / 2);
+
+		// depth filtering
+		if (options.depth !== undefined && depth > options.depth) {
+			continue;
+		}
+
+		const isInteractive = INTERACTIVE_ROLES.has(roleLower);
+		const isContent = CONTENT_ROLES.has(roleLower);
+		const isStructural = STRUCTURAL_ROLES.has(roleLower);
+
+		// interactive-only mode: skip non-interactive elements
+		if (options.interactive && !isInteractive) {
+			continue;
+		}
+
+		// compact mode: drop unnamed structural elements (pruning happens later)
+		if (options.compact && isStructural && !name) {
+			continue;
+		}
+
+		// determine if this element gets a ref
+		const shouldHaveRef = isInteractive || (isContent && !!name);
+
+		let refTag = '';
+		if (shouldHaveRef) {
+			const ref = nextRef();
+			const nth = tracker.getNextIndex(roleLower, name);
+			tracker.trackRef(roleLower, name, ref);
+
+			refs[ref] = { role: roleLower, name, nth };
+			refTag = ` [ref=${ref}]`;
+		}
+
+		// reconstruct line with ref tag
+		const nthTag =
+			shouldHaveRef && refs[`e${refCounter}`]?.nth ? ` [nth=${refs[`e${refCounter}`]!.nth}]` : '';
+		const reconstructed = name
+			? `${prefix}${role} "${name}"${refTag}${nthTag}${suffix}`
+			: `${prefix}${role}${refTag}${suffix}`;
+
+		const hasInlineContent = !!suffix && suffix.includes(':') && !suffix.endsWith(':');
+		output.push({
+			text: reconstructed,
+			depth,
+			hasRef: shouldHaveRef,
+			hasContent: hasInlineContent || !!name,
+		});
+	}
+
+	// post-process: remove nth from non-duplicates
+	{
+		const dupes = tracker.getDuplicateKeys();
+		for (const [ref, entry] of Object.entries(refs)) {
+			const key = makeKey(entry.role, entry.name);
+			if (!dupes.has(key)) {
+				entry.nth = undefined;
+				// also clean up the [nth=0] from output lines
+				const idx = output.findIndex((l) => l.text.includes(`[ref=${ref}]`));
+				if (idx !== -1) {
+					output[idx]!.text = output[idx]!.text.replace(/\s*\[nth=\d+\]/, '');
+				}
+			}
+		}
+	}
+
+	// compact mode: prune branches that have no refs
+	if (options.compact) {
+		const pruned = compactTree(output);
+		return { text: pruned.map((l) => l.text).join('\n'), refs };
+	}
+
+	return { text: output.map((l) => l.text).join('\n'), refs };
+};
+
+/**
+ * prunes branches from the tree that contain no refs.
+ * keeps: lines with refs, lines with inline content, and structural ancestors of ref-bearing lines.
+ */
+const compactTree = (
+	lines: Array<{ text: string; depth: number; hasRef: boolean; hasContent: boolean }>,
+): typeof lines => {
+	// mark lines that should be kept: has ref, or has inline content
+	const keep = Array.from({ length: lines.length }, () => false);
+
+	for (let i = 0; i < lines.length; i++) {
+		if (lines[i]!.hasRef || lines[i]!.hasContent) {
+			keep[i] = true;
+		}
+	}
+
+	// for each kept line, also keep all its ancestors
+	for (let i = 0; i < lines.length; i++) {
+		if (!keep[i]) {
+			continue;
+		}
+
+		const targetDepth = lines[i]!.depth;
+		// walk backwards to find ancestors at each shallower depth
+		for (let j = i - 1; j >= 0 && lines[j]!.depth < targetDepth; j--) {
+			if (!keep[j]) {
+				keep[j] = true;
+			}
+		}
+	}
+
+	return lines.filter((_, i) => keep[i]);
+};
+
+// #endregion
+
+// #region ref resolution
+
+/**
+ * parses a ref string (e.g. "@e1", "ref=e1", "e1") into the bare ref id.
+ * @param input the ref string
+ * @returns the bare ref id or null if not a valid ref format
+ */
+export const parseRef = (input: string): string | null => {
+	if (input.startsWith('@')) {
+		return input.slice(1);
+	}
+	if (input.startsWith('ref=')) {
+		return input.slice(4);
+	}
+	if (/^e\d+$/.test(input)) {
+		return input;
+	}
+	return null;
+};
+
+/**
+ * resolves a ref or CSS selector to a Playwright locator.
+ * @param page the Playwright page
+ * @param selectorOrRef a ref string (e.g. "@e1") or CSS selector
+ * @param refs the current ref map
+ * @returns the resolved Playwright locator
+ * @throws if a ref is provided but not found in the ref map
+ */
+export const resolveLocator = (page: Page, selectorOrRef: string, refs: RefMap): Locator => {
+	const ref = parseRef(selectorOrRef);
+
+	if (ref) {
+		const entry = refs[ref];
+		if (!entry) {
+			throw new Error(`ref ${selectorOrRef} not found — run snapshot to refresh refs`);
+		}
+
+		let locator: Locator;
+		if (entry.name) {
+			locator = page.getByRole(entry.role as Parameters<Page['getByRole']>[0], {
+				name: entry.name,
+				exact: true,
+			});
+		} else {
+			locator = page.getByRole(entry.role as Parameters<Page['getByRole']>[0]);
+		}
+
+		if (entry.nth !== undefined) {
+			locator = locator.nth(entry.nth);
+		}
+
+		return locator;
+	}
+
+	// fall back to CSS selector
+	return page.locator(selectorOrRef);
+};
+
+// #endregion