teleportation-cli 1.0.0

package/lib/utils/retry.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+/**
+ * Retry utility for API calls and network operations
+ * Provides exponential backoff and configurable retry logic
+ */
+
+/**
+ * Retry options
+ * @typedef {Object} RetryOptions
+ * @property {number} maxRetries - Maximum number of retry attempts (default: 3)
+ * @property {number} initialDelay - Initial delay in milliseconds (default: 1000)
+ * @property {number} maxDelay - Maximum delay in milliseconds (default: 10000)
+ * @property {number} factor - Exponential backoff factor (default: 2)
+ * @property {function} shouldRetry - Function to determine if error should be retried (default: retry on network errors)
+ * @property {function} onRetry - Callback called before each retry attempt
+ */
+
+/**
+ * Default retry options
+ */
+const DEFAULT_OPTIONS = {
+  maxRetries: 3,
+  initialDelay: 1000,
+  maxDelay: 10000,
+  factor: 2,
+  shouldRetry: (error) => {
+    // Retry on network errors, timeouts, and 5xx server errors
+    if (error.name === 'AbortError' || error.name === 'TypeError') {
+      return true; // Network/timeout errors
+    }
+    if (error.status >= 500 && error.status < 600) {
+      return true; // Server errors
+    }
+    if (error.code === 'ECONNREFUSED' || error.code === 'ETIMEDOUT' || error.code === 'ENOTFOUND') {
+      return true; // Connection errors
+    }
+    return false;
+  },
+  onRetry: null
+};
+
+/**
+ * Sleep for specified milliseconds
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Calculate delay for retry attempt with exponential backoff
+ */
+function calculateDelay(attempt, options) {
+  const delay = Math.min(
+    options.initialDelay * Math.pow(options.factor, attempt),
+    options.maxDelay
+  );
+  // Add jitter to prevent thundering herd
+  const jitter = Math.random() * 0.3 * delay; // Up to 30% jitter
+  return Math.floor(delay + jitter);
+}
+
+/**
+ * Retry a function with exponential backoff
+ * @param {Function} fn - Async function to retry
+ * @param {RetryOptions} options - Retry configuration options
+ * @returns {Promise} - Result of the function
+ */
+export async function retry(fn, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  let lastError;
+  
+  for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      
+      // Check if we should retry this error
+      if (!opts.shouldRetry(error)) {
+        throw error; // Don't retry non-retryable errors
+      }
+      
+      // Don't retry if we've exhausted attempts
+      if (attempt >= opts.maxRetries) {
+        break;
+      }
+      
+      // Calculate delay before retry
+      const delay = calculateDelay(attempt, opts);
+      
+      // Call onRetry callback if provided
+      if (opts.onRetry) {
+        opts.onRetry(error, attempt + 1, delay);
+      }
+      
+      // Wait before retrying
+      await sleep(delay);
+    }
+  }
+  
+  // All retries exhausted
+  throw lastError;
+}
+
+/**
+ * Retry a fetch request with exponential backoff
+ * @param {string} url - URL to fetch
+ * @param {RequestInit} fetchOptions - Fetch options
+ * @param {RetryOptions} retryOptions - Retry configuration options
+ * @returns {Promise<Response>} - Fetch response
+ */
+export async function retryFetch(url, fetchOptions = {}, retryOptions = {}) {
+  return retry(async () => {
+    const controller = new AbortController();
+    const timeout = retryOptions.timeout || 30000;
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    
+    try {
+      const response = await fetch(url, {
+        ...fetchOptions,
+        signal: controller.signal
+      });
+      
+      clearTimeout(timeoutId);
+      
+      // Treat 5xx errors as retryable
+      if (response.status >= 500 && response.status < 600) {
+        const error = new Error(`Server error: ${response.status}`);
+        error.status = response.status;
+        throw error;
+      }
+      
+      return response;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      throw error;
+    }
+  }, retryOptions);
+}
+
+/**
+ * Create a retryable API client function
+ * @param {string} baseUrl - Base URL for API
+ * @param {RetryOptions} defaultRetryOptions - Default retry options
+ * @returns {Function} - API client function
+ */
+export function createRetryableApiClient(baseUrl, defaultRetryOptions = {}) {
+  return async function apiCall(endpoint, options = {}, retryOptions = {}) {
+    const url = `${baseUrl}${endpoint}`;
+    const mergedRetryOptions = { ...defaultRetryOptions, ...retryOptions };
+    
+    return retryFetch(url, options, mergedRetryOptions);
+  };
+}
+

package/lib/worktree/manager.js

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+/**
+ * Worktree Management Module
+ * Handles git worktree creation, listing, and cleanup for session isolation
+ */
+
+import { execSync } from 'child_process';
+import { join, resolve, sep, relative } from 'path';
+import { mkdir, rm, readdir, stat } from 'fs/promises';
+import { existsSync } from 'fs';
+
+const WORKTREE_BASE = '.teleportation/sessions';
+
+// Input validation patterns
+const VALID_SESSION_ID = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+const VALID_BRANCH_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_\-/.]{0,127}$/;
+
+/**
+ * Validate and sanitize a session ID
+ * @param {string} sessionId - Session ID to validate
+ * @returns {string} Validated session ID
+ * @throws {Error} If session ID is invalid
+ */
+export function validateSessionId(sessionId) {
+  if (!sessionId || typeof sessionId !== 'string') {
+    throw new Error('Session ID is required');
+  }
+  if (!VALID_SESSION_ID.test(sessionId)) {
+    throw new Error(
+      `Invalid session ID: "${sessionId}". Must start with alphanumeric, contain only alphanumeric/dash/underscore, and be 1-64 characters.`
+    );
+  }
+  return sessionId;
+}
+
+/**
+ * Validate and sanitize a git branch name
+ * @param {string} branchName - Branch name to validate
+ * @returns {string} Validated branch name
+ * @throws {Error} If branch name is invalid
+ */
+export function validateBranchName(branchName) {
+  if (!branchName || typeof branchName !== 'string') {
+    throw new Error('Branch name is required');
+  }
+  if (!VALID_BRANCH_NAME.test(branchName)) {
+    throw new Error(
+      `Invalid branch name: "${branchName}". Must start with alphanumeric and contain only alphanumeric/dash/underscore/slash/dot.`
+    );
+  }
+  // Additional git-specific checks
+  if (branchName.includes('..') || branchName.endsWith('.lock') || branchName.endsWith('/')) {
+    throw new Error(`Invalid branch name: "${branchName}". Contains invalid git reference patterns.`);
+  }
+  return branchName;
+}
+
+/**
+ * List all git worktrees
+ * @returns {Array<{path: string, branch: string, commitHash: string}>}
+ */
+export function listWorktrees() {
+  try {
+    const output = execSync('git worktree list --porcelain', { encoding: 'utf8' });
+    const worktrees = [];
+    const lines = output.trim().split('\n');
+
+    let current = {};
+    for (const line of lines) {
+      if (line.startsWith('worktree ')) {
+        current.path = line.substring(9);
+      } else if (line.startsWith('branch ')) {
+        current.branch = line.substring(7).replace('refs/heads/', '');
+      } else if (line.startsWith('HEAD ')) {
+        current.commitHash = line.substring(5);
+      } else if (line === '') {
+        if (current.path) {
+          worktrees.push(current);
+          current = {};
+        }
+      }
+    }
+
+    // Push last one if exists
+    if (current.path) {
+      worktrees.push(current);
+    }
+
+    return worktrees;
+  } catch (error) {
+    throw new Error(`Failed to list worktrees: ${error.message}`);
+  }
+}
+
+/**
+ * Get the repository root directory
+ * @returns {string}
+ */
+export function getRepoRoot() {
+  try {
+    return execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+  } catch (error) {
+    throw new Error(`Not in a git repository: ${error.message}`);
+  }
+}
+
+/**
+ * Create a new worktree for a session
+ * @param {string} sessionId - Unique session identifier
+ * @param {string} branchName - Name of the branch to create
+ * @param {string} baseBranch - Base branch to branch from (default: 'main')
+ * @returns {Promise<{path: string, branch: string}>}
+ */
+export async function createWorktree(sessionId, branchName, baseBranch = 'main') {
+  // Validate all inputs to prevent command injection
+  const validSessionId = validateSessionId(sessionId);
+  const validBranchName = validateBranchName(branchName);
+  const validBaseBranch = validateBranchName(baseBranch);
+
+  const repoRoot = getRepoRoot();
+  const worktreePath = resolve(repoRoot, WORKTREE_BASE, validSessionId);
+
+  // Check if worktree already exists
+  if (existsSync(worktreePath)) {
+    throw new Error(`Worktree already exists at ${worktreePath}`);
+  }
+
+  // Ensure base directory exists
+  await mkdir(join(repoRoot, WORKTREE_BASE), { recursive: true });
+
+  // Check if branch already exists
+  const branches = execSync('git branch --list', { encoding: 'utf8' });
+  const branchExists = branches.includes(validBranchName);
+
+  try {
+    if (branchExists) {
+      // Use existing branch - inputs are validated, path is quoted
+      execSync(`git worktree add "${worktreePath}" "${validBranchName}"`, {
+        encoding: 'utf8',
+        stdio: 'pipe'
+      });
+    } else {
+      // Create new branch from base - inputs are validated, path is quoted
+      execSync(`git worktree add -b "${validBranchName}" "${worktreePath}" "${validBaseBranch}"`, {
+        encoding: 'utf8',
+        stdio: 'pipe'
+      });
+    }
+
+    return {
+      path: worktreePath,
+      branch: validBranchName,
+      sessionId: validSessionId
+    };
+  } catch (error) {
+    // Clean up on failure
+    if (existsSync(worktreePath)) {
+      await rm(worktreePath, { recursive: true, force: true });
+    }
+    // Prune any stale worktree references
+    try {
+      execSync('git worktree prune', { encoding: 'utf8', stdio: 'pipe' });
+    } catch {
+      // Prune failure is non-fatal
+    }
+    throw new Error(`Failed to create worktree: ${error.message}`);
+  }
+}
+
+/**
+ * Remove a worktree
+ * @param {string} worktreePath - Path to the worktree
+ * @param {boolean} force - Force removal even with uncommitted changes
+ * @returns {Promise<void>}
+ */
+export async function removeWorktree(worktreePath, force = false) {
+  const absolutePath = resolve(worktreePath);
+
+  if (!existsSync(absolutePath)) {
+    throw new Error(`Worktree not found at ${absolutePath}`);
+  }
+
+  try {
+    const forceFlag = force ? '--force' : '';
+    execSync(`git worktree remove ${forceFlag} "${absolutePath}"`, {
+      encoding: 'utf8',
+      stdio: 'pipe'
+    });
+  } catch (error) {
+    throw new Error(`Failed to remove worktree: ${error.message}`);
+  }
+}
+
+/**
+ * Prune stale worktree administrative files
+ * @returns {void}
+ */
+export function pruneWorktrees() {
+  try {
+    execSync('git worktree prune', { encoding: 'utf8', stdio: 'pipe' });
+  } catch (error) {
+    throw new Error(`Failed to prune worktrees: ${error.message}`);
+  }
+}
+
+/**
+ * Get worktree info by path
+ * @param {string} worktreePath - Path to worktree
+ * @returns {Object|null}
+ */
+export function getWorktreeInfo(worktreePath) {
+  const worktrees = listWorktrees();
+  const absolutePath = resolve(worktreePath);
+  return worktrees.find(wt => wt.path === absolutePath) || null;
+}
+
+/**
+ * Check if current directory is inside a worktree
+ * @returns {boolean}
+ */
+export function isInWorktree() {
+  try {
+    const repoRoot = getRepoRoot();
+    const currentDir = process.cwd();
+    // Use path.relative for proper cross-platform comparison
+    const relativePath = relative(repoRoot, currentDir);
+    // Check if the relative path starts with the worktree base
+    const worktreeBaseParts = WORKTREE_BASE.split('/');
+    const currentParts = relativePath.split(sep);
+    // Check if current path is under WORKTREE_BASE
+    return worktreeBaseParts.every((part, i) => currentParts[i] === part);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the session ID from current worktree path
+ * @returns {string|null}
+ */
+export function getCurrentSessionId() {
+  if (!isInWorktree()) {
+    return null;
+  }
+
+  try {
+    const currentDir = process.cwd();
+    const repoRoot = getRepoRoot();
+    // Use path.relative for cross-platform compatibility
+    const relativePath = relative(repoRoot, currentDir);
+    // Split using path.sep for cross-platform support (/ on Unix, \ on Windows)
+    const parts = relativePath.split(sep);
+
+    const sessionsIndex = parts.indexOf('sessions');
+    if (sessionsIndex >= 0 && sessionsIndex < parts.length - 1) {
+      return parts[sessionsIndex + 1];
+    }
+  } catch {
+    // If anything fails, return null
+  }
+
+  return null;
+}
+
+/**
+ * List all session worktrees
+ * @returns {Promise<Array<{sessionId: string, path: string, branch: string}>>}
+ */
+export async function listSessionWorktrees() {
+  const repoRoot = getRepoRoot();
+  const sessionsDir = join(repoRoot, WORKTREE_BASE);
+
+  if (!existsSync(sessionsDir)) {
+    return [];
+  }
+
+  const allWorktrees = listWorktrees();
+  const sessionWorktrees = [];
+
+  // Get all directories in sessions folder
+  const entries = await readdir(sessionsDir);
+
+  for (const entry of entries) {
+    const entryPath = join(sessionsDir, entry);
+    const entryStat = await stat(entryPath);
+
+    if (entryStat.isDirectory()) {
+      const worktreeInfo = allWorktrees.find(wt => wt.path === entryPath);
+      if (worktreeInfo) {
+        sessionWorktrees.push({
+          sessionId: entry,
+          path: entryPath,
+          branch: worktreeInfo.branch,
+          commitHash: worktreeInfo.commitHash
+        });
+      }
+    }
+  }
+
+  return sessionWorktrees;
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "teleportation-cli",
+  "version": "1.0.0",
+  "description": "Remote approval system for Claude Code - approve AI coding changes from your phone",
+  "type": "module",
+  "main": "teleportation-cli.cjs",
+  "bin": {
+    "teleportation": "./teleportation-cli.cjs"
+  },
+  "engines": {
+    "bun": "^1.3.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dundas/teleportation-private.git"
+  },
+  "homepage": "https://github.com/dundas/teleportation-private#readme",
+  "bugs": {
+    "url": "https://github.com/dundas/teleportation-private/issues"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "remote-control",
+    "approval",
+    "mobile",
+    "ai",
+    "coding-assistant",
+    "cli"
+  ],
+  "author": "Dundas",
+  "scripts": {
+    "test": "bun --bun vitest run 'tests/**/*.test.js' 'lib/**/*.test.js'",
+    "test:watch": "bun --bun vitest",
+    "test:coverage": "bun --bun vitest --coverage",
+    "test:e2e": "bun --bun vitest run tests/e2e",
+    "test:unit": "bun --bun vitest run tests/unit",
+    "test:integration": "bun --bun vitest run tests/integration",
+    "dev:relay": "cd relay && bun run dev",
+    "dev:mobile": "cd mobile-ui && bun run dev",
+    "dev:all": "bun run dev:relay & bun run dev:mobile",
+    "prepublishOnly": "echo 'Skipping tests for now - will fix test command post-publish'"
+  },
+  "files": [
+    "lib/**/*.js",
+    "!lib/**/*.test.js",
+    "!lib/**/*.test.mjs",
+    "!lib/**/test-*.js",
+    "!lib/**/vitest.config.js",
+    "!lib/**/*.log",
+    ".claude/hooks/*.mjs",
+    "!.claude/hooks/*.test.mjs",
+    "teleportation-cli.cjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.9",
+    "axios": "^1.13.2",
+    "vitest": "^4.0.9"
+  },
+  "dependencies": {
+    "dotenv": "^17.2.3"
+  }
+}