teleportation-cli 1.1.5 → 1.2.0

package/lib/remote/providers/sprites-provider.js

@@ -0,0 +1,711 @@
+/**
+ * Sprites.dev Provider for Remote Development Environments
+ *
+ * Uses Sprites.dev (Fly.io's Firecracker micro-VMs) for ephemeral development workspaces.
+ * Sprites offer:
+ * - Sub-10 second boot times
+ * - 300ms checkpoint/restore
+ * - Auto-hibernate after 30 seconds of inactivity
+ * - Pay-per-compute pricing
+ *
+ * Ideal for:
+ * - Long-running tasks (overnight builds, large refactors)
+ * - Tasks requiring checkpoints/rollback
+ * - State preservation across sessions
+ *
+ * @see https://sprites.dev/docs/api
+ */
+
+import { BaseProvider } from './base-provider.js';
+
+export class SpritesProvider extends BaseProvider {
+  /**
+   * Initialize SpritesProvider
+   * @param {Object} config - Provider configuration
+   * @param {VaultClient} config.vaultClient - Mech Vault client
+   * @param {LivePortClient} config.livePortClient - LivePort client
+   * @param {string} [config.spritesToken] - Sprites API token (or SPRITES_TOKEN env var)
+   * @param {string} [config.apiUrl] - Sprites API URL (default: https://api.sprites.dev/v1)
+   * @param {number} [config.timeout] - Request timeout in ms (default: 60000)
+   */
+  constructor(config) {
+    super(config);
+    this.apiKey = config.spritesToken || process.env.SPRITES_TOKEN;
+    this.apiUrl = config.apiUrl || process.env.SPRITES_API_URL || 'https://api.sprites.dev/v1';
+    this.timeout = config.timeout || 60000; // 60 second default (sprites boot is fast but setup may take time)
+
+    if (!this.apiKey) {
+      throw new Error('SPRITES_TOKEN is required for SpritesProvider');
+    }
+  }
+
+  /**
+   * Create headers for Sprites API
+   * @private
+   * @returns {Object} HTTP headers
+   */
+  _headers() {
+    return {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${this.apiKey}`,
+    };
+  }
+
+  /**
+   * Format API error response for better debugging
+   * @private
+   * @param {Response} response - Fetch response
+   * @param {string} url - Request URL
+   * @returns {Promise<string>} Formatted error message
+   */
+  async _formatApiError(response, url) {
+    let body = '';
+    try {
+      body = await response.text();
+    } catch {
+      body = '';
+    }
+
+    const truncated = body.length > 500 ? `${body.slice(0, 500)}…` : body;
+    return `Sprites API error: ${response.status} ${response.statusText} (${url})\n${truncated}`;
+  }
+
+  /**
+   * Fetch with timeout support
+   * @private
+   * @param {string} url - URL to fetch
+   * @param {Object} options - Fetch options
+   * @param {number} [customTimeout] - Custom timeout in ms (overrides this.timeout)
+   * @returns {Promise<Response>} Fetch response
+   * @throws {Error} If request times out or fails
+   */
+  async _fetchWithTimeout(url, options = {}, customTimeout = null) {
+    const timeoutMs = customTimeout || this.timeout;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+      });
+      clearTimeout(timeoutId);
+      return response;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error.name === 'AbortError') {
+        throw new Error(`Request timed out after ${timeoutMs}ms: ${url}`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Escape shell argument by wrapping in single quotes and escaping any single quotes.
+   * This is critical for preventing shell injection attacks.
+   *
+   * @private
+   * @param {string} arg - Argument to escape
+   * @returns {string} Shell-safe escaped argument
+   */
+  _escapeShellArg(arg) {
+    if (arg === null || arg === undefined) return "''";
+    // Convert to string and replace any single quotes with '\'' (end quote, escaped quote, start quote)
+    return `'${String(arg).replace(/'/g, "'\\''")}'`;
+  }
+
+  /**
+   * Sanitize sprite name to match API requirements (alphanumeric, dashes, underscores only)
+   * @private
+   * @param {string} sessionId - Session identifier
+   * @returns {string} Sanitized sprite name
+   */
+  _sanitizeSpriteName(sessionId) {
+    // Remove non-alphanumeric except dashes and underscores, limit length
+    const sanitized = String(sessionId)
+      .replace(/[^a-zA-Z0-9_-]/g, '')
+      .substring(0, 50);
+    return `teleport-${sanitized}`;
+  }
+
+  /**
+   * Create a remote Sprites workspace
+   *
+   * Provisions a new Sprites micro-VM with:
+   * - Git repository cloned automatically
+   * - SSH access configured
+   * - LivePort tunnel setup
+   * - All secrets stored in Vault
+   * - Auto-hibernate when inactive
+   *
+   * @param {Object} sessionConfig - Session configuration (see BaseProvider)
+   * @returns {Promise<Object>} Sprite details with IDs for cleanup
+   * @throws {Error} If sprite creation fails
+   */
+  async createMachine(sessionConfig) {
+    this._validateSessionConfig(sessionConfig);
+
+    const sessionId = sessionConfig.sessionId;
+    const spriteName = this._sanitizeSpriteName(sessionId);
+    const namespace = `teleportationsprite${String(sessionId).replace(/[^a-zA-Z0-9]/g, '')}`;
+
+    // 1. Setup SSH access
+    const ssh = await this._setupSSHAccess(sessionId, namespace);
+
+    // 2. Setup LivePort tunnel
+    const tunnel = await this._setupTunnel(sessionId, spriteName);
+
+    // 3. Store necessary secrets in Vault
+    const secrets = {
+      RELAY_API_URL: sessionConfig.relayApiUrl,
+      RELAY_API_KEY: sessionConfig.relayApiKey,
+      GITHUB_TOKEN: sessionConfig.githubToken,
+      MECH_API_KEY: sessionConfig.mechApiKey,
+      LIVEPORT_BRIDGE_KEY: tunnel.bridgeKey,
+      ...sessionConfig.additionalSecrets,
+    };
+
+    const secretIds = await this._storeSecrets(namespace, secrets);
+
+    // 4. Create sprite configuration
+    const spriteConfig = {
+      name: spriteName,
+      url_settings: {
+        auth: 'sprite', // Use Sprites-native auth
+      },
+      // Image with development tools pre-installed
+      image: sessionConfig.image || 'oven/bun:latest',
+      // Resource allocation
+      guest: {
+        cpus: sessionConfig.cpus || 1,
+        memory_mb: sessionConfig.memory || 2048,
+      },
+      // Metadata for tracking
+      metadata: {
+        session_id: sessionId,
+        provider: 'SpritesProvider',
+        created_at: new Date().toISOString(),
+      },
+    };
+
+    // 5. Create the sprite
+    const createUrl = `${this.apiUrl}/sprites`;
+    const response = await this._fetchWithTimeout(createUrl, {
+      method: 'POST',
+      headers: this._headers(),
+      body: JSON.stringify(spriteConfig),
+    });
+
+    if (!response.ok) {
+      // Cleanup on failure
+      await this._cleanup(namespace, tunnel.keyId, ssh.keyId);
+      throw new Error(await this._formatApiError(response, createUrl));
+    }
+
+    const sprite = await response.json();
+
+    // 6. Execute bootstrap script on the sprite
+    try {
+      const bootstrapScript = this._generateBootstrapScript(sessionConfig, tunnel, ssh);
+      await this._executeBootstrap(spriteName, bootstrapScript);
+    } catch (error) {
+      // Cleanup on bootstrap failure
+      console.error(`[sprites-provider] Bootstrap failed: ${error.message}`);
+      await this.destroyMachine(spriteName).catch(() => {});
+      await this._cleanup(namespace, tunnel.keyId, ssh.keyId);
+      throw new Error(`Sprite bootstrap failed: ${error.message}`);
+    }
+
+    return {
+      machineId: spriteName,
+      spriteName,
+      spriteUrl: sprite.url || `https://${spriteName}.sprites.dev`,
+      tunnelUrl: tunnel.tunnelUrl,
+      namespace,
+      secretIds,
+      sshKeyId: ssh.keyId,
+      bridgeKeyId: tunnel.keyId,
+      status: sprite.state || 'running',
+    };
+  }
+
+  /**
+   * Generate bootstrap script for Sprites workspace
+   *
+   * This script runs after the sprite is created and sets up:
+   * - SSH authorized keys
+   * - Git repository clone
+   * - Apply uncommitted changes (if any)
+   * - Environment variables
+   * - Transcript file placement
+   * - LivePort tunnel
+   * - CLI resume
+   *
+   * SECURITY: All user-provided values MUST be escaped to prevent shell injection.
+   *
+   * @private
+   * @param {Object} sessionConfig - Session configuration
+   * @param {Object} tunnel - Tunnel configuration with tunnelCommand
+   * @param {Object} ssh - SSH key with publicKey
+   * @returns {string} Shell script for sprite initialization
+   */
+  _generateBootstrapScript(sessionConfig, tunnel, ssh) {
+    // CRITICAL: Escape all user-provided values to prevent command injection
+    const safePublicKey = this._escapeShellArg(ssh.publicKey);
+    const safeRepoUrl = this._escapeShellArg(sessionConfig.repoUrl);
+    const safeBranch = this._escapeShellArg(sessionConfig.branch || 'main');
+    const safeSessionId = this._escapeShellArg(sessionConfig.sessionId);
+    const safeTask = this._escapeShellArg(sessionConfig.task || '');
+    const safeRelayApiUrl = this._escapeShellArg(sessionConfig.relayApiUrl);
+    const safeRelayApiKey = this._escapeShellArg(sessionConfig.relayApiKey);
+    const safeGithubToken = this._escapeShellArg(sessionConfig.githubToken || '');
+    const safeTunnelCommand = tunnel.tunnelCommand; // This is generated internally, not user input
+
+    // Build script with escaped values
+    return `#!/bin/bash
+set -e
+
+echo "[bootstrap] Starting sprite initialization..."
+
+# Setup SSH key for access
+mkdir -p ~/.ssh
+echo ${safePublicKey} >> ~/.ssh/authorized_keys
+chmod 700 ~/.ssh
+chmod 600 ~/.ssh/authorized_keys
+
+# Configure git to use token for authentication
+# SECURITY: Use printf with %s to safely interpolate the token without shell interpretation
+# This prevents command injection even if the token contains special characters
+git config --global credential.helper store
+if [ -n ${safeGithubToken} ] && [ ${safeGithubToken} != "''" ]; then
+  printf 'https://oauth2:%s@github.com\n' ${safeGithubToken} > ~/.git-credentials
+  chmod 600 ~/.git-credentials
+fi
+
+# Clone repository
+echo "[bootstrap] Cloning repository..."
+cd /workspace
+git clone ${safeRepoUrl} repo || { echo "Git clone failed"; exit 1; }
+cd repo
+
+# Checkout specified branch
+git checkout ${safeBranch} || git checkout -b ${safeBranch}
+
+# Apply uncommitted changes if provided
+if [ -n "${sessionConfig.patch ? '1' : ''}" ]; then
+  echo "[bootstrap] Applying uncommitted changes..."
+  echo ${this._escapeShellArg(sessionConfig.patch || '')} | base64 -d | git apply --allow-empty || echo "Patch apply warning (continuing)"
+fi
+
+# Set environment variables
+export RELAY_API_URL=${safeRelayApiUrl}
+export RELAY_API_KEY=${safeRelayApiKey}
+export SESSION_ID=${safeSessionId}
+
+# Install dependencies
+echo "[bootstrap] Installing dependencies..."
+bun install || npm install
+
+# Start LivePort tunnel in background
+echo "[bootstrap] Starting LivePort tunnel..."
+${safeTunnelCommand} &
+TUNNEL_PID=$!
+
+# Wait for tunnel to be ready
+for i in 1 2 3 4 5; do
+  if ! kill -0 "$TUNNEL_PID" 2>/dev/null; then
+    echo "[bootstrap] LivePort tunnel failed to start"
+    exit 1
+  fi
+  sleep 1
+done
+
+echo "[bootstrap] Sprite ready!"
+
+# If a task was provided, start the teleportation daemon
+if [ -n ${safeTask} ] && [ ${safeTask} != "''" ]; then
+  echo "[bootstrap] Starting task: ${safeTask}"
+  bun teleportation-cli.cjs daemon start --session-id ${safeSessionId} --task ${safeTask} &
+fi
+`;
+  }
+
+  /**
+   * Execute bootstrap script on sprite
+   *
+   * Bootstrap operations (git clone, package install, etc.) can take significant time,
+   * so we use a longer timeout (5 minutes) than normal API requests.
+   *
+   * @private
+   * @param {string} spriteName - Sprite name
+   * @param {string} script - Bootstrap script to execute
+   * @returns {Promise<Object>} Execution result
+   * @throws {Error} If bootstrap times out or fails
+   */
+  async _executeBootstrap(spriteName, script) {
+    const BOOTSTRAP_TIMEOUT_MS = 300000; // 5 minutes for git clone + npm/bun install
+
+    const result = await this.executeCommand(spriteName, script, { timeout: BOOTSTRAP_TIMEOUT_MS });
+    if (result.exitCode !== 0) {
+      throw new Error(`Bootstrap script failed with exit code ${result.exitCode}: ${result.stderr}`);
+    }
+    return result;
+  }
+
+  /**
+   * Execute command on sprite
+   *
+   * @param {string} spriteName - Sprite name
+   * @param {string} command - Command to execute
+   * @param {Object} [options] - Execution options
+   * @param {number} [options.timeout] - Custom timeout in ms (default: this.timeout)
+   * @returns {Promise<Object>} Execution result
+   * @returns {string} return.stdout - Standard output
+   * @returns {string} return.stderr - Standard error
+   * @returns {number} return.exitCode - Exit code
+   * @throws {Error} If execution fails or times out
+   */
+  async executeCommand(spriteName, command, options = {}) {
+    this._validateMachineId(spriteName);
+
+    const url = `${this.apiUrl}/sprites/${spriteName}/exec`;
+    const response = await this._fetchWithTimeout(url, {
+      method: 'POST',
+      headers: this._headers(),
+      body: JSON.stringify({ command }),
+    }, options.timeout);
+
+    if (!response.ok) {
+      throw new Error(await this._formatApiError(response, url));
+    }
+
+    const result = await response.json();
+    return {
+      stdout: result.stdout || '',
+      stderr: result.stderr || '',
+      exitCode: result.exit_code ?? result.exitCode ?? 0,
+    };
+  }
+
+  /**
+   * Create a checkpoint of the sprite's current state
+   *
+   * Sprites checkpoints are fast (~300ms) and allow instant restore.
+   *
+   * @param {string} spriteName - Sprite name
+   * @param {string} [comment] - Optional comment for the checkpoint
+   * @returns {Promise<Object>} Checkpoint details
+   * @returns {string} return.checkpointId - Unique checkpoint ID
+   * @returns {string} return.createdAt - Checkpoint creation timestamp
+   * @throws {Error} If checkpoint creation fails
+   */
+  async createCheckpoint(spriteName, comment = '') {
+    this._validateMachineId(spriteName);
+
+    const url = `${this.apiUrl}/sprites/${spriteName}/checkpoints`;
+    const response = await this._fetchWithTimeout(url, {
+      method: 'POST',
+      headers: this._headers(),
+      body: JSON.stringify({
+        comment: comment || `Checkpoint at ${new Date().toISOString()}`,
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(await this._formatApiError(response, url));
+    }
+
+    const checkpoint = await response.json();
+    return {
+      checkpointId: checkpoint.id,
+      createdAt: checkpoint.created_at || checkpoint.createdAt,
+      comment: checkpoint.comment,
+    };
+  }
+
+  /**
+   * List all checkpoints for a sprite
+   *
+   * @param {string} spriteName - Sprite name
+   * @returns {Promise<Array>} Array of checkpoint objects
+   * @throws {Error} If listing fails
+   */
+  async listCheckpoints(spriteName) {
+    this._validateMachineId(spriteName);
+
+    const url = `${this.apiUrl}/sprites/${spriteName}/checkpoints`;
+    const response = await this._fetchWithTimeout(url, {
+      method: 'GET',
+      headers: this._headers(),
+    });
+
+    if (!response.ok) {
+      throw new Error(await this._formatApiError(response, url));
+    }
+
+    const data = await response.json();
+    return data.checkpoints || data || [];
+  }
+
+  /**
+   * Restore sprite to a previous checkpoint
+   *
+   * @param {string} spriteName - Sprite name
+   * @param {string} checkpointId - Checkpoint ID to restore
+   * @returns {Promise<Object>} Restore result
+   * @throws {Error} If restore fails
+   */
+  async restoreCheckpoint(spriteName, checkpointId) {
+    this._validateMachineId(spriteName);
+
+    if (!checkpointId) {
+      throw new Error('Checkpoint ID is required for restore');
+    }
+
+    const url = `${this.apiUrl}/sprites/${spriteName}/restore`;
+    const response = await this._fetchWithTimeout(url, {
+      method: 'POST',
+      headers: this._headers(),
+      body: JSON.stringify({ checkpoint_id: checkpointId }),
+    });
+
+    if (!response.ok) {
+      throw new Error(await this._formatApiError(response, url));
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Destroy the sprite
+   *
+   * Permanently deletes the sprite and all its checkpoints.
+   *
+   * @param {string} spriteName - Sprite name
+   * @returns {Promise<boolean>} True if destroyed successfully
+   * @throws {Error} If destruction fails (except 404 which is success)
+   */
+  async destroyMachine(spriteName) {
+    this._validateMachineId(spriteName);
+
+    const url = `${this.apiUrl}/sprites/${spriteName}`;
+    const response = await this._fetchWithTimeout(url, {
+      method: 'DELETE',
+      headers: this._headers(),
+    });
+
+    // 404 means already deleted - treat as success
+    if (response.status === 404) {
+      return true;
+    }
+
+    if (!response.ok) {
+      throw new Error(await this._formatApiError(response, url));
+    }
+
+    return true;
+  }
+
+  /**
+   * Get sprite status
+   *
+   * Returns current state of the sprite.
+   *
+   * @param {string} spriteName - Sprite name
+   * @returns {Promise<Object>} Sprite status
+   * @returns {string} return.status - Sprite state ('cold', 'warm', 'running')
+   * @returns {string} return.url - Sprite URL
+   * @returns {string} return.createdAt - Creation timestamp
+   * @returns {string} return.lastActive - Last activity timestamp
+   * @throws {Error} If status fetch fails
+   */
+  async getMachineStatus(spriteName) {
+    this._validateMachineId(spriteName);
+
+    const url = `${this.apiUrl}/sprites/${spriteName}`;
+    const response = await this._fetchWithTimeout(url, {
+      method: 'GET',
+      headers: this._headers(),
+    });
+
+    if (!response.ok) {
+      throw new Error(await this._formatApiError(response, url));
+    }
+
+    const sprite = await response.json();
+
+    // Map Sprites states to standardized status
+    const statusMap = {
+      'cold': 'stopped',
+      'warm': 'hibernating',
+      'running': 'running',
+      'starting': 'starting',
+      'stopping': 'stopping',
+    };
+
+    return {
+      status: statusMap[sprite.state] || sprite.state || 'unknown',
+      url: sprite.url,
+      createdAt: sprite.created_at || sprite.createdAt,
+      lastActive: sprite.last_active || sprite.lastActive,
+      state: sprite.state, // Original Sprites state
+    };
+  }
+
+  /**
+   * Get sprite logs
+   *
+   * @param {string} spriteName - Sprite name
+   * @param {Object} [options] - Log retrieval options
+   * @param {number} [options.tail] - Number of lines to retrieve
+   * @param {boolean} [options.follow] - Stream logs (not implemented)
+   * @returns {Promise<Object>} Log data
+   * @throws {Error} If log retrieval fails
+   */
+  async getLogs(spriteName, options = {}) {
+    this._validateMachineId(spriteName);
+
+    const params = new URLSearchParams();
+    if (options.tail) params.set('tail', options.tail);
+
+    const url = `${this.apiUrl}/sprites/${spriteName}/logs${params.toString() ? '?' + params : ''}`;
+    const response = await this._fetchWithTimeout(url, {
+      method: 'GET',
+      headers: this._headers(),
+    });
+
+    if (!response.ok) {
+      throw new Error(await this._formatApiError(response, url));
+    }
+
+    const data = await response.json();
+    return {
+      logs: data.logs || data || [],
+    };
+  }
+
+  /**
+   * Wake up a hibernating sprite
+   *
+   * Sprites auto-hibernate after 30 seconds of inactivity.
+   * This method wakes them up.
+   *
+   * @param {string} spriteName - Sprite name
+   * @returns {Promise<Object>} Wake result
+   * @throws {Error} If wake fails
+   */
+  async wakeSprite(spriteName) {
+    this._validateMachineId(spriteName);
+
+    const url = `${this.apiUrl}/sprites/${spriteName}/wake`;
+    const response = await this._fetchWithTimeout(url, {
+      method: 'POST',
+      headers: this._headers(),
+    });
+
+    if (!response.ok) {
+      throw new Error(await this._formatApiError(response, url));
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Get provider capabilities
+   *
+   * @returns {Object} Provider capabilities
+   */
+  getCapabilities() {
+    return {
+      supportsCheckpoints: true,
+      supportsSnapshots: true,
+      supportsHibernation: true,
+      supportsAutoStop: true,
+      autoHibernate: true,
+      bootTime: 10000, // ~10 seconds
+      checkpointTime: 300, // ~300ms
+      supportsResume: true,
+      provider: 'sprites',
+    };
+  }
+
+  /**
+   * Check provider health
+   *
+   * @returns {Promise<Object>} Health check result
+   */
+  async checkHealth() {
+    try {
+      // Try to list sprites - if this works, the API is healthy
+      const url = `${this.apiUrl}/sprites`;
+      const response = await this._fetchWithTimeout(url, {
+        method: 'GET',
+        headers: this._headers(),
+      }, 10000); // 10 second timeout for health check
+
+      if (!response.ok) {
+        return {
+          healthy: false,
+          provider: 'sprites',
+          error: `API returned status ${response.status}`,
+        };
+      }
+
+      return {
+        healthy: true,
+        provider: 'sprites',
+        details: {
+          apiUrl: this.apiUrl,
+          timestamp: new Date().toISOString(),
+        },
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        provider: 'sprites',
+        error: error.message,
+      };
+    }
+  }
+
+  /**
+   * Update sprite labels/tags
+   *
+   * @param {string} spriteName - Sprite name
+   * @param {Object} labels - Key-value pairs of labels
+   * @returns {Promise<Object>} Updated sprite info
+   */
+  async updateLabels(spriteName, labels) {
+    this._validateMachineId(spriteName);
+
+    if (!labels || typeof labels !== 'object') {
+      throw new Error('Labels must be an object');
+    }
+
+    const url = `${this.apiUrl}/sprites/${spriteName}`;
+    const response = await this._fetchWithTimeout(url, {
+      method: 'PATCH',
+      headers: this._headers(),
+      body: JSON.stringify({ labels }),
+    });
+
+    if (!response.ok) {
+      throw new Error(await this._formatApiError(response, url));
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Get sprite labels
+   *
+   * @param {string} spriteName - Sprite name
+   * @returns {Promise<Object>} Labels object
+   */
+  async getLabels(spriteName) {
+    const status = await this.getMachineStatus(spriteName);
+    return status.labels || {};
+  }
+}
+
+export default SpritesProvider;