teleportation-cli 1.0.0

package/lib/handoff/handoff.js

@@ -0,0 +1,277 @@
+/**
+ * Main Handoff Operations
+ * 
+ * High-level functions for handoff and sync operations.
+ * Coordinates git operations, session state, and cloud provider.
+ */
+
+import { GitHandoff } from './git-handoff.js';
+import { SessionState, loadSessionState, saveSessionState, getOrCreateSessionState } from './session-state.js';
+import { getHandoffConfig } from './config.js';
+
+/**
+ * Perform a handoff from local to cloud
+ * 
+ * @param {Object} options
+ * @param {string} options.projectPath - Path to the project
+ * @param {string} options.sessionId - Teleportation session ID
+ * @param {string} [options.message] - Optional message describing what was being worked on
+ * @param {boolean} [options.skipCommit] - Skip committing (if already committed)
+ * @param {boolean} [options.skipPush] - Skip pushing (dry run)
+ * @param {Function} [options.onProgress] - Progress callback
+ * @returns {Promise<{success: boolean, commit?: string, branch?: string, error?: string}>}
+ */
+export async function handoff(options) {
+  const {
+    projectPath,
+    sessionId,
+    message = '',
+    skipCommit = false,
+    skipPush = false,
+    onProgress = () => {},
+  } = options;
+  
+  const config = getHandoffConfig(projectPath);
+  
+  if (!config.enabled) {
+    return { success: false, error: 'Handoff is disabled in configuration' };
+  }
+  
+  onProgress({ step: 'init', message: 'Initializing handoff...' });
+  
+  // Initialize git handoff
+  const git = new GitHandoff({
+    repoPath: projectPath,
+    sessionId,
+    branchPrefix: config.wip_branch_prefix,
+    verbose: true,
+  });
+  
+  // Load or create session state
+  const state = getOrCreateSessionState(projectPath, sessionId);
+  
+  try {
+    // Check for remote URL
+    const remoteUrl = await git.getRemoteUrl();
+    if (!remoteUrl) {
+      return { success: false, error: 'No git remote configured. Cannot handoff.' };
+    }
+    
+    let commit = await git.getCurrentCommit();
+    let files = [];
+    
+    // Commit WIP changes if needed
+    if (!skipCommit && config.commit_uncommitted) {
+      onProgress({ step: 'commit', message: 'Committing work in progress...' });
+      
+      const hasChanges = await git.hasUncommittedChanges();
+      if (hasChanges) {
+        const result = await git.commitWip(message);
+        commit = result.commit;
+        files = result.files;
+        onProgress({ step: 'commit', message: `Committed ${files.length} files` });
+      } else {
+        onProgress({ step: 'commit', message: 'No uncommitted changes' });
+      }
+    }
+    
+    // Push to WIP branch
+    let branch = git.wipBranch;
+    if (!skipPush) {
+      onProgress({ step: 'push', message: `Pushing to ${branch}...` });
+      const pushResult = await git.pushToWipBranch();
+      branch = pushResult.branch;
+      commit = pushResult.commit;
+      onProgress({ step: 'push', message: 'Pushed successfully' });
+    }
+    
+    // Update session state
+    state.recordHandoff({
+      type: 'local_to_cloud',
+      commit,
+      branch,
+      message,
+      files,
+    });
+    saveSessionState(projectPath, state);
+    
+    onProgress({ step: 'done', message: 'Handoff complete' });
+    
+    return {
+      success: true,
+      commit,
+      branch,
+      files,
+      sessionId,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Sync changes from cloud back to local
+ * 
+ * @param {Object} options
+ * @param {string} options.projectPath - Path to the project
+ * @param {string} options.sessionId - Teleportation session ID
+ * @param {string} [options.strategy='merge'] - 'merge' or 'rebase'
+ * @param {boolean} [options.force] - Force sync even if conflicts
+ * @param {Function} [options.onProgress] - Progress callback
+ * @returns {Promise<{success: boolean, commit?: string, files?: string[], conflicts?: string[], error?: string}>}
+ */
+export async function sync(options) {
+  const {
+    projectPath,
+    sessionId,
+    strategy = 'merge',
+    force = false,
+    onProgress = () => {},
+  } = options;
+  
+  const config = getHandoffConfig(projectPath);
+  
+  onProgress({ step: 'init', message: 'Checking for remote changes...' });
+  
+  // Initialize git handoff
+  const git = new GitHandoff({
+    repoPath: projectPath,
+    sessionId,
+    branchPrefix: config.wip_branch_prefix,
+    verbose: true,
+  });
+  
+  // Load session state
+  const state = loadSessionState(projectPath);
+  
+  try {
+    // Check if there are remote changes
+    const { hasChanges, localCommit, remoteCommit } = await git.checkRemoteChanges();
+    
+    if (!hasChanges) {
+      onProgress({ step: 'done', message: 'Already up to date' });
+      return {
+        success: true,
+        commit: localCommit,
+        files: [],
+        message: 'Already up to date',
+      };
+    }
+    
+    // Get diff summary
+    const diff = await git.getDiffSummary();
+    onProgress({ 
+      step: 'diff', 
+      message: `${diff.behind} commits behind, ${diff.files.length} files changed` 
+    });
+    
+    // Perform sync
+    onProgress({ step: 'sync', message: `Syncing with ${strategy}...` });
+    const result = await git.syncFromRemote({ strategy, stashLocal: true });
+    
+    if (!result.success && result.conflicts.length > 0) {
+      if (!force) {
+        return {
+          success: false,
+          conflicts: result.conflicts,
+          error: `Merge conflicts in: ${result.conflicts.join(', ')}`,
+        };
+      }
+      // Force mode: accept theirs
+      onProgress({ step: 'resolve', message: 'Force resolving conflicts...' });
+      // TODO: Implement force resolution
+    }
+    
+    // Update session state
+    if (state) {
+      state.recordHandoff({
+        type: 'cloud_to_local',
+        commit: result.commit,
+        files: diff.files,
+      });
+      saveSessionState(projectPath, state);
+    }
+    
+    onProgress({ step: 'done', message: 'Sync complete' });
+    
+    return {
+      success: true,
+      commit: result.commit,
+      files: diff.files,
+      previousCommit: localCommit,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Get the current handoff status
+ * 
+ * @param {Object} options
+ * @param {string} options.projectPath - Path to the project
+ * @param {string} options.sessionId - Teleportation session ID
+ * @returns {Promise<{location: string, hasRemoteChanges: boolean, localCommit: string, remoteCommit?: string, diff?: Object}>}
+ */
+export async function getHandoffStatus(options) {
+  const { projectPath, sessionId } = options;
+  const config = getHandoffConfig(projectPath);
+  
+  const git = new GitHandoff({
+    repoPath: projectPath,
+    sessionId,
+    branchPrefix: config.wip_branch_prefix,
+  });
+  
+  const state = loadSessionState(projectPath);
+  
+  const localCommit = await git.getCurrentCommit();
+  const currentBranch = await git.getCurrentBranch();
+  const hasUncommitted = await git.hasUncommittedChanges();
+  
+  // Check remote
+  const { hasChanges, remoteCommit } = await git.checkRemoteChanges();
+  
+  let diff = null;
+  if (hasChanges) {
+    diff = await git.getDiffSummary();
+  }
+  
+  return {
+    location: state?.location || 'local',
+    sessionId: state?.sessionId || sessionId,
+    currentBranch,
+    wipBranch: git.wipBranch,
+    localCommit,
+    remoteCommit,
+    hasUncommittedChanges: hasUncommitted,
+    hasRemoteChanges: hasChanges,
+    diff,
+    lastHandoff: state?.handoffHistory?.slice(-1)[0] || null,
+    cloudContainer: state?.cloudContainer || null,
+  };
+}
+
+/**
+ * Check if a handoff is currently in progress
+ * 
+ * @param {string} projectPath
+ * @returns {boolean}
+ */
+export function isHandoffInProgress(projectPath) {
+  const state = loadSessionState(projectPath);
+  return state?.location === 'syncing';
+}
+
+export default {
+  handoff,
+  sync,
+  getHandoffStatus,
+  isHandoffInProgress,
+};

package/lib/handoff/index.js

@@ -0,0 +1,25 @@
+/**
+ * Teleportation Handoff Module
+ * 
+ * Handles seamless handoff between local and cloud dev environments.
+ * 
+ * Key features:
+ * - Auto-commit WIP changes to teleport/wip-<session> branch
+ * - Push to remote for cloud pickup
+ * - Sync changes back from cloud
+ * - Session state persistence in .teleportation/ directory
+ * 
+ * @module lib/handoff
+ */
+
+export { GitHandoff, createGitHandoff } from './git-handoff.js';
+export { SessionState, loadSessionState, saveSessionState } from './session-state.js';
+export { 
+  handoff, 
+  sync, 
+  getHandoffStatus,
+  isHandoffInProgress 
+} from './handoff.js';
+
+// Re-export config helpers
+export { getHandoffConfig, DEFAULT_HANDOFF_CONFIG } from './config.js';

package/lib/handoff/session-state.js

@@ -0,0 +1,238 @@
+/**
+ * Session State Management
+ * 
+ * Persists session state to .teleportation/ directory so it can be
+ * synced between local and cloud environments.
+ * 
+ * State includes:
+ * - Session metadata (ID, timestamps, location)
+ * - Handoff history
+ * - Task progress
+ * - Conversation context (optional)
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Session state structure
+ */
+export class SessionState {
+  constructor(data = {}) {
+    // Core identifiers
+    this.sessionId = data.sessionId || null;
+    this.projectPath = data.projectPath || null;
+    
+    // Location tracking
+    this.location = data.location || 'local'; // 'local' | 'cloud' | 'syncing'
+    this.lastLocalActivity = data.lastLocalActivity || null;
+    this.lastCloudActivity = data.lastCloudActivity || null;
+    
+    // Handoff tracking
+    this.handoffHistory = data.handoffHistory || [];
+    this.lastHandoffCommit = data.lastHandoffCommit || null;
+    this.lastSyncCommit = data.lastSyncCommit || null;
+    
+    // Cloud container info (when in cloud)
+    this.cloudContainer = data.cloudContainer || null;
+    
+    // Task/workflow state
+    this.currentTask = data.currentTask || null;
+    this.taskProgress = data.taskProgress || {};
+    
+    // Timestamps
+    this.createdAt = data.createdAt || new Date().toISOString();
+    this.updatedAt = data.updatedAt || new Date().toISOString();
+  }
+  
+  /**
+   * Record a handoff event
+   * @param {Object} event
+   * @param {string} event.type - 'local_to_cloud' | 'cloud_to_local'
+   * @param {string} event.commit - Git commit hash
+   * @param {string} [event.message] - Optional message
+   */
+  recordHandoff(event) {
+    this.handoffHistory.push({
+      ...event,
+      timestamp: new Date().toISOString(),
+    });
+    
+    if (event.type === 'local_to_cloud') {
+      this.lastHandoffCommit = event.commit;
+      this.location = 'cloud';
+      this.lastLocalActivity = new Date().toISOString();
+    } else if (event.type === 'cloud_to_local') {
+      this.lastSyncCommit = event.commit;
+      this.location = 'local';
+      this.lastCloudActivity = new Date().toISOString();
+    }
+    
+    this.updatedAt = new Date().toISOString();
+  }
+  
+  /**
+   * Update location
+   * @param {'local'|'cloud'|'syncing'} location
+   */
+  setLocation(location) {
+    this.location = location;
+    if (location === 'local') {
+      this.lastLocalActivity = new Date().toISOString();
+    } else if (location === 'cloud') {
+      this.lastCloudActivity = new Date().toISOString();
+    }
+    this.updatedAt = new Date().toISOString();
+  }
+  
+  /**
+   * Update cloud container info
+   * @param {Object|null} container
+   */
+  setCloudContainer(container) {
+    this.cloudContainer = container;
+    this.updatedAt = new Date().toISOString();
+  }
+  
+  /**
+   * Update current task
+   * @param {Object|null} task
+   */
+  setCurrentTask(task) {
+    this.currentTask = task;
+    this.updatedAt = new Date().toISOString();
+  }
+  
+  /**
+   * Update task progress
+   * @param {string} taskId
+   * @param {Object} progress
+   */
+  updateTaskProgress(taskId, progress) {
+    this.taskProgress[taskId] = {
+      ...this.taskProgress[taskId],
+      ...progress,
+      updatedAt: new Date().toISOString(),
+    };
+    this.updatedAt = new Date().toISOString();
+  }
+  
+  /**
+   * Serialize to JSON
+   * @returns {Object}
+   */
+  toJSON() {
+    return {
+      sessionId: this.sessionId,
+      projectPath: this.projectPath,
+      location: this.location,
+      lastLocalActivity: this.lastLocalActivity,
+      lastCloudActivity: this.lastCloudActivity,
+      handoffHistory: this.handoffHistory,
+      lastHandoffCommit: this.lastHandoffCommit,
+      lastSyncCommit: this.lastSyncCommit,
+      cloudContainer: this.cloudContainer,
+      currentTask: this.currentTask,
+      taskProgress: this.taskProgress,
+      createdAt: this.createdAt,
+      updatedAt: this.updatedAt,
+    };
+  }
+}
+
+/**
+ * Get the .teleportation directory path for a project
+ * @param {string} projectPath
+ * @returns {string}
+ */
+function getTeleportationDir(projectPath) {
+  return join(projectPath, '.teleportation');
+}
+
+/**
+ * Get the session state file path
+ * @param {string} projectPath
+ * @returns {string}
+ */
+function getSessionStatePath(projectPath) {
+  return join(getTeleportationDir(projectPath), 'session.json');
+}
+
+/**
+ * Ensure .teleportation directory exists
+ * @param {string} projectPath
+ */
+function ensureTeleportationDir(projectPath) {
+  const dir = getTeleportationDir(projectPath);
+  if (!existsSync(dir)) {
+    // Create with 700 permissions (owner only) for security
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+}
+
+/**
+ * Load session state from disk
+ * @param {string} projectPath - Project directory
+ * @returns {SessionState|null}
+ */
+export function loadSessionState(projectPath) {
+  const statePath = getSessionStatePath(projectPath);
+  
+  if (!existsSync(statePath)) {
+    return null;
+  }
+  
+  try {
+    const data = JSON.parse(readFileSync(statePath, 'utf-8'));
+    return new SessionState(data);
+  } catch (error) {
+    console.error(`[session-state] Failed to load state: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Save session state to disk
+ * @param {string} projectPath - Project directory
+ * @param {SessionState} state - State to save
+ */
+export function saveSessionState(projectPath, state) {
+  ensureTeleportationDir(projectPath);
+  const statePath = getSessionStatePath(projectPath);
+  
+  try {
+    // Write with 600 permissions (owner read/write only) for security
+    // Session state may contain sensitive info like cloud container credentials
+    writeFileSync(statePath, JSON.stringify(state.toJSON(), null, 2), { mode: 0o600 });
+  } catch (error) {
+    console.error(`[session-state] Failed to save state: ${error.message}`);
+    throw error;
+  }
+}
+
+/**
+ * Create or load session state
+ * @param {string} projectPath
+ * @param {string} sessionId
+ * @returns {SessionState}
+ */
+export function getOrCreateSessionState(projectPath, sessionId) {
+  let state = loadSessionState(projectPath);
+  
+  if (!state || state.sessionId !== sessionId) {
+    state = new SessionState({
+      sessionId,
+      projectPath,
+    });
+    saveSessionState(projectPath, state);
+  }
+  
+  return state;
+}
+
+export default {
+  SessionState,
+  loadSessionState,
+  saveSessionState,
+  getOrCreateSessionState,
+};