aios-core 1.0.0

package/src/installer/dependency-installer.js

@@ -0,0 +1,335 @@
+/**
+ * Dependency Installer Module
+ *
+ * Story 1.7: Dependency Installation
+ * Handles automatic installation of npm dependencies with package manager detection,
+ * retry logic, and offline mode support.
+ *
+ * @module installer/dependency-installer
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const ora = require('ora');
+
+/**
+ * Allowed package managers (Security: Command injection prevention)
+ * @constant {string[]}
+ */
+const ALLOWED_PACKAGE_MANAGERS = ['npm', 'yarn', 'pnpm', 'bun'];
+
+/**
+ * Package manager lock file mapping
+ * Priority order: bun > pnpm > yarn > npm
+ * @constant {Object}
+ */
+const LOCK_FILES = {
+  'bun.lockb': 'bun',
+  'pnpm-lock.yaml': 'pnpm',
+  'yarn.lock': 'yarn',
+  'package-lock.json': 'npm',
+};
+
+/**
+ * Detect package manager from lock files
+ *
+ * @param {string} [projectPath=process.cwd()] - Project directory path
+ * @returns {string} Detected package manager ('npm', 'yarn', 'pnpm', 'bun')
+ *
+ * @example
+ * const pm = detectPackageManager();
+ * console.log(pm); // 'npm'
+ */
+function detectPackageManager(projectPath = process.cwd()) {
+  // Check for lock files in priority order
+  for (const [lockFile, packageManager] of Object.entries(LOCK_FILES)) {
+    const lockPath = path.join(projectPath, lockFile);
+    if (fs.existsSync(lockPath)) {
+      return packageManager;
+    }
+  }
+
+  // Fallback to npm
+  return 'npm';
+}
+
+/**
+ * Validate package manager against whitelist (Security check)
+ *
+ * @param {string} packageManager - Package manager to validate
+ * @throws {Error} If package manager is not in whitelist
+ *
+ * @example
+ * validatePackageManager('npm'); // OK
+ * validatePackageManager('malicious'); // Throws Error
+ */
+function validatePackageManager(packageManager) {
+  if (!ALLOWED_PACKAGE_MANAGERS.includes(packageManager)) {
+    throw new Error(
+      `Invalid package manager: ${packageManager}. ` +
+      `Allowed: ${ALLOWED_PACKAGE_MANAGERS.join(', ')}`,
+    );
+  }
+}
+
+/**
+ * Check if node_modules exists and has contents (Offline mode detection)
+ *
+ * @param {string} [projectPath=process.cwd()] - Project directory path
+ * @returns {boolean} True if node_modules exists with packages
+ */
+function hasExistingDependencies(projectPath = process.cwd()) {
+  const nodeModulesPath = path.join(projectPath, 'node_modules');
+
+  if (!fs.existsSync(nodeModulesPath)) {
+    return false;
+  }
+
+  try {
+    const contents = fs.readdirSync(nodeModulesPath);
+    // node_modules exists and has more than just .bin or .cache
+    return contents.length > 0 && contents.some(item => !item.startsWith('.'));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Execute package manager install command
+ *
+ * @param {string} packageManager - Package manager to use
+ * @param {string} [projectPath=process.cwd()] - Project directory path
+ * @returns {Promise<Object>} Result object with success status
+ *
+ * @example
+ * const result = await executeInstall('npm');
+ * if (result.success) {
+ *   console.log('Dependencies installed!');
+ * }
+ */
+async function executeInstall(packageManager, projectPath = process.cwd()) {
+  return new Promise((resolve) => {
+    // Security: Use args array to prevent shell injection
+    const args = ['install'];
+
+    // Windows requires shell: true because npm is actually npm.cmd
+    // On Unix, we can use shell: false for better security
+    const isWindows = process.platform === 'win32';
+
+    // Spawn process
+    const child = spawn(packageManager, args, {
+      cwd: projectPath,
+      stdio: 'inherit', // Show real-time output to user
+      shell: isWindows, // Windows needs shell to find npm.cmd, Unix doesn't
+    });
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve({ success: true, exitCode: 0 });
+      } else {
+        resolve({
+          success: false,
+          exitCode: code,
+          error: `${packageManager} install exited with code ${code}`,
+        });
+      }
+    });
+
+    child.on('error', (error) => {
+      resolve({
+        success: false,
+        error: error.message,
+      });
+    });
+  });
+}
+
+/**
+ * Categorize error type for better user guidance
+ *
+ * @param {Error|string} error - Error object or message
+ * @returns {Object} Error category and suggested solution
+ */
+function categorizeError(error) {
+  const errorMsg = typeof error === 'string' ? error : error.message;
+
+  // Network errors
+  if (errorMsg.includes('ENOTFOUND') || errorMsg.includes('ETIMEDOUT') ||
+      errorMsg.includes('EAI_AGAIN') || errorMsg.includes('fetch failed')) {
+    return {
+      category: 'network',
+      message: 'Network connection failed',
+      solution: 'Check your internet connection and try again',
+    };
+  }
+
+  // Permission errors
+  if (errorMsg.includes('EACCES') || errorMsg.includes('EPERM') ||
+      errorMsg.includes('permission denied')) {
+    return {
+      category: 'permission',
+      message: 'Permission denied',
+      solution: 'Try running with elevated permissions or check folder ownership',
+    };
+  }
+
+  // Disk space errors
+  if (errorMsg.includes('ENOSPC') || errorMsg.includes('no space')) {
+    return {
+      category: 'diskspace',
+      message: 'Insufficient disk space',
+      solution: 'Free up disk space and try again',
+    };
+  }
+
+  // Generic error
+  return {
+    category: 'unknown',
+    message: errorMsg,
+    solution: 'Check the error message above for details',
+  };
+}
+
+/**
+ * Sleep utility for retry backoff
+ *
+ * @param {number} ms - Milliseconds to sleep
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Install dependencies with retry logic
+ *
+ * @param {string} packageManager - Package manager to use
+ * @param {string} projectPath - Project directory path
+ * @param {number} maxRetries - Maximum retry attempts
+ * @param {number} attempt - Current attempt number (internal)
+ * @returns {Promise<Object>} Result object
+ */
+async function installWithRetry(packageManager, projectPath, maxRetries = 3, attempt = 1) {
+  const result = await executeInstall(packageManager, projectPath);
+
+  if (result.success) {
+    return result;
+  }
+
+  // Max retries reached
+  if (attempt >= maxRetries) {
+    return result;
+  }
+
+  // Exponential backoff: 2s, 4s, 8s
+  const delay = Math.pow(2, attempt) * 1000;
+  console.log(`\n⏳ Retrying in ${delay / 1000}s... (Attempt ${attempt + 1}/${maxRetries})`);
+  await sleep(delay);
+
+  return installWithRetry(packageManager, projectPath, maxRetries, attempt + 1);
+}
+
+/**
+ * Main installation function with all features
+ *
+ * @param {Object} options - Installation options
+ * @param {string} [options.packageManager] - Package manager override
+ * @param {string} [options.projectPath=process.cwd()] - Project directory
+ * @param {boolean} [options.skipRetry=false] - Skip retry logic
+ * @param {number} [options.maxRetries=3] - Maximum retry attempts
+ * @returns {Promise<Object>} Installation result
+ *
+ * @example
+ * const result = await installDependencies({
+ *   packageManager: 'npm',
+ *   projectPath: '/path/to/project'
+ * });
+ */
+async function installDependencies(options = {}) {
+  const {
+    packageManager: pmOverride,
+    projectPath = process.cwd(),
+    skipRetry = false,
+    maxRetries = 3,
+  } = options;
+
+  let spinner;
+
+  try {
+    // Detect or use provided package manager
+    const packageManager = pmOverride || detectPackageManager(projectPath);
+
+    // Security: Validate package manager
+    validatePackageManager(packageManager);
+
+    // Check for offline mode (AC6)
+    if (hasExistingDependencies(projectPath)) {
+      console.log('\n📦 Existing dependencies found (offline mode)');
+      console.log('   Skipping installation - using cached node_modules');
+      return {
+        success: true,
+        offlineMode: true,
+        packageManager,
+      };
+    }
+
+    // Start installation
+    spinner = ora(`Installing dependencies with ${packageManager}...`).start();
+
+    // Execute with or without retry
+    let result;
+    if (skipRetry) {
+      result = await executeInstall(packageManager, projectPath);
+    } else {
+      result = await installWithRetry(packageManager, projectPath, maxRetries);
+    }
+
+    if (result.success) {
+      spinner.succeed(`Dependencies installed with ${packageManager}!`);
+      return {
+        success: true,
+        packageManager,
+      };
+    } else {
+      spinner.fail('Installation failed');
+
+      // Categorize error for user guidance
+      const errorInfo = categorizeError(result.error);
+
+      return {
+        success: false,
+        packageManager,
+        error: result.error,
+        errorCategory: errorInfo.category,
+        errorMessage: errorInfo.message,
+        solution: errorInfo.solution,
+      };
+    }
+  } catch (error) {
+    if (spinner) {
+      spinner.fail('Installation failed');
+    }
+
+    const errorInfo = categorizeError(error);
+
+    return {
+      success: false,
+      error: error.message,
+      errorCategory: errorInfo.category,
+      errorMessage: errorInfo.message,
+      solution: errorInfo.solution,
+    };
+  }
+}
+
+module.exports = {
+  detectPackageManager,
+  validatePackageManager,
+  hasExistingDependencies,
+  installDependencies,
+  // Export for testing
+  executeInstall,
+  categorizeError,
+  installWithRetry,
+};

package/src/installer/file-hasher.js

@@ -0,0 +1,137 @@
+/**
+ * File Hasher Utility
+ * Cross-platform file hashing with line ending normalization
+ *
+ * @module src/installer/file-hasher
+ * @story 6.18 - Dynamic Manifest & Brownfield Upgrade System
+ */
+
+const crypto = require('crypto');
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * List of file extensions that should be treated as binary (not normalized)
+ */
+const BINARY_EXTENSIONS = [
+  '.png', '.jpg', '.jpeg', '.gif', '.ico', '.webp', '.svg',
+  '.pdf', '.zip', '.tar', '.gz', '.7z',
+  '.woff', '.woff2', '.ttf', '.eot',
+  '.mp3', '.mp4', '.wav', '.avi',
+  '.exe', '.dll', '.so', '.dylib',
+];
+
+/**
+ * Check if a file should be treated as binary based on extension
+ * @param {string} filePath - Path to the file
+ * @returns {boolean} - True if file is binary
+ */
+function isBinaryFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  return BINARY_EXTENSIONS.includes(ext);
+}
+
+/**
+ * Normalize line endings from CRLF to LF for consistent cross-platform hashing
+ * @param {string} content - File content as string
+ * @returns {string} - Normalized content with LF line endings
+ */
+function normalizeLineEndings(content) {
+  return content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+
+/**
+ * Remove UTF-8 BOM if present
+ * @param {string} content - File content
+ * @returns {string} - Content without BOM
+ */
+function removeBOM(content) {
+  if (content.charCodeAt(0) === 0xFEFF) {
+    return content.slice(1);
+  }
+  return content;
+}
+
+/**
+ * Compute SHA256 hash of a file with cross-platform normalization
+ * Text files have line endings normalized for consistent hashes across OS
+ * Binary files are hashed as-is
+ *
+ * @param {string} filePath - Absolute path to the file
+ * @returns {string} - SHA256 hash as hex string
+ * @throws {Error} - If file cannot be read
+ */
+function hashFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+
+  const stats = fs.statSync(filePath);
+  if (stats.isDirectory()) {
+    throw new Error(`Cannot hash directory: ${filePath}`);
+  }
+
+  let content;
+
+  if (isBinaryFile(filePath)) {
+    // Binary files: hash raw bytes
+    content = fs.readFileSync(filePath);
+  } else {
+    // Text files: normalize line endings and remove BOM
+    const rawContent = fs.readFileSync(filePath, 'utf8');
+    const withoutBOM = removeBOM(rawContent);
+    const normalized = normalizeLineEndings(withoutBOM);
+    content = Buffer.from(normalized, 'utf8');
+  }
+
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Compute SHA256 hash of a string (for manifest integrity)
+ * @param {string} content - String content to hash
+ * @returns {string} - SHA256 hash as hex string
+ */
+function hashString(content) {
+  return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+}
+
+/**
+ * Compare two hashes for equality
+ * @param {string} hash1 - First hash
+ * @param {string} hash2 - Second hash
+ * @returns {boolean} - True if hashes match
+ */
+function hashesMatch(hash1, hash2) {
+  if (!hash1 || !hash2) return false;
+  return hash1.toLowerCase() === hash2.toLowerCase();
+}
+
+/**
+ * Get file metadata including hash
+ * @param {string} filePath - Absolute path to the file
+ * @param {string} basePath - Base path for relative path calculation
+ * @returns {Object} - File metadata object
+ */
+function getFileMetadata(filePath, basePath) {
+  const stats = fs.statSync(filePath);
+  const relativePath = path.relative(basePath, filePath).replace(/\\/g, '/');
+
+  return {
+    path: relativePath,
+    hash: `sha256:${hashFile(filePath)}`,
+    size: stats.size,
+    isBinary: isBinaryFile(filePath),
+  };
+}
+
+module.exports = {
+  hashFile,
+  hashString,
+  hashesMatch,
+  getFileMetadata,
+  isBinaryFile,
+  normalizeLineEndings,
+  removeBOM,
+  BINARY_EXTENSIONS,
+};

package/src/utils/aios-colors.js

@@ -0,0 +1,234 @@
+/**
+ * AIOS Color Palette v2.1
+ * 
+ * Brand-inspired color system for CLI tools and terminal output.
+ * Colors derived from AIOS logo gradient (magenta → orange → purple → blue)
+ * Primary purple references ClickUp brand color.
+ * 
+ * @see docs/standards/AIOS-COLOR-PALETTE-V2.1.md
+ * @module aios-colors
+ */
+
+const chalk = require('chalk');
+
+/**
+ * AIOS Brand Color Palette
+ * All colors are WCAG AA compliant on dark terminals
+ */
+const colors = {
+  // ============================================
+  // CORE BRAND COLORS
+  // ============================================
+  
+  /**
+   * Primary brand color - ClickUp-inspired purple
+   * Usage: Main questions, headers, CTAs, primary actions
+   */
+  primary: chalk.hex('#8B5CF6'),
+  
+  /**
+   * Secondary brand color - Magenta accent from logo gradient
+   * Usage: Important highlights, special emphasis, key information
+   */
+  secondary: chalk.hex('#EC4899'),
+  
+  /**
+   * Tertiary brand color - Blue accent from logo gradient
+   * Usage: Secondary actions, links, complementary elements
+   */
+  tertiary: chalk.hex('#3B82F6'),
+  
+  // ============================================
+  // FUNCTIONAL COLORS
+  // ============================================
+  
+  /**
+   * Success state color
+   * Usage: Checkmarks, completed steps, success messages
+   */
+  success: chalk.hex('#10B981'),
+  
+  /**
+   * Warning state color - Orange from logo gradient
+   * Usage: Warnings, confirmations, caution states
+   */
+  warning: chalk.hex('#F59E0B'),
+  
+  /**
+   * Error state color
+   * Usage: Errors, critical alerts, validation failures
+   */
+  error: chalk.hex('#EF4444'),
+  
+  /**
+   * Info state color - Cyan-blue from logo gradient
+   * Usage: Info messages, tips, helper text, additional context
+   */
+  info: chalk.hex('#06B6D4'),
+  
+  // ============================================
+  // NEUTRAL COLORS
+  // ============================================
+  
+  /**
+   * Muted text color
+   * Usage: Subtle text, disabled states, secondary content
+   */
+  muted: chalk.hex('#94A3B8'),
+  
+  /**
+   * Dim text color
+   * Usage: Secondary text, muted content, less important info
+   */
+  dim: chalk.hex('#64748B'),
+  
+  // ============================================
+  // GRADIENT SYSTEM
+  // ============================================
+  
+  /**
+   * Brand gradient colors for animations and special effects
+   * Matches AIOS logo gradient: magenta → purple → blue
+   */
+  gradient: {
+    /** Gradient start - Magenta (logo top) */
+    start: chalk.hex('#EC4899'),
+    
+    /** Gradient middle - Purple (brand) */
+    middle: chalk.hex('#8B5CF6'),
+    
+    /** Gradient end - Blue (logo bottom) */
+    end: chalk.hex('#3B82F6'),
+  },
+  
+  // ============================================
+  // SEMANTIC SHORTCUTS
+  // ============================================
+  
+  /**
+   * Highlighted text - Bold magenta for key information
+   */
+  highlight: chalk.hex('#EC4899').bold,
+  
+  /**
+   * Primary branding - Bold purple for AIOS brand moments
+   */
+  brandPrimary: chalk.hex('#8B5CF6').bold,
+  
+  /**
+   * Secondary branding - Cyan for supporting brand elements
+   */
+  brandSecondary: chalk.hex('#06B6D4'),
+};
+
+/**
+ * Pre-formatted status indicators with color and symbols
+ */
+const status = {
+  /** Success indicator: ✓ (green) */
+  success: (text) => `${colors.success('✓')} ${text}`,
+  
+  /** Error indicator: ✗ (red) */
+  error: (text) => `${colors.error('✗')} ${text}`,
+  
+  /** Warning indicator: ⚠️ (orange) */
+  warning: (text) => `${colors.warning('⚠️')} ${text}`,
+  
+  /** Info indicator: ℹ (cyan) */
+  info: (text) => `${colors.info('ℹ')} ${text}`,
+  
+  /** Loading indicator: ⏳ (cyan) */
+  loading: (text) => `${colors.info('⏳')} ${text}`,
+  
+  /** Skipped indicator: ⊘ (muted) */
+  skipped: (text) => `${colors.muted('⊘')} ${text}`,
+  
+  /** Tip indicator: 💡 (info) */
+  tip: (text) => `${colors.info('💡')} ${text}`,
+  
+  /** Party indicator: 🎉 (brand primary) */
+  celebrate: (text) => `${colors.brandPrimary('🎉')} ${text}`,
+};
+
+/**
+ * Formatted heading helpers
+ */
+const headings = {
+  /** H1 - Brand primary, bold, large spacing */
+  h1: (text) => `\n${colors.brandPrimary(text)}\n`,
+  
+  /** H2 - Primary color, bold */
+  h2: (text) => `\n${colors.primary.bold(text)}\n`,
+  
+  /** H3 - Primary color */
+  h3: (text) => colors.primary(text),
+  
+  /** Section divider */
+  divider: () => colors.dim('─'.repeat(50)),
+};
+
+/**
+ * Formatted list helpers
+ */
+const lists = {
+  /** Bullet point (primary) */
+  bullet: (text) => `${colors.primary('•')} ${text}`,
+  
+  /** Numbered item (primary) */
+  numbered: (num, text) => `${colors.primary(`${num}.`)} ${text}`,
+  
+  /** Checkbox unchecked */
+  checkbox: (text, checked = false) => {
+    const icon = checked ? colors.success('☑') : colors.muted('☐');
+    return `${icon} ${text}`;
+  },
+};
+
+/**
+ * Example usage for documentation
+ */
+const examples = {
+  welcome: () => {
+    console.log(headings.h1('🎉 Welcome to AIOS v2.1 Installer!'));
+    console.log(colors.info('Let\'s configure your project in just a few steps...\n'));
+  },
+  
+  question: () => {
+    console.log(colors.primary('? Select your project type:'));
+    console.log(lists.bullet('Greenfield (new project)'));
+    console.log(lists.bullet('Brownfield (existing project)'));
+  },
+  
+  progress: () => {
+    console.log(status.loading('Installing dependencies...'));
+    console.log(status.success('Dependencies installed'));
+    console.log(status.loading('Configuring environment...'));
+  },
+  
+  feedback: () => {
+    console.log(status.success('Configuration complete!'));
+    console.log(status.warning('Existing .env found. Overwrite?'));
+    console.log(status.error('Invalid path provided'));
+    console.log(status.tip('You can change this later in settings'));
+  },
+  
+  complete: () => {
+    console.log('\n' + headings.divider());
+    console.log(status.celebrate('Installation Complete!'));
+    console.log(colors.info('Your AIOS project is ready to use.'));
+    console.log(headings.divider() + '\n');
+  },
+};
+
+// Export all utilities
+module.exports = {
+  colors,
+  status,
+  headings,
+  lists,
+  examples,
+};
+
+// Also export as default for ESM compatibility
+module.exports.default = module.exports;
+