xcoder-dna 0.0.0-stage → 1.3.0

package/dist/tools/browse-tool.d.ts

@@ -0,0 +1,105 @@
+/**
+ * `browse` — let the agent (or `xcoder browse …`) drive a real browser through
+ * a list of steps: navigate, click, type, read text/links, screenshot, assert.
+ * Unlike `ui_test` (pass/fail only) it RETURNS what it read, so the model can
+ * decide its next step. Requires the optional `playwright` dependency.
+ *
+ * Safety:
+ *  - every request (navigation, redirect, sub-resource) goes through
+ *    `checkRequestAllowed` — http(s) only, no file:/chrome:/ftp:, and no
+ *    private-network or cloud-metadata hosts unless XCODER_BROWSE_ALLOW_PRIVATE=1
+ *    (localhost is always allowed so local apps can be tested);
+ *  - secrets are typed via `credentialRef` (env var name) and never returned;
+ *    LLM / GitHub key variables can never be used as a credentialRef;
+ *  - screenshots can only be written inside the workspace.
+ */
+export type BrowseStep = {
+    op: "goto";
+    url: string;
+} | {
+    op: "click" | "hover" | "check" | "uncheck";
+    selector: string;
+} | {
+    op: "fill" | "type";
+    selector: string;
+    value?: string;
+    credentialRef?: string;
+} | {
+    op: "select";
+    selector: string;
+    value: string;
+} | {
+    op: "press";
+    key: string;
+    selector?: string;
+} | {
+    op: "scroll";
+    to: "top" | "bottom" | "up" | "down" | string;
+} | {
+    op: "wait_for";
+    selector: string;
+    state?: "visible" | "hidden" | "attached" | "detached";
+    timeoutMs?: number;
+} | {
+    op: "wait";
+    ms: number;
+} | {
+    op: "text";
+    selector?: string;
+} | {
+    op: "attr";
+    selector: string;
+    name: string;
+} | {
+    op: "links";
+    selector?: string;
+} | {
+    op: "title" | "url" | "back" | "forward" | "reload" | "close";
+} | {
+    op: "screenshot";
+    path?: string;
+    fullPage?: boolean;
+} | {
+    op: "expect_text";
+    selector: string;
+    text: string;
+} | {
+    op: "expect_url";
+    contains: string;
+};
+export interface BrowseInput {
+    /** Optional starting URL (same as a leading `goto` step). */
+    url?: string;
+    steps: BrowseStep[];
+    /** Keep the browser open between calls under this name (cookies/login survive). End with {op:"close"}. */
+    session?: string;
+    headed?: boolean;
+    /** Per-step timeout, default 10000. */
+    timeoutMs?: number;
+}
+export interface BrowseStepResult {
+    op: string;
+    ok: boolean;
+    note: string;
+    data?: unknown;
+}
+export interface BrowseResult {
+    ok: boolean;
+    detail: string;
+    steps: BrowseStepResult[];
+    page?: {
+        url: string;
+        title: string;
+        text: string;
+    };
+    screenshots: string[];
+}
+/** Returns a reason string if the URL must be blocked, otherwise null. */
+export declare function checkRequestAllowed(rawUrl: string, opts?: {
+    navigation?: boolean;
+}): string | null;
+export declare function closeAllBrowseSessions(): Promise<void>;
+/** Split "SEL=VALUE" at the first `=` that is not inside [] or quotes. */
+export declare function splitSelectorValue(s: string): [string, string | undefined];
+export declare function parseStepSpec(spec: string): BrowseStep;
+export declare function runBrowse(root: string, input: BrowseInput): Promise<BrowseResult>;

package/dist/tools/browse-tool.js

@@ -0,0 +1,394 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveCredential, redact } from "./credential.js";
+const MAX_TEXT = 4000;
+const MAX_LINKS = 50;
+const MAX_SESSIONS = 3;
+const FORBIDDEN_CREDENTIAL_REFS = /^(XCODER_API_KEY|DEEPSEEK_API_KEY|ANTHROPIC_API_KEY|OPENAI_API_KEY|GITHUB_TOKEN|GH_TOKEN)$/i;
+// ── URL policy ──────────────────────────────────────────────────────────────
+function isPrivateIPv4(host) {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    if (!m)
+        return false;
+    const [a, b] = [Number(m[1]), Number(m[2])];
+    if (a === 127)
+        return false; // loopback is allowed (local apps)
+    return a === 10 || a === 0 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254) || (a === 100 && b >= 64 && b <= 127);
+}
+function isPrivateIPv6(host) {
+    const h = host.replace(/^\[|\]$/g, "").toLowerCase();
+    if (!h.includes(":"))
+        return false; // a domain name like "fd-cdn.example.com", not an IPv6 literal
+    if (h === "::1")
+        return false; // loopback allowed
+    // IPv4-mapped: WHATWG URL normalises ::ffff:10.0.0.1 to ::ffff:a00:1
+    const hex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(h);
+    if (hex) {
+        const hi = parseInt(hex[1], 16);
+        const lo = parseInt(hex[2], 16);
+        return isPrivateIPv4(`${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`);
+    }
+    if (h.startsWith("::ffff:"))
+        return isPrivateIPv4(h.slice(7));
+    return /^(fc|fd)/.test(h) || /^fe[89ab]/.test(h) || h === "::";
+}
+/** Returns a reason string if the URL must be blocked, otherwise null. */
+export function checkRequestAllowed(rawUrl, opts = {}) {
+    let u;
+    try {
+        u = new URL(rawUrl);
+    }
+    catch {
+        return `invalid URL "${rawUrl}"`;
+    }
+    const proto = u.protocol;
+    if (proto === "http:" || proto === "https:") {
+        const host = u.hostname.toLowerCase();
+        if (process.env.XCODER_BROWSE_ALLOW_PRIVATE === "1")
+            return null;
+        if (host === "metadata.google.internal" || host.endsWith(".internal") || host === "metadata")
+            return `host "${host}" is blocked (cloud metadata)`;
+        if (isPrivateIPv4(host) || isPrivateIPv6(host)) {
+            return `private-network address "${host}" is blocked (set XCODER_BROWSE_ALLOW_PRIVATE=1 to allow; localhost is always allowed)`;
+        }
+        return null;
+    }
+    // Sub-resources may be data:/blob:/about:, but navigation must be http(s).
+    if (!opts.navigation && (proto === "data:" || proto === "blob:" || proto === "about:"))
+        return null;
+    return `scheme "${proto}" is not allowed (http and https only)`;
+}
+const sessions = new Map();
+export async function closeAllBrowseSessions() {
+    for (const [name, s] of sessions) {
+        sessions.delete(name);
+        await s.browser.close().catch(() => undefined);
+    }
+}
+// ── step DSL for the CLI:  xcoder browse --step "click:#login" ───────────────
+/** Split "SEL=VALUE" at the first `=` that is not inside [] or quotes. */
+export function splitSelectorValue(s) {
+    let depth = 0;
+    let quote = "";
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (quote) {
+            if (c === quote)
+                quote = "";
+        }
+        else if (c === '"' || c === "'")
+            quote = c;
+        else if (c === "[")
+            depth++;
+        else if (c === "]")
+            depth = Math.max(0, depth - 1);
+        else if (c === "=" && depth === 0)
+            return [s.slice(0, i), s.slice(i + 1)];
+    }
+    return [s, undefined];
+}
+export function parseStepSpec(spec) {
+    const raw = spec.trim();
+    if (/^https?:\/\//i.test(raw))
+        return { op: "goto", url: raw };
+    const colon = raw.indexOf(":");
+    const op = (colon === -1 ? raw : raw.slice(0, colon)).trim().toLowerCase();
+    const rest = colon === -1 ? "" : raw.slice(colon + 1).trim();
+    const need = (what) => {
+        if (!rest)
+            throw new Error(`step "${spec}": ${op} needs ${what}`);
+        return rest;
+    };
+    const pair = (what) => {
+        const [sel, val] = splitSelectorValue(need(what));
+        if (val === undefined)
+            throw new Error(`step "${spec}": expected ${op}:SELECTOR=VALUE`);
+        return [sel, val];
+    };
+    switch (op) {
+        case "goto":
+        case "open":
+            return { op: "goto", url: need("a URL") };
+        case "click":
+        case "hover":
+        case "check":
+        case "uncheck":
+            return { op, selector: need("a selector") };
+        case "fill":
+        case "type": {
+            const [selector, value] = pair("SELECTOR=VALUE");
+            return { op, selector, value };
+        }
+        case "select": {
+            const [selector, value] = pair("SELECTOR=VALUE");
+            return { op: "select", selector, value };
+        }
+        case "press": {
+            const [sel, val] = splitSelectorValue(need("a key"));
+            return val === undefined ? { op: "press", key: sel } : { op: "press", selector: sel, key: val };
+        }
+        case "scroll":
+            return { op: "scroll", to: need("top|bottom|up|down|SELECTOR") };
+        case "wait": {
+            if (/^\d+$/.test(rest))
+                return { op: "wait", ms: Number(rest) };
+            return { op: "wait_for", selector: need("milliseconds or a selector") };
+        }
+        case "text":
+            return rest ? { op: "text", selector: rest } : { op: "text" };
+        case "links":
+            return rest ? { op: "links", selector: rest } : { op: "links" };
+        case "attr": {
+            const at = need("SELECTOR@attribute").lastIndexOf("@");
+            if (at < 1)
+                throw new Error(`step "${spec}": expected attr:SELECTOR@name`);
+            return { op: "attr", selector: rest.slice(0, at), name: rest.slice(at + 1) };
+        }
+        case "title":
+        case "url":
+        case "back":
+        case "forward":
+        case "reload":
+        case "close":
+            return { op };
+        case "screenshot":
+        case "shot":
+            return rest ? { op: "screenshot", path: rest } : { op: "screenshot" };
+        case "expect_text": {
+            const [selector, text] = pair("SELECTOR=TEXT");
+            return { op: "expect_text", selector, text };
+        }
+        case "expect_url":
+            return { op: "expect_url", contains: need("text the URL contains") };
+        default:
+            throw new Error(`unknown step "${spec}" (goto, click, fill, type, press, select, check, hover, scroll, wait, text, links, attr, title, url, screenshot, back, forward, reload, expect_text, expect_url)`);
+    }
+}
+// ── runner ──────────────────────────────────────────────────────────────────
+const clip = (s, n = MAX_TEXT) => (s.length > n ? `${s.slice(0, n)}… [truncated ${s.length - n} chars]` : s);
+function screenshotTarget(root, requested) {
+    const rel = requested ?? path.join(".xcoder", "screenshots", `shot-${new Date().toISOString().replace(/[:.]/g, "-")}.png`);
+    const full = path.resolve(root, rel);
+    const base = path.resolve(root);
+    if (full !== base && !full.startsWith(base + path.sep))
+        throw new Error(`screenshot path "${rel}" is outside the workspace`);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    // Resolve symlinks on the directory so a link inside the workspace can't redirect the write.
+    const realDir = fs.realpathSync(path.dirname(full));
+    const realBase = fs.realpathSync(base);
+    if (realDir !== realBase && !realDir.startsWith(realBase + path.sep))
+        throw new Error(`screenshot path "${rel}" resolves outside the workspace`);
+    return path.join(realDir, path.basename(full));
+}
+export async function runBrowse(root, input) {
+    const results = [];
+    const screenshots = [];
+    const fail = (detail) => ({ ok: false, detail, steps: results, screenshots });
+    const steps = [...(input.url ? [{ op: "goto", url: input.url }] : []), ...(input.steps ?? [])];
+    if (steps.length === 0)
+        return fail("no steps given");
+    let chromium;
+    try {
+        ({ chromium } = await import("playwright"));
+    }
+    catch {
+        return fail("the `playwright` package isn't installed. Run `npm install` then `npx playwright install chromium`.");
+    }
+    const sessionName = input.session?.trim() || undefined;
+    let session = sessionName ? sessions.get(sessionName) : undefined;
+    let created = false;
+    if (!session) {
+        if (sessionName && sessions.size >= MAX_SESSIONS)
+            return fail(`too many open browser sessions (max ${MAX_SESSIONS}); close one with {"op":"close"}`);
+        const browser = await chromium.launch({ headless: !input.headed });
+        const context = await browser.newContext();
+        await context.route("**/*", (route) => {
+            const why = checkRequestAllowed(route.request().url(), { navigation: route.request().isNavigationRequest() });
+            if (why)
+                return route.abort("blockedbyclient");
+            return route.continue();
+        });
+        const page = await context.newPage();
+        session = { browser, page };
+        created = true;
+        if (sessionName)
+            sessions.set(sessionName, session);
+    }
+    const { page } = session;
+    page.setDefaultTimeout(input.timeoutMs ?? 10000);
+    let ok = true;
+    let closeRequested = false;
+    const secretRefs = [];
+    try {
+        for (const step of steps) {
+            const label = step.op;
+            try {
+                switch (step.op) {
+                    case "goto": {
+                        const why = checkRequestAllowed(step.url, { navigation: true });
+                        if (why)
+                            throw new Error(why);
+                        const resp = await page.goto(step.url, { waitUntil: "domcontentloaded" });
+                        results.push({ op: label, ok: true, note: `${step.url} → ${resp ? resp.status() : "no response"}` });
+                        break;
+                    }
+                    case "click":
+                    case "hover":
+                    case "check":
+                    case "uncheck":
+                        await page[step.op](step.selector);
+                        results.push({ op: label, ok: true, note: step.selector });
+                        break;
+                    case "fill":
+                    case "type": {
+                        let value = step.value;
+                        if (step.credentialRef) {
+                            if (FORBIDDEN_CREDENTIAL_REFS.test(step.credentialRef))
+                                throw new Error(`credentialRef "${step.credentialRef}" is not allowed in browse`);
+                            value = resolveCredential(step.credentialRef);
+                            secretRefs.push(step.credentialRef);
+                        }
+                        if (value === undefined)
+                            throw new Error(`${step.op} needs "value" or "credentialRef"`);
+                        if (step.op === "fill")
+                            await page.fill(step.selector, value);
+                        else
+                            await page.type(step.selector, value);
+                        results.push({ op: label, ok: true, note: `${step.selector}${step.credentialRef ? " (value redacted)" : ""}` });
+                        break;
+                    }
+                    case "select":
+                        await page.selectOption(step.selector, step.value);
+                        results.push({ op: label, ok: true, note: `${step.selector} = ${step.value}` });
+                        break;
+                    case "press":
+                        if (step.selector)
+                            await page.press(step.selector, step.key);
+                        else
+                            await page.keyboard.press(step.key);
+                        results.push({ op: label, ok: true, note: step.key });
+                        break;
+                    case "scroll": {
+                        if (["top", "bottom", "up", "down"].includes(step.to)) {
+                            // Browser-side code is passed as a string so this file needs no DOM typings.
+                            await page.evaluate(`(() => { const to = ${JSON.stringify(step.to)}; const h = document.documentElement.scrollHeight;
+                  if (to === "top") window.scrollTo(0, 0);
+                  else if (to === "bottom") window.scrollTo(0, h);
+                  else window.scrollBy(0, to === "down" ? window.innerHeight * 0.8 : -window.innerHeight * 0.8); })()`);
+                        }
+                        else {
+                            await page.locator(step.to).first().scrollIntoViewIfNeeded();
+                        }
+                        results.push({ op: label, ok: true, note: step.to });
+                        break;
+                    }
+                    case "wait_for":
+                        await page.waitForSelector(step.selector, { state: step.state ?? "visible", timeout: step.timeoutMs });
+                        results.push({ op: label, ok: true, note: `${step.selector} ${step.state ?? "visible"}` });
+                        break;
+                    case "wait":
+                        await page.waitForTimeout(Math.min(Math.max(step.ms, 0), 30000));
+                        results.push({ op: label, ok: true, note: `${step.ms}ms` });
+                        break;
+                    case "text": {
+                        const t = (await page.innerText(step.selector ?? "body")) ?? "";
+                        results.push({ op: label, ok: true, note: step.selector ?? "body", data: clip(t) });
+                        break;
+                    }
+                    case "attr": {
+                        const v = await page.getAttribute(step.selector, step.name);
+                        results.push({ op: label, ok: true, note: `${step.selector}@${step.name}`, data: v });
+                        break;
+                    }
+                    case "links": {
+                        const links = (await page.$$eval(`${step.selector ?? "body"} a[href]`, `(as) => as.map((a) => ({ text: (a.innerText || "").trim().slice(0, 80), href: a.href }))`));
+                        results.push({ op: label, ok: true, note: `${links.length} link(s)`, data: links.slice(0, MAX_LINKS) });
+                        break;
+                    }
+                    case "title":
+                        results.push({ op: label, ok: true, note: await page.title() });
+                        break;
+                    case "url":
+                        results.push({ op: label, ok: true, note: page.url() });
+                        break;
+                    case "back":
+                    case "forward":
+                    case "reload": {
+                        const fn = step.op === "back" ? "goBack" : step.op === "forward" ? "goForward" : "reload";
+                        await page[fn]({ waitUntil: "domcontentloaded" });
+                        results.push({ op: label, ok: true, note: page.url() });
+                        break;
+                    }
+                    case "screenshot": {
+                        const target = screenshotTarget(root, step.path);
+                        await page.screenshot({ path: target, fullPage: step.fullPage ?? false });
+                        const rel = path.relative(root, target) || target;
+                        screenshots.push(rel);
+                        results.push({ op: label, ok: true, note: rel });
+                        break;
+                    }
+                    case "expect_text": {
+                        const content = await page.textContent(step.selector);
+                        const hit = !!content && content.includes(step.text);
+                        results.push({ op: label, ok: hit, note: hit ? "matched" : `expected "${step.text}", got "${clip(content ?? "", 200)}"` });
+                        if (!hit)
+                            ok = false;
+                        break;
+                    }
+                    case "expect_url": {
+                        const hit = page.url().includes(step.contains);
+                        results.push({ op: label, ok: hit, note: hit ? "matched" : `got ${page.url()}` });
+                        if (!hit)
+                            ok = false;
+                        break;
+                    }
+                    case "close":
+                        closeRequested = true;
+                        results.push({ op: label, ok: true, note: "browser closed" });
+                        break;
+                    default:
+                        throw new Error(`unknown op "${step.op}"`);
+                }
+            }
+            catch (e) {
+                ok = false;
+                let msg = e.message;
+                for (const ref of secretRefs)
+                    msg = redact(msg, ref);
+                results.push({ op: label, ok: false, note: clip(msg, 500) });
+                break; // stop at the first hard failure
+            }
+            if (closeRequested)
+                break;
+        }
+        let pageInfo;
+        if (!closeRequested) {
+            try {
+                pageInfo = {
+                    url: page.url(),
+                    title: await page.title(),
+                    text: clip((await page.innerText("body").catch(() => "")).replace(/\n{3,}/g, "\n\n"), 2000),
+                };
+            }
+            catch {
+                pageInfo = undefined;
+            }
+        }
+        return {
+            ok,
+            detail: ok ? "all steps completed" : "a step failed — see `steps`",
+            steps: results,
+            page: pageInfo,
+            screenshots,
+        };
+    }
+    finally {
+        const keepOpen = sessionName && !closeRequested && ok;
+        if (!keepOpen) {
+            if (sessionName)
+                sessions.delete(sessionName);
+            if (created || sessionName)
+                await session.browser.close().catch(() => undefined);
+        }
+    }
+}

package/dist/tools/credential.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The one rule this file exists to enforce: a raw credential must never
+ * cross back into the LLM's context, a tool-call log, or the RAO trace.
+ *
+ * The Sub Agent only ever holds a `credentialRef` — the NAME of an
+ * environment variable, not a value. Resolution happens here, at the last
+ * possible moment, inside the tool execution that actually needs the
+ * secret (the Playwright tool), and the resolved value never gets returned
+ * to the caller. If you're tempted to add a `getCredentialValue` export
+ * that hands the string back to a caller outside `tools/`, don't — that's
+ * the exact mistake this module is here to prevent.
+ */
+export declare class CredentialResolutionError extends Error {
+}
+export declare function resolveCredential(ref: string): string;
+/** For anything that might echo a string containing a resolved secret (logs, RAO trace, errors). */
+export declare function redact(text: string, ref?: string): string;

package/dist/tools/credential.js

@@ -0,0 +1,32 @@
+/**
+ * The one rule this file exists to enforce: a raw credential must never
+ * cross back into the LLM's context, a tool-call log, or the RAO trace.
+ *
+ * The Sub Agent only ever holds a `credentialRef` — the NAME of an
+ * environment variable, not a value. Resolution happens here, at the last
+ * possible moment, inside the tool execution that actually needs the
+ * secret (the Playwright tool), and the resolved value never gets returned
+ * to the caller. If you're tempted to add a `getCredentialValue` export
+ * that hands the string back to a caller outside `tools/`, don't — that's
+ * the exact mistake this module is here to prevent.
+ */
+export class CredentialResolutionError extends Error {
+}
+export function resolveCredential(ref) {
+    const value = process.env[ref];
+    if (!value) {
+        throw new CredentialResolutionError(`credential ref "${ref}" is not set in the environment. Set it before running, e.g. ` +
+            `\`${ref}=... xcoder -task "..."\`. Xcoder SDLC never accepts a raw secret as a CLI argument ` +
+            `or task input — only a reference to where it lives.`);
+    }
+    return value;
+}
+/** For anything that might echo a string containing a resolved secret (logs, RAO trace, errors). */
+export function redact(text, ref) {
+    if (!ref)
+        return text;
+    const value = process.env[ref];
+    if (!value)
+        return text;
+    return text.split(value).join(`«redacted:${ref}»`);
+}

package/dist/tools/dependency-graph.d.ts

@@ -0,0 +1,23 @@
+export interface DependencyGraphResultOk {
+    ok: true;
+    relPath: string;
+    imports: Array<{
+        specifier: string;
+        resolved: string | null;
+        isExternal: boolean;
+    }>;
+    importers: string[];
+    parseMethod: "regex" | "tokenizer" | "none";
+    note?: string;
+}
+export type DependencyGraphResult = DependencyGraphResultOk | {
+    ok: false;
+    code: "file_not_found" | "workspace_escape" | "unsupported";
+    error: string;
+};
+/**
+ * get_dependency_graph — imports + importers for one file, best-effort.
+ * Never throws: unknown extensions (or unparseable files) return typed
+ * `unsupported`, missing files `file_not_found`.
+ */
+export declare function getDependencyGraphTool(root: string, relPath: string): Promise<DependencyGraphResult>;