@duckflux/runner 0.6.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@duckflux/runner",
+  "version": "0.6.0",
+  "type": "module",
+  "bin": {
+    "duckflux": "dist/main.js"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./dist/main.js": "./dist/main.js"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "bun build src/main.ts --outdir dist --target node --format esm --banner '#!/usr/bin/env node' && tsc --project tsconfig.build.json",
+    "postbuild": "chmod +x dist/main.js",
+    "prepublishOnly": "bun run build",
+    "compile:linux-x64": "bun build --compile --target=bun-linux-x64 src/main.ts --outfile bin/duckflux-linux-x64",
+    "compile:linux-arm64": "bun build --compile --target=bun-linux-arm64 src/main.ts --outfile bin/duckflux-linux-arm64",
+    "compile:darwin-x64": "bun build --compile --target=bun-darwin-x64 src/main.ts --outfile bin/duckflux-darwin-x64",
+    "compile:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/main.ts --outfile bin/duckflux-darwin-arm64",
+    "compile:windows-x64": "bun build --compile --target=bun-windows-x64 src/main.ts --outfile bin/duckflux-windows-x64.exe",
+    "compile": "bun run compile:linux-x64 && bun run compile:linux-arm64 && bun run compile:darwin-x64 && bun run compile:darwin-arm64 && bun run compile:windows-x64"
+  },
+  "dependencies": {
+    "@duckflux/core": "workspace:*"
+  },
+  "optionalDependencies": {
+    "@duckflux/hub-nats": "workspace:*",
+    "@duckflux/hub-redis": "workspace:*"
+  }
+}

package/src/lint.ts

@@ -0,0 +1,179 @@
+#!/usr/bin/env bun
+import { dirname } from "node:path";
+import { parseWorkflowFile, validateSchema, validateSemantic } from "@duckflux/core";
+import type { Workflow } from "@duckflux/core";
+
+interface LintWarning {
+  path: string;
+  message: string;
+}
+
+function collectLintWarnings(workflow: Workflow): LintWarning[] {
+  const warnings: LintWarning[] = [];
+  const participants = workflow.participants ?? {};
+
+  collectFlowWarnings(workflow.flow ?? [], participants, warnings);
+
+  return warnings;
+}
+
+function collectFlowWarnings(
+  flow: unknown[],
+  participants: Record<string, { type: string; as?: string; [key: string]: unknown }>,
+  warnings: LintWarning[],
+  basePath = "flow",
+): void {
+  for (const [index, step] of flow.entries()) {
+    const stepPath = `${basePath}[${index}]`;
+
+    if (!step || typeof step !== "object") continue;
+
+    const obj = step as Record<string, unknown>;
+
+    // Warn: loop with no `until` and no `max`
+    if (obj.loop && Object.keys(obj).length === 1) {
+      const loopDef = obj.loop as Record<string, unknown>;
+      if (loopDef.until == null && loopDef.max == null) {
+        warnings.push({
+          path: `${stepPath}.loop`,
+          message: "loop has no 'until' and no 'max' — this will be rejected at runtime",
+        });
+      }
+      collectFlowWarnings(
+        (loopDef.steps ?? []) as unknown[],
+        participants,
+        warnings,
+        `${stepPath}.loop.steps`,
+      );
+      continue;
+    }
+
+    // Warn: parallel branches referencing the same mutable state via `set`
+    if (obj.parallel && Object.keys(obj).length === 1) {
+      const parallelSteps = obj.parallel as unknown[];
+      const branchSetKeys: Map<string, number[]> = new Map();
+      for (const [branchIdx, branch] of parallelSteps.entries()) {
+        const setKeys = collectSetKeys(branch);
+        for (const key of setKeys) {
+          const branches = branchSetKeys.get(key) ?? [];
+          branches.push(branchIdx);
+          branchSetKeys.set(key, branches);
+        }
+      }
+      for (const [key, branches] of branchSetKeys) {
+        if (branches.length > 1) {
+          warnings.push({
+            path: `${stepPath}.parallel`,
+            message: `branches [${branches.join(", ")}] both write to '${key}' via set — race condition risk`,
+          });
+        }
+      }
+      collectFlowWarnings(parallelSteps, participants, warnings, `${stepPath}.parallel`);
+      continue;
+    }
+
+    // Warn: anonymous participant output referenced by name (unreachable)
+    if ("type" in obj && !obj.as) {
+      warnings.push({
+        path: stepPath,
+        message: "inline participant without 'as' — its output cannot be referenced by name",
+      });
+      continue;
+    }
+
+    if (obj.if && Object.keys(obj).length === 1) {
+      const ifDef = obj.if as Record<string, unknown>;
+      collectFlowWarnings(
+        (ifDef.then ?? []) as unknown[],
+        participants,
+        warnings,
+        `${stepPath}.if.then`,
+      );
+      if (ifDef.else) {
+        collectFlowWarnings(
+          ifDef.else as unknown[],
+          participants,
+          warnings,
+          `${stepPath}.if.else`,
+        );
+      }
+    }
+  }
+}
+
+function collectSetKeys(step: unknown): string[] {
+  if (!step || typeof step !== "object") return [];
+  const obj = step as Record<string, unknown>;
+
+  if ("set" in obj && Object.keys(obj).length === 1) {
+    return Object.keys(obj.set as Record<string, unknown>);
+  }
+
+  // Recurse into nested flow structures
+  const keys: string[] = [];
+  if (obj.loop) {
+    const loopDef = obj.loop as Record<string, unknown>;
+    for (const s of (loopDef.steps ?? []) as unknown[]) {
+      keys.push(...collectSetKeys(s));
+    }
+  }
+  if (obj.if) {
+    const ifDef = obj.if as Record<string, unknown>;
+    for (const s of (ifDef.then ?? []) as unknown[]) {
+      keys.push(...collectSetKeys(s));
+    }
+    if (ifDef.else) {
+      for (const s of ifDef.else as unknown[]) {
+        keys.push(...collectSetKeys(s));
+      }
+    }
+  }
+  return keys;
+}
+
+export default async function lintCommand(filePath?: string): Promise<number> {
+  if (!filePath) {
+    console.error("Usage: duckflux lint <workflow.yaml>");
+    return 1;
+  }
+
+  try {
+    const workflow = await parseWorkflowFile(filePath);
+
+    const schemaRes = validateSchema(workflow);
+    if (!schemaRes.valid) {
+      console.error("Schema validation failed:");
+      for (const e of schemaRes.errors) {
+        console.error(`  - ${e.path}: ${e.message}`);
+      }
+      return 1;
+    }
+
+    const basePath = dirname(filePath);
+    const semanticRes = await validateSemantic(workflow, basePath);
+    if (!semanticRes.valid) {
+      console.error("Semantic validation failed:");
+      for (const e of semanticRes.errors) {
+        console.error(`  - ${e.path}: ${e.message}`);
+      }
+      return 1;
+    }
+
+    // Lint warnings (non-blocking)
+    const warnings = collectLintWarnings(workflow);
+    if (warnings.length > 0) {
+      console.warn("Warnings:");
+      for (const w of warnings) {
+        console.warn(`  - ${w.path}: ${w.message}`);
+      }
+    }
+
+    console.log("valid");
+    return 0;
+  } catch (err: any) {
+    console.error("Error during lint:", err && err.message ? err.message : err);
+    return 1;
+  }
+}
+
+export { lintCommand };

package/src/main.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env bun
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { dirname, resolve } from "node:path";
+import runCommand from "./run";
+import lintCommand from "./lint";
+import validateCommand from "./validate";
+
+function getVersion(): string {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(dirname(new URL(import.meta.url).pathname), "../package.json"), "utf-8"));
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+if (import.meta.main) {
+  const argv = Bun.argv.slice(2);
+  const { values, positionals } = parseArgs({
+    args: argv,
+    options: {
+      input: { type: "string", multiple: true, short: "i" },
+      "input-file": { type: "string" },
+      verbose: { type: "boolean", short: "v" },
+      quiet: { type: "boolean", default: false },
+      cwd: { type: "string" },
+      "event-backend": { type: "string", default: "memory" },
+      "nats-url": { type: "string" },
+      "nats-stream": { type: "string", default: "duckflux-events" },
+      "redis-addr": { type: "string", default: "localhost:6379" },
+      "redis-db": { type: "string", default: "0" },
+    },
+    allowPositionals: true,
+  });
+
+  const cmd = positionals[0] ?? "run";
+
+  if (cmd === "version") {
+    console.log(getVersion());
+  } else if (cmd === "run") {
+    const file = positionals[1];
+    const exitCode = await runCommand(file, values);
+    if (typeof exitCode === "number" && exitCode !== 0) process.exit(exitCode);
+  } else if (cmd === "lint") {
+    const file = positionals[1];
+    const exitCode = await lintCommand(file);
+    if (typeof exitCode === "number" && exitCode !== 0) process.exit(exitCode);
+  } else if (cmd === "validate") {
+    const file = positionals[1];
+    const exitCode = await validateCommand(file, values);
+    if (typeof exitCode === "number" && exitCode !== 0) process.exit(exitCode);
+  } else {
+    console.error("Unknown command:", cmd);
+    console.error("Available commands: run, lint, validate, version");
+    process.exit(1);
+  }
+}

package/src/run.ts

@@ -0,0 +1,164 @@
+#!/usr/bin/env bun
+import { readFile } from "node:fs/promises";
+import { runWorkflowFromFile } from "@duckflux/core/engine";
+import type { ExecuteOptions, EventHub } from "@duckflux/core/engine";
+
+type CLIValues = Record<string, unknown> | undefined;
+
+async function createHubFromFlags(values: CLIValues): Promise<EventHub | undefined> {
+  const backend = (values?.["event-backend"] as string) ?? "memory";
+
+  if (backend === "memory") {
+    const { MemoryHub } = await import("@duckflux/core/eventhub");
+    return new MemoryHub();
+  }
+
+  if (backend === "nats") {
+    const url = values?.["nats-url"] as string | undefined;
+    if (!url) {
+      console.error("Error: --nats-url is required when using the NATS backend");
+      throw new Error("missing --nats-url");
+    }
+    const stream = (values?.["nats-stream"] as string) ?? "duckflux-events";
+    try {
+      const { NatsHub } = await import("@duckflux/hub-nats");
+      return await NatsHub.create({ url, stream });
+    } catch (err: unknown) {
+      if (err instanceof Error && (err.message.includes("Cannot find module") || err.message.includes("Cannot find package"))) {
+        console.error("Error: install @duckflux/hub-nats to use the NATS backend");
+        throw new Error("@duckflux/hub-nats not installed");
+      }
+      throw err;
+    }
+  }
+
+  if (backend === "redis") {
+    const addr = (values?.["redis-addr"] as string) ?? "localhost:6379";
+    const db = Number((values?.["redis-db"] as string) ?? "0");
+    try {
+      const { RedisHub } = await import("@duckflux/hub-redis");
+      return await RedisHub.create({ addr, db });
+    } catch (err: unknown) {
+      if (err instanceof Error && (err.message.includes("Cannot find module") || err.message.includes("Cannot find package"))) {
+        console.error("Error: install @duckflux/hub-redis to use the Redis backend");
+        throw new Error("@duckflux/hub-redis not installed");
+      }
+      throw err;
+    }
+  }
+
+  console.error(`Error: unknown event backend "${backend}". Supported: memory, nats, redis`);
+  throw new Error(`unknown event backend: ${backend}`);
+}
+
+function parseInputFlags(arr: string[] | undefined): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (!arr) return out;
+  for (const item of arr) {
+    const idx = item.indexOf("=");
+    if (idx === -1) {
+      out[item] = true;
+    } else {
+      const k = item.slice(0, idx);
+      const v = item.slice(idx + 1);
+      try {
+        out[k] = JSON.parse(v);
+      } catch {
+        out[k] = v;
+      }
+    }
+  }
+  return out;
+}
+
+export default async function runCommand(filePath?: string, cliValues?: CLIValues): Promise<number> {
+  if (!filePath) {
+    console.error("Usage: duckflux run <workflow.yaml> [--input k=v] [--input-file file.json] [--cwd dir]");
+    return 1;
+  }
+
+  // Input precedence: --input > --input-file > stdin
+  let inputs: Record<string, unknown> = {};
+
+  // 1. Try stdin first (lowest priority)
+  try {
+    if (process.stdin && !process.stdin.isTTY) {
+      let stdin = "";
+      for await (const chunk of process.stdin) {
+        stdin += chunk;
+      }
+      stdin = stdin.trim();
+      if (stdin.length > 0) {
+        try {
+          const parsed = JSON.parse(stdin);
+          if (typeof parsed === "object" && parsed !== null) inputs = { ...inputs, ...parsed };
+        } catch {
+          // ignore non-json stdin
+        }
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  if (cliValues) {
+    // 2. --input-file (overrides stdin)
+    if (cliValues["input-file"]) {
+      try {
+        const content = await readFile(String(cliValues["input-file"]), "utf-8");
+        const parsed = JSON.parse(content);
+        if (typeof parsed === "object" && parsed !== null) inputs = { ...inputs, ...parsed };
+      } catch (err) {
+        console.error("Failed to read input file:", err);
+        return 1;
+      }
+    }
+
+    // 3. --input flags (highest priority)
+    if (cliValues.input) {
+      const parsed = Array.isArray(cliValues.input) ? cliValues.input : [cliValues.input];
+      inputs = { ...inputs, ...parseInputFlags(parsed as string[]) };
+    }
+  }
+
+  let hub: EventHub | undefined;
+  try {
+    hub = await createHubFromFlags(cliValues);
+  } catch {
+    return 1;
+  }
+
+  const options: ExecuteOptions = {
+    hub,
+    cwd: cliValues?.cwd as string | undefined,
+    verbose: cliValues?.verbose as boolean | undefined,
+    quiet: cliValues?.quiet as boolean | undefined,
+  };
+
+  try {
+    const res = await runWorkflowFromFile(filePath, inputs, options);
+
+    // Print resolved output, not full WorkflowResult
+    const output = res.output;
+    if (output === undefined || output === null) {
+      // No output
+    } else if (typeof output === "string") {
+      process.stdout.write(output);
+    } else {
+      console.log(JSON.stringify(output, null, 2));
+    }
+
+    return res.success ? 0 : 2;
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error("Error:", msg);
+    if (cliValues?.verbose && err instanceof Error && err.stack) {
+      console.error(err.stack);
+    }
+    return 1;
+  } finally {
+    await hub?.close();
+  }
+}
+
+export { createHubFromFlags, parseInputFlags };

package/src/validate.ts

@@ -0,0 +1,95 @@
+#!/usr/bin/env bun
+import { readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { parseInputFlags } from "./run";
+import { parseWorkflowFile, validateSchema, validateSemantic, validateInputs } from "@duckflux/core";
+
+type CLIValues = Record<string, any> | undefined;
+
+export default async function validateCommand(filePath?: string, cliValues?: CLIValues): Promise<number> {
+  if (!filePath) {
+    console.error("Usage: duckflux validate <workflow.yaml> [--input k=v] [--input-file file.json]");
+    return 1;
+  }
+
+  let inputs: Record<string, unknown> = {};
+
+  if (cliValues) {
+    if (cliValues.input) {
+      const parsed = Array.isArray(cliValues.input) ? cliValues.input : [cliValues.input];
+      inputs = { ...inputs, ...parseInputFlags(parsed) };
+    }
+    if (cliValues["input-file"]) {
+      try {
+        const content = await readFile(String(cliValues["input-file"]), "utf-8");
+        const parsed = JSON.parse(content);
+        if (typeof parsed === "object" && parsed !== null) inputs = { ...inputs, ...parsed };
+      } catch (err) {
+        console.error("Failed to read input file:", err);
+        return 1;
+      }
+    }
+  }
+
+  // Try stdin if piped and no inputs provided
+  try {
+    if (process.stdin && !process.stdin.isTTY && Object.keys(inputs).length === 0) {
+      let stdin = "";
+      for await (const chunk of process.stdin) {
+        stdin += chunk;
+      }
+      stdin = stdin.trim();
+      if (stdin.length > 0) {
+        try {
+          const parsed = JSON.parse(stdin);
+          if (typeof parsed === "object" && parsed !== null) inputs = { ...inputs, ...parsed };
+        } catch {
+          // ignore non-json stdin
+        }
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  try {
+    const workflow = await parseWorkflowFile(filePath);
+
+    const schemaRes = validateSchema(workflow);
+    if (!schemaRes.valid) {
+      console.error("Schema validation failed:");
+      for (const e of schemaRes.errors) {
+        console.error(`- ${e.path}: ${e.message}`);
+      }
+      return 1;
+    }
+
+    const basePath = dirname(filePath);
+    const semanticRes = await validateSemantic(workflow, basePath);
+    if (!semanticRes.valid) {
+      console.error("Semantic validation failed:");
+      for (const e of semanticRes.errors) {
+        console.error(`- ${e.path}: ${e.message}`);
+      }
+      return 1;
+    }
+
+    // Validate inputs against declared schema
+    const { result: inputsResult, resolved } = validateInputs(workflow.inputs as any, inputs);
+    if (!inputsResult.valid) {
+      console.error("Input validation failed:");
+      for (const e of inputsResult.errors) {
+        console.error(`- ${e.path}: ${e.message}`);
+      }
+      return 1;
+    }
+
+    console.log("valid");
+    return 0;
+  } catch (err: any) {
+    console.error("Error during validate:", err && err.message ? err.message : err);
+    return 1;
+  }
+}
+
+export { validateCommand };