generator-mico-cli 0.2.24 → 0.2.25

package/README.md

@@ -10,6 +10,9 @@
 | [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 / 可配置化 / 冗余清理） |
 
 ## 要求
 
@@ -69,20 +72,39 @@ mico create micro-react -- --help
 
 ## 配置文件
 
-可以在项目目录或用户主目录创建 `.micorc` 或 `.micorc.json` 文件来预设默认值：
+可以在项目目录或用户主目录创建 `.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"
+  "defaultSubappName": "subapp",
+  "devPort": "8010",
+  "defaultUmdName": "my-widget",
+  "umdDevPort": "9100"
 }
 ```
 
-配置查找顺序：
-1. 当前目录的 `.micorc` 或 `.micorc.json`
-2. 用户主目录的 `.micorc` 或 `.micorc.json`
+| 字段 | 类型 | 适用生成器 | 说明 | 默认值 |
+|------|------|-----------|------|--------|
+| `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)
 
@@ -138,9 +160,9 @@ mico create subapp-umd
 
 DevTools Sources 面板中可在 `webpack://<name>/src/` 下定位原始 TypeScript 源码进行断点调试。
 
-## 本地调试
+## 开发指南
 
-克隆项目后，执行以下步骤进行本地开发和调试：
+### 环境准备
 
 ```bash
 # 1. 安装依赖
@@ -168,24 +190,92 @@ mico create subapp-react
 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/helpers/setup.js` | 测试共享工具（路径常量、monorepo fixture 工厂） |
+
+### 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

@@ -6,6 +6,10 @@ 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')
@@ -85,8 +89,8 @@ function listGenerators() {
     if (fs.existsSync(metaPath)) {
       try {
         meta = { ...meta, ...JSON.parse(fs.readFileSync(metaPath, 'utf8')) };
-      } catch {
-        // 忽略解析错误
+      } catch (e) {
+        console.warn(`  ⚠ Failed to parse ${metaPath}: ${e.message}`);
       }
     }
 
@@ -409,17 +413,25 @@ function runGenerator(generator, rest, passthroughArgs, options = {}) {
 
   const child = spawn('yo', yoArgs, { stdio: 'inherit', env });
 
+  let exited = false;
+  const quit = (code) => {
+    if (!exited) {
+      exited = true;
+      process.exit(code);
+    }
+  };
+
   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);
     }
-    process.exit(1);
+    quit(1);
   });
 
   child.on('exit', (code) => {
-    process.exit(typeof code === 'number' ? code : 1);
+    quit(typeof code === 'number' ? code : 1);
   });
 }
 

package/generators/micro-react/templates/apps/layout/config/config.dev.ts

@@ -19,6 +19,7 @@ const config: ReturnType<typeof defineConfig> = {
         window.__MICO_MENUS__ = ${JSON.stringify(mockMenus)};
         window.__MICO_PAGES__ = ${JSON.stringify(mockPages)};
         window.__MICO_CONFIG__ = {
+          appId: '<%= projectName %>',
           appName: '<%= projectName %>',
           title: '测试样例',
           logo: '',
@@ -62,7 +63,6 @@ const config: ReturnType<typeof defineConfig> = {
   },
   define: {
     'process.env.NODE_ENV': 'development',
-    'process.env.APP_ID': '<%= projectName %>',
     'process.env.API_BASE_URL': '',
     'process.env.PROXY_SUFFIX': '/proxy/<%= projectName %>_svr',
     'process.env.LOGIN_ENDPOINT':

package/generators/micro-react/templates/apps/layout/config/config.prod.development.ts

@@ -21,7 +21,6 @@ const config: ReturnType<typeof defineConfig> = {
   },
   define: {
     'process.env.NODE_ENV': 'development',
-    'process.env.APP_ID': '<%= projectName %>',
     'process.env.API_BASE_URL': 'https://dashboard-api-test.micoplatform.com',
     'process.env.PROXY_SUFFIX': '/proxy/<%= projectName %>_svr',
     'process.env.LOGIN_ENDPOINT':

package/generators/micro-react/templates/apps/layout/config/config.prod.testing.ts

@@ -21,7 +21,6 @@ const config: ReturnType<typeof defineConfig> = {
   },
   define: {
     'process.env.NODE_ENV': 'testing',
-    'process.env.APP_ID': '<%= projectName %>',
     'process.env.API_BASE_URL': 'https://dashboard-api-test.micoplatform.com',
     'process.env.PROXY_SUFFIX': '/proxy/<%= projectName %>_svr',
     'process.env.LOGIN_ENDPOINT':

package/generators/micro-react/templates/apps/layout/config/config.prod.ts

@@ -16,7 +16,6 @@ const config: ReturnType<typeof defineConfig> = {
   devtool: 'hidden-source-map',
   define: {
     'process.env.NODE_ENV': 'production',
-    'process.env.APP_ID': '<%= projectName %>',
     'process.env.API_BASE_URL': 'https://dashboard-api.micoplatform.com',
     'process.env.PROXY_SUFFIX': '/proxy/<%= projectName %>_svr',
     'process.env.LOGIN_ENDPOINT':

package/generators/micro-react/templates/apps/layout/docs/fix-SSO/346/227/240/351/231/220/351/207/215/345/256/232/345/220/221.md

@@ -0,0 +1,88 @@
+# 修复 SSO 无限重定向循环
+
+> 创建时间：2026-03-12
+
+## 功能概述
+
+修复 SSO 登录流程中 `redirect_count` 防护机制被过早清除，导致 `fetchUserInfo` 返回 401 时可能触发无限 SSO 重定向循环的问题。
+
+## 问题分析
+
+### 原始流程（存在缺陷）
+
+```
+SSO 回跳（URL 含 redirect_count=1 & ticket）
+  → ensureSsoSession() ticket 换 token 成功
+  → 立即删除 redirect_count        ← 问题根因
+  → fetchUserInfo() 返回 401
+  → refreshAuthToken() 失败
+  → handleAuthFailureRedirect() 检查 redirect_count = 0（已被删除）
+  → 允许重定向 → 跳转 SSO
+  → SSO 自动登录回跳 → 重复以上流程 → 无限循环
+```
+
+### 根因
+
+`ensureSsoSession()` 在 ticket 换取 token 成功后**立即删除** URL 中的 `redirect_count` 参数，但后续的 `fetchUserInfo` 尚未执行。当 `fetchUserInfo` 返回 401 且 token 刷新失败时，`handleAuthFailureRedirect()` 因检测不到 `redirect_count` 而误判为首次重定向，触发循环。
+
+## 技术方案
+
+### 核心思路
+
+将 `redirect_count` 的清除时机从"SSO ticket 换 token 成功后"延后到"整个认证流程（SSO + fetchUserInfo）完全成功后"。
+
+### 修复后流程
+
+```
+SSO 回跳（URL 含 redirect_count=1 & ticket）
+  → ensureSsoSession() ticket 换 token 成功
+  → 保留 redirect_count              ← 修复点
+  → fetchUserInfo() 返回 401
+  → refreshAuthToken() 失败
+  → handleAuthFailureRedirect() 检查 redirect_count = 1
+  → 已达最大重定向次数 → 停止重定向 ✅
+```
+
+```
+SSO 回跳（URL 含 redirect_count=1 & ticket）
+  → ensureSsoSession() ticket 换 token 成功
+  → 保留 redirect_count
+  → fetchUserInfo() 成功
+  → clearRedirectCount() 清除 redirect_count ✅
+```
+
+## 文件清单
+
+### 修改文件
+
+| 文件路径 | 修改内容 |
+| --- | --- |
+| `src/common/request/sso.ts` | 移除 `ensureSsoSession` 中过早删除 `redirect_count` 的逻辑；新增 `clearRedirectCount()` 函数 |
+| `src/app.tsx` | 导入 `clearRedirectCount`，在 `fetchUserInfo` 成功后调用 |
+
+## API / 组件接口
+
+### clearRedirectCount
+
+```typescript
+export const clearRedirectCount = (): void
+```
+
+清除 URL 中的 `redirect_count` 参数。仅在整个认证流程完全成功后调用。
+
+## 设计决策
+
+| 决策点 | 选择 | 理由 |
+| --- | --- | --- |
+| redirect_count 清除时机 | 延后到 fetchUserInfo 成功后 | 最小改动，不改变现有 URL 参数机制，仅调整调用时序 |
+| clearRedirectCount 放置位置 | `sso.ts` | 与 `handleAuthFailureRedirect` 同属 SSO 模块，保持内聚 |
+
+## 注意事项
+
+- `handleAuthFailureRedirect` 可能在 `request/index.ts`（refresh 失败时）和 `app.tsx`（fetchUserInfo 返回 null 时）被双重调用，但修复后两处检查到 `redirect_count >= 1` 均会停止重定向，不影响正确性
+- `redirect_count` 最大值为 1，即只允许一次自动 SSO 重定向尝试
+
+## 相关文档
+
+- [请求模块架构](./arch-请求模块.md)
+- [菜单权限控制](./feature-菜单权限控制.md)

package/generators/micro-react/templates/apps/layout/src/app.tsx

@@ -17,6 +17,7 @@ import {
   setMicroAppProps,
 } from './common/micro';
 import {
+  clearRedirectCount,
   ensureSsoSession,
   handleAuthFailureRedirect,
 } from './common/request/sso';
@@ -140,6 +141,7 @@ export async function getInitialState(): Promise<{
   if (getStoredAuthToken()) {
     const userInfo = await fetchUserInfoFn();
     if (userInfo) {
+      clearRedirectCount();
       return {
         fetchUserInfo: fetchUserInfoFn,
         currentUser: userInfo,

package/generators/micro-react/templates/apps/layout/src/common/request/config.ts

@@ -1,8 +1,8 @@
 /**
  * 请求客户端配置管理
- * appId 优先从 window.__MICO_WORKSPACE__ 获取；
+ * appId 优先从 window.__MICO_WORKSPACE__ 获取，其次从 window.__MICO_CONFIG__ 获取；
  * externalLoginPath 优先从 window.__MICO_WORKSPACE__.casServerLoginUrl 获取；
- * 其余 defaultClientOptions / apiBaseUrl / proxySuffix / loginEndpoint / refreshEndpoint 优先从 window.__MICO_CONFIG__ 同名字段获取。
+ * 其余 apiBaseUrl / proxySuffix / loginEndpoint / refreshEndpoint 优先从 window.__MICO_CONFIG__ 同名字段获取，兜底取 process.env 环境变量。
  */
 
 import { getStoredAuthToken } from '../auth/auth-manager';
@@ -20,7 +20,7 @@ function getMicoWorkspace(): Window['__MICO_WORKSPACE__'] {
 
 function buildDefaultClientOptions(): RequestClientOptions {
   const envDefaults: RequestClientOptions = {
-    appId: process.env.APP_ID ?? '',
+    appId: '',
     ticketParam: 'ticket',
     logoutPath: '/logout',
     apiBaseUrl: process.env.API_BASE_URL ?? '',

package/generators/micro-react/templates/apps/layout/src/common/request/interceptors.ts

@@ -184,7 +184,6 @@ export const initDefaultInterceptors = (
     return data;
   });
 
-
   // 处理业务错误码（{ code, msg, data } 格式）
   addResponseInterceptor(async (data: unknown) => {
     if (
@@ -194,16 +193,17 @@ export const initDefaultInterceptors = (
       !('result' in data) &&
       !('success' in data)
     ) {
-      const typedData = data as { code?: number; msg?: string };
-      if (typeof typedData.code === 'number' && typedData.code !== 200) {
+      const typedData = data as { code?: number | string; msg?: string };
+      const code = Number(typedData.code);
+      if (!isNaN(code) && code !== 200 && code !== 0) {
         const error = new Error(
-          typedData.msg || `请求失败 (${typedData.code})`,
+          typedData.msg || `请求失败 (${code})`,
         ) as Error & {
           code: number;
           msg: string;
           response: unknown;
         };
-        error.code = typedData.code;
+        error.code = code;
         error.msg = typedData.msg || '';
         error.response = data;
         throw error;

package/generators/micro-react/templates/apps/layout/src/common/request/sso.ts

@@ -113,16 +113,6 @@ export const ensureSsoSession = async (): Promise<void> => {
         setFetchingToken(false);
 
         if (resolveAuthToken()) {
-          // SSO 认证成功，删除 URL 中的 redirect_count 参数
-          if (typeof window !== 'undefined') {
-            const current = new URL(window.location.href);
-            current.searchParams.delete('redirect_count');
-            const nextUrl = `${current.pathname}${
-              current.search ? `?${current.searchParams}` : ''
-            }${current.hash}`;
-            window.history.replaceState(null, '', nextUrl);
-          }
-
           processPendingRequests();
         } else {
           throw new Error('SSO 认证失败');
@@ -143,3 +133,19 @@ export const ensureSsoSession = async (): Promise<void> => {
 
   await ticketPromise;
 };
+
+/**
+ * 清除 URL 中的 redirect_count 参数
+ * 仅在整个认证流程（SSO + fetchUserInfo）完全成功后调用，
+ * 避免过早清除导致无限重定向循环
+ */
+export const clearRedirectCount = (): void => {
+  if (typeof window === 'undefined') return;
+  const current = new URL(window.location.href);
+  if (!current.searchParams.has('redirect_count')) return;
+  current.searchParams.delete('redirect_count');
+  const nextUrl = `${current.pathname}${
+    current.search ? `?${current.searchParams}` : ''
+  }${current.hash}`;
+  window.history.replaceState(null, '', nextUrl);
+};

package/generators/micro-react/templates/apps/layout/src/components/MicroAppLoader/index.tsx

@@ -86,6 +86,10 @@ const MicroAppLoader: React.FC<MicroAppLoaderProps> = ({
     };
   }, [env, routePath]);
 
+  // ref 持有最新的 buildProps，避免加载 effect 依赖它导致子应用被重载
+  const buildPropsRef = useRef(buildProps);
+  buildPropsRef.current = buildProps;
+
   // 当 props 变化时，通知子应用更新（不重新加载）
   useEffect(() => {
     if (state.mounted) {
@@ -93,7 +97,7 @@ const MicroAppLoader: React.FC<MicroAppLoaderProps> = ({
     }
   }, [state.mounted, buildProps]);
 
-  // 加载微应用
+  // 加载微应用（只在 entry/appName/isAuthReady 变化时触发）
   useEffect(() => {
     const wrapper = wrapperRef.current;
     if (!wrapper) {
@@ -117,7 +121,7 @@ const MicroAppLoader: React.FC<MicroAppLoaderProps> = ({
       name: appName,
       entry,
       target: wrapper,
-      props: buildProps(),
+      props: buildPropsRef.current(),
     });
 
     return () => {
@@ -125,7 +129,7 @@ const MicroAppLoader: React.FC<MicroAppLoaderProps> = ({
       microAppManager.cancel();
       microAppManager.setStateCallback(null);
     };
-  }, [entry, appName, isAuthReady, buildProps]);
+  }, [entry, appName, isAuthReady]);
 
   return (
     <div className="micro-app-container">

package/generators/micro-react/templates/apps/layout/src/layouts/index.less

@@ -79,7 +79,7 @@ body {
   }
 }
 
-.<%= projectName %>-sider {
+.layout-web-sider {
   box-shadow: none;
   background-color: @color-text-5;
   z-index: 999;

package/generators/subapp-react/index.js

@@ -10,6 +10,7 @@ const {
   transformDestPath,
   isTemplateFile,
   getPackageVersionsParallel,
+  detectPackageScope,
   setupErrorHandlers,
   createLogger,
   loadMicorc,
@@ -61,24 +62,6 @@ module.exports = class extends Generator {
     }
   }
 
-  _detectPackageScope() {
-    // 从根 package.json 的 name 推断 scope（与 micro-react 生成的项目一致）
-    const rootPkgPath = path.join(this.monorepoRoot, 'package.json');
-    if (fs.existsSync(rootPkgPath)) {
-      try {
-        const pkg = JSON.parse(fs.readFileSync(rootPkgPath, 'utf-8'));
-        if (pkg.name) {
-          return pkg.name.startsWith('@')
-            ? pkg.name.replace(/^(@[^/]+)\/.*/, '$1')
-            : `@${pkg.name}`;
-        }
-      } catch (e) {
-        // 忽略解析错误
-      }
-    }
-    return null;
-  }
-
   async prompting() {
     try {
       if (!this.monorepoRoot) {
@@ -88,7 +71,7 @@ module.exports = class extends Generator {
         process.exit(1);
       }
 
-      const detectedScope = this._detectPackageScope();
+      const detectedScope = detectPackageScope(this.monorepoRoot);
       const rc = this.rcConfig || {};
 
       this.answers = await this.prompt([
@@ -349,7 +332,7 @@ module.exports = class extends Generator {
         '    accessControlEnabled: false,',
         '    adminOnly: false,',
         '    routeKey: null,',
-        `    mainDocumentId: ${Math.floor(Math.random() * 900) + 100},`,
+        `    mainDocumentId: ${maxId + 1},`,
         "    version: '',",
         '  },',
       ].join('\n');

package/generators/subapp-umd/index.js

@@ -10,6 +10,7 @@ const {
   collectFiles,
   transformDestPath,
   isTemplateFile,
+  detectPackageScope,
   setupErrorHandlers,
   createLogger,
   loadMicorc,
@@ -53,26 +54,9 @@ module.exports = class extends Generator {
     }
   }
 
-  _detectPackageScope() {
-    const rootPkgPath = path.join(this.monorepoRoot, 'package.json');
-    if (fs.existsSync(rootPkgPath)) {
-      try {
-        const pkg = JSON.parse(fs.readFileSync(rootPkgPath, 'utf-8'));
-        if (pkg.name) {
-          return pkg.name.startsWith('@')
-            ? pkg.name.replace(/^(@[^/]+)\/.*/, '$1')
-            : `@${pkg.name}`;
-        }
-      } catch (e) {
-        // ignore
-      }
-    }
-    return null;
-  }
-
   async prompting() {
     try {
-      const detectedScope = this._detectPackageScope();
+      const detectedScope = detectPackageScope(this.monorepoRoot);
       const rc = this.rcConfig || {};
 
       this.answers = await this.prompt([

package/generators/subapp-umd/templates/webpack.config.js

@@ -57,8 +57,10 @@ module.exports = (env, argv) => {
       port: <%= devPort %>,
       hot: true,
       open: false,
+      allowedHosts: 'all',
       headers: {
         'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Methods': 'GET',
       },
       static: {
         directory: path.join(__dirname, 'public'),

package/lib/utils.js

@@ -2,7 +2,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { execSync, exec } = require('node:child_process');
+const { execSync, execFileSync, execFile } = require('node:child_process');
 const os = require('node:os');
 
 /**
@@ -122,6 +122,31 @@ function isTemplateFile(filePath) {
   return TEMPLATE_EXTENSIONS.has(path.extname(filePath));
 }
 
+/**
+ * 从 monorepo 根目录的 package.json 推断包 scope
+ * @param {string} monorepoRoot - monorepo 根目录路径
+ * @returns {string|null} 推断出的 scope（如 '@my-project'），未找到返回 null
+ */
+function detectPackageScope(monorepoRoot) {
+  const rootPkgPath = path.join(monorepoRoot, 'package.json');
+  if (fs.existsSync(rootPkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(rootPkgPath, 'utf-8'));
+      if (pkg.name) {
+        return pkg.name.startsWith('@')
+          ? pkg.name.replace(/^(@[^/]+)\/.*/, '$1')
+          : `@${pkg.name}`;
+      }
+    } catch {
+      // ignore
+    }
+  }
+  return null;
+}
+
+/** 合法 npm 包名正则：可选 @scope/name，仅允许字母数字、连字符、点、下划线 */
+const VALID_PACKAGE_NAME_RE = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/i;
+
 /** scope 包含 mico 时使用的 registry（如 @mico-platform/*） */
 const MICO_NPM_REGISTRY = 'https://nexus-vywrajy.micoworld.net/repository/mico-base-common/';
 
@@ -146,11 +171,14 @@ function getRegistryForPackage(packageName) {
  * @returns {string} 版本号，如 '1.2.3'
  */
 function getLatestNpmVersion(packageName, fallback = '1.0.0', timeoutMs = 8000, cwd) {
+  if (!VALID_PACKAGE_NAME_RE.test(packageName)) {
+    return fallback;
+  }
   const registry = getRegistryForPackage(packageName);
-  const registryArg = registry ? `--registry=${registry}` : '';
+  const args = ['view', packageName, 'version'];
+  if (registry) args.push(`--registry=${registry}`);
   try {
-    const cmd = `npm view ${packageName} version ${registryArg}`.trim();
-    const out = execSync(cmd, {
+    const out = execFileSync('npm', args, {
       encoding: 'utf-8',
       timeout: timeoutMs,
       stdio: ['pipe', 'pipe', 'pipe'],
@@ -172,28 +200,38 @@ function getLatestNpmVersion(packageName, fallback = '1.0.0', timeoutMs = 8000,
  * @returns {Promise<string>} 版本号，如 '1.2.3'
  */
 function getLatestNpmVersionAsync(packageName, fallback = '1.0.0', timeoutMs = 8000, cwd) {
+  if (!VALID_PACKAGE_NAME_RE.test(packageName)) {
+    return Promise.resolve(fallback);
+  }
   return new Promise((resolve) => {
+    let settled = false;
+    const done = (value) => {
+      if (!settled) {
+        settled = true;
+        resolve(value);
+      }
+    };
+
     const registry = getRegistryForPackage(packageName);
-    const registryArg = registry ? `--registry=${registry}` : '';
-    const cmd = `npm view ${packageName} version ${registryArg}`.trim();
+    const args = ['view', packageName, 'version'];
+    if (registry) args.push(`--registry=${registry}`);
 
-    const child = exec(cmd, {
+    const child = execFile('npm', args, {
       encoding: 'utf-8',
       timeout: timeoutMs,
       ...(cwd && { cwd })
     }, (error, stdout) => {
       if (error) {
-        resolve(fallback);
+        done(fallback);
         return;
       }
       const v = stdout.trim();
-      resolve(v && /^\d+\.\d+\.\d+/.test(v) ? v : fallback);
+      done(v && /^\d+\.\d+\.\d+/.test(v) ? v : fallback);
     });
 
-    // 确保超时后也能 resolve
     setTimeout(() => {
       child.kill();
-      resolve(fallback);
+      done(fallback);
     }, timeoutMs + 100);
   });
 }
@@ -277,8 +315,7 @@ function mergeDefaults(defaults, rcConfig) {
  */
 function checkCommand(command) {
   try {
-    const versionFlag = command === 'pnpm' ? '--version' : '--version';
-    const out = execSync(`${command} ${versionFlag}`, {
+    const out = execSync(`${command} --version`, {
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],
       timeout: 5000
@@ -396,8 +433,11 @@ function createLogger(generator) {
 
 /**
  * 安装全局未捕获异常处理
+ * 在 Vitest 等测试环境中自动跳过，避免干扰测试 runner 的进程管理
  */
 function setupErrorHandlers() {
+  if (process.env.VITEST) return;
+
   process.on('uncaughtException', (error) => {
     console.error('');
     console.error('❌ Unexpected error:');
@@ -431,6 +471,7 @@ module.exports = {
   toPascal,
   toCamel,
   // Generator 工具
+  detectPackageScope,
   shouldIgnorePath,
   collectFiles,
   transformDestPath,

package/package.json

@@ -1,22 +1,35 @@
 {
   "name": "generator-mico-cli",
-  "version": "0.2.24",
+  "version": "0.2.25",
   "description": "Yeoman generator for Mico CLI projects",
-  "keywords": ["yeoman-generator", "generator", "cli"],
+  "keywords": [
+    "yeoman-generator",
+    "generator",
+    "cli"
+  ],
   "license": "MIT",
   "main": "generators/subapp-react/index.js",
   "bin": {
     "mico": "bin/mico.js"
   },
-  "files": ["bin", "lib", "generators"],
+  "files": [
+    "bin",
+    "lib",
+    "generators"
+  ],
   "scripts": {
     "format": "biome format --write .",
     "format:check": "biome format .",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "sync:subapp-react-template": "node scripts/sync-subapp-react-template.js",
     "verify:micro-react": "node scripts/verify-micro-react.js"
   },
   "devDependencies": {
-    "@biomejs/biome": "^1.9.4"
+    "@biomejs/biome": "^1.9.4",
+    "vitest": "^4.0.18",
+    "yeoman-environment": "^3.19.3",
+    "yeoman-test": "^6.3.0"
   },
   "engines": {
     "node": ">=18"