claude-comms 1.0.1 → 1.0.2

package/src/utils/platform.js

@@ -0,0 +1,362 @@
+/**
+ * Platform detection and cross-platform utilities
+ * Handles OS detection, path normalization, and platform-specific operations
+ */
+
+const path = require('path');
+const os = require('os');
+const fs = require('fs').promises;
+
+/**
+ * Platform information and utilities
+ */
+class Platform {
+  constructor() {
+    this.platform = os.platform();
+    this.arch = os.arch();
+    this.release = os.release();
+    this.homedir = os.homedir();
+    this.tmpdir = os.tmpdir();
+  }
+
+  /**
+   * Check if running on Windows
+   */
+  isWindows() {
+    return this.platform === 'win32';
+  }
+
+  /**
+   * Check if running on macOS
+   */
+  isMacOS() {
+    return this.platform === 'darwin';
+  }
+
+  /**
+   * Check if running on Linux
+   */
+  isLinux() {
+    return this.platform === 'linux';
+  }
+
+  /**
+   * Check if running on Unix-like system (Linux or macOS)
+   */
+  isUnix() {
+    return this.isLinux() || this.isMacOS();
+  }
+
+  /**
+   * Get platform-specific line ending
+   */
+  getLineEnding() {
+    return this.isWindows() ? '\r\n' : '\n';
+  }
+
+  /**
+   * Get platform-specific path separator
+   */
+  getPathSeparator() {
+    return path.sep;
+  }
+
+  /**
+   * Normalize path for current platform
+   */
+  normalizePath(inputPath) {
+    if (!inputPath) return inputPath;
+    return path.normalize(inputPath);
+  }
+
+  /**
+   * Resolve path relative to home directory
+   */
+  resolveHome(inputPath) {
+    if (!inputPath) return inputPath;
+    if (inputPath.startsWith('~/') || inputPath === '~') {
+      return path.join(this.homedir, inputPath.slice(2));
+    }
+    return inputPath;
+  }
+
+  /**
+   * Get absolute path, resolving ~ and relative paths
+   */
+  getAbsolutePath(inputPath, relativeTo = process.cwd()) {
+    if (!inputPath) return relativeTo;
+
+    // Resolve home directory
+    let resolved = this.resolveHome(inputPath);
+
+    // Make absolute if relative
+    if (!path.isAbsolute(resolved)) {
+      resolved = path.resolve(relativeTo, resolved);
+    }
+
+    return this.normalizePath(resolved);
+  }
+
+  /**
+   * Check if path is safe (prevent directory traversal)
+   */
+  isSafePath(inputPath, basePath) {
+    try {
+      const absolute = this.getAbsolutePath(inputPath);
+      const baseAbsolute = this.getAbsolutePath(basePath);
+      const relative = path.relative(baseAbsolute, absolute);
+
+      // Check if path escapes base directory
+      return !relative.startsWith('..') && !path.isAbsolute(relative);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get user's shell information
+   */
+  getShellInfo() {
+    const shell = process.env.SHELL || (this.isWindows() ? 'cmd' : 'bash');
+    const shellName = path.basename(shell);
+
+    return {
+      path: shell,
+      name: shellName,
+      isInteractive: !!process.stdout.isTTY
+    };
+  }
+
+  /**
+   * Check if running in CI environment
+   */
+  isCI() {
+    return !!(
+      process.env.CI ||
+      process.env.CONTINUOUS_INTEGRATION ||
+      process.env.BUILD_NUMBER ||
+      process.env.GITHUB_ACTIONS ||
+      process.env.TRAVIS ||
+      process.env.CIRCLECI
+    );
+  }
+
+  /**
+   * Get available disk space for a path
+   */
+  async getDiskSpace(targetPath) {
+    try {
+      const stats = await fs.statfs ? fs.statfs(targetPath) : null;
+      if (stats) {
+        return {
+          free: stats.bavail * stats.bsize,
+          total: stats.blocks * stats.bsize
+        };
+      }
+    } catch (error) {
+      // Fallback: return null if can't determine
+    }
+    return null;
+  }
+
+  /**
+   * Check if directory is writable
+   */
+  async isWritable(dirPath) {
+    try {
+      const testFile = path.join(dirPath, '.write-test-' + Date.now());
+      await fs.writeFile(testFile, 'test');
+      await fs.unlink(testFile);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get platform-specific configuration directory
+   */
+  getConfigDir(appName = 'claude-code') {
+    if (this.isWindows()) {
+      return path.join(process.env.APPDATA || this.homedir, appName);
+    } else if (this.isMacOS()) {
+      return path.join(this.homedir, 'Library', 'Application Support', appName);
+    } else {
+      return path.join(process.env.XDG_CONFIG_HOME || path.join(this.homedir, '.config'), appName);
+    }
+  }
+
+  /**
+   * Get platform-specific cache directory
+   */
+  getCacheDir(appName = 'claude-code') {
+    if (this.isWindows()) {
+      return path.join(process.env.LOCALAPPDATA || this.tmpdir, appName);
+    } else if (this.isMacOS()) {
+      return path.join(this.homedir, 'Library', 'Caches', appName);
+    } else {
+      return path.join(process.env.XDG_CACHE_HOME || path.join(this.homedir, '.cache'), appName);
+    }
+  }
+
+  /**
+   * Get platform-specific executable extension
+   */
+  getExecutableExtension() {
+    return this.isWindows() ? '.exe' : '';
+  }
+
+  /**
+   * Find executable in PATH
+   */
+  async findExecutable(name) {
+    const extension = this.getExecutableExtension();
+    const execName = name + extension;
+
+    // Check current directory first
+    try {
+      const localPath = path.join(process.cwd(), execName);
+      await fs.access(localPath, fs.constants.F_OK | fs.constants.X_OK);
+      return localPath;
+    } catch {
+      // Continue to PATH search
+    }
+
+    // Search in PATH
+    const pathEnv = process.env.PATH || '';
+    const pathDirs = pathEnv.split(path.delimiter);
+
+    for (const dir of pathDirs) {
+      if (!dir) continue;
+
+      try {
+        const execPath = path.join(dir, execName);
+        await fs.access(execPath, fs.constants.F_OK | fs.constants.X_OK);
+        return execPath;
+      } catch {
+        // Continue searching
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Check if a command is available
+   */
+  async hasCommand(command) {
+    return (await this.findExecutable(command)) !== null;
+  }
+
+  /**
+   * Get environment variable with platform-specific defaults
+   */
+  getEnvVar(name, defaultValue = null, options = {}) {
+    const value = process.env[name];
+
+    if (value !== undefined) {
+      if (options.type === 'boolean') {
+        return ['true', '1', 'yes', 'on'].includes(value.toLowerCase());
+      }
+      if (options.type === 'number') {
+        const num = Number(value);
+        return isNaN(num) ? defaultValue : num;
+      }
+      if (options.type === 'array') {
+        const separator = options.separator || (this.isWindows() ? ';' : ':');
+        return value.split(separator).filter(Boolean);
+      }
+      return value;
+    }
+
+    return defaultValue;
+  }
+
+  /**
+   * Get platform-specific temp file path
+   */
+  getTempFilePath(prefix = 'claude-installer', extension = '') {
+    const filename = `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2)}${extension}`;
+    return path.join(this.tmpdir, filename);
+  }
+
+  /**
+   * Convert file content for platform (handle line endings)
+   */
+  convertFileContent(content, targetPlatform = null) {
+    const target = targetPlatform || this.platform;
+    const targetEnding = target === 'win32' ? '\r\n' : '\n';
+
+    // Normalize all line endings to \n first, then convert to target
+    return content.replace(/\r\n|\r|\n/g, '\n').replace(/\n/g, targetEnding);
+  }
+
+  /**
+   * Get platform summary for debugging
+   */
+  getSummary() {
+    return {
+      platform: this.platform,
+      arch: this.arch,
+      release: this.release,
+      nodeVersion: process.version,
+      isCI: this.isCI(),
+      shell: this.getShellInfo(),
+      homedir: this.homedir,
+      configDir: this.getConfigDir(),
+      cacheDir: this.getCacheDir()
+    };
+  }
+}
+
+/**
+ * Singleton platform instance
+ */
+const platform = new Platform();
+
+/**
+ * Utility functions using the singleton
+ */
+const platformUtils = {
+  // Platform checks
+  isWindows: () => platform.isWindows(),
+  isMacOS: () => platform.isMacOS(),
+  isLinux: () => platform.isLinux(),
+  isUnix: () => platform.isUnix(),
+  isCI: () => platform.isCI(),
+
+  // Path utilities
+  normalizePath: (path) => platform.normalizePath(path),
+  resolveHome: (path) => platform.resolveHome(path),
+  getAbsolutePath: (path, relativeTo) => platform.getAbsolutePath(path, relativeTo),
+  isSafePath: (path, basePath) => platform.isSafePath(path, basePath),
+
+  // System utilities
+  getShellInfo: () => platform.getShellInfo(),
+  getDiskSpace: (path) => platform.getDiskSpace(path),
+  isWritable: (path) => platform.isWritable(path),
+
+  // Executable utilities
+  findExecutable: (name) => platform.findExecutable(name),
+  hasCommand: (command) => platform.hasCommand(command),
+
+  // Directory utilities
+  getConfigDir: (appName) => platform.getConfigDir(appName),
+  getCacheDir: (appName) => platform.getCacheDir(appName),
+  getTempFilePath: (prefix, extension) => platform.getTempFilePath(prefix, extension),
+
+  // Environment utilities
+  getEnvVar: (name, defaultValue, options) => platform.getEnvVar(name, defaultValue, options),
+
+  // Content utilities
+  getLineEnding: () => platform.getLineEnding(),
+  convertFileContent: (content, targetPlatform) => platform.convertFileContent(content, targetPlatform),
+
+  // Debug utilities
+  getSummary: () => platform.getSummary(),
+
+  // Access to Platform class
+  Platform
+};
+
+module.exports = platformUtils;

package/src/utils/retry.js

@@ -0,0 +1,358 @@
+/**
+ * Retry utility with exponential backoff logic
+ * Provides resilient operation patterns for network and file system operations
+ */
+
+const { ErrorFactory } = require('./errors');
+
+/**
+ * Default retry configuration
+ */
+const DEFAULT_RETRY_CONFIG = {
+  maxAttempts: 3,
+  baseDelay: 1000,        // 1 second base delay
+  maxDelay: 30000,        // 30 seconds max delay
+  backoffFactor: 2,       // Exponential factor
+  jitter: true,           // Add randomness to prevent thundering herd
+  jitterFactor: 0.1,      // 10% jitter
+  retryCondition: null,   // Function to determine if error is retryable
+  onRetry: null           // Callback function called before each retry
+};
+
+/**
+ * Retry an async operation with exponential backoff
+ */
+async function retry(operation, options = {}) {
+  const config = { ...DEFAULT_RETRY_CONFIG, ...options };
+
+  let lastError;
+  let attempt = 0;
+
+  while (attempt < config.maxAttempts) {
+    attempt++;
+
+    try {
+      const result = await operation(attempt);
+      return result;
+    } catch (error) {
+      lastError = error;
+
+      // Check if we should retry this error
+      if (!shouldRetry(error, config.retryCondition, attempt, config.maxAttempts)) {
+        throw error;
+      }
+
+      // Don't delay after the last attempt
+      if (attempt >= config.maxAttempts) {
+        break;
+      }
+
+      // Calculate delay with exponential backoff and jitter
+      const delay = calculateDelay(attempt, config);
+
+      // Call retry callback if provided
+      if (config.onRetry) {
+        await config.onRetry(error, attempt, delay);
+      }
+
+      // Wait before next attempt
+      await sleep(delay);
+    }
+  }
+
+  // All attempts exhausted
+  throw ErrorFactory.fromCaught(lastError, `Failed after ${config.maxAttempts} attempts`);
+}
+
+/**
+ * Determine if an error should trigger a retry
+ */
+function shouldRetry(error, retryCondition, attempt, maxAttempts) {
+  // Don't retry if we've exhausted attempts
+  if (attempt >= maxAttempts) {
+    return false;
+  }
+
+  // Use custom retry condition if provided
+  if (retryCondition) {
+    return retryCondition(error, attempt);
+  }
+
+  // Default retry conditions
+  if (error.isRecoverable && error.isRecoverable()) {
+    return true;
+  }
+
+  // Network and GitHub API errors are generally retryable
+  const retryableTypes = ['NetworkError', 'GitHubAPIError'];
+  if (retryableTypes.includes(error.constructor.name)) {
+    return true;
+  }
+
+  // Rate limit errors should be retried
+  if (error.code === 'GITHUB_RATE_LIMIT' || error.code === 'NETWORK_TIMEOUT') {
+    return true;
+  }
+
+  // Server errors (5xx) should be retried
+  if (error.status >= 500 && error.status < 600) {
+    return true;
+  }
+
+  // ECONNRESET, ETIMEDOUT, ENOTFOUND are typically temporary
+  const retryableCodes = ['ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'ECONNREFUSED'];
+  if (error.code && retryableCodes.includes(error.code)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Calculate delay with exponential backoff and jitter
+ */
+function calculateDelay(attempt, config) {
+  // Base exponential backoff: baseDelay * (backoffFactor ^ (attempt - 1))
+  let delay = config.baseDelay * Math.pow(config.backoffFactor, attempt - 1);
+
+  // Cap at max delay
+  delay = Math.min(delay, config.maxDelay);
+
+  // Add jitter to prevent thundering herd
+  if (config.jitter) {
+    const jitterRange = delay * config.jitterFactor;
+    const jitterOffset = (Math.random() - 0.5) * 2 * jitterRange;
+    delay = Math.max(0, delay + jitterOffset);
+  }
+
+  return Math.floor(delay);
+}
+
+/**
+ * Sleep for specified milliseconds
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Retry wrapper for common operations
+ */
+class RetryWrapper {
+  constructor(config = {}) {
+    this.config = { ...DEFAULT_RETRY_CONFIG, ...config };
+  }
+
+  /**
+   * Retry an HTTP fetch operation
+   */
+  async fetch(url, options = {}) {
+    return retry(async (_attempt) => {
+      const response = await fetch(url, {
+        ...options,
+        headers: {
+          'User-Agent': '@claude-code/setup-installer',
+          ...options.headers
+        }
+      });
+
+      // Check for HTTP errors
+      if (!response.ok) {
+        const error = new Error(`HTTP ${response.status}: ${response.statusText}`);
+        error.status = response.status;
+        error.response = response;
+        throw error;
+      }
+
+      return response;
+    }, {
+      ...this.config,
+      retryCondition: (error, _attempt) => {
+        // Retry on network errors and 5xx server errors
+        return error.status >= 500 || !error.status;
+      },
+      onRetry: (error, attempt, delay) => {
+        if (this.config.logger) {
+          this.config.logger.warn(
+            `HTTP request failed (attempt ${attempt}), retrying in ${delay}ms: ${error.message}`,
+            { url, attempt, delay }
+          );
+        }
+      }
+    });
+  }
+
+  /**
+   * Retry a file system operation
+   */
+  async fileOperation(operation, operationName = 'file operation') {
+    return retry(operation, {
+      ...this.config,
+      retryCondition: (error, _attempt) => {
+        // Retry on temporary file system errors
+        const retryableCodes = ['EMFILE', 'ENFILE', 'EAGAIN', 'EBUSY'];
+        return error.code && retryableCodes.includes(error.code);
+      },
+      onRetry: (error, attempt, delay) => {
+        if (this.config.logger) {
+          this.config.logger.warn(
+            `${operationName} failed (attempt ${attempt}), retrying in ${delay}ms: ${error.message}`,
+            { operation: operationName, attempt, delay }
+          );
+        }
+      }
+    });
+  }
+
+  /**
+   * Retry with custom configuration
+   */
+  async withConfig(operation, customConfig) {
+    const mergedConfig = { ...this.config, ...customConfig };
+    return retry(operation, mergedConfig);
+  }
+}
+
+/**
+ * Pre-configured retry wrappers for common scenarios
+ */
+const retryPresets = {
+  /**
+   * GitHub API operations with rate limit handling
+   */
+  github: new RetryWrapper({
+    maxAttempts: 5,
+    baseDelay: 2000,
+    maxDelay: 60000,
+    retryCondition: (error, _attempt) => {
+      // Always retry rate limits with longer delays
+      if (error.code === 'GITHUB_RATE_LIMIT') {
+        return true;
+      }
+      // Retry server errors and network issues
+      return error.status >= 500 || !error.status;
+    }
+  }),
+
+  /**
+   * Network operations with fast retry
+   */
+  network: new RetryWrapper({
+    maxAttempts: 3,
+    baseDelay: 500,
+    maxDelay: 5000,
+    retryCondition: (error, _attempt) => {
+      const networkCodes = ['ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'ECONNREFUSED'];
+      return error.code && networkCodes.includes(error.code);
+    }
+  }),
+
+  /**
+   * File system operations with quick retry
+   */
+  filesystem: new RetryWrapper({
+    maxAttempts: 3,
+    baseDelay: 100,
+    maxDelay: 1000,
+    jitterFactor: 0.2,
+    retryCondition: (error, _attempt) => {
+      const fsCodes = ['EMFILE', 'ENFILE', 'EAGAIN', 'EBUSY'];
+      return error.code && fsCodes.includes(error.code);
+    }
+  })
+};
+
+/**
+ * Circuit breaker pattern for failing operations
+ */
+class CircuitBreaker {
+  constructor(options = {}) {
+    this.failureThreshold = options.failureThreshold || 5;
+    this.resetTimeout = options.resetTimeout || 30000;
+    this.monitoringPeriod = options.monitoringPeriod || 60000;
+
+    this.state = 'CLOSED'; // CLOSED, OPEN, HALF_OPEN
+    this.failures = 0;
+    this.lastFailureTime = null;
+    this.successCount = 0;
+  }
+
+  /**
+   * Execute operation through circuit breaker
+   */
+  async execute(operation) {
+    if (this.state === 'OPEN') {
+      if (Date.now() - this.lastFailureTime > this.resetTimeout) {
+        this.state = 'HALF_OPEN';
+        this.successCount = 0;
+      } else {
+        throw ErrorFactory.network('Circuit breaker is OPEN - too many failures');
+      }
+    }
+
+    try {
+      const result = await operation();
+
+      if (this.state === 'HALF_OPEN') {
+        this.successCount++;
+        if (this.successCount >= 3) {
+          this.reset();
+        }
+      } else {
+        this.failures = 0;
+      }
+
+      return result;
+    } catch (error) {
+      this.recordFailure();
+      throw error;
+    }
+  }
+
+  /**
+   * Record a failure and potentially open the circuit
+   */
+  recordFailure() {
+    this.failures++;
+    this.lastFailureTime = Date.now();
+
+    if (this.failures >= this.failureThreshold) {
+      this.state = 'OPEN';
+    } else if (this.state === 'HALF_OPEN') {
+      this.state = 'OPEN';
+    }
+  }
+
+  /**
+   * Reset circuit breaker to closed state
+   */
+  reset() {
+    this.state = 'CLOSED';
+    this.failures = 0;
+    this.lastFailureTime = null;
+    this.successCount = 0;
+  }
+
+  /**
+   * Get current circuit breaker status
+   */
+  getStatus() {
+    return {
+      state: this.state,
+      failures: this.failures,
+      lastFailureTime: this.lastFailureTime,
+      successCount: this.successCount
+    };
+  }
+}
+
+module.exports = {
+  retry,
+  RetryWrapper,
+  CircuitBreaker,
+  retryPresets,
+  calculateDelay,
+  shouldRetry,
+  sleep,
+  DEFAULT_RETRY_CONFIG
+};

package/templates/settings.local.json

@@ -0,0 +1 @@
+{\n  \"observability\": {\n    \"server_url\": \"http://localhost:3001\",\n    \"enabled\": true,\n    \"auto_start\": false\n  },\n  \"hooks\": {\n    \"enabled\": true,\n    \"python_path\": \"python3\",\n    \"uv_path\": \"uv\",\n    \"timeout\": 30\n  },\n  \"agents\": {\n    \"max_concurrent\": 10,\n    \"timeout\": 300,\n    \"retry_attempts\": 3\n  },\n  \"communication\": {\n    \"message_retention_hours\": 24,\n    \"broadcast_enabled\": true\n  },\n  \"development\": {\n    \"verbose_logging\": false,\n    \"debug_mode\": false\n  }\n}