@f5-sales-demo/xcsh 19.51.2

package/src/browser/ax.ts

@@ -0,0 +1,134 @@
+import type { Locator } from "./selector";
+
+export interface AxNode {
+	role: string;
+	name?: string;
+	children?: AxNode[];
+	[k: string]: unknown;
+}
+
+export class NotFoundError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "NotFoundError";
+	}
+}
+
+export class AmbiguousError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "AmbiguousError";
+	}
+}
+
+function norm(s: string): string {
+	return s.trim().replace(/\s+/g, " ");
+}
+
+function collect(node: AxNode, results: AxNode[]): void {
+	results.push(node);
+	for (const child of node.children ?? []) {
+		collect(child, results);
+	}
+}
+
+export function matchNode(tree: AxNode, loc: Locator): AxNode {
+	if (loc.kind === "css") {
+		throw new Error("css locators cannot be resolved against an AX tree — resolve live via CDP");
+	}
+
+	const all: AxNode[] = [];
+	collect(tree, all);
+
+	let matches: AxNode[];
+
+	if (loc.kind === "roleName") {
+		const wantRole = loc.role;
+		const wantName = norm(loc.name);
+		matches = all.filter(n => {
+			if (n.role !== wantRole) return false;
+			const nodeName = norm(n.name ?? "");
+			// roleName from role:text('X') pattern — text match (includes)
+			// roleName from role[name='X'] pattern — exact match
+			// We always use exact match for roleName kind (the parser normalises both patterns to roleName)
+			return nodeName === wantName;
+		});
+	} else if (loc.kind === "role") {
+		matches = all.filter(n => n.role === loc.role);
+	} else {
+		// kind === "text"
+		const want = norm(loc.text);
+		matches = all.filter(n => {
+			const nodeName = norm(n.name ?? "");
+			return nodeName === want || nodeName.includes(want);
+		});
+	}
+
+	if (matches.length === 0) {
+		// Collect candidates for helpful error message
+		let hint = "";
+		if (loc.kind === "roleName" || loc.kind === "role") {
+			const sameRole = all.filter(n => n.role === loc.role && n.name).map(n => JSON.stringify(n.name));
+			if (sameRole.length > 0) {
+				hint = ` (same-role candidates: ${sameRole.slice(0, 5).join(", ")})`;
+			}
+		} else if (loc.kind === "text") {
+			// For text kind, list nearby text candidates (non-empty normalized names)
+			const textCandidates: string[] = [];
+			const seen = new Set<string>();
+			for (const node of all) {
+				if (node.name) {
+					const normalized = norm(node.name);
+					if (normalized.length > 0 && !seen.has(normalized)) {
+						seen.add(normalized);
+						textCandidates.push(JSON.stringify(normalized));
+						if (textCandidates.length >= 5) break;
+					}
+				}
+			}
+			if (textCandidates.length > 0) {
+				hint = ` (nearby text candidates: ${textCandidates.join(", ")})`;
+			}
+		}
+		throw new NotFoundError(`No AX node found for ${JSON.stringify(loc)}${hint}`);
+	}
+
+	// For text locators, return the first match (presence semantics).
+	// For roleName and role, enforce strict 1:1 matching.
+	if (loc.kind === "text") {
+		return matches[0]!;
+	}
+
+	if (matches.length > 1) {
+		const names = matches.map(n => JSON.stringify(n.name ?? n.role));
+		throw new AmbiguousError(
+			`${matches.length} AX nodes match ${JSON.stringify(loc)}: ${names.slice(0, 5).join(", ")}`,
+		);
+	}
+
+	return matches[0]!;
+}
+
+export function matchNodes(tree: AxNode, loc: Locator): AxNode[] {
+	if (loc.kind === "css") {
+		throw new Error("css locators cannot be resolved against an AX tree — resolve live via CDP");
+	}
+
+	const all: AxNode[] = [];
+	collect(tree, all);
+
+	if (loc.kind === "roleName") {
+		const wantRole = loc.role;
+		const wantName = norm(loc.name);
+		return all.filter(n => n.role === wantRole && norm(n.name ?? "") === wantName);
+	} else if (loc.kind === "role") {
+		return all.filter(n => n.role === loc.role);
+	} else {
+		// kind === "text"
+		const want = norm(loc.text);
+		return all.filter(n => {
+			const nodeName = norm(n.name ?? "");
+			return nodeName === want || nodeName.includes(want);
+		});
+	}
+}

package/src/browser/cdp-core.ts

@@ -0,0 +1,45 @@
+import type { Browser, CDPSession, Page } from "puppeteer";
+import type { AcquireMode } from "./acquire";
+
+type Settings = { get(key: string): unknown };
+
+export class BrowserSession {
+	#browser: Browser | null = null;
+	#page: Page | null = null;
+	#cdp: CDPSession | null = null;
+	#mode: AcquireMode | null = null;
+	constructor(private readonly settings: Settings) {}
+
+	get mode(): AcquireMode | null {
+		return this.#mode;
+	}
+
+	async ensurePage(): Promise<Page> {
+		if (this.#page && !this.#page.isClosed()) return this.#page;
+		const { acquirePage } = await import("./acquire");
+		const { browser, page, mode } = await acquirePage({ settings: this.settings });
+		this.#browser = browser;
+		this.#page = page;
+		this.#mode = mode;
+		this.#cdp = null;
+		return this.#page;
+	}
+
+	async cdp(): Promise<CDPSession> {
+		const page = await this.ensurePage();
+		if (!this.#cdp) this.#cdp = await page.createCDPSession();
+		return this.#cdp;
+	}
+
+	async close(): Promise<void> {
+		if (this.#browser) {
+			// Never terminate the user's Chrome (attached or launched against their profile);
+			// just detach. Puppeteer's disconnect leaves the browser running.
+			await this.#browser.disconnect().catch(() => {});
+		}
+		this.#browser = null;
+		this.#page = null;
+		this.#cdp = null;
+		this.#mode = null;
+	}
+}

package/src/browser/cdp-page-actions.ts

@@ -0,0 +1,51 @@
+import type { Page } from "puppeteer";
+import * as actions from "./actions";
+import type { PageActions } from "./page-actions";
+
+/** CDP-backed `PageActions`: wraps a Puppeteer `Page` and delegates to `actions.ts`. */
+export class CdpPageActions implements PageActions {
+	#page: Page;
+	constructor(page: Page) {
+		this.#page = page;
+	}
+
+	async goto(url: string, opts?: { waitUntil?: string; timeout?: number }): Promise<void> {
+		type GotoOptions = NonNullable<Parameters<Page["goto"]>[1]>;
+		await this.#page.goto(url, {
+			waitUntil: (opts?.waitUntil as GotoOptions["waitUntil"]) ?? "networkidle2",
+			timeout: opts?.timeout,
+		});
+	}
+
+	async click(selector: string, context?: string): Promise<void> {
+		await actions.click(this.#page, selector, context);
+	}
+
+	async fill(selector: string, value: string, context?: string): Promise<void> {
+		await actions.fill(this.#page, selector, value, context);
+	}
+
+	async selectOption(selector: string, value: string, context?: string): Promise<void> {
+		await actions.selectOption(this.#page, selector, value, context);
+	}
+
+	async scrollIntoView(selector: string, context?: string): Promise<void> {
+		await actions.scrollIntoView(this.#page, selector, context);
+	}
+
+	async pressKey(key: string): Promise<void> {
+		await actions.pressKey(this.#page, key);
+	}
+
+	async assertText(selector: string, expected: string, context?: string): Promise<void> {
+		await actions.assertText(this.#page, selector, expected, context);
+	}
+
+	async waitFor(selector: string, context?: string, timeoutMs?: number): Promise<void> {
+		await actions.waitFor(this.#page, selector, context, timeoutMs);
+	}
+
+	async screenshot(file: string): Promise<void> {
+		await actions.screenshot(this.#page, file);
+	}
+}

package/src/browser/chrome-locate.ts

@@ -0,0 +1,66 @@
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface LocateChromeOpts {
+	settings?: { get(key: string): unknown };
+	platform?: NodeJS.Platform;
+	env?: NodeJS.ProcessEnv;
+	exists?: (p: string) => boolean;
+	which?: (cmd: string) => string | null;
+}
+
+export interface LocatedChrome {
+	path: string;
+	source: "setting" | "macos" | "path" | "nixos" | "windows";
+}
+
+function defaultWhich(cmd: string): string | null {
+	try {
+		const out = execFileSync("sh", ["-c", `command -v ${cmd}`], { encoding: "utf-8" }).trim();
+		return out || null;
+	} catch {
+		return null;
+	}
+}
+
+export function locateChrome(opts: LocateChromeOpts = {}): LocatedChrome | null {
+	const platform = opts.platform ?? process.platform;
+	const env = opts.env ?? process.env;
+	const exists = opts.exists ?? ((p: string) => fs.existsSync(p));
+	const which = opts.which ?? defaultWhich;
+
+	const override = opts.settings?.get("browser.chromePath");
+	if (typeof override === "string" && override.trim() && exists(override.trim())) {
+		return { path: override.trim(), source: "setting" };
+	}
+
+	if (platform === "darwin") {
+		const macCandidates = [
+			"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+			"/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+			"/Applications/Chromium.app/Contents/MacOS/Chromium",
+		];
+		for (const c of macCandidates) if (exists(c)) return { path: c, source: "macos" };
+		return null;
+	}
+
+	if (platform === "win32") {
+		const roots = [env.PROGRAMFILES, env["PROGRAMFILES(X86)"], env.LOCALAPPDATA].filter(Boolean) as string[];
+		for (const root of roots) {
+			const c = path.join(root, "Google", "Chrome", "Application", "chrome.exe");
+			if (exists(c)) return { path: c, source: "windows" };
+		}
+		return null;
+	}
+
+	// linux / other unix
+	for (const cmd of ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser"]) {
+		const found = which(cmd);
+		if (found) return { path: found, source: "path" };
+	}
+	for (const c of [path.join(env.HOME ?? "", ".nix-profile/bin/chromium"), "/run/current-system/sw/bin/chromium"]) {
+		if (c && exists(c)) return { path: c, source: "nixos" };
+	}
+	return null;
+}

package/src/browser/dom-context.ts

@@ -0,0 +1,89 @@
+/**
+ * DOM context scoping for XC component classes.
+ * Pure module — no Puppeteer imports. Works under linkedom in tests and
+ * the live document in page.evaluate in the resolver (Task 5).
+ *
+ * We define minimal structural interfaces instead of relying on the DOM lib
+ * (the project tsconfig does not include DOM types globally).
+ */
+
+/** Minimal structural interface matching both linkedom and browser Element. */
+export interface DomElement {
+	tagName: string;
+	textContent: string | null;
+	className: string | { toString(): string };
+	parentElement: DomElement | null;
+	querySelector(sel: string): DomElement | null;
+	querySelectorAll(sel: string): ArrayLike<DomElement>;
+}
+
+/** Minimal structural interface matching both linkedom and browser Document. */
+export interface DomDocument {
+	body: DomElement | null;
+	documentElement: DomElement;
+	querySelectorAll(sel: string): ArrayLike<DomElement>;
+}
+
+/** Strip a leading asterisk, trim, and collapse internal whitespace. */
+export function normLabel(s: string): string {
+	return s.trim().replace(/^\*/, "").trim().replace(/\s+/g, " ");
+}
+
+/** Suffixes we strip before matching a label phrase. */
+export const STRIP_SUFFIX = / (?:section|table|table row|selector)$/i;
+
+/** CSS selectors that identify XC field/section labels. */
+export const LABEL_SELECTORS = [
+	"label.ves-label_level_3_label",
+	"label[class*='ves-label_level_3_label']",
+	".datatable-header-cell-label",
+	".tile-header__name",
+	"label.form-control-label",
+];
+
+/** CSS that identifies "interactive" controls — presence means the ancestor is the section container. */
+export const CONTROL_SELECTOR = "button, [role='listbox'], .listbox, input";
+
+/**
+ * Find the nearest ancestor element that:
+ *   1. Is an ancestor of the matched label element, AND
+ *   2. Contains at least one interactive control (button / listbox / input).
+ *
+ * Walk up from the label, stopping at `document.body` (or `documentElement`).
+ */
+export function findControlBearingAncestor(label: DomElement, doc: DomDocument): DomElement | null {
+	const body = doc.body ?? doc.documentElement;
+	let current: DomElement | null = label.parentElement;
+	while (current && current !== body) {
+		if (current.querySelector(CONTROL_SELECTOR)) {
+			return current;
+		}
+		current = current.parentElement;
+	}
+	return null;
+}
+
+/**
+ * Given a phrase like "Domains table" or "Origin Pools section",
+ * strip the trailing qualifier, find the matching label element in the DOM,
+ * then return the nearest ancestor that contains an interactive control.
+ *
+ * Returns `null` if no label or no control-bearing ancestor is found.
+ */
+export function findSectionContainer(doc: DomDocument, phrase: string): DomElement | null {
+	const bare = phrase.replace(STRIP_SUFFIX, "").trim();
+	const want = normLabel(bare);
+
+	// Try each label selector in priority order
+	for (const sel of LABEL_SELECTORS) {
+		const candidates = Array.from(doc.querySelectorAll(sel));
+		for (const el of candidates) {
+			if (normLabel(el.textContent ?? "") === want) {
+				const container = findControlBearingAncestor(el, doc);
+				if (container) return container;
+			}
+		}
+	}
+
+	return null;
+}

package/src/browser/dt-context.ts

@@ -0,0 +1,100 @@
+/**
+ * ngx-datatable column-aware cell resolver for XC CDP accessibility.
+ * Pure module — no Puppeteer imports. Works under linkedom in tests and
+ * in page.evaluateHandle in the resolver (injected as IIFE via .toString()).
+ *
+ * Structural interfaces match both linkedom and browser DOM without
+ * requiring a global DOM lib.
+ */
+
+/** Minimal structural interface matching both linkedom and browser Element. */
+interface DtElement {
+	textContent: string | null;
+	querySelectorAll(sel: string): ArrayLike<DtElement>;
+	querySelector(sel: string): DtElement | null;
+}
+
+/** Minimal structural interface matching both linkedom and browser Document. */
+interface DtDocument {
+	querySelectorAll(sel: string): ArrayLike<DtElement>;
+}
+
+/**
+ * Strip a leading asterisk, trim, and collapse internal whitespace.
+ * Self-contained copy so the injection IIFE is standalone (no imports).
+ */
+export function normLabel(s: string): string {
+	return s.trim().replace(/^\*/, "").trim().replace(/\s+/g, " ");
+}
+
+/**
+ * Find the input (or textarea / [role=textbox]) in a specific ngx-datatable
+ * column cell.
+ *
+ * Algorithm:
+ *   1. Scan every `.datatable-header-cell-label` for one whose normLabel
+ *      matches the given columnName.
+ *   2. Walk up to the enclosing ngx-datatable (the element that owns the
+ *      header cells array).
+ *   3. Determine the column index = position of the matched header cell among
+ *      all `.datatable-header-cell` elements inside that datatable.
+ *   4. Pick the body row: `which === "last"` → last `.datatable-body-row`,
+ *      else first.
+ *   5. Return the first `input`, `textarea`, or `[role=textbox]` inside the
+ *      `.datatable-body-cell` at the resolved column index.
+ *
+ * Uses only standard DOM querySelectorAll / textContent APIs so it works
+ * under linkedom AND in the live browser page.
+ */
+export function findDatatableColumnInput(
+	doc: DtDocument,
+	columnName: string,
+	which: "first" | "last",
+): DtElement | null {
+	const wantName = normLabel(columnName);
+
+	// Step 1 — find the header label element that matches columnName
+	const allLabels = Array.from(doc.querySelectorAll(".datatable-header-cell-label"));
+	const matchedLabel = allLabels.find(lbl => normLabel(lbl.textContent ?? "") === wantName);
+	if (!matchedLabel) return null;
+
+	// Step 2 — collect ALL header cells from the entire document and determine
+	// which datatable owns the matched label.  We do this by finding the header
+	// cell that CONTAINS the matched label, then looking at the ordered list of
+	// all header cells to derive the index.
+	const allHeaderCells = Array.from(doc.querySelectorAll(".datatable-header-cell"));
+	const matchedHeaderCell = allHeaderCells.find(cell => {
+		const labels = Array.from(cell.querySelectorAll(".datatable-header-cell-label"));
+		return labels.some(lbl => normLabel(lbl.textContent ?? "") === wantName);
+	});
+	if (!matchedHeaderCell) return null;
+
+	// Step 3 — column index = position of matched header cell within ALL header
+	// cells that share the same datatable ancestor.  Because ngx-datatable puts
+	// all its header cells under a single <datatable-header>, the relative order
+	// in document order == the column index.
+	//
+	// To scope to the correct datatable, we collect only the header cells that
+	// appear before the FIRST body row of a different datatable.  In the common
+	// single-datatable case, the simple index into allHeaderCells works directly.
+	const colIndex = allHeaderCells.indexOf(matchedHeaderCell);
+	if (colIndex === -1) return null;
+
+	// Step 4 — pick the body row
+	const allBodyRows = Array.from(doc.querySelectorAll(".datatable-body-row"));
+	if (allBodyRows.length === 0) return null;
+	const row = which === "last" ? allBodyRows[allBodyRows.length - 1]! : allBodyRows[0]!;
+
+	// Step 5 — get the body cell at the same column index
+	const bodyCells = Array.from(row.querySelectorAll(".datatable-body-cell"));
+	const targetCell = bodyCells[colIndex];
+	if (!targetCell) return null;
+
+	// Return the first interactive text input inside the cell
+	return (
+		targetCell.querySelector("input") ??
+		targetCell.querySelector("textarea") ??
+		targetCell.querySelector("[role=textbox]") ??
+		null
+	);
+}

package/src/browser/extension-bridge.ts

@@ -0,0 +1,182 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { Socket, UnixSocketListener } from "bun";
+
+export interface ToolResult {
+	content: unknown;
+	is_error: boolean;
+}
+
+/**
+ * Id-correlated pending-request registry. Pure (no socket I/O) so it can be
+ * unit-tested directly. Each {@link create} returns a fresh id and a promise
+ * that is settled by a later {@link resolve} (matching id) or {@link rejectAll}.
+ */
+export class PendingRequests {
+	#m = new Map<
+		string,
+		{
+			resolve: (r: ToolResult) => void;
+			reject: (e: Error) => void;
+			timer: ReturnType<typeof setTimeout>;
+		}
+	>();
+
+	create(timeoutMs: number): { id: string; promise: Promise<ToolResult> } {
+		const id = randomUUID();
+		let resolve!: (r: ToolResult) => void;
+		let reject!: (e: Error) => void;
+		const promise = new Promise<ToolResult>((res, rej) => {
+			resolve = res;
+			reject = rej;
+		});
+		const timer = setTimeout(() => {
+			if (this.#m.delete(id)) reject(new Error(`bridge request ${id} timed out`));
+		}, timeoutMs);
+		this.#m.set(id, { resolve, reject, timer });
+		return { id, promise };
+	}
+
+	resolve(id: string, result: ToolResult): boolean {
+		const e = this.#m.get(id);
+		if (!e) return false;
+		clearTimeout(e.timer);
+		this.#m.delete(id);
+		e.resolve(result);
+		return true;
+	}
+
+	rejectAll(err: Error): void {
+		for (const e of this.#m.values()) {
+			clearTimeout(e.timer);
+			e.reject(err);
+		}
+		this.#m.clear();
+	}
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+type BridgeData = { buf: string };
+
+/**
+ * Unix-socket server bridging xcsh to the Chrome extension's native-messaging
+ * host. Speaks newline-delimited JSON: requests `{type:"tool_request",...}`,
+ * replies `{type:"tool_result",...}`, plus `{type:"ping"|"pong"}`. Tracks a
+ * single connected client and correlates replies via {@link PendingRequests}.
+ */
+export class BridgeServer {
+	#pending = new PendingRequests();
+	#listener: UnixSocketListener<BridgeData> | null = null;
+	#client: Socket<BridgeData> | null = null;
+	#onConnected: Array<() => void> = [];
+	#onDisconnected: Array<() => void> = [];
+
+	get connected(): boolean {
+		return this.#client !== null;
+	}
+
+	onConnected(cb: () => void): void {
+		this.#onConnected.push(cb);
+	}
+
+	onDisconnected(cb: () => void): void {
+		this.#onDisconnected.push(cb);
+	}
+
+	/** Bind the server to a Unix socket path. Called by {@link startBridgeServer}. */
+	listen(socketPath: string): void {
+		this.#listener = Bun.listen<BridgeData>({
+			unix: socketPath,
+			socket: {
+				open: socket => {
+					socket.data = { buf: "" };
+					this.#client = socket;
+					for (const cb of this.#onConnected) cb();
+				},
+				data: (socket, chunk) => {
+					this.#onData(socket, chunk);
+				},
+				close: socket => {
+					this.#onClose(socket);
+				},
+				error: socket => {
+					this.#onClose(socket);
+				},
+			},
+		});
+	}
+
+	#onData(socket: Socket<BridgeData>, chunk: Buffer): void {
+		socket.data.buf += chunk.toString("utf8");
+		let idx = socket.data.buf.indexOf("\n");
+		while (idx !== -1) {
+			const line = socket.data.buf.slice(0, idx);
+			socket.data.buf = socket.data.buf.slice(idx + 1);
+			if (line.length > 0) this.#handleLine(socket, line);
+			idx = socket.data.buf.indexOf("\n");
+		}
+	}
+
+	#handleLine(socket: Socket<BridgeData>, line: string): void {
+		let msg: { type?: string; id?: string; content?: unknown; is_error?: boolean };
+		try {
+			msg = JSON.parse(line);
+		} catch {
+			return;
+		}
+		if (msg.type === "tool_result" && typeof msg.id === "string") {
+			this.#pending.resolve(msg.id, {
+				content: msg.content,
+				is_error: msg.is_error === true,
+			});
+		} else if (msg.type === "ping") {
+			this.#write(socket, { type: "pong" });
+		}
+	}
+
+	#onClose(socket: Socket<BridgeData>): void {
+		if (this.#client !== socket) return;
+		this.#client = null;
+		this.#pending.rejectAll(new Error("bridge client disconnected"));
+		for (const cb of this.#onDisconnected) cb();
+	}
+
+	#write(socket: Socket<BridgeData>, msg: unknown): void {
+		socket.write(`${JSON.stringify(msg)}\n`);
+	}
+
+	/** Send a `tool_request` to the connected client and await its `tool_result`. */
+	request(tool: string, params: unknown, timeoutMs: number = DEFAULT_TIMEOUT_MS): Promise<ToolResult> {
+		const client = this.#client;
+		if (!client) return Promise.reject(new Error("bridge: no client connected"));
+		const { id, promise } = this.#pending.create(timeoutMs);
+		this.#write(client, { type: "tool_request", id, tool, params });
+		return promise;
+	}
+
+	async close(): Promise<void> {
+		this.#pending.rejectAll(new Error("bridge server closed"));
+		this.#client?.end();
+		this.#client = null;
+		this.#listener?.stop(true);
+		this.#listener = null;
+	}
+}
+
+/**
+ * Resolve the default socket path (`~/.xcsh/chrome-bridge.sock`), ensure the
+ * directory exists, remove any stale socket, start the {@link BridgeServer},
+ * and tighten the socket permissions to owner-only (0600).
+ */
+export async function startBridgeServer(socketPath?: string): Promise<BridgeServer> {
+	const resolved = socketPath ?? path.join(os.homedir(), ".xcsh", "chrome-bridge.sock");
+	fs.mkdirSync(path.dirname(resolved), { recursive: true });
+	fs.rmSync(resolved, { force: true });
+	const server = new BridgeServer();
+	server.listen(resolved);
+	fs.chmodSync(resolved, 0o600);
+	return server;
+}