@dazl/api-client 1.0.43 → 1.0.45

package/src/workflow-document.ts

@@ -0,0 +1,333 @@
+import { z } from "zod";
+
+/** The only schema version there has ever been. Interactive fields are ordinary optional fields. */
+export const WORKFLOW_DOCUMENT_SCHEMA_VERSION = "1";
+
+/** Directory the editor creates workflow files in. Discovery is by extension, not by directory. */
+export const WORKFLOWS_DIR = "workflows";
+export const WORKFLOW_FILE_EXTENSION = ".flow.json";
+
+/** How a run can start. A closed set: nothing else starts a run, and there is no schedule trigger. */
+export const TRIGGER_SOURCES = ["workspace-prompt", "chat-prompt", "chat-agent-tool"] as const;
+export type TriggerSource = (typeof TRIGGER_SOURCES)[number];
+
+/**
+ * Whether a path stays inside the project root it is resolved against: not an absolute POSIX, drive
+ * or UNC path, not a URL, no `..` segment, no NUL byte. Both `/` and `\` count as separators, so the
+ * guarantee holds for a consumer on Windows too. A backslash is otherwise allowed, because git
+ * C-quotes a non-ASCII name (`"\303\251.txt"`) and observed paths carry that verbatim. `.` and empty
+ * segments cannot escape, so a `./` prefix or a doubled slash is accepted rather than rejected.
+ */
+function staysInProjectRoot(path: string): boolean {
+  return (
+    !/^[/\\]/.test(path) &&
+    !/^[a-z]:/i.test(path) &&
+    !/^[a-z][a-z\d+.-]*:\/\//i.test(path) &&
+    !path.split(/[/\\]/).includes("..") &&
+    !path.includes("\0")
+  );
+}
+
+const relativePathSchema = z.string().refine(staysInProjectRoot, {
+  message: "Must be a project-relative path: not absolute, not a URL, and without '..' segments",
+});
+
+/** A non-empty path relative to the project root that cannot leave it. */
+export const projectRelativePathSchema = relativePathSchema.min(1);
+
+/**
+ * What every node produces. The same shape for every node in every workflow — it is not authored and
+ * is not part of the document. A step that needs to hand on anything richer than prose writes a file
+ * and names it here.
+ */
+export const workflowNodeOutputSchema = z.object({
+  text: z.string(),
+  /** Project-relative paths. Never absolute, never a URL, never escaping the root. */
+  files: z.array(projectRelativePathSchema).default([]),
+  /**
+   * What the executor observed this step change, one entry per repository whose head moved.
+   *
+   * Written by the executor after the agent's own output, never by the agent: `text` and `files`
+   * are what a step says it did, and this is what it was seen to do. Optional because an output
+   * stored before this existed must still parse, and because a step that moved no head records
+   * nothing at all. Absent therefore means "nothing was observed", which covers both a step that
+   * changed nothing and a step nobody was watching - the two are deliberately not distinguished
+   * here. What is kept distinct is absent versus an empty array, which no producer ever writes.
+   */
+  changes: z
+    .array(
+      z.object({
+        /** Directory under the project root; '' when the project root is itself the repo. */
+        dirName: relativePathSchema,
+        from: z.string(),
+        to: z.string(),
+        commits: z.number().int().nonnegative(),
+        /** Project-relative, as `getChangedFilesBetween` reports them. */
+        files: z.array(projectRelativePathSchema),
+      }),
+    )
+    .optional(),
+});
+export type WorkflowNodeOutput = z.infer<typeof workflowNodeOutputSchema>;
+
+const nodePositionSchema = z.object({ x: z.number(), y: z.number() });
+
+const nodeSizeSchema = z.object({ width: z.number(), height: z.number() });
+
+const baseNodeSchema = z.object({
+  id: z.string().min(1),
+  title: z.string(),
+  description: z.string().optional(),
+  position: nodePositionSchema,
+  /** Set once a user drags a node, so auto-layout stops moving it. */
+  manualPosition: z.boolean().optional(),
+  size: nodeSizeSchema.optional(),
+  /** The one node that follows this one. Absent means the run ends here. */
+  nextStep: z.string().optional(),
+  skippable: z.boolean().default(false),
+});
+
+/** One reviewer on a review node: an agent, optionally speaking for a person. */
+export const workflowReviewerSchema = z.object({
+  /**
+   * An agent document's `meta.name`. Deliberately not `.min(1)`, for the same reason as the `work`
+   * node's `agent` field below: a reviewer can be added before its agent is picked, and rejecting
+   * `""` here would make the whole document non-conforming over the step the user just touched.
+   * `validateWorkflowChain` warns about an empty reviewer agent; sync time is where it becomes an
+   * error.
+   */
+  agent: z.string(),
+  prompt: z.string().optional(),
+  /** Email of the person this reviewer represents, matching how rule owners are named. */
+  onBehalfOf: z.string().optional(),
+  /** Omission means personal. Only an explicit designation makes a conversation workspace-visible. */
+  conversationRole: z.enum(["personal", "workspace"]).optional(),
+});
+export type WorkflowReviewer = z.infer<typeof workflowReviewerSchema>;
+
+export const workflowNodeSchema = z.discriminatedUnion("kind", [
+  baseNodeSchema.extend({
+    kind: z.literal("trigger"),
+    source: z.enum(TRIGGER_SOURCES),
+  }),
+  baseNodeSchema.extend({
+    kind: z.literal("work"),
+    interaction: z.enum(["automatic", "interactive"]).optional(),
+    /**
+     * An agent document's `meta.name`. Resolved at sync time, warned about while authoring -
+     * deliberately not `.min(1)`. A work step exists before an agent is chosen for it, and a
+     * `.min(1)` here would make the whole document non-conforming the instant such a step is
+     * created, collapsing the panel around the step the user just added. `""` is a safe sentinel
+     * for "not picked yet" because every other agent reference in this file is `.min(1)`, so no
+     * real agent can be named the empty string. `validateWorkflowChain` warns about it instead.
+     */
+    agent: z.string(),
+    /** Extra instruction for this step, appended to the agent's own system prompt. */
+    prompt: z.string().optional(),
+  }),
+  baseNodeSchema.extend({
+    kind: z.literal("review"),
+    interaction: z.enum(["automatic", "interactive"]).optional(),
+    reviewers: z.array(workflowReviewerSchema).default([]),
+  }),
+]);
+export type WorkflowNode = z.infer<typeof workflowNodeSchema>;
+
+/**
+ * Kinds that can only ever *begin* a chain: nothing may name one as its `nextStep`.
+ *
+ * A named list rather than a `=== "trigger"` written out wherever the question comes up, because it
+ * is asked in three places that must agree - `validateWorkflowChain` below, the editor's chain
+ * mutations, and the editor's add menus - and two of those are in another repository reaching this
+ * file through the SDK. It is a list rather than a single value because several triggers in one
+ * workflow are coming, each starting its own chain, and because a second head-only kind would then
+ * be one entry here rather than a fourth copy of the same comparison.
+ */
+export const CHAIN_HEAD_KINDS: readonly WorkflowNode["kind"][] = ["trigger"];
+
+/** Whether a node of this kind can only start a chain. `undefined` - an unknown node - is not one. */
+export function isChainHeadKind(kind: string | undefined): boolean {
+  return kind !== undefined && (CHAIN_HEAD_KINDS as readonly string[]).includes(kind);
+}
+
+export const workflowDocumentSchema = z.object({
+  schemaVersion: z.literal(WORKFLOW_DOCUMENT_SCHEMA_VERSION).optional(),
+  meta: z.object({
+    /**
+     * Deliberately not `.min(1)`. A user clearing the field to retype it would otherwise invalidate
+     * the document mid-keystroke and collapse the form around them — the exact defect step 1a shipped
+     * and had to fix. An empty name is recoverable; a missing one is still an error.
+     */
+    name: z.string(),
+    description: z.string().optional(),
+  }),
+  nodes: z.array(workflowNodeSchema).default([]),
+});
+
+export type WorkflowDocument = z.infer<typeof workflowDocumentSchema>;
+export type WorkflowDocumentInput = z.input<typeof workflowDocumentSchema>;
+
+/** Inspects the whole document. Execution must first restrict this to its selected reachable chain. */
+export function isInteractiveWorkflowDocument(document: WorkflowDocument): boolean {
+  return document.nodes.some((node) => node.kind !== "trigger" && node.interaction === "interactive");
+}
+
+export interface WorkflowDocumentError {
+  path: string;
+  message: string;
+}
+
+export type WorkflowDocumentValidation =
+  { valid: true; document: WorkflowDocument } | { valid: false; errors: WorkflowDocumentError[] };
+
+export function validateWorkflowDocument(value: unknown): WorkflowDocumentValidation {
+  const result = workflowDocumentSchema.safeParse(value);
+  if (result.success) {
+    return { valid: true, document: result.data };
+  }
+  return {
+    valid: false,
+    errors: result.error.issues.map((issue) => ({
+      path: issue.path.length > 0 ? issue.path.join(".") : "document",
+      message: issue.message,
+    })),
+  };
+}
+
+export interface WorkflowChainWarning {
+  nodeId: string;
+  message: string;
+}
+
+/**
+ * Chain integrity, reported separately from schema validity and deliberately as warnings.
+ *
+ * A half-built workflow is a normal state to be in while authoring — a node whose `nextStep` is not
+ * written yet must not make the file invalid. Step 2's sync is where these become failures.
+ */
+export function validateWorkflowChain(nodes: readonly WorkflowNode[]): WorkflowChainWarning[] {
+  const warnings: WorkflowChainWarning[] = [];
+
+  // Not a chain-shape problem, but the same "authoring problem, not a schema violation" category:
+  // `agent` accepts "" so that adding a step or a reviewer never invalidates the document, and this
+  // is where that loosened value gets flagged instead.
+  for (const node of nodes) {
+    if (node.kind === "work" && node.agent === "") {
+      warnings.push({ nodeId: node.id, message: "This step has no agent assigned yet." });
+    }
+    if (node.kind === "review") {
+      if (
+        node.interaction === "interactive" &&
+        node.reviewers.filter((r) => r.conversationRole === "workspace").length !== 1
+      ) {
+        warnings.push({
+          nodeId: node.id,
+          message: "An interactive review must designate exactly one workspace reviewer.",
+        });
+      }
+      for (const reviewer of node.reviewers) {
+        if (reviewer.agent === "") {
+          warnings.push({ nodeId: node.id, message: "This step has a reviewer with no agent assigned yet." });
+        }
+      }
+    }
+  }
+
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  const incoming = new Map<string, number>();
+  const seen = new Set<string>();
+
+  for (const node of nodes) {
+    if (node.nextStep === undefined) {
+      continue;
+    }
+    if (node.nextStep === node.id) {
+      warnings.push({ nodeId: node.id, message: "This step points at itself." });
+      seen.add(node.id);
+      continue;
+    }
+    const target = byId.get(node.nextStep);
+    if (target === undefined) {
+      warnings.push({ nodeId: node.id, message: `Next step "${node.nextStep}" is not a step in this workflow.` });
+      continue;
+    }
+    // A trigger is a chain head and nothing may point at one. Reported against the step holding the
+    // link rather than against the trigger, because the link is the thing that is wrong and the step
+    // holding it is the only one that can be repaired - the trigger itself is fine as it is.
+    if (isChainHeadKind(target.kind)) {
+      warnings.push({
+        nodeId: node.id,
+        message: "This step points at a trigger, and a trigger can only start a chain.",
+      });
+    }
+    incoming.set(node.nextStep, (incoming.get(node.nextStep) ?? 0) + 1);
+  }
+
+  for (const [nodeId, count] of incoming) {
+    if (count > 1) {
+      warnings.push({ nodeId, message: "More than one step leads here, and the flow is a single chain." });
+    }
+  }
+
+  // A cycle is only reachable once every hop resolves, so this runs after the checks above.
+  for (const node of nodes) {
+    if (seen.has(node.id)) {
+      continue;
+    }
+    const path = new Set<string>();
+    let current: WorkflowNode | undefined = node;
+    while (current && !seen.has(current.id)) {
+      if (path.has(current.id)) {
+        warnings.push({ nodeId: current.id, message: "These steps form a cycle, so the run would never end." });
+        break;
+      }
+      path.add(current.id);
+      current = current.nextStep === undefined ? undefined : byId.get(current.nextStep);
+    }
+    for (const id of path) {
+      seen.add(id);
+    }
+  }
+
+  return warnings;
+}
+
+export function createDefaultWorkflowDocument(name: string): WorkflowDocumentInput {
+  return {
+    schemaVersion: WORKFLOW_DOCUMENT_SCHEMA_VERSION,
+    meta: { name },
+    nodes: [
+      {
+        // A uuid, like every other node id. `id` is what becomes `WorkflowNodeRun.nodeKey` when a
+        // run is projected, and the editor's own `createNode` uses `crypto.randomUUID()` - so the
+        // literal "trigger" here meant every workflow ever created shipped with exactly one node
+        // whose key was not a uuid, and two workflows whose first steps collided on it.
+        id: crypto.randomUUID(),
+        kind: "trigger",
+        title: "Start",
+        source: "workspace-prompt",
+        position: { x: 0, y: 0 },
+      },
+    ],
+  };
+}
+
+/**
+ * Filename for a workflow, derived from its display name.
+ *
+ * Throws rather than returning a bare extension for a name with no ASCII alphanumerics, matching
+ * `CanvasManager.createCanvasFileName`. Step 1a's agent equivalent shipped without this guard and a
+ * non-Latin name silently wrote a dotfile.
+ */
+export function toSafeWorkflowFileName(name: string): string {
+  const slug = name
+    .replace(/[^a-zA-Z0-9]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60)
+    .toLowerCase();
+  if (!slug) {
+    throw new Error("Workflow name must contain at least one letter or number");
+  }
+  return `${slug}${WORKFLOW_FILE_EXTENSION}`;
+}