@united-workforce/cli 0.3.0 → 0.5.0

package/src/text-renderers.ts

@@ -0,0 +1,355 @@
+/**
+ * Per-command text renderers — the per-command registry from spec
+ * `cli-format-text-renderer-registry.md`.
+ *
+ * Each renderer accepts the command's payload (already mapped via the
+ * output-mappers module) and returns a human-readable string. Renderers must
+ * never throw on partial/missing data and must never return `undefined`.
+ *
+ * Distinct from the existing Liquid template registry in `format.ts`: this
+ * registry is plain JS functions (the spec contract is
+ * `Record<string, (data: unknown) => string>`). The Liquid templates remain
+ * the primary rendering path inside `writeEnvelope`; these renderers are the
+ * fallback contract surface so callers can resolve `text` rendering without
+ * needing access to a CAS store.
+ */
+
+type ThreadListItem = {
+  threadId: string;
+  workflowHash: string;
+  workflowName: string | null;
+  status: string;
+  currentRole: string | null;
+  startedAt: number | null;
+  completedAt: number | null;
+};
+
+type ThreadListPayload = { items: ThreadListItem[] };
+
+type ThreadStatusPayload = {
+  threadId: string;
+  workflowHash: string;
+  head: string | null;
+  status: string;
+  currentRole: string | null;
+  suspendedRole: string | null;
+  suspendMessage: string | null;
+  done: boolean;
+};
+
+type ThreadStartPayload = {
+  threadId: string;
+  workflowHash: string;
+};
+
+type WorkflowListItem = {
+  name: string;
+  hash: string;
+  source: string;
+  description: string;
+};
+
+type WorkflowListPayload = { items: WorkflowListItem[] };
+
+type WorkflowDetailPayload = {
+  name: string;
+  hash: string;
+  version: number;
+  description: string;
+  roles: Record<string, { description: string; goal: string }>;
+  graph: Record<string, Record<string, { role: string; prompt: string }>>;
+};
+
+type StepListItem = {
+  hash: string;
+  role: string;
+  durationMs: number | null;
+};
+
+type StepListPayload = {
+  threadId: string;
+  items: StepListItem[];
+};
+
+type ThreadCancelPayload = {
+  thread: string;
+  cancelled: boolean;
+};
+
+type ThreadStopPayload = {
+  thread: string;
+  stopped: boolean;
+};
+
+type StepDetailPayload = {
+  hash: string;
+  role: string;
+  agent: string;
+  status: string;
+  startedAtMs: number | null;
+  completedAtMs: number | null;
+  durationMs: number | null;
+  frontmatter: Record<string, unknown>;
+  turns: Array<{ role: string; content: string; timestamp: number | null }>;
+};
+
+function asObject(data: unknown): Record<string, unknown> {
+  if (data !== null && typeof data === "object" && !Array.isArray(data)) {
+    return data as Record<string, unknown>;
+  }
+  return {};
+}
+
+function asString(value: unknown, fallback = "-"): string {
+  if (typeof value === "string" && value.length > 0) return value;
+  return fallback;
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function formatDuration(durationMs: unknown): string {
+  if (typeof durationMs !== "number" || !Number.isFinite(durationMs)) return "-";
+  if (durationMs >= 1000) return `${(durationMs / 1000).toFixed(1)}s`;
+  return `${durationMs}ms`;
+}
+
+function pad(s: string, width: number): string {
+  if (s.length >= width) return s.slice(0, width);
+  return s + " ".repeat(width - s.length);
+}
+
+function formatTimestamp(ts: unknown): string {
+  if (typeof ts !== "number" || !Number.isFinite(ts)) return "-";
+  const d = new Date(ts);
+  if (Number.isNaN(d.getTime())) return "-";
+  const pad2 = (n: number): string => n.toString().padStart(2, "0");
+  return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())} ${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+}
+
+export function renderThreadList(data: unknown): string {
+  const payload = asObject(data) as Partial<ThreadListPayload>;
+  const items = asArray(payload.items) as ThreadListItem[];
+  const lines: string[] = [
+    "THREAD                      WORKFLOW       STATUS     ROLE       STARTED",
+  ];
+  for (const item of items) {
+    const it = asObject(item);
+    const threadId = asString(it.threadId);
+    const workflowHash = asString(it.workflowHash);
+    const status = pad(asString(it.status), 9);
+    const role = pad(asString(it.currentRole), 10);
+    const started = formatTimestamp(it.startedAt);
+    lines.push(`${threadId}  ${workflowHash}  ${status} ${role} ${started}`);
+  }
+  return lines.join("\n");
+}
+
+export function renderThreadShow(data: unknown): string {
+  const p = asObject(data) as Partial<ThreadStatusPayload>;
+  const status = asString(p.status);
+  const role =
+    status === "suspended" && typeof p.suspendedRole === "string" && p.suspendedRole.length > 0
+      ? p.suspendedRole
+      : asString(p.currentRole);
+  const head = asString(p.head);
+  const lines = [
+    `Thread  ${asString(p.threadId)}`,
+    `Workflow ${asString(p.workflowHash)}`,
+    `Status  ${status}`,
+    `Role    ${role}`,
+    `Head    ${head}`,
+  ];
+  if (
+    status === "suspended" &&
+    typeof p.suspendMessage === "string" &&
+    p.suspendMessage.length > 0
+  ) {
+    lines.push(`Suspend  ${p.suspendMessage}`);
+  }
+  return lines.join("\n");
+}
+
+export function renderThreadStart(data: unknown): string {
+  const p = asObject(data) as Partial<ThreadStartPayload>;
+  return `Thread  ${asString(p.threadId)}\nWorkflow ${asString(p.workflowHash)}`;
+}
+
+export function renderWorkflowList(data: unknown): string {
+  const payload = asObject(data) as Partial<WorkflowListPayload>;
+  const items = asArray(payload.items) as WorkflowListItem[];
+  const lines: string[] = ["NAME          HASH           SOURCE     DESCRIPTION"];
+  for (const item of items) {
+    const it = asObject(item);
+    const name = pad(asString(it.name), 13);
+    const hash = asString(it.hash);
+    const source = pad(asString(it.source), 10);
+    const description = asString(it.description, "");
+    lines.push(`${name} ${hash}  ${source} ${description}`);
+  }
+  return lines.join("\n");
+}
+
+export function renderWorkflowShow(data: unknown): string {
+  const p = asObject(data) as Partial<WorkflowDetailPayload>;
+  const roles =
+    p.roles !== null && typeof p.roles === "object" && !Array.isArray(p.roles)
+      ? Object.keys(p.roles)
+      : [];
+  const lines = [
+    `Workflow  ${asString(p.name)}`,
+    `Version   ${typeof p.version === "number" ? p.version : "-"}`,
+    `Hash      ${asString(p.hash)}`,
+    `Roles     ${roles.join(", ")}`,
+  ];
+  if (typeof p.description === "string" && p.description.length > 0) {
+    lines.push(`Description ${p.description}`);
+  }
+  return lines.join("\n");
+}
+
+export function renderStepList(data: unknown): string {
+  const payload = asObject(data) as Partial<StepListPayload>;
+  const items = asArray(payload.items) as StepListItem[];
+  const lines: string[] = ["HASH           ROLE        DURATION"];
+  for (const item of items) {
+    const it = asObject(item);
+    const hash = asString(it.hash);
+    const role = pad(asString(it.role), 10);
+    const dur = formatDuration(it.durationMs);
+    lines.push(`${hash}  ${role}  ${dur}`);
+  }
+  return lines.join("\n");
+}
+
+export function renderStepShow(data: unknown): string {
+  const p = asObject(data) as Partial<StepDetailPayload>;
+  return [
+    `Step    ${asString(p.hash)}`,
+    `Role    ${asString(p.role)}`,
+    `Agent   ${asString(p.agent)}`,
+    `Status  ${asString(p.status)}`,
+    `Duration ${formatDuration(p.durationMs)}`,
+  ].join("\n");
+}
+
+export function renderThreadCancel(data: unknown): string {
+  const p = asObject(data) as Partial<ThreadCancelPayload>;
+  const cancelled = typeof p.cancelled === "boolean" ? (p.cancelled ? "yes" : "no") : "-";
+  return [
+    `Thread     ${asString(p.thread)}`,
+    `Status     cancelled`,
+    `Cancelled  ${cancelled}`,
+  ].join("\n");
+}
+
+export function renderThreadStop(data: unknown): string {
+  const p = asObject(data) as Partial<ThreadStopPayload>;
+  const stopped = typeof p.stopped === "boolean" ? (p.stopped ? "yes" : "no") : "-";
+  return [`Thread   ${asString(p.thread)}`, `Stopped  ${stopped}`].join("\n");
+}
+
+// ── Config renderers ────────────────────────────────────────────────
+
+/**
+ * Flatten a nested object into dot-notation key-value lines.
+ * Arrays are rendered as compact JSON; scalars as strings.
+ */
+function flattenConfig(obj: Record<string, unknown>, prefix: string): string[] {
+  const lines: string[] = [];
+  for (const [key, value] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    if (Array.isArray(value)) {
+      lines.push(`${fullKey}\t${JSON.stringify(value)}`);
+    } else if (value !== null && typeof value === "object") {
+      lines.push(...flattenConfig(value as Record<string, unknown>, fullKey));
+    } else {
+      lines.push(`${fullKey}\t${String(value)}`);
+    }
+  }
+  return lines;
+}
+
+export function renderConfigList(data: unknown): string {
+  const obj = asObject(data);
+  if (Object.keys(obj).length === 0) return "";
+  return flattenConfig(obj as Record<string, unknown>, "").join("\n");
+}
+
+export function renderConfigGet(data: unknown): string {
+  const obj = asObject(data) as Record<string, unknown>;
+  const value = obj.value;
+  if (value === null || value === undefined) return "";
+  if (typeof value === "object" && !Array.isArray(value)) {
+    return flattenConfig(value as Record<string, unknown>, "").join("\n");
+  }
+  if (Array.isArray(value)) return JSON.stringify(value);
+  return String(value);
+}
+
+export function renderConfigSet(data: unknown): string {
+  const obj = asObject(data) as Record<string, unknown>;
+  const key = asString(obj.key as string | undefined);
+  const value = obj.value;
+  const rendered = Array.isArray(value) ? JSON.stringify(value) : String(value ?? "");
+  return `${key} = ${rendered}`;
+}
+
+// ── Log renderers ───────────────────────────────────────────────────
+
+type LogListItem = {
+  name: string;
+  size: number;
+  date: string;
+};
+
+type LogEntry = {
+  ts: string;
+  pid: string;
+  tag: string;
+  msg: string;
+  thread: string | null;
+  workflow: string | null;
+};
+
+function formatSize(bytes: unknown): string {
+  if (typeof bytes !== "number" || !Number.isFinite(bytes) || bytes < 0) return "-";
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}K`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)}M`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}G`;
+}
+
+export function renderLogList(data: unknown): string {
+  const items = asArray(data) as LogListItem[];
+  if (items.length === 0) return "No log files.";
+  const lines: string[] = ["DATE        SIZE      NAME"];
+  for (const item of items) {
+    const it = asObject(item);
+    const date = pad(asString(it.date), 11);
+    const size = pad(formatSize(it.size), 9);
+    const name = asString(it.name);
+    lines.push(`${date} ${size} ${name}`);
+  }
+  return lines.join("\n");
+}
+
+export function renderLogShow(data: unknown): string {
+  const items = asArray(data) as LogEntry[];
+  if (items.length === 0) return "No log entries.";
+  const lines: string[] = [];
+  for (const item of items) {
+    const it = asObject(item);
+    const ts = asString(it.ts);
+    const pid = asString(it.pid);
+    const tag = asString(it.tag);
+    const msg = asString(it.msg, "");
+    const thread = typeof it.thread === "string" && it.thread.length > 0 ? it.thread : null;
+    const parts = [ts, `pid=${pid}`, tag];
+    if (thread !== null) parts.push(`thread=${thread}`);
+    parts.push(msg);
+    lines.push(parts.join(" "));
+  }
+  return lines.join("\n");
+}

package/src/validate-semantic.ts

@@ -1,21 +1,11 @@
 import type { WorkflowPayload } from "@united-workforce/protocol";
+import { Liquid } from "liquidjs";
 
 type SchemaObj = Record<string, unknown>;
 
 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: string): string[] {
-  const vars: string[] = [];
-  const re = /\{\{\{?([^}]+)\}\}\}?/g;
-  let m: RegExpExecArray | null = re.exec(prompt);
-  while (m !== null) {
-    vars.push(m[1]);
-    m = re.exec(prompt);
-  }
-  return vars;
-}
+const PSEUDO_TARGETS = new Set(["$END"]);
+const SUSPEND_TARGET = "$SUSPEND";
 
 /** Check if a frontmatter schema is a oneOf (multi-exit) type. */
 function isOneOfSchema(fm: unknown): fm is SchemaObj & { oneOf: SchemaObj[] } {
@@ -42,13 +32,6 @@ function getConstStatuses(fm: SchemaObj): string[] {
   return [];
 }
 
-/** Get property names from a schema object. */
-function getPropertyNames(schema: SchemaObj): Set<string> {
-  const props = schema.properties;
-  if (typeof props !== "object" || props === null) return new Set();
-  return new Set(Object.keys(props as Record<string, unknown>));
-}
-
 /** Extract $status const values from oneOf variants. */
 function getOneOfStatuses(variants: SchemaObj[]): string[] {
   const statuses: string[] = [];
@@ -64,6 +47,76 @@ function getOneOfStatuses(variants: SchemaObj[]): string[] {
   return statuses;
 }
 
+/** Generate mock data from schema property names for template rendering. */
+function generateMockData(schema: SchemaObj): Record<string, string> {
+  const mock: Record<string, string> = {};
+  const props = schema.properties as Record<string, SchemaObj> | undefined;
+  if (!props) return mock;
+  for (const key of Object.keys(props)) {
+    mock[key] = `mock_${key}`;
+  }
+  // _body is engine-injected (markdown body after frontmatter), not in the schema.
+  // Always provide it so templates referencing {{ _body }} pass strict validation.
+  mock._body = "mock__body";
+  return mock;
+}
+
+/** Extract variable name from a LiquidJS UndefinedVariableError message. */
+function extractVarName(err: unknown): string {
+  const msg = String(err);
+  const match = msg.match(/undefined variable: ([^,\s]+)/);
+  return match ? match[1] : "unknown";
+}
+
+/** Validate edge templates using LiquidJS strict-render for a multi-exit role. */
+function validateMultiExitTemplates(
+  roleName: string,
+  graphEntry: Record<string, { role: string; prompt: string }>,
+  variants: SchemaObj[],
+  errors: string[],
+): void {
+  const strictEngine = new Liquid({ strictVariables: true });
+
+  for (const [status, target] of Object.entries(graphEntry)) {
+    const variant = variants.find((v) => {
+      const props = v.properties as Record<string, SchemaObj> | undefined;
+      return props?.$status?.const === status;
+    });
+    if (!variant) continue;
+    const mockData = generateMockData(variant);
+    try {
+      strictEngine.parseAndRenderSync(target.prompt, mockData);
+    } catch (err) {
+      const varName = extractVarName(err);
+      errors.push(
+        `template variable "${varName}" not found in role "${roleName}" variant "${status}"`,
+      );
+    }
+  }
+}
+
+/** Validate edge templates using LiquidJS strict-render for a flat schema. */
+function validateFlatTemplates(
+  roleName: string,
+  graphEntry: Record<string, { role: string; prompt: string }>,
+  fm: SchemaObj,
+  errors: string[],
+): void {
+  const strictEngine = new Liquid({ strictVariables: true });
+  const mockData = generateMockData(fm);
+
+  for (const [status, target] of Object.entries(graphEntry)) {
+    try {
+      strictEngine.parseAndRenderSync(target.prompt, mockData);
+    } catch (err) {
+      const varName = extractVarName(err);
+      errors.push(
+        `template variable "${varName}" in graph[${roleName}][${status}] not found in role "${roleName}" frontmatter`,
+      );
+    }
+  }
+}
+
 /** Check reserved names and role/graph reference integrity. */
 function checkRoleReferences(payload: WorkflowPayload, errors: string[]): void {
   const roleNames = new Set(Object.keys(payload.roles));
@@ -89,6 +142,27 @@ function checkRoleReferences(payload: WorkflowPayload, errors: string[]): void {
   }
 }
 
+/** Validate each graph edge's target role, including the removed $SUSPEND target. */
+function checkEdgeTargets(
+  payload: WorkflowPayload,
+  roleNames: Set<string>,
+  errors: string[],
+): void {
+  for (const [node, statusMap] of Object.entries(payload.graph)) {
+    for (const [status, target] of Object.entries(statusMap)) {
+      if (target.role === SUSPEND_TARGET) {
+        errors.push(
+          `edge ${node}→${status}: "${SUSPEND_TARGET}" is no longer a valid graph target. Emit $status: "${SUSPEND_TARGET}" from the "${node}" role output instead.`,
+        );
+        continue;
+      }
+      if (!PSEUDO_TARGETS.has(target.role) && !roleNames.has(target.role)) {
+        errors.push(`edge ${node}→${status}: unknown target role "${target.role}"`);
+      }
+    }
+  }
+}
+
 /** Check $START/$END constraints, edge targets, and reachability. */
 function checkGraphStructure(payload: WorkflowPayload, errors: string[]): void {
   const roleNames = new Set(Object.keys(payload.roles));
@@ -107,17 +181,13 @@ function checkGraphStructure(payload: WorkflowPayload, errors: string[]): void {
     errors.push("$END must not have outgoing edges");
   }
 
-  if (graphNodes.has("$SUSPEND")) {
-    errors.push("$SUSPEND must not have outgoing edges");
+  if (graphNodes.has(SUSPEND_TARGET)) {
+    errors.push(
+      `"${SUSPEND_TARGET}" is no longer a valid graph node — it is now an engine-level reserved $status. Emit $status: "${SUSPEND_TARGET}" from a role output instead.`,
+    );
   }
 
-  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}"`);
-      }
-    }
-  }
+  checkEdgeTargets(payload, roleNames, errors);
 
   checkReachability(roleNames, collectReachableRoles(payload.graph), errors);
 }
@@ -207,31 +277,33 @@ function checkStatusEdges(
   }
 }
 
-/** Check mustache variables for multi-exit role. */
-function checkMultiExitMustache(
-  roleName: string,
-  graphEntry: Record<string, { role: string; prompt: string }>,
-  variants: SchemaObj[],
-  errors: string[],
-): void {
-  for (const [status, target] of Object.entries(graphEntry)) {
-    const vars = extractMustacheVars(target.prompt);
-    const variant = variants.find((v) => {
-      const props = v.properties as Record<string, SchemaObj> | undefined;
-      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}"`);
+/** Reserved property names that must not appear in frontmatter schemas. */
+const RESERVED_PROPERTIES = new Set(["_body"]);
+
+/** Check that frontmatter schemas do not define reserved property names. */
+function checkReservedProperties(roleName: string, fm: unknown, errors: string[]): void {
+  const schemasToCheck: SchemaObj[] = [];
+
+  if (isOneOfSchema(fm)) {
+    schemasToCheck.push(...(fm.oneOf as SchemaObj[]));
+  } else if (typeof fm === "object" && fm !== null) {
+    schemasToCheck.push(fm as SchemaObj);
+  }
+
+  for (const schema of schemasToCheck) {
+    const props = schema.properties as Record<string, unknown> | undefined;
+    if (!props) continue;
+    for (const key of Object.keys(props)) {
+      if (RESERVED_PROPERTIES.has(key)) {
+        errors.push(
+          `role "${roleName}" frontmatter must not define reserved property "${key}" — it is injected by the engine`,
+        );
       }
     }
   }
 }
 
-/** Check status-edge consistency and mustache for each role. */
+/** Check status-edge consistency and template vars for each role. */
 function checkRoleConsistency(payload: WorkflowPayload, errors: string[]): void {
   for (const [roleName, role] of Object.entries(payload.roles)) {
     if (RESERVED_NAMES.has(roleName)) continue;
@@ -241,18 +313,19 @@ function checkRoleConsistency(payload: WorkflowPayload, errors: string[]): void
     const fm = role.frontmatter as unknown;
     const graphKeys = new Set(Object.keys(graphEntry));
 
+    checkReservedProperties(roleName, fm, errors);
+
     if (isOneOfSchema(fm)) {
       const variants = fm.oneOf as SchemaObj[];
       const statuses = getOneOfStatuses(variants);
 
       checkOneOfDiscriminant(roleName, variants, statuses, errors);
       checkStatusEdges(roleName, graphKeys, new Set(statuses), errors);
-      checkMultiExitMustache(roleName, graphEntry, variants, errors);
+      validateMultiExitTemplates(roleName, graphEntry, variants, errors);
     } else if (hasStatusConst(fm)) {
       const statuses = getConstStatuses(fm as SchemaObj);
       checkStatusEdges(roleName, graphKeys, new Set(statuses), errors);
-      // For const-based flat schemas, mustache vars come from the flat properties
-      checkFlatMustache(roleName, graphEntry, fm as SchemaObj, errors);
+      validateFlatTemplates(roleName, graphEntry, fm as SchemaObj, errors);
     } else {
       errors.push(
         `role "${roleName}" must define "$status" as const (or oneOf with const) in frontmatter`,
@@ -261,27 +334,6 @@ function checkRoleConsistency(payload: WorkflowPayload, errors: string[]): void
   }
 }
 
-/** Check mustache vars in all edge prompts against flat schema properties. */
-function checkFlatMustache(
-  roleName: string,
-  graphEntry: Record<string, { role: string; prompt: string }>,
-  fm: SchemaObj,
-  errors: string[],
-): void {
-  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.

package/src/validate.ts

@@ -1,5 +1,6 @@
 import { basename, dirname } from "node:path";
 import type { CasRef, WorkflowPayload } from "@united-workforce/protocol";
+import { CURRENT_WORKFLOW_VERSION } from "@united-workforce/protocol";
 
 const CAS_REF_PATTERN = /^[0-9A-HJKMNP-TV-Z]{13}$/;
 
@@ -113,12 +114,26 @@ export function parseWorkflowPayload(raw: unknown): WorkflowPayload | null {
   if (typeof raw.name !== "string" || typeof raw.description !== "string") {
     return null;
   }
+  // version is optional in legacy YAML — falls back to CURRENT_WORKFLOW_VERSION.
+  // When present, it MUST be an integer (booleans, strings, floats are rejected).
+  if (raw.version !== undefined) {
+    if (
+      typeof raw.version !== "number" ||
+      !Number.isInteger(raw.version) ||
+      typeof raw.version === "boolean"
+    ) {
+      return null;
+    }
+  }
   if (!isStringRecord(raw.roles, isRoleDefinition) || !isGraph(raw.graph)) {
     return null;
   }
 
   // Normalize location field: undefined → null
   const normalized = { ...raw } as WorkflowPayload;
+  if (normalized.version === undefined || normalized.version === null) {
+    normalized.version = CURRENT_WORKFLOW_VERSION;
+  }
   for (const roleName of Object.keys(normalized.graph)) {
     const statusMap = normalized.graph[roleName];
     if (statusMap !== undefined) {
@@ -135,3 +150,15 @@ export function parseWorkflowPayload(raw: unknown): WorkflowPayload | null {
 
   return normalized;
 }
+
+/**
+ * Returns true when the parsed YAML document had no top-level `version` field.
+ * Used by `uwf workflow add` to emit a deprecation warning while still
+ * accepting legacy workflow YAML.
+ */
+export function isMissingVersion(raw: unknown): boolean {
+  if (!isRecord(raw)) {
+    return false;
+  }
+  return raw.version === undefined;
+}

package/dist/__tests__/setup-validate.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=setup-validate.test.d.ts.map

package/dist/__tests__/setup-validate.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"setup-validate.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/setup-validate.test.ts"],"names":[],"mappings":""}