@intent-systems/nexus 2026.1.5-3

package/dist/cli/browser-cli-actions-input.js

@@ -0,0 +1,459 @@
+import { resolveBrowserControlUrl } from "../browser/client.js";
+import { browserAct, browserArmDialog, browserArmFileChooser, browserNavigate, } from "../browser/client-actions.js";
+import { danger } from "../globals.js";
+import { defaultRuntime } from "../runtime.js";
+async function readFile(path) {
+    const fs = await import("node:fs/promises");
+    return await fs.readFile(path, "utf8");
+}
+async function readFields(opts) {
+    const payload = opts.fieldsFile
+        ? await readFile(opts.fieldsFile)
+        : (opts.fields ?? "");
+    if (!payload.trim())
+        throw new Error("fields are required");
+    const parsed = JSON.parse(payload);
+    if (!Array.isArray(parsed))
+        throw new Error("fields must be an array");
+    return parsed.map((entry, index) => {
+        if (!entry || typeof entry !== "object") {
+            throw new Error(`fields[${index}] must be an object`);
+        }
+        const rec = entry;
+        const ref = typeof rec.ref === "string" ? rec.ref.trim() : "";
+        const type = typeof rec.type === "string" ? rec.type.trim() : "";
+        if (!ref || !type) {
+            throw new Error(`fields[${index}] must include ref and type`);
+        }
+        if (typeof rec.value === "string" ||
+            typeof rec.value === "number" ||
+            typeof rec.value === "boolean") {
+            return { ref, type, value: rec.value };
+        }
+        if (rec.value === undefined || rec.value === null) {
+            return { ref, type };
+        }
+        throw new Error(`fields[${index}].value must be string, number, boolean, or null`);
+    });
+}
+export function registerBrowserActionInputCommands(browser, parentOpts) {
+    browser
+        .command("navigate")
+        .description("Navigate the current tab to a URL")
+        .argument("<url>", "URL to navigate to")
+        .option("--target-id <id>", "CDP target id (or unique prefix)")
+        .action(async (url, opts, cmd) => {
+        const parent = parentOpts(cmd);
+        const baseUrl = resolveBrowserControlUrl(parent?.url);
+        const profile = parent?.profile;
+        try {
+            const result = await browserNavigate(baseUrl, {
+                url,
+                targetId: opts.targetId?.trim() || undefined,
+                profile,
+            });
+            if (parent?.json) {
+                defaultRuntime.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            defaultRuntime.log(`navigated to ${result.url ?? url}`);
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    });
+    browser
+        .command("resize")
+        .description("Resize the viewport")
+        .argument("<width>", "Viewport width", (v) => Number(v))
+        .argument("<height>", "Viewport height", (v) => Number(v))
+        .option("--target-id <id>", "CDP target id (or unique prefix)")
+        .action(async (width, height, opts, cmd) => {
+        const parent = parentOpts(cmd);
+        const baseUrl = resolveBrowserControlUrl(parent?.url);
+        const profile = parent?.profile;
+        if (!Number.isFinite(width) || !Number.isFinite(height)) {
+            defaultRuntime.error(danger("width and height must be numbers"));
+            defaultRuntime.exit(1);
+            return;
+        }
+        try {
+            const result = await browserAct(baseUrl, {
+                kind: "resize",
+                width,
+                height,
+                targetId: opts.targetId?.trim() || undefined,
+            }, { profile });
+            if (parent?.json) {
+                defaultRuntime.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            defaultRuntime.log(`resized to ${width}x${height}`);
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    });
+    browser
+        .command("click")
+        .description("Click an element by ref from snapshot")
+        .argument("<ref>", "Ref id from ai snapshot")
+        .option("--target-id <id>", "CDP target id (or unique prefix)")
+        .option("--double", "Double click", false)
+        .option("--button <left|right|middle>", "Mouse button to use")
+        .option("--modifiers <list>", "Comma-separated modifiers (Shift,Alt,Meta)")
+        .action(async (ref, opts, cmd) => {
+        const parent = parentOpts(cmd);
+        const baseUrl = resolveBrowserControlUrl(parent?.url);
+        const profile = parent?.profile;
+        const refValue = typeof ref === "string" ? ref.trim() : "";
+        if (!refValue) {
+            defaultRuntime.error(danger("ref is required"));
+            defaultRuntime.exit(1);
+            return;
+        }
+        const modifiers = opts.modifiers
+            ? String(opts.modifiers)
+                .split(",")
+                .map((v) => v.trim())
+                .filter(Boolean)
+            : undefined;
+        try {
+            const result = await browserAct(baseUrl, {
+                kind: "click",
+                ref: refValue,
+                targetId: opts.targetId?.trim() || undefined,
+                doubleClick: Boolean(opts.double),
+                button: opts.button?.trim() || undefined,
+                modifiers,
+            }, { profile });
+            if (parent?.json) {
+                defaultRuntime.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            const suffix = result.url ? ` on ${result.url}` : "";
+            defaultRuntime.log(`clicked ref ${refValue}${suffix}`);
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    });
+    browser
+        .command("type")
+        .description("Type into an element by ref from snapshot")
+        .argument("<ref>", "Ref id from ai snapshot")
+        .argument("<text>", "Text to type")
+        .option("--submit", "Press Enter after typing", false)
+        .option("--slowly", "Type slowly (human-like)", false)
+        .option("--target-id <id>", "CDP target id (or unique prefix)")
+        .action(async (ref, text, opts, cmd) => {
+        const parent = parentOpts(cmd);
+        const baseUrl = resolveBrowserControlUrl(parent?.url);
+        const profile = parent?.profile;
+        const refValue = typeof ref === "string" ? ref.trim() : "";
+        if (!refValue) {
+            defaultRuntime.error(danger("ref is required"));
+            defaultRuntime.exit(1);
+            return;
+        }
+        try {
+            const result = await browserAct(baseUrl, {
+                kind: "type",
+                ref: refValue,
+                text,
+                submit: Boolean(opts.submit),
+                slowly: Boolean(opts.slowly),
+                targetId: opts.targetId?.trim() || undefined,
+            }, { profile });
+            if (parent?.json) {
+                defaultRuntime.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            defaultRuntime.log(`typed into ref ${refValue}`);
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    });
+    browser
+        .command("press")
+        .description("Press a key")
+        .argument("<key>", "Key to press (e.g. Enter)")
+        .option("--target-id <id>", "CDP target id (or unique prefix)")
+        .action(async (key, opts, cmd) => {
+        const parent = parentOpts(cmd);
+        const baseUrl = resolveBrowserControlUrl(parent?.url);
+        const profile = parent?.profile;
+        try {
+            const result = await browserAct(baseUrl, {
+                kind: "press",
+                key,
+                targetId: opts.targetId?.trim() || undefined,
+            }, { profile });
+            if (parent?.json) {
+                defaultRuntime.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            defaultRuntime.log(`pressed ${key}`);
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    });
+    browser
+        .command("hover")
+        .description("Hover an element by ai ref")
+        .argument("<ref>", "Ref id from ai snapshot")
+        .option("--target-id <id>", "CDP target id (or unique prefix)")
+        .action(async (ref, opts, cmd) => {
+        const parent = parentOpts(cmd);
+        const baseUrl = resolveBrowserControlUrl(parent?.url);
+        const profile = parent?.profile;
+        try {
+            const result = await browserAct(baseUrl, {
+                kind: "hover",
+                ref,
+                targetId: opts.targetId?.trim() || undefined,
+            }, { profile });
+            if (parent?.json) {
+                defaultRuntime.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            defaultRuntime.log(`hovered ref ${ref}`);
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    });
+    browser
+        .command("drag")
+        .description("Drag from one ref to another")
+        .argument("<startRef>", "Start ref id")
+        .argument("<endRef>", "End ref id")
+        .option("--target-id <id>", "CDP target id (or unique prefix)")
+        .action(async (startRef, endRef, opts, cmd) => {
+        const parent = parentOpts(cmd);
+        const baseUrl = resolveBrowserControlUrl(parent?.url);
+        const profile = parent?.profile;
+        try {
+            const result = await browserAct(baseUrl, {
+                kind: "drag",
+                startRef,
+                endRef,
+                targetId: opts.targetId?.trim() || undefined,
+            }, { profile });
+            if (parent?.json) {
+                defaultRuntime.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            defaultRuntime.log(`dragged ${startRef} → ${endRef}`);
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    });
+    browser
+        .command("select")
+        .description("Select option(s) in a select element")
+        .argument("<ref>", "Ref id from ai snapshot")
+        .argument("<values...>", "Option values to select")
+        .option("--target-id <id>", "CDP target id (or unique prefix)")
+        .action(async (ref, values, opts, cmd) => {
+        const parent = parentOpts(cmd);
+        const baseUrl = resolveBrowserControlUrl(parent?.url);
+        const profile = parent?.profile;
+        try {
+            const result = await browserAct(baseUrl, {
+                kind: "select",
+                ref,
+                values,
+                targetId: opts.targetId?.trim() || undefined,
+            }, { profile });
+            if (parent?.json) {
+                defaultRuntime.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            defaultRuntime.log(`selected ${values.join(", ")}`);
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    });
+    browser
+        .command("upload")
+        .description("Arm file upload for the next file chooser")
+        .argument("<paths...>", "File paths to upload")
+        .option("--ref <ref>", "Ref id from ai snapshot to click after arming")
+        .option("--input-ref <ref>", "Ref id for <input type=file> to set directly")
+        .option("--element <selector>", "CSS selector for <input type=file>")
+        .option("--target-id <id>", "CDP target id (or unique prefix)")
+        .option("--timeout-ms <ms>", "How long to wait for the next file chooser (default: 120000)", (v) => Number(v))
+        .action(async (paths, opts, cmd) => {
+        const parent = parentOpts(cmd);
+        const baseUrl = resolveBrowserControlUrl(parent?.url);
+        const profile = parent?.profile;
+        try {
+            const result = await browserArmFileChooser(baseUrl, {
+                paths,
+                ref: opts.ref?.trim() || undefined,
+                inputRef: opts.inputRef?.trim() || undefined,
+                element: opts.element?.trim() || undefined,
+                targetId: opts.targetId?.trim() || undefined,
+                timeoutMs: Number.isFinite(opts.timeoutMs)
+                    ? opts.timeoutMs
+                    : undefined,
+                profile,
+            });
+            if (parent?.json) {
+                defaultRuntime.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            defaultRuntime.log(`upload armed for ${paths.length} file(s)`);
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    });
+    browser
+        .command("fill")
+        .description("Fill a form with JSON field descriptors")
+        .option("--fields <json>", "JSON array of field objects")
+        .option("--fields-file <path>", "Read JSON array from a file")
+        .option("--target-id <id>", "CDP target id (or unique prefix)")
+        .action(async (opts, cmd) => {
+        const parent = parentOpts(cmd);
+        const baseUrl = resolveBrowserControlUrl(parent?.url);
+        const profile = parent?.profile;
+        try {
+            const fields = await readFields({
+                fields: opts.fields,
+                fieldsFile: opts.fieldsFile,
+            });
+            const result = await browserAct(baseUrl, {
+                kind: "fill",
+                fields,
+                targetId: opts.targetId?.trim() || undefined,
+            }, { profile });
+            if (parent?.json) {
+                defaultRuntime.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            defaultRuntime.log(`filled ${fields.length} field(s)`);
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    });
+    browser
+        .command("dialog")
+        .description("Arm the next modal dialog (alert/confirm/prompt)")
+        .option("--accept", "Accept the dialog", false)
+        .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: 120000)", (v) => Number(v))
+        .action(async (opts, cmd) => {
+        const parent = parentOpts(cmd);
+        const baseUrl = resolveBrowserControlUrl(parent?.url);
+        const profile = parent?.profile;
+        const accept = opts.accept ? true : opts.dismiss ? false : undefined;
+        if (accept === undefined) {
+            defaultRuntime.error(danger("Specify --accept or --dismiss"));
+            defaultRuntime.exit(1);
+            return;
+        }
+        try {
+            const result = await browserArmDialog(baseUrl, {
+                accept,
+                promptText: opts.prompt?.trim() || undefined,
+                targetId: opts.targetId?.trim() || undefined,
+                timeoutMs: Number.isFinite(opts.timeoutMs)
+                    ? opts.timeoutMs
+                    : undefined,
+                profile,
+            });
+            if (parent?.json) {
+                defaultRuntime.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            defaultRuntime.log("dialog armed");
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    });
+    browser
+        .command("wait")
+        .description("Wait for time or text conditions")
+        .option("--time <ms>", "Wait for N milliseconds", (v) => Number(v))
+        .option("--text <value>", "Wait for text to appear")
+        .option("--text-gone <value>", "Wait for text to disappear")
+        .option("--target-id <id>", "CDP target id (or unique prefix)")
+        .action(async (opts, cmd) => {
+        const parent = parentOpts(cmd);
+        const baseUrl = resolveBrowserControlUrl(parent?.url);
+        const profile = parent?.profile;
+        try {
+            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,
+            }, { profile });
+            if (parent?.json) {
+                defaultRuntime.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            defaultRuntime.log("wait complete");
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    });
+    browser
+        .command("evaluate")
+        .description("Evaluate a function against the page or a ref")
+        .option("--fn <code>", "Function source, e.g. (el) => el.textContent")
+        .option("--ref <id>", "ARIA ref from ai snapshot")
+        .option("--target-id <id>", "CDP target id (or unique prefix)")
+        .action(async (opts, cmd) => {
+        const parent = parentOpts(cmd);
+        const baseUrl = resolveBrowserControlUrl(parent?.url);
+        const profile = parent?.profile;
+        if (!opts.fn) {
+            defaultRuntime.error(danger("Missing --fn"));
+            defaultRuntime.exit(1);
+            return;
+        }
+        try {
+            const result = await browserAct(baseUrl, {
+                kind: "evaluate",
+                fn: opts.fn,
+                ref: opts.ref?.trim() || undefined,
+                targetId: opts.targetId?.trim() || undefined,
+            }, { profile });
+            if (parent?.json) {
+                defaultRuntime.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            defaultRuntime.log(JSON.stringify(result.result ?? null, null, 2));
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    });
+}

package/dist/cli/browser-cli-actions-observe.js

@@ -0,0 +1,56 @@
+import { resolveBrowserControlUrl } from "../browser/client.js";
+import { browserConsoleMessages, browserPdfSave, } from "../browser/client-actions.js";
+import { danger } from "../globals.js";
+import { defaultRuntime } from "../runtime.js";
+export function registerBrowserActionObserveCommands(browser, parentOpts) {
+    browser
+        .command("console")
+        .description("Get recent console messages")
+        .option("--level <level>", "Filter by level (error, warn, info)")
+        .option("--target-id <id>", "CDP target id (or unique prefix)")
+        .action(async (opts, cmd) => {
+        const parent = parentOpts(cmd);
+        const baseUrl = resolveBrowserControlUrl(parent?.url);
+        const profile = parent?.profile;
+        try {
+            const result = await browserConsoleMessages(baseUrl, {
+                level: opts.level?.trim() || undefined,
+                targetId: opts.targetId?.trim() || undefined,
+                profile,
+            });
+            if (parent?.json) {
+                defaultRuntime.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            defaultRuntime.log(JSON.stringify(result.messages, null, 2));
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    });
+    browser
+        .command("pdf")
+        .description("Save page as PDF")
+        .option("--target-id <id>", "CDP target id (or unique prefix)")
+        .action(async (opts, cmd) => {
+        const parent = parentOpts(cmd);
+        const baseUrl = resolveBrowserControlUrl(parent?.url);
+        const profile = parent?.profile;
+        try {
+            const result = await browserPdfSave(baseUrl, {
+                targetId: opts.targetId?.trim() || undefined,
+                profile,
+            });
+            if (parent?.json) {
+                defaultRuntime.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            defaultRuntime.log(`PDF: ${result.path}`);
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    });
+}

package/dist/cli/browser-cli-examples.js

@@ -0,0 +1,31 @@
+export const browserCoreExamples = [
+    "nexus browser status",
+    "nexus browser start",
+    "nexus browser stop",
+    "nexus browser tabs",
+    "nexus browser open https://example.com",
+    "nexus browser focus abcd1234",
+    "nexus browser close abcd1234",
+    "nexus browser screenshot",
+    "nexus browser screenshot --full-page",
+    "nexus browser screenshot --ref 12",
+    "nexus browser snapshot",
+    "nexus browser snapshot --format aria --limit 200",
+];
+export const browserActionExamples = [
+    "nexus browser navigate https://example.com",
+    "nexus browser resize 1280 720",
+    "nexus browser click 12 --double",
+    'nexus browser type 23 "hello" --submit',
+    "nexus browser press Enter",
+    "nexus browser hover 44",
+    "nexus browser drag 10 11",
+    "nexus browser select 9 OptionA OptionB",
+    "nexus browser upload /tmp/file.pdf",
+    'nexus browser fill --fields \'[{"ref":"1","value":"Ada"}]\'',
+    "nexus browser dialog --accept",
+    'nexus browser wait --text "Done"',
+    "nexus browser evaluate --fn '(el) => el.textContent' --ref 7",
+    "nexus browser console --level error",
+    "nexus browser pdf",
+];

package/dist/cli/browser-cli-inspect.js

@@ -0,0 +1,97 @@
+import { browserSnapshot, resolveBrowserControlUrl, } from "../browser/client.js";
+import { browserScreenshotAction } from "../browser/client-actions.js";
+import { danger } from "../globals.js";
+import { defaultRuntime } from "../runtime.js";
+export function registerBrowserInspectCommands(browser, parentOpts) {
+    browser
+        .command("screenshot")
+        .description("Capture a screenshot (MEDIA:<path>)")
+        .argument("[targetId]", "CDP target id (or unique prefix)")
+        .option("--full-page", "Capture full scrollable page", false)
+        .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")
+        .action(async (targetId, opts, cmd) => {
+        const parent = parentOpts(cmd);
+        const baseUrl = resolveBrowserControlUrl(parent?.url);
+        const profile = parent?.profile;
+        try {
+            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",
+                profile,
+            });
+            if (parent?.json) {
+                defaultRuntime.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            defaultRuntime.log(`MEDIA:${result.path}`);
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    });
+    browser
+        .command("snapshot")
+        .description("Capture a snapshot (default: ai; aria is the accessibility tree)")
+        .option("--format <aria|ai>", "Snapshot format (default: ai)", "ai")
+        .option("--target-id <id>", "CDP target id (or unique prefix)")
+        .option("--limit <n>", "Max nodes (default: 500/800)", (v) => Number(v))
+        .option("--out <path>", "Write snapshot to a file")
+        .action(async (opts, cmd) => {
+        const parent = parentOpts(cmd);
+        const baseUrl = resolveBrowserControlUrl(parent?.url);
+        const profile = parent?.profile;
+        const format = opts.format === "aria" ? "aria" : "ai";
+        try {
+            const result = await browserSnapshot(baseUrl, {
+                format,
+                targetId: opts.targetId?.trim() || undefined,
+                limit: Number.isFinite(opts.limit) ? opts.limit : undefined,
+                profile,
+            });
+            if (opts.out) {
+                const fs = await import("node:fs/promises");
+                if (result.format === "ai") {
+                    await fs.writeFile(opts.out, result.snapshot, "utf8");
+                }
+                else {
+                    const payload = JSON.stringify(result, null, 2);
+                    await fs.writeFile(opts.out, payload, "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;
+            }
+            if (result.format === "ai") {
+                defaultRuntime.log(result.snapshot);
+                return;
+            }
+            const nodes = "nodes" in result ? result.nodes : [];
+            defaultRuntime.log(nodes
+                .map((n) => {
+                const indent = "  ".repeat(Math.min(20, n.depth));
+                const name = n.name ? ` "${n.name}"` : "";
+                const value = n.value ? ` = "${n.value}"` : "";
+                return `${indent}- ${n.role}${name}${value}`;
+            })
+                .join("\n"));
+        }
+        catch (err) {
+            defaultRuntime.error(danger(String(err)));
+            defaultRuntime.exit(1);
+        }
+    });
+}