aios-core 2.1.0

package/packages/installer/src/config/templates/env-template.js

@@ -0,0 +1,127 @@
+/**
+ * .env Template Generator
+ * Story 1.6: Environment Configuration
+ *
+ * Generates .env file with secure defaults and helpful comments
+ *
+ * @module env-template
+ */
+
+/**
+ * Generate .env file content
+ *
+ * @param {Object} apiKeys - API keys provided by user
+ * @param {string} [apiKeys.openai] - OpenAI API key (optional)
+ * @param {string} [apiKeys.anthropic] - Anthropic API key (optional)
+ * @param {string} [apiKeys.clickup] - ClickUp API key (optional)
+ * @param {string} [apiKeys.github] - GitHub token (optional)
+ * @param {string} [apiKeys.exa] - Exa API key (optional)
+ * @returns {string} .env file content
+ */
+function generateEnvContent(apiKeys = {}) {
+  const content = `# AIOS Environment Configuration
+# Generated by AIOS Installer
+# DO NOT commit this file - it contains sensitive credentials
+
+# ============================================================================
+# AIOS Core Configuration
+# ============================================================================
+NODE_ENV=development
+AIOS_VERSION=2.1.0
+
+# ============================================================================
+# AI Providers (at least one recommended)
+# ============================================================================
+# OpenAI API Key - Get yours at: https://platform.openai.com/api-keys
+OPENAI_API_KEY=${apiKeys.openai || ''}
+
+# Anthropic API Key - Get yours at: https://console.anthropic.com/
+ANTHROPIC_API_KEY=${apiKeys.anthropic || ''}
+
+# ============================================================================
+# Optional Services
+# ============================================================================
+# ClickUp API Key - For task management integration
+# Get yours at: https://app.clickup.com/settings/apps
+CLICKUP_API_KEY=${apiKeys.clickup || ''}
+
+# GitHub Personal Access Token - For GitHub integration
+# Create at: https://github.com/settings/tokens
+GITHUB_TOKEN=${apiKeys.github || ''}
+
+# Exa API Key - For web search capabilities
+# Get yours at: https://exa.ai/
+EXA_API_KEY=${apiKeys.exa || ''}
+
+# ============================================================================
+# Database Configuration (if applicable)
+# ============================================================================
+# DATABASE_URL=postgresql://user:password@localhost:5432/dbname
+
+# ============================================================================
+# Custom Configuration
+# ============================================================================
+# Add your custom environment variables below
+`;
+
+  return content;
+}
+
+/**
+ * Generate .env.example file content (no sensitive data)
+ *
+ * @returns {string} .env.example file content
+ */
+function generateEnvExample() {
+  const content = `# AIOS Environment Configuration Template
+# Copy this file to .env and fill in your actual values
+# DO NOT commit .env with real credentials
+
+# ============================================================================
+# AIOS Core Configuration
+# ============================================================================
+NODE_ENV=development
+AIOS_VERSION=2.1.0
+
+# ============================================================================
+# AI Providers (at least one recommended)
+# ============================================================================
+# OpenAI API Key - Get yours at: https://platform.openai.com/api-keys
+OPENAI_API_KEY=
+
+# Anthropic API Key - Get yours at: https://console.anthropic.com/
+ANTHROPIC_API_KEY=
+
+# ============================================================================
+# Optional Services
+# ============================================================================
+# ClickUp API Key - For task management integration
+# Get yours at: https://app.clickup.com/settings/apps
+CLICKUP_API_KEY=
+
+# GitHub Personal Access Token - For GitHub integration
+# Create at: https://github.com/settings/tokens
+GITHUB_TOKEN=
+
+# Exa API Key - For web search capabilities
+# Get yours at: https://exa.ai/
+EXA_API_KEY=
+
+# ============================================================================
+# Database Configuration (if applicable)
+# ============================================================================
+# DATABASE_URL=postgresql://user:password@localhost:5432/dbname
+
+# ============================================================================
+# Custom Configuration
+# ============================================================================
+# Add your custom environment variables below
+`;
+
+  return content;
+}
+
+module.exports = {
+  generateEnvContent,
+  generateEnvExample,
+};

package/packages/installer/src/config/validation/config-validator.js

@@ -0,0 +1,243 @@
+/**
+ * Configuration Validation Module
+ * Story 1.6: Environment Configuration
+ *
+ * Validates .env and YAML configuration files
+ *
+ * @module config-validator
+ */
+
+const yaml = require('js-yaml');
+const path = require('path');
+
+/**
+ * Validate .env file format
+ *
+ * @param {string} content - .env file content
+ * @returns {Object} Validation result { valid: boolean, errors: Array<string> }
+ */
+function validateEnvFormat(content) {
+  const errors = [];
+  const lines = content.split('\n');
+
+  lines.forEach((line, index) => {
+    const lineNum = index + 1;
+    const trimmed = line.trim();
+
+    // Skip empty lines and comments
+    if (!trimmed || trimmed.startsWith('#')) {
+      return;
+    }
+
+    // Check for KEY=value format (no spaces around =)
+    if (!trimmed.match(/^[A-Z_][A-Z0-9_]*=/)) {
+      errors.push(`Line ${lineNum}: Invalid format. Expected KEY=value (no spaces around =)`);
+      return;
+    }
+
+    // Check for spaces around =
+    if (trimmed.match(/\s*=\s*/)) {
+      const [key, ...rest] = trimmed.split('=');
+      if (key.includes(' ') || (rest.length > 0 && rest[0].startsWith(' '))) {
+        errors.push(`Line ${lineNum}: Remove spaces around = in "${trimmed}"`);
+      }
+    }
+  });
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Validate API key format (basic check)
+ *
+ * @param {string} key - API key to validate
+ * @param {string} [provider] - Provider name for specific validation
+ * @returns {Object} Validation result { valid: boolean, error: string|null }
+ */
+function validateApiKeyFormat(key, provider = null) {
+  // Null/undefined/empty is valid (skip logic)
+  if (key === null || key === undefined || key === '') {
+    return { valid: true, error: null };
+  }
+
+  const trimmed = typeof key === 'string' ? key.trim() : '';
+
+  // Whitespace-only keys are invalid
+  if (key !== '' && trimmed === '') {
+    return { valid: false, error: 'API key cannot be only whitespace' };
+  }
+
+  // Provider-specific validation
+  if (provider) {
+    switch (provider.toLowerCase()) {
+      case 'openai':
+        // OpenAI keys start with sk- and are at least 20 chars
+        if (!trimmed.startsWith('sk-') || trimmed.length < 20) {
+          return { valid: false, error: 'OpenAI API keys should start with "sk-" and be at least 20 characters' };
+        }
+        break;
+
+      case 'anthropic':
+        // Anthropic keys start with sk-ant- and are longer
+        if (!trimmed.startsWith('sk-ant-') || trimmed.length < 30) {
+          return { valid: false, error: 'Anthropic API keys should start with "sk-ant-" and be at least 30 characters' };
+        }
+        break;
+
+      case 'github':
+        // GitHub tokens: ghp_ (personal), gho_ (OAuth), ghs_ (server), ghu_ (user), ghr_ (refresh), github_pat_ (fine-grained)
+        if (!trimmed.match(/^(ghp_|gho_|ghs_|ghu_|ghr_|github_pat_)/)) {
+          return { valid: false, error: 'GitHub tokens should start with ghp_, gho_, ghs_, ghu_, ghr_, or github_pat_' };
+        }
+        break;
+
+      // Other providers use basic validation
+      default:
+        break;
+    }
+  }
+
+  // Check for suspicious patterns (spaces, newlines)
+  if (trimmed.match(/\s/)) {
+    return { valid: false, error: 'API key should not contain spaces or newlines' };
+  }
+
+  // Check for minimum length (general safety)
+  if (trimmed.length < 10) {
+    return { valid: false, error: 'API key seems too short (minimum 10 characters)' };
+  }
+
+  return { valid: true, error: null };
+}
+
+/**
+ * Validate YAML syntax
+ *
+ * @param {string} content - YAML content
+ * @returns {Object} Validation result { valid: boolean, error: string|null, parsed: Object|null }
+ */
+function validateYamlSyntax(content) {
+  try {
+    const parsed = yaml.load(content);
+    return { valid: true, error: null, parsed };
+  } catch (error) {
+    return {
+      valid: false,
+      error: `YAML syntax error: ${error.message}`,
+      parsed: null,
+    };
+  }
+}
+
+/**
+ * Validate core-config.yaml structure
+ *
+ * @param {Object} config - Parsed YAML config
+ * @returns {Object} Validation result { valid: boolean, errors: Array<string> }
+ */
+function validateCoreConfigStructure(config) {
+  const errors = [];
+  const requiredFields = ['project', 'qa', 'prd', 'architecture'];
+
+  // Check required top-level fields
+  requiredFields.forEach(field => {
+    if (!config[field]) {
+      errors.push(`Missing required field: ${field}`);
+    }
+  });
+
+  // Validate project section
+  if (config.project) {
+    if (!config.project.type) {
+      errors.push('Missing project.type');
+    } else {
+      // Accept both lowercase and uppercase project types
+      const validTypes = ['GREENFIELD', 'BROWNFIELD', 'EXISTING_AIOS', 'greenfield', 'brownfield', 'existing_aios'];
+      if (!validTypes.includes(config.project.type)) {
+        errors.push(`Invalid project.type: ${config.project.type}. Expected greenfield, brownfield, or existing_aios`);
+      }
+    }
+  }
+
+  // Validate IDE section
+  if (config.ide) {
+    if (!Array.isArray(config.ide.selected)) {
+      errors.push('ide.selected must be an array');
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Validate file path (cross-platform)
+ *
+ * @param {string} filePath - Path to validate
+ * @returns {Object} Validation result { valid: boolean, error: string|null }
+ */
+function validatePath(filePath) {
+  // Check for null/undefined
+  if (!filePath) {
+    return { valid: false, error: 'Path cannot be empty' };
+  }
+
+  // Check for path traversal attempts (before normalization)
+  if (filePath.includes('..')) {
+    return { valid: false, error: 'Path traversal detected (..)' };
+  }
+
+  // Normalize and check again
+  const normalized = path.normalize(filePath);
+  if (normalized.includes('..')) {
+    return { valid: false, error: 'Path traversal detected (..)' };
+  }
+
+  // Check for invalid characters (basic check)
+  const invalidChars = /[<>"|?*\0]/;
+  if (invalidChars.test(filePath)) {
+    return { valid: false, error: 'Path contains invalid characters' };
+  }
+
+  return { valid: true, error: null };
+}
+
+/**
+ * Sanitize input to prevent injection
+ *
+ * @param {string} input - Input to sanitize
+ * @returns {string} Sanitized input
+ */
+function sanitizeInput(input) {
+  if (typeof input !== 'string') {
+    return '';
+  }
+
+  // Remove null bytes
+  let sanitized = input.replace(/\0/g, '');
+
+  // Trim whitespace
+  sanitized = sanitized.trim();
+
+  // Limit length (prevent DoS)
+  const maxLength = 10000;
+  if (sanitized.length > maxLength) {
+    sanitized = sanitized.substring(0, maxLength);
+  }
+
+  return sanitized;
+}
+
+module.exports = {
+  validateEnvFormat,
+  validateApiKeyFormat,
+  validateYamlSyntax,
+  validateCoreConfigStructure,
+  validatePath,
+  sanitizeInput,
+};

package/packages/installer/src/detection/detect-project-type.js

@@ -0,0 +1,81 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Detects the type of project in the current directory
+ * 
+ * Detection Priority Order:
+ * 1. EXISTING_AIOS - .aios-core/ directory exists
+ * 2. GREENFIELD - directory is empty
+ * 3. BROWNFIELD - package.json OR .git exists
+ * 4. UNKNOWN - directory has files but no recognized markers
+ * 
+ * @param {string} targetDir - Directory to analyze (defaults to process.cwd())
+ * @returns {string} 'GREENFIELD' | 'BROWNFIELD' | 'EXISTING_AIOS' | 'UNKNOWN'
+ * @throws {Error} If directory cannot be accessed
+ * 
+ * @example
+ * // Detect current directory
+ * const type = detectProjectType();
+ * console.log(type); // 'GREENFIELD'
+ * 
+ * @example
+ * // Detect specific directory
+ * const type = detectProjectType('/path/to/project');
+ * console.log(type); // 'BROWNFIELD'
+ */
+function detectProjectType(targetDir = process.cwd()) {
+  try {
+    // Validate targetDir parameter
+    if (!targetDir || typeof targetDir !== 'string') {
+      throw new Error('Invalid targetDir parameter: must be a non-empty string');
+    }
+
+    // Normalize path for cross-platform compatibility
+    const normalizedDir = path.resolve(targetDir);
+
+    // Check if directory exists before attempting to read
+    if (!fs.existsSync(normalizedDir)) {
+      throw new Error(`Directory does not exist: ${normalizedDir}`);
+    }
+
+    // Check for AIOS installation markers (use path.join for security)
+    const hasAiosCore = fs.existsSync(path.join(normalizedDir, '.aios-core'));
+    
+    // If AIOS already installed, return immediately (highest priority)
+    if (hasAiosCore) {
+      return 'EXISTING_AIOS';
+    }
+
+    // Check directory contents
+    const dirContents = fs.readdirSync(normalizedDir);
+    const isEmpty = dirContents.length === 0;
+    
+    // Empty directory = greenfield (second priority)
+    if (isEmpty) {
+      return 'GREENFIELD';
+    }
+
+    // Check for project markers (third priority)
+    const hasPackageJson = fs.existsSync(path.join(normalizedDir, 'package.json'));
+    const hasGit = fs.existsSync(path.join(normalizedDir, '.git'));
+    
+    // Existing project markers = brownfield
+    if (hasPackageJson || hasGit) {
+      return 'BROWNFIELD';
+    }
+
+    // Directory has files but no recognized markers = unknown
+    return 'UNKNOWN';
+
+  } catch (error) {
+    // Log error with context for debugging
+    console.error(`[detect-project-type] Error detecting project type in '${targetDir}': ${error.message}`);
+    
+    // Re-throw with more context for caller to handle
+    throw new Error(`Failed to detect project type: ${error.message}`);
+  }
+}
+
+module.exports = { detectProjectType };
+

package/packages/installer/src/wizard/wizard.js

@@ -0,0 +1,244 @@
+const { detectProjectType } = require('../detection/detect-project-type');
+const {
+  detectInstallationMode,
+  getModeOptions,
+  validateModeSelection,
+  InstallationMode,
+} = require('../../../../.aios-core/infrastructure/scripts/documentation-integrity/mode-detector');
+
+/**
+ * Interactive Wizard for AIOS Installation
+ *
+ * Supports three installation modes:
+ * - GREENFIELD: New project - generates all docs and config
+ * - BROWNFIELD: Existing project - analyzes and adapts
+ * - FRAMEWORK_DEV: Contributing to aios-core itself
+ *
+ * @module wizard
+ * @version 2.0.0
+ * @story 6.9
+ */
+
+/**
+ * Run the interactive installer wizard
+ *
+ * @param {Object} options - Wizard options
+ * @param {string} options.targetDir - Target directory for installation
+ * @param {string} options.mode - Pre-selected mode (skip detection)
+ * @returns {Promise<Object>} Installation configuration
+ */
+async function runWizard(options = {}) {
+  const targetDir = options.targetDir || process.cwd();
+
+  try {
+    // Step 1: Welcome screen
+    console.log('🚀 Welcome to AIOS Installer\n');
+
+    // Step 2: Detect installation mode (Story 6.9)
+    console.log('📊 Analyzing project directory...');
+    const detected = detectInstallationMode(targetDir);
+    console.log(`✅ Detected: ${detected.mode} (${detected.reason})\n`);
+
+    // Step 3: Select installation mode (with user override)
+    const selectedMode = options.mode || (await selectInstallationMode(detected));
+
+    // Step 4: Validate selection
+    const validation = validateModeSelection(selectedMode, detected);
+    if (validation.warnings.length > 0) {
+      console.log('\n⚠️  Warnings:');
+      validation.warnings.forEach((w) => console.log(`   - ${w}`));
+      console.log('');
+    }
+
+    // Step 5: Mode-specific configuration
+    const modeConfig = await configureModeSpecific(selectedMode, targetDir, detected);
+
+    // Step 6: Continue with installation (Stories 1.4-1.8)
+    // - IDE Selection (Story 1.4)
+    // - MCP Installation (Story 1.5)
+    // - Environment Config (Story 1.6)
+    // - Validation (Story 1.8)
+
+    return {
+      projectType: detected.legacyType, // Backward compatibility
+      installationMode: selectedMode,
+      targetDir,
+      detected,
+      modeConfig,
+      // Other configuration will be added by downstream stories
+    };
+  } catch (error) {
+    console.error('❌ Installation failed:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Select installation mode with user input
+ *
+ * @param {Object} detected - Detection result from mode detector
+ * @returns {Promise<string>} Selected installation mode
+ */
+async function selectInstallationMode(detected) {
+  const options = getModeOptions(detected);
+
+  console.log('Select installation type:\n');
+  options.forEach((opt, index) => {
+    const marker = opt.value === detected.mode ? '→' : ' ';
+    console.log(`${marker} ${index + 1}. ${opt.label}`);
+    console.log(`     ${opt.hint}\n`);
+  });
+
+  // Stub: In real implementation, use @clack/prompts select()
+  // For now, return detected mode or first option
+  console.log(`(Using detected mode: ${detected.mode})`);
+  console.log('(Interactive selection via @clack/prompts in Story 1.2)\n');
+
+  return detected.mode !== InstallationMode.UNKNOWN ? detected.mode : InstallationMode.GREENFIELD;
+}
+
+/**
+ * Configure mode-specific settings
+ *
+ * @param {string} mode - Selected installation mode
+ * @param {string} targetDir - Target directory
+ * @param {Object} detected - Detection result
+ * @returns {Promise<Object>} Mode-specific configuration
+ */
+async function configureModeSpecific(mode, targetDir, detected) {
+  const config = {
+    mode,
+    generateDocs: true,
+    generateConfig: true,
+    generateGitignore: true,
+    runSetupGithub: false,
+    deployment: null,
+  };
+
+  switch (mode) {
+    case InstallationMode.FRAMEWORK_DEV:
+      // Framework development - skip project setup
+      console.log('🔧 Framework Development Mode');
+      console.log('   → Using existing framework standards');
+      console.log('   → Skipping project documentation generation');
+      console.log('   → Skipping infrastructure setup\n');
+      config.generateDocs = false;
+      config.generateConfig = false;
+      config.generateGitignore = false;
+      break;
+
+    case InstallationMode.GREENFIELD:
+      // New project - full scaffolding
+      console.log('🆕 Greenfield Mode');
+      console.log('   → Will generate project documentation');
+      console.log('   → Will create project-specific core-config');
+      console.log('   → Will generate .gitignore based on tech stack');
+      console.log('   → Will offer *setup-github for infrastructure\n');
+      config.runSetupGithub = true;
+      // Deployment config will be elicited in Phase 3
+      config.deployment = await elicitDeploymentConfig();
+      break;
+
+    case InstallationMode.BROWNFIELD:
+      // Existing project - analyze and adapt
+      console.log('📂 Brownfield Mode');
+      console.log('   → Will analyze existing source tree');
+      console.log('   → Will detect existing coding standards');
+      console.log('   → Will merge with existing .gitignore');
+      console.log('   → Will analyze existing GitHub workflows\n');
+      // Deployment config will be elicited based on analysis in Phase 3
+      config.deployment = await elicitDeploymentConfig();
+      break;
+
+    default:
+      console.log('❓ Unknown mode - using greenfield defaults\n');
+  }
+
+  return config;
+}
+
+/**
+ * Elicit deployment configuration from user
+ * Implements Task 3.3 from Story 6.9
+ *
+ * @returns {Promise<Object>} Deployment configuration
+ */
+async function elicitDeploymentConfig() {
+  // Stub implementation - will be fully implemented in Phase 3
+  console.log('📦 Deployment Configuration');
+  console.log('   (Full elicitation will be implemented in Phase 3)\n');
+
+  // Return default staging-first workflow
+  return {
+    workflow: 'staging-first',
+    branches: {
+      staging_targets: ['feature/*', 'fix/*', 'docs/*', 'chore/*', 'refactor/*', 'test/*'],
+      production_targets: ['hotfix/*'],
+      staging_branch: 'staging',
+      production_branch: 'main',
+      default_target: 'staging',
+    },
+    environments: {
+      staging: {
+        name: 'Staging',
+        auto_deploy: true,
+        platform: null, // To be detected/elicited
+      },
+      production: {
+        name: 'Production',
+        auto_deploy: true,
+        platform: null,
+      },
+    },
+    quality_gates: {
+      lint: true,
+      typecheck: true,
+      tests: true,
+      security_scan: false,
+    },
+  };
+}
+
+/**
+ * Confirm project type with user or allow override
+ * @deprecated Use selectInstallationMode instead
+ *
+ * @param {string} detectedType - Detected project type
+ * @returns {Promise<string>} Confirmed project type
+ */
+async function confirmProjectType(detectedType) {
+  // Kept for backward compatibility
+  const typeDescriptions = {
+    GREENFIELD: 'New project - AIOS will create complete structure',
+    BROWNFIELD: 'Existing project - AIOS will integrate with current setup',
+    EXISTING_AIOS: 'AIOS already installed - Would you like to update or reinstall?',
+    UNKNOWN: 'Unknown project type - Manual selection required',
+  };
+
+  console.log(`Project Type: ${detectedType}`);
+  console.log(`Description: ${typeDescriptions[detectedType]}`);
+  console.log('(Use selectInstallationMode for new three-mode selection)\n');
+
+  return detectedType;
+}
+
+/**
+ * Get project type for a directory (exposed for downstream stories)
+ * 
+ * @param {string} targetDir - Directory to check
+ * @returns {string} Project type
+ */
+function getProjectType(targetDir) {
+  return detectProjectType(targetDir);
+}
+
+module.exports = {
+  runWizard,
+  selectInstallationMode,
+  configureModeSpecific,
+  elicitDeploymentConfig,
+  confirmProjectType, // Deprecated - kept for backward compatibility
+  getProjectType,
+  InstallationMode,
+};
+