@linkedclaw/cli 0.1.2 → 0.1.5

package/test/arena-commands.test.ts

@@ -0,0 +1,559 @@
+import { Command } from "commander";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { registerArenaCommands } from "../src/commands/arena.js";
+import { sha256Digest } from "../src/arena/hash.js";
+
+const cfgRef = vi.hoisted(() => ({
+  current: {
+    apiKey: "k",
+    cloudUrl: "http://cloud.test",
+    servicesHostUrl: "http://services.test",
+  } as Record<string, string | undefined>,
+}));
+
+const consumerRef = vi.hoisted(() => ({
+  current: {
+    getAgent: vi.fn(),
+    resolveAgentHandle: vi.fn(),
+  },
+}));
+const apiRef = vi.hoisted(() => ({ current: {} as any }));
+const makeArenaApiMock = vi.hoisted(() => vi.fn(() => apiRef.current));
+const originalServicesHostEnv = process.env.LINKEDCLAW_SERVICES_HOST_URL;
+
+vi.mock("../src/context.js", () => ({
+  buildContext: () => ({ cfg: cfgRef.current, consumer: consumerRef.current }),
+}));
+
+vi.mock("../src/arena/api.js", () => ({
+  makeArenaApi: makeArenaApiMock,
+}));
+
+function makeProgram(): Command {
+  const program = new Command();
+  program.exitOverride();
+  registerArenaCommands(program);
+  return program;
+}
+
+async function run(args: string[]): Promise<{ stdout: string; stderr: string; exitCode: number | undefined }> {
+  let stdout = "";
+  let stderr = "";
+  const out = vi.spyOn(process.stdout, "write").mockImplementation((chunk: any) => {
+    stdout += String(chunk);
+    return true;
+  });
+  const err = vi.spyOn(process.stderr, "write").mockImplementation((chunk: any) => {
+    stderr += String(chunk);
+    return true;
+  });
+  const prevExitCode = process.exitCode;
+  process.exitCode = undefined;
+  try {
+    await makeProgram().parseAsync(["node", "test", ...args], { from: "node" });
+    return { stdout, stderr, exitCode: process.exitCode as number | undefined };
+  } finally {
+    process.exitCode = prevExitCode;
+    out.mockRestore();
+    err.mockRestore();
+  }
+}
+
+beforeEach(() => {
+  delete process.env.LINKEDCLAW_SERVICES_HOST_URL;
+  cfgRef.current = {
+    apiKey: "k",
+    cloudUrl: "http://cloud.test",
+    servicesHostUrl: "http://services.test",
+  };
+  apiRef.current = {
+    register: vi.fn(async () => ({ registration: { registration_id: "areg_1" } })),
+    listOffers: vi.fn(async () => ({ offers: [] })),
+    acceptOffer: vi.fn(async () => ({ offer: { offer_id: "aoff_123" } })),
+    createTournamentArena: vi.fn(async () => ({ arena: { arena_id: "arn_tournament" }, replayed: false })),
+    submit: vi.fn(async () => ({ submission: { submission_id: "asub_1" } })),
+    commitJuror: vi.fn(async () => ({ juror: { juror_id: "ajur_1" } })),
+    voteTask: vi.fn(async () => ({ vote: { vote_id: "ajv_1" } })),
+    voteMatch: vi.fn(async () => ({ vote: { vote_id: "amjv_1" } })),
+    listArenas: vi.fn(async () => ({ arenas: [] })),
+    getLeaderboard: vi.fn(async () => ({ arena_id: "arn_123", leaderboard: [] })),
+    getCategoryLeaderboard: vi.fn(async () => ({
+      category: { topic: "coding", subtopic: "patches" },
+      mode: "match",
+      leaderboard: [],
+    })),
+  };
+  consumerRef.current.getAgent.mockReset();
+  consumerRef.current.resolveAgentHandle.mockReset();
+  consumerRef.current.getAgent.mockImplementation(async (agentId: string) => ({
+    agent_id: agentId,
+    capabilities: ["arena.v1"],
+    external_endpoint: "https://third-pa.test",
+  }));
+  consumerRef.current.resolveAgentHandle.mockImplementation(async () => ({
+    agent_id: "agt_first_party_arena",
+    capabilities: ["arena.v1", "arena_entry"],
+  }));
+  makeArenaApiMock.mockClear();
+});
+
+afterEach(() => {
+  if (originalServicesHostEnv === undefined) {
+    delete process.env.LINKEDCLAW_SERVICES_HOST_URL;
+  } else {
+    process.env.LINKEDCLAW_SERVICES_HOST_URL = originalServicesHostEnv;
+  }
+  vi.restoreAllMocks();
+});
+
+describe("arena commands", () => {
+  it("register builds contestant, mandate, and two-level category", async () => {
+    await run([
+      "arena",
+      "register",
+      "--agent-id",
+      "agt_1",
+      "--mandate-id",
+      "mand_1",
+      "--category-topic",
+      "code",
+      "--category-subtopic",
+      "rust",
+    ]);
+    expect(apiRef.current.register).toHaveBeenCalledWith({
+      contestant_agent_id: "agt_1",
+      mandate_id: "mand_1",
+      category: { topic: "code", subtopic: "rust" },
+    });
+  });
+
+  it("offers calls listOffers", async () => {
+    await run(["arena", "offers"]);
+    expect(apiRef.current.listOffers).toHaveBeenCalledOnce();
+  });
+
+  it("accept calls acceptOffer", async () => {
+    await run(["arena", "accept", "aoff_123"]);
+    expect(apiRef.current.acceptOffer).toHaveBeenCalledWith("aoff_123");
+  });
+
+  it("tournament create passes through an exact task-child JSON manifest", async () => {
+    const tmp = mkdtempSync(join(tmpdir(), "lc-arena-tournament-"));
+    try {
+      const path = join(tmp, "tournament.json");
+      const manifest = {
+        mode: "tournament",
+        category: { topic: "code", subtopic: "typescript" },
+        config: {
+          bracket_shape: "single_elim",
+          child_mode: "task_submission",
+          advancement_rule: "top_k(1)",
+          child_config: { prompt: "implement it" },
+          bracket_size: 4,
+          seeding: "unseeded",
+        },
+      };
+      writeFileSync(path, JSON.stringify(manifest), "utf8");
+      await run(["arena", "tournament", "create", path, "--idempotency-key", "idem_task"]);
+      expect(apiRef.current.createTournamentArena).toHaveBeenCalledWith(manifest, {
+        idempotencyKey: "idem_task",
+      });
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("tournament create preserves match-child seeded and remote dispatch config", async () => {
+    const tmp = mkdtempSync(join(tmpdir(), "lc-arena-tournament-"));
+    try {
+      const path = join(tmp, "tournament.json");
+      const manifest = {
+        mode: "tournament",
+        category: { topic: "debate", subtopic: "crux" },
+        config: {
+          bracket_shape: "single_elim",
+          child_mode: "match",
+          advancement_rule: "head_to_head_winner",
+          child_config: { prompt_source: { kind: "poster_set", prompts: ["a", "b"] } },
+          bracket_size: 8,
+          seeding: "poster_set",
+          seed_order: ["usr_a", "usr_b", "usr_c"],
+          child_dispatch: { kind: "remote_pa", agent_id: "agt_remote_arena" },
+          settlement: { prize_credits: 100 },
+        },
+      };
+      writeFileSync(path, JSON.stringify(manifest), "utf8");
+      await run(["arena", "tournament", "create", path, "--idempotency-key", "idem_match"]);
+      expect(apiRef.current.createTournamentArena).toHaveBeenCalledWith(manifest, {
+        idempotencyKey: "idem_match",
+      });
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("tournament create reuses --target Arena PA resolution", async () => {
+    const tmp = mkdtempSync(join(tmpdir(), "lc-arena-tournament-"));
+    try {
+      const path = join(tmp, "tournament.json");
+      writeFileSync(path, JSON.stringify({
+        mode: "tournament",
+        category: { topic: "code", subtopic: "rust" },
+        config: {},
+      }), "utf8");
+      await run([
+        "arena",
+        "tournament",
+        "create",
+        path,
+        "--idempotency-key",
+        "idem_target",
+        "--target",
+        "agt_third",
+      ]);
+      expect(consumerRef.current.getAgent).toHaveBeenCalledWith("agt_third");
+      expect(makeArenaApiMock).toHaveBeenCalledWith("https://third-pa.test", "k");
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("tournament create rejects missing or non-tournament mode", async () => {
+    const tmp = mkdtempSync(join(tmpdir(), "lc-arena-tournament-"));
+    try {
+      const path = join(tmp, "not-tournament.json");
+      writeFileSync(path, JSON.stringify({
+        mode: "match",
+        category: { topic: "code", subtopic: "rust" },
+        config: {},
+      }), "utf8");
+      const result = await run(["arena", "tournament", "create", path, "--idempotency-key", "idem_bad"]);
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toContain("arena_tournament_manifest_mode_invalid");
+      expect(apiRef.current.createTournamentArena).not.toHaveBeenCalled();
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("tournament create rejects blank idempotency keys before API calls", async () => {
+    const tmp = mkdtempSync(join(tmpdir(), "lc-arena-tournament-"));
+    try {
+      const path = join(tmp, "tournament.json");
+      writeFileSync(path, JSON.stringify({
+        mode: "tournament",
+        category: { topic: "code", subtopic: "rust" },
+        config: {},
+      }), "utf8");
+      const result = await run(["arena", "tournament", "create", path, "--idempotency-key", "   "]);
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toContain("arena_idempotency_key_required");
+      expect(apiRef.current.createTournamentArena).not.toHaveBeenCalled();
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("tournament create rejects missing idempotency keys before API calls", async () => {
+    const tmp = mkdtempSync(join(tmpdir(), "lc-arena-tournament-"));
+    try {
+      const path = join(tmp, "tournament.json");
+      writeFileSync(path, JSON.stringify({
+        mode: "tournament",
+        category: { topic: "code", subtopic: "rust" },
+        config: {},
+      }), "utf8");
+      const result = await run(["arena", "tournament", "create", path]);
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toContain("arena_idempotency_key_required");
+      expect(apiRef.current.createTournamentArena).not.toHaveBeenCalled();
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("tournament create rejects idempotency keys with embedded newlines", async () => {
+    const tmp = mkdtempSync(join(tmpdir(), "lc-arena-tournament-"));
+    try {
+      const path = join(tmp, "tournament.json");
+      writeFileSync(path, JSON.stringify({
+        mode: "tournament",
+        category: { topic: "code", subtopic: "rust" },
+        config: {},
+      }), "utf8");
+      const result = await run([
+        "arena",
+        "tournament",
+        "create",
+        path,
+        "--idempotency-key",
+        "idem_1\r\nX-Evil: 1",
+      ]);
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toContain("arena_idempotency_key_invalid");
+      expect(apiRef.current.createTournamentArena).not.toHaveBeenCalled();
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("tournament create rejects stdin '-' when stdin is a TTY", async () => {
+    const original = process.stdin.isTTY;
+    Object.defineProperty(process.stdin, "isTTY", { configurable: true, value: true });
+    try {
+      const result = await run([
+        "arena",
+        "tournament",
+        "create",
+        "-",
+        "--idempotency-key",
+        "idem_tty",
+      ]);
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toContain("arena_tournament_manifest_stdin_tty");
+      expect(apiRef.current.createTournamentArena).not.toHaveBeenCalled();
+    } finally {
+      Object.defineProperty(process.stdin, "isTTY", { configurable: true, value: original });
+    }
+  });
+
+  it("submit with body computes the expected hash and calls submit", async () => {
+    const result = await run(["arena", "submit", "arn_123", "--offer-id", "aoff_123", "--body", "hello"]);
+    const request = apiRef.current.submit.mock.calls[0][1];
+    expect(apiRef.current.submit).toHaveBeenCalledWith("arn_123", expect.any(Object));
+    expect(request).toMatchObject({
+      offer_id: "aoff_123",
+      raw_content: "hello",
+      seq: 1,
+      submission_hash: sha256Digest(Buffer.from("hello", "utf8")),
+    });
+    expect(JSON.parse(result.stdout).submission.submission_hash).toBe(request.submission_hash);
+  });
+
+  it("submit passes match_id for match-mode submissions", async () => {
+    await run([
+      "arena",
+      "submit",
+      "arn_123",
+      "--offer-id",
+      "aoff_123",
+      "--match-id",
+      "amch_1234567890abcdef",
+      "--body",
+      "hello",
+    ]);
+    expect(apiRef.current.submit).toHaveBeenCalledWith(
+      "arn_123",
+      expect.objectContaining({ match_id: "amch_1234567890abcdef" }),
+    );
+  });
+
+
+  it("submit with file reads file content and defaults content_ref to the path", async () => {
+    const tmp = mkdtempSync(join(tmpdir(), "lc-arena-command-"));
+    try {
+      const path = join(tmp, "answer.txt");
+      writeFileSync(path, "file answer", "utf8");
+      await run(["arena", "submit", "arn_123", "--offer-id", "aoff_123", "--file", path]);
+      expect(apiRef.current.submit.mock.calls[0][1]).toMatchObject({
+        raw_content: "file answer",
+        content_ref: path,
+        submission_hash: sha256Digest(Buffer.from("file answer", "utf8")),
+      });
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("submit rejects both file and body", async () => {
+    const result = await run([
+      "arena",
+      "submit",
+      "arn_123",
+      "--offer-id",
+      "aoff_123",
+      "--file",
+      "answer.txt",
+      "--body",
+      "hello",
+    ]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("submission_source_conflict");
+    expect(apiRef.current.submit).not.toHaveBeenCalled();
+  });
+
+  it("submit rejects missing file and body", async () => {
+    const result = await run(["arena", "submit", "arn_123", "--offer-id", "aoff_123"]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("submission_source_required");
+    expect(apiRef.current.submit).not.toHaveBeenCalled();
+  });
+
+  it("vote task submits a numeric score with rationale reference", async () => {
+    await run([
+      "arena",
+      "vote",
+      "task",
+      "arn_123",
+      "asub_123",
+      "0.75",
+      "--rationale-ref",
+      "note://1",
+    ]);
+    expect(apiRef.current.voteTask).toHaveBeenCalledWith("arn_123", {
+      submission_id: "asub_123",
+      score: 0.75,
+      rationale_ref: "note://1",
+    });
+  });
+
+  it("vote task rejects invalid scores", async () => {
+    const result = await run(["arena", "vote", "task", "arn_123", "asub_123", "1.2"]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("invalid_juror_score");
+    expect(apiRef.current.voteTask).not.toHaveBeenCalled();
+  });
+
+  it("vote task rejects non-numeric scores", async () => {
+    const result = await run(["arena", "vote", "task", "arn_123", "asub_123", "nope"]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("invalid_juror_score");
+    expect(apiRef.current.voteTask).not.toHaveBeenCalled();
+  });
+
+  it("vote match submits an outcome with rationale reference", async () => {
+    await run([
+      "arena",
+      "vote",
+      "match",
+      "arn_123",
+      "amch_123",
+      "a",
+      "--rationale-ref",
+      "note://2",
+    ]);
+    expect(apiRef.current.voteMatch).toHaveBeenCalledWith("arn_123", "amch_123", {
+      outcome: "a",
+      rationale_ref: "note://2",
+    });
+  });
+
+  it("vote match rejects invalid outcomes", async () => {
+    const result = await run(["arena", "vote", "match", "arn_123", "amch_123", "winner"]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("invalid_juror_outcome");
+    expect(apiRef.current.voteMatch).not.toHaveBeenCalled();
+  });
+
+  it("list --registered passes registered true", async () => {
+    await run(["arena", "list", "--registered"]);
+    expect(apiRef.current.listArenas).toHaveBeenCalledWith({ registered: true });
+  });
+
+  it("leaderboard with arena id calls getLeaderboard", async () => {
+    await run(["arena", "leaderboard", "arn_123"]);
+    expect(apiRef.current.getLeaderboard).toHaveBeenCalledWith("arn_123");
+  });
+
+  it("leaderboard without arena id calls getCategoryLeaderboard", async () => {
+    await run([
+      "arena",
+      "leaderboard",
+      "--category-topic",
+      "coding",
+      "--category-subtopic",
+      "patches",
+      "--mode",
+      "match",
+    ]);
+    expect(apiRef.current.getCategoryLeaderboard).toHaveBeenCalledWith(
+      { topic: "coding", subtopic: "patches" },
+      "match",
+    );
+  });
+
+  it("leaderboard without arena id requires category topic", async () => {
+    const result = await run([
+      "arena",
+      "leaderboard",
+      "--category-subtopic",
+      "patches",
+      "--mode",
+      "match",
+    ]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("missing_category_topic");
+    expect(apiRef.current.getCategoryLeaderboard).not.toHaveBeenCalled();
+  });
+
+  it("leaderboard without arena id requires category subtopic", async () => {
+    const result = await run([
+      "arena",
+      "leaderboard",
+      "--category-topic",
+      "coding",
+      "--mode",
+      "match",
+    ]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("missing_category_subtopic");
+    expect(apiRef.current.getCategoryLeaderboard).not.toHaveBeenCalled();
+  });
+
+  it("leaderboard without arena id rejects unsupported mode", async () => {
+    const result = await run([
+      "arena",
+      "leaderboard",
+      "--category-topic",
+      "coding",
+      "--category-subtopic",
+      "patches",
+      "--mode",
+      "task_submission",
+    ]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("unsupported_arena_leaderboard_mode");
+    expect(apiRef.current.getCategoryLeaderboard).not.toHaveBeenCalled();
+  });
+
+  it("--target resolves an Arena PA agent id and uses its external endpoint", async () => {
+    await run(["arena", "offers", "--target", "agt_third"]);
+    expect(consumerRef.current.getAgent).toHaveBeenCalledWith("agt_third");
+    expect(makeArenaApiMock).toHaveBeenCalledWith("https://third-pa.test", "k");
+  });
+
+  it("--target rejects raw URLs", async () => {
+    const result = await run(["arena", "offers", "--target", "http://raw-pa.test"]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("arena_target_must_be_agent_id");
+    expect(makeArenaApiMock).not.toHaveBeenCalled();
+  });
+
+  it("discovers the first-party Arena PA by default", async () => {
+    await run(["arena", "offers"]);
+    expect(consumerRef.current.resolveAgentHandle).toHaveBeenCalledWith("gig-pa-operator", "arena-v1");
+    expect(makeArenaApiMock).toHaveBeenCalledWith("http://services.test", "k");
+  });
+
+  it("rejects targets that do not advertise arena.v1", async () => {
+    consumerRef.current.getAgent.mockResolvedValueOnce({ agent_id: "agt_not_arena", capabilities: ["echo"] });
+    const result = await run(["arena", "offers", "--target", "agt_not_arena"]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("arena_target_not_arena_pa");
+    expect(makeArenaApiMock).not.toHaveBeenCalled();
+  });
+
+  it("uses servicesHostUrl by default", async () => {
+    await run(["arena", "offers"]);
+    expect(makeArenaApiMock).toHaveBeenCalledWith("http://services.test", "k");
+  });
+
+  it("falls back to cloudUrl without servicesHostUrl", async () => {
+    cfgRef.current = { apiKey: "k", cloudUrl: "http://cloud.test", servicesHostUrl: undefined };
+    await run(["arena", "offers"]);
+    expect(makeArenaApiMock).toHaveBeenCalledWith("http://cloud.test", "k");
+  });
+});

package/test/arena-hash.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { hashFile, sha256Digest } from "../src/arena/hash.js";
+
+describe("arena hash helpers", () => {
+  it("hashes a known string", () => {
+    expect(sha256Digest("hello")).toBe(
+      "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
+    );
+  });
+
+  it("hashFile matches hashing the same bytes", () => {
+    const tmp = mkdtempSync(join(tmpdir(), "lc-arena-hash-"));
+    try {
+      const path = join(tmp, "answer.txt");
+      const bytes = Buffer.from("answer\n", "utf8");
+      writeFileSync(path, bytes);
+      const result = hashFile(path);
+      expect(result.bytes.equals(bytes)).toBe(true);
+      expect(result.digest).toBe(sha256Digest(bytes));
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("hashes non-ASCII bytes without text normalization", () => {
+    const composed = Buffer.from("café", "utf8");
+    const decomposed = Buffer.from("cafe\u0301", "utf8");
+    expect(sha256Digest(composed)).not.toBe(sha256Digest(decomposed));
+  });
+});

package/test/cli-help.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const BIN = path.resolve(__dirname, "../dist/bin.js");
+
+beforeAll(() => {
+  if (!existsSync(BIN)) {
+    throw new Error(`bin not built — run 'pnpm -r --filter @linkedclaw/cli build' first (${BIN})`);
+  }
+});
+
+function run(args: string[]): { code: number | null; stdout: string; stderr: string } {
+  const r = spawnSync("node", [BIN, ...args], { encoding: "utf8" });
+  return { code: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+}
+
+describe("cli help", () => {
+  it("--help lists every top-level verb from §3.9", () => {
+    const { code, stdout } = run(["--help"]);
+    expect(code).toBe(0);
+    for (const verb of [
+      "provider", "gig-task", "search", "hire", "send", "end",
+      "invoke", "receipt", "trust", "credits", "register", "login", "whoami",
+      "agent", "arena",
+    ]) {
+      expect(stdout).toContain(verb);
+    }
+  });
+
+  it("hire --help shows --message and --interactive", () => {
+    const { code, stdout } = run(["hire", "--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toContain("--message");
+    expect(stdout).toContain("--interactive");
+  });
+
+  it("register --help shows --no-browser and --cloud-url", () => {
+    const { code, stdout } = run(["register", "--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toContain("--no-browser");
+    expect(stdout).toContain("--cloud-url");
+  });
+
+  it("provider --help shows all six subcommands", () => {
+    const { code, stdout } = run(["provider", "--help"]);
+    expect(code).toBe(0);
+    for (const sub of ["register", "update", "listings", "run", "pick", "submit"]) {
+      expect(stdout).toContain(sub);
+    }
+  });
+
+  it("gig-task --help shows all six subcommands", () => {
+    const { code, stdout } = run(["gig-task", "--help"]);
+    expect(code).toBe(0);
+    for (const sub of ["create", "get", "list", "available", "accept", "submit"]) {
+      expect(stdout).toContain(sub);
+    }
+  });
+
+  it("arena --help shows all subcommands", () => {
+    const { code, stdout } = run(["arena", "--help"]);
+    expect(code).toBe(0);
+    for (const sub of ["tournament", "register", "offers", "accept", "submit", "list", "leaderboard"]) {
+      expect(stdout).toContain(sub);
+    }
+  });
+
+  it("arena tournament help shows create and idempotency key", () => {
+    const tournament = run(["arena", "tournament", "--help"]);
+    expect(tournament.code).toBe(0);
+    expect(tournament.stdout).toContain("create");
+
+    const create = run(["arena", "tournament", "create", "--help"]);
+    expect(create.code).toBe(0);
+    expect(create.stdout).toContain("--idempotency-key");
+    expect(create.stdout).toContain("--target");
+  });
+});