@drej/core 0.3.0 → 0.4.0

package/dist/ledger.d.ts

@@ -1,102 +0,0 @@
-/** 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. */
-    RunStarted = "run_started",
-    /** Emitted at the beginning of each step. */
-    StepStart = "step_start",
-    /** Emitted when a step finishes successfully. */
-    StepComplete = "step_complete",
-    /** Emitted when a step throws an unrecoverable error. */
-    StepFailed = "step_failed",
-    /** Emitted when a step's rollback handler completes during saga compensation. */
-    StepRolledBack = "step_rolled_back",
-    /** Emitted after all steps finish without error. */
-    WorkflowComplete = "workflow_complete",
-    /** Emitted after rollback completes following a step failure. */
-    WorkflowFailed = "workflow_failed",
-    /** Durable resumption point written after each successful step. */
-    Checkpoint = "checkpoint",
-    /** Streaming output chunk from `exec()` or `execCode()`. */
-    ExecEvent = "exec_event",
-    /** Emitted when a sandbox snapshot is captured mid-run. */
-    Snapshot = "snapshot"
-}
-/** A single event record written to the storage adapter during a workflow run. */
-export interface LedgerEntry {
-    /** Unix timestamp in milliseconds. */
-    ts: number;
-    workflowName: string;
-    runId: string;
-    /** Zero-based index of the step that produced this event. `-1` for run-level events. */
-    stepIndex: number;
-    /** Parallel branch index, when this step is inside a `parallel()` block. */
-    branch?: number;
-    event: LedgerEvent;
-    /** Event-specific data (step output, snapshot ID, exec text, etc.). */
-    payload?: unknown;
-    /** Error message when `event` is `StepFailed` or `WorkflowFailed`. */
-    error?: string;
-}
-/**
- * Persistence interface for workflow event storage.
- *
- * Implement this interface to plug in any storage backend. drej ships two
- * official implementations: `@drej/sqlite` (local dev, zero infra) and
- * `@drej/postgres` (production).
- *
- * @example
- * ```ts
- * import { SQLiteAdapter } from "@drej/sqlite";
- * const client = new DrejClient({ baseUrl, adapter: new SQLiteAdapter("./drej.db") });
- * await client.connect();
- * ```
- */
-export interface IStorageAdapter {
-    /** Run migrations / open connections. Must be called before first use. */
-    connect?(): Promise<void>;
-    /** Release connections and resources. Call on graceful shutdown. */
-    close?(): Promise<void>;
-    /** Persist a single ledger event. Called automatically during workflow execution. */
-    append(entry: LedgerEntry): Promise<void>;
-    /** Return all events for a specific run, in ascending timestamp order. */
-    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 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/logger.d.ts

@@ -1,23 +0,0 @@
-export declare enum LogLevel {
-    Debug = 0,
-    Info = 1,
-    Warn = 2,
-    Error = 3,
-    Silent = 4
-}
-export interface ILogger {
-    debug(msg: string, meta?: Record<string, unknown>): void;
-    info(msg: string, meta?: Record<string, unknown>): void;
-    warn(msg: string, meta?: Record<string, unknown>): void;
-    error(msg: string, meta?: Record<string, unknown>): void;
-}
-export declare class ConsoleLogger implements ILogger {
-    private readonly minLevel;
-    constructor(minLevel?: LogLevel);
-    private log;
-    debug(msg: string, meta?: Record<string, unknown>): void;
-    info(msg: string, meta?: Record<string, unknown>): void;
-    warn(msg: string, meta?: Record<string, unknown>): void;
-    error(msg: string, meta?: Record<string, unknown>): void;
-}
-export declare const noopLogger: ILogger;

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

@@ -1,19 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,35 +0,0 @@
-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

@@ -1,7 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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

@@ -1,178 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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 +0,0 @@
-import { type StepDef } from "./steps";
-export declare function validateWorkflow(name: string, steps: StepDef[]): void;

package/dist/workflow.d.ts

@@ -1,106 +0,0 @@
-import type { IStorageAdapter, LedgerEntry } from "./ledger";
-import type { ControlClient, ExecClient } from "@drej/opensandbox";
-import type { ILogger } from "./logger";
-export interface WorkflowRunContext {
-    readonly workflowName: string;
-    readonly runId: string;
-    readonly stepIndex: number;
-    readonly control: ControlClient;
-    readonly resolveExec: (sandboxId: string) => Promise<ExecClient>;
-    emit(entry: LedgerEntry): Promise<void>;
-}
-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>;
-}
-export interface WorkflowCheckpoint {
-    workflowName: string;
-    runId: string;
-    stepIndex: number;
-    completedSteps: Record<number, {
-        output: unknown;
-        completedAt: number;
-    }>;
-    timestamp: number;
-}
-export declare enum WorkflowStatus {
-    Idle = "idle",
-    Running = "running",
-    Completed = "completed",
-    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 {
-    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;
-    private readonly deps;
-    readonly name: string;
-    readonly runId: string;
-    private _status;
-    private readonly completedSteps;
-    private readonly log;
-    get status(): WorkflowStatus;
-    constructor(name: string, runId: string, steps: WorkflowStep[], deps: WorkflowDeps);
-    private callHook;
-    run(input: unknown, startFromStep?: number): Promise<unknown>;
-    rollback(toStep?: number): Promise<void>;
-    snapshot(): WorkflowCheckpoint;
-    static resumeFromLedger(workflowName: string, runId: string, steps: WorkflowStep[], deps: WorkflowDeps): Promise<{
-        workflow: Workflow;
-        nextStep: number;
-        lastOutput: unknown;
-    }>;
-    private makeContext;
-}