@nextclaw/x-harness 0.1.0 → 0.2.0

package/dist/api.js

@@ -1,19 +1,80 @@
 import { createGrowthHarness } from "./growth.js";
 import { readResult, decisions, diagnostic, stableReason } from "./results.js";
-export function createBusinessHarness(dependencies) {
-    const { store } = dependencies;
-    const core = createGrowthHarness(dependencies);
-    const readCache = new Map();
-    // All public operations share the same error boundary. Full errors remain local proof.
-    async function invoke(operation, args) {
+export class BusinessHarness {
+    #store;
+    #core;
+    #readCache;
+    constructor(dependencies) {
+        this.verifyFollow = this.verifyFollow.bind(this);
+        this.followBatch = this.followBatch.bind(this);
+        this.verifyPublishedPost = this.verifyPublishedPost.bind(this);
+        this.verifySubmission = this.verifySubmission.bind(this);
+        this.followOne = this.followOne.bind(this);
+        this.replyToPost = this.replyToPost.bind(this);
+        this.publishPost = this.publishPost.bind(this);
+        this.runGrowthRound = this.runGrowthRound.bind(this);
+        this.inspectRound = this.inspectRound.bind(this);
+        this.inspectAccount = this.inspectAccount.bind(this);
+        this.readFeedback = this.readFeedback.bind(this);
+        this.readPerson = this.readPerson.bind(this);
+        this.readPost = this.readPost.bind(this);
+        this.searchSources = this.searchSources.bind(this);
+        this.readBookmarks = this.readBookmarks.bind(this);
+        this.readCreator = this.readCreator.bind(this);
+        const { store } = dependencies;
+        this.#store = store;
+        this.#core = createGrowthHarness(dependencies);
+        this.#readCache = new Map();
+    }
+    async invoke(operation, args) {
         try {
-            return await core[operation](args);
+            const raw = await this.#core[operation](args);
+            // Legacy core decisions can contain a human error without a diagnostic proof.
+            // Expose a bounded recovery route; consumers never need implementation source.
+            const errors = [
+                raw.reason,
+                ...(raw.decision ?? []).flatMap((d) => [
+                    d.reason,
+                    d.error,
+                ]),
+            ].filter((reason) => typeof reason === "string" && stableReason(reason) !== reason);
+            if (errors.length) {
+                const evidenceRef = await this.#store.recordProof({
+                    operation,
+                    error: errors[0],
+                    ...(errors.length > 1 ? { errors } : {}),
+                });
+                return {
+                    ...raw,
+                    ...(raw.reason ? { reason: stableReason(raw.reason) } : {}),
+                    evidenceRef,
+                    ...(raw.decision
+                        ? {
+                            decision: raw.decision.map((d) => ({
+                                ...d,
+                                reason: stableReason(d.reason),
+                            })),
+                        }
+                        : {}),
+                    diagnostic: {
+                        operation,
+                        category: "boundary",
+                        code: "harness-boundary-error",
+                        next: "inspect-local-proof",
+                        evidenceRef,
+                    },
+                };
+            }
+            return raw;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             let evidenceRef;
             try {
-                evidenceRef = await store.recordProof({ operation, error: message });
+                evidenceRef = await this.#store.recordProof({
+                    operation,
+                    error: message,
+                });
             }
             catch {
                 /* Evidence failure is explicit below. */
@@ -29,10 +90,19 @@ export function createBusinessHarness(dependencies) {
                 ...(evidenceRef
                     ? { evidenceRef }
                     : { missing: ["local-proof-unavailable"] }),
+                diagnostic: {
+                    operation,
+                    category: "boundary",
+                    code: evidenceRef
+                        ? "harness-boundary-error"
+                        : "evidence-store-unavailable",
+                    next: evidenceRef ? "inspect-local-proof" : "restore-proof-store",
+                    ...(evidenceRef ? { evidenceRef } : {}),
+                },
             };
         }
     }
-    async function read(operation, args = {}, mode = "receipt") {
+    async read(operation, args = {}, mode = "receipt") {
         if (!["receipt", "decision", "delta"].includes(mode))
             return {
                 status: "needsDecision",
@@ -40,7 +110,7 @@ export function createBusinessHarness(dependencies) {
                 reason: "read-mode-invalid",
             };
         // Always collect fresh evidence once. Projection, not a second browser call, chooses output.
-        const raw = await invoke(operation, { ...args, mode: "decision" });
+        const raw = await this.invoke(operation, { ...args, mode: "decision" });
         const output = readResult(operation, raw, mode);
         if (mode === "receipt")
             return output;
@@ -55,11 +125,11 @@ export function createBusinessHarness(dependencies) {
                 continue;
             }
             const key = JSON.stringify([operation, id]), value = JSON.stringify(entry);
-            if (readCache.get(key) === value)
+            if (this.#readCache.get(key) === value)
                 unchangedIds.push(id);
             else
                 changed.push(entry);
-            readCache.set(key, value);
+            this.#readCache.set(key, value);
         }
         // Creator metadata changes independently from the post collection.
         if (operation === "readCreator") {
@@ -68,9 +138,9 @@ export function createBusinessHarness(dependencies) {
                     continue;
                 const key = JSON.stringify([operation, name, args.handle]);
                 const value = JSON.stringify(output[name], (k, v) => k === "observedAt" ? undefined : v);
-                if (mode === "delta" && readCache.get(key) === value)
+                if (mode === "delta" && this.#readCache.get(key) === value)
                     delete output[name];
-                readCache.set(key, value);
+                this.#readCache.set(key, value);
             }
         }
         // A decision has delivered complete evidence and seeds the next delta.
@@ -87,8 +157,8 @@ export function createBusinessHarness(dependencies) {
         output.unchangedIds = unchangedIds;
         return output;
     }
-    async function compactRound(operation, args) {
-        const raw = await invoke(operation, args);
+    async compactRound(operation, args) {
+        const raw = await this.invoke(operation, args);
         const out = {
             status: raw.status,
             taskId: args.taskId,
@@ -112,6 +182,9 @@ export function createBusinessHarness(dependencies) {
             out.decision = issues;
         if (raw.evidenceRef)
             out.evidenceRef = raw.evidenceRef;
+        const d = diagnostic(raw.diagnostic);
+        if (d)
+            out.diagnostic = d;
         if (Array.isArray(raw.settlementErrors))
             out.settlementErrors = raw.settlementErrors
                 .map(stableReason)
@@ -132,11 +205,11 @@ export function createBusinessHarness(dependencies) {
             };
         return out;
     }
-    async function single(operation, args, selector) {
-        const raw = await invoke(operation, args);
+    async single(operation, args, selector) {
+        const raw = await this.invoke(operation, args);
         let snapshot;
         try {
-            snapshot = await store.load();
+            snapshot = await this.#store.load();
         }
         catch {
             return {
@@ -197,60 +270,90 @@ export function createBusinessHarness(dependencies) {
             out.diagnostic = d;
         return out;
     }
-    return {
-        readCreator: (args) => read("readCreator", args, args.mode),
-        readBookmarks: (args) => read("readBookmarks", args, args.mode),
-        searchSources: (args) => read("searchSources", args, args.mode),
-        readPost: ({ target, mode }) => read("readPost", target, mode),
-        readPerson: ({ target, mode }) => read("readPerson", target, mode),
-        readFeedback: (args) => read("readFeedback", args, args.mode),
-        inspectAccount: (args = {}) => read("inspectAccount", args, args.mode),
-        inspectRound: (args) => compactRound("inspectRound", args),
-        runGrowthRound: (args) => compactRound("runGrowthRound", args),
-        publishPost: (args) => single("publishPost", args, (a) => a.kind === "original" && a.draftPath === args.draftPath),
-        replyToPost: (args) => single("replyToPost", args, (a) => a.kind === "reply" &&
-            a.postId === args.postId &&
-            a.text === args.text),
-        followOne: (args) => single("followOne", args, (a) => a.kind === "follow" &&
-            a.handle?.toLowerCase() === args.handle.toLowerCase()),
-        verifySubmission: (args) => single("verifySubmission", args, (a) => a.id === args.actionId),
-        verifyPublishedPost: (args) => single("verifyPublishedPost", args, (a) => a.kind === "original" && a.draftPath === args.draftPath),
-        followBatch: async (args) => {
-            const raw = await invoke("followBatch", args);
-            const output = {
-                status: raw.status ?? (raw.mayEnd ? "verified" : "needsDecision"),
-                taskId: args.taskId,
-                planned: raw.planned ?? args.handles.length,
-                attempted: raw.attempted ?? 0,
-                verified: raw.verifiedThisCall ?? 0,
-                unknown: raw.unknownInBatch ?? 0,
-                remaining: raw.remaining ?? args.handles.length,
-                mayEnd: raw.mayEnd === true,
-            };
-            if (raw.batchId)
-                output.batchId = raw.batchId;
-            if (raw.evidenceRef)
-                output.evidenceRef = raw.evidenceRef;
-            const issues = decisions(raw.decision);
-            if (raw.reason)
-                issues.push({ reason: raw.reason, status: "needsDecision" });
-            if (raw.missing)
-                issues.push({ missing: raw.missing });
-            if (issues.length)
-                output.decision = issues;
-            return output;
-        },
-        verifyFollow: async (args) => {
-            const raw = await invoke("verifyFollow", {
-                ...args,
-                mode: args.mode ?? "receipt",
-            });
-            const out = readResult("verifyFollow", raw, "receipt");
-            out.handle = args.handle;
-            out.verified = raw.verified === true;
-            if (args.mode === "decision" && raw.observation)
-                out.person = readResult("readPerson", raw.observation, "decision").person;
-            return out;
-        },
-    };
+    readCreator(args) {
+        return this.read("readCreator", args, args.mode);
+    }
+    readBookmarks(args) {
+        return this.read("readBookmarks", args, args.mode);
+    }
+    searchSources(args) {
+        return this.read("searchSources", args, args.mode);
+    }
+    readPost({ target, mode, }) {
+        return this.read("readPost", target, mode);
+    }
+    readPerson({ target, mode, }) {
+        return this.read("readPerson", target, mode);
+    }
+    readFeedback(args) {
+        return this.read("readFeedback", args, args.mode);
+    }
+    inspectAccount(args = {}) {
+        return this.read("inspectAccount", args, args.mode);
+    }
+    inspectRound(args) {
+        return this.compactRound("inspectRound", args);
+    }
+    runGrowthRound(args) {
+        return this.compactRound("runGrowthRound", args);
+    }
+    publishPost(args) {
+        return this.single("publishPost", args, (a) => a.kind === "original" && a.draftPath === args.draftPath);
+    }
+    replyToPost(args) {
+        return this.single("replyToPost", args, (a) => a.kind === "reply" && a.postId === args.postId && a.text === args.text);
+    }
+    followOne(args) {
+        return this.single("followOne", args, (a) => a.kind === "follow" &&
+            a.handle?.toLowerCase() === args.handle.toLowerCase());
+    }
+    verifySubmission(args) {
+        return this.single("verifySubmission", args, (a) => a.id === args.actionId);
+    }
+    verifyPublishedPost(args) {
+        return this.single("verifyPublishedPost", args, (a) => a.kind === "original" && a.draftPath === args.draftPath);
+    }
+    async followBatch(args) {
+        const raw = await this.invoke("followBatch", args);
+        const output = {
+            status: raw.status ?? (raw.mayEnd ? "verified" : "needsDecision"),
+            taskId: args.taskId,
+            planned: raw.planned ?? args.handles.length,
+            attempted: raw.attempted ?? 0,
+            verified: raw.verifiedThisCall ?? 0,
+            unknown: raw.unknownInBatch ?? 0,
+            remaining: raw.remaining ?? args.handles.length,
+            mayEnd: raw.mayEnd === true,
+        };
+        if (raw.batchId)
+            output.batchId = raw.batchId;
+        if (raw.evidenceRef)
+            output.evidenceRef = raw.evidenceRef;
+        const d = diagnostic(raw.diagnostic);
+        if (d)
+            output.diagnostic = d;
+        const issues = decisions(raw.decision);
+        if (raw.reason)
+            issues.push({ reason: raw.reason, status: "needsDecision" });
+        if (raw.missing)
+            issues.push({ missing: raw.missing });
+        if (issues.length)
+            output.decision = issues;
+        return output;
+    }
+    async verifyFollow(args) {
+        const raw = await this.invoke("verifyFollow", {
+            ...args,
+            mode: args.mode ?? "receipt",
+        });
+        const out = readResult("verifyFollow", raw, "receipt");
+        out.handle = args.handle;
+        out.verified = raw.verified === true;
+        if (args.mode === "decision" && raw.observation)
+            out.person = readResult("readPerson", raw.observation, "decision").person;
+        return out;
+    }
+}
+export function createBusinessHarness(...args) {
+    return new BusinessHarness(...args);
 }

package/dist/boundary.js

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

package/dist/browser-common.d.ts

@@ -1,4 +1,15 @@
 export declare const plain: (label: any) => any;
 export declare const valueOf: (label: any) => any;
 export declare const missingMethods: (object: any, names: any) => any;
+/** One instance owns one browser session and its concurrency boundary. */
+export declare class SerializedBrowser {
+    #private;
+    collectCreator?: (args: unknown) => Promise<any>;
+    constructor(port: any);
+    private run;
+    observe(query: any): Promise<any>;
+    act(command: any): Promise<any>;
+    screenshot(): Promise<any>;
+    private collect;
+}
 export declare function serialized(port: any): any;

package/dist/browser-common.js

@@ -1,29 +1,45 @@
 export const plain = (label) => label.replace(/^(?:按钮|link|文本输入区域|文本输入区|文本区域|文本栏) /, "");
 export const valueOf = (label) => label.match(/, Value: ([\s\S]*)$/)?.[1] ?? null;
 export const missingMethods = (object, names) => names.filter((name) => typeof object?.[name] !== "function");
-export function serialized(port) {
-    let busy = false;
-    const run = async (fn) => {
-        if (busy)
+/** One instance owns one browser session and its concurrency boundary. */
+export class SerializedBrowser {
+    #busy = false;
+    #port;
+    collectCreator;
+    constructor(port) {
+        this.#port = port;
+        Object.assign(this, port);
+        this.observe = SerializedBrowser.prototype.observe.bind(this);
+        this.act = SerializedBrowser.prototype.act.bind(this);
+        this.screenshot = SerializedBrowser.prototype.screenshot.bind(this);
+        if (port.collectCreator)
+            this.collectCreator = this.collect.bind(this);
+    }
+    async run(fn) {
+        if (this.#busy)
             throw new Error("浏览器harness操作进行中，禁止并发");
-        busy = true;
+        this.#busy = true;
         try {
             return await fn();
         }
         finally {
-            busy = false;
+            this.#busy = false;
         }
-    };
-    return {
-        ...port,
-        observe: (query) => run(() => port.observe(query)),
-        act: (command) => run(() => port.act(command)),
-        screenshot: () => run(() => port.screenshot()),
-        ...(port.collectCreator
-            ? {
-                collectCreator: (args) => run(() => port.collectCreator(args)),
-            }
-            : {}),
-    };
+    }
+    observe(query) {
+        return this.run(() => this.#port.observe(query));
+    }
+    act(command) {
+        return this.run(() => this.#port.act(command));
+    }
+    screenshot() {
+        return this.run(() => this.#port.screenshot());
+    }
+    collect(args) {
+        return this.run(() => this.#port.collectCreator(args));
+    }
+}
+export function serialized(port) {
+    return new SerializedBrowser(port);
 }
 // AX indices never cross this port. Only semantic commands reach the platform layer.

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

@@ -0,0 +1,9 @@
+import type { DOMDependencies } from "./browser-dom-dependencies.js";
+export declare class DOMCapabilities {
+    #private;
+    constructor(dependencies: Pick<DOMDependencies, "tab" | "nativeSubmit">);
+    capabilities(operation: any): any;
+    private creatorCapabilities;
+    private collectionCapabilities;
+}
+export declare function createDOMCapabilities(...args: ConstructorParameters<typeof DOMCapabilities>): DOMCapabilities;

package/dist/browser-dom-capabilities.js

@@ -0,0 +1,131 @@
+import { missingMethods } from "./browser-common.js";
+export class DOMCapabilities {
+    #tab;
+    #nativeSubmit;
+    constructor(dependencies) {
+        this.capabilities = this.capabilities.bind(this);
+        const { tab, nativeSubmit } = dependencies;
+        this.#tab = tab;
+        this.#nativeSubmit = nativeSubmit;
+    }
+    capabilities(operation) {
+        const base = missingMethods(this.#tab?.playwright, ["evaluate"]);
+        if (operation === "readCreator") {
+            return this.creatorCapabilities(base, operation);
+        }
+        if (["readBookmarks", "searchSources", "readFeedback"].includes(operation)) {
+            return this.collectionCapabilities(base, operation);
+        }
+        if (operation !== "read")
+            base.push(...missingMethods(this.#tab?.playwright, ["getByRole"]), ...missingMethods(this.#tab, ["goto"]));
+        if (operation !== "read" &&
+            typeof this.#tab?.playwright?.getByRole === "function") {
+            base.push(...missingMethods(this.#tab.playwright.getByRole("button"), [
+                "count",
+                "click",
+            ]));
+            if (operation !== "submitFollow")
+                base.push(...missingMethods(this.#tab.playwright.getByRole("textbox"), [
+                    "count",
+                    "fill",
+                ]));
+            if (["submitPost", "submitReply"].includes(operation)) {
+                base.push(...missingMethods(this.#tab.playwright, [
+                    "locator",
+                    "waitForLoadState",
+                ]));
+                base.push(...missingMethods(this.#tab.playwright.getByRole("button"), [
+                    "and",
+                    "waitFor",
+                ]));
+            }
+        }
+        if (operation === "refreshPerson" || operation === "refreshPosts") {
+            base.push(...missingMethods(this.#tab, ["reload"]));
+            base.push(...missingMethods(this.#tab?.playwright, ["waitForLoadState"]));
+            if (typeof this.#tab?.playwright?.getByRole === "function")
+                base.push(...missingMethods(this.#tab.playwright.getByRole("button"), [
+                    "waitFor",
+                ]));
+        }
+        if (operation === "openOwnPostMenu") {
+            base.push(...missingMethods(this.#tab?.playwright, ["locator"]));
+            if (typeof this.#tab?.playwright?.getByRole === "function")
+                base.push(...missingMethods(this.#tab.playwright.getByRole("article"), [
+                    "filter",
+                    "getByRole",
+                ]));
+        }
+        if (operation === "submitEditedPost") {
+            base.push(...missingMethods(this.#tab?.playwright, ["waitForLoadState"]));
+            if (typeof this.#tab?.playwright?.getByRole === "function")
+                base.push(...missingMethods(this.#tab.playwright.getByRole("button"), [
+                    "press",
+                ]));
+        }
+        if (operation === "attachAssets")
+            base.push(...missingMethods(this.#tab?.playwright, [
+                "waitForEvent",
+                "getByLabel",
+                "getByPlaceholder",
+            ]));
+        if (this.#nativeSubmit && ["submitPost", "submitReply"].includes(operation))
+            base.push(...missingMethods(this.#tab, ["getAXState", "click"]));
+        return base;
+    }
+    creatorCapabilities(base, operation) {
+        base.push(...missingMethods(this.#tab, [
+            "url",
+            "goto",
+            "reload",
+            "getAXState",
+            "scroll",
+        ]));
+        base.push(...missingMethods(this.#tab.playwright, ["locator"]));
+        if (typeof this.#tab.playwright?.locator === "function") {
+            const article = this.#tab.playwright.locator("article");
+            base.push(...missingMethods(article, ["first", "getByRole"]));
+            if (typeof article.first === "function")
+                base.push(...missingMethods(article.first(), ["waitFor"]));
+            if (typeof article.getByRole === "function")
+                base.push(...missingMethods(article.getByRole("button", { name: "显示更多", exact: true }), ["all"]));
+        }
+        return base;
+    }
+    collectionCapabilities(base, operation) {
+        base.push(...missingMethods(this.#tab, ["goto"]));
+        base.push(...missingMethods(this.#tab?.playwright, ["getByRole", "waitForURL"]));
+        if (typeof this.#tab?.playwright?.getByRole === "function")
+            base.push(...missingMethods(this.#tab.playwright.getByRole("article"), [
+                "first",
+                "waitFor",
+            ]));
+        if (operation !== "readFeedback") {
+            base.push(...missingMethods(this.#tab?.playwright, [
+                "getByRole",
+                "getByText",
+                "locator",
+                "waitForURL",
+            ]));
+            if (typeof this.#tab?.playwright?.getByRole === "function")
+                base.push(...missingMethods(this.#tab.playwright.getByRole("main"), [
+                    "count",
+                    "click",
+                    "first",
+                    "waitFor",
+                ]));
+            if (typeof this.#tab?.playwright?.locator === "function")
+                base.push(...missingMethods(this.#tab.playwright.locator("a"), [
+                    "count",
+                    "filter",
+                    "press",
+                ]));
+            if (typeof this.#tab?.playwright?.getByText === "function")
+                base.push(...missingMethods(this.#tab.playwright.getByText(""), ["waitFor"]));
+        }
+        return base;
+    }
+}
+export function createDOMCapabilities(...args) {
+    return new DOMCapabilities(...args);
+}

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

@@ -0,0 +1,16 @@
+export interface DOMSession {
+    current?: any;
+    replyBinding?: any;
+    refreshNotice?: any;
+    editBinding?: any;
+}
+export interface DOMDependencies {
+    tab: any;
+    nativeSubmit: boolean;
+    readDOM: any;
+    session: DOMSession;
+    submitAX: any;
+    observe: (query: any) => Promise<any>;
+    locator: (role: any, name?: any) => any;
+    unique: (loc: any) => Promise<any>;
+}

package/dist/browser-dom-dependencies.js

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