aios-core 1.0.0

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,
+};
+

package/packages/installer/tests/integration/environment-configuration.test.js

@@ -0,0 +1,329 @@
+/**
+ * Integration Tests: Environment Configuration
+ * Story 1.6: Environment Configuration
+ *
+ * Tests for configure-environment.js with file system operations
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+const { configureEnvironment, updateGitignore } = require('../../src/config/configure-environment');
+
+/**
+ * Cleanup helper with retry logic for flaky file system operations
+ * Handles ENOTEMPTY and EBUSY errors common in CI environments
+ * @param {string} dir - Directory to remove
+ * @param {number} maxRetries - Maximum retry attempts
+ * @param {number} retryDelay - Delay between retries in ms
+ */
+async function cleanupWithRetry(dir, maxRetries = 5, retryDelay = 100) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      if (await fs.pathExists(dir)) {
+        await fs.remove(dir);
+      }
+      return;
+    } catch (error) {
+      const isRetryable = error.code && ['ENOTEMPTY', 'EBUSY', 'EPERM', 'EACCES'].includes(error.code);
+      if (attempt === maxRetries || !isRetryable) {
+        // Last attempt failed or non-retryable error, log but don't throw
+        console.warn(`Warning: Failed to cleanup ${dir} after ${attempt} attempts:`, error.code);
+        return;
+      }
+      // Linear backoff (100ms, 200ms, 300ms...)
+      await new Promise(resolve => setTimeout(resolve, retryDelay * attempt));
+    }
+  }
+}
+
+describe('Environment Configuration Integration', () => {
+  let testDir;
+  let testId;
+
+  beforeEach(async () => {
+    // Create unique temporary test directory with random suffix to avoid collisions
+    testId = `${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+    testDir = path.join(os.tmpdir(), `aios-env-test-${testId}`);
+    await fs.ensureDir(testDir);
+  });
+
+  afterEach(async () => {
+    // Small delay to allow file handles to close
+    await new Promise(resolve => setTimeout(resolve, 50));
+    // Cleanup test directory with retry logic
+    await cleanupWithRetry(testDir);
+  });
+
+  describe('configureEnvironment', () => {
+    it('should create .env file with skip prompts', async () => {
+      const result = await configureEnvironment({
+        targetDir: testDir,
+        skipPrompts: true,
+        projectType: 'GREENFIELD',
+        selectedIDEs: ['vscode'],
+        mcpServers: [],
+      });
+
+      expect(result.envCreated).toBe(true);
+
+      const envPath = path.join(testDir, '.env');
+      expect(await fs.pathExists(envPath)).toBe(true);
+
+      const content = await fs.readFile(envPath, 'utf8');
+      expect(content).toContain('NODE_ENV=development');
+      // Version-agnostic: check AIOS_VERSION exists with valid semver format
+      expect(content).toMatch(/AIOS_VERSION=\d+\.\d+\.\d+/);
+    });
+
+    it('should create .env.example file', async () => {
+      const result = await configureEnvironment({
+        targetDir: testDir,
+        skipPrompts: true,
+      });
+
+      expect(result.envExampleCreated).toBe(true);
+
+      const envExamplePath = path.join(testDir, '.env.example');
+      expect(await fs.pathExists(envExamplePath)).toBe(true);
+
+      const content = await fs.readFile(envExamplePath, 'utf8');
+      expect(content).toContain('OPENAI_API_KEY=');
+      expect(content).not.toMatch(/sk-[a-zA-Z0-9]{20,}/);
+    });
+
+    it('should create core-config.yaml', async () => {
+      const result = await configureEnvironment({
+        targetDir: testDir,
+        skipPrompts: true,
+        projectType: 'BROWNFIELD',
+        selectedIDEs: ['vscode', 'cursor'],
+        mcpServers: [{ name: 'github' }, { name: 'exa' }],
+      });
+
+      expect(result.coreConfigCreated).toBe(true);
+
+      const configPath = path.join(testDir, '.aios-core', 'core-config.yaml');
+      expect(await fs.pathExists(configPath)).toBe(true);
+
+      const content = await fs.readFile(configPath, 'utf8');
+      expect(content).toContain('type: BROWNFIELD');
+      expect(content).toContain('- vscode');
+      expect(content).toContain('- cursor');
+      expect(content).toContain('- github');
+      expect(content).toContain('- exa');
+    });
+
+    it('should update .gitignore', async () => {
+      const result = await configureEnvironment({
+        targetDir: testDir,
+        skipPrompts: true,
+      });
+
+      expect(result.gitignoreUpdated).toBe(true);
+
+      const gitignorePath = path.join(testDir, '.gitignore');
+      expect(await fs.pathExists(gitignorePath)).toBe(true);
+
+      const content = await fs.readFile(gitignorePath, 'utf8');
+      expect(content).toContain('.env');
+    });
+
+    it('should set .env file permissions on Unix', async () => {
+      if (process.platform === 'win32') {
+        // Skip on Windows
+        return;
+      }
+
+      await configureEnvironment({
+        targetDir: testDir,
+        skipPrompts: true,
+      });
+
+      const envPath = path.join(testDir, '.env');
+      const stats = await fs.stat(envPath);
+
+      // Check permissions are 0600 (owner read/write only)
+      const mode = stats.mode & 0o777;
+      expect(mode).toBe(0o600);
+    });
+
+    it('should create backup of existing .env in non-prompt mode', async () => {
+      // Create existing .env
+      const envPath = path.join(testDir, '.env');
+      await fs.writeFile(envPath, 'EXISTING_KEY=existing_value', 'utf8');
+
+      // Run configuration (skipPrompts mode doesn't backup)
+      await configureEnvironment({
+        targetDir: testDir,
+        skipPrompts: true,
+      });
+
+      // In skipPrompts mode, no backup is created, file is overwritten
+      const content = await fs.readFile(envPath, 'utf8');
+      expect(content).not.toContain('EXISTING_KEY=existing_value');
+    });
+
+    it('should handle errors gracefully', async () => {
+      // Try to write to a read-only directory (simulate permission error)
+      const readOnlyDir = path.join(testDir, 'readonly');
+      await fs.ensureDir(readOnlyDir);
+
+      // Note: This test is platform-dependent and may not work on all systems
+      // Just verify the function handles errors
+      try {
+        await configureEnvironment({
+          targetDir: '/invalid/path/that/does/not/exist',
+          skipPrompts: true,
+        });
+        fail('Should have thrown an error');
+      } catch (error) {
+        expect(error).toBeDefined();
+      }
+    });
+  });
+
+  describe('updateGitignore', () => {
+    it('should create .gitignore if not exists', async () => {
+      await updateGitignore(testDir);
+
+      const gitignorePath = path.join(testDir, '.gitignore');
+      expect(await fs.pathExists(gitignorePath)).toBe(true);
+
+      const content = await fs.readFile(gitignorePath, 'utf8');
+      expect(content).toContain('.env');
+    });
+
+    it('should append to existing .gitignore', async () => {
+      const gitignorePath = path.join(testDir, '.gitignore');
+      await fs.writeFile(gitignorePath, 'node_modules\n*.log\n', 'utf8');
+
+      await updateGitignore(testDir);
+
+      const content = await fs.readFile(gitignorePath, 'utf8');
+      expect(content).toContain('node_modules');
+      expect(content).toContain('*.log');
+      expect(content).toContain('.env');
+    });
+
+    it('should not duplicate .env entry', async () => {
+      const gitignorePath = path.join(testDir, '.gitignore');
+      await fs.writeFile(gitignorePath, '.env\n', 'utf8');
+
+      await updateGitignore(testDir);
+
+      const content = await fs.readFile(gitignorePath, 'utf8');
+      const lines = content.split('\n').filter(line => line.trim() === '.env' || line.trim() === '/.env');
+      expect(lines.length).toBe(1);
+    });
+
+    it('should recognize existing .env entry with slash', async () => {
+      const gitignorePath = path.join(testDir, '.gitignore');
+      await fs.writeFile(gitignorePath, '/.env\n', 'utf8');
+
+      await updateGitignore(testDir);
+
+      const content = await fs.readFile(gitignorePath, 'utf8');
+      const lines = content.split('\n').filter(line => line.trim() === '.env' || line.trim() === '/.env');
+      expect(lines.length).toBe(1);
+    });
+  });
+
+  describe('Wizard Integration', () => {
+    it('should integrate with wizard state from previous stories', async () => {
+      // Simulate wizard state from Stories 1.3, 1.4, 1.5
+      const wizardState = {
+        projectType: 'GREENFIELD',
+        selectedIDEs: ['vscode', 'cursor'],
+        mcpServers: [
+          { name: 'github', id: 'github' },
+          { name: 'exa', id: 'exa' },
+        ],
+      };
+
+      const result = await configureEnvironment({
+        targetDir: testDir,
+        skipPrompts: true,
+        ...wizardState,
+      });
+
+      // Verify all files created
+      expect(result.envCreated).toBe(true);
+      expect(result.coreConfigCreated).toBe(true);
+      expect(result.gitignoreUpdated).toBe(true);
+
+      // Verify core-config includes wizard state
+      const configPath = path.join(testDir, '.aios-core', 'core-config.yaml');
+      const configContent = await fs.readFile(configPath, 'utf8');
+
+      expect(configContent).toContain('GREENFIELD');
+      expect(configContent).toContain('vscode');
+      expect(configContent).toContain('cursor');
+      expect(configContent).toContain('github');
+      expect(configContent).toContain('exa');
+    });
+  });
+
+  describe('Cross-Platform Compatibility', () => {
+    it('should handle Windows paths', async () => {
+      const result = await configureEnvironment({
+        targetDir: testDir,
+        skipPrompts: true,
+      });
+
+      expect(result.envCreated).toBe(true);
+      expect(result.coreConfigCreated).toBe(true);
+    });
+
+    it('should create valid YAML on all platforms', async () => {
+      await configureEnvironment({
+        targetDir: testDir,
+        skipPrompts: true,
+        projectType: 'GREENFIELD',
+      });
+
+      const yaml = require('js-yaml');
+      const configPath = path.join(testDir, '.aios-core', 'core-config.yaml');
+      const content = await fs.readFile(configPath, 'utf8');
+
+      // Should parse without errors
+      const parsed = yaml.load(content);
+      expect(parsed).toBeDefined();
+      expect(parsed.project.type).toBe('GREENFIELD');
+    });
+  });
+
+  describe('File Structure', () => {
+    it('should create correct directory structure', async () => {
+      await configureEnvironment({
+        targetDir: testDir,
+        skipPrompts: true,
+      });
+
+      // Check all expected files exist
+      const expectedFiles = [
+        '.env',
+        '.env.example',
+        '.gitignore',
+        '.aios-core/core-config.yaml',
+      ];
+
+      for (const file of expectedFiles) {
+        const filePath = path.join(testDir, file);
+        expect(await fs.pathExists(filePath)).toBe(true);
+      }
+    });
+
+    it('should create .aios-core directory if missing', async () => {
+      const aioscoreDir = path.join(testDir, '.aios-core');
+      expect(await fs.pathExists(aioscoreDir)).toBe(false);
+
+      await configureEnvironment({
+        targetDir: testDir,
+        skipPrompts: true,
+      });
+
+      expect(await fs.pathExists(aioscoreDir)).toBe(true);
+    });
+  });
+});