@drej/core 0.2.0 → 0.3.0

package/dist/errors.d.ts

@@ -29,3 +29,12 @@ export declare class CommandError extends WorkflowError {
     readonly sandboxId: string;
     constructor(exitCode: number, command: string, sandboxId: string);
 }
+/**
+ * Thrown when a step exceeds its `timeoutMs` limit (either set per-step or
+ * via `RunOptions.stepTimeoutMs`). The workflow will roll back after this error.
+ */
+export declare class StepTimeoutError extends WorkflowError {
+    readonly stepId: string;
+    readonly timeoutMs: number;
+    constructor(stepId: string, timeoutMs: number);
+}

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-export { LedgerEvent } from "./ledger";
-export type { LedgerEntry, IStorageAdapter } from "./ledger";
+export { LedgerEvent, RunStatus } from "./ledger";
+export type { LedgerEntry, IStorageAdapter, RunDetails, ListRunsOptions } from "./ledger";
 export { LogLevel, ConsoleLogger, noopLogger } from "./logger";
 export type { ILogger } from "./logger";
-export { Workflow, WorkflowStatus } from "./workflow";
-export type { WorkflowRunContext, WorkflowStep, WorkflowCheckpoint, WorkflowDeps, WorkflowHooks, } from "./workflow";
-export { buildStep, resolveExecClient, shouldSnapshot, waitForSnapshot } from "./steps";
+export { Workflow, WorkflowStatus, mergeHooks } from "./workflow";
+export type { WorkflowRunContext, WorkflowStep, WorkflowCheckpoint, WorkflowDeps, WorkflowHooks, WorkflowHookInfo, StepHookInfo, StepCompleteHookInfo, StepFailedHookInfo, WorkflowCompleteHookInfo, WorkflowFailedHookInfo, } from "./workflow";
+export { buildStep, resolveExecClient, shouldSnapshot, waitForSnapshot, StepType, Encoding, Backoff } from "./steps";
 export type { StepDef, Predicate, WorkflowState, SnapshotConfig } from "./steps";
 export { validateWorkflow } from "./validate";
-export { WorkflowError, SandboxError, ExecConnectionError, CommandError } from "./errors";
+export { WorkflowError, SandboxError, ExecConnectionError, CommandError, StepTimeoutError } from "./errors";

package/dist/ledger.d.ts

@@ -1,3 +1,32 @@
+/** Status of a workflow run derived from its ledger events. */
+export declare enum RunStatus {
+    Running = "running",
+    Completed = "completed",
+    Failed = "failed",
+    Cancelled = "cancelled"
+}
+/** Derived metadata for a workflow run, computed from its ledger events. */
+export interface RunDetails {
+    workflowName: string;
+    runId: string;
+    status: RunStatus;
+    /** Unix timestamp (ms) of the `run_started` event. */
+    startedAt: number;
+    /** Unix timestamp (ms) of the terminal event, if the run has ended. */
+    completedAt?: number;
+    /** Number of steps that completed successfully. */
+    stepCount: number;
+    /** Error message, present when status is `Failed`. */
+    error?: string;
+}
+/** Options for filtering run listings. */
+export interface ListRunsOptions {
+    status?: RunStatus;
+    /** Max number of results to return. */
+    limit?: number;
+    /** Return only runs that started before this Unix timestamp (ms). */
+    before?: number;
+}
 /** Events emitted during workflow execution and stored in the ledger. */
 export declare enum LedgerEvent {
     /** Emitted once when a workflow run starts, before any steps execute. */
@@ -62,6 +91,12 @@ export interface IStorageAdapter {
     readAll(workflowName: string, runId: string): Promise<LedgerEntry[]>;
     /** Return the most recent checkpoint entry for a run, or `null` if none exists. */
     lastCheckpoint(workflowName: string, runId: string): Promise<LedgerEntry | null>;
-    /** Return all run IDs recorded under a workflow name. */
-    listRuns(workflowName: string): Promise<string[]>;
+    /** Return details for all runs of a workflow, newest first. */
+    listRunDetails(workflowName: string, opts?: ListRunsOptions): Promise<RunDetails[]>;
+    /** Return details for runs across all workflows, newest first. */
+    listAllRunDetails(opts?: ListRunsOptions): Promise<RunDetails[]>;
+    /** Return details for a single run, or `null` if not found. */
+    getRunDetails(workflowName: string, runId: string): Promise<RunDetails | null>;
+    /** Delete all ledger events for a run. */
+    deleteRun(workflowName: string, runId: string): Promise<void>;
 }

package/dist/steps/control-flow.d.ts

@@ -0,0 +1,19 @@
+import type { WorkflowStep } from "../workflow";
+import { StepType, type StepDef } from "./types";
+type BuildStepFn = (def: StepDef) => WorkflowStep;
+export declare function buildRetryStep(def: Extract<StepDef, {
+    type: StepType.Retry;
+}>, buildStepFn: BuildStepFn): WorkflowStep;
+export declare function buildConditionalStep(def: Extract<StepDef, {
+    type: StepType.Conditional;
+}>, buildStepFn: BuildStepFn): WorkflowStep;
+export declare function buildLoopStep(def: Extract<StepDef, {
+    type: StepType.Loop;
+}>, buildStepFn: BuildStepFn): WorkflowStep;
+export declare function buildParallelStep(def: Extract<StepDef, {
+    type: StepType.Parallel;
+}>, buildStepFn: BuildStepFn): WorkflowStep;
+export declare function buildSequenceStep(def: Extract<StepDef, {
+    type: StepType.Sequence;
+}>, buildStepFn: BuildStepFn): WorkflowStep;
+export {};

package/dist/steps/exec.d.ts

@@ -0,0 +1,8 @@
+import type { WorkflowStep } from "../workflow";
+import { StepType, type StepDef } from "./types";
+export declare function buildExecCommandStep(def: Extract<StepDef, {
+    type: StepType.ExecCommand;
+}>): WorkflowStep;
+export declare function buildExecCodeStep(def: Extract<StepDef, {
+    type: StepType.ExecCode;
+}>): WorkflowStep;

package/dist/steps/file.d.ts

@@ -0,0 +1,35 @@
+import type { WorkflowStep } from "../workflow";
+import { StepType, type StepDef } from "./types";
+export declare function buildWriteFileStep(def: Extract<StepDef, {
+    type: StepType.WriteFile;
+}>): WorkflowStep;
+export declare function buildReadFileStep(def: Extract<StepDef, {
+    type: StepType.ReadFile;
+}>): WorkflowStep;
+export declare function buildDeleteFileStep(def: Extract<StepDef, {
+    type: StepType.DeleteFile;
+}>): WorkflowStep;
+export declare function buildMoveFileStep(def: Extract<StepDef, {
+    type: StepType.MoveFile;
+}>): WorkflowStep;
+export declare function buildListDirectoryStep(def: Extract<StepDef, {
+    type: StepType.ListDirectory;
+}>): WorkflowStep;
+export declare function buildSearchFilesStep(def: Extract<StepDef, {
+    type: StepType.SearchFiles;
+}>): WorkflowStep;
+export declare function buildCreateDirectoryStep(def: Extract<StepDef, {
+    type: StepType.CreateDirectory;
+}>): WorkflowStep;
+export declare function buildDeleteDirectoryStep(def: Extract<StepDef, {
+    type: StepType.DeleteDirectory;
+}>): WorkflowStep;
+export declare function buildSetPermissionsStep(def: Extract<StepDef, {
+    type: StepType.SetPermissions;
+}>): WorkflowStep;
+export declare function buildReplaceInFilesStep(def: Extract<StepDef, {
+    type: StepType.ReplaceInFiles;
+}>): WorkflowStep;
+export declare function buildGetFileInfoStep(def: Extract<StepDef, {
+    type: StepType.GetFileInfo;
+}>): WorkflowStep;

package/dist/steps/index.d.ts

@@ -0,0 +1,7 @@
+import type { WorkflowStep } from "../workflow";
+import { type StepDef } from "./types";
+export declare function buildStep(def: StepDef): WorkflowStep;
+export { StepType, Encoding, Backoff } from "./types";
+export type { StepDef, Predicate, WorkflowState, SnapshotConfig } from "./types";
+export { resolveExecClient } from "./sandbox";
+export { shouldSnapshot, waitForSnapshot } from "./snapshot";

package/dist/steps/sandbox.d.ts

@@ -0,0 +1,8 @@
+import { ControlClient, ExecClient } from "@drej/opensandbox";
+import type { WorkflowStep } from "../workflow";
+import { StepType, type StepDef } from "./types";
+export declare function resolveExecClient(control: ControlClient, sandboxId: string, retries?: number, delayMs?: number): Promise<ExecClient>;
+export declare function buildCreateSandboxStep(def: Extract<StepDef, {
+    type: StepType.CreateSandbox;
+}>): WorkflowStep;
+export declare function buildDeleteSandboxStep(): WorkflowStep;

package/dist/steps/snapshot.d.ts

@@ -0,0 +1,6 @@
+import type { ControlClient } from "@drej/opensandbox";
+import type { WorkflowStep } from "../workflow";
+import { type SnapshotConfig } from "./types";
+export declare function shouldSnapshot(config: SnapshotConfig, stepIndex: number): boolean;
+export declare function waitForSnapshot(control: ControlClient, snapshotId: string, timeoutMs?: number): Promise<void>;
+export declare function buildSnapshotStep(): WorkflowStep;

package/dist/steps/types.d.ts

@@ -0,0 +1,178 @@
+import { CodeLanguage } from "@drej/opensandbox";
+export type Predicate = {
+    op: "eq" | "neq";
+    field: string;
+    value: unknown;
+} | {
+    op: "gt" | "lt" | "gte" | "lte";
+    field: string;
+    value: number;
+} | {
+    op: "exists" | "not_exists";
+    field: string;
+} | {
+    op: "and" | "or";
+    predicates: Predicate[];
+};
+export declare enum StepType {
+    CreateSandbox = "create_sandbox",
+    ExecCode = "exec_code",
+    ExecCommand = "exec_command",
+    DeleteSandbox = "delete_sandbox",
+    WriteFile = "write_file",
+    ReadFile = "read_file",
+    DeleteFile = "delete_file",
+    MoveFile = "move_file",
+    ListDirectory = "list_directory",
+    SearchFiles = "search_files",
+    CreateDirectory = "create_directory",
+    DeleteDirectory = "delete_directory",
+    SetPermissions = "set_permissions",
+    ReplaceInFiles = "replace_in_files",
+    GetFileInfo = "get_file_info",
+    Snapshot = "snapshot",
+    Retry = "retry",
+    Conditional = "conditional",
+    Loop = "loop",
+    Parallel = "parallel",
+    Sequence = "sequence"
+}
+export declare enum Encoding {
+    UTF8 = "utf8",
+    Base64 = "base64"
+}
+export declare enum Backoff {
+    Fixed = "fixed",
+    Exponential = "exponential"
+}
+export type StepDef = {
+    type: StepType.CreateSandbox;
+    image?: {
+        uri: string;
+        auth?: {
+            username: string;
+            password: string;
+        };
+    };
+    snapshotId?: string;
+    timeout?: number;
+    entrypoint?: string[];
+    env?: Record<string, string>;
+    metadata?: Record<string, string>;
+    resourceLimits?: {
+        cpu?: string;
+        memory?: string;
+        gpu?: string;
+    };
+} | {
+    type: StepType.ExecCode;
+    code: string;
+    context?: {
+        id: string;
+        language: CodeLanguage;
+    };
+    timeoutMs?: number;
+} | {
+    type: StepType.ExecCommand;
+    command: string;
+    cwd?: string;
+    envs?: Record<string, string>;
+    capture?: string;
+    strict?: boolean;
+    timeoutMs?: number;
+} | {
+    type: StepType.DeleteSandbox;
+} | {
+    type: StepType.WriteFile;
+    path: string;
+    content: string;
+    encoding?: Encoding;
+    timeoutMs?: number;
+} | {
+    type: StepType.ReadFile;
+    path: string;
+    as: string;
+    encoding?: Encoding;
+    timeoutMs?: number;
+} | {
+    type: StepType.DeleteFile;
+    path: string;
+    timeoutMs?: number;
+} | {
+    type: StepType.MoveFile;
+    from: string;
+    to: string;
+    timeoutMs?: number;
+} | {
+    type: StepType.ListDirectory;
+    path: string;
+    as: string;
+    depth?: number;
+    timeoutMs?: number;
+} | {
+    type: StepType.SearchFiles;
+    pattern: string;
+    as: string;
+    dir?: string;
+    timeoutMs?: number;
+} | {
+    type: StepType.CreateDirectory;
+    path: string;
+    timeoutMs?: number;
+} | {
+    type: StepType.DeleteDirectory;
+    path: string;
+    timeoutMs?: number;
+} | {
+    type: StepType.SetPermissions;
+    path: string;
+    mode: string;
+    timeoutMs?: number;
+} | {
+    type: StepType.ReplaceInFiles;
+    replacements: Array<{
+        path: string;
+        old: string;
+        new: string;
+    }>;
+    timeoutMs?: number;
+} | {
+    type: StepType.GetFileInfo;
+    path: string;
+    as: string;
+    timeoutMs?: number;
+} | {
+    type: StepType.Snapshot;
+} | {
+    type: StepType.Retry;
+    step: StepDef;
+    maxAttempts: number;
+    delayMs?: number;
+    backoff?: Backoff;
+} | {
+    type: StepType.Conditional;
+    condition: Predicate;
+    then: StepDef[];
+    else?: StepDef[];
+} | {
+    type: StepType.Loop;
+    over?: string;
+    items?: unknown[];
+    as: string;
+    steps: StepDef[];
+    maxConcurrency?: number;
+} | {
+    type: StepType.Parallel;
+    steps: StepDef[];
+    maxConcurrency?: number;
+} | {
+    type: StepType.Sequence;
+    steps: StepDef[];
+};
+export type WorkflowState = Record<string, unknown> & {
+    sandboxId?: string;
+};
+export interface SnapshotConfig {
+    afterSteps?: number[];
+    everyNSteps?: number;
+}

package/dist/steps/utils.d.ts

@@ -0,0 +1,5 @@
+import type { Predicate, WorkflowState } from "./types";
+export declare function getPath(obj: unknown, path: string): unknown;
+export declare function interpolate(template: string, state: WorkflowState): string;
+export declare function evaluate(predicate: Predicate, state: unknown): boolean;
+export declare function runWithConcurrency<T>(tasks: Array<() => Promise<T>>, max: number): Promise<T[]>;

package/dist/validate.d.ts

@@ -1,2 +1,2 @@
-import type { StepDef } from "./steps";
+import { type StepDef } from "./steps";
 export declare function validateWorkflow(name: string, steps: StepDef[]): void;

package/dist/workflow.d.ts

@@ -11,6 +11,13 @@ export interface WorkflowRunContext {
 }
 export interface WorkflowStep {
     readonly id: string;
+    /**
+     * Maximum milliseconds this step may run. When exceeded, an `AbortSignal`
+     * fires on the step's execution context and `StepTimeoutError` is thrown.
+     * Set per-step in the builder (`exec("cmd", { timeoutMs: 5000 })`) or as a
+     * global default via `RunOptions.stepTimeoutMs`.
+     */
+    readonly timeoutMs?: number;
     run(input: unknown, ctx: WorkflowRunContext): Promise<unknown>;
     rollback?(output: unknown, ctx: WorkflowRunContext): Promise<void>;
 }
@@ -31,50 +38,50 @@ export declare enum WorkflowStatus {
     Failed = "failed",
     RolledBack = "rolled_back"
 }
+export interface WorkflowHookInfo {
+    workflowName: string;
+    runId: string;
+}
+export interface StepHookInfo extends WorkflowHookInfo {
+    stepIndex: number;
+    stepId: string;
+}
+export interface StepCompleteHookInfo extends StepHookInfo {
+    output: unknown;
+}
+export interface StepFailedHookInfo extends StepHookInfo {
+    error: Error;
+}
+export interface WorkflowCompleteHookInfo extends WorkflowHookInfo {
+    output: unknown;
+}
+export interface WorkflowFailedHookInfo extends WorkflowHookInfo {
+    error: Error;
+}
 export interface WorkflowHooks {
-    onStepStart?(info: {
-        workflowName: string;
-        runId: string;
-        stepIndex: number;
-        stepId: string;
-    }): void | Promise<void>;
-    onStepComplete?(info: {
-        workflowName: string;
-        runId: string;
-        stepIndex: number;
-        stepId: string;
-        output: unknown;
-    }): void | Promise<void>;
-    onStepFailed?(info: {
-        workflowName: string;
-        runId: string;
-        stepIndex: number;
-        stepId: string;
-        error: Error;
-    }): void | Promise<void>;
-    onStepRolledBack?(info: {
-        workflowName: string;
-        runId: string;
-        stepIndex: number;
-        stepId: string;
-    }): void | Promise<void>;
-    onWorkflowComplete?(info: {
-        workflowName: string;
-        runId: string;
-        output: unknown;
-    }): void | Promise<void>;
-    onWorkflowFailed?(info: {
-        workflowName: string;
-        runId: string;
-        error: Error;
-    }): void | Promise<void>;
+    onWorkflowStart?(info: WorkflowHookInfo): void | Promise<void>;
+    onStepStart?(info: StepHookInfo): void | Promise<void>;
+    onStepComplete?(info: StepCompleteHookInfo): void | Promise<void>;
+    onStepFailed?(info: StepFailedHookInfo): void | Promise<void>;
+    onStepRolledBack?(info: StepHookInfo): void | Promise<void>;
+    onWorkflowComplete?(info: WorkflowCompleteHookInfo): void | Promise<void>;
+    onWorkflowFailed?(info: WorkflowFailedHookInfo): void | Promise<void>;
 }
+export declare function mergeHooks(...hooks: (WorkflowHooks | undefined)[]): WorkflowHooks;
 export interface WorkflowDeps {
     control: ControlClient;
     resolveExec: (sandboxId: string) => Promise<ExecClient>;
     adapter: IStorageAdapter;
     logger?: ILogger;
     hooks?: WorkflowHooks;
+    /** Global per-step timeout in ms. Applied to any step that does not set its own `timeoutMs`. */
+    stepTimeoutMs?: number;
+    /**
+     * External abort signal. When fired, the current in-flight step is aborted
+     * via its per-step `AbortController` and `StepTimeoutError` (or the signal's
+     * reason) propagates out of `Workflow.run()`.
+     */
+    signal?: AbortSignal;
 }
 export declare class Workflow {
     private readonly steps;

package/package.json

@@ -1,20 +1,25 @@
 {
   "name": "@drej/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",
   "files": [
     "dist"
   ],
-  "publishConfig": { "access": "public" },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
-    "build:types": "tsc --project tsconfig.build.json"
+    "build:types": "tsc --project tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
     "@drej/opensandbox": "workspace:*"
   },
   "devDependencies": {
-    "bun-types": "latest",
-    "typescript": "latest"
+    "bun-types": "1.3.14",
+    "typescript": "6.0.3",
+    "vitest": "4.1.9"
   }
 }

package/dist/steps.d.ts

@@ -1,100 +0,0 @@
-import { ControlClient, ExecClient } from "@drej/opensandbox";
-import type { WorkflowStep } from "./workflow";
-export type Predicate = {
-    op: "eq" | "neq";
-    field: string;
-    value: unknown;
-} | {
-    op: "gt" | "lt" | "gte" | "lte";
-    field: string;
-    value: number;
-} | {
-    op: "exists" | "not_exists";
-    field: string;
-} | {
-    op: "and" | "or";
-    predicates: Predicate[];
-};
-export type StepDef = {
-    type: "create_sandbox";
-    image?: {
-        uri: string;
-        auth?: {
-            username: string;
-            password: string;
-        };
-    };
-    snapshotId?: string;
-    timeout?: number;
-    entrypoint?: string[];
-    env?: Record<string, string>;
-    metadata?: Record<string, string>;
-    resourceLimits?: {
-        cpu?: string;
-        memory?: string;
-        gpu?: string;
-    };
-} | {
-    type: "exec_code";
-    code: string;
-    context?: {
-        id: string;
-        language: string;
-    };
-} | {
-    type: "exec_command";
-    command: string;
-    cwd?: string;
-    envs?: Record<string, string>;
-    capture?: string;
-    strict?: boolean;
-} | {
-    type: "delete_sandbox";
-} | {
-    type: "write_file";
-    path: string;
-    content: string;
-    encoding?: "utf8" | "base64";
-} | {
-    type: "read_file";
-    path: string;
-    as: string;
-    encoding?: "utf8" | "base64";
-} | {
-    type: "snapshot";
-} | {
-    type: "retry";
-    step: StepDef;
-    maxAttempts: number;
-    delayMs?: number;
-    backoff?: "fixed" | "exponential";
-} | {
-    type: "conditional";
-    condition: Predicate;
-    then: StepDef[];
-    else?: StepDef[];
-} | {
-    type: "loop";
-    over?: string;
-    items?: unknown[];
-    as: string;
-    steps: StepDef[];
-    concurrently?: boolean;
-} | {
-    type: "parallel";
-    steps: StepDef[];
-} | {
-    type: "sequence";
-    steps: StepDef[];
-};
-export type WorkflowState = Record<string, unknown> & {
-    sandboxId?: string;
-};
-export interface SnapshotConfig {
-    afterSteps?: number[];
-    everyNSteps?: number;
-}
-export declare function resolveExecClient(control: ControlClient, sandboxId: string, retries?: number, delayMs?: number): Promise<ExecClient>;
-export declare function shouldSnapshot(config: SnapshotConfig, stepIndex: number): boolean;
-export declare function waitForSnapshot(control: ControlClient, snapshotId: string, timeoutMs?: number): Promise<void>;
-export declare function buildStep(def: StepDef): WorkflowStep;