@duckflux/core 0.6.8

package/src/parser/validate_inputs.ts

@@ -0,0 +1,187 @@
+import type { InputDefinition, ValidationError, ValidationResult } from "../model/index";
+
+function coerceValue(value: unknown, typeName: string): unknown {
+  if (typeof value !== "string") return value;
+
+  switch (typeName) {
+    case "integer": {
+      const n = Number(value);
+      if (Number.isInteger(n)) return n;
+      return value;
+    }
+    case "number": {
+      const n = Number(value);
+      if (Number.isFinite(n)) return n;
+      return value;
+    }
+    case "boolean": {
+      if (value === "true") return true;
+      if (value === "false") return false;
+      return value;
+    }
+    default:
+      return value;
+  }
+}
+
+function matchesType(typeName: string, value: unknown): boolean {
+  switch (typeName) {
+    case "string":
+      return typeof value === "string";
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "number":
+      return typeof value === "number";
+    case "boolean":
+      return typeof value === "boolean";
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return typeof value === "object" && value !== null && !Array.isArray(value);
+    default:
+      return true;
+  }
+}
+
+function validateConstraints(
+  name: string,
+  value: unknown,
+  definition: InputDefinition,
+  errors: ValidationError[],
+): void {
+  // Enum
+  if (definition.enum && !definition.enum.includes(value)) {
+    errors.push({
+      path: `inputs.${name}`,
+      message: `input '${name}' must be one of: ${definition.enum.join(", ")}`,
+    });
+  }
+
+  // Numeric constraints
+  if (typeof value === "number") {
+    if (definition.minimum !== undefined && value < definition.minimum) {
+      errors.push({
+        path: `inputs.${name}`,
+        message: `input '${name}' must be >= ${definition.minimum}`,
+      });
+    }
+    if (definition.maximum !== undefined && value > definition.maximum) {
+      errors.push({
+        path: `inputs.${name}`,
+        message: `input '${name}' must be <= ${definition.maximum}`,
+      });
+    }
+  }
+
+  // String constraints
+  if (typeof value === "string") {
+    if (definition.minLength !== undefined && value.length < definition.minLength) {
+      errors.push({
+        path: `inputs.${name}`,
+        message: `input '${name}' must have at least ${definition.minLength} characters`,
+      });
+    }
+    if (definition.maxLength !== undefined && value.length > definition.maxLength) {
+      errors.push({
+        path: `inputs.${name}`,
+        message: `input '${name}' must have at most ${definition.maxLength} characters`,
+      });
+    }
+    if (definition.pattern) {
+      const regex = new RegExp(definition.pattern);
+      if (!regex.test(value)) {
+        errors.push({
+          path: `inputs.${name}`,
+          message: `input '${name}' must match pattern: ${definition.pattern}`,
+        });
+      }
+    }
+  }
+
+  // Format validation (best-effort)
+  if (typeof value === "string" && definition.format) {
+    let valid = true;
+    switch (definition.format) {
+      case "date":
+        valid = !Number.isNaN(Date.parse(value)) && /^\d{4}-\d{2}-\d{2}$/.test(value);
+        break;
+      case "date-time":
+        valid = !Number.isNaN(Date.parse(value));
+        break;
+      case "uri":
+        try {
+          new URL(value);
+        } catch {
+          valid = false;
+        }
+        break;
+      case "email":
+        valid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+        break;
+    }
+    if (!valid) {
+      errors.push({
+        path: `inputs.${name}`,
+        message: `input '${name}' must be a valid ${definition.format}`,
+      });
+    }
+  }
+}
+
+export function validateInputs(
+  inputDefs: Record<string, InputDefinition | null> | undefined,
+  provided: Record<string, unknown>,
+): { result: ValidationResult; resolved: Record<string, unknown> } {
+  if (!inputDefs) {
+    return {
+      result: { valid: true, errors: [] },
+      resolved: { ...provided },
+    };
+  }
+
+  const errors: ValidationError[] = [];
+  const resolved: Record<string, unknown> = { ...provided };
+
+  for (const [name, definition] of Object.entries(inputDefs)) {
+    // null definition means string type with no schema
+    if (definition === null) {
+      continue;
+    }
+
+    const hasProvided = name in provided;
+
+    if (!hasProvided) {
+      if (definition.default !== undefined) {
+        resolved[name] = definition.default;
+      } else if (definition.required) {
+        errors.push({
+          path: `inputs.${name}`,
+          message: `required input '${name}' is missing`,
+        });
+      }
+      continue;
+    }
+
+    // Coerce from CLI string values
+    if (definition.type) {
+      resolved[name] = coerceValue(provided[name], definition.type);
+    }
+
+    const value = resolved[name];
+
+    if (definition.type && !matchesType(definition.type, value)) {
+      errors.push({
+        path: `inputs.${name}`,
+        message: `input '${name}' must be of type '${definition.type}'`,
+      });
+      continue;
+    }
+
+    validateConstraints(name, value, definition, errors);
+  }
+
+  return {
+    result: { valid: errors.length === 0, errors },
+    resolved,
+  };
+}

package/src/participant/emit.ts

@@ -0,0 +1,63 @@
+import { evaluateCel } from "../cel/index";
+import type { EventHub } from "../eventhub/types";
+import type { EmitParticipant, StepResult } from "../model/index";
+import { parseDuration } from "../engine/errors";
+
+export async function executeEmit(
+  participant: EmitParticipant,
+  context: Record<string, unknown>,
+  hub: EventHub,
+): Promise<StepResult> {
+  const startedAt = new Date().toISOString();
+  const start = Date.now();
+
+  // Resolve payload
+  let resolvedPayload: unknown;
+  if (typeof participant.payload === "string") {
+    resolvedPayload = evaluateCel(participant.payload, context);
+  } else if (participant.payload && typeof participant.payload === "object") {
+    const resolved: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(participant.payload)) {
+      resolved[key] = typeof value === "string" ? evaluateCel(value, context) : value;
+    }
+    resolvedPayload = resolved;
+  } else {
+    resolvedPayload = {};
+  }
+
+  try {
+    if (participant.ack) {
+      const timeoutMs = participant.timeout ? parseDuration(participant.timeout) : 30000;
+      await hub.publishAndWaitAck(participant.event, resolvedPayload, timeoutMs);
+    } else {
+      await hub.publish(participant.event, resolvedPayload);
+    }
+
+    return {
+      status: "success",
+      output: JSON.stringify({ ack: true }),
+      parsedOutput: { ack: true },
+      duration: Date.now() - start,
+      startedAt,
+      finishedAt: new Date().toISOString(),
+    };
+  } catch (err) {
+    const isTimeout =
+      err instanceof Error &&
+      (err.name === "AbortError" ||
+        err.name === "TimeoutError" ||
+        /timed?\s*out/i.test(err.message));
+
+    if (participant.onTimeout === "skip" && isTimeout) {
+      return {
+        status: "success",
+        output: JSON.stringify({ ack: false }),
+        parsedOutput: { ack: false },
+        duration: Date.now() - start,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+      };
+    }
+    throw err;
+  }
+}

package/src/participant/exec.ts

@@ -0,0 +1,158 @@
+import { spawn } from "node:child_process";
+import type { StepResult } from "../model/index";
+
+function isMap(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function mapToEnvVars(input: Record<string, unknown>): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(input)) {
+    env[key] = typeof value === "string" ? value : String(value);
+  }
+  return env;
+}
+
+export async function executeExec(
+  participant: { run?: string; env?: Record<string, string>; cwd?: string },
+  input?: unknown,
+  env: Record<string, string> = {},
+  signal?: AbortSignal,
+): Promise<StepResult> {
+  const command = participant.run ?? "";
+  const participantEnv = participant.env ?? {};
+  const cwd = participant.cwd ?? process.cwd();
+
+  // Spec v0.6: map input → env vars, string input → stdin, no input → nothing
+  const inputEnvVars = isMap(input) ? mapToEnvVars(input) : {};
+  const stdinData = typeof input === "string" ? input : undefined;
+
+  const startedAt = new Date().toISOString();
+  const start = Date.now();
+
+  return new Promise<StepResult>((resolve) => {
+    try {
+      const proc = spawn("sh", ["-c", command], {
+        env: { ...process.env, ...env, ...participantEnv, ...inputEnvVars },
+        cwd,
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+
+      let stdout = "";
+      let stderr = "";
+
+      proc.stdout.on("data", (d: Buffer) => {
+        stdout += d.toString();
+      });
+      proc.stderr.on("data", (d: Buffer) => {
+        stderr += d.toString();
+      });
+
+      let aborted = false;
+      const onAbort = () => {
+        aborted = true;
+        try {
+          proc.kill("SIGKILL");
+        } catch (_) {}
+      };
+
+      if (signal) {
+        if (signal.aborted) onAbort();
+        else signal.addEventListener("abort", onAbort);
+      }
+
+      proc.on("error", (err) => {
+        const duration = Date.now() - start;
+        if (signal) signal.removeEventListener("abort", onAbort);
+        resolve({
+          status: "failure",
+          output: "",
+          parsedOutput: undefined,
+          error: String(err),
+          duration,
+          startedAt,
+          finishedAt: new Date().toISOString(),
+          cwd,
+        });
+      });
+
+      proc.on("close", (code) => {
+        const duration = Date.now() - start;
+        if (signal) signal.removeEventListener("abort", onAbort);
+
+        if (aborted) {
+          resolve({
+            status: "failure",
+            output: stdout,
+            parsedOutput: undefined,
+            error: "aborted",
+            duration,
+            startedAt,
+            finishedAt: new Date().toISOString(),
+            cwd,
+          });
+          return;
+        }
+
+        const exitCode = code ?? 1;
+        if (exitCode !== 0) {
+          const errMsg = stderr.trim() || `exit code ${exitCode}`;
+          resolve({
+            status: "failure",
+            output: stdout,
+            parsedOutput: undefined,
+            error: errMsg,
+            duration,
+            startedAt,
+            finishedAt: new Date().toISOString(),
+            cwd,
+          });
+          return;
+        }
+
+        let parsed: unknown | undefined = undefined;
+        try {
+          parsed = JSON.parse(stdout);
+        } catch (_) {
+          // ignore parse errors
+        }
+
+        resolve({
+          status: "success",
+          output: stdout,
+          parsedOutput: parsed,
+          duration,
+          startedAt,
+          finishedAt: new Date().toISOString(),
+          cwd,
+        });
+      });
+
+      // Spec v0.6: only write to stdin when input is a string
+      if (stdinData !== undefined) {
+        try {
+          proc.stdin.write(stdinData);
+          proc.stdin.end();
+        } catch (_) {
+          // ignore
+        }
+      } else {
+        try { proc.stdin.end(); } catch (_) { /* ignore */ }
+      }
+    } catch (err) {
+      const duration = Date.now() - start;
+      resolve({
+        status: "failure",
+        output: "",
+        parsedOutput: undefined,
+        error: String(err),
+        duration,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        cwd,
+      });
+    }
+  });
+}
+
+export default executeExec;

package/src/participant/http.ts

@@ -0,0 +1,45 @@
+import type { StepResult } from "../model/index";
+
+export default async function executeHttp(participant: { url: string; method?: string; headers?: Record<string, string>; body?: unknown }, input?: string): Promise<StepResult> {
+  const startedAt = new Date().toISOString();
+  const start = Date.now();
+  const method = (participant.method ?? "GET").toUpperCase();
+  const url = participant.url;
+  const headers = participant.headers ?? {};
+  let body: unknown = participant.body;
+  if ((body === undefined || body === null) && input !== undefined) {
+    body = input;
+  }
+
+  const fetchOptions: RequestInit = { method, headers: headers as HeadersInit };
+  if (body !== undefined) fetchOptions.body = typeof body === "string" ? body : JSON.stringify(body);
+
+  const res = await fetch(url, fetchOptions);
+  const text = await res.text();
+  const duration = Date.now() - start;
+
+  if (!res.ok) {
+    const err: Error & { httpStatus?: number; responseBody?: string } = new Error(
+      `http participant request failed: ${res.status} ${res.statusText}`,
+    );
+    err.httpStatus = res.status;
+    err.responseBody = text;
+    throw err;
+  }
+
+  let parsedOutput: unknown;
+  try {
+    parsedOutput = JSON.parse(text);
+  } catch (_) {
+    // ignore parse errors
+  }
+
+  return {
+    status: "success",
+    output: text,
+    parsedOutput,
+    duration,
+    startedAt,
+    finishedAt: new Date().toISOString(),
+  };
+}

package/src/participant/index.ts

@@ -0,0 +1,61 @@
+import type { EventHub } from "../eventhub/types";
+import type { EmitParticipant, McpParticipant, Participant, StepResult, WorkflowParticipant } from "../model/index";
+import { executeEmit } from "./emit";
+import { executeExec } from "./exec";
+import executeHttp from "./http";
+import { executeMcp } from "./mcp";
+import { executeSubWorkflow } from "./workflow";
+import type { AncestorPaths, WorkflowEngineExecutor } from "./workflow";
+
+export type ExecutorFunction = (
+  participant: Participant,
+  input: unknown,
+  env: Record<string, string>,
+  basePath?: string,
+  engineExecutor?: WorkflowEngineExecutor,
+  hub?: EventHub,
+  celContext?: Record<string, unknown>,
+  ancestorPaths?: AncestorPaths,
+) => Promise<StepResult>;
+
+const executors: Record<string, ExecutorFunction> = {
+  exec: async (participant, input, env) => executeExec(participant as Parameters<typeof executeExec>[0], input, env),
+  http: async (participant, input) => executeHttp(participant as Parameters<typeof executeHttp>[0], input as string | undefined),
+  workflow: async (participant, input, _env, basePath, engineExecutor, _hub, _celContext, ancestorPaths) => {
+    if (!basePath) {
+      throw new Error("workflow participant execution requires basePath");
+    }
+    if (!engineExecutor) {
+      throw new Error("workflow participant execution requires engineExecutor");
+    }
+    return executeSubWorkflow(participant as WorkflowParticipant, input, basePath, engineExecutor, ancestorPaths);
+  },
+  mcp: async (participant, input) => executeMcp(participant as McpParticipant, input),
+  emit: async (participant, _input, _env, _basePath, _engineExecutor, hub, celContext) => {
+    if (!hub) {
+      throw new Error("emit participant requires an event hub but none was provided");
+    }
+    if (!celContext) {
+      throw new Error("emit participant requires CEL context");
+    }
+    return executeEmit(participant as EmitParticipant, celContext, hub);
+  },
+};
+
+export async function executeParticipant(
+  participant: Participant,
+  input: unknown,
+  env: Record<string, string> = {},
+  basePath?: string,
+  engineExecutor?: WorkflowEngineExecutor,
+  hub?: EventHub,
+  celContext?: Record<string, unknown>,
+  ancestorPaths?: AncestorPaths,
+): Promise<StepResult> {
+  const executor = executors[participant.type];
+  if (!executor) {
+    throw new Error(`participant type '${participant.type}' is not yet implemented`);
+  }
+
+  return executor(participant, input, env, basePath, engineExecutor, hub, celContext, ancestorPaths);
+}

package/src/participant/mcp.ts

@@ -0,0 +1,8 @@
+import type { McpParticipant, StepResult } from "../model/index";
+
+export async function executeMcp(participant: McpParticipant, _input: unknown): Promise<StepResult> {
+  throw new Error(
+    `mcp participant is not yet implemented (server: ${participant.server ?? "unspecified"}, tool: ${participant.tool ?? "unspecified"}). ` +
+    "Use onError to handle this gracefully.",
+  );
+}

package/src/participant/workflow.ts

@@ -0,0 +1,73 @@
+import { dirname, resolve } from "node:path";
+import type { StepResult, Workflow, WorkflowParticipant, WorkflowResult } from "../model/index";
+import { parseWorkflowFile } from "../parser/parser";
+import { validateSchema } from "../parser/schema";
+import { validateSemantic } from "../parser/validate";
+
+export type WorkflowEngineExecutor = (
+  workflow: Workflow,
+  inputs: Record<string, unknown>,
+  basePath: string,
+) => Promise<WorkflowResult>;
+
+/** Set of ancestor workflow file paths, injected by engine for circular detection */
+export type AncestorPaths = Set<string>;
+
+function toWorkflowInputs(input: unknown): Record<string, unknown> {
+  if (input && typeof input === "object" && !Array.isArray(input)) {
+    return { ...(input as Record<string, unknown>) };
+  }
+
+  if (input === undefined) {
+    return {};
+  }
+
+  return { input };
+}
+
+export async function executeSubWorkflow(
+  participant: WorkflowParticipant,
+  input: unknown,
+  basePath: string,
+  engineExecutor: WorkflowEngineExecutor,
+  ancestorPaths?: AncestorPaths,
+): Promise<StepResult> {
+  const start = Date.now();
+
+  const resolvedPath = resolve(basePath, participant.path);
+
+  // Circular sub-workflow detection (§13.2)
+  if (ancestorPaths?.has(resolvedPath)) {
+    throw new Error(
+      `circular sub-workflow detected: '${resolvedPath}' is already on the call stack`,
+    );
+  }
+  ancestorPaths?.add(resolvedPath);
+
+  const subWorkflow = await parseWorkflowFile(resolvedPath);
+
+  const schemaResult = validateSchema(subWorkflow);
+  if (!schemaResult.valid) {
+    throw new Error(`schema validation failed: ${JSON.stringify(schemaResult.errors)}`);
+  }
+
+  const semanticResult = await validateSemantic(subWorkflow, dirname(resolvedPath));
+  if (!semanticResult.valid) {
+    throw new Error(`semantic validation failed: ${JSON.stringify(semanticResult.errors)}`);
+  }
+
+  try {
+    const result = await engineExecutor(subWorkflow, toWorkflowInputs(input), dirname(resolvedPath));
+    const output =
+      typeof result.output === "string" ? result.output : JSON.stringify(result.output ?? null);
+
+    return {
+      status: result.success ? "success" : "failure",
+      output,
+      parsedOutput: result.output,
+      duration: Date.now() - start,
+    };
+  } finally {
+    ancestorPaths?.delete(resolvedPath);
+  }
+}