@nextclaw/x-harness 0.1.0 → 0.2.0

package/cli/main.js

@@ -1,207 +1,251 @@
 #!/usr/bin/env node
 import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, renameSync, rmSync, cpSync, mkdtempSync, openSync, closeSync, unlinkSync, readdirSync, } from "node:fs";
-import { join, resolve, dirname } from "node:path";
+import { join, resolve, dirname, relative } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { randomUUID } from "node:crypto";
-const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const release = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
-const args = process.argv.slice(2);
-const command = args.shift() ?? "help";
-const flags = new Map();
-for (let i = 0; i < args.length; i += 2) {
-    const key = args[i], value = args[i + 1];
-    if (!["--target", "--home", "--directory", "--account"].includes(key) ||
-        !value ||
-        value.startsWith("--") ||
-        flags.has(key))
-        throw Error(`Invalid argument: ${key}`);
-    flags.set(key, value);
-}
-const customHome = flags.get("--home");
-const home = resolve(customHome ?? join(homedir(), ".x-harness"));
 const readJSON = (path) => JSON.parse(readFileSync(path, "utf8"));
 const output = (value) => process.stdout.write(JSON.stringify(value, null, 2) + "\n");
-const marker = (path, file) => existsSync(join(path, file)) &&
-    [release.name, "@peiiii/x-harness"].includes(readJSON(join(path, file)).managedBy);
-function guard(path, file) {
-    if (existsSync(path) &&
-        (lstatSync(path).isSymbolicLink() || !marker(path, file)))
-        throw Error(`Refusing to overwrite unmanaged directory: ${path}`);
-}
-function skillPath(target) {
-    if (!["codex", "claude"].includes(target))
-        throw Error("Target must be codex or claude");
-    return customHome
-        ? join(home, "skills", target, "x-harness")
-        : join(homedir(), `.${target}`, "skills", "x-harness");
-}
-function location() {
-    return {
-        version: release.version,
-        moduleURL: pathToFileURL(join(packageRoot, "dist", "index.js")).href,
-        cliPath: fileURLToPath(import.meta.url),
-        home,
-    };
-}
-function setup() {
-    const target = flags.get("--target") ?? "codex";
-    const stateFile = join(home, "installation.json");
-    if (!existsSync(stateFile) &&
-        readdirSync(home).some((name) => name !== ".installation.lock"))
-        throw Error(`Unmanaged installation home: ${home}`);
-    const previous = existsSync(stateFile)
-        ? readJSON(stateFile)
-        : { managedBy: release.name, targets: [] };
-    if (![release.name, "@peiiii/x-harness"].includes(previous.managedBy))
-        throw Error("Unmanaged installation state");
-    const targets = [...new Set([...previous.targets, target])];
-    const runtime = join(home, "runtime");
-    guard(runtime, ".x-harness-managed.json");
-    for (const t of targets)
-        guard(skillPath(t), ".x-harness-managed.json");
-    mkdirSync(home, { recursive: true, mode: 0o700 });
-    const stage = mkdtempSync(join(home, ".setup-"));
-    const backup = join(home, "backups", `${Date.now()}-${randomUUID()}`);
-    const changes = [];
-    let completed = false;
-    try {
+class XHarnessCLI {
+    #packageRoot;
+    #release;
+    #args;
+    #command;
+    #flags;
+    #customHome;
+    #home;
+    constructor(argv = process.argv.slice(2)) {
+        this.#packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+        this.#release = JSON.parse(readFileSync(join(this.#packageRoot, "package.json"), "utf8"));
+        this.#args = argv.slice();
+        this.#command = this.#args.shift() ?? "help";
+        this.#flags = new Map();
+        for (let i = 0; i < this.#args.length; i += 2) {
+            const key = this.#args[i], value = this.#args[i + 1];
+            if (!["--target", "--home", "--directory", "--account"].includes(key) ||
+                !value ||
+                value.startsWith("--") ||
+                this.#flags.has(key))
+                throw Error(`Invalid argument: ${key}`);
+            this.#flags.set(key, value);
+        }
+        this.#customHome = this.#flags.get("--home");
+        this.#home = resolve(this.#customHome ?? join(homedir(), ".x-harness"));
+    }
+    marker(path, file) {
+        return (existsSync(join(path, file)) &&
+            [this.#release.name, "@peiiii/x-harness"].includes(readJSON(join(path, file)).managedBy));
+    }
+    guard(path, file) {
+        if (existsSync(path) &&
+            (lstatSync(path).isSymbolicLink() || !this.marker(path, file)))
+            throw Error(`Refusing to overwrite unmanaged directory: ${path}`);
+    }
+    skillPath(target) {
+        if (!["codex", "claude"].includes(target))
+            throw Error("Target must be codex or claude");
+        return this.#customHome
+            ? join(this.#home, "skills", target, "x-harness")
+            : join(homedir(), `.${target}`, "skills", "x-harness");
+    }
+    location() {
+        return {
+            version: this.#release.version,
+            moduleURL: pathToFileURL(join(this.#packageRoot, "dist", "index.js"))
+                .href,
+            cliPath: fileURLToPath(import.meta.url),
+            home: this.#home,
+        };
+    }
+    stageRuntime(stage, runtime) {
         const stagedRuntime = join(stage, "runtime");
-        mkdirSync(stagedRuntime);
-        const installedRoot = join(stagedRuntime, "node_modules", ...release.name.split("/"));
-        // npx has already fetched this release. Persist its dependency-free runtime once.
-        cpSync(packageRoot, installedRoot, { recursive: true });
-        if (readJSON(join(installedRoot, "package.json")).version !== release.version)
+        const suffix = join("versions", this.#release.version, "node_modules", ...this.#release.name.split("/"));
+        const installedRoot = join(stagedRuntime, suffix);
+        cpSync(this.#packageRoot, installedRoot, { recursive: true });
+        if (readJSON(join(installedRoot, "package.json")).version !==
+            this.#release.version)
             throw Error("Installed version mismatch");
-        const metadata = { managedBy: release.name, version: release.version };
-        writeFileSync(join(stagedRuntime, ".x-harness-managed.json"), JSON.stringify(metadata));
-        const finalRoot = join(runtime, "node_modules", ...release.name.split("/"));
-        const installs = [{ src: stagedRuntime, dest: runtime, key: "runtime" }];
-        for (const t of targets) {
-            const stagedSkill = join(stage, `skill-${t}`);
-            cpSync(join(installedRoot, "skill"), stagedSkill, { recursive: true });
-            const content = readFileSync(join(stagedSkill, "SKILL.md"), "utf8")
-                .replaceAll("{{MODULE_URL}}", pathToFileURL(join(finalRoot, "dist", "index.js")).href)
-                .replaceAll("{{CLI_PATH}}", join(finalRoot, "cli", "main.js"));
-            writeFileSync(join(stagedSkill, "SKILL.md"), content);
-            writeFileSync(join(stagedSkill, ".x-harness-managed.json"), JSON.stringify(metadata));
-            installs.push({
-                src: stagedSkill,
-                dest: skillPath(t),
-                key: `skill-${t}`,
+        const finalRoot = join(runtime, suffix);
+        const stableRoot = join(stagedRuntime, "node_modules", ...this.#release.name.split("/"));
+        const stableCLI = join(runtime, "node_modules", ...this.#release.name.split("/"), "cli", "main.js");
+        mkdirSync(join(stableRoot, "cli"), { recursive: true });
+        writeFileSync(join(stableRoot, "package.json"), JSON.stringify({ type: "module" }));
+        const entry = relative(dirname(stableCLI), join(finalRoot, "cli", "main.js"))
+            .split("\\")
+            .join("/");
+        writeFileSync(join(stableRoot, "cli", "main.js"), `#!/usr/bin/env node\nawait import(new URL(${JSON.stringify(entry)}, import.meta.url));\n`);
+        return { stagedRuntime, installedRoot, finalRoot, stableCLI };
+    }
+    setup() {
+        const target = this.#flags.get("--target") ?? "codex";
+        const stateFile = join(this.#home, "installation.json");
+        if (!existsSync(stateFile) &&
+            readdirSync(this.#home).some((name) => name !== ".installation.lock"))
+            throw Error(`Unmanaged installation home: ${this.#home}`);
+        const previous = existsSync(stateFile)
+            ? readJSON(stateFile)
+            : { managedBy: this.#release.name, targets: [] };
+        if (![this.#release.name, "@peiiii/x-harness"].includes(previous.managedBy))
+            throw Error("Unmanaged installation state");
+        const targets = [
+            ...new Set([...previous.targets, target]),
+        ];
+        const runtime = join(this.#home, "runtime");
+        this.guard(runtime, ".x-harness-managed.json");
+        for (const t of targets)
+            this.guard(this.skillPath(t), ".x-harness-managed.json");
+        mkdirSync(this.#home, { recursive: true, mode: 0o700 });
+        const stage = mkdtempSync(join(this.#home, ".setup-"));
+        const backup = join(this.#home, "backups", `${Date.now()}-${randomUUID()}`);
+        const changes = [];
+        let completed = false;
+        try {
+            // Persist npx's already fetched runtime once; versioned URLs invalidate the whole module graph.
+            const { stagedRuntime, installedRoot, finalRoot, stableCLI } = this.stageRuntime(stage, runtime);
+            const metadata = {
+                managedBy: this.#release.name,
+                version: this.#release.version,
+            };
+            writeFileSync(join(stagedRuntime, ".x-harness-managed.json"), JSON.stringify(metadata));
+            const installs = [{ src: stagedRuntime, dest: runtime, key: "runtime" }];
+            for (const t of targets) {
+                const stagedSkill = join(stage, `skill-${t}`);
+                cpSync(join(installedRoot, "skill"), stagedSkill, { recursive: true });
+                const content = readFileSync(join(stagedSkill, "SKILL.md"), "utf8")
+                    .replaceAll("{{MODULE_URL}}", pathToFileURL(join(finalRoot, "dist", "index.js")).href)
+                    .replaceAll("{{CLI_PATH}}", stableCLI);
+                writeFileSync(join(stagedSkill, "SKILL.md"), content);
+                writeFileSync(join(stagedSkill, ".x-harness-managed.json"), JSON.stringify(metadata));
+                installs.push({
+                    src: stagedSkill,
+                    dest: this.skillPath(t),
+                    key: `skill-${t}`,
+                });
+            }
+            // Install/download succeeds before replacing either managed artifact.
+            for (const item of installs) {
+                const saved = join(backup, item.key), hadOld = existsSync(item.dest);
+                mkdirSync(dirname(item.dest), { recursive: true });
+                if (hadOld) {
+                    mkdirSync(backup, { recursive: true });
+                    renameSync(item.dest, saved);
+                }
+                changes.push({ dest: item.dest, backup: saved, hadOld });
+                renameSync(item.src, item.dest);
+            }
+            const state = {
+                ...metadata,
+                targets,
+                updatedAt: new Date().toISOString(),
+            };
+            const nextState = join(stage, "installation.json");
+            writeFileSync(nextState, JSON.stringify(state, null, 2));
+            renameSync(nextState, stateFile);
+            completed = true;
+            output({
+                status: "installed",
+                ...state,
+                moduleURL: pathToFileURL(join(finalRoot, "dist", "index.js")).href,
+                cliPath: stableCLI,
+                skillPaths: targets.map(this.skillPath.bind(this)),
+                backup: changes.some((c) => c.hadOld) ? backup : null,
+                next: "Start a fresh module binding using the installed x-harness Skill.",
             });
         }
-        // Install/download succeeds before replacing either managed artifact.
-        for (const item of installs) {
-            const saved = join(backup, item.key), hadOld = existsSync(item.dest);
-            mkdirSync(dirname(item.dest), { recursive: true });
-            if (hadOld) {
-                mkdirSync(backup, { recursive: true });
-                renameSync(item.dest, saved);
-            }
-            changes.push({ dest: item.dest, backup: saved, hadOld });
-            renameSync(item.src, item.dest);
+        finally {
+            if (!completed)
+                for (const change of changes.reverse()) {
+                    rmSync(change.dest, { recursive: true, force: true });
+                    if (change.hadOld)
+                        renameSync(change.backup, change.dest);
+                }
+            rmSync(stage, { recursive: true, force: true });
         }
-        const state = { ...metadata, targets, updatedAt: new Date().toISOString() };
-        const nextState = join(stage, "installation.json");
-        writeFileSync(nextState, JSON.stringify(state, null, 2));
-        renameSync(nextState, stateFile);
-        completed = true;
-        output({
-            status: "installed",
-            ...state,
-            moduleURL: pathToFileURL(join(finalRoot, "dist", "index.js")).href,
-            cliPath: join(finalRoot, "cli", "main.js"),
-            skillPaths: targets.map(skillPath),
-            backup: changes.some((c) => c.hadOld) ? backup : null,
-            next: "Start a fresh module binding using the installed x-harness Skill.",
-        });
     }
-    finally {
-        if (!completed)
-            for (const change of changes.reverse()) {
-                rmSync(change.dest, { recursive: true, force: true });
-                if (change.hadOld)
-                    renameSync(change.backup, change.dest);
-            }
-        rmSync(stage, { recursive: true, force: true });
-    }
-}
-function init() {
-    const directory = resolve(flags.get("--directory") ?? "./x-workspace");
-    const account = (flags.get("--account") ?? "").replace(/^@/, "");
-    if (!/^[a-zA-Z0-9_]{1,15}$/.test(account))
-        throw Error("Provide your own X handle with --account");
-    const configPath = join(directory, "x-harness.json");
-    if (existsSync(configPath)) {
-        const config = readJSON(configPath);
-        if (config.accountHandle !== account)
-            throw Error("Existing workspace belongs to a different account");
-        output({ status: "existing", configPath, ...config });
-        return;
+    init() {
+        const directory = resolve(this.#flags.get("--directory") ?? "./x-workspace");
+        const account = (this.#flags.get("--account") ?? "").replace(/^@/, "");
+        if (!/^[a-zA-Z0-9_]{1,15}$/.test(account))
+            throw Error("Provide your own X handle with --account");
+        const configPath = join(directory, "x-harness.json");
+        if (existsSync(configPath)) {
+            const config = readJSON(configPath);
+            if (config.accountHandle !== account)
+                throw Error("Existing workspace belongs to a different account");
+            output({ status: "existing", configPath, ...config });
+            return;
+        }
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const ledgerPath = join(directory, "round.md"), proofDirectory = join(directory, "proofs");
+        if (existsSync(ledgerPath))
+            throw Error("Existing ledger is unmanaged; use its configuration instead of overwriting");
+        const taskId = `x-${randomUUID()}`;
+        const state = {
+            batchId: taskId,
+            status: "RUNNING",
+            updatedAt: new Date().toISOString(),
+            accountHandle: account,
+            items: ["follow", "original", "reply"].map((kind) => ({
+                kind,
+                planned: 0,
+                verified: 0,
+                unknown: 0,
+                actionable: true,
+            })),
+            execution: { owner: "harness", exclusive: true },
+            attempts: [],
+            actions: [],
+        };
+        mkdirSync(proofDirectory);
+        writeFileSync(ledgerPath, `# @${account} · Your X workspace\n\n\`\`\`x-round-state\n${JSON.stringify(state, null, 2)}\n\`\`\`\n`, { flag: "wx", mode: 0o600 });
+        const config = {
+            accountHandle: account,
+            taskId,
+            ledgerPath,
+            proofDirectory,
+        };
+        writeFileSync(configPath, JSON.stringify(config, null, 2), {
+            flag: "wx",
+            mode: 0o600,
+        });
+        output({ status: "initialized", configPath, ...config });
     }
-    mkdirSync(directory, { recursive: true, mode: 0o700 });
-    const ledgerPath = join(directory, "round.md"), proofDirectory = join(directory, "proofs");
-    if (existsSync(ledgerPath))
-        throw Error("Existing ledger is unmanaged; use its configuration instead of overwriting");
-    const taskId = `x-${randomUUID()}`;
-    const state = {
-        batchId: taskId,
-        status: "RUNNING",
-        updatedAt: new Date().toISOString(),
-        accountHandle: account,
-        items: ["follow", "original", "reply"].map((kind) => ({
-            kind,
-            planned: 0,
-            verified: 0,
-            unknown: 0,
-            actionable: true,
-        })),
-        execution: { owner: "harness", exclusive: true },
-        attempts: [],
-        actions: [],
-    };
-    mkdirSync(proofDirectory);
-    writeFileSync(ledgerPath, `# @${account} · Your X workspace\n\n\`\`\`x-round-state\n${JSON.stringify(state, null, 2)}\n\`\`\`\n`, { flag: "wx", mode: 0o600 });
-    const config = { accountHandle: account, taskId, ledgerPath, proofDirectory };
-    writeFileSync(configPath, JSON.stringify(config, null, 2), {
-        flag: "wx",
-        mode: 0o600,
-    });
-    output({ status: "initialized", configPath, ...config });
-}
-try {
-    if (["setup", "update"].includes(command)) {
-        mkdirSync(home, { recursive: true, mode: 0o700 });
-        const lockPath = join(home, ".installation.lock");
-        const lock = openSync(lockPath, "wx", 0o600);
+    run() {
         try {
-            setup();
+            if (["setup", "update"].includes(this.#command)) {
+                mkdirSync(this.#home, { recursive: true, mode: 0o700 });
+                const lockPath = join(this.#home, ".installation.lock");
+                const lock = openSync(lockPath, "wx", 0o600);
+                try {
+                    this.setup();
+                }
+                finally {
+                    closeSync(lock);
+                    unlinkSync(lockPath);
+                }
+            }
+            else if (this.#command === "init")
+                this.init();
+            else if (this.#command === "location")
+                output(this.location());
+            else if (this.#command === "help")
+                output({
+                    setup: "npx @nextclaw/x-harness@latest setup --target codex",
+                    update: "npx @nextclaw/x-harness@latest update --target codex",
+                    init: "node <cliPath> init --directory ./x-workspace --account YOUR_HANDLE",
+                    targets: ["codex", "claude"],
+                    requires: "Node 22+; compatible CUA browser host and your own X login",
+                });
+            else
+                throw Error(`Unknown command: ${this.#command}`);
         }
-        finally {
-            closeSync(lock);
-            unlinkSync(lockPath);
+        catch (error) {
+            process.stderr.write(JSON.stringify({
+                status: "failed",
+                reason: error instanceof Error ? error.message : String(error),
+            }) + "\n");
+            process.exitCode = 1;
         }
     }
-    else if (command === "init")
-        init();
-    else if (command === "location")
-        output(location());
-    else if (command === "help")
-        output({
-            setup: "npx @nextclaw/x-harness@latest setup --target codex",
-            update: "npx @nextclaw/x-harness@latest update --target codex",
-            init: "node <cliPath> init --directory ./x-workspace --account YOUR_HANDLE",
-            targets: ["codex", "claude"],
-            requires: "Node 22+; compatible CUA browser host and your own X login",
-        });
-    else
-        throw Error(`Unknown command: ${command}`);
-}
-catch (error) {
-    process.stderr.write(JSON.stringify({
-        status: "failed",
-        reason: error instanceof Error ? error.message : String(error),
-    }) + "\n");
-    process.exitCode = 1;
 }
+new XHarnessCLI().run();

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import type { XGrowthHarness } from "./types.js";
+import type { ActionResult, ReadMode, ReadResult, RoundResult, XGrowthHarness, BatchResult } from "./types.js";
 import type { BoundaryRecord } from "./boundary.js";
 /** Internal dependencies; only the normal X factory is exported from the root. */
 export interface BusinessDependencies {
@@ -7,4 +7,58 @@ export interface BusinessDependencies {
     clock?: () => number;
     executor?: BoundaryRecord;
 }
-export declare function createBusinessHarness(dependencies: BusinessDependencies): XGrowthHarness;
+export declare class BusinessHarness implements XGrowthHarness {
+    #private;
+    constructor(dependencies: BusinessDependencies);
+    private invoke;
+    private read;
+    private compactRound;
+    private single;
+    readCreator(args: import("./types.js").CreatorOptions): Promise<ReadResult>;
+    readBookmarks(args: import("./types.js").BookmarkOptions): Promise<ReadResult>;
+    searchSources(args: import("./types.js").SearchOptions): Promise<ReadResult>;
+    readPost({ target, mode, }: {
+        target: import("./types.js").PostTarget;
+        mode?: ReadMode;
+    }): Promise<ReadResult>;
+    readPerson({ target, mode, }: {
+        target: import("./types.js").PersonTarget;
+        mode?: ReadMode;
+    }): Promise<ReadResult>;
+    readFeedback(args: import("./types.js").FeedbackOptions): Promise<ReadResult>;
+    inspectAccount(args?: {
+        mode?: ReadMode;
+    } | undefined): Promise<ReadResult>;
+    inspectRound(args: {
+        taskId: string;
+    }): Promise<RoundResult>;
+    runGrowthRound(args: import("./types.js").RoundOptions): Promise<RoundResult>;
+    publishPost(args: import("./types.js").PublishOptions): Promise<ActionResult>;
+    replyToPost(args: import("./types.js").ReplyOptions): Promise<ActionResult>;
+    followOne(args: {
+        taskId: string;
+        handle: string;
+    }): Promise<ActionResult>;
+    verifySubmission(args: {
+        taskId: string;
+        actionId: string;
+    }): Promise<ActionResult>;
+    verifyPublishedPost(args: {
+        taskId: string;
+        draftPath: string;
+        publicURL: string;
+        evidenceRef: import("./types.js").EvidenceRef;
+        sourceLink?: import("./types.js").SourceLinkEvidence;
+    }): Promise<ActionResult>;
+    followBatch(args: import("./types.js").FollowOptions): Promise<BatchResult>;
+    verifyFollow(args: {
+        handle: string;
+        url?: string;
+        evidenceRef?: import("./types.js").EvidenceRef;
+        mode?: "receipt" | "decision";
+    }): Promise<ReadResult & {
+        handle: string;
+        verified: boolean;
+    }>;
+}
+export declare function createBusinessHarness(...args: ConstructorParameters<typeof BusinessHarness>): XGrowthHarness;