let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(browser): simplify control API

Browse Source
This commit is contained in:
Peter Steinberger
2025-12-20 03:27:12 +00:00
parent 06806a1ea1
commit 235f3ce0ba
23 changed files with 776 additions and 2214 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
src/cli/browser-cli-actions-input.ts
View File

@@ -1,19 +1,10 @@
import type { Command } from "commander";
import { resolveBrowserControlUrl } from "../browser/client.js";
import {
browserClick,
browserDrag,
browserEvaluate,
browserFillForm,
browserHandleDialog,
browserHover,
browserAct,
browserArmDialog,
browserArmFileChooser,
browserNavigate,
browserPressKey,
browserResize,
browserSelectOption,
browserType,
browserUpload,
browserWaitFor,
} from "../browser/client-actions.js";
import { danger } from "../globals.js";
import { defaultRuntime } from "../runtime.js";
@@ -80,7 +71,8 @@ export function registerBrowserActionInputCommands(
return;
}
try {
const result = await browserResize(baseUrl, {
const result = await browserAct(baseUrl, {
kind: "resize",
width,
height,
targetId: opts.targetId?.trim() || undefined,
@@ -114,7 +106,8 @@ export function registerBrowserActionInputCommands(
.filter(Boolean)
: undefined;
try {
const result = await browserClick(baseUrl, {
const result = await browserAct(baseUrl, {
kind: "click",
ref,
targetId: opts.targetId?.trim() || undefined,
doubleClick: Boolean(opts.double),
@@ -145,7 +138,8 @@ export function registerBrowserActionInputCommands(
const parent = parentOpts(cmd);
const baseUrl = resolveBrowserControlUrl(parent?.url);
try {
const result = await browserType(baseUrl, {
const result = await browserAct(baseUrl, {
kind: "type",
ref,
text,
submit: Boolean(opts.submit),
@@ -172,7 +166,8 @@ export function registerBrowserActionInputCommands(
const parent = parentOpts(cmd);
const baseUrl = resolveBrowserControlUrl(parent?.url);
try {
const result = await browserPressKey(baseUrl, {
const result = await browserAct(baseUrl, {
kind: "press",
key,
targetId: opts.targetId?.trim() || undefined,
});
@@ -196,7 +191,8 @@ export function registerBrowserActionInputCommands(
const parent = parentOpts(cmd);
const baseUrl = resolveBrowserControlUrl(parent?.url);
try {
const result = await browserHover(baseUrl, {
const result = await browserAct(baseUrl, {
kind: "hover",
ref,
targetId: opts.targetId?.trim() || undefined,
});
@@ -221,7 +217,8 @@ export function registerBrowserActionInputCommands(
const parent = parentOpts(cmd);
const baseUrl = resolveBrowserControlUrl(parent?.url);
try {
const result = await browserDrag(baseUrl, {
const result = await browserAct(baseUrl, {
kind: "drag",
startRef,
endRef,
targetId: opts.targetId?.trim() || undefined,
@@ -247,7 +244,8 @@ export function registerBrowserActionInputCommands(
const parent = parentOpts(cmd);
const baseUrl = resolveBrowserControlUrl(parent?.url);
try {
const result = await browserSelectOption(baseUrl, {
const result = await browserAct(baseUrl, {
kind: "select",
ref,
values,
targetId: opts.targetId?.trim() || undefined,
@@ -268,13 +266,21 @@ export function registerBrowserActionInputCommands(
.description("Arm file upload for the next file chooser")
.argument("<paths...>", "File paths to upload")
.option("--target-id <id>", "CDP target id (or unique prefix)")
.option(
"--timeout-ms <ms>",
"How long to wait for the next file chooser (default: 10000)",
(v: string) => Number(v),
)
.action(async (paths: string[], opts, cmd) => {
const parent = parentOpts(cmd);
const baseUrl = resolveBrowserControlUrl(parent?.url);
try {
const result = await browserUpload(baseUrl, {
const result = await browserArmFileChooser(baseUrl, {
paths,
targetId: opts.targetId?.trim() || undefined,
timeoutMs: Number.isFinite(opts.timeoutMs)
? opts.timeoutMs
: undefined,
});
if (parent?.json) {
defaultRuntime.log(JSON.stringify(result, null, 2));
@@ -301,7 +307,8 @@ export function registerBrowserActionInputCommands(
fields: opts.fields,
fieldsFile: opts.fieldsFile,
});
const result = await browserFillForm(baseUrl, {
const result = await browserAct(baseUrl, {
kind: "fill",
fields,
targetId: opts.targetId?.trim() || undefined,
});
@@ -323,6 +330,11 @@ export function registerBrowserActionInputCommands(
.option("--dismiss", "Dismiss the dialog", false)
.option("--prompt <text>", "Prompt response text")
.option("--target-id <id>", "CDP target id (or unique prefix)")
.option(
"--timeout-ms <ms>",
"How long to wait for the next dialog (default: 10000)",
(v: string) => Number(v),
)
.action(async (opts, cmd) => {
const parent = parentOpts(cmd);
const baseUrl = resolveBrowserControlUrl(parent?.url);
@@ -333,10 +345,13 @@ export function registerBrowserActionInputCommands(
return;
}
try {
const result = await browserHandleDialog(baseUrl, {
const result = await browserArmDialog(baseUrl, {
accept,
promptText: opts.prompt?.trim() || undefined,
targetId: opts.targetId?.trim() || undefined,
timeoutMs: Number.isFinite(opts.timeoutMs)
? opts.timeoutMs
: undefined,
});
if (parent?.json) {
defaultRuntime.log(JSON.stringify(result, null, 2));
@@ -360,8 +375,9 @@ export function registerBrowserActionInputCommands(
const parent = parentOpts(cmd);
const baseUrl = resolveBrowserControlUrl(parent?.url);
try {
const result = await browserWaitFor(baseUrl, {
time: Number.isFinite(opts.time) ? opts.time : undefined,
const result = await browserAct(baseUrl, {
kind: "wait",
timeMs: Number.isFinite(opts.time) ? opts.time : undefined,
text: opts.text?.trim() || undefined,
textGone: opts.textGone?.trim() || undefined,
targetId: opts.targetId?.trim() || undefined,
@@ -392,7 +408,8 @@ export function registerBrowserActionInputCommands(
return;
}
try {
const result = await browserEvaluate(baseUrl, {
const result = await browserAct(baseUrl, {
kind: "evaluate",
fn: opts.fn,
ref: opts.ref?.trim() || undefined,
targetId: opts.targetId?.trim() || undefined,
@@ -401,7 +418,7 @@ export function registerBrowserActionInputCommands(
defaultRuntime.log(JSON.stringify(result, null, 2));
return;
}
defaultRuntime.log(JSON.stringify(result.result, null, 2));
defaultRuntime.log(JSON.stringify(result.result ?? null, null, 2));
} catch (err) {
defaultRuntime.error(danger(String(err)));
defaultRuntime.exit(1);

118
src/cli/browser-cli-actions-observe.ts
View File

@@ -3,10 +3,6 @@ import { resolveBrowserControlUrl } from "../browser/client.js";
import {
browserConsoleMessages,
browserPdfSave,
browserVerifyElementVisible,
browserVerifyListVisible,
browserVerifyTextVisible,
browserVerifyValue,
} from "../browser/client-actions.js";
import { danger } from "../globals.js";
import { defaultRuntime } from "../runtime.js";
@@ -61,118 +57,4 @@ export function registerBrowserActionObserveCommands(
defaultRuntime.exit(1);
}
});
browser
.command("verify-element")
.description("Verify element visible by role + name")
.option("--role <role>", "ARIA role")
.option("--name <text>", "Accessible name")
.option("--target-id <id>", "CDP target id (or unique prefix)")
.action(async (opts, cmd) => {
const parent = parentOpts(cmd);
const baseUrl = resolveBrowserControlUrl(parent?.url);
if (!opts.role || !opts.name) {
defaultRuntime.error(danger("--role and --name are required"));
defaultRuntime.exit(1);
return;
}
try {
const result = await browserVerifyElementVisible(baseUrl, {
role: opts.role,
accessibleName: opts.name,
targetId: opts.targetId?.trim() || undefined,
});
if (parent?.json) {
defaultRuntime.log(JSON.stringify(result, null, 2));
return;
}
defaultRuntime.log("element visible");
} catch (err) {
defaultRuntime.error(danger(String(err)));
defaultRuntime.exit(1);
}
});
browser
.command("verify-text")
.description("Verify text is visible")
.argument("<text>", "Text to find")
.option("--target-id <id>", "CDP target id (or unique prefix)")
.action(async (text: string, opts, cmd) => {
const parent = parentOpts(cmd);
const baseUrl = resolveBrowserControlUrl(parent?.url);
try {
const result = await browserVerifyTextVisible(baseUrl, {
text,
targetId: opts.targetId?.trim() || undefined,
});
if (parent?.json) {
defaultRuntime.log(JSON.stringify(result, null, 2));
return;
}
defaultRuntime.log("text visible");
} catch (err) {
defaultRuntime.error(danger(String(err)));
defaultRuntime.exit(1);
}
});
browser
.command("verify-list")
.description("Verify list items under a ref")
.argument("<ref>", "Ref id from ai snapshot")
.argument("<items...>", "List items to verify")
.option("--target-id <id>", "CDP target id (or unique prefix)")
.action(async (ref: string, items: string[], opts, cmd) => {
const parent = parentOpts(cmd);
const baseUrl = resolveBrowserControlUrl(parent?.url);
try {
const result = await browserVerifyListVisible(baseUrl, {
ref,
items,
targetId: opts.targetId?.trim() || undefined,
});
if (parent?.json) {
defaultRuntime.log(JSON.stringify(result, null, 2));
return;
}
defaultRuntime.log("list visible");
} catch (err) {
defaultRuntime.error(danger(String(err)));
defaultRuntime.exit(1);
}
});
browser
.command("verify-value")
.description("Verify a form control value")
.option("--ref <ref>", "Ref id from ai snapshot")
.option("--type <type>", "Input type (textbox, checkbox, slider, etc)")
.option("--value <value>", "Expected value")
.option("--target-id <id>", "CDP target id (or unique prefix)")
.action(async (opts, cmd) => {
const parent = parentOpts(cmd);
const baseUrl = resolveBrowserControlUrl(parent?.url);
if (!opts.ref || !opts.type) {
defaultRuntime.error(danger("--ref and --type are required"));
defaultRuntime.exit(1);
return;
}
try {
const result = await browserVerifyValue(baseUrl, {
ref: opts.ref,
type: opts.type,
value: opts.value,
targetId: opts.targetId?.trim() || undefined,
});
if (parent?.json) {
defaultRuntime.log(JSON.stringify(result, null, 2));
return;
}
defaultRuntime.log("value verified");
} catch (err) {
defaultRuntime.error(danger(String(err)));
defaultRuntime.exit(1);
}
});
}

6
src/cli/browser-cli-examples.ts
View File

@@ -9,8 +9,6 @@ export const browserCoreExamples = [
"clawdis browser screenshot",
"clawdis browser screenshot --full-page",
"clawdis browser screenshot --ref 12",
'clawdis browser query "a" --limit 5',
"clawdis browser dom --format text --max-chars 5000",
"clawdis browser snapshot --format aria --limit 200",
"clawdis browser snapshot --format ai",
];
@@ -31,8 +29,4 @@ export const browserActionExamples = [
"clawdis browser evaluate --fn '(el) => el.textContent' --ref 7",
"clawdis browser console --level error",
"clawdis browser pdf",
'clawdis browser verify-element --role button --name "Submit"',
'clawdis browser verify-text "Welcome"',
"clawdis browser verify-list 3 ItemA ItemB",
"clawdis browser verify-value --ref 4 --type textbox --value hello",
];

119
src/cli/browser-cli-inspect.ts
View File

@@ -1,9 +1,6 @@
import type { Command } from "commander";
import {
browserDom,
browserQuery,
browserScreenshot,
browserSnapshot,
resolveBrowserControlUrl,
} from "../browser/client.js";
@@ -24,25 +21,17 @@ export function registerBrowserInspectCommands(
.option("--ref <ref>", "ARIA ref from ai snapshot")
.option("--element <selector>", "CSS selector for element screenshot")
.option("--type <png|jpeg>", "Output type (default: png)", "png")
.option("--filename <name>", "Preferred output filename")
.action(async (targetId: string | undefined, opts, cmd) => {
const parent = parentOpts(cmd);
const baseUrl = resolveBrowserControlUrl(parent?.url);
try {
const advanced = Boolean(opts.ref || opts.element || opts.filename);
const result = advanced
? await browserScreenshotAction(baseUrl, {
targetId: targetId?.trim() || undefined,
fullPage: Boolean(opts.fullPage),
ref: opts.ref?.trim() || undefined,
element: opts.element?.trim() || undefined,
filename: opts.filename?.trim() || undefined,
type: opts.type === "jpeg" ? "jpeg" : "png",
})
: await browserScreenshot(baseUrl, {
targetId: targetId?.trim() || undefined,
fullPage: Boolean(opts.fullPage),
});
const result = await browserScreenshotAction(baseUrl, {
targetId: targetId?.trim() || undefined,
fullPage: Boolean(opts.fullPage),
ref: opts.ref?.trim() || undefined,
element: opts.element?.trim() || undefined,
type: opts.type === "jpeg" ? "jpeg" : "png",
});
if (parent?.json) {
defaultRuntime.log(JSON.stringify(result, null, 2));
return;
@@ -54,88 +43,10 @@ export function registerBrowserInspectCommands(
}
});
browser
.command("query")
.description("Query selector matches")
.argument("<selector>", "CSS selector")
.option("--target-id <id>", "CDP target id (or unique prefix)")
.option("--limit <n>", "Max matches (default: 20)", (v: string) =>
Number(v),
)
.action(async (selector: string, opts, cmd) => {
const parent = parentOpts(cmd);
const baseUrl = resolveBrowserControlUrl(parent?.url);
try {
const result = await browserQuery(baseUrl, {
selector,
targetId: opts.targetId?.trim() || undefined,
limit: Number.isFinite(opts.limit) ? opts.limit : undefined,
});
if (parent?.json) {
defaultRuntime.log(JSON.stringify(result, null, 2));
return;
}
defaultRuntime.log(JSON.stringify(result.matches, null, 2));
} catch (err) {
defaultRuntime.error(danger(String(err)));
defaultRuntime.exit(1);
}
});
browser
.command("dom")
.description("Dump DOM (html or text) with truncation")
.option("--format <html|text>", "Output format (default: html)", "html")
.option("--target-id <id>", "CDP target id (or unique prefix)")
.option("--selector <css>", "Optional CSS selector to scope the dump")
.option(
"--max-chars <n>",
"Max characters (default: 200000)",
(v: string) => Number(v),
)
.option("--out <path>", "Write output to a file")
.action(async (opts, cmd) => {
const parent = parentOpts(cmd);
const baseUrl = resolveBrowserControlUrl(parent?.url);
const format = opts.format === "text" ? "text" : "html";
try {
const result = await browserDom(baseUrl, {
format,
targetId: opts.targetId?.trim() || undefined,
maxChars: Number.isFinite(opts.maxChars) ? opts.maxChars : undefined,
selector: opts.selector?.trim() || undefined,
});
if (opts.out) {
const fs = await import("node:fs/promises");
await fs.writeFile(opts.out, result.text, "utf8");
if (parent?.json) {
defaultRuntime.log(
JSON.stringify({ ok: true, out: opts.out }, null, 2),
);
} else {
defaultRuntime.log(opts.out);
}
return;
}
if (parent?.json) {
defaultRuntime.log(JSON.stringify(result, null, 2));
return;
}
defaultRuntime.log(result.text);
} catch (err) {
defaultRuntime.error(danger(String(err)));
defaultRuntime.exit(1);
}
});
browser
.command("snapshot")
.description("Capture an AI-friendly snapshot (aria, domSnapshot, or ai)")
.option(
"--format <aria|domSnapshot|ai>",
"Snapshot format (default: aria)",
"aria",
)
.description("Capture an AI-friendly snapshot (aria or ai)")
.option("--format <aria|ai>", "Snapshot format (default: aria)", "aria")
.option("--target-id <id>", "CDP target id (or unique prefix)")
.option("--limit <n>", "Max nodes (default: 500/800)", (v: string) =>
Number(v),
@@ -144,12 +55,7 @@ export function registerBrowserInspectCommands(
.action(async (opts, cmd) => {
const parent = parentOpts(cmd);
const baseUrl = resolveBrowserControlUrl(parent?.url);
const format =
opts.format === "domSnapshot"
? "domSnapshot"
: opts.format === "ai"
? "ai"
: "aria";
const format = opts.format === "ai" ? "ai" : "aria";
try {
const result = await browserSnapshot(baseUrl, {
format,
@@ -185,11 +91,6 @@ export function registerBrowserInspectCommands(
return;
}
if (result.format === "domSnapshot") {
defaultRuntime.log(JSON.stringify(result, null, 2));
return;
}
const nodes = "nodes" in result ? result.nodes : [];
defaultRuntime.log(
nodes

4
src/cli/browser-cli-manage.ts
View File

@@ -10,7 +10,7 @@ import {
browserTabs,
resolveBrowserControlUrl,
} from "../browser/client.js";
import { browserClosePage } from "../browser/client-actions.js";
import { browserAct } from "../browser/client-actions.js";
import { danger, info } from "../globals.js";
import { defaultRuntime } from "../runtime.js";
import type { BrowserParentOpts } from "./browser-cli-shared.js";
@@ -168,7 +168,7 @@ export function registerBrowserManageCommands(
if (targetId?.trim()) {
await browserCloseTab(baseUrl, targetId.trim());
} else {
await browserClosePage(baseUrl);
await browserAct(baseUrl, { kind: "close" });
}
if (parent?.json) {
defaultRuntime.log(JSON.stringify({ ok: true }, null, 2));