@nextclaw/x-harness 0.1.0 → 0.2.0

package/dist/browser-dom-navigation.js

@@ -0,0 +1,181 @@
+import { xURL } from "./platform-rules.js";
+export class DOMNavigation {
+    #session;
+    #tab;
+    #observe;
+    searchSources;
+    waitForFolder;
+    waitForPosts;
+    openObserved;
+    refreshPerson;
+    refreshPosts;
+    constructor(dependencies) {
+        const { session, tab, observe } = dependencies;
+        this.#session = session;
+        this.#tab = tab;
+        this.#observe = observe;
+        this.searchSources = this.handleSearchSources.bind(this);
+        this.waitForFolder = this.handleWaitForFolder.bind(this);
+        this.waitForPosts = this.handleWaitForPosts.bind(this);
+        this.openObserved = this.handleOpenObserved.bind(this);
+        this.refreshPerson = this.handleRefreshPerson.bind(this);
+        this.refreshPosts = this.handleRefreshPosts.bind(this);
+    }
+    async handleSearchSources(command) {
+        if (typeof command.query !== "string" ||
+            !command.query.trim() ||
+            command.query.length > 300)
+            throw new Error("需一条有效搜索词");
+        this.#session.current = null;
+        const destination = `https://x.com/search?q=${encodeURIComponent(command.query)}&src=typed_query&f=live`;
+        if (typeof this.#tab.url !== "function" ||
+            (await this.#tab.url()) !== destination)
+            await this.#tab.goto(destination);
+        return;
+    }
+    async handleWaitForFolder(command) {
+        await this.#tab.playwright
+            .getByText(command.folder, { exact: true })
+            .waitFor({ state: "visible", timeoutMs: 2000 });
+        return;
+    }
+    async handleWaitForPosts(command) {
+        await this.#tab.playwright
+            .getByRole("article")
+            .first()
+            .waitFor({ state: "visible", timeoutMs: 5000 });
+        return;
+    }
+    async handleOpenObserved(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 this.#tab.url === "function" &&
+            (await this.#tab.url()) === xURL(command.url).href)
+            return;
+        const originalPage = this.#session.current?.result?.page;
+        this.#session.replyBinding = null;
+        this.#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 this.#tab.playwright?.locator === "function") {
+            link = this.#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 this.#tab.goto(command.url);
+        try {
+            await this.#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 this.#observe({
+                view: command.view,
+                handle: command.handle,
+                limit: 1,
+            });
+            if (check.page !== originalPage ||
+                check.needsStateCheck ||
+                check.alerts?.length)
+                throw error;
+            await this.#tab.goto(command.url);
+            await this.#tab.playwright.waitForURL(command.url, { timeoutMs: 5000 });
+        }
+        if (command.view === "person") {
+            // Profile readiness belongs to profile content; self profiles have no Follow button.
+            await this.#tab.playwright
+                .locator('[data-testid="UserName"]')
+                .waitFor({ state: "visible", timeoutMs: 5000 });
+        }
+        else if (command.view === "composer") {
+            await this.#tab.playwright
+                .getByRole("textbox", { name: /^(帖子文本|Post text)$/i })
+                .waitFor({ state: "visible", timeoutMs: 5000 });
+        }
+        else if (command.view === "posts") {
+            await this.#tab.playwright
+                .getByRole("article")
+                .first()
+                .waitFor({ state: "visible", timeoutMs: 5000 });
+        }
+        return;
+    }
+    async handleRefreshPerson(command) {
+        const at = xURL(await this.#tab.url());
+        this.#session.replyBinding = null;
+        if (at.href !== xURL(command.url).href ||
+            at.pathname.toLowerCase() !== `/${command.handle}`.toLowerCase())
+            throw new Error("持久核验页面不匹配");
+        this.#session.current = null;
+        // Let the actual UI request settle before reloading; optimistic Following is not durable proof.
+        let idleTimedOut = false;
+        try {
+            await this.#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 this.#tab.reload();
+        await this.#tab.playwright
+            .getByRole("button", {
+            name: new RegExp(`^(?:正在关注|取消关注|关注|回关) @${command.handle}$`, "i"),
+        })
+            .waitFor({ state: "visible", timeoutMs: 5000 });
+        if (idleTimedOut)
+            this.#session.refreshNotice =
+                "networkidle超时，已沿真实reload与目标关系控件恢复核验";
+        return;
+    }
+    async handleRefreshPosts(command) {
+        this.#session.replyBinding = null;
+        if (!command.evidenceRef ||
+            xURL(await this.#tab.url()).href !== xURL(command.url).href)
+            throw new Error("公开核验页面不匹配");
+        this.#session.current = null;
+        await this.#tab.reload();
+        // Native observation settles the real loading transition when the tab exposes it.
+        if (typeof this.#tab.getAXState === "function")
+            await this.#tab.getAXState({ emit: false });
+        await this.#tab.playwright
+            .getByRole("article")
+            .first()
+            .waitFor({ state: "visible", timeoutMs: 5000 });
+        return;
+    }
+}
+export function createDOMNavigation(...args) {
+    return new DOMNavigation(...args);
+}

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,7 @@
+import type { DOMDependencies } from "./browser-dom-dependencies.js";
+export declare class DOMSubmission {
+    #private;
+    constructor(dependencies: Pick<DOMDependencies, "submitAX" | "session" | "tab" | "observe" | "unique" | "locator">);
+    finishDOMAction(command: any, prepared: any, query: any, result: any): Promise<void>;
+}
+export declare function createDOMSubmission(...args: ConstructorParameters<typeof DOMSubmission>): (command: any, prepared: any, query: any, result: any) => Promise<void>;

package/dist/browser-dom-submission.js

@@ -0,0 +1,101 @@
+import { xURL } from "./platform-rules.js";
+import { valueOf } from "./browser-common.js";
+export class DOMSubmission {
+    #submitAX;
+    #session;
+    #tab;
+    #observe;
+    #unique;
+    #locator;
+    constructor(dependencies) {
+        this.finishDOMAction = this.finishDOMAction.bind(this);
+        const { submitAX, session, tab, observe, unique, locator } = dependencies;
+        this.#submitAX = submitAX;
+        this.#session = session;
+        this.#tab = tab;
+        this.#observe = observe;
+        this.#unique = unique;
+        this.#locator = locator;
+    }
+    async 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 (this.#submitAX &&
+            ["submitPost", "submitReply"].includes(command.operation)) {
+            const native = await this.#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?.();
+        this.#session.current = null;
+        if (nativeSubmitIndex !== undefined)
+            await this.#submitAX.act({
+                index: nativeSubmitIndex,
+                operation: "click",
+                read: { mode: "composer" },
+            });
+        else if (command.activation === "keyboard")
+            await loc.press("Enter");
+        else
+            await loc.click();
+        if (binding) {
+            this.#session.replyBinding = binding;
+            await this.#tab.playwright
+                .getByRole("textbox", { name: /^(帖子文本|Post text)$/i })
+                .waitFor({ state: "visible", timeoutMs: 5000 });
+            if (xURL(await this.#tab.url()).pathname === "/compose/post")
+                await this.#tab.playwright
+                    .getByText(`回复 @${binding.author}`, { exact: true })
+                    .waitFor({ state: "visible", timeoutMs: 5000 });
+            const composer = await this.#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 this.#unique(this.#locator("dialog").filter({ visible: true }));
+                const more = await this.#unique(dialog.getByRole("button", { name: /^(显示更多|Show more)$/i }));
+                this.#session.current = null;
+                await more.click();
+                await this.#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 this.#tab.playwright.waitForLoadState({
+                state: "networkidle",
+                timeoutMs: 8000,
+            });
+    }
+}
+export function createDOMSubmission(...args) {
+    return new DOMSubmission(...args).finishDOMAction;
+}

package/dist/browser-dom.d.ts

@@ -1,2 +1,14 @@
-export declare function createDOMXBrowser(tab: any, { readDOM, nativeSubmit }?: any): any;
-export declare function readXNetworkDiagnostics(tab: any, { afterSequence, startObserving }?: any): Promise<any>;
+export { readXNetworkDiagnostics } from "./browser-dom-network.js";
+export declare class DOMXBrowser {
+    #private;
+    capabilities: (operation: any) => any;
+    observe: (query: any) => Promise<any>;
+    constructor(tab: any, { readDOM, nativeSubmit }?: any);
+    private handleObserve;
+    private locator;
+    private unique;
+    collectCreator({ handle, ...options }: import("./types.js").CreatorOptions): Promise<import("./boundary.js").BoundaryRecord>;
+    screenshot(): any;
+    act(command: any): Promise<any>;
+}
+export declare function createDOMXBrowser(...args: ConstructorParameters<typeof DOMXBrowser>): any;