generator-mico-cli 0.2.1 → 0.2.2-8.beta.1

package/README.md

@@ -9,39 +9,89 @@
 | [docs/mico-cli.md](docs/mico-cli.md) | Mico CLI 功能概述与技术方案 |
 | [docs/micro-react-generator.md](docs/micro-react-generator.md) | Monorepo 项目生成器说明 |
 | [docs/subapp-react-generator.md](docs/subapp-react-generator.md) | React 子应用生成器说明 |
+| [docs/subapp-umd-generator.md](docs/subapp-umd-generator.md) | UMD 组件包生成器说明 |
+| [docs/feat-integration-tests.md](docs/feat-integration-tests.md) | 集成测试方案（Vitest + yeoman-test） |
+| [docs/fix-command-injection.md](docs/fix-command-injection.md) | 修复 npm version 查询命令注入风险 |
+| [docs/refactor-code-quality-optimizations.md](docs/refactor-code-quality-optimizations.md) | 代码质量优化（DRY / 错误处理 / 确定性 ID / 可配置化 / 冗余清理） |
 
 ## 要求
 
 - Node >= 18
-- Yeoman CLI: `npm install -g yo`
 
 ## 安装和使用
 
 ```bash
-npm install -g yo generator-mico-cli
+npm install -g generator-mico-cli
 ```
 
 ## 包装器 CLI
 
-全局安装后，`mico` 命令可用于委托给 Yeoman 生成器。
-如果 `generators/<name>` 下存在本地生成器，它将作为 `yo mico-cli:<name>` 运行。
+全局安装后，`mico` 命令可用于运行内置的 Yeoman 生成器。
 
 ```bash
 mico create subapp-react
 ```
 
-等同于：
+列出所有可用的生成器：
 
 ```bash
-yo subapp-react
+mico list
 ```
 
-将额外参数传递给生成器：
+使用详细输出模式（显示文件处理过程）：
 
 ```bash
-mico create micro-react -- --help
+mico create micro-react --verbose
 ```
 
+预览模式（只显示将创建的文件，不实际创建）：
+
+```bash
+mico create micro-react --dry-run
+```
+
+检查环境依赖：
+
+```bash
+mico doctor
+```
+
+## 配置文件
+
+可以在项目目录或用户主目录创建 `.micorc` 或 `.micorc.json` 文件来预设默认值。
+
+配置查找顺序：
+1. 当前目录（或 monorepo 根目录）的 `.micorc` / `.micorc.json`
+2. 用户主目录的 `.micorc` / `.micorc.json`
+
+### 完整字段列表
+
+```json
+{
+  "projectName": "my-app",
+  "packageScope": "@my-company",
+  "cdnPrefix": "portal",
+  "author": "Team <team@example.com>",
+  "defaultSubappName": "subapp",
+  "devPort": "8010",
+  "defaultUmdName": "my-widget",
+  "umdDevPort": "9100"
+}
+```
+
+| 字段 | 类型 | 适用生成器 | 说明 | 默认值 |
+|------|------|-----------|------|--------|
+| `projectName` | string | micro-react | 项目名称 | 当前目录名 |
+| `packageScope` | string | 所有 | 包作用域（如 `@my-company`） | micro-react: `@<projectName>`；其他: 从根 `package.json` 检测 |
+| `cdnPrefix` | string | micro-react | CDN 路径前缀（如 `portal`、`admin/v2`） | 空字符串 |
+| `author` | string | micro-react | 作者信息 | `Your Name <email@example.com>` |
+| `defaultSubappName` | string | subapp-react | 子应用默认名称 | `subapp` |
+| `devPort` | string | subapp-react | 子应用开发端口 | `8010` |
+| `defaultUmdName` | string | subapp-umd | UMD 包默认名称 | `my-widget` |
+| `umdDevPort` | string | subapp-umd | UMD 包开发端口 | `9100` |
+
+所有字段均为可选，未配置时使用默认值或交互式提示。
+
 ## Monorepo 项目生成器 (micro-react)
 
 创建基于 qiankun 微前端架构的完整 Monorepo 项目：
@@ -53,9 +103,10 @@ mico create micro-react
 
 生成的项目包含：
 - 主应用 (layout) - qiankun master
-- 共享样式包 (shared-styles)
+- @mico-platform/ui、@mico-platform/theme
 - Turborepo + pnpm Workspace
 - Husky + Commitlint
+- @common-web/sentry 错误监控与 SourceMap 上传
 
 ## React 子应用生成器
 
@@ -67,18 +118,151 @@ cd <monorepo-root>
 mico create subapp-react
 ```
 
-## 同步子应用模板
+## UMD 组件包生成器
+
+在 Monorepo 的 `packages/` 目录下创建 UMD 格式的组件包，使用 Webpack 构建。适用于通过 `<script>` 标签加载的场景（如主应用菜单挂载组件、第三方系统嵌入 Widget 等）。
+
+```bash
+cd <monorepo-root>
+mico create subapp-umd
+```
+
+生成器会提示输入：
+- **Package name** — 包名（如 `my-widget`）
+- **UMD global variable name** — 全局变量名（如 `MyWidget`）
+- **Package scope** — 包作用域（自动从根 `package.json` 检测）
+- **Dev server port** — 开发端口（默认 `9100`）
+
+生成的包支持：
+- `pnpm dev` — 启动 webpack-dev-server，同时提供 HTML 预览页和 UMD JS 文件
+- `pnpm build` — 构建生产环境 UMD 产物到 `dist/`
+
+开发模式下：
+
+| URL | 用途 |
+|---|---|
+| `http://localhost:<port>/` | HTML 预览页，独立调试 |
+| `http://localhost:<port>/<name>.umd.js` | UMD JS 文件，供主应用通过 `jsUrls` 联调 |
+
+DevTools Sources 面板中可在 `webpack://<name>/src/` 下定位原始 TypeScript 源码进行断点调试。
+
+## 开发指南
+
+### 环境准备
+
+```bash
+# 1. 安装依赖
+pnpm install
+
+# 2. 将本地包链接到全局
+npm link
+
+# 3. 验证链接成功
+mico --version
+```
+
+链接成功后，`mico` 命令会使用本地代码，可以直接修改代码并测试：
+
+```bash
+# 测试 micro-react 生成器
+mkdir test-project && cd test-project
+mico create micro-react
+
+# 测试 subapp-react 生成器（需在已有 monorepo 中执行）
+mico create subapp-react
+
+# 测试 subapp-umd 生成器（需在已有 monorepo 中执行）
+mico create subapp-umd
+```
+
+调试完成后，取消全局链接：
+
+```bash
+npm unlink -g generator-mico-cli
+```
+
+### 运行测试
 
-将源项目的 `apps/homepage` 同步到生成器模板目录：
+项目使用 Vitest + yeoman-test 进行单元测试和集成测试：
 
 ```bash
-SOURCE_PROJECT_ROOT=<source-project-root> npm run sync:subapp-react-template
+# 运行全部测试
+pnpm test
+
+# watch 模式
+pnpm test:watch
 ```
 
-也可以直接传入路径：
+测试目录结构：
+
+| 目录/文件 | 说明 |
+|----------|------|
+| `tests/unit/utils.test.js` | `lib/utils.js` 的单元测试 |
+| `tests/integration/micro-react.test.js` | micro-react 生成器集成测试 |
+| `tests/integration/subapp-react.test.js` | subapp-react 生成器集成测试 |
+| `tests/integration/subapp-umd.test.js` | subapp-umd 生成器集成测试 |
+| `tests/integration/mico-cli.test.js` | `mico` 入口子进程测试（help / version / list / create / doctor） |
+| `tests/helpers/setup.js` | 测试共享工具（路径常量、monorepo fixture 工厂） |
+| `tests/helpers/mico-subprocess.js` | 子进程运行 `bin/mico.js` 工具函数 |
+
+### Scripts 说明
+
+| 脚本 | 命令 | 说明 |
+|------|------|------|
+| `sync:subapp-react-template` | `pnpm run sync:subapp-react-template -- <source-path>` | 将源项目的 `apps/homepage` 同步到 `subapp-react` 模板目录，忽略清单见 `generators/subapp-react/ignore-list.json` |
+| `verify:micro-react` | `node scripts/verify-micro-react.js [test-dir]` | 端到端验证 micro-react + subapp-react 生成器，自动创建项目并回车通过所有提示 |
+
+#### verify-micro-react.js
+
+自动化验证脚本，依次执行：
+1. 创建或清空测试目录
+2. 运行 `mico create micro-react`（自动回车通过 5 个提示）
+3. 运行 `mico create subapp-react`（自动回车通过 4 个提示）
+
+测试目录支持三种方式指定：
+- 命令行参数：`node scripts/verify-micro-react.js /path/to/dir`
+- 环境变量：`VERIFY_TEST_DIR=/path node scripts/verify-micro-react.js`
+- 默认值：`../test-app2`
+
+#### sync-subapp-react-template.js
+
+从源 monorepo 项目同步 `apps/homepage` 到生成器模板目录：
 
 ```bash
-npm run sync:subapp-react-template -- <source-project-root>
+# 通过环境变量
+SOURCE_PROJECT_ROOT=<source-path> pnpm run sync:subapp-react-template
+
+# 通过命令行参数
+pnpm run sync:subapp-react-template -- <source-path>
+```
+
+会自动记录源仓库的 git commit 信息到 `.template-version.json`。
+
+### 项目结构
+
+```
+mico-cli/
+├── bin/mico.js              # CLI 入口（命令解析、生成器调度）
+├── lib/utils.js             # 共享工具函数（字符串转换、文件处理、npm 版本查询、配置加载）
+├── generators/
+│   ├── micro-react/         # Monorepo 项目生成器
+│   ├── subapp-react/        # React 子应用生成器
+│   └── subapp-umd/          # UMD 组件包生成器
+├── scripts/                 # 辅助脚本
+├── tests/                   # 测试文件
+├── docs/                    # 功能文档
+└── vitest.config.js         # 测试配置
 ```
 
-忽略清单位于 `generators/subapp-react/ignore-list.json`。
+### 提交规范
+
+请使用语义化提交信息：
+
+```
+feat: 添加新功能
+fix: 修复 Bug
+refactor: 代码重构
+docs: 文档更新
+test: 测试相关
+chore: 构建/工具链变更
+```

package/bin/mico.js

@@ -1,11 +1,15 @@
 #!/usr/bin/env node
 'use strict';
 
-const { spawn, spawnSync } = require('node:child_process');
+const { spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
 const readline = require('node:readline');
 
+const { setupErrorHandlers } = require('../lib/utils');
+
+setupErrorHandlers();
+
 const rootDir = path.resolve(__dirname, '..');
 const pkg = JSON.parse(
   fs.readFileSync(path.join(rootDir, 'package.json'), 'utf8')
@@ -20,24 +24,112 @@ Usage: mico <command> [options]
 
 Commands:
   create <generator>    Run a generator (e.g., mico create subapp-react)
+  list                  List all available generators
   update                Update mico-cli to the latest version
+  doctor                Check environment dependencies
 
 Options:
   --help, -h            Show this help message
   --version, -v         Show version number
+  --verbose             Show detailed output during generation
+  --dry-run             Preview files without creating them
+  --force               Overwrite all existing files without confirmation
   --no-update-check     Skip update check
 
 Examples:
   mico create subapp-react
-  mico create app
+  mico create micro-react --verbose
+  mico create micro-react --dry-run
+  mico create micro-react --force
+  mico list
   mico update
+  mico doctor
+
+Configuration:
+  Create a .micorc or .micorc.json file in your project or home directory
+  to set default values for prompts:
+
+  {
+    "packageScope": "@my-company",
+    "cdnPrefix": "portal",
+    "author": "Team <team@example.com>"
+  }
 
 Notes:
-  Requires Yeoman CLI (yo) installed globally.
   If a local generator exists at generators/<name>, it will be used.
 `);
 }
 
+/**
+ * 列出所有可用的生成器
+ */
+function listGenerators() {
+  const generatorsDir = path.join(rootDir, 'generators');
+
+  if (!fs.existsSync(generatorsDir)) {
+    console.error('❌ Error: generators directory not found.');
+    process.exit(1);
+  }
+
+  const entries = fs.readdirSync(generatorsDir, { withFileTypes: true });
+  const generators = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const generatorPath = path.join(generatorsDir, entry.name);
+    const indexPath = path.join(generatorPath, 'index.js');
+    const metaPath = path.join(generatorPath, 'meta.json');
+
+    // 必须有 index.js 才算有效生成器
+    if (!fs.existsSync(indexPath)) continue;
+
+    let meta = { name: entry.name, description: '(No description)' };
+    if (fs.existsSync(metaPath)) {
+      try {
+        meta = { ...meta, ...JSON.parse(fs.readFileSync(metaPath, 'utf8')) };
+      } catch (e) {
+        console.warn(`  ⚠ Failed to parse ${metaPath}: ${e.message}`);
+      }
+    }
+
+    generators.push(meta);
+  }
+
+  if (generators.length === 0) {
+    console.log('');
+    console.log('  No generators found.');
+    console.log('');
+    return;
+  }
+
+  console.log('');
+  console.log(`  \x1b[1mAvailable Generators\x1b[0m (mico-cli v${pkg.version})`);
+  console.log('');
+
+  // 计算最长名称用于对齐
+  const maxNameLen = Math.max(...generators.map((g) => g.name.length));
+
+  for (const gen of generators) {
+    const name = gen.name.padEnd(maxNameLen + 2);
+    console.log(`  \x1b[36m${name}\x1b[0m ${gen.description}`);
+
+    // 如果有 features，显示特性列表
+    if (gen.features && gen.features.length > 0) {
+      for (const feature of gen.features) {
+        console.log(`  ${' '.repeat(maxNameLen + 2)}  • ${feature}`);
+      }
+    }
+
+    // 如果有 usage，显示用法
+    if (gen.usage) {
+      console.log(`  ${' '.repeat(maxNameLen + 2)}  \x1b[2m$ ${gen.usage}\x1b[0m`);
+    }
+
+    console.log('');
+  }
+}
+
 /**
  * 打印版本信息
  */
@@ -45,6 +137,76 @@ function printVersion() {
   console.log(`mico-cli v${pkg.version}`);
 }
 
+/**
+ * 运行 doctor 检查
+ */
+async function runDoctor() {
+  const { runDoctorChecks, loadMicorc } = require('../lib/utils');
+
+  console.log('');
+  console.log(`  \x1b[1mMico CLI Environment Check\x1b[0m (v${pkg.version})`);
+  console.log('');
+
+  const results = await runDoctorChecks();
+
+  // Node.js
+  const nodeIcon = results.node.satisfied ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+  const nodeStatus = results.node.satisfied ? 'OK' : `Required: >= ${results.node.required}`;
+  console.log(`  ${nodeIcon} Node.js ${results.node.current} (${nodeStatus})`);
+
+  // pnpm
+  const pnpmIcon = results.pnpm.available ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+  if (results.pnpm.available) {
+    console.log(`  ${pnpmIcon} pnpm ${results.pnpm.version}`);
+  } else {
+    console.log(`  ${pnpmIcon} pnpm not found`);
+    console.log('     Install: npm install -g pnpm');
+  }
+
+  // Git
+  const gitIcon = results.git.available ? '\x1b[32m✓\x1b[0m' : '\x1b[33m⚠\x1b[0m';
+  if (results.git.available) {
+    console.log(`  ${gitIcon} git ${results.git.version}`);
+  } else {
+    console.log(`  ${gitIcon} git not found (optional)`);
+  }
+
+  // npm registry
+  const npmIcon = results.npm.reachable ? '\x1b[32m✓\x1b[0m' : '\x1b[33m⚠\x1b[0m';
+  if (results.npm.reachable) {
+    console.log(`  ${npmIcon} npm registry reachable`);
+  } else {
+    console.log(`  ${npmIcon} npm registry unreachable (${results.npm.error})`);
+  }
+
+  // .micorc 配置
+  console.log('');
+  const { config, configPath } = loadMicorc();
+  if (configPath) {
+    console.log(`  \x1b[32m✓\x1b[0m Config loaded from: ${configPath}`);
+    const keys = Object.keys(config);
+    if (keys.length > 0) {
+      console.log(`     Keys: ${keys.join(', ')}`);
+    }
+  } else {
+    console.log('  \x1b[2m○\x1b[0m No .micorc config found (optional)');
+  }
+
+  console.log('');
+
+  // 总结
+  const allGood = results.node.satisfied && results.pnpm.available;
+  if (allGood) {
+    console.log('  \x1b[32m✅ All required dependencies are installed!\x1b[0m');
+  } else {
+    console.log('  \x1b[31m❌ Some required dependencies are missing.\x1b[0m');
+    console.log('     Please install them before using mico-cli.');
+  }
+  console.log('');
+
+  return allGood;
+}
+
 /**
  * 检查是否有新版本
  * @returns {Promise<{current: string, latest: string, hasUpdate: boolean} | null>}
@@ -178,8 +340,13 @@ function performUpdate(latestVersion) {
 
 /**
  * 运行 Yeoman 生成器
+ * @param {string} generator - 生成器名称
+ * @param {object} options - 选项
+ * @param {boolean} options.verbose - 是否启用详细输出
+ * @param {boolean} options.dryRun - 是否启用 dry-run 模式
+ * @param {boolean} options.force - 是否强制覆盖已有文件
  */
-function runGenerator(generator, rest, passthroughArgs) {
+async function runGenerator(generator, options = {}) {
   const localGeneratorEntry = path.join(
     rootDir,
     'generators',
@@ -187,34 +354,50 @@ function runGenerator(generator, rest, passthroughArgs) {
     'index.js'
   );
 
+  if (!fs.existsSync(localGeneratorEntry)) {
+    console.error(`❌ Cannot find generator "${generator}".`);
+    console.error(`   Expected: ${localGeneratorEntry}`);
+    console.error('');
+    console.error('   Run "mico list" to see available generators.');
+    process.exit(1);
+  }
+
   const pkgName = typeof pkg.name === 'string' ? pkg.name : '';
   const localNamespace =
     pkgName.replace(/^generator-/, '') || pkgName || 'generator';
+  const namespace = `${localNamespace}:${generator}`;
 
-  const yoGenerator = fs.existsSync(localGeneratorEntry)
-    ? `${localNamespace}:${generator}`
-    : generator;
-
-  const yoArgs = [yoGenerator, ...rest];
-
-  if (passthroughArgs.length > 0) {
-    yoArgs.push('--', ...passthroughArgs);
+  if (options.verbose) {
+    process.env.MICO_VERBOSE = '1';
+  }
+  if (options.dryRun) {
+    process.env.MICO_DRY_RUN = '1';
   }
 
-  const child = spawn('yo', yoArgs, { stdio: 'inherit' });
+  const runOptions = {};
+  if (options.dryRun) {
+    runOptions.dryRun = true;
+  }
+  if (options.force) {
+    runOptions.force = true;
+  }
 
-  child.on('error', (error) => {
-    if (error && error.code === 'ENOENT') {
-      console.error('Cannot find "yo". Install it with: npm install -g yo');
-    } else {
-      console.error(error);
+  if (options.verbose) {
+    console.log('');
+    console.log('  \x1b[2m[verbose] Running generator:', namespace, '\x1b[0m');
+    if (options.dryRun) {
+      console.log('  \x1b[2m[verbose] Dry-run mode enabled\x1b[0m');
     }
-    process.exit(1);
-  });
+    if (options.force) {
+      console.log('  \x1b[2m[verbose] Force mode enabled\x1b[0m');
+    }
+    console.log('');
+  }
 
-  child.on('exit', (code) => {
-    process.exit(typeof code === 'number' ? code : 1);
-  });
+  const yeomanEnv = require('yeoman-environment');
+  const env = yeomanEnv.createEnv();
+  env.register(localGeneratorEntry, namespace);
+  await env.run(namespace, runOptions);
 }
 
 /**
@@ -234,6 +417,9 @@ async function main() {
   const hasHelp = mainArgs.includes('--help') || mainArgs.includes('-h');
   const hasVersion = mainArgs.includes('--version') || mainArgs.includes('-v');
   const skipUpdateCheck = mainArgs.includes('--no-update-check');
+  const isVerbose = mainArgs.includes('--verbose');
+  const isDryRun = mainArgs.includes('--dry-run');
+  const isForce = mainArgs.includes('--force');
 
   // 过滤掉标志参数
   const filteredArgs = mainArgs.filter(
@@ -242,7 +428,10 @@ async function main() {
       arg !== '-h' &&
       arg !== '--version' &&
       arg !== '-v' &&
-      arg !== '--no-update-check'
+      arg !== '--no-update-check' &&
+      arg !== '--verbose' &&
+      arg !== '--dry-run' &&
+      arg !== '--force'
   );
 
   // 处理 --version
@@ -259,6 +448,18 @@ async function main() {
 
   const [command, ...rest] = filteredArgs;
 
+  // 处理 list 命令
+  if (command === 'list' || command === 'ls') {
+    listGenerators();
+    process.exit(0);
+  }
+
+  // 处理 doctor 命令
+  if (command === 'doctor') {
+    const success = await runDoctor();
+    process.exit(success ? 0 : 1);
+  }
+
   // 处理 update 命令
   if (command === 'update') {
     const updateInfo = await checkForUpdate();
@@ -280,8 +481,8 @@ async function main() {
       process.exit(1);
     }
 
-    // 检查更新（除非跳过）
-    if (!skipUpdateCheck) {
+    // 检查更新（除非跳过或 dry-run）
+    if (!skipUpdateCheck && !isDryRun) {
       const updateInfo = await checkForUpdate();
       if (updateInfo && updateInfo.hasUpdate) {
         const shouldUpdate = await askForUpdate(
@@ -300,7 +501,11 @@ async function main() {
     }
 
     // 运行生成器
-    runGenerator(generator, rest.slice(1), passthroughArgs);
+    await runGenerator(generator, {
+      verbose: isVerbose,
+      dryRun: isDryRun,
+      force: isForce
+    });
     return;
   }