generator-mico-cli 0.2.31 → 0.2.32

package/README.md

@@ -4,16 +4,26 @@
 
 ## 文档索引
 
+### 项目总览与设计
+
 | 文档 | 说明 |
 |---|---|
+| [docs/mico-cli.md](docs/mico-cli.md) | `mico` CLI 整体能力、命令清单（`create` / `list` / `doctor` / `--verbose` / `--dry-run`）与子进程调用约定 |
 | [docs/architecture.md](docs/architecture.md) | 项目架构、模块职责、关键约定、依赖关系 |
-| [docs/generators.md](docs/generators.md) | 三个生成器的 prompt / 模板变量 / 联动修改细节 |
-| [docs/configuration.md](docs/configuration.md) | `.micorc` 配置字段与加载顺序 |
-| [docs/testing.md](docs/testing.md) | Vitest + yeoman-test 测试体系与 Mock 策略 |
-| [docs/scripts.md](docs/scripts.md) | `sync:subapp-react-template` 与 `verify:micro-react` |
-| [generators/micro-react/README.md](generators/micro-react/README.md) | `micro-react` 生成器就近说明 |
-| [generators/subapp-react/README.md](generators/subapp-react/README.md) | `subapp-react` 生成器就近说明 |
-| [generators/subapp-umd/README.md](generators/subapp-umd/README.md) | `subapp-umd` 生成器就近说明 |
+| [docs/generators.md](docs/generators.md) | 各生成器的 prompt / 模板变量 / 联动修改细节（生成器之间的协作总览） |
+| [docs/configuration.md](docs/configuration.md) | `.micorc` / `.micorc.json` 配置字段、加载顺序与默认值 |
+| [docs/testing.md](docs/testing.md) | Vitest + yeoman-test 测试体系、目录结构与 Mock 策略 |
+| [docs/scripts.md](docs/scripts.md) | `sync:subapp-react-template` 与 `verify:micro-react` 辅助脚本 |
+
+### 各生成器使用说明（按生成器拆分，建议先于代码改动阅读）
+
+| 生成器 | 使用说明 | 仓库内就近说明 |
+|---|---|---|
+| `micro-react`（qiankun Monorepo 基座） | [docs/micro-react-generator.md](docs/micro-react-generator.md) | [generators/micro-react/README.md](generators/micro-react/README.md) |
+| `subapp-react`（在已有 Monorepo 中新增 React 子应用） | [docs/subapp-react-generator.md](docs/subapp-react-generator.md) | [generators/subapp-react/README.md](generators/subapp-react/README.md) |
+| `h5-react`（Umi 4 H5 Monorepo 基座 + 联动 `subapp-h5`） | [docs/h5-react-generator.md](docs/h5-react-generator.md) | —（模板内置 README，由生成器写入目标项目根目录） |
+| `subapp-h5`（在 H5 Monorepo 中新增 Umi 子应用） | [docs/subapp-h5-generator.md](docs/subapp-h5-generator.md) | —（无独立 README，约定见上文与 `templates/.cursor/rules/`） |
+| `subapp-umd`（UMD 组件包，`<script>` 加载场景） | —（详见本 README 「UMD 组件包生成器」一节） | [generators/subapp-umd/README.md](generators/subapp-umd/README.md) |
 
 ## 要求
 
@@ -57,6 +67,14 @@ mico create micro-react --dry-run
 mico doctor
 ```
 
+执行配置任务（如配置自托管 Multica Desktop）：
+
+```bash
+mico setup multica-desktop
+```
+
+详见下文 [Multica Desktop 自托管配置](#multica-desktop-自托管配置setup-multica-desktop)。
+
 ## 配置文件
 
 可以在项目目录或用户主目录创建 `.micorc` 或 `.micorc.json` 文件来预设默认值。
@@ -74,6 +92,8 @@ mico doctor
   "packageScope": "@my-company",
   "cdnPrefix": "portal",
   "author": "Team <team@example.com>",
+  "initialSubAppName": "app",
+  "initialSubAppDevPort": "8000",
   "defaultSubappName": "subapp",
   "devPort": "8010",
   "defaultUmdName": "my-widget",
@@ -83,13 +103,15 @@ mico doctor
 
 | 字段 | 类型 | 适用生成器 | 说明 | 默认值 |
 |------|------|-----------|------|--------|
-| `projectName` | string | micro-react | 项目名称 | 当前目录名 |
+| `projectName` | string | micro-react、h5-react | 项目名称 | 当前目录名 |
 | `appId` | string | micro-react | 开发环境 `window.__MICO_CONFIG__.appId`（请求代理等） | `portal_dev` |
-| `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` |
+| `packageScope` | string | 所有 | 包作用域（如 `@my-company`） | micro-react / h5-react: 见各生成器提示；其他: 多从根 `package.json` 检测 |
+| `cdnPrefix` | string | micro-react、h5-react | CDN 路径前缀（如 `portal`、`admin/v2`），写入 CICD 脚本中的 `CDN_PUBLIC_PATH` 等 | 空字符串 |
+| `author` | string | micro-react、h5-react、subapp-h5 | 作者信息 | 见各生成器提示 |
+| `initialSubAppName` | string | h5-react | 首个子应用目录名（`apps/` 下） | `app` |
+| `initialSubAppDevPort` | string | h5-react | 首个子应用独立 `pnpm dev` 端口 | `8000` |
+| `defaultSubappName` | string | subapp-react、subapp-h5 | 子应用默认名称 | subapp-react: `subapp`；subapp-h5: `app` |
+| `devPort` | string | subapp-react、subapp-h5 | 子应用开发端口 | subapp-react: `8010`；subapp-h5: `8000` |
 | `defaultUmdName` | string | subapp-umd | UMD 包默认名称 | `my-widget` |
 | `umdDevPort` | string | subapp-umd | UMD 包开发端口 | `9100` |
 
@@ -111,7 +133,9 @@ mico create micro-react
 - Husky + Commitlint
 - @common-web/sentry 错误监控与 SourceMap 上传
 
-## React 子应用生成器
+若需要 **Umi 4 H5 多应用 + 开发网关 / dev 预设**，请使用 **h5-react**（见 [docs/h5-react-generator.md](docs/h5-react-generator.md)）。
+
+## React 子应用生成器（subapp-react）
 
 该生成器会复制 `apps/homepage` 模板为新的子应用，并替换标识字符串。
 `config/` 目录下的多环境配置会完整保留。
@@ -121,6 +145,39 @@ cd <monorepo-root>
 mico create subapp-react
 ```
 
+详见 [docs/subapp-react-generator.md](docs/subapp-react-generator.md)。
+
+## H5 Monorepo 生成器（h5-react）
+
+用于创建 **Umi 4** 多子应用 H5 仓库：pnpm workspace、Turborepo、开发网关（`page.config.ts`）、dev 预设，并**联动** **`subapp-h5`** 生成首个 `apps/<名>/` 子应用。内部包含 11 个 workspace 包：**`domain`**（API/CDN/多语言基址）、**`js-bridge`**（H5 ↔ 原生通信）、**`request`**（基于 Umi 的统一请求；`isShowLoading` 默认 `true`）、**`common-intl`**（`init()` 经 `js-bridge.getUserInfo` 取语言）、**`components`**（沉浸式 H5 布局）、**`constant`** / **`deeplink`**、**`umi-config`**（**子应用 `config/*.ts` 全部委托到此包的工厂**，并内置 Sentry sourcemap 上传插件 **`src/plugins/apply-sentry-plugin.ts`**）、**`utils`**、**`eslint`**、**`typescript`**。模板内已接入 **`@common-web/sentry`**（子应用布局错误边界、生产构建 externals），根目录提供 **`build` / `build:development` / `build:testing` / `build:production`** 与 CICD 各环境对应；环境变量 **`.env.development` / `.env.testing` / `.env.production`** 集中维护在仓库根，`lint-staged` 通过 **`.lintstagedrc.js`** 集中维护。`pnpm-workspace.yaml` 的 **catalog** 钉扎 `umi`、`react*`、`tailwindcss`、`tailwindcss-safe-area`、`@umijs/plugins`、`cross-env`、`@common-web/sentry` 等版本（**`@sentry/webpack-plugin`** 仅装在 `packages/umi-config`，不在仓库根、不在子应用）。
+
+```bash
+mkdir my-h5 && cd my-h5
+mico create h5-react
+```
+
+若当前目录已存在 `pnpm-workspace.yaml`，需使用 **`mico create h5-react --force`**（会覆盖已有文件，请谨慎）。
+
+详见 [docs/h5-react-generator.md](docs/h5-react-generator.md)。
+
+## H5 子应用生成器（subapp-h5）
+
+在由 **h5-react** 初始化的 Monorepo **根目录**执行，在 `apps/<名>/` 下新增 Umi 子应用，并更新根目录 **`page.config.ts`**、**`dev.preset.json`**。子应用模板默认：
+
+- **`config/`** 全部委托到 **`<%= packageScope %>/umi-config`**（`createBaseConfig` / `createDevConfig` / `createProConfig` / `createDevelopmentConfig` / `createTestingConfig` / `createProductionConfig`）；不再在子应用里重抄 `plugins`、`request: {}`、`externals` 或 Sentry 上传逻辑——`createProductionConfig` 自动接入 sourcemap 上传（需 `SENTRY_AUTH_TOKEN`）
+- **`src/intl.ts` + `src/app.tsx`**：`init({ tag, indexedDBParams })` 取得 `{ fetchMultilingualData, i18n }`，首屏前 `fetchMultilingualData()`；`init()` 内部经 `<%= packageScope %>/js-bridge` 的 `getUserInfo()` 取语言
+- **`src/layouts/index.tsx`**：`<SentryErrorBoundary><Outlet/></SentryErrorBoundary>`
+- **`src/services/<域>.ts`** 就近定义请求/响应 interface 与服务函数；**`mock/<域>.ts`** 复用 `<%= packageScope %>/utils/mock` 的 `baseUrl` / `tryProxy`（zod 入参校验、mockjs 占位、可选 `?remote=` 透传到真实后端）
+- **Tailwind 3 + `tailwindcss-safe-area`**：`tailwind.css`（含 `font-size: 16px;` + `1vw` 适配）、`tailwind.config.js`（**ESM**，扫描 `./src/**` + `packages/components/src`，挂安全区插件）
+- **`config/routes.ts`** 仅含静态基础路由；动态菜单可与 `window.__MICO_MENUS__` 等配合
+
+```bash
+cd <h5-monorepo-root>
+mico create subapp-h5
+```
+
+详见 [docs/subapp-h5-generator.md](docs/subapp-h5-generator.md)。
+
 ## UMD 组件包生成器
 
 在 Monorepo 的 `packages/` 目录下创建 UMD 格式的组件包，使用 Webpack 构建。适用于通过 `<script>` 标签加载的场景（如主应用菜单挂载组件、第三方系统嵌入 Widget 等）。
@@ -149,6 +206,63 @@ mico create subapp-umd
 
 DevTools Sources 面板中可在 `webpack://<name>/src/` 下定位原始 TypeScript 源码进行断点调试。
 
+## Multica Desktop 自托管配置（`setup multica-desktop`）
+
+[Multica Desktop](https://multica.ai/docs/zh/desktop-app) 默认连接 Multica Cloud；要让它指向公司自托管实例，需要在用户目录写入 `~/.multica/desktop.json`（[配置规范见官方文档](https://github.com/multica-ai/multica/blob/main/apps/docs/content/docs/desktop-app.zh.mdx)）。`mico setup multica-desktop` 把这个一次性配置封装成了跨平台命令：
+
+```bash
+mico setup multica-desktop
+```
+
+写入的默认内容（指向米可自托管地址）：
+
+```json
+{
+  "schemaVersion": 1,
+  "apiUrl": "https://multica-api.micoplatform.com",
+  "appUrl": "https://multica.micoplatform.com"
+}
+```
+
+`wsUrl` 不写，由 Desktop 按官方规则从 `apiUrl` 自动推导为 `wss://multica-api.micoplatform.com/ws`。
+
+### 目标路径（跨平台）
+
+| 平台 | 实际路径 |
+|---|---|
+| macOS | `/Users/<Username>/.multica/desktop.json` |
+| Linux | `/home/<Username>/.multica/desktop.json` |
+| Windows | `C:\Users\<Username>\.multica\desktop.json` |
+
+路径统一通过 `os.homedir()` 解析，三平台无需任何额外参数。
+
+### 默认行为
+
+- 如果文件**不存在**：创建 `.multica` 目录，写入默认配置。
+- 如果文件**已存在**：先备份为 `desktop.json.bak.<时间戳>`，再覆盖。
+- 完成后需要**重启 Multica Desktop** 让配置生效。
+
+### 可选参数
+
+| 参数 | 说明 |
+|---|---|
+| `--dry-run` | 仅预览输出内容，不写盘 |
+| `--no-backup` | 已存在时直接覆盖，不生成 `.bak` |
+| `--force` | 同 `--no-backup`，沿用全局 `--force` 语义 |
+| `--api-url=<url>` | 覆盖默认 `apiUrl` |
+| `--app-url=<url>` | 覆盖默认 `appUrl` |
+| `--ws-url=<url>` | 显式设置 `wsUrl`（不传则由 Desktop 自动推导） |
+
+示例：
+
+```bash
+mico setup multica-desktop --dry-run
+mico setup multica-desktop --no-backup
+mico setup multica-desktop \
+  --api-url=https://api.your-domain \
+  --app-url=https://your-domain
+```
+
 ## 开发指南
 
 ### 环境准备
@@ -174,6 +288,12 @@ mico create micro-react
 # 测试 subapp-react 生成器（需在已有 monorepo 中执行）
 mico create subapp-react
 
+# 测试 h5-react（空目录）
+mico create h5-react
+
+# 测试 subapp-h5（需在含 apps/ 的 H5 monorepo 根目录执行）
+mico create subapp-h5
+
 # 测试 subapp-umd 生成器（需在已有 monorepo 中执行）
 mico create subapp-umd
 ```
@@ -201,10 +321,13 @@ pnpm test:watch
 | 目录/文件 | 说明 |
 |----------|------|
 | `tests/unit/utils.test.js` | `lib/utils.js` 的单元测试 |
+| `tests/unit/setup-multica-desktop.test.js` | `lib/setup-multica-desktop.js` 单元测试（隔离 home 目录，覆盖首次写入 / 备份 / `--no-backup` / `--dry-run`） |
 | `tests/integration/micro-react.test.js` | micro-react 生成器集成测试 |
 | `tests/integration/subapp-react.test.js` | subapp-react 生成器集成测试 |
+| `tests/integration/h5-react.test.js` | h5-react 生成器集成测试 |
+| `tests/integration/subapp-h5.test.js` | subapp-h5 生成器集成测试 |
 | `tests/integration/subapp-umd.test.js` | subapp-umd 生成器集成测试 |
-| `tests/integration/mico-cli.test.js` | `mico` 入口子进程测试（help / version / list / create / doctor） |
+| `tests/integration/mico-cli.test.js` | `mico` 入口子进程测试（help / version / list / create / doctor / setup） |
 | `tests/helpers/setup.js` | 测试共享工具（路径常量、monorepo fixture 工厂） |
 | `tests/helpers/mico-subprocess.js` | 子进程运行 `bin/mico.js` 工具函数 |
 
@@ -245,11 +368,15 @@ pnpm run sync:subapp-react-template -- <source-path>
 
 ```
 mico-cli/
-├── bin/mico.js              # CLI 入口（命令解析、生成器调度）
-├── lib/utils.js             # 共享工具函数（字符串转换、文件处理、npm 版本查询、配置加载）
+├── bin/mico.js              # CLI 入口（命令解析、生成器调度、setup 子命令分发）
+├── lib/
+│   ├── utils.js             # 共享工具函数（字符串转换、文件处理、npm 版本查询、配置加载）
+│   └── setup-multica-desktop.js  # `mico setup multica-desktop` 核心实现
 ├── generators/
-│   ├── micro-react/         # Monorepo 项目生成器
+│   ├── micro-react/         # Monorepo 项目生成器（qiankun）
 │   ├── subapp-react/        # React 子应用生成器
+│   ├── h5-react/            # H5 Monorepo（Umi + 网关 / 预设）
+│   ├── subapp-h5/           # H5 Umi 子应用
 │   └── subapp-umd/          # UMD 组件包生成器
 ├── scripts/                 # 辅助脚本
 ├── tests/                   # 测试文件

package/bin/mico.js

@@ -25,6 +25,7 @@ Usage: mico <command> [options]
 Commands:
   create <generator>    Run a generator (e.g., mico create subapp-react)
   list                  List all available generators
+  setup <target>        Run a setup task (e.g., mico setup multica-desktop)
   update                Update mico-cli to the latest version
   doctor                Check environment dependencies
 
@@ -36,12 +37,25 @@ Options:
   --force               Overwrite all existing files without confirmation
   --no-update-check     Skip update check
 
+Setup targets:
+  multica-desktop       Write ~/.multica/desktop.json for self-hosted Multica
+                        Options:
+                          --api-url=<url>    override apiUrl
+                          --app-url=<url>    override appUrl
+                          --ws-url=<url>     override wsUrl (auto-derived if omitted)
+                          --no-backup        skip creating .bak before overwrite
+                          --dry-run          preview without writing
+
 Examples:
   mico create subapp-react
   mico create micro-react --verbose
   mico create micro-react --dry-run
   mico create micro-react --force
+  mico create subapp-h5
+  mico create h5-react
   mico list
+  mico setup multica-desktop
+  mico setup multica-desktop --dry-run
   mico update
   mico doctor
 
@@ -338,6 +352,50 @@ function performUpdate(latestVersion) {
   }
 }
 
+/**
+ * 解析形如 `--key=value` 的带值标志（仅识别白名单 key）。
+ * @param {string[]} args
+ * @param {string[]} keys
+ * @returns {Record<string, string>}
+ */
+function parseValueFlags(args, keys) {
+  const result = {};
+  for (const raw of args) {
+    if (!raw.startsWith('--')) continue;
+    const eq = raw.indexOf('=');
+    if (eq === -1) continue;
+    const key = raw.slice(2, eq);
+    if (!keys.includes(key)) continue;
+    result[key] = raw.slice(eq + 1);
+  }
+  return result;
+}
+
+/**
+ * 运行 `mico setup multica-desktop`，把仓库根的 lib 模块作为单一实现源。
+ * @param {string[]} extraArgs setup 后剩余的参数
+ * @param {{ dryRun?: boolean, force?: boolean }} globalFlags 来自 main 的全局标志
+ */
+async function runSetupMulticaDesktop(extraArgs, globalFlags = {}) {
+  const { runSetupMulticaDesktop: run } = require('../lib/setup-multica-desktop');
+  const noBackup = extraArgs.includes('--no-backup');
+  const values = parseValueFlags(extraArgs, ['api-url', 'app-url', 'ws-url']);
+
+  try {
+    run({
+      apiUrl: values['api-url'],
+      appUrl: values['app-url'],
+      wsUrl: values['ws-url'],
+      dryRun: Boolean(globalFlags.dryRun),
+      force: Boolean(globalFlags.force),
+      noBackup,
+    });
+  } catch (err) {
+    console.error(`❌ Error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
 /**
  * 运行 Yeoman 生成器
  * @param {string} generator - 生成器名称
@@ -460,6 +518,24 @@ async function main() {
     process.exit(success ? 0 : 1);
   }
 
+  // 处理 setup 命令
+  if (command === 'setup') {
+    const target = rest[0];
+    if (!target) {
+      console.error('❌ Error: missing setup target.');
+      console.error('   Available targets: multica-desktop');
+      printHelp();
+      process.exit(1);
+    }
+    if (target === 'multica-desktop') {
+      await runSetupMulticaDesktop(rest.slice(1), { dryRun: isDryRun, force: isForce });
+      process.exit(0);
+    }
+    console.error(`❌ Unknown setup target: ${target}`);
+    console.error('   Available targets: multica-desktop');
+    process.exit(1);
+  }
+
   // 处理 update 命令
   if (command === 'update') {
     const updateInfo = await checkForUpdate();

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

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