@drej/core 0.2.0 → 0.4.0

package/dist/index.d.mts

@@ -0,0 +1,497 @@
+import { ControlClient, ExecClient, FileInfo, SSEEvent } from "@drej/opensandbox";
+
+//#region src/ledger.d.ts
+/** Status of a sandbox session derived from its ledger events. */
+declare enum SandboxStatus {
+  Running = "running",
+  Completed = "completed"
+}
+/** Derived metadata for a sandbox session, computed from its ledger events. */
+interface SandboxDetails {
+  /** User-provided name (or auto-generated). */
+  name: string;
+  sandboxId: string;
+  status: SandboxStatus;
+  /** Unix timestamp (ms) of the `sandbox_created` event. */
+  startedAt: number;
+  /** Unix timestamp (ms) of the `sandbox_closed` event, if the session has ended. */
+  completedAt?: number;
+  /** Number of exec() calls that completed. */
+  execCount: number;
+}
+/** Options for filtering session listings. */
+interface ListSandboxOptions {
+  status?: SandboxStatus;
+  /** Max number of results to return. */
+  limit?: number;
+  /** Return only sessions that started before this Unix timestamp (ms). */
+  before?: number;
+}
+/** Events emitted during execution and stored in the ledger. */
+declare enum LedgerEvent {
+  /** Emitted when a sandbox is created and reaches Running state. */
+  SandboxCreated = "sandbox_created",
+  /** Emitted at the start of each exec() or execCode() call. */
+  ExecStart = "exec_start",
+  /** Streaming output chunk from exec() or execCode(). */
+  ExecEvent = "exec_event",
+  /** Emitted when an exec() or execCode() call completes. */
+  ExecComplete = "exec_complete",
+  /** Emitted when checkpoint() captures a snapshot. */
+  CheckpointCreated = "checkpoint_created",
+  /** Emitted when a sandbox is closed. */
+  SandboxClosed = "sandbox_closed",
+  /** 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",
+  /** Emitted when a sandbox snapshot is captured mid-run. */
+  Snapshot = "snapshot"
+}
+/** A single event record written to the storage adapter during a session. */
+interface LedgerEntry {
+  /** Unix timestamp in milliseconds. */
+  ts: number;
+  /** Sandbox session name. */
+  name: string;
+  sandboxId: string;
+  /** Zero-based index of the step that produced this event. `-1` for session-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;
+}
+/** A recorded checkpoint for a sandbox session. */
+interface CheckpointInfo {
+  /** OpenSandbox snapshot ID. */
+  snapshotId: string;
+  /** User-supplied name, if provided when calling `sb.checkpoint(name)`. */
+  tag?: string;
+  /** Unix timestamp (ms) when the checkpoint was created. */
+  createdAt: number;
+}
+/**
+ * Persisted record for a named, reusable sandbox environment.
+ * Written once when the environment is first built; updated on rebuild.
+ */
+interface EnvironmentRecord {
+  /** User-provided environment name. */
+  name: string;
+  /** OpenSandbox snapshot ID to restore from. */
+  snapshotId: string;
+  /** Raw image URI resolved at build time. */
+  image: string;
+  /** Unix timestamp (ms) when the environment was last built. */
+  builtAt: number;
+}
+/**
+ * Persistence interface for session 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 Drej({ baseUrl, adapter: new SQLiteAdapter("./drej.db") });
+ * ```
+ */
+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 execution. */
+  append(entry: LedgerEntry): Promise<void>;
+  /** Return all events for a specific session, in ascending timestamp order. */
+  readAll(name: string, sandboxId: string): Promise<LedgerEntry[]>;
+  /** Return the most recent checkpoint entry for a session, or `null` if none exists. */
+  lastCheckpoint(name: string, sandboxId: string): Promise<LedgerEntry | null>;
+  /** Return details for all sessions with a given name, newest first. */
+  listSandboxDetails(name: string, opts?: ListSandboxOptions): Promise<SandboxDetails[]>;
+  /** Return details for sessions across all names, newest first. */
+  listAllSandboxDetails(opts?: ListSandboxOptions): Promise<SandboxDetails[]>;
+  /** Return details for a single session, or `null` if not found. */
+  getSandboxDetails(name: string, sandboxId: string): Promise<SandboxDetails | null>;
+  /** Delete all ledger events for a session. */
+  deleteSandbox(name: string, sandboxId: string): Promise<void>;
+  /** Return all checkpoints for a session in creation order. */
+  listCheckpoints(name: string, sandboxId: string): Promise<CheckpointInfo[]>;
+  /** Return the cached record for a named environment, or null if not built yet. */
+  getEnvironment(name: string): Promise<EnvironmentRecord | null>;
+  /** Upsert an environment record after a successful build. */
+  saveEnvironment(record: EnvironmentRecord): Promise<void>;
+  /** Remove the record for a named environment. Does not delete the server-side snapshot. */
+  deleteEnvironment(name: string): Promise<void>;
+  /** Return all environment records, newest first. */
+  listEnvironments(): Promise<EnvironmentRecord[]>;
+}
+//#endregion
+//#region src/logger.d.ts
+declare enum LogLevel {
+  Debug = 0,
+  Info = 1,
+  Warn = 2,
+  Error = 3,
+  Silent = 4
+}
+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;
+}
+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;
+}
+declare const noopLogger: ILogger;
+//#endregion
+//#region src/exec-handle.d.ts
+interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+type ExecDriver = {
+  type: "stream";
+  gen: AsyncGenerator<SSEEvent>;
+  onDone: (r: ExecResult) => Promise<void>;
+} | {
+  type: "replay";
+  result: ExecResult;
+};
+/**
+ * Returned by `Sandbox.exec()` and `Sandbox.execCode()`.
+ *
+ * Implements `PromiseLike<ExecResult>` so `await sb.exec(...)` works naturally.
+ * Also exposes `pipe()`, `stdout()`, and `result()` for streaming output.
+ *
+ * @example
+ * ```ts
+ * // simple await
+ * const { exitCode } = await sb.exec("npm test");
+ *
+ * // stream to stdout
+ * await sb.exec("npm run build").pipe(process.stdout);
+ *
+ * // async generator
+ * for await (const chunk of sb.exec("npm test").stdout()) process.stdout.write(chunk);
+ * ```
+ */
+declare class ExecHandle implements PromiseLike<ExecResult> {
+  private readonly _promise;
+  private readonly _chunks;
+  private _wakeup;
+  private _done;
+  private _err;
+  private _hasErr;
+  constructor(driver: ExecDriver);
+  private _drain;
+  private _notify;
+  then<T, E>(onfulfilled?: ((value: ExecResult) => T | PromiseLike<T>) | null, onrejected?: ((reason: unknown) => E | PromiseLike<E>) | null): Promise<T | E>;
+  /** Resolve the full result: `{ stdout, stderr, exitCode }`. */
+  result(): Promise<ExecResult>;
+  /** Async generator yielding stdout chunks as they arrive. */
+  stdout(): AsyncGenerator<string>;
+  /** Pipe stdout to any writable with a `write(chunk: string)` method. */
+  pipe(writable: {
+    write(chunk: string): unknown;
+  }): Promise<void>;
+}
+//#endregion
+//#region src/sandbox.d.ts
+interface ExecOptions {
+  /** Working directory inside the sandbox. */
+  cwd?: string;
+  /** Environment variables to set for this exec. */
+  env?: Record<string, string>;
+  /** Abort the command after this many milliseconds. */
+  timeoutMs?: number;
+  /**
+   * Throw `CommandError` if the command exits with a non-zero code.
+   * Defaults to `true`.
+   */
+  strict?: boolean;
+  /**
+   * Path to the shell binary used to execute the command.
+   * Overrides the sandbox-level default set in `SandboxOptions.shell`.
+   * Defaults to `"/bin/sh"`.
+   */
+  shell?: string;
+}
+interface ExecCodeOptions {
+  /** Execution context (stateful interpreter session). */
+  context?: {
+    id: string;
+    language: import("@drej/opensandbox").CodeLanguage;
+  };
+}
+/** Lifecycle hooks for observability. Pass via `SandboxDeps.hooks`. */
+interface SandboxHooks {
+  onSandboxCreated?(sandboxId: string, name: string): void;
+  onExecStart?(sandboxId: string, seq: number, cmd: string): void;
+  onExecComplete?(sandboxId: string, seq: number, result: ExecResult): void;
+  onCheckpoint?(sandboxId: string, snapshotId: string, name?: string): void;
+  onSandboxClosed?(sandboxId: string): void;
+  onSandboxFailed?(sandboxId: string, error: Error): void;
+}
+/** Internal dependencies injected by `DrejClient`. */
+interface SandboxDeps {
+  control: ControlClient;
+  adapter: IStorageAdapter;
+  hooks?: SandboxHooks;
+  /** Called when `close()` completes — used by `Drej` for concurrency accounting. */
+  onClose?: () => void;
+  /** Default shell for all `exec()` calls on this sandbox. Defaults to `"/bin/sh"`. */
+  shell?: string;
+  /** Called by `fork()` to create a new Sandbox from a snapshot — injected by `Drej`. */
+  fork?: (snapshotId: string, tag?: string) => Promise<Sandbox>;
+  /** Route execd and proxy calls through the OpenSandbox server. Required when the server runs in Docker. */
+  useServerProxy?: boolean;
+}
+/**
+ * Resolve an ExecClient for a sandbox. Calls getEndpoint once (each call
+ * returns a different ephemeral proxy port) then polls listContexts until
+ * execd is ready to accept connections.
+ */
+declare function resolveExecClient(control: ControlClient, sandboxId: string, useServerProxy?: boolean, retries?: number, delayMs?: number): Promise<ExecClient>;
+/**
+ * A live sandbox container. Returned by `DrejClient.sandbox()` and `DrejClient.resume()`.
+ *
+ * Call `exec()` to run commands, `checkpoint()` to snapshot state, and `close()`
+ * when done. Multiple sandboxes can be held simultaneously — just assign to
+ * different variables.
+ *
+ * @example
+ * ```ts
+ * const sb = await client.sandbox({ image: "node:22", resources: { cpu: "500m", memory: "256Mi" } });
+ * await sb.exec("npm ci");
+ * await sb.checkpoint();
+ * await sb.exec("npm test").pipe(process.stdout);
+ * await sb.close();
+ * ```
+ */
+declare class Sandbox {
+  /** OpenSandbox container ID — also the unique ledger key for this session. */
+  readonly sandboxId: string;
+  /** User-provided name (or auto-generated). */
+  readonly name: string;
+  private readonly _deps;
+  /** Cached exec results for replay mode (populated by DrejClient.resume()). */
+  private readonly _replayCache;
+  private _execClient;
+  private _seq;
+  private _closed;
+  constructor(sandboxId: string, name: string, deps: SandboxDeps, replayCache?: Map<number, ExecResult>);
+  private _getExecClient;
+  private _emit;
+  /**
+   * Execute a shell command inside the sandbox.
+   *
+   * Returns an `ExecHandle` — await it for the result, call `.pipe()` to stream
+   * stdout, or use `.stdout()` as an async generator. Every call is logged to
+   * the ledger; replayed execs in a resumed sandbox return cached output
+   * instantly without re-running.
+   *
+   * @example
+   * ```ts
+   * const { exitCode } = await sb.exec("npm test");
+   * await sb.exec("npm run build").pipe(process.stdout);
+   * ```
+   */
+  exec(cmd: string, opts?: ExecOptions): ExecHandle;
+  /**
+   * Create a code execution context for use with `execCode()`.
+   *
+   * The code interpreter requires a context for every `execCode()` call. Call
+   * this once per session (or once per isolated scope), then pass the returned
+   * object as `opts.context` to `execCode()`. Variables defined in one call
+   * are visible to subsequent calls sharing the same context.
+   *
+   * @example
+   * ```ts
+   * const ctx = await sb.createCodeContext(CodeLanguage.Python);
+   * await sb.execCode('x = 42', { context: ctx });
+   * await sb.execCode('print(x)', { context: ctx }); // prints 42
+   * ```
+   */
+  createCodeContext(language: import("@drej/opensandbox").CodeLanguage): Promise<import("@drej/opensandbox").CodeContext>;
+  /**
+   * Execute code via the sandbox's code interpreter (Python, JS, etc.).
+   *
+   * Uses the execd `/code` endpoint for stateful, Jupyter-style execution.
+   * Contexts persist across calls — use `opts.context` to target a specific one.
+   * Create a context first with `sb.createCodeContext(language)`.
+   */
+  execCode(code: string, opts?: ExecCodeOptions): ExecHandle;
+  /** Write a file into the sandbox. */
+  writeFile(path: string, content: string): Promise<void>;
+  /** Read a file from the sandbox as a UTF-8 string. */
+  readFile(path: string): Promise<string>;
+  /** Delete a file from the sandbox. */
+  deleteFile(path: string): Promise<void>;
+  /** Move or rename a file inside the sandbox. */
+  moveFile(from: string, to: string): Promise<void>;
+  /** List files in a directory inside the sandbox. */
+  listDirectory(path: string, opts?: {
+    depth?: number;
+  }): Promise<import("@drej/opensandbox").FileInfo[]>;
+  /** Search for files matching a glob pattern inside the sandbox. */
+  searchFiles(pattern: string, path?: string): Promise<string[]>;
+  /** Create a directory (and parents) inside the sandbox. */
+  createDirectory(path: string): Promise<void>;
+  /** Delete a directory inside the sandbox. */
+  deleteDirectory(path: string): Promise<void>;
+  /** Return metadata for a file or directory (size, type, mode, timestamps). */
+  getFileInfo(path: string): Promise<import("@drej/opensandbox").FileInfo>;
+  /**
+   * Replace substrings in one or more files inside the sandbox.
+   *
+   * More efficient than `readFile` → string replace → `writeFile` for targeted edits.
+   *
+   * @example
+   * ```ts
+   * await sb.replaceInFiles([{ path: "/app/config.json", old: "localhost", new: "0.0.0.0" }]);
+   * ```
+   */
+  replaceInFiles(replacements: Array<{
+    path: string;
+    old: string;
+    new: string;
+  }>): Promise<void>;
+  /**
+   * Copy a file from this sandbox into another sandbox.
+   *
+   * Reads the file as a UTF-8 string and writes it to the same path on the target.
+   * Use this to move results between a fork and its origin, or between parallel sandboxes.
+   *
+   * @example
+   * ```ts
+   * await sb.transfer("/app/output.json", fork);
+   * ```
+   */
+  transfer(path: string, target: Sandbox): Promise<void>;
+  /**
+   * Return a proxied URL and auth headers for a port inside the sandbox.
+   *
+   * Use this to send HTTP requests to a server running inside the sandbox.
+   *
+   * @example
+   * ```ts
+   * await sb.exec("node server.js &");
+   * const { url, headers } = await sb.proxy(3000);
+   * const res = await fetch(`${url}/health`, { headers });
+   * ```
+   */
+  proxy(port: number): Promise<{
+    url: string;
+    headers: Record<string, string>;
+  }>;
+  /** Return current CPU and memory usage for this sandbox. */
+  metrics(): Promise<{
+    cpu: number;
+    memory: number;
+    timestamp: string;
+  }>;
+  /** Return all checkpoints for this sandbox in creation order. */
+  listCheckpoints(): Promise<CheckpointInfo[]>;
+  /**
+   * Snapshot the current sandbox and return a new independent `Sandbox` from that state.
+   *
+   * The original sandbox keeps running. Both operate on separate containers restored
+   * from the same snapshot. Equivalent to `checkpoint()` followed by `resume()` on a
+   * clone, but without closing the original.
+   *
+   * @example
+   * ```ts
+   * await sb.exec("npm ci");
+   * const fork = await sb.fork("after-install");
+   *
+   * await sb.exec("npm test");         // runs on original
+   * await fork.exec("npm run build");  // runs on fork
+   * ```
+   */
+  fork(tag?: string): Promise<Sandbox>;
+  /**
+   * Capture a snapshot of the sandbox's current filesystem state.
+   *
+   * Writes a `checkpoint_created` event to the ledger with the snapshot ID.
+   * Use `DrejClient.resume(sandboxId)` to restore from the latest checkpoint.
+   */
+  checkpoint(name?: string): Promise<void>;
+  private _waitForSnapshot;
+  /**
+   * Delete the sandbox container and release its resources.
+   *
+   * Always call `close()` when done — even on error — to avoid leaking containers.
+   * Idempotent: subsequent calls are no-ops.
+   */
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/errors.d.ts
+/** Base class for all drej workflow runtime errors. */
+declare class WorkflowError extends Error {
+  constructor(message: string);
+}
+/** Thrown when a sandbox fails to create, boot, or reach `Running` state. */
+declare class SandboxError extends WorkflowError {
+  /** The sandbox ID, if one was assigned before the failure. */
+  readonly sandboxId?: string | undefined;
+  constructor(message: string, /** The sandbox ID, if one was assigned before the failure. */
+
+  sandboxId?: string | undefined);
+}
+/**
+ * Thrown when execd inside a sandbox never becomes ready within the retry window.
+ * The sandbox is `Running` from the control plane's perspective, but the exec
+ * daemon is not accepting connections.
+ */
+declare class ExecConnectionError extends WorkflowError {
+  readonly sandboxId: string;
+  constructor(sandboxId: string);
+}
+/**
+ * Thrown when an `exec()` step exits with a non-zero exit code and the
+ * `strict` option is enabled. Carries the exit code and original command.
+ */
+declare class CommandError extends WorkflowError {
+  readonly exitCode: number;
+  readonly command: string;
+  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.
+ */
+declare class StepTimeoutError extends WorkflowError {
+  readonly stepId: string;
+  readonly timeoutMs: number;
+  constructor(stepId: string, timeoutMs: number);
+}
+//#endregion
+export { type CheckpointInfo, CommandError, ConsoleLogger, type EnvironmentRecord, type ExecCodeOptions, ExecConnectionError, ExecHandle, type ExecOptions, type ExecResult, type FileInfo, type ILogger, type IStorageAdapter, type LedgerEntry, LedgerEvent, type ListSandboxOptions, LogLevel, Sandbox, type SandboxDeps, type SandboxDetails, SandboxError, type SandboxHooks, SandboxStatus, StepTimeoutError, WorkflowError, noopLogger, resolveExecClient };