@icebreakers/monorepo-templates 0.1.15 → 1.0.0

package/templates/vitepress/index.md

@@ -4,124 +4,189 @@ layout: doc
 
 # icebreaker's monorepo 模板
 
-整套模板围绕 **pnpm + Turborepo + TypeScript** 打造，帮助团队快速落地一个可维护、可编排、可持续迭代的 `monorepo` 工程。这里我们把使用方式拆成几个核心模块，方便你按需查阅。
+这套模板的目标很直接：用一套尽量短、尽量稳定的命令，把 `pnpm + Turborepo + TypeScript + 工程化校验 + changesets` 串成一个真正能落地的 monorepo 起步架子。
 
-## 核心能力
+如果你只想知道最简单怎么用，先记住下面这 5 步。
 
-- **工作区管理**：`pnpm` workspace + Turborepo 任务编排，内置缓存和过滤能力。
-- **全链路 TypeScript**：所有模板（应用、类库、CLI）均使用 TS，并自带基础测试脚手架（`vitest`）。
-- **质量与规范**：集成 `eslint`、`stylelint`、`husky`、`commitlint`、`lint-staged`，开箱即用。
-- **自动化发布**：`changesets` + GitHub Actions + Dockerfile 模板，实现语义化发版和部署。
-- **命令行助手**：`@icebreakers/monorepo` CLI 提供创建、同步、升级、镜像等常用命令，可通过 `monorepo.config.ts` 自定义行为。
+## 先这样用
 
-## 快速上手
+```bash
+pnpm install
+pnpm setup
+pnpm doctor
+pnpm new
+pnpm check
+```
+
+- `pnpm install`：安装整个 workspace 的依赖。
+- `pnpm setup`：同步当前仓库推荐的基础元信息和工具链配置。
+- `pnpm doctor`：检查你是不是站在正确的仓库根目录、Node 版本对不对、根脚本齐不齐、配置文件有没有冲突、提交链路是否完整。
+- `pnpm new`：创建一个新的 package 或 app。
+- `pnpm check`：执行推荐的本地校验，适合提交前快速确认。
+
+> 模板生成后的仓库优先推荐使用这些根脚本；底层实际对应的还是 `repo` CLI。`repoctl` 和 `@icebreakers/monorepo` 继续兼容，但不再是主文档入口。
+
+## 最小心智模型
+
+这个模板故意只保留三层命令入口：
+
+| 层级     | 推荐写法                                                 | 适合什么场景                             |
+| -------- | -------------------------------------------------------- | ---------------------------------------- |
+| 根脚本   | `pnpm setup` / `pnpm new` / `pnpm doctor` / `pnpm check` | 新人日常使用，最短、最不容易记错         |
+| 主 CLI   | `pnpm exec repo ...`                                     | 需要明确调用 CLI，或仓库还没同步根脚本时 |
+| 分组命令 | `repo ws up` / `repo tg init` / `repo skills sync`       | 已经熟悉命令体系，想走更细粒度入口       |
+
+简单理解：
+
+- 想上手，用 `pnpm ...`
+- 想看清楚实际做的是哪个命令，用 `repo ...`
+- 想做高级操作，再看分组命令
+
+## 最常用的命令
+
+### 1. 仓库初始化与新建
+
+```bash
+pnpm setup
+pnpm new my-package
+pnpm new my-app --template client
+```
+
+- `setup` 是老仓库接入模板标准资产的第一步。
+- `new` 支持交互式选择，也支持 `--template` 直接指定模板。
+- 如果在 `repoctl.config.ts` 中设置了 `commands.create.defaultTemplate`，那么 `repo new foo` 会直接创建，不再多问一次模板。
+
+### 2. 诊断、校验、同步
+
+```bash
+pnpm doctor
+pnpm check
+pnpm exec repo upgrade
+```
 
-1. **拉取模板**：[GitHub](https://github.com/sonofmagic/monorepo-template) 右上角 `Use this template`，或克隆源码。
-2. **安装依赖**：在 `pnpm-workspace.yaml` 所在目录执行 `pnpm install`（需要 Node.js ≥ 20，推荐 `npm i -g pnpm`）。
-3. **可选清理**：直接运行 `npx -y @icebreakers/monorepo@latest clean` 远程执行清理，移除演示包后再执行 `pnpm install`（避免依赖本地构建 `monorepo`）；如已安装依赖，也可使用 `pnpm script:clean`。
-4. **初始化元数据**：`pnpm script:init` 会批量更新 `package.json`、`README.md` 等公共信息。
+- `doctor` 看“仓库能不能顺利开始使用”
+- `check` 看“当前改动能不能顺利提交”
+- `upgrade` 看“模板最新的标准资产要不要同步进来”
 
-## 仓库结构速览
+这三个命令不要混着理解：
 
-| 目录                  | 描述                             |
-| --------------------- | -------------------------------- |
-| `templates/cli`       | TypeScript 编写的 CLI 模板       |
-| `templates/client`    | Vue 3 + Vite 客户端示例          |
-| `templates/server`    | 基于 Hono 的服务端模板           |
-| `templates/vitepress` | VitePress 文档站（即本网站源码） |
-| `templates/tsup`      | 使用 `tsup` 打包的库模板         |
-| `templates/unbuild`   | 使用 `unbuild` 打包的库模板      |
-| `templates/vue-lib`   | Vue 组件库模板                   |
-| `packages/monorepo`   | CLI 及配置同步工具，支持独立升级 |
+| 命令      | 解决的问题                                           |
+| --------- | ---------------------------------------------------- |
+| `doctor`  | 当前目录是不是一个正确、完整、可用的 monorepo 根目录 |
+| `check`   | 当前提交前校验是否能过                               |
+| `upgrade` | 我要不要把最新模板里的脚本、配置、工作流同步过来     |
 
-## 常用脚本
+## 你现在拿到的基础架子
 
-| 命令                 | 说明                                                |
-| -------------------- | --------------------------------------------------- |
-| `pnpm script:clean`  | 清理演示仓库，保留最小模板                          |
-| `pnpm script:init`   | 同步初始化 `package.json`、`README.md` 等基础信息   |
-| `pnpm script:sync`   | 使用 `cnpm` 同步所有包到 npmmirror（需预装 `cnpm`） |
-| `pnpm script:mirror` | 为 VS Code 终端写入国内镜像环境变量                 |
+| 目录                  | 作用                                           |
+| --------------------- | ---------------------------------------------- |
+| `templates/cli`       | TypeScript CLI 模板                            |
+| `templates/client`    | Vue 3 + Vite 客户端模板                        |
+| `templates/server`    | Hono 服务端模板                                |
+| `templates/tsdown`    | 使用 `tsdown` 的 TypeScript 类库模板           |
+| `templates/vue-lib`   | Vue 组件库模板                                 |
+| `templates/vitepress` | 文档站模板                                     |
+| `packages/monorepo`   | 真正的 CLI 核心实现、升级逻辑、tooling wrapper |
+| `packages/repoctl`    | 面向使用者的默认包名与入口封装                 |
 
-更多脚本可在根目录 `package.json` 中查看，命令介绍详见 [工具区](./tools/turborepo.md)。
+## 推荐上手路径
 
-## CLI 命令概览
+### 场景 1：你刚用模板创建了一个新仓库
 
 ```bash
-npx monorepo new           # 创建子包/应用
-npx -y @icebreakers/monorepo@latest clean  # 远程清理已勾选的子项目，避免依赖本地构建
-npx monorepo sync          # 同步所有包到 npmmirror
-npx monorepo mirror        # 写入 VS Code 镜像配置
-npx monorepo up            # 从最新模板同步配置文件
-npx monorepo ai create     # 生成 Agentic 任务提示词模板（支持输出到文件，可用别名 ai new）
+pnpm install
+pnpm doctor
+pnpm new
+pnpm check
+pnpm build
 ```
 
-示例：`npx monorepo ai create -o agentic-task.md -f`，可直接生成 Markdown 模板并覆盖旧文件。默认会写入 `agentic/prompts/<timestamp>/prompt.md`，同时生成一个按时间排序的目录，并会提示你确认或修改目录名称，方便后续补充图片等素材；也可以用别名 `npx monorepo ai new`.
+这时通常不需要先跑 `upgrade`，因为模板本身已经是新生成的。
+
+### 场景 2：你把 `repoctl` 接进一个已有仓库
+
+```bash
+pnpm install
+pnpm exec repo setup
+pnpm exec repo doctor
+pnpm exec repo upgrade
+pnpm exec repo doctor
+```
+
+这里先 `doctor` 一次，是为了看现在缺什么；`upgrade` 之后再跑一次，可以确认问题是不是已经被修平。
+
+## 配置文件约定
+
+推荐只使用一个配置文件：
+
+```txt
+repoctl.config.ts
+```
 
-多文件场景：
+兼容旧文件名：
 
-- `npx monorepo ai create --name checkout` 自动落盘到 `agentic/prompts/checkout.md`（默认目录可改）。
-- `npx monorepo ai create --tasks agentic/tasks.json -f` 读取 JSON 数组批量生成，适合多人协作收口任务。
+```txt
+monorepo.config.ts
+```
 
-所有命令都支持在 `monorepo.config.ts` 中覆写默认行为，例如新增模板、修改同步命令、跳过 README 初始化等。配置示例见下文和 [配置中心说明](./monorepo/manage.md#使用-monorepo-configts-定制命令行为)。
+但两者不能同时存在。现在 CLI 会明确拒绝加载冲突配置，`repo doctor` 也会直接把这个问题标红。
 
-## 自定义配置：`monorepo.config.ts`
+最小示例：
 
 ```ts
-import { defineMonorepoConfig } from '@icebreakers/monorepo'
+import { defineMonorepoConfig } from 'repoctl'
 
 export default defineMonorepoConfig({
   commands: {
-    ai: {
-      baseDir: 'agentic/custom-prompts',
-      format: 'json',
-      force: true,
-      tasksFile: 'agentic/tasks.json',
-    },
     create: {
-      defaultTemplate: 'cli',
-      renameJson: true,
-    },
-    clean: {
-      autoConfirm: true,
-      ignorePackages: ['docs'],
+      defaultTemplate: 'tsdown',
     },
     upgrade: {
       skipOverwrite: true,
-      targets: ['.github', 'monorepo.config.ts'],
     },
   },
 })
 ```
 
-更多可配置项详见 [管理指南](./monorepo/manage.md)。
+## 默认质量门禁
 
-## 依赖与版本升级
+模板默认鼓励你走这条链路：
 
-```bash
-pnpm up -rLi
-```
+1. `pnpm build`
+2. `pnpm lint`
+3. `pnpm typecheck`
+4. `pnpm tsd`
+5. `pnpm test`
+
+如果仓库保留了默认的 `.husky` 与 `lint-staged.config.js`：
 
-- `-r`：递归遍历所有 workspace
-- `-L`：升级到最新版本
-- `-i`：交互式选择（推荐查看差异后再确认）
+- `pre-commit` 会聚焦 staged 文件
+- 样式文件会跑 `stylelint`
+- JS / TS / Vue 会跑 `eslint`
+- TS / Vue 相关文件会按 workspace 跑 `typecheck`
+- `pre-push` 会补跑整仓的 `lint`、`typecheck`，以及受影响包的 `build` / `test` / `tsd`
 
-## 自动化发布
+## 下一步看哪里
 
-模板默认集成 [`changesets`](https://github.com/changesets/changesets) 与推荐的 GitHub Actions 工作流：
+- 想理解为什么这套模板这样拆：[为什么往 monorepo 方向演进](./monorepo/index.md)
+- 第一次接手仓库先看：[新手使用指南](./getting-started.md)
+- 想看真实的日常管理方式：[如何管理 monorepo](./monorepo/manage.md)
+- 想要最完整的命令速查：[命令速查](./monorepo/commands.md)
+- 命令报错了怎么处理：[排障指南](./monorepo/troubleshooting.md)
+- 要发包和生成 changelog：[发包与变更日志](./monorepo/publish.md)
 
-1. 安装 [changeset-bot](https://github.com/apps/changeset-bot)。
-2. 在仓库设置中开启 `Actions` 的 `Read and write permissions` 并勾选允许创建 PR。
-3. 在 `Repository secrets` 中配置 `NPM_TOKEN`（若需要 Codecov 也可配置 `CODECOV_TOKEN`）。
-4. 运行 `pnpm changeset`、`pnpm changeset version`、`pnpm changeset publish` 完成发布；或交由 CI 自动执行。
+## 兼容命令说明
 
-具体操作指南参见 [发包流程](./monorepo/publish.md)。
+下面这些命令依然可用：
 
-## 更多资源
+```bash
+pnpm exec repoctl doctor
+pnpm exec repoctl new
+pnpm exec monorepo doctor
+pnpm exec monorepo ws up
+```
 
-- [为什么选择 monorepo？](./monorepo/index.md)
-- [pnpm workspaces 与 Turborepo 组合的优势](./monorepo/manage.md)
-- [工具链介绍](./tools/turborepo.md)
-- [常见思考与 FAQ](./thinking.md)
+只是文档不再优先推荐它们。现在主入口统一收口到：
 
-> 欢迎结合自己的业务场景对模板做进一步裁剪与扩展，建议在自定义后保留 `monorepo.config.ts` 以便集中管理命令默认值。
+- `repo`
+- 以及生成仓库里的 `pnpm setup / pnpm new / pnpm doctor / pnpm check`

package/templates/vitepress/monorepo/commands.md

@@ -0,0 +1,281 @@
+# 命令速查
+
+这一页只保留高频、实用、容易记错的命令。
+
+## 最推荐的入口
+
+在模板生成后的仓库里，优先使用根脚本：
+
+```bash
+pnpm setup
+pnpm doctor
+pnpm new
+pnpm check
+```
+
+对应关系如下：
+
+| 根脚本        | 实际等价命令  |
+| ------------- | ------------- |
+| `pnpm setup`  | `repo setup`  |
+| `pnpm doctor` | `repo doctor` |
+| `pnpm new`    | `repo new`    |
+| `pnpm check`  | `repo check`  |
+
+## 上手四连
+
+### 新仓库
+
+```bash
+pnpm install
+pnpm doctor
+pnpm new
+pnpm check
+```
+
+### 存量仓库接入
+
+```bash
+pnpm install
+pnpm exec repo setup
+pnpm exec repo doctor
+pnpm exec repo upgrade
+pnpm exec repo doctor
+```
+
+## 顶层命令
+
+### `repo setup`
+
+```bash
+repo setup
+repo setup --preset minimal
+repo setup --preset standard --force
+```
+
+用途：
+
+- 初始化当前 workspace 的推荐默认值
+- 同步 README / package.json / changeset / tooling 相关基础资产
+
+### `repo doctor`
+
+```bash
+repo doctor
+repo doctor --strict
+repo doctor --json
+repo doctor --json --out reports/doctor.json
+repo doctor --markdown --out reports/doctor.md
+repo doctor --markdown --redact --out reports/doctor.md
+```
+
+用途：
+
+- 诊断当前目录是不是可直接开始使用的 monorepo 根目录
+- 检查 Node 版本、workspace 文件、CLI 依赖、根脚本、配置冲突、提交链路
+- `--strict` 会把 warning 也视为失败，适合 CI 门禁或团队模板验收
+- `--json` 只输出结构化报告，适合 CI、脚本和编辑器集成
+- `--markdown` 输出适合贴到 issue / PR 的摘要报告
+- `--redact` 会脱敏 workspace / cwd / home 绝对路径，适合发给外部协作者
+- `--out <file>` 把文本、JSON 或 Markdown 报告写入文件，仍会按 blocking issue 返回非零状态
+
+### `repo new`
+
+```bash
+repo new
+repo new sdk --template tsdown
+repo new docs --template vitepress
+repo new docs --template vitepress --dry-run
+repo new docs --template vitepress --json
+repo new docs --template vitepress --json --out plans/docs.json
+```
+
+用途：
+
+- 交互式或直接创建新的 package / app
+- `--dry-run` 只预览模板、目标目录、package 名称和输出文件，不写入磁盘
+- `--json` 以结构化数据输出创建预览，隐含 `--dry-run`
+- `--out <file>` 把当前创建预览写入文件，也隐含 `--dry-run`
+- 显式传入的 `--template` 会先校验，拼错时会失败并提示相近模板 key
+
+### `repo templates`
+
+```bash
+repo templates
+repo templates tsdown
+repo templates --category library
+repo templates --check
+repo templates --check --json
+repo templates --json
+repo templates --markdown
+repo templates tsdown --markdown
+repo templates --markdown --out docs/templates.md
+```
+
+用途：
+
+- 查看内置模板 key、分类、默认生成目录和用途
+- 传入模板 key 时查看单个模板详情
+- `--check` 检查内置模板元数据、目录、package.json 和临时文件
+- 在写自动化脚本时用 `--json` 获取结构化输出
+- 用 `--markdown` 生成可直接放进文档的模板表格或详情页
+- 用 `--out <file>` 把当前 JSON、Markdown 或文本输出写入文件
+
+### `repo check`
+
+```bash
+repo check
+repo check --staged
+repo check --full
+repo check --edit-file .git/COMMIT_EDITMSG
+repo check --dry-run
+repo check --json --out reports/check-plan.json
+repo check --markdown --out reports/check-plan.md
+repo check --markdown --redact --out reports/check-plan.md
+```
+
+用途：
+
+- 运行推荐的本地校验入口
+- `--staged` 偏 pre-commit
+- `--full` 偏 pre-push
+- `--edit-file` 用于 commit message 校验
+- `--dry-run` 只预览将要执行的校验
+- `--json` / `--out <file>` 输出校验计划，适合 CI、脚本和编辑器集成
+- `--markdown` 输出适合贴到 PR / issue 的校验计划摘要
+- `--redact` 会脱敏 cwd / home 绝对路径，适合发给外部协作者
+
+### `repo upgrade`
+
+```bash
+repo upgrade
+repo upgrade --core
+repo upgrade -i
+repo upgrade -s
+```
+
+用途：
+
+- 同步仓库标准资产与脚本
+
+常见参数：
+
+- `--core`：只同步核心配置，跳过 GitHub 相关资产
+- `-i`：交互式选择
+- `-s`：跳过新增，只覆盖已存在文件
+
+### 兼容命令
+
+```bash
+repo sync
+repo clean --yes
+repo mirror
+```
+
+- `sync`：兼容入口，本质上仍是升级同步
+- `clean`：清理选中的 workspace 包
+- `mirror`：设置 VS Code 相关镜像环境变量
+
+## 分组命令
+
+### workspace / ws
+
+```bash
+repo workspace upgrade
+repo ws up
+repo workspace init
+repo ws ls
+repo ws ls --json --out reports/workspaces.json
+repo ws ls --markdown --redact --out reports/workspaces.md
+repo workspace clean --yes
+```
+
+### tooling / tg
+
+```bash
+repo tooling init eslint vitest
+repo tg init --all --force
+```
+
+### package / pkg
+
+```bash
+repo package create
+repo pkg new
+```
+
+### verify / v
+
+```bash
+repo verify pre-commit
+repo verify pre-push
+repo verify commit-msg .git/COMMIT_EDITMSG
+repo verify staged-typecheck packages/app/src/main.ts
+```
+
+### env / e
+
+```bash
+repo env info
+repo e i --json --out reports/env.json
+repo e i --markdown --redact --out reports/env.md
+repo env snapshot --json --out reports/snapshot.json
+repo env snapshot --markdown --redact --out reports/snapshot.md
+repo env snapshot --markdown --redact --strict --out reports/snapshot.md
+repo env paths --json --out reports/paths.json
+repo env paths --markdown --redact --out reports/paths.md
+repo env support --json --out reports/support.json
+repo env support --json --redact --out reports/support.json
+repo env support --markdown --redact --out reports/support.md
+repo env support --markdown --redact --strict --out reports/support.md
+repo env mirror
+```
+
+### config / cfg
+
+```bash
+repo config inspect
+repo cfg i --json --out reports/config.json
+repo cfg i --markdown --redact --out reports/config.md
+```
+
+### skills / sk
+
+```bash
+repo skills sync --codex
+repo sk s --claude
+```
+
+### ai / ai p
+
+```bash
+repo ai prompt create --name checkout
+repo ai p new
+repo ai prompt create --tasks agentic/tasks.json -f
+```
+
+## `repo`、`repoctl`、`monorepo` 的关系
+
+三者共用同一套 CLI 实现：
+
+```bash
+repo doctor
+repoctl doctor
+monorepo doctor
+```
+
+都能用，但推荐顺序是：
+
+1. `pnpm setup / doctor / new / check`
+2. `repo ...`
+3. `repoctl ...` 或 `monorepo ...` 仅作为兼容入口
+
+## 什么时候用哪个命令
+
+| 你的问题                   | 先用什么       |
+| -------------------------- | -------------- |
+| 仓库是不是搭对了           | `repo doctor`  |
+| 我现在这次改动能不能过校验 | `repo check`   |
+| 我要补齐模板最新脚本和配置 | `repo upgrade` |
+| 我要新增一个子包           | `repo new`     |
+| 我要直接操作更细的模块     | 分组命令       |