computesdk 1.12.0 → 1.13.0

package/dist/index.mjs

@@ -1845,6 +1845,87 @@ var Child = class {
   }
 };
 
+// src/client/resources/overlay.ts
+var Overlay = class {
+  constructor(handlers) {
+    this.createHandler = handlers.create;
+    this.listHandler = handlers.list;
+    this.retrieveHandler = handlers.retrieve;
+    this.destroyHandler = handlers.destroy;
+  }
+  /**
+   * Create a new overlay from a template directory
+   *
+   * The overlay symlinks files from the source directory into the target path,
+   * allowing instant access to template files. Heavy directories (node_modules,
+   * .venv, etc.) are copied in the background.
+   *
+   * @param options - Overlay creation options
+   * @param options.source - Absolute path to source directory
+   * @param options.target - Relative path in sandbox
+   * @returns Overlay info with copy status
+   */
+  async create(options) {
+    const response = await this.createHandler(options);
+    return this.toOverlayInfo(response);
+  }
+  /**
+   * List all overlays for the current sandbox
+   * @returns Array of overlay info
+   */
+  async list() {
+    const response = await this.listHandler();
+    return response.overlays.map((o) => this.toOverlayInfo(o));
+  }
+  /**
+   * Retrieve a specific overlay by ID
+   *
+   * Useful for polling the copy status of an overlay.
+   *
+   * @param id - Overlay ID
+   * @returns Overlay info
+   */
+  async retrieve(id) {
+    const response = await this.retrieveHandler(id);
+    return this.toOverlayInfo(response);
+  }
+  /**
+   * Destroy (delete) an overlay
+   * @param id - Overlay ID
+   */
+  async destroy(id) {
+    return this.destroyHandler(id);
+  }
+  /**
+   * Convert API response to OverlayInfo
+   */
+  toOverlayInfo(response) {
+    return {
+      id: response.id,
+      source: response.source,
+      target: response.target,
+      createdAt: response.created_at,
+      stats: {
+        symlinkedFiles: response.stats.symlinked_files,
+        symlinkedDirs: response.stats.symlinked_dirs,
+        skipped: response.stats.skipped
+      },
+      copyStatus: this.validateCopyStatus(response.copy_status),
+      copyError: response.copy_error
+    };
+  }
+  /**
+   * Validate and return copy status, defaulting to 'pending' for unknown values
+   */
+  validateCopyStatus(status) {
+    const validStatuses = ["pending", "in_progress", "complete", "failed"];
+    if (validStatuses.includes(status)) {
+      return status;
+    }
+    return "pending";
+  }
+};
+
 // src/client/types.ts
 var CommandExitError = class extends Error {
   constructor(result) {
@@ -1939,7 +2020,13 @@ var Sandbox = class {
       },
       remove: async (path) => {
         await this.deleteFile(path);
-      }
+      },
+      overlay: new Overlay({
+        create: async (options) => this.createOverlay(options),
+        list: async () => this.listOverlays(),
+        retrieve: async (id) => this.getOverlay(id),
+        destroy: async (id) => this.deleteOverlay(id)
+      })
     };
     this.terminal = new Terminal({
       create: async (options) => this.createTerminal(options),
@@ -2424,6 +2511,63 @@ API request failed (${response.status}): ${error}`
     });
   }
   // ============================================================================
+  // Filesystem Overlays
+  // ============================================================================
+  /**
+   * Create a new filesystem overlay from a template directory
+   *
+   * Overlays enable instant sandbox setup by symlinking template files first,
+   * then copying heavy directories (node_modules, .venv, etc.) in the background.
+   *
+   * @param options - Overlay creation options
+   * @param options.source - Absolute path to source directory (template)
+   * @param options.target - Relative path in sandbox where overlay will be mounted
+   * @returns Overlay response with copy status
+   *
+   * @example
+   * ```typescript
+   * // Prefer using sandbox.filesystem.overlay.create() for camelCase response
+   * const overlay = await sandbox.filesystem.overlay.create({
+   *   source: '/templates/nextjs',
+   *   target: 'project',
+   * });
+   * console.log(overlay.copyStatus); // 'pending' | 'in_progress' | 'complete' | 'failed'
+   * ```
+   */
+  async createOverlay(options) {
+    return this.request("/filesystem/overlays", {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+  }
+  /**
+   * List all filesystem overlays for the current sandbox
+   * @returns List of overlays with their copy status
+   */
+  async listOverlays() {
+    return this.request("/filesystem/overlays");
+  }
+  /**
+   * Get a specific filesystem overlay by ID
+   *
+   * Useful for polling the copy status of an overlay.
+   *
+   * @param id - Overlay ID
+   * @returns Overlay details with current copy status
+   */
+  async getOverlay(id) {
+    return this.request(`/filesystem/overlays/${id}`);
+  }
+  /**
+   * Delete a filesystem overlay
+   * @param id - Overlay ID
+   */
+  async deleteOverlay(id) {
+    return this.request(`/filesystem/overlays/${id}`, {
+      method: "DELETE"
+    });
+  }
+  // ============================================================================
   // Terminal Management
   // ============================================================================
   /**