@nextclaw/x-harness 0.0.0-stage → 0.1.1

package/dist/browser-dom-navigation.js

@@ -0,0 +1,165 @@
+import { xURL } from "./platform-rules.js";
+export function createDOMNavigation(dependencies) {
+    const { session, tab, observe } = dependencies;
+    async function searchSources(command) {
+        if (typeof command.query !== "string" ||
+            !command.query.trim() ||
+            command.query.length > 300)
+            throw new Error("需一条有效搜索词");
+        session.current = null;
+        const destination = `https://x.com/search?q=${encodeURIComponent(command.query)}&src=typed_query&f=live`;
+        if (typeof tab.url !== "function" || (await tab.url()) !== destination)
+            await tab.goto(destination);
+        return;
+    }
+    async function waitForFolder(command) {
+        await tab.playwright
+            .getByText(command.folder, { exact: true })
+            .waitFor({ state: "visible", timeoutMs: 2000 });
+        return;
+    }
+    async function waitForPosts(command) {
+        await tab.playwright
+            .getByRole("article")
+            .first()
+            .waitFor({ state: "visible", timeoutMs: 5000 });
+        return;
+    }
+    async function openObserved(command) {
+        xURL(command.url);
+        if (!command.evidenceRef)
+            throw new Error("导航缺已观察证据");
+        // A direct adapter caller must also preserve a page already at the target.
+        // Explicit recovery uses forceNavigation; durable verification uses refreshPerson.
+        if (!command.forceNavigation &&
+            typeof tab.url === "function" &&
+            (await tab.url()) === xURL(command.url).href)
+            return;
+        const originalPage = session.current?.result?.page;
+        session.replyBinding = null;
+        session.current = null;
+        // Keep the loaded X client when the exact observed permalink is already visible.
+        // An ambiguous/missing link retains the existing navigation path, never an arbitrary click.
+        const path = xURL(command.url).pathname + xURL(command.url).search;
+        let link;
+        if (!command.forceNavigation &&
+            typeof tab.playwright?.locator === "function") {
+            link = tab.playwright
+                .locator(`a[href=${JSON.stringify(path)}]`)
+                .filter({ visible: true });
+            if (command.view === "person" &&
+                /^[A-Za-z0-9_]{1,15}$/.test(command.handle ?? "") &&
+                (await link.count()) > 1) {
+                // Avatar and name often share a profile href. Use the exact observed
+                // handle token to select the name link, never the arbitrary first match.
+                const named = link.filter({
+                    hasText: new RegExp(`@${command.handle}(?![A-Za-z0-9_])`, "i"),
+                });
+                if ((await named.count()) === 1)
+                    link = named;
+            }
+        }
+        const clickedLink = link && (await link.count()) === 1;
+        if (clickedLink)
+            await link.click();
+        else
+            await tab.goto(command.url);
+        try {
+            await tab.playwright.waitForURL(command.url, { timeoutMs: 5000 });
+        }
+        catch (error) {
+            // One inert client-link timeout may use the same observed URL directly.
+            // A changed route, warning, unknown UI or interrupted connection never falls back.
+            if (!clickedLink ||
+                !originalPage ||
+                !/Timed out waiting for URL/.test(error instanceof Error ? error.message : ""))
+                throw error;
+            const check = await observe({
+                view: command.view,
+                handle: command.handle,
+                limit: 1,
+            });
+            if (check.page !== originalPage ||
+                check.needsStateCheck ||
+                check.alerts?.length)
+                throw error;
+            await tab.goto(command.url);
+            await tab.playwright.waitForURL(command.url, { timeoutMs: 5000 });
+        }
+        if (command.view === "person") {
+            // Profile readiness belongs to profile content; self profiles have no Follow button.
+            await tab.playwright
+                .locator('[data-testid="UserName"]')
+                .waitFor({ state: "visible", timeoutMs: 5000 });
+        }
+        else if (command.view === "composer") {
+            await tab.playwright
+                .getByRole("textbox", { name: /^(帖子文本|Post text)$/i })
+                .waitFor({ state: "visible", timeoutMs: 5000 });
+        }
+        else if (command.view === "posts") {
+            await tab.playwright
+                .getByRole("article")
+                .first()
+                .waitFor({ state: "visible", timeoutMs: 5000 });
+        }
+        return;
+    }
+    async function refreshPerson(command) {
+        const at = xURL(await tab.url());
+        session.replyBinding = null;
+        if (at.href !== xURL(command.url).href ||
+            at.pathname.toLowerCase() !== `/${command.handle}`.toLowerCase())
+            throw new Error("持久核验页面不匹配");
+        session.current = null;
+        // Let the actual UI request settle before reloading; optimistic Following is not durable proof.
+        let idleTimedOut = false;
+        try {
+            await tab.playwright.waitForLoadState({
+                state: "networkidle",
+                timeoutMs: 8000,
+            });
+        }
+        catch (error) {
+            if (!/Timed out waiting for networkidle/i.test(error.message ?? ""))
+                throw error;
+            // Long-lived X requests can prevent idle; the following reload still
+            // must expose the target relationship before any fresh observation.
+            idleTimedOut = true;
+        }
+        await tab.reload();
+        await tab.playwright
+            .getByRole("button", {
+            name: new RegExp(`^(?:正在关注|取消关注|关注|回关) @${command.handle}$`, "i"),
+        })
+            .waitFor({ state: "visible", timeoutMs: 5000 });
+        if (idleTimedOut)
+            session.refreshNotice =
+                "networkidle超时，已沿真实reload与目标关系控件恢复核验";
+        return;
+    }
+    async function refreshPosts(command) {
+        session.replyBinding = null;
+        if (!command.evidenceRef ||
+            xURL(await tab.url()).href !== xURL(command.url).href)
+            throw new Error("公开核验页面不匹配");
+        session.current = null;
+        await tab.reload();
+        // Native observation settles the real loading transition when the tab exposes it.
+        if (typeof tab.getAXState === "function")
+            await tab.getAXState({ emit: false });
+        await tab.playwright
+            .getByRole("article")
+            .first()
+            .waitFor({ state: "visible", timeoutMs: 5000 });
+        return;
+    }
+    return {
+        searchSources,
+        waitForFolder,
+        waitForPosts,
+        openObserved,
+        refreshPerson,
+        refreshPosts,
+    };
+}

package/dist/browser-dom-network.d.ts

@@ -0,0 +1 @@
+export declare function readXNetworkDiagnostics(tab: any, { afterSequence, startObserving }?: any): Promise<any>;

package/dist/browser-dom-network.js

@@ -0,0 +1,128 @@
+// Read-only transport diagnostics through the same real Chrome tab capability.
+// Never return credential headers, cookies or bodies; only numeric rate metadata is allowed.
+export async function readXNetworkDiagnostics(tab, { afterSequence = 0, startObserving = false } = {}) {
+    if (typeof tab?.capabilities?.get !== "function")
+        throw new Error("缺真实Chrome诊断能力");
+    const cdp = await tab.capabilities.get("cdp");
+    if (typeof cdp?.readEvents !== "function")
+        throw new Error("缺只读网络事件能力");
+    if (startObserving)
+        await cdp.send("Network.enable");
+    const result = await cdp.readEvents({
+        afterSequence,
+        limit: 1000,
+        methods: [
+            "Network.requestWillBeSent",
+            "Network.responseReceived",
+            "Network.loadingFailed",
+        ],
+    });
+    const traffic = new Map();
+    const times = [];
+    for (const event of result.events) {
+        const p = event.params ?? {};
+        let u;
+        try {
+            u = new URL(p.response?.url ?? p.request?.url);
+        }
+        catch {
+            continue;
+        }
+        if (!((u.hostname === "x.com" && u.pathname.startsWith("/i/api/")) ||
+            u.hostname === "api.x.com"))
+            continue;
+        const location = u.origin + u.pathname;
+        const row = traffic.get(location) ?? {
+            location,
+            requests: 0,
+            responses: 0,
+            statuses: {},
+        };
+        if (event.method === "Network.requestWillBeSent")
+            row.requests++;
+        if (event.method === "Network.responseReceived") {
+            row.responses++;
+            const status = p.response?.status;
+            if (Number.isInteger(status))
+                row.statuses[status] = (row.statuses[status] ?? 0) + 1;
+        }
+        if (Number.isFinite(p.timestamp))
+            times.push(p.timestamp);
+        traffic.set(location, row);
+    }
+    const rates = (headers = {}) => {
+        const allowed = {};
+        for (const [key, value] of Object.entries(headers)) {
+            const name = key.toLowerCase();
+            if (![
+                "x-rate-limit-limit",
+                "x-rate-limit-remaining",
+                "x-rate-limit-reset",
+                "retry-after",
+            ].includes(name))
+                continue;
+            if (!/^\d{1,12}$/.test(String(value).trim()))
+                continue;
+            allowed[name] = Number(value);
+        }
+        const out = {};
+        if (allowed["x-rate-limit-limit"] !== undefined)
+            out.limit = allowed["x-rate-limit-limit"];
+        if (allowed["x-rate-limit-remaining"] !== undefined)
+            out.remaining = allowed["x-rate-limit-remaining"];
+        if (allowed["x-rate-limit-reset"] !== undefined) {
+            const date = new Date(allowed["x-rate-limit-reset"] * 1000);
+            if (Number.isFinite(date.getTime()))
+                out.resetAt = date.toISOString();
+        }
+        if (allowed["retry-after"] !== undefined)
+            out.retryAfterSeconds = allowed["retry-after"];
+        return Object.keys(out).length ? out : undefined;
+    };
+    return {
+        cursor: result.cursor,
+        hasMore: result.hasMore,
+        truncated: result.truncated,
+        traffic: {
+            complete: !result.truncated && !result.hasMore,
+            requests: [...traffic.values()].reduce((n, r) => n + r.requests, 0),
+            responses: [...traffic.values()].reduce((n, r) => n + r.responses, 0),
+            durationSeconds: times.length > 1 ? Math.max(...times) - Math.min(...times) : null,
+            endpointCount: traffic.size,
+            endpoints: [...traffic.values()]
+                .sort((a, b) => b.requests - a.requests)
+                .slice(0, 10),
+        },
+        events: result.events
+            .map((e) => {
+            const p = e.params ?? {};
+            const response = p.response ?? {};
+            let location;
+            try {
+                const u = new URL(response.url ?? p.request?.url);
+                location = ["http:", "https:"].includes(u.protocol)
+                    ? u.origin + u.pathname
+                    : null;
+            }
+            catch {
+                location = null;
+            }
+            return {
+                method: e.method,
+                requestId: p.requestId,
+                location,
+                requestMethod: p.request?.method,
+                status: response.status,
+                errorText: p.errorText,
+                canceled: p.canceled,
+                timestamp: Number.isFinite(p.timestamp) ? p.timestamp : undefined,
+                rateLimit: rates(response.headers),
+            };
+        })
+            .filter((e) => e.method === "Network.loadingFailed" ||
+            (e.location &&
+                (e.status >= 400 ||
+                    e.requestMethod === "POST" ||
+                    /\/(EditTweet|CreateTweet)$/.test(e.location)))),
+    };
+}

package/dist/browser-dom-submission.d.ts

@@ -0,0 +1,2 @@
+import type { DOMDependencies } from "./browser-dom-dependencies.js";
+export declare function createDOMSubmission(dependencies: Pick<DOMDependencies, "submitAX" | "session" | "tab" | "observe" | "unique" | "locator">): (command: any, prepared: any, query: any, result: any) => Promise<void>;

package/dist/browser-dom-submission.js

@@ -0,0 +1,82 @@
+import { xURL } from "./platform-rules.js";
+import { valueOf } from "./browser-common.js";
+export function createDOMSubmission(dependencies) {
+    const { submitAX, session, tab, observe, unique, locator } = dependencies;
+    return async function finishDOMAction(command, prepared, query, result) {
+        const { loc, submittedEditor } = prepared;
+        const binding = command.operation === "openReply"
+            ? {
+                page: result.page,
+                postId: command.postId,
+                body: result.posts[0].body,
+                author: result.posts[0].author,
+            }
+            : null;
+        let nativeSubmitIndex;
+        if (submitAX && ["submitPost", "submitReply"].includes(command.operation)) {
+            const native = await submitAX.observe({ mode: "composer" });
+            const editors = native.evidence?.filter((e) => /^(?:文本输入区(?:域)?|文本区域|文本栏) /.test(e.label)) ?? [];
+            const buttons = native.evidence?.filter((e) => new RegExp(command.operation === "submitReply"
+                ? "^按钮 (回复|Reply)(?:,|$)"
+                : "^按钮 (发帖|发布|Post)(?:,|$)", "i").test(e.label)) ?? [];
+            if (native.needsStateCheck ||
+                native.alerts?.length ||
+                xURL(native.page).href !== xURL(result.page).href ||
+                editors.length !== 1 ||
+                valueOf(editors[0].label)?.trim() !== result.editorText.trim() ||
+                buttons.length !== 1)
+                throw new Error("原生提交缺同页、全文及唯一按钮证据");
+            nativeSubmitIndex = buttons[0].index;
+        }
+        if (["submitPost", "submitReply"].includes(command.operation))
+            await command.beforeSubmit?.();
+        session.current = null;
+        if (nativeSubmitIndex !== undefined)
+            await submitAX.act({
+                index: nativeSubmitIndex,
+                operation: "click",
+                read: { mode: "composer" },
+            });
+        else if (command.activation === "keyboard")
+            await loc.press("Enter");
+        else
+            await loc.click();
+        if (binding) {
+            session.replyBinding = binding;
+            await tab.playwright
+                .getByRole("textbox", { name: /^(帖子文本|Post text)$/i })
+                .waitFor({ state: "visible", timeoutMs: 5000 });
+            if (xURL(await tab.url()).pathname === "/compose/post")
+                await tab.playwright
+                    .getByText(`回复 @${binding.author}`, { exact: true })
+                    .waitFor({ state: "visible", timeoutMs: 5000 });
+            const composer = await observe({ view: "composer" });
+            const quote = composer.replyQuotes?.length === 1 ? composer.replyQuotes[0] : null;
+            if (!composer.replyToId &&
+                !composer.needsStateCheck &&
+                !composer.alerts?.length &&
+                composer.editorText?.trim() === "" &&
+                composer.replyContexts?.length === 1 &&
+                composer.replyContexts[0].includes(`回复 @${binding.author}`) &&
+                /显示更多|Show more/.test(composer.replyContexts[0]) &&
+                quote?.length >= 30 &&
+                binding.body?.startsWith(quote)) {
+                // Expand the observed quote; the unchanged full-context binding gate must still pass.
+                const dialog = await unique(locator("dialog").filter({ visible: true }));
+                const more = await unique(dialog.getByRole("button", { name: /^(显示更多|Show more)$/i }));
+                session.current = null;
+                await more.click();
+                await observe({ view: "composer" });
+            }
+        }
+        // Inline replies keep the editor mounted. Wait for this submitted text to clear before
+        // receipt navigation/reload can interrupt the actual submission request.
+        if (submittedEditor)
+            await submittedEditor.waitFor({ state: "hidden", timeoutMs: 10000 });
+        if (["submitPost", "submitReply"].includes(command.operation))
+            await tab.playwright.waitForLoadState({
+                state: "networkidle",
+                timeoutMs: 8000,
+            });
+    };
+}

package/dist/browser-dom.d.ts

@@ -0,0 +1,2 @@
+export { readXNetworkDiagnostics } from "./browser-dom-network.js";
+export declare function createDOMXBrowser(tab: any, { readDOM, nativeSubmit }?: any): any;

package/dist/browser-dom.js

@@ -0,0 +1,103 @@
+import { createAXHarness } from "./readers-ax-host.js";
+import { readXObservation } from "./observation.js";
+import { collectCreatorDOM } from "./creator.js";
+import { serialized } from "./browser-common.js";
+import { createDOMCapabilities } from "./browser-dom-capabilities.js";
+import { createDOMNavigation } from "./browser-dom-navigation.js";
+import { createDOMEditing } from "./browser-dom-editing.js";
+import { createDOMSubmission } from "./browser-dom-submission.js";
+export { readXNetworkDiagnostics } from "./browser-dom-network.js";
+export function createDOMXBrowser(tab, { readDOM = readXObservation, nativeSubmit = false } = {}) {
+    const session = {};
+    const submitAX = nativeSubmit
+        ? createAXHarness({
+            getAXState: (options) => tab.getAXState(options),
+            click: (index) => tab.click(index),
+        })
+        : null;
+    async function observe(query) {
+        session.current = null;
+        const evaluate = tab?.playwright?.evaluate?.bind(tab.playwright);
+        if (!evaluate)
+            throw new Error("缺playwright.evaluate能力");
+        const result = await evaluate(readDOM, {
+            ...query,
+            limit: query.limit ?? 1,
+        });
+        const raw = result;
+        // This observed disclosure confirms AI provenance; preserve it without treating it as a rate/login failure.
+        result.notices = (result.alerts ?? []).filter((text) => text.trim() === "检测到 AI 生成内容");
+        if (session.refreshNotice) {
+            result.notices.push(session.refreshNotice);
+            session.refreshNotice = null;
+        }
+        result.alerts = (result.alerts ?? []).filter((text) => text.trim() !== "检测到 AI 生成内容");
+        if (query.view === "composer") {
+            result.editorText =
+                raw.editors?.length === 1 ? raw.editors[0].text : null;
+            if (result.inlineComposer &&
+                raw.editors?.length === 1 &&
+                session.replyBinding?.page === result.page &&
+                result.page.match(/\/status\/(\d+)$/)?.[1] ===
+                    session.replyBinding.postId)
+                result.replyToId = session.replyBinding.postId;
+            if (!result.inlineComposer &&
+                raw.editors?.length === 1 &&
+                session.replyBinding?.body &&
+                session.replyBinding?.author &&
+                result.replyContexts?.length === 1 &&
+                (result.replyContexts[0].includes(session.replyBinding.body) ||
+                    (result.replyQuotes?.length === 1 &&
+                        result.replyQuotes[0].length >= 80 &&
+                        session.replyBinding.body.startsWith(result.replyQuotes[0]))) &&
+                result.replyContexts[0].includes(`回复 @${session.replyBinding.author}`))
+                result.replyToId = session.replyBinding.postId;
+        }
+        session.current = { query, result };
+        return result;
+    }
+    const locator = (role, label = undefined) => tab.playwright.getByRole(role, label ? { name: label, exact: true } : {});
+    const unique = async (loc) => {
+        if ((await loc.count()) !== 1)
+            throw new Error("DOM语义控件不唯一");
+        return loc;
+    };
+    const navigation = createDOMNavigation({ session, tab, observe });
+    const editing = createDOMEditing({ session, unique, locator, tab, observe });
+    const finishDOMAction = createDOMSubmission({
+        submitAX,
+        session,
+        tab,
+        observe,
+        unique,
+        locator,
+    });
+    return serialized({
+        ...createDOMCapabilities({ tab, nativeSubmit }),
+        observe,
+        async collectCreator({ handle, ...options }) {
+            session.current = null;
+            return collectCreatorDOM(tab, handle, options);
+        },
+        screenshot: () => {
+            session.current = null;
+            return tab.screenshot();
+        },
+        async act(command) {
+            if (Object.hasOwn(navigation, command.operation))
+                return navigation[command.operation](command);
+            if (!session.current)
+                throw new Error("DOM语义操作必须先observe");
+            const { query, result } = session.current;
+            const handler = Object.hasOwn(editing, command.operation)
+                ? editing[command.operation]
+                : undefined;
+            if (!handler)
+                throw new Error("未封装的DOM动作");
+            const prepared = await handler(command);
+            if (prepared.completed)
+                return prepared.value;
+            return finishDOMAction(command, prepared, query, result);
+        },
+    });
+}

package/dist/browser-native.d.ts

@@ -0,0 +1 @@
+export declare function createNativeXBrowser(app: any): any;