teleportation-cli 1.0.0

package/lib/snapshot/manager.js

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+/**
+ * Snapshot Management Module
+ * Handles creation, restoration, and management of code snapshots
+ */
+
+import { execSync } from 'child_process';
+import { join, resolve, basename } from 'path';
+import { mkdir, writeFile, readFile, readdir, rm } from 'fs/promises';
+import { existsSync } from 'fs';
+import { getRepoRoot, validateSessionId } from '../worktree/manager.js';
+
+const SNAPSHOT_BASE = '.teleportation/snapshots';
+
+// Validation pattern for snapshot IDs (session-type-timestamp format)
+const VALID_SNAPSHOT_ID = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}-[a-z-]+-\d+$/;
+
+/**
+ * Validate a snapshot ID format
+ * @param {string} snapshotId - Snapshot ID to validate
+ * @returns {string} Validated snapshot ID
+ * @throws {Error} If snapshot ID is invalid
+ */
+function validateSnapshotId(snapshotId) {
+  if (!snapshotId || typeof snapshotId !== 'string') {
+    throw new Error('Snapshot ID is required');
+  }
+  if (!VALID_SNAPSHOT_ID.test(snapshotId)) {
+    throw new Error(
+      `Invalid snapshot ID format: "${snapshotId}". Expected format: sessionId-type-timestamp`
+    );
+  }
+  return snapshotId;
+}
+
+/**
+ * Validate a commit hash (SHA-1 or abbreviated)
+ * @param {string} commitHash - Commit hash to validate
+ * @returns {string} Validated commit hash
+ * @throws {Error} If commit hash is invalid
+ */
+function validateCommitHash(commitHash) {
+  if (!commitHash || typeof commitHash !== 'string') {
+    throw new Error('Commit hash is required');
+  }
+  // SHA-1 hashes are 40 hex chars, but abbreviated can be 7+
+  if (!/^[a-f0-9]{7,40}$/i.test(commitHash)) {
+    throw new Error(`Invalid commit hash: "${commitHash}"`);
+  }
+  return commitHash;
+}
+
+/**
+ * Validate a stash reference
+ * @param {string} stashRef - Stash reference to validate
+ * @returns {string} Validated stash reference
+ * @throws {Error} If stash reference is invalid
+ */
+function validateStashRef(stashRef) {
+  if (!stashRef || typeof stashRef !== 'string') {
+    throw new Error('Stash reference is required');
+  }
+  // stash@{n} format
+  if (!/^stash@\{\d+\}$/.test(stashRef)) {
+    throw new Error(`Invalid stash reference: "${stashRef}"`);
+  }
+  return stashRef;
+}
+
+/**
+ * Snapshot types
+ */
+export const SnapshotType = {
+  BASELINE: 'baseline',        // Initial state when session starts
+  CHECKPOINT: 'checkpoint',    // Manual checkpoint
+  PRE_MERGE: 'pre-merge',     // Before merging from another branch
+  PRE_COMMIT: 'pre-commit',   // Before committing
+  AUTO: 'auto',               // Automatic periodic snapshot
+  PRE_DESTROY: 'pre-destroy'  // Before destroying worktree
+};
+
+/**
+ * Create a snapshot of the current working directory state
+ * @param {string} sessionId - Session identifier
+ * @param {string} type - Snapshot type
+ * @param {string} message - Optional message describing the snapshot
+ * @returns {Promise<{id: string, type: string, timestamp: number, message: string, stashRef: string}>}
+ */
+export async function createSnapshot(sessionId, type = SnapshotType.AUTO, message = '') {
+  // Validate session ID to prevent command injection
+  const validSessionId = validateSessionId(sessionId);
+
+  // Validate snapshot type
+  const validTypes = Object.values(SnapshotType);
+  if (!validTypes.includes(type)) {
+    throw new Error(`Invalid snapshot type: "${type}". Valid types: ${validTypes.join(', ')}`);
+  }
+
+  const repoRoot = getRepoRoot();
+  const timestamp = Date.now();
+  const snapshotId = `${validSessionId}-${type}-${timestamp}`;
+
+  // Create snapshot metadata
+  const metadata = {
+    id: snapshotId,
+    sessionId,
+    type,
+    timestamp,
+    message,
+    branch: getCurrentBranch(),
+    commitHash: getCurrentCommitHash(),
+    hasUncommittedChanges: hasUncommittedChanges(),
+    hasUntrackedFiles: hasUntrackedFiles()
+  };
+
+  // Ensure snapshot directory exists
+  const snapshotDir = join(repoRoot, SNAPSHOT_BASE, sessionId);
+  await mkdir(snapshotDir, { recursive: true });
+
+  // If there are uncommitted changes, create a git stash
+  let stashRef = null;
+  if (metadata.hasUncommittedChanges || metadata.hasUntrackedFiles) {
+    stashRef = createStash(snapshotId);
+    metadata.stashRef = stashRef;
+  }
+
+  // Save metadata
+  const metadataPath = join(snapshotDir, `${snapshotId}.json`);
+  await writeFile(metadataPath, JSON.stringify(metadata, null, 2));
+
+  return metadata;
+}
+
+/**
+ * Restore a snapshot
+ * @param {string} snapshotId - Snapshot ID to restore
+ * @param {boolean} force - Force restore even with uncommitted changes
+ * @returns {Promise<void>}
+ */
+export async function restoreSnapshot(snapshotId, force = false) {
+  const repoRoot = getRepoRoot();
+
+  // Find snapshot metadata
+  const metadata = await getSnapshotMetadata(snapshotId);
+  if (!metadata) {
+    throw new Error(`Snapshot not found: ${snapshotId}`);
+  }
+
+  // Validate commit hash before using in command
+  const validCommitHash = validateCommitHash(metadata.commitHash);
+
+  // Check for uncommitted changes
+  if (!force && (hasUncommittedChanges() || hasUntrackedFiles())) {
+    throw new Error(
+      'Cannot restore snapshot: uncommitted changes present. Use --force to override.'
+    );
+  }
+
+  // Restore commit state
+  try {
+    execSync(`git checkout "${validCommitHash}"`, {
+      encoding: 'utf8',
+      stdio: 'pipe'
+    });
+  } catch (error) {
+    throw new Error(`Failed to checkout commit ${validCommitHash}: ${error.message}`);
+  }
+
+  // Restore stash if exists - use apply to allow multiple restores
+  if (metadata.stashRef) {
+    const validStashRef = validateStashRef(metadata.stashRef);
+    try {
+      // Use 'apply' instead of 'pop' to keep stash for multiple restores
+      // The stash is only dropped when the snapshot is deleted
+      execSync(`git stash apply "${validStashRef}"`, {
+        encoding: 'utf8',
+        stdio: 'pipe'
+      });
+
+      // Track restoration in metadata (but keep stashRef for future restores)
+      const metadataPath = join(
+        repoRoot,
+        SNAPSHOT_BASE,
+        metadata.sessionId,
+        `${snapshotId}.json`
+      );
+      metadata.lastRestoredAt = Date.now();
+      metadata.restoreCount = (metadata.restoreCount || 0) + 1;
+      await writeFile(metadataPath, JSON.stringify(metadata, null, 2));
+    } catch (error) {
+      throw new Error(`Failed to apply stash ${validStashRef}: ${error.message}`);
+    }
+  }
+}
+
+/**
+ * List all snapshots for a session
+ * @param {string} sessionId - Session identifier
+ * @returns {Promise<Array<Object>>}
+ */
+export async function listSnapshots(sessionId) {
+  const repoRoot = getRepoRoot();
+  const snapshotDir = join(repoRoot, SNAPSHOT_BASE, sessionId);
+
+  if (!existsSync(snapshotDir)) {
+    return [];
+  }
+
+  const files = await readdir(snapshotDir);
+  const snapshots = [];
+
+  for (const file of files) {
+    if (file.endsWith('.json')) {
+      const metadataPath = join(snapshotDir, file);
+      const content = await readFile(metadataPath, 'utf8');
+      snapshots.push(JSON.parse(content));
+    }
+  }
+
+  // Sort by timestamp (newest first)
+  snapshots.sort((a, b) => b.timestamp - a.timestamp);
+
+  return snapshots;
+}
+
+/**
+ * Delete a snapshot
+ * @param {string} snapshotId - Snapshot ID to delete
+ * @returns {Promise<void>}
+ */
+export async function deleteSnapshot(snapshotId) {
+  const metadata = await getSnapshotMetadata(snapshotId);
+  if (!metadata) {
+    throw new Error(`Snapshot not found: ${snapshotId}`);
+  }
+
+  const repoRoot = getRepoRoot();
+  const metadataPath = join(
+    repoRoot,
+    SNAPSHOT_BASE,
+    metadata.sessionId,
+    `${snapshotId}.json`
+  );
+
+  // Delete stash if it exists
+  if (metadata.stashRef) {
+    const validStashRef = validateStashRef(metadata.stashRef);
+    try {
+      execSync(`git stash drop "${validStashRef}"`, {
+        encoding: 'utf8',
+        stdio: 'pipe'
+      });
+    } catch (error) {
+      // Check if stash still exists - if yes, it's a real error
+      const stashList = execSync('git stash list', { encoding: 'utf8' });
+      if (stashList.includes(validStashRef)) {
+        throw new Error(`Failed to drop stash ${validStashRef}: stash still exists`);
+      }
+      // Stash already gone (possibly from earlier operation), safe to continue
+    }
+  }
+
+  // Now safe to delete metadata file
+  await rm(metadataPath, { force: true });
+}
+
+/**
+ * Delete all snapshots for a session
+ * @param {string} sessionId - Session identifier
+ * @returns {Promise<number>} Number of snapshots deleted
+ */
+export async function deleteAllSnapshots(sessionId) {
+  const snapshots = await listSnapshots(sessionId);
+
+  for (const snapshot of snapshots) {
+    await deleteSnapshot(snapshot.id);
+  }
+
+  // Remove session directory if empty
+  const repoRoot = getRepoRoot();
+  const snapshotDir = join(repoRoot, SNAPSHOT_BASE, sessionId);
+
+  try {
+    await rm(snapshotDir, { recursive: true, force: true });
+  } catch {
+    // Directory might not be empty or might not exist, that's ok
+  }
+
+  return snapshots.length;
+}
+
+/**
+ * Get diff between current state and a snapshot
+ * @param {string} snapshotId - Snapshot ID
+ * @returns {Promise<string>}
+ */
+export async function getSnapshotDiff(snapshotId) {
+  const metadata = await getSnapshotMetadata(snapshotId);
+  if (!metadata) {
+    throw new Error(`Snapshot not found: ${snapshotId}`);
+  }
+
+  // Validate commit hash before using in command
+  const validCommitHash = validateCommitHash(metadata.commitHash);
+
+  try {
+    const diff = execSync(`git diff "${validCommitHash}"`, {
+      encoding: 'utf8'
+    });
+    return diff;
+  } catch (error) {
+    throw new Error(`Failed to get diff: ${error.message}`);
+  }
+}
+
+// Helper functions
+
+function getCurrentBranch() {
+  try {
+    return execSync('git branch --show-current', { encoding: 'utf8' }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function getCurrentCommitHash() {
+  try {
+    return execSync('git rev-parse HEAD', { encoding: 'utf8' }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function hasUncommittedChanges() {
+  try {
+    const status = execSync('git status --porcelain', { encoding: 'utf8' });
+    // Check for modified or staged files (lines starting with M, A, D, etc.)
+    return status.split('\n').some(line => {
+      const trimmed = line.trim();
+      return trimmed && !trimmed.startsWith('??');
+    });
+  } catch {
+    return false;
+  }
+}
+
+function hasUntrackedFiles() {
+  try {
+    const status = execSync('git status --porcelain', { encoding: 'utf8' });
+    // Check for untracked files (lines starting with ??)
+    return status.includes('??');
+  } catch {
+    return false;
+  }
+}
+
+function createStash(snapshotId) {
+  // snapshotId is already validated in createSnapshot, but double-check format
+  // to ensure no shell metacharacters in stash message
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*-[a-z-]+-\d+$/.test(snapshotId)) {
+    throw new Error(`Invalid snapshot ID for stash: ${snapshotId}`);
+  }
+
+  try {
+    execSync(`git stash push -u -m "snapshot:${snapshotId}"`, {
+      encoding: 'utf8',
+      stdio: 'pipe'
+    });
+
+    // Get the stash reference
+    const stashList = execSync('git stash list', { encoding: 'utf8' });
+    const match = stashList.match(/stash@\{0\}/);
+    return match ? match[0] : null;
+  } catch (error) {
+    throw new Error(`Failed to create stash: ${error.message}`);
+  }
+}
+
+async function getSnapshotMetadata(snapshotId) {
+  const repoRoot = getRepoRoot();
+  const sessionId = snapshotId.split('-')[0];
+  const metadataPath = join(repoRoot, SNAPSHOT_BASE, sessionId, `${snapshotId}.json`);
+
+  if (!existsSync(metadataPath)) {
+    return null;
+  }
+
+  const content = await readFile(metadataPath, 'utf8');
+  return JSON.parse(content);
+}

package/lib/utils/errors.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+/**
+ * Custom error classes for Teleportation CLI
+ * Provides structured error handling with user-friendly messages
+ */
+
+class TeleportationError extends Error {
+  constructor(message, code = 'UNKNOWN_ERROR', details = null) {
+    super(message);
+    this.name = 'TeleportationError';
+    this.code = code;
+    this.details = details;
+    Error.captureStackTrace(this, this.constructor);
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      details: this.details
+    };
+  }
+}
+
+class ConfigurationError extends TeleportationError {
+  constructor(message, details = null) {
+    super(message, 'CONFIG_ERROR', details);
+    this.name = 'ConfigurationError';
+  }
+}
+
+class AuthenticationError extends TeleportationError {
+  constructor(message, details = null) {
+    super(message, 'AUTH_ERROR', details);
+    this.name = 'AuthenticationError';
+  }
+}
+
+class NetworkError extends TeleportationError {
+  constructor(message, details = null) {
+    super(message, 'NETWORK_ERROR', details);
+    this.name = 'NetworkError';
+  }
+}
+
+class ValidationError extends TeleportationError {
+  constructor(message, details = null) {
+    super(message, 'VALIDATION_ERROR', details);
+    this.name = 'ValidationError';
+  }
+}
+
+class FileSystemError extends TeleportationError {
+  constructor(message, details = null) {
+    super(message, 'FILESYSTEM_ERROR', details);
+    this.name = 'FileSystemError';
+  }
+}
+
+/**
+ * Format error for user display
+ */
+function formatError(error) {
+  if (error instanceof TeleportationError) {
+    return {
+      message: error.message,
+      code: error.code,
+      details: error.details,
+      userFriendly: getUserFriendlyMessage(error)
+    };
+  }
+  
+  // Handle standard errors
+  return {
+    message: error.message,
+    code: 'UNKNOWN_ERROR',
+    details: null,
+    userFriendly: getUserFriendlyMessage(error)
+  };
+}
+
+/**
+ * Get user-friendly error message
+ */
+function getUserFriendlyMessage(error) {
+  if (error instanceof ConfigurationError) {
+    return `Configuration error: ${error.message}. Please check your settings with 'teleportation config list'.`;
+  }
+  
+  if (error instanceof AuthenticationError) {
+    return `Authentication failed: ${error.message}. Please try 'teleportation login' again.`;
+  }
+  
+  if (error instanceof NetworkError) {
+    return `Network error: ${error.message}. Please check your internet connection and try again.`;
+  }
+  
+  if (error instanceof ValidationError) {
+    return `Invalid input: ${error.message}. Please check your command syntax.`;
+  }
+  
+  if (error instanceof FileSystemError) {
+    return `File system error: ${error.message}. Please check file permissions.`;
+  }
+  
+  // Handle common system errors
+  if (error.code === 'ENOENT') {
+    return `File not found: ${error.message}. The file may have been moved or deleted.`;
+  }
+  
+  if (error.code === 'EACCES') {
+    return `Permission denied: ${error.message}. Please check file permissions.`;
+  }
+  
+  if (error.code === 'ECONNREFUSED') {
+    return `Connection refused: ${error.message}. The server may be down or unreachable.`;
+  }
+  
+  if (error.code === 'ETIMEDOUT') {
+    return `Connection timeout: ${error.message}. The server took too long to respond.`;
+  }
+  
+  // Default message
+  return error.message || 'An unexpected error occurred. Please try again.';
+}
+
+/**
+ * Handle error and exit with appropriate code
+ */
+function handleError(error, logger = null) {
+  const formatted = formatError(error);
+  
+  if (logger) {
+    logger.error('Error occurred', formatted);
+  } else {
+    console.error(`❌ Error [${formatted.code}]: ${formatted.userFriendly}`);
+    if (formatted.details && process.env.DEBUG) {
+      console.error('Details:', formatted.details);
+    }
+  }
+  
+  // Exit with appropriate code
+  const exitCodes = {
+    'CONFIG_ERROR': 2,
+    'AUTH_ERROR': 3,
+    'NETWORK_ERROR': 4,
+    'VALIDATION_ERROR': 5,
+    'FILESYSTEM_ERROR': 6
+  };
+  
+  process.exit(exitCodes[formatted.code] || 1);
+}
+
+export {
+  TeleportationError,
+  ConfigurationError,
+  AuthenticationError,
+  NetworkError,
+  ValidationError,
+  FileSystemError,
+  formatError,
+  getUserFriendlyMessage,
+  handleError
+};
+

package/lib/utils/logger.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * Structured logging utility for Teleportation CLI
+ * Supports different log levels and output formats
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const LOG_LEVELS = {
+  DEBUG: 0,
+  INFO: 1,
+  WARN: 2,
+  ERROR: 3,
+  NONE: 4
+};
+
+const LOG_LEVEL_NAMES = {
+  0: 'DEBUG',
+  1: 'INFO',
+  2: 'WARN',
+  3: 'ERROR',
+  4: 'NONE'
+};
+
+class Logger {
+  constructor(options = {}) {
+    this.level = options.level || (process.env.DEBUG ? LOG_LEVELS.DEBUG : LOG_LEVELS.INFO);
+    this.logFile = options.logFile || path.join(os.homedir(), '.teleportation', 'logs', 'cli.log');
+    this.enableFileLogging = options.enableFileLogging !== false;
+    this.enableColors = options.enableColors !== false && process.stdout.isTTY;
+    
+    // Ensure log directory exists
+    if (this.enableFileLogging) {
+      const logDir = path.dirname(this.logFile);
+      if (!fs.existsSync(logDir)) {
+        fs.mkdirSync(logDir, { recursive: true });
+      }
+    }
+  }
+
+  _colorize(level, message) {
+    if (!this.enableColors) return message;
+    
+    const colors = {
+      DEBUG: '\x1b[0;36m', // Cyan
+      INFO: '\x1b[0;32m',  // Green
+      WARN: '\x1b[1;33m',  // Yellow
+      ERROR: '\x1b[0;31m'  // Red
+    };
+    const reset = '\x1b[0m';
+    
+    return `${colors[level] || ''}${message}${reset}`;
+  }
+
+  _formatMessage(level, message, data = null) {
+    const timestamp = new Date().toISOString();
+    const levelName = LOG_LEVEL_NAMES[level];
+    const prefix = `[${timestamp}] [${levelName}]`;
+    
+    let formatted = `${prefix} ${message}`;
+    if (data) {
+      formatted += ` ${JSON.stringify(data)}`;
+    }
+    
+    return formatted;
+  }
+
+  _write(level, message, data = null) {
+    if (level < this.level) {
+      return;
+    }
+
+    const formatted = this._formatMessage(level, message, data);
+    const levelName = LOG_LEVEL_NAMES[level];
+    
+    // Console output (with colors)
+    const consoleMessage = this._colorize(levelName, formatted);
+    if (level >= LOG_LEVELS.ERROR) {
+      console.error(consoleMessage);
+    } else {
+      console.log(consoleMessage);
+    }
+
+    // File output (without colors)
+    if (this.enableFileLogging) {
+      try {
+        fs.appendFileSync(this.logFile, formatted + '\n', { flag: 'a' });
+      } catch (e) {
+        // Silently fail if log file can't be written
+      }
+    }
+  }
+
+  debug(message, data) {
+    this._write(LOG_LEVELS.DEBUG, message, data);
+  }
+
+  info(message, data) {
+    this._write(LOG_LEVELS.INFO, message, data);
+  }
+
+  warn(message, data) {
+    this._write(LOG_LEVELS.WARN, message, data);
+  }
+
+  error(message, data) {
+    this._write(LOG_LEVELS.ERROR, message, data);
+  }
+
+  // Convenience methods for common patterns
+  success(message) {
+    if (this.enableColors) {
+      console.log(`\x1b[0;32m✓\x1b[0m ${message}`);
+    } else {
+      console.log(`✓ ${message}`);
+    }
+  }
+
+  failure(message) {
+    if (this.enableColors) {
+      console.error(`\x1b[0;31m✗\x1b[0m ${message}`);
+    } else {
+      console.error(`✗ ${message}`);
+    }
+  }
+
+  // Get log file path
+  getLogFile() {
+    return this.logFile;
+  }
+
+  // Set log level
+  setLevel(level) {
+    if (typeof level === 'string') {
+      level = LOG_LEVELS[level.toUpperCase()] || LOG_LEVELS.INFO;
+    }
+    this.level = level;
+  }
+}
+
+// Create default logger instance
+const logger = new Logger();
+
+export default logger;
+export { Logger, LOG_LEVELS };
+