claude-comms 1.0.1 → 1.0.2

package/src/orchestrator/main.js

@@ -0,0 +1,267 @@
+/**
+ * Claude Code Setup Installer - Main Module
+ *
+ * This module orchestrates the complete installation flow:
+ * 1. Validates target directory and dependencies
+ * 2. Fetches latest setup files from GitHub
+ * 3. Installs .claude directory and CLAUDE.md
+ * 4. Configures local settings
+ * 5. Provides post-installation guidance
+ */
+
+const path = require('path');
+const fs = require('fs-extra');
+const ora = require('ora');
+
+// Import core modules (these will be implemented in WP02-06)
+const logger = require('./utils/logger');
+const { InstallationError } = require('./utils/errors');
+const fetcher = require('./fetcher/github');
+const fileWriter = require('./installer/file-writer');
+const dependencyChecker = require('./installer/dependency-check');
+const prompts = require('./cli/prompts');
+
+/**
+ * Main installation function
+ * @param {Object} options - Installation options
+ * @param {string} options.targetDir - Target directory for installation
+ * @param {string} options.gitRef - Git reference (branch/tag/commit) to install
+ * @param {boolean} options.force - Force overwrite existing files
+ * @param {boolean} options.checkPython - Whether to check Python/uv dependencies
+ * @param {boolean} options.dev - Development mode with verbose logging
+ * @param {boolean} options.verify - Verification mode (no changes)
+ * @param {boolean} options.dryRun - Dry run mode (show what would be done)
+ */
+async function install(options = {}) {
+  const {
+    targetDir = process.cwd(),
+    gitRef = 'main',
+    force = false,
+    checkPython = true,
+    dev = false,
+    verify = false,
+    dryRun = false
+  } = options;
+
+  // Configure logger for development mode
+  logger.configure({ verbose: dev, verify, dryRun });
+
+  try {
+    logger.info('Starting Claude Code installation...');
+
+    // Phase 1: Pre-installation validation
+    await validateEnvironment(targetDir, checkPython);
+
+    // Phase 2: Handle existing files
+    await handleExistingFiles(targetDir, force, verify, dryRun);
+
+    // Phase 3: Fetch setup files from GitHub
+    const setupFiles = await fetchSetupFiles(gitRef);
+
+    // Phase 4: Install files to target directory
+    await installFiles(setupFiles, targetDir, verify, dryRun);
+
+    // Phase 5: Post-installation configuration
+    await configureLocalSettings(targetDir, verify, dryRun);
+
+    // Phase 6: Verify installation
+    await verifyInstallation(targetDir);
+
+    logger.success('Installation completed successfully!');
+
+  } catch (error) {
+    logger.error('Installation failed:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Validate installation environment
+ */
+async function validateEnvironment(targetDir, checkPython) {
+  const spinner = ora('Validating environment...').start();
+
+  try {
+    // Check target directory exists and is writable
+    await fs.ensureDir(targetDir);
+    await fs.access(targetDir, fs.constants.W_OK);
+
+    // Check dependencies if requested
+    if (checkPython) {
+      await dependencyChecker.validatePythonEnvironment();
+    }
+
+    spinner.succeed('Environment validation complete');
+
+  } catch (error) {
+    spinner.fail('Environment validation failed');
+    throw new InstallationError(`Environment validation failed: ${error.message}`, 'ENV_VALIDATION_FAILED');
+  }
+}
+
+/**
+ * Handle existing .claude directory and CLAUDE.md
+ */
+async function handleExistingFiles(targetDir, force, verify, dryRun) {
+  const claudeDir = path.join(targetDir, '.claude');
+  const claudeMd = path.join(targetDir, 'CLAUDE.md');
+
+  const existingFiles = [];
+  if (await fs.pathExists(claudeDir)) existingFiles.push('.claude/');
+  if (await fs.pathExists(claudeMd)) existingFiles.push('CLAUDE.md');
+
+  if (existingFiles.length === 0) {
+    logger.info('No existing files found - proceeding with fresh installation');
+    return;
+  }
+
+  if (verify || dryRun) {
+    logger.info(`Found existing files: ${existingFiles.join(', ')}`);
+    return;
+  }
+
+  if (force) {
+    logger.info(`Force mode enabled - will overwrite: ${existingFiles.join(', ')}`);
+    return;
+  }
+
+  // Interactive prompt for handling existing files
+  const action = await prompts.handleExistingFiles(existingFiles);
+
+  switch (action) {
+  case 'backup':
+    await fileWriter.backupExistingFiles(targetDir, existingFiles);
+    break;
+  case 'skip':
+    logger.info('Skipping existing files');
+    break;
+  case 'cancel':
+    throw new InstallationError('Installation cancelled by user', 'USER_CANCELLED');
+  default:
+    // Overwrite - no action needed
+    break;
+  }
+}
+
+/**
+ * Fetch setup files from GitHub repository
+ */
+async function fetchSetupFiles(gitRef) {
+  const spinner = ora(`Fetching setup files from GitHub (${gitRef})...`).start();
+
+  try {
+    const files = await fetcher.fetchClaudeSetup(gitRef);
+
+    spinner.succeed(`Fetched ${Object.keys(files).length} files from GitHub`);
+    logger.debug('Fetched files:', Object.keys(files));
+
+    return files;
+
+  } catch (error) {
+    spinner.fail('Failed to fetch setup files');
+    throw new InstallationError(`GitHub fetch failed: ${error.message}`, 'GITHUB_FETCH_FAILED');
+  }
+}
+
+/**
+ * Install files to target directory
+ */
+async function installFiles(setupFiles, targetDir, verify, dryRun) {
+  const spinner = ora('Installing files...').start();
+
+  try {
+    const stats = await fileWriter.writeSetupFiles(setupFiles, targetDir, { verify, dryRun });
+
+    if (verify || dryRun) {
+      spinner.succeed(`Would install ${stats.fileCount} files (${stats.totalSize} bytes)`);
+    } else {
+      spinner.succeed(`Installed ${stats.fileCount} files (${stats.totalSize} bytes)`);
+    }
+
+  } catch (error) {
+    spinner.fail('File installation failed');
+    throw new InstallationError(`File installation failed: ${error.message}`, 'FILE_INSTALL_FAILED');
+  }
+}
+
+/**
+ * Configure local settings file
+ */
+async function configureLocalSettings(targetDir, verify, dryRun) {
+  const spinner = ora('Configuring local settings...').start();
+
+  try {
+    const settingsPath = path.join(targetDir, '.claude', 'settings.local.json');
+
+    if (verify || dryRun) {
+      spinner.succeed('Would create settings.local.json');
+      return;
+    }
+
+    // Create basic local settings template
+    const defaultSettings = {
+      'observability': {
+        'server_url': 'http://localhost:3001',
+        'enabled': true
+      },
+      'hooks': {
+        'enabled': true,
+        'python_path': 'python3'
+      },
+      'agents': {
+        'max_concurrent': 10,
+        'timeout': 300
+      }
+    };
+
+    await fs.writeJson(settingsPath, defaultSettings, { spaces: 2 });
+
+    spinner.succeed('Local settings configured');
+
+  } catch (error) {
+    spinner.fail('Settings configuration failed');
+    throw new InstallationError(`Settings configuration failed: ${error.message}`, 'SETTINGS_CONFIG_FAILED');
+  }
+}
+
+/**
+ * Verify installation was successful
+ */
+async function verifyInstallation(targetDir) {
+  const spinner = ora('Verifying installation...').start();
+
+  try {
+    const claudeDir = path.join(targetDir, '.claude');
+    const claudeMd = path.join(targetDir, 'CLAUDE.md');
+    const settingsPath = path.join(claudeDir, 'settings.local.json');
+
+    // Check required files exist
+    const checks = [
+      { path: claudeDir, name: '.claude directory' },
+      { path: claudeMd, name: 'CLAUDE.md' },
+      { path: settingsPath, name: 'settings.local.json' }
+    ];
+
+    for (const check of checks) {
+      if (!(await fs.pathExists(check.path))) {
+        throw new Error(`Missing ${check.name}`);
+      }
+    }
+
+    spinner.succeed('Installation verification complete');
+
+  } catch (error) {
+    spinner.fail('Installation verification failed');
+    throw new InstallationError(`Installation verification failed: ${error.message}`, 'VERIFICATION_FAILED');
+  }
+}
+
+module.exports = {
+  install,
+  validateEnvironment,
+  handleExistingFiles,
+  fetchSetupFiles,
+  installFiles,
+  configureLocalSettings,
+  verifyInstallation
+};

package/src/orchestrator/mocks/index.js

@@ -0,0 +1,388 @@
+/**
+ * Mock Implementations for Team Integration - WP06
+ *
+ * Provides mock implementations that match the interface contracts
+ * for integration with WP03 (GitHub Fetcher) and WP04 (File Writer).
+ *
+ * These mocks allow the orchestrator to be tested independently
+ * while providing clear integration points for the real implementations.
+ */
+
+/**
+ * Mock Fetcher implementation matching FetcherAPI interface
+ * Will be replaced by IsabelMatrix's GitHub fetcher (WP03)
+ */
+class MockFetcher {
+  constructor(options = {}) {
+    this.mockData = options.mockData || this._getDefaultMockData();
+    this.simulateDelay = options.simulateDelay !== false;
+    this.shouldFail = options.shouldFail || false;
+  }
+
+  async fetchDirectory(path, _options = {}) {
+    if (this.simulateDelay) {
+      await this._delay(500);
+    }
+
+    if (this.shouldFail) {
+      throw new Error(`Mock fetcher: Failed to fetch directory ${path}`);
+    }
+
+    return this.mockData.directories[path] || {
+      path,
+      type: 'dir',
+      children: []
+    };
+  }
+
+  async fetchFile(path, _options = {}) {
+    if (this.simulateDelay) {
+      await this._delay(200);
+    }
+
+    if (this.shouldFail) {
+      throw new Error(`Mock fetcher: Failed to fetch file ${path}`);
+    }
+
+    return this.mockData.files[path] || {
+      path,
+      content: `# Mock content for ${path}`,
+      encoding: 'utf-8',
+      sha: 'mock-sha-' + Date.now()
+    };
+  }
+
+  async validateConnection() {
+    if (this.simulateDelay) {
+      await this._delay(100);
+    }
+    return !this.shouldFail;
+  }
+
+  _delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  _getDefaultMockData() {
+    return {
+      directories: {
+        '.claude': {
+          path: '.claude',
+          type: 'dir',
+          children: [
+            {
+              path: 'settings.json',
+              type: 'file',
+              content: JSON.stringify({
+                version: '1.0.0',
+                observability_server: 'http://localhost:4000',
+                hooks_enabled: true
+              }, null, 2),
+              encoding: 'utf-8'
+            },
+            {
+              path: 'agents',
+              type: 'dir',
+              children: [
+                {
+                  path: 'engineer.md',
+                  type: 'file',
+                  content: '# Engineer Agent\n\nImplementation specialist.',
+                  encoding: 'utf-8'
+                },
+                {
+                  path: 'architect.md',
+                  type: 'file',
+                  content: '# Architect Agent\n\nSystem design specialist.',
+                  encoding: 'utf-8'
+                }
+              ]
+            },
+            {
+              path: 'hooks',
+              type: 'dir',
+              children: [
+                {
+                  path: 'comms',
+                  type: 'dir',
+                  children: [
+                    {
+                      path: 'send_message.py',
+                      type: 'file',
+                      content: '#!/usr/bin/env python3\n# Team communication hook\nprint("Send message hook")',
+                      encoding: 'utf-8',
+                      permissions: 0o755
+                    },
+                    {
+                      path: 'get_unread_messages.py',
+                      type: 'file',
+                      content: '#!/usr/bin/env python3\n# Message retrieval hook\nprint("Get messages hook")',
+                      encoding: 'utf-8',
+                      permissions: 0o755
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      },
+      files: {
+        'CLAUDE.md': {
+          path: 'CLAUDE.md',
+          content: '# Claude Code Multi-Agent Setup\n\nThis project is configured for Claude multi-agent orchestration.\n\n## Features\n- Multi-agent team coordination\n- Observability and monitoring\n- Hook-based extensibility\n\n## Getting Started\nReview .claude/settings.local.json for configuration.',
+          encoding: 'utf-8',
+          sha: 'mock-claude-md-sha'
+        }
+      }
+    };
+  }
+}
+
+/**
+ * Mock Writer implementation matching WriterAPI interface
+ * Will be replaced by JackTensor's file writer (WP04)
+ */
+class MockWriter {
+  constructor(options = {}) {
+    this.simulateDelay = options.simulateDelay !== false;
+    this.shouldFail = options.shouldFail || false;
+    this.dryRun = options.dryRun || false;
+    this.writtenFiles = new Set();
+    this.backups = new Map();
+  }
+
+  async writeFile(filePath, content, options = {}) {
+    if (this.simulateDelay) {
+      await this._delay(100);
+    }
+
+    if (this.shouldFail) {
+      throw new Error(`Mock writer: Failed to write file ${filePath}`);
+    }
+
+    if (options.dryRun || this.dryRun) {
+      console.log(`[DRY RUN] Would write file: ${filePath}`);
+      return;
+    }
+
+    this.writtenFiles.add(filePath);
+    console.log(`[MOCK] Wrote file: ${filePath} (${content.length} bytes)`);
+  }
+
+  async writeDirectory(files, options = {}) {
+    if (this.simulateDelay) {
+      await this._delay(300);
+    }
+
+    if (this.shouldFail) {
+      throw new Error('Mock writer: Failed to write directory');
+    }
+
+    const result = {
+      written: [],
+      skipped: [],
+      backed_up: new Map(),
+      errors: []
+    };
+
+    for (const file of files) {
+      const targetPath = options.targetDir
+        ? require('path').join(options.targetDir, file.path)
+        : file.path;
+
+      if (options.dryRun || this.dryRun) {
+        console.log(`[DRY RUN] Would write: ${targetPath}`);
+        continue;
+      }
+
+      // Simulate backup if file exists and backup is enabled
+      if (options.backup && this.writtenFiles.has(targetPath)) {
+        const backupPath = `${targetPath}.backup-${Date.now()}`;
+        result.backed_up.set(targetPath, backupPath);
+        this.backups.set(targetPath, backupPath);
+      }
+
+      this.writtenFiles.add(targetPath);
+      result.written.push(targetPath);
+
+      console.log(`[MOCK] Wrote: ${targetPath} (${file.content?.length || 0} bytes)`);
+    }
+
+    return result;
+  }
+
+  async backup(filePath) {
+    if (this.simulateDelay) {
+      await this._delay(50);
+    }
+
+    const backupPath = `${filePath}.backup-${Date.now()}`;
+    this.backups.set(filePath, backupPath);
+
+    console.log(`[MOCK] Created backup: ${filePath} -> ${backupPath}`);
+    return backupPath;
+  }
+
+  async rollback(backupPath, originalPath) {
+    if (this.simulateDelay) {
+      await this._delay(100);
+    }
+
+    console.log(`[MOCK] Rolled back: ${backupPath} -> ${originalPath}`);
+    this.writtenFiles.delete(originalPath);
+  }
+
+  async removeFile(filePath) {
+    if (this.simulateDelay) {
+      await this._delay(50);
+    }
+
+    console.log(`[MOCK] Removed file: ${filePath}`);
+    this.writtenFiles.delete(filePath);
+  }
+
+  _delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+/**
+ * Mock Logger implementation
+ */
+class MockLogger {
+  constructor(options = {}) {
+    this.verbose = options.verbose || false;
+    this.prefix = options.prefix || '[MOCK]';
+  }
+
+  info(message, ...args) {
+    console.log(`${this.prefix} [INFO] ${message}`, ...args);
+  }
+
+  warn(message, ...args) {
+    console.warn(`${this.prefix} [WARN] ${message}`, ...args);
+  }
+
+  error(message, ...args) {
+    console.error(`${this.prefix} [ERROR] ${message}`, ...args);
+  }
+
+  debug(message, ...args) {
+    if (this.verbose) {
+      console.log(`${this.prefix} [DEBUG] ${message}`, ...args);
+    }
+  }
+
+  success(message, ...args) {
+    console.log(`${this.prefix} [SUCCESS] ${message}`, ...args);
+  }
+}
+
+/**
+ * Mock Validator implementation
+ */
+class MockValidator {
+  constructor(options = {}) {
+    this.shouldFail = options.shouldFail || false;
+    this.issues = options.issues || [];
+  }
+
+  async validateTargetDirectory(_targetDir) {
+    if (this.shouldFail) {
+      return {
+        code: 'E301',
+        message: 'Target directory is not writable',
+        severity: 'error'
+      };
+    }
+    return null;
+  }
+
+  async validatePythonEnvironment() {
+    if (this.shouldFail) {
+      return {
+        code: 'E302',
+        message: 'Python or uv not found',
+        severity: 'error'
+      };
+    }
+    return null;
+  }
+
+  async checkExistingFiles(_targetDir) {
+    // Return any pre-configured issues
+    return this.issues.find(issue => issue.type === 'existing_files') || null;
+  }
+
+  async validateNetworkAccess() {
+    if (this.shouldFail) {
+      return {
+        code: 'E101',
+        message: 'Cannot connect to GitHub',
+        severity: 'error'
+      };
+    }
+    return null;
+  }
+
+  async pathExists(_path) {
+    // Mock - assume paths exist unless configured otherwise
+    return true;
+  }
+}
+
+/**
+ * Factory function to create a complete set of mock dependencies
+ */
+function createMockDependencies(options = {}) {
+  return {
+    fetcher: new MockFetcher(options.fetcher),
+    writer: new MockWriter(options.writer),
+    logger: new MockLogger(options.logger),
+    validator: new MockValidator(options.validator)
+  };
+}
+
+/**
+ * Helper to create mock dependencies that simulate specific scenarios
+ */
+function createScenarioMocks(scenario) {
+  switch (scenario) {
+  case 'success':
+    return createMockDependencies();
+
+  case 'network_failure':
+    return createMockDependencies({
+      fetcher: { shouldFail: true },
+      validator: { shouldFail: true }
+    });
+
+  case 'write_failure':
+    return createMockDependencies({
+      writer: { shouldFail: true }
+    });
+
+  case 'validation_failure':
+    return createMockDependencies({
+      validator: { shouldFail: true }
+    });
+
+  case 'dry_run':
+    return createMockDependencies({
+      writer: { dryRun: true }
+    });
+
+  default:
+    return createMockDependencies();
+  }
+}
+
+module.exports = {
+  MockFetcher,
+  MockWriter,
+  MockLogger,
+  MockValidator,
+  createMockDependencies,
+  createScenarioMocks
+};