@united-workforce/cli 0.1.0

package/src/commands/workflow.ts

@@ -0,0 +1,213 @@
+import { readFile } from "node:fs/promises";
+import { dirname, resolve as resolvePath } from "node:path";
+
+import type { JSONSchema } from "@ocas/core";
+import { putSchema, validate } from "@ocas/core";
+import type { CasRef, RoleDefinition, Target, WorkflowPayload } from "@united-workforce/protocol";
+import { parse } from "yaml";
+import { createIncludeTag } from "../include.js";
+
+import {
+  createUwfStore,
+  discoverProjectWorkflows,
+  findRegistryName,
+  loadWorkflowRegistry,
+  resolveWorkflowHash,
+  saveWorkflowRegistry,
+  type UwfStore,
+} from "../store.js";
+import { checkWorkflowFilenameConsistency, parseWorkflowPayload } from "../validate.js";
+import { validateWorkflow } from "../validate-semantic.js";
+
+export type WorkflowOrigin = "local" | "global";
+
+export type WorkflowListEntry = {
+  name: string;
+  hash: CasRef;
+  origin: WorkflowOrigin;
+};
+
+export type WorkflowAddOutput = {
+  name: string;
+  hash: CasRef;
+};
+
+export type WorkflowShowOutput = {
+  hash: CasRef;
+  name: string | null;
+  type: CasRef;
+  payload: WorkflowPayload;
+  timestamp: number;
+};
+
+function fail(message: string): never {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+function isJsonSchema(value: unknown): value is JSONSchema {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Normalize graph: validate each status → target mapping. */
+function normalizeGraph(
+  graph: Record<string, Record<string, Target>>,
+): Record<string, Record<string, Target>> {
+  const result: Record<string, Record<string, Target>> = {};
+  for (const [node, statusMap] of Object.entries(graph)) {
+    const normalized: Record<string, Target> = {};
+    for (const [status, target] of Object.entries(statusMap)) {
+      if (typeof target.prompt !== "string" || target.prompt.trim() === "") {
+        fail(`graph[${node}][${status}] → "${target.role}": prompt is required (non-empty string)`);
+      }
+      normalized[status] = {
+        role: target.role,
+        prompt: target.prompt,
+        location: target.location ?? null,
+      };
+    }
+    result[node] = normalized;
+  }
+  return result;
+}
+
+async function resolveFrontmatterRef(
+  uwf: UwfStore,
+  roleName: string,
+  frontmatter: unknown,
+): Promise<CasRef> {
+  if (!isJsonSchema(frontmatter)) {
+    fail(`role "${roleName}": frontmatter must be a JSON Schema object`);
+  }
+  const schema: JSONSchema =
+    frontmatter.title === undefined ? { ...frontmatter, title: roleName } : frontmatter;
+  return putSchema(uwf.store, schema);
+}
+
+export async function materializeWorkflowPayload(
+  uwf: UwfStore,
+  raw: WorkflowPayload,
+): Promise<WorkflowPayload> {
+  const roles: Record<string, RoleDefinition> = {};
+  for (const [roleName, role] of Object.entries(raw.roles)) {
+    const frontmatter = await resolveFrontmatterRef(
+      uwf,
+      `${raw.name}.${roleName}`,
+      role.frontmatter,
+    );
+    roles[roleName] = {
+      description: role.description,
+      goal: role.goal,
+      capabilities: role.capabilities,
+      procedure: role.procedure,
+      output: role.output,
+      frontmatter,
+    };
+  }
+  return {
+    name: raw.name,
+    description: raw.description,
+    roles,
+    graph: normalizeGraph(raw.graph),
+  };
+}
+
+export async function cmdWorkflowAdd(
+  storageRoot: string,
+  filePath: string,
+): Promise<WorkflowAddOutput> {
+  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) {
+    fail(filenameError);
+  }
+
+  const semanticErrors = validateWorkflow(payload);
+  if (semanticErrors.length > 0) {
+    fail(`workflow validation failed:\n${semanticErrors.map((e) => `  - ${e}`).join("\n")}`);
+  }
+
+  const uwf = await createUwfStore(storageRoot);
+  const materialized = await materializeWorkflowPayload(uwf, payload);
+
+  const hash = await uwf.store.cas.put(uwf.schemas.workflow, materialized);
+  const node = uwf.store.cas.get(hash);
+  if (node === null || !validate(uwf.store, node)) {
+    fail("stored workflow failed schema validation");
+  }
+
+  saveWorkflowRegistry(uwf.varStore, materialized.name, hash);
+
+  return { name: materialized.name, hash };
+}
+
+export async function cmdWorkflowShow(
+  storageRoot: string,
+  id: string,
+): Promise<WorkflowShowOutput> {
+  const uwf = await createUwfStore(storageRoot);
+  const registry = loadWorkflowRegistry(uwf.varStore);
+  const hash = resolveWorkflowHash(registry, id);
+
+  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})`);
+  }
+
+  const payload = node.payload as WorkflowPayload;
+  return {
+    hash,
+    name: findRegistryName(registry, hash),
+    type: node.type,
+    payload,
+    timestamp: node.timestamp,
+  };
+}
+
+export async function cmdWorkflowList(
+  storageRoot: string,
+  projectRoot: string,
+): Promise<WorkflowListEntry[]> {
+  const uwf = await createUwfStore(storageRoot);
+  const localEntries = await discoverProjectWorkflows(projectRoot);
+  const registry = loadWorkflowRegistry(uwf.varStore);
+
+  const result: WorkflowListEntry[] = [];
+  const localNames = new Set<string>();
+
+  for (const entry of localEntries) {
+    localNames.add(entry.name);
+    result.push({ name: entry.name, hash: "(local)", origin: "local" });
+  }
+
+  for (const [name, hash] of Object.entries(registry)) {
+    if (!localNames.has(name)) {
+      result.push({ name, hash, origin: "global" });
+    }
+  }
+
+  return result;
+}

package/src/format.ts

@@ -0,0 +1,12 @@
+import { stringify } from "yaml";
+
+export type OutputFormat = "json" | "yaml";
+
+export function formatOutput(data: unknown, format: OutputFormat): string {
+  switch (format) {
+    case "json":
+      return JSON.stringify(data);
+    case "yaml":
+      return stringify(data, { aliasDuplicateObjects: false }).trimEnd();
+  }
+}

package/src/include.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+import { dirname, extname, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+
+/**
+ * Create a YAML customTags entry for !include that resolves file paths
+ * relative to the given base directory.
+ *
+ * Security: resolved paths must stay within baseDir (path traversal prevention).
+ * Nested !include in .yaml/.yml files is supported (customTags passed recursively).
+ */
+export function createIncludeTag(baseDir: string) {
+  const resolvedBase = resolve(baseDir);
+  return {
+    tag: "!include",
+    resolve(str: string) {
+      const filePath = resolve(resolvedBase, str);
+      // Path traversal guard: resolved path must be inside baseDir
+      if (!filePath.startsWith(`${resolvedBase}/`) && filePath !== resolvedBase) {
+        throw new Error(
+          `!include path traversal blocked: "${str}" resolves outside base directory`,
+        );
+      }
+      const content = readFileSync(filePath, "utf8");
+      const ext = extname(filePath).toLowerCase();
+      if (ext === ".json") {
+        return JSON.parse(content);
+      }
+      if (ext === ".yaml" || ext === ".yml") {
+        // Pass customTags recursively so nested !include works,
+        // scoped to the included file's directory
+        return parseYaml(content, { customTags: [createIncludeTag(dirname(filePath))] });
+      }
+      return content;
+    },
+  };
+}

package/src/moderator/__tests__/evaluate.test.ts

@@ -0,0 +1,199 @@
+import { describe, expect, test } from "vitest";
+import { evaluate } from "../evaluate.js";
+import { isSuspendResult } from "../types.js";
+
+describe("Edge prompt template variable resolution", () => {
+  test("returns error when rendered prompt is empty string", () => {
+    const graph = {
+      $START: {
+        _: { role: "classifier", prompt: "{{{userPrompt}}}", location: null },
+      },
+    };
+
+    const result = evaluate(graph, "$START", {});
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.message).toContain("prompt");
+      expect(result.error.message).toContain("empty");
+    }
+  });
+
+  test("returns error when rendered prompt is whitespace-only", () => {
+    const graph = {
+      $START: {
+        _: { role: "classifier", prompt: "  {{{userPrompt}}}  ", location: null },
+      },
+    };
+
+    const result = evaluate(graph, "$START", {});
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.message).toContain("prompt");
+      expect(result.error.message).toContain("empty");
+    }
+  });
+
+  test("succeeds when all template variables resolve to non-empty values", () => {
+    const graph = {
+      $START: {
+        _: { role: "classifier", prompt: "{{{userPrompt}}}", location: null },
+      },
+    };
+
+    const result = evaluate(graph, "$START", { userPrompt: "Fix the bug" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.prompt).toBe("Fix the bug");
+    }
+  });
+
+  test("succeeds with static (no-variable) prompt", () => {
+    const graph = {
+      $START: {
+        _: { role: "classifier", prompt: "Classify this input", location: null },
+      },
+    };
+
+    const result = evaluate(graph, "$START", {});
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.prompt).toBe("Classify this input");
+    }
+  });
+
+  test("succeeds when prompt has mix of static text and unresolved variables", () => {
+    const graph = {
+      $START: {
+        _: { role: "classifier", prompt: "Please handle: {{{userPrompt}}}", location: null },
+      },
+    };
+
+    const result = evaluate(graph, "$START", {});
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.prompt).toBe("Please handle: ");
+    }
+  });
+
+  test("returns error when ALL variables missing and no static text remains", () => {
+    const graph = {
+      $START: {
+        _: { role: "classifier", prompt: "{{{a}}}{{{b}}}", location: null },
+      },
+    };
+
+    const result = evaluate(graph, "$START", {});
+
+    expect(result.ok).toBe(false);
+  });
+});
+
+describe("Moderator location resolution", () => {
+  test("returns null location when edge has no location field", () => {
+    const graph = {
+      planner: {
+        ready: {
+          role: "coder",
+          prompt: "Implement the code",
+          location: null,
+        },
+      },
+    };
+
+    const result = evaluate(graph, "planner", { $status: "ready" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok && !isSuspendResult(result.value)) {
+      expect(result.value.location).toBe(null);
+    }
+  });
+
+  test("resolves static location string", () => {
+    const graph = {
+      planner: {
+        ready: {
+          role: "coder",
+          prompt: "Implement the code",
+          location: "/static/path",
+        },
+      },
+    };
+
+    const result = evaluate(graph, "planner", { $status: "ready" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok && !isSuspendResult(result.value)) {
+      expect(result.value.location).toBe("/static/path");
+    }
+  });
+
+  test("resolves mustache template location", () => {
+    const graph = {
+      planner: {
+        ready: {
+          role: "coder",
+          prompt: "Implement the code",
+          location: "{{{repoPath}}}",
+        },
+      },
+    };
+
+    const result = evaluate(graph, "planner", {
+      $status: "ready",
+      repoPath: "/home/user/repo",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok && !isSuspendResult(result.value)) {
+      expect(result.value.location).toBe("/home/user/repo");
+    }
+  });
+
+  test("resolves mustache template with multiple variables", () => {
+    const graph = {
+      planner: {
+        ready: {
+          role: "coder",
+          prompt: "Implement the code",
+          location: "{{{basePath}}}/{{{projectName}}}",
+        },
+      },
+    };
+
+    const result = evaluate(graph, "planner", {
+      $status: "ready",
+      basePath: "/home/user",
+      projectName: "myproject",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok && !isSuspendResult(result.value)) {
+      expect(result.value.location).toBe("/home/user/myproject");
+    }
+  });
+
+  test("handles missing template variable gracefully", () => {
+    const graph = {
+      planner: {
+        ready: {
+          role: "coder",
+          prompt: "Implement the code",
+          location: "{{{repoPath}}}",
+        },
+      },
+    };
+
+    const result = evaluate(graph, "planner", { $status: "ready" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok && !isSuspendResult(result.value)) {
+      // Mustache renders missing variables as empty string
+      expect(result.value.location).toBe("");
+    }
+  });
+});

package/src/moderator/evaluate.ts

@@ -0,0 +1,80 @@
+import type { Target } from "@united-workforce/protocol";
+import mustache from "mustache";
+
+import type { EvaluateResult, Result } from "./types.js";
+
+// Disable HTML escaping — prompts are plain text, not HTML.
+mustache.escape = (text: string) => text;
+
+const START_ROLE = "$START";
+const SUSPEND_ROLE = "$SUSPEND";
+// $START is a special entry node with no agent output — it always uses this key.
+const START_STATUS = "_";
+
+type LastOutput = Record<string, unknown>;
+
+const STATUS_KEY = "$status";
+
+export function evaluate(
+  graph: Record<string, Record<string, Target>>,
+  lastRole: string,
+  lastOutput: LastOutput,
+): Result<EvaluateResult, Error> {
+  let status: string;
+  if (lastRole === START_ROLE) {
+    status = START_STATUS;
+  } else if (typeof lastOutput[STATUS_KEY] === "string") {
+    status = lastOutput[STATUS_KEY] as string;
+  } else {
+    return {
+      ok: false,
+      error: new Error(`agent output for role "${lastRole}" is missing required "$status" string`),
+    };
+  }
+
+  const roleTargets = graph[lastRole];
+  if (roleTargets === undefined) {
+    return {
+      ok: false,
+      error: new Error(`no transitions defined for role "${lastRole}"`),
+    };
+  }
+
+  const target = roleTargets[status];
+  if (target === undefined) {
+    return {
+      ok: false,
+      error: new Error(`no transition for role "${lastRole}" with status "${status}"`),
+    };
+  }
+
+  try {
+    const prompt = mustache.render(target.prompt, lastOutput);
+    if (prompt.trim() === "") {
+      return {
+        ok: false,
+        error: new Error(
+          `edge prompt resolved to empty string for role "${target.role}" (template: "${target.prompt}"). Check that upstream output includes required variables.`,
+        ),
+      };
+    }
+    if (target.role === SUSPEND_ROLE) {
+      return {
+        ok: true,
+        value: {
+          action: "suspend",
+          suspendedRole: lastRole,
+          prompt,
+        },
+      };
+    }
+
+    const location = target.location !== null ? mustache.render(target.location, lastOutput) : null;
+    return { ok: true, value: { role: target.role, prompt, location } };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error : new Error(String(error)),
+    };
+  }
+}

package/src/moderator/index.ts

@@ -0,0 +1,7 @@
+export { evaluate } from "./evaluate.js";
+export type {
+  EvaluateResult,
+  EvaluateRouteResult,
+  EvaluateSuspendResult,
+} from "./types.js";
+export { isSuspendResult } from "./types.js";

package/src/moderator/types.ts

@@ -0,0 +1,24 @@
+export type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
+
+/** Moderator routes the thread to a real role (or `$END`). */
+export type EvaluateRouteResult = {
+  role: string;
+  prompt: string;
+  /** Resolved working directory from edge location field (null = inherit thread cwd). */
+  location: string | null;
+};
+
+/** Moderator routes the thread to `$SUSPEND` — waiting for external input. */
+export type EvaluateSuspendResult = {
+  action: "suspend";
+  /** Role whose output triggered the suspend transition. */
+  suspendedRole: string;
+  prompt: string;
+};
+
+/** The result of moderator evaluation. */
+export type EvaluateResult = EvaluateRouteResult | EvaluateSuspendResult;
+
+export function isSuspendResult(result: EvaluateResult): result is EvaluateSuspendResult {
+  return "action" in result && result.action === "suspend";
+}

package/src/schemas.ts

@@ -0,0 +1,26 @@
+import type { Hash, Store } from "@ocas/core";
+import { putSchema } from "@ocas/core";
+import { START_NODE_SCHEMA, STEP_NODE_SCHEMA, WORKFLOW_SCHEMA } from "@united-workforce/protocol";
+
+export const TEXT_SCHEMA = { type: "string" as const };
+
+export type UwfSchemaHashes = {
+  workflow: Hash;
+  startNode: Hash;
+  stepNode: Hash;
+  text: Hash;
+};
+
+/**
+ * Register Workflow, StartNode, and StepNode JSON Schemas in the CAS store.
+ * Idempotent: safe to call on every CLI invocation.
+ */
+export async function registerUwfSchemas(store: Store): Promise<UwfSchemaHashes> {
+  const [workflow, startNode, stepNode, text] = await Promise.all([
+    putSchema(store, WORKFLOW_SCHEMA),
+    putSchema(store, START_NODE_SCHEMA),
+    putSchema(store, STEP_NODE_SCHEMA),
+    putSchema(store, TEXT_SCHEMA),
+  ]);
+  return { workflow, startNode, stepNode, text };
+}