drej 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # drej
 
+## 0.4.0
+
+### Minor Changes
+
+- d0486df: Add fluent workflow builder API to TypeScript SDK.
+
+  `workflow(id)` returns a `WorkflowBuilder` with chainable `.sandbox()` and `.parallel()` methods. Inside a sandbox scope, `SandboxStepBuilder` provides `.exec()`, `.writeFile()`, `.retry()`, `.forEach()`, `.when()`, and `.parallel()`. The `forEach` callback receives `(s, item)` where `item` serialises to `{{name}}` in template literals, enabling natural JS interpolation. Top-level `.parallel()` supports multiple concurrent sandbox sessions via `WorkflowParallelBuilder`. `DrejClient.run(w)` accepts a built workflow directly. The `sandbox()` helper defaults the entrypoint to `["tail", "-f", "/dev/null"]`.
+
+  Adds a server-side `sequence` step type that runs child steps sequentially, used internally by the builder to represent multi-step parallel branches.
+
+- e1f9bb8: Add `snapshotConfig` option to `client.run()` and a `replayFromSnapshot()` method.
+
+  Pass `snapshotConfig: { afterSteps?: number[]; everyNSteps?: number }` to capture sandbox snapshots at specific points in a workflow. Call `client.replayFromSnapshot(name, runId, workflow)` to start a new run booted from the latest captured snapshot — skipping any setup steps already baked into the image.
+
+- 9a30c31: Introduce per-run ledger with workflow name / run ID separation.
+
+  Each workflow execution now has a stable **workflow name** (user-defined) and an auto-generated **run ID** (UUID). Ledger files are stored at `ledgers/<name>/<runId>.ndjson` so all runs of a workflow are grouped together.
+
+  API changes:
+
+  - `POST /v1/workflows/:name/runs` — starts a run; first SSE event is `run_started` carrying the run ID
+  - `POST /v1/workflows/:name/runs/:runId/resume` — resumes a specific run
+  - `GET /v1/workflows/:name/runs` — lists all run IDs for a workflow
+  - `GET /v1/workflows/:name/runs/:runId/ledger` — fetches ledger for a specific run
+
+  SDK changes:
+
+  - `client.run(w)` is now `async` and returns `Promise<WorkflowRun>`; `run.id` gives the run ID, `run.name` the workflow name, and it is async-iterable for events
+  - `client.resumeRun(name, runId, w)` resumes a run
+  - `client.listWorkflowRuns(name)` lists runs
+  - `client.getWorkflowLedger(name, runId)` fetches the ledger
+  - `WorkflowEvent` fields renamed: `workflowId` → `workflowName` + `runId`
+
+### Patch Changes
+
+- b3c0bc9: feat: lifecycle hooks, append-only WAL, and clean adapter layer
+
+  - Add `WorkflowHooks` interface with `onStepStart`, `onStepComplete`, `onStepFailed`, `onStepRolledBack`, `onWorkflowComplete`, `onWorkflowFailed` callbacks on `WorkflowDeps`
+  - Fix `NdjsonLedger.append` to use `appendFileSync` (O_APPEND) instead of read-then-overwrite (O_TRUNC), preventing ledger truncation on crash
+  - Make `NdjsonLedger.readAll` resilient to malformed lines from partial writes
+  - Add `OpenSandboxControlAdapter` and `OpenSandboxExecFactory` to `@drej/opensandbox` — concrete implementations of `ISandboxControl` and `IExecClientFactory` that encapsulate execd readiness polling
+  - Remove `as unknown as` double-cast from `apps/api`; adapter wiring is now explicit and type-safe
+
 ## 0.3.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drej",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "scripts": {

package/src/client.ts

@@ -185,6 +185,7 @@ export interface DrejClientOptions {
 // ── Workflow types ─────────────────────────────────────────────────────────
 
 export type WorkflowEventKind =
+  | "run_started"
   | "step_start"
   | "step_complete"
   | "step_failed"
@@ -192,19 +193,44 @@ export type WorkflowEventKind =
   | "workflow_complete"
   | "workflow_failed"
   | "checkpoint"
-  | "exec_event";
+  | "exec_event"
+  | "snapshot";
+
+export interface SnapshotConfig {
+  /** Take a snapshot after these step indices (0-based). */
+  afterSteps?: number[];
+  /** Take a snapshot after every N steps. */
+  everyNSteps?: number;
+}
+
+export interface RunOptions {
+  snapshotConfig?: SnapshotConfig;
+}
 
 export interface WorkflowEvent {
   ts: number;
-  workflowId: string;
+  workflowName: string;
+  runId: string;
   stepIndex: number;
-  branch?: number; // set on events emitted from parallel branches
+  branch?: number;
   event: WorkflowEventKind;
   payload?: unknown;
   error?: string;
   result?: unknown;
 }
 
+export class WorkflowRun implements AsyncIterable<WorkflowEvent> {
+  constructor(
+    public readonly name: string,
+    public readonly id: string,
+    private readonly _events: AsyncGenerator<WorkflowEvent>,
+  ) {}
+
+  [Symbol.asyncIterator](): AsyncIterator<WorkflowEvent> {
+    return this._events;
+  }
+}
+
 export type Predicate =
   | { op: "eq" | "neq"; field: string; value: unknown }
   | { op: "gt" | "lt" | "gte" | "lte"; field: string; value: number }
@@ -229,7 +255,8 @@ export type StepDef =
   | { 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: "parallel"; steps: StepDef[] }
+  | { type: "sequence"; steps: StepDef[] };
 
 // ── SSE parsers ────────────────────────────────────────────────────────────
 
@@ -560,29 +587,98 @@ export class DrejClient {
 
   // ── Workflows ────────────────────────────────────────────────────────────
 
-  async *runWorkflow(id: string, steps: StepDef[]): AsyncGenerator<WorkflowEvent> {
-    const res = await fetch(`${this.baseUrl}/v1/workflows`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ id, steps }),
-    });
-    if (!res.ok) throw new DrejError("drej API error", res.status);
-    if (!res.body) return;
-    yield* parseWorkflowSSE(res.body);
+  async run(
+    w: { build(): { name: string; steps: StepDef[] } },
+    options?: RunOptions,
+  ): Promise<WorkflowRun> {
+    const { name, steps } = w.build();
+    return this._startRun(name, steps, options?.snapshotConfig);
+  }
+
+  /**
+   * Start a new run using a snapshot captured from a previous run.
+   *
+   * Reads the ledger for the given run, finds the latest snapshot entry,
+   * and injects the snapshotId into the first `create_sandbox` step of the
+   * provided workflow — so the new sandbox boots from that snapshot with the
+   * previous environment already in place.
+   */
+  async replayFromSnapshot(
+    name: string,
+    runId: string,
+    w: { build(): { name: string; steps: StepDef[] } },
+  ): Promise<WorkflowRun> {
+    const ledger = await this.getWorkflowLedger(name, runId);
+    const snapEntry = [...ledger].reverse().find((e) => e.event === "snapshot");
+    if (!snapEntry) throw new DrejError(`No snapshot found in ledger for ${name}/${runId}`, 404);
+    const { snapshotId } = snapEntry.payload as { snapshotId: string };
+
+    const { name: wfName, steps } = w.build();
+    const replaySteps: StepDef[] = steps.map((step) =>
+      step.type === "create_sandbox" ? { ...step, snapshotId } : step,
+    );
+
+    return this._startRun(wfName, replaySteps);
   }
 
-  async *resumeWorkflow(id: string, steps: StepDef[]): AsyncGenerator<WorkflowEvent> {
-    const res = await fetch(`${this.baseUrl}/v1/workflows/${id}/resume`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ steps }),
-    });
+  async resumeRun(
+    name: string,
+    runId: string,
+    w: { build(): { name: string; steps: StepDef[] } } | StepDef[],
+  ): Promise<WorkflowRun> {
+    const steps = Array.isArray(w) ? w : w.build().steps;
+    const res = await fetch(
+      `${this.baseUrl}/v1/workflows/${encodeURIComponent(name)}/runs/${encodeURIComponent(runId)}/resume`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ steps }),
+      },
+    );
     if (!res.ok) throw new DrejError("drej API error", res.status);
-    if (!res.body) return;
-    yield* parseWorkflowSSE(res.body);
+    if (!res.body) throw new DrejError("empty response body", 500);
+    return this._consumeRunStarted(name, res.body);
   }
 
-  getWorkflowLedger(id: string): Promise<WorkflowEvent[]> {
-    return this.request("GET", `/v1/workflows/${id}/ledger`);
+  listWorkflowRuns(name: string): Promise<{ runs: string[] }> {
+    return this.request("GET", `/v1/workflows/${encodeURIComponent(name)}/runs`);
+  }
+
+  getWorkflowLedger(name: string, runId: string): Promise<WorkflowEvent[]> {
+    return this.request(
+      "GET",
+      `/v1/workflows/${encodeURIComponent(name)}/runs/${encodeURIComponent(runId)}/ledger`,
+    );
+  }
+
+  private async _startRun(
+    name: string,
+    steps: StepDef[],
+    snapshotConfig?: SnapshotConfig,
+  ): Promise<WorkflowRun> {
+    const res = await fetch(
+      `${this.baseUrl}/v1/workflows/${encodeURIComponent(name)}/runs`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ steps, ...(snapshotConfig ? { snapshotConfig } : {}) }),
+      },
+    );
+    if (!res.ok) throw new DrejError("drej API error", res.status);
+    if (!res.body) throw new DrejError("empty response body", 500);
+    return this._consumeRunStarted(name, res.body);
+  }
+
+  private async _consumeRunStarted(
+    name: string,
+    body: ReadableStream<Uint8Array>,
+  ): Promise<WorkflowRun> {
+    const stream = parseWorkflowSSE(body);
+    const first = await stream.next();
+    if (first.done || first.value.event !== "run_started") {
+      throw new DrejError("expected run_started as first SSE event", 500);
+    }
+    const { runId } = first.value.payload as { runId: string };
+    return new WorkflowRun(name, runId, stream);
   }
 }

package/src/index.ts

@@ -1,4 +1,4 @@
-export { DrejClient, DrejError } from "./client";
+export { DrejClient, DrejError, WorkflowRun } from "./client";
 export type {
   DrejClientOptions,
   Resources,
@@ -27,4 +27,9 @@ export type {
   WorkflowEvent,
   WorkflowEventKind,
   StepDef,
+  SnapshotConfig,
+  RunOptions,
 } from "./client";
+
+export { workflow, WorkflowBuilder, SandboxStepBuilder } from "./workflow";
+export type { SandboxOpts, LoopItem } from "./workflow";

package/src/workflow.ts

@@ -0,0 +1,214 @@
+import type { StepDef, ImageSpec, Resources, Predicate } from "./client";
+
+// Placeholder that serialises to {{name}} inside template literals.
+// Used as the `item` parameter in forEach callbacks so users write
+// `s.exec(`upload ${item}`)` instead of `s.exec("upload {{item}}")`.
+class LoopVar {
+  constructor(private name: string) {}
+  toString() {
+    return `{{${this.name}}}`;
+  }
+}
+
+export type LoopItem = { toString(): string };
+
+export type SandboxOpts = {
+  image?: ImageSpec;
+  snapshotId?: string;
+  timeout?: number;
+  entrypoint?: string[];
+  env?: Record<string, string>;
+  metadata?: Record<string, string>;
+  resourceLimits?: Resources;
+};
+
+type ForEachOpts = {
+  concurrency?: number;
+  as?: string;
+};
+
+type ForEachSource = unknown[] | { from: string };
+type ForEachCallback = (s: SandboxStepBuilder, item: LoopItem) => SandboxStepBuilder | string;
+
+function wrapSteps(steps: StepDef[]): StepDef {
+  return steps.length === 1 ? steps[0] : { type: "sequence", steps };
+}
+
+// ── SandboxStepBuilder ────────────────────────────────────────────────────────
+
+export class SandboxStepBuilder {
+  protected _steps: StepDef[] = [];
+
+  exec(command: string, opts?: { cwd?: string; envs?: Record<string, string> }): this {
+    this._steps.push({ type: "exec_command", command, ...opts });
+    return this;
+  }
+
+  writeFile(path: string, content: string, encoding?: "utf8" | "base64"): this {
+    this._steps.push({ type: "write_file", path, content, ...(encoding ? { encoding } : {}) });
+    return this;
+  }
+
+  retry(
+    maxAttempts: number,
+    fn: (s: SandboxStepBuilder) => SandboxStepBuilder,
+    opts?: { delayMs?: number; backoff?: "fixed" | "exponential" },
+  ): this {
+    const inner = new SandboxStepBuilder();
+    fn(inner);
+    this._steps.push({ type: "retry", step: wrapSteps(inner.build()), maxAttempts, ...opts });
+    return this;
+  }
+
+  forEach(source: ForEachSource, fn: ForEachCallback): this;
+  forEach(source: ForEachSource, opts: ForEachOpts, fn: ForEachCallback): this;
+  forEach(
+    source: ForEachSource,
+    optsOrFn: ForEachOpts | ForEachCallback,
+    fn?: ForEachCallback,
+  ): this {
+    const opts: ForEachOpts = typeof optsOrFn === "function" ? {} : optsOrFn;
+    const callback: ForEachCallback = typeof optsOrFn === "function" ? optsOrFn : fn!;
+
+    const varName = opts.as ?? "item";
+    const loopVar = new LoopVar(varName);
+    const inner = new SandboxStepBuilder();
+    const result = callback(inner, loopVar);
+
+    const steps: StepDef[] =
+      typeof result === "string"
+        ? [{ type: "exec_command", command: result }]
+        : result.build();
+
+    this._steps.push({
+      type: "loop",
+      as: varName,
+      steps,
+      ...(Array.isArray(source) ? { items: source } : { over: source.from }),
+      ...(opts.concurrency !== undefined && opts.concurrency > 1 ? { concurrently: true } : {}),
+    });
+
+    return this;
+  }
+
+  when(
+    condition: Predicate,
+    thenFn: (s: SandboxStepBuilder) => SandboxStepBuilder,
+    elseFn?: (s: SandboxStepBuilder) => SandboxStepBuilder,
+  ): this {
+    const thenBuilder = new SandboxStepBuilder();
+    thenFn(thenBuilder);
+
+    const elseSteps = elseFn
+      ? (() => {
+          const b = new SandboxStepBuilder();
+          elseFn(b);
+          return b.build();
+        })()
+      : undefined;
+
+    this._steps.push({
+      type: "conditional",
+      condition,
+      then: thenBuilder.build(),
+      ...(elseSteps ? { else: elseSteps } : {}),
+    });
+
+    return this;
+  }
+
+  parallel(fn: (p: SandboxParallelBuilder) => SandboxParallelBuilder): this {
+    const pb = new SandboxParallelBuilder();
+    fn(pb);
+    this._steps.push({ type: "parallel", steps: pb.build() });
+    return this;
+  }
+
+  build(): StepDef[] {
+    return [...this._steps];
+  }
+}
+
+// ── SandboxParallelBuilder ────────────────────────────────────────────────────
+// Used inside a sandbox scope — branches share the same sandbox, no new ones.
+
+class SandboxParallelBuilder {
+  private _branches: StepDef[] = [];
+
+  branch(fn: (s: SandboxStepBuilder) => SandboxStepBuilder): this {
+    const sb = new SandboxStepBuilder();
+    fn(sb);
+    this._branches.push(wrapSteps(sb.build()));
+    return this;
+  }
+
+  build(): StepDef[] {
+    return this._branches;
+  }
+}
+
+// ── WorkflowParallelBuilder ───────────────────────────────────────────────────
+// Used at the top-level workflow scope — each branch can own its own sandbox.
+
+class WorkflowParallelBuilder {
+  private _branches: StepDef[] = [];
+
+  sandbox(opts: SandboxOpts, fn: (s: SandboxStepBuilder) => SandboxStepBuilder): this {
+    const sb = new SandboxStepBuilder();
+    fn(sb);
+    this._branches.push({
+      type: "sequence",
+      steps: [
+        { type: "create_sandbox", entrypoint: ["tail", "-f", "/dev/null"], ...opts },
+        ...sb.build(),
+        { type: "delete_sandbox" },
+      ],
+    });
+    return this;
+  }
+
+  branch(fn: (s: SandboxStepBuilder) => SandboxStepBuilder): this {
+    const sb = new SandboxStepBuilder();
+    fn(sb);
+    this._branches.push(wrapSteps(sb.build()));
+    return this;
+  }
+
+  build(): StepDef[] {
+    return this._branches;
+  }
+}
+
+// ── WorkflowBuilder ───────────────────────────────────────────────────────────
+
+export class WorkflowBuilder {
+  private _steps: StepDef[] = [];
+
+  constructor(private _name: string) {}
+
+  sandbox(opts: SandboxOpts, fn: (s: SandboxStepBuilder) => SandboxStepBuilder): this {
+    const sb = new SandboxStepBuilder();
+    fn(sb);
+    this._steps.push(
+      { type: "create_sandbox", entrypoint: ["tail", "-f", "/dev/null"], ...opts },
+      ...sb.build(),
+      { type: "delete_sandbox" },
+    );
+    return this;
+  }
+
+  parallel(fn: (p: WorkflowParallelBuilder) => WorkflowParallelBuilder): this {
+    const pb = new WorkflowParallelBuilder();
+    fn(pb);
+    this._steps.push({ type: "parallel", steps: pb.build() });
+    return this;
+  }
+
+  build(): { name: string; steps: StepDef[] } {
+    return { name: this._name, steps: this._steps };
+  }
+}
+
+export function workflow(name: string): WorkflowBuilder {
+  return new WorkflowBuilder(name);
+}