@ryanfw/prompt-orchestration-pipeline 1.3.2 → 1.3.4

package/src/config/__tests__/sse-events.test.ts

@@ -0,0 +1,470 @@
+import { describe, expect, it } from "bun:test";
+import type { APIJob } from "../../ui/state/types.ts";
+import {
+  DOCUMENTED_SSE_EVENTS,
+  emitSseEvent,
+  parseSseEvent,
+  SseEvent,
+  type JobWire,
+  type SseEventType,
+} from "../sse-events.ts";
+
+type _AssertJobWireAssignableToAPIJob = JobWire extends APIJob ? true : false;
+const _assertJobWireAssignable: _AssertJobWireAssignableToAPIJob = true;
+
+describe("SseEvent", () => {
+  describe("parseSseEvent round-trips each variant", () => {
+    it("parses state:change with required jobId and path", () => {
+      // Arrange
+      const data = { jobId: "job-1", path: "pipeline-data/current/job-1/tasks-status.json" };
+
+      // Act
+      const event = parseSseEvent("state:change", data);
+
+      // Assert
+      expect(event).not.toBeNull();
+      expect(event?.type).toBe("state:change");
+      expect(event?.data).toEqual(data);
+    });
+
+    it("parses state:summary with changeCount", () => {
+      // Arrange
+      const data = { changeCount: 7 };
+
+      // Act
+      const event = parseSseEvent("state:summary", data);
+
+      // Assert
+      expect(event).not.toBeNull();
+      expect(event?.type).toBe("state:summary");
+      expect(event?.data).toEqual(data);
+    });
+
+    it("parses job:created with a complete JobWire payload", () => {
+      // Arrange
+      const data = {
+        jobId: "job-abc",
+        title: "My Job",
+        status: "running",
+        progress: 42,
+        createdAt: "2026-06-19T10:00:00.000Z",
+        updatedAt: "2026-06-19T10:05:00.000Z",
+        location: "current",
+        tasks: { research: { state: "done" } },
+        costsSummary: {
+          totalTokens: 100,
+          totalInputTokens: 60,
+          totalOutputTokens: 40,
+          totalCost: 0.5,
+          totalInputCost: 0.3,
+          totalOutputCost: 0.2,
+          estimatedCost: 0,
+          hasEstimated: false,
+          unavailableCost: 0,
+        },
+      };
+
+      // Act
+      const event = parseSseEvent("job:created", data);
+
+      // Assert
+      expect(event).not.toBeNull();
+      expect(event?.type).toBe("job:created");
+      expect(event?.data).toEqual(data);
+    });
+
+    it("parses job:updated with a complete JobWire payload", () => {
+      // Arrange
+      const data = {
+        jobId: "job-abc",
+        title: "My Job",
+        status: "complete",
+        progress: 100,
+        createdAt: "2026-06-19T10:00:00.000Z",
+        updatedAt: "2026-06-19T10:30:00.000Z",
+        location: "current",
+        tasks: {},
+        costsSummary: {
+          totalTokens: 200,
+          totalInputTokens: 120,
+          totalOutputTokens: 80,
+          totalCost: 1.0,
+          totalInputCost: 0.6,
+          totalOutputCost: 0.4,
+          estimatedCost: 0,
+          hasEstimated: false,
+          unavailableCost: 0,
+        },
+      };
+
+      // Act
+      const event = parseSseEvent("job:updated", data);
+
+      // Assert
+      expect(event).not.toBeNull();
+      expect(event?.type).toBe("job:updated");
+      expect(event?.data).toEqual(data);
+    });
+
+    it("parses job:removed with required jobId", () => {
+      // Arrange
+      const data = { jobId: "job-removed" };
+
+      // Act
+      const event = parseSseEvent("job:removed", data);
+
+      // Assert
+      expect(event).not.toBeNull();
+      expect(event?.type).toBe("job:removed");
+      expect(event?.data).toEqual(data);
+    });
+
+    it("parses heartbeat with ok and timestamp", () => {
+      // Arrange
+      const data = { ok: true, timestamp: "2026-06-19T11:00:00.000Z" };
+
+      // Act
+      const event = parseSseEvent("heartbeat", data);
+
+      // Assert
+      expect(event).not.toBeNull();
+      expect(event?.type).toBe("heartbeat");
+      expect(event?.data).toEqual(data);
+    });
+
+    it("parses seed:uploaded with an empty payload", () => {
+      // Arrange
+      const data = {};
+
+      // Act
+      const event = parseSseEvent("seed:uploaded", data);
+
+      // Assert
+      expect(event).not.toBeNull();
+      expect(event?.type).toBe("seed:uploaded");
+      expect(event?.data).toEqual({});
+    });
+  });
+
+  describe("parseSseEvent rejects unknown or invalid input", () => {
+    it("returns null for an unknown type string", () => {
+      // Arrange / Act
+      const event = parseSseEvent("task:updated", { jobId: "job-1" });
+
+      // Assert
+      expect(event).toBeNull();
+    });
+
+    it("returns null for the empty string", () => {
+      // Arrange / Act
+      const event = parseSseEvent("", { jobId: "job-1" });
+
+      // Assert
+      expect(event).toBeNull();
+    });
+
+    it("returns null for a non-string type", () => {
+      // Arrange / Act
+      const event = parseSseEvent(undefined as unknown as string, { jobId: "job-1" });
+
+      // Assert
+      expect(event).toBeNull();
+    });
+
+    it("returns null when state:change is missing jobId", () => {
+      // Arrange
+      const data = { path: "pipeline-data/current/job-1/tasks-status.json" };
+
+      // Act
+      const event = parseSseEvent("state:change", data);
+
+      // Assert
+      expect(event).toBeNull();
+    });
+
+    it("returns null when job:created is missing jobId", () => {
+      // Arrange
+      const data = {
+        title: "x",
+        status: "pending",
+        progress: 0,
+        createdAt: null,
+        updatedAt: null,
+        location: null,
+        tasks: {},
+        costsSummary: {
+          totalTokens: 0,
+          totalInputTokens: 0,
+          totalOutputTokens: 0,
+          totalCost: 0,
+          totalInputCost: 0,
+          totalOutputCost: 0,
+        },
+      };
+
+      // Act
+      const event = parseSseEvent("job:created", data);
+
+      // Assert
+      expect(event).toBeNull();
+    });
+
+    it("returns null when job:updated is missing jobId", () => {
+      // Arrange
+      const data = {
+        title: "x",
+        status: "running",
+        progress: 50,
+        createdAt: null,
+        updatedAt: null,
+        location: null,
+        tasks: {},
+        costsSummary: {
+          totalTokens: 0,
+          totalInputTokens: 0,
+          totalOutputTokens: 0,
+          totalCost: 0,
+          totalInputCost: 0,
+          totalOutputCost: 0,
+        },
+      };
+
+      // Act
+      const event = parseSseEvent("job:updated", data);
+
+      // Assert
+      expect(event).toBeNull();
+    });
+
+    it("returns null when job:removed is missing jobId", () => {
+      // Arrange
+      const data = {};
+
+      // Act
+      const event = parseSseEvent("job:removed", data);
+
+      // Assert
+      expect(event).toBeNull();
+    });
+
+    it("returns null when heartbeat has a non-boolean ok", () => {
+      // Arrange
+      const data = { ok: "yes", timestamp: "2026-06-19T11:00:00.000Z" };
+
+      // Act
+      const event = parseSseEvent("heartbeat", data);
+
+      // Assert
+      expect(event).toBeNull();
+    });
+
+    it("returns null when job:created has a mistyped status", () => {
+      // Arrange
+      const data = {
+        jobId: "job-1",
+        title: "x",
+        status: "done",
+        progress: 0,
+        createdAt: null,
+        updatedAt: null,
+        location: null,
+        tasks: {},
+        costsSummary: {
+          totalTokens: 0,
+          totalInputTokens: 0,
+          totalOutputTokens: 0,
+          totalCost: 0,
+          totalInputCost: 0,
+          totalOutputCost: 0,
+        },
+      };
+
+      // Act
+      const event = parseSseEvent("job:created", data);
+
+      // Assert
+      expect(event).toBeNull();
+    });
+  });
+
+  describe("forward-compat: extra unknown fields are preserved (passthrough)", () => {
+    it("state:change accepts and preserves unknown fields alongside jobId and path", () => {
+      // Arrange
+      const data = {
+        jobId: "job-1",
+        path: "pipeline-data/current/job-1/tasks-status.json",
+        lifecycle: "current",
+        unknownField: 42,
+        nested: { foo: "bar" },
+      };
+
+      // Act
+      const event = parseSseEvent("state:change", data);
+
+      // Assert
+      expect(event).not.toBeNull();
+      expect(event?.data).toEqual(data);
+    });
+
+    it("job:updated accepts and preserves unknown fields beyond the schema", () => {
+      // Arrange
+      const data = {
+        jobId: "job-1",
+        title: "x",
+        status: "running",
+        progress: 10,
+        createdAt: null,
+        updatedAt: null,
+        location: null,
+        tasks: {},
+        costsSummary: {
+          totalTokens: 0,
+          totalInputTokens: 0,
+          totalOutputTokens: 0,
+          totalCost: 0,
+          totalInputCost: 0,
+          totalOutputCost: 0,
+        },
+        futureField: "ok",
+      };
+
+      // Act
+      const event = parseSseEvent("job:updated", data);
+
+      // Assert
+      expect(event).not.toBeNull();
+      expect((event?.data as Record<string, unknown>).futureField).toBe("ok");
+    });
+
+    it("heartbeat accepts extra fields beyond ok and timestamp", () => {
+      // Arrange
+      const data = {
+        ok: true,
+        timestamp: "2026-06-19T11:00:00.000Z",
+        serverVersion: "1.2.3",
+      };
+
+      // Act
+      const event = parseSseEvent("heartbeat", data);
+
+      // Assert
+      expect(event).not.toBeNull();
+      expect((event?.data as Record<string, unknown>).serverVersion).toBe("1.2.3");
+    });
+
+    it("seed:uploaded accepts any payload shape", () => {
+      // Arrange
+      const data = { filename: "seed.json", size: 1234 };
+
+      // Act
+      const event = parseSseEvent("seed:uploaded", data);
+
+      // Assert
+      expect(event).not.toBeNull();
+      expect(event?.data).toEqual(data);
+    });
+  });
+});
+
+describe("emitSseEvent", () => {
+  it("broadcasts a validated event with type and data", () => {
+    // Arrange
+    const broadcasts: Array<{ type: string; data: unknown }> = [];
+    const registry = {
+      broadcast(type: string, data: unknown) {
+        broadcasts.push({ type, data });
+      },
+    };
+    const event = {
+      type: "heartbeat" as const,
+      data: { ok: true, timestamp: "2026-06-19T11:00:00.000Z" },
+    };
+
+    // Act
+    emitSseEvent(registry, event);
+
+    // Assert
+    expect(broadcasts).toHaveLength(1);
+    expect(broadcasts[0]?.type).toBe("heartbeat");
+    expect(broadcasts[0]?.data).toEqual(event.data);
+  });
+
+  it("throws and does not broadcast when the event fails re-validation", () => {
+    // Arrange
+    const broadcasts: Array<{ type: string; data: unknown }> = [];
+    const registry = {
+      broadcast(type: string, data: unknown) {
+        broadcasts.push({ type, data });
+      },
+    };
+    const badEvent = {
+      type: "heartbeat" as const,
+      data: { ok: "not-a-boolean", timestamp: "2026-06-19T11:00:00.000Z" },
+    } as unknown as Parameters<typeof emitSseEvent>[1];
+
+    // Act + Assert
+    expect(() => emitSseEvent(registry, badEvent)).toThrow(/heartbeat/);
+    expect(broadcasts).toHaveLength(0);
+  });
+});
+
+describe("SseEvent discriminated union", () => {
+  it("SseEvent.parse accepts a state:change payload", () => {
+    // Arrange
+    const payload = {
+      type: "state:change",
+      data: { jobId: "j", path: "/p" },
+    };
+
+    // Act
+    const result = SseEvent.safeParse(payload);
+
+    // Assert
+    expect(result.success).toBe(true);
+  });
+
+  it("SseEvent.parse rejects a payload whose data does not match the discriminator", () => {
+    // Arrange
+    const payload = {
+      type: "state:change",
+      data: { jobId: 123, path: "/p" },
+    };
+
+    // Act
+    const result = SseEvent.safeParse(payload);
+
+    // Assert
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("DOCUMENTED_SSE_EVENTS", () => {
+  it("lists exactly the seven browser-facing event names", () => {
+    // Arrange / Act
+    const names = [...DOCUMENTED_SSE_EVENTS].sort();
+
+    // Assert
+    expect(names).toEqual([
+      "heartbeat",
+      "job:created",
+      "job:removed",
+      "job:updated",
+      "seed:uploaded",
+      "state:change",
+      "state:summary",
+    ]);
+  });
+
+  it("does not list task:updated (legacy dead event)", () => {
+    // Arrange / Act / Assert
+    expect(DOCUMENTED_SSE_EVENTS).not.toContain("task:updated");
+  });
+
+  it("SseEventType is assignable from each documented name", () => {
+    // Arrange
+    const sample: SseEventType = DOCUMENTED_SSE_EVENTS[0];
+
+    // Assert — this assignment compiles only if every name is a valid SseEventType
+    expect(typeof sample).toBe("string");
+  });
+});

package/src/config/__tests__/statuses.test.ts

@@ -8,6 +8,7 @@ import {
   VALID_JOB_LOCATIONS,
   normalizeTaskState,
   normalizeJobStatus,
+  jobStateToStatus,
   deriveJobStatusFromTasks,
 } from "../statuses";
 
@@ -159,6 +160,10 @@ describe("normalizeJobStatus", () => {
     expect(normalizeJobStatus("completed")).toBe("complete");
   });
 
+  it("handles synonym: done → complete", () => {
+    expect(normalizeJobStatus("done")).toBe("complete");
+  });
+
   it("handles synonym: error → failed", () => {
     expect(normalizeJobStatus("error")).toBe("failed");
   });
@@ -193,6 +198,42 @@ describe("normalizeJobStatus", () => {
   });
 });
 
+describe("jobStateToStatus", () => {
+  it("returns canonical for each recognized JobState", () => {
+    expect(jobStateToStatus("pending")).toBe("pending");
+    expect(jobStateToStatus("running")).toBe("running");
+    expect(jobStateToStatus("waiting")).toBe("waiting");
+    expect(jobStateToStatus("failed")).toBe("failed");
+  });
+
+  it("maps done (persisted JobState) to complete (canonical JobStatusValue)", () => {
+    expect(jobStateToStatus("done")).toBe("complete");
+  });
+
+  it("is case-insensitive and trims whitespace", () => {
+    expect(jobStateToStatus("DONE")).toBe("complete");
+    expect(jobStateToStatus("  failed  ")).toBe("failed");
+    expect(jobStateToStatus("Waiting")).toBe("waiting");
+  });
+
+  it("returns null for non-string input", () => {
+    expect(jobStateToStatus(null)).toBeNull();
+    expect(jobStateToStatus(undefined)).toBeNull();
+    expect(jobStateToStatus(42)).toBeNull();
+    expect(jobStateToStatus({})).toBeNull();
+  });
+
+  it("returns null for unrecognized strings", () => {
+    expect(jobStateToStatus("bogus-state")).toBeNull();
+  });
+
+  it("does not accept JobStatus synonyms that are not JobState values", () => {
+    expect(jobStateToStatus("error")).toBeNull();
+    expect(jobStateToStatus("completed")).toBeNull();
+    expect(jobStateToStatus("complete")).toBeNull();
+  });
+});
+
 describe("deriveJobStatusFromTasks", () => {
   it("returns failed when any task is failed (failed priority)", () => {
     expect(deriveJobStatusFromTasks([{ state: "failed" }, { state: "done" }])).toBe("failed");

package/src/config/paths.ts

@@ -1,5 +1,6 @@
-import { join } from "node:path";
-import type { JobLocationValue } from "./statuses";
+import { join, resolve } from "node:path";
+
+type JobLocationValue = "pending" | "current" | "complete" | "rejected";
 
 export interface PipelinePaths {
   readonly pending: string;
@@ -57,3 +58,11 @@ export function getJobPipelinePath(
 ): string {
   return join(getJobDirectoryPath(baseDir, jobId, location), "pipeline.json");
 }
+
+export function resolveWorkspaceRoot(explicit?: string): string {
+  const raw = explicit ?? process.env["PO_ROOT"];
+  if (!raw) {
+    throw new Error("Workspace root is required: pass --root or set PO_ROOT");
+  }
+  return resolve(raw);
+}