@united-workforce/cli 0.4.0 → 0.5.0

package/src/concurrency/concurrency.ts

@@ -0,0 +1,245 @@
+import { unlinkSync } from "node:fs";
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isPidAlive } from "../background/index.js";
+import type { AcquireSlotOptions, SlotHandle } from "./types.js";
+
+/** Default concurrency limit when no config or flag is provided. */
+export const DEFAULT_MAX_RUNNING = 2;
+
+/** Default poll interval (ms) for waiting on a slot. */
+const DEFAULT_POLL_INTERVAL_MS = 2000;
+
+/**
+ * Get the path to the slots directory.
+ */
+export function getSlotsDir(storageRoot: string): string {
+  return join(storageRoot, "slots");
+}
+
+/**
+ * Count active slot files (alive PIDs only). Stale slots are skipped but not removed.
+ */
+export async function countActiveSlots(storageRoot: string): Promise<number> {
+  const slotsDir = getSlotsDir(storageRoot);
+  let files: string[];
+  try {
+    files = await readdir(slotsDir);
+  } catch {
+    return 0;
+  }
+
+  let count = 0;
+  for (const file of files) {
+    if (!file.endsWith(".slot")) {
+      continue;
+    }
+    const pidStr = file.slice(0, -5);
+    const pid = Number(pidStr);
+    if (Number.isNaN(pid)) {
+      continue;
+    }
+    if (isPidAlive(pid)) {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * Remove slot files whose PIDs are no longer alive.
+ * Returns the number of stale slots cleaned.
+ */
+export async function cleanStaleSlots(storageRoot: string): Promise<number> {
+  const slotsDir = getSlotsDir(storageRoot);
+  let files: string[];
+  try {
+    files = await readdir(slotsDir);
+  } catch {
+    return 0;
+  }
+
+  let cleaned = 0;
+  for (const file of files) {
+    if (!file.endsWith(".slot")) {
+      continue;
+    }
+    const pidStr = file.slice(0, -5);
+    const pid = Number(pidStr);
+    if (Number.isNaN(pid)) {
+      continue;
+    }
+    if (!isPidAlive(pid)) {
+      try {
+        await rm(join(slotsDir, file), { force: true });
+        cleaned++;
+      } catch {
+        // Ignore removal errors (race with another cleanup)
+      }
+    }
+  }
+  return cleaned;
+}
+
+/**
+ * Create a slot file for the current process. Returns the path to the created file.
+ */
+async function writeSlotFile(storageRoot: string): Promise<string> {
+  const slotsDir = getSlotsDir(storageRoot);
+  await mkdir(slotsDir, { recursive: true });
+  const slotPath = join(slotsDir, `${process.pid}.slot`);
+  await writeFile(slotPath, "", "utf8");
+  return slotPath;
+}
+
+/**
+ * Remove a slot file. Idempotent — silently ignores missing file.
+ */
+async function removeSlotFile(slotPath: string): Promise<void> {
+  try {
+    await rm(slotPath, { force: true });
+  } catch {
+    // Already removed or race condition — safe to ignore
+  }
+}
+
+function sleep(ms: number, signal: AbortSignal | null): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("aborted"));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    if (signal !== null) {
+      const onAbort = () => {
+        clearTimeout(timer);
+        reject(new Error("aborted"));
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
+
+/**
+ * Try to claim a slot. Returns the slot path on success, null if a race was
+ * detected (post-write count exceeds maxRunning → rolls back).
+ */
+async function tryClaimSlot(storageRoot: string, maxRunning: number): Promise<string | null> {
+  const slotPath = await writeSlotFile(storageRoot);
+  const postWriteCount = await countActiveSlots(storageRoot);
+  if (postWriteCount > maxRunning) {
+    await removeSlotFile(slotPath);
+    return null;
+  }
+  return slotPath;
+}
+
+function createSlotHandle(slotPath: string): SlotHandle {
+  let released = false;
+  return {
+    slotPath,
+    release: async () => {
+      if (released) return;
+      released = true;
+      await removeSlotFile(slotPath);
+    },
+  };
+}
+
+type ResolvedOptions = {
+  onWaiting: ((info: string) => void) | null;
+  onAcquired: (() => void) | null;
+  pollIntervalMs: number;
+  signal: AbortSignal | null;
+};
+
+function resolveOptions(options: Partial<AcquireSlotOptions>): ResolvedOptions {
+  return {
+    onWaiting: options.onWaiting ?? null,
+    onAcquired: options.onAcquired ?? null,
+    pollIntervalMs: options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+    signal: options.signal ?? null,
+  };
+}
+
+function notifyWaiting(opts: ResolvedOptions, waited: boolean, message: string): boolean {
+  if (!waited && opts.onWaiting !== null) {
+    opts.onWaiting(message);
+    return true;
+  }
+  return waited;
+}
+
+/**
+ * Acquire a concurrency slot. If all slots are occupied, polls until one is available.
+ *
+ * Race protection: after writing the slot file, double-checks countActiveSlots.
+ * If the count exceeds maxRunning, rolls back (removes own slot) and retries.
+ */
+export async function acquireSlot(
+  storageRoot: string,
+  maxRunning: number,
+  options: Partial<AcquireSlotOptions> = {},
+): Promise<SlotHandle> {
+  const opts = resolveOptions(options);
+  let waited = false;
+
+  while (true) {
+    await cleanStaleSlots(storageRoot);
+
+    const currentCount = await countActiveSlots(storageRoot);
+    if (currentCount >= maxRunning) {
+      waited = notifyWaiting(opts, waited, `${currentCount}/${maxRunning} running`);
+      await sleep(opts.pollIntervalMs, opts.signal);
+      continue;
+    }
+
+    const slotPath = await tryClaimSlot(storageRoot, maxRunning);
+    if (slotPath === null) {
+      waited = notifyWaiting(opts, waited, `race detected, retrying`);
+      await sleep(opts.pollIntervalMs, opts.signal);
+      continue;
+    }
+
+    if (waited && opts.onAcquired !== null) {
+      opts.onAcquired();
+    }
+    return createSlotHandle(slotPath);
+  }
+}
+
+/**
+ * Alias for SlotHandle.release() — explicit function form for callers that
+ * prefer passing the handle as an argument.
+ */
+export async function releaseSlot(handle: SlotHandle): Promise<void> {
+  await handle.release();
+}
+
+/**
+ * Install process signal handlers that release the slot on SIGINT/SIGTERM.
+ * Returns a cleanup function that removes the handlers (call on normal exit).
+ */
+export function installSlotCleanup(handle: SlotHandle): () => void {
+  const cleanup = () => {
+    try {
+      unlinkSync(handle.slotPath);
+    } catch {
+      // Already removed
+    }
+  };
+
+  const onSignal = () => {
+    cleanup();
+    process.exit(1);
+  };
+
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+
+  // Return a function to uninstall the handlers
+  return () => {
+    process.removeListener("SIGINT", onSignal);
+    process.removeListener("SIGTERM", onSignal);
+  };
+}

package/src/concurrency/index.ts

@@ -0,0 +1,10 @@
+export {
+  acquireSlot,
+  cleanStaleSlots,
+  countActiveSlots,
+  DEFAULT_MAX_RUNNING,
+  getSlotsDir,
+  installSlotCleanup,
+  releaseSlot,
+} from "./concurrency.js";
+export type { AcquireSlotOptions, SlotHandle } from "./types.js";

package/src/concurrency/types.ts

@@ -0,0 +1,19 @@
+/** Handle returned by acquireSlot; call release() to free the slot. */
+export type SlotHandle = {
+  /** Remove the slot file. Idempotent — second call is a no-op. */
+  release: () => Promise<void>;
+  /** The slot file path (for signal-handler cleanup). */
+  slotPath: string;
+};
+
+/** Options for acquireSlot polling behavior and callbacks. */
+export type AcquireSlotOptions = {
+  /** Called when the function starts waiting (all slots occupied). */
+  onWaiting: ((info: string) => void) | null;
+  /** Called when a slot becomes available after waiting. */
+  onAcquired: (() => void) | null;
+  /** Poll interval in milliseconds (default: 2000). */
+  pollIntervalMs: number;
+  /** AbortSignal to cancel waiting. */
+  signal: AbortSignal | null;
+};

package/src/format.ts

@@ -1,12 +1,292 @@
+import type { Hash, Store } from "@ocas/core";
+import type { OutputSchemaName } from "@united-workforce/protocol";
+import { Liquid } from "liquidjs";
 import { stringify } from "yaml";
+import type { UwfSchemaHashes } from "./schemas.js";
+import {
+  renderConfigGet,
+  renderConfigList,
+  renderConfigSet,
+  renderLogList,
+  renderLogShow,
+  renderStepList,
+  renderStepShow,
+  renderThreadCancel,
+  renderThreadList,
+  renderThreadShow,
+  renderThreadStart,
+  renderThreadStop,
+  renderWorkflowList,
+  renderWorkflowShow,
+} from "./text-renderers.js";
 
-export type OutputFormat = "json" | "yaml";
+/**
+ * Five output formats supported by the uwf CLI. `text` is the default and
+ * produces a Liquid-rendered human-readable view. `json` and `yaml` wrap the
+ * payload in an ocas envelope `{ type, value }` for self-describing output.
+ * `raw-json` and `raw-yaml` emit the bare value, preserving 0.5.0 byte-for-byte
+ * output for backward-compat consumers.
+ */
+export type OutputFormat = "text" | "json" | "yaml" | "raw-json" | "raw-yaml";
 
-export function formatOutput(data: unknown, format: OutputFormat): string {
+export const SUPPORTED_FORMATS: readonly OutputFormat[] = [
+  "text",
+  "json",
+  "yaml",
+  "raw-json",
+  "raw-yaml",
+];
+
+export function isOutputFormat(v: string): v is OutputFormat {
+  return (SUPPORTED_FORMATS as readonly string[]).includes(v);
+}
+
+/**
+ * Per-command text renderer registry. Maps a fully-qualified command path
+ * (e.g. `"thread list"`, `"workflow show"`) to a function that converts
+ * the command's payload into a human-readable string.
+ *
+ * Renderers must:
+ * - Always return a `string` (never `undefined`).
+ * - Tolerate missing/null fields without throwing.
+ *
+ * The Liquid template path inside `writeEnvelope` is the primary rendering
+ * implementation. This registry exists so callers without a CAS store
+ * (tests, library consumers) can resolve `text` rendering, and so
+ * `formatOutput(data, "text", commandPath)` returns a meaningful string.
+ */
+export type TextRenderer = (data: unknown) => string;
+
+export const TEXT_RENDERERS: Record<string, TextRenderer> = {
+  "thread list": renderThreadList,
+  "thread show": renderThreadShow,
+  "thread start": renderThreadStart,
+  "thread cancel": renderThreadCancel,
+  "thread stop": renderThreadStop,
+  "workflow list": renderWorkflowList,
+  "workflow show": renderWorkflowShow,
+  "step list": renderStepList,
+  "step show": renderStepShow,
+  "config list": renderConfigList,
+  "config get": renderConfigGet,
+  "config set": renderConfigSet,
+  "log list": renderLogList,
+  "log show": renderLogShow,
+};
+
+/** Look up a registered text renderer by command path. */
+export function getTextRenderer(commandPath: string): TextRenderer | undefined {
+  return TEXT_RENDERERS[commandPath];
+}
+
+/** Register (or override) a text renderer for a command path. */
+export function registerTextRenderer(commandPath: string, renderer: TextRenderer): void {
+  TEXT_RENDERERS[commandPath] = renderer;
+}
+
+/**
+ * Format a payload as a string in the requested output format.
+ *
+ * For `"text"`, `formatOutput` looks up the registered renderer for
+ * `commandPath` (when provided) and falls back to a JSON serialization when
+ * no renderer is registered. The result is always a `string` — never
+ * `undefined`. For `"json"` and `"yaml"` the bare value is serialized.
+ * For `"raw-json"` and `"raw-yaml"` the output is identical to `"json"` /
+ * `"yaml"` (both modes emit the bare value; envelope wrapping happens in
+ * `writeEnvelope`).
+ *
+ * Note: this is the legacy in-process formatter used by raw output paths
+ * (`thread cancel`, `step fork`, `setup`, `log/config`) and tests. Production
+ * commands with a registered output schema go through `writeEnvelope`.
+ */
+export function formatOutput(data: unknown, format: OutputFormat, commandPath?: string): string {
   switch (format) {
     case "json":
+    case "raw-json":
       return JSON.stringify(data);
     case "yaml":
+    case "raw-yaml":
       return stringify(data, { aliasDuplicateObjects: false }).trimEnd();
+    case "text": {
+      if (commandPath !== undefined) {
+        const renderer = TEXT_RENDERERS[commandPath];
+        if (renderer !== undefined) {
+          return renderer(data);
+        }
+      }
+      // Fallback: JSON pretty-printed so `formatOutput(_, "text")` never returns
+      // `"undefined"` (the bug from issue #327).
+      return JSON.stringify(data, null, 2);
+    }
+  }
+}
+
+const schemaHashCache = new Map<OutputSchemaName, Hash>();
+
+/**
+ * Resolve the CAS hash for an output schema by short name, caching the result
+ * for the lifetime of the process.
+ */
+export function resolveOutputSchemaHash(
+  outputs: Record<OutputSchemaName, Hash>,
+  schemaName: OutputSchemaName,
+): Hash {
+  const cached = schemaHashCache.get(schemaName);
+  if (cached !== undefined) return cached;
+  const hash = outputs[schemaName];
+  if (hash === undefined) {
+    throw new Error(`output schema not registered: @uwf/output/${schemaName}`);
+  }
+  schemaHashCache.set(schemaName, hash);
+  return hash;
+}
+
+export type WriteEnvelopeOptions = {
+  format: OutputFormat;
+  store: Store;
+  schemas: UwfSchemaHashes;
+};
+
+/**
+ * Wrap a CLI command payload in the chosen format and write it to stdout.
+ *
+ * - `text`     → Liquid template at `@ocas/template/text/<hash>` (fallback YAML envelope)
+ * - `json`     → `{"type":<hash>,"value":<payload>}` (envelope JSON)
+ * - `yaml`     → envelope as multi-line YAML
+ * - `raw-json` → bare `<payload>` (legacy 0.5.0 shape)
+ * - `raw-yaml` → bare `<payload>` (legacy 0.5.0 shape)
+ */
+export async function writeEnvelope(
+  payload: unknown,
+  schemaName: OutputSchemaName,
+  options: WriteEnvelopeOptions,
+): Promise<void> {
+  const { format, store, schemas } = options;
+  const schemaHash = resolveOutputSchemaHash(schemas.outputs, schemaName);
+
+  let body: string;
+  switch (format) {
+    case "json":
+      body = JSON.stringify({ type: schemaHash, value: payload });
+      break;
+    case "yaml":
+      body = stringify(
+        { type: schemaHash, value: payload },
+        { aliasDuplicateObjects: false },
+      ).trimEnd();
+      break;
+    case "raw-json":
+      body = JSON.stringify(payload);
+      break;
+    case "raw-yaml":
+      body = stringify(payload, { aliasDuplicateObjects: false }).trimEnd();
+      break;
+    case "text":
+      body = await renderEnvelopeText(store, schemaHash, payload, schemaName);
+      break;
+  }
+
+  process.stdout.write(`${body}\n`);
+}
+
+let liquidEngine: Liquid | null = null;
+
+type GraphMap = Record<string, Record<string, { role?: string }>>;
+
+function firstRole(graph: GraphMap, current: string): string | null {
+  const transitions = graph[current];
+  if (!transitions) return null;
+  const firstKey = Object.keys(transitions)[0];
+  if (firstKey === undefined) return null;
+  const next = transitions[firstKey]?.role;
+  return typeof next === "string" ? next : null;
+}
+
+function buildGraphPath(graph: GraphMap, start: string, limit: number): string[] {
+  const out: string[] = [start];
+  const seen = new Set<string>([start]);
+  let cur = start;
+  while (out.length < limit) {
+    const next = firstRole(graph, cur);
+    if (next === null || next === "$END") {
+      out.push("$END");
+      break;
+    }
+    if (seen.has(next)) break;
+    seen.add(next);
+    out.push(next);
+    cur = next;
+  }
+  return out;
+}
+
+function getLiquidEngine(): Liquid {
+  if (liquidEngine !== null) return liquidEngine;
+  const engine = new Liquid({ cache: false, strictFilters: false, strictVariables: false });
+  engine.registerFilter("keys", (input: unknown) =>
+    input !== null && typeof input === "object" ? Object.keys(input as object) : [],
+  );
+  engine.registerFilter("graph_path", (graph: unknown, start: unknown, max: unknown): string[] => {
+    if (graph === null || typeof graph !== "object") return [];
+    const limit = typeof max === "number" ? max : 5;
+    const startNode = typeof start === "string" ? start : "$START";
+    return buildGraphPath(graph as GraphMap, startNode, limit);
+  });
+  liquidEngine = engine;
+  return engine;
+}
+
+function readTemplateContent(store: Store, schemaHash: Hash): string | null {
+  const varName = `@ocas/template/text/${schemaHash}`;
+  const variable = store.var.get(varName);
+  if (variable === null) return null;
+  const node = store.cas.get(variable.value);
+  if (node === null) return null;
+  if (typeof node.payload !== "string") return null;
+  return node.payload;
+}
+
+function buildLiquidContext(payload: unknown, schemaHash: Hash): Record<string, unknown> {
+  const ctx: Record<string, unknown> = { payload, type: schemaHash };
+  if (payload !== null && typeof payload === "object" && !Array.isArray(payload)) {
+    for (const [k, v] of Object.entries(payload)) {
+      if (k !== "payload" && k !== "type") {
+        ctx[k] = v;
+      }
+    }
+  }
+  return ctx;
+}
+
+async function renderEnvelopeText(
+  store: Store,
+  schemaHash: Hash,
+  payload: unknown,
+  schemaName: OutputSchemaName,
+): Promise<string> {
+  const template = readTemplateContent(store, schemaHash);
+  if (template === null) {
+    process.stderr.write(
+      `warning: missing text template for @uwf/output/${schemaName} (var @ocas/template/text/${schemaHash}); falling back to YAML\n`,
+    );
+    return stringify(
+      { type: schemaHash, value: payload },
+      { aliasDuplicateObjects: false },
+    ).trimEnd();
+  }
+  try {
+    const engine = getLiquidEngine();
+    const context = buildLiquidContext(payload, schemaHash);
+    const out = await engine.parseAndRender(template, context);
+    return out.replace(/\n+$/, "");
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    process.stderr.write(
+      `warning: failed to render text template for @uwf/output/${schemaName}: ${message}; falling back to YAML\n`,
+    );
+    return stringify(
+      { type: schemaHash, value: payload },
+      { aliasDuplicateObjects: false },
+    ).trimEnd();
   }
 }