@united-workforce/cli 0.3.0 → 0.5.0

package/src/__tests__/write-envelope.test.ts

@@ -0,0 +1,257 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { openStore } from "@ocas/fs";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { isOutputFormat, type OutputFormat, SUPPORTED_FORMATS, writeEnvelope } from "../format.js";
+import { registerUwfSchemas, type UwfSchemaHashes } from "../schemas.js";
+
+let tmp: string;
+let store: Awaited<ReturnType<typeof openStore>>;
+let schemas: UwfSchemaHashes;
+
+beforeEach(async () => {
+  tmp = await mkdtemp(join(tmpdir(), "uwf-write-envelope-"));
+  store = await openStore(tmp);
+  schemas = await registerUwfSchemas(store);
+});
+
+afterEach(async () => {
+  await rm(tmp, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+function captureStdout<T>(fn: () => Promise<T>): { result: Promise<T>; output: string[] } {
+  const buf: string[] = [];
+  const spy = vi.spyOn(process.stdout, "write").mockImplementation(((
+    chunk: string | Uint8Array,
+  ): boolean => {
+    buf.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+    return true;
+  }) as typeof process.stdout.write);
+  return {
+    result: (async () => {
+      try {
+        return await fn();
+      } finally {
+        spy.mockRestore();
+      }
+    })(),
+    output: buf,
+  };
+}
+
+describe("isOutputFormat type guard", () => {
+  test("accepts every supported format", () => {
+    for (const fmt of SUPPORTED_FORMATS) {
+      expect(isOutputFormat(fmt)).toBe(true);
+    }
+  });
+
+  test("rejects unknown formats", () => {
+    expect(isOutputFormat("xml")).toBe(false);
+    expect(isOutputFormat("")).toBe(false);
+    expect(isOutputFormat("JSON")).toBe(false);
+  });
+});
+
+describe("SUPPORTED_FORMATS", () => {
+  test("contains exactly the five formats specified in cli-envelope-writer.md", () => {
+    expect([...SUPPORTED_FORMATS].sort()).toEqual(["json", "raw-json", "raw-yaml", "text", "yaml"]);
+  });
+});
+
+describe("writeEnvelope — json format", () => {
+  test("emits {type,value} JSON envelope with trailing newline", async () => {
+    const payload = { valid: true, errors: [] };
+    const { result, output } = captureStdout(async () =>
+      writeEnvelope(payload, "validate-result", { format: "json", store, schemas }),
+    );
+    await result;
+
+    const out = output.join("");
+    expect(out.endsWith("\n")).toBe(true);
+    const parsed = JSON.parse(out);
+    expect(parsed).toEqual({
+      type: schemas.outputs["validate-result"],
+      value: { valid: true, errors: [] },
+    });
+  });
+});
+
+describe("writeEnvelope — yaml format", () => {
+  test("emits envelope yaml with type then value keys", async () => {
+    const payload = { valid: false, errors: ["a", "b"] };
+    const { result, output } = captureStdout(async () =>
+      writeEnvelope(payload, "validate-result", { format: "yaml", store, schemas }),
+    );
+    await result;
+
+    const out = output.join("");
+    expect(out.endsWith("\n")).toBe(true);
+    expect(out).toContain(`type: ${schemas.outputs["validate-result"]}`);
+    expect(out).toContain("value:");
+    expect(out).toContain("valid: false");
+    // type must precede value
+    expect(out.indexOf("type:")).toBeLessThan(out.indexOf("value:"));
+  });
+});
+
+describe("writeEnvelope — raw-json format", () => {
+  test("emits bare value JSON without envelope (legacy 0.5.0 shape)", async () => {
+    const payload = { valid: true, errors: [] };
+    const { result, output } = captureStdout(async () =>
+      writeEnvelope(payload, "validate-result", { format: "raw-json", store, schemas }),
+    );
+    await result;
+
+    const out = output.join("");
+    expect(out.endsWith("\n")).toBe(true);
+    const parsed = JSON.parse(out);
+    expect(parsed).toEqual({ valid: true, errors: [] });
+    // Must NOT contain envelope keys
+    expect(parsed.type).toBeUndefined();
+    expect(parsed.value).toBeUndefined();
+  });
+});
+
+describe("writeEnvelope — raw-yaml format", () => {
+  test("emits bare value YAML without envelope (legacy 0.5.0 shape)", async () => {
+    const payload = { valid: true, errors: [] };
+    const { result, output } = captureStdout(async () =>
+      writeEnvelope(payload, "validate-result", { format: "raw-yaml", store, schemas }),
+    );
+    await result;
+
+    const out = output.join("");
+    expect(out.endsWith("\n")).toBe(true);
+    expect(out).toContain("valid: true");
+    expect(out).toContain("errors:");
+    expect(out).not.toContain("type:");
+    expect(out).not.toContain("value:");
+  });
+});
+
+describe("writeEnvelope — text format (Liquid template)", () => {
+  test("renders validate-result valid case as `✓ valid`", async () => {
+    const payload = { valid: true, errors: [] };
+    const { result, output } = captureStdout(async () =>
+      writeEnvelope(payload, "validate-result", { format: "text", store, schemas }),
+    );
+    await result;
+
+    const out = output.join("");
+    expect(out.trim()).toBe("✓ valid");
+  });
+
+  test("renders validate-result invalid case with bulleted errors", async () => {
+    const payload = {
+      valid: false,
+      errors: ['unknown role "bogus"', "$START missing resume edge"],
+    };
+    const { result, output } = captureStdout(async () =>
+      writeEnvelope(payload, "validate-result", { format: "text", store, schemas }),
+    );
+    await result;
+
+    const out = output.join("");
+    expect(out).toContain("✗ invalid (2 errors)");
+    expect(out).toContain('  - unknown role "bogus"');
+    expect(out).toContain("  - $START missing resume edge");
+  });
+
+  test("renders workflow-add as Registered/Hash key-value lines", async () => {
+    const payload = { name: "review-pr", hash: "2TBP6T37TZAJZ" };
+    const { result, output } = captureStdout(async () =>
+      writeEnvelope(payload, "workflow-add", { format: "text", store, schemas }),
+    );
+    await result;
+
+    const out = output.join("");
+    expect(out).toBe("Registered  review-pr\nHash        2TBP6T37TZAJZ\n");
+    // No JSON envelope leakage
+    expect(out).not.toContain("{");
+    expect(out).not.toContain("undefined");
+    // Single trailing newline
+    expect(out.endsWith("\n")).toBe(true);
+    expect(out.endsWith("\n\n")).toBe(false);
+  });
+
+  test("workflow-add tolerates empty hash field without throwing", async () => {
+    const payload = { name: "review-pr", hash: "" };
+    const { result, output } = captureStdout(async () =>
+      writeEnvelope(payload, "workflow-add", { format: "text", store, schemas }),
+    );
+    await result;
+
+    const out = output.join("");
+    // Renders without throwing; empty hash leaves trailing whitespace
+    expect(out).toContain("Registered  review-pr");
+    expect(out).toContain("Hash        ");
+    expect(out).not.toContain("undefined");
+  });
+});
+
+describe("writeEnvelope — workflow-add formats", () => {
+  test("json format wraps payload in {type,value} envelope", async () => {
+    const payload = { name: "review-pr", hash: "2TBP6T37TZAJZ" };
+    const { result, output } = captureStdout(async () =>
+      writeEnvelope(payload, "workflow-add", { format: "json", store, schemas }),
+    );
+    await result;
+
+    const out = output.join("");
+    const parsed = JSON.parse(out);
+    expect(parsed).toEqual({
+      type: schemas.outputs["workflow-add"],
+      value: { name: "review-pr", hash: "2TBP6T37TZAJZ" },
+    });
+  });
+
+  test("raw-json format emits bare payload (legacy 0.5.0 shape)", async () => {
+    const payload = { name: "review-pr", hash: "2TBP6T37TZAJZ" };
+    const { result, output } = captureStdout(async () =>
+      writeEnvelope(payload, "workflow-add", { format: "raw-json", store, schemas }),
+    );
+    await result;
+
+    const out = output.join("");
+    expect(out).toBe('{"name":"review-pr","hash":"2TBP6T37TZAJZ"}\n');
+  });
+
+  test("yaml format emits envelope with type and value keys", async () => {
+    const payload = { name: "review-pr", hash: "2TBP6T37TZAJZ" };
+    const { result, output } = captureStdout(async () =>
+      writeEnvelope(payload, "workflow-add", { format: "yaml", store, schemas }),
+    );
+    await result;
+
+    const out = output.join("");
+    expect(out).toContain(`type: ${schemas.outputs["workflow-add"]}`);
+    expect(out).toContain("value:");
+    expect(out).toContain("name: review-pr");
+    expect(out).toContain("hash: 2TBP6T37TZAJZ");
+  });
+});
+
+describe("writeEnvelope — schema lookup", () => {
+  test("throws when schema short name is unknown", async () => {
+    await expect(
+      // @ts-expect-error invalid schema name on purpose
+      writeEnvelope({}, "not-a-real-schema", { format: "json", store, schemas }),
+    ).rejects.toThrow(/output schema not registered/);
+  });
+
+  test("each format calls in to the same registered schema hash", async () => {
+    const payload = { valid: true, errors: [] };
+    const formats: OutputFormat[] = ["json", "yaml"];
+    for (const fmt of formats) {
+      const { result, output } = captureStdout(async () =>
+        writeEnvelope(payload, "validate-result", { format: fmt, store, schemas }),
+      );
+      await result;
+      const out = output.join("");
+      expect(out).toContain(schemas.outputs["validate-result"]);
+    }
+  });
+});

package/src/background/background.ts

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { RunningThreadItem, ThreadId } from "@united-workforce/protocol";
@@ -18,6 +19,42 @@ export function getMarkerPath(storageRoot: string, threadId: ThreadId): string {
   return join(getRunningDir(storageRoot), `${threadId}.json`);
 }
 
+/**
+ * Read the process start time from /proc/<pid>/stat (field 22, starttime).
+ * Returns the value in clock ticks since boot, or null on non-Linux systems
+ * or when the process does not exist.
+ */
+export function getProcessStartTime(pid: number): number | null {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    // /proc/<pid>/stat format: pid (comm) state ... field22_starttime ...
+    // The comm field can contain spaces and parentheses, so we find the last ')' first
+    const closeParenIdx = stat.lastIndexOf(")");
+    if (closeParenIdx === -1) {
+      return null;
+    }
+    // Fields after (comm) start at index 2 (state is field 3, index 2 in 0-based after split)
+    // starttime is field 22 (1-based), which is index 19 in the fields after ')'
+    const fieldsAfterComm = stat
+      .slice(closeParenIdx + 2)
+      .trim()
+      .split(" ");
+    // Field indices after comm (0-based): 0=state(3), 1=ppid(4), ..., 19=starttime(22)
+    const startTimeStr = fieldsAfterComm[19];
+    if (startTimeStr === undefined) {
+      return null;
+    }
+    const startTime = Number(startTimeStr);
+    if (Number.isNaN(startTime)) {
+      return null;
+    }
+    return startTime;
+  } catch {
+    // /proc not available (non-Linux) or process doesn't exist
+    return null;
+  }
+}
+
 /**
  * Check if a PID is still running.
  * Returns true if the process exists, false otherwise.
@@ -33,6 +70,39 @@ export function isPidAlive(pid: number): boolean {
   }
 }
 
+/**
+ * Validate that a running marker still refers to the same process.
+ * Checks both that the PID is alive AND that its start time matches.
+ * Returns false if:
+ *   - The PID is no longer alive
+ *   - The PID is alive but its start time doesn't match (PID was recycled)
+ * Returns true if:
+ *   - PID is alive AND start times match
+ *   - PID is alive AND marker has null processStartTime (backward compat / non-Linux)
+ */
+export function isMarkerValid(marker: RunningMarker): boolean {
+  if (!isPidAlive(marker.pid)) {
+    return false;
+  }
+
+  // If marker has no processStartTime (legacy marker or non-Linux at creation time),
+  // fall back to PID-alive-only check for backward compatibility
+  if (marker.processStartTime === null) {
+    return true;
+  }
+
+  // Verify process identity by comparing start times
+  const actualStartTime = getProcessStartTime(marker.pid);
+
+  // If we can't read the actual start time (non-Linux runtime), trust PID-alive check
+  if (actualStartTime === null) {
+    return true;
+  }
+
+  // Start times must match — if they differ, PID was recycled
+  return marker.processStartTime === actualStartTime;
+}
+
 /**
  * Create a marker file for a running thread.
  * Writes to a temp file in the same directory, then atomically renames.
@@ -63,6 +133,7 @@ export async function deleteMarker(storageRoot: string, threadId: ThreadId): Pro
 
 /**
  * Read a marker file. Returns null if file doesn't exist or is invalid.
+ * Handles legacy markers that lack processStartTime by defaulting to null.
  */
 export async function readMarker(
   storageRoot: string,
@@ -71,7 +142,15 @@ export async function readMarker(
   const markerPath = getMarkerPath(storageRoot, threadId);
   try {
     const content = await readFile(markerPath, "utf8");
-    const marker = JSON.parse(content) as RunningMarker;
+    const raw = JSON.parse(content) as Record<string, unknown>;
+    // Normalize legacy markers that lack processStartTime
+    const marker: RunningMarker = {
+      thread: raw.thread as ThreadId,
+      workflow: raw.workflow as string,
+      pid: raw.pid as number,
+      startedAt: raw.startedAt as number,
+      processStartTime: typeof raw.processStartTime === "number" ? raw.processStartTime : null,
+    };
     return marker;
   } catch {
     return null;
@@ -80,6 +159,8 @@ export async function readMarker(
 
 /**
  * List all running threads, filtering out stale markers.
+ * A marker is stale if the PID is dead or if the PID was recycled
+ * (processStartTime mismatch).
  */
 export async function listRunningThreads(storageRoot: string): Promise<RunningThreadItem[]> {
   const runningDir = getRunningDir(storageRoot);
@@ -107,8 +188,8 @@ export async function listRunningThreads(storageRoot: string): Promise<RunningTh
       continue;
     }
 
-    if (!isPidAlive(marker.pid)) {
-      // Stale marker - process no longer exists
+    if (!isMarkerValid(marker)) {
+      // Stale marker - process no longer exists or PID was recycled
       await deleteMarker(storageRoot, threadId);
       continue;
     }
@@ -126,7 +207,8 @@ export async function listRunningThreads(storageRoot: string): Promise<RunningTh
 
 /**
  * Check if a thread is currently executing in the background.
- * Returns the marker if running, null otherwise.
+ * Returns the marker if running (and process identity is verified), null otherwise.
+ * Automatically deletes stale markers (dead PID or recycled PID).
  */
 export async function isThreadRunning(
   storageRoot: string,
@@ -137,8 +219,8 @@ export async function isThreadRunning(
     return null;
   }
 
-  if (!isPidAlive(marker.pid)) {
-    // Stale marker
+  if (!isMarkerValid(marker)) {
+    // Stale marker — PID dead or recycled
     await deleteMarker(storageRoot, threadId);
     return null;
   }

package/src/background/index.ts

@@ -2,7 +2,9 @@ export {
   createMarker,
   deleteMarker,
   getMarkerPath,
+  getProcessStartTime,
   getRunningDir,
+  isMarkerValid,
   isPidAlive,
   isThreadRunning,
   listRunningThreads,

package/src/background/types.ts

@@ -6,4 +6,5 @@ export type RunningMarker = {
   workflow: CasRef;
   pid: number;
   startedAt: number;
+  processStartTime: number | null;
 };