@f5-sales-demo/xcsh 19.51.2

package/src/browser/resolver.ts

@@ -0,0 +1,126 @@
+import type { ElementHandle, Page, SerializedAXNode } from "puppeteer";
+import { type AxNode, matchNode, matchNodes, NotFoundError } from "./ax";
+import {
+	CONTROL_SELECTOR,
+	findControlBearingAncestor,
+	findSectionContainer,
+	LABEL_SELECTORS,
+	normLabel,
+	STRIP_SUFFIX,
+} from "./dom-context";
+import { normLabel as dtNormLabel, findDatatableColumnInput } from "./dt-context";
+import { parseLocator } from "./selector";
+
+/** ARIA input roles treated as datatable column targets. */
+const DATATABLE_INPUT_ROLES = new Set(["textbox", "spinbutton", "searchbox", "combobox"]);
+
+/** Regex to detect a datatable-column context phrase (ends with " table" or " table row"). */
+const DATATABLE_CONTEXT_RE = /\s+table(?:\s+row)?$/i;
+
+/**
+ * Attempt to resolve a datatable column input by injecting the SAME
+ * (unit-tested) findDatatableColumnInput/normLabel into the live page via
+ * evaluateHandle — their source is reflected via .toString() of the real
+ * dt-context exports, so there is one canonical implementation with zero
+ * hand-copied logic here.
+ *
+ * Returns null (without throwing) when the datatable element is not found,
+ * so the caller can fall through to the generic context-scoping path.
+ */
+async function findDatatableColumnInputHandle(
+	page: Page,
+	columnName: string,
+	which: "first" | "last",
+): Promise<ElementHandle | null> {
+	const expr = `(() => {
+  const normLabel = ${dtNormLabel.toString()};
+  const findDatatableColumnInput = ${findDatatableColumnInput.toString()};
+  return findDatatableColumnInput(document, ${JSON.stringify(columnName)}, ${JSON.stringify(which)});
+})()`;
+
+	const handle = await page.evaluateHandle(expr);
+	const el = handle.asElement() as ElementHandle | null;
+	if (!el) {
+		await handle.dispose();
+		return null;
+	}
+	return el;
+}
+
+/**
+ * Resolve the section container for a `context` phrase by running the SAME
+ * (unit-tested) findSectionContainer/normLabel in the live page — their source
+ * is reflected via .toString() / JSON.stringify of the real dom-context exports,
+ * so there is one canonical implementation with zero hand-copied logic here.
+ */
+async function findSectionContainerHandle(page: Page, phrase: string): Promise<ElementHandle> {
+	// Build the injected IIFE entirely from the real dom-context exports.
+	// Declare dependencies before dependents (normLabel before findSectionContainer, etc.).
+	const expr = `(() => {
+  const STRIP_SUFFIX = ${STRIP_SUFFIX.toString()};
+  const LABEL_SELECTORS = ${JSON.stringify(LABEL_SELECTORS)};
+  const CONTROL_SELECTOR = ${JSON.stringify(CONTROL_SELECTOR)};
+  const normLabel = ${normLabel.toString()};
+  const findControlBearingAncestor = ${findControlBearingAncestor.toString()};
+  const findSectionContainer = ${findSectionContainer.toString()};
+  return findSectionContainer(document, ${JSON.stringify(phrase)});
+})()`;
+
+	const handle = await page.evaluateHandle(expr);
+	const el = handle.asElement() as ElementHandle | null;
+	if (!el) {
+		await handle.dispose();
+		throw new Error(`context container not found for "${phrase}"`);
+	}
+	return el;
+}
+
+export async function resolve(page: Page, selector: string, context?: string): Promise<ElementHandle> {
+	const loc = parseLocator(selector);
+	if (loc.kind === "css") {
+		const h = (await page.$(loc.css)) as ElementHandle | null;
+		if (!h) throw new Error(`CSS selector matched nothing: ${loc.css}`);
+		return h;
+	}
+
+	// Datatable column path — try BEFORE the generic context-scoping path.
+	// Triggered when: context ends with " table" or " table row" AND the
+	// locator targets an input-like ARIA role.
+	if (
+		context &&
+		DATATABLE_CONTEXT_RE.test(context) &&
+		(loc.kind === "role" || loc.kind === "roleName") &&
+		DATATABLE_INPUT_ROLES.has(loc.role)
+	) {
+		const columnName = context.replace(DATATABLE_CONTEXT_RE, "").trim();
+		const which: "first" | "last" = /row$/i.test(context) ? "last" : "first";
+		const dtHandle = await findDatatableColumnInputHandle(page, columnName, which);
+		if (dtHandle) return dtHandle;
+		// Fall through to the generic path if not found
+	}
+
+	let root: ElementHandle | undefined;
+	try {
+		if (context) root = await findSectionContainerHandle(page, context);
+		const snapshot = (await page.accessibility.snapshot({
+			interestingOnly: false,
+			...(root ? { root } : {}),
+		})) as SerializedAXNode | null;
+		if (!snapshot) throw new Error("accessibility snapshot unavailable");
+		let node: SerializedAXNode;
+		if (context) {
+			const axSnapshot = snapshot as unknown as AxNode;
+			const nodes = matchNodes(axSnapshot, loc);
+			if (nodes.length === 0)
+				throw new NotFoundError(`No AX node found for ${JSON.stringify(loc)} in context "${context}"`);
+			node = nodes[0] as unknown as SerializedAXNode;
+		} else {
+			node = matchNode(snapshot as unknown as AxNode, loc) as unknown as SerializedAXNode;
+		}
+		const handle = await node.elementHandle();
+		if (!handle) throw new Error(`matched AX node for "${selector}" has no backing DOM element`);
+		return handle as ElementHandle;
+	} finally {
+		if (root) await root.dispose().catch(() => {});
+	}
+}

package/src/browser/selector.ts

@@ -0,0 +1,40 @@
+export type Locator =
+	| { kind: "roleName"; role: string; name: string }
+	| { kind: "role"; role: string }
+	| { kind: "text"; text: string }
+	| { kind: "css"; css: string };
+
+/** ARIA roles the catalogue addresses by bare role or role+name. */
+export const KNOWN_ROLES: ReadonlySet<string> = new Set([
+	"button",
+	"tab",
+	"option",
+	"textbox",
+	"spinbutton",
+	"listbox",
+	"combobox",
+	"checkbox",
+	"radio",
+	"switch",
+	"link",
+	"menuitem",
+	"searchbox",
+	"slider",
+	"treeitem",
+]);
+
+const TEXT_RE = /^text\('([^']*)'\)$/;
+const ROLE_TEXT_RE = /^([a-z]+):text\('([^']*)'\)$/;
+const ROLE_NAME_RE = /^([a-z]+)\[name='([^']*)'\]$/;
+const BARE_ROLE_RE = /^[a-z]+$/;
+
+export function parseLocator(selector: string): Locator {
+	const text = selector.match(TEXT_RE);
+	if (text) return { kind: "text", text: text[1]! };
+	const roleText = selector.match(ROLE_TEXT_RE);
+	if (roleText) return { kind: "roleName", role: roleText[1]!, name: roleText[2]! };
+	const roleName = selector.match(ROLE_NAME_RE);
+	if (roleName) return { kind: "roleName", role: roleName[1]!, name: roleName[2]! };
+	if (BARE_ROLE_RE.test(selector) && KNOWN_ROLES.has(selector)) return { kind: "role", role: selector };
+	return { kind: "css", css: selector };
+}

package/src/bun-imports.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Type declarations for Bun's import attributes.
+ * These allow importing non-JS files as text at build time.
+ */
+
+// Markdown files imported as text
+declare module "*.md" {
+	const content: string;
+	export default content;
+}
+
+// Text files imported as text
+declare module "*.txt" {
+	const content: string;
+	export default content;
+}
+
+// Python files imported as text
+declare module "*.py" {
+	const content: string;
+	export default content;
+}

package/src/capability/context-file.ts

@@ -0,0 +1,43 @@
+/**
+ * Context Files Capability
+ *
+ * System instruction files (XCSH.md) that provide persistent guidance to the agent.
+ */
+import * as path from "node:path";
+import { defineCapability } from ".";
+import type { SourceMeta } from "./types";
+
+/**
+ * A context file that provides persistent instructions to the agent.
+ */
+export interface ContextFile {
+	/** Absolute path to the file */
+	path: string;
+	/** File content */
+	content: string;
+	/** Which level this came from */
+	level: "user" | "project";
+	/** Distance from cwd (0 = in cwd, 1 = parent, etc.) for project files */
+	depth?: number;
+	/** Source metadata */
+	_source: SourceMeta;
+}
+
+export const contextFileCapability = defineCapability<ContextFile>({
+	id: "context-files",
+	displayName: "Context Files",
+	description: "Persistent instruction files (XCSH.md) that guide agent behavior",
+	// Deduplicate by scope: one user-level file, and one project-level file per directory depth.
+	// Within each depth level, higher-priority providers shadow lower-priority ones.
+	// This supports monorepo hierarchies where XCSH.md exists at multiple ancestor levels.
+	// Clamp depth >= 0: files inside config subdirectories of an ancestor (e.g. .xcsh/, .github/)
+	// are same-scope as the ancestor itself.
+	key: file => (file.level === "user" ? "user" : `project:${Math.max(0, file.depth ?? 0)}`),
+	toExtensionId: file => `context-file:${file.level}:${path.basename(file.path)}`,
+	validate: file => {
+		if (!file.path) return "Missing path";
+		if (file.content === undefined) return "Missing content";
+		if (file.level !== "user" && file.level !== "project") return "Invalid level: must be 'user' or 'project'";
+		return undefined;
+	},
+});

package/src/capability/extension-module.ts

@@ -0,0 +1,34 @@
+/**
+ * Extension Modules Capability
+ *
+ * TypeScript/JavaScript extension modules loaded by the extension system.
+ */
+import { defineCapability } from ".";
+import type { SourceMeta } from "./types";
+
+/**
+ * A loaded extension module.
+ */
+export interface ExtensionModule {
+	/** Extension module name (derived from path) */
+	name: string;
+	/** Absolute path to extension entrypoint */
+	path: string;
+	/** Source level */
+	level: "user" | "project";
+	/** Source metadata */
+	_source: SourceMeta;
+}
+
+export const extensionModuleCapability = defineCapability<ExtensionModule>({
+	id: "extension-modules",
+	displayName: "Extension Modules",
+	description: "TypeScript/JavaScript extension modules loaded by the extension system",
+	key: ext => ext.name,
+	toExtensionId: ext => `extension-module:${ext.name}`,
+	validate: ext => {
+		if (!ext.name) return "Missing name";
+		if (!ext.path) return "Missing path";
+		return undefined;
+	},
+});

package/src/capability/extension.ts

@@ -0,0 +1,47 @@
+/**
+ * Extensions Capability
+ *
+ * Gemini-style extensions that provide MCP servers, tools, and context.
+ */
+import { defineCapability } from ".";
+import type { MCPServer } from "./mcp";
+import type { SourceMeta } from "./types";
+
+/**
+ * Extension manifest structure.
+ */
+export interface ExtensionManifest {
+	name?: string;
+	description?: string;
+	mcpServers?: Record<string, Omit<MCPServer, "name" | "_source">>;
+	tools?: unknown[];
+	context?: unknown;
+}
+
+/**
+ * A loaded extension.
+ */
+export interface Extension {
+	/** Extension name (from manifest.name or directory name) */
+	name: string;
+	/** Absolute path to extension directory */
+	path: string;
+	/** Parsed manifest data */
+	manifest: ExtensionManifest;
+	/** Source level */
+	level: "user" | "project";
+	/** Source metadata */
+	_source: SourceMeta;
+}
+
+export const extensionCapability = defineCapability<Extension>({
+	id: "extensions",
+	displayName: "Extensions",
+	description: "Gemini-style extensions providing MCP servers, tools, and context",
+	key: ext => ext.name,
+	validate: ext => {
+		if (!ext.name) return "Missing extension name";
+		if (!ext.path) return "Missing extension path";
+		return undefined;
+	},
+});

package/src/capability/fs.ts

@@ -0,0 +1,107 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const contentCache = new Map<string, string | null>();
+const dirCache = new Map<string, fs.Dirent[]>();
+
+function resolvePath(filePath: string): string {
+	return path.resolve(filePath);
+}
+
+export async function readFile(filePath: string): Promise<string | null> {
+	const abs = resolvePath(filePath);
+	if (contentCache.has(abs)) {
+		return contentCache.get(abs) ?? null;
+	}
+
+	try {
+		const content = await Bun.file(abs).text();
+		contentCache.set(abs, content);
+		return content;
+	} catch {
+		contentCache.set(abs, null);
+		return null;
+	}
+}
+
+export async function readDirEntries(dirPath: string): Promise<fs.Dirent[]> {
+	const abs = resolvePath(dirPath);
+	if (dirCache.has(abs)) {
+		return dirCache.get(abs) ?? [];
+	}
+
+	try {
+		const entries = await fs.promises.readdir(abs, { withFileTypes: true });
+		dirCache.set(abs, entries);
+		return entries;
+	} catch {
+		dirCache.set(abs, []);
+		return [];
+	}
+}
+
+export async function readDir(dirPath: string): Promise<string[]> {
+	const entries = await readDirEntries(dirPath);
+	return entries.map(entry => entry.name);
+}
+
+export async function walkUp(
+	startDir: string,
+	name: string,
+	opts: { file?: boolean; dir?: boolean } = {},
+): Promise<string | null> {
+	const { file = true, dir = true } = opts;
+	let current = resolvePath(startDir);
+
+	while (true) {
+		const entries = await readDirEntries(current);
+		const entry = entries.find(e => e.name === name);
+		if (entry) {
+			if (file && entry.isFile()) return path.join(current, name);
+			if (dir && entry.isDirectory()) return path.join(current, name);
+		}
+		const parent = path.dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+}
+
+/**
+ * Walk up from startDir looking for a `.git` entry (file or directory).
+ * Returns the directory containing `.git` (the repo root), or null if not in a git repo.
+ * Results are based on the cached readDirEntries, so repeated calls are cheap.
+ */
+export async function findRepoRoot(startDir: string): Promise<string | null> {
+	let current = resolvePath(startDir);
+	while (true) {
+		const entries = await readDirEntries(current);
+		if (entries.some(e => e.name === ".git")) {
+			return current;
+		}
+		const parent = path.dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+}
+
+export function cacheStats(): { content: number; dir: number } {
+	return {
+		content: contentCache.size,
+		dir: dirCache.size,
+	};
+}
+
+export function clearCache(): void {
+	contentCache.clear();
+	dirCache.clear();
+}
+
+export function invalidate(filePath: string): void {
+	const abs = resolvePath(filePath);
+	contentCache.delete(abs);
+	dirCache.delete(abs);
+	const parent = path.dirname(abs);
+	if (parent !== abs) {
+		dirCache.delete(parent);
+	}
+}

package/src/capability/hook.ts

@@ -0,0 +1,40 @@
+/**
+ * Hooks Capability
+ *
+ * Pre/post tool execution hooks defined as shell scripts.
+ */
+import { defineCapability } from ".";
+import type { SourceMeta } from "./types";
+
+/**
+ * A hook script.
+ */
+export interface Hook {
+	/** Hook name (filename without extension) */
+	name: string;
+	/** Absolute path to hook file */
+	path: string;
+	/** Hook type (pre/post) and associated tool */
+	type: "pre" | "post";
+	/** Tool this hook applies to, or "*" for all */
+	tool: string;
+	/** Source level */
+	level: "user" | "project";
+	/** Source metadata */
+	_source: SourceMeta;
+}
+
+export const hookCapability = defineCapability<Hook>({
+	id: "hooks",
+	displayName: "Hooks",
+	description: "Pre/post tool execution hooks",
+	key: hook => `${hook.type}:${hook.tool}:${hook.name}`,
+	toExtensionId: hook => `hook:${hook.type}:${hook.tool}:${hook.name}`,
+	validate: hook => {
+		if (!hook.name) return "Missing name";
+		if (!hook.path) return "Missing path";
+		if (hook.type !== "pre" && hook.type !== "post") return "Invalid type (must be 'pre' or 'post')";
+		if (!hook.tool) return "Missing tool";
+		return undefined;
+	},
+});