@nextclaw/x-harness 0.1.0 → 0.2.0

package/dist/platform-capabilities.d.ts

@@ -0,0 +1,8 @@
+import type { PlatformDependencies } from "./platform-dependencies.js";
+export declare class PlatformCapabilities {
+    #private;
+    preflight: ({ operation, input }: any) => any;
+    constructor(dependencies: Pick<PlatformDependencies, "missing" | "browser">);
+    private handlePreflight;
+}
+export declare function createPlatformCapabilities(...args: ConstructorParameters<typeof PlatformCapabilities>): PlatformCapabilities;

package/dist/platform-capabilities.js

@@ -0,0 +1,29 @@
+export class PlatformCapabilities {
+    #missing;
+    #browser;
+    preflight;
+    constructor(dependencies) {
+        const { missing, browser } = dependencies;
+        this.#missing = missing;
+        this.#browser = browser;
+        this.preflight = this.handlePreflight.bind(this);
+    }
+    handlePreflight({ operation, input = {} }) {
+        const absent = this.#missing(operation);
+        if (operation === "readCreator" &&
+            typeof this.#browser.collectCreator !== "function")
+            absent.push("browser.collectCreator");
+        if (input.kind === "follow" || operation === "submitFollow")
+            absent.push(...(this.#browser.capabilities?.("refreshPerson") ?? ["refreshPerson"]));
+        if (operation !== "read" && input.assets?.length)
+            absent.push(...(this.#browser.capabilities?.("attachAssets") ?? ["attachAssets"]));
+        return {
+            covered: absent.length === 0,
+            missing: [...new Set(absent)],
+            owner: "scripts/x-harness-browser.mjs",
+        };
+    }
+}
+export function createPlatformCapabilities(...args) {
+    return new PlatformCapabilities(...args);
+}

package/dist/platform-collections.d.ts

@@ -0,0 +1,14 @@
+import type { PlatformDependencies } from "./platform-dependencies.js";
+export declare class PlatformCollections {
+    #private;
+    collectSources: ({ processedIds, maxPages, limit }?: any) => Promise<any>;
+    readCreator: (args: import("./types.js").CreatorOptions) => Promise<any>;
+    readBookmarks: ({ folder, ...window }?: any) => Promise<any>;
+    searchSources: ({ query, limit, maxPages, processedIds, }?: any) => Promise<any>;
+    constructor(dependencies: Pick<PlatformDependencies, "ready" | "observed" | "browser" | "choose">);
+    private handleCollectSources;
+    private handleReadCreator;
+    private handleReadBookmarks;
+    private handleSearchSources;
+}
+export declare function createPlatformCollections(...args: ConstructorParameters<typeof PlatformCollections>): PlatformCollections;

package/dist/platform-collections.js

@@ -0,0 +1,250 @@
+import { xURL, source } from "./platform-rules.js";
+export class PlatformCollections {
+    #ready;
+    #observed;
+    #browser;
+    #choose;
+    collectSources;
+    readCreator;
+    readBookmarks;
+    searchSources;
+    constructor(dependencies) {
+        const { ready, observed, browser, choose } = dependencies;
+        this.#ready = ready;
+        this.#observed = observed;
+        this.#browser = browser;
+        this.#choose = choose;
+        this.collectSources = this.handleCollectSources.bind(this);
+        this.readCreator = this.handleReadCreator.bind(this);
+        this.readBookmarks = this.handleReadBookmarks.bind(this);
+        this.searchSources = this.handleSearchSources.bind(this);
+    }
+    async handleCollectSources({ processedIds = [], maxPages = 3, limit = 1, } = {}) {
+        if (!Array.isArray(processedIds) ||
+            !Number.isInteger(maxPages) ||
+            maxPages < 1 ||
+            maxPages > 10 ||
+            !Number.isInteger(limit) ||
+            limit < 1 ||
+            limit > 5)
+            throw new Error("来源窗口须为1–5，页面上限1–10及已处理ID数组");
+        const seen = new Set(processedIds), sources = [], missing = [];
+        let last, previousIds = "", offset = 0, firstDOMId;
+        for (let page = 0; page < maxPages && sources.length < limit; page++) {
+            last = await this.#ready({ view: "posts", offset, limit: 5 });
+            if (page === 0)
+                firstDOMId = last.posts?.[0]?.id;
+            if (last.needsStateCheck || last.alerts?.length)
+                return {
+                    ...last,
+                    sources,
+                    complete: false,
+                    missing: ["source-page-unconfirmed"],
+                };
+            if (offset && !last.posts?.length) {
+                missing.push("source-window-not-yet-rendered");
+                break;
+            }
+            const ids = (last.posts ?? []).map((p) => p.id).join(",");
+            if (page && ids === previousIds) {
+                missing.push("pagination-did-not-advance");
+                break;
+            }
+            previousIds = ids;
+            for (const candidate of last.posts ?? []) {
+                if (!candidate.id || seen.has(candidate.id))
+                    continue;
+                seen.add(candidate.id);
+                let post = candidate;
+                if (candidate.needsExpansion) {
+                    const target = await this.#observed({
+                        view: "posts",
+                        targetId: candidate.id,
+                        limit: 1,
+                    });
+                    if (target.posts?.length !== 1) {
+                        missing.push("expansion-target-unconfirmed");
+                        continue;
+                    }
+                    await this.#browser.act({
+                        operation: "expandPost",
+                        postId: candidate.id,
+                    });
+                    const expanded = await this.#ready({
+                        view: "posts",
+                        targetId: candidate.id,
+                        limit: 1,
+                    });
+                    if (expanded.needsStateCheck || expanded.alerts?.length)
+                        return {
+                            ...expanded,
+                            sources,
+                            complete: false,
+                            missing: ["expanded-source-unconfirmed"],
+                        };
+                    post = expanded.posts?.[0];
+                }
+                if (!post ||
+                    post.needsExpansion ||
+                    !post.body ||
+                    !post.author ||
+                    !Number.isFinite(Date.parse(post.datetime))) {
+                    missing.push(`incomplete-source:${candidate.id}`);
+                    continue;
+                }
+                sources.push(source(post, last.page));
+                if (sources.length >= limit)
+                    break;
+            }
+            if (sources.length < limit && page + 1 < maxPages) {
+                // Expansion narrowed the semantic window; restore the list before scrolling.
+                last = await this.#observed({ view: "posts", offset, limit: 5 });
+                if (last.moreInDOM)
+                    offset += 5;
+                else {
+                    await this.#browser.act({ operation: "nextPosts" });
+                    const advanced = await this.#ready({ view: "posts", limit: 5 });
+                    // Retained DOM prefixes include a partial final window too; skip
+                    // exactly the consumed cards, while virtualized replacements restart.
+                    offset =
+                        firstDOMId && advanced.posts?.[0]?.id === firstDOMId
+                            ? offset + (last.posts?.length ?? 0)
+                            : 0;
+                    firstDOMId = advanced.posts?.[0]?.id;
+                }
+            }
+        }
+        return {
+            page: last?.page,
+            accountHandle: last?.accountHandle,
+            observedAt: last?.observedAt,
+            fresh: true,
+            sources,
+            complete: sources.length >= limit,
+            pageComplete: false,
+            missing: sources.length >= limit
+                ? []
+                : [...new Set([...missing, "bounded-source-window-exhausted"])],
+        };
+    }
+    async handleReadCreator(args) {
+        if (typeof this.#browser.collectCreator !== "function")
+            return {
+                status: "needsCapability",
+                complete: false,
+                missing: ["browser.collectCreator"],
+            };
+        const value = await this.#browser.collectCreator(args);
+        const absent = [
+            ...new Set([
+                ...(value.missing ?? []),
+                ...(value.profile?.alerts ?? []),
+                ...(value.meta?.missing ?? []),
+            ]),
+        ];
+        return {
+            ...value,
+            sources: value.posts,
+            page: `https://x.com/${args.handle}`,
+            pageComplete: false,
+            complete: value.complete === true && !absent.length && !value.alerts?.length,
+            missing: absent,
+        };
+    }
+    async handleReadBookmarks({ folder, ...window } = {}) {
+        if (typeof folder !== "string" || !folder.trim())
+            throw new Error("需指定收藏文件夹；不以全部书签冒充命名文件夹");
+        let nav = await this.#ready({ view: "navigation", targetLabel: folder });
+        const bookmark = (c) => /^(书签|收藏|Bookmarks)$/i.test(c.label);
+        if (!(await this.#choose(nav, bookmark, { activateSelected: true }))) {
+            if (await this.#choose(nav, (c) => /^(更多菜单项|More menu items)$/i.test(c.label))) {
+                nav = await this.#ready({ view: "menu" });
+                if (!(await this.#choose(nav, bookmark))) {
+                    if (nav.items?.length)
+                        await this.#browser.act({ operation: "dismissMenu" });
+                    nav = await this.#ready({ view: "navigation", targetLabel: folder });
+                    if (!(await this.#choose(nav, (c) => /^(历史|History)$/i.test(c.label))))
+                        return {
+                            status: "needsCapability",
+                            owner: "scripts/x-harness-browser.mjs",
+                            missing: ["bookmarks-entry-not-observed"],
+                        };
+                }
+            }
+            else if (!(await this.#choose(nav, (c) => /^(历史|History)$/i.test(c.label))))
+                return {
+                    status: "needsCapability",
+                    owner: "scripts/x-harness-browser.mjs",
+                    missing: ["bookmarks-entry-not-observed"],
+                };
+        }
+        nav = await this.#ready({ view: "navigation", targetLabel: folder });
+        const tabs = (nav.controls ?? []).filter((c) => c.role === "tab" && bookmark(c));
+        if (tabs.length === 1 &&
+            (!tabs[0].selected ||
+                !(nav.controls ?? []).some((c) => c.label.split("\n")[0] === folder))) {
+            await this.#choose(nav, (c) => c === tabs[0], {
+                activateSelected: true,
+            });
+            nav = await this.#ready({ view: "navigation", targetLabel: folder });
+        }
+        if (!(nav.controls ?? []).some((c) => c.label.split("\n")[0] === folder)) {
+            try {
+                await this.#browser.act({ operation: "waitForFolder", folder });
+            }
+            catch (error) {
+                if (!/timed out|timeout/i.test(error.message))
+                    throw error;
+            }
+            nav = await this.#ready({ view: "navigation", targetLabel: folder });
+        }
+        if (!(await this.#choose(nav, (c) => c.label.split("\n")[0] === folder)))
+            return {
+                status: "needsCapability",
+                owner: "scripts/x-harness-browser.mjs",
+                page: nav.page,
+                missing: ["named-bookmark-folder-not-observed"],
+                folder,
+                controls: nav.controls,
+            };
+        const selected = await this.#ready({ view: "navigation" });
+        if (selected.page === nav.page && !selected.headings?.includes(folder))
+            return {
+                status: "needsDecision",
+                complete: false,
+                missing: ["folder-selection-unconfirmed"],
+                folder,
+                page: selected.page,
+            };
+        const value = await this.handleCollectSources(window);
+        return {
+            ...value,
+            folder,
+            folderEvidence: {
+                entryPage: nav.page,
+                selectedPage: selected.page,
+                name: folder,
+            },
+        };
+    }
+    async handleSearchSources({ query, limit = 3, maxPages = 1, processedIds = [], } = {}) {
+        await this.#browser.act({ operation: "searchSources", query });
+        const value = await this.handleCollectSources({
+            limit,
+            maxPages,
+            processedIds,
+        });
+        if (!value.page ||
+            xURL(value.page).pathname !== "/search" ||
+            xURL(value.page).searchParams.get("q") !== query)
+            return {
+                ...value,
+                complete: false,
+                missing: ["search-query-unconfirmed"],
+            };
+        return { ...value, query };
+    }
+}
+export function createPlatformCollections(...args) {
+    return new PlatformCollections(...args);
+}

package/dist/platform-dependencies.d.ts

@@ -0,0 +1,43 @@
+import type { CreatorOptions } from "./types.js";
+import type { BoundaryRecord } from "./boundary.js";
+export interface PlatformDependencies {
+    browser: BoundaryRecord;
+    clock: () => number;
+    followStage: (action: any, stage: any, run: any) => Promise<any>;
+    missing: (operation: any) => any[];
+    observed: (query: any) => Promise<any>;
+    open: (target: any, query: any) => Promise<any>;
+    ready: (query: any) => Promise<any>;
+    choose: (value: any, pattern: any, { activateSelected }?: any) => Promise<any>;
+    source: (post: any, page: any) => {
+        id: any;
+        author: any;
+        datetime: any;
+        url: string | null;
+        body: any;
+        images: any;
+        media: any;
+        links: any;
+        needsExpansion: any;
+        missing: any[];
+    };
+    collectSources: ({ processedIds, maxPages, limit }?: any) => Promise<any>;
+    compose: (action: any) => Promise<any>;
+    preflight: ({ operation, input }: any) => any;
+    readCreator: (args: 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;
+    };
+}

package/dist/platform-dependencies.js

@@ -0,0 +1 @@
+export {};

package/dist/platform-diagnostics.d.ts

@@ -0,0 +1,14 @@
+import type { PlatformDependencies } from "./platform-dependencies.js";
+export declare class PlatformDiagnostics {
+    #private;
+    followStage: (action: any, stage: any, run: any) => Promise<any>;
+    captureProof: ({ observation }: any) => {
+        followDiagnostics?: any[] | undefined;
+        capturedAt: string;
+        observation: any;
+    };
+    constructor(dependencies: Pick<PlatformDependencies, "clock">);
+    private handleFollowStage;
+    private handleCaptureProof;
+}
+export declare function createPlatformDiagnostics(...args: ConstructorParameters<typeof PlatformDiagnostics>): PlatformDiagnostics;

package/dist/platform-diagnostics.js

@@ -0,0 +1,63 @@
+export class PlatformDiagnostics {
+    #clock;
+    #followDiagnostics;
+    followStage;
+    captureProof;
+    constructor(dependencies) {
+        const { clock } = dependencies;
+        this.#clock = clock;
+        this.#followDiagnostics = [];
+        this.followStage = this.handleFollowStage.bind(this);
+        this.captureProof = this.handleCaptureProof.bind(this);
+    }
+    async handleFollowStage(action, stage, run) {
+        const started = this.#clock();
+        const event = {
+            actionId: action.id ?? null,
+            handle: action.handle,
+            stage,
+            startedAt: new Date(started).toISOString(),
+        };
+        this.#followDiagnostics.push(event);
+        if (this.#followDiagnostics.length > 40)
+            this.#followDiagnostics.shift();
+        try {
+            const value = await run();
+            Object.assign(event, {
+                status: "returned",
+                durationMs: this.#clock() - started,
+            });
+            if (value && typeof value === "object")
+                Object.assign(event, {
+                    page: value.page,
+                    accountHandle: value.accountHandle,
+                    relationship: value.relationship,
+                    relationshipControls: value.relationshipControls,
+                    needsStateCheck: value.needsStateCheck,
+                    alerts: value.alerts,
+                    fresh: value.fresh,
+                });
+            return value;
+        }
+        catch (error) {
+            Object.assign(event, {
+                status: "error",
+                durationMs: this.#clock() - started,
+                error: String(error.message ?? error).slice(0, 500),
+            });
+            throw error;
+        }
+    }
+    handleCaptureProof({ observation }) {
+        return {
+            capturedAt: new Date(this.#clock()).toISOString(),
+            observation,
+            ...(this.#followDiagnostics.length
+                ? { followDiagnostics: structuredClone(this.#followDiagnostics) }
+                : {}),
+        };
+    }
+}
+export function createPlatformDiagnostics(...args) {
+    return new PlatformDiagnostics(...args);
+}

package/dist/platform-observation.d.ts

@@ -0,0 +1,16 @@
+import type { PlatformDependencies } from "./platform-dependencies.js";
+export declare class PlatformObservation {
+    #private;
+    missing: (operation: any) => any[];
+    observed: (query: any) => Promise<any>;
+    open: (target: any, query: any) => Promise<any>;
+    ready: (query: any) => Promise<any>;
+    choose: (value: any, pattern: any, { activateSelected }?: any) => Promise<any>;
+    constructor(dependencies: Pick<PlatformDependencies, "browser" | "clock">);
+    private handleObserved;
+    private handleOpen;
+    private handleReady;
+    private handleChoose;
+    private handleMissing;
+}
+export declare function createPlatformObservation(...args: ConstructorParameters<typeof PlatformObservation>): PlatformObservation;

package/dist/platform-observation.js

@@ -0,0 +1,96 @@
+import { xURL } from "./platform-rules.js";
+export class PlatformObservation {
+    #browser;
+    #clock;
+    #methods;
+    missing;
+    observed;
+    open;
+    ready;
+    choose;
+    constructor(dependencies) {
+        const { browser, clock } = dependencies;
+        this.#browser = browser;
+        this.#clock = clock;
+        this.#methods = ["observe", "act"];
+        this.missing = this.handleMissing.bind(this);
+        this.observed = this.handleObserved.bind(this);
+        this.open = this.handleOpen.bind(this);
+        this.ready = this.handleReady.bind(this);
+        this.choose = this.handleChoose.bind(this);
+    }
+    async handleObserved(query) {
+        const value = await this.#browser.observe(query);
+        return {
+            ...value,
+            observedAt: new Date(this.#clock()).toISOString(),
+            fresh: true,
+        };
+    }
+    async handleOpen(target, query) {
+        const url = xURL(target.url);
+        if (!target.evidenceRef)
+            throw new Error("目标URL缺已观察证据");
+        let value = await this.handleObserved(query);
+        let atTarget = false;
+        try {
+            atTarget = xURL(value.page).href === url.href;
+        }
+        catch {
+            /* Blank/non-X pages require observed navigation. */
+        }
+        if (!atTarget) {
+            await this.#browser.act({
+                operation: "openObserved",
+                url: url.href,
+                evidenceRef: target.evidenceRef,
+                view: query.view,
+                handle: query.handle,
+            });
+            value = await this.handleReady(query);
+        }
+        if (!value.page || xURL(value.page).href !== url.href)
+            return {
+                ...value,
+                needsStateCheck: true,
+                missing: ["target-page-mismatch"],
+            };
+        return value;
+    }
+    async handleReady(query) {
+        let value = await this.handleObserved(query);
+        if (value.needsStateCheck &&
+            !value.alerts?.length &&
+            query.view === "posts") {
+            try {
+                await this.#browser.act({ operation: "waitForPosts" });
+            }
+            catch (error) {
+                if (!/timed out|timeout/i.test(error.message))
+                    throw error;
+            }
+            value = await this.handleObserved(query);
+        }
+        return value;
+    }
+    async handleChoose(value, pattern, { activateSelected = false } = {}) {
+        const controls = (value.controls ?? value.items ?? []).filter((c) => !c.disabled && pattern(c));
+        if (controls.length !== 1)
+            return false;
+        if (controls[0].selected && !activateSelected)
+            return true;
+        await this.#browser.act({ operation: "openControl", ...controls[0] });
+        return true;
+    }
+    handleMissing(operation) {
+        return [
+            ...this.#methods.filter((name) => typeof this.#browser?.[name] !== "function"),
+            ...(typeof this.#browser?.capabilities === "function"
+                ? this.#browser.capabilities(operation)
+                : ["capabilities"]),
+        ];
+    }
+}
+export function createPlatformObservation(...args) {
+    return new PlatformObservation(...args);
+}

package/dist/platform-rules.d.ts

@@ -0,0 +1,17 @@
+export declare const handlePattern: RegExp;
+export declare function xURL(value: any): any;
+export declare const sameHandle: (a: any, b: any) => boolean;
+export declare const sameText: (a: any, b: any) => boolean;
+export declare const samePublishedText: (a: any, b: any) => boolean;
+export declare const source: (post: any, page: any) => {
+    id: any;
+    author: any;
+    datetime: any;
+    url: string | null;
+    body: any;
+    images: any;
+    media: any;
+    links: any;
+    needsExpansion: any;
+    missing: any[];
+};

package/dist/platform-rules.js

@@ -0,0 +1,41 @@
+export const handlePattern = /^[A-Za-z0-9_]{1,15}$/;
+export function xURL(value) {
+    const url = new URL(/^x\.com\//.test(value ?? "") ? `https://${value}` : value);
+    if (url.protocol !== "https:" ||
+        url.hostname !== "x.com" ||
+        url.username ||
+        url.password ||
+        url.port)
+        throw new Error("只接受已观察的https://x.com目标");
+    return url;
+}
+export const sameHandle = (a, b) => typeof a === "string" &&
+    typeof b === "string" &&
+    a.toLowerCase() === b.toLowerCase();
+export const sameText = (a, b) => typeof a === "string" &&
+    typeof b === "string" &&
+    a.replace(/\r\n/g, "\n").replace(/\n{3,}/g, "\n\n") ===
+        b.replace(/\r\n/g, "\n").replace(/\n{3,}/g, "\n\n");
+export const samePublishedText = (a, b) => {
+    const rendered = (value) => typeof value === "string"
+        ? value
+            .replace(/(https?:\/\/[^\s…]+)…(?=\s|$)/g, "$1")
+            .replace(/(https?:\/\/[A-Za-z0-9.-]+(?::\d+)?)\/(?=[\s`]|$)/g, "$1")
+        : value;
+    return sameText(rendered(a), rendered(b));
+};
+export const source = (post, page) => ({
+    id: post.id,
+    author: post.author,
+    datetime: post.datetime,
+    url: post.primary ? new URL(post.primary, page).href : null,
+    body: post.body,
+    images: post.images ?? [],
+    media: post.media ?? [],
+    links: post.links ?? [],
+    needsExpansion: post.needsExpansion,
+    missing: [
+        ...(post.missing ?? []),
+        ...(!post.body ? ["exact-body-unconfirmed"] : []),
+    ],
+});

package/dist/platform-targets.d.ts

@@ -0,0 +1,14 @@
+import type { PlatformDependencies } from "./platform-dependencies.js";
+export declare class PlatformTargets {
+    #private;
+    readAccount: () => Promise<any>;
+    readFeedback: ({ targets, replyLimit }?: any) => Promise<any>;
+    readPerson: (target: any) => Promise<any>;
+    readPost: (target: any) => Promise<any>;
+    constructor(dependencies: Pick<PlatformDependencies, "observed" | "open" | "browser" | "ready">);
+    private handleReadFeedback;
+    private handleReadPerson;
+    private handleReadPost;
+    private handleReadAccount;
+}
+export declare function createPlatformTargets(...args: ConstructorParameters<typeof PlatformTargets>): PlatformTargets;