@cascade-flow/runner 0.1.0

package/dist/step-executor.d.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env bun
+/**
+ * Step executor - runs a single step in isolation
+ *
+ * Receives via stdin:
+ * {
+ *   "stepPath": "/path/to/step.ts",
+ *   "dependencies": { "depName": <serialized-output> },
+ *   "ctx": { "runId": "...", ... }
+ * }
+ *
+ * Environment variables:
+ * - STEP_OUTPUT_FILE: If set, write step result to this file (enables stdout/stderr capture)
+ *
+ * When STEP_OUTPUT_FILE is set:
+ * - Outputs to file: Step result as JSON
+ * - Outputs to stdout: console.log/info output
+ * - Outputs to stderr: console.error/warn output
+ *
+ * When STEP_OUTPUT_FILE is NOT set (backward compatibility):
+ * - Outputs to stdout: Step result as JSON
+ * - Outputs to stderr: All console output (redirected)
+ */
+export {};
+//# sourceMappingURL=step-executor.d.ts.map

package/dist/step-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-executor.d.ts","sourceRoot":"","sources":["../src/step-executor.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;GAqBG"}

package/dist/subprocess-executor.d.ts

@@ -0,0 +1,26 @@
+import type { LogEntry } from "@cascade-flow/backend-interface";
+import type { StepOutput, RunnerContext } from "./types.ts";
+type SubprocessOptions = {
+    signal?: AbortSignal;
+};
+/**
+ * Execute a step in an isolated child process
+ *
+ * Spawns a subprocess using step-executor.ts, captures stdout/stderr,
+ * and reads the step output from a file.
+ *
+ * @param stepFile - Absolute path to the step.ts file
+ * @param stepId - Unique identifier of the step (directory name)
+ * @param dependencies - Resolved dependency outputs
+ * @param ctx - Runner context passed to step
+ * @param attemptNumber - Current attempt number (for retries)
+ * @param outputPath - Path where subprocess should write output JSON
+ * @param onLog - Optional callback for real-time log emission
+ * @returns Promise resolving to step result and collected logs
+ */
+export declare function executeStepInSubprocess(stepFile: string, stepId: string, dependencies: Record<string, unknown>, ctx: RunnerContext, attemptNumber: number, outputPath: string, onLog?: (log: LogEntry) => void | Promise<void>, options?: SubprocessOptions): Promise<{
+    result: StepOutput;
+    logs: LogEntry[];
+}>;
+export {};
+//# sourceMappingURL=subprocess-executor.d.ts.map

package/dist/subprocess-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocess-executor.d.ts","sourceRoot":"","sources":["../src/subprocess-executor.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAEhE,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAc5D,KAAK,iBAAiB,GAAG;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAiDF;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,GAAG,EAAE,aAAa,EAClB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAC/C,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,QAAQ,EAAE,CAAA;CAAE,CAAC,CA4JnD"}

package/dist/types.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Shared types for the workflow runner
+ */
+import { z } from "zod";
+/**
+ * JSON primitive types
+ */
+export type JSONPrimitive = string | number | boolean | null;
+/**
+ * JSON array - an array of JSON values
+ */
+export interface JSONArray extends Array<JSONValue> {
+}
+/**
+ * JSON object - an object with string keys and JSON values
+ */
+export interface JSONObject {
+    [key: string]: JSONValue;
+}
+/**
+ * JSON value - any valid JSON type
+ */
+export type JSONValue = JSONPrimitive | JSONArray | JSONObject;
+/**
+ * Step output must be JSON-serializable
+ */
+export type StepOutput = JSONValue;
+/**
+ * Base step definition with common properties
+ * Generic over dependencies type and function signature
+ */
+export type BaseStepDefinition<TDeps = any, TFn = any> = {
+    name?: string;
+    dependencies?: TDeps;
+    exportOutput?: boolean;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    timeoutMs?: number;
+    fn: TFn;
+};
+export type StepModuleExport = {
+    step: BaseStepDefinition<Record<string, any>, // other steps' `step` objects
+    (args: {
+        dependencies: Record<string, StepOutput>;
+        ctx: RunnerContext;
+    }) => Promise<StepOutput> | StepOutput>;
+};
+/**
+ * Loaded step representation after discovery
+ * - id: The step's unique identifier (always the directory name)
+ * - name: The step's display name (from step.name or falls back to directory name)
+ * - dir: Absolute path to the step directory
+ */
+export type LoadedStep = {
+    id: string;
+    name: string;
+    dir: string;
+    fn: StepModuleExport["step"]["fn"];
+    exportOutput?: boolean;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    timeoutMs?: number;
+    dependencies: Record<string, LoadedStep>;
+};
+/**
+ * Workflow configuration from workflow.json - Zod schema
+ */
+export declare const workflowConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Workflow configuration type inferred from Zod schema
+ */
+export type WorkflowConfig = z.infer<typeof workflowConfigSchema>;
+/**
+ * Step configuration validation schema
+ * Validates optional step properties during discovery
+ */
+export declare const stepConfigSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    dependencies: z.ZodOptional<z.ZodAny>;
+    exportOutput: z.ZodOptional<z.ZodBoolean>;
+    maxRetries: z.ZodOptional<z.ZodNumber>;
+    retryDelayMs: z.ZodOptional<z.ZodNumber>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    fn: z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>;
+}, z.core.$strict>;
+/**
+ * Local workflow metadata after discovery (filesystem-specific)
+ * Extends backend WorkflowMetadata with local filesystem paths for direct execution
+ */
+export type LocalWorkflowMetadata = {
+    slug: string;
+    name: string;
+    dir: string;
+    stepsDir: string;
+    inputSchema?: z.ZodSchema<any>;
+};
+export type RunnerContext = {
+    runId: string;
+    workflow: {
+        slug: string;
+        name: string;
+    };
+    input?: unknown;
+    log: (...args: any[]) => void;
+};
+export type InferStepOutput<T> = T extends {
+    fn: (...args: any[]) => infer R;
+} ? Awaited<R> : never;
+/**
+ * Unwrap an OptionalDependency to get the underlying step type
+ * @internal
+ */
+export type UnwrapOptional<T> = T extends import("@cascade-flow/workflow").OptionalDependency<infer U extends {
+    fn: (...args: any[]) => any;
+}> ? U : T;
+/**
+ * Infer the output type of a dependency, making it optional if wrapped with optional()
+ * - Regular dependency: returns the step's output type
+ * - Optional dependency: returns the step's output type | undefined
+ *
+ * Uses branded type check (__optional property) for unambiguous type narrowing
+ * @internal
+ */
+export type InferDependencyOutput<T> = '__optional' extends keyof T ? InferStepOutput<UnwrapOptional<T>> | undefined : InferStepOutput<T>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/validation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Step validation - detects circular dependencies and other graph issues
+ */
+import type { LoadedStep } from "./types.ts";
+/**
+ * Detects circular dependencies in the step dependency graph
+ * Uses depth-first search to find cycles
+ *
+ * @param steps - Array of loaded steps to validate
+ * @throws Error if a cycle is detected
+ */
+export declare function detectCycles(steps: LoadedStep[]): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI,CAgBtD"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@cascade-flow/runner",
+  "version": "0.1.0",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts --outdir dist --target node --sourcemap=external --external=@cascade-flow/* && tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "test:unit": "bun test tests/unit",
+    "test:integration": "bun test tests/integration",
+    "test:e2e": "bun test tests/e2e",
+    "test:coverage": "bun test --coverage"
+  },
+  "dependencies": {
+    "@cascade-flow/backend-filesystem": "0.1.0",
+    "@cascade-flow/backend-interface": "0.1.0",
+    "@cascade-flow/workflow": "0.1.0",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cascadeflow/cascadeflow.git",
+    "directory": "packages/runner"
+  },
+  "license": "MIT",
+  "description": "Core workflow execution engine for CascadeFlow with dependency-aware parallel task execution",
+  "keywords": [
+    "workflow",
+    "orchestrator",
+    "dag",
+    "execution",
+    "parallel",
+    "dependencies"
+  ]
+}