@nextclaw/x-harness 0.1.0 → 0.2.0

package/dist/browser-native.d.ts

@@ -1 +1,14 @@
-export declare function createNativeXBrowser(app: any): any;
+import type { BoundaryRecord } from "./boundary.js";
+export declare class NativeXBrowser {
+    #private;
+    observe: (query: any) => Promise<any>;
+    constructor(app: any);
+    private navigateNativeTarget;
+    private handleObserve;
+    private one;
+    collectCreator(args: import("./types.js").CreatorOptions): Promise<BoundaryRecord>;
+    capabilities(operation: any): any;
+    act(command: any): Promise<any>;
+    screenshot(): any;
+}
+export declare function createNativeXBrowser(...args: ConstructorParameters<typeof NativeXBrowser>): any;

package/dist/browser-native.js

@@ -1,52 +1,107 @@
-import { createAXHarness, readAX } from "./readers.js";
-import { xURL } from "./platform.js";
+import { collectCreatorNative } from "./creator-native.js";
+import { createAXHarness } from "./readers-ax-host.js";
+import { readAX } from "./readers-ax-parser.js";
+import { xURL } from "./platform-rules.js";
 import { serialized, missingMethods, plain, valueOf, } from "./browser-common.js";
-export function createNativeXBrowser(app) {
-    let latestAX;
-    const delegated = {};
-    for (const name of [
-        "getAXState",
-        "click",
-        "pressKey",
-        "paste",
-        "scroll",
-        "performSecondaryAction",
-        "getScreenshot",
-    ]) {
-        Object.defineProperty(delegated, name, {
-            get() {
-                if (typeof app?.[name] !== "function")
-                    return undefined;
-                return name === "getAXState"
-                    ? async (options) => {
-                        latestAX = await app.getAXState(options);
-                        return latestAX;
-                    }
-                    : (...args) => app[name](...args);
+export class NativeXBrowser {
+    #app;
+    #latestAX;
+    #delegated;
+    #low;
+    #current;
+    #modes;
+    observe;
+    constructor(app) {
+        this.screenshot = this.screenshot.bind(this);
+        this.act = this.act.bind(this);
+        this.capabilities = this.capabilities.bind(this);
+        this.collectCreator = this.collectCreator.bind(this);
+        this.#app = app;
+        this.#delegated = {};
+        for (const name of [
+            "getAXState",
+            "click",
+            "pressKey",
+            "paste",
+            "scroll",
+            "performSecondaryAction",
+            "getScreenshot",
+        ]) {
+            Object.defineProperty(this.#delegated, name, {
+                get: () => {
+                    if (typeof this.#app?.[name] !== "function")
+                        return undefined;
+                    return name === "getAXState"
+                        ? async (options) => {
+                            this.#latestAX = await this.#app.getAXState(options);
+                            return this.#latestAX;
+                        }
+                        : (...args) => this.#app[name](...args);
+                },
+            });
+        }
+        this.#low = createAXHarness(this.#delegated);
+        this.#modes = {
+            account: "navigation",
+            person: "profile",
+            posts: "posts",
+            composer: "composer",
+        };
+        this.observe = this.handleObserve.bind(this);
+        Object.assign(this, serialized({
+            collectCreator: (args) => collectCreatorNative(this.#low, args),
+            capabilities: this.capabilities,
+            observe: this.handleObserve.bind(this),
+            act: this.act,
+            screenshot: () => {
+                this.#current = null;
+                return this.#low.screenshot();
             },
+        }));
+    }
+    async navigateNativeTarget(command) {
+        xURL(command.url);
+        if (!command.evidenceRef)
+            throw new Error("导航URL缺原观察证据");
+        await this.#low.observe({ mode: "navigation" }).then((raw) => {
+            this.#current = { raw };
+        });
+        let index = this.one((e) => /^文本栏 .*地址和搜索栏/.test(e.label));
+        await this.#low
+            .act({
+            index,
+            operation: "fill",
+            value: command.url,
+            read: { mode: "navigation" },
+        })
+            .then((raw) => {
+            this.#current = { raw };
+        });
+        index = this.one((e) => /^文本栏 .*地址和搜索栏/.test(e.label));
+        await this.#low.act({
+            index,
+            operation: "pressKey",
+            value: "Return",
+            read: { mode: "navigation" },
         });
+        this.#current = null;
+        return;
     }
-    const low = createAXHarness(delegated);
-    let current;
-    const modes = {
-        account: "navigation",
-        person: "profile",
-        posts: "posts",
-        composer: "composer",
-    };
-    async function observe(query) {
-        current = null;
-        if (!modes[query.view])
+    async handleObserve(query) {
+        this.#current = null;
+        if (!this.#modes[query.view])
             throw new Error("未封装的业务视图");
-        const raw = await low.observe({
-            mode: modes[query.view],
+        const raw = await this.#low.observe({
+            mode: this.#modes[query.view],
             ...(query.targetId ? { targetId: query.targetId } : {}),
             limit: query.limit ?? 1,
         });
-        current = { query, raw };
+        this.#current = { query, raw };
         const entries = raw.evidence ?? [];
         // Bind actor and target to the SAME suppressed observation; no additional tool round trip.
-        const ownLinks = readAX(latestAX, { mode: "navigation" }).evidence.filter((e) => /^link 个人资料, Value: x\.com\/\w+$/.test(e.label));
+        const ownLinks = readAX(this.#latestAX, {
+            mode: "navigation",
+        }).evidence.filter((e) => /^link 个人资料, Value: x\.com\/\w+$/.test(e.label));
         const base = {
             page: raw.page,
             alerts: raw.alerts,
@@ -100,112 +155,94 @@ export function createNativeXBrowser(app) {
             })),
         };
     }
-    const one = (predicate) => {
-        const entries = (current?.raw.evidence ?? [])
-            .concat(current?.raw.navigation ?? [])
+    one(predicate) {
+        const entries = (this.#current?.raw.evidence ?? [])
+            .concat(this.#current?.raw.navigation ?? [])
             .filter(predicate);
         if (entries.length !== 1)
             throw new Error("语义控件未唯一观察：先补能力/证据");
         return entries[0].index;
-    };
-    return serialized({
-        capabilities(operation) {
-            if (["readBookmarks", "searchSources", "readFeedback"].includes(operation))
-                return [`native.${operation}`];
-            const names = operation === "read"
-                ? ["getAXState"]
-                : ["getAXState", "click", "pressKey", "paste"];
-            return operation === "attachAssets"
-                ? ["native.attachAssets"]
-                : operation === "refreshPosts"
-                    ? ["native.refreshPosts"]
-                    : missingMethods(app, names);
-        },
-        observe,
-        async act(command) {
-            if (command.operation === "openObserved") {
-                xURL(command.url);
-                if (!command.evidenceRef)
-                    throw new Error("导航URL缺原观察证据");
-                await low.observe({ mode: "navigation" }).then((raw) => {
-                    current = { raw };
-                });
-                let index = one((e) => /^文本栏 .*地址和搜索栏/.test(e.label));
-                await low
-                    .act({
-                    index,
-                    operation: "fill",
-                    value: command.url,
-                    read: { mode: "navigation" },
-                })
-                    .then((raw) => {
-                    current = { raw };
-                });
-                index = one((e) => /^文本栏 .*地址和搜索栏/.test(e.label));
-                await low.act({
-                    index,
-                    operation: "pressKey",
-                    value: "Return",
-                    read: { mode: "navigation" },
-                });
-                current = null;
-                return;
-            }
-            if (command.operation === "refreshPerson") {
-                xURL(command.url);
-                await low.observe({ mode: "navigation" }).then((raw) => {
-                    current = { raw };
-                });
-                const index = one((e) => /^按钮 (重新加载|刷新)(?:,|$)/.test(e.label));
-                current = null;
-                return low.act({
-                    index,
-                    operation: "click",
-                    read: { mode: "profile" },
-                });
-            }
-            if (!current)
-                throw new Error("语义操作必须先observe");
-            let index, operation = "click", value;
-            if (command.operation === "follow")
-                index = one((e) => [
-                    `按钮 关注 @${command.handle}`,
-                    `按钮 回关 @${command.handle}`,
-                ].includes(e.label));
-            else if (command.operation === "openReply") {
-                if (current.query?.targetId !== command.postId)
-                    throw new Error("回复目标不匹配");
-                const target = current.raw.posts?.filter((p) => p.id === command.postId);
-                if (target?.length !== 1)
-                    throw new Error("回复主帖不唯一");
-                const buttons = target[0].evidence.filter((e) => /^按钮 .*回复/.test(e.label));
-                if (buttons.length !== 1)
-                    throw new Error("回复按钮不唯一");
-                index = buttons[0].index;
-            }
-            else if (command.operation === "fillComposer") {
-                index = one((e) => /^(?:文本输入区(?:域)?|文本区域|文本栏) /.test(e.label));
-                operation = "fill";
-                value = command.text;
-            }
-            else if (["submitPost", "submitReply"].includes(command.operation)) {
-                index = one((e) => new RegExp(command.operation === "submitReply"
-                    ? "^按钮 (回复|Reply)(?:,|$)"
-                    : "^按钮 (发帖|发布|Post)(?:,|$)", "i").test(e.label));
-            }
-            else
-                throw new Error("未封装的原生动作");
-            const read = {
-                mode: command.operation === "follow" ? "profile" : "composer",
-            };
-            if (["submitPost", "submitReply"].includes(command.operation))
-                await command.beforeSubmit?.();
-            current = null;
-            return low.act({ index, operation, value, read });
-        },
-        screenshot: () => {
-            current = null;
-            return low.screenshot();
-        },
-    });
+    }
+    collectCreator(args) {
+        return collectCreatorNative(this.#low, args);
+    }
+    capabilities(operation) {
+        if (["readBookmarks", "searchSources", "readFeedback"].includes(operation))
+            return [`native.${operation}`];
+        const names = operation === "read"
+            ? ["getAXState"]
+            : ["getAXState", "click", "pressKey", "paste"];
+        return operation === "attachAssets"
+            ? ["native.attachAssets"]
+            : operation === "refreshPosts"
+                ? ["native.refreshPosts"]
+                : missingMethods(this.#app, names);
+    }
+    async act(command) {
+        if (command.operation === "waitForPosts") {
+            this.#current = null;
+            return this.#low.observe({ mode: "posts", limit: 5 });
+        }
+        if (command.operation === "openObserved") {
+            return this.navigateNativeTarget(command);
+        }
+        if (command.operation === "refreshPerson") {
+            xURL(command.url);
+            await this.#low.observe({ mode: "navigation" }).then((raw) => {
+                this.#current = { raw };
+            });
+            const index = this.one((e) => /^按钮 (重新加载|刷新)(?:,|$)/.test(e.label));
+            this.#current = null;
+            return this.#low.act({
+                index,
+                operation: "click",
+                read: { mode: "profile" },
+            });
+        }
+        if (!this.#current)
+            throw new Error("语义操作必须先observe");
+        let index, operation = "click", value;
+        if (command.operation === "follow")
+            index = this.one((e) => [
+                `按钮 关注 @${command.handle}`,
+                `按钮 回关 @${command.handle}`,
+            ].includes(e.label));
+        else if (command.operation === "openReply") {
+            if (this.#current.query?.targetId !== command.postId)
+                throw new Error("回复目标不匹配");
+            const target = this.#current.raw.posts?.filter((p) => p.id === command.postId);
+            if (target?.length !== 1)
+                throw new Error("回复主帖不唯一");
+            const buttons = target[0].evidence.filter((e) => /^按钮 .*回复/.test(e.label));
+            if (buttons.length !== 1)
+                throw new Error("回复按钮不唯一");
+            index = buttons[0].index;
+        }
+        else if (command.operation === "fillComposer") {
+            index = this.one((e) => /^(?:文本输入区(?:域)?|文本区域|文本栏) /.test(e.label));
+            operation = "fill";
+            value = command.text;
+        }
+        else if (["submitPost", "submitReply"].includes(command.operation)) {
+            index = this.one((e) => new RegExp(command.operation === "submitReply"
+                ? "^按钮 (回复|Reply)(?:,|$)"
+                : "^按钮 (发帖|发布|Post)(?:,|$)", "i").test(e.label));
+        }
+        else
+            throw new Error("未封装的原生动作");
+        const read = {
+            mode: command.operation === "follow" ? "profile" : "composer",
+        };
+        if (["submitPost", "submitReply"].includes(command.operation))
+            await command.beforeSubmit?.();
+        this.#current = null;
+        return this.#low.act({ index, operation, value, read });
+    }
+    screenshot() {
+        this.#current = null;
+        return this.#low.screenshot();
+    }
+}
+export function createNativeXBrowser(...args) {
+    return new NativeXBrowser(...args);
 }

package/dist/browser.js

@@ -1,4 +1,7 @@
-import { readProfile, readPosts, readComposer, readMediaEditor, readNavigation, readMenu, } from "./readers.js";
+import { readProfile } from "./readers-profile.js";
+import { readPosts } from "./readers-posts.js";
+import { readComposer, readMediaEditor } from "./readers-composer.js";
+import { readNavigation, readMenu } from "./readers-navigation.js";
 export { createDOMXBrowser, readXNetworkDiagnostics } from "./browser-dom.js";
 export { createNativeXBrowser } from "./browser-native.js";
 // Read-only supplement: account identity, composer context and exact tweet bodies.
@@ -106,7 +109,8 @@ export function readXSurface({ view, posts = [], targetId, replyTargetId, } = {}
                             const read = (node) => {
                                 if (node.nodeType === 3)
                                     return node.textContent ?? "";
-                                if (node.nodeType === 1 && node.tagName === "A") {
+                                if (node.nodeType === 1 &&
+                                    node.tagName === "A") {
                                     const href = node.getAttribute("href") ?? "";
                                     if (/^\/\w{1,15}\/status\/\d+$/.test(href))
                                         return `https://x.com${href}`;

package/dist/creator-native.d.ts

@@ -0,0 +1,3 @@
+import type { BoundaryRecord } from "./boundary.js";
+import type { CreatorOptions } from "./types.js";
+export declare function collectCreatorNative(low: BoundaryRecord, { handle, target, maxScrolls, navigate }: CreatorOptions): Promise<BoundaryRecord>;

package/dist/creator-native.js

@@ -0,0 +1,113 @@
+// Bounded collection on an already selected profile. Relative AX times stay unknown.
+export async function collectCreatorNative(low, { handle, target = 10, maxScrolls = 18, navigate = true }) {
+    if (!/^[A-Za-z0-9_]{1,15}$/.test(handle) ||
+        !Number.isInteger(target) ||
+        target < 1 ||
+        target > 50 ||
+        !Number.isInteger(maxScrolls) ||
+        maxScrolls < 0 ||
+        maxScrolls > 50)
+        throw new Error("Invalid creator collection input");
+    if (navigate)
+        return {
+            status: "needsCapability",
+            complete: false,
+            posts: [],
+            missing: ["native.creator-navigation"],
+        };
+    const profile = await low.observe({ mode: "profile" });
+    const expected = new RegExp(`^(?:https?://)?x\\.com/${handle}/?$`, "i");
+    if (!expected.test(profile.page ?? "") || profile.needsStateCheck)
+        throw new Error("creator-url-mismatch");
+    const posts = new Map();
+    const missing = new Set();
+    const labels = (profile.evidence ?? [])
+        .filter((e) => /^(?:文本|text|link) /.test(e.label))
+        .map((e) => e.label.replace(/^(?:文本|text|link) /, ""));
+    const meta = {
+        headerText: labels.join("\n"),
+        totalPostsText: labels.find((label) => /^[\d,.万亿KMB]+ 帖子$/.test(label)) ??
+            null,
+        missing: [],
+    };
+    let scrolls = 0, stagnant = 0, last;
+    const result = () => {
+        const selected = [...posts.values()].slice(0, target);
+        if (selected.length < target)
+            missing.add("creator-target-not-reached");
+        for (const post of selected) {
+            if (!post.datetime)
+                missing.add("absolute-time-missing");
+            if (post.needsExpansion)
+                missing.add("post-needs-expansion");
+            if (!post.body)
+                missing.add("post-body-missing");
+        }
+        if (profile.alerts?.length)
+            missing.add("platform-alert");
+        return {
+            profile: { ...profile, handle },
+            meta,
+            posts: selected,
+            complete: missing.size === 0,
+            missing: [...missing],
+            scrolls,
+            observedAt: new Date().toISOString(),
+        };
+    };
+    for (;;) {
+        const before = posts.size;
+        for (let offset = 0; offset < 250; offset += 5) {
+            last = await low.observe({ mode: "posts", offset, limit: 5 });
+            if (!expected.test(last.page ?? "") ||
+                last.needsStateCheck ||
+                last.alerts?.length) {
+                missing.add("creator-window-unconfirmed");
+                return { ...result(), alerts: last.alerts ?? [] };
+            }
+            for (const post of last.posts ?? []) {
+                if (post.id && post.author?.toLowerCase() === handle.toLowerCase())
+                    posts.set(post.id, {
+                        ...post,
+                        body: post.text,
+                        primary: `https://x.com/${post.author}/status/${post.id}`,
+                        links: (post.evidence ?? []).flatMap((e) => {
+                            const href = e.label.match(/Value: ((?:https?:\/\/)?(?:[\w.-]+\.[a-z]+)\/[^\s,]*)/i)?.[1];
+                            return href
+                                ? [href.startsWith("http") ? href : `https://${href}`]
+                                : [];
+                        }),
+                        metricDescriptions: (post.evidence ?? []).map((e) => e.label),
+                    });
+            }
+            if (!last.moreInDOM || posts.size >= target)
+                break;
+        }
+        stagnant = posts.size === before ? stagnant + 1 : 0;
+        if (posts.size >= target || scrolls >= maxScrolls || stagnant >= 3)
+            break;
+        // Restore a fresh visible window so the scroll index is never from an old read.
+        last = await low.observe({ mode: "posts", limit: 5 });
+        if (!expected.test(last.page ?? "") ||
+            last.needsStateCheck ||
+            last.alerts?.length) {
+            missing.add("creator-window-unconfirmed");
+            return result();
+        }
+        const control = last.posts
+            ?.flatMap((post) => post.evidence ?? [])
+            .find((entry) => /^link .*Value: x\.com\/\w+\/status\/\d+(?:,|$)/.test(entry.label));
+        if (!control) {
+            missing.add("native.creator-scroll-target");
+            break;
+        }
+        await low.act({
+            index: control.index,
+            operation: "scroll",
+            value: "down",
+            read: { mode: "posts", limit: 5 },
+        });
+        scrolls++;
+    }
+    return result();
+}

package/dist/creator.js

@@ -1,4 +1,4 @@
-import { readProfile } from "./readers.js";
+import { readProfile } from "./readers-profile.js";
 import { readXObservation } from "./observation.js";
 // Read-only DOM metadata. Counts retain the platform's displayed precision.
 export function readCreatorMeta() {

package/dist/diagnostics.d.ts

@@ -0,0 +1,11 @@
+/** Explicit lower-level diagnostics and legacy consumers. Normal tasks use the root. */
+export { createGrowthHarness } from "./growth.js";
+export { createBusinessHarness } from "./api.js";
+export { createFileRoundStore, HarnessConflict } from "./store.js";
+export { createXPlatform, xURL } from "./platform.js";
+export { createDOMXBrowser, createNativeXBrowser, readXSurface, atomicObservationCode, readXNetworkDiagnostics, } from "./browser.js";
+export { readXObservation } from "./observation.js";
+export * from "./readers.js";
+export { checkRound, readRound, runRoundCLI } from "./round-state.js";
+export { readCreatorMeta, readCreatorPostExtras } from "./creator.js";
+export type { BoundaryRecord } from "./boundary.js";

package/dist/diagnostics.js

@@ -0,0 +1,10 @@
+/** Explicit lower-level diagnostics and legacy consumers. Normal tasks use the root. */
+export { createGrowthHarness } from "./growth.js";
+export { createBusinessHarness } from "./api.js";
+export { createFileRoundStore, HarnessConflict } from "./store.js";
+export { createXPlatform, xURL } from "./platform.js";
+export { createDOMXBrowser, createNativeXBrowser, readXSurface, atomicObservationCode, readXNetworkDiagnostics, } from "./browser.js";
+export { readXObservation } from "./observation.js";
+export * from "./readers.js";
+export { checkRound, readRound, runRoundCLI } from "./round-state.js";
+export { readCreatorMeta, readCreatorPostExtras } from "./creator.js";

package/dist/growth-batch.d.ts

@@ -0,0 +1,8 @@
+import type { BoundaryRecord } from "./boundary.js";
+import type { GrowthDependencies } from "./growth-dependencies.js";
+export declare class FollowBatch {
+    #private;
+    constructor(dependencies: Pick<GrowthDependencies, "prepareActionsForCall" | "store" | "scope" | "stamp" | "clock" | "evidenceExists" | "executor" | "parallelRound" | "round">);
+    followBatch({ taskId, handles, preparedActions }?: any): Promise<BoundaryRecord>;
+}
+export declare function createFollowBatch(...args: ConstructorParameters<typeof FollowBatch>): FollowBatch;