create-byan-agent 2.7.0 → 2.7.2

package/lib/yanstaller/index.js

@@ -0,0 +1,139 @@
+/**
+ * YANSTALLER - Main Orchestrator
+ * 
+ * Coordinates all YANSTALLER modules to perform intelligent BYAN installation.
+ * 
+ * @module yanstaller
+ */
+
+const detector = require('./detector');
+const recommender = require('./recommender');
+const installer = require('./installer');
+const validator = require('./validator');
+const troubleshooter = require('./troubleshooter');
+const interviewer = require('./interviewer');
+const backuper = require('./backuper');
+const wizard = require('./wizard');
+const platformSelector = require('./platform-selector');
+const logger = require('../utils/logger');
+
+/**
+ * @typedef {Object} YanInstallerOptions
+ * @property {boolean} [yes] - Skip confirmations (--yes flag)
+ * @property {string} [mode] - Installation mode: 'full' | 'minimal' | 'custom'
+ * @property {string[]} [platforms] - Target platforms (override detection)
+ * @property {boolean} [verbose] - Verbose output
+ * @property {boolean} [quiet] - Minimal output
+ */
+
+/**
+ * Main installation flow
+ * 
+ * @param {YanInstallerOptions} [options={}] - Installation options
+ * @returns {Promise<void>}
+ */
+async function install(options = {}) {
+  let backupPath = null;
+  
+  try {
+    // Phase 1: Detect environment
+    logger.info('🔍 Detecting environment...');
+    const detection = await detector.detect();
+    
+    // Phase 2: Validate Node version (FAIL FAST)
+    if (!detector.isNodeVersionValid(detection.nodeVersion, '18.0.0')) {
+      throw new Error(`Node.js >= 18.0.0 required. Found: ${detection.nodeVersion}`);
+    }
+    
+    // Phase 3: Platform Selection
+    let platformSelection;
+    if (options.platforms) {
+      // CLI override
+      platformSelection = {
+        platforms: options.platforms,
+        mode: 'manual'
+      };
+    } else if (options.yes) {
+      // Auto mode
+      platformSelection = {
+        platforms: detection.platforms.filter(p => p.detected).map(p => p.name),
+        mode: 'auto'
+      };
+    } else {
+      // Interactive selection
+      platformSelection = await platformSelector.select(detection);
+    }
+    
+    logger.info(`\n✓ Selected ${platformSelection.platforms.length} platform(s)`);
+    logger.info(`  Mode: ${platformSelection.mode}`);
+    if (platformSelection.specialist) {
+      logger.info(`  Specialist: @bmad-agent-${platformSelection.specialist}`);
+    }
+    
+    // Phase 4: Recommend configuration
+    // TODO: Implement
+    
+    // Phase 5: Run interview (unless --yes)
+    // TODO: Implement
+    
+    // Phase 6: Backup existing installation
+    // backupPath = await backuper.backup('_bmad');
+    
+    // Phase 7: Install agents
+    // TODO: Implement
+    
+    // Phase 8: Validate installation
+    // TODO: Implement
+    
+    // Phase 9: Show post-install wizard
+    // TODO: Implement
+  } catch (error) {
+    // ROLLBACK STRATEGY: Leave partial state + clear message
+    // Rationale (Mantra #37 Ockham's Razor):
+    // - Installation = mostly file copies (low risk)
+    // - User can re-run (idempotent)
+    // - Backup exists for manual restore
+    // - Auto-rollback risks losing working partial install
+    
+    logger.error('Installation failed:', error.message);
+    
+    if (backupPath) {
+      logger.info('\nPartial installation completed.');
+      logger.info(`Backup available at: ${backupPath}`);
+      logger.info('\nOptions:');
+      logger.info('1. Re-run: npx create-byan-agent');
+      logger.info(`2. Restore backup: yanstaller restore ${backupPath}`);
+      logger.info('3. Troubleshoot: yanstaller doctor');
+    }
+    
+    throw error; // Re-throw for exit code handling
+  }
+}
+
+/**
+ * Uninstall BYAN
+ * 
+ * @returns {Promise<void>}
+ */
+async function uninstall() {
+  // TODO: Remove _bmad/, .github/agents/ stubs
+}
+
+/**
+ * Update existing BYAN installation
+ * 
+ * @param {string} version - Target version
+ * @returns {Promise<void>}
+ */
+async function update(version) {
+  // TODO: Backup → Update agents → Merge configs
+}
+
+module.exports = {
+  install,
+  uninstall,
+  update,
+  // Expose for testing
+  detector,
+  platformSelector
+};

package/lib/yanstaller/installer.js

@@ -0,0 +1,140 @@
+/**
+ * INSTALLER Module
+ * 
+ * Installs BYAN agents across multiple platforms.
+ * Most complex module: 56h development.
+ * 
+ * Phase 3: 56h development
+ * 
+ * @module yanstaller/installer
+ */
+
+const path = require('path');
+const fileUtils = require('../utils/file-utils');
+const logger = require('../utils/logger');
+
+/**
+ * @typedef {Object} InstallConfig
+ * @property {string} mode - 'full' | 'minimal' | 'custom'
+ * @property {string[]} agents - Agent names to install
+ * @property {string} userName - User's name
+ * @property {string} language - 'Francais' | 'English'
+ * @property {string[]} targetPlatforms - Platforms to install on
+ * @property {string} outputFolder - Output folder path
+ * @property {string} projectRoot - Project root directory
+ */
+
+/**
+ * @typedef {Object} InstallResult
+ * @property {boolean} success
+ * @property {number} agentsInstalled - Number of agents installed
+ * @property {string[]} platforms - Platforms installed on
+ * @property {string[]} errors - Installation errors
+ * @property {number} duration - Duration in ms
+ */
+
+/**
+ * Install BYAN agents
+ * 
+ * @param {InstallConfig} config - Installation configuration
+ * @returns {Promise<InstallResult>}
+ */
+async function install(config) {
+  const startTime = Date.now();
+  const errors = [];
+  
+  try {
+    // TODO: Implement installation
+    // 1. Create _bmad/ structure
+    // 2. Copy agent files from templates/
+    // 3. Generate platform-specific stubs
+    // 4. Create config files
+    
+    logger.info(`Installing ${config.agents.length} agents...`);
+    
+    // Placeholder
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    
+    return {
+      success: true,
+      agentsInstalled: config.agents.length,
+      platforms: config.targetPlatforms,
+      errors,
+      duration: Date.now() - startTime
+    };
+  } catch (error) {
+    errors.push(error.message);
+    return {
+      success: false,
+      agentsInstalled: 0,
+      platforms: [],
+      errors,
+      duration: Date.now() - startTime
+    };
+  }
+}
+
+/**
+ * Create _bmad/ directory structure
+ * 
+ * @param {string} projectRoot - Project root directory
+ * @returns {Promise<void>}
+ */
+async function createBmadStructure(projectRoot) {
+  // TODO: Create directories
+  // _bmad/
+  // ├── _config/
+  // ├── _memory/
+  // ├── core/
+  // ├── bmm/
+  // ├── bmb/
+  // ├── tea/
+  // └── cis/
+}
+
+/**
+ * Copy agent file from template
+ * 
+ * @param {string} agentName - Agent name
+ * @param {string} targetPath - Target directory
+ * @returns {Promise<void>}
+ */
+async function copyAgentFile(agentName, targetPath) {
+  // TODO: Copy from lib/templates/agents/{agentName}.md
+}
+
+/**
+ * Generate platform-specific stub
+ * 
+ * @param {string} agentName - Agent name
+ * @param {string} platform - Platform name
+ * @param {string} targetPath - Target directory
+ * @returns {Promise<void>}
+ */
+async function generateStub(agentName, platform, targetPath) {
+  // TODO: Generate stub based on platform
+  // - Copilot CLI: .github/agents/{agentName}.md with YAML frontmatter
+  // - VSCode: Same as Copilot CLI
+  // - Claude Code: MCP config JSON
+  // - Codex: .codex/prompts/{agentName}.md
+}
+
+/**
+ * Create module config file
+ * 
+ * @param {string} moduleName - Module name (core, bmm, bmb, tea, cis)
+ * @param {InstallConfig} config - Installation config
+ * @param {string} targetPath - Target directory
+ * @returns {Promise<void>}
+ */
+async function createModuleConfig(moduleName, config, targetPath) {
+  // TODO: Generate config.yaml with user settings
+}
+
+module.exports = {
+  install,
+  createBmadStructure,
+  copyAgentFile,
+  generateStub,
+  createModuleConfig
+};

package/lib/yanstaller/interviewer.js

@@ -0,0 +1,88 @@
+/**
+ * INTERVIEWER Module
+ * 
+ * Conducts quick interview (5-7 questions, <5 min) to personalize installation.
+ * 
+ * Phase 6 (part of 7): 16h development
+ * 
+ * @module yanstaller/interviewer
+ */
+
+const inquirer = require('inquirer');
+
+/**
+ * @typedef {Object} InterviewResult
+ * @property {string} userName
+ * @property {string} language - 'Francais' | 'English'
+ * @property {string} mode - 'full' | 'minimal' | 'custom'
+ * @property {string[]} agents - Selected agents (if custom mode)
+ * @property {string[]} targetPlatforms - Platforms to install on
+ * @property {boolean} createSampleAgent - Whether to create sample agent after install
+ */
+
+/**
+ * Run quick interview
+ * 
+ * @param {import('./recommender').Recommendation} recommendation - Recommended config
+ * @returns {Promise<InterviewResult>}
+ */
+async function ask(recommendation) {
+  // TODO: Implement inquirer prompts
+  // Q1: Your name?
+  // Q2: Preferred language?
+  // Q3: Installation mode? (with recommendation)
+  // Q4: (if custom) Which agents?
+  // Q5: Which platforms to install on?
+  // Q6: Create sample agent after install?
+  
+  return {
+    userName: 'User',
+    language: 'English',
+    mode: recommendation.mode,
+    agents: recommendation.agents,
+    targetPlatforms: ['copilot-cli'],
+    createSampleAgent: false
+  };
+}
+
+/**
+ * Ask single question
+ * 
+ * @param {string} question - Question text
+ * @param {string} type - 'input' | 'list' | 'confirm' | 'checkbox'
+ * @param {Array} [choices] - Choices for list/checkbox
+ * @returns {Promise<any>}
+ */
+async function askQuestion(question, type, choices = []) {
+  // TODO: Use inquirer
+  const answer = await inquirer.prompt([
+    {
+      type,
+      name: 'answer',
+      message: question,
+      choices
+    }
+  ]);
+  
+  return answer.answer;
+}
+
+/**
+ * Get available agents list for custom selection
+ * 
+ * @returns {Array<{name: string, value: string, checked: boolean}>}
+ */
+function getAgentChoices() {
+  // TODO: Return all 29 agents with descriptions
+  return [
+    { name: 'BYAN - Agent Creator', value: 'byan', checked: true },
+    { name: 'RACHID - NPM Deployment', value: 'rachid', checked: true },
+    // ... 27 more
+  ];
+}
+
+module.exports = {
+  ask,
+  askQuestion,
+  getAgentChoices
+};

package/lib/yanstaller/platform-selector.js

@@ -0,0 +1,328 @@
+/**
+ * PLATFORM SELECTOR Module
+ * 
+ * Interactive platform selection for BYAN installation.
+ * Detects available platforms and lets user choose target(s).
+ * 
+ * @module yanstaller/platform-selector
+ */
+
+const inquirer = require('inquirer');
+const logger = require('../utils/logger');
+const platforms = require('../platforms');
+
+/**
+ * @typedef {Object} PlatformChoice
+ * @property {string} name - Display name
+ * @property {string} id - Platform ID ('copilot-cli' | 'vscode' | 'claude' | 'codex')
+ * @property {boolean} detected - Is platform installed?
+ * @property {string} [path] - Installation path if detected
+ * @property {boolean} native - Native integration available?
+ * @property {string} [agentSpecialist] - Agent specialist for this platform
+ */
+
+/**
+ * @typedef {Object} PlatformSelectionResult
+ * @property {string[]} platforms - Selected platform IDs
+ * @property {string} mode - 'native' | 'conversational' | 'auto'
+ * @property {string} [specialist] - Agent specialist to use
+ */
+
+const PLATFORM_INFO = {
+  'copilot-cli': {
+    displayName: 'GitHub Copilot CLI',
+    native: true,
+    specialist: 'marc',
+    icon: '🤖'
+  },
+  'claude': {
+    displayName: 'Claude Code',
+    native: true,
+    specialist: 'claude',
+    icon: '🎭'
+  },
+  'codex': {
+    displayName: 'OpenCode/Codex',
+    native: true, // NOW NATIVE!
+    specialist: 'codex',
+    icon: '📝'
+  },
+  'vscode': {
+    displayName: 'VS Code',
+    native: false,
+    specialist: null,
+    icon: '💻'
+  }
+};
+
+/**
+ * Detect and select platforms interactively
+ * 
+ * @param {Object} detectionResult - Result from detector.detect()
+ * @returns {Promise<PlatformSelectionResult>}
+ */
+async function select(detectionResult) {
+  logger.info('\n🎯 Platform Selection\n');
+  
+  // Build platform choices from detection
+  const choices = buildChoices(detectionResult.platforms);
+  
+  // Check if any native integration available
+  const hasNative = choices.some(c => c.native && c.detected);
+  
+  if (choices.length === 0) {
+    logger.warn('No platforms detected. Will create _byan/ structure only.');
+    return {
+      platforms: [],
+      mode: 'manual'
+    };
+  }
+  
+  // Show primary platform selection first
+  const nativePlatforms = choices.filter(c => c.native && c.detected);
+  
+  // Step 1: Choose primary platform (if native available)
+  if (nativePlatforms.length > 0) {
+    const primaryAnswer = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'primary',
+        message: '🎯 Choose your PRIMARY platform for native agent invocation:',
+        choices: [
+          ...nativePlatforms.map(c => ({
+            name: `${c.icon} ${c.name} - ${c.agentSpecialist ? `@bmad-agent-${c.agentSpecialist}` : 'No specialist'}`,
+            value: c.id,
+            short: c.name
+          })),
+          new inquirer.Separator(),
+          {
+            name: '🔧 Advanced: Install on multiple platforms',
+            value: 'multi'
+          },
+          {
+            name: '⏭️  Skip native integration (manual install only)',
+            value: 'skip'
+          }
+        ]
+      }
+    ]);
+    
+    // If user chose single platform, return immediately
+    if (primaryAnswer.primary !== 'multi' && primaryAnswer.primary !== 'skip') {
+      const platform = nativePlatforms.find(c => c.id === primaryAnswer.primary);
+      return {
+        platforms: [primaryAnswer.primary],
+        mode: 'native',
+        specialist: platform.agentSpecialist,
+        primary: primaryAnswer.primary
+      };
+    }
+    
+    // If skip, fall through to conversational mode
+    if (primaryAnswer.primary === 'skip') {
+      return {
+        platforms: choices.map(c => c.id),
+        mode: 'conversational'
+      };
+    }
+    
+    // If multi, show full menu
+  }
+  
+  // Step 2: Full menu (multi-platform or no native available)
+  const answer = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'selection',
+      message: 'Choose installation target:',
+      choices: [
+        {
+          name: `🚀 Auto (detect & install all available) - ${choices.length} platform(s)`,
+          value: 'auto'
+        },
+        ...choices.map(c => ({
+          name: formatPlatformChoice(c),
+          value: `single:${c.id}`
+        })),
+        {
+          name: '🔧 Custom (select multiple)',
+          value: 'custom'
+        }
+      ]
+    }
+  ]);
+  
+  if (answer.selection === 'auto') {
+    return handleAutoMode(choices);
+  }
+  
+  if (answer.selection === 'custom') {
+    return handleCustomMode(choices);
+  }
+  
+  // Single platform selection
+  const platformId = answer.selection.replace('single:', '');
+  return handleSinglePlatform(platformId, choices);
+}
+
+/**
+ * Build platform choices from detection result
+ * 
+ * @param {Array} detectedPlatforms - From detector
+ * @returns {PlatformChoice[]}
+ */
+function buildChoices(detectedPlatforms) {
+  return detectedPlatforms
+    .filter(p => p.detected)
+    .map(p => {
+      const info = PLATFORM_INFO[p.name] || {
+        displayName: p.name,
+        native: false,
+        specialist: null,
+        icon: '❓'
+      };
+      
+      return {
+        name: info.displayName,
+        id: p.name,
+        detected: p.detected,
+        path: p.path,
+        native: info.native,
+        agentSpecialist: info.specialist,
+        icon: info.icon
+      };
+    });
+}
+
+/**
+ * Format platform choice for display
+ * 
+ * @param {PlatformChoice} choice
+ * @returns {string}
+ */
+function formatPlatformChoice(choice) {
+  const nativeBadge = choice.native ? '✨ Native' : '💬 Conversational';
+  const statusBadge = choice.detected ? '✓' : '✗';
+  
+  return `${choice.icon} ${choice.name} (${nativeBadge}) ${statusBadge}`;
+}
+
+/**
+ * Handle auto mode - install on all detected platforms
+ * 
+ * @param {PlatformChoice[]} choices
+ * @returns {Promise<PlatformSelectionResult>}
+ */
+async function handleAutoMode(choices) {
+  const nativePlatforms = choices.filter(c => c.native);
+  
+  if (nativePlatforms.length > 0) {
+    // Use native integration for first platform (or all?)
+    return {
+      platforms: choices.map(c => c.id),
+      mode: 'native',
+      specialist: nativePlatforms[0].agentSpecialist
+    };
+  }
+  
+  return {
+    platforms: choices.map(c => c.id),
+    mode: 'conversational'
+  };
+}
+
+/**
+ * Handle custom mode - user selects multiple platforms
+ * 
+ * @param {PlatformChoice[]} choices
+ * @returns {Promise<PlatformSelectionResult>}
+ */
+async function handleCustomMode(choices) {
+  const answer = await inquirer.prompt([
+    {
+      type: 'checkbox',
+      name: 'platforms',
+      message: 'Select platforms to install on:',
+      choices: choices.map(c => ({
+        name: formatPlatformChoice(c),
+        value: c.id,
+        checked: c.detected
+      }))
+    }
+  ]);
+  
+  if (answer.platforms.length === 0) {
+    logger.warn('No platforms selected. Installation cancelled.');
+    return {
+      platforms: [],
+      mode: 'manual'
+    };
+  }
+  
+  // Check if any selected platform has native integration
+  const selectedChoices = choices.filter(c => answer.platforms.includes(c.id));
+  const nativePlatform = selectedChoices.find(c => c.native);
+  
+  if (nativePlatform) {
+    return {
+      platforms: answer.platforms,
+      mode: 'native',
+      specialist: nativePlatform.agentSpecialist
+    };
+  }
+  
+  return {
+    platforms: answer.platforms,
+    mode: 'conversational'
+  };
+}
+
+/**
+ * Handle single platform selection
+ * 
+ * @param {string} platformId
+ * @param {PlatformChoice[]} choices
+ * @returns {PlatformSelectionResult}
+ */
+function handleSinglePlatform(platformId, choices) {
+  const choice = choices.find(c => c.id === platformId);
+  
+  if (!choice) {
+    throw new Error(`Platform ${platformId} not found`);
+  }
+  
+  return {
+    platforms: [platformId],
+    mode: choice.native ? 'native' : 'conversational',
+    specialist: choice.agentSpecialist
+  };
+}
+
+/**
+ * Get specialist agent for platform
+ * 
+ * @param {string} platformId
+ * @returns {string|null}
+ */
+function getSpecialist(platformId) {
+  const info = PLATFORM_INFO[platformId];
+  return info ? (info.specialist || null) : null;
+}
+
+/**
+ * Check if platform has native integration
+ * 
+ * @param {string} platformId
+ * @returns {boolean}
+ */
+function hasNativeIntegration(platformId) {
+  const info = PLATFORM_INFO[platformId];
+  return info ? (info.native || false) : false;
+}
+
+module.exports = {
+  select,
+  getSpecialist,
+  hasNativeIntegration,
+  PLATFORM_INFO
+};