@llryiop/avatar-boot-cli 1.0.0

package/docs/plans/2026-03-12-avatar-boot-cli-plan.md

@@ -0,0 +1,681 @@
+# Avatar Boot CLI Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Build an npx CLI tool that interactively scaffolds AvatarBoot Java microservice projects from a Git template.
+
+**Architecture:** Node.js CLI using commander for commands, inquirer for prompts, simple string replacement on cloned Git template. Template sourced from `https://code.iflytek.com/YHZ_VoicePlatform/avatar-scaffold-project.git`.
+
+**Tech Stack:** Node.js, commander, inquirer, chalk, ora, glob, child_process (git)
+
+---
+
+### Task 1: Initialize npm project and create CLI entry point
+
+**Files:**
+- Create: `package.json`
+- Create: `bin/cli.js`
+- Create: `src/index.js`
+
+**Step 1: Create package.json**
+
+```json
+{
+  "name": "avatar-boot-cli",
+  "version": "1.0.0",
+  "description": "CLI tool for scaffolding AvatarBoot Java microservice projects",
+  "main": "src/index.js",
+  "bin": {
+    "avatar-boot-cli": "./bin/cli.js"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "node --test src/__tests__/*.test.js"
+  },
+  "keywords": ["avatar", "boot", "scaffold", "java", "microservice"],
+  "license": "ISC"
+}
+```
+
+**Step 2: Install dependencies**
+
+Run: `npm install commander inquirer chalk ora glob`
+Expected: node_modules created, dependencies added to package.json
+
+**Step 3: Create bin/cli.js**
+
+```javascript
+#!/usr/bin/env node
+import { run } from '../src/index.js';
+run();
+```
+
+**Step 4: Create src/index.js (skeleton)**
+
+```javascript
+import { Command } from 'commander';
+import chalk from 'chalk';
+
+export function run() {
+  const program = new Command();
+
+  program
+    .name('avatar-boot-cli')
+    .description('CLI tool for scaffolding AvatarBoot Java microservice projects')
+    .version('1.0.0');
+
+  program
+    .command('init [project-name]')
+    .description('Initialize a new AvatarBoot project')
+    .action(async (projectName) => {
+      console.log(chalk.blue('🚀 Avatar Boot CLI'));
+      console.log('Project:', projectName || 'my-avatar-service');
+    });
+
+  program.parse();
+}
+```
+
+**Step 5: Test CLI entry point**
+
+Run: `chmod +x bin/cli.js && node bin/cli.js init test-project`
+Expected: Output showing "Avatar Boot CLI" and "Project: test-project"
+
+**Step 6: Commit**
+
+```bash
+git init
+git add package.json bin/cli.js src/index.js
+git commit -m "feat: initialize avatar-boot-cli project with commander setup"
+```
+
+---
+
+### Task 2: Implement Git clone logic
+
+**Files:**
+- Create: `src/clone.js`
+
+**Step 1: Create src/clone.js**
+
+```javascript
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+
+const REPO_URL = 'https://code.iflytek.com/YHZ_VoicePlatform/avatar-scaffold-project.git';
+
+/**
+ * Fetch available tags from remote repository
+ * @returns {string[]} List of tag names
+ */
+export function fetchTags() {
+  try {
+    const output = execSync(`git ls-remote --tags ${REPO_URL}`, {
+      encoding: 'utf-8',
+      timeout: 30000,
+    });
+    const tags = output
+      .split('\n')
+      .filter((line) => line.includes('refs/tags/'))
+      .map((line) => line.replace(/.*refs\/tags\//, '').replace(/\^{}$/, ''))
+      .filter((tag, index, arr) => arr.indexOf(tag) === index)
+      .filter((tag) => tag.length > 0)
+      .reverse();
+    return tags;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Clone the scaffold template repository
+ * @param {string} targetDir - Directory to clone into
+ * @param {string} [tag] - Specific tag/branch to clone
+ */
+export function cloneTemplate(targetDir, tag) {
+  const absoluteTarget = path.resolve(targetDir);
+
+  if (fs.existsSync(absoluteTarget)) {
+    throw new Error(`Directory "${targetDir}" already exists`);
+  }
+
+  const branchArg = tag ? `--branch ${tag}` : '';
+  execSync(`git clone --depth 1 ${branchArg} ${REPO_URL} "${absoluteTarget}"`, {
+    stdio: 'pipe',
+    timeout: 120000,
+  });
+
+  // Remove .git directory
+  fs.rmSync(path.join(absoluteTarget, '.git'), { recursive: true, force: true });
+}
+```
+
+**Step 2: Test clone module**
+
+Run: `node -e "import('./src/clone.js').then(m => console.log('Tags:', m.fetchTags()))"`
+Expected: List of tags (or empty array if no tags yet)
+
+**Step 3: Commit**
+
+```bash
+git add src/clone.js
+git commit -m "feat: add git clone and tag fetching logic"
+```
+
+---
+
+### Task 3: Implement interactive prompts
+
+**Files:**
+- Create: `src/prompts.js`
+
+**Step 1: Create src/prompts.js**
+
+```javascript
+import inquirer from 'inquirer';
+import { fetchTags } from './clone.js';
+
+const STARTER_MODULES = [
+  { name: 'avatar-boot-starter-web (Web 基础设施)', value: 'web', checked: true },
+  { name: 'avatar-boot-starter-nacos (服务注册与配置)', value: 'nacos', checked: true },
+  { name: 'avatar-boot-starter-feign (服务间调用)', value: 'feign', checked: false },
+  { name: 'avatar-boot-starter-mysql (MySQL 数据库)', value: 'mysql', checked: false },
+  { name: 'avatar-boot-starter-redis (Redis 缓存)', value: 'redis', checked: false },
+  { name: 'avatar-boot-starter-kafka (Kafka 消息队列)', value: 'kafka', checked: false },
+  { name: 'avatar-boot-starter-rocketmq (RocketMQ 消息队列)', value: 'rocketmq', checked: false },
+  { name: 'avatar-boot-starter-job (XXL-Job 任务调度)', value: 'job', checked: false },
+  { name: 'avatar-boot-starter-oss (对象存储)', value: 'oss', checked: false },
+];
+
+/**
+ * Run interactive prompts to collect project configuration
+ * @param {string} [initialName] - Project name from CLI argument
+ * @returns {Promise<object>} User configuration
+ */
+export async function collectConfig(initialName) {
+  const tags = fetchTags();
+
+  const versionChoices = tags.length > 0
+    ? [...tags.map((t) => ({ name: t, value: t })), { name: 'latest (main branch)', value: '' }]
+    : [{ name: 'latest (main branch)', value: '' }];
+
+  const questions = [
+    {
+      type: 'input',
+      name: 'projectName',
+      message: '项目名称:',
+      default: initialName || 'my-avatar-service',
+      validate: (input) => /^[a-z][a-z0-9-]*$/.test(input) || '项目名称只能包含小写字母、数字和连字符，且以字母开头',
+    },
+    {
+      type: 'input',
+      name: 'groupId',
+      message: 'Maven groupId:',
+      default: 'com.iflytek.avatar',
+      validate: (input) => /^[a-z][a-z0-9.]*$/.test(input) || 'groupId 格式不正确',
+    },
+    {
+      type: 'list',
+      name: 'version',
+      message: 'Avatar Boot 版本:',
+      choices: versionChoices,
+    },
+    {
+      type: 'checkbox',
+      name: 'starters',
+      message: '选择 Starter 模块:',
+      choices: STARTER_MODULES,
+    },
+    {
+      type: 'confirm',
+      name: 'includeExample',
+      message: '是否生成示例代码 (login 模块):',
+      default: true,
+    },
+    {
+      type: 'input',
+      name: 'nacosAddr',
+      message: 'Nacos 地址:',
+      default: '127.0.0.1:8848',
+      when: (answers) => answers.starters.includes('nacos'),
+    },
+    {
+      type: 'input',
+      name: 'dbUrl',
+      message: '数据库地址 (host:port/dbname):',
+      default: 'localhost:3306/avatar',
+      when: (answers) => answers.starters.includes('mysql'),
+    },
+    {
+      type: 'confirm',
+      name: 'includeAiConfig',
+      message: '是否生成 .claude/ AI Agent 配置:',
+      default: true,
+    },
+    {
+      type: 'input',
+      name: 'serverPort',
+      message: '服务端口:',
+      default: '8888',
+    },
+  ];
+
+  return inquirer.prompt(questions);
+}
+```
+
+**Step 2: Test prompts module**
+
+Run: `node -e "import('./src/prompts.js').then(m => m.collectConfig('test').then(c => console.log(JSON.stringify(c, null, 2))))"`
+Expected: Interactive prompts appear, config object printed after completion
+
+**Step 3: Commit**
+
+```bash
+git add src/prompts.js
+git commit -m "feat: add interactive prompts for project configuration"
+```
+
+---
+
+### Task 4: Implement template transformation logic
+
+**Files:**
+- Create: `src/transform.js`
+- Create: `src/utils.js`
+
+**Step 1: Create src/utils.js**
+
+```javascript
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Convert groupId to directory path (e.g., "com.iflytek.avatar" → "com/iflytek/avatar")
+ */
+export function groupIdToPath(groupId) {
+  return groupId.replace(/\./g, '/');
+}
+
+/**
+ * Recursively get all files in a directory
+ */
+export function getAllFiles(dir, fileList = []) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      getAllFiles(fullPath, fileList);
+    } else {
+      fileList.push(fullPath);
+    }
+  }
+  return fileList;
+}
+
+/**
+ * Replace content in a file
+ */
+export function replaceInFile(filePath, replacements) {
+  let content = fs.readFileSync(filePath, 'utf-8');
+  for (const [search, replace] of replacements) {
+    content = content.replaceAll(search, replace);
+  }
+  fs.writeFileSync(filePath, content, 'utf-8');
+}
+
+/**
+ * Rename directory
+ */
+export function renameDir(oldPath, newPath) {
+  if (fs.existsSync(oldPath)) {
+    fs.mkdirSync(path.dirname(newPath), { recursive: true });
+    fs.renameSync(oldPath, newPath);
+  }
+}
+```
+
+**Step 2: Create src/transform.js**
+
+```javascript
+import fs from 'fs';
+import path from 'path';
+import { groupIdToPath, getAllFiles, replaceInFile, renameDir } from './utils.js';
+
+const DEFAULT_GROUP_ID = 'com.iflytek.avatar';
+const DEFAULT_GROUP_PATH = 'com/iflytek/avatar';
+const DEFAULT_ARTIFACT_ID = 'avatar-template';
+const DEFAULT_APP_NAME = 'scaffold-template';
+const DEFAULT_NACOS_ADDR = '172.29.242.247:8848';
+
+// All starters that can be managed in service pom.xml
+const ALL_STARTERS = ['web', 'nacos', 'feign', 'mysql', 'redis', 'kafka', 'rocketmq', 'job', 'oss'];
+
+/**
+ * Transform cloned template based on user configuration
+ * @param {string} projectDir - Root directory of cloned template
+ * @param {object} config - User configuration from prompts
+ */
+export function transformProject(projectDir, config) {
+  const {
+    projectName,
+    groupId = DEFAULT_GROUP_ID,
+    starters = ['web', 'nacos'],
+    includeExample = true,
+    nacosAddr = '127.0.0.1:8848',
+    dbUrl,
+    includeAiConfig = true,
+    serverPort = '8888',
+  } = config;
+
+  const newGroupPath = groupIdToPath(groupId);
+  const apiModule = `${projectName}-api`;
+  const serviceModule = `${projectName}-service`;
+
+  // 1. Rename module directories
+  renameDir(
+    path.join(projectDir, 'avatar-scaffold-api'),
+    path.join(projectDir, apiModule)
+  );
+  renameDir(
+    path.join(projectDir, 'avatar-scaffold-service'),
+    path.join(projectDir, serviceModule)
+  );
+
+  // 2. Rename Java package directories if groupId changed
+  if (groupId !== DEFAULT_GROUP_ID) {
+    // API module
+    const apiOldPkg = path.join(projectDir, apiModule, 'src/main/java', DEFAULT_GROUP_PATH);
+    const apiNewPkg = path.join(projectDir, apiModule, 'src/main/java', newGroupPath);
+    if (fs.existsSync(apiOldPkg)) {
+      renameDir(apiOldPkg, apiNewPkg);
+      // Clean up empty parent directories
+      cleanEmptyDirs(path.join(projectDir, apiModule, 'src/main/java'));
+    }
+
+    // Service module
+    const svcOldPkg = path.join(projectDir, serviceModule, 'src/main/java', DEFAULT_GROUP_PATH);
+    const svcNewPkg = path.join(projectDir, serviceModule, 'src/main/java', newGroupPath);
+    if (fs.existsSync(svcOldPkg)) {
+      renameDir(svcOldPkg, svcNewPkg);
+      cleanEmptyDirs(path.join(projectDir, serviceModule, 'src/main/java'));
+    }
+  }
+
+  // 3. Remove example code if not needed
+  if (!includeExample) {
+    const apiLoginDir = path.join(projectDir, apiModule, 'src/main/java', newGroupPath, 'login');
+    const svcLoginDir = path.join(projectDir, serviceModule, 'src/main/java', newGroupPath, 'login');
+    if (fs.existsSync(apiLoginDir)) fs.rmSync(apiLoginDir, { recursive: true });
+    if (fs.existsSync(svcLoginDir)) fs.rmSync(svcLoginDir, { recursive: true });
+  }
+
+  // 4. Remove .claude/ if not needed
+  if (!includeAiConfig) {
+    const claudeDir = path.join(projectDir, '.claude');
+    if (fs.existsSync(claudeDir)) fs.rmSync(claudeDir, { recursive: true });
+    const claudeMd = path.join(projectDir, 'CLAUDE.md');
+    if (fs.existsSync(claudeMd)) fs.unlinkSync(claudeMd);
+  }
+
+  // 5. Replace content in all text files
+  const textExtensions = ['.xml', '.java', '.yaml', '.yml', '.properties', '.md', '.txt'];
+  const allFiles = getAllFiles(projectDir);
+  const textFiles = allFiles.filter((f) =>
+    textExtensions.some((ext) => f.endsWith(ext))
+  );
+
+  const replacements = [
+    // Module names in pom.xml
+    ['avatar-scaffold-api', apiModule],
+    ['avatar-scaffold-service', serviceModule],
+    // Artifact IDs
+    ['avatar-template-api', `${projectName}-api`],
+    ['avatar-template-service', `${projectName}-service`],
+    ['avatar-template', projectName],
+    // Group ID
+    [DEFAULT_GROUP_ID, groupId],
+    // Package path in Java files
+    [`package ${DEFAULT_GROUP_ID}`, `package ${groupId}`],
+    [`import ${DEFAULT_GROUP_ID}`, `import ${groupId}`],
+    // Application name
+    [DEFAULT_APP_NAME, projectName],
+    // Nacos address
+    [DEFAULT_NACOS_ADDR, nacosAddr],
+    // Server port
+    ['port: 8888', `port: ${serverPort}`],
+    // Main class reference
+    [`${DEFAULT_GROUP_ID}.Application`, `${groupId}.Application`],
+  ];
+
+  for (const file of textFiles) {
+    replaceInFile(file, replacements);
+  }
+
+  // 6. Handle starter dependencies in service pom.xml
+  transformServicePom(path.join(projectDir, serviceModule, 'pom.xml'), starters);
+
+  // 7. Handle database URL in config
+  if (dbUrl && starters.includes('mysql')) {
+    const devYaml = path.join(projectDir, serviceModule, 'src/main/resources/application-dev.yaml');
+    if (fs.existsSync(devYaml)) {
+      replaceInFile(devYaml, [['localhost:3306/avatar', dbUrl]]);
+    }
+  }
+
+  // 8. Remove .DS_Store files
+  for (const file of allFiles) {
+    if (path.basename(file) === '.DS_Store') {
+      fs.unlinkSync(file);
+    }
+  }
+}
+
+/**
+ * Manage starter dependencies in service pom.xml
+ * - Selected starters: uncomment if commented, add if missing
+ * - Unselected starters: comment out if present
+ */
+function transformServicePom(pomPath, selectedStarters) {
+  if (!fs.existsSync(pomPath)) return;
+
+  let content = fs.readFileSync(pomPath, 'utf-8');
+
+  for (const starter of ALL_STARTERS) {
+    const artifactId = `avatar-boot-starter-${starter}`;
+    const depBlock = `        <dependency>\n            <groupId>com.iflytek.avatar.boot</groupId>\n            <artifactId>${artifactId}</artifactId>\n        </dependency>`;
+    const commentedPattern = new RegExp(
+      `<!--\\s*<dependency>\\s*\\n\\s*<groupId>com\\.iflytek\\.avatar\\.boot</groupId>\\s*\\n\\s*<artifactId>${artifactId}</artifactId>\\s*\\n\\s*</dependency>\\s*-->`,
+      's'
+    );
+    const uncommentedPattern = new RegExp(
+      `<dependency>\\s*\\n\\s*<groupId>com\\.iflytek\\.avatar\\.boot</groupId>\\s*\\n\\s*<artifactId>${artifactId}</artifactId>\\s*\\n\\s*</dependency>`,
+      's'
+    );
+
+    if (selectedStarters.includes(starter)) {
+      // Uncomment if commented
+      const commentedMatch = content.match(commentedPattern);
+      if (commentedMatch) {
+        content = content.replace(commentedMatch[0], depBlock);
+      } else if (!uncommentedPattern.test(content)) {
+        // Add dependency if not present at all
+        const insertPoint = content.indexOf('</dependencies>');
+        if (insertPoint !== -1) {
+          content = content.slice(0, insertPoint) + depBlock + '\n' + content.slice(insertPoint);
+        }
+      }
+    } else {
+      // Comment out if uncommented
+      const uncommentedMatch = content.match(uncommentedPattern);
+      if (uncommentedMatch) {
+        content = content.replace(
+          uncommentedMatch[0],
+          `<!--${uncommentedMatch[0]}-->`
+        );
+      }
+    }
+  }
+
+  fs.writeFileSync(pomPath, content, 'utf-8');
+}
+
+/**
+ * Remove empty directories recursively (bottom-up)
+ */
+function cleanEmptyDirs(dir) {
+  if (!fs.existsSync(dir)) return;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      cleanEmptyDirs(path.join(dir, entry.name));
+    }
+  }
+  // Re-read after potential child cleanup
+  const remaining = fs.readdirSync(dir);
+  if (remaining.length === 0) {
+    fs.rmdirSync(dir);
+  }
+}
+```
+
+**Step 3: Commit**
+
+```bash
+git add src/utils.js src/transform.js
+git commit -m "feat: add template transformation and string replacement logic"
+```
+
+---
+
+### Task 5: Wire everything together in src/index.js
+
+**Files:**
+- Modify: `src/index.js`
+
+**Step 1: Update src/index.js with full init flow**
+
+```javascript
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { collectConfig } from './prompts.js';
+import { cloneTemplate } from './clone.js';
+import { transformProject } from './transform.js';
+
+export function run() {
+  const program = new Command();
+
+  program
+    .name('avatar-boot-cli')
+    .description('CLI tool for scaffolding AvatarBoot Java microservice projects')
+    .version('1.0.0');
+
+  program
+    .command('init [project-name]')
+    .description('Initialize a new AvatarBoot project')
+    .action(async (projectName) => {
+      console.log('');
+      console.log(chalk.blue.bold('  Avatar Boot CLI'));
+      console.log(chalk.gray('  AvatarBoot Java 微服务项目脚手架工具'));
+      console.log('');
+
+      try {
+        // 1. Collect configuration
+        const config = await collectConfig(projectName);
+
+        console.log('');
+
+        // 2. Clone template
+        const spinner = ora('正在克隆模板仓库...').start();
+        try {
+          cloneTemplate(config.projectName, config.version || undefined);
+          spinner.succeed('模板仓库克隆完成');
+        } catch (err) {
+          spinner.fail('模板仓库克隆失败');
+          console.error(chalk.red(err.message));
+          process.exit(1);
+        }
+
+        // 3. Transform project
+        const transformSpinner = ora('正在生成项目...').start();
+        try {
+          transformProject(config.projectName, config);
+          transformSpinner.succeed('项目生成完成');
+        } catch (err) {
+          transformSpinner.fail('项目生成失败');
+          console.error(chalk.red(err.message));
+          process.exit(1);
+        }
+
+        // 4. Print success message
+        console.log('');
+        console.log(chalk.green.bold('  ✅ 项目创建成功!'));
+        console.log('');
+        console.log(chalk.white('  开始开发:'));
+        console.log(chalk.cyan(`    cd ${config.projectName}`));
+        console.log(chalk.cyan('    mvn clean compile'));
+        console.log('');
+        console.log(chalk.white('  项目结构:'));
+        console.log(chalk.gray(`    ${config.projectName}/`));
+        console.log(chalk.gray(`    ├── ${config.projectName}-api/        # API 模块 (接口定义)`));
+        console.log(chalk.gray(`    ├── ${config.projectName}-service/    # Service 模块 (业务实现)`));
+        console.log(chalk.gray(`    └── pom.xml`));
+        console.log('');
+      } catch (err) {
+        if (err.name === 'ExitPromptError') {
+          console.log(chalk.yellow('\n  已取消'));
+        } else {
+          console.error(chalk.red(`\n  错误: ${err.message}`));
+        }
+        process.exit(1);
+      }
+    });
+
+  program.parse();
+}
+```
+
+**Step 2: Test full flow**
+
+Run: `node bin/cli.js init`
+Expected: Full interactive flow works — prompts → clone → transform → success message
+
+**Step 3: Commit**
+
+```bash
+git add src/index.js
+git commit -m "feat: wire init command with prompts, clone, and transform"
+```
+
+---
+
+### Task 6: Add .gitignore and finalize
+
+**Files:**
+- Create: `.gitignore`
+
+**Step 1: Create .gitignore**
+
+```
+node_modules/
+.DS_Store
+```
+
+**Step 2: Final commit**
+
+```bash
+git add .gitignore
+git commit -m "chore: add .gitignore"
+```
+
+---
+
+## Task Dependencies
+
+```
+Task 1 (npm + CLI entry) → Task 2 (clone) → Task 3 (prompts) → Task 4 (transform) → Task 5 (wire together) → Task 6 (finalize)
+```
+
+All tasks are sequential — each builds on the previous.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@llryiop/avatar-boot-cli",
+  "version": "1.0.0",
+  "description": "CLI tool for scaffolding AvatarBoot Java microservice projects",
+  "main": "src/index.js",
+  "bin": {
+    "avatar-boot-cli": "./bin/cli.js"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "node --test src/__tests__/*.test.js"
+  },
+  "keywords": [
+    "avatar",
+    "boot",
+    "scaffold",
+    "java",
+    "microservice"
+  ],
+  "license": "ISC",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "glob": "^13.0.6",
+    "inquirer": "^13.3.0",
+    "ora": "^9.3.0"
+  }
+}