@united-workforce/cli 0.3.0 → 0.5.0

package/src/commands/workflow.ts

@@ -1,5 +1,5 @@
 import { readFile } from "node:fs/promises";
-import { dirname, resolve as resolvePath } from "node:path";
+import { basename, dirname, isAbsolute, resolve as resolvePath } from "node:path";
 
 import type { JSONSchema } from "@ocas/core";
 import { putSchema, validate } from "@ocas/core";
@@ -12,11 +12,17 @@ import {
   discoverProjectWorkflows,
   findRegistryName,
   loadWorkflowRegistry,
+  resolveProjectWorkflowFile,
   resolveWorkflowHash,
   saveWorkflowRegistry,
   type UwfStore,
 } from "../store.js";
-import { checkWorkflowFilenameConsistency, parseWorkflowPayload } from "../validate.js";
+import {
+  checkWorkflowFilenameConsistency,
+  isCasRef,
+  isMissingVersion,
+  parseWorkflowPayload,
+} from "../validate.js";
 import { validateWorkflow } from "../validate-semantic.js";
 
 export type WorkflowOrigin = "local" | "global";
@@ -105,6 +111,7 @@ export async function materializeWorkflowPayload(
     };
   }
   return {
+    version: raw.version,
     name: raw.name,
     description: raw.description,
     roles,
@@ -112,6 +119,43 @@ export async function materializeWorkflowPayload(
   };
 }
 
+/**
+ * Validate a workflow YAML file without registering it.
+ *
+ * CI-friendly: does not touch CAS or the workflow registry. On success,
+ * returns silently (no stdout/stderr) and exits 0. On any error, writes a
+ * single message to stderr and exits 1.
+ */
+export async function cmdWorkflowValidate(filePath: string): Promise<string[]> {
+  let text: string;
+  try {
+    text = await readFile(filePath, "utf8");
+  } catch {
+    fail(`file not found: ${filePath}`);
+  }
+
+  let raw: unknown;
+  try {
+    raw = parse(text, {
+      customTags: [createIncludeTag(dirname(resolvePath(filePath)))],
+    }) as unknown;
+  } catch (e) {
+    fail(`invalid YAML: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  const payload = parseWorkflowPayload(raw);
+  if (payload === null) {
+    fail("invalid workflow YAML: expected WorkflowPayload shape");
+  }
+
+  const filenameError = checkWorkflowFilenameConsistency(filePath, payload);
+  if (filenameError !== null) {
+    return [filenameError];
+  }
+
+  return validateWorkflow(payload);
+}
+
 export async function cmdWorkflowAdd(
   storageRoot: string,
   filePath: string,
@@ -137,6 +181,12 @@ export async function cmdWorkflowAdd(
     fail("invalid workflow YAML: expected WorkflowPayload shape");
   }
 
+  if (isMissingVersion(raw)) {
+    process.stderr.write(
+      `warning: workflow YAML "${basename(filePath)}" is missing top-level \`version\` field; falling back to version 1. Add \`version: 1\` to silence this warning.\n`,
+    );
+  }
+
   const filenameError = checkWorkflowFilenameConsistency(filePath, payload);
   if (filenameError !== null) {
     fail(filenameError);
@@ -161,13 +211,113 @@ export async function cmdWorkflowAdd(
   return { name: materialized.name, hash };
 }
 
+// ── workflow show resolution helpers ──────────────────────────────────────────
+
+function isFilePath(input: string): boolean {
+  return (
+    input.includes("/") || input.includes("\\") || input.endsWith(".yaml") || input.endsWith(".yml")
+  );
+}
+
+async function materializeLocalWorkflowForShow(uwf: UwfStore, filePath: string): Promise<CasRef> {
+  let text: string;
+  try {
+    text = await readFile(filePath, "utf8");
+  } catch {
+    fail(`project workflow file not found: ${filePath}`);
+  }
+
+  let raw: unknown;
+  try {
+    raw = parse(text, { customTags: [createIncludeTag(dirname(filePath))] }) as unknown;
+  } catch (e) {
+    fail(`invalid YAML in ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  const payload = parseWorkflowPayload(raw);
+  if (payload === null) {
+    fail(`invalid workflow YAML in ${filePath}: expected WorkflowPayload shape`);
+  }
+
+  const filenameError = checkWorkflowFilenameConsistency(filePath, payload);
+  if (filenameError !== null) {
+    fail(filenameError);
+  }
+
+  const semanticErrors = validateWorkflow(payload);
+  if (semanticErrors.length > 0) {
+    fail(`workflow validation failed:\n${semanticErrors.map((e) => `  - ${e}`).join("\n")}`);
+  }
+
+  const materialized = await materializeWorkflowPayload(uwf, payload);
+  const hash = await uwf.store.cas.put(uwf.schemas.workflow, materialized);
+  const stored = uwf.store.cas.get(hash);
+  if (stored === null || !validate(uwf.store, stored)) {
+    fail("stored local workflow failed schema validation");
+  }
+
+  return hash;
+}
+
+async function resolveWorkflowCasRefForShow(
+  uwf: UwfStore,
+  workflowId: string,
+  projectRoot: string,
+): Promise<CasRef> {
+  // Validate input
+  const trimmed = workflowId.trim();
+  if (trimmed === "") {
+    fail("workflow ID cannot be empty");
+  }
+
+  // Strategy 1: Direct CAS hash
+  if (isCasRef(trimmed)) {
+    const node = uwf.store.cas.get(trimmed);
+    if (node === null) {
+      fail(`CAS node not found: ${trimmed}`);
+    }
+    if (node.type !== uwf.schemas.workflow) {
+      fail(`node ${trimmed} is not a Workflow (type ${node.type})`);
+    }
+    return trimmed;
+  }
+
+  // Strategy 2: Explicit file path (relative or absolute)
+  if (isFilePath(trimmed)) {
+    const absolutePath = isAbsolute(trimmed) ? trimmed : resolvePath(projectRoot, trimmed);
+    return materializeLocalWorkflowForShow(uwf, absolutePath);
+  }
+
+  // Strategy 3: Local discovery (reuses discoverProjectWorkflows from store.ts)
+  const localEntries = await discoverProjectWorkflows(projectRoot);
+  const localPath = resolveProjectWorkflowFile(localEntries, trimmed);
+  if (localPath !== null) {
+    return materializeLocalWorkflowForShow(uwf, localPath);
+  }
+
+  // Strategy 4: Global registry fallback
+  const registry = loadWorkflowRegistry(uwf.varStore);
+  const hash = resolveWorkflowHash(registry, trimmed);
+  if (!isCasRef(hash)) {
+    fail(`workflow not found: ${trimmed}`);
+  }
+  const node = uwf.store.cas.get(hash);
+  if (node === null) {
+    fail(`CAS node not found: ${hash}`);
+  }
+  if (node.type !== uwf.schemas.workflow) {
+    fail(`node ${hash} is not a Workflow (type ${node.type})`);
+  }
+  return hash;
+}
+
 export async function cmdWorkflowShow(
   storageRoot: string,
   id: string,
+  projectRoot: string,
 ): Promise<WorkflowShowOutput> {
   const uwf = await createUwfStore(storageRoot);
-  const registry = loadWorkflowRegistry(uwf.varStore);
-  const hash = resolveWorkflowHash(registry, id);
+  const hash = await resolveWorkflowCasRefForShow(uwf, id, projectRoot);
 
   const node = uwf.store.cas.get(hash);
   if (node === null) {
@@ -178,6 +328,7 @@ export async function cmdWorkflowShow(
   }
 
   const payload = node.payload as WorkflowPayload;
+  const registry = loadWorkflowRegistry(uwf.varStore);
   return {
     hash,
     name: findRegistryName(registry, hash),

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;
+};