teleportation-cli 1.1.5 → 1.2.1

package/lib/teleport/manager.js

@@ -0,0 +1,620 @@
+/**
+ * Teleport Manager
+ *
+ * Orchestrates the full teleportation flow:
+ * 1. Capture local session state
+ * 2. Upload state to relay API
+ * 3. Provision cloud environment
+ * 4. Export and upload transcript
+ * 5. Resume session on cloud
+ *
+ * @module lib/teleport/manager
+ */
+
+import { nanoid } from 'nanoid';
+import { captureSessionState } from './session-capture.js';
+import { getExporterForCoder } from './exporters/index.js';
+import { GitCommitter } from './git-committer.js';
+import { ResultsDelivery } from '../remote/results-delivery.js';
+
+/**
+ * Teleport modes
+ * @enum {string}
+ */
+export const TeleportMode = {
+  /** Pause local session, continue on cloud */
+  PAUSE: 'pause',
+  /** Fork: local continues, cloud runs in parallel */
+  FORK: 'fork',
+};
+
+/**
+ * Teleport status
+ * @enum {string}
+ */
+export const TeleportStatus = {
+  PENDING: 'pending',
+  CAPTURING: 'capturing',
+  UPLOADING: 'uploading',
+  PROVISIONING: 'provisioning',
+  EXPORTING: 'exporting',
+  RESUMING: 'resuming',
+  RUNNING: 'running',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+};
+
+/**
+ * TeleportManager orchestrates session teleportation to cloud environments.
+ */
+export class TeleportManager {
+  /**
+   * Initialize TeleportManager
+   *
+   * @param {Object} config - Manager configuration
+   * @param {Object} config.providerFactory - Provider factory instance
+   * @param {string} config.relayApiUrl - Relay API URL
+   * @param {string} config.relayApiKey - Relay API key
+   * @param {Object} [config.vaultClient] - Vault client for secrets
+   * @param {Object} [config.livePortClient] - LivePort client for tunnels
+   */
+  constructor(config) {
+    if (!config) {
+      throw new Error('TeleportManager config is required');
+    }
+    if (!config.providerFactory) {
+      throw new Error('providerFactory is required');
+    }
+    if (!config.relayApiUrl) {
+      throw new Error('relayApiUrl is required');
+    }
+    if (!config.relayApiKey) {
+      throw new Error('relayApiKey is required');
+    }
+
+    this.providerFactory = config.providerFactory;
+    this.relayApiUrl = config.relayApiUrl;
+    this.relayApiKey = config.relayApiKey;
+    this.vaultClient = config.vaultClient;
+    this.livePortClient = config.livePortClient;
+
+    // Track active teleports
+    this.activeTeleports = new Map();
+  }
+
+  /**
+   * Initiate a teleportation session.
+   *
+   * @param {string} sessionId - Local session ID
+   * @param {Object} options - Teleport options
+   * @param {string} [options.provider] - Force specific provider
+   * @param {string} [options.targetCoder='claude-code'] - Target CLI (claude-code, gemini-cli)
+   * @param {TeleportMode} [options.mode='pause'] - Teleport mode
+   * @param {string} [options.task] - Task description for the cloud session
+   * @param {string} [options.cwd] - Working directory
+   * @param {string} [options.claudeSessionId] - Claude session ID for transcript
+   * @param {string} [options.githubToken] - GitHub token for repo access
+   * @param {Function} [options.onProgress] - Progress callback
+   * @returns {Promise<Object>} Teleport result
+   */
+  async initiateTeleport(sessionId, options = {}) {
+    const {
+      provider,
+      targetCoder = 'claude-code',
+      mode = TeleportMode.PAUSE,
+      task,
+      cwd,
+      claudeSessionId,
+      githubToken,
+      onProgress,
+      commitInterval,
+    } = options;
+
+    // Generate teleport ID
+    const teleportId = `tel_${nanoid(12)}`;
+
+    // Initialize teleport state
+    const teleportState = {
+      teleportId,
+      sessionId,
+      status: TeleportStatus.PENDING,
+      targetCoder,
+      mode,
+      task,
+      createdAt: new Date().toISOString(),
+      provider: null,
+      machineId: null,
+      error: null,
+      gitCommitter: null,
+    };
+
+    this.activeTeleports.set(teleportId, teleportState);
+
+    try {
+      // Step 1: Capture session state
+      this._updateStatus(teleportId, TeleportStatus.CAPTURING, onProgress);
+      const sessionState = await this._captureSession(sessionId, {
+        cwd,
+        claudeSessionId,
+      });
+
+      // Store session state for later use (e.g., deliverResults)
+      teleportState.sessionState = sessionState;
+
+      // Step 2: Upload session state to relay
+      this._updateStatus(teleportId, TeleportStatus.UPLOADING, onProgress);
+      const teleportRecord = await this._uploadSessionState(teleportId, sessionId, sessionState, {
+        targetCoder,
+        mode,
+        task,
+      });
+
+      // Step 3: Provision cloud environment
+      this._updateStatus(teleportId, TeleportStatus.PROVISIONING, onProgress);
+      const cloudMachine = await this._provisionCloud(teleportId, sessionState, {
+        provider,
+        targetCoder,
+        task,
+        githubToken,
+      });
+
+      teleportState.provider = cloudMachine.provider;
+      teleportState.machineId = cloudMachine.machineId;
+
+      // Step 4: Export and upload transcript
+      this._updateStatus(teleportId, TeleportStatus.EXPORTING, onProgress);
+      const transcriptPath = await this._prepareTranscript(sessionId, targetCoder, cloudMachine);
+
+      // Step 5: Resume session on cloud
+      this._updateStatus(teleportId, TeleportStatus.RESUMING, onProgress);
+      await this._resumeSession(teleportId, cloudMachine, transcriptPath, {
+        targetCoder,
+        task,
+        claudeSessionId,
+      });
+
+      // Success!
+      this._updateStatus(teleportId, TeleportStatus.RUNNING, onProgress);
+
+      // Start auto-commit if we have repo info
+      if (sessionState.git && sessionState.cwd) {
+        const gitCommitter = new GitCommitter({
+          repoPath: sessionState.cwd,
+          branch: `teleport/${teleportId}`,
+          teleportId,
+          interval: options.commitInterval,
+        });
+
+        teleportState.gitCommitter = gitCommitter;
+        gitCommitter.startAutoCommit();
+      }
+
+      return {
+        teleportId,
+        sessionId,
+        provider: cloudMachine.provider,
+        machineId: cloudMachine.machineId,
+        spriteUrl: cloudMachine.spriteUrl,
+        tunnelUrl: cloudMachine.tunnelUrl,
+        targetCoder,
+        mode,
+        status: TeleportStatus.RUNNING,
+        timelineUrl: `${this.relayApiUrl}/sessions/${sessionId}/timeline`,
+      };
+    } catch (error) {
+      teleportState.status = TeleportStatus.FAILED;
+      teleportState.error = error.message;
+
+      // Attempt cleanup on failure
+      await this._cleanupOnError(teleportId, teleportState);
+
+      throw error;
+    }
+  }
+
+  /**
+   * Capture local session state.
+   *
+   * @private
+   * @param {string} sessionId - Session ID
+   * @param {Object} options - Capture options
+   * @returns {Promise<Object>} Session state
+   */
+  async _captureSession(sessionId, options = {}) {
+    return captureSessionState(sessionId, {
+      cwd: options.cwd,
+      claudeSessionId: options.claudeSessionId,
+      includeUntracked: false, // Don't include untracked files by default
+    });
+  }
+
+  /**
+   * Upload session state to relay API.
+   *
+   * @private
+   * @param {string} teleportId - Teleport ID
+   * @param {string} sessionId - Session ID
+   * @param {Object} sessionState - Captured session state
+   * @param {Object} options - Upload options
+   * @returns {Promise<Object>} Teleport record from relay
+   */
+  async _uploadSessionState(teleportId, sessionId, sessionState, options = {}) {
+    const response = await fetch(`${this.relayApiUrl}/api/sessions/${sessionId}/teleport`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.relayApiKey}`,
+      },
+      body: JSON.stringify({
+        teleport_id: teleportId,
+        git_state: sessionState.git,
+        patch: sessionState.patch,
+        target_coder: options.targetCoder,
+        mode: options.mode,
+        task: options.task,
+        meta: sessionState.meta,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Failed to upload session state: ${response.status} ${error}`);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Provision cloud environment.
+   *
+   * @private
+   * @param {string} teleportId - Teleport ID
+   * @param {Object} sessionState - Session state
+   * @param {Object} options - Provisioning options
+   * @returns {Promise<Object>} Cloud machine details
+   */
+  async _provisionCloud(teleportId, sessionState, options = {}) {
+    // Select provider based on task or explicit choice
+    const providerType = this.providerFactory.selectProvider(
+      options.task || '',
+      { provider: options.provider }
+    );
+
+    // Create provider instance
+    const provider = this.providerFactory.createProvider(providerType);
+
+    // Configure session for cloud
+    const sessionConfig = {
+      sessionId: teleportId,
+      repoUrl: sessionState.git.repoUrl,
+      branch: sessionState.git.branch,
+      relayApiUrl: this.relayApiUrl,
+      relayApiKey: this.relayApiKey,
+      githubToken: options.githubToken || process.env.GITHUB_TOKEN,
+      mechApiKey: process.env.MECH_API_KEY,
+      task: options.task,
+      patch: sessionState.patch,
+    };
+
+    // Create the machine
+    const machine = await provider.createMachine(sessionConfig);
+
+    return {
+      provider: providerType,
+      machineId: machine.machineId,
+      spriteUrl: machine.spriteUrl,
+      tunnelUrl: machine.tunnelUrl,
+      namespace: machine.namespace,
+      sshKeyId: machine.sshKeyId,
+      bridgeKeyId: machine.bridgeKeyId,
+    };
+  }
+
+  /**
+   * Prepare and upload transcript for target CLI.
+   *
+   * @private
+   * @param {string} sessionId - Session ID
+   * @param {string} targetCoder - Target CLI name
+   * @param {Object} cloudMachine - Cloud machine details
+   * @returns {Promise<string>} Transcript path on cloud
+   */
+  async _prepareTranscript(sessionId, targetCoder, cloudMachine) {
+    // Fetch timeline events from relay
+    const response = await fetch(`${this.relayApiUrl}/api/sessions/${sessionId}/timeline`, {
+      headers: {
+        'Authorization': `Bearer ${this.relayApiKey}`,
+      },
+    });
+
+    if (!response.ok) {
+      // Timeline might not exist yet - that's OK
+      if (response.status === 404) {
+        return null;
+      }
+      throw new Error(`Failed to fetch timeline: ${response.status}`);
+    }
+
+    const timeline = await response.json();
+    const events = timeline.events || [];
+
+    if (events.length === 0) {
+      return null; // No transcript to export
+    }
+
+    // Get appropriate exporter
+    const exporter = await getExporterForCoder(targetCoder);
+
+    // Export to CLI format
+    const transcript = await exporter.export(events);
+
+    // Upload transcript to relay for cloud to download
+    const uploadResponse = await fetch(
+      `${this.relayApiUrl}/api/teleports/${cloudMachine.machineId}/transcript`,
+      {
+        method: 'PUT',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${this.relayApiKey}`,
+        },
+        body: JSON.stringify({
+          content: transcript,
+          format: targetCoder,
+        }),
+      }
+    );
+
+    if (!uploadResponse.ok) {
+      throw new Error(`Failed to upload transcript: ${uploadResponse.status}`);
+    }
+
+    const result = await uploadResponse.json();
+    return result.path;
+  }
+
+  /**
+   * Resume session on cloud environment.
+   *
+   * @private
+   * @param {string} teleportId - Teleport ID
+   * @param {Object} cloudMachine - Cloud machine details
+   * @param {string|null} transcriptPath - Path to transcript on cloud
+   * @param {Object} options - Resume options
+   * @returns {Promise<void>}
+   */
+  async _resumeSession(teleportId, cloudMachine, transcriptPath, options = {}) {
+    // The bootstrap script on the cloud should handle:
+    // 1. Writing transcript to CLI-native location
+    // 2. Starting the CLI with --resume flag
+    // 3. Starting the teleportation daemon
+
+    // Notify relay that teleport is ready
+    await fetch(`${this.relayApiUrl}/api/teleports/${teleportId}/ready`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.relayApiKey}`,
+      },
+      body: JSON.stringify({
+        machine_id: cloudMachine.machineId,
+        provider: cloudMachine.provider,
+        transcript_path: transcriptPath,
+        target_coder: options.targetCoder,
+      }),
+    });
+  }
+
+  /**
+   * Update teleport status and notify callback.
+   *
+   * @private
+   * @param {string} teleportId - Teleport ID
+   * @param {TeleportStatus} status - New status
+   * @param {Function} [onProgress] - Progress callback
+   */
+  _updateStatus(teleportId, status, onProgress) {
+    const state = this.activeTeleports.get(teleportId);
+    if (state) {
+      state.status = status;
+      state.updatedAt = new Date().toISOString();
+    }
+
+    if (onProgress) {
+      onProgress({ teleportId, status });
+    }
+  }
+
+  /**
+   * Cleanup resources on error.
+   *
+   * @private
+   * @param {string} teleportId - Teleport ID
+   * @param {Object} teleportState - Teleport state
+   */
+  async _cleanupOnError(teleportId, teleportState) {
+    try {
+      // Stop auto-commits
+      if (teleportState.gitCommitter) {
+        teleportState.gitCommitter.stopAutoCommit();
+      }
+
+      if (teleportState.machineId && teleportState.provider) {
+        const provider = this.providerFactory.createProvider(teleportState.provider);
+        await provider.destroyMachine(teleportState.machineId);
+      }
+    } catch (cleanupError) {
+      console.error(`[teleport-manager] Cleanup failed for ${teleportId}:`, cleanupError.message);
+    }
+  }
+
+  /**
+   * Get teleport status.
+   *
+   * @param {string} teleportId - Teleport ID
+   * @returns {Object|null} Teleport state or null if not found
+   */
+  getTeleportStatus(teleportId) {
+    return this.activeTeleports.get(teleportId) || null;
+  }
+
+  /**
+   * Stop a running teleport and destroy cloud resources.
+   *
+   * @param {string} teleportId - Teleport ID
+   * @param {Object} [options] - Stop options
+   * @param {boolean} [options.success=true] - Whether task completed successfully
+   * @param {string} [options.description] - Final commit description
+   * @param {string} [options.reason] - Reason for stopping (if not success)
+   * @param {boolean} [options.createPR=false] - Whether to create PR with results
+   * @param {string} [options.baseBranch] - Base branch for PR
+   * @returns {Promise<Object>} Stop result with optional PR details
+   */
+  async stopTeleport(teleportId, options = {}) {
+    const state = this.activeTeleports.get(teleportId);
+    if (!state) {
+      return { success: false, error: 'Teleport not found' };
+    }
+
+    const { success = true, description, reason, createPR = false, baseBranch } = options;
+
+    try {
+      // Stop auto-commits and create final commit
+      if (state.gitCommitter) {
+        state.gitCommitter.stopAutoCommit();
+
+        if (success) {
+          await state.gitCommitter.createFinalCommit(
+            description || state.task || 'Task completed'
+          );
+        } else {
+          await state.gitCommitter.createPartialCommit(
+            description || 'Partial work completed',
+            reason || 'Session stopped'
+          );
+        }
+
+        // Push to remote before destroying machine
+        if (createPR) {
+          try {
+            await state.gitCommitter.push();
+          } catch (pushError) {
+            console.error(`[teleport-manager] Push failed: ${pushError.message}`);
+          }
+        }
+      }
+
+      if (state.machineId && state.provider) {
+        const provider = this.providerFactory.createProvider(state.provider);
+        await provider.destroyMachine(state.machineId);
+      }
+
+      state.status = TeleportStatus.COMPLETED;
+      state.completedAt = new Date().toISOString();
+
+      const result = { success: true };
+
+      // Create PR if requested
+      if (createPR) {
+        try {
+          const deliveryResult = await this.deliverResults(teleportId, { baseBranch });
+          result.delivery = deliveryResult;
+        } catch (deliveryError) {
+          result.deliveryError = deliveryError.message;
+        }
+      }
+
+      return result;
+    } catch (error) {
+      state.error = error.message;
+      throw error;
+    }
+  }
+
+  /**
+   * List all active teleports.
+   *
+   * @returns {Object[]} Array of teleport states
+   */
+  listActiveTeleports() {
+    return Array.from(this.activeTeleports.values());
+  }
+
+  /**
+   * Update activity description for WIP commits.
+   *
+   * @param {string} teleportId - Teleport ID
+   * @param {string} activity - Current activity description
+   */
+  updateActivity(teleportId, activity) {
+    const state = this.activeTeleports.get(teleportId);
+    if (state && state.gitCommitter) {
+      state.gitCommitter.updateActivity(activity);
+    }
+  }
+
+  /**
+   * Get commit statistics for a teleport session.
+   *
+   * @param {string} teleportId - Teleport ID
+   * @returns {Object|null} Commit stats or null if not found
+   */
+  getCommitStats(teleportId) {
+    const state = this.activeTeleports.get(teleportId);
+    if (state && state.gitCommitter) {
+      return state.gitCommitter.getStats();
+    }
+    return null;
+  }
+
+  /**
+   * Deliver results from a completed teleport session.
+   *
+   * Creates a PR (preferred) or falls back to a local branch.
+   *
+   * @param {string} teleportId - Teleport ID
+   * @param {Object} [options] - Delivery options
+   * @param {string} [options.baseBranch] - Base branch for PR (defaults to 'main')
+   * @returns {Promise<Object>} Delivery result
+   */
+  async deliverResults(teleportId, options = {}) {
+    const state = this.activeTeleports.get(teleportId);
+    if (!state) {
+      throw new Error(`Teleport ${teleportId} not found`);
+    }
+
+    if (!state.sessionState || !state.sessionState.cwd) {
+      throw new Error(`No repository path for teleport ${teleportId}`);
+    }
+
+    const remoteBranch = state.gitCommitter?.branch || `teleport/${teleportId}`;
+
+    // Create ResultsDelivery instance
+    const resultsDelivery = new ResultsDelivery({
+      repoPath: state.sessionState.cwd,
+      sessionId: state.sessionId,
+      remoteBranch,
+      verbose: options.verbose,
+    });
+
+    // Deliver results with fallback strategy
+    const result = await resultsDelivery.deliverResults({
+      task: state.task,
+      baseBranch: options.baseBranch,
+      timelineUrl: `${this.relayApiUrl}/sessions/${state.sessionId}/timeline`,
+      metadata: {
+        provider: state.provider,
+        machineId: state.machineId,
+        duration: state.completedAt && state.createdAt
+          ? Math.floor((new Date(state.completedAt) - new Date(state.createdAt)) / 1000)
+          : undefined,
+      },
+    });
+
+    // Update state with delivery result
+    state.deliveryResult = result;
+
+    return result;
+  }
+}
+
+export default TeleportManager;