@drej/workflow 1.1.0

package/dist/index.d.mts

@@ -0,0 +1,229 @@
+import { Drej, ExecCodeOptions, ExecOptions, SandboxOptions } from "drej";
+
+//#region src/sandbox-builder.d.ts
+/** An operation queued on a SandboxBuilder and executed later. */
+type SandboxOp = {
+  kind: "exec";
+  cmd: string;
+  opts: ExecOptions;
+} | {
+  kind: "execCode";
+  code: string;
+  opts: ExecCodeOptions;
+} | {
+  kind: "writeFile";
+  path: string;
+  content: string;
+} | {
+  kind: "readFile";
+  path: string;
+  as: string;
+} | {
+  kind: "deleteFile";
+  path: string;
+} | {
+  kind: "moveFile";
+  from: string;
+  to: string;
+} | {
+  kind: "checkpoint";
+  name?: string;
+} | {
+  kind: "retry";
+  maxAttempts: number;
+  fn: (sb: SandboxBuilder) => void;
+  opts: RetryOptions;
+} | {
+  kind: "when";
+  pred: WhenPredicate;
+  then: (sb: SandboxBuilder) => void;
+  else?: (sb: SandboxBuilder) => void;
+} | {
+  kind: "forEach";
+  items: unknown[];
+  fn: (sb: SandboxBuilder, item: unknown, index: number) => void;
+  opts: ForEachOptions;
+};
+interface RetryOptions {
+  backoff?: "fixed" | "exponential";
+  delayMs?: number;
+}
+type WhenPredicate = (ctx: {
+  stdout: string;
+  exitCode: number;
+  vars: Record<string, unknown>;
+}) => boolean;
+interface ForEachOptions {
+  concurrency?: number;
+}
+/**
+ * Synchronous lazy builder for sandbox operations.
+ *
+ * All methods queue an operation and return `this` — no awaits, no async.
+ * The queue is flushed when `WorkflowBuilder.pipe()` or `.result()` is called.
+ * This gives a single `await` at the end regardless of workflow complexity.
+ *
+ * @example
+ * ```ts
+ * await workflow(client)
+ *   .sandbox({ image: "node:22", resources: { cpu: "500m", memory: "256Mi" } }, (sb) => {
+ *     sb.exec("npm ci")
+ *     sb.checkpoint()
+ *     sb.retry(3, (sb) => sb.exec("npm test"), { backoff: "exponential" })
+ *   })
+ *   .pipe(process.stdout);
+ * ```
+ */
+declare class SandboxBuilder {
+  readonly _ops: SandboxOp[];
+  /** Queue a shell command. */
+  exec(cmd: string, opts?: ExecOptions): this;
+  /** Queue a code execution (Python/JS/TS via execd code interpreter). */
+  execCode(code: string, opts?: ExecCodeOptions): this;
+  /** Queue a file write into the sandbox. */
+  writeFile(path: string, content: string): this;
+  /** Queue a file read from the sandbox, stored in `vars[as]`. */
+  readFile(path: string, as: string): this;
+  /** Queue a file deletion inside the sandbox. */
+  deleteFile(path: string): this;
+  /** Queue a file move/rename inside the sandbox. */
+  moveFile(from: string, to: string): this;
+  /** Queue a checkpoint (snapshot). */
+  checkpoint(name?: string): this;
+  /**
+   * Retry an inner builder callback up to `maxAttempts` times on failure.
+   *
+   * @example
+   * ```ts
+   * sb.retry(3, (sb) => sb.exec("npm test"), { backoff: "exponential" })
+   * ```
+   */
+  retry(maxAttempts: number, fn: (sb: SandboxBuilder) => void, opts?: RetryOptions): this;
+  /**
+   * Conditionally execute one of two builder callbacks based on a predicate.
+   *
+   * The predicate receives `{ stdout, exitCode, vars }` from the last exec.
+   *
+   * @example
+   * ```ts
+   * sb.when(
+   *   (ctx) => ctx.exitCode === 0,
+   *   (sb) => sb.exec("echo success"),
+   *   (sb) => sb.exec("echo failure"),
+   * )
+   * ```
+   */
+  when(pred: WhenPredicate, then: (sb: SandboxBuilder) => void, otherwise?: (sb: SandboxBuilder) => void): this;
+  /**
+   * Execute a builder callback for each item in `items`, optionally in parallel.
+   *
+   * @example
+   * ```ts
+   * sb.forEach(["a", "b", "c"], (sb, item) => sb.exec(`echo ${item}`))
+   * ```
+   */
+  forEach(items: unknown[], fn: (sb: SandboxBuilder, item: unknown, index: number) => void, opts?: ForEachOptions): this;
+}
+//#endregion
+//#region src/workflow-builder.d.ts
+interface WorkflowResult {
+  /** Concatenated stdout from all sandboxes in the workflow. */
+  stdout: string;
+  /** Named values captured by `sb.readFile(path, as)`. */
+  vars: Record<string, unknown>;
+}
+/** A single step in a `.sequence()` call. */
+interface SequenceStep {
+  image: SandboxOptions["image"];
+  resources: SandboxOptions["resources"];
+  env?: SandboxOptions["env"];
+  timeout?: SandboxOptions["timeout"];
+  name?: string;
+  run: (sb: SandboxBuilder, prevResult?: WorkflowResult) => void;
+}
+/**
+ * Lazy workflow builder. Collects stages and executes them all when `.pipe()` or
+ * `.result()` is awaited. Sandboxes are created via the `Drej` client internally
+ * — the user never manages sandbox lifecycle when using this layer.
+ *
+ * @example
+ * ```ts
+ * import { workflow } from "@drej/workflow";
+ *
+ * await workflow(client)
+ *   .sandbox({ image: "node:22", resources: { cpu: "500m", memory: "256Mi" } }, (sb) => {
+ *     sb.exec("npm ci")
+ *     sb.checkpoint()
+ *     sb.retry(3, (sb) => sb.exec("npm test"), { backoff: "exponential" })
+ *   })
+ *   .pipe(process.stdout);
+ * ```
+ */
+declare class WorkflowBuilder {
+  private readonly _client;
+  private readonly _stages;
+  constructor(client: Drej);
+  /**
+   * Add a sandbox stage. The `fn` callback receives a `SandboxBuilder` to
+   * queue operations synchronously. Sandboxes across multiple `.sandbox()` calls
+   * run sequentially, top-to-bottom.
+   */
+  sandbox(opts: SandboxOptions, fn: (sb: SandboxBuilder) => void): this;
+  /**
+   * Run the same operation across multiple sandbox configurations in parallel.
+   * All sandboxes receive the same `fn` callback.
+   *
+   * @example
+   * ```ts
+   * await workflow(client)
+   *   .parallel(
+   *     [{ image: "node:20" }, { image: "node:22" }, { image: "node:24" }],
+   *     (sb) => sb.exec("npm test"),
+   *   )
+   *   .pipe(process.stdout);
+   * ```
+   */
+  parallel(configs: SandboxOptions[], fn: (sb: SandboxBuilder) => void): this;
+  /**
+   * Run sandboxes in sequence, passing the previous stage's result to the next.
+   *
+   * @example
+   * ```ts
+   * await workflow(client)
+   *   .sequence([
+   *     { image: "node:22", run: (sb) => sb.exec("npm run build") },
+   *     { image: "ubuntu:22.04", run: (sb, prev) => sb.exec("./deploy.sh") },
+   *   ])
+   *   .pipe(process.stdout);
+   * ```
+   */
+  sequence(steps: SequenceStep[]): this;
+  /** Execute the workflow and pipe stdout to a writable. */
+  pipe(writable: {
+    write(chunk: string): unknown;
+  }): Promise<void>;
+  /** Execute the workflow and return the full result. */
+  result(): Promise<WorkflowResult>;
+  private _execute;
+  private _runSandbox;
+  private _runParallel;
+  private _runSequence;
+}
+/**
+ * Create a workflow builder attached to a `Drej` client.
+ *
+ * @example
+ * ```ts
+ * import { workflow } from "@drej/workflow";
+ *
+ * await workflow(client)
+ *   .sandbox({ image: "node:22", resources: { cpu: "500m", memory: "256Mi" } }, (sb) => {
+ *     sb.exec("npm ci")
+ *     sb.exec("npm test")
+ *   })
+ *   .pipe(process.stdout);
+ * ```
+ */
+declare function workflow(client: Drej): WorkflowBuilder;
+//#endregion
+export { type ForEachOptions, type RetryOptions, SandboxBuilder, type SandboxOp, type SequenceStep, type WhenPredicate, WorkflowBuilder, type WorkflowResult, workflow };

package/dist/index.mjs

@@ -0,0 +1,423 @@
+//#region src/sandbox-builder.ts
+/**
+* Synchronous lazy builder for sandbox operations.
+*
+* All methods queue an operation and return `this` — no awaits, no async.
+* The queue is flushed when `WorkflowBuilder.pipe()` or `.result()` is called.
+* This gives a single `await` at the end regardless of workflow complexity.
+*
+* @example
+* ```ts
+* await workflow(client)
+*   .sandbox({ image: "node:22", resources: { cpu: "500m", memory: "256Mi" } }, (sb) => {
+*     sb.exec("npm ci")
+*     sb.checkpoint()
+*     sb.retry(3, (sb) => sb.exec("npm test"), { backoff: "exponential" })
+*   })
+*   .pipe(process.stdout);
+* ```
+*/
+var SandboxBuilder = class {
+	_ops = [];
+	/** Queue a shell command. */
+	exec(cmd, opts = {}) {
+		this._ops.push({
+			kind: "exec",
+			cmd,
+			opts
+		});
+		return this;
+	}
+	/** Queue a code execution (Python/JS/TS via execd code interpreter). */
+	execCode(code, opts = {}) {
+		this._ops.push({
+			kind: "execCode",
+			code,
+			opts
+		});
+		return this;
+	}
+	/** Queue a file write into the sandbox. */
+	writeFile(path, content) {
+		this._ops.push({
+			kind: "writeFile",
+			path,
+			content
+		});
+		return this;
+	}
+	/** Queue a file read from the sandbox, stored in `vars[as]`. */
+	readFile(path, as) {
+		this._ops.push({
+			kind: "readFile",
+			path,
+			as
+		});
+		return this;
+	}
+	/** Queue a file deletion inside the sandbox. */
+	deleteFile(path) {
+		this._ops.push({
+			kind: "deleteFile",
+			path
+		});
+		return this;
+	}
+	/** Queue a file move/rename inside the sandbox. */
+	moveFile(from, to) {
+		this._ops.push({
+			kind: "moveFile",
+			from,
+			to
+		});
+		return this;
+	}
+	/** Queue a checkpoint (snapshot). */
+	checkpoint(name) {
+		this._ops.push({
+			kind: "checkpoint",
+			name
+		});
+		return this;
+	}
+	/**
+	* Retry an inner builder callback up to `maxAttempts` times on failure.
+	*
+	* @example
+	* ```ts
+	* sb.retry(3, (sb) => sb.exec("npm test"), { backoff: "exponential" })
+	* ```
+	*/
+	retry(maxAttempts, fn, opts = {}) {
+		this._ops.push({
+			kind: "retry",
+			maxAttempts,
+			fn,
+			opts
+		});
+		return this;
+	}
+	/**
+	* Conditionally execute one of two builder callbacks based on a predicate.
+	*
+	* The predicate receives `{ stdout, exitCode, vars }` from the last exec.
+	*
+	* @example
+	* ```ts
+	* sb.when(
+	*   (ctx) => ctx.exitCode === 0,
+	*   (sb) => sb.exec("echo success"),
+	*   (sb) => sb.exec("echo failure"),
+	* )
+	* ```
+	*/
+	when(pred, then, otherwise) {
+		this._ops.push({
+			kind: "when",
+			pred,
+			then,
+			else: otherwise
+		});
+		return this;
+	}
+	/**
+	* Execute a builder callback for each item in `items`, optionally in parallel.
+	*
+	* @example
+	* ```ts
+	* sb.forEach(["a", "b", "c"], (sb, item) => sb.exec(`echo ${item}`))
+	* ```
+	*/
+	forEach(items, fn, opts = {}) {
+		this._ops.push({
+			kind: "forEach",
+			items,
+			fn,
+			opts
+		});
+		return this;
+	}
+};
+/** Flush a SandboxBuilder's op queue against a live Sandbox. */
+async function flushOps(sandbox, ops, ctx) {
+	for (const op of ops) switch (op.kind) {
+		case "exec": {
+			const handle = sandbox.exec(op.cmd, op.opts);
+			if (ctx.sink) {
+				for await (const chunk of handle.stdout()) {
+					ctx.stdout += chunk;
+					ctx.sink.write(chunk);
+				}
+				ctx.exitCode = (await handle.result()).exitCode;
+			} else {
+				const result = await handle;
+				ctx.stdout += result.stdout;
+				ctx.exitCode = result.exitCode;
+			}
+			break;
+		}
+		case "execCode": {
+			const handle = sandbox.execCode(op.code, op.opts);
+			if (ctx.sink) {
+				for await (const chunk of handle.stdout()) {
+					ctx.stdout += chunk;
+					ctx.sink.write(chunk);
+				}
+				ctx.exitCode = (await handle.result()).exitCode;
+			} else {
+				const result = await handle;
+				ctx.stdout += result.stdout;
+				ctx.exitCode = result.exitCode;
+			}
+			break;
+		}
+		case "writeFile":
+			await sandbox.writeFile(op.path, op.content);
+			break;
+		case "readFile": {
+			const content = await sandbox.readFile(op.path);
+			ctx.vars[op.as] = content;
+			break;
+		}
+		case "deleteFile":
+			await sandbox.deleteFile(op.path);
+			break;
+		case "moveFile":
+			await sandbox.moveFile(op.from, op.to);
+			break;
+		case "checkpoint":
+			await sandbox.checkpoint(op.name);
+			break;
+		case "retry":
+			await flushRetry(sandbox, op.fn, op.maxAttempts, op.opts, ctx);
+			break;
+		case "when": {
+			const branch = op.pred(ctx) ? op.then : op["else"];
+			if (branch) {
+				const inner = new SandboxBuilder();
+				branch(inner);
+				await flushOps(sandbox, inner._ops, ctx);
+			}
+			break;
+		}
+		case "forEach":
+			await flushForEach(sandbox, op.items, op.fn, op.opts, ctx);
+			break;
+	}
+}
+async function flushRetry(sandbox, fn, maxAttempts, opts, ctx) {
+	let lastErr;
+	for (let attempt = 0; attempt < maxAttempts; attempt++) {
+		if (attempt > 0) {
+			const base = opts.delayMs ?? 1e3;
+			const delay = opts.backoff === "exponential" ? base * 2 ** (attempt - 1) : base;
+			await new Promise((r) => setTimeout(r, delay));
+		}
+		try {
+			const inner = new SandboxBuilder();
+			fn(inner);
+			await flushOps(sandbox, inner._ops, ctx);
+			return;
+		} catch (err) {
+			lastErr = err;
+		}
+	}
+	throw lastErr;
+}
+async function flushForEach(sandbox, items, fn, opts, ctx) {
+	const concurrency = opts.concurrency ?? 1;
+	if (concurrency <= 1) for (let i = 0; i < items.length; i++) {
+		const inner = new SandboxBuilder();
+		fn(inner, items[i], i);
+		await flushOps(sandbox, inner._ops, ctx);
+	}
+	else {
+		let idx = 0;
+		async function worker() {
+			while (idx < items.length) {
+				const i = idx++;
+				const inner = new SandboxBuilder();
+				fn(inner, items[i], i);
+				await flushOps(sandbox, inner._ops, { ...ctx });
+			}
+		}
+		const workers = Array.from({ length: Math.min(concurrency, items.length) }, worker);
+		await Promise.all(workers);
+	}
+}
+//#endregion
+//#region src/workflow-builder.ts
+/**
+* Lazy workflow builder. Collects stages and executes them all when `.pipe()` or
+* `.result()` is awaited. Sandboxes are created via the `Drej` client internally
+* — the user never manages sandbox lifecycle when using this layer.
+*
+* @example
+* ```ts
+* import { workflow } from "@drej/workflow";
+*
+* await workflow(client)
+*   .sandbox({ image: "node:22", resources: { cpu: "500m", memory: "256Mi" } }, (sb) => {
+*     sb.exec("npm ci")
+*     sb.checkpoint()
+*     sb.retry(3, (sb) => sb.exec("npm test"), { backoff: "exponential" })
+*   })
+*   .pipe(process.stdout);
+* ```
+*/
+var WorkflowBuilder = class {
+	_client;
+	_stages = [];
+	constructor(client) {
+		this._client = client;
+	}
+	/**
+	* Add a sandbox stage. The `fn` callback receives a `SandboxBuilder` to
+	* queue operations synchronously. Sandboxes across multiple `.sandbox()` calls
+	* run sequentially, top-to-bottom.
+	*/
+	sandbox(opts, fn) {
+		this._stages.push({
+			type: "sandbox",
+			opts,
+			fn
+		});
+		return this;
+	}
+	/**
+	* Run the same operation across multiple sandbox configurations in parallel.
+	* All sandboxes receive the same `fn` callback.
+	*
+	* @example
+	* ```ts
+	* await workflow(client)
+	*   .parallel(
+	*     [{ image: "node:20" }, { image: "node:22" }, { image: "node:24" }],
+	*     (sb) => sb.exec("npm test"),
+	*   )
+	*   .pipe(process.stdout);
+	* ```
+	*/
+	parallel(configs, fn) {
+		this._stages.push({
+			type: "parallel",
+			configs,
+			fn
+		});
+		return this;
+	}
+	/**
+	* Run sandboxes in sequence, passing the previous stage's result to the next.
+	*
+	* @example
+	* ```ts
+	* await workflow(client)
+	*   .sequence([
+	*     { image: "node:22", run: (sb) => sb.exec("npm run build") },
+	*     { image: "ubuntu:22.04", run: (sb, prev) => sb.exec("./deploy.sh") },
+	*   ])
+	*   .pipe(process.stdout);
+	* ```
+	*/
+	sequence(steps) {
+		this._stages.push({
+			type: "sequence",
+			steps
+		});
+		return this;
+	}
+	/** Execute the workflow and pipe stdout to a writable. */
+	async pipe(writable) {
+		await this._execute(writable);
+	}
+	/** Execute the workflow and return the full result. */
+	async result() {
+		return this._execute(void 0);
+	}
+	async _execute(sink) {
+		const combined = {
+			stdout: "",
+			vars: {}
+		};
+		for (const stage of this._stages) if (stage.type === "sandbox") {
+			const result = await this._runSandbox(stage.opts, stage.fn, sink);
+			combined.stdout += result.stdout;
+			Object.assign(combined.vars, result.vars);
+		} else if (stage.type === "parallel") {
+			const results = await this._runParallel(stage.configs, stage.fn, sink);
+			for (const r of results) {
+				combined.stdout += r.stdout;
+				Object.assign(combined.vars, r.vars);
+			}
+		} else if (stage.type === "sequence") {
+			const result = await this._runSequence(stage.steps, sink);
+			combined.stdout += result.stdout;
+			Object.assign(combined.vars, result.vars);
+		}
+		return combined;
+	}
+	async _runSandbox(opts, fn, sink) {
+		const sb = new SandboxBuilder();
+		fn(sb);
+		const sandbox = await this._client.sandbox(opts);
+		try {
+			const ctx = {
+				stdout: "",
+				exitCode: 0,
+				vars: {},
+				sink
+			};
+			await flushOps(sandbox, sb._ops, ctx);
+			return {
+				stdout: ctx.stdout,
+				vars: ctx.vars
+			};
+		} finally {
+			await sandbox.close();
+		}
+	}
+	async _runParallel(configs, fn, sink) {
+		return Promise.all(configs.map((opts) => this._runSandbox(opts, fn, sink)));
+	}
+	async _runSequence(steps, sink) {
+		const combined = {
+			stdout: "",
+			vars: {}
+		};
+		let prev;
+		for (const step of steps) {
+			const opts = {
+				image: step.image,
+				resources: step.resources,
+				env: step.env,
+				timeout: step.timeout,
+				name: step.name
+			};
+			const result = await this._runSandbox(opts, (sb) => step.run(sb, prev), sink);
+			combined.stdout += result.stdout;
+			Object.assign(combined.vars, result.vars);
+			prev = result;
+		}
+		return combined;
+	}
+};
+/**
+* Create a workflow builder attached to a `Drej` client.
+*
+* @example
+* ```ts
+* import { workflow } from "@drej/workflow";
+*
+* await workflow(client)
+*   .sandbox({ image: "node:22", resources: { cpu: "500m", memory: "256Mi" } }, (sb) => {
+*     sb.exec("npm ci")
+*     sb.exec("npm test")
+*   })
+*   .pipe(process.stdout);
+* ```
+*/
+function workflow(client) {
+	return new WorkflowBuilder(client);
+}
+//#endregion
+export { SandboxBuilder, WorkflowBuilder, workflow };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@drej/workflow",
+  "version": "1.1.0",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "drej": "workspace:*"
+  },
+  "devDependencies": {
+    "bun-types": "1.3.14",
+    "tsdown": "0.22.3",
+    "typescript": "6.0.3",
+    "vitest": "4.1.9"
+  }
+}