@silbercue/chrome 0.2.0

package/build/tools/evaluate.js

@@ -0,0 +1,217 @@
+import { z } from "zod";
+import { wrapCdpError } from "./error-utils.js";
+import { getProHooks } from "../hooks/pro-hooks.js";
+/**
+ * Detects top-level const/let/class declarations and wraps the expression in
+ * an IIFE to avoid "Identifier has already been declared" errors across
+ * repeated Runtime.evaluate calls (which share the global scope).
+ *
+ * The last ExpressionStatement is automatically returned so callers still
+ * get the evaluation result.
+ */
+export function wrapInIIFE(expression) {
+    // Quick check: does the code need IIFE wrapping?
+    // - const/let/class declarations (would collide across repeated evaluate calls)
+    // - top-level return statements (illegal outside function body)
+    // - top-level await (FR-H3: illegal outside async function)
+    const hasDeclarations = /^[ \t]*(const|let|class)\s/m.test(expression);
+    const hasTopLevelReturn = /^[ \t]*return\s/m.test(expression);
+    const hasTopLevelAwait = /\bawait\b/.test(expression);
+    if (!hasDeclarations && !hasTopLevelReturn && !hasTopLevelAwait)
+        return expression;
+    // Already wrapped in an IIFE? Don't double-wrap.
+    const trimmed = expression.trim();
+    if (/^\([\s\S]*\)\s*\(\s*\)\s*;?\s*$/.test(trimmed))
+        return expression;
+    // FR-H3: Use async IIFE when code contains await
+    const asyncPrefix = hasTopLevelAwait ? "async " : "";
+    // If code already has explicit return statements, just wrap in IIFE — don't insert return.
+    if (hasTopLevelReturn) {
+        return `(${asyncPrefix}() => {\n${expression}\n})()`;
+    }
+    // Insert `return` before the last expression statement so the IIFE
+    // returns its value (arrow function block bodies don't auto-return).
+    const lines = expression.split("\n");
+    // FR-001: Use bracket-depth tracking to find the START of the last multi-line expression.
+    // Walk backwards from the last line, tracking depth of () {} [].
+    // When depth reaches 0, we've found the start of the expression.
+    let depth = 0;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].trim();
+        if (!line || line.startsWith("//"))
+            continue;
+        // Count brackets right-to-left (we're scanning backwards)
+        for (let c = line.length - 1; c >= 0; c--) {
+            const ch = line[c];
+            if (ch === ")" || ch === "}" || ch === "]")
+                depth++;
+            else if (ch === "(" || ch === "{" || ch === "[")
+                depth--;
+        }
+        // depth > 0 means we're still inside a multi-line expression — keep walking up
+        if (depth > 0)
+            continue;
+        // Found the start of the last complete expression/statement.
+        if (/^(const|let|var|if|for|while|switch|try|throw|return|class|function)\b/.test(line)) {
+            // It's a statement keyword — check for trailing expression after last ;
+            const lastSemi = line.lastIndexOf(";");
+            if (lastSemi >= 0 && lastSemi < line.length - 1) {
+                const trailing = line.substring(lastSemi + 1).trim();
+                if (trailing && !/^(const|let|var|if|for|while|switch|try|throw|return|class|function)\b/.test(trailing)) {
+                    const indent = lines[i].match(/^(\s*)/)?.[1] ?? "";
+                    lines[i] = indent + line.substring(0, lastSemi + 1);
+                    lines.splice(i + 1, 0, indent + "return " + trailing);
+                }
+            }
+            break;
+        }
+        // Pure expression — prepend return
+        const indent = lines[i].match(/^(\s*)/)?.[1] ?? "";
+        lines[i] = indent + "return " + lines[i].trimStart();
+        break;
+    }
+    return `(${asyncPrefix}() => {\n${lines.join("\n")}\n})()`;
+}
+export const evaluateSchema = z.object({
+    expression: z.string().describe("JavaScript code to execute in the page context"),
+    await_promise: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Whether to await Promise results"),
+});
+/**
+ * FR-024: Detect common evaluate anti-patterns where a dedicated tool would be better.
+ * Returns a hint string appended to the evaluate result, or null if no pattern matched.
+ * Intent: "what you did isn't wrong, but there's a more reliable tool for this".
+ *
+ * Design: be specific enough to avoid false positives on legitimate DOM work
+ * (e.g. `document.querySelector('.card').style.width = '200px'` is NOT an
+ * anti-pattern — it's a style edit that no other tool covers).
+ */
+export function detectEvaluateAntiPattern(expression) {
+    const hints = [];
+    // Pattern 1A: Bulk element discovery via querySelectorAll / getElementsByXxx.
+    // This is read_page's core job — stable refs survive, selectors don't.
+    const bulkDiscovery = /\bdocument\.(querySelectorAll|getElementsByTagName|getElementsByClassName|getElementsByName)\b/.test(expression);
+    // Pattern 1B: querySelector with a bare interactive tag selector (e.g. 'button', 'input').
+    // Someone using tag selectors is almost always discovering interactive elements.
+    const querySelectorForTag = /\bdocument\.querySelector\s*\(\s*['"`](button|input|select|textarea|form|label|a)\b/i.test(expression);
+    // Pattern 1C: query-then-interact — get element by ID/selector, then use it as an interactive target
+    // (click/focus/submit/value/checked/selectedIndex). This is click/type/fill_form territory.
+    // Allowed through: .style.*, .classList.*, .dataset.*, .scrollTop — those are handled elsewhere.
+    const queryThenInteract = /\bdocument\.(querySelector|getElementById)\s*\([^)]*\)\s*(?:\?\.)?\s*\.(click\s*\(|focus\s*\(|blur\s*\(|submit\s*\(|value\b|checked\b|selectedIndex\b|disabled\b|selected\b)/.test(expression);
+    if (bulkDiscovery || querySelectorForTag || queryThenInteract) {
+        hints.push("Interactive elements (buttons, links, inputs) are already surfaced as stable refs by read_page. Try click(ref: 'eN') or fill_form(fields: [...]) instead of DOM queries — refs survive layout changes, selectors don't.");
+    }
+    // Pattern 2: Reading innerText/textContent to extract visible text.
+    // filter:'all' on a subtree ref exposes the same text without a second round-trip.
+    // Require a leading dot so that string literals mentioning the word don't trigger.
+    if (/[.?]\s*(innerText|textContent)\b(?!\s*=)/.test(expression)) {
+        hints.push("Reading .innerText/.textContent? The a11y tree already contains visible text. Try read_page(ref: 'eN', filter: 'all') — table cells, static codes, paragraphs all show up with stable refs.");
+    }
+    // Pattern 3: Inspecting function source via .toString() on a Tests.* / test harness function.
+    // This is usually "the LLM is reverse-engineering the test instead of reading the UI".
+    if (/\b(Tests?|Benchmark|Spec)\b[\w.]*\.toString\s*\(\s*\)/.test(expression) ||
+        /\bfunction[\s\S]{0,80}\.toString\s*\(\s*\)/.test(expression)) {
+        hints.push("Reading test/function source via .toString()? The visible UI usually has the task description (e.g. .test-desc text). Try read_page(ref, filter:'all') first — don't debug the test harness.");
+    }
+    // Pattern 4: Scrolling via element.scrollIntoView() or container.scrollTop = N.
+    // The scroll tool handles both patterns with ref-based targeting and smooth fallback.
+    if (/\.scrollIntoView\s*\(/.test(expression) ||
+        /\.scrollTop\s*=\s*\d/.test(expression)) {
+        hints.push("Scrolling via JS? The scroll tool supports ref/selector and container scrolling — scroll(ref: 'eN') or scroll(container_ref: 'eN', direction: 'down').");
+    }
+    // Pattern 5: Dispatching click events via .click() or dispatchEvent(new MouseEvent).
+    // The click tool fires the full CDP pointer event chain which works with widgets
+    // that only listen to pointerdown/mousedown.
+    if (/\.click\s*\(\s*\)/.test(expression) ||
+        /dispatchEvent\s*\(\s*new\s+(Mouse|Pointer)Event/.test(expression)) {
+        hints.push("Dispatching click via JS? The click tool fires the full CDP pointer chain (pointerdown → mousedown → pointerup → mouseup → click), which works with custom widgets that DOM .click() silently skips.");
+    }
+    if (hints.length === 0)
+        return null;
+    return "\n\nTip: " + hints.join("\n\nTip: ");
+}
+export async function evaluateHandler(params, cdpClient, sessionId) {
+    const start = performance.now();
+    try {
+        // --- Execute expression ---
+        const wrappedExpression = wrapInIIFE(params.expression);
+        const cdpResult = await cdpClient.send("Runtime.evaluate", {
+            expression: wrappedExpression,
+            returnByValue: true,
+            awaitPromise: params.await_promise,
+        }, sessionId);
+        const elapsedMs = Math.round(performance.now() - start);
+        // Check for JS exception
+        if (cdpResult.exceptionDetails) {
+            const details = cdpResult.exceptionDetails;
+            const message = details.exception?.description || details.text || "Unknown JavaScript error";
+            return {
+                content: [{ type: "text", text: message }],
+                isError: true,
+                _meta: { elapsedMs, method: "evaluate" },
+            };
+        }
+        // Extract result value
+        const resultValue = cdpResult.result;
+        let text;
+        if (resultValue.type === "undefined") {
+            text = "undefined";
+        }
+        else if (resultValue.value === undefined) {
+            // Non-serializable result (e.g. DOM nodes) — returnByValue couldn't serialize
+            const desc = resultValue.description || resultValue.className || resultValue.subtype || resultValue.type;
+            return {
+                content: [{ type: "text", text: `Result not serializable: ${desc}` }],
+                isError: true,
+                _meta: { elapsedMs, method: "evaluate" },
+            };
+        }
+        else {
+            text = JSON.stringify(resultValue.value);
+        }
+        // FR-024: Detect evaluate anti-patterns and append actionable hints so the
+        // LLM learns better defaults over time. The result stays correct — this is
+        // a "what you did isn't wrong, but there's a better tool" nudge.
+        const antiPatternHint = detectEvaluateAntiPattern(params.expression);
+        const textWithHint = antiPatternHint ? text + antiPatternHint : text;
+        const baseResult = {
+            content: [{ type: "text", text: textWithHint }],
+            _meta: {
+                elapsedMs: Math.round(performance.now() - start),
+                method: "evaluate",
+            },
+        };
+        // Story 15.2: Visual Feedback (Geometry-Diff + Clip-Screenshot) is a
+        // Pro-Feature. The Pro-Repo registers `enhanceEvaluateResult` via
+        // `registerProHooks(...)` to inject geometry + screenshot data. When
+        // no Pro-Repo is loaded, the plain text result is returned unchanged.
+        //
+        // Code-Review M2: The hook is defensively wrapped in try/catch. Any
+        // exception (sync throw or rejected Promise) falls back to `baseResult`
+        // so that a buggy Pro-Repo cannot crash the evaluate tool.
+        const hooks = getProHooks();
+        if (hooks.enhanceEvaluateResult) {
+            try {
+                return await hooks.enhanceEvaluateResult(params.expression, baseResult, {
+                    cdpClient,
+                    sessionId,
+                });
+            }
+            catch {
+                return baseResult;
+            }
+        }
+        return baseResult;
+    }
+    catch (err) {
+        const elapsedMs = Math.round(performance.now() - start);
+        return {
+            content: [{ type: "text", text: wrapCdpError(err, "evaluate") }],
+            isError: true,
+            _meta: { elapsedMs, method: "evaluate" },
+        };
+    }
+}

package/build/tools/file-upload.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import type { CdpClient } from "../cdp/cdp-client.js";
+import type { SessionManager } from "../cdp/session-manager.js";
+import type { ToolResponse } from "../types.js";
+export declare const fileUploadSchema: z.ZodObject<{
+    ref: z.ZodOptional<z.ZodString>;
+    selector: z.ZodOptional<z.ZodString>;
+    path: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>;
+}, "strip", z.ZodTypeAny, {
+    path: string | string[];
+    ref?: string | undefined;
+    selector?: string | undefined;
+}, {
+    path: string | string[];
+    ref?: string | undefined;
+    selector?: string | undefined;
+}>;
+export type FileUploadParams = z.infer<typeof fileUploadSchema>;
+export declare function formatFileSize(bytes: number): string;
+export declare function fileUploadHandler(params: FileUploadParams, cdpClient: CdpClient, sessionId?: string, sessionManager?: SessionManager): Promise<ToolResponse>;

package/build/tools/file-upload.js

@@ -0,0 +1,174 @@
+import { z } from "zod";
+import { existsSync, statSync } from "node:fs";
+import { basename, isAbsolute } from "node:path";
+import { resolveElement, buildRefNotFoundError, RefNotFoundError } from "./element-utils.js";
+import { wrapCdpError } from "./error-utils.js";
+// --- Schema (Task 1.1) ---
+export const fileUploadSchema = z.object({
+    ref: z
+        .string()
+        .optional()
+        .describe("A11y-Tree element ref (e.g. 'e8') — preferred over selector"),
+    selector: z
+        .string()
+        .optional()
+        .describe("CSS selector (e.g. 'input[type=file]') — fallback when ref is not available"),
+    path: z
+        .union([z.string(), z.array(z.string()).min(1)])
+        .describe("Absolute file path(s) to upload. String for single file, array for multiple files."),
+});
+// --- Helpers (Task 1.3) ---
+export function formatFileSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+// --- Main handler (Task 1.2) ---
+export async function fileUploadHandler(params, cdpClient, sessionId, sessionManager) {
+    const start = performance.now();
+    // Step 1: Validate ref/selector — at least one must be provided
+    if (!params.ref && !params.selector) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "file_upload requires either 'ref' or 'selector' to identify the target element",
+                },
+            ],
+            isError: true,
+            _meta: { elapsedMs: 0, method: "file_upload" },
+        };
+    }
+    // Step 2: Normalize paths — string or array → always string[]
+    const filePaths = Array.isArray(params.path) ? params.path : [params.path];
+    // Step 2b: Validate all paths are absolute
+    for (const filePath of filePaths) {
+        if (!isAbsolute(filePath)) {
+            const elapsedMs = Math.round(performance.now() - start);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Relativer Pfad nicht erlaubt: "${filePath}". Bitte absoluten Pfad verwenden (z.B. /Users/…/datei.pdf).`,
+                    },
+                ],
+                isError: true,
+                _meta: { elapsedMs, method: "file_upload" },
+            };
+        }
+    }
+    // Step 3: Validate all file paths exist BEFORE any CDP calls
+    for (const filePath of filePaths) {
+        if (!existsSync(filePath)) {
+            const elapsedMs = Math.round(performance.now() - start);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Datei nicht gefunden: ${filePath}`,
+                    },
+                ],
+                isError: true,
+                _meta: { elapsedMs, method: "file_upload" },
+            };
+        }
+    }
+    try {
+        // Step 4: Resolve element (ref preferred over selector, with OOPIF routing)
+        const target = params.ref ? { ref: params.ref } : { selector: params.selector };
+        const element = await resolveElement(cdpClient, sessionId, target, sessionManager);
+        const targetSession = element.resolvedSessionId;
+        // Step 5: File-Input validation — check if element is <input type="file">
+        const tagCheck = await cdpClient.send("Runtime.callFunctionOn", {
+            objectId: element.objectId,
+            functionDeclaration: `function() {
+          return this.tagName + '|' + this.type;
+        }`,
+            returnByValue: true,
+        }, targetSession);
+        const [tagName, inputType] = tagCheck.result.value.split("|");
+        if (tagName !== "INPUT" || inputType !== "file") {
+            // Search for nearest file input in DOM for helpful error message
+            const hint = await cdpClient.send("Runtime.evaluate", {
+                expression: `(() => {
+            const fi = document.querySelector('input[type=file]');
+            if (!fi) return '';
+            return fi.name || fi.id || fi.getAttribute('aria-label') || 'unnamed';
+          })()`,
+                returnByValue: true,
+            }, targetSession);
+            const elapsedMs = Math.round(performance.now() - start);
+            let errorText = `Element ${params.ref ?? params.selector} ist kein File-Input (${tagName.toLowerCase()} ${inputType || ""}).`;
+            if (hint.result.value) {
+                errorText += ` Naechstes File-Input im DOM: ${hint.result.value}`;
+            }
+            return {
+                content: [{ type: "text", text: errorText.trimEnd() }],
+                isError: true,
+                _meta: { elapsedMs, method: "file_upload" },
+            };
+        }
+        // Step 6: Multiple-validation — reject multiple files when input doesn't have multiple attribute
+        if (filePaths.length > 1) {
+            const multiCheck = await cdpClient.send("Runtime.callFunctionOn", {
+                objectId: element.objectId,
+                functionDeclaration: "function() { return this.multiple; }",
+                returnByValue: true,
+            }, targetSession);
+            if (!multiCheck.result.value) {
+                const elapsedMs = Math.round(performance.now() - start);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "File-Input akzeptiert keine mehrfachen Dateien (multiple nicht gesetzt). Nur eine Datei hochladen.",
+                        },
+                    ],
+                    isError: true,
+                    _meta: { elapsedMs, method: "file_upload" },
+                };
+            }
+        }
+        // Step 7: Execute upload via CDP DOM.setFileInputFiles
+        await cdpClient.send("DOM.setFileInputFiles", { files: filePaths, backendNodeId: element.backendNodeId }, targetSession);
+        // Step 8: Get file sizes and build success response
+        const fileDetails = filePaths.map((fp) => {
+            const size = statSync(fp).size;
+            return `- ${basename(fp)} (${formatFileSize(size)})`;
+        });
+        const elapsedMs = Math.round(performance.now() - start);
+        const displayName = element.name
+            ? `${element.role} '${element.name}'`
+            : (params.ref ?? params.selector);
+        const fileWord = filePaths.length === 1 ? "file" : "files";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Uploaded ${filePaths.length} ${fileWord} to ${displayName}:\n${fileDetails.join("\n")}`,
+                },
+            ],
+            _meta: { elapsedMs, method: "file_upload" },
+        };
+    }
+    catch (err) {
+        // RefNotFoundError — contextual error with "did you mean?" suggestion
+        if (err instanceof RefNotFoundError && params.ref) {
+            const errorText = buildRefNotFoundError(params.ref);
+            return {
+                content: [{ type: "text", text: errorText }],
+                isError: true,
+                _meta: { elapsedMs: 0, method: "file_upload" },
+            };
+        }
+        // CDP connection errors — wrap for user-friendly message (consistent with other tools)
+        const elapsedMs = Math.round(performance.now() - start);
+        return {
+            content: [{ type: "text", text: wrapCdpError(err, "file_upload") }],
+            isError: true,
+            _meta: { elapsedMs, method: "file_upload" },
+        };
+    }
+}

package/build/tools/fill-form.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import type { CdpClient } from "../cdp/cdp-client.js";
+import type { SessionManager } from "../cdp/session-manager.js";
+import type { ToolResponse } from "../types.js";
+export declare const fillFormSchema: z.ZodObject<{
+    fields: z.ZodArray<z.ZodObject<{
+        ref: z.ZodOptional<z.ZodString>;
+        selector: z.ZodOptional<z.ZodString>;
+        value: z.ZodUnion<[z.ZodString, z.ZodBoolean, z.ZodNumber]>;
+    }, "strip", z.ZodTypeAny, {
+        value: string | number | boolean;
+        ref?: string | undefined;
+        selector?: string | undefined;
+    }, {
+        value: string | number | boolean;
+        ref?: string | undefined;
+        selector?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    fields: {
+        value: string | number | boolean;
+        ref?: string | undefined;
+        selector?: string | undefined;
+    }[];
+}, {
+    fields: {
+        value: string | number | boolean;
+        ref?: string | undefined;
+        selector?: string | undefined;
+    }[];
+}>;
+export type FillFormParams = z.infer<typeof fillFormSchema>;
+/**
+ * Story 16.5: Optional human-type callback injected via the `enhanceTool`
+ * Pro-Hook. Used to replace the raw `Input.insertText` with a realistic
+ * per-character typing sequence from the Pro-Repo Human Touch module.
+ */
+export type HumanTypeFn = (cdpClient: CdpClient, sessionId: string, text: string) => Promise<void>;
+export declare function fillFormHandler(params: FillFormParams, cdpClient: CdpClient, sessionId?: string, sessionManager?: SessionManager): Promise<ToolResponse>;