@linkedclaw/cli 0.1.2 → 0.1.5

package/test/converge-status.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect } from "vitest";
+import { reduceRunState } from "../src/commands/converge.js";
+import type { CommonsLogEvent, RunWorkspace } from "../src/converge/types.js";
+
+const FAKE_WS: RunWorkspace = {
+  runId: "clg_run00000000",
+  sourceDebateId: "dbt_source001",
+  paAgentId: "agt_pa001",
+  targetCorpus: "/corpus",
+  stagingDir: "/corpus/converged/staging/clg_run00000000",
+};
+
+const SAMPLE_EVENTS: CommonsLogEvent[] = [
+  {
+    seq: 1,
+    event_type: "run_started",
+    payload: {},
+    appended_at: "2026-04-30T10:00:00Z",
+    signed_by: "sys",
+  },
+  {
+    seq: 2,
+    event_type: "sub_debate_dispatched",
+    payload: { crux_id: "crux_001", sub_debate_id: "dbt_sub001" },
+    appended_at: "2026-04-30T10:01:00Z",
+    signed_by: "sys",
+  },
+  {
+    seq: 3,
+    event_type: "sub_debate_dispatched",
+    payload: { crux_id: "crux_002", sub_debate_id: "dbt_sub002" },
+    appended_at: "2026-04-30T10:02:00Z",
+    signed_by: "sys",
+  },
+  {
+    seq: 4,
+    event_type: "sub_debate_outcome_observed",
+    payload: { crux_id: "crux_001", outcome: "already_aligned", bilateral_mandate_intact: true },
+    appended_at: "2026-04-30T10:05:00Z",
+    signed_by: "sys",
+  },
+];
+
+describe("reduceRunState", () => {
+  it("extracts started_at from run_started event", () => {
+    const summary = reduceRunState(FAKE_WS, SAMPLE_EVENTS);
+    expect(summary.started_at).toBe("2026-04-30T10:00:00Z");
+  });
+
+  it("owner_b_accepted is false when no event emitted", () => {
+    const summary = reduceRunState(FAKE_WS, SAMPLE_EVENTS);
+    expect(summary.owner_b_accepted).toBe(false);
+  });
+
+  it("owner_b_accepted flips to true when event present", () => {
+    const events: CommonsLogEvent[] = [
+      ...SAMPLE_EVENTS,
+      {
+        seq: 5,
+        event_type: "owner_b_accepted",
+        payload: {},
+        appended_at: "2026-04-30T10:06:00Z",
+        signed_by: "owner_b",
+      },
+    ];
+    const summary = reduceRunState(FAKE_WS, events);
+    expect(summary.owner_b_accepted).toBe(true);
+  });
+
+  it("builds two crux entries from dispatched events", () => {
+    const summary = reduceRunState(FAKE_WS, SAMPLE_EVENTS);
+    expect(summary.cruxes).toHaveLength(2);
+  });
+
+  it("crux_001 has outcome=already_aligned and bilateral_mandate_intact=true", () => {
+    const summary = reduceRunState(FAKE_WS, SAMPLE_EVENTS);
+    const c1 = summary.cruxes.find((c) => c.crux_id === "crux_001");
+    expect(c1).toBeDefined();
+    expect(c1!.outcome).toBe("already_aligned");
+    expect(c1!.bilateral_mandate_intact).toBe(true);
+    expect(c1!.latest_sub_debate_id).toBe("dbt_sub001");
+  });
+
+  it("crux_002 has null outcome (in-progress)", () => {
+    const summary = reduceRunState(FAKE_WS, SAMPLE_EVENTS);
+    const c2 = summary.cruxes.find((c) => c.crux_id === "crux_002");
+    expect(c2).toBeDefined();
+    expect(c2!.outcome).toBeNull();
+    expect(c2!.bilateral_mandate_intact).toBeNull();
+  });
+
+  it("terminal_emitted is false without terminal event", () => {
+    const summary = reduceRunState(FAKE_WS, SAMPLE_EVENTS);
+    expect(summary.terminal_emitted).toBe(false);
+  });
+
+  it("terminal_emitted is true on convergence_map event", () => {
+    const events: CommonsLogEvent[] = [
+      ...SAMPLE_EVENTS,
+      {
+        seq: 6,
+        event_type: "convergence_map",
+        payload: {},
+        appended_at: "2026-04-30T11:00:00Z",
+        signed_by: "sys",
+      },
+    ];
+    const summary = reduceRunState(FAKE_WS, events);
+    expect(summary.terminal_emitted).toBe(true);
+  });
+
+  it("re-dispatch appends to sub_debate_chain and updates latest_sub_debate_id", () => {
+    const events: CommonsLogEvent[] = [
+      ...SAMPLE_EVENTS,
+      {
+        seq: 5,
+        event_type: "sub_debate_dispatched",
+        payload: { crux_id: "crux_001", sub_debate_id: "dbt_sub001b" },
+        appended_at: "2026-04-30T10:07:00Z",
+        signed_by: "sys",
+      },
+    ];
+    const summary = reduceRunState(FAKE_WS, events);
+    const c1 = summary.cruxes.find((c) => c.crux_id === "crux_001")!;
+    expect(c1.latest_sub_debate_id).toBe("dbt_sub001b");
+    expect(c1.sub_debate_chain).toEqual(["dbt_sub001", "dbt_sub001b"]);
+  });
+
+  it("empty event list yields empty cruxes and null started_at", () => {
+    const summary = reduceRunState(FAKE_WS, []);
+    expect(summary.cruxes).toHaveLength(0);
+    expect(summary.started_at).toBeNull();
+    expect(summary.terminal_emitted).toBe(false);
+  });
+
+  it("run_id and source_debate_id come from workspace", () => {
+    const summary = reduceRunState(FAKE_WS, SAMPLE_EVENTS);
+    expect(summary.run_id).toBe(FAKE_WS.runId);
+    expect(summary.source_debate_id).toBe(FAKE_WS.sourceDebateId);
+  });
+});

package/test/converge-workspace.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { resolveWorkspace, writeRunMeta, readRunMeta } from "../src/converge/workspace.js";
+import type { RunMeta } from "../src/converge/types.js";
+
+const SAMPLE_META: RunMeta = {
+  run_id: "clg_aabbccdd11223344",
+  source_debate_id: "dbt_001",
+  pa_agent_id: "agt_pa001",
+  target_corpus: "/corpus/root",
+  owner_role: "a",
+};
+
+let tmp: string;
+
+beforeEach(() => {
+  tmp = mkdtempSync(join(tmpdir(), "lc-ws-test-"));
+});
+
+afterEach(() => {
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("resolveWorkspace", () => {
+  it("returns workspace from --staging-dir with .run-meta.yaml", async () => {
+    writeRunMeta(tmp, SAMPLE_META);
+    const ws = await resolveWorkspace({ stagingDir: tmp });
+    expect(ws.runId).toBe(SAMPLE_META.run_id);
+    expect(ws.sourceDebateId).toBe(SAMPLE_META.source_debate_id);
+    expect(ws.stagingDir).toBe(resolve(tmp));
+  });
+
+  it("searches upward from cwd and finds meta", async () => {
+    writeRunMeta(tmp, SAMPLE_META);
+    const subdir = join(tmp, "sub", "dir");
+    mkdirSync(subdir, { recursive: true });
+    const ws = await resolveWorkspace({ cwd: subdir });
+    expect(ws.runId).toBe(SAMPLE_META.run_id);
+    expect(ws.stagingDir).toBe(tmp);
+  });
+
+  it("throws run_id_mismatch when --run-id conflicts with meta", async () => {
+    writeRunMeta(tmp, SAMPLE_META);
+    await expect(
+      resolveWorkspace({ stagingDir: tmp, runId: "clg_different00000000" }),
+    ).rejects.toMatchObject({ code: "run_id_mismatch" });
+  });
+
+  it("succeeds when --run-id matches meta", async () => {
+    writeRunMeta(tmp, SAMPLE_META);
+    const ws = await resolveWorkspace({ stagingDir: tmp, runId: SAMPLE_META.run_id });
+    expect(ws.runId).toBe(SAMPLE_META.run_id);
+  });
+
+  it("throws meta_not_found when staging-dir has no meta", async () => {
+    await expect(resolveWorkspace({ stagingDir: tmp })).rejects.toMatchObject({
+      code: "meta_not_found",
+    });
+  });
+
+  it("throws meta_not_found with guidance when --run-id given but no meta found", async () => {
+    const empty = mkdtempSync(join(tmpdir(), "lc-empty-"));
+    try {
+      await expect(
+        resolveWorkspace({ runId: "clg_xyz", cwd: empty }),
+      ).rejects.toMatchObject({ code: "meta_not_found" });
+    } finally {
+      rmSync(empty, { recursive: true, force: true });
+    }
+  });
+
+  it("returns absolute paths even when stagingDir is relative concept (resolved from cwd)", async () => {
+    writeRunMeta(tmp, SAMPLE_META);
+    const ws = await resolveWorkspace({ stagingDir: tmp });
+    expect(ws.stagingDir).toMatch(/^\//);
+  });
+});
+
+describe("readRunMeta / writeRunMeta roundtrip", () => {
+  it("roundtrips all fields correctly", () => {
+    writeRunMeta(tmp, SAMPLE_META);
+    const loaded = readRunMeta(tmp);
+    expect(loaded).toEqual(SAMPLE_META);
+  });
+
+  it("returns null when file does not exist", () => {
+    const result = readRunMeta(join(tmp, "nonexistent"));
+    expect(result).toBeNull();
+  });
+});

package/test/hire-flags.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect, vi } from "vitest";
+
+const sendSpy = vi.fn().mockResolvedValue({ ok: true });
+const eventsSpy = vi.fn().mockResolvedValue({ events: [{}, {}] });
+const hireSpy = vi.fn().mockResolvedValue({ session: { session_id: "s1" }, activated: true });
+const endSessionSpy = vi.fn().mockResolvedValue({ ok: true });
+
+vi.mock("../src/context.js", () => ({
+  buildContext: () => ({
+    cfg: { apiKey: "k", cloudUrl: "http://x" },
+    requesterFlows: { hire: hireSpy, send: sendSpy, search: vi.fn(), invoke: vi.fn() },
+    consumer: { getSessionEvents: eventsSpy, endSession: endSessionSpy, invoke: vi.fn() },
+    providerClient: {},
+  }),
+}));
+
+vi.mock("../src/output.js", () => ({
+  runCommand: async (fn: () => Promise<unknown>) => fn(),
+  readStdin: async () => "",
+  printError: () => {},
+  printResult: () => {},
+}));
+
+describe("hire --message", () => {
+  it("calls requesterFlows.send once with message and seq=1", async () => {
+    const { Command } = await import("commander");
+    const program = new Command();
+    program.exitOverride();
+    const { registerRequesterCommands } = await import("../src/commands/requester.js");
+    registerRequesterCommands(program);
+
+    await program.parseAsync([
+      "node", "cli", "hire", "agent-1",
+      "--capability", "test-cap",
+      "--message", "hello",
+    ]);
+
+    expect(hireSpy).toHaveBeenCalled();
+    expect(sendSpy).toHaveBeenCalledWith("s1", "hello", 1);
+  });
+});
+
+describe("hire --interactive flag", () => {
+  it("--interactive option is registered on the hire command", async () => {
+    const { Command } = await import("commander");
+    const program = new Command();
+    const { registerRequesterCommands } = await import("../src/commands/requester.js");
+    registerRequesterCommands(program);
+
+    const hireCmd = program.commands.find((c) => c.name() === "hire");
+    expect(hireCmd).toBeDefined();
+    const interactiveOpt = hireCmd!.options.find((o) => o.long === "--interactive");
+    expect(interactiveOpt).toBeDefined();
+  });
+});

package/test/recv-flags.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it, vi } from "vitest";
+
+const eventsSpy = vi.fn();
+
+vi.mock("../src/context.js", () => ({
+  buildContext: () => ({
+    cfg: { apiKey: "k", cloudUrl: "http://x" },
+    requesterFlows: { hire: vi.fn(), send: vi.fn(), search: vi.fn(), invoke: vi.fn() },
+    consumer: { getSessionEvents: eventsSpy, endSession: vi.fn(), invoke: vi.fn() },
+    providerClient: {},
+  }),
+}));
+
+vi.mock("../src/output.js", () => ({
+  runCommand: async (fn: () => Promise<unknown>) => fn(),
+  readStdin: async () => "",
+  printError: () => {},
+  printResult: () => {},
+}));
+
+describe("recv subcommand", () => {
+  it("registers with --since, --wait, --human options", async () => {
+    const { Command } = await import("commander");
+    const program = new Command();
+    const { registerRequesterCommands } = await import("../src/commands/requester.js");
+    registerRequesterCommands(program);
+
+    const recvCmd = program.commands.find((c) => c.name() === "recv");
+    expect(recvCmd).toBeDefined();
+    expect(recvCmd!.options.find((o) => o.long === "--since")).toBeDefined();
+    expect(recvCmd!.options.find((o) => o.long === "--wait")).toBeDefined();
+    expect(recvCmd!.options.find((o) => o.long === "--human")).toBeDefined();
+  });
+
+  it("calls getSessionEvents with offset=0 by default", async () => {
+    eventsSpy.mockResolvedValueOnce({ events: [{ event_seq: 1 }], next_offset: 1 });
+    const { Command } = await import("commander");
+    const program = new Command();
+    program.exitOverride();
+    const { registerRequesterCommands } = await import("../src/commands/requester.js");
+    registerRequesterCommands(program);
+
+    await program.parseAsync(["node", "cli", "recv", "ses_1"]);
+
+    expect(eventsSpy).toHaveBeenCalledWith("ses_1", { offset: 0 });
+  });
+
+  it("forwards --since as offset", async () => {
+    eventsSpy.mockResolvedValueOnce({ events: [{ event_seq: 7 }], next_offset: 7 });
+    const { Command } = await import("commander");
+    const program = new Command();
+    program.exitOverride();
+    const { registerRequesterCommands } = await import("../src/commands/requester.js");
+    registerRequesterCommands(program);
+
+    await program.parseAsync(["node", "cli", "recv", "ses_2", "--since", "5"]);
+
+    expect(eventsSpy).toHaveBeenCalledWith("ses_2", { offset: 5 });
+  });
+
+  it("polls repeatedly under --wait until events arrive", async () => {
+    eventsSpy.mockReset();
+    eventsSpy
+      .mockResolvedValueOnce({ events: [], next_offset: 0 })
+      .mockResolvedValueOnce({ events: [], next_offset: 0 })
+      .mockResolvedValueOnce({ events: [{ event_seq: 1 }], next_offset: 1 });
+
+    vi.useFakeTimers();
+    const { Command } = await import("commander");
+    const program = new Command();
+    program.exitOverride();
+    const { registerRequesterCommands } = await import("../src/commands/requester.js");
+    registerRequesterCommands(program);
+
+    const promise = program.parseAsync(["node", "cli", "recv", "ses_3", "--wait", "10"]);
+    await vi.advanceTimersByTimeAsync(1500);
+    await vi.advanceTimersByTimeAsync(1500);
+    await promise;
+    vi.useRealTimers();
+
+    expect(eventsSpy).toHaveBeenCalledTimes(3);
+  });
+});

package/test/register-browser.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect, vi } from "vitest";
+
+const writeSpy = vi.fn();
+const readFileSpy = vi.fn().mockReturnValue({});
+
+vi.mock("../src/config.js", () => ({
+  configPath: () => "/tmp/cli-test-config.yaml",
+  configDir: () => "/tmp",
+  readFileConfig: readFileSpy,
+  writeFileConfig: writeSpy,
+  resolveConfig: () => ({ apiKey: "", cloudUrl: "http://localhost:17221" }),
+}));
+
+vi.mock("../src/output.js", () => ({
+  runCommand: async (fn: () => Promise<unknown>) => fn(),
+  readLine: async () => "test-api-key-abc123",
+  readStdin: async () => "test-api-key-abc123",
+  printError: () => {},
+  printResult: () => {},
+}));
+
+const openSpy = vi.fn().mockResolvedValue(undefined);
+vi.mock("open", () => ({ default: openSpy }));
+
+describe("register --browser", () => {
+  it("opens portal URL and persists pasted key via writeFileConfig", async () => {
+    openSpy.mockResolvedValueOnce(undefined);
+
+    const { Command } = await import("commander");
+    const program = new Command();
+    program.exitOverride();
+    const { registerAuthCommands } = await import("../src/commands/auth.js");
+    registerAuthCommands(program);
+
+    await program.parseAsync(["node", "cli", "register", "--cloud-url", "http://test:17221"]);
+
+    expect(openSpy).toHaveBeenCalledWith("http://test:17221/register");
+    expect(writeSpy).toHaveBeenCalledWith(expect.objectContaining({ apiKey: "test-api-key-abc123" }));
+  });
+
+  it("falls through to URL print when open() throws (headless)", async () => {
+    openSpy.mockRejectedValueOnce(new Error("no DISPLAY"));
+    writeSpy.mockClear();
+
+    const { Command } = await import("commander");
+    const program = new Command();
+    program.exitOverride();
+    const { registerAuthCommands } = await import("../src/commands/auth.js");
+    registerAuthCommands(program);
+
+    await program.parseAsync(["node", "cli", "register", "--cloud-url", "http://test:17221"]);
+
+    expect(writeSpy).toHaveBeenCalled();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules", "test"]
+}

package/tsup.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/bin.ts"],
+  format: ["esm"],
+  platform: "node",
+  dts: false,
+  sourcemap: true,
+  clean: true,
+  target: "node20",
+  splitting: false,
+  shims: false,
+  banner: { js: "#!/usr/bin/env node" },
+  // Bundle the four SDK packages so `npm install -g @linkedclaw/cli` works without
+  // separate installs.
+  noExternal: [
+    "@linkedclaw/consumer",
+    "@linkedclaw/consumer-runtime",
+    "@linkedclaw/provider",
+    "@linkedclaw/provider-runtime",
+  ],
+  // ws is CJS and requires Node built-ins dynamically; keep it external so Node
+  // resolves it natively at runtime (ws is a direct dep for this reason).
+  external: ["ws"],
+});

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["test/**/*.test.ts"],
+    environment: "node",
+  },
+});