@nextclaw/x-harness 0.1.0 → 0.2.0

package/dist/readers-actions.d.ts

@@ -0,0 +1,2 @@
+export declare function attachImage(tab: any, { path }?: any): Promise<any>;
+export declare function openReply(tab: any, { postId }?: any): Promise<any>;

package/dist/readers-actions.js

@@ -0,0 +1,66 @@
+import { readComposer } from "./readers-composer.js";
+import { readPosts } from "./readers-posts.js";
+// Upload only through the observed image button and browser file chooser.
+export async function attachImage(tab, { path } = {}) {
+    if (!/^\/.*\.(?:png|jpe?g|webp)$/i.test(path ?? ""))
+        throw new Error("需要绝对图片路径");
+    if (typeof tab?.playwright?.evaluate !== "function" ||
+        typeof tab?.playwright?.getByRole !== "function" ||
+        typeof tab?.playwright?.waitForEvent !== "function")
+        throw new Error("harness能力不足：DOM图片选择器");
+    const before = await tab.playwright.evaluate(readComposer);
+    if (before.needsStateCheck || before.alerts?.length)
+        throw new Error("图片上传前编辑器未确认");
+    const buttons = before.buttons.filter((b) => /^(添加照片或视频|Add photos or video)$/i.test(b.label) && !b.disabled);
+    if (buttons.length !== 1)
+        throw new Error("图片按钮未唯一观察");
+    const button = tab.playwright.getByRole("button", {
+        name: buttons[0].label,
+        exact: true,
+    });
+    if ((await button.count()) !== 1 || typeof button.click !== "function")
+        throw new Error("图片按钮未唯一定位");
+    const chooserPromise = tab.playwright.waitForEvent("filechooser", {
+        timeoutMs: 10000,
+    });
+    await button.click();
+    const chooser = await chooserPromise;
+    if (typeof chooser?.setFiles !== "function")
+        throw new Error("harness能力不足：setFiles");
+    await chooser.setFiles([path]);
+    return tab.playwright.evaluate(readComposer);
+}
+export async function openReply(tab, { postId } = {}) {
+    if (!/^\d+$/.test(postId ?? ""))
+        throw new Error("需要已观察公开ID");
+    if (typeof tab?.playwright?.evaluate !== "function" ||
+        typeof tab?.playwright?.locator !== "function")
+        throw new Error("harness能力不足：精准回复范围");
+    const state = await tab.playwright.evaluate(readPosts, {
+        targetId: postId,
+        limit: 1,
+    });
+    const post = state.posts[0];
+    if (state.needsStateCheck ||
+        state.alerts.length ||
+        state.posts.length !== 1 ||
+        post.missing.length ||
+        post.needsExpansion)
+        throw new Error("回复根帖证据未完整");
+    const buttons = post.buttons.filter((b) => /回复|Reply/i.test(b.label) && !b.disabled);
+    if (buttons.length !== 1)
+        throw new Error("回复按钮未唯一观察");
+    const article = tab.playwright
+        .locator("article")
+        .filter({ has: tab.playwright.locator(`a[href="${post.primary}"]`) });
+    if ((await article.count()) !== 1)
+        throw new Error("回复文章范围不唯一");
+    const button = article.getByRole("button", {
+        name: buttons[0].label,
+        exact: true,
+    });
+    if ((await button.count()) !== 1)
+        throw new Error("回复控件不唯一");
+    await button.click();
+    return tab.playwright.evaluate(readComposer);
+}

package/dist/readers-ax-host.d.ts

@@ -0,0 +1,12 @@
+export declare function createAXTabHarness(tab: any): any;
+export declare class AXHarness {
+    #private;
+    constructor(app: any);
+    private requireMethods;
+    private indexes;
+    private handleObserve;
+    observe(options?: any): Promise<any>;
+    act({ index, operation, value, read, }?: any): Promise<any>;
+    screenshot(): Promise<any>;
+}
+export declare function createAXHarness(...args: ConstructorParameters<typeof AXHarness>): any;

package/dist/readers-ax-host.js

@@ -0,0 +1,134 @@
+import { readAX } from "./readers-ax-parser.js";
+// Native operations share one observation boundary. No raw AX leaves this session.
+// Browser Tab input takes (index, value), while native App input takes (value).
+export function createAXTabHarness(tab) {
+    return createAXHarness({
+        getAXState: (options) => tab.getAXState(options),
+        click: (index) => tab.click(index),
+        pressKey: (key) => tab.pressKey(null, key),
+        paste: (value) => tab.paste(null, value),
+        scroll: (...args) => tab.scroll(...args),
+        getScreenshot: (options) => tab.getScreenshot(options),
+    });
+}
+export class AXHarness {
+    #app;
+    #controls;
+    #readable;
+    #busy;
+    constructor(app) {
+        this.screenshot = this.screenshot.bind(this);
+        this.act = this.act.bind(this);
+        this.observe = this.observe.bind(this);
+        this.#app = app;
+        this.#controls = new Map();
+        this.#readable = false;
+        this.#busy = false;
+    }
+    requireMethods(methods) {
+        const missing = methods.filter((name) => typeof this.#app?.[name] !== "function");
+        if (missing.length) {
+            this.#controls.clear();
+            this.#readable = false;
+            throw new Error(`harness能力不足：${missing.join("/")}；先补原入口并验证，未执行操作`);
+        }
+    }
+    indexes(value) {
+        if (!value || typeof value !== "object")
+            return;
+        if (Number.isInteger(value.index) && typeof value.label === "string")
+            this.#controls.set(value.index, value.label);
+        for (const child of Object.values(value))
+            this.indexes(child);
+    }
+    async handleObserve(options = {}) {
+        this.#controls.clear();
+        this.#readable = false;
+        readAX("", options);
+        this.requireMethods(["getAXState"]);
+        const result = readAX(await this.#app.getAXState({ emit: false, disableDiffing: true }), options);
+        this.indexes(result);
+        this.#readable = true;
+        return result;
+    }
+    async observe(options = {}) {
+        if (this.#busy)
+            throw new Error("AX操作进行中，禁止并发读取");
+        this.#busy = true;
+        try {
+            return await this.handleObserve(options);
+        }
+        finally {
+            this.#busy = false;
+        }
+    }
+    async act({ index, operation = "click", value, read = {}, } = {}) {
+        if (this.#busy)
+            throw new Error("AX操作进行中，禁止并发写入");
+        if (!this.#readable || !this.#controls.has(index))
+            throw new Error("必须先observe；index须来自最新定向证据");
+        if (!["click", "fill", "paste", "pressKey", "scroll", "secondary"].includes(operation))
+            throw new Error("未封装的AX操作，先补能力并验证");
+        // Validate before any side effect; a malformed follow-up read must never submit.
+        readAX("", read);
+        if (["fill", "paste", "pressKey", "secondary"].includes(operation) &&
+            typeof value !== "string")
+            throw new Error("AX操作value须为字符串");
+        if (["fill", "paste", "pressKey"].includes(operation) &&
+            !/^(?:文本输入区(?:域)?|文本区域|文本栏|组合框) /.test(this.#controls.get(index)))
+            throw new Error("键盘操作须定位最新证据中的编辑控件");
+        if (operation === "secondary" &&
+            !this.#controls.get(index).includes(`Secondary Actions: ${value}`))
+            throw new Error("未观察到该辅助动作");
+        if (operation === "scroll" &&
+            !["up", "down", "left", "right"].includes(value))
+            throw new Error("无效滚动方向");
+        const methods = operation === "fill"
+            ? ["click", "pressKey", "paste"]
+            : ["paste", "pressKey"].includes(operation)
+                ? ["click", operation]
+                : [operation === "secondary" ? "performSecondaryAction" : operation];
+        this.requireMethods([...methods, "getAXState"]);
+        this.#busy = true;
+        this.#controls.clear();
+        this.#readable = false;
+        try {
+            if (operation === "click")
+                await this.#app.click(index);
+            else if (["fill", "paste", "pressKey"].includes(operation)) {
+                await this.#app.click(index);
+                if (operation === "fill") {
+                    await this.#app.pressKey("super+a");
+                    await this.#app.paste(value);
+                }
+                else
+                    await this.#app[operation](value);
+            }
+            else if (operation === "scroll")
+                await this.#app.scroll(index, value, 1);
+            else
+                await this.#app.performSecondaryAction(index, value);
+            return await this.handleObserve(read);
+        }
+        finally {
+            this.#busy = false;
+        }
+    }
+    async screenshot() {
+        if (this.#busy)
+            throw new Error("AX操作进行中，禁止并发截图");
+        this.requireMethods(["getScreenshot"]);
+        this.#busy = true;
+        this.#controls.clear();
+        this.#readable = false;
+        try {
+            return await this.#app.getScreenshot({ emit: false });
+        }
+        finally {
+            this.#busy = false;
+        }
+    }
+}
+export function createAXHarness(...args) {
+    return new AXHarness(...args);
+}

package/dist/readers-ax-parser.d.ts

@@ -0,0 +1 @@
+export declare function readAX(state: any, { mode, offset, limit, targetId, targetHandle, }?: any): any;

package/dist/readers-ax-parser.js

@@ -0,0 +1,69 @@
+// Native Chrome fallback: process a suppressed full AX observation in the REPL.
+// Keeps visible leaf evidence and action indexes; never reconstructs a diff as a full page.
+import { parseAXNodes, createAXTree } from "./readers-ax-tree.js";
+import { projectAXFilepicker, projectAXMedia, projectAXNavigation, projectAXPeople, projectAXPosts, projectAXProfile, projectAXComposer, } from "./readers-ax-views.js";
+export function readAX(state, { mode = "posts", offset = 0, limit = 1, targetId = "", targetHandle = "", } = {}) {
+    if (![
+        "posts",
+        "composer",
+        "profile",
+        "people",
+        "navigation",
+        "filepicker",
+        "media",
+    ].includes(mode))
+        throw new Error("AX mode必须为posts/composer/profile/people/navigation");
+    if (typeof state !== "string")
+        throw new Error("AX state必须为完整字符串");
+    if (!Number.isInteger(offset) ||
+        offset < 0 ||
+        !Number.isInteger(limit) ||
+        limit < 1 ||
+        limit > 5 ||
+        (targetId && !/^\d+$/.test(targetId)))
+        throw new Error("无效AX读取窗口或ID");
+    if (targetHandle && (mode !== "people" || !/^\w{1,15}$/.test(targetHandle)))
+        throw new Error("targetHandle必须为people模式已观察的handle");
+    const alertLines = state
+        .split("\n")
+        .filter((line) => /抱歉.*限制|速度限制|请求异常|访问受限|验证码|验证挑战|登录以继续|captcha|rate limit/i.test(line));
+    const unknown = (reason) => ({
+        mode,
+        posts: [],
+        evidence: [],
+        alerts: alertLines,
+        missing: [reason],
+        needsStateCheck: true,
+        pageComplete: false,
+    });
+    if (/following is a diff|Removed element IDs:|no change in the accessibility tree/i.test(state))
+        return unknown("full-ax-required");
+    const page = state.match(/URL:\s*((?:https?:\/\/)?x\.com\/[^\s,]*)/)?.[1];
+    if (!page && !["navigation", "filepicker"].includes(mode))
+        return unknown("x-page-unconfirmed");
+    const nodes = parseAXNodes(state);
+    const tree = createAXTree(nodes);
+    const context = {
+        mode,
+        page,
+        offset,
+        limit,
+        targetId,
+        targetHandle,
+        unknown,
+        alertLines,
+    };
+    if (mode === "filepicker")
+        return projectAXFilepicker(tree, context);
+    if (mode === "media")
+        return projectAXMedia(tree, context);
+    if (mode === "navigation")
+        return projectAXNavigation(tree, context);
+    if (mode === "people")
+        return projectAXPeople(tree, context);
+    if (mode === "posts")
+        return projectAXPosts(tree, context);
+    if (mode === "profile")
+        return projectAXProfile(tree, context);
+    return projectAXComposer(tree, context);
+}

package/dist/readers-ax-program.d.ts

@@ -0,0 +1 @@
+export declare const axParserCode: string;

package/dist/readers-ax-program.js

@@ -0,0 +1,5 @@
+import { readAX } from "./readers-ax-parser.js";
+import { parseAXNodes, createAXTree } from "./readers-ax-tree.js";
+import { projectAXFilepicker, projectAXMedia, projectAXNavigation, projectAXPeople, projectAXPosts, projectAXProfile, projectAXComposer, } from "./readers-ax-views.js";
+// Explicit serialization closure; the same parser runs in Node and the REPL.
+export const axParserCode = `(function(){const parseAXNodes=${parseAXNodes.toString()};const createAXTree=${createAXTree.toString()};const projectAXFilepicker=${projectAXFilepicker.toString()};const projectAXMedia=${projectAXMedia.toString()};const projectAXNavigation=${projectAXNavigation.toString()};const projectAXPeople=${projectAXPeople.toString()};const projectAXPosts=${projectAXPosts.toString()};const projectAXProfile=${projectAXProfile.toString()};const projectAXComposer=${projectAXComposer.toString()};return ${readAX.toString()};})()`;

package/dist/readers-ax-tree.d.ts

@@ -0,0 +1,19 @@
+export declare function parseAXNodes(state: string): any[];
+export declare function createAXTree(nodes: any[]): {
+    nodes: any[];
+    descendants: (i: any) => any[];
+    evidence: (ns: any) => any;
+    navigation: {
+        index: any;
+        label: any;
+    }[];
+    roots: any[];
+    peopleRoots: any[];
+    peopleTimeline: number;
+    within: (node: any, root: any) => boolean;
+    alerts: {
+        index: any;
+        label: any;
+    }[];
+};
+export type AXTree = ReturnType<typeof createAXTree>;

package/dist/readers-ax-tree.js

@@ -0,0 +1,111 @@
+export function parseAXNodes(state) {
+    const nodes = [], stack = [];
+    for (const line of state.split("\n")) {
+        const match = line.match(/^(\s*)(\d+) (.*)$/);
+        // Multiline post text such as "37 位中文主样本" is not an AX node.
+        if (!match ||
+            (!match[1] &&
+                !/^(?:标准窗口|表单|对话框|sheet|dialog|window|menu bar)(?: |$)/i.test(match[3]))) {
+            if (nodes.length &&
+                line.trim() &&
+                !/^The focused UI|Window:|Wall time:|Output:/.test(line))
+                nodes.at(-1).label += "\n" + line;
+            continue;
+        }
+        const depth = match[1].replace(/\t/g, "    ").length;
+        while (stack.length && nodes[stack.at(-1)].depth >= depth)
+            stack.pop();
+        // Chrome tab AX uses English role names; native app AX uses the canonical labels below.
+        const label = match[3]
+            .replace(/^link Description: /, "link ")
+            .replace(/^combo box(?: \([^)]*\))? (?:Description: )?/, "组合框 ")
+            .replace(/^button(?: \((?![^)]*disabled)[^)]*\))? /, "按钮 ")
+            .replace(/^text entry area(?: \(settable\))? Description: /, "文本输入区域 ");
+        const node = {
+            index: Number(match[2]),
+            label,
+            depth,
+            parent: stack.at(-1) ?? null,
+        };
+        nodes.push(node);
+        stack.push(nodes.length - 1);
+    }
+    return nodes;
+}
+export function createAXTree(nodes) {
+    const descendants = (i) => {
+        let end = i + 1;
+        while (end < nodes.length && nodes[end].depth > nodes[i].depth)
+            end++;
+        return nodes.slice(i + 1, end);
+    };
+    const leaf = (n) => /^(?:文本(?: |$)|text |link |按钮 |弹出式按钮 |切换按钮 |标签 |tab |图像 |文本输入区(?:域)? |文本区域 |文本栏 |组合框 |单选按钮 |复选框 )/.test(n.label) || /^container [\d,.万亿KMB]+ 次(?:观看|查看)$/.test(n.label);
+    const evidence = (ns) => ns.filter(leaf).map(({ index, label }) => ({ index, label }));
+    const navigation = nodes
+        .filter((n) => /^(?:标准窗口|window|HTML 内容) .*URL:/.test(n.label) ||
+        /^文本栏 .*地址和搜索栏/.test(n.label) ||
+        /^按钮 (?:重新加载|新标签页)$/.test(n.label) ||
+        n.label === "窗口" ||
+        /, ID: makeKeyAndOrderFront:$/.test(n.label) ||
+        /^标签 \((?:selected|settable)/.test(n.label) ||
+        /^(?:tab|标签)(?: \([^)]*\))? (?:帖子|回复|转帖|媒体|文章|Posts|Replies|Reposts|Media|Articles)(?:,|$)/.test(n.label) ||
+        /^组合框 (?:查询词条|Search)(?:,|$)/.test(n.label) ||
+        /^link (?:主页|搜索和发现|通知|个人资料), Value: x\.com\//.test(n.label))
+        .map(({ index, label }) => ({ index, label }));
+    const roots = [];
+    const within = (node, root) => {
+        let p = node.parent;
+        while (p !== null) {
+            if (p === root)
+                return true;
+            p = nodes[p].parent;
+        }
+        return false;
+    };
+    nodes.forEach((n, i) => {
+        // Chrome's window container also contains @handle and every post link.
+        if (!/^(?:container |article ).*@\w+/.test(n.label) ||
+            /\bURL:/.test(n.label))
+            return;
+        if (roots.some((root) => within(n, root)))
+            return;
+        if (descendants(i).some((d) => /^link /.test(d.label) && /x\.com\/\w+\/status\/\d+/.test(d.label)))
+            roots.push(i);
+    });
+    const peopleTimeline = nodes.findIndex((n) => /^container 时间线：(认证关注者|关注者|正在关注)$/.test(n.label));
+    const peopleRoots = peopleTimeline < 0
+        ? []
+        : nodes
+            .map((n, i) => ({ n, i }))
+            .filter(({ n, i }) => within(n, peopleTimeline) &&
+            /^按钮 .*@\w+(?: |$)/.test(n.label) &&
+            descendants(i).some((d) => /^link @\w+, Value: x\.com\/\w+(?:,|$)/.test(d.label)))
+            .map(({ i }) => i);
+    const warning = /抱歉.*限制|速度限制|请求异常|访问受限|验证码|验证挑战|登录以继续|captcha|rate limit/i;
+    const explicitAlert = (n) => {
+        let current = n;
+        while (current) {
+            if (/^(?:alert|警告|对话框|dialog|status|状态)(?: |$)/i.test(current.label))
+                return true;
+            current = current.parent === null ? null : nodes[current.parent];
+        }
+        return /^(?:文本输入区(?:域)?|文本区域|文本栏|按钮) /i.test(n.label);
+    };
+    const alerts = nodes
+        .filter((n, i) => warning.test(n.label) &&
+        (![...roots, ...peopleRoots].some((root) => i === root || within(n, root)) ||
+            explicitAlert(n)) &&
+        !descendants(i).some((d) => warning.test(d.label)))
+        .map((n) => ({ index: n.index, label: n.label }));
+    return {
+        nodes,
+        descendants,
+        evidence,
+        navigation,
+        roots,
+        peopleRoots,
+        peopleTimeline,
+        within,
+        alerts,
+    };
+}

package/dist/readers-ax-views.d.ts

@@ -0,0 +1,87 @@
+import type { AXTree } from "./readers-ax-tree.js";
+type AXProjection = {
+    mode: string;
+    page: string | undefined;
+    offset: number;
+    limit: number;
+    targetId: string;
+    targetHandle: string;
+    unknown: (reason: string) => any;
+    alertLines: string[];
+};
+export declare function projectAXFilepicker(tree: AXTree, context: AXProjection): any;
+export declare function projectAXMedia(tree: AXTree, context: AXProjection): any;
+export declare function projectAXNavigation(tree: AXTree, context: AXProjection): {
+    mode: string;
+    page: string | undefined;
+    posts: never[];
+    evidence: {
+        index: any;
+        label: any;
+    }[];
+    alerts: {
+        index: any;
+        label: any;
+    }[];
+    pageComplete: boolean;
+    needsStateCheck: boolean;
+    missing: string[];
+};
+export declare function projectAXPeople(tree: AXTree, context: AXProjection): {
+    mode: string;
+    page: string | undefined;
+    posts: never[];
+    people: {
+        handle: any;
+        evidence: any;
+    }[];
+    renderedPeople: number;
+    matched: number;
+    offset: number;
+    moreInDOM: boolean;
+    alerts: {
+        index: any;
+        label: any;
+    }[];
+    navigation: {
+        index: any;
+        label: any;
+    }[] | undefined;
+    missing: string[];
+    needsStateCheck: boolean;
+    pageComplete: boolean;
+};
+export declare function projectAXPosts(tree: AXTree, context: AXProjection): {
+    mode: string;
+    page: string | undefined;
+    renderedArticles: number;
+    matched: number;
+    offset: number;
+    moreInDOM: boolean;
+    pageComplete: boolean;
+    needsStateCheck: boolean;
+    missing: string[];
+    posts: {
+        timeEvidence: any;
+        text: string;
+        evidence: any;
+        needsExpansion: any;
+        missing: (string | false)[];
+        datetimePrecision?: string | undefined;
+        id: any;
+        author: any;
+        primary: any;
+        datetime: string | null;
+    }[];
+    alerts: {
+        index: any;
+        label: any;
+    }[];
+    navigation: {
+        index: any;
+        label: any;
+    }[] | undefined;
+};
+export declare function projectAXProfile(tree: AXTree, context: AXProjection): any;
+export declare function projectAXComposer(tree: AXTree, context: AXProjection): any;
+export {};