create-byan-agent 2.7.0 → 2.7.2

package/lib/utils/yaml-utils.js

@@ -0,0 +1,87 @@
+/**
+ * YAML Utilities
+ * 
+ * Wrapper around js-yaml for YAML parsing/dumping.
+ * 
+ * @module utils/yaml-utils
+ */
+
+const yaml = require('js-yaml');
+const fileUtils = require('./file-utils');
+
+/**
+ * Parse YAML string
+ * 
+ * @param {string} yamlString - YAML string
+ * @returns {Object}
+ */
+function parse(yamlString) {
+  return yaml.load(yamlString);
+}
+
+/**
+ * Dump object to YAML string
+ * 
+ * @param {Object} obj - Object to dump
+ * @returns {string}
+ */
+function dump(obj) {
+  return yaml.dump(obj, {
+    indent: 2,
+    lineWidth: -1
+  });
+}
+
+/**
+ * Read YAML file
+ * 
+ * @param {string} filePath - YAML file path
+ * @returns {Promise<Object>}
+ */
+async function readYAML(filePath) {
+  const content = await fileUtils.readFile(filePath);
+  return parse(content);
+}
+
+/**
+ * Write YAML file
+ * 
+ * @param {string} filePath - YAML file path
+ * @param {Object} data - Data to write
+ * @returns {Promise<void>}
+ */
+async function writeYAML(filePath, data) {
+  const yamlString = dump(data);
+  await fileUtils.writeFile(filePath, yamlString);
+}
+
+/**
+ * Extract YAML frontmatter from markdown
+ * 
+ * @param {string} markdownContent - Markdown content
+ * @returns {{frontmatter: Object | null, content: string}}
+ */
+function extractFrontmatter(markdownContent) {
+  const frontmatterRegex = /^---\n([\s\S]+?)\n---\n([\s\S]*)$/;
+  const match = markdownContent.match(frontmatterRegex);
+  
+  if (!match) {
+    return {
+      frontmatter: null,
+      content: markdownContent
+    };
+  }
+  
+  return {
+    frontmatter: parse(match[1]),
+    content: match[2]
+  };
+}
+
+module.exports = {
+  parse,
+  dump,
+  readYAML,
+  writeYAML,
+  extractFrontmatter
+};

package/lib/yanstaller/agent-launcher.js

@@ -0,0 +1,348 @@
+/**
+ * AGENT LAUNCHER Module
+ * 
+ * Launches specialist agents using native platform commands.
+ * Each platform has its own invocation syntax.
+ * 
+ * @module yanstaller/agent-launcher
+ */
+
+const { execSync, spawn } = require('child_process');
+const logger = require('../utils/logger');
+
+/**
+ * @typedef {Object} LaunchOptions
+ * @property {string} agent - Agent name (e.g., 'claude', 'marc')
+ * @property {string} platform - Platform ID (e.g., 'copilot-cli', 'claude')
+ * @property {string} [prompt] - Initial prompt/action
+ * @property {string} [model] - Model to use
+ * @property {Object} [config] - Additional config
+ */
+
+/**
+ * @typedef {Object} LaunchResult
+ * @property {boolean} success
+ * @property {string} method - How agent was launched
+ * @property {string} [output] - Command output
+ * @property {string} [error] - Error message if failed
+ */
+
+/**
+ * Platform-specific launch configurations
+ */
+const LAUNCH_CONFIGS = {
+  'copilot-cli': {
+    command: 'gh',
+    args: (agent, options) => {
+      const args = ['copilot'];
+      
+      // Use @agent syntax if available
+      if (agent) {
+        args.push(`@bmad-agent-${agent}`);
+      }
+      
+      if (options.prompt) {
+        args.push(options.prompt);
+      }
+      
+      return args;
+    },
+    checkAvailable: () => {
+      try {
+        execSync('which gh', { stdio: 'ignore' });
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  },
+  
+  'claude': {
+    command: 'claude',
+    args: (agent, options = {}) => {
+      const args = [];
+      
+      // Agent specification
+      if (agent) {
+        args.push('--agent', agent);
+      }
+      
+      // Model selection
+      if (options.model) {
+        args.push('--model', options.model);
+      }
+      
+      // System prompt for context (before positional prompt)
+      if (options.systemPrompt) {
+        args.push('--system-prompt', options.systemPrompt);
+      }
+      
+      // MCP config if needed
+      if (options.mcpConfig) {
+        args.push('--mcp-config', options.mcpConfig);
+      }
+      
+      // Prompt as POSITIONAL argument (not --prompt)
+      // Must come AFTER all flags
+      if (options.prompt) {
+        args.push(options.prompt);
+      }
+      
+      return args;
+    },
+    checkAvailable: () => {
+      try {
+        execSync('which claude', { stdio: 'ignore' });
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  },
+  
+  'codex': {
+    command: 'codex',
+    args: (agent, options = {}) => {
+      const args = [];
+      
+      // Codex uses "skills" not "agents"
+      // Format: codex skill <skill-name> [prompt]
+      
+      if (agent) {
+        args.push('skill', `bmad-${agent}`);
+      }
+      
+      // Prompt as positional argument
+      if (options.prompt) {
+        args.push(options.prompt);
+      }
+      
+      // Model selection (if Codex supports it)
+      if (options.model) {
+        args.push('--model', options.model);
+      }
+      
+      return args;
+    },
+    checkAvailable: () => {
+      try {
+        execSync('which codex', { stdio: 'ignore' });
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  }
+};
+
+/**
+ * Launch agent using native platform command
+ * 
+ * @param {LaunchOptions} options - Launch options
+ * @returns {Promise<LaunchResult>}
+ */
+async function launch(options) {
+  const { agent, platform, prompt, model, config } = options;
+  
+  const platformConfig = LAUNCH_CONFIGS[platform];
+  
+  if (!platformConfig) {
+    return {
+      success: false,
+      method: 'unsupported',
+      error: `Platform ${platform} not supported for native launch`
+    };
+  }
+  
+  // Check if platform command is available
+  if (!platformConfig.checkAvailable()) {
+    return {
+      success: false,
+      method: 'command-not-found',
+      error: `Command '${platformConfig.command}' not found in PATH`
+    };
+  }
+  
+  // Build command arguments
+  const args = platformConfig.args(agent, {
+    prompt,
+    model,
+    systemPrompt: config ? config.systemPrompt : undefined,
+    mcpConfig: config ? config.mcpConfig : undefined
+  });
+  
+  const fullCommand = `${platformConfig.command} ${args.join(' ')}`;
+  
+  logger.info(`Launching agent via: ${fullCommand}`);
+  
+  try {
+    // Launch in interactive mode (inherit stdio)
+    const result = spawn(platformConfig.command, args, {
+      stdio: 'inherit',
+      shell: true
+    });
+    
+    return new Promise((resolve) => {
+      result.on('close', (code) => {
+        if (code === 0) {
+          resolve({
+            success: true,
+            method: 'native-interactive',
+            output: `Agent launched successfully via ${platform}`
+          });
+        } else {
+          resolve({
+            success: false,
+            method: 'native-interactive',
+            error: `Agent exited with code ${code}`
+          });
+        }
+      });
+      
+      result.on('error', (error) => {
+        resolve({
+          success: false,
+          method: 'native-interactive',
+          error: error.message
+        });
+      });
+    });
+  } catch (error) {
+    return {
+      success: false,
+      method: 'native-interactive',
+      error: error.message
+    };
+  }
+}
+
+/**
+ * Launch agent with specific prompt (non-interactive)
+ * 
+ * Useful for automation or scripted workflows.
+ * 
+ * @param {LaunchOptions} options - Launch options
+ * @returns {Promise<LaunchResult>}
+ */
+async function launchWithPrompt(options) {
+  const { agent, platform, prompt, model, config } = options;
+  
+  if (!prompt) {
+    throw new Error('Prompt required for non-interactive launch');
+  }
+  
+  const platformConfig = LAUNCH_CONFIGS[platform];
+  
+  if (!platformConfig) {
+    return {
+      success: false,
+      method: 'unsupported',
+      error: `Platform ${platform} not supported`
+    };
+  }
+  
+  if (!platformConfig.checkAvailable()) {
+    return {
+      success: false,
+      method: 'command-not-found',
+      error: `Command '${platformConfig.command}' not found`
+    };
+  }
+  
+  const args = platformConfig.args(agent, {
+    prompt,
+    model,
+    systemPrompt: config ? config.systemPrompt : undefined
+  });
+  
+  // Add --print flag for Claude to get output
+  if (platform === 'claude') {
+    args.unshift('--print');
+  }
+  
+  const fullCommand = `${platformConfig.command} ${args.join(' ')}`;
+  
+  logger.info(`Executing: ${fullCommand}`);
+  
+  try {
+    const output = execSync(fullCommand, {
+      encoding: 'utf8',
+      maxBuffer: 10 * 1024 * 1024 // 10MB
+    });
+    
+    return {
+      success: true,
+      method: 'native-print',
+      output: output.trim()
+    };
+  } catch (error) {
+    return {
+      success: false,
+      method: 'native-print',
+      error: error.message
+    };
+  }
+}
+
+/**
+ * Generate launch instructions for manual invocation
+ * 
+ * Used as fallback when native launch isn't possible.
+ * 
+ * @param {LaunchOptions} options - Launch options
+ * @returns {string} - Human-readable instructions
+ */
+function getLaunchInstructions(options) {
+  const { agent, platform, prompt, model } = options;
+  
+  const platformConfig = LAUNCH_CONFIGS[platform];
+  
+  if (!platformConfig) {
+    return `Platform ${platform} not yet supported for automated launch.\nPlease activate the agent manually.`;
+  }
+  
+  const args = platformConfig.args(agent, { prompt, model });
+  const command = `${platformConfig.command} ${args.join(' ')}`;
+  
+  return `
+To activate the agent, run:
+
+  ${command}
+
+Or in interactive mode:
+  ${platformConfig.command}
+  Then: @bmad-agent-${agent}
+`;
+}
+
+/**
+ * Check if platform supports native agent launch
+ * 
+ * @param {string} platform - Platform ID
+ * @returns {boolean}
+ */
+function supportsNativeLaunch(platform) {
+  const config = LAUNCH_CONFIGS[platform];
+  if (!config) return false;
+  return config.checkAvailable();
+}
+
+/**
+ * Get available platforms for native launch
+ * 
+ * @returns {string[]} - List of platform IDs
+ */
+function getAvailablePlatforms() {
+  return Object.keys(LAUNCH_CONFIGS).filter(platform => {
+    const config = LAUNCH_CONFIGS[platform];
+    return config.checkAvailable();
+  });
+}
+
+module.exports = {
+  launch,
+  launchWithPrompt,
+  getLaunchInstructions,
+  supportsNativeLaunch,
+  getAvailablePlatforms
+};

package/lib/yanstaller/backuper.js

@@ -0,0 +1,108 @@
+/**
+ * BACKUPER Module
+ * 
+ * Backs up and restores _bmad/ directory.
+ * 
+ * Phase 6: 24h development
+ * 
+ * @module yanstaller/backuper
+ */
+
+const path = require('path');
+const fileUtils = require('../utils/file-utils');
+
+/**
+ * @typedef {Object} BackupResult
+ * @property {boolean} success
+ * @property {string} backupPath - Path to backup directory
+ * @property {number} filesBackedUp
+ * @property {number} size - Backup size in bytes
+ */
+
+/**
+ * Backup _bmad/ directory
+ * 
+ * @param {string} bmadPath - Path to _bmad/ directory
+ * @returns {Promise<BackupResult>}
+ */
+async function backup(bmadPath) {
+  const timestamp = Date.now();
+  const backupPath = `${bmadPath}.backup-${timestamp}`;
+  
+  try {
+    // TODO: Copy entire _bmad/ to backup path
+    // await fileUtils.copy(bmadPath, backupPath);
+    
+    return {
+      success: true,
+      backupPath,
+      filesBackedUp: 0,
+      size: 0
+    };
+  } catch (error) {
+    throw new BackupError(`Failed to backup ${bmadPath}`, { cause: error });
+  }
+}
+
+/**
+ * Restore from backup
+ * 
+ * @param {string} backupPath - Path to backup directory
+ * @param {string} targetPath - Target restoration path
+ * @returns {Promise<void>}
+ */
+async function restore(backupPath, targetPath) {
+  // TODO: Remove current _bmad/, copy backup to target
+  // await fileUtils.remove(targetPath);
+  // await fileUtils.copy(backupPath, targetPath);
+}
+
+/**
+ * List available backups
+ * 
+ * @param {string} projectRoot - Project root directory
+ * @returns {Promise<string[]>} - Array of backup paths
+ */
+async function listBackups(projectRoot) {
+  // TODO: Find all _bmad.backup-* directories
+  return [];
+}
+
+/**
+ * Clean old backups (keep last N)
+ * 
+ * @param {string} projectRoot - Project root directory
+ * @param {number} keep - Number of backups to keep
+ * @returns {Promise<number>} - Number of backups deleted
+ */
+async function cleanOldBackups(projectRoot, keep = 3) {
+  // TODO: Sort by timestamp, delete oldest
+  return 0;
+}
+
+/**
+ * Get backup size
+ * 
+ * @param {string} backupPath - Path to backup directory
+ * @returns {Promise<number>} - Size in bytes
+ */
+async function getBackupSize(backupPath) {
+  // TODO: Recursively calculate directory size
+  return 0;
+}
+
+class BackupError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = 'BackupError';
+  }
+}
+
+module.exports = {
+  backup,
+  restore,
+  listBackups,
+  cleanOldBackups,
+  getBackupSize,
+  BackupError
+};

package/lib/yanstaller/detector.js

@@ -0,0 +1,141 @@
+/**
+ * DETECTOR Module
+ * 
+ * Detects OS, Node.js version, Git, and installed platforms.
+ * 
+ * Phase 1: 40h development
+ * 
+ * @module yanstaller/detector
+ */
+
+const osDetector = require('../utils/os-detector');
+const nodeDetector = require('../utils/node-detector');
+const gitDetector = require('../utils/git-detector');
+const platforms = require('../platforms');
+
+/**
+ * @typedef {Object} DetectionResult
+ * @property {string} os - 'windows' | 'linux' | 'macos'
+ * @property {string} osVersion - e.g., '11' for Windows 11
+ * @property {string} nodeVersion - e.g., '18.19.0'
+ * @property {boolean} hasGit
+ * @property {string} [gitVersion] - e.g., '2.43.0'
+ * @property {PlatformInfo[]} platforms - Detected platforms
+ */
+
+/**
+ * @typedef {Object} PlatformInfo
+ * @property {string} name - 'copilot-cli' | 'vscode' | 'claude' | 'codex'
+ * @property {boolean} detected
+ * @property {string} [path] - Installation path if detected
+ * @property {string} [version] - Version if detected
+ */
+
+const logger = require('../utils/logger');
+
+/**
+ * Detect full environment
+ * 
+ * Runs parallel detection for speed.
+ * Non-blocking: platform detection failures are caught and logged.
+ * 
+ * @returns {Promise<DetectionResult>}
+ */
+async function detect() {
+  // Parallel detection for speed (Mantra #7 KISS)
+  const [osInfo, nodeVersion, gitInfo] = await Promise.all([
+    osDetector.detect(),
+    Promise.resolve(nodeDetector.detect()), // Sync wrapped in Promise
+    gitDetector.detect()
+  ]);
+  
+  // Platform detection with timeout protection
+  const platformNames = ['copilot-cli', 'vscode', 'claude', 'codex'];
+  const platformsInfo = await Promise.all(
+    platformNames.map(name => detectPlatform(name))
+  );
+  
+  // Check if ALL platforms failed
+  const allFailed = platformsInfo.every(p => !p.detected);
+  if (allFailed) {
+    const errors = platformsInfo
+      .filter(p => p.error)
+      .map(p => `${p.name}: ${p.error}`)
+      .join(', ');
+    if (errors) {
+      logger.warn(`0/4 platforms detected. Errors: [${errors}]`);
+    }
+  }
+  
+  return {
+    os: osInfo.name,
+    osVersion: osInfo.version,
+    nodeVersion,
+    hasGit: gitInfo.installed,
+    gitVersion: gitInfo.version,
+    platforms: platformsInfo
+  };
+}
+
+/**
+ * Check if Node.js version meets minimum requirement
+ * 
+ * Handles version suffixes (-beta, -rc1) by stripping them.
+ * 
+ * @param {string} currentVersion - e.g., '18.19.0'
+ * @param {string} requiredVersion - e.g., '18.0.0'
+ * @returns {boolean}
+ */
+function isNodeVersionValid(currentVersion, requiredVersion) {
+  return nodeDetector.meetsRequirement(currentVersion, requiredVersion);
+}
+
+/**
+ * Detect specific platform
+ * 
+ * Non-blocking: errors are caught and returned in result.
+ * 
+ * @param {string} platformName - 'copilot-cli' | 'vscode' | 'claude' | 'codex'
+ * @returns {Promise<PlatformInfo>}
+ */
+async function detectPlatform(platformName) {
+  const platform = platforms[platformName];
+  if (!platform) {
+    throw new Error(`Unknown platform: ${platformName}`);
+  }
+  
+  try {
+    const detected = await platform.detect();
+    
+    // Handle timeout response format (object with detected + error)
+    if (typeof detected === 'object' && 'error' in detected) {
+      logger.warn(`Platform ${platformName} detection failed: ${detected.error}`);
+      return {
+        name: platformName,
+        detected: false,
+        error: detected.error
+      };
+    }
+    
+    return {
+      name: platformName,
+      detected: !!detected,
+      path: detected ? platform.getPath() : undefined
+    };
+  } catch (error) {
+    // Non-blocking: platform detection failure shouldn't crash detection
+    // Error UX: Log warning and include in report for user visibility
+    logger.warn(`Platform ${platformName} detection failed: ${error.message}`);
+    return {
+      name: platformName,
+      detected: false,
+      error: error.message
+    };
+  }
+}
+
+module.exports = {
+  detect,
+  isNodeVersionValid,
+  detectPlatform
+};