teleportation-cli 1.1.5 → 1.2.1

package/lib/teleport/exporters/interface.js

@@ -0,0 +1,153 @@
+/**
+ * TranscriptExporter Interface
+ *
+ * Base class for CLI-specific transcript exporters.
+ * Converts Timeline API events to native CLI transcript formats.
+ *
+ * @module lib/teleport/exporters/interface
+ */
+
+import { writeFile, mkdir } from 'fs/promises';
+import { dirname } from 'path';
+
+/**
+ * Timeline event types that can be exported
+ * @typedef {'user_message'|'assistant_response'|'tool_use'|'tool_result'|'thinking'|'compact_summary'} TimelineEventType
+ */
+
+/**
+ * Timeline event structure from the relay API
+ * @typedef {Object} TimelineEvent
+ * @property {string} id - Unique event ID
+ * @property {TimelineEventType} event_type - Type of event
+ * @property {Object} data - Event-specific data
+ * @property {number} timestamp - Unix timestamp in milliseconds
+ * @property {string} session_id - Parent session ID
+ */
+
+/**
+ * Export options
+ * @typedef {Object} ExportOptions
+ * @property {boolean} [includeThinking=true] - Include thinking blocks if supported
+ * @property {boolean} [prettyPrint=false] - Pretty-print JSON output
+ * @property {string} [projectSlug] - Project identifier for path generation
+ */
+
+/**
+ * Base class for transcript exporters.
+ *
+ * Subclasses must implement:
+ * - export(events, options) - Convert timeline events to CLI format
+ * - getTranscriptPath(sessionId, projectSlug) - Get native transcript path
+ *
+ * @example
+ * ```js
+ * import { ClaudeTranscriptExporter } from './claude-exporter.js';
+ *
+ * const exporter = new ClaudeTranscriptExporter();
+ * const transcript = await exporter.export(timelineEvents);
+ * await exporter.write(timelineEvents, sessionId, projectSlug);
+ * ```
+ */
+export class TranscriptExporter {
+  /**
+   * The CLI name this exporter targets
+   * @type {string}
+   */
+  name = 'base';
+
+  /**
+   * Human-readable exporter name
+   * @type {string}
+   */
+  displayName = 'Base Exporter';
+
+  /**
+   * Export timeline events to CLI-native transcript format.
+   *
+   * @abstract
+   * @param {TimelineEvent[]} events - Timeline events from relay API
+   * @param {ExportOptions} [options={}] - Export options
+   * @returns {Promise<string>} Transcript content in CLI-native format
+   * @throws {Error} If events array is invalid or export fails
+   */
+  async export(events, options = {}) {
+    throw new Error('TranscriptExporter.export() must be implemented by subclass');
+  }
+
+  /**
+   * Get the native transcript file path for a CLI.
+   *
+   * @abstract
+   * @param {string} sessionId - Session identifier
+   * @param {string} projectSlug - Project slug/identifier
+   * @returns {string} Absolute path to transcript file
+   */
+  getTranscriptPath(sessionId, projectSlug) {
+    throw new Error('TranscriptExporter.getTranscriptPath() must be implemented by subclass');
+  }
+
+  /**
+   * Export and write transcript to the CLI-native location.
+   *
+   * @param {TimelineEvent[]} events - Timeline events from relay API
+   * @param {string} sessionId - Session identifier
+   * @param {string} projectSlug - Project slug/identifier
+   * @param {ExportOptions} [options={}] - Export options
+   * @returns {Promise<string>} Path where transcript was written
+   */
+  async write(events, sessionId, projectSlug, options = {}) {
+    const transcript = await this.export(events, { ...options, projectSlug });
+    const path = this.getTranscriptPath(sessionId, projectSlug);
+
+    // Ensure directory exists
+    await mkdir(dirname(path), { recursive: true });
+
+    // Write transcript
+    await writeFile(path, transcript, 'utf-8');
+
+    return path;
+  }
+
+  /**
+   * Validate timeline events array.
+   *
+   * @protected
+   * @param {TimelineEvent[]} events - Events to validate
+   * @throws {Error} If events are invalid
+   */
+  validateEvents(events) {
+    if (!Array.isArray(events)) {
+      throw new Error('Events must be an array');
+    }
+
+    // Empty array is valid (new session with no messages)
+    if (events.length === 0) {
+      return;
+    }
+
+    // Check each event has required fields
+    for (let i = 0; i < events.length; i++) {
+      const event = events[i];
+      if (!event || typeof event !== 'object') {
+        throw new Error(`Event at index ${i} is not an object`);
+      }
+      if (!event.event_type) {
+        throw new Error(`Event at index ${i} is missing event_type`);
+      }
+    }
+  }
+
+  /**
+   * Sort events by timestamp.
+   *
+   * @protected
+   * @param {TimelineEvent[]} events - Events to sort
+   * @returns {TimelineEvent[]} Sorted events (oldest first)
+   */
+  sortEvents(events) {
+    return [...events].sort((a, b) => (a.timestamp || 0) - (b.timestamp || 0));
+  }
+}
+
+export default TranscriptExporter;

package/lib/teleport/fork-tracker.js

@@ -0,0 +1,415 @@
+/**
+ * Fork Tracker
+ *
+ * Tracks parallel sessions when using fork mode teleportation.
+ * Monitors both local and cloud sessions, detects conflicts,
+ * and provides coordination utilities.
+ *
+ * @module lib/teleport/fork-tracker
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+/**
+ * Fork session state
+ * @enum {string}
+ */
+export const ForkSessionState = {
+  /** Session is active and making changes */
+  ACTIVE: 'active',
+  /** Session is idle (no recent activity) */
+  IDLE: 'idle',
+  /** Session has completed */
+  COMPLETED: 'completed',
+  /** Session encountered an error */
+  ERRORED: 'errored',
+};
+
+/**
+ * ForkTracker manages parallel sessions in fork mode.
+ */
+export class ForkTracker {
+  /**
+   * Initialize ForkTracker
+   *
+   * @param {Object} config - Configuration
+   * @param {string} config.teleportId - Teleport ID
+   * @param {string} config.repoPath - Path to git repository
+   * @param {string} config.localBranch - Local session branch
+   * @param {string} config.cloudBranch - Cloud session branch
+   */
+  constructor(config) {
+    if (!config) {
+      throw new Error('ForkTracker config is required');
+    }
+    if (!config.teleportId) {
+      throw new Error('teleportId is required');
+    }
+    if (!config.repoPath) {
+      throw new Error('repoPath is required');
+    }
+
+    this.teleportId = config.teleportId;
+    this.repoPath = config.repoPath;
+    this.localBranch = config.localBranch || 'HEAD';
+    this.cloudBranch = config.cloudBranch || `teleport/${config.teleportId}`;
+
+    // Session states
+    this.localSession = {
+      state: ForkSessionState.ACTIVE,
+      lastActivityAt: new Date().toISOString(),
+      commitCount: 0,
+      lastCommitSha: null,
+    };
+
+    this.cloudSession = {
+      state: ForkSessionState.ACTIVE,
+      lastActivityAt: new Date().toISOString(),
+      commitCount: 0,
+      lastCommitSha: null,
+    };
+
+    // Fork point (common ancestor)
+    this.forkPoint = null;
+
+    // Conflict tracking
+    this.conflicts = [];
+    this.lastConflictCheck = null;
+  }
+
+  /**
+   * Initialize fork tracking.
+   * Records the fork point and initial state.
+   *
+   * @returns {Promise<Object>} Fork point info
+   */
+  async initialize() {
+    const cwd = this.repoPath;
+
+    try {
+      // Record current commit as fork point
+      const { stdout: sha } = await execAsync('git rev-parse HEAD', { cwd });
+      this.forkPoint = sha.trim();
+
+      // Get branch info
+      const { stdout: branch } = await execAsync('git rev-parse --abbrev-ref HEAD', { cwd });
+      this.localBranch = branch.trim();
+
+      return {
+        forkPoint: this.forkPoint,
+        localBranch: this.localBranch,
+        cloudBranch: this.cloudBranch,
+        timestamp: new Date().toISOString(),
+      };
+    } catch (error) {
+      throw new Error(`Failed to initialize fork tracker: ${error.message}`);
+    }
+  }
+
+  /**
+   * Update local session state.
+   *
+   * @param {Object} update - Update data
+   * @param {ForkSessionState} [update.state] - New state
+   * @param {string} [update.commitSha] - Latest commit SHA
+   */
+  updateLocalSession(update) {
+    if (update.state) {
+      this.localSession.state = update.state;
+    }
+    if (update.commitSha) {
+      this.localSession.lastCommitSha = update.commitSha;
+      this.localSession.commitCount++;
+    }
+    this.localSession.lastActivityAt = new Date().toISOString();
+  }
+
+  /**
+   * Update cloud session state.
+   *
+   * @param {Object} update - Update data
+   * @param {ForkSessionState} [update.state] - New state
+   * @param {string} [update.commitSha] - Latest commit SHA
+   */
+  updateCloudSession(update) {
+    if (update.state) {
+      this.cloudSession.state = update.state;
+    }
+    if (update.commitSha) {
+      this.cloudSession.lastCommitSha = update.commitSha;
+      this.cloudSession.commitCount++;
+    }
+    this.cloudSession.lastActivityAt = new Date().toISOString();
+  }
+
+  /**
+   * Check for conflicts between local and cloud branches.
+   *
+   * @returns {Promise<Object>} Conflict check result
+   */
+  async checkConflicts() {
+    const cwd = this.repoPath;
+
+    try {
+      // Try to fetch cloud branch from origin (ignore if no remote)
+      await execAsync(`git fetch origin ${this.cloudBranch}`, { cwd }).catch(() => {});
+
+      // Determine cloud branch reference (origin/ prefix if remote exists, otherwise local)
+      let cloudRef;
+      try {
+        await execAsync(`git rev-parse origin/${this.cloudBranch}`, { cwd });
+        cloudRef = `origin/${this.cloudBranch}`;
+      } catch {
+        // No remote - try local branch
+        try {
+          await execAsync(`git rev-parse ${this.cloudBranch}`, { cwd });
+          cloudRef = this.cloudBranch;
+        } catch {
+          // Cloud branch doesn't exist yet
+          this.lastConflictCheck = new Date().toISOString();
+          this.conflicts = [];
+          return {
+            hasConflicts: false,
+            conflictingFiles: [],
+            localChanges: 0,
+            cloudChanges: 0,
+            checkedAt: this.lastConflictCheck,
+          };
+        }
+      }
+
+      // Get files changed in local branch since fork point
+      const { stdout: localChanges } = await execAsync(
+        `git diff --name-only ${this.forkPoint}..HEAD`,
+        { cwd }
+      ).catch(() => ({ stdout: '' }));
+
+      // Get files changed in cloud branch since fork point
+      const { stdout: cloudChanges } = await execAsync(
+        `git diff --name-only ${this.forkPoint}..${cloudRef}`,
+        { cwd }
+      ).catch(() => ({ stdout: '' }));
+
+      const localFiles = localChanges.trim().split('\n').filter(Boolean);
+      const cloudFiles = cloudChanges.trim().split('\n').filter(Boolean);
+
+      // Find overlapping files (potential conflicts)
+      const conflictingFiles = localFiles.filter(f => cloudFiles.includes(f));
+
+      this.lastConflictCheck = new Date().toISOString();
+
+      if (conflictingFiles.length > 0) {
+        this.conflicts = conflictingFiles;
+
+        return {
+          hasConflicts: true,
+          conflictingFiles,
+          localChanges: localFiles.length,
+          cloudChanges: cloudFiles.length,
+          checkedAt: this.lastConflictCheck,
+        };
+      }
+
+      this.conflicts = [];
+
+      return {
+        hasConflicts: false,
+        conflictingFiles: [],
+        localChanges: localFiles.length,
+        cloudChanges: cloudFiles.length,
+        checkedAt: this.lastConflictCheck,
+      };
+    } catch (error) {
+      throw new Error(`Failed to check conflicts: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get divergence statistics between branches.
+   *
+   * @returns {Promise<Object>} Divergence stats
+   */
+  async getDivergence() {
+    const cwd = this.repoPath;
+
+    try {
+      // Try to fetch cloud branch from origin (ignore if no remote)
+      await execAsync(`git fetch origin ${this.cloudBranch}`, { cwd }).catch(() => {});
+
+      // Determine cloud branch reference
+      let cloudRef;
+      try {
+        await execAsync(`git rev-parse origin/${this.cloudBranch}`, { cwd });
+        cloudRef = `origin/${this.cloudBranch}`;
+      } catch {
+        // Try local branch
+        try {
+          await execAsync(`git rev-parse ${this.cloudBranch}`, { cwd });
+          cloudRef = this.cloudBranch;
+        } catch {
+          // Cloud branch doesn't exist - count local commits from fork point
+          if (this.forkPoint) {
+            const { stdout } = await execAsync(
+              `git rev-list --count ${this.forkPoint}..HEAD`,
+              { cwd }
+            ).catch(() => ({ stdout: '0' }));
+            return {
+              localAhead: parseInt(stdout.trim(), 10) || 0,
+              cloudAhead: 0,
+              diverged: false,
+              forkPoint: this.forkPoint,
+            };
+          }
+          return {
+            localAhead: this.localSession.commitCount,
+            cloudAhead: 0,
+            diverged: false,
+            forkPoint: this.forkPoint,
+          };
+        }
+      }
+
+      // Count commits ahead/behind
+      const { stdout: aheadBehind } = await execAsync(
+        `git rev-list --left-right --count HEAD...${cloudRef}`,
+        { cwd }
+      ).catch(() => ({ stdout: '0\t0' }));
+
+      const [localAhead, cloudAhead] = aheadBehind.trim().split('\t').map(Number);
+
+      return {
+        localAhead,
+        cloudAhead,
+        diverged: localAhead > 0 && cloudAhead > 0,
+        forkPoint: this.forkPoint,
+      };
+    } catch (error) {
+      // If cloud branch doesn't exist yet, only local has commits
+      return {
+        localAhead: this.localSession.commitCount,
+        cloudAhead: 0,
+        diverged: false,
+        forkPoint: this.forkPoint,
+      };
+    }
+  }
+
+  /**
+   * Generate merge plan for combining fork branches.
+   *
+   * @returns {Promise<Object>} Merge plan
+   */
+  async generateMergePlan() {
+    const conflicts = await this.checkConflicts();
+    const divergence = await this.getDivergence();
+
+    const plan = {
+      canAutoMerge: !conflicts.hasConflicts,
+      conflicts: conflicts.conflictingFiles,
+      divergence,
+      recommendedStrategy: null,
+      steps: [],
+    };
+
+    if (!conflicts.hasConflicts) {
+      // No conflicts - can auto-merge
+      if (divergence.localAhead === 0) {
+        plan.recommendedStrategy = 'fast-forward';
+        plan.steps = [
+          `git fetch origin ${this.cloudBranch}`,
+          `git merge origin/${this.cloudBranch}`,
+        ];
+      } else if (divergence.cloudAhead === 0) {
+        plan.recommendedStrategy = 'push';
+        plan.steps = [
+          `git push origin ${this.localBranch}:${this.cloudBranch}`,
+        ];
+      } else {
+        plan.recommendedStrategy = 'merge';
+        plan.steps = [
+          `git fetch origin ${this.cloudBranch}`,
+          `git merge origin/${this.cloudBranch}`,
+          'git push origin HEAD',
+        ];
+      }
+    } else {
+      // Has conflicts - manual resolution needed
+      plan.recommendedStrategy = 'manual';
+      plan.steps = [
+        `git fetch origin ${this.cloudBranch}`,
+        `git merge origin/${this.cloudBranch}`,
+        '# Resolve conflicts manually',
+        'git add <resolved-files>',
+        'git commit -m "Merge cloud session changes"',
+        'git push origin HEAD',
+      ];
+    }
+
+    return plan;
+  }
+
+  /**
+   * Get summary of fork state.
+   *
+   * @returns {Object} Fork state summary
+   */
+  getSummary() {
+    return {
+      teleportId: this.teleportId,
+      forkPoint: this.forkPoint,
+      localSession: {
+        ...this.localSession,
+        branch: this.localBranch,
+      },
+      cloudSession: {
+        ...this.cloudSession,
+        branch: this.cloudBranch,
+      },
+      conflicts: this.conflicts,
+      lastConflictCheck: this.lastConflictCheck,
+    };
+  }
+
+  /**
+   * Check if both sessions are still active.
+   *
+   * @returns {boolean} True if both sessions are active
+   */
+  areBothSessionsActive() {
+    return (
+      this.localSession.state === ForkSessionState.ACTIVE &&
+      this.cloudSession.state === ForkSessionState.ACTIVE
+    );
+  }
+
+  /**
+   * Mark local session as completed.
+   *
+   * @param {Object} [result] - Completion result
+   */
+  completeLocalSession(result) {
+    this.localSession.state = ForkSessionState.COMPLETED;
+    this.localSession.completedAt = new Date().toISOString();
+    if (result) {
+      this.localSession.result = result;
+    }
+  }
+
+  /**
+   * Mark cloud session as completed.
+   *
+   * @param {Object} [result] - Completion result
+   */
+  completeCloudSession(result) {
+    this.cloudSession.state = ForkSessionState.COMPLETED;
+    this.cloudSession.completedAt = new Date().toISOString();
+    if (result) {
+      this.cloudSession.result = result;
+    }
+  }
+}
+
+export default ForkTracker;