@nextclaw/x-harness 0.1.0 → 0.2.0

package/dist/platform-targets.js

@@ -0,0 +1,154 @@
+import { xURL, sameHandle, handlePattern, source } from "./platform-rules.js";
+export class PlatformTargets {
+    #observed;
+    #open;
+    #browser;
+    #ready;
+    readAccount;
+    readFeedback;
+    readPerson;
+    readPost;
+    constructor(dependencies) {
+        const { observed, open, browser, ready } = dependencies;
+        this.#observed = observed;
+        this.#open = open;
+        this.#browser = browser;
+        this.#ready = ready;
+        this.readAccount = this.handleReadAccount.bind(this);
+        this.readFeedback = this.handleReadFeedback.bind(this);
+        this.readPerson = this.handleReadPerson.bind(this);
+        this.readPost = this.handleReadPost.bind(this);
+    }
+    async handleReadFeedback({ targets, replyLimit = 3, } = {}) {
+        if (!Array.isArray(targets) || targets.length < 1 || targets.length > 5)
+            throw new Error("反馈窗口须为1–5个已发布ID");
+        if (!Number.isInteger(replyLimit) || replyLimit < 0 || replyLimit > 3)
+            throw new Error("回复核验窗口须为0–3");
+        const feedback = [];
+        for (const target of targets) {
+            const value = await this.handleReadPost(target), post = value.posts?.find((p) => p.id === target.postId);
+            if (value.needsStateCheck || value.alerts?.length || !post) {
+                feedback.push({
+                    id: target.postId,
+                    missing: ["published-post-unconfirmed"],
+                });
+                continue;
+            }
+            const thread = await this.#observed({ view: "posts", limit: 5 });
+            const replies = [], unconfirmedReplyIds = [];
+            const targetIndex = (thread.posts ?? []).findIndex((p) => p.id === post.id);
+            const candidates = targetIndex < 0
+                ? []
+                : thread.posts.slice(targetIndex + 1, targetIndex + 1 + replyLimit);
+            for (const candidate of candidates) {
+                if (!candidate.primary || !candidate.id)
+                    continue;
+                const url = new URL(candidate.primary, thread.page).href;
+                const detail = await this.#open({
+                    url,
+                    evidenceRef: {
+                        page: thread.page,
+                        observedAt: thread.observedAt,
+                        publicId: candidate.id,
+                        primary: candidate.primary,
+                    },
+                }, {
+                    view: "posts",
+                    targetId: candidate.id,
+                    replyTargetId: target.postId,
+                    limit: 1,
+                });
+                const reply = detail.posts?.find((p) => p.id === candidate.id);
+                if (!detail.needsStateCheck &&
+                    !detail.alerts?.length &&
+                    reply?.replyToId === target.postId &&
+                    reply.body &&
+                    !reply.needsExpansion)
+                    replies.push(source(reply, detail.page));
+                else
+                    unconfirmedReplyIds.push(candidate.id);
+            }
+            feedback.push({
+                id: post.id,
+                author: post.author,
+                metrics: [...(post.buttons ?? []), ...(post.metrics ?? [])],
+                replies,
+                unconfirmedReplyIds,
+                pageComplete: false,
+                observedAt: value.observedAt,
+            });
+        }
+        return {
+            feedback,
+            fresh: true,
+            complete: feedback.every((f) => !f.missing),
+            pageComplete: false,
+        };
+    }
+    async handleReadPerson(target) {
+        if (!handlePattern.test(target.handle ?? ""))
+            throw new Error("无效已观察handle");
+        if (xURL(target.url).pathname.toLowerCase() !==
+            `/${target.handle}`.toLowerCase())
+            throw new Error("人物URL与handle不一致");
+        const value = await this.#open(target, {
+            view: "person",
+            handle: target.handle,
+        });
+        return sameHandle(value.handle, target.handle)
+            ? { ...value, url: target.url }
+            : {
+                ...value,
+                needsStateCheck: true,
+                missing: ["person-identity-mismatch"],
+            };
+    }
+    async handleReadPost(target) {
+        if (!/^\d+$/.test(target.postId ?? "") ||
+            xURL(target.url).pathname.match(/\/status\/(\d+)$/)?.[1] !== target.postId)
+            throw new Error("帖子URL与公开ID不一致");
+        let value = await this.#open(target, {
+            view: "posts",
+            targetId: target.postId,
+        });
+        if (!target.expand)
+            return value;
+        let posts = (value.posts ?? []).filter((p) => p.id === target.postId);
+        if (!value.needsStateCheck &&
+            !value.alerts?.length &&
+            posts.length === 1 &&
+            posts[0].needsExpansion) {
+            await this.#browser.act({
+                operation: "expandPost",
+                postId: target.postId,
+            });
+            value = await this.#ready({ view: "posts", targetId: target.postId });
+            posts = (value.posts ?? []).filter((p) => p.id === target.postId);
+        }
+        const missing = [...(value.missing ?? [])];
+        if (posts.length !== 1)
+            missing.push("unique-target-post-unconfirmed");
+        else {
+            if (!posts[0].body)
+                missing.push("exact-body-unconfirmed");
+            if (posts[0].needsExpansion)
+                missing.push("post-expansion-unconfirmed");
+            if (!posts[0].author)
+                missing.push("post-author-unconfirmed");
+            if (!Number.isFinite(Date.parse(posts[0].datetime)))
+                missing.push("absolute-time-unconfirmed");
+        }
+        return {
+            ...value,
+            posts,
+            complete: !missing.length && !value.needsStateCheck && !value.alerts?.length,
+            missing,
+        };
+    }
+    handleReadAccount() {
+        return this.#observed({ view: "account" });
+    }
+}
+export function createPlatformTargets(...args) {
+    return new PlatformTargets(...args);
+}

package/dist/platform-writing.d.ts

@@ -0,0 +1,16 @@
+import type { PlatformDependencies } from "./platform-dependencies.js";
+export declare class PlatformWriting {
+    #private;
+    compose: (action: any) => Promise<any>;
+    findSubmission: (action: any) => Promise<any>;
+    submitFollow: (action: any) => Promise<any>;
+    submitPost: (action: any) => Promise<any>;
+    submitReply: (action: any) => Promise<any>;
+    constructor(dependencies: Pick<PlatformDependencies, "observed" | "browser" | "followStage" | "readPerson" | "open" | "clock" | "readPost">);
+    private handleCompose;
+    private handleFindSubmission;
+    private handleSubmitFollow;
+    private handleSubmitPost;
+    private handleSubmitReply;
+}
+export declare function createPlatformWriting(...args: ConstructorParameters<typeof PlatformWriting>): PlatformWriting;

package/dist/platform-writing.js

@@ -0,0 +1,202 @@
+import { xURL, sameHandle, sameText, samePublishedText, } from "./platform-rules.js";
+export class PlatformWriting {
+    #observed;
+    #browser;
+    #followStage;
+    #readPerson;
+    #open;
+    #clock;
+    #readPost;
+    compose;
+    findSubmission;
+    submitFollow;
+    submitPost;
+    submitReply;
+    constructor(dependencies) {
+        const { observed, browser, followStage, readPerson, open, clock, readPost, } = dependencies;
+        this.#observed = observed;
+        this.#browser = browser;
+        this.#followStage = followStage;
+        this.#readPerson = readPerson;
+        this.#open = open;
+        this.#clock = clock;
+        this.#readPost = readPost;
+        this.compose = this.handleCompose.bind(this);
+        this.findSubmission = this.handleFindSubmission.bind(this);
+        this.submitFollow = this.handleSubmitFollow.bind(this);
+        this.submitPost = this.handleSubmitPost.bind(this);
+        this.submitReply = this.handleSubmitReply.bind(this);
+    }
+    async handleCompose(action) {
+        let value = await this.#observed({ view: "composer" });
+        if (value.needsStateCheck ||
+            value.alerts?.length ||
+            typeof value.editorText !== "string" ||
+            value.editorText.trim() !== "" ||
+            (action.kind === "reply" && value.replyToId !== action.postId))
+            throw new Error("编辑器不为空或回复上下文未绑定");
+        if (action.assets?.length)
+            await this.#browser.act({
+                operation: "attachAssets",
+                assets: action.assets,
+            });
+        await this.#browser.act({ operation: "fillComposer", text: action.text });
+        value = await this.#observed({ view: "composer" });
+        if (!sameText(value.editorText, action.text) ||
+            value.needsStateCheck ||
+            value.alerts?.length ||
+            (action.kind === "reply" && value.replyToId !== action.postId) ||
+            (action.accountHandle &&
+                !sameHandle(value.accountHandle, action.accountHandle)))
+            throw new Error(`提交前账号/正文/目标未核实 ${JSON.stringify({ textMatches: sameText(value.editorText, action.text), needsStateCheck: value.needsStateCheck, alerts: value.alerts, accountHandle: value.accountHandle, replyToId: value.replyToId })}`);
+        return this.#browser.act({
+            operation: action.kind === "reply" ? "submitReply" : "submitPost",
+            beforeSubmit: action.beforeSubmit,
+            ...(action.activation ? { activation: action.activation } : {}),
+        });
+    }
+    async handleFindSubmission(action) {
+        if (action.kind === "follow") {
+            let value = await this.#followStage(action, "verify-read", () => this.#readPerson(action));
+            if (!value.needsStateCheck) {
+                const absent = this.#browser.capabilities?.("refreshPerson") ?? [
+                    "refreshPerson",
+                ];
+                if (absent.length)
+                    return {
+                        ...value,
+                        verified: false,
+                        missing: absent,
+                        needsStateCheck: true,
+                    };
+                await this.#followStage(action, "verify-refresh", () => this.#browser.act({
+                    operation: "refreshPerson",
+                    handle: action.handle,
+                    url: action.url,
+                    evidenceRef: action.evidenceRef,
+                }));
+                value = await this.#followStage(action, "verify-after-refresh", () => this.#readPerson(action));
+            }
+            return {
+                ...value,
+                verified: !value.needsStateCheck &&
+                    !value.alerts?.length &&
+                    value.relationship === "following" &&
+                    (!action.accountHandle ||
+                        sameHandle(value.accountHandle, action.accountHandle)),
+                publicId: null,
+            };
+        }
+        // A bounded window cannot prove absence. Reply receipts use the observed target conversation.
+        const observedReceipt = ["reply", "original"].includes(action.kind) &&
+            action.observedPublicURL &&
+            action.observedPublicEvidenceRef;
+        const receiptPath = observedReceipt
+            ? xURL(action.observedPublicURL).pathname.split("/")
+            : [];
+        if (observedReceipt &&
+            (receiptPath.length !== 4 ||
+                !sameHandle(receiptPath[1], action.accountHandle) ||
+                receiptPath[2] !== "status" ||
+                !/^[0-9]+$/.test(receiptPath[3])))
+            throw new Error("已观察回复回执须属于原账号");
+        const receiptTarget = observedReceipt
+            ? {
+                url: action.observedPublicURL,
+                evidenceRef: action.observedPublicEvidenceRef,
+            }
+            : action.kind === "reply" && action.url && action.evidenceRef
+                ? { url: action.url, evidenceRef: action.evidenceRef }
+                : { url: action.accountURL, evidenceRef: action.accountEvidenceRef };
+        let value = await this.#open(receiptTarget, { view: "posts", limit: 5 });
+        if (!(action.kind === "original" && observedReceipt) &&
+            !value.needsStateCheck &&
+            !(this.#browser.capabilities?.("refreshPosts") ?? ["refreshPosts"]).length) {
+            await this.#browser.act({
+                operation: "refreshPosts",
+                url: receiptTarget.url,
+                evidenceRef: receiptTarget.evidenceRef,
+            });
+            value = await this.#observed({ view: "posts", limit: 5 });
+        }
+        const matchesContent = (post) => sameHandle(post.author, action.accountHandle) &&
+            samePublishedText(post.body, action.text) &&
+            /^\d+$/.test(post.id ?? "") &&
+            (!action.assets?.length ||
+                action.assets.every((asset) => post.images?.some((image) => image.alt === asset.alt))) &&
+            !(action.beforeIds ?? []).includes(post.id) &&
+            Number.isFinite(Date.parse(post.datetime)) &&
+            Date.parse(post.datetime) >= Date.parse(action.intentAt) &&
+            Date.parse(post.datetime) <= this.#clock() + 5000 &&
+            !post.needsExpansion;
+        let matches = (value.posts ?? []).filter(matchesContent);
+        if (action.kind === "reply" &&
+            matches.length === 1 &&
+            matches[0].replyToId == null &&
+            matches[0].primary) {
+            // The candidate URL comes from this fresh public observation, not from a guessed ID path.
+            const candidate = matches[0];
+            const url = xURL(new URL(candidate.primary, xURL(value.page).origin).href);
+            if (url.pathname.toLowerCase() ===
+                `/${action.accountHandle}/status/${candidate.id}`.toLowerCase()) {
+                value = await this.#open({
+                    url: url.href,
+                    evidenceRef: {
+                        page: value.page,
+                        observedAt: value.observedAt,
+                        publicId: candidate.id,
+                        primary: candidate.primary,
+                    },
+                }, {
+                    view: "posts",
+                    targetId: candidate.id,
+                    replyTargetId: action.postId,
+                });
+                matches = (value.posts ?? []).filter(matchesContent);
+            }
+        }
+        if (action.kind === "reply")
+            matches = matches.filter((post) => post.replyToId === action.postId);
+        return {
+            ...value,
+            verified: !value.needsStateCheck && !value.alerts?.length && matches.length === 1,
+            publicId: matches.length === 1 ? matches[0].id : null,
+            missing: matches.length === 1 ? [] : ["unique-public-submission-unconfirmed"],
+        };
+    }
+    async handleSubmitFollow(action) {
+        const value = await this.#followStage(action, "submit-preflight-read", () => this.#readPerson(action));
+        if (value.needsStateCheck ||
+            value.alerts?.length ||
+            !["not-following", "follows-you"].includes(value.relationship) ||
+            (action.accountHandle &&
+                !sameHandle(value.accountHandle, action.accountHandle)))
+            throw new Error("fresh账号/人物关系不允许关注");
+        await this.#followStage(action, "submit-guard", () => action.beforeSubmit?.());
+        // A returned click is not a receipt from X; durable success still requires fresh verification.
+        const clicked = await this.#followStage(action, "click", () => this.#browser.act({ operation: "follow", handle: action.handle }));
+        try {
+            await this.#followStage(action, "click-ui-observation", () => this.#observed({ view: "person", handle: action.handle }));
+        }
+        catch {
+            /* The click may have committed; retain diagnostic failure and use the original fresh receipt path. */
+        }
+        return clicked;
+    }
+    async handleSubmitPost(action) {
+        await this.#open({ url: action.composeURL, evidenceRef: action.composeEvidenceRef }, { view: "composer" });
+        return this.handleCompose(action);
+    }
+    async handleSubmitReply(action) {
+        const value = await this.#readPost(action);
+        if (value.needsStateCheck ||
+            value.alerts?.length ||
+            !(value.posts ?? []).some((p) => p.id === action.postId))
+            throw new Error("回复主帖身份未核实");
+        await this.#browser.act({ operation: "openReply", postId: action.postId });
+        return this.handleCompose(action);
+    }
+}
+export function createPlatformWriting(...args) {
+    return new PlatformWriting(...args);
+}

package/dist/platform.d.ts

@@ -1,2 +1,23 @@
-export declare function xURL(value: any): any;
-export declare function createXPlatform(browser: any, { clock }?: any): any;
+export { xURL } from "./platform-rules.js";
+export declare class XPlatform {
+    #private;
+    preflight: ({ operation, input }: any) => any;
+    readCreator: (args: import("./types.js").CreatorOptions) => Promise<any>;
+    readAccount: () => Promise<any>;
+    readBookmarks: ({ folder, ...window }?: any) => Promise<any>;
+    searchSources: ({ query, limit, maxPages, processedIds, }?: any) => Promise<any>;
+    readFeedback: ({ targets, replyLimit }?: any) => Promise<any>;
+    readPerson: (target: any) => Promise<any>;
+    readPost: (target: any) => Promise<any>;
+    findSubmission: (action: any) => Promise<any>;
+    submitFollow: (action: any) => Promise<any>;
+    submitPost: (action: any) => Promise<any>;
+    submitReply: (action: any) => Promise<any>;
+    captureProof: ({ observation }: any) => {
+        followDiagnostics?: any[] | undefined;
+        capturedAt: string;
+        observation: any;
+    };
+    constructor(browser: any, { clock }?: any);
+}
+export declare function createXPlatform(...args: ConstructorParameters<typeof XPlatform>): any;