teleportation-cli 1.0.0 → 1.0.1

package/lib/remote/session-manager.js

@@ -0,0 +1,273 @@
+/**
+ * RemoteSessionManager
+ *
+ * Manages remote session tracking and metadata:
+ * - Register/unregister sessions
+ * - Update session metadata
+ * - List and query sessions
+ * - Cleanup stale sessions
+ * - Session statistics
+ *
+ * Extends existing session registry pattern from lib/session-registry/
+ */
+
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { join } from 'path';
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+
+const DEFAULT_REGISTRY_PATH = join(homedir(), '.teleportation', 'remote-sessions');
+const REGISTRY_FILE = 'sessions.json';
+const DEFAULT_MAX_AGE = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+/**
+ * Remote session entry structure
+ * @typedef {Object} RemoteSessionEntry
+ * @property {string} id - Session ID
+ * @property {string} provider - Provider type (fly, daytona)
+ * @property {string} machineId - Remote machine ID
+ * @property {string} branch - Git branch
+ * @property {string} status - Session status (running, paused, completed, failed)
+ * @property {number} createdAt - Creation timestamp
+ * @property {number} lastActiveAt - Last activity timestamp
+ * @property {Object} metadata - Additional metadata (task, tunnelUrl, etc.)
+ */
+
+/**
+ * RemoteSessionManager class
+ */
+export class RemoteSessionManager {
+  /**
+   * @param {Object} options
+   * @param {string} [options.registryPath] - Custom registry directory path
+   */
+  constructor(options = {}) {
+    this.registryPath = options.registryPath || DEFAULT_REGISTRY_PATH;
+    this.registryFile = join(this.registryPath, REGISTRY_FILE);
+  }
+
+  /**
+   * Load the session registry
+   * @private
+   * @returns {Promise<Array<RemoteSessionEntry>>}
+   */
+  async _loadRegistry() {
+    await mkdir(this.registryPath, { recursive: true, mode: 0o700 });
+
+    if (!existsSync(this.registryFile)) {
+      return [];
+    }
+
+    try {
+      const content = await readFile(this.registryFile, 'utf8');
+      return JSON.parse(content);
+    } catch (error) {
+      console.error(`[RemoteSessionManager] Failed to load registry: ${error.message}`);
+      return [];
+    }
+  }
+
+  /**
+   * Save the session registry
+   * @private
+   * @param {Array<RemoteSessionEntry>} sessions
+   * @returns {Promise<void>}
+   */
+  async _saveRegistry(sessions) {
+    await mkdir(this.registryPath, { recursive: true, mode: 0o700 });
+    await writeFile(this.registryFile, JSON.stringify(sessions, null, 2), { mode: 0o600 });
+  }
+
+  /**
+   * Register a new session
+   * @param {Object} options
+   * @param {string} options.id - Session ID
+   * @param {string} options.provider - Provider type (fly, daytona)
+   * @param {string} options.machineId - Remote machine ID
+   * @param {string} options.branch - Git branch
+   * @param {Object} [options.metadata] - Additional metadata
+   * @param {string} [options.status] - Initial status (default: running)
+   * @returns {Promise<RemoteSessionEntry>}
+   * @throws {Error} If session already exists or required fields are missing
+   *
+   * @note Known limitation: There is a potential race condition if multiple
+   * processes attempt to register the same session ID simultaneously. The check
+   * for existing sessions (line 103) and the save operation (line 120) are not
+   * atomic. This is an acceptable limitation for the current single-user CLI
+   * use case. Future versions may use file locking (e.g., proper-lockfile) or
+   * a database (e.g., SQLite) for multi-user/concurrent scenarios.
+   */
+  async registerSession(options) {
+    const { id, provider, machineId, branch, metadata = {}, status = 'running' } = options;
+
+    // Validate required fields
+    if (!id || !provider || !machineId || !branch) {
+      throw new Error('Required fields: id, provider, machineId, branch');
+    }
+
+    const sessions = await this._loadRegistry();
+
+    // Check if session already exists
+    const existing = sessions.find((s) => s.id === id);
+    if (existing) {
+      throw new Error(`Session ${id} already exists`);
+    }
+
+    const session = {
+      id,
+      provider,
+      machineId,
+      branch,
+      status,
+      createdAt: Date.now(),
+      lastActiveAt: Date.now(),
+      metadata
+    };
+
+    sessions.push(session);
+    await this._saveRegistry(sessions);
+
+    return session;
+  }
+
+  /**
+   * Update session metadata or status
+   * @param {string} sessionId - Session ID
+   * @param {Object} updates - Fields to update
+   * @returns {Promise<RemoteSessionEntry>}
+   */
+  async updateSession(sessionId, updates) {
+    const sessions = await this._loadRegistry();
+    const session = sessions.find((s) => s.id === sessionId);
+
+    if (!session) {
+      throw new Error(`Session ${sessionId} not found`);
+    }
+
+    // Update fields
+    if (updates.status !== undefined) {
+      session.status = updates.status;
+    }
+
+    if (updates.metadata !== undefined) {
+      session.metadata = { ...session.metadata, ...updates.metadata };
+    }
+
+    // Always update lastActiveAt
+    session.lastActiveAt = Date.now();
+
+    await this._saveRegistry(sessions);
+
+    return session;
+  }
+
+  /**
+   * List sessions with optional filtering
+   * @param {Object} filters
+   * @param {string} [filters.status] - Filter by status
+   * @param {string} [filters.provider] - Filter by provider
+   * @returns {Promise<Array<RemoteSessionEntry>>}
+   */
+  async listSessions(filters = {}) {
+    let sessions = await this._loadRegistry();
+
+    // Apply filters
+    if (filters.status) {
+      sessions = sessions.filter((s) => s.status === filters.status);
+    }
+
+    if (filters.provider) {
+      sessions = sessions.filter((s) => s.provider === filters.provider);
+    }
+
+    // Sort by createdAt descending (newest first)
+    sessions.sort((a, b) => b.createdAt - a.createdAt);
+
+    return sessions;
+  }
+
+  /**
+   * Get session by ID
+   * @param {string} sessionId - Session ID
+   * @returns {Promise<RemoteSessionEntry|null>}
+   */
+  async getSession(sessionId) {
+    const sessions = await this._loadRegistry();
+    return sessions.find((s) => s.id === sessionId) || null;
+  }
+
+  /**
+   * Unregister (remove) a session
+   * @param {string} sessionId - Session ID
+   * @returns {Promise<void>}
+   */
+  async unregisterSession(sessionId) {
+    const sessions = await this._loadRegistry();
+    const filtered = sessions.filter((s) => s.id !== sessionId);
+
+    if (filtered.length === sessions.length) {
+      throw new Error(`Session ${sessionId} not found`);
+    }
+
+    await this._saveRegistry(filtered);
+  }
+
+  /**
+   * Cleanup stale sessions
+   * @param {Object} options
+   * @param {number} [options.maxAge] - Max age in ms (default: 7 days)
+   * @returns {Promise<number>} Number of sessions removed
+   */
+  async cleanupStale(options = {}) {
+    const { maxAge = DEFAULT_MAX_AGE } = options;
+    const sessions = await this._loadRegistry();
+    const threshold = Date.now() - maxAge;
+
+    const active = sessions.filter((s) => {
+      return s.lastActiveAt > threshold;
+    });
+
+    const removed = sessions.length - active.length;
+
+    if (removed > 0) {
+      await this._saveRegistry(active);
+    }
+
+    return removed;
+  }
+
+  /**
+   * Get session statistics
+   * @returns {Promise<Object>}
+   */
+  async getStats() {
+    const sessions = await this._loadRegistry();
+
+    const stats = {
+      total: sessions.length,
+      running: 0,
+      paused: 0,
+      completed: 0,
+      failed: 0,
+      byProvider: {}
+    };
+
+    for (const session of sessions) {
+      // Count by status
+      if (session.status === 'running') stats.running++;
+      else if (session.status === 'paused') stats.paused++;
+      else if (session.status === 'completed') stats.completed++;
+      else if (session.status === 'failed') stats.failed++;
+
+      // Count by provider
+      if (!stats.byProvider[session.provider]) {
+        stats.byProvider[session.provider] = 0;
+      }
+      stats.byProvider[session.provider]++;
+    }
+
+    return stats;
+  }
+}
+
+export default RemoteSessionManager;

package/lib/remote/state-capture.js

@@ -0,0 +1,324 @@
+/**
+ * State Capturer for Remote Sessions
+ *
+ * Captures local state before initiating a remote session:
+ * - Git state (branch, commit, remote URL)
+ * - Environment variables (.env files + process.env)
+ * - Uncommitted changes
+ *
+ * Integrates with existing handoff utilities (GitHandoff, SessionState)
+ */
+
+import { GitHandoff } from '../handoff/git-handoff.js';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * StateCapturer class
+ */
+export class StateCapturer {
+  /**
+   * @param {Object} options
+   * @param {string} options.repoPath - Path to git repository
+   * @param {string} options.sessionId - Session ID
+   * @param {boolean} [options.verbose] - Enable verbose logging
+   */
+  constructor(options) {
+    if (!options.repoPath) {
+      throw new Error('repoPath is required');
+    }
+    if (!options.sessionId) {
+      throw new Error('sessionId is required');
+    }
+
+    this.repoPath = options.repoPath;
+    this.sessionId = options.sessionId;
+    this.verbose = options.verbose || false;
+
+    // Create GitHandoff instance for git operations
+    this.gitHandoff = options.gitHandoff || new GitHandoff({
+      repoPath: this.repoPath,
+      sessionId: this.sessionId,
+      verbose: this.verbose,
+    });
+  }
+
+  /**
+   * Capture current git state
+   *
+   * @returns {Promise<Object>} Git state
+   * @returns {boolean} return.isRepo - Whether directory is a git repo
+   * @returns {string|null} return.branch - Current branch name
+   * @returns {string|null} return.commit - Current commit hash
+   * @returns {string|null} return.remoteUrl - Remote origin URL
+   * @throws {Error} If git operations fail
+   */
+  async captureGitState() {
+    try {
+      const isRepo = await this.gitHandoff.isGitRepo();
+
+      if (!isRepo) {
+        return {
+          isRepo: false,
+          branch: null,
+          commit: null,
+          remoteUrl: null,
+        };
+      }
+
+      const [branch, commit, remoteUrl] = await Promise.all([
+        this.gitHandoff.getCurrentBranch(),
+        this.gitHandoff.getCurrentCommit(),
+        this.gitHandoff.getRemoteUrl(),
+      ]);
+
+      return {
+        isRepo: true,
+        branch,
+        commit,
+        remoteUrl,
+      };
+    } catch (error) {
+      throw new Error(`Failed to capture git state: ${error?.message || error}`);
+    }
+  }
+
+  /**
+   * Capture uncommitted changes
+   *
+   * @returns {Promise<Object>} Uncommitted changes info
+   * @returns {boolean} return.hasChanges - Whether there are uncommitted changes
+   * @returns {string[]} return.files - Array of changed file paths
+   * @returns {number} return.count - Number of changed files
+   * @throws {Error} If git operations fail
+   */
+  async captureUncommittedChanges() {
+    try {
+      const hasChanges = await this.gitHandoff.hasUncommittedChanges();
+      const files = hasChanges ? await this.gitHandoff.getChangedFiles() : [];
+
+      return {
+        hasChanges,
+        files,
+        count: files.length,
+      };
+    } catch (error) {
+      throw new Error(`Failed to capture uncommitted changes: ${error?.message || error}`);
+    }
+  }
+
+  /**
+   * Capture environment variables
+   *
+   * Reads from:
+   * - process.env (whitelist only for security)
+   * - .env files (.env, .env.local, .env.production, .env.development)
+   *
+   * SECURITY: By default, only captures whitelisted variables to prevent
+   * exposure of sensitive credentials (SSH keys, AWS credentials, etc.)
+   *
+   * @param {Object} [options]
+   * @param {RegExp} [options.filterPattern] - Only include vars matching this pattern (default: safe whitelist)
+   * @param {string[]} [options.exclude] - Exclude these specific keys
+   * @param {string[]} [options.dotenvFiles] - Custom .env file paths (defaults to standard files)
+   * @returns {Promise<Object>} Environment variables
+   * @returns {Object} return.process - Variables from process.env
+   * @returns {Array} return.dotenvFiles - Parsed .env files
+   * @returns {Object} [return.errors] - Parse errors for .env files
+   */
+  async captureEnvVars(options = {}) {
+    const {
+      // Default to safe whitelist: only capture known-safe prefixes
+      // Prevents exposure of SSH_PRIVATE_KEY, AWS_SECRET_ACCESS_KEY, etc.
+      filterPattern = /^(RELAY_|TELEPORTATION_|MECH_|NODE_ENV$|PATH$|HOME$|USER$|SHELL$)/,
+      exclude = [],
+      dotenvFiles = ['.env', '.env.local', '.env.production', '.env.development'],
+    } = options;
+
+    // Capture only whitelisted environment variables
+    const processEnv = {};
+    for (const [key, value] of Object.entries(process.env)) {
+      if (filterPattern.test(key) && !exclude.includes(key)) {
+        processEnv[key] = value;
+      }
+    }
+
+    // Parse .env files
+    const parsedDotenvFiles = [];
+    const errors = {};
+
+    for (const filename of dotenvFiles) {
+      const filepath = join(this.repoPath, filename);
+
+      if (!existsSync(filepath)) {
+        continue;
+      }
+
+      try {
+        const content = readFileSync(filepath, 'utf-8');
+        const vars = this._parseDotenvContent(content);
+
+        parsedDotenvFiles.push({
+          path: filepath,
+          vars,
+        });
+      } catch (error) {
+        errors[filepath] = error.message;
+      }
+    }
+
+    const result = {
+      process: processEnv,
+      dotenvFiles: parsedDotenvFiles,
+    };
+
+    if (Object.keys(errors).length > 0) {
+      result.errors = errors;
+    }
+
+    return result;
+  }
+
+  /**
+   * Parse .env file content
+   *
+   * Simple parser for KEY=value format
+   * Supports:
+   * - KEY=value
+   * - # comments
+   * - Empty lines
+   *
+   * SECURITY: Enforces limits to prevent DoS attacks via malicious .env files
+   *
+   * @private
+   * @param {string} content - .env file content
+   * @param {Object} [options] - Parsing options
+   * @param {number} [options.maxLines=1000] - Maximum number of lines to process
+   * @param {number} [options.maxLineLength=10000] - Maximum length per line
+   * @param {number} [options.maxVars=500] - Maximum number of variables
+   * @returns {Object} Parsed key-value pairs
+   */
+  _parseDotenvContent(content, options = {}) {
+    const { maxLines = 1000, maxLineLength = 10000, maxVars = 500 } = options;
+
+    const vars = {};
+    const lines = content.split('\n').slice(0, maxLines); // Limit total lines
+
+    for (const line of lines) {
+      // Skip lines that are too long (potential DoS)
+      if (line.length > maxLineLength) {
+        continue;
+      }
+
+      const trimmed = line.trim();
+
+      // Skip empty lines and comments
+      if (!trimmed || trimmed.startsWith('#')) {
+        continue;
+      }
+
+      // Enforce max variables limit
+      if (Object.keys(vars).length >= maxVars) {
+        break;
+      }
+
+      // Parse KEY=value
+      const match = trimmed.match(/^([^=]+)=(.*)$/);
+      if (match) {
+        const key = match[1].trim();
+        let value = match[2].trim();
+
+        // Remove surrounding quotes if present
+        if (
+          (value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))
+        ) {
+          value = value.slice(1, -1);
+        }
+
+        vars[key] = value;
+      }
+    }
+
+    return vars;
+  }
+
+  /**
+   * Capture all state (git + env + uncommitted changes)
+   *
+   * @param {Object} [options]
+   * @param {Object} [options.envOptions] - Options to pass to captureEnvVars()
+   * @returns {Promise<Object>} Complete state snapshot
+   * @returns {Object} return.git - Git state
+   * @returns {Object} return.env - Environment variables
+   * @returns {Object} return.uncommittedChanges - Uncommitted changes
+   * @returns {string} return.timestamp - ISO 8601 timestamp
+   * @returns {string} return.sessionId - Session ID
+   * @returns {string} return.repoPath - Repository path
+   */
+  async captureAll(options = {}) {
+    const { envOptions = {} } = options;
+
+    const [git, env, uncommittedChanges] = await Promise.all([
+      this.captureGitState(),
+      this.captureEnvVars(envOptions),
+      this.captureUncommittedChanges(),
+    ]);
+
+    return {
+      git,
+      env,
+      uncommittedChanges,
+      timestamp: new Date().toISOString(),
+      sessionId: this.sessionId,
+      repoPath: this.repoPath,
+    };
+  }
+
+  /**
+   * Commit and push uncommitted changes to WIP branch
+   *
+   * Uses GitHandoff to:
+   * 1. Commit all uncommitted changes with WIP message
+   * 2. Push to teleport/wip-{sessionId} branch
+   *
+   * @param {string} [message] - Optional message to include in commit
+   * @returns {Promise<Object>} Commit result
+   * @returns {boolean} return.committed - Whether changes were committed
+   * @returns {string|null} return.commit - Commit hash (if committed)
+   * @returns {string[]} return.files - Files that were committed
+   * @returns {string|null} return.branch - Branch that was pushed to
+   * @throws {Error} If commit/push fails
+   */
+  async commitAndPushChanges(message) {
+    try {
+      const hasChanges = await this.gitHandoff.hasUncommittedChanges();
+
+      if (!hasChanges) {
+        return {
+          committed: false,
+          commit: null,
+          files: [],
+          branch: null,
+        };
+      }
+
+      // Commit WIP changes
+      const { commit, files } = await this.gitHandoff.commitWip(message);
+
+      // Push to WIP branch (force=true for WIP branches)
+      const { branch } = await this.gitHandoff.pushToWipBranch(true);
+
+      return {
+        committed: true,
+        commit,
+        files,
+        branch,
+      };
+    } catch (error) {
+      throw new Error(`Failed to commit and push changes: ${error?.message || error}`);
+    }
+  }
+}
+
+export default StateCapturer;