generator-mico-cli 0.1.18

package/README.md

@@ -0,0 +1,84 @@
+# Mico CLI Generator
+
+用于搭建基于 TypeScript 的 Node.js CLI 项目的 Yeoman 生成器。
+
+## 文档索引
+
+| 文档 | 说明 |
+|---|---|
+| [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 子应用生成器说明 |
+
+## 要求
+
+- Node >= 18
+- Yeoman CLI: `npm install -g yo`
+
+## 安装和使用
+
+```bash
+npm install -g yo generator-mico-cli
+```
+
+## 包装器 CLI
+
+全局安装后，`mico` 命令可用于委托给 Yeoman 生成器。
+如果 `generators/<name>` 下存在本地生成器，它将作为 `yo mico-cli:<name>` 运行。
+
+```bash
+mico create subapp-react
+```
+
+等同于：
+
+```bash
+yo subapp-react
+```
+
+将额外参数传递给生成器：
+
+```bash
+mico create micro-react -- --help
+```
+
+## Monorepo 项目生成器 (micro-react)
+
+创建基于 qiankun 微前端架构的完整 Monorepo 项目：
+
+```bash
+mkdir my-project && cd my-project
+mico create micro-react
+```
+
+生成的项目包含：
+- 主应用 (layout) - qiankun master
+- 共享样式包 (shared-styles)
+- Turborepo + pnpm Workspace
+- Husky + Commitlint
+
+## React 子应用生成器
+
+该生成器会复制 `apps/homepage` 模板为新的子应用，并替换标识字符串。
+`config/` 目录下的多环境配置会完整保留。
+
+```bash
+cd <monorepo-root>
+mico create subapp-react
+```
+
+## 同步子应用模板
+
+将源项目的 `apps/homepage` 同步到生成器模板目录：
+
+```bash
+SOURCE_PROJECT_ROOT=<source-project-root> npm run sync:subapp-react-template
+```
+
+也可以直接传入路径：
+
+```bash
+npm run sync:subapp-react-template -- <source-project-root>
+```
+
+忽略清单位于 `generators/subapp-react/ignore-list.json`。

package/bin/mico.js

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawn, spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const readline = require('node:readline');
+
+const rootDir = path.resolve(__dirname, '..');
+const pkg = JSON.parse(
+  fs.readFileSync(path.join(rootDir, 'package.json'), 'utf8')
+);
+
+/**
+ * 打印帮助信息
+ */
+function printHelp() {
+  console.log(`
+Usage: mico <command> [options]
+
+Commands:
+  create <generator>    Run a generator (e.g., mico create subapp-react)
+  update                Update mico-cli to the latest version
+
+Options:
+  --help, -h            Show this help message
+  --version, -v         Show version number
+  --no-update-check     Skip update check
+
+Examples:
+  mico create subapp-react
+  mico create app
+  mico update
+
+Notes:
+  Requires Yeoman CLI (yo) installed globally.
+  If a local generator exists at generators/<name>, it will be used.
+`);
+}
+
+/**
+ * 打印版本信息
+ */
+function printVersion() {
+  console.log(`mico-cli v${pkg.version}`);
+}
+
+/**
+ * 检查是否有新版本
+ * @returns {Promise<{current: string, latest: string, hasUpdate: boolean} | null>}
+ */
+async function checkForUpdate() {
+  try {
+    const updateNotifier = (await import('update-notifier')).default;
+    const semver = (await import('semver')).default;
+    const notifier = updateNotifier({
+      pkg,
+      updateCheckInterval: 0 // 每次都检查
+    });
+
+    // 等待检查完成
+    await notifier.fetchInfo();
+
+    // 使用 semver 比较，确保 latest > current
+    if (notifier.update && semver.gt(notifier.update.latest, pkg.version)) {
+      return {
+        current: pkg.version,
+        latest: notifier.update.latest,
+        hasUpdate: true
+      };
+    }
+    return { current: pkg.version, latest: pkg.version, hasUpdate: false };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 询问用户是否更新
+ * @returns {Promise<boolean>}
+ */
+function askForUpdate(current, latest) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    console.log('');
+    console.log(`  📦 New version available: ${current} → \x1b[32m${latest}\x1b[0m`);
+    rl.question('  Do you want to update now? (Y/n) ', (answer) => {
+      rl.close();
+      const normalized = answer.trim().toLowerCase();
+      resolve(normalized === '' || normalized === 'y' || normalized === 'yes');
+    });
+  });
+}
+
+/**
+ * 检测当前使用的包管理器
+ * 通过检查可执行文件的安装路径来判断
+ * @returns {'npm' | 'pnpm' | 'yarn'}
+ */
+function detectPackageManager() {
+  // 首先检查环境变量（通过包管理器脚本运行时有效）
+  const npmUserAgent = process.env.npm_config_user_agent || '';
+  if (npmUserAgent.includes('pnpm')) return 'pnpm';
+  if (npmUserAgent.includes('yarn')) return 'yarn';
+
+  // 检查当前脚本的安装路径
+  // pnpm 全局安装路径通常包含: pnpm, .local/share/pnpm, Library/pnpm
+  const scriptPath = process.argv[1] || '';
+  const scriptPathLower = scriptPath.toLowerCase();
+  if (
+    scriptPathLower.includes('pnpm') ||
+    scriptPathLower.includes('.local/share/pnpm') ||
+    scriptPathLower.includes('library/pnpm')
+  ) {
+    return 'pnpm';
+  }
+  if (scriptPathLower.includes('yarn')) return 'yarn';
+
+  // 检查 rootDir 路径（当前包的安装位置）
+  const rootDirLower = rootDir.toLowerCase();
+  if (
+    rootDirLower.includes('pnpm') ||
+    rootDirLower.includes('.local/share/pnpm') ||
+    rootDirLower.includes('library/pnpm')
+  ) {
+    return 'pnpm';
+  }
+  if (rootDirLower.includes('yarn')) return 'yarn';
+
+  // 默认使用 npm
+  return 'npm';
+}
+
+/**
+ * 执行更新
+ * @param {string} latestVersion - 要更新到的版本号
+ * @returns {boolean} 是否更新成功
+ */
+function performUpdate(latestVersion) {
+  console.log('');
+  console.log('  ⏳ Updating mico-cli...');
+
+  // 检测包管理器
+  const pm = detectPackageManager();
+
+  // 指定具体版本号，避免缓存问题
+  const packageSpec = latestVersion ? `${pkg.name}@${latestVersion}` : `${pkg.name}@latest`;
+
+  // 执行全局安装
+  const installCmd = pm === 'yarn' ? 'yarn' : pm;
+  const installArgs =
+    pm === 'yarn'
+      ? ['global', 'add', packageSpec]
+      : ['install', '-g', packageSpec];
+
+  console.log(`  Using ${pm} to install ${packageSpec}`);
+
+  const result = spawnSync(installCmd, installArgs, {
+    stdio: 'inherit',
+    shell: process.platform === 'win32'
+  });
+
+  if (result.status === 0) {
+    console.log('');
+    console.log('  ✅ Update successful! Please re-run your command.');
+    return true;
+  } else {
+    console.log('');
+    console.log('  ❌ Update failed. Please try manually:');
+    console.log(`     ${installCmd} ${installArgs.join(' ')}`);
+    return false;
+  }
+}
+
+/**
+ * 运行 Yeoman 生成器
+ */
+function runGenerator(generator, rest, passthroughArgs) {
+  const localGeneratorEntry = path.join(
+    rootDir,
+    'generators',
+    generator,
+    'index.js'
+  );
+
+  const pkgName = typeof pkg.name === 'string' ? pkg.name : '';
+  const localNamespace =
+    pkgName.replace(/^generator-/, '') || pkgName || 'generator';
+
+  const yoGenerator = fs.existsSync(localGeneratorEntry)
+    ? `${localNamespace}:${generator}`
+    : generator;
+
+  const yoArgs = [yoGenerator, ...rest];
+
+  if (passthroughArgs.length > 0) {
+    yoArgs.push('--', ...passthroughArgs);
+  }
+
+  const child = spawn('yo', yoArgs, { stdio: 'inherit' });
+
+  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);
+  });
+
+  child.on('exit', (code) => {
+    process.exit(typeof code === 'number' ? code : 1);
+  });
+}
+
+/**
+ * 主函数
+ */
+async function main() {
+  const args = process.argv.slice(2);
+
+  // 解析参数
+  const doubleDashIndex = args.indexOf('--');
+  const passthroughArgs =
+    doubleDashIndex === -1 ? [] : args.slice(doubleDashIndex + 1);
+  const mainArgs =
+    doubleDashIndex === -1 ? args : args.slice(0, doubleDashIndex);
+
+  // 检查特殊标志
+  const hasHelp = mainArgs.includes('--help') || mainArgs.includes('-h');
+  const hasVersion = mainArgs.includes('--version') || mainArgs.includes('-v');
+  const skipUpdateCheck = mainArgs.includes('--no-update-check');
+
+  // 过滤掉标志参数
+  const filteredArgs = mainArgs.filter(
+    (arg) =>
+      arg !== '--help' &&
+      arg !== '-h' &&
+      arg !== '--version' &&
+      arg !== '-v' &&
+      arg !== '--no-update-check'
+  );
+
+  // 处理 --version
+  if (hasVersion) {
+    printVersion();
+    process.exit(0);
+  }
+
+  // 处理 --help 或无参数
+  if (hasHelp || filteredArgs.length === 0) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const [command, ...rest] = filteredArgs;
+
+  // 处理 update 命令
+  if (command === 'update') {
+    const updateInfo = await checkForUpdate();
+    if (updateInfo && updateInfo.hasUpdate) {
+      performUpdate(updateInfo.latest);
+    } else if (updateInfo) {
+      console.log(`  ✅ You are using the latest version (v${updateInfo.current})`);
+    } else {
+      console.log('  ⚠️  Could not check for updates');
+    }
+    process.exit(0);
+  }
+
+  // 处理 create 命令
+  if (command === 'create') {
+    const generator = rest[0];
+    if (!generator) {
+      printHelp();
+      process.exit(1);
+    }
+
+    // 检查更新（除非跳过）
+    if (!skipUpdateCheck) {
+      const updateInfo = await checkForUpdate();
+      if (updateInfo && updateInfo.hasUpdate) {
+        const shouldUpdate = await askForUpdate(
+          updateInfo.current,
+          updateInfo.latest
+        );
+        if (shouldUpdate) {
+          const success = performUpdate(updateInfo.latest);
+          if (success) {
+            process.exit(0);
+          }
+          // 更新失败则继续执行
+        }
+        console.log('');
+      }
+    }
+
+    // 运行生成器
+    runGenerator(generator, rest.slice(1), passthroughArgs);
+    return;
+  }
+
+  // 未知命令
+  console.error(`Unknown command: ${command}`);
+  printHelp();
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/generators/micro-react/ignore-list.json

@@ -0,0 +1,8 @@
+[
+  "node_modules",
+  "dist",
+  ".umi",
+  ".umi-production",
+  ".turbo",
+  "pnpm-lock.yaml"
+]

package/generators/micro-react/index.js

@@ -0,0 +1,158 @@
+'use strict';
+
+const Generator = require('yeoman-generator');
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  toKebab,
+  toPascal,
+  collectFiles,
+  transformDestPath,
+  isTemplateFile,
+  setupErrorHandlers
+} = require('../../lib/utils');
+
+const IGNORE_LIST = require('./ignore-list.json');
+
+// 安装全局错误处理
+setupErrorHandlers();
+
+module.exports = class extends Generator {
+  initializing() {
+    this.projectRoot = process.cwd();
+
+    // 检查当前目录是否已是一个 monorepo
+    const workspaceFile = path.join(this.projectRoot, 'pnpm-workspace.yaml');
+    if (fs.existsSync(workspaceFile)) {
+      console.error('');
+      console.error('❌ Error: Current directory is already a monorepo.');
+      console.error('');
+      console.error('   A pnpm-workspace.yaml file already exists.');
+      console.error('   Please run this command in an empty directory or specify a new project name.');
+      console.error('');
+      console.error('   Usage:');
+      console.error('     mkdir my-project && cd my-project');
+      console.error('     mico create micro-react');
+      console.error('');
+      process.exit(1);
+    }
+  }
+
+  async prompting() {
+    try {
+      this.answers = await this.prompt([
+        {
+          type: 'input',
+          name: 'projectName',
+          message: 'Project name',
+          default: path.basename(this.projectRoot),
+          filter: (input) => toKebab(input),
+          validate: (input) => {
+            const value = toKebab(input);
+            if (!value) return 'Project name is required';
+            return true;
+          }
+        },
+        {
+          type: 'input',
+          name: 'packageScope',
+          message: 'Package scope (e.g., @my-project)',
+          default: (answers) => `@${toKebab(answers.projectName)}`,
+          validate: (input) => {
+            if (!input) return 'Package scope is required';
+            if (!input.startsWith('@')) return 'Package scope must start with @';
+            return true;
+          }
+        },
+        {
+          type: 'input',
+          name: 'author',
+          message: 'Author',
+          default: 'Your Name <email@example.com>'
+        }
+      ]);
+
+      this.projectName = toKebab(this.answers.projectName);
+      this.ProjectName = toPascal(this.projectName);
+      this.packageScope = this.answers.packageScope;
+      this.author = this.answers.author;
+      this.templateDir = this.templatePath();
+      this.destDir = this.projectRoot;
+    } catch (error) {
+      console.error('');
+      console.error('❌ Error during prompting:');
+      console.error(`   ${error.message}`);
+      console.error('');
+      process.exit(1);
+    }
+  }
+
+  writing() {
+    try {
+      if (!fs.existsSync(this.templateDir)) {
+        console.error('');
+        console.error('❌ Error: Template directory not found.');
+        console.error(`   Expected: ${this.templateDir}`);
+        console.error('');
+        process.exit(1);
+      }
+
+      const templateData = {
+        projectName: this.projectName,
+        ProjectName: this.ProjectName,
+        packageScope: this.packageScope,
+        author: this.author
+      };
+
+      const files = collectFiles(this.templateDir, this.templateDir, IGNORE_LIST);
+
+      if (files.length === 0) {
+        console.error('');
+        console.error('❌ Error: No template files found.');
+        console.error(`   Template directory: ${this.templateDir}`);
+        console.error('');
+        process.exit(1);
+      }
+
+      this.log('');
+      this.log(`📦 Creating project: ${this.projectName}`);
+      this.log(`   Scope: ${this.packageScope}`);
+      this.log('');
+
+      for (const relPath of files) {
+        const srcPath = path.join(this.templateDir, relPath);
+        const destRelPath = transformDestPath(relPath);
+        const destPath = path.join(this.destDir, destRelPath);
+
+        if (isTemplateFile(relPath)) {
+          this.fs.copyTpl(srcPath, destPath, templateData);
+        } else {
+          this.fs.copy(srcPath, destPath);
+        }
+      }
+    } catch (error) {
+      console.error('');
+      console.error('❌ Error during file generation:');
+      console.error(`   ${error.message}`);
+      console.error('');
+      process.exit(1);
+    }
+  }
+
+  end() {
+    this.log('');
+    this.log('✅ 项目创建成功！');
+    this.log('');
+    this.log('   后续步骤:');
+    this.log('');
+    this.log('   # 安装依赖');
+    this.log('   pnpm install');
+    this.log('');
+    this.log('   # 启动开发服务器');
+    this.log('   pnpm dev');
+    this.log('');
+    this.log('   # 创建新的子应用');
+    this.log('   mico create subapp-react');
+    this.log('');
+  }
+};

package/generators/micro-react/templates/.commitlintrc.js

@@ -0,0 +1,6 @@
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'header-max-length': [0, 'always', 10000],
+  },
+};

package/generators/micro-react/templates/.cursor/rules/always-read-docs.mdc

@@ -0,0 +1,129 @@
+---
+description: 开发前必读 - 强制查阅项目文档
+alwaysApply: true
+---
+
+# 开发前必读文档
+
+## ⚠️ 重要规则
+
+**在开始任何开发需求之前，必须先查阅相关文档！**
+
+## 📚 文档位置
+
+### 1. 项目级文档 (`/docs/`)
+```
+docs/
+└── commit-message.md      # Git 提交规范
+```
+
+### 2. Layout 应用文档 (`/apps/layout/docs/`)
+```
+apps/layout/docs/
+├── feature-微前端模式.md   # qiankun 微前端架构
+└── feature-主题色切换.md   # 主题系统实现
+```
+
+### 3. 其他应用文档
+每个子应用可能在 `apps/<app>/docs/` 下有功能文档。
+
+## 🔍 开发前检查清单
+
+在开始开发需求时，请按以下步骤操作：
+
+### Step 1: 确认需求涉及的模块
+- 微前端相关 → 阅读 `apps/layout/docs/feature-微前端模式.md`
+- 主题/样式相关 → 阅读 `apps/layout/docs/feature-主题色切换.md`
+- 请求/认证相关 → 阅读 `src/common/request/` 和 `src/common/auth/` 源码
+- 菜单相关 → 阅读 `src/common/menu/` 源码
+
+### Step 2: 查找相关文档
+```bash
+# 搜索 docs 目录
+find . -path "*/docs/*.md" -type f
+
+# 搜索所有 markdown 文档
+find . -name "*.md" -type f | grep -v node_modules
+```
+
+### Step 3: 阅读相关源码目录的 README
+某些目录下可能有 `README.md` 或 `index.ts` 中的注释说明。
+
+## 📋 常用文档速查
+
+| 需求类型 | 必读文档 |
+|---------|---------|
+| 新建子应用 | `apps/layout/docs/feature-微前端模式.md` |
+| 主题适配 | `apps/layout/docs/feature-主题色切换.md` |
+| 提交代码 | `docs/commit-message.md` |
+| API 请求 | `src/common/request/index.ts` 源码注释 |
+| 认证登录 | `src/common/auth/` 目录源码 |
+| 菜单配置 | `src/common/menu/types.ts` 类型定义 |
+
+## 🚨 AI 助手行为要求
+
+1. **接收到开发需求时**：
+   - 首先识别需求涉及哪些模块
+   - 使用 `list_dir` 查看对应目录是否有 docs 文件夹
+   - 使用 `read_file` 阅读相关文档
+   - 阅读相关源码理解现有实现
+
+2. **修改现有功能时**：
+   - 先阅读该功能的现有代码
+   - 查找是否有对应的文档说明
+   - 理解设计意图后再进行修改
+
+3. **新增功能时**：
+   - 参考类似功能的实现方式
+   - 遵循项目现有的代码风格和架构模式
+   - 考虑是否需要同步更新文档
+
+## 📝 文档模板
+
+新功能开发完成后，建议创建对应文档：
+
+```markdown
+# 功能名称
+
+> 创建时间：YYYY-MM-DD
+
+## 功能概述
+
+简要描述功能用途。
+
+## 技术方案
+
+### 技术栈
+- 列出使用的技术
+
+### 核心实现
+1. 实现步骤 1
+2. 实现步骤 2
+
+## 文件清单
+
+| 文件路径 | 说明 |
+|---------|------|
+| `src/xxx` | 描述 |
+
+## API / 组件接口
+
+```typescript
+// 接口定义
+```
+
+## 使用示例
+
+```tsx
+// 代码示例
+```
+
+## 注意事项
+
+- 注意点 1
+- 注意点 2
+
+## 相关文档
+
+- [相关文档 1](./xxx.md)
+```