Runner

Workflow discovery and step execution utilities used by the worker package.

Installation

bun install

Exports

// Step execution
executeStepInProcess(stepFile, stepId, dependencies, ctx, attemptNumber, backend, onLog?, options?): Promise<{ result, logs }>;

// Discovery
discoverWorkflows(dir?: string): Promise<WorkflowMetadata[]>;
discoverSteps(workflowDir: string): Promise<LoadedStep[]>;

// Versioning
calculateWorkflowHash(workflow): Promise<string>;
getGitInfo(dir): Promise<GitInfo | undefined>;

// Validation
getAllDependents(stepId, steps): string[];
validateWorkflowVersion(workflowSlug, runId, currentVersionId, backend, log): Promise<string>;

// Types
LoadedStep  // Step with resolved dependencies

Key Features

• Workflow discovery - Auto-discovers workflows from ./workflows/ directory
• Step discovery - Loads and wires step dependencies with full TypeScript inference
• Subprocess execution - Executes steps in isolated child processes
• Cycle detection - DFS validation prevents circular dependencies
• Version tracking - SHA-256 hashing for workflow version comparison

Workflow Structure

workflows/my-workflow/
├── workflow.json       # {"name": "My Workflow"}
├── input-schema.ts     # Optional: Zod schema
└── steps/
    ├── step-1/step.ts                    # Flat step
    ├── step-2/step.ts                    # Flat step
    └── data-processing/                  # Optional: Group directory
        └── extract/
            └── fetch-data/step.ts        # Nested step

Note

For workflow authoring APIs (defineStep, baseDefineStep, Skip, optional), see the @cascade-flow/workflow package.