helloagents 1.0.0

package/lib/index.js

@@ -0,0 +1,297 @@
+/**
+ * Index - Main flow implementation
+ */
+
+'use strict';
+
+const path = require('path');
+const fsPromises = require('fs').promises;
+
+const { getHomeDir, getSourcePaths, getTargetPaths, fileExists, dirExists, readFileContent, rmrf, ensureDir } = require('./utils');
+const { detectDefaultPlatform, getDefaultLang } = require('./defaults');
+const { createReadline, askPlatform, askLanguage, askConfigConflict, askSkillsConflict } = require('./prompts');
+const { backupFile, backupDir } = require('./backup');
+const { checkConfigFile, checkSkillsDir, checkNewFile, backupNewFileIfDifferent, resolveConflict } = require('./conflict');
+const { copyFile, copyDir, writeNewFile, listFiles } = require('./copy');
+const { createOutput, printWelcome, printSummary, printDryRunSummary, printRecoveryInstructions, info, success, warn, error, log, newline, header, divider, operation } = require('./output');
+
+/**
+ * Main run function
+ * @param {Object} options - CLI options
+ * @param {Object} deps - Dependencies for testing
+ * @returns {Promise<void>}
+ */
+async function run(options, deps = {}) {
+  const fsModule = deps.fs || fsPromises;
+  const homeDir = getHomeDir(deps);
+  const output = deps.output || createOutput(deps);
+
+  // Track stats and backups
+  const stats = { write: 0, backup: 0, newFile: 0, skip: 0 };
+  const backups = [];
+
+  // Readline interface (only created if needed)
+  let rl = null;
+
+  try {
+    // Print welcome message
+    output.printWelcome();
+
+    // Determine platform
+    let platform = options.platform;
+    let platformReason = '';
+
+    if (!platform) {
+      if (options.yes) {
+        // Auto-detect in -y mode
+        const detected = await detectDefaultPlatform(deps);
+        platform = detected.platform;
+        platformReason = detected.reason;
+        output.info(`[默认] ${platformReason}，使用 ${platform === 'claude' ? 'Claude Code' : 'Codex'}`);
+      } else {
+        // Interactive mode
+        rl = createReadline();
+        const detected = await detectDefaultPlatform(deps);
+        platform = await askPlatform(rl, detected.platform, detected.reason);
+      }
+    } else {
+      output.info(`使用指定平台: ${platform === 'claude' ? 'Claude Code' : 'Codex'}`);
+    }
+
+    // Determine language
+    let lang = options.lang;
+
+    if (!lang) {
+      if (options.yes) {
+        // Use default in -y mode
+        const defaultLang = getDefaultLang();
+        lang = defaultLang.lang;
+        output.info(`[默认] 使用语言: ${lang === 'cn' ? '中文' : 'English'}`);
+      } else {
+        // Interactive mode
+        if (!rl) {
+          rl = createReadline();
+        }
+        const defaultLang = getDefaultLang();
+        lang = await askLanguage(rl, defaultLang.lang);
+      }
+    } else {
+      output.info(`使用指定语言: ${lang === 'cn' ? '中文' : 'English'}`);
+    }
+
+    // Get source and target paths
+    const sourcePaths = getSourcePaths(platform, lang);
+    const targetPaths = getTargetPaths(platform, deps);
+
+    // Validate source files exist
+    const sourceConfigExists = await fileExists(sourcePaths.configFile, deps);
+    const sourceSkillsExists = await dirExists(sourcePaths.skillsDir, deps);
+
+    if (!sourceConfigExists) {
+      throw new Error(`源配置文件不存在: ${sourcePaths.configFile}`);
+    }
+
+    if (!sourceSkillsExists) {
+      throw new Error(`源技能目录不存在: ${sourcePaths.skillsDir}`);
+    }
+
+    // Ensure target directory exists
+    await ensureDir(targetPaths.targetDir, deps);
+
+    // Dry run mode
+    if (options.dryRun) {
+      output.header('[Dry Run] 以下操作不会实际执行：');
+
+      // Check config file
+      if (!options.skillsOnly) {
+        const configExists = await checkConfigFile(targetPaths.configFile, deps);
+        const configFileName = platform === 'claude' ? 'CLAUDE.md' : 'AGENTS.md';
+
+        if (configExists) {
+          if (options.overwrite) {
+            output.operation(sourcePaths.configFile, targetPaths.configFile, '备份后覆盖');
+            stats.backup++;
+            stats.write++;
+          } else {
+            output.operation(sourcePaths.configFile, targetPaths.newFile, `生成 .helloagents.new（${configFileName} 已存在）`);
+            stats.newFile++;
+          }
+        } else {
+          output.operation(sourcePaths.configFile, targetPaths.configFile, '写入');
+          stats.write++;
+        }
+      }
+
+      // Check skills directory
+      const skillsExists = await checkSkillsDir(targetPaths.skillsDir, deps);
+
+      if (skillsExists) {
+        if (options.noBackup) {
+          output.operation(sourcePaths.skillsDir, targetPaths.skillsDir, '直接覆盖');
+        } else {
+          output.operation(sourcePaths.skillsDir, targetPaths.skillsDir, '备份后覆盖');
+          stats.backup++;
+        }
+        stats.write++;
+      } else {
+        output.operation(sourcePaths.skillsDir, targetPaths.skillsDir, '写入');
+        stats.write++;
+      }
+
+      output.printDryRunSummary(stats);
+      return;
+    }
+
+    // Process config file (unless --skills-only)
+    if (!options.skillsOnly) {
+      const configExists = await checkConfigFile(targetPaths.configFile, deps);
+      const configFileName = platform === 'claude' ? 'CLAUDE.md' : 'AGENTS.md';
+
+      if (configExists) {
+        // Determine action
+        let action;
+        if (options.yes) {
+          action = resolveConflict(options, 'config');
+        } else {
+          if (!rl) {
+            rl = createReadline();
+          }
+          action = await askConfigConflict(rl, configFileName);
+        }
+
+        switch (action) {
+          case 'new': {
+            // Check if .new file already exists
+            const sourceContent = await readFileContent(sourcePaths.configFile, deps);
+            const newFileStatus = await checkNewFile(targetPaths.newFile, sourceContent, deps);
+
+            if (newFileStatus.exists) {
+              if (newFileStatus.sameContent) {
+                output.info(`.helloagents.new 已是最新，跳过`);
+                stats.skip++;
+              } else {
+                // Backup existing .new file
+                const newBackupPath = await backupNewFileIfDifferent(targetPaths.newFile, deps);
+                backups.push(newBackupPath);
+                output.info(`已备份旧的 .helloagents.new 至 ${path.basename(newBackupPath)}`);
+                stats.backup++;
+
+                // Write new .new file
+                await writeNewFile(sourcePaths.configFile, targetPaths.newFile, deps);
+                output.success(`已生成 .helloagents.new`);
+                stats.newFile++;
+              }
+            } else {
+              await writeNewFile(sourcePaths.configFile, targetPaths.newFile, deps);
+              output.success(`已生成 .helloagents.new`);
+              stats.newFile++;
+            }
+            break;
+          }
+
+          case 'backup': {
+            const backupPath = await backupFile(targetPaths.configFile, deps);
+            backups.push(backupPath);
+            output.info(`已备份 ${configFileName} 至 ${path.basename(backupPath)}`);
+            stats.backup++;
+
+            await copyFile(sourcePaths.configFile, targetPaths.configFile, deps);
+            output.success(`已覆盖 ${configFileName}`);
+            stats.write++;
+            break;
+          }
+
+          case 'overwrite': {
+            await copyFile(sourcePaths.configFile, targetPaths.configFile, deps);
+            output.success(`已覆盖 ${configFileName}`);
+            stats.write++;
+            break;
+          }
+
+          case 'skip': {
+            output.info(`跳过 ${configFileName}`);
+            stats.skip++;
+            break;
+          }
+        }
+      } else {
+        // No conflict, just copy
+        await copyFile(sourcePaths.configFile, targetPaths.configFile, deps);
+        output.success(`已写入 ${configFileName}`);
+        stats.write++;
+      }
+    }
+
+    // Process skills directory
+    const skillsExists = await checkSkillsDir(targetPaths.skillsDir, deps);
+
+    if (skillsExists) {
+      // Determine action
+      let action;
+      if (options.yes) {
+        action = resolveConflict(options, 'skills');
+      } else {
+        if (!rl) {
+          rl = createReadline();
+        }
+        action = await askSkillsConflict(rl);
+      }
+
+      switch (action) {
+        case 'backup': {
+          const backupPath = await backupDir(targetPaths.skillsDir, deps);
+          backups.push(backupPath);
+          output.info(`已备份 skills/helloagents 至 ${path.basename(backupPath)}`);
+          stats.backup++;
+
+          // Remove old directory and copy new
+          await rmrf(targetPaths.skillsDir, deps);
+          await copyDir(sourcePaths.skillsDir, targetPaths.skillsDir, deps);
+          output.success(`已更新 skills/helloagents`);
+          stats.write++;
+          break;
+        }
+
+        case 'overwrite': {
+          await rmrf(targetPaths.skillsDir, deps);
+          await copyDir(sourcePaths.skillsDir, targetPaths.skillsDir, deps);
+          output.success(`已覆盖 skills/helloagents`);
+          stats.write++;
+          break;
+        }
+
+        case 'skip': {
+          output.info(`跳过 skills/helloagents`);
+          stats.skip++;
+          break;
+        }
+      }
+    } else {
+      // No conflict, ensure parent directory exists and copy
+      await ensureDir(path.dirname(targetPaths.skillsDir), deps);
+      await copyDir(sourcePaths.skillsDir, targetPaths.skillsDir, deps);
+      output.success(`已写入 skills/helloagents`);
+      stats.write++;
+    }
+
+    // Print summary
+    output.printSummary(stats, backups);
+
+  } catch (err) {
+    // Print recovery instructions if we have backups
+    if (backups.length > 0) {
+      output.printRecoveryInstructions(err.message, backups, options.platform || 'claude');
+    }
+    throw err;
+
+  } finally {
+    // Close readline if opened
+    if (rl) {
+      rl.close();
+    }
+  }
+}
+
+module.exports = {
+  run,
+};

package/lib/output.js

@@ -0,0 +1,220 @@
+/**
+ * Output - Formatted output with ANSI colors
+ */
+
+'use strict';
+
+// Check if colors should be disabled
+const NO_COLOR = process.env.NO_COLOR !== undefined || process.argv.includes('--no-color');
+
+// ANSI color codes
+const colors = {
+  reset: NO_COLOR ? '' : '\x1b[0m',
+  bold: NO_COLOR ? '' : '\x1b[1m',
+  dim: NO_COLOR ? '' : '\x1b[2m',
+
+  // Foreground colors
+  red: NO_COLOR ? '' : '\x1b[31m',
+  green: NO_COLOR ? '' : '\x1b[32m',
+  yellow: NO_COLOR ? '' : '\x1b[33m',
+  blue: NO_COLOR ? '' : '\x1b[34m',
+  magenta: NO_COLOR ? '' : '\x1b[35m',
+  cyan: NO_COLOR ? '' : '\x1b[36m',
+  white: NO_COLOR ? '' : '\x1b[37m',
+};
+
+// Symbols
+const symbols = {
+  success: NO_COLOR ? '[OK]' : '✔',
+  error: NO_COLOR ? '[ERROR]' : '✖',
+  warning: NO_COLOR ? '[WARN]' : '⚠',
+  info: NO_COLOR ? '[INFO]' : 'ℹ',
+  arrow: NO_COLOR ? '->' : '→',
+  bullet: NO_COLOR ? '*' : '•',
+};
+
+/**
+ * Create output functions with injectable stdout
+ * @param {Object} deps - Dependencies
+ * @returns {Object} Output functions
+ */
+function createOutput(deps = {}) {
+  const stdout = deps.stdout || process.stdout;
+  const stderr = deps.stderr || process.stderr;
+
+  function write(stream, message) {
+    stream.write(message + '\n');
+  }
+
+  return {
+    /**
+     * Print success message
+     * @param {string} message
+     */
+    success(message) {
+      write(stdout, `${colors.green}${symbols.success}${colors.reset} ${message}`);
+    },
+
+    /**
+     * Print error message
+     * @param {string} message
+     */
+    error(message) {
+      write(stderr, `${colors.red}${symbols.error}${colors.reset} ${message}`);
+    },
+
+    /**
+     * Print warning message
+     * @param {string} message
+     */
+    warn(message) {
+      write(stdout, `${colors.yellow}${symbols.warning}${colors.reset} ${message}`);
+    },
+
+    /**
+     * Print info message
+     * @param {string} message
+     */
+    info(message) {
+      write(stdout, `${colors.cyan}${symbols.info}${colors.reset} ${message}`);
+    },
+
+    /**
+     * Print plain message
+     * @param {string} message
+     */
+    log(message) {
+      write(stdout, message);
+    },
+
+    /**
+     * Print empty line
+     */
+    newline() {
+      write(stdout, '');
+    },
+
+    /**
+     * Print header
+     * @param {string} title
+     */
+    header(title) {
+      write(stdout, `\n${colors.bold}${colors.cyan}${title}${colors.reset}\n`);
+    },
+
+    /**
+     * Print divider
+     */
+    divider() {
+      write(stdout, `${colors.dim}${'─'.repeat(40)}${colors.reset}`);
+    },
+
+    /**
+     * Print operation item
+     * @param {string} source
+     * @param {string} target
+     * @param {string} action
+     */
+    operation(source, target, action) {
+      write(stdout, `\n源: ${colors.cyan}${source}${colors.reset}`);
+      write(stdout, `  ${symbols.arrow} 目标: ${colors.cyan}${target}${colors.reset}`);
+      write(stdout, `  ${symbols.arrow} 操作: ${action}`);
+    },
+
+    /**
+     * Print dry-run summary
+     * @param {Object} stats - { write, backup, newFile, skip }
+     */
+    printDryRunSummary(stats) {
+      write(stdout, '');
+      write(stdout, `${colors.dim}${'─'.repeat(40)}${colors.reset}`);
+      write(stdout, `汇总: 写入 ${stats.write || 0} | 备份 ${stats.backup || 0} | 生成.new ${stats.newFile || 0} | 跳过 ${stats.skip || 0}`);
+      write(stdout, '');
+      write(stdout, `${colors.yellow}${symbols.warning}${colors.reset}  Dry Run 模式：不会做任何写入`);
+    },
+
+    /**
+     * Print final summary
+     * @param {Object} stats - { write, backup, newFile, skip }
+     * @param {Array} backups - List of backup paths
+     */
+    printSummary(stats, backups = []) {
+      write(stdout, '');
+      write(stdout, `${colors.dim}${'─'.repeat(40)}${colors.reset}`);
+      write(stdout, `${colors.green}${symbols.success}${colors.reset} 安装完成！`);
+      write(stdout, '');
+      write(stdout, `汇总: 写入 ${stats.write || 0} | 备份 ${stats.backup || 0} | 生成.new ${stats.newFile || 0} | 跳过 ${stats.skip || 0}`);
+
+      if (backups.length > 0) {
+        write(stdout, '');
+        write(stdout, `${colors.cyan}已创建的备份:${colors.reset}`);
+        for (const backup of backups) {
+          write(stdout, `  ${symbols.bullet} ${backup}`);
+        }
+      }
+    },
+
+    /**
+     * Print welcome message
+     */
+    printWelcome() {
+      write(stdout, '');
+      write(stdout, `${colors.bold}${colors.cyan}HelloAGENTS${colors.reset} - AI编程模块化技能系统`);
+      write(stdout, `${colors.dim}配置工具 v1.0.0${colors.reset}`);
+      write(stdout, '');
+    },
+
+    /**
+     * Print recovery instructions on failure
+     * @param {string} errorMessage
+     * @param {Array} backups - List of backup paths
+     * @param {string} platform - 'claude' or 'codex'
+     */
+    printRecoveryInstructions(errorMessage, backups, platform) {
+      const configDir = platform === 'claude' ? '.claude' : '.codex';
+
+      write(stderr, '');
+      write(stderr, `${colors.red}${symbols.error} 复制失败: ${errorMessage}${colors.reset}`);
+
+      if (backups.length > 0) {
+        write(stderr, '');
+        write(stderr, `${colors.cyan}已创建的备份:${colors.reset}`);
+        for (const backup of backups) {
+          write(stderr, `  ${backup}`);
+        }
+
+        write(stderr, '');
+        write(stderr, `${colors.cyan}恢复命令（如需回滚）:${colors.reset}`);
+        write(stderr, '');
+        write(stderr, `# macOS/Linux`);
+        for (const backup of backups) {
+          const original = backup.replace(/\.backup-\d{8}-\d{6}\/?$/, '');
+          const name = original.split('/').pop() || original.split('\\').pop();
+          write(stderr, `rm -rf ${original}`);
+          write(stderr, `mv ${backup} ${original}`);
+        }
+        write(stderr, '');
+        write(stderr, `# Windows PowerShell`);
+        for (const backup of backups) {
+          const original = backup.replace(/\.backup-\d{8}-\d{6}\/?$/, '');
+          const name = original.split('/').pop() || original.split('\\').pop();
+          write(stderr, `Remove-Item "${original}" -Recurse -Force`);
+          write(stderr, `Rename-Item "${backup}" "${name}"`);
+        }
+      }
+
+      write(stderr, '');
+      write(stderr, `请修复问题后重新运行，或使用上述命令手动恢复。`);
+    },
+  };
+}
+
+// Default instance
+const defaultOutput = createOutput();
+
+module.exports = {
+  colors,
+  symbols,
+  createOutput,
+  ...defaultOutput,
+};

package/lib/prompts.js

@@ -0,0 +1,173 @@
+/**
+ * Prompts - Interactive prompts using native readline
+ */
+
+'use strict';
+
+const readline = require('readline');
+
+/**
+ * Create readline interface
+ * @returns {readline.Interface}
+ */
+function createReadline() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+/**
+ * Ask a question and get answer
+ * @param {readline.Interface} rl - Readline interface
+ * @param {string} question - Question to ask
+ * @returns {Promise<string>}
+ */
+function ask(rl, question) {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * Ask for platform selection
+ * @param {readline.Interface} rl - Readline interface
+ * @param {string} defaultPlatform - Default platform
+ * @param {string} reason - Reason for default
+ * @returns {Promise<string>} 'claude' or 'codex'
+ */
+async function askPlatform(rl, defaultPlatform = 'claude', reason = '') {
+  const defaultNum = defaultPlatform === 'claude' ? '1' : '2';
+  const reasonText = reason ? ` (${reason})` : '';
+
+  console.log('');
+  console.log('选择目标平台:');
+  console.log(`  1. Claude Code${defaultPlatform === 'claude' ? ` [默认]${reasonText}` : ''}`);
+  console.log(`  2. Codex${defaultPlatform === 'codex' ? ` [默认]${reasonText}` : ''}`);
+  console.log('');
+
+  const answer = await ask(rl, `请输入选项 (1-2) [${defaultNum}]: `);
+
+  if (answer === '' || answer === defaultNum) {
+    return defaultPlatform;
+  }
+
+  if (answer === '1') {
+    return 'claude';
+  }
+
+  if (answer === '2') {
+    return 'codex';
+  }
+
+  // Invalid input, ask again
+  console.log('无效输入，请输入 1 或 2');
+  return askPlatform(rl, defaultPlatform, reason);
+}
+
+/**
+ * Ask for language selection
+ * @param {readline.Interface} rl - Readline interface
+ * @param {string} defaultLang - Default language
+ * @returns {Promise<string>} 'cn' or 'en'
+ */
+async function askLanguage(rl, defaultLang = 'cn') {
+  const defaultNum = defaultLang === 'cn' ? '1' : '2';
+
+  console.log('');
+  console.log('选择语言版本:');
+  console.log(`  1. 中文${defaultLang === 'cn' ? ' [默认]' : ''}`);
+  console.log(`  2. English${defaultLang === 'en' ? ' [默认]' : ''}`);
+  console.log('');
+
+  const answer = await ask(rl, `请输入选项 (1-2) [${defaultNum}]: `);
+
+  if (answer === '' || answer === defaultNum) {
+    return defaultLang;
+  }
+
+  if (answer === '1') {
+    return 'cn';
+  }
+
+  if (answer === '2') {
+    return 'en';
+  }
+
+  // Invalid input, ask again
+  console.log('无效输入，请输入 1 或 2');
+  return askLanguage(rl, defaultLang);
+}
+
+/**
+ * Ask for config file conflict resolution
+ * @param {readline.Interface} rl - Readline interface
+ * @param {string} fileName - Name of the config file
+ * @returns {Promise<string>} 'new' | 'backup' | 'overwrite' | 'skip'
+ */
+async function askConfigConflict(rl, fileName) {
+  console.log('');
+  console.log(`检测到 ${fileName} 已存在，请选择处理方式:`);
+  console.log('  1. 生成 .helloagents.new 文件（保留原文件）[默认]');
+  console.log('  2. 备份后覆盖');
+  console.log('  3. 直接覆盖（不备份）');
+  console.log('  4. 跳过');
+  console.log('');
+
+  const answer = await ask(rl, '请输入选项 (1-4) [1]: ');
+
+  switch (answer) {
+    case '':
+    case '1':
+      return 'new';
+    case '2':
+      return 'backup';
+    case '3':
+      return 'overwrite';
+    case '4':
+      return 'skip';
+    default:
+      console.log('无效输入，请输入 1-4');
+      return askConfigConflict(rl, fileName);
+  }
+}
+
+/**
+ * Ask for skills directory conflict resolution
+ * @param {readline.Interface} rl - Readline interface
+ * @returns {Promise<string>} 'backup' | 'overwrite' | 'skip'
+ */
+async function askSkillsConflict(rl) {
+  console.log('');
+  console.log('检测到 skills/helloagents 目录已存在，请选择处理方式:');
+  console.log('  1. 备份后覆盖 [默认]');
+  console.log('  2. 直接覆盖（不备份）');
+  console.log('  3. 跳过');
+  console.log('');
+
+  const answer = await ask(rl, '请输入选项 (1-3) [1]: ');
+
+  switch (answer) {
+    case '':
+    case '1':
+      return 'backup';
+    case '2':
+      return 'overwrite';
+    case '3':
+      return 'skip';
+    default:
+      console.log('无效输入，请输入 1-3');
+      return askSkillsConflict(rl);
+  }
+}
+
+module.exports = {
+  createReadline,
+  ask,
+  askPlatform,
+  askLanguage,
+  askConfigConflict,
+  askSkillsConflict,
+};