create-byan-agent 2.0.1 → 2.1.0

package/install/lib/utils/logger.js

@@ -0,0 +1,64 @@
+/**
+ * Logger Utility
+ * 
+ * Wrapper around chalk and console for colored logging.
+ * 
+ * @module utils/logger
+ */
+
+const chalk = require('chalk');
+
+/**
+ * Log info message
+ * 
+ * @param {string} message - Message to log
+ */
+function info(message) {
+  console.log(chalk.blue('ℹ'), message);
+}
+
+/**
+ * Log success message
+ * 
+ * @param {string} message - Message to log
+ */
+function success(message) {
+  console.log(chalk.green('✓'), message);
+}
+
+/**
+ * Log warning message
+ * 
+ * @param {string} message - Message to log
+ */
+function warn(message) {
+  console.log(chalk.yellow('⚠'), message);
+}
+
+/**
+ * Log error message
+ * 
+ * @param {string} message - Message to log
+ */
+function error(message) {
+  console.error(chalk.red('✖'), message);
+}
+
+/**
+ * Log debug message (only if DEBUG env var set)
+ * 
+ * @param {string} message - Message to log
+ */
+function debug(message) {
+  if (process.env.DEBUG) {
+    console.log(chalk.gray('[DEBUG]'), message);
+  }
+}
+
+module.exports = {
+  info,
+  success,
+  warn,
+  error,
+  debug
+};

package/install/lib/utils/node-detector.js

@@ -0,0 +1,58 @@
+/**
+ * Node.js Detector Utility
+ * 
+ * Detects Node.js version.
+ * 
+ * @module utils/node-detector
+ */
+
+/**
+ * Detect Node.js version
+ * 
+ * @returns {string} - Version string (e.g., '18.19.0')
+ */
+function detect() {
+  return process.version.slice(1); // Remove 'v' prefix
+}
+
+/**
+ * Compare two semver versions
+ * 
+ * Strips version suffixes (-beta, -rc1, etc.) before comparison.
+ * 
+ * @param {string} version1 - First version
+ * @param {string} version2 - Second version
+ * @returns {number} - -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+ */
+function compareVersions(version1, version2) {
+  // Strip suffixes: '18.0.0-beta' → '18.0.0'
+  const cleanV1 = version1.replace(/-.*$/, '');
+  const cleanV2 = version2.replace(/-.*$/, '');
+  
+  const v1Parts = cleanV1.split('.').map(Number);
+  const v2Parts = cleanV2.split('.').map(Number);
+  
+  for (let i = 0; i < 3; i++) {
+    if (v1Parts[i] > v2Parts[i]) return 1;
+    if (v1Parts[i] < v2Parts[i]) return -1;
+  }
+  
+  return 0;
+}
+
+/**
+ * Check if Node version meets minimum requirement
+ * 
+ * @param {string} currentVersion - Current Node version
+ * @param {string} requiredVersion - Required Node version
+ * @returns {boolean}
+ */
+function meetsRequirement(currentVersion, requiredVersion) {
+  return compareVersions(currentVersion, requiredVersion) >= 0;
+}
+
+module.exports = {
+  detect,
+  compareVersions,
+  meetsRequirement
+};

package/install/lib/utils/os-detector.js

@@ -0,0 +1,74 @@
+/**
+ * OS Detector Utility
+ * 
+ * Detects operating system and version.
+ * 
+ * @module utils/os-detector
+ */
+
+const os = require('os');
+
+/**
+ * Detect operating system
+ * 
+ * @returns {{name: string, version: string, platform: string}}
+ */
+function detect() {
+  const platform = os.platform();
+  const release = os.release();
+  
+  let name;
+  switch (platform) {
+    case 'win32':
+      name = 'windows';
+      break;
+    case 'darwin':
+      name = 'macos';
+      break;
+    case 'linux':
+      name = 'linux';
+      break;
+    default:
+      name = 'unknown';
+  }
+  
+  return {
+    name,
+    version: release,
+    platform
+  };
+}
+
+/**
+ * Check if running on Windows
+ * 
+ * @returns {boolean}
+ */
+function isWindows() {
+  return os.platform() === 'win32';
+}
+
+/**
+ * Check if running on macOS
+ * 
+ * @returns {boolean}
+ */
+function isMacOS() {
+  return os.platform() === 'darwin';
+}
+
+/**
+ * Check if running on Linux
+ * 
+ * @returns {boolean}
+ */
+function isLinux() {
+  return os.platform() === 'linux';
+}
+
+module.exports = {
+  detect,
+  isWindows,
+  isMacOS,
+  isLinux
+};

package/install/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/install/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/install/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
+};

package/install/lib/yanstaller/index.js

@@ -0,0 +1,93 @@
+/**
+ * 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 logger = require('../utils/logger');
+
+/**
+ * @typedef {Object} YanInstallerOptions
+ * @property {boolean} [yes] - Skip confirmations (--yes flag)
+ * @property {string} [mode] - Installation mode: 'full' | 'minimal' | 'custom'
+ * @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 {
+    // TODO: Implement Phase 1-8 orchestration
+    // 1. Detect environment
+    // 2. Validate Node version (FAIL FAST)
+    // 3. Recommend configuration
+    // 4. Run interview (unless --yes)
+    // 5. Backup existing installation
+    // backupPath = await backuper.backup('_bmad');
+    // 6. Install agents
+    // 7. Validate installation
+    // 8. Show post-install wizard
+  } 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
+};