@f5-sales-demo/xcsh 19.53.1 → 19.54.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.53.1",
+	"version": "19.54.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -55,13 +55,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.53.1",
-		"@f5-sales-demo/pi-agent-core": "19.53.1",
-		"@f5-sales-demo/pi-ai": "19.53.1",
-		"@f5-sales-demo/pi-natives": "19.53.1",
-		"@f5-sales-demo/pi-resource-management": "19.53.1",
-		"@f5-sales-demo/pi-tui": "19.53.1",
-		"@f5-sales-demo/pi-utils": "19.53.1",
+		"@f5-sales-demo/xcsh-stats": "19.54.0",
+		"@f5-sales-demo/pi-agent-core": "19.54.0",
+		"@f5-sales-demo/pi-ai": "19.54.0",
+		"@f5-sales-demo/pi-natives": "19.54.0",
+		"@f5-sales-demo/pi-resource-management": "19.54.0",
+		"@f5-sales-demo/pi-tui": "19.54.0",
+		"@f5-sales-demo/pi-utils": "19.54.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/scripts/demo-presentation.ts

@@ -0,0 +1,108 @@
+#!/usr/bin/env bun
+/**
+ * Live demo: drive console form-creates with the INSTRUCTOR presentation profile
+ * so a human watcher sees the agent's "human-like browsing" — fingerprint-before-
+ * click + highlight overlays, slow watchable pacing (2.2s/step), and full per-step
+ * narration. Built for showing the automation to an audience.
+ *
+ * Usage:
+ *   XCSH_BROWSER_PROVIDER=extension XCSH_API_URL=… XCSH_API_TOKEN=… XCSH_NAMESPACE=demo \
+ *   bun scripts/demo-presentation.ts [resource1 resource2 …]
+ *   (defaults to: health-check origin-pool)
+ */
+import * as path from "node:path";
+import { startBridgeServer } from "../src/browser/extension-bridge";
+import { ExtensionBrowserProvider } from "../src/browser/extension-provider";
+import { paramsFor } from "../src/sweep/sweep-params";
+import { apiItemPath } from "../src/sweep/sweep-scoring";
+import { CatalogWorkflowRunnerTool } from "../src/tools/catalog-workflow-runner";
+
+const NAMESPACE = process.env.XCSH_NAMESPACE ?? "demo";
+const BASE_URL = (process.env.XCSH_API_URL ?? "").replace(/\/+$/, "");
+const TOKEN = process.env.XCSH_API_TOKEN ?? "";
+const CONSOLE_ROOT = path.resolve(import.meta.dir, "../../../../console");
+const PROFILE = (process.env.XCSH_PRESENTATION ?? "instructor") as "guided" | "instructor";
+
+process.env.XCSH_BROWSER_PROVIDER ??= "extension";
+
+const RESOURCES = process.argv.slice(2).length ? process.argv.slice(2) : ["health-check", "origin-pool"];
+
+function sweepName(resource: string): string {
+	return `demo-${resource}`
+		.toLowerCase()
+		.replace(/[^a-z0-9-]/g, "-")
+		.slice(0, 63);
+}
+
+async function apiDelete(resource: string, name: string): Promise<void> {
+	if (!BASE_URL || !TOKEN) return;
+	for (const ns of [NAMESPACE, "system"]) {
+		await fetch(`${BASE_URL}${apiItemPath(resource, ns, name)}`, {
+			method: "DELETE",
+			headers: { Authorization: `APIToken ${TOKEN}` },
+			signal: AbortSignal.timeout(8000),
+		}).catch(() => {});
+	}
+}
+
+async function apiExists(resource: string, name: string): Promise<boolean> {
+	if (!BASE_URL || !TOKEN) return false;
+	for (const ns of [NAMESPACE, "system"]) {
+		try {
+			const r = await fetch(`${BASE_URL}${apiItemPath(resource, ns, name)}`, {
+				headers: { Authorization: `APIToken ${TOKEN}` },
+				signal: AbortSignal.timeout(8000),
+			});
+			if (r.ok) return true;
+		} catch {
+			/* try next */
+		}
+	}
+	return false;
+}
+
+async function main() {
+	console.log(`\n🎬 xcsh automation demo — profile: ${PROFILE} (fingerprint-before-click, highlights, narration)\n`);
+	const server = await startBridgeServer();
+	const tool = new CatalogWorkflowRunnerTool({ settings: { get: () => undefined } } as never);
+
+	console.log("  Waiting for the extension to connect (open Chrome with xcsh loaded)…");
+	const deadline = Date.now() + 60_000;
+	while (Date.now() < deadline && !server.connected) await new Promise(r => setTimeout(r, 300));
+	if (!server.connected) {
+		console.error("  ✗ Extension did not connect.");
+		await server.close();
+		process.exit(1);
+	}
+	console.log("  ✓ Extension connected.\n");
+	tool.setProvider(new ExtensionBrowserProvider({ server }));
+
+	for (const resource of RESOURCES) {
+		const name = sweepName(resource);
+		console.log(`\n▶ Creating ${resource} as "${name}" …`);
+		await apiDelete(resource, name); // clean so the create is real
+		await new Promise(r => setTimeout(r, 1500));
+		try {
+			await tool.execute(`${resource}-create`, {
+				resource,
+				operation: "create",
+				params: paramsFor(resource, { name, namespace: NAMESPACE }),
+				base_url: BASE_URL,
+				catalog_path: CONSOLE_ROOT,
+				presentation: PROFILE,
+			} as never);
+		} catch (e) {
+			console.error(`  ✗ ${resource}: ${e instanceof Error ? e.message : String(e)}`);
+		}
+		const ok = await apiExists(resource, name);
+		console.log(`  ${ok ? "✅" : "❌"} ${resource} ${ok ? "created (API-confirmed)" : "not created"}`);
+	}
+
+	console.log("\n🎬 Demo complete.\n");
+	await server.close();
+}
+
+main().catch(e => {
+	console.error(e);
+	process.exit(1);
+});

package/scripts/gen-specs.ts

@@ -0,0 +1,96 @@
+#!/usr/bin/env bun
+/**
+ * Generate minimal valid create specs for resources by walking the enriched
+ * OpenAPI schemas (openapi-spec.ts), then VALIDATE each against the live API by
+ * POSTing to the correct API-group path and deleting on success. Emits a
+ * resource→spec map + a pass/fail report. This is the hybrid spec source for the
+ * JSON-tab create path: OpenAPI structure, API as source of truth.
+ *
+ * Usage:
+ *   XCSH_API_URL=… XCSH_API_TOKEN=… XCSH_NAMESPACE=demo \
+ *   bun scripts/gen-specs.ts [resource1 …]      # omit args = all (non-cloud)
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { buildMinimalSpec, type SchemaIndex } from "../src/sweep/openapi-spec";
+import { probeSpec } from "../src/sweep/spec-probe";
+import { isScopedOut } from "../src/sweep/sweep-params";
+import { apiKindFor } from "../src/sweep/sweep-scoring";
+
+const SPECS_DIR =
+	process.env.XCSH_OPENAPI_DIR ??
+	path.resolve(import.meta.dir, "../../../../api-specs-enriched/docs/specifications/api");
+const WORKFLOWS_DIR = path.resolve(import.meta.dir, "../../../../console/catalog/workflows");
+const NAMESPACE = process.env.XCSH_NAMESPACE ?? "demo";
+const BASE_URL = (process.env.XCSH_API_URL ?? "").replace(/\/+$/, "");
+const TOKEN = process.env.XCSH_API_TOKEN ?? "";
+const OUT = process.env.SPECS_OUT ?? path.join(WORKFLOWS_DIR, "../generated-specs.json");
+
+function loadIndex(): SchemaIndex {
+	const index: SchemaIndex = {};
+	for (const f of fs.readdirSync(SPECS_DIR)) {
+		if (!f.endsWith(".json") || f === "index.json") continue;
+		try {
+			const d = JSON.parse(fs.readFileSync(path.join(SPECS_DIR, f), "utf8"));
+			for (const [name, sch] of Object.entries(d?.components?.schemas ?? {})) {
+				if (!(name in index)) index[name] = sch as SchemaIndex[string];
+			}
+		} catch {
+			/* skip unparseable spec file */
+		}
+	}
+	return index;
+}
+
+/** Singular API kind for the OpenAPI schema name, e.g. "healthchecks" → "healthcheck". */
+function singularKind(resource: string): string {
+	return apiKindFor(resource).replace(/s$/, "");
+}
+
+function discover(filter: string[]): string[] {
+	return fs
+		.readdirSync(WORKFLOWS_DIR)
+		.filter(d => fs.existsSync(path.join(WORKFLOWS_DIR, d, "create.yaml")))
+		.filter(d => !isScopedOut(d))
+		.filter(d => filter.length === 0 || filter.includes(d))
+		.sort();
+}
+
+async function main() {
+	const index = loadIndex();
+	console.log(`Loaded ${Object.keys(index).length} schemas from ${SPECS_DIR}`);
+	const resources = discover(process.argv.slice(2));
+	const specs: Record<string, unknown> = {};
+	let pass = 0;
+	for (const resource of resources) {
+		const name = /domain|dns-zone/.test(resource) ? "xcsh-gen.example.com" : `xcsh-gen-${resource}`.slice(0, 63);
+		const built = buildMinimalSpec(index, singularKind(resource), name, NAMESPACE);
+		if (!built.ok) {
+			console.log(`  ❌ ${resource.padEnd(26)} ${built.reason}`);
+			continue;
+		}
+		// Walker-seed → prober-patch: start the error-driven prober from the walker's spec.
+		const v = await probeSpec({
+			baseUrl: BASE_URL,
+			token: TOKEN,
+			namespace: NAMESPACE,
+			resource,
+			name,
+			seedSpec: built.body.spec as Record<string, unknown>,
+		});
+		if (v.ok) {
+			pass++;
+			specs[resource] = { namespace: v.namespace, metadata: { name, namespace: v.namespace }, spec: v.spec };
+			console.log(`  ✅ ${resource.padEnd(26)} [${v.namespace}/${v.iters}i] ${JSON.stringify(v.spec).slice(0, 55)}`);
+		} else {
+			console.log(`  ❌ ${resource.padEnd(26)} ${v.lastError}`);
+		}
+	}
+	fs.writeFileSync(OUT, JSON.stringify(specs, null, 2));
+	console.log(`\nWalker+API validated: ${pass}/${resources.length} → wrote ${OUT}`);
+}
+
+main().catch(e => {
+	console.error(e);
+	process.exit(1);
+});

package/scripts/inspect-form.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env bun
+/**
+ * Live form inspector. Opens a resource's create form via the Chrome extension
+ * and dumps the REAL attributes of every visible input/select (role, aria-label,
+ * name, placeholder, id, class, nearest label) — so we author selectors from
+ * ground truth instead of guessing `role[name='VisibleLabel']` (which fails when
+ * the input has no accessible name matching its column header / field label).
+ *
+ * Uses javascript_tool (read_ax freezes on heavy console forms).
+ *
+ * Usage:
+ *   XCSH_BROWSER_PROVIDER=extension XCSH_API_URL=… XCSH_USERNAME=… \
+ *   XCSH_CONSOLE_PASSWORD=… XCSH_NAMESPACE=demo \
+ *   bun scripts/inspect-form.ts <resource>
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as yaml from "yaml";
+import { startBridgeServer } from "../src/browser/extension-bridge";
+import { ExtensionBrowserProvider } from "../src/browser/extension-provider";
+
+const CONSOLE_ROOT = process.env.CONSOLE_CATALOG_DIR ?? path.resolve(import.meta.dir, "../../../../console");
+const NAMESPACE = process.env.XCSH_NAMESPACE ?? "demo";
+const BASE_URL = (process.env.XCSH_API_URL ?? "").replace(/\/+$/, "");
+process.env.XCSH_BROWSER_PROVIDER ??= "extension";
+
+const resource = process.argv[2];
+if (!resource) {
+	console.error("usage: bun scripts/inspect-form.ts <resource>");
+	process.exit(1);
+}
+
+const wf = yaml.parse(fs.readFileSync(path.join(CONSOLE_ROOT, "catalog/workflows", resource, "create.yaml"), "utf8"));
+const navStep = (wf.steps ?? []).find((s: { action?: string }) => s.action === "navigate");
+const addStep = (wf.steps ?? []).find((s: { selector?: string }) => /text\('Add /.test(s.selector ?? ""));
+const listUrl: string = (navStep?.url ?? "").replace(/\{namespace\}/g, NAMESPACE);
+const addText: string = (addStep?.selector?.match(/text\('([^']+)'\)/)?.[1] ?? "Add").trim();
+
+const DUMP = `(() => {
+  const sel = 'input,select,textarea,[role=spinbutton],[role=combobox],[role=textbox],[role=listbox]';
+  const labelFor = (e) => {
+    if (e.getAttribute('aria-labelledby')) { const l=document.getElementById(e.getAttribute('aria-labelledby')); if(l) return l.textContent.trim().slice(0,40); }
+    const lab = e.closest('label') || (e.id && document.querySelector('label[for=\\''+e.id+'\\']'));
+    if (lab) return lab.textContent.trim().slice(0,40);
+    let p=e.parentElement, hops=0; while(p&&hops<4){const h=p.querySelector('label,.field-label,[class*=label]');if(h&&h.textContent.trim())return h.textContent.trim().slice(0,40);p=p.parentElement;hops++;}
+    return null;
+  };
+  const section=(e)=>{let p=e;while(p&&p.tagName!=='BODY'){const h=p.querySelector&&p.querySelector('.section-header,[class*=section] h3,[class*=section] h4,h3,h4');if(h&&h.textContent.trim())return h.textContent.trim().slice(0,30);p=p.parentElement;}return null;};
+  const out=[...document.querySelectorAll(sel)].map(e=>{
+    const r=e.getBoundingClientRect();
+    return {
+      vis:e.offsetParent!==null,
+      tag:e.tagName.toLowerCase(), type:e.getAttribute('type'), role:e.getAttribute('role'),
+      ariaLabel:e.getAttribute('aria-label'), name:e.getAttribute('name'),
+      placeholder:e.getAttribute('placeholder'), id:e.id||null,
+      e2e:e.getAttribute('ves-e2e-test'), testid:e.getAttribute('data-testid'),
+      cls:(e.className||'').slice(0,50), label:labelFor(e), section:section(e),
+      dt:!!e.closest('ngx-datatable'), cell:!!e.closest('datatable-body-cell'),
+      xy:[Math.round(r.left),Math.round(r.top)],
+    };
+  });
+  return JSON.stringify(out);
+})()`;
+
+const CLICK_ADD = `(() => {
+  const t=${JSON.stringify(addText)};
+  const el=[...document.querySelectorAll('button,a,[role=button],span')].find(e=>e.textContent && e.textContent.trim()===t)
+    || [...document.querySelectorAll('button,a,[role=button],span')].find(e=>e.textContent && e.textContent.trim().includes(t));
+  if(el){el.click();return 'clicked: '+el.tagName;} return 'NOTFOUND: '+t;
+})()`;
+
+function unwrapJs(content: unknown): unknown {
+	const payload =
+		content && typeof content === "object" && "result" in (content as object)
+			? (content as { result: unknown }).result
+			: content;
+	if (typeof payload !== "string") return payload;
+	try {
+		return JSON.parse(payload);
+	} catch {
+		return payload; // plain string result (e.g. the click ack)
+	}
+}
+
+async function main() {
+	const server = await startBridgeServer();
+	const provider = new ExtensionBrowserProvider({ server });
+	console.log(`Acquiring (login) ${BASE_URL} …`);
+	const acquired = await provider.acquire(BASE_URL);
+	try {
+		console.log(`Navigate: ${BASE_URL}${listUrl}`);
+		await server.request("navigate", { url: `${BASE_URL}${listUrl}` }, 30000);
+		await new Promise(r => setTimeout(r, 2500));
+		const clicked = await server.request("javascript_tool", { code: CLICK_ADD }, 15000);
+		console.log(`Open form (${addText}):`, unwrapJs(clicked.content));
+		await new Promise(r => setTimeout(r, 3500));
+		// If the form has an "Add Item" button (datatable), click it to instantiate the row input.
+		const ai = await server.request(
+			"javascript_tool",
+			{
+				code: `(()=>{const b=[...document.querySelectorAll('button,a,span')].find(e=>e.textContent.trim()==='Add Item');if(b){b.click();return 'clicked-add-item';}return 'no-add-item';})()`,
+			},
+			15000,
+		);
+		console.log("Add Item:", unwrapJs(ai.content));
+		await new Promise(r => setTimeout(r, 2500));
+		const dump = await server.request("javascript_tool", { code: DUMP }, 15000);
+		const inputs = unwrapJs(dump.content) as Array<Record<string, unknown>>;
+		console.log(`\n=== ${resource}: ${inputs.length} visible inputs ===`);
+		for (const i of inputs) {
+			console.log(
+				`  ${i.vis ? "VIS" : "hid"} <${i.tag}${i.type ? ` type=${i.type}` : ""}> @${JSON.stringify(i.xy)} ` +
+					`aria=${JSON.stringify(i.ariaLabel)} ph=${JSON.stringify(i.placeholder)} ` +
+					`e2e=${JSON.stringify(i.e2e)} dt=${i.dt} cell=${i.cell}\n      cls=${JSON.stringify(i.cls)}`,
+			);
+		}
+	} finally {
+		await acquired.release().catch(() => {});
+		await server.close().catch(() => {});
+	}
+}
+
+main().catch(e => {
+	console.error(e);
+	process.exit(1);
+});

package/scripts/json-create-spike.ts

@@ -0,0 +1,114 @@
+#!/usr/bin/env bun
+/**
+ * Spike: create ip-prefix-set via the JSON tab (ACE editor) instead of the form.
+ * Sets the full spec with one ace setValue(), clicks save, reports the error
+ * banner. Decisive test of whether JSON-create bypasses the no-accessible-name
+ * form-selector problem. Verify creation separately via API-GET.
+ */
+import { startBridgeServer } from "../src/browser/extension-bridge";
+import { ExtensionBrowserProvider } from "../src/browser/extension-provider";
+
+const NAMESPACE = process.env.XCSH_NAMESPACE ?? "demo";
+const BASE_URL = (process.env.XCSH_API_URL ?? "").replace(/\/+$/, "");
+process.env.XCSH_BROWSER_PROVIDER ??= "extension";
+
+const LIST_URL = `/web/workspaces/web-app-and-api-protection/namespaces/${NAMESPACE}/manage/shared_objects/ip_prefix_sets`;
+const SPEC = {
+	metadata: { name: "xcsh-sweep-ip-prefix-set", namespace: NAMESPACE },
+	spec: { ipv4_prefixes: [{ ipv4_prefix: "10.10.0.0/24" }] },
+};
+const SPEC_JSON = JSON.stringify(SPEC, null, 2);
+
+const clickByText = (t: string) => `(() => {
+  const t=${JSON.stringify(t)};
+  const el=[...document.querySelectorAll('button,a,[role=button],span')].find(e=>e.textContent.trim()===t)
+    || [...document.querySelectorAll('button,a,[role=button],span')].find(e=>e.textContent.trim().includes(t));
+  if(el){el.click();return 'clicked '+el.tagName;} return 'NOTFOUND '+t;
+})()`;
+
+const SET_ACE = `(() => {
+  const el=document.querySelector('.ace_editor');
+  if(!el||!el.env||!el.env.editor) return 'NO_ACE';
+  const ed=el.env.editor;
+  ed.setValue(${JSON.stringify(SPEC_JSON)}, -1);
+  // Simulate a real edit so the console's change handler commits JSON->model:
+  ed.focus(); ed.navigateFileEnd(); ed.insert(' '); ed.remove('left');
+  return 'set:'+ed.getValue().length+'chars';
+})()`;
+
+const READ_FORM = `(() => {
+  const name=document.querySelector("input[aria-label='Name']");
+  const all=[...document.querySelectorAll('input')].filter(e=>e.offsetParent!==null).map(e=>({a:e.getAttribute('aria-label'),v:(e.value||'').slice(0,40)}));
+  return JSON.stringify({ nameVal: name? name.value: 'NO_NAME_INPUT', inputs: all });
+})()`;
+
+function unwrapJs(content: unknown): unknown {
+	const p =
+		content && typeof content === "object" && "result" in (content as object)
+			? (content as { result: unknown }).result
+			: content;
+	if (typeof p !== "string") return p;
+	try {
+		return JSON.parse(p);
+	} catch {
+		return p;
+	}
+}
+
+async function main() {
+	const server = await startBridgeServer();
+	const provider = new ExtensionBrowserProvider({ server });
+	const acquired = await provider.acquire(BASE_URL);
+	const js = (code: string) => server.request("javascript_tool", { code }, 15000).then(r => unwrapJs(r.content));
+	const sleep = (ms: number) => new Promise(r => setTimeout(r, ms));
+	const present = (t: string) =>
+		js(
+			`(()=>{const b=[...document.querySelectorAll('button,a,span')].find(e=>(e.textContent||'').trim().includes(${JSON.stringify(t)}));return b?'YES':'no';})()`,
+		);
+	const waitFor = async (t: string, secs = 25) => {
+		for (let i = 0; i < secs; i++) {
+			if ((await present(t)) === "YES") return true;
+			await sleep(1000);
+		}
+		return false;
+	};
+	try {
+		// Robust open: navigate (retry up to 3×) and POLL for the list to render
+		// before clicking — the SPA intermittently shows the workspace picker.
+		let opened = false;
+		for (let attempt = 0; attempt < 3 && !opened; attempt++) {
+			await server.request("navigate", { url: `${BASE_URL}${LIST_URL}` }, 30000);
+			opened = await waitFor("Add IP Prefix Set", 20);
+			console.log(`navigate attempt ${attempt + 1}: list rendered=${opened}`);
+		}
+		if (!opened) {
+			console.log("LIST NEVER RENDERED — aborting");
+			return;
+		}
+		console.log("open:", await js(clickByText("Add IP Prefix Set")));
+		await waitFor("JSON", 15);
+		console.log("json tab:", await js(clickByText("JSON")));
+		await new Promise(r => setTimeout(r, 2000));
+		console.log("set ace:", await js(SET_ACE));
+		await sleep(2000);
+		// Switching to Form COMMITS JSON->model (proven). With a valid schema there's
+		// no error modal, so the model populates and we can save from the Form tab.
+		console.log("form tab:", await js(clickByText("Form")));
+		await sleep(3000);
+		console.log("FORM AFTER COMMIT:", await js(READ_FORM));
+		const SAVE = `(()=>{const btns=[...document.querySelectorAll('button')].filter(x=>x.offsetParent!==null);
+		  const b=btns.find(x=>/save-btn/.test(x.className||'')) || btns.filter(x=>/Add IP Prefix Set/i.test(x.textContent||'')).pop();
+		  if(b){b.click();return 'saved:'+(b.className||b.tagName);}return 'NO_SAVE';})()`;
+		console.log("save:", await js(SAVE));
+		await sleep(6000);
+		console.log("final url:", await js("(()=>location.href)()"));
+	} finally {
+		await acquired.release().catch(() => {});
+		await server.close().catch(() => {});
+	}
+}
+
+main().catch(e => {
+	console.error(e);
+	process.exit(1);
+});

package/scripts/json-spike.ts

@@ -0,0 +1,102 @@
+#!/usr/bin/env bun
+/**
+ * Spike: can we create a resource via the console's JSON tab instead of the
+ * per-field form? Most vsui form inputs have no accessible name, so the JSON
+ * editor (one field) could be a far more robust create path.
+ *
+ * This probe opens a resource's create form, clicks the JSON tab, and reports
+ * what editor it is (Monaco / CodeMirror / ACE / textarea) + its current value,
+ * so we know how to set its content. Read-only — does not save.
+ *
+ * Usage: bun scripts/json-spike.ts <resource>
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as yaml from "yaml";
+import { startBridgeServer } from "../src/browser/extension-bridge";
+import { ExtensionBrowserProvider } from "../src/browser/extension-provider";
+
+const CONSOLE_ROOT = process.env.CONSOLE_CATALOG_DIR ?? path.resolve(import.meta.dir, "../../../../console");
+const NAMESPACE = process.env.XCSH_NAMESPACE ?? "demo";
+const BASE_URL = (process.env.XCSH_API_URL ?? "").replace(/\/+$/, "");
+process.env.XCSH_BROWSER_PROVIDER ??= "extension";
+
+const resource = process.argv[2] ?? "ip-prefix-set";
+const wf = yaml.parse(fs.readFileSync(path.join(CONSOLE_ROOT, "catalog/workflows", resource, "create.yaml"), "utf8"));
+const navStep = (wf.steps ?? []).find((s: { action?: string }) => s.action === "navigate");
+const addStep = (wf.steps ?? []).find((s: { selector?: string }) => /text\('Add /.test(s.selector ?? ""));
+const listUrl: string = (navStep?.url ?? "").replace(/\{namespace\}/g, NAMESPACE);
+const addText: string = (addStep?.selector?.match(/text\('([^']+)'\)/)?.[1] ?? "Add").trim();
+
+const clickByText = (t: string) => `(() => {
+  const t=${JSON.stringify(t)};
+  const el=[...document.querySelectorAll('button,a,[role=button],span,div,li')].find(e=>{
+    const own=[...e.childNodes].filter(n=>n.nodeType===3).map(n=>n.textContent).join('').trim();
+    return own===t;
+  }) || [...document.querySelectorAll('button,a,[role=button],span')].find(e=>e.textContent.trim()===t);
+  if(el){el.click();return 'clicked '+el.tagName;} return 'NOTFOUND '+t;
+})()`;
+
+const PROBE = `(() => {
+  const r = { monaco:false, codemirror:false, ace:false, textareas:0, value:null, editorKind:null };
+  if (document.querySelector('.monaco-editor')) r.monaco=true;
+  if (document.querySelector('.CodeMirror')) r.codemirror=true;
+  if (document.querySelector('.ace_editor')) r.ace=true;
+  const tas=[...document.querySelectorAll('textarea')].filter(e=>e.offsetParent!==null);
+  r.textareas=tas.length;
+  try {
+    const aceEl=document.querySelector('.ace_editor');
+    if (aceEl && aceEl.env && aceEl.env.editor){ r.editorKind='ace'; const ed=aceEl.env.editor; r.value=ed.getValue(); r.readOnly=ed.getReadOnly(); }
+    else if (window.monaco && monaco.editor && monaco.editor.getModels().length){ r.editorKind='monaco'; r.value=monaco.editor.getModels()[0].getValue(); }
+    else if (tas.length){ r.editorKind='textarea'; r.value=(tas[0].value||''); }
+    if (r.value) r.value=r.value.slice(0,400);
+    // Controls near the editor that might commit/import JSON
+    r.buttons=[...document.querySelectorAll('button,a,[role=button]')].filter(b=>b.offsetParent!==null).map(b=>b.textContent.trim()).filter(t=>t&&t.length<26).slice(0,30);
+  } catch(e){ r.err=String(e); }
+  return JSON.stringify(r);
+})()`;
+
+function unwrapJs(content: unknown): unknown {
+	const p =
+		content && typeof content === "object" && "result" in (content as object)
+			? (content as { result: unknown }).result
+			: content;
+	if (typeof p !== "string") return p;
+	try {
+		return JSON.parse(p);
+	} catch {
+		return p;
+	}
+}
+
+async function main() {
+	const server = await startBridgeServer();
+	const provider = new ExtensionBrowserProvider({ server });
+	console.log(`Acquiring ${BASE_URL} …`);
+	const acquired = await provider.acquire(BASE_URL);
+	try {
+		await server.request("navigate", { url: `${BASE_URL}${listUrl}` }, 30000);
+		await new Promise(r => setTimeout(r, 2500));
+		console.log(
+			"open form:",
+			unwrapJs((await server.request("javascript_tool", { code: clickByText(addText) }, 15000)).content),
+		);
+		await new Promise(r => setTimeout(r, 3000));
+		console.log(
+			"click JSON tab:",
+			unwrapJs((await server.request("javascript_tool", { code: clickByText("JSON") }, 15000)).content),
+		);
+		await new Promise(r => setTimeout(r, 2500));
+		const probe = unwrapJs((await server.request("javascript_tool", { code: PROBE }, 15000)).content);
+		console.log("\n=== JSON editor probe ===");
+		console.log(JSON.stringify(probe, null, 2));
+	} finally {
+		await acquired.release().catch(() => {});
+		await server.close().catch(() => {});
+	}
+}
+
+main().catch(e => {
+	console.error(e);
+	process.exit(1);
+});

package/scripts/spec-prober.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env bun
+/**
+ * CLI: derive minimal valid specs purely by error-driven API probing (seed {}).
+ * Thin wrapper over `probeSpec` (src/sweep/spec-probe.ts) — the same engine the
+ * hybrid (gen-specs.ts) uses with an OpenAPI-walker seed.
+ *
+ * Usage: XCSH_API_URL=… XCSH_API_TOKEN=… XCSH_NAMESPACE=demo \
+ *        bun scripts/spec-prober.ts <resource1> [resource2 …]
+ */
+import { probeSpec } from "../src/sweep/spec-probe";
+
+const NAMESPACE = process.env.XCSH_NAMESPACE ?? "demo";
+const BASE_URL = (process.env.XCSH_API_URL ?? "").replace(/\/+$/, "");
+const TOKEN = process.env.XCSH_API_TOKEN ?? "";
+
+async function main() {
+	if (!BASE_URL || !TOKEN) {
+		console.error("XCSH_API_URL / XCSH_API_TOKEN required");
+		process.exit(1);
+	}
+	for (const resource of process.argv.slice(2)) {
+		const name = /domain|dns-zone/.test(resource) ? "xcsh-probe.example.com" : `xcsh-probe-${resource}`.slice(0, 63);
+		const r = await probeSpec({ baseUrl: BASE_URL, token: TOKEN, namespace: NAMESPACE, resource, name });
+		console.log(
+			`\n${r.ok ? "✅" : "❌"} ${resource} (${r.iters} iters, ns=${r.namespace})` +
+				`\n   spec: ${JSON.stringify(r.spec)}` +
+				(r.ok ? "" : `\n   stuck: ${r.lastError}`),
+		);
+	}
+}
+
+main().catch(e => {
+	console.error(e);
+	process.exit(1);
+});