@magic-marker/nurt 0.1.0

package/dist/flow-DqIejS_0.d.ts

@@ -0,0 +1,306 @@
+declare class History {
+    private readonly store;
+    set(key: string, value: unknown): void;
+    get<T>(key: string): T | undefined;
+    has(key: string): boolean;
+    snapshot(): ReadonlyMap<string, unknown>;
+}
+
+type StepStatus = "pending" | "running" | "success" | "error" | "skipped";
+type RunStatus = "idle" | "running" | "success" | "error";
+type StepResult<T> = {
+    status: "success";
+    value: T;
+} | {
+    error: string;
+    status: "error";
+} | {
+    status: "skipped";
+};
+interface RunHandle {
+    addGroupMember(groupName: string, member: GroupMember): void;
+    provide(path: string, value: unknown): void;
+    sealGroup(groupName: string): void;
+    spawnGroup(groupName: string, members: readonly GroupMember[]): void;
+}
+interface StepContext {
+    readonly history: History;
+    provided<T>(): T;
+    readonly run: RunHandle;
+    readonly runId: string;
+    readonly signal: AbortSignal;
+}
+interface Executable<TInput, TOutput> {
+    execute(input: TInput, ctx: StepContext): Promise<TOutput>;
+}
+type StepHandler<TInput, TOutput> = ((input: TInput, ctx: StepContext) => Promise<TOutput>) | Executable<TInput, TOutput>;
+interface StepOptions<TInput, TOutput> {
+    allowFailures?: boolean;
+    execute: StepHandler<TInput, TOutput>;
+    terminal?: boolean;
+    transform?: (parentOutputs: unknown) => TInput;
+}
+interface StepDefinition {
+    readonly allowFailures: boolean;
+    readonly handler: StepHandler<unknown, unknown>;
+    readonly name: string;
+    readonly parentNames: readonly string[];
+    readonly terminal: boolean;
+    readonly transform?: (parentOutputs: unknown) => unknown;
+}
+interface GroupDefinition {
+    readonly dependsOn: readonly string[];
+    readonly name: string;
+}
+interface StepRecord {
+    completedAt?: number;
+    durationMs?: number;
+    error?: string;
+    readonly name: string;
+    output?: unknown;
+    readonly parentNames: readonly string[];
+    startedAt?: number;
+    status: StepStatus;
+}
+interface FlowRunResult {
+    readonly completedAt: number;
+    readonly history: ReadonlyMap<string, unknown>;
+    readonly runId: string;
+    readonly startedAt: number;
+    readonly status: RunStatus;
+    readonly steps: readonly StepRecord[];
+}
+interface FlowHooks {
+    onChange?: () => void;
+    onRunComplete?: (result: FlowRunResult) => void;
+    onStepAdded?: (step: StepRecord) => void;
+    onStepComplete?: (step: StepRecord) => void;
+    onStepError?: (step: StepRecord) => void;
+    onStepStart?: (step: StepRecord) => void;
+}
+interface RunOptions {
+    failFast?: boolean;
+    hooks?: FlowHooks;
+    injectedSteps?: Map<string, unknown>;
+}
+declare const GROUP_REF_BRAND: unique symbol;
+interface GroupRef<K extends string> {
+    readonly [GROUP_REF_BRAND]: true;
+    readonly groupName: K;
+}
+declare function group<K extends string>(name: K): GroupRef<K>;
+declare function isGroupRef(value: unknown): value is GroupRef<string>;
+type ParentOutputs<TRegistry extends Record<string, unknown>, TParents extends readonly (keyof TRegistry & string)[]> = {
+    [K in TParents[number]]: TRegistry[K];
+};
+/**
+ * Resolves a mixed dependency array (step names + group refs) to their types.
+ */
+type ResolveInput<TRegistry extends Record<string, unknown>, TDeps extends readonly unknown[]> = {
+    [K in TDeps[number] as K extends string ? K : K extends GroupRef<infer G> ? G : never]: K extends string ? TRegistry[K] : K extends GroupRef<infer G> ? TRegistry[G] : never;
+};
+interface SingleMember<TInput, TOutput> {
+    readonly execute: StepHandler<TInput, TOutput>;
+    readonly name: string;
+}
+interface SubgraphMember {
+    readonly externalDeps?: Record<string, string>;
+    readonly flow: Flow;
+    readonly name: string;
+}
+type GroupMember = SingleMember<unknown, unknown> | SubgraphMember;
+declare function isSubgraphMember(member: GroupMember): member is SubgraphMember;
+declare function isExecutable(value: unknown): value is Executable<unknown, unknown>;
+declare function invokeHandler<TInput, TOutput>(handler: StepHandler<TInput, TOutput>, input: TInput, ctx: StepContext): Promise<TOutput>;
+
+interface GroupRuntime {
+    readonly dependsOn: readonly string[];
+    readonly members: GroupMemberRuntime[];
+    readonly name: string;
+    sealed: boolean;
+}
+interface GroupMemberRuntime {
+    childRun?: FlowRun;
+    completedAt?: number;
+    error?: string;
+    readonly member: GroupMember;
+    readonly name: string;
+    output?: unknown;
+    startedAt?: number;
+    status: "pending" | "running" | "success" | "error";
+}
+
+interface FlowSnapshot {
+    flow: {
+        groups: FlowSnapshotGroup[];
+        name: string;
+        steps: FlowSnapshotStep[];
+    };
+    run: {
+        completedAt?: number;
+        runId: string;
+        startedAt: number;
+        status: RunStatus;
+    };
+}
+interface FlowSnapshotStep {
+    allowFailures: boolean;
+    completedAt?: number;
+    durationMs?: number;
+    error?: string;
+    name: string;
+    output?: unknown;
+    parentNames: string[];
+    startedAt?: number;
+    status: StepStatus;
+    terminal: boolean;
+}
+interface FlowSnapshotGroup {
+    dependsOn: string[];
+    members: FlowSnapshotGroupMember[];
+    name: string;
+    sealed: boolean;
+}
+interface FlowSnapshotGroupMember {
+    completedAt?: number;
+    durationMs?: number;
+    error?: string;
+    externalDeps?: Record<string, string>;
+    name: string;
+    output?: unknown;
+    startedAt?: number;
+    status: "pending" | "running" | "success" | "error";
+    subgraph?: FlowSnapshot;
+    type: "single" | "subgraph";
+}
+interface SnapshotInput {
+    flow: {
+        groups: ReadonlyArray<{
+            dependsOn: readonly string[];
+            name: string;
+        }>;
+        name: string;
+        steps: ReadonlyArray<{
+            allowFailures: boolean;
+            name: string;
+            parentNames: readonly string[];
+            terminal: boolean;
+        }>;
+    };
+    groupRuntimes: ReadonlyMap<string, GroupRuntime>;
+    run: {
+        completedAt?: number;
+        runId: string;
+        startedAt: number;
+        status: RunStatus;
+    };
+    stepRecords: ReadonlyMap<string, {
+        completedAt?: number;
+        durationMs?: number;
+        error?: string;
+        name: string;
+        output?: unknown;
+        parentNames: readonly string[];
+        startedAt?: number;
+        status: StepStatus;
+    }>;
+}
+declare function createSnapshot(input: SnapshotInput): FlowSnapshot;
+
+/**
+ * Runtime execution engine for a single flow run.
+ * Uses wave-based scheduling: collect ready steps, launch concurrently,
+ * await all, find newly ready steps, repeat.
+ */
+declare class FlowRun<TRegistry extends Record<string, unknown> = Record<string, unknown>> {
+    readonly runId: string;
+    private readonly flow;
+    private readonly hooks;
+    private readonly failFast;
+    private readonly abortController;
+    private readonly history;
+    private readonly stepDefs;
+    private readonly stepRecords;
+    private readonly stepOutputs;
+    private readonly groupRuntimes;
+    private readonly providedSlots;
+    private readonly providedData;
+    private status;
+    private startedAt;
+    private resolveResult;
+    readonly result: Promise<FlowRunResult>;
+    private loopRunning;
+    private readonly pendingGroupStarts;
+    private dynamicStepsAdded;
+    constructor(flow: Flow<TRegistry>, options?: RunOptions);
+    /**
+     * Read-only snapshot of current step records.
+     */
+    get steps(): readonly StepRecord[];
+    /**
+     * JSON-serializable snapshot of the current flow + run state.
+     */
+    snapshot(): FlowSnapshot;
+    /**
+     * Abort the run — signals all in-progress steps.
+     */
+    abort(): void;
+    /**
+     * Add a step dynamically during execution.
+     */
+    addStep(def: StepDefinition): void;
+    /**
+     * Spawn members into a group and auto-seal it.
+     */
+    spawnGroup(groupName: string, members: readonly GroupMember[]): void;
+    /**
+     * Add a single member to a group (without sealing).
+     */
+    addGroupMember(groupName: string, member: GroupMember): void;
+    /**
+     * Seal a group — no more members can be added.
+     */
+    sealGroup(groupName: string): void;
+    /**
+     * Provide a step implementation (slot fill) or external data.
+     */
+    provide(path: string, value: StepHandler<unknown, unknown> | Record<string, unknown> | unknown): void;
+    private createContext;
+    private startExecution;
+    private executionLoop;
+    /**
+     * Check for and launch any newly ready steps without waiting for the full wave.
+     * Called after each individual step completion.
+     */
+    private scheduleReadySteps;
+    private executeStep;
+    private buildInput;
+    private markSkippableSteps;
+    private getStatusMap;
+    private hasAnyError;
+    private areGroupDependenciesMet;
+    private startOrDeferGroup;
+    private flushPendingGroups;
+    private startGroupMembers;
+    private checkGroupCompletion;
+    private completeRun;
+    private fireHook;
+}
+
+/**
+ * Immutable DAG blueprint produced by FlowBuilder.build().
+ * Call .run() to create execution instances.
+ */
+declare class Flow<TRegistry extends Record<string, unknown> = Record<string, unknown>> {
+    readonly name: string;
+    readonly steps: readonly StepDefinition[];
+    readonly groups: readonly GroupDefinition[];
+    constructor(name: string, steps: StepDefinition[], groups: GroupDefinition[]);
+    /**
+     * Creates a new FlowRun instance.
+     * Multiple runs can execute concurrently from the same Flow.
+     */
+    run(options?: RunOptions): FlowRun<TRegistry>;
+}
+
+export { isGroupRef as A, isSubgraphMember as B, type Executable as E, Flow as F, type GroupDefinition as G, History as H, type ParentOutputs as P, type ResolveInput as R, type StepDefinition as S, type StepHandler as a, type StepOptions as b, type GroupRef as c, type SubgraphMember as d, type StepStatus as e, type FlowHooks as f, FlowRun as g, type FlowRunResult as h, type FlowSnapshot as i, type FlowSnapshotGroup as j, type FlowSnapshotGroupMember as k, type FlowSnapshotStep as l, type GroupMember as m, type GroupMemberRuntime as n, type GroupRuntime as o, type RunHandle as p, type RunOptions as q, type RunStatus as r, type SingleMember as s, type StepContext as t, type StepRecord as u, type StepResult as v, createSnapshot as w, group as x, invokeHandler as y, isExecutable as z };

package/dist/index.d.ts

@@ -0,0 +1,136 @@
+import { S as StepDefinition, G as GroupDefinition, a as StepHandler, b as StepOptions, c as GroupRef, F as Flow, d as SubgraphMember, e as StepStatus } from './flow-DqIejS_0.js';
+export { E as Executable, f as FlowHooks, g as FlowRun, h as FlowRunResult, i as FlowSnapshot, j as FlowSnapshotGroup, k as FlowSnapshotGroupMember, l as FlowSnapshotStep, m as GroupMember, n as GroupMemberRuntime, o as GroupRuntime, H as History, P as ParentOutputs, R as ResolveInput, p as RunHandle, q as RunOptions, r as RunStatus, s as SingleMember, t as StepContext, u as StepRecord, v as StepResult, w as createSnapshot, x as group, y as invokeHandler, z as isExecutable, A as isGroupRef, B as isSubgraphMember } from './flow-DqIejS_0.js';
+
+/**
+ * Chainable builder for constructing type-safe flow graphs.
+ *
+ * Each `.step()` call returns a new FlowBuilder with an expanded registry.
+ * Positional arguments allow TypeScript to infer literal string types
+ * without needing `as const`.
+ */
+declare class FlowBuilder<TRegistry extends Record<string, unknown> = {}> {
+    private readonly flowName;
+    private readonly steps;
+    private readonly groups;
+    private readonly knownNames;
+    constructor(flowName: string, steps?: StepDefinition[], groups?: GroupDefinition[], knownNames?: Set<string>);
+    /**
+     * Root step — no parents.
+     * .step("name", executeFn)
+     * .step("name", executableInstance)
+     */
+    step<TName extends string, TOutput>(name: TName, handler: StepHandler<Record<string, unknown>, TOutput>): FlowBuilder<TRegistry & Record<TName, TOutput>>;
+    /**
+     * Step with parents — input auto-derived from parent outputs.
+     * .step("name", ["parent1", "parent2"], executeFn)
+     */
+    step<TName extends string, TParents extends readonly (keyof TRegistry & string)[], TOutput>(name: TName, parents: [...TParents], handler: StepHandler<{
+        [K in TParents[number]]: TRegistry[K];
+    }, TOutput>): FlowBuilder<TRegistry & Record<TName, TOutput>>;
+    /**
+     * Step with parents + options object.
+     * .step("name", ["parent1"], { execute, transform?, allowFailures?, terminal? })
+     */
+    step<TName extends string, TParents extends readonly (keyof TRegistry & string)[], TOutput>(name: TName, parents: [...TParents], options: StepOptions<{
+        [K in TParents[number]]: TRegistry[K];
+    }, TOutput>): FlowBuilder<TRegistry & Record<TName, TOutput>>;
+    /**
+     * Step with group ref dependencies.
+     * .step("name", [group("reviews")], executeFn)
+     */
+    step<TName extends string, TDeps extends readonly unknown[], TOutput>(name: TName, deps: [...TDeps], handler: StepHandler<{
+        [K in TDeps[number] as K extends string ? K : K extends GroupRef<infer G> ? G : never]: K extends string ? TRegistry[K & keyof TRegistry] : K extends GroupRef<infer G> ? TRegistry[G & keyof TRegistry] : never;
+    }, TOutput> | StepOptions<{
+        [K in TDeps[number] as K extends string ? K : K extends GroupRef<infer G> ? G : never]: K extends string ? TRegistry[K & keyof TRegistry] : K extends GroupRef<infer G> ? TRegistry[G & keyof TRegistry] : never;
+    }, TOutput>): FlowBuilder<TRegistry & Record<TName, TOutput>>;
+    /**
+     * Declare a typed group for dynamic fan-in.
+     * .group<TOut>("reviews", { dependsOn: ["arbiter"] })
+     */
+    group<TOut, TName extends string = string>(name: TName, options?: {
+        dependsOn?: (keyof TRegistry & string)[];
+    }): FlowBuilder<TRegistry & Record<TName, TOut[]>>;
+    /**
+     * Validates the DAG and returns an immutable Flow.
+     */
+    build(): Flow<TRegistry>;
+}
+/**
+ * Entry point: creates a new FlowBuilder.
+ */
+declare function flow(name: string): FlowBuilder;
+
+interface PipelineStepDef {
+    execute?: StepHandler<unknown, unknown>;
+    name: string;
+}
+/**
+ * Convenience builder that creates a SubgraphMember with a linear DAG.
+ * Each step depends on the previous one, forming a sequential pipeline.
+ *
+ * ```typescript
+ * pipeline("tone-analysis", [
+ *   { name: "detect", execute: detectFn },
+ *   { name: "classify", execute: classifyFn },
+ *   { name: "score", execute: scoreFn },
+ * ])
+ * ```
+ *
+ * is equivalent to building a flow:
+ *   detect → classify → score (terminal)
+ */
+declare function pipeline(name: string, steps: PipelineStepDef[]): SubgraphMember;
+
+declare class CycleDetectedError extends Error {
+    constructor(cycle: string[]);
+}
+declare class DuplicateStepError extends Error {
+    constructor(name: string);
+}
+declare class UnknownParentError extends Error {
+    constructor(stepName: string, parentName: string);
+}
+declare class UnsealedGroupError extends Error {
+    constructor(groupName: string);
+}
+declare class UnfilledSlotError extends Error {
+    constructor(slotPath: string);
+}
+declare class StepExecutionError extends Error {
+    readonly stepName: string;
+    readonly cause: unknown;
+    constructor(stepName: string, cause: unknown);
+}
+
+interface GraphNode {
+    readonly name: string;
+    readonly parentNames: readonly string[];
+}
+/**
+ * Validates that the graph has no cycles using Kahn's algorithm.
+ * Throws CycleDetectedError if a cycle is found.
+ */
+declare function validateAcyclic(nodes: readonly GraphNode[]): void;
+/**
+ * Returns a valid topological ordering of the nodes.
+ * Assumes the graph is acyclic (call validateAcyclic first).
+ */
+declare function topologicalSort(nodes: readonly GraphNode[]): string[];
+/**
+ * Returns names of steps that are ready to execute:
+ * all parents have completed with "success" status.
+ */
+declare function getReadySteps(steps: readonly GraphNode[], statuses: ReadonlyMap<string, StepStatus>): string[];
+/**
+ * Returns names of steps that should be skipped because
+ * at least one parent has "error" or "skipped" status
+ * and the step does NOT have allowFailures set.
+ */
+declare function getSkippableSteps(steps: readonly StepDefinition[], statuses: ReadonlyMap<string, StepStatus>): string[];
+/**
+ * Returns names of steps with allowFailures that are ready to execute:
+ * all parents have completed (success, error, or skipped).
+ */
+declare function getReadyWithFailures(steps: readonly StepDefinition[], statuses: ReadonlyMap<string, StepStatus>): string[];
+
+export { CycleDetectedError, DuplicateStepError, Flow, FlowBuilder, GroupRef, type PipelineStepDef, StepDefinition, StepExecutionError, StepHandler, StepOptions, StepStatus, SubgraphMember, UnfilledSlotError, UnknownParentError, UnsealedGroupError, flow, getReadySteps, getReadyWithFailures, getSkippableSteps, pipeline, topologicalSort, validateAcyclic };