@nextclaw/x-harness 0.1.0 → 0.1.1

package/dist/browser-dom-editing.js

@@ -0,0 +1,386 @@
+import { attachImage } from "./readers-actions.js";
+export function createDOMEditing(dependencies) {
+    const { session, unique, locator, tab, observe } = dependencies;
+    async function dismissMenu(command) {
+        const { query, result } = session.current;
+        let loc, submittedEditor;
+        if (query.view !== "menu" ||
+            result.needsStateCheck ||
+            !result.items?.length)
+            throw new Error("关闭菜单需已有菜单证据");
+        const item = result.items[0];
+        session.current = null;
+        await (await unique(locator(item.role, item.label))).press("Escape");
+        return { completed: true };
+        return { completed: false, loc, submittedEditor };
+    }
+    async function openControl(command) {
+        const { query, result } = session.current;
+        let loc, submittedEditor;
+        if (!["navigation", "menu"].includes(query.view) || result.needsStateCheck)
+            throw new Error("导航控件须先唯一观察");
+        const matches = (result.controls ?? result.items ?? []).filter((c) => c.role === command.role &&
+            c.label === command.label &&
+            c.href === command.href &&
+            !c.disabled);
+        if (matches.length !== 1)
+            throw new Error("导航控件未唯一观察");
+        session.current = null;
+        await (await unique(command.role === "text"
+            ? tab.playwright.getByText(command.label, { exact: true })
+            : locator(command.role, command.label))).click();
+        if (command.href?.startsWith("/"))
+            await tab.playwright.waitForURL(`https://x.com${command.href}`, {
+                timeoutMs: 5000,
+            });
+        return { completed: true };
+        return { completed: false, loc, submittedEditor };
+    }
+    async function openOwnPostMenu(command) {
+        const { query, result } = session.current;
+        let loc, submittedEditor;
+        const post = result.posts?.[0];
+        if (query.view !== "posts" ||
+            result.needsStateCheck ||
+            result.posts?.length !== 1 ||
+            post.id !== command.postId ||
+            post.author?.toLowerCase() !== result.accountHandle?.toLowerCase() ||
+            post.primary?.match(/\/status\/(\d+)$/)?.[1] !== command.postId)
+            throw new Error("编辑需唯一本人原帖");
+        const more = post.buttons.filter((b) => /^(更多|More)$/.test(b.label) && !b.disabled);
+        if (more.length !== 1)
+            throw new Error("原帖更多按钮未唯一观察");
+        const article = locator("article").filter({
+            has: tab.playwright.locator(`a[href=${JSON.stringify(post.primary)}]`),
+            visible: true,
+        });
+        session.editBinding = {
+            postId: post.id,
+            accountHandle: result.accountHandle,
+            body: post.body,
+        };
+        session.current = null;
+        await (await unique((await unique(article)).getByRole("button", {
+            name: more[0].label,
+            exact: true,
+        }))).click();
+        return { completed: true };
+        return { completed: false, loc, submittedEditor };
+    }
+    async function submitEditedPost(command) {
+        const { query, result } = session.current;
+        let loc, submittedEditor;
+        if (query.view !== "composer" ||
+            result.needsStateCheck ||
+            result.alerts?.length ||
+            !session.editBinding ||
+            session.editBinding.postId !== command.postId ||
+            result.accountHandle !== session.editBinding.accountHandle ||
+            !command.evidenceRef ||
+            !command.approvedText?.trim() ||
+            result.editorText !== command.approvedText ||
+            result.editors?.length !== 1)
+            throw new Error("编辑提交缺本人原帖绑定或精确审稿证据");
+        const updates = result.buttons.filter((b) => /^(更新|Update)$/.test(b.label) && !b.disabled);
+        if (updates.length !== 1)
+            throw new Error("编辑更新按钮未唯一观察");
+        const update = await unique(locator("button", updates[0].label));
+        await command.beforeSubmit?.();
+        session.current = null;
+        session.editBinding = null;
+        if (command.activation === "keyboard")
+            await update.press("Enter");
+        else
+            await update.click();
+        await tab.playwright.waitForLoadState({
+            state: "networkidle",
+            timeoutMs: 8000,
+        });
+        return { completed: true };
+        return { completed: false, loc, submittedEditor };
+    }
+    async function expandPost(command) {
+        const { query, result } = session.current;
+        let loc, submittedEditor;
+        if (query.view !== "posts" ||
+            result.posts?.length !== 1 ||
+            result.posts[0].id !== command.postId)
+            throw new Error("展开需唯一原帖");
+        const primary = result.posts[0].primary;
+        const article = locator("article").filter({
+            has: tab.playwright.locator(`a[href=${JSON.stringify(primary)}]`),
+            visible: true,
+        });
+        const control = (await unique(article)).getByText(/^(显示更多|Show more)$/i);
+        session.current = null;
+        await (await unique(control)).click();
+        return { completed: true };
+        return { completed: false, loc, submittedEditor };
+    }
+    async function nextPosts(command) {
+        const { query, result } = session.current;
+        let loc, submittedEditor;
+        if (query.view !== "posts" || result.needsStateCheck)
+            throw new Error("翻页须先观察原列表");
+        const primary = result.posts?.at(-1)?.primary;
+        if (!primary)
+            throw new Error("翻页须有已观察原帖链接");
+        const anchor = await unique(tab.playwright
+            .locator(`a[href=${JSON.stringify(primary)}]`)
+            .filter({ visible: true }));
+        session.current = null;
+        await anchor.press("PageDown");
+        return { completed: true };
+        return { completed: false, loc, submittedEditor };
+    }
+    async function clearPreparedText(command) {
+        const { query, result } = session.current;
+        let loc, submittedEditor;
+        if (query.view !== "composer" ||
+            result.needsStateCheck ||
+            !command.evidenceRef ||
+            typeof command.text !== "string" ||
+            result.editorText?.replace(/\n{3,}/g, "\n\n") !==
+                command.text.replace(/\n{3,}/g, "\n\n") ||
+            result.editors?.length !== 1)
+            throw new Error("仅恢复本次已知稿件准备");
+        const editor = await unique(locator("textbox", result.editors[0].label));
+        await editor.press("Meta+A");
+        await editor.press("Backspace");
+        return { completed: true, value: observe({ view: "composer" }) };
+        return { completed: false, loc, submittedEditor };
+    }
+    async function closePreparedReply(command) {
+        const { query, result } = session.current;
+        let loc, submittedEditor;
+        if (query.view !== "composer" ||
+            result.needsStateCheck ||
+            result.editorText?.trim() !== "" ||
+            !command.evidenceRef)
+            throw new Error("仅关闭有准备失败证据的空回复");
+        await (await unique(locator("button", "关闭"))).click();
+        session.replyBinding = null;
+        return { completed: true, value: observe({ view: "posts", limit: 5 }) };
+        return { completed: false, loc, submittedEditor };
+    }
+    async function closePreparedMedia(command) {
+        const { query, result } = session.current;
+        let loc, submittedEditor;
+        if (query.view !== "media" ||
+            result.needsStateCheck ||
+            !command.evidenceRef)
+            throw new Error("媒体恢复须有准备失败证据");
+        const backs = result.controls.filter((b) => b.role === "button" && /^(返回|Back)$/i.test(b.label) && !b.disabled);
+        if (backs.length !== 1)
+            throw new Error("媒体返回入口不唯一");
+        await (await unique(locator("button", backs[0].label))).click();
+        await tab.playwright
+            .getByRole("textbox", { name: /^(帖子文本|Post text)$/i })
+            .waitFor({ state: "visible", timeoutMs: 5000 });
+        return { completed: true, value: observe({ view: "composer" }) };
+        return { completed: false, loc, submittedEditor };
+    }
+    async function removePreparedMedia(command) {
+        const { query, result } = session.current;
+        let loc, submittedEditor;
+        if (query.view !== "composer" ||
+            result.needsStateCheck ||
+            result.editorText?.trim() !== "" ||
+            !command.evidenceRef)
+            throw new Error("仅恢复有来源证据的空正文媒体准备");
+        const removes = result.buttons.filter((b) => /^(移除媒体|Remove media)$/i.test(b.label) && !b.disabled);
+        if (removes.length !== 1)
+            throw new Error("待恢复媒体不唯一");
+        await (await unique(locator("button", removes[0].label))).click();
+        return { completed: true, value: observe({ view: "composer" }) };
+        return { completed: false, loc, submittedEditor };
+    }
+    async function attachAssets(command) {
+        const { query, result } = session.current;
+        let loc, submittedEditor;
+        if (query.view !== "composer" ||
+            result.needsStateCheck ||
+            command.assets?.length !== 1)
+            throw new Error("仅上传已观察编辑器的一张带ALT图片");
+        const asset = command.assets[0];
+        if (!asset.alt?.trim())
+            throw new Error("图片须有完整ALT");
+        session.current = null;
+        await attachImage(tab, { path: asset.path });
+        await tab.playwright
+            .getByRole("button", {
+            name: /^(?:编辑|Edit)(?:图片|照片|媒体| image| photo| media)?(?: \d+)?$/i,
+        })
+            .waitFor({ state: "visible", timeoutMs: 5000 });
+        const composer = await observe({ view: "composer" });
+        const edits = composer.buttons.filter((b) => /^(?:编辑|Edit)(?:图片|照片|媒体| image| photo| media)?(?: \d+)?$/i.test(b.label) && !b.disabled);
+        if (edits.length !== 1)
+            throw new Error("图片编辑入口未唯一观察");
+        await (await unique(locator("button", edits[0].label))).click();
+        await tab.playwright
+            .getByRole("tab", {
+            name: /^(编辑图片描述|Edit image description)$/i,
+        })
+            .waitFor({ state: "visible", timeoutMs: 5000 });
+        let media = await observe({ view: "media" });
+        const tabControl = media.controls.find((c) => c.role === "tab" &&
+            /^(编辑图片描述|Edit image description)$/i.test(c.label));
+        if (!tabControl)
+            throw new Error("ALT页签未观察");
+        await (await unique(locator("tab", tabControl.label))).click();
+        media = await observe({ view: "media" });
+        if (media.needsStateCheck || media.fields.length !== 1)
+            throw new Error("ALT输入未唯一观察");
+        const field = media.fields[0];
+        const input = field.label
+            ? tab.playwright.getByLabel(field.label, { exact: true })
+            : field.placeholder
+                ? tab.playwright.getByPlaceholder(field.placeholder, {
+                    exact: true,
+                })
+                : locator("textbox");
+        await (await unique(input)).fill(asset.alt);
+        media = await observe({ view: "media" });
+        if (media.fields[0]?.value !== asset.alt)
+            throw new Error("ALT全文不匹配");
+        const save = media.controls.filter((c) => c.role === "button" && /^(保存|Save)$/i.test(c.label) && !c.disabled);
+        if (save.length !== 1)
+            throw new Error("ALT保存入口不唯一");
+        await (await unique(locator("button", save[0].label))).click();
+        const after = await observe({ view: "composer" });
+        if (after.needsStateCheck || !after.images?.length)
+            throw new Error("上传图片未回到编辑器");
+        return {
+            completed: true,
+            value: {
+                assets: [{ path: asset.path, alt: asset.alt }],
+                mediaEvidence: media,
+                composer: after,
+            },
+        };
+        return { completed: false, loc, submittedEditor };
+    }
+    async function follow(command) {
+        const { query, result } = session.current;
+        let loc, submittedEditor;
+        if (query.view !== "person" ||
+            query.handle !== command.handle ||
+            result.needsStateCheck)
+            throw new Error("人物身份未绑定");
+        const name = result.relationship === "follows-you"
+            ? `回关 @${command.handle}`
+            : `关注 @${command.handle}`;
+        loc = await unique(locator("button", name));
+        return { completed: false, loc, submittedEditor };
+    }
+    async function openReply(command) {
+        const { query, result } = session.current;
+        let loc, submittedEditor;
+        session.replyBinding = null;
+        if (query.targetId !== command.postId || result.posts?.length !== 1)
+            throw new Error("回复主帖未唯一绑定");
+        const names = result.posts[0].buttons.filter((b) => /回复|Reply/i.test(b.label));
+        if (names.length !== 1)
+            throw new Error("回复按钮未唯一观察");
+        const primary = result.posts[0].primary;
+        if (!primary || primary.match(/\/status\/(\d+)$/)?.[1] !== command.postId)
+            throw new Error("回复主帖永久链接未绑定");
+        const article = locator("article").filter({
+            has: tab.playwright.locator(`a[href=${JSON.stringify(primary)}]`),
+            visible: true,
+        });
+        loc = await unique((await unique(article)).getByRole("button", {
+            name: names[0].label,
+            exact: true,
+        }));
+        return { completed: false, loc, submittedEditor };
+    }
+    async function fillComposer(command) {
+        const { query, result } = session.current;
+        let loc, submittedEditor;
+        if (query.view !== "composer" || result.editors?.length !== 1)
+            throw new Error("编辑器未唯一观察");
+        loc = await unique(locator("textbox", result.editors[0].label));
+        session.current = null;
+        await loc.fill(command.text);
+        const submits = result.buttons.filter((b) => /^(回复|Reply|发帖|发布|Post|更新|Update)$/i.test(b.label));
+        if (submits.length !== 1)
+            throw new Error("编辑后提交入口不唯一");
+        await locator("button", submits[0].label)
+            .and(tab.playwright.locator(':not([disabled]):not([aria-disabled="true"])'))
+            .waitFor({ state: "visible", timeoutMs: 5000 });
+        return { completed: true };
+        return { completed: false, loc, submittedEditor };
+    }
+    async function submitPost(command) {
+        const { query, result } = session.current;
+        let loc, submittedEditor;
+        if (query.view !== "composer")
+            throw new Error("未观察编辑器");
+        const pattern = command.operation === "submitReply"
+            ? /^(回复|Reply)$/i
+            : /^(发帖|发布|Post)$/i;
+        const buttons = result.buttons?.filter((b) => pattern.test(b.label) && !b.disabled) ?? [];
+        if (buttons.length !== 1)
+            throw new Error("提交按钮未唯一观察");
+        loc = await unique(locator("button", buttons[0].label));
+        if (command.activation !== undefined &&
+            !["click", "keyboard"].includes(command.activation))
+            throw new Error("提交激活方式无效");
+        if (command.activation === "keyboard" && typeof loc.press !== "function")
+            throw new Error("缺语义按钮键盘提交能力");
+        if (command.operation === "submitReply") {
+            if (result.editors?.length !== 1 || !result.editorText?.trim())
+                throw new Error("回复提交缺唯一完整编辑器");
+            submittedEditor = locator("textbox", result.editors[0].label).filter({
+                hasText: new RegExp(
+                // Full text and actor are checked by platform.compose before this act.
+                // Use a short observed anchor for the retained-text wait: host locator
+                // bridges can reject a multi-kilobyte hasText regex on long posts.
+                result.editorText
+                    .trim()
+                    .split(/\r?\n/)[0]
+                    .slice(0, 64)
+                    .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")),
+            });
+            await unique(submittedEditor);
+        }
+        else {
+            if (result.editors?.length !== 1 || !result.editorText?.trim())
+                throw new Error("发帖提交缺唯一完整编辑器");
+            // Publication with media may stay pending after the click. Do not let
+            // receipt navigation interrupt it while the submitted text is retained.
+            submittedEditor = locator("textbox", result.editors[0].label).filter({
+                hasText: new RegExp(
+                // Full text and actor are checked by platform.compose before this act.
+                // Use a short observed anchor for the retained-text wait: host locator
+                // bridges can reject a multi-kilobyte hasText regex on long posts.
+                result.editorText
+                    .trim()
+                    .split(/\r?\n/)[0]
+                    .slice(0, 64)
+                    .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")),
+            });
+            await unique(submittedEditor);
+        }
+        return { completed: false, loc, submittedEditor };
+    }
+    return {
+        dismissMenu,
+        openControl,
+        openOwnPostMenu,
+        submitEditedPost,
+        expandPost,
+        nextPosts,
+        clearPreparedText,
+        closePreparedReply,
+        closePreparedMedia,
+        removePreparedMedia,
+        attachAssets,
+        follow,
+        openReply,
+        fillComposer,
+        submitPost,
+        submitReply: submitPost,
+    };
+}

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

@@ -0,0 +1,9 @@
+import type { DOMDependencies } from "./browser-dom-dependencies.js";
+export declare function createDOMNavigation(dependencies: Pick<DOMDependencies, "session" | "tab" | "observe">): {
+    searchSources: (command: any) => Promise<void>;
+    waitForFolder: (command: any) => Promise<void>;
+    waitForPosts: (command: any) => Promise<void>;
+    openObserved: (command: any) => Promise<void>;
+    refreshPerson: (command: any) => Promise<void>;
+    refreshPosts: (command: any) => Promise<void>;
+};

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>;