@united-workforce/cli 0.1.0

package/dist/validate-semantic.js

@@ -0,0 +1,263 @@
+const RESERVED_NAMES = new Set(["$START", "$END", "$SUSPEND"]);
+const PSEUDO_TARGETS = new Set(["$END", "$SUSPEND"]);
+/** Extract mustache variable names from a prompt string. */
+function extractMustacheVars(prompt) {
+    const vars = [];
+    const re = /\{\{\{?([^}]+)\}\}\}?/g;
+    let m = re.exec(prompt);
+    while (m !== null) {
+        vars.push(m[1]);
+        m = re.exec(prompt);
+    }
+    return vars;
+}
+/** Check if a frontmatter schema is a oneOf (multi-exit) type. */
+function isOneOfSchema(fm) {
+    if (typeof fm !== "object" || fm === null)
+        return false;
+    const obj = fm;
+    return Array.isArray(obj.oneOf);
+}
+/** Check if a frontmatter schema declares "$status" as an enum (the required form for user roles). */
+function hasStatusEnum(fm) {
+    if (typeof fm !== "object" || fm === null)
+        return false;
+    const obj = fm;
+    const props = obj.properties;
+    if (!props?.$status)
+        return false;
+    return Array.isArray(props.$status.enum);
+}
+/** Extract status values from an enum-based $status field. */
+function getEnumStatuses(fm) {
+    const props = fm.properties;
+    if (!props?.$status)
+        return [];
+    const statusDef = props.$status;
+    if (!Array.isArray(statusDef.enum))
+        return [];
+    return statusDef.enum;
+}
+/** Get property names from a schema object. */
+function getPropertyNames(schema) {
+    const props = schema.properties;
+    if (typeof props !== "object" || props === null)
+        return new Set();
+    return new Set(Object.keys(props));
+}
+/** Extract $status const values from oneOf variants. */
+function getOneOfStatuses(variants) {
+    const statuses = [];
+    for (const variant of variants) {
+        const props = variant.properties;
+        if (props?.$status) {
+            const statusDef = props.$status;
+            if (typeof statusDef.const === "string") {
+                statuses.push(statusDef.const);
+            }
+        }
+    }
+    return statuses;
+}
+/** Check reserved names and role/graph reference integrity. */
+function checkRoleReferences(payload, errors) {
+    const roleNames = new Set(Object.keys(payload.roles));
+    const graphNodes = new Set(Object.keys(payload.graph));
+    for (const name of roleNames) {
+        if (RESERVED_NAMES.has(name)) {
+            errors.push(`reserved name "${name}" must not appear in roles`);
+        }
+    }
+    for (const node of graphNodes) {
+        if (!RESERVED_NAMES.has(node) && !roleNames.has(node)) {
+            errors.push(`graph references unknown role "${node}"`);
+        }
+    }
+    for (const name of roleNames) {
+        if (RESERVED_NAMES.has(name))
+            continue;
+        if (!graphNodes.has(name)) {
+            errors.push(`role "${name}" is defined but not referenced in graph`);
+        }
+    }
+}
+/** Check $START/$END constraints, edge targets, and reachability. */
+function checkGraphStructure(payload, errors) {
+    const roleNames = new Set(Object.keys(payload.roles));
+    const graphNodes = new Set(Object.keys(payload.graph));
+    if (!graphNodes.has("$START")) {
+        errors.push("$START must be defined in graph");
+    }
+    else {
+        const startKeys = Object.keys(payload.graph.$START);
+        if (startKeys.length !== 1 || startKeys[0] !== "_") {
+            errors.push('$START must have exactly one edge with status "_"');
+        }
+    }
+    if (graphNodes.has("$END")) {
+        errors.push("$END must not have outgoing edges");
+    }
+    if (graphNodes.has("$SUSPEND")) {
+        errors.push("$SUSPEND must not have outgoing edges");
+    }
+    for (const [node, statusMap] of Object.entries(payload.graph)) {
+        for (const [status, target] of Object.entries(statusMap)) {
+            if (!PSEUDO_TARGETS.has(target.role) && !roleNames.has(target.role)) {
+                errors.push(`edge ${node}→${status}: unknown target role "${target.role}"`);
+            }
+        }
+    }
+    checkReachability(roleNames, collectReachableRoles(payload.graph), errors);
+}
+/** BFS to collect all roles reachable from $START. */
+function collectReachableRoles(graph) {
+    const reachable = new Set();
+    const startEdges = graph.$START;
+    if (!startEdges)
+        return reachable;
+    const queue = [];
+    for (const target of Object.values(startEdges)) {
+        if (!PSEUDO_TARGETS.has(target.role) && !reachable.has(target.role)) {
+            reachable.add(target.role);
+            queue.push(target.role);
+        }
+    }
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const edges = graph[current];
+        if (!edges)
+            continue;
+        for (const target of Object.values(edges)) {
+            if (!PSEUDO_TARGETS.has(target.role) && !reachable.has(target.role)) {
+                reachable.add(target.role);
+                queue.push(target.role);
+            }
+        }
+    }
+    return reachable;
+}
+/** Check that all defined roles are reachable from $START. */
+function checkReachability(roleNames, reachable, errors) {
+    for (const name of roleNames) {
+        if (RESERVED_NAMES.has(name))
+            continue;
+        if (!reachable.has(name)) {
+            errors.push(`role "${name}" is not reachable from $START`);
+        }
+    }
+}
+/** Check oneOf discriminant validity for a role. */
+function checkOneOfDiscriminant(roleName, variants, statuses, errors) {
+    if (statuses.length === variants.length)
+        return;
+    let foundMissing = false;
+    for (const variant of variants) {
+        const props = variant.properties;
+        if (!props?.$status) {
+            errors.push(`role "${roleName}": oneOf variants must have "$status" as const discriminant`);
+            foundMissing = true;
+            break;
+        }
+        if (typeof props.$status.const !== "string") {
+            errors.push(`role "${roleName}": oneOf variant $status must be a const value`);
+            foundMissing = true;
+            break;
+        }
+    }
+    if (!foundMissing) {
+        errors.push(`role "${roleName}": oneOf variant $status must be a const value`);
+    }
+}
+/** Check status-edge consistency for a user role. "_" is reserved for $START and rejected here. */
+function checkStatusEdges(roleName, graphKeys, statusSet, errors) {
+    if (graphKeys.has("_")) {
+        errors.push(`role "${roleName}" must use explicit $status keys in graph, not "_"`);
+        return;
+    }
+    if (statusSet.has("_")) {
+        errors.push(`role "${roleName}" $status enum must use explicit values, not "_"`);
+        return;
+    }
+    const extraKeys = [...graphKeys].filter((k) => !statusSet.has(k));
+    const missingKeys = [...statusSet].filter((k) => !graphKeys.has(k));
+    if (extraKeys.length > 0) {
+        errors.push(`role "${roleName}" graph has extra status keys: ${extraKeys.join(", ")}`);
+    }
+    if (missingKeys.length > 0) {
+        errors.push(`role "${roleName}" graph is missing status keys: ${missingKeys.join(", ")}`);
+    }
+}
+/** Check mustache variables for multi-exit role. */
+function checkMultiExitMustache(roleName, graphEntry, variants, errors) {
+    for (const [status, target] of Object.entries(graphEntry)) {
+        const vars = extractMustacheVars(target.prompt);
+        const variant = variants.find((v) => {
+            const props = v.properties;
+            return props?.$status?.const === status;
+        });
+        if (!variant)
+            continue;
+        const propNames = getPropertyNames(variant);
+        for (const v of vars) {
+            if (v === "$status")
+                continue;
+            if (!propNames.has(v)) {
+                errors.push(`prompt variable "${v}" not found in role "${roleName}" variant "${status}"`);
+            }
+        }
+    }
+}
+/** Check status-edge consistency and mustache for each role. */
+function checkRoleConsistency(payload, errors) {
+    for (const [roleName, role] of Object.entries(payload.roles)) {
+        if (RESERVED_NAMES.has(roleName))
+            continue;
+        const graphEntry = payload.graph[roleName];
+        if (!graphEntry)
+            continue;
+        const fm = role.frontmatter;
+        const graphKeys = new Set(Object.keys(graphEntry));
+        if (isOneOfSchema(fm)) {
+            const variants = fm.oneOf;
+            const statuses = getOneOfStatuses(variants);
+            checkOneOfDiscriminant(roleName, variants, statuses, errors);
+            checkStatusEdges(roleName, graphKeys, new Set(statuses), errors);
+            checkMultiExitMustache(roleName, graphEntry, variants, errors);
+        }
+        else if (hasStatusEnum(fm)) {
+            const statuses = getEnumStatuses(fm);
+            checkStatusEdges(roleName, graphKeys, new Set(statuses), errors);
+            // For enum-based schemas, mustache vars come from the flat properties
+            checkEnumMustache(roleName, graphEntry, fm, errors);
+        }
+        else {
+            errors.push(`role "${roleName}" must define "$status" as an enum (or oneOf const) in frontmatter`);
+        }
+    }
+}
+/** Check mustache vars in all edge prompts against flat schema properties. */
+function checkEnumMustache(roleName, graphEntry, fm, errors) {
+    const propNames = getPropertyNames(fm);
+    for (const [status, target] of Object.entries(graphEntry)) {
+        const vars = extractMustacheVars(target.prompt);
+        for (const v of vars) {
+            if (v === "$status")
+                continue;
+            if (!propNames.has(v)) {
+                errors.push(`prompt variable "${v}" in graph[${roleName}][${status}] not found in role "${roleName}" frontmatter`);
+            }
+        }
+    }
+}
+/**
+ * Validate a parsed WorkflowPayload for semantic correctness.
+ * Returns an array of error messages. Empty array = valid.
+ */
+export function validateWorkflow(payload) {
+    const errors = [];
+    checkRoleReferences(payload, errors);
+    checkGraphStructure(payload, errors);
+    checkRoleConsistency(payload, errors);
+    return errors;
+}
+//# sourceMappingURL=validate-semantic.js.map

package/dist/validate-semantic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-semantic.js","sourceRoot":"","sources":["../src/validate-semantic.ts"],"names":[],"mappings":"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"}

package/dist/validate.d.ts

@@ -0,0 +1,16 @@
+import type { CasRef, WorkflowPayload } from "@united-workforce/protocol";
+export declare function isCasRef(value: string): value is CasRef;
+/**
+ * Derive the expected workflow name from a file path (stem without extension).
+ * Returns the stem for `.yaml` / `.yml` files.
+ */
+export declare function workflowNameFromPath(filePath: string): string;
+/**
+ * Check that the `name` field in a parsed payload matches the expected name
+ * derived from the file path.  Returns an error message string on mismatch,
+ * or null when the names are consistent.
+ */
+export declare function checkWorkflowFilenameConsistency(filePath: string, payload: WorkflowPayload): string | null;
+/** Validate YAML-parsed workflow document shape (outputSchema may be inline JSON Schema). */
+export declare function parseWorkflowPayload(raw: unknown): WorkflowPayload | null;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAI1E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,MAAM,CAEvD;AAkED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAW7D;AAED;;;;GAIG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,eAAe,GACvB,MAAM,GAAG,IAAI,CAMf;AAED,6FAA6F;AAE7F,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CA4BzE"}

package/dist/validate.js

@@ -0,0 +1,115 @@
+import { basename, dirname } from "node:path";
+const CAS_REF_PATTERN = /^[0-9A-HJKMNP-TV-Z]{13}$/;
+export function isCasRef(value) {
+    return CAS_REF_PATTERN.test(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRoleDefinition(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const frontmatter = value.frontmatter;
+    const frontmatterOk = isRecord(frontmatter) &&
+        (typeof frontmatter.type === "string" || Array.isArray(frontmatter.oneOf));
+    const capabilities = value.capabilities;
+    const capabilitiesOk = Array.isArray(capabilities) && capabilities.every((c) => typeof c === "string");
+    return (typeof value.description === "string" &&
+        typeof value.goal === "string" &&
+        capabilitiesOk &&
+        typeof value.procedure === "string" &&
+        typeof value.output === "string" &&
+        frontmatterOk);
+}
+function isTarget(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const hasValidLocation = value.location === undefined || value.location === null || typeof value.location === "string";
+    return (typeof value.role === "string" &&
+        typeof value.prompt === "string" &&
+        value.prompt.trim() !== "" &&
+        hasValidLocation);
+}
+function isStringRecord(value, itemCheck) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return Object.values(value).every(itemCheck);
+}
+function isGraph(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return Object.entries(value).every(([node, statusMap]) => {
+        if (!isRecord(statusMap)) {
+            return false;
+        }
+        return Object.entries(statusMap).every(([status, target]) => {
+            // "_" is only valid as a status key for the $START entry node.
+            if (status === "_" && node !== "$START") {
+                return false;
+            }
+            return isTarget(target);
+        });
+    });
+}
+/**
+ * Derive the expected workflow name from a file path (stem without extension).
+ * Returns the stem for `.yaml` / `.yml` files.
+ */
+export function workflowNameFromPath(filePath) {
+    const base = basename(filePath);
+    const stem = base.endsWith(".yaml")
+        ? base.slice(0, -5)
+        : base.endsWith(".yml")
+            ? base.slice(0, -4)
+            : base;
+    if (stem === "index") {
+        return basename(dirname(filePath));
+    }
+    return stem;
+}
+/**
+ * Check that the `name` field in a parsed payload matches the expected name
+ * derived from the file path.  Returns an error message string on mismatch,
+ * or null when the names are consistent.
+ */
+export function checkWorkflowFilenameConsistency(filePath, payload) {
+    const expected = workflowNameFromPath(filePath);
+    if (payload.name !== expected) {
+        return `workflow name mismatch: file "${basename(filePath)}" implies name "${expected}" but YAML declares name "${payload.name}"`;
+    }
+    return null;
+}
+/** Validate YAML-parsed workflow document shape (outputSchema may be inline JSON Schema). */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: validation function with many field checks
+export function parseWorkflowPayload(raw) {
+    if (!isRecord(raw)) {
+        return null;
+    }
+    if (typeof raw.name !== "string" || typeof raw.description !== "string") {
+        return null;
+    }
+    if (!isStringRecord(raw.roles, isRoleDefinition) || !isGraph(raw.graph)) {
+        return null;
+    }
+    // Normalize location field: undefined → null
+    const normalized = { ...raw };
+    for (const roleName of Object.keys(normalized.graph)) {
+        const statusMap = normalized.graph[roleName];
+        if (statusMap !== undefined) {
+            for (const status of Object.keys(statusMap)) {
+                const target = statusMap[status];
+                if (target !== undefined) {
+                    if (target.location === undefined) {
+                        target.location = null;
+                    }
+                }
+            }
+        }
+    }
+    return normalized;
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@united-workforce/cli",
+  "version": "0.1.0",
+  "files": [
+    "src",
+    "dist",
+    "package.json"
+  ],
+  "type": "module",
+  "bin": {
+    "uwf": "./dist/cli.js"
+  },
+  "dependencies": {
+    "@ocas/core": "^0.3.0",
+    "@ocas/fs": "^0.3.0",
+    "commander": "^14.0.3",
+    "dotenv": "^16.6.1",
+    "mustache": "^4.2.0",
+    "yaml": "^2.8.4",
+    "@united-workforce/util-agent": "^0.1.0",
+    "@united-workforce/protocol": "^0.1.0",
+    "@united-workforce/util": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/mustache": "^4.2.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://git.shazhou.work/shazhou/united-workforce.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://git.shazhou.work/shazhou/united-workforce#readme",
+  "bugs": {
+    "url": "https://git.shazhou.work/shazhou/united-workforce/issues"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "vitest run src/",
+    "test:ci": "vitest run src/"
+  }
+}

package/src/__tests__/adapter-json-roundtrip.test.ts

@@ -0,0 +1,181 @@
+import { execFileSync } from "node:child_process";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { putSchema } from "@ocas/core";
+import { openStore } from "@ocas/fs";
+import type { CasRef, StepNodePayload, ThreadId } from "@united-workforce/protocol";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { registerUwfSchemas } from "../schemas.js";
+import { seedThreads } from "./thread-test-helpers.js";
+
+// ── schemas ──────────────────────────────────────────────────────────────────
+
+const OUTPUT_SCHEMA = {
+  type: "object" as const,
+  properties: {
+    $status: { type: "string" as const, enum: ["done", "failed"] },
+    result: { type: "string" as const },
+  },
+  required: ["$status"],
+  additionalProperties: false,
+};
+
+// ── fixture ──────────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "cli-uwf-roundtrip-test-"));
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+describe("C1: adapter JSON round-trip integration", () => {
+  test("mock agent outputs JSON, CLI parses it and updates thread head in CAS", async () => {
+    // 1. Set up CAS store with workflow, start node, and output schema
+    const casDir = join(tmpDir, "cas");
+    await mkdir(casDir, { recursive: true });
+    const store = await openStore(casDir);
+    const schemas = await registerUwfSchemas(store);
+
+    const outputSchemaHash = await putSchema(store, OUTPUT_SCHEMA);
+
+    const workflowHash = await store.cas.put(schemas.workflow, {
+      name: "test-roundtrip",
+      description: "roundtrip integration test",
+      roles: {
+        worker: {
+          description: "Worker role",
+          goal: "Do work",
+          capabilities: [],
+          procedure: "work",
+          output: "result",
+          frontmatter: outputSchemaHash,
+        },
+      },
+      graph: {
+        $START: { _: { role: "worker", prompt: "Do the work", location: null } },
+        worker: { done: { role: "$END", prompt: "completed", location: null } },
+      },
+    });
+
+    const startHash = await store.cas.put(schemas.startNode, {
+      workflow: workflowHash,
+      prompt: "Test round-trip task",
+    });
+
+    process.env.OCAS_HOME = casDir;
+
+    const threadId = "01ROUNDTRIPTEST0000000000" as ThreadId;
+    await seedThreads(tmpDir, { [threadId]: startHash });
+
+    // 2. Pre-create CAS nodes that the mock agent would produce
+    const outputHash = await store.cas.put(outputSchemaHash, {
+      $status: "done",
+      result: "test-ok",
+    });
+
+    // Use text schema for detail (simple placeholder)
+    const detailHash = await store.cas.put(schemas.text, "mock detail");
+
+    const startedAtMs = 1716600000000;
+    const completedAtMs = 1716600001500;
+
+    const stepHash = await store.cas.put(schemas.stepNode, {
+      start: startHash,
+      prev: null,
+      role: "worker",
+      output: outputHash,
+      detail: detailHash,
+      agent: "uwf-mock",
+      edgePrompt: "Do the work",
+      startedAtMs,
+      completedAtMs,
+      cwd: tmpDir,
+    });
+
+    // 3. Create a minimal mock agent shell script that just outputs JSON
+    //    The step node is already in CAS — the agent just needs to print the JSON line
+    const mockAgentPath = join(tmpDir, "mock-agent.sh");
+    const adapterJson = JSON.stringify({
+      stepHash,
+      detailHash,
+      role: "worker",
+      frontmatter: { $status: "done", result: "test-ok" },
+      body: "",
+      startedAtMs,
+      completedAtMs,
+    });
+    await writeFile(mockAgentPath, `#!/bin/sh\necho '${adapterJson}'\n`, { mode: 0o755 });
+
+    // 4. Write config.yaml
+    const configPath = join(tmpDir, "config.yaml");
+    await writeFile(
+      configPath,
+      `defaultAgent: uwf-hermes\ndefaultModel: test-model\nagentOverrides: null\nagents: {}\nproviders: {}\nmodels: {}\n`,
+    );
+
+    // 5. Run CLI with agent override pointing to our mock
+    const cliPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "dist", "cli.js");
+    let stdout: string;
+    let stderr: string;
+    let exitCode: number;
+
+    try {
+      stdout = execFileSync(
+        process.execPath,
+        [cliPath, "thread", "exec", threadId, "--agent", mockAgentPath],
+        {
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "pipe"],
+          env: {
+            ...process.env,
+            UWF_HOME: tmpDir,
+            OCAS_HOME: casDir,
+          },
+          cwd: tmpDir,
+          timeout: 30000,
+        },
+      );
+      stderr = "";
+      exitCode = 0;
+    } catch (e: unknown) {
+      const err = e as NodeJS.ErrnoException & {
+        stdout?: string;
+        stderr?: string;
+        status?: number;
+      };
+      stdout = err.stdout ?? "";
+      stderr = err.stderr ?? "";
+      exitCode = err.status ?? 1;
+    }
+
+    // 6. Verify
+    if (exitCode !== 0) {
+      throw new Error(`CLI exited with code ${exitCode}\nstdout: ${stdout}\nstderr: ${stderr}`);
+    }
+
+    // Parse CLI output
+    const cliOutput = JSON.parse(stdout.trim());
+    expect(cliOutput).toHaveProperty("thread", threadId);
+    expect(cliOutput).toHaveProperty("head", stepHash);
+    expect(cliOutput.head).toMatch(/^[0-9A-HJ-NP-TV-Z]{13}$/);
+
+    // Verify the CAS step node exists and has correct metadata
+    const storeAfter = await openStore(casDir);
+    const stepNode = storeAfter.cas.get(cliOutput.head as CasRef);
+    expect(stepNode).not.toBeNull();
+
+    const payload = stepNode!.payload as StepNodePayload;
+    expect(payload.role).toBe("worker");
+    expect(payload.agent).toBe("uwf-mock");
+    expect(payload.startedAtMs).toBe(1716600000000);
+    expect(payload.completedAtMs).toBe(1716600001500);
+    expect(payload.output).toBe(outputHash);
+    expect(payload.detail).toBe(detailHash);
+  });
+});