@cascade-flow/runner 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# Runner
+
+Core workflow execution engine for direct (non-queue) execution.
+
+## Installation
+
+```bash
+bun install
+```
+
+## Usage
+
+```typescript
+import { runAll, defineStep, baseDefineStep } from "runner";
+
+// Execute workflow
+const results = await runAll({
+  workflow: "my-workflow",
+  input: { userId: "123" },
+  only: ["step1", "step2"],  // Optional: run subset
+  resume: true,              // Optional: resume from previous run
+  runId: "previous-run-id",  // Optional: specific run to resume
+});
+```
+
+## Defining Steps
+
+### Basic Step
+
+```typescript
+// workflows/my-workflow/steps/my-step/step.ts
+import { defineStep } from "runner";
+import { step as dependency } from "../other-step/step.ts";
+
+export const step = defineStep({
+  dependencies: { dependency },
+  exportOutput: true,
+  fn: async ({ dependencies, ctx }) => {
+    return { result: dependencies.dependency.value * 2 };
+  }
+});
+```
+
+### Typed Workflow Input
+
+```typescript
+// workflows/my-workflow/input-schema.ts
+import { z } from "zod";
+export const inputSchema = z.object({
+  userId: z.string(),
+  count: z.number()
+});
+export type WorkflowInput = z.infer<typeof inputSchema>;
+
+// workflows/my-workflow/defineStep.ts
+import { baseDefineStep } from "runner";
+import type { WorkflowInput } from "./input-schema";
+export const defineStep = baseDefineStep<WorkflowInput>();
+
+// workflows/my-workflow/steps/my-step/step.ts
+import { defineStep } from "../../defineStep";
+
+export const step = defineStep({
+  fn: async ({ ctx }) => {
+    const userId = ctx.input.userId;  // Fully typed!
+    return { processed: true };
+  }
+});
+```
+
+## Workflow Structure
+
+```
+workflows/my-workflow/
+├── workflow.json       # {"name": "My Workflow"}
+├── input-schema.ts     # Optional: Zod schema
+├── defineStep.ts       # Optional: Typed helper
+└── steps/
+    ├── step-1/step.ts
+    └── step-2/step.ts
+```
+
+## Key Features
+
+- **Promise caching** - Automatic parallelization via cached promises
+- **Type-safe dependencies** - Import step objects for full TypeScript inference
+- **Cycle detection** - DFS validation prevents circular dependencies
+- **Resume capability** - Continue from previous runs
+- **Pluggable backend** - Abstract persistence layer
+
+## Exports
+
+```typescript
+// Main execution
+runAll(options: RunAllOptions): Promise<WorkflowOutput>;
+
+// Step helpers
+defineStep(config: StepConfig): StepDefinition;
+baseDefineStep<TInput>(): typeof defineStep;
+
+// Discovery
+discoverWorkflows(dir?: string): Promise<WorkflowMetadata[]>;
+discoverSteps(workflowDir: string): Promise<LoadedStep[]>;
+```

package/dist/discovery.d.ts

@@ -0,0 +1,25 @@
+import { type LoadedStep, type WorkflowConfig, type LocalWorkflowMetadata } from "./types";
+/**
+ * Loads and validates a workflow.json configuration file using Zod
+ *
+ * @param workflowDir - Path to the workflow directory
+ * @returns Parsed and validated workflow configuration
+ * @throws Error if workflow.json is missing or invalid
+ */
+export declare function loadWorkflowConfig(workflowDir: string): Promise<WorkflowConfig>;
+/**
+ * Discovers all workflows in the workflows directory
+ *
+ * @param workflowsRoot - Root directory containing workflow subdirectories (defaults to "./workflows")
+ * @returns Array of local workflow metadata for all discovered workflows
+ * @throws Error if workflows directory doesn't exist
+ */
+export declare function discoverWorkflows(workflowsRoot?: string): Promise<LocalWorkflowMetadata[]>;
+/**
+ * Discovers and loads all steps from a directory
+ *
+ * @param root - Root directory containing step subdirectories (defaults to "./steps")
+ * @returns Array of loaded steps with wired dependencies
+ */
+export declare function discoverSteps(root?: string): Promise<LoadedStep[]>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAMA,OAAO,EAA0C,KAAK,UAAU,EAAyB,KAAK,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAG1J;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,cAAc,CAAC,CA0BzB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,aAAa,SAA4B,GACxC,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAyElC;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,IAAI,SAAwB,GAC3B,OAAO,CAAC,UAAU,EAAE,CAAC,CA2FvB"}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import type { Backend, LogEntry } from "@cascade-flow/backend-interface";
+import type { StepOutput, LoadedStep, RunnerContext } from "./types";
+export type { LoadedStep };
+/**
+ * Execute a step in an isolated child process
+ *
+ * Wrapper around executeStepInSubprocess that generates the output path.
+ */
+export declare function executeStepInProcess(stepFile: string, stepId: string, dependencies: Record<string, unknown>, ctx: RunnerContext, attemptNumber: number, backend: Backend, onLog?: (log: LogEntry) => void | Promise<void>, options?: {
+    signal?: AbortSignal;
+}): Promise<{
+    result: StepOutput;
+    logs: LogEntry[];
+}>;
+export declare function runAll(options: {
+    workflow: string;
+    only?: string[];
+    ctx?: Partial<RunnerContext>;
+    resume?: boolean;
+    runId?: string;
+    backend: Backend;
+    input?: unknown;
+}): Promise<Record<string, StepOutput>>;
+export { discoverWorkflows, discoverSteps } from "./discovery";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAa,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAMpF,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EACV,aAAa,EACd,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,UAAU,EAAE,CAAC;AAE3B;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,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,OAAO,EAAE,OAAO,EAChB,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAC/C,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GACjC,OAAO,CAAC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,QAAQ,EAAE,CAAA;CAAE,CAAC,CAoBnD;AAED,wBAAsB,MAAM,CAAC,OAAO,EAAE;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CA4ZtC;AAGD,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}