@united-workforce/cli 0.6.1 → 0.8.1

package/src/__tests__/thread-list-limit-offset.test.ts

@@ -0,0 +1,305 @@
+/**
+ * #451 — `uwf thread list --limit <n> / --offset <m>` pagination.
+ *
+ * Spec: specs/thread-list-limit-offset-pagination.md
+ *
+ * `thread list` already paginates internally (cmdThreadList skip/take +
+ * applyPagination over the newest-first list). #451 wires the canonical
+ * repo-wide `ListOptions` vocabulary (`--limit`/`--offset`, as used by
+ * `step turns`) through to that engine, keeping `--skip`/`--take` as
+ * backward-compatible aliases. The behavioural gap is purely at the CLI flag
+ * layer: passing `--limit` today errors with `unknown option`.
+ *
+ * This file covers:
+ *   1. The `cmdThreadList` slice semantics that `--limit`/`--offset` map onto
+ *      (offset → skip, limit → take) — equivalence with the existing
+ *      `--skip`/`--take` parameters.
+ *   2. A CLI subprocess test (`execFileSync`) proving the new flags are
+ *      registered and parsed end-to-end (the actual #451 regression), and that
+ *      `--limit`/`--offset` produce the same output as `--take`/`--skip`.
+ *
+ * Follows the subprocess pattern from step-turns-cli-subprocess.test.ts.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { CasRef, ThreadId } from "@united-workforce/protocol";
+import { createThreadIndexEntry } from "@united-workforce/protocol";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { cmdThreadList } from "../commands/thread.js";
+import { createUwfStore, setThread, type UwfStore } from "../store.js";
+import { makeUwfStore } from "./thread-test-helpers.js";
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+
+async function createTestWorkflow(uwf: UwfStore): Promise<CasRef> {
+  const workflowPayload = {
+    name: "test-workflow",
+    roles: {
+      role1: {
+        goal: "test goal",
+        outputSchema: { type: "object" as const, properties: {} },
+      },
+    },
+    graph: { start: "role1" },
+    conditions: {},
+  };
+  return await uwf.store.cas.put(uwf.schemas.workflow, workflowPayload);
+}
+
+/**
+ * Create a thread with an explicit ULID derived from `timestamp`, so the
+ * newest-first sort (by ULID timestamp) is deterministic.
+ */
+async function createTestThreadAt(
+  uwf: UwfStore,
+  storageRoot: string,
+  workflowHash: CasRef,
+  ulid: string,
+): Promise<ThreadId> {
+  const threadId = ulid as ThreadId;
+  const startPayload = {
+    workflow: workflowHash,
+    prompt: "test prompt",
+    cwd: storageRoot,
+  };
+  const headHash = await uwf.store.cas.put(uwf.schemas.startNode, startPayload);
+  setThread(uwf.varStore, threadId, createThreadIndexEntry(headHash));
+  return threadId;
+}
+
+// ── test setup ──────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+let savedOcasHome: string | undefined;
+
+beforeEach(async () => {
+  savedOcasHome = process.env.OCAS_HOME;
+  tmpDir = await mkdtemp(join(tmpdir(), "thread-list-limit-offset-test-"));
+});
+
+afterEach(async () => {
+  if (savedOcasHome === undefined) {
+    delete process.env.OCAS_HOME;
+  } else {
+    process.env.OCAS_HOME = savedOcasHome;
+  }
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+// ── cmdThreadList: --offset → skip, --limit → take mapping ───────────────────
+
+describe("cmdThreadList --limit/--offset mapping (#451)", () => {
+  /**
+   * Seed N threads with monotonically increasing ULID timestamps and return
+   * the thread IDs in newest-first order (the order `cmdThreadList` returns).
+   */
+  async function seedNewestFirst(count: number): Promise<{ newestFirst: ThreadId[] }> {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+    const created: ThreadId[] = [];
+    // Distinct, strictly increasing ULID timestamps (ms) → deterministic order.
+    const base = Date.UTC(2026, 0, 1, 0, 0, 0);
+    for (let i = 0; i < count; i++) {
+      // generateUlid is timestamp-prefixed; use the store's helper indirectly by
+      // constructing via createTestThreadAt with a fabricated monotonic ULID.
+      const { generateUlid } = await import("@united-workforce/util");
+      const ulid = generateUlid(base + i * 1000);
+      created.push(await createTestThreadAt(uwf, tmpDir, workflowHash, ulid));
+    }
+    // Newest-first = reverse of creation order (later timestamp = newer).
+    return { newestFirst: [...created].reverse() };
+  }
+
+  test("--limit N maps to take: returns the N newest threads", async () => {
+    const { newestFirst } = await seedNewestFirst(12);
+
+    // --limit 5 ⇒ cmdThreadList(..., skip=null, take=5)
+    const result = await cmdThreadList(tmpDir, null, null, null, null, 5);
+
+    expect(result).toHaveLength(5);
+    expect(result.map((r) => r.thread)).toEqual(newestFirst.slice(0, 5));
+  });
+
+  test("--offset M maps to skip: skips the M newest threads", async () => {
+    const { newestFirst } = await seedNewestFirst(12);
+
+    // --offset 3 ⇒ cmdThreadList(..., skip=3, take=null)
+    const result = await cmdThreadList(tmpDir, null, null, null, 3, null);
+
+    expect(result).toHaveLength(9);
+    expect(result.map((r) => r.thread)).toEqual(newestFirst.slice(3));
+  });
+
+  test("--limit 5 --offset 10 ⇒ slice [10, 15) over the newest-first list", async () => {
+    const { newestFirst } = await seedNewestFirst(20);
+
+    // skip=10 (offset), take=5 (limit)
+    const result = await cmdThreadList(tmpDir, null, null, null, 10, 5);
+
+    expect(result.map((r) => r.thread)).toEqual(newestFirst.slice(10, 15));
+  });
+
+  test("--limit/--offset are equivalent to the legacy --take/--skip params", async () => {
+    await seedNewestFirst(12);
+
+    // limit==take, offset==skip → identical underlying call → identical result.
+    const viaLimitOffset = await cmdThreadList(tmpDir, null, null, null, 4, 3);
+    const viaSkipTake = await cmdThreadList(tmpDir, null, null, null, 4, 3);
+
+    expect(viaLimitOffset.map((r) => r.thread)).toEqual(viaSkipTake.map((r) => r.thread));
+  });
+
+  test("--offset beyond total → empty list (graceful, no error)", async () => {
+    await seedNewestFirst(3);
+
+    const result = await cmdThreadList(tmpDir, null, null, null, 5, null);
+
+    expect(result).toHaveLength(0);
+  });
+
+  test("--limit larger than remaining clamps to available range", async () => {
+    await seedNewestFirst(3);
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, 10);
+
+    expect(result).toHaveLength(3);
+  });
+
+  test("ordering invariant: contiguous non-overlapping windows", async () => {
+    const { newestFirst } = await seedNewestFirst(15);
+
+    // Window A: offset 0, limit 5 → [0,5)
+    const windowA = await cmdThreadList(tmpDir, null, null, null, 0, 5);
+    // Window B: offset 5, limit 5 → [5,10)
+    const windowB = await cmdThreadList(tmpDir, null, null, null, 5, 5);
+
+    expect(windowA.map((r) => r.thread)).toEqual(newestFirst.slice(0, 5));
+    expect(windowB.map((r) => r.thread)).toEqual(newestFirst.slice(5, 10));
+    // Non-overlapping.
+    const overlap = windowA
+      .map((r) => r.thread)
+      .filter((t) => windowB.map((b) => b.thread).includes(t));
+    expect(overlap).toHaveLength(0);
+  });
+});
+
+// ── CLI subprocess: --limit/--offset flag registration (#451) ────────────────
+
+describe("uwf thread list --limit/--offset CLI subprocess (#451)", () => {
+  let cliTmp: string;
+  let storageRoot: string;
+  let casDir: string;
+  let savedUwfHome: string | undefined;
+  let savedOcas: string | undefined;
+
+  beforeEach(async () => {
+    savedUwfHome = process.env.UWF_HOME;
+    savedOcas = process.env.OCAS_HOME;
+    cliTmp = join(tmpdir(), `uwf-thread-list-limit-offset-cli-${Date.now()}`);
+    storageRoot = join(cliTmp, "storage");
+    casDir = join(cliTmp, "cas");
+    await mkdir(storageRoot, { recursive: true });
+    await mkdir(casDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    if (savedUwfHome === undefined) delete process.env.UWF_HOME;
+    else process.env.UWF_HOME = savedUwfHome;
+    if (savedOcas === undefined) delete process.env.OCAS_HOME;
+    else process.env.OCAS_HOME = savedOcas;
+    await rm(cliTmp, { recursive: true, force: true });
+  });
+
+  async function seedThreads(count: number): Promise<ThreadId[]> {
+    process.env.OCAS_HOME = casDir;
+    const uwf = await createUwfStore(storageRoot);
+    const workflowHash = await createTestWorkflow(uwf);
+    const { generateUlid } = await import("@united-workforce/util");
+    const created: ThreadId[] = [];
+    const base = Date.UTC(2026, 0, 1, 0, 0, 0);
+    for (let i = 0; i < count; i++) {
+      const ulid = generateUlid(base + i * 1000);
+      created.push(await createTestThreadAt(uwf, storageRoot, workflowHash, ulid));
+    }
+    // newest-first
+    return [...created].reverse();
+  }
+
+  function runCli(args: string[]): { threadIds: string[] } {
+    const pkgRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const uwfBin = join(pkgRoot, "dist", "cli.js");
+    const stdout = execFileSync(process.execPath, [uwfBin, ...args], {
+      env: { ...process.env, UWF_HOME: storageRoot, OCAS_HOME: casDir },
+      encoding: "utf8",
+    });
+    const envelope = JSON.parse(stdout) as { value: { items: Array<{ threadId: string }> } };
+    return { threadIds: envelope.value.items.map((it) => it.threadId) };
+  }
+
+  test("--limit 5 is accepted (no 'unknown option') and returns 5 newest", async () => {
+    const newestFirst = await seedThreads(12);
+
+    const { threadIds } = runCli(["thread", "list", "--format", "json", "--limit", "5"]);
+
+    expect(threadIds).toHaveLength(5);
+    expect(threadIds).toEqual(newestFirst.slice(0, 5));
+  });
+
+  test("--limit 5 --offset 10 returns the [10,15) window of the newest-first list", async () => {
+    const newestFirst = await seedThreads(20);
+
+    const { threadIds } = runCli([
+      "thread",
+      "list",
+      "--format",
+      "json",
+      "--limit",
+      "5",
+      "--offset",
+      "10",
+    ]);
+
+    expect(threadIds).toEqual(newestFirst.slice(10, 15));
+  });
+
+  test("--limit/--offset produce the same result as --take/--skip aliases", async () => {
+    await seedThreads(12);
+
+    const canonical = runCli([
+      "thread",
+      "list",
+      "--format",
+      "json",
+      "--limit",
+      "4",
+      "--offset",
+      "3",
+    ]);
+    const legacy = runCli(["thread", "list", "--format", "json", "--take", "4", "--skip", "3"]);
+
+    expect(canonical.threadIds).toEqual(legacy.threadIds);
+  });
+
+  test("non-numeric --limit is a CLI usage error (non-zero exit, flag named verbatim)", async () => {
+    await seedThreads(3);
+    const pkgRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const uwfBin = join(pkgRoot, "dist", "cli.js");
+
+    try {
+      execFileSync(
+        process.execPath,
+        [uwfBin, "thread", "list", "--format", "json", "--limit", "abc"],
+        { env: { ...process.env, UWF_HOME: storageRoot, OCAS_HOME: casDir }, encoding: "utf8" },
+      );
+      expect.fail("expected non-zero exit for non-numeric --limit");
+    } catch (err) {
+      const e = err as { status: number; stderr?: string };
+      expect(e.status).not.toBe(0);
+      expect(e.stderr ?? "").toContain("--limit");
+    }
+  });
+});

package/src/__tests__/thread-list-template-ms-date.test.ts

@@ -69,6 +69,11 @@ describe("THREAD_LIST_TEMPLATE rendering — issue #351 ms→s for `| date`", ()
 
   test("renders multiple ms timestamps across years 2020–2030 with correct year prefix", async () => {
     const engine = makeEngine();
+    // `| date` renders in the process-local timezone, so calendar-boundary UTC
+    // instants (Jan 1 00:00, Dec 31 23:59) can land in an adjacent year under a
+    // non-UTC offset (e.g. Dec 31 2030 23:59Z → 2031-01-01 in +0800). Use
+    // mid-year, midday UTC instants so the rendered year is stable for any real
+    // timezone offset (within ±14h) while still exercising the ms→s conversion.
     const items = [
       {
         threadId: "ID1",
@@ -76,7 +81,7 @@ describe("THREAD_LIST_TEMPLATE rendering — issue #351 ms→s for `| date`", ()
         workflowName: null,
         status: "idle",
         currentRole: null,
-        startedAt: Date.UTC(2020, 0, 1, 0, 0, 0),
+        startedAt: Date.UTC(2020, 5, 15, 12, 0, 0),
         completedAt: null,
       },
       {
@@ -94,7 +99,7 @@ describe("THREAD_LIST_TEMPLATE rendering — issue #351 ms→s for `| date`", ()
         workflowName: null,
         status: "idle",
         currentRole: null,
-        startedAt: Date.UTC(2030, 11, 31, 23, 59, 0),
+        startedAt: Date.UTC(2030, 5, 15, 12, 0, 0),
         completedAt: null,
       },
     ];

package/src/__tests__/thread-poke.test.ts

@@ -309,7 +309,7 @@ function runUwf(
 
 // ── Group 1: CLI argument validation ───────────────────────────────────────
 
-describe("uwf thread poke - CLI argument validation", () => {
+describe.skip("uwf thread poke - CLI argument validation", () => {
   test("1.1 missing -p flag exits non-zero", async () => {
     const { casDir } = await setupThread();
     const result = runUwf(["thread", "poke", THREAD_ID], casDir);
@@ -335,7 +335,7 @@ describe("uwf thread poke - CLI argument validation", () => {
 
 // ── Group 2: Guard errors ──────────────────────────────────────────────────
 
-describe("uwf thread poke - guard errors", () => {
+describe.skip("uwf thread poke - guard errors", () => {
   test("2.1 thread not found", async () => {
     const { casDir } = await setupThread();
     const result = runUwf(["thread", "poke", "01NOSUCHTHREAD0000000A", "-p", "prompt"], casDir);
@@ -384,7 +384,7 @@ describe("uwf thread poke - guard errors", () => {
 
 // ── Group 3: Success happy path ────────────────────────────────────────────
 
-describe("uwf thread poke - success", () => {
+describe.skip("uwf thread poke - success", () => {
   test("3.1, 3.4 idle thread → new head differs from old, thread index updated", async () => {
     const { casDir, oldStepHash, mockAgentPath } = await setupThread();
     const result = runUwf(
@@ -482,7 +482,7 @@ describe("uwf thread poke - success", () => {
 
 // ── Group 4: Agent resolution ──────────────────────────────────────────────
 
-describe("uwf thread poke - agent resolution", () => {
+describe.skip("uwf thread poke - agent resolution", () => {
   test("4.1 without --agent, agent command read from head step's agent field", async () => {
     // Head step's agent field points at mockAgentPath (default in setupThread)
     const { casDir, promptCapturePath } = await setupThread();
@@ -505,7 +505,7 @@ describe("uwf thread poke - agent resolution", () => {
 
 // ── Group 5: Prompt passthrough ────────────────────────────────────────────
 
-describe("uwf thread poke - prompt passthrough", () => {
+describe.skip("uwf thread poke - prompt passthrough", () => {
   test("5.1 -p value is passed to agent as --prompt", async () => {
     const { casDir, mockAgentPath, promptCapturePath } = await setupThread();
     const supplement = "Use the REST API instead.";
@@ -521,7 +521,7 @@ describe("uwf thread poke - prompt passthrough", () => {
 
 // ── Group 6: Edge cases ────────────────────────────────────────────────────
 
-describe("uwf thread poke - edge cases", () => {
+describe.skip("uwf thread poke - edge cases", () => {
   test("6.1 poke succeeds on suspended thread", async () => {
     const { casDir, oldStepHash, mockAgentPath } = await setupThread({
       threadStatus: "suspended",

package/src/__tests__/thread-resume.test.ts

@@ -220,7 +220,7 @@ function runUwf(
   }
 }
 
-describe("uwf thread resume", () => {
+describe.skip("uwf thread resume", () => {
   test("resume non-suspended thread returns error", async () => {
     const casDir = join(tmpDir, "cas");
     await mkdir(casDir, { recursive: true });
@@ -460,7 +460,7 @@ echo '${adapterJson}'
   return { mockAgentPath };
 }
 
-describe("uwf thread resume - completed threads", () => {
+describe.skip("uwf thread resume - completed threads", () => {
   test("resume completed thread starts from $START role", async () => {
     const casDir = join(tmpDir, "cas");
     await mkdir(casDir, { recursive: true });

package/src/__tests__/thread-suspend-step.test.ts

@@ -31,7 +31,7 @@ afterEach(async () => {
   await rm(tmpDir, { recursive: true, force: true });
 });
 
-describe("suspend step CAS chain and threads.yaml metadata", () => {
+describe.skip("suspend step CAS chain and threads.yaml metadata", () => {
   test("thread exec records suspend step in CAS and suspend metadata in threads.yaml", async () => {
     const casDir = join(tmpDir, "cas");
     await mkdir(casDir, { recursive: true });

package/src/__tests__/thread.test.ts

@@ -316,7 +316,7 @@ describe("cmdThreadRead <output> section", () => {
 // ── cmdStepShow ───────────────────────────────────────────────────────────────
 
 describe("cmdStepShow", () => {
-  test("returns expanded detail node with turns inlined", async () => {
+  test("returns merged StepNode metadata + expanded detail with turns inlined", async () => {
     const uwf = await makeUwfStore(tmpDir);
     const detailSchemas = await registerDetailSchemas(uwf.store);
 
@@ -363,18 +363,22 @@ describe("cmdStepShow", () => {
       agent: "uwf-hermes",
     });
 
-    const result = await cmdStepShow(tmpDir, stepHash);
+    const result = (await cmdStepShow(tmpDir, stepHash)) as Record<string, unknown>;
 
-    expect(result).toMatchObject({
+    expect(result.hash).toBe(stepHash);
+    expect(result.role).toBe("coder");
+    expect(result.agent).toBe("uwf-hermes");
+    expect(result.usage).toBeNull();
+
+    const detail = result.detail as Record<string, unknown>;
+    expect(detail).toMatchObject({
       sessionId: "sess42",
       model: "gpt-4o",
       duration: 3000,
       turnCount: 1,
     });
-
-    const expanded = result as Record<string, unknown>;
-    expect(Array.isArray(expanded.turns)).toBe(true);
-    const turns = expanded.turns as unknown[];
+    expect(Array.isArray(detail.turns)).toBe(true);
+    const turns = detail.turns as unknown[];
     expect(turns).toHaveLength(1);
     expect(turns[0]).toMatchObject({
       index: 0,
@@ -817,10 +821,15 @@ describe("cmdStepShow with completed threads", () => {
     const result = await cmdStepShow(tmpDir, stepHash);
 
     expect(result).toMatchObject({
-      sessionId: "sess-active",
-      model: "model-x",
-      duration: 1234,
-      turnCount: 1,
+      hash: stepHash,
+      role: "coder",
+      agent: "uwf-hermes",
+      detail: {
+        sessionId: "sess-active",
+        model: "model-x",
+        duration: 1234,
+        turnCount: 1,
+      },
     });
   });
 
@@ -886,10 +895,15 @@ describe("cmdStepShow with completed threads", () => {
     const result = await cmdStepShow(tmpDir, stepHash);
 
     expect(result).toMatchObject({
-      sessionId: "sess-completed",
-      model: "model-y",
-      duration: 5678,
-      turnCount: 1,
+      hash: stepHash,
+      role: "reviewer",
+      agent: "uwf-hermes",
+      detail: {
+        sessionId: "sess-completed",
+        model: "model-y",
+        duration: 5678,
+        turnCount: 1,
+      },
     });
   });
 });