helloagents 1.0.0

package/bin/cli.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+/**
+ * HelloAGENTS CLI - Entry Point
+ *
+ * CLI tool to configure HelloAGENTS for Claude Code and Codex
+ */
+
+'use strict';
+
+const { parseArgs } = require('../lib/args');
+const { run } = require('../lib/index');
+const { error, info } = require('../lib/output');
+const pkg = require('../package.json');
+
+const HELP_TEXT = `
+HelloAGENTS - AI编程模块化技能系统配置工具
+
+Usage: npx helloagents [options]
+
+Options:
+  --platform <claude|codex>  目标平台（跳过交互）
+  --lang <cn|en>             语言版本（跳过交互）
+  --yes, -y                  全部使用默认选项（非交互）
+  --dry-run                  仅显示将执行的操作，不实际写入
+  --skills-only              仅更新 skills/helloagents，跳过顶层配置文件
+  --overwrite                强制覆盖顶层配置文件（不生成 .new）
+  --no-backup                跳过备份步骤
+  --no-color                 禁用 ANSI 颜色输出
+  --help, -h                 显示帮助
+  --version, -v              显示版本
+
+Examples:
+  npx helloagents                          # 交互式安装
+  npx helloagents -y                       # 使用默认选项安装
+  npx helloagents --platform claude --lang cn  # 指定平台和语言
+  npx helloagents --dry-run                # 预览将执行的操作
+  npx helloagents --skills-only            # 仅更新技能模块
+
+Documentation: https://github.com/hellowind777/helloagents
+`;
+
+async function main() {
+  try {
+    // Parse command line arguments
+    const options = parseArgs(process.argv.slice(2));
+
+    // Handle --help
+    if (options.help) {
+      console.log(HELP_TEXT);
+      process.exit(0);
+    }
+
+    // Handle --version
+    if (options.version) {
+      console.log(`helloagents v${pkg.version}`);
+      process.exit(0);
+    }
+
+    // Run main logic
+    await run(options);
+
+  } catch (err) {
+    // Handle known error types
+    if (err.code === 'MUTEX_PARAMS') {
+      error(err.message);
+      process.exit(1);
+    }
+
+    if (err.code === 'INVALID_PARAM') {
+      error(err.message);
+      process.exit(1);
+    }
+
+    // Handle unexpected errors
+    error(`发生错误: ${err.message}`);
+    if (process.env.DEBUG) {
+      console.error(err.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Run CLI
+main();

package/lib/args.js

@@ -0,0 +1,106 @@
+/**
+ * Args - Command line argument parsing
+ */
+
+'use strict';
+
+/**
+ * Parse command line arguments
+ * @param {string[]} argv - Command line arguments (without node and script)
+ * @returns {Object} Parsed options
+ * @throws {Error} On invalid arguments
+ */
+function parseArgs(argv) {
+  const options = {
+    platform: null,
+    lang: null,
+    yes: false,
+    dryRun: false,
+    skillsOnly: false,
+    overwrite: false,
+    noBackup: false,
+    noColor: false,
+    help: false,
+    version: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    switch (arg) {
+      case '--platform':
+        options.platform = argv[++i];
+        if (!options.platform || !['claude', 'codex'].includes(options.platform)) {
+          const err = new Error(`无效的平台参数: ${options.platform}。有效值: claude, codex`);
+          err.code = 'INVALID_PARAM';
+          throw err;
+        }
+        break;
+
+      case '--lang':
+        options.lang = argv[++i];
+        if (!options.lang || !['cn', 'en'].includes(options.lang)) {
+          const err = new Error(`无效的语言参数: ${options.lang}。有效值: cn, en`);
+          err.code = 'INVALID_PARAM';
+          throw err;
+        }
+        break;
+
+      case '--yes':
+      case '-y':
+        options.yes = true;
+        break;
+
+      case '--dry-run':
+        options.dryRun = true;
+        break;
+
+      case '--skills-only':
+        options.skillsOnly = true;
+        break;
+
+      case '--overwrite':
+        options.overwrite = true;
+        break;
+
+      case '--no-backup':
+        options.noBackup = true;
+        break;
+
+      case '--no-color':
+        options.noColor = true;
+        break;
+
+      case '--help':
+      case '-h':
+        options.help = true;
+        break;
+
+      case '--version':
+      case '-v':
+        options.version = true;
+        break;
+
+      default:
+        if (arg.startsWith('-')) {
+          const err = new Error(`未知参数: ${arg}`);
+          err.code = 'INVALID_PARAM';
+          throw err;
+        }
+        break;
+    }
+  }
+
+  // Check for mutually exclusive options
+  if (options.skillsOnly && options.overwrite) {
+    const err = new Error('--skills-only 与 --overwrite 不能同时使用');
+    err.code = 'MUTEX_PARAMS';
+    throw err;
+  }
+
+  return options;
+}
+
+module.exports = {
+  parseArgs,
+};

package/lib/backup.js

@@ -0,0 +1,81 @@
+/**
+ * Backup - File and directory backup functionality
+ */
+
+'use strict';
+
+const path = require('path');
+const fsPromises = require('fs').promises;
+const { getTimestamp, ensureDir } = require('./utils');
+
+/**
+ * Backup a single file
+ * @param {string} filePath - Path to file to backup
+ * @param {Object} deps - Dependencies
+ * @returns {Promise<string>} Backup path
+ */
+async function backupFile(filePath, deps = {}) {
+  const fsModule = deps.fs || fsPromises;
+  const timestamp = getTimestamp(deps);
+
+  const dir = path.dirname(filePath);
+  const ext = path.extname(filePath);
+  const base = path.basename(filePath, ext);
+  const backupPath = path.join(dir, `${base}${ext}.backup-${timestamp}`);
+
+  await fsModule.copyFile(filePath, backupPath);
+
+  return backupPath;
+}
+
+/**
+ * Backup a directory
+ * @param {string} dirPath - Path to directory to backup
+ * @param {Object} deps - Dependencies
+ * @returns {Promise<string>} Backup path
+ */
+async function backupDir(dirPath, deps = {}) {
+  const fsModule = deps.fs || fsPromises;
+  const timestamp = getTimestamp(deps);
+
+  const parent = path.dirname(dirPath);
+  const name = path.basename(dirPath);
+  const backupPath = path.join(parent, `${name}.backup-${timestamp}`);
+
+  // Recursively copy directory
+  await copyDirRecursive(dirPath, backupPath, deps);
+
+  return backupPath;
+}
+
+/**
+ * Recursively copy a directory
+ * @param {string} src - Source directory
+ * @param {string} dest - Destination directory
+ * @param {Object} deps - Dependencies
+ * @returns {Promise<void>}
+ */
+async function copyDirRecursive(src, dest, deps = {}) {
+  const fsModule = deps.fs || fsPromises;
+
+  await ensureDir(dest, deps);
+
+  const entries = await fsModule.readdir(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDirRecursive(srcPath, destPath, deps);
+    } else {
+      await fsModule.copyFile(srcPath, destPath);
+    }
+  }
+}
+
+module.exports = {
+  backupFile,
+  backupDir,
+  copyDirRecursive,
+};

package/lib/conflict.js

@@ -0,0 +1,118 @@
+/**
+ * Conflict - Conflict detection and resolution
+ */
+
+'use strict';
+
+const path = require('path');
+const fsPromises = require('fs').promises;
+const { fileExists, dirExists, readFileContent, getTimestamp } = require('./utils');
+
+/**
+ * Check if config file exists
+ * @param {string} targetPath - Path to config file
+ * @param {Object} deps - Dependencies
+ * @returns {Promise<boolean>}
+ */
+async function checkConfigFile(targetPath, deps = {}) {
+  return fileExists(targetPath, deps);
+}
+
+/**
+ * Check if skills directory exists
+ * @param {string} targetPath - Path to skills directory
+ * @param {Object} deps - Dependencies
+ * @returns {Promise<boolean>}
+ */
+async function checkSkillsDir(targetPath, deps = {}) {
+  return dirExists(targetPath, deps);
+}
+
+/**
+ * Check if .new file exists and compare content
+ * @param {string} newFilePath - Path to .new file
+ * @param {string} sourceContent - Content to compare
+ * @param {Object} deps - Dependencies
+ * @returns {Promise<Object>} { exists, sameContent }
+ */
+async function checkNewFile(newFilePath, sourceContent, deps = {}) {
+  const exists = await fileExists(newFilePath, deps);
+
+  if (!exists) {
+    return { exists: false, sameContent: false };
+  }
+
+  try {
+    const existingContent = await readFileContent(newFilePath, deps);
+    const sameContent = existingContent === sourceContent;
+    return { exists: true, sameContent };
+  } catch (err) {
+    return { exists: true, sameContent: false };
+  }
+}
+
+/**
+ * Backup existing .new file if content is different
+ * @param {string} newFilePath - Path to .new file
+ * @param {Object} deps - Dependencies
+ * @returns {Promise<string|null>} Backup path or null if no backup needed
+ */
+async function backupNewFileIfDifferent(newFilePath, deps = {}) {
+  const fsModule = deps.fs || fsPromises;
+  const timestamp = getTimestamp(deps);
+
+  const dir = path.dirname(newFilePath);
+  const name = path.basename(newFilePath);
+  const backupPath = path.join(dir, `${name}.backup-${timestamp}`);
+
+  await fsModule.rename(newFilePath, backupPath);
+
+  return backupPath;
+}
+
+/**
+ * Determine conflict resolution action
+ * @param {Object} options - CLI options
+ * @param {string} conflictType - 'config' or 'skills'
+ * @param {string} userChoice - User's choice from prompt
+ * @returns {string} Action to take
+ */
+function resolveConflict(options, conflictType, userChoice = null) {
+  // If user made a choice, use it
+  if (userChoice) {
+    return userChoice;
+  }
+
+  // -y mode: use defaults
+  if (options.yes) {
+    if (conflictType === 'config') {
+      return options.overwrite ? 'overwrite' : 'new';
+    }
+    if (conflictType === 'skills') {
+      return options.noBackup ? 'overwrite' : 'backup';
+    }
+  }
+
+  // --overwrite flag for config
+  if (conflictType === 'config' && options.overwrite) {
+    return options.noBackup ? 'overwrite' : 'backup';
+  }
+
+  // Default actions
+  if (conflictType === 'config') {
+    return 'new';
+  }
+  if (conflictType === 'skills') {
+    return options.noBackup ? 'overwrite' : 'backup';
+  }
+
+  return 'skip';
+}
+
+module.exports = {
+  checkConfigFile,
+  checkSkillsDir,
+  checkNewFile,
+  backupNewFileIfDifferent,
+  resolveConflict,
+};

package/lib/copy.js

@@ -0,0 +1,125 @@
+/**
+ * Copy - File copying with near-atomic writes
+ */
+
+'use strict';
+
+const path = require('path');
+const fsPromises = require('fs').promises;
+const { randomSuffix, ensureDir, readFileContent } = require('./utils');
+
+/**
+ * Copy a file with near-atomic write
+ * @param {string} src - Source file path
+ * @param {string} dest - Destination file path
+ * @param {Object} deps - Dependencies
+ * @returns {Promise<void>}
+ */
+async function copyFile(src, dest, deps = {}) {
+  const fsModule = deps.fs || fsPromises;
+  const suffix = randomSuffix(deps);
+
+  // Ensure destination directory exists
+  await ensureDir(path.dirname(dest), deps);
+
+  // Write to temporary file first
+  const tempPath = `${dest}.tmp-${suffix}`;
+
+  try {
+    // Copy to temp file
+    await fsModule.copyFile(src, tempPath);
+
+    // Verify copy by comparing sizes
+    const srcStat = await fsModule.stat(src);
+    const tempStat = await fsModule.stat(tempPath);
+
+    if (srcStat.size !== tempStat.size) {
+      throw new Error('File copy verification failed: size mismatch');
+    }
+
+    // Rename temp to final destination (atomic on most filesystems)
+    await fsModule.rename(tempPath, dest);
+
+  } catch (err) {
+    // Clean up temp file on failure
+    try {
+      await fsModule.unlink(tempPath);
+    } catch (cleanupErr) {
+      // Ignore cleanup errors
+    }
+    throw err;
+  }
+}
+
+/**
+ * Copy a directory recursively
+ * @param {string} src - Source directory path
+ * @param {string} dest - Destination directory path
+ * @param {Object} deps - Dependencies
+ * @returns {Promise<void>}
+ */
+async function copyDir(src, dest, deps = {}) {
+  const fsModule = deps.fs || fsPromises;
+
+  await ensureDir(dest, deps);
+
+  const entries = await fsModule.readdir(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath, deps);
+    } else {
+      await copyFile(srcPath, destPath, deps);
+    }
+  }
+}
+
+/**
+ * Write content to .new file
+ * @param {string} src - Source file path
+ * @param {string} dest - Destination .new file path
+ * @param {Object} deps - Dependencies
+ * @returns {Promise<void>}
+ */
+async function writeNewFile(src, dest, deps = {}) {
+  await copyFile(src, dest, deps);
+}
+
+/**
+ * Get list of files in a directory recursively
+ * @param {string} dir - Directory path
+ * @param {Object} deps - Dependencies
+ * @returns {Promise<string[]>} List of relative file paths
+ */
+async function listFiles(dir, deps = {}) {
+  const fsModule = deps.fs || fsPromises;
+  const files = [];
+
+  async function walk(currentDir, relativePath = '') {
+    const entries = await fsModule.readdir(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      const relPath = path.join(relativePath, entry.name);
+
+      if (entry.isDirectory()) {
+        await walk(fullPath, relPath);
+      } else {
+        files.push(relPath);
+      }
+    }
+  }
+
+  await walk(dir);
+  return files;
+}
+
+module.exports = {
+  copyFile,
+  copyDir,
+  writeNewFile,
+  listFiles,
+};

package/lib/defaults.js

@@ -0,0 +1,47 @@
+/**
+ * Defaults - Default value detection for platform and language
+ */
+
+'use strict';
+
+const path = require('path');
+const { dirExists, getHomeDir } = require('./utils');
+
+/**
+ * Detect default platform based on existing directories
+ * @param {Object} deps - Dependencies
+ * @returns {Promise<Object>} { platform, reason }
+ */
+async function detectDefaultPlatform(deps = {}) {
+  const homeDir = getHomeDir(deps);
+
+  const claudeDir = path.join(homeDir, '.claude');
+  const codexDir = path.join(homeDir, '.codex');
+
+  const claudeExists = await dirExists(claudeDir, deps);
+  const codexExists = await dirExists(codexDir, deps);
+
+  if (codexExists && !claudeExists) {
+    return { platform: 'codex', reason: '检测到 ~/.codex' };
+  }
+
+  if (claudeExists && !codexExists) {
+    return { platform: 'claude', reason: '检测到 ~/.claude' };
+  }
+
+  // Both exist or neither exists -> default to claude
+  return { platform: 'claude', reason: '默认选择' };
+}
+
+/**
+ * Get default language
+ * @returns {Object} { lang, reason }
+ */
+function getDefaultLang() {
+  return { lang: 'cn', reason: '默认选择' };
+}
+
+module.exports = {
+  detectDefaultPlatform,
+  getDefaultLang,
+};