@icebreakers/monorepo-templates 0.1.16 → 1.0.1

package/templates/vitepress/monorepo/index.md

@@ -1,46 +1,115 @@
-# 为什么选择 Monorepo？
+# 为什么往 monorepo 方向演进
 
-随着项目复杂度提升，Node.js 团队越来越倾向于把多套服务、组件库、CLI 工具放在同一个仓库里。Monorepo 的核心价值在于 **集中管理依赖与流程**，从而让重构、协作、发布都更高效。
+选择 monorepo，不是为了“更先进”，而是为了把多包协作里最常见的重复劳动砍掉。
 
-## Monorepo 的主要收益
+当你的仓库里同时存在应用、类库、CLI、文档站，或者多个团队要共享同一套类型、配置、脚手架时，monorepo 的收益会很快超过它的管理成本。
 
-| 维度     | 收益                                                               |
-| -------- | ------------------------------------------------------------------ |
-| 依赖管理 | `pnpm` 等工具会共享缓存、避免重复安装；严格依赖隔离杜绝“幽灵依赖”  |
-| 构建效率 | 借助 Turborepo 的缓存与依赖图，仅构建真正改动的包，CI 时间显著降低 |
-| 原子提交 | 一个提交即可跨多个模块同步改动，便于回滚与审计                     |
-| 协作体验 | 同一仓库统一配置、脚本与规范，减少跨项目跳转和环境差异             |
-| 可复用性 | 公共库、UI 组件、工具函数在 workspace 内即可本地引用并共享         |
+## 这套模板解决的真实问题
 
-## 与 Polyrepo 的对比
+### 1. 依赖和脚本不再分散
 
-| Polyrepo 常见痛点                | Monorepo 的解决方式                                |
-| -------------------------------- | -------------------------------------------------- |
-| 每个仓库单独装依赖、重复维护脚本 | Workspace 共享依赖与脚本，一次配置多处使用         |
-| 同步多个仓库中的接口或配置       | 原子提交 + Turborepo 构建，修改一次即可全仓库生效  |
-| CI/CD 配置分散、发布流程冗长     | 基于 changesets 和统一仓库配置快速搭建自动化流水线 |
-| 大规模重构成本高                 | 搜索范围集中，易于批量修改、验证与回滚             |
+在 polyrepo 里，最常见的问题不是代码本身，而是：
 
-## 常见落地场景
+- 每个仓库都要单独装依赖
+- 每个仓库都维护一套 lint / typecheck / test 脚本
+- 同样的工具链升级要重复做很多次
+- 团队成员很难判断哪个仓库的规范才是“当前标准”
 
-- **多端同仓**：Web、Server、CLI 共存，代码共享严格受控。
-- **组件库/工具链**：公共 API 与内部应用一起维护，避免版本漂移。
-- **微服务集成**：多个服务共享协议、类型定义，发布与部署流程统一。
-- **巨石拆分**：将原有大型项目拆成多个 package，逐步抽象并复用。
+在 monorepo 里，这些东西可以收敛到一个根目录。
 
-## 迁移建议
+### 2. 跨包改动可以原子提交
 
-1. **先集中依赖**：把最常见的公共依赖和脚本统一到根目录，利用 `pnpm workspace` 管理版本。
-2. **逐步迁移模块**：按照业务领域或团队边界迁移子模块，保留原 CI 作为兜底。
-3. **引入构建缓存**：配置 Turborepo，使用 `turbo run <task> --filter=<scope>` 控制任务范围。
-4. **接入 changesets**：在迁移过程中就开始记录版本与变更，养成可发布的节奏。
-5. **通过 monorepo.config.ts 定制命令**：按团队习惯调整 `create` 模板、`clean` 行为、`upgrade` 目标等，提高可维护性。
+如果一个接口变更同时影响：
 
-## 进一步阅读
+- `packages/types`
+- `packages/sdk`
+- `apps/web`
+- `apps/server`
 
-- [仓库管理实践](./manage.md) —— 如何将 pnpm + Turborepo + monorepo.config 协同使用。
-- [发包与变更日志](./publish.md) —— 使用 changesets 管理版本、自动化发布。
-- [工具专题](../tools/turborepo.md) —— 常用工具的配置与技巧。
-- [常见思考](../thinking.md) —— 关于模块拆分、包结构的经验分享。
+那么在 monorepo 里，一次提交就能把它们一起改完、一起验证、一起回滚。对重构和版本审计都更友好。
 
-> Monorepo 不是银弹，但在需要大量复用、自动化、跨团队协作的场景下，它能显著提升工程效率。关键是配合合适的工具与规范，让拆分后的每个模块都有清晰的职责与边界。
+### 3. 构建与测试更容易增量化
+
+`pnpm` 负责 workspace 依赖管理，`turborepo` 负责任务编排和缓存，结果就是：
+
+- 没改动的包不需要重复构建
+- CI 可以按依赖图只跑受影响任务
+- 大仓库也能保持比较稳定的反馈速度
+
+## 这套模板的立场
+
+这不是一个“什么都能配”的框架，而是一套偏实战、偏收敛的默认值：
+
+| 维度     | 默认选择                                       |
+| -------- | ---------------------------------------------- |
+| 包管理   | `pnpm workspace`                               |
+| 任务编排 | `turborepo`                                    |
+| 语言     | TypeScript 优先                                |
+| 校验链路 | ESLint + Stylelint + typecheck + Vitest        |
+| 提交规范 | Husky + lint-staged + commitlint               |
+| 发包     | changesets                                     |
+| 命令入口 | `repo` 为主，`repoctl` / `monorepo` 为兼容入口 |
+
+这些选择的目的只有一个：减少“每个项目重新想一遍”的成本。
+
+## 什么时候适合用 monorepo
+
+下面这些情况，适合直接上：
+
+- 你要同时维护多个 npm 包
+- 你有前后端、CLI、文档站共用一套类型或工具
+- 你希望升级脚本、工程化配置时一次同步全仓
+- 你有持续重构、跨包联动改动的需求
+
+下面这些情况，不一定值得上：
+
+- 只有一个很小的应用，没有共享代码需求
+- 团队还没有接受统一规范的准备
+- 构建链路本身还不稳定，先统一仓库只会放大问题
+
+## 模板提供的补位能力
+
+单纯有 monorepo 还不够，真正难的是“如何让它易用”。这个模板多补了三层东西：
+
+### 1. 更短的日常命令
+
+```bash
+pnpm setup
+pnpm doctor
+pnpm new
+pnpm check
+```
+
+不用先背完整 CLI，先把日常路径跑顺。
+
+### 2. `repo doctor` 这种面向新人的诊断命令
+
+它会直接回答这些问题：
+
+- 你是不是站在仓库根目录
+- `pnpm-workspace.yaml` 在不在
+- Node 版本对不对
+- 有没有安装 CLI 依赖
+- 根脚本齐不齐
+- `repoctl.config.ts` 和 `monorepo.config.ts` 有没有冲突
+- Husky / lint-staged 链路是不是半残状态
+
+### 3. `repo upgrade` 这种面向存量仓库的同步命令
+
+当模板默认值变了，你不需要手抄配置，只要选择性同步标准资产。
+
+## 实际收益通常体现在这里
+
+| 场景         | Polyrepo 常见成本  | Monorepo 常见收益      |
+| ------------ | ------------------ | ---------------------- |
+| 工具链升级   | 多仓重复改配置     | 一次升级，多包受益     |
+| 共享类型变更 | 多仓分别发版联调   | 一次改动，一次验证     |
+| CI 反馈      | 每仓重复跑全量     | 利用缓存和依赖图做增量 |
+| 新人接手     | 先理解多个仓库差异 | 先理解一套统一约定     |
+
+## 继续阅读
+
+- [如何管理 monorepo](./manage.md)
+- [命令速查](./commands.md)
+- [排障指南](./troubleshooting.md)
+- [发包与变更日志](./publish.md)

package/templates/vitepress/monorepo/manage.md

@@ -1,129 +1,230 @@
 # 如何管理 monorepo
 
-本节结合模板实践，总结一套围绕 **pnpm + Turborepo + monorepo.config** 的管理方法：从依赖安装、任务调度到命令覆写，帮助团队高效协作。
+这一页只讲一件事：拿到这套模板后，日常到底怎么用，才是最省心的。
 
-## 基础设施速览
+## 先记住默认工作流
 
-| 能力           | 工具                 | 要点                                                                        |
-| -------------- | -------------------- | --------------------------------------------------------------------------- |
-| Workspace 管理 | `pnpm`               | 内容寻址、硬链接，安装速度快、占用小；严格依赖隔离杜绝“幽灵依赖”            |
-| 任务编排       | `turborepo`          | 基于依赖图调度任务，支持并行与缓存，`turbo run build --filter=...` 精准执行 |
-| 命令自定义     | `monorepo.config.ts` | 使用 `c12` 加载，可对 create/clean/sync/upgrade/init/mirror 覆写默认行为    |
+```bash
+pnpm install
+pnpm doctor
+pnpm new
+pnpm check
+pnpm build
+```
 
-## 日常操作流程
+大多数场景里，这已经够了。
 
-### 1. 管理依赖
+如果你在接入一个旧仓库，再多加一步：
 
 ```bash
-# 安装/更新
-pnpm install
-pnpm up -rLi
+pnpm setup
+```
+
+## 命令分层
+
+这套模板故意把入口做得很少。
 
-# 查看依赖图
-pnpm ls --depth 2
+### 第一层：根脚本
+
+这是最推荐的入口：
+
+```bash
+pnpm setup
+pnpm new
+pnpm doctor
+pnpm check
 ```
 
-- `pnpm install` 自动按 workspace 复用依赖。
-- `pnpm up -rLi` 交互式升级所有包，`-L` 为最新版本，`-i` 逐项确认。
+适合：
+
+- 新人
+- 日常开发
+- 文档教程
+- 团队内部统一约定
+
+### 第二层：主 CLI
 
-### 2. 调度构建与测试
+当你要明确告诉别人“这是 CLI 行为，不只是 package.json 脚本”时，用：
 
 ```bash
-# 全量构建 / 测试
-pnpm build
-pnpm test
+pnpm exec repo setup
+pnpm exec repo new
+pnpm exec repo doctor
+pnpm exec repo check
+pnpm exec repo upgrade
+```
+
+### 第三层：分组命令
 
-# 只构建受影响的包
-pnpm build --filter={templates/client}
+更细的高级操作保留在分组里：
 
-# 观察执行计划
-pnpm exec turbo run build --dry=json | jq '.'
+```bash
+repo workspace upgrade
+repo ws up
+repo tooling init eslint vitest
+repo tg init --all
+repo skills sync --codex
+repo ai prompt create --name checkout
 ```
 
-Turborepo 会缓存任务输出：
+## 日常任务对照表
+
+| 你想做什么             | 推荐命令                     | 说明                                              |
+| ---------------------- | ---------------------------- | ------------------------------------------------- |
+| 初始化一个刚接入的仓库 | `pnpm setup`                 | 同步推荐的仓库元信息和基础工程化配置              |
+| 看仓库当前状态是否健康 | `pnpm doctor`                | 先排根目录、Node、脚本、配置冲突、提交链路        |
+| 创建一个新的包或应用   | `pnpm new`                   | 支持交互式选择，也支持 `--template`               |
+| 提交前做本地校验       | `pnpm check`                 | 默认对齐推荐 pre-commit / pre-push 逻辑           |
+| 同步模板最新标准资产   | `pnpm exec repo upgrade`     | 适合模板升级、老仓库补齐                          |
+| 清理演示仓库或非必要包 | `pnpm exec repo clean --yes` | 零安装也可以用 `pnpm dlx repo@latest clean --yes` |
+
+## `doctor`、`check`、`upgrade` 的边界
+
+这是最容易混淆的三个命令。
+
+### `doctor`
+
+偏“仓库体检”。
+
+它不关心你当前改了什么代码，而是关心：
+
+- 这个仓库是不是完整
+- 当前目录是不是根目录
+- 当前机器的 Node 版本能不能跑
+- 命令入口和配置文件是不是一致
+
+### `check`
 
-| 构建场景       | 全量（首次） | 增量（未改动） |
-| -------------- | ------------ | -------------- |
-| 传统脚本       | 120s         | 120s           |
-| Turbo 本地缓存 | 120s         | **≈5s**        |
-| Turbo 远程缓存 | 120s         | **≈2s**        |
+偏“提交前校验”。
 
-> 建议在 CI 中启用远程缓存（Vercel/Turbo Cloud 或自建存储）进一步缩短时间。
+它更像一个人工触发的推荐检查入口，适合：
 
-### 3. 自定义命令行为
+- 提交前自查
+- 怀疑 lint / typecheck / hooks 有问题时快速复现
+- 用 `repo check --dry-run`、`repo check --json --out reports/check-plan.json` 或 `repo check --markdown --redact --out reports/check-plan.md` 先确认校验路由
 
-使用 `defineMonorepoConfig` 即可集中覆写：
+### `upgrade`
+
+偏“模板资产同步”。
+
+它解决的是：
+
+- 模板最新默认脚本要不要补进来
+- 工作流、配置文件、GitHub 资产要不要同步
+- 存量仓库要不要追上现在的标准
+
+## 配置推荐
+
+推荐只保留一个文件：
 
 ```ts
-import { defineMonorepoConfig } from '@icebreakers/monorepo'
+// repoctl.config.ts
+import { defineMonorepoConfig } from 'repoctl'
 
 export default defineMonorepoConfig({
   commands: {
     create: {
-      templatesDir: './custom-templates',
-      templateMap: {
-        'cloud-function': {
-          source: 'functions/cloud',
-          target: 'apps/functions/cloud',
-        },
-      },
-      choices: [
-        { value: 'cli', name: 'CLI 模板' },
-        { value: 'cloud-function', name: '云函数模板' },
-      ],
-    },
-    sync: {
-      command: 'cnpm sync {name}',
-      concurrency: 4,
+      defaultTemplate: 'tsdown',
     },
     clean: {
       autoConfirm: true,
-      pinnedVersion: '^2.0.0',
+    },
+    upgrade: {
+      skipOverwrite: true,
     },
   },
 })
 ```
 
-常用配置项：
+说明：
 
-| 命令      | 可覆盖字段                                                                         | 说明                                                                                        |
-| --------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `create`  | `templatesDir` / `templateMap` / `choices` / `defaultTemplate`                     | 扩展模板来源、修改提示内容                                                                  |
-| `clean`   | `autoConfirm` / `ignorePackages` / `includePrivate` / `pinnedVersion`              | 控制交互、过滤包、锁定依赖版本                                                              |
-| `sync`    | `concurrency` / `command` / `packages`                                             | 定义同步命令与并发度                                                                        |
-| `upgrade` | `targets` / `mergeTargets` / `scripts` / `skipChangesetMarkdown` / `skipOverwrite` | 改写配置同步策略                                                                            |
-| `init`    | `skipReadme` / `skipPkgJson` / `skipChangeset`                                     | 按需跳过初始化步骤                                                                          |
-| `mirror`  | `env`                                                                              | 注入镜像环境变量                                                                            |
-| `ai`      | `output` / `format` / `force` / `baseDir` / `tasksFile`                            | 预设 Agentic 模板输出目录、格式与批量任务，默认写入 `agentic/prompts/<timestamp>/prompt.md` |
+- 优先使用 `repoctl.config.ts`
+- `monorepo.config.ts` 继续兼容
+- 两者不能同时存在
 
-更多细节可参考 CLI 命令文档或源码中的 `commands/*`。
+如果同时存在，现在 CLI 会直接报错，`repo doctor` 也会把它判成阻塞项。
 
-### 4. 依赖升级 / 配置同步
+## `new` 的推荐用法
+
+### 交互式
 
 ```bash
-npx monorepo up           # 使用本地 CLI
-npx @icebreakers/monorepo@latest up  # 直接使用远端 CLI
+pnpm new
+```
 
-# 常用参数
-# -c, --core  仅同步核心配置，排除 GitHub 相关文件
-# -i          以交互方式筛选文件
-# -s          跳过新增，仅覆盖已存在文件
+适合第一次使用模板、想先看看有哪些模板可选。
+
+### 直接指定模板
+
+```bash
+pnpm exec repo new docs --template vitepress
+pnpm exec repo new sdk --template tsdown
+```
+
+适合你已经明确知道要创建什么。
+
+### 固化团队默认模板
+
+```ts
+import { defineMonorepoConfig } from 'repoctl'
+
+export default defineMonorepoConfig({
+  commands: {
+    create: {
+      defaultTemplate: 'tsdown',
+    },
+  },
+})
 ```
 
-升级 CLI 后再执行 `up`，可以同步获得模板最新的工作流、脚手架与配置。
+设置后：
+
+```bash
+pnpm exec repo new utils
+```
+
+会直接按默认模板生成，不再额外询问模板类型。
+
+## 默认提交链路
+
+如果你保留模板默认生成的 `.husky` 与 `lint-staged.config.js`，通常会得到这条链路：
+
+| 阶段         | 默认行为                                                                |
+| ------------ | ----------------------------------------------------------------------- |
+| `pre-commit` | 聚焦 staged 文件运行 `stylelint`、`eslint`、workspace `typecheck`       |
+| `pre-push`   | 运行整仓 `lint`、`typecheck`，再补跑受影响包的 `build` / `test` / `tsd` |
+
+这也是为什么：
+
+- `pnpm doctor` 会检查 Husky 与 lint-staged 是否同时存在
+- `pnpm check` 会成为最自然的人工入口
+
+## 依赖与构建建议
+
+```bash
+pnpm install
+pnpm up -rLi
+pnpm build
+pnpm test
+```
+
+- `pnpm install`：统一安装 workspace 依赖
+- `pnpm up -rLi`：交互式升级依赖
+- `pnpm build` / `pnpm test`：让 Turborepo 帮你做任务编排与缓存
+
+## 工具层 API 什么时候用
+
+如果你只是要使用默认 CLI，不需要直接碰 `@icebreakers/monorepo/tooling`。
 
-## 常见问题与建议
+只有下面两种情况建议直接使用：
 
-- **依赖冲突**：使用 `pnpm why <pkg>` 定位冲突来源，优先升级上游依赖或将共享依赖提升到顶层。
-- **缓存命中率低**：确认是否使用了 `turbo run <task> --filter` 以及 `dependsOn` 配置是否准确，必要时开启远程缓存。
-- **CI 时间长**：结合 `pnpm fetch` 预拉取依赖，配合 `turbo` 缓存，通常能把 pipeline 压缩到原来的 1/3。
-- **命令行为差异**：将所有自定义行为写入 `monorepo.config.ts`，避免脚本散落多处难以维护。
+- 你要在仓库里手写 tooling wrapper 配置
+- 你在维护这套 CLI / 模板本身
 
-## 进一步阅读
+其余大多数团队，停留在 `repoctl.config.ts` 这一层就够了。
 
-- [为什么越来越多团队迁移到 monorepo？](./index.md)
-- [changesets 发包指南](./publish.md)
-- [工具篇：pnpm、Turborepo、Changesets 等](../tools/turborepo.md)
-- [常见思考与实践](../thinking.md)
+## 继续阅读
 
-> 小提示：在迁移现有项目时，可以先把最常变的模块放进 monorepo，再逐步收拢其它仓库，配合 `monorepo.config.ts` 就能实现平滑衔接。
+- [命令速查](./commands.md)
+- [排障指南](./troubleshooting.md)
+- [发包与变更日志](./publish.md)