teleportation-cli 1.0.0

package/lib/handoff/config.js

@@ -0,0 +1,102 @@
+/**
+ * Handoff Configuration
+ * 
+ * Default settings and config loading for cloud handoff.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+/**
+ * Default handoff configuration
+ */
+export const DEFAULT_HANDOFF_CONFIG = {
+  // Whether auto-handoff is enabled
+  enabled: true,
+  
+  // What triggers auto-handoff: "away" | "idle" | "manual"
+  // - "away": When approval times out (is_away: true)
+  // - "idle": After idle_timeout_minutes of no activity
+  // - "manual": Only via explicit `teleport handoff` command
+  trigger: 'away',
+  
+  // Minutes of inactivity before auto-handoff (for "idle" trigger)
+  idle_timeout_minutes: 5,
+  
+  // Auto-commit uncommitted changes before handoff
+  commit_uncommitted: true,
+  
+  // Send push notification on handoff
+  notify_on_handoff: true,
+  
+  // Cloud provider: "daytona" | "gitpod" | "codespaces" | "devpod"
+  cloud_provider: 'daytona',
+  
+  // Branch prefix for WIP commits
+  wip_branch_prefix: 'teleport/wip-',
+  
+  // Auto-sync when returning to local
+  auto_sync_on_return: false, // Prompt by default
+  
+  // How often cloud should auto-commit (minutes, 0 = disabled)
+  cloud_auto_commit_interval: 5,
+};
+
+/**
+ * Load handoff config from various sources
+ * Priority: env vars > project config > user config > defaults
+ * 
+ * @param {string} [projectPath] - Project directory path
+ * @returns {Object} Merged configuration
+ */
+export function getHandoffConfig(projectPath = process.cwd()) {
+  let config = { ...DEFAULT_HANDOFF_CONFIG };
+  
+  // 1. Load user-level config (~/.teleportation/config.json)
+  const userConfigPath = join(homedir(), '.teleportation', 'config.json');
+  if (existsSync(userConfigPath)) {
+    try {
+      const userConfig = JSON.parse(readFileSync(userConfigPath, 'utf-8'));
+      if (userConfig.auto_handoff) {
+        config = { ...config, ...userConfig.auto_handoff };
+      }
+    } catch (e) {
+      // Ignore parse errors
+    }
+  }
+  
+  // 2. Load project-level config (.teleportation/config.json)
+  const projectConfigPath = join(projectPath, '.teleportation', 'config.json');
+  if (existsSync(projectConfigPath)) {
+    try {
+      const projectConfig = JSON.parse(readFileSync(projectConfigPath, 'utf-8'));
+      if (projectConfig.auto_handoff) {
+        config = { ...config, ...projectConfig.auto_handoff };
+      }
+    } catch (e) {
+      // Ignore parse errors
+    }
+  }
+  
+  // 3. Override with environment variables
+  if (process.env.TELEPORT_HANDOFF_ENABLED !== undefined) {
+    config.enabled = process.env.TELEPORT_HANDOFF_ENABLED === 'true';
+  }
+  if (process.env.TELEPORT_HANDOFF_TRIGGER) {
+    config.trigger = process.env.TELEPORT_HANDOFF_TRIGGER;
+  }
+  if (process.env.TELEPORT_CLOUD_PROVIDER) {
+    config.cloud_provider = process.env.TELEPORT_CLOUD_PROVIDER;
+  }
+  if (process.env.TELEPORT_IDLE_TIMEOUT) {
+    config.idle_timeout_minutes = parseInt(process.env.TELEPORT_IDLE_TIMEOUT, 10);
+  }
+  
+  return config;
+}
+
+export default {
+  DEFAULT_HANDOFF_CONFIG,
+  getHandoffConfig,
+};

package/lib/handoff/example.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * Handoff Module Example / Test Script
+ * 
+ * Demonstrates the handoff and sync operations.
+ * 
+ * Usage:
+ *   node lib/handoff/example.js status
+ *   node lib/handoff/example.js handoff [message]
+ *   node lib/handoff/example.js sync
+ */
+
+import { handoff, sync, getHandoffStatus } from './handoff.js';
+import { getHandoffConfig } from './config.js';
+
+const projectPath = process.cwd();
+const sessionId = process.env.TELEPORT_SESSION_ID || `test-${Date.now()}`;
+
+async function showStatus() {
+  console.log('=== Handoff Status ===\n');
+  
+  const config = getHandoffConfig(projectPath);
+  console.log('Configuration:');
+  console.log(`  Enabled: ${config.enabled}`);
+  console.log(`  Trigger: ${config.trigger}`);
+  console.log(`  Cloud Provider: ${config.cloud_provider}`);
+  console.log(`  WIP Branch Prefix: ${config.wip_branch_prefix}`);
+  console.log('');
+  
+  try {
+    const status = await getHandoffStatus({ projectPath, sessionId });
+    
+    console.log('Git Status:');
+    console.log(`  Current Branch: ${status.currentBranch}`);
+    console.log(`  WIP Branch: ${status.wipBranch}`);
+    console.log(`  Local Commit: ${status.localCommit?.slice(0, 7)}`);
+    console.log(`  Remote Commit: ${status.remoteCommit?.slice(0, 7) || '(none)'}`);
+    console.log(`  Uncommitted Changes: ${status.hasUncommittedChanges ? 'Yes' : 'No'}`);
+    console.log(`  Remote Changes: ${status.hasRemoteChanges ? 'Yes' : 'No'}`);
+    console.log('');
+    
+    console.log('Session State:');
+    console.log(`  Location: ${status.location}`);
+    console.log(`  Session ID: ${status.sessionId}`);
+    if (status.lastHandoff) {
+      console.log(`  Last Handoff: ${status.lastHandoff.type} at ${status.lastHandoff.timestamp}`);
+    }
+    if (status.cloudContainer) {
+      console.log(`  Cloud Container: ${status.cloudContainer.id}`);
+    }
+    console.log('');
+    
+    if (status.diff) {
+      console.log('Diff Summary:');
+      console.log(`  Ahead: ${status.diff.ahead} commits`);
+      console.log(`  Behind: ${status.diff.behind} commits`);
+      if (status.diff.files.length > 0) {
+        console.log(`  Files: ${status.diff.files.slice(0, 5).join(', ')}${status.diff.files.length > 5 ? '...' : ''}`);
+      }
+    }
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+  }
+}
+
+async function doHandoff(message) {
+  console.log('=== Performing Handoff ===\n');
+  console.log(`Project: ${projectPath}`);
+  console.log(`Session: ${sessionId}`);
+  console.log(`Message: ${message || '(none)'}`);
+  console.log('');
+  
+  const result = await handoff({
+    projectPath,
+    sessionId,
+    message,
+    onProgress: ({ step, message }) => {
+      console.log(`[${step}] ${message}`);
+    },
+  });
+  
+  console.log('');
+  if (result.success) {
+    console.log('✓ Handoff successful!');
+    console.log(`  Branch: ${result.branch}`);
+    console.log(`  Commit: ${result.commit?.slice(0, 7)}`);
+    if (result.files?.length > 0) {
+      console.log(`  Files: ${result.files.length}`);
+    }
+  } else {
+    console.log(`✗ Handoff failed: ${result.error}`);
+  }
+}
+
+async function doSync() {
+  console.log('=== Syncing from Cloud ===\n');
+  console.log(`Project: ${projectPath}`);
+  console.log(`Session: ${sessionId}`);
+  console.log('');
+  
+  const result = await sync({
+    projectPath,
+    sessionId,
+    strategy: 'merge',
+    onProgress: ({ step, message }) => {
+      console.log(`[${step}] ${message}`);
+    },
+  });
+  
+  console.log('');
+  if (result.success) {
+    console.log('✓ Sync successful!');
+    console.log(`  Commit: ${result.commit?.slice(0, 7)}`);
+    if (result.files?.length > 0) {
+      console.log(`  Files synced: ${result.files.length}`);
+      result.files.slice(0, 5).forEach(f => console.log(`    - ${f}`));
+      if (result.files.length > 5) {
+        console.log(`    ... and ${result.files.length - 5} more`);
+      }
+    }
+    if (result.message) {
+      console.log(`  Note: ${result.message}`);
+    }
+  } else {
+    console.log(`✗ Sync failed: ${result.error}`);
+    if (result.conflicts?.length > 0) {
+      console.log('  Conflicts:');
+      result.conflicts.forEach(f => console.log(`    - ${f}`));
+    }
+  }
+}
+
+// Main
+const command = process.argv[2] || 'status';
+const arg = process.argv[3];
+
+switch (command) {
+  case 'status':
+    await showStatus();
+    break;
+  case 'handoff':
+    await doHandoff(arg);
+    break;
+  case 'sync':
+    await doSync();
+    break;
+  default:
+    console.log('Usage:');
+    console.log('  node lib/handoff/example.js status');
+    console.log('  node lib/handoff/example.js handoff [message]');
+    console.log('  node lib/handoff/example.js sync');
+}

package/lib/handoff/git-handoff.js

@@ -0,0 +1,351 @@
+/**
+ * Git Handoff Operations
+ * 
+ * Handles git operations for seamless local ↔ cloud handoff:
+ * - Auto-commit WIP changes
+ * - Push to teleport/wip-<session> branch
+ * - Pull/sync from cloud
+ * - Conflict detection
+ */
+
+import { execSync, exec } from 'child_process';
+import { promisify } from 'util';
+import { writeFileSync, unlinkSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+const execAsync = promisify(exec);
+
+/**
+ * GitHandoff class for managing git operations during handoff
+ */
+export class GitHandoff {
+  /**
+   * @param {Object} options
+   * @param {string} options.repoPath - Path to the git repository
+   * @param {string} options.sessionId - Teleportation session ID
+   * @param {string} [options.branchPrefix] - Prefix for WIP branches
+   * @param {boolean} [options.verbose] - Enable verbose logging
+   */
+  constructor(options) {
+    this.repoPath = options.repoPath;
+    this.sessionId = options.sessionId;
+    this.branchPrefix = options.branchPrefix || 'teleport/wip-';
+    this.verbose = options.verbose || false;
+    
+    this.wipBranch = `${this.branchPrefix}${this.sessionId}`;
+  }
+  
+  /**
+   * Execute a git command in the repo
+   * @private
+   */
+  async git(command, options = {}) {
+    const fullCommand = `git ${command}`;
+    if (this.verbose) {
+      console.log(`[git-handoff] ${fullCommand}`);
+    }
+    
+    try {
+      const { stdout, stderr } = await execAsync(fullCommand, {
+        cwd: this.repoPath,
+        ...options,
+      });
+      return stdout.trim();
+    } catch (error) {
+      if (this.verbose) {
+        console.error(`[git-handoff] Error: ${error.message}`);
+      }
+      throw error;
+    }
+  }
+  
+  /**
+   * Check if this is a valid git repository
+   * @returns {Promise<boolean>}
+   */
+  async isGitRepo() {
+    try {
+      await this.git('rev-parse --is-inside-work-tree');
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  
+  /**
+   * Check if the repo has uncommitted changes
+   * @returns {Promise<boolean>}
+   */
+  async hasUncommittedChanges() {
+    const status = await this.git('status --porcelain');
+    return status.length > 0;
+  }
+  
+  /**
+   * Alias for hasUncommittedChanges
+   * @returns {Promise<boolean>}
+   */
+  async hasChanges() {
+    return this.hasUncommittedChanges();
+  }
+  
+  /**
+   * Get list of changed files
+   * @returns {Promise<string[]>}
+   */
+  async getChangedFiles() {
+    const status = await this.git('status --porcelain');
+    if (!status) return [];
+    
+    return status.split('\n').map(line => {
+      // Format: "XY filename" or "XY filename -> newname"
+      const match = line.match(/^..\s+(.+?)(?:\s+->\s+.+)?$/);
+      return match ? match[1] : line.slice(3);
+    });
+  }
+  
+  /**
+   * Get the current branch name
+   * @returns {Promise<string>}
+   */
+  async getCurrentBranch() {
+    return this.git('rev-parse --abbrev-ref HEAD');
+  }
+  
+  /**
+   * Get the current commit hash
+   * @returns {Promise<string>}
+   */
+  async getCurrentCommit() {
+    return this.git('rev-parse HEAD');
+  }
+  
+  /**
+   * Get the remote URL for origin
+   * @returns {Promise<string|null>}
+   */
+  async getRemoteUrl() {
+    try {
+      return await this.git('remote get-url origin');
+    } catch {
+      return null;
+    }
+  }
+  
+  /**
+   * Check if a remote branch exists
+   * @param {string} branch - Branch name
+   * @returns {Promise<boolean>}
+   */
+  async remoteBranchExists(branch) {
+    try {
+      await this.git(`ls-remote --exit-code origin ${branch}`);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  
+  /**
+   * Commit all changes with a WIP message
+   * @param {string} [message] - Optional message to include
+   * @returns {Promise<{commit: string, files: string[]}>}
+   */
+  async commitWip(message = '') {
+    const files = await this.getChangedFiles();
+    if (files.length === 0) {
+      return { commit: await this.getCurrentCommit(), files: [] };
+    }
+    
+    // Stage all changes
+    await this.git('add -A');
+    
+    // Build commit message
+    const timestamp = new Date().toISOString();
+    const commitMessage = [
+      `[teleport] WIP handoff${message ? `: ${message}` : ''}`,
+      '',
+      `Session: ${this.sessionId}`,
+      `Timestamp: ${timestamp}`,
+      `Source: local`,
+      '',
+      'Files changed:',
+      ...files.map(f => `- ${f}`),
+    ].join('\n');
+    
+    // Commit using temp file to avoid shell injection
+    // Using -F flag prevents any shell metacharacter interpretation
+    const tempFile = join(tmpdir(), `teleport-commit-${Date.now()}-${Math.random().toString(36).slice(2)}.txt`);
+    try {
+      writeFileSync(tempFile, commitMessage, { mode: 0o600 });
+      await this.git(`commit -F "${tempFile}"`);
+    } finally {
+      try { unlinkSync(tempFile); } catch { /* ignore cleanup errors */ }
+    }
+    
+    const commit = await this.getCurrentCommit();
+    return { commit, files };
+  }
+  
+  /**
+   * Push current branch to the WIP branch on remote
+   * @param {boolean} [force=true] - Force push (default true for WIP branches)
+   * @returns {Promise<{branch: string, commit: string}>}
+   */
+  async pushToWipBranch(force = true) {
+    const commit = await this.getCurrentCommit();
+    const forceFlag = force ? '--force' : '';
+    
+    await this.git(`push origin HEAD:${this.wipBranch} ${forceFlag}`);
+    
+    return { branch: this.wipBranch, commit };
+  }
+  
+  /**
+   * Fetch the WIP branch from remote
+   * @returns {Promise<boolean>} - True if branch exists and was fetched
+   */
+  async fetchWipBranch() {
+    try {
+      await this.git(`fetch origin ${this.wipBranch}`);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  
+  /**
+   * Check if there are changes on the remote WIP branch
+   * @returns {Promise<{hasChanges: boolean, localCommit: string, remoteCommit: string|null}>}
+   */
+  async checkRemoteChanges() {
+    const localCommit = await this.getCurrentCommit();
+    
+    const fetched = await this.fetchWipBranch();
+    if (!fetched) {
+      return { hasChanges: false, localCommit, remoteCommit: null };
+    }
+    
+    try {
+      const remoteCommit = await this.git(`rev-parse origin/${this.wipBranch}`);
+      return {
+        hasChanges: localCommit !== remoteCommit,
+        localCommit,
+        remoteCommit,
+      };
+    } catch {
+      return { hasChanges: false, localCommit, remoteCommit: null };
+    }
+  }
+  
+  /**
+   * Sync changes from the remote WIP branch
+   * @param {Object} options
+   * @param {string} [options.strategy='merge'] - 'merge' or 'rebase'
+   * @param {boolean} [options.stashLocal=true] - Stash local changes first
+   * @returns {Promise<{success: boolean, commit: string, conflicts: string[]}>}
+   */
+  async syncFromRemote(options = {}) {
+    const { strategy = 'merge', stashLocal = true } = options;
+    
+    // Stash local changes if any
+    let stashed = false;
+    if (stashLocal && await this.hasUncommittedChanges()) {
+      await this.git('stash push -m "teleport-sync-stash"');
+      stashed = true;
+    }
+    
+    try {
+      // Fetch latest
+      await this.fetchWipBranch();
+      
+      // Merge or rebase
+      if (strategy === 'rebase') {
+        await this.git(`rebase origin/${this.wipBranch}`);
+      } else {
+        await this.git(`merge origin/${this.wipBranch} --no-edit`);
+      }
+      
+      // Pop stash if we stashed
+      if (stashed) {
+        try {
+          await this.git('stash pop');
+        } catch (e) {
+          // Stash pop conflict - leave in stash
+          console.warn('[git-handoff] Stash pop had conflicts, changes left in stash');
+        }
+      }
+      
+      return {
+        success: true,
+        commit: await this.getCurrentCommit(),
+        conflicts: [],
+      };
+    } catch (error) {
+      // Check for merge conflicts
+      const status = await this.git('status --porcelain');
+      const conflicts = status
+        .split('\n')
+        .filter(line => line.startsWith('UU') || line.startsWith('AA'))
+        .map(line => line.slice(3));
+      
+      return {
+        success: false,
+        commit: await this.getCurrentCommit(),
+        conflicts,
+      };
+    }
+  }
+  
+  /**
+   * Get a summary of the diff between local and remote
+   * @returns {Promise<{ahead: number, behind: number, files: string[]}>}
+   */
+  async getDiffSummary() {
+    await this.fetchWipBranch();
+    
+    try {
+      const ahead = await this.git(`rev-list --count origin/${this.wipBranch}..HEAD`);
+      const behind = await this.git(`rev-list --count HEAD..origin/${this.wipBranch}`);
+      
+      let files = [];
+      if (parseInt(behind) > 0) {
+        const diff = await this.git(`diff --name-only HEAD..origin/${this.wipBranch}`);
+        files = diff ? diff.split('\n') : [];
+      }
+      
+      return {
+        ahead: parseInt(ahead),
+        behind: parseInt(behind),
+        files,
+      };
+    } catch {
+      return { ahead: 0, behind: 0, files: [] };
+    }
+  }
+  
+  /**
+   * Clean up the WIP branch (delete from remote)
+   * @returns {Promise<boolean>}
+   */
+  async cleanupWipBranch() {
+    try {
+      await this.git(`push origin --delete ${this.wipBranch}`);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * Create a GitHandoff instance
+ * @param {Object} options - Same as GitHandoff constructor
+ * @returns {GitHandoff}
+ */
+export function createGitHandoff(options) {
+  return new GitHandoff(options);
+}
+
+export default GitHandoff;