instavm 0.13.0 → 0.15.0

package/dist/cli.js

@@ -0,0 +1,3446 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cli.ts
+var cli_exports = {};
+__export(cli_exports, {
+  createProgram: () => createProgram,
+  runCli: () => runCli
+});
+module.exports = __toCommonJS(cli_exports);
+var import_fs3 = __toESM(require("fs"));
+var import_path12 = __toESM(require("path"));
+var import_child_process = require("child_process");
+var import_commander = require("commander");
+
+// src/client/HTTPClient.ts
+var import_axios = __toESM(require("axios"));
+
+// src/errors/BaseError.ts
+var InstaVMError = class extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = options?.code;
+    this.statusCode = options?.statusCode;
+    this.response = options?.response;
+    Object.setPrototypeOf(this, new.target.prototype);
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var AuthenticationError = class extends InstaVMError {
+  constructor(message = "Authentication failed", options) {
+    super(message, { ...options, statusCode: 401 });
+  }
+};
+var RateLimitError = class extends InstaVMError {
+  constructor(message = "Rate limit exceeded", retryAfter, options) {
+    super(message, { ...options, statusCode: 429 });
+    this.retryAfter = retryAfter;
+  }
+};
+var QuotaExceededError = class extends InstaVMError {
+  constructor(message = "Usage quota exceeded", options) {
+    super(message, { ...options, statusCode: 402 });
+  }
+};
+var NetworkError = class extends InstaVMError {
+  constructor(message = "Network error", options) {
+    super(message, options);
+  }
+};
+var ExecutionError = class extends InstaVMError {
+  constructor(message, executionOutput, executionTime, options) {
+    super(message, options);
+    this.executionOutput = executionOutput;
+    this.executionTime = executionTime;
+  }
+};
+var SessionError = class extends InstaVMError {
+  constructor(message = "Session error", options) {
+    super(message, options);
+  }
+};
+var BrowserError = class extends InstaVMError {
+  constructor(message = "Browser error", options) {
+    super(message, options);
+  }
+};
+var BrowserSessionError = class extends BrowserError {
+  constructor(message = "Browser session error", options) {
+    super(message, options);
+  }
+};
+var BrowserInteractionError = class extends BrowserError {
+  constructor(message = "Browser interaction error", options) {
+    super(message, options);
+  }
+};
+var BrowserTimeoutError = class extends BrowserError {
+  constructor(message = "Browser operation timed out", options) {
+    super(message, options);
+  }
+};
+var BrowserNavigationError = class extends BrowserError {
+  constructor(message = "Browser navigation error", options) {
+    super(message, options);
+  }
+};
+var ElementNotFoundError = class extends BrowserError {
+  constructor(message = "Element not found", selector, options) {
+    super(message, options);
+    this.selector = selector;
+  }
+};
+var UnsupportedOperationError = class extends InstaVMError {
+  constructor(message = "Operation not supported", options) {
+    super(message, options);
+  }
+};
+
+// src/utils/retry.ts
+function defaultRetryCondition(error) {
+  if (error instanceof NetworkError) return true;
+  if (error instanceof RateLimitError) return true;
+  if (error.response?.status >= 500) return true;
+  if (error.code === "ECONNABORTED" || error.code === "ETIMEDOUT") return true;
+  if (error.code === "ECONNRESET" || error.code === "ENOTFOUND") return true;
+  return false;
+}
+function calculateRetryDelay(attempt, baseDelay, maxDelay = 3e4) {
+  const exponentialDelay = baseDelay * Math.pow(2, attempt - 1);
+  const jitteredDelay = exponentialDelay * (0.5 + Math.random() * 0.5);
+  return Math.min(jitteredDelay, maxDelay);
+}
+async function withRetry(fn, options) {
+  const {
+    retries,
+    retryDelay,
+    maxRetryDelay = 3e4,
+    retryCondition = defaultRetryCondition
+  } = options;
+  let lastError;
+  for (let attempt = 1; attempt <= retries + 1; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (attempt === retries + 1) {
+        break;
+      }
+      if (!retryCondition(error)) {
+        break;
+      }
+      const delay = calculateRetryDelay(attempt, retryDelay, maxRetryDelay);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+  throw lastError;
+}
+
+// src/client/HTTPClient.ts
+var HTTPClient = class {
+  get apiKey() {
+    return this.config.apiKey;
+  }
+  constructor(config) {
+    this.config = config;
+    this.client = import_axios.default.create({
+      baseURL: config.baseURL,
+      timeout: config.timeout,
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": "instavm-js-sdk/0.15.0"
+      }
+    });
+    this.setupInterceptors();
+  }
+  setupInterceptors() {
+    this.client.interceptors.request.use(
+      (config) => {
+        if (config.url?.includes("/browser/")) {
+          config.headers["X-API-Key"] = this.config.apiKey;
+        }
+        return config;
+      },
+      (error) => Promise.reject(error)
+    );
+    this.client.interceptors.response.use(
+      (response) => response,
+      (error) => {
+        const axiosError = error;
+        const status = axiosError.response?.status;
+        const data = axiosError.response?.data;
+        const message = data?.message || data?.error || data?.detail || axiosError.message;
+        switch (status) {
+          case 401:
+            throw new AuthenticationError(message, {
+              statusCode: status,
+              response: data
+            });
+          case 402:
+            throw new QuotaExceededError(message, {
+              statusCode: status,
+              response: data
+            });
+          case 429: {
+            const retryAfter = parseInt(
+              axiosError.response?.headers["retry-after"] || "60"
+            );
+            const rateLimitMessage = data?.detail || message;
+            throw new RateLimitError(rateLimitMessage, retryAfter, {
+              statusCode: status,
+              response: data
+            });
+          }
+          case 500:
+          case 502:
+          case 503:
+          case 504:
+            throw new NetworkError(message, {
+              statusCode: status,
+              response: data
+            });
+          default:
+            if (axiosError.code === "ECONNABORTED") {
+              throw new NetworkError("Request timeout", {
+                code: axiosError.code
+              });
+            }
+            throw new InstaVMError(message, {
+              statusCode: status,
+              response: data,
+              code: axiosError.code
+            });
+        }
+      }
+    );
+  }
+  /**
+   * Make an HTTP request with retry logic
+   */
+  async request(requestConfig) {
+    const axiosConfig = {
+      method: requestConfig.method,
+      url: requestConfig.url,
+      headers: requestConfig.headers,
+      data: requestConfig.data,
+      params: requestConfig.params,
+      timeout: requestConfig.timeout || this.config.timeout
+    };
+    const makeRequest = async () => {
+      const response = await this.client.request(axiosConfig);
+      return response.data;
+    };
+    return withRetry(makeRequest, {
+      retries: this.config.maxRetries,
+      retryDelay: this.config.retryDelay
+    });
+  }
+  /**
+   * POST request with JSON body
+   */
+  async post(url, data, headers, timeout) {
+    return this.request({
+      method: "POST",
+      url,
+      data,
+      headers,
+      timeout
+    });
+  }
+  /**
+   * POST request for code execution (uses X-API-Key header like Python client)
+   */
+  async postExecution(url, data, headers, timeout) {
+    const requestHeaders = {
+      "X-API-Key": this.config.apiKey,
+      ...headers
+    };
+    return this.request({
+      method: "POST",
+      url,
+      data,
+      headers: requestHeaders,
+      timeout
+    });
+  }
+  /**
+   * POST request with form data (for file uploads)
+   */
+  async postFormData(url, formData, headers) {
+    const requestHeaders = {
+      "X-API-Key": this.config.apiKey,
+      ...formData.getHeaders(),
+      ...headers
+    };
+    return this.request({
+      method: "POST",
+      url,
+      data: formData,
+      headers: requestHeaders
+    });
+  }
+  /**
+   * POST request with URL-encoded form data (like Python requests data= parameter)
+   */
+  async postFormUrlEncoded(url, data, headers) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(data)) {
+      params.append(key, String(value));
+    }
+    const requestHeaders = {
+      "X-API-Key": this.config.apiKey,
+      "Content-Type": "application/x-www-form-urlencoded",
+      ...headers
+    };
+    return this.request({
+      method: "POST",
+      url,
+      data: params.toString(),
+      headers: requestHeaders
+    });
+  }
+  /**
+   * GET request
+   */
+  async get(url, params, headers) {
+    return this.request({
+      method: "GET",
+      url,
+      params,
+      headers
+    });
+  }
+  /**
+   * DELETE request
+   */
+  async delete(url, headers) {
+    return this.request({
+      method: "DELETE",
+      url,
+      headers
+    });
+  }
+  /**
+   * PUT request
+   */
+  async put(url, data, headers) {
+    return this.request({
+      method: "PUT",
+      url,
+      data,
+      headers
+    });
+  }
+  /**
+   * PATCH request
+   */
+  async patch(url, data, headers) {
+    return this.request({
+      method: "PATCH",
+      url,
+      data,
+      headers
+    });
+  }
+  /**
+   * OPTIONS request
+   */
+  async options(url, headers, params) {
+    return this.request({
+      method: "OPTIONS",
+      url,
+      headers,
+      params
+    });
+  }
+  /**
+   * POST request that returns raw binary data (for file downloads)
+   */
+  async postRaw(url, data, headers) {
+    const requestHeaders = {
+      "X-API-Key": this.config.apiKey,
+      ...headers
+    };
+    const axiosConfig = {
+      method: "POST",
+      url,
+      data,
+      headers: requestHeaders,
+      responseType: "arraybuffer",
+      timeout: this.config.timeout
+    };
+    const makeRequest = async () => {
+      const response = await this.client.request(axiosConfig);
+      return response.data;
+    };
+    return withRetry(makeRequest, {
+      retries: this.config.maxRetries,
+      retryDelay: this.config.retryDelay
+    });
+  }
+};
+
+// src/client/BrowserSession.ts
+var import_eventemitter3 = require("eventemitter3");
+function getErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+var BrowserSession = class extends import_eventemitter3.EventEmitter {
+  constructor(sessionId, httpClient) {
+    super();
+    this._isActive = true;
+    this.sessionId = sessionId;
+    this.httpClient = httpClient;
+  }
+  /**
+   * Navigate to a URL
+   */
+  async navigate(url, options = {}) {
+    this.ensureActive();
+    const requestData = {
+      url,
+      session_id: this.sessionId,
+      wait_timeout: options.waitTimeout || 3e4,
+      wait_until: options.waitUntil || "load"
+    };
+    try {
+      const response = await this.httpClient.post(
+        "/v1/browser/interactions/navigate",
+        requestData
+      );
+      const result = {
+        success: response.success !== false,
+        url: response.url || url,
+        title: response.title,
+        status: response.status
+      };
+      this.emit("navigation", result);
+      return result;
+    } catch (error) {
+      const navigationError = new BrowserNavigationError(
+        `Navigation failed: ${getErrorMessage(error)}`,
+        { cause: error }
+      );
+      this.emit("error", navigationError);
+      throw navigationError;
+    }
+  }
+  /**
+   * Click an element
+   */
+  async click(selector, options = {}) {
+    this.ensureActive();
+    const requestData = {
+      selector,
+      session_id: this.sessionId,
+      timeout: options.timeout || 1e4,
+      button: options.button || "left",
+      click_count: options.clickCount || 1,
+      force: options.force || false
+    };
+    try {
+      await this.httpClient.post(
+        "/v1/browser/interactions/click",
+        requestData
+      );
+    } catch (error) {
+      const errorMessage = getErrorMessage(error);
+      if (errorMessage.includes("not found") || errorMessage.includes("selector")) {
+        throw new ElementNotFoundError(
+          `Element not found: ${selector}`,
+          selector,
+          { cause: error }
+        );
+      }
+      if (errorMessage.includes("timeout")) {
+        throw new BrowserTimeoutError(
+          `Click timeout: ${selector}`,
+          { cause: error }
+        );
+      }
+      throw new BrowserInteractionError(
+        `Click failed: ${errorMessage}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Type text into an element
+   */
+  async type(selector, text, options = {}) {
+    this.ensureActive();
+    const requestData = {
+      selector,
+      text,
+      session_id: this.sessionId,
+      timeout: options.timeout || 1e4,
+      delay: options.delay || 0,
+      clear: options.clear !== false
+    };
+    try {
+      await this.httpClient.post(
+        "/v1/browser/interactions/type",
+        requestData
+      );
+    } catch (error) {
+      const errorMessage = getErrorMessage(error);
+      if (errorMessage.includes("not found") || errorMessage.includes("selector")) {
+        throw new ElementNotFoundError(
+          `Element not found: ${selector}`,
+          selector,
+          { cause: error }
+        );
+      }
+      throw new BrowserInteractionError(
+        `Type failed: ${errorMessage}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Fill a form field
+   */
+  async fill(selector, value, options = {}) {
+    this.ensureActive();
+    const requestData = {
+      selector,
+      value,
+      session_id: this.sessionId,
+      timeout: options.timeout || 1e4,
+      force: options.force || false
+    };
+    try {
+      await this.httpClient.post(
+        "/v1/browser/interactions/fill",
+        requestData
+      );
+    } catch (error) {
+      const errorMessage = getErrorMessage(error);
+      if (errorMessage.includes("not found") || errorMessage.includes("selector")) {
+        throw new ElementNotFoundError(
+          `Element not found: ${selector}`,
+          selector,
+          { cause: error }
+        );
+      }
+      throw new BrowserInteractionError(
+        `Fill failed: ${errorMessage}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Scroll the page
+   */
+  async scroll(options = {}) {
+    this.ensureActive();
+    const requestData = {
+      session_id: this.sessionId,
+      x: options.x || 0,
+      y: options.y || 500,
+      behavior: options.behavior || "auto"
+    };
+    try {
+      await this.httpClient.post(
+        "/v1/browser/interactions/scroll",
+        requestData
+      );
+    } catch (error) {
+      throw new BrowserInteractionError(
+        `Scroll failed: ${getErrorMessage(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Take a screenshot
+   */
+  async screenshot(options = {}) {
+    this.ensureActive();
+    const requestData = {
+      session_id: this.sessionId,
+      full_page: options.fullPage !== false,
+      format: options.format || "png",
+      quality: options.quality || 90,
+      clip: options.clip
+    };
+    try {
+      const response = await this.httpClient.post(
+        "/v1/browser/interactions/screenshot",
+        requestData
+      );
+      if (!response.screenshot) {
+        throw new BrowserError("Screenshot data not returned");
+      }
+      return response.screenshot;
+    } catch (error) {
+      throw new BrowserInteractionError(
+        `Screenshot failed: ${getErrorMessage(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Extract elements from the page
+   */
+  async extractElements(selector, attributes = ["text"], options = {}) {
+    this.ensureActive();
+    const requestData = {
+      selector,
+      attributes,
+      session_id: this.sessionId,
+      max_results: options.maxResults || 100
+    };
+    try {
+      const response = await this.httpClient.post(
+        "/v1/browser/interactions/extract",
+        requestData
+      );
+      return response.elements || [];
+    } catch (error) {
+      throw new BrowserInteractionError(
+        `Element extraction failed: ${getErrorMessage(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Extract LLM-friendly content from the current page
+   *
+   * Returns clean article content, interactive elements, and content anchors
+   * for intelligent browser automation with LLMs.
+   *
+   * @param options - Content extraction options
+   * @returns Extracted content with readable text, interactive elements, and content anchors
+   *
+   * @example
+   * ```typescript
+   * const content = await session.extractContent();
+   *
+   * // LLM reads clean content
+   * const article = content.readableContent.content;
+   *
+   * // LLM finds "Sign Up" in content and uses anchors to get selector
+   * const signUpAnchor = content.contentAnchors?.find(
+   *   anchor => anchor.text.toLowerCase().includes('sign up')
+   * );
+   * if (signUpAnchor) {
+   *   await session.click(signUpAnchor.selector);
+   * }
+   * ```
+   */
+  async extractContent(options = {}) {
+    this.ensureActive();
+    const requestData = {
+      session_id: this.sessionId,
+      include_interactive: options.includeInteractive !== false,
+      include_anchors: options.includeAnchors !== false,
+      max_anchors: options.maxAnchors ?? 50
+    };
+    try {
+      const response = await this.httpClient.post(
+        "/v1/browser/interactions/content",
+        requestData
+      );
+      return {
+        readableContent: {
+          ...response.readable_content || {},
+          content: response.readable_content?.content || ""
+        },
+        interactiveElements: response.interactive_elements,
+        contentAnchors: response.content_anchors
+      };
+    } catch (error) {
+      throw new BrowserInteractionError(
+        `Content extraction failed: ${getErrorMessage(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Wait for a condition
+   */
+  async wait(condition, timeout = 1e4) {
+    this.ensureActive();
+    let requestData = {
+      session_id: this.sessionId,
+      timeout
+    };
+    if (condition.type === "timeout") {
+      await new Promise((resolve) => setTimeout(resolve, condition.ms));
+      return;
+    }
+    requestData = {
+      ...requestData,
+      condition: condition.type,
+      selector: "selector" in condition ? condition.selector : void 0
+    };
+    try {
+      await this.httpClient.post(
+        "/v1/browser/interactions/wait",
+        requestData
+      );
+    } catch (error) {
+      const errorMessage = getErrorMessage(error);
+      if (errorMessage.includes("timeout")) {
+        throw new BrowserTimeoutError(
+          `Wait condition timeout: ${condition.type}`,
+          { cause: error }
+        );
+      }
+      throw new BrowserInteractionError(
+        `Wait failed: ${errorMessage}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Close the browser session
+   */
+  async close() {
+    if (!this._isActive) {
+      return;
+    }
+    try {
+      await this.httpClient.delete(`/v1/browser/sessions/${this.sessionId}`);
+    } catch (error) {
+      console.warn(`Failed to close browser session ${this.sessionId}:`, getErrorMessage(error));
+    } finally {
+      this._isActive = false;
+      this.emit("close");
+    }
+  }
+  /**
+   * Check if session is active
+   */
+  get isActive() {
+    return this._isActive;
+  }
+  /**
+   * Ensure session is active before operations
+   */
+  ensureActive() {
+    if (!this._isActive) {
+      throw new BrowserError("Browser session is not active");
+    }
+  }
+};
+
+// src/client/BrowserManager.ts
+var BrowserManager = class {
+  constructor(httpClient, local = false) {
+    this.activeSessions = /* @__PURE__ */ new Map();
+    this.httpClient = httpClient;
+    this.local = local;
+  }
+  /**
+   * Create a new browser session
+   */
+  async createSession(options = {}) {
+    if (this.local) {
+      throw new UnsupportedOperationError(
+        "Browser session management is not supported in local mode. Use navigate() or extractContent() with URL directly."
+      );
+    }
+    const requestData = {
+      viewport_width: options.viewportWidth || 1920,
+      viewport_height: options.viewportHeight || 1080,
+      user_agent: options.userAgent
+    };
+    try {
+      const response = await this.httpClient.post(
+        "/v1/browser/sessions/",
+        requestData
+      );
+      if (!response.session_id) {
+        throw new BrowserSessionError("No session ID returned from server");
+      }
+      const session = new BrowserSession(response.session_id, this.httpClient);
+      this.activeSessions.set(response.session_id, session);
+      session.on("close", () => {
+        this.activeSessions.delete(response.session_id);
+      });
+      return session;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new BrowserSessionError(
+        `Failed to create browser session: ${errorMessage}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Get information about a specific session
+   */
+  async getSession(sessionId) {
+    try {
+      const response = await this.httpClient.get(
+        `/v1/browser/sessions/${sessionId}`
+      );
+      return {
+        sessionId: response.session_id,
+        status: response.status || "active",
+        createdAt: response.created_at,
+        viewportWidth: response.viewport_width,
+        viewportHeight: response.viewport_height,
+        userAgent: response.user_agent
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new BrowserSessionError(
+        `Failed to get session info: ${errorMessage}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * List all browser sessions
+   */
+  async listSessions() {
+    try {
+      const response = await this.httpClient.get("/v1/browser/sessions/");
+      if (!Array.isArray(response.sessions)) {
+        return [];
+      }
+      return response.sessions.map((session) => ({
+        sessionId: session.session_id,
+        status: session.status || "active",
+        createdAt: session.created_at,
+        viewportWidth: session.viewport_width,
+        viewportHeight: session.viewport_height,
+        userAgent: session.user_agent
+      }));
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new BrowserSessionError(
+        `Failed to list sessions: ${errorMessage}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Get a locally tracked session
+   */
+  getLocalSession(sessionId) {
+    return this.activeSessions.get(sessionId);
+  }
+  /**
+   * Get all locally tracked sessions
+   */
+  getLocalSessions() {
+    return Array.from(this.activeSessions.values());
+  }
+  /**
+   * Close all active sessions
+   */
+  async closeAllSessions() {
+    const sessions = Array.from(this.activeSessions.values());
+    await Promise.allSettled(
+      sessions.map((session) => session.close())
+    );
+    this.activeSessions.clear();
+  }
+  /**
+   * Navigate to a URL (local mode support - no session required)
+   */
+  async navigate(url, options = {}) {
+    if (!this.local) {
+      throw new UnsupportedOperationError(
+        "navigate() without session is only supported in local mode. In cloud mode, create a session first."
+      );
+    }
+    const requestData = {
+      url,
+      wait_timeout: options.waitTimeout || 3e4
+    };
+    try {
+      const response = await this.httpClient.post(
+        "/v1/browser/interactions/navigate",
+        requestData
+      );
+      return {
+        success: response.success !== false,
+        url: response.url || url,
+        title: response.title,
+        status: response.status
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new BrowserNavigationError(
+        `Navigation failed: ${errorMessage}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Extract LLM-friendly content (local mode support - no session required)
+   */
+  async extractContent(options = {}) {
+    if (!this.local) {
+      throw new UnsupportedOperationError(
+        "extractContent() without session is only supported in local mode. In cloud mode, create a session first."
+      );
+    }
+    if (!options.url) {
+      throw new BrowserInteractionError("url is required in local mode");
+    }
+    const requestData = {
+      url: options.url,
+      include_interactive: options.includeInteractive !== false,
+      include_anchors: options.includeAnchors !== false,
+      max_anchors: options.maxAnchors ?? 50
+    };
+    try {
+      const response = await this.httpClient.post(
+        "/v1/browser/interactions/content",
+        requestData
+      );
+      return {
+        readableContent: {
+          ...response.readable_content || {},
+          content: response.readable_content?.content || ""
+        },
+        interactiveElements: response.interactive_elements,
+        contentAnchors: response.content_anchors
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new BrowserInteractionError(
+        `Content extraction failed: ${errorMessage}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Clean up resources
+   */
+  async dispose() {
+    await this.closeAllSessions();
+  }
+};
+
+// src/utils/path.ts
+function encodePathSegment(value) {
+  const segment = String(value);
+  if (segment === "." || segment === "..") {
+    throw new Error("Path traversal not allowed in path segment");
+  }
+  return encodeURIComponent(segment);
+}
+function encodePathSegments(path4) {
+  const segments = path4.replace(/^\/+/, "").split("/").filter((segment) => segment.length > 0 && segment !== ".");
+  if (segments.some((segment) => segment === "..")) {
+    throw new Error("Path traversal not allowed in proxy path");
+  }
+  return segments.map((segment) => encodeURIComponent(segment)).join("/");
+}
+
+// src/client/VMsManager.ts
+var VMsManager = class {
+  constructor(httpClient, local = false) {
+    this.httpClient = httpClient;
+    this.local = local;
+  }
+  ensureCloud(operation) {
+    if (this.local) {
+      throw new UnsupportedOperationError(
+        `${operation} is not supported in local mode.`
+      );
+    }
+  }
+  async create(payload = {}, wait = true) {
+    this.ensureCloud("VM creation");
+    return this.httpClient.request({
+      method: "POST",
+      url: "/v1/vms",
+      params: { wait },
+      data: payload,
+      headers: { "X-API-Key": this.httpClient.apiKey }
+    });
+  }
+  async list() {
+    this.ensureCloud("VM listing");
+    return this.httpClient.get(
+      "/v1/vms",
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async listAll() {
+    return this.listAllRecords();
+  }
+  /**
+   * Calls GET /v1/vms/ (trailing slash), a distinct route from GET /v1/vms.
+   */
+  async listAllRecords() {
+    this.ensureCloud("VM listing");
+    return this.httpClient.get(
+      "/v1/vms/",
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async get(itemId) {
+    this.ensureCloud("VM lookup");
+    const safeItemId = encodePathSegment(itemId);
+    return this.httpClient.get(
+      `/v1/vms/${safeItemId}`,
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async update(vmId, payload = {}) {
+    this.ensureCloud("VM update");
+    const safeVmId = encodePathSegment(vmId);
+    return this.httpClient.patch(
+      `/v1/vms/${safeVmId}`,
+      payload,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async delete(vmId) {
+    this.ensureCloud("VM deletion");
+    const safeVmId = encodePathSegment(vmId);
+    return this.httpClient.delete(
+      `/v1/vms/${safeVmId}`,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async clone(vmId, payload = {}, wait = true) {
+    this.ensureCloud("VM clone");
+    const safeVmId = encodePathSegment(vmId);
+    return this.httpClient.request({
+      method: "POST",
+      url: `/v1/vms/${safeVmId}/clone`,
+      params: { wait },
+      data: payload,
+      headers: { "X-API-Key": this.httpClient.apiKey }
+    });
+  }
+  async snapshot(vmId, payload = {}, wait = true) {
+    this.ensureCloud("VM snapshot");
+    const safeVmId = encodePathSegment(vmId);
+    return this.httpClient.request({
+      method: "POST",
+      url: `/v1/vms/${safeVmId}/snapshot`,
+      params: { wait },
+      data: payload,
+      headers: { "X-API-Key": this.httpClient.apiKey }
+    });
+  }
+  async mountVolume(vmId, payload, wait = true) {
+    this.ensureCloud("VM volume mount");
+    const safeVmId = encodePathSegment(vmId);
+    return this.httpClient.request({
+      method: "POST",
+      url: `/v1/vms/${safeVmId}/volumes`,
+      params: { wait },
+      data: payload,
+      headers: { "X-API-Key": this.httpClient.apiKey }
+    });
+  }
+  async listVolumes(vmId) {
+    this.ensureCloud("VM volume listing");
+    const safeVmId = encodePathSegment(vmId);
+    return this.httpClient.get(
+      `/v1/vms/${safeVmId}/volumes`,
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async unmountVolume(vmId, volumeId, mountPath, wait = true) {
+    this.ensureCloud("VM volume unmount");
+    const safeVmId = encodePathSegment(vmId);
+    const safeVolumeId = encodePathSegment(volumeId);
+    return this.httpClient.request({
+      method: "DELETE",
+      url: `/v1/vms/${safeVmId}/volumes/${safeVolumeId}`,
+      params: { mount_path: mountPath, wait },
+      headers: { "X-API-Key": this.httpClient.apiKey }
+    });
+  }
+};
+
+// src/client/SnapshotsManager.ts
+var SnapshotsManager = class {
+  constructor(httpClient, local = false) {
+    this.httpClient = httpClient;
+    this.local = local;
+  }
+  ensureCloud(operation) {
+    if (this.local) {
+      throw new UnsupportedOperationError(
+        `${operation} is not supported in local mode.`
+      );
+    }
+  }
+  async create(payload) {
+    this.ensureCloud("Snapshot creation");
+    return this.httpClient.post(
+      "/v1/snapshots",
+      payload,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async list(options = {}) {
+    this.ensureCloud("Snapshot listing");
+    return this.httpClient.get(
+      "/v1/snapshots",
+      options,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async get(snapshotId) {
+    this.ensureCloud("Snapshot lookup");
+    const safeSnapshotId = encodePathSegment(snapshotId);
+    return this.httpClient.get(
+      `/v1/snapshots/${safeSnapshotId}`,
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async delete(snapshotId) {
+    this.ensureCloud("Snapshot deletion");
+    const safeSnapshotId = encodePathSegment(snapshotId);
+    return this.httpClient.delete(
+      `/v1/snapshots/${safeSnapshotId}`,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+};
+
+// src/client/SharesManager.ts
+var SharesManager = class {
+  constructor(httpClient, local = false, getSessionId = () => null) {
+    this.httpClient = httpClient;
+    this.local = local;
+    this.getSessionId = getSessionId;
+  }
+  ensureCloud(operation) {
+    if (this.local) {
+      throw new UnsupportedOperationError(
+        `${operation} is not supported in local mode.`
+      );
+    }
+  }
+  async create(payload) {
+    this.ensureCloud("Share creation");
+    const body = { ...payload };
+    if (!body.session_id && !body.vm_id) {
+      const sid = this.getSessionId();
+      if (!sid) {
+        throw new SessionError(
+          "Provide session_id/vm_id or create a session before creating a share."
+        );
+      }
+      body.session_id = sid;
+    }
+    return this.httpClient.post(
+      "/v1/shares",
+      body,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async update(shareId, payload) {
+    this.ensureCloud("Share update");
+    const safeShareId = encodePathSegment(shareId);
+    return this.httpClient.patch(
+      `/v1/shares/${safeShareId}`,
+      payload,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+};
+
+// src/client/CustomDomainsManager.ts
+var CustomDomainsManager = class {
+  constructor(httpClient, local = false) {
+    this.httpClient = httpClient;
+    this.local = local;
+  }
+  ensureCloud(operation) {
+    if (this.local) {
+      throw new UnsupportedOperationError(
+        `${operation} is not supported in local mode.`
+      );
+    }
+  }
+  async create(payload) {
+    this.ensureCloud("Custom domain creation");
+    return this.httpClient.post(
+      "/v1/custom-domains",
+      payload,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async list() {
+    this.ensureCloud("Custom domain listing");
+    return this.httpClient.get(
+      "/v1/custom-domains",
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async health(domainId) {
+    this.ensureCloud("Custom domain health");
+    const safeDomainId = encodePathSegment(domainId);
+    return this.httpClient.get(
+      `/v1/custom-domains/${safeDomainId}/health`,
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async verify(domainId) {
+    this.ensureCloud("Custom domain verification");
+    const safeDomainId = encodePathSegment(domainId);
+    return this.httpClient.post(
+      `/v1/custom-domains/${safeDomainId}/verify`,
+      {},
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async delete(domainId) {
+    this.ensureCloud("Custom domain deletion");
+    const safeDomainId = encodePathSegment(domainId);
+    return this.httpClient.delete(
+      `/v1/custom-domains/${safeDomainId}`,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+};
+
+// src/client/ComputerUseManager.ts
+var ComputerUseManager = class {
+  constructor(httpClient, local = false) {
+    this.httpClient = httpClient;
+    this.local = local;
+  }
+  ensureCloud(operation) {
+    if (this.local) {
+      throw new UnsupportedOperationError(
+        `${operation} is not supported in local mode.`
+      );
+    }
+  }
+  async viewerUrl(sessionId) {
+    this.ensureCloud("Computer-use viewer URL");
+    const safeSessionId = encodePathSegment(sessionId);
+    return this.httpClient.get(
+      `/v1/computeruse/${safeSessionId}/viewer-url`,
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async proxy(sessionId, path4, method = "GET", options = {}) {
+    this.ensureCloud("Computer-use proxy");
+    const safeSessionId = encodePathSegment(sessionId);
+    const cleanPath = encodePathSegments(path4);
+    return this.httpClient.request({
+      method,
+      url: `/v1/computeruse/${safeSessionId}/${cleanPath}`,
+      params: options.params,
+      data: options.body,
+      headers: { "X-API-Key": this.httpClient.apiKey }
+    });
+  }
+  async get(sessionId, path4, params) {
+    return this.proxy(sessionId, path4, "GET", { params });
+  }
+  async post(sessionId, path4, body) {
+    return this.proxy(sessionId, path4, "POST", { body });
+  }
+  async put(sessionId, path4, body) {
+    return this.proxy(sessionId, path4, "PUT", { body });
+  }
+  async patch(sessionId, path4, body) {
+    return this.proxy(sessionId, path4, "PATCH", { body });
+  }
+  async delete(sessionId, path4, params) {
+    return this.proxy(sessionId, path4, "DELETE", { params });
+  }
+  async options(sessionId, path4, params) {
+    return this.proxy(sessionId, path4, "OPTIONS", { params });
+  }
+  async head(sessionId, path4, params) {
+    return this.proxy(sessionId, path4, "HEAD", { params });
+  }
+  /**
+   * Get the VNC WebSocket URL for a computer-use session.
+   * Returns the URL to connect to; the actual connection requires a WebSocket client.
+   */
+  async vncWebsockify(sessionId) {
+    this.ensureCloud("Computer-use VNC websockify");
+    const safeSessionId = encodePathSegment(sessionId);
+    return this.httpClient.get(
+      `/v1/computeruse/${safeSessionId}/vnc/websockify`,
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+};
+
+// src/client/APIKeysManager.ts
+var APIKeysManager = class {
+  constructor(httpClient, local = false) {
+    this.httpClient = httpClient;
+    this.local = local;
+  }
+  ensureCloud(operation) {
+    if (this.local) {
+      throw new UnsupportedOperationError(
+        `${operation} is not supported in local mode.`
+      );
+    }
+  }
+  async create(payload = {}) {
+    this.ensureCloud("API key creation");
+    return this.httpClient.post(
+      "/v1/api-keys/",
+      payload,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async list() {
+    this.ensureCloud("API key listing");
+    return this.httpClient.get(
+      "/v1/api-keys/",
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async get(itemId) {
+    this.ensureCloud("API key lookup");
+    const safeItemId = encodePathSegment(itemId);
+    return this.httpClient.get(
+      `/v1/api-keys/${safeItemId}`,
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async update(itemId, payload) {
+    this.ensureCloud("API key update");
+    const safeItemId = encodePathSegment(itemId);
+    return this.httpClient.patch(
+      `/v1/api-keys/${safeItemId}`,
+      payload,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async delete(itemId) {
+    this.ensureCloud("API key deletion");
+    const safeItemId = encodePathSegment(itemId);
+    return this.httpClient.delete(
+      `/v1/api-keys/${safeItemId}`,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+};
+
+// src/client/AuditManager.ts
+var AuditManager = class {
+  constructor(httpClient, local = false) {
+    this.httpClient = httpClient;
+    this.local = local;
+  }
+  ensureCloud(operation) {
+    if (this.local) {
+      throw new UnsupportedOperationError(
+        `${operation} is not supported in local mode.`
+      );
+    }
+  }
+  async catalog() {
+    this.ensureCloud("Audit catalog");
+    return this.httpClient.get(
+      "/v1/audit/catalog",
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async events(query = {}) {
+    this.ensureCloud("Audit event listing");
+    return this.httpClient.get(
+      "/v1/audit/events",
+      query,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async getEvent(eventId) {
+    this.ensureCloud("Audit event lookup");
+    const safeEventId = encodePathSegment(eventId);
+    return this.httpClient.get(
+      `/v1/audit/events/${safeEventId}`,
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+};
+
+// src/client/WebhooksManager.ts
+var WebhooksManager = class {
+  constructor(httpClient, local = false) {
+    this.httpClient = httpClient;
+    this.local = local;
+  }
+  ensureCloud(operation) {
+    if (this.local) {
+      throw new UnsupportedOperationError(
+        `${operation} is not supported in local mode.`
+      );
+    }
+  }
+  async createEndpoint(payload) {
+    this.ensureCloud("Webhook endpoint creation");
+    return this.httpClient.post(
+      "/v1/webhooks/endpoints",
+      payload,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async listEndpoints() {
+    this.ensureCloud("Webhook endpoint listing");
+    return this.httpClient.get(
+      "/v1/webhooks/endpoints",
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async getEndpoint(endpointId) {
+    this.ensureCloud("Webhook endpoint lookup");
+    const safeEndpointId = encodePathSegment(endpointId);
+    return this.httpClient.get(
+      `/v1/webhooks/endpoints/${safeEndpointId}`,
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async updateEndpoint(endpointId, payload) {
+    this.ensureCloud("Webhook endpoint update");
+    const safeEndpointId = encodePathSegment(endpointId);
+    return this.httpClient.patch(
+      `/v1/webhooks/endpoints/${safeEndpointId}`,
+      payload,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async deleteEndpoint(endpointId) {
+    this.ensureCloud("Webhook endpoint deletion");
+    const safeEndpointId = encodePathSegment(endpointId);
+    return this.httpClient.delete(
+      `/v1/webhooks/endpoints/${safeEndpointId}`,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async rotateSecret(endpointId) {
+    this.ensureCloud("Webhook secret rotation");
+    const safeEndpointId = encodePathSegment(endpointId);
+    return this.httpClient.post(
+      `/v1/webhooks/endpoints/${safeEndpointId}/rotate-secret`,
+      {},
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async sendTestEvent(endpointId) {
+    this.ensureCloud("Webhook test event");
+    const safeEndpointId = encodePathSegment(endpointId);
+    return this.httpClient.post(
+      `/v1/webhooks/endpoints/${safeEndpointId}/test`,
+      {},
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async verifyEndpoint(endpointId) {
+    this.ensureCloud("Webhook endpoint verification");
+    const safeEndpointId = encodePathSegment(endpointId);
+    return this.httpClient.post(
+      `/v1/webhooks/endpoints/${safeEndpointId}/verify`,
+      {},
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async listDeliveries(query = {}) {
+    this.ensureCloud("Webhook delivery listing");
+    return this.httpClient.get(
+      "/v1/webhooks/deliveries",
+      query,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async replayDelivery(deliveryId) {
+    this.ensureCloud("Webhook delivery replay");
+    const safeDeliveryId = encodePathSegment(deliveryId);
+    return this.httpClient.post(
+      `/v1/webhooks/deliveries/${safeDeliveryId}/replay`,
+      {},
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+};
+
+// src/client/VolumesManager.ts
+var import_fs = __toESM(require("fs"));
+var import_path9 = __toESM(require("path"));
+var import_form_data = __toESM(require("form-data"));
+var VolumesManager = class {
+  constructor(httpClient, local = false) {
+    this.httpClient = httpClient;
+    this.local = local;
+  }
+  ensureCloud(operation) {
+    if (this.local) {
+      throw new UnsupportedOperationError(
+        `${operation} is not supported in local mode.`
+      );
+    }
+  }
+  async create(payload) {
+    this.ensureCloud("Volume creation");
+    return this.httpClient.post(
+      "/v1/volumes",
+      payload,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async list(refreshUsage = false) {
+    this.ensureCloud("Volume listing");
+    return this.httpClient.get(
+      "/v1/volumes",
+      { refresh_usage: refreshUsage },
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async get(volumeId, refreshUsage = false) {
+    this.ensureCloud("Volume lookup");
+    const safeVolumeId = encodePathSegment(volumeId);
+    return this.httpClient.get(
+      `/v1/volumes/${safeVolumeId}`,
+      { refresh_usage: refreshUsage },
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async update(volumeId, payload) {
+    this.ensureCloud("Volume update");
+    const safeVolumeId = encodePathSegment(volumeId);
+    return this.httpClient.patch(
+      `/v1/volumes/${safeVolumeId}`,
+      payload,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async delete(volumeId) {
+    this.ensureCloud("Volume deletion");
+    const safeVolumeId = encodePathSegment(volumeId);
+    return this.httpClient.delete(
+      `/v1/volumes/${safeVolumeId}`,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async createCheckpoint(volumeId, payload = {}) {
+    this.ensureCloud("Volume checkpoint creation");
+    const safeVolumeId = encodePathSegment(volumeId);
+    return this.httpClient.post(
+      `/v1/volumes/${safeVolumeId}/checkpoints`,
+      payload,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async listCheckpoints(volumeId) {
+    this.ensureCloud("Volume checkpoint listing");
+    const safeVolumeId = encodePathSegment(volumeId);
+    return this.httpClient.get(
+      `/v1/volumes/${safeVolumeId}/checkpoints`,
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async deleteCheckpoint(volumeId, checkpointId) {
+    this.ensureCloud("Volume checkpoint deletion");
+    const safeVolumeId = encodePathSegment(volumeId);
+    const safeCheckpointId = encodePathSegment(checkpointId);
+    return this.httpClient.delete(
+      `/v1/volumes/${safeVolumeId}/checkpoints/${safeCheckpointId}`,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async uploadFile(volumeId, payload) {
+    this.ensureCloud("Volume file upload");
+    if (!payload.path || payload.path.trim().length === 0) {
+      throw new Error("payload.path is required");
+    }
+    const hasFilePath = typeof payload.filePath === "string" && payload.filePath.length > 0;
+    const hasFileContent = payload.fileContent !== void 0;
+    if (hasFilePath === hasFileContent) {
+      throw new Error("Provide exactly one of payload.filePath or payload.fileContent");
+    }
+    const safeVolumeId = encodePathSegment(volumeId);
+    const formData = new import_form_data.default();
+    if (hasFilePath) {
+      const sourcePath = payload.filePath;
+      const filename = payload.filename || import_path9.default.basename(sourcePath);
+      formData.append("file", import_fs.default.createReadStream(sourcePath), { filename });
+    } else {
+      const filename = payload.filename || "upload.bin";
+      const raw = payload.fileContent;
+      const buffer = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+      formData.append("file", buffer, { filename });
+    }
+    formData.append("path", payload.path);
+    if (payload.overwrite !== void 0) {
+      formData.append("overwrite", String(payload.overwrite));
+    }
+    return this.httpClient.postFormData(
+      `/v1/volumes/${safeVolumeId}/files/upload`,
+      formData
+    );
+  }
+  async downloadFile(volumeId, path4) {
+    this.ensureCloud("Volume file download");
+    const safeVolumeId = encodePathSegment(volumeId);
+    const response = await this.httpClient.post(
+      `/v1/volumes/${safeVolumeId}/files/download`,
+      { path: path4 },
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+    return {
+      path: response.path,
+      filename: response.filename,
+      size: response.size,
+      content: Buffer.from(response.content || "", "base64")
+    };
+  }
+  async listFiles(volumeId, options = {}) {
+    this.ensureCloud("Volume file listing");
+    const safeVolumeId = encodePathSegment(volumeId);
+    return this.httpClient.get(
+      `/v1/volumes/${safeVolumeId}/files`,
+      {
+        prefix: options.prefix ?? "",
+        recursive: options.recursive ?? true,
+        limit: options.limit ?? 1e3
+      },
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  async deleteFile(volumeId, targetPath) {
+    this.ensureCloud("Volume file deletion");
+    const safeVolumeId = encodePathSegment(volumeId);
+    return this.httpClient.request({
+      method: "DELETE",
+      url: `/v1/volumes/${safeVolumeId}/files`,
+      params: { path: targetPath },
+      headers: { "X-API-Key": this.httpClient.apiKey }
+    });
+  }
+};
+
+// src/client/InstaVM.ts
+var import_form_data2 = __toESM(require("form-data"));
+var InstaVM = class {
+  constructor(apiKey, options = {}) {
+    this._sessionId = null;
+    this._vmUsed = false;
+    this.local = options.local || false;
+    this.timeout = options.timeout || 3e5;
+    this.memory_mb = options.memory_mb;
+    this.cpu_count = options.cpu_count;
+    this.metadata = options.metadata;
+    this.env = options.env;
+    if (!this.local && !apiKey) {
+      throw new AuthenticationError("API key is required for cloud mode");
+    }
+    const config = {
+      baseURL: this.local ? options.localURL || "http://coderunner.local:8222" : options.baseURL || "https://api.instavm.io",
+      timeout: this.timeout,
+      maxRetries: options.maxRetries || 3,
+      retryDelay: options.retryDelay || 1e3,
+      apiKey: apiKey || ""
+    };
+    this.httpClient = new HTTPClient(config);
+    this.browser = new BrowserManager(this.httpClient, this.local);
+    this.vms = new VMsManager(this.httpClient, this.local);
+    this.snapshots = new SnapshotsManager(this.httpClient, this.local);
+    this.shares = new SharesManager(this.httpClient, this.local, () => this._sessionId);
+    this.customDomains = new CustomDomainsManager(this.httpClient, this.local);
+    this.computerUse = new ComputerUseManager(this.httpClient, this.local);
+    this.apiKeys = new APIKeysManager(this.httpClient, this.local);
+    this.audit = new AuditManager(this.httpClient, this.local);
+    this.webhooks = new WebhooksManager(this.httpClient, this.local);
+    this.volumes = new VolumesManager(this.httpClient, this.local);
+  }
+  /**
+   * Ensure operation is not called in local mode
+   */
+  ensureNotLocal(operationName) {
+    if (this.local) {
+      throw new UnsupportedOperationError(
+        `${operationName} is not supported in local mode. This operation is only available when using the cloud API.`
+      );
+    }
+  }
+  /**
+   * Execute code synchronously
+   *
+   * @param command - Command to execute
+   * @param options - Execution options
+   * @param options.timeout - Request timeout in milliseconds (used for HTTP request timeout and sent to API in seconds)
+   * @returns Execution result
+   */
+  async execute(command, options = {}) {
+    let sessionId = options.sessionId || this._sessionId;
+    if (!this.local && !sessionId) {
+      sessionId = await this.createSession();
+    }
+    const requestData = {
+      command,
+      language: options.language || "python"
+    };
+    if (options.timeout !== void 0) {
+      requestData.timeout = Math.floor(options.timeout / 1e3);
+    }
+    if (!this.local && sessionId) {
+      requestData.session_id = sessionId;
+    }
+    const requestTimeout = options.timeout !== void 0 ? options.timeout : this.timeout;
+    try {
+      const response = await this.httpClient.postExecution(
+        "/execute",
+        requestData,
+        void 0,
+        requestTimeout
+      );
+      if (response.session_id) {
+        this._sessionId = response.session_id;
+      }
+      if (!this.local) {
+        this._vmUsed = true;
+      }
+      return {
+        stdout: response.stdout || "",
+        stderr: response.stderr || "",
+        success: response.success !== false,
+        executionTime: response.execution_time,
+        cpuTime: response.cpu_time,
+        createdAt: response.created_at,
+        sessionId: response.session_id,
+        error: response.error
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new ExecutionError(
+        `Code execution failed: ${errorMessage}`,
+        void 0,
+        void 0,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Execute code asynchronously
+   */
+  async executeAsync(command, options = {}) {
+    this.ensureNotLocal("Async execution");
+    let sessionId = options.sessionId || this._sessionId;
+    if (!sessionId) {
+      sessionId = await this.createSession();
+    }
+    const requestData = {
+      command,
+      language: options.language || "python",
+      timeout: options.timeout || 15,
+      session_id: sessionId
+    };
+    try {
+      const response = await this.httpClient.postExecution(
+        "/execute_async",
+        requestData
+      );
+      if (response.session_id) {
+        this._sessionId = response.session_id;
+      }
+      this._vmUsed = true;
+      return {
+        taskId: response.task_id,
+        status: response.status || "pending",
+        output: response.stdout || response.output,
+        success: response.success,
+        executionTime: response.execution_time,
+        sessionId: response.session_id,
+        error: response.error
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new ExecutionError(
+        `Async code execution failed: ${errorMessage}`,
+        void 0,
+        void 0,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Poll for async task result
+   *
+   * @param taskId - The task ID from executeAsync
+   * @param pollInterval - Seconds between polls (default: 1)
+   * @param timeout - Maximum seconds to wait (default: 60)
+   * @returns Task result with stdout, stderr, execution time, etc.
+   * @throws Error if task doesn't complete within timeout
+   */
+  async getTaskResult(taskId, pollInterval = 1, timeout = 60) {
+    this.ensureNotLocal("Async task result retrieval");
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout * 1e3) {
+      try {
+        const response = await this.httpClient.get(
+          `/v1/executions/${taskId}`,
+          void 0,
+          { "X-API-Key": this.httpClient.apiKey }
+        );
+        if (response.is_complete) {
+          return {
+            stdout: response.serialized_stdout || "",
+            stderr: response.serialized_stderr || "",
+            cpuTime: response.cpu_time,
+            executionTime: response.execution_time,
+            createdAt: response.created_at
+          };
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollInterval * 1e3));
+      } catch (error) {
+        if (error instanceof AuthenticationError || error instanceof RateLimitError || error instanceof NetworkError) {
+          throw error;
+        }
+        if (Date.now() - startTime >= timeout * 1e3) {
+          throw new ExecutionError(
+            `Failed to get task result: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollInterval * 1e3));
+      }
+    }
+    throw new ExecutionError(`Task ${taskId} timed out after ${timeout}s`);
+  }
+  /**
+   * Upload files to the execution environment
+   */
+  async upload(files, options = {}) {
+    this.ensureNotLocal("File upload");
+    const sessionId = options.sessionId || this._sessionId;
+    if (!sessionId) {
+      throw new SessionError("Session ID not set. Please create a session first using createSession().");
+    }
+    const formData = new import_form_data2.default();
+    for (const file of files) {
+      if (Buffer.isBuffer(file.content)) {
+        formData.append("files", file.content, file.name);
+      } else {
+        formData.append("files", Buffer.from(file.content), file.name);
+      }
+      if (file.path) {
+        formData.append("paths", file.path);
+      }
+    }
+    formData.append("session_id", sessionId);
+    if (options.remotePath) {
+      formData.append("remote_path", options.remotePath);
+    }
+    if (options.recursive !== void 0) {
+      formData.append("recursive", String(options.recursive));
+    }
+    try {
+      const response = await this.httpClient.postFormData(
+        "/upload",
+        formData
+      );
+      return {
+        success: response.success !== false,
+        files: response.files || [],
+        message: response.message
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new SessionError(
+        `File upload failed: ${errorMessage}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Create a new execution session
+   */
+  async createSession() {
+    this.ensureNotLocal("Session management");
+    try {
+      const requestBody = {
+        api_key: this.httpClient.apiKey,
+        vm_lifetime_seconds: Math.floor(this.timeout / 1e3)
+      };
+      if (this.memory_mb !== void 0) {
+        requestBody.memory_mb = this.memory_mb;
+      }
+      if (this.cpu_count !== void 0) {
+        requestBody.vcpu_count = this.cpu_count;
+      }
+      if (this.metadata !== void 0) {
+        requestBody.metadata = this.metadata;
+      }
+      if (this.env !== void 0) {
+        requestBody.env = this.env;
+      }
+      const response = await this.httpClient.post(
+        "/v1/sessions/session",
+        requestBody
+      );
+      if (response.session_id) {
+        this._sessionId = response.session_id;
+        return response.session_id;
+      }
+      throw new SessionError("Session creation failed: No session ID returned");
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new SessionError(
+        `Session creation failed: ${errorMessage}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Close a session
+   * Note: Sessions auto-expire on the server side. This just clears local state.
+   */
+  async closeSession(sessionId) {
+    const targetSessionId = sessionId || this._sessionId;
+    if (!targetSessionId) {
+      return;
+    }
+    if (targetSessionId === this._sessionId) {
+      this._sessionId = null;
+    }
+  }
+  /**
+   * Check if current session is still active by checking VM status
+   *
+   * @returns true if session is active, false otherwise
+   */
+  async isSessionActive(sessionId) {
+    const targetSessionId = sessionId || this._sessionId;
+    if (!targetSessionId) {
+      return false;
+    }
+    try {
+      const response = await this.httpClient.get(
+        `/v1/sessions/status/${targetSessionId}`,
+        void 0,
+        { "X-API-Key": this.httpClient.apiKey }
+      );
+      return response.vm_status === "active";
+    } catch (error) {
+      if (error instanceof SessionError || error instanceof AuthenticationError || error instanceof NetworkError) {
+        return false;
+      }
+      return false;
+    }
+  }
+  /**
+   * Get the app URL for a session
+   *
+   * @param sessionId - Session ID (uses current session if not provided)
+   * @param port - Port to expose (1-65535, default: 80)
+   */
+  async getSessionAppUrl(sessionId, port) {
+    this.ensureNotLocal("Session app URL");
+    const targetSessionId = sessionId || this._sessionId;
+    if (!targetSessionId) {
+      throw new SessionError("Session ID not set. Please create a session first.");
+    }
+    const params = {};
+    if (port !== void 0) {
+      params.port = port;
+    }
+    return this.httpClient.get(
+      `/v1/sessions/app-url/${targetSessionId}`,
+      params,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  /**
+   * List sandbox records with optional filtering
+   *
+   * @param options.metadata - JSON-serializable metadata filters
+   * @param options.limit - Maximum number of results (1-1000, default: 100)
+   */
+  async listSandboxes(options = {}) {
+    this.ensureNotLocal("Sandbox listing");
+    const params = {};
+    if (options.metadata !== void 0) {
+      params.metadata = JSON.stringify(options.metadata);
+    }
+    if (options.limit !== void 0) {
+      params.limit = options.limit;
+    }
+    return this.httpClient.get(
+      "/v1/sessions/sandboxes",
+      params,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  /**
+   * Get usage statistics for a session
+   */
+  async getUsage(sessionId) {
+    this.ensureNotLocal("Usage tracking");
+    const targetSessionId = sessionId || this._sessionId;
+    if (!targetSessionId) {
+      throw new SessionError("No active session to get usage for");
+    }
+    try {
+      const response = await this.httpClient.get(
+        `/v1/sessions/usage/${targetSessionId}`,
+        void 0,
+        { "X-API-Key": this.httpClient.apiKey }
+      );
+      return {
+        sessionsUsed: response.sessions_used || 0,
+        executionTime: response.execution_time || 0,
+        quotaRemaining: response.quota_remaining || 0,
+        quotaLimit: response.quota_limit || 0
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new SessionError(
+        `Failed to get usage stats: ${errorMessage}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Get the current user profile.
+   */
+  async getCurrentUser() {
+    this.ensureNotLocal("User profile lookup");
+    return this.httpClient.get(
+      "/v1/me",
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  /**
+   * Get the current status of a session.
+   */
+  async getSessionStatus(sessionId) {
+    this.ensureNotLocal("Session management");
+    const targetSessionId = sessionId || this._sessionId;
+    if (!targetSessionId) {
+      throw new SessionError("Session ID not set. Please create a session first.");
+    }
+    return this.httpClient.get(
+      `/v1/sessions/status/${targetSessionId}`,
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+  }
+  /**
+   * Download a file from the remote VM
+   */
+  async download(filename, options = {}) {
+    this.ensureNotLocal("File download");
+    const targetSessionId = options.sessionId || this._sessionId;
+    if (!targetSessionId) {
+      throw new SessionError("No active session to download from");
+    }
+    try {
+      const response = await this.httpClient.postFormUrlEncoded("/download", {
+        filename,
+        session_id: targetSessionId
+      });
+      const encodedContent = response.content || "";
+      const content = encodedContent ? Buffer.from(encodedContent, "base64") : Buffer.from(response);
+      return {
+        success: true,
+        filename,
+        content,
+        size: content.length
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new SessionError(
+        `File download failed: ${errorMessage}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Get the current session ID
+   */
+  get sessionId() {
+    return this._sessionId;
+  }
+  /**
+   * Kill the VM associated with a session
+   *
+   * @param sessionId - The session UUID whose VM should be killed. If not provided, uses current sessionId
+   * @returns Result containing success message and killed VM ID
+   */
+  async kill(sessionId) {
+    this.ensureNotLocal("VM kill operation");
+    const targetSessionId = sessionId || this._sessionId;
+    if (!targetSessionId) {
+      throw new SessionError("Session ID not set. Please provide a sessionId or start a session first.");
+    }
+    try {
+      const response = await this.httpClient.post(
+        "/kill",
+        { session_id: targetSessionId },
+        { "X-API-Key": this.httpClient.apiKey }
+      );
+      if (!sessionId && this._sessionId === targetSessionId) {
+        this._sessionId = null;
+      }
+      return response;
+    } catch (error) {
+      if (error instanceof Error && "statusCode" in error) {
+        const statusCode = error.statusCode;
+        if (statusCode === 403) {
+          throw new AuthenticationError("You don't own this session", { cause: error });
+        }
+        if (statusCode === 404) {
+          throw new SessionError("Session not found or no VM assigned to session (has execute() been called?)", { cause: error });
+        }
+      }
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new SessionError(
+        `Failed to kill VM: ${errorMessage}`,
+        { cause: error }
+      );
+    }
+  }
+  // --- Egress Policy Methods ---
+  /**
+   * Set egress policy for a session
+   */
+  async setSessionEgress(options = {}, sessionId) {
+    this.ensureNotLocal("Egress policy management");
+    const targetSessionId = sessionId || this._sessionId;
+    if (!targetSessionId) {
+      throw new SessionError("Session ID not set. Please create a session first.");
+    }
+    const response = await this.httpClient.post(
+      `/v1/egress/session/${targetSessionId}`,
+      {
+        allow_public_repos: options.allowPackageManagers ?? true,
+        allow_http: options.allowHttp ?? true,
+        allow_https: options.allowHttps ?? true,
+        allowed_domains: options.allowedDomains ?? [],
+        allowed_cidrs: options.allowedCidrs ?? []
+      },
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+    return response;
+  }
+  /**
+   * Get egress policy for a session
+   */
+  async getSessionEgress(sessionId) {
+    this.ensureNotLocal("Egress policy management");
+    const targetSessionId = sessionId || this._sessionId;
+    if (!targetSessionId) {
+      throw new SessionError("Session ID not set. Please create a session first.");
+    }
+    const response = await this.httpClient.get(
+      `/v1/egress/session/${targetSessionId}`,
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+    return {
+      allowPackageManagers: response.allow_public_repos,
+      allowHttp: response.allow_http,
+      allowHttps: response.allow_https,
+      allowedDomains: response.allowed_domains || [],
+      allowedCidrs: response.allowed_cidrs || []
+    };
+  }
+  /**
+   * Set egress policy for a specific VM
+   */
+  async setVmEgress(vmId, options = {}) {
+    this.ensureNotLocal("Egress policy management");
+    const response = await this.httpClient.post(
+      `/v1/egress/vm/${vmId}`,
+      {
+        allow_public_repos: options.allowPackageManagers ?? true,
+        allow_http: options.allowHttp ?? true,
+        allow_https: options.allowHttps ?? true,
+        allowed_domains: options.allowedDomains ?? [],
+        allowed_cidrs: options.allowedCidrs ?? []
+      },
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+    return response;
+  }
+  /**
+   * Get egress policy for a specific VM
+   */
+  async getVmEgress(vmId) {
+    this.ensureNotLocal("Egress policy management");
+    const response = await this.httpClient.get(
+      `/v1/egress/vm/${vmId}`,
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+    return {
+      allowPackageManagers: response.allow_public_repos,
+      allowHttp: response.allow_http,
+      allowHttps: response.allow_https,
+      allowedDomains: response.allowed_domains || [],
+      allowedCidrs: response.allowed_cidrs || []
+    };
+  }
+  // --- SSH Key Methods ---
+  /**
+   * Add an SSH public key
+   */
+  async addSshKey(publicKey) {
+    this.ensureNotLocal("SSH key management");
+    const response = await this.httpClient.post(
+      "/v1/ssh-keys",
+      { public_key: publicKey },
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+    return {
+      id: response.id,
+      fingerprint: response.fingerprint,
+      keyType: response.key_type,
+      comment: response.comment ?? null,
+      createdAt: response.created_at
+    };
+  }
+  /**
+   * List all active SSH keys
+   */
+  async listSshKeys() {
+    this.ensureNotLocal("SSH key management");
+    const response = await this.httpClient.get(
+      "/v1/ssh-keys",
+      void 0,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+    const keys = response.keys || [];
+    return keys.map((k) => ({
+      id: k.id,
+      fingerprint: k.fingerprint,
+      keyType: k.key_type,
+      comment: k.comment ?? null,
+      createdAt: k.created_at
+    }));
+  }
+  /**
+   * Delete an SSH key by ID
+   */
+  async deleteSshKey(keyId) {
+    this.ensureNotLocal("SSH key management");
+    const response = await this.httpClient.delete(
+      `/v1/ssh-keys/${keyId}`,
+      { "X-API-Key": this.httpClient.apiKey }
+    );
+    return response;
+  }
+  /**
+   * Clean up resources
+   */
+  async dispose() {
+    if (this._sessionId && !this.local && this._vmUsed) {
+      try {
+        await this.kill();
+      } catch (e) {
+      }
+    } else if (this._sessionId) {
+      await this.closeSession();
+    }
+    await this.browser.dispose();
+  }
+};
+
+// src/cli/config.ts
+var import_fs2 = __toESM(require("fs"));
+var import_os = __toESM(require("os"));
+var import_path11 = __toESM(require("path"));
+var import_url = require("url");
+var CONFIG_DIRNAME = ".instavm";
+var CONFIG_FILENAME = "config.json";
+var SCHEMA_VERSION = 1;
+var DEFAULT_BASE_URL = "https://api.instavm.io";
+var DEFAULT_DOCS_URL = "https://docs.instavm.io";
+var DEFAULT_BILLING_URL = "https://dashboard.instavm.io/billing";
+var DEFAULT_SSH_HOST = "instavm.dev";
+var ConfigError = class extends Error {
+};
+function getConfigDir(homeDir = import_os.default.homedir()) {
+  return import_path11.default.join(homeDir, CONFIG_DIRNAME);
+}
+function getConfigPath(homeDir = import_os.default.homedir()) {
+  return import_path11.default.join(getConfigDir(homeDir), CONFIG_FILENAME);
+}
+function defaultConfig() {
+  return {
+    schema_version: SCHEMA_VERSION,
+    active_profile: "default",
+    profiles: {
+      default: {
+        auth: {
+          type: "api_key",
+          api_key: null
+        }
+      }
+    }
+  };
+}
+function normalizeProfile(profile) {
+  const normalized = { ...profile };
+  const auth = typeof profile.auth === "object" && profile.auth !== null ? { ...profile.auth } : {};
+  auth.type = String(auth.type || "api_key").trim() || "api_key";
+  auth.api_key = auth.api_key ? String(auth.api_key).trim() : null;
+  normalized.auth = auth;
+  for (const field of ["base_url", "ssh_host"]) {
+    const rawValue = normalized[field];
+    if (typeof rawValue !== "string") {
+      delete normalized[field];
+      continue;
+    }
+    const cleaned = rawValue.trim();
+    if (cleaned) {
+      normalized[field] = cleaned;
+    } else {
+      delete normalized[field];
+    }
+  }
+  return normalized;
+}
+function normalizeConfig(rawConfig) {
+  const config = defaultConfig();
+  if (!rawConfig || typeof rawConfig !== "object") {
+    return config;
+  }
+  if (Number.isInteger(rawConfig.schema_version)) {
+    config.schema_version = Number(rawConfig.schema_version);
+  }
+  if (rawConfig.profiles && typeof rawConfig.profiles === "object") {
+    config.profiles = {};
+    for (const [name, profile] of Object.entries(rawConfig.profiles)) {
+      if (typeof name === "string" && profile && typeof profile === "object") {
+        config.profiles[name] = normalizeProfile(profile);
+      }
+    }
+  }
+  if (!config.profiles.default) {
+    config.profiles.default = defaultConfig().profiles.default;
+  }
+  if (typeof rawConfig.active_profile === "string" && Object.prototype.hasOwnProperty.call(config.profiles, rawConfig.active_profile)) {
+    config.active_profile = rawConfig.active_profile;
+  }
+  return config;
+}
+function loadConfig(configPath = getConfigPath()) {
+  if (!import_fs2.default.existsSync(configPath)) {
+    return defaultConfig();
+  }
+  try {
+    const raw = import_fs2.default.readFileSync(configPath, "utf8");
+    return normalizeConfig(JSON.parse(raw));
+  } catch (error) {
+    throw new ConfigError(`Unable to load CLI config from ${configPath}`);
+  }
+}
+function applyPosixMode(targetPath, mode) {
+  if (process.platform !== "win32") {
+    import_fs2.default.chmodSync(targetPath, mode);
+  }
+}
+function saveConfig(config, configPath = getConfigPath()) {
+  const configDir = import_path11.default.dirname(configPath);
+  try {
+    import_fs2.default.mkdirSync(configDir, { recursive: true, mode: 448 });
+    applyPosixMode(configDir, 448);
+    const normalized = normalizeConfig(config);
+    const tempPath = import_path11.default.join(configDir, `.${import_path11.default.basename(configPath)}.${process.pid}.${Date.now()}.tmp`);
+    import_fs2.default.writeFileSync(tempPath, `${JSON.stringify(normalized, null, 2)}
+`, "utf8");
+    applyPosixMode(tempPath, 384);
+    import_fs2.default.renameSync(tempPath, configPath);
+    applyPosixMode(configPath, 384);
+  } catch (error) {
+    throw new ConfigError(`Unable to write CLI config to ${configPath}`);
+  }
+  return configPath;
+}
+function getActiveProfile(config) {
+  return config.profiles[config.active_profile] || config.profiles.default;
+}
+function redactSecret(secret) {
+  if (!secret) {
+    return null;
+  }
+  const trimmed = secret.trim();
+  if (trimmed.length <= 8) {
+    return "*".repeat(trimmed.length);
+  }
+  return `${trimmed.slice(0, 8)}...${trimmed.slice(-4)}`;
+}
+function deriveSshHost(baseURL) {
+  try {
+    const parsed = new import_url.URL(baseURL);
+    const host = parsed.hostname.trim().toLowerCase();
+    if (!host) {
+      return DEFAULT_SSH_HOST;
+    }
+    if (host === "localhost" || host === "127.0.0.1") {
+      return host;
+    }
+    if (host.includes("staging") && host.includes("instavm")) {
+      return "staging.instavm.dev";
+    }
+    if (host.startsWith("api.") && host.includes("instavm")) {
+      return DEFAULT_SSH_HOST;
+    }
+    if (host.includes("instavm")) {
+      return DEFAULT_SSH_HOST;
+    }
+    return host;
+  } catch (error) {
+    return DEFAULT_SSH_HOST;
+  }
+}
+function resolveRuntimeConfig(options = {}) {
+  const env = options.env || process.env;
+  const configPath = options.configPath || getConfigPath();
+  const config = normalizeConfig(options.config || loadConfig(configPath));
+  const profile = getActiveProfile(config);
+  const storedKey = profile.auth?.api_key ? String(profile.auth.api_key).trim() : void 0;
+  let apiKey;
+  let apiKeySource = "missing";
+  if (options.apiKey) {
+    apiKey = options.apiKey.trim();
+    apiKeySource = "flag";
+  } else if (env.INSTAVM_API_KEY) {
+    apiKey = env.INSTAVM_API_KEY.trim();
+    apiKeySource = "env";
+  } else if (storedKey) {
+    apiKey = storedKey;
+    apiKeySource = "config";
+  }
+  let baseURL = DEFAULT_BASE_URL;
+  let baseURLSource = "default";
+  if (options.baseURL) {
+    baseURL = options.baseURL.trim();
+    baseURLSource = "flag";
+  } else if (env.INSTAVM_BASE_URL) {
+    baseURL = env.INSTAVM_BASE_URL.trim();
+    baseURLSource = "env";
+  } else if (profile.base_url) {
+    baseURL = String(profile.base_url).trim();
+    baseURLSource = "config";
+  }
+  let sshHost = deriveSshHost(baseURL);
+  let sshHostSource = "derived";
+  if (options.sshHost) {
+    sshHost = options.sshHost.trim();
+    sshHostSource = "flag";
+  } else if (env.INSTAVM_SSH_HOST) {
+    sshHost = env.INSTAVM_SSH_HOST.trim();
+    sshHostSource = "env";
+  } else if (profile.ssh_host) {
+    sshHost = String(profile.ssh_host).trim();
+    sshHostSource = "config";
+  }
+  return {
+    apiKey,
+    baseURL,
+    sshHost,
+    apiKeySource,
+    baseURLSource,
+    sshHostSource,
+    configPath,
+    config
+  };
+}
+function updateProfileSettings(options) {
+  const configPath = options.configPath || getConfigPath();
+  const config = loadConfig(configPath);
+  const profileName = config.active_profile || "default";
+  const existing = config.profiles[profileName] || { auth: { type: "api_key", api_key: null } };
+  const profile = normalizeProfile(existing);
+  const auth = { ...profile.auth || {} };
+  auth.type = String(auth.type || "api_key");
+  if (options.clearApiKey) {
+    auth.api_key = null;
+  } else if (options.apiKey !== void 0) {
+    auth.api_key = options.apiKey.trim() || null;
+  }
+  if (options.baseURL !== void 0) {
+    const cleaned = options.baseURL.trim();
+    if (cleaned) {
+      profile.base_url = cleaned;
+    } else {
+      delete profile.base_url;
+    }
+  }
+  if (options.sshHost !== void 0) {
+    const cleaned = options.sshHost.trim();
+    if (cleaned) {
+      profile.ssh_host = cleaned;
+    } else {
+      delete profile.ssh_host;
+    }
+  }
+  profile.auth = auth;
+  config.profiles[profileName] = profile;
+  return saveConfig(config, configPath);
+}
+
+// src/cli.ts
+var defaultDeps = {
+  stdout: process.stdout,
+  stderr: process.stderr,
+  spawnSync: import_child_process.spawnSync,
+  resolveRuntimeConfig,
+  updateProfileSettings,
+  clientFactory: (apiKey, options) => new InstaVM(apiKey, options),
+  promptSecret,
+  readStdin,
+  writeFile: (outputPath, content) => {
+    import_fs3.default.writeFileSync(outputPath, content);
+  }
+};
+function printJson(deps, payload) {
+  deps.stdout.write(`${JSON.stringify(payload)}
+`);
+}
+function printLines(deps, lines) {
+  for (const line of lines) {
+    deps.stdout.write(`${line}
+`);
+  }
+}
+function emitOutput(deps, options, payload, textLines) {
+  if (options.json) {
+    printJson(deps, payload);
+  } else {
+    printLines(deps, textLines);
+  }
+  return 0;
+}
+function addRuntimeOptions(command, options = {}) {
+  command.option("--api-key <apiKey>", "Override the InstaVM API key for this command");
+  command.option("--base-url <baseUrl>", "Override the InstaVM API base URL for this command");
+  if (options.includeSshHost) {
+    command.option("--ssh-host <sshHost>", "Override the SSH gateway host for this command");
+  }
+  if (options.includeJson !== false) {
+    command.option("-j, --json", "Emit JSON output");
+  }
+  return command;
+}
+function parseSize(value) {
+  const raw = value.trim().toLowerCase();
+  if (!raw) {
+    throw new Error("size is required");
+  }
+  const units = [
+    ["tb", 1024 ** 4],
+    ["gb", 1024 ** 3],
+    ["mb", 1024 ** 2],
+    ["kb", 1024],
+    ["b", 1]
+  ];
+  for (const [suffix, multiplier] of units) {
+    if (raw.endsWith(suffix) && raw !== suffix) {
+      const number = raw.slice(0, -suffix.length).trim();
+      return Math.floor(Number.parseFloat(number) * multiplier);
+    }
+  }
+  return Number.parseInt(raw, 10);
+}
+function humanBytes(value) {
+  let amount = Number(value || 0);
+  for (const unit of ["B", "KB", "MB", "GB", "TB"]) {
+    if (amount < 1024 || unit === "TB") {
+      if (unit === "B") {
+        return `${Math.trunc(amount)}${unit}`;
+      }
+      return `${amount.toFixed(1)}${unit}`;
+    }
+    amount /= 1024;
+  }
+  return `${Math.trunc(Number(value || 0))}B`;
+}
+function parseEnvPairs(values) {
+  const pairs = {};
+  for (const entry of values || []) {
+    const separatorIndex = entry.indexOf("=");
+    if (separatorIndex < 1) {
+      throw new Error(`Expected KEY=VALUE, got: ${entry}`);
+    }
+    const key = entry.slice(0, separatorIndex).trim();
+    const value = entry.slice(separatorIndex + 1);
+    if (!key) {
+      throw new Error(`Invalid env key: ${entry}`);
+    }
+    pairs[key] = value;
+  }
+  return pairs;
+}
+function parseVolumeSpec(spec) {
+  const parts = spec.split(":");
+  if (parts.length < 2) {
+    throw new Error("volume mounts must use <volume_id>:<mount_path>[:rw|ro[:checkpoint_id]]");
+  }
+  const volumeId = parts[0].trim();
+  const mountPath = parts[1].trim();
+  let mode = "rw";
+  let checkpointId = null;
+  if (parts[2]?.trim()) {
+    mode = parts[2].trim().toLowerCase();
+  }
+  if (parts[3]?.trim()) {
+    checkpointId = parts[3].trim();
+  }
+  if (parts.length > 4) {
+    throw new Error("volume mounts must use <volume_id>:<mount_path>[:rw|ro[:checkpoint_id]]");
+  }
+  if (!["rw", "ro"].includes(mode)) {
+    throw new Error("volume mount mode must be rw or ro");
+  }
+  if (mode === "rw" && checkpointId) {
+    throw new Error("checkpoint_id is only allowed for ro mounts");
+  }
+  if (mode === "ro" && !checkpointId) {
+    checkpointId = "latest";
+  }
+  return {
+    volume_id: volumeId,
+    mount_path: mountPath,
+    mode,
+    checkpoint_id: checkpointId
+  };
+}
+function looksLikeUuid(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+function statusPayload(deps, options) {
+  const settings = deps.resolveRuntimeConfig({
+    apiKey: options.apiKey,
+    baseURL: options.baseUrl,
+    sshHost: options.sshHost
+  });
+  const profile = getActiveProfile(settings.config);
+  const storedKey = profile.auth?.api_key ? String(profile.auth.api_key) : void 0;
+  return {
+    config_path: settings.configPath,
+    active_profile: settings.config.active_profile,
+    api_key: {
+      configured: Boolean(settings.apiKey),
+      redacted: redactSecret(settings.apiKey),
+      source: settings.apiKeySource,
+      stored: Boolean(storedKey)
+    },
+    base_url: {
+      value: settings.baseURL,
+      source: settings.baseURLSource
+    },
+    ssh_host: {
+      value: settings.sshHost,
+      source: settings.sshHostSource
+    }
+  };
+}
+function statusText(payload) {
+  const lines = [
+    `Config path: ${payload.config_path}`,
+    `Active profile: ${payload.active_profile}`,
+    `API key: ${payload.api_key.redacted || "not configured"} (${payload.api_key.source})`,
+    `Base URL: ${payload.base_url.value} (${payload.base_url.source})`,
+    `SSH host: ${payload.ssh_host.value} (${payload.ssh_host.source})`
+  ];
+  if (payload.api_key.stored) {
+    lines.push("Stored key: present");
+  }
+  return lines;
+}
+function resolveSettings(deps, options) {
+  return deps.resolveRuntimeConfig({
+    apiKey: options.apiKey,
+    baseURL: options.baseUrl,
+    sshHost: options.sshHost
+  });
+}
+function requireClient(deps, options) {
+  const settings = resolveSettings(deps, options);
+  if (!settings.apiKey) {
+    throw new Error("No InstaVM API key configured. Run `instavm auth set-key` or export INSTAVM_API_KEY.");
+  }
+  return {
+    client: deps.clientFactory(settings.apiKey, { baseURL: settings.baseURL }),
+    settings
+  };
+}
+async function resolveDesktopTarget(client, target) {
+  if (looksLikeUuid(target)) {
+    const status = await client.getSessionStatus(target);
+    return { ...status, session_id: target };
+  }
+  const vm = await client.vms.get(target);
+  const sessionId = vm.session_id ? String(vm.session_id) : null;
+  if (sessionId) {
+    const status = await client.getSessionStatus(sessionId);
+    return {
+      ...status,
+      session_id: sessionId,
+      vm_id: status.vm_id || vm.vm_id
+    };
+  }
+  return {
+    session_id: null,
+    vm_id: vm.vm_id,
+    vm_status: vm.status,
+    vm_alive: vm.status === "active"
+  };
+}
+async function desktopPayload(client, target) {
+  const payload = await resolveDesktopTarget(client, target);
+  if (payload.vm_alive && payload.session_id) {
+    try {
+      Object.assign(payload, await client.computerUse.viewerUrl(String(payload.session_id)));
+    } catch (error) {
+    }
+  }
+  return payload;
+}
+function createProgram(deps = defaultDeps) {
+  const program = new import_commander.Command();
+  program.name("instavm").description("InstaVM CLI for VM, snapshot, volume, desktop, identity, and sharing workflows.").showHelpAfterError().showSuggestionAfterError().configureOutput({
+    writeOut: (str) => deps.stdout.write(str),
+    writeErr: (str) => deps.stderr.write(str)
+  }).addHelpCommand("help [command]", "Show help for the CLI or a subcommand").exitOverride();
+  const auth = program.command("auth").description("Manage stored auth for the installed CLI");
+  addRuntimeOptions(
+    auth.command("set-key").description("Store an InstaVM API key in ~/.instavm/config.json from a hidden prompt or stdin").action(async (options) => {
+      const apiKey = process.stdin.isTTY ? (await deps.promptSecret("InstaVM API key: ")).trim() : (await deps.readStdin()).trim();
+      if (!apiKey) {
+        throw new Error("API key is required. Enter it at the prompt or pipe it over stdin.");
+      }
+      const configPath = deps.updateProfileSettings({
+        apiKey,
+        baseURL: options.baseUrl,
+        sshHost: options.sshHost
+      });
+      const payload = {
+        status: "stored",
+        config_path: configPath,
+        api_key: redactSecret(apiKey),
+        base_url: options.baseUrl || null,
+        ssh_host: options.sshHost || null
+      };
+      emitOutput(
+        deps,
+        options,
+        payload,
+        [
+          `Stored API key in ${configPath}`,
+          `API key: ${payload.api_key}`,
+          ...options.baseUrl ? [`Default base URL: ${options.baseUrl}`] : [],
+          ...options.sshHost ? [`Default SSH host: ${options.sshHost}`] : []
+        ]
+      );
+    }),
+    { includeSshHost: true }
+  );
+  addRuntimeOptions(
+    auth.command("status").description("Show the effective CLI auth and endpoint settings").action(async (options) => {
+      const payload = statusPayload(deps, options);
+      emitOutput(deps, options, payload, statusText(payload));
+    }),
+    { includeSshHost: true }
+  );
+  addRuntimeOptions(
+    auth.command("logout").description("Remove the stored API key from the local CLI config").action(async (options) => {
+      const settings = resolveSettings(deps, options);
+      const configPath = deps.updateProfileSettings({ clearApiKey: true });
+      const payload = {
+        status: "logged_out",
+        config_path: configPath,
+        env_key_active: settings.apiKeySource === "env"
+      };
+      emitOutput(
+        deps,
+        options,
+        payload,
+        [
+          `Removed the stored API key from ${configPath}`,
+          ...payload.env_key_active ? ["INSTAVM_API_KEY is still set in the environment and will remain active."] : []
+        ]
+      );
+    }),
+    { includeSshHost: true }
+  );
+  addRuntimeOptions(
+    program.command("whoami").description("Show the current account and SSH key registrations").action(async (options) => {
+      const { client } = requireClient(deps, options);
+      const [user, sshKeys] = await Promise.all([client.getCurrentUser(), client.listSshKeys()]);
+      const payload = {
+        id: user.id,
+        email: user.email,
+        name: user.name,
+        is_verified: user.is_verified,
+        ssh_keys: sshKeys
+      };
+      emitOutput(
+        deps,
+        options,
+        payload,
+        [
+          `Email: ${payload.email || "-"}`,
+          `User ID: ${payload.id}`,
+          `Name: ${payload.name || "-"}`,
+          `Verified: ${payload.is_verified ? "yes" : "no"}`,
+          "SSH Keys:",
+          ...sshKeys.length ? sshKeys.map((key) => `  ${key.id}	${key.fingerprint}	${key.comment || ""}`.trimEnd()) : ["  none"]
+        ]
+      );
+    })
+  );
+  addRuntimeOptions(
+    program.command("create").alias("new").description("Create a new VM or desktop").option("--type <type>", "VM type", "standard").option("--timeout <seconds>", "VM lifetime in seconds").option("--memory <mb>", "Memory in MB").option("--vcpu <count>", "vCPU count").option("--snapshot <snapshotId>", "Snapshot ID to boot from").option("--session <sessionId>", "Session ID to attach or respawn").option("--volume <spec>", "Volume spec: <volume_id>:<mount_path>[:rw|ro[:checkpoint_id]]", (value, all) => {
+      all.push(value);
+      return all;
+    }, []).action(async (options) => {
+      const { client, settings } = requireClient(deps, options);
+      const payload = {};
+      if (options.type === "computer-use") {
+        payload.image_variant = "computer-use";
+      }
+      if (options.timeout) {
+        payload.vm_lifetime_seconds = Number.parseInt(options.timeout, 10);
+      }
+      if (options.memory) {
+        payload.memory_mb = Number.parseInt(options.memory, 10);
+      }
+      if (options.vcpu) {
+        payload.vcpu_count = Number.parseInt(options.vcpu, 10);
+      }
+      if (options.snapshot) {
+        payload.snapshot_id = options.snapshot;
+      }
+      if (options.session) {
+        payload.session_id = options.session;
+      }
+      if (options.volume.length > 0) {
+        payload.volumes = options.volume.map(parseVolumeSpec);
+      }
+      const result = await client.vms.create(payload, true);
+      emitOutput(
+        deps,
+        options,
+        result,
+        [
+          `VM: ${result.vm_id || "-"}`,
+          `Session: ${result.session_id || "-"}`,
+          `Status: ${result.status || "-"}`,
+          ...result.vm_id ? [`SSH: ssh ${result.vm_id}@${settings.sshHost}`] : []
+        ]
+      );
+    })
+  );
+  addRuntimeOptions(
+    program.command("ls").alias("list").description("List your VMs").option("--all", "Include all VM records, not just active VMs").action(async (options) => {
+      const { client } = requireClient(deps, options);
+      const vms = options.all ? await client.vms.listAllRecords() : await client.vms.list();
+      emitOutput(
+        deps,
+        options,
+        { vms },
+        vms.length > 0 ? vms.map((vm) => `${vm.vm_id}	${vm.status || "-"}	${vm.created_at || "-"}	${vm.ssh_host || "-"}`) : ["No VMs."]
+      );
+    })
+  );
+  addRuntimeOptions(
+    program.command("rm").alias("delete").description("Delete one or more VMs").argument("<vmIds...>").action(async (vmIds, options) => {
+      const { client } = requireClient(deps, options);
+      const results = [];
+      for (const vmId of vmIds) {
+        results.push({ vm_id: vmId, ...await client.vms.delete(vmId) });
+      }
+      emitOutput(
+        deps,
+        options,
+        { results },
+        results.map((entry) => `${entry.vm_id}: ${entry.status || "ok"}`)
+      );
+    })
+  );
+  addRuntimeOptions(
+    program.command("clone").description("Clone a VM via snapshot").argument("<vmId>").option("--name <name>", "Snapshot name used during clone").action(async (vmId, options) => {
+      const { client, settings } = requireClient(deps, options);
+      const result = await client.vms.clone(vmId, options.name ? { snapshot_name: options.name } : {}, true);
+      emitOutput(
+        deps,
+        options,
+        result,
+        [
+          `VM: ${result.vm_id || "-"}`,
+          `Session: ${result.session_id || "-"}`,
+          `Status: ${result.status || "-"}`,
+          ...result.vm_id ? [`SSH: ssh ${result.vm_id}@${settings.sshHost}`] : []
+        ]
+      );
+    })
+  );
+  addRuntimeOptions(
+    program.command("connect").description("SSH into a VM with the local ssh client").argument("<vmId>").argument("[sshArgs...]").action(async (vmId, sshArgs, options) => {
+      const settings = resolveSettings(deps, options);
+      const sshBinary = process.platform === "win32" ? findExecutable(deps, "ssh.exe") || findExecutable(deps, "ssh") : findExecutable(deps, "ssh") || findExecutable(deps, "ssh.exe");
+      if (!sshBinary) {
+        throw new Error("ssh client not found on PATH");
+      }
+      const passthroughArgs = [...sshArgs || []];
+      if (passthroughArgs[0] === "--") {
+        passthroughArgs.shift();
+      }
+      const command = [sshBinary, `${vmId}@${settings.sshHost}`, ...passthroughArgs];
+      if (options.json) {
+        printJson(deps, { command });
+        return;
+      }
+      const result = deps.spawnSync(command[0], command.slice(1), { stdio: "inherit" });
+      if (result.error) {
+        throw result.error;
+      }
+      if ((result.status ?? 0) !== 0) {
+        throw new import_commander.CommanderError(result.status ?? 1, "ssh.exit", `ssh exited with status ${result.status ?? 1}`);
+      }
+    }),
+    { includeSshHost: true }
+  );
+  const snapshot = program.command("snapshot").description("List, inspect, build, create, and delete snapshots");
+  addRuntimeOptions(
+    snapshot.command("ls").alias("list").description("List snapshots").option("--type <type>", "Snapshot type filter").action(async (options) => {
+      const { client } = requireClient(deps, options);
+      const snapshots = await client.snapshots.list(options.type ? { type: options.type } : {});
+      emitOutput(
+        deps,
+        options,
+        { snapshots },
+        snapshots.length > 0 ? snapshots.map((snap) => `${snap.id}	${snap.name || "-"}	${snap.status || "-"}	${snap.type || "-"}`) : ["No snapshots."]
+      );
+    })
+  );
+  addRuntimeOptions(
+    snapshot.command("create").description("Create a snapshot from a running VM").argument("<vmId>").option("--name <name>", "Snapshot name").action(async (vmId, options) => {
+      const { client } = requireClient(deps, options);
+      const result = await client.vms.snapshot(vmId, options.name ? { name: options.name } : {}, true);
+      emitOutput(
+        deps,
+        options,
+        result,
+        [`Snapshot: ${result.snapshot_id || result.id || "-"}`, `Status: ${result.status || "-"}`]
+      );
+    })
+  );
+  addRuntimeOptions(
+    snapshot.command("build").description("Build a snapshot from an OCI image").argument("<ociImage>").option("--name <name>", "Snapshot name").option("--vcpu <count>", "vCPU count").option("--memory <mb>", "Memory in MB").option("--disk-size <gb>", "Snapshot disk size in GB").option("--env <pair>", "Build environment variable in KEY=VALUE form", (value, all) => {
+      all.push(value);
+      return all;
+    }, []).option("--git-clone <url>", "Git repository to clone during build").option("--git-branch <branch>", "Git branch to checkout").option("--run <command>", "Command to run after the image is prepared").option("--apt <packages>", "Extra apt packages").option("--pip <packages>", "Extra pip packages").option("--npm <packages>", "Extra npm packages").option("--type <type>", "Snapshot type", "user").action(async (ociImage, options) => {
+      const { client } = requireClient(deps, options);
+      const buildArgs = {};
+      if (options.apt) buildArgs.extra_apt_packages = options.apt;
+      if (options.pip) buildArgs.extra_pip_packages = options.pip;
+      if (options.npm) buildArgs.extra_npm_packages = options.npm;
+      if (options.gitClone) buildArgs.git_clone_url = options.gitClone;
+      if (options.gitBranch) buildArgs.git_clone_branch = options.gitBranch;
+      if (options.diskSize) buildArgs.disk_size_gb = Number.parseInt(options.diskSize, 10);
+      if (options.run) buildArgs.post_build_cmd = options.run;
+      if (options.env.length > 0) buildArgs.envs = parseEnvPairs(options.env);
+      const result = await client.snapshots.create({
+        oci_image: ociImage,
+        name: options.name,
+        vcpu_count: options.vcpu ? Number.parseInt(options.vcpu, 10) : void 0,
+        memory_mb: options.memory ? Number.parseInt(options.memory, 10) : void 0,
+        build_args: Object.keys(buildArgs).length > 0 ? buildArgs : void 0,
+        type: options.type
+      });
+      emitOutput(
+        deps,
+        options,
+        result,
+        [`Snapshot: ${result.id || "-"}`, `Name: ${result.name || "-"}`, `Status: ${result.status || "-"}`]
+      );
+    })
+  );
+  addRuntimeOptions(
+    snapshot.command("get").description("Get a snapshot by ID").argument("<snapshotId>").action(async (snapshotId, options) => {
+      const { client } = requireClient(deps, options);
+      const result = await client.snapshots.get(snapshotId);
+      emitOutput(
+        deps,
+        options,
+        result,
+        [
+          `Snapshot: ${result.id || "-"}`,
+          `Name: ${result.name || "-"}`,
+          `Status: ${result.status || "-"}`,
+          `Type: ${result.type || "-"}`
+        ]
+      );
+    })
+  );
+  addRuntimeOptions(
+    snapshot.command("rm").alias("delete").description("Delete a snapshot").argument("<snapshotId>").action(async (snapshotId, options) => {
+      const { client } = requireClient(deps, options);
+      const result = await client.snapshots.delete(snapshotId);
+      emitOutput(deps, options, { snapshot_id: snapshotId, ...result }, [`Deleted snapshot ${snapshotId}`]);
+    })
+  );
+  const share = program.command("share").description("Create and manage VM shares");
+  addRuntimeOptions(
+    share.command("create").description("Create a share for a VM and port").argument("<vmId>").argument("<port>").option("--public", "Create the share as public").action(async (vmId, port, options) => {
+      const { client } = requireClient(deps, options);
+      const result = await client.shares.create({
+        vm_id: vmId,
+        port: Number.parseInt(port, 10),
+        is_public: Boolean(options.public)
+      });
+      emitOutput(
+        deps,
+        options,
+        result,
+        [
+          `Share: ${result.share_id}`,
+          `URL: ${result.url}`,
+          `Port: ${result.port}`,
+          `Visibility: ${result.is_public ? "public" : "private"}`
+        ]
+      );
+    })
+  );
+  const addShareUpdateCommand = (name, description, mode) => {
+    addRuntimeOptions(
+      share.command(name).description(description).argument("<shareId>").action(async (shareId, options) => {
+        const { client } = requireClient(deps, options);
+        const result = await client.shares.update(
+          shareId,
+          mode === "revoke" ? { revoke: true } : { is_public: mode === "public" }
+        );
+        emitOutput(
+          deps,
+          options,
+          { share_id: shareId, ...result },
+          [mode === "revoke" ? `Revoked share ${shareId}` : `Updated share ${shareId} to ${mode}`]
+        );
+      })
+    );
+  };
+  addShareUpdateCommand("set-public", "Set a share to public visibility", "public");
+  addShareUpdateCommand("set-private", "Set a share to private visibility", "private");
+  addShareUpdateCommand("revoke", "Revoke a share by share ID", "revoke");
+  const sshKey = program.command("ssh-key").alias("sshkey").description("Manage SSH keys on your account");
+  addRuntimeOptions(
+    sshKey.command("list").description("List active SSH keys").action(async (options) => {
+      const { client } = requireClient(deps, options);
+      const keys = await client.listSshKeys();
+      emitOutput(
+        deps,
+        options,
+        { keys },
+        keys.length > 0 ? keys.map((key) => `${key.id}	${key.fingerprint}	${key.comment || ""}`.trimEnd()) : ["No SSH keys."]
+      );
+    })
+  );
+  addRuntimeOptions(
+    sshKey.command("add").description("Add an SSH public key").argument("[publicKey]").action(async (publicKey, options) => {
+      const { client } = requireClient(deps, options);
+      const value = publicKey?.trim() || (!process.stdin.isTTY ? (await deps.readStdin()).trim() : "");
+      if (!value) {
+        throw new Error("Public key is required");
+      }
+      const result = await client.addSshKey(value);
+      emitOutput(deps, options, result, [`Added ${result.fingerprint || result.id}`]);
+    })
+  );
+  addRuntimeOptions(
+    sshKey.command("remove").description("Remove an SSH key by key ID").argument("<keyId>").action(async (keyId, options) => {
+      const { client } = requireClient(deps, options);
+      const result = await client.deleteSshKey(Number.parseInt(keyId, 10));
+      emitOutput(deps, options, { key_id: Number.parseInt(keyId, 10), ...result }, [`Removed ${keyId}`]);
+    })
+  );
+  const desktop = program.command("desktop").description("Manage computer-use desktops and viewer handoff");
+  const addDesktopCommand = (name, description, action) => {
+    addRuntimeOptions(
+      desktop.command(name).description(description).argument("<target>").action(action)
+    );
+  };
+  addDesktopCommand("status", "Show desktop status for a VM or session", async (target, options) => {
+    const { client } = requireClient(deps, options);
+    const payload = await desktopPayload(client, target);
+    emitOutput(
+      deps,
+      options,
+      payload,
+      [
+        `Session: ${payload.session_id || "-"}`,
+        `VM: ${payload.vm_id || "-"}`,
+        `Status: ${payload.vm_status || (payload.vm_alive ? "active" : "stopped")}`,
+        ...payload.viewer_url ? [`Viewer: ${payload.viewer_url}`] : []
+      ]
+    );
+  });
+  addDesktopCommand("viewer", "Get the noVNC viewer URL for a running desktop", async (target, options) => {
+    const { client } = requireClient(deps, options);
+    const payload = await desktopPayload(client, target);
+    if (!payload.session_id || !payload.vm_alive) {
+      throw new Error("Desktop is not running.");
+    }
+    if (!payload.viewer_url) {
+      Object.assign(payload, await client.computerUse.viewerUrl(String(payload.session_id)));
+    }
+    emitOutput(
+      deps,
+      options,
+      payload,
+      [
+        `Session: ${payload.session_id}`,
+        `VM: ${payload.vm_id || "-"}`,
+        `Viewer URL: ${payload.viewer_url}`,
+        ...payload.websocket_url ? [`WebSocket: ${payload.websocket_url}`] : []
+      ]
+    );
+  });
+  addDesktopCommand("start", "Start a computer-use desktop for a session", async (target, options) => {
+    const { client } = requireClient(deps, options);
+    const payload = await desktopPayload(client, target);
+    if (payload.vm_alive) {
+      emitOutput(
+        deps,
+        options,
+        payload,
+        [`Desktop already running: ${payload.vm_id || "-"}`, `Session: ${payload.session_id || "-"}`]
+      );
+      return;
+    }
+    if (!payload.session_id) {
+      throw new Error("Desktop start requires a session-backed VM or session ID.");
+    }
+    const result = await client.vms.create({ session_id: String(payload.session_id), image_variant: "computer-use" }, true);
+    const merged = await desktopPayload(client, String(result.session_id || payload.session_id));
+    Object.assign(merged, result);
+    emitOutput(
+      deps,
+      options,
+      merged,
+      [
+        `Desktop started: ${merged.vm_id || result.vm_id || "-"}`,
+        `Session: ${merged.session_id || result.session_id || "-"}`,
+        ...merged.viewer_url ? [`Viewer: ${merged.viewer_url}`] : []
+      ]
+    );
+  });
+  addDesktopCommand("stop", "Stop a running desktop VM", async (target, options) => {
+    const { client } = requireClient(deps, options);
+    const payload = await desktopPayload(client, target);
+    if (!payload.vm_alive) {
+      emitOutput(deps, options, payload, ["Desktop is already stopped."]);
+      return;
+    }
+    const result = payload.session_id ? await client.kill(String(payload.session_id)) : await client.vms.delete(String(payload.vm_id));
+    emitOutput(
+      deps,
+      options,
+      { session_id: payload.session_id, vm_id: payload.vm_id, ...result },
+      [`Stopping ${payload.vm_id || payload.session_id}...`]
+    );
+  });
+  const volume = program.command("volume").alias("volumes").description("Manage persistent volumes");
+  addRuntimeOptions(
+    volume.command("ls").alias("list").description("List volumes").option("--refresh", "Refresh usage before listing").action(async (options) => {
+      const { client } = requireClient(deps, options);
+      const volumes = await client.volumes.list(Boolean(options.refresh));
+      emitOutput(
+        deps,
+        options,
+        { volumes },
+        volumes.length > 0 ? volumes.map((entry) => `${entry.id}	${entry.name}	${humanBytes(entry.used_bytes)}/${humanBytes(entry.quota_bytes)}	${entry.status}`) : ["No volumes."]
+      );
+    })
+  );
+  addRuntimeOptions(
+    volume.command("get").description("Get a volume").argument("<volumeId>").option("--refresh", "Refresh usage before reading").action(async (volumeId, options) => {
+      const { client } = requireClient(deps, options);
+      const result = await client.volumes.get(volumeId, Boolean(options.refresh));
+      emitOutput(
+        deps,
+        options,
+        result,
+        [
+          `ID: ${result.id}`,
+          `Name: ${result.name}`,
+          `Status: ${result.status}`,
+          `Quota: ${humanBytes(result.quota_bytes)}`,
+          `Used: ${humanBytes(result.used_bytes)}`
+        ]
+      );
+    })
+  );
+  addRuntimeOptions(
+    volume.command("create").description("Create a volume").argument("<name>").requiredOption("--quota <size>", "Quota in bytes or units like 5gb").action(async (name, options) => {
+      const { client } = requireClient(deps, options);
+      const result = await client.volumes.create({ name, quota_bytes: parseSize(options.quota) });
+      emitOutput(
+        deps,
+        options,
+        result,
+        [`Volume: ${result.id}`, `Name: ${result.name}`, `Quota: ${humanBytes(result.quota_bytes)}`]
+      );
+    })
+  );
+  addRuntimeOptions(
+    volume.command("update").description("Update a volume").argument("<volumeId>").option("--name <name>", "Updated volume name").option("--quota <size>", "Updated quota in bytes or units like 5gb").action(async (volumeId, options) => {
+      const { client } = requireClient(deps, options);
+      const payload = {};
+      if (options.name) payload.name = options.name;
+      if (options.quota) payload.quota_bytes = parseSize(options.quota);
+      if (Object.keys(payload).length === 0) {
+        throw new Error("Provide --name and/or --quota");
+      }
+      const result = await client.volumes.update(volumeId, payload);
+      emitOutput(deps, options, result, [`Updated volume ${result.id || volumeId}`]);
+    })
+  );
+  addRuntimeOptions(
+    volume.command("rm").alias("delete").description("Delete a volume").argument("<volumeId>").action(async (volumeId, options) => {
+      const { client } = requireClient(deps, options);
+      const result = await client.volumes.delete(volumeId);
+      emitOutput(deps, options, { volume_id: volumeId, ...result }, [`Deleted ${volumeId}`]);
+    })
+  );
+  const checkpoint = volume.command("checkpoint").description("Manage checkpoints for a volume");
+  addRuntimeOptions(
+    checkpoint.command("ls").alias("list").description("List checkpoints for a volume").argument("<volumeId>").action(async (volumeId, options) => {
+      const { client } = requireClient(deps, options);
+      const checkpoints = await client.volumes.listCheckpoints(volumeId);
+      emitOutput(
+        deps,
+        options,
+        { checkpoints },
+        checkpoints.length > 0 ? checkpoints.map((entry) => `${entry.id}	${entry.name || "-"}	${entry.status || "-"}`) : ["No checkpoints."]
+      );
+    })
+  );
+  addRuntimeOptions(
+    checkpoint.command("create").description("Create a checkpoint for a volume").argument("<volumeId>").option("--name <name>", "Checkpoint name").action(async (volumeId, options) => {
+      const { client } = requireClient(deps, options);
+      const result = await client.volumes.createCheckpoint(volumeId, options.name ? { name: options.name } : {});
+      emitOutput(deps, options, result, [`Created checkpoint ${result.id || "-"}`]);
+    })
+  );
+  addRuntimeOptions(
+    checkpoint.command("rm").alias("delete").description("Delete a checkpoint").argument("<volumeId>").argument("<checkpointId>").action(async (volumeId, checkpointId, options) => {
+      const { client } = requireClient(deps, options);
+      const result = await client.volumes.deleteCheckpoint(volumeId, checkpointId);
+      emitOutput(deps, options, { checkpoint_id: checkpointId, ...result }, [`Deleted checkpoint ${checkpointId}`]);
+    })
+  );
+  const files = volume.command("files").description("Manage files stored inside a volume");
+  addRuntimeOptions(
+    files.command("ls").alias("list").description("List files inside a volume").argument("<volumeId>").option("--prefix <prefix>", "Path prefix filter").option("--limit <limit>", "Maximum number of entries", "1000").option("--no-recursive", "Do not recurse into subdirectories").action(async (volumeId, options) => {
+      const { client } = requireClient(deps, options);
+      const result = await client.volumes.listFiles(volumeId, {
+        prefix: options.prefix || "",
+        recursive: options.recursive,
+        limit: Number.parseInt(options.limit, 10)
+      });
+      emitOutput(
+        deps,
+        options,
+        { files: result },
+        result.length > 0 ? result.map((entry) => `${entry.path}	${humanBytes(entry.size)}`) : ["No files."]
+      );
+    })
+  );
+  addRuntimeOptions(
+    files.command("upload").description("Upload a file into a volume").argument("<volumeId>").argument("<localPath>").option("--path <remotePath>", "Remote path inside the volume").option("--overwrite", "Overwrite if the path already exists").action(async (volumeId, localPath, options) => {
+      const { client } = requireClient(deps, options);
+      const remotePath = options.path || import_path12.default.basename(localPath);
+      const result = await client.volumes.uploadFile(volumeId, {
+        filePath: localPath,
+        path: remotePath,
+        overwrite: Boolean(options.overwrite)
+      });
+      emitOutput(deps, options, result, [`Uploaded ${localPath} -> ${remotePath}`]);
+    })
+  );
+  addRuntimeOptions(
+    files.command("download").description("Download a file from a volume").argument("<volumeId>").argument("<remotePath>").option("--out <outputPath>", "Local output path").action(async (volumeId, remotePath, options) => {
+      const { client } = requireClient(deps, options);
+      const result = await client.volumes.downloadFile(volumeId, remotePath);
+      const outputPath = options.out || import_path12.default.basename(remotePath);
+      deps.writeFile(outputPath, result.content);
+      emitOutput(
+        deps,
+        options,
+        {
+          path: result.path,
+          filename: result.filename,
+          size: result.size,
+          local_path: outputPath
+        },
+        [`Downloaded ${remotePath} -> ${outputPath}`]
+      );
+    })
+  );
+  addRuntimeOptions(
+    files.command("rm").alias("delete").description("Delete a file from a volume").argument("<volumeId>").argument("<remotePath>").action(async (volumeId, remotePath, options) => {
+      const { client } = requireClient(deps, options);
+      const result = await client.volumes.deleteFile(volumeId, remotePath);
+      emitOutput(deps, options, { path: remotePath, ...result }, [`Deleted ${remotePath}`]);
+    })
+  );
+  program.command("doc").alias("docs").description("Show InstaVM documentation links").option("-j, --json", "Emit JSON output").action((options) => {
+    emitOutput(deps, options, { url: DEFAULT_DOCS_URL }, [DEFAULT_DOCS_URL]);
+  });
+  program.command("billing").description("Show the billing portal URL").option("-j, --json", "Emit JSON output").action((options) => {
+    emitOutput(deps, options, { url: DEFAULT_BILLING_URL }, [DEFAULT_BILLING_URL]);
+  });
+  return program;
+}
+async function runCli(argv, deps = defaultDeps) {
+  const program = createProgram(deps);
+  try {
+    await program.parseAsync(["node", "instavm", ...argv]);
+    return 0;
+  } catch (error) {
+    if (error instanceof import_commander.CommanderError) {
+      if (error.code === "commander.helpDisplayed") {
+        return error.exitCode;
+      }
+      deps.stderr.write(`${error.message}
+`);
+      return error.exitCode || 1;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    deps.stderr.write(`Error: ${message}
+`);
+    return 1;
+  }
+}
+function findExecutable(deps, binary) {
+  const result = deps.spawnSync(process.platform === "win32" ? "where" : "which", [binary], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  if (result.status === 0) {
+    const output = (result.stdout || "").toString().split(/\r?\n/).find(Boolean);
+    return output || null;
+  }
+  return null;
+}
+async function promptSecret(prompt) {
+  if (!process.stdin.isTTY) {
+    return "";
+  }
+  return new Promise((resolve, reject) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    let value = "";
+    const cleanup = () => {
+      stdin.removeListener("data", onData);
+      stdin.pause();
+      if (typeof stdin.setRawMode === "function") {
+        stdin.setRawMode(false);
+      }
+      stdout.write("\n");
+    };
+    const onData = (chunk) => {
+      const input = chunk.toString("utf8");
+      for (const character of input) {
+        if (character === "") {
+          cleanup();
+          reject(new Error("Interrupted."));
+          return;
+        }
+        if (character === "\r" || character === "\n") {
+          cleanup();
+          resolve(value);
+          return;
+        }
+        if (character === "\x7F") {
+          value = value.slice(0, -1);
+          continue;
+        }
+        value += character;
+      }
+    };
+    stdout.write(prompt);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    if (typeof stdin.setRawMode === "function") {
+      stdin.setRawMode(true);
+    }
+    stdin.on("data", onData);
+  });
+}
+async function readStdin() {
+  if (process.stdin.isTTY) {
+    return "";
+  }
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    process.stdin.on("data", (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+    process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    process.stdin.on("error", reject);
+  });
+}
+async function main() {
+  const exitCode = await runCli(process.argv.slice(2));
+  if (exitCode !== 0) {
+    process.exitCode = exitCode;
+  }
+}
+if (require.main === module) {
+  void main();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createProgram,
+  runCli
+});
+//# sourceMappingURL=cli.js.map