@lizard-build/sdk 0.1.30 → 0.1.32

package/dist/index.d.mts

@@ -25,7 +25,9 @@ interface ProcessOpts {
     envs?: Record<string, string>;
     user?: string;
     workdir?: string;
+    /** Called with each stdout line as it is produced, rather than at the end. */
     onStdout?: (data: string) => void;
+    /** Called with each stderr line as it is produced, rather than at the end. */
     onStderr?: (data: string) => void;
 }
 /**
@@ -62,6 +64,12 @@ declare class Process {
      * ```
      */
     exec(cmd: string, opts?: ProcessOpts): Promise<ProcessResult>;
+    /**
+     * Read an SSE exec stream, handing each line to the caller as it arrives while
+     * still accumulating the full result. Events are `{stream, line}` for output and
+     * `{exitCode}` at the end.
+     */
+    private consumeStream;
 }
 
 interface FsOpts {
@@ -70,8 +78,12 @@ interface FsOpts {
 interface FileInfo {
     name: string;
     path: string;
-    type: 'file' | 'dir';
+    type: 'file' | 'dir' | 'symlink';
     size: number;
+    /** Permission bits as a string, e.g. `-rw-r--r--`. Absent on older sandboxes. */
+    mode?: string;
+    /** Last modification time, unix milliseconds. Absent on older sandboxes. */
+    modTime?: number;
 }
 /**
  * Read and write files inside a Lizard sandbox microVM.
@@ -126,6 +138,35 @@ declare class Fs {
      * Create a directory (and any missing parents) inside the microVM.
      */
     makeDir(path: string, opts?: FsOpts): Promise<void>;
+    /**
+     * Metadata for a single path — size, type, permissions, modification time.
+     *
+     * Saves listing a parent directory and filtering it just to answer "does this
+     * exist, and how big is it".
+     *
+     * @example
+     * ```ts
+     * const info = await sandbox.fs.stat('/app/out.bin')
+     * console.log(info.size, info.type)
+     * ```
+     *
+     * Throws `NotFoundError` if the path does not exist. Sandboxes created before
+     * this shipped run a guest agent without it and throw `LizardError` (501) —
+     * recreate the sandbox to use it.
+     */
+    stat(path: string, opts?: FsOpts): Promise<FileInfo>;
+    /**
+     * Move or rename a path. Creates the destination's parent directories.
+     *
+     * @example
+     * ```ts
+     * await sandbox.fs.move('/tmp/build.log', '/app/logs/build.log')
+     * ```
+     *
+     * Sandboxes created before this shipped run a guest agent without it and throw
+     * `LizardError` (501) — recreate the sandbox to use it.
+     */
+    move(from: string, to: string): Promise<void>;
     private execInternal;
 }
 

package/dist/index.d.ts

@@ -25,7 +25,9 @@ interface ProcessOpts {
     envs?: Record<string, string>;
     user?: string;
     workdir?: string;
+    /** Called with each stdout line as it is produced, rather than at the end. */
     onStdout?: (data: string) => void;
+    /** Called with each stderr line as it is produced, rather than at the end. */
     onStderr?: (data: string) => void;
 }
 /**
@@ -62,6 +64,12 @@ declare class Process {
      * ```
      */
     exec(cmd: string, opts?: ProcessOpts): Promise<ProcessResult>;
+    /**
+     * Read an SSE exec stream, handing each line to the caller as it arrives while
+     * still accumulating the full result. Events are `{stream, line}` for output and
+     * `{exitCode}` at the end.
+     */
+    private consumeStream;
 }
 
 interface FsOpts {
@@ -70,8 +78,12 @@ interface FsOpts {
 interface FileInfo {
     name: string;
     path: string;
-    type: 'file' | 'dir';
+    type: 'file' | 'dir' | 'symlink';
     size: number;
+    /** Permission bits as a string, e.g. `-rw-r--r--`. Absent on older sandboxes. */
+    mode?: string;
+    /** Last modification time, unix milliseconds. Absent on older sandboxes. */
+    modTime?: number;
 }
 /**
  * Read and write files inside a Lizard sandbox microVM.
@@ -126,6 +138,35 @@ declare class Fs {
      * Create a directory (and any missing parents) inside the microVM.
      */
     makeDir(path: string, opts?: FsOpts): Promise<void>;
+    /**
+     * Metadata for a single path — size, type, permissions, modification time.
+     *
+     * Saves listing a parent directory and filtering it just to answer "does this
+     * exist, and how big is it".
+     *
+     * @example
+     * ```ts
+     * const info = await sandbox.fs.stat('/app/out.bin')
+     * console.log(info.size, info.type)
+     * ```
+     *
+     * Throws `NotFoundError` if the path does not exist. Sandboxes created before
+     * this shipped run a guest agent without it and throw `LizardError` (501) —
+     * recreate the sandbox to use it.
+     */
+    stat(path: string, opts?: FsOpts): Promise<FileInfo>;
+    /**
+     * Move or rename a path. Creates the destination's parent directories.
+     *
+     * @example
+     * ```ts
+     * await sandbox.fs.move('/tmp/build.log', '/app/logs/build.log')
+     * ```
+     *
+     * Sandboxes created before this shipped run a guest agent without it and throw
+     * `LizardError` (501) — recreate the sandbox to use it.
+     */
+    move(from: string, to: string): Promise<void>;
     private execInternal;
 }
 

package/dist/index.js

@@ -163,9 +163,10 @@ var Process = class {
    * ```
    */
   async exec(cmd, opts) {
+    const streaming = Boolean(opts?.onStdout || opts?.onStderr);
     const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/exec`, {
       method: "POST",
-      headers: this.config.headers,
+      headers: streaming ? { ...this.config.headers, Accept: "text/event-stream" } : this.config.headers,
       body: JSON.stringify({
         cmd,
         envs: opts?.envs,
@@ -176,7 +177,51 @@ var Process = class {
       signal: AbortSignal.timeout(opts?.timeoutMs ?? 6e4)
     });
     if (!res.ok) await handleApiError(res);
-    return res.json();
+    if (!streaming) return res.json();
+    return this.consumeStream(res, opts);
+  }
+  /**
+   * Read an SSE exec stream, handing each line to the caller as it arrives while
+   * still accumulating the full result. Events are `{stream, line}` for output and
+   * `{exitCode}` at the end.
+   */
+  async consumeStream(res, opts) {
+    const reader = res.body?.getReader();
+    if (!reader) return { stdout: "", stderr: "", exitCode: 0 };
+    const decoder = new TextDecoder();
+    let buf = "";
+    let stdout = "";
+    let stderr = "";
+    let exitCode = 0;
+    const handle = (raw) => {
+      if (!raw.startsWith("data:")) return;
+      let ev;
+      try {
+        ev = JSON.parse(raw.slice(5).trim());
+      } catch {
+        return;
+      }
+      if (ev.line !== void 0) {
+        if (ev.stream === "stderr") {
+          stderr += ev.line + "\n";
+          opts.onStderr?.(ev.line);
+        } else {
+          stdout += ev.line + "\n";
+          opts.onStdout?.(ev.line);
+        }
+      }
+      if (ev.exitCode !== void 0) exitCode = ev.exitCode;
+    };
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      const lines = buf.split("\n");
+      buf = lines.pop() ?? "";
+      for (const l of lines) handle(l);
+    }
+    if (buf) handle(buf);
+    return { stdout: stdout.trimEnd(), stderr: stderr.trimEnd(), exitCode };
   }
 };
 
@@ -261,6 +306,49 @@ var Fs = class {
   async makeDir(path, opts) {
     await this.execInternal(`mkdir -p ${JSON.stringify(path)}`, opts?.user);
   }
+  /**
+   * Metadata for a single path — size, type, permissions, modification time.
+   *
+   * Saves listing a parent directory and filtering it just to answer "does this
+   * exist, and how big is it".
+   *
+   * @example
+   * ```ts
+   * const info = await sandbox.fs.stat('/app/out.bin')
+   * console.log(info.size, info.type)
+   * ```
+   *
+   * Throws `NotFoundError` if the path does not exist. Sandboxes created before
+   * this shipped run a guest agent without it and throw `LizardError` (501) —
+   * recreate the sandbox to use it.
+   */
+  async stat(path, opts) {
+    const url = new URL(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files/stat`);
+    url.searchParams.set("path", path);
+    if (opts?.user) url.searchParams.set("user", opts.user);
+    const res = await fetch(url.toString(), { headers: this.config.headers });
+    if (!res.ok) await handleApiError(res);
+    return res.json();
+  }
+  /**
+   * Move or rename a path. Creates the destination's parent directories.
+   *
+   * @example
+   * ```ts
+   * await sandbox.fs.move('/tmp/build.log', '/app/logs/build.log')
+   * ```
+   *
+   * Sandboxes created before this shipped run a guest agent without it and throw
+   * `LizardError` (501) — recreate the sandbox to use it.
+   */
+  async move(from, to) {
+    const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files/move`, {
+      method: "POST",
+      headers: this.config.headers,
+      body: JSON.stringify({ from, to })
+    });
+    if (!res.ok) await handleApiError(res);
+  }
   async execInternal(cmd, user) {
     const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/exec`, {
       method: "POST",

package/dist/index.mjs

@@ -127,9 +127,10 @@ var Process = class {
    * ```
    */
   async exec(cmd, opts) {
+    const streaming = Boolean(opts?.onStdout || opts?.onStderr);
     const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/exec`, {
       method: "POST",
-      headers: this.config.headers,
+      headers: streaming ? { ...this.config.headers, Accept: "text/event-stream" } : this.config.headers,
       body: JSON.stringify({
         cmd,
         envs: opts?.envs,
@@ -140,7 +141,51 @@ var Process = class {
       signal: AbortSignal.timeout(opts?.timeoutMs ?? 6e4)
     });
     if (!res.ok) await handleApiError(res);
-    return res.json();
+    if (!streaming) return res.json();
+    return this.consumeStream(res, opts);
+  }
+  /**
+   * Read an SSE exec stream, handing each line to the caller as it arrives while
+   * still accumulating the full result. Events are `{stream, line}` for output and
+   * `{exitCode}` at the end.
+   */
+  async consumeStream(res, opts) {
+    const reader = res.body?.getReader();
+    if (!reader) return { stdout: "", stderr: "", exitCode: 0 };
+    const decoder = new TextDecoder();
+    let buf = "";
+    let stdout = "";
+    let stderr = "";
+    let exitCode = 0;
+    const handle = (raw) => {
+      if (!raw.startsWith("data:")) return;
+      let ev;
+      try {
+        ev = JSON.parse(raw.slice(5).trim());
+      } catch {
+        return;
+      }
+      if (ev.line !== void 0) {
+        if (ev.stream === "stderr") {
+          stderr += ev.line + "\n";
+          opts.onStderr?.(ev.line);
+        } else {
+          stdout += ev.line + "\n";
+          opts.onStdout?.(ev.line);
+        }
+      }
+      if (ev.exitCode !== void 0) exitCode = ev.exitCode;
+    };
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      const lines = buf.split("\n");
+      buf = lines.pop() ?? "";
+      for (const l of lines) handle(l);
+    }
+    if (buf) handle(buf);
+    return { stdout: stdout.trimEnd(), stderr: stderr.trimEnd(), exitCode };
   }
 };
 
@@ -225,6 +270,49 @@ var Fs = class {
   async makeDir(path, opts) {
     await this.execInternal(`mkdir -p ${JSON.stringify(path)}`, opts?.user);
   }
+  /**
+   * Metadata for a single path — size, type, permissions, modification time.
+   *
+   * Saves listing a parent directory and filtering it just to answer "does this
+   * exist, and how big is it".
+   *
+   * @example
+   * ```ts
+   * const info = await sandbox.fs.stat('/app/out.bin')
+   * console.log(info.size, info.type)
+   * ```
+   *
+   * Throws `NotFoundError` if the path does not exist. Sandboxes created before
+   * this shipped run a guest agent without it and throw `LizardError` (501) —
+   * recreate the sandbox to use it.
+   */
+  async stat(path, opts) {
+    const url = new URL(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files/stat`);
+    url.searchParams.set("path", path);
+    if (opts?.user) url.searchParams.set("user", opts.user);
+    const res = await fetch(url.toString(), { headers: this.config.headers });
+    if (!res.ok) await handleApiError(res);
+    return res.json();
+  }
+  /**
+   * Move or rename a path. Creates the destination's parent directories.
+   *
+   * @example
+   * ```ts
+   * await sandbox.fs.move('/tmp/build.log', '/app/logs/build.log')
+   * ```
+   *
+   * Sandboxes created before this shipped run a guest agent without it and throw
+   * `LizardError` (501) — recreate the sandbox to use it.
+   */
+  async move(from, to) {
+    const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files/move`, {
+      method: "POST",
+      headers: this.config.headers,
+      body: JSON.stringify({ from, to })
+    });
+    if (!res.ok) await handleApiError(res);
+  }
   async execInternal(cmd, user) {
     const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/exec`, {
       method: "POST",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lizard-build/sdk",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "description": "Firecracker microVM sandboxes for AI agents — boot Linux in milliseconds, run code, write files, expose ports over HTTPS, then pause a session with memory intact and resume it later. TypeScript SDK for Lizard Sandboxes (lizard.build).",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",