@icebreakers/monorepo-templates 1.0.2 → 1.0.3

package/templates/vitepress/index.md

@@ -1,192 +1,57 @@
 ---
-layout: doc
+layout: home
+
+hero:
+  name: repoctl
+  text: 让 pnpm monorepo 的日常操作更短、更稳
+  tagline: 用一套 CLI 管理初始化、诊断、创建模板、提交前校验和模板资产同步。
+  image:
+    src: /logo.jpg
+    alt: repoctl logo
+  actions:
+    - theme: brand
+      text: 快速开始
+      link: /repoctl/getting-started
+    - theme: alt
+      text: 命令速查
+      link: /repoctl/commands
+
+features:
+  - title: 从已有仓库开始
+    details: 安装 repoctl 后运行 setup 和 doctor，先把 workspace、根脚本、配置冲突和提交链路检查清楚。
+  - title: 用模板创建包和应用
+    details: repo new 支持交互式创建、指定模板、dry-run、JSON 输出和创建计划落盘。
+  - title: 把质量门禁变成日常命令
+    details: repo check 统一预览和执行 lint、typecheck、build、test、tsd 等推荐校验。
 ---
 
-# icebreaker's monorepo 模板
-
-这套模板的目标很直接：用一套尽量短、尽量稳定的命令，把 `pnpm + Turborepo + TypeScript + 工程化校验 + changesets` 串成一个真正能落地的 monorepo 起步架子。
-
-如果你只想知道最简单怎么用，先记住下面这 5 步。
-
-## 先这样用
+## 最短路径
 
 ```bash
-pnpm install
-pnpm setup
-pnpm doctor
-pnpm new
-pnpm check
+pnpm add -D repoctl
+pnpm exec repo setup
+pnpm exec repo doctor
+pnpm exec repo new
+pnpm exec repo 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
-```
-
-- `doctor` 看“仓库能不能顺利开始使用”
-- `check` 看“当前改动能不能顺利提交”
-- `upgrade` 看“模板最新的标准资产要不要同步进来”
-
-这三个命令不要混着理解：
-
-| 命令      | 解决的问题                                           |
-| --------- | ---------------------------------------------------- |
-| `doctor`  | 当前目录是不是一个正确、完整、可用的 monorepo 根目录 |
-| `check`   | 当前提交前校验是否能过                               |
-| `upgrade` | 我要不要把最新模板里的脚本、配置、工作流同步过来     |
-
-## 你现在拿到的基础架子
-
-| 目录                  | 作用                                           |
-| --------------------- | ---------------------------------------------- |
-| `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`    | 面向使用者的默认包名与入口封装                 |
-
-## 推荐上手路径
-
-### 场景 1：你刚用模板创建了一个新仓库
-
-```bash
-pnpm install
 pnpm doctor
 pnpm new
 pnpm check
-pnpm build
-```
-
-这时通常不需要先跑 `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
-```
-
-兼容旧文件名：
-
-```txt
-monorepo.config.ts
-```
-
-但两者不能同时存在。现在 CLI 会明确拒绝加载冲突配置，`repo doctor` 也会直接把这个问题标红。
-
-最小示例：
-
-```ts
-import { defineMonorepoConfig } from 'repoctl'
-
-export default defineMonorepoConfig({
-  commands: {
-    create: {
-      defaultTemplate: 'tsdown',
-    },
-    upgrade: {
-      skipOverwrite: true,
-    },
-  },
-})
-```
-
-## 默认质量门禁
-
-模板默认鼓励你走这条链路：
-
-1. `pnpm build`
-2. `pnpm lint`
-3. `pnpm typecheck`
-4. `pnpm tsd`
-5. `pnpm test`
-
-如果仓库保留了默认的 `.husky` 与 `lint-staged.config.js`：
-
-- `pre-commit` 会聚焦 staged 文件
-- 样式文件会跑 `stylelint`
-- JS / TS / Vue 会跑 `eslint`
-- TS / Vue 相关文件会按 workspace 跑 `typecheck`
-- `pre-push` 会补跑整仓的 `lint`、`typecheck`，以及受影响包的 `build` / `test` / `tsd`
-
-## 下一步看哪里
-
-- 想理解为什么这套模板这样拆：[为什么往 monorepo 方向演进](./monorepo/index.md)
-- 第一次接手仓库先看：[新手使用指南](./getting-started.md)
-- 想看真实的日常管理方式：[如何管理 monorepo](./monorepo/manage.md)
-- 想要最完整的命令速查：[命令速查](./monorepo/commands.md)
-- 命令报错了怎么处理：[排障指南](./monorepo/troubleshooting.md)
-- 要发包和生成 changelog：[发包与变更日志](./monorepo/publish.md)
-
-## 兼容命令说明
-
-下面这些命令依然可用：
-
-```bash
-pnpm exec repoctl doctor
-pnpm exec repoctl new
-pnpm exec monorepo doctor
-pnpm exec monorepo ws up
 ```
 
-只是文档不再优先推荐它们。现在主入口统一收口到：
+## 你可以继续阅读
 
-- `repo`
-- 以及生成仓库里的 `pnpm setup / pnpm new / pnpm doctor / pnpm check`
+- [repoctl 概览](./repoctl/index.md)
+- [快速开始](./repoctl/getting-started.md)
+- [接入已有仓库](./repoctl/adopt-existing.md)
+- [按场景选命令](./repoctl/scenarios.md)
+- [命令速查](./repoctl/commands.md)
+- [配置文件](./repoctl/config.md)
+- [模板与创建](./repoctl/templates.md)
+- [工作流与 CI](./repoctl/workflows.md)
+- [知识库：为什么往 monorepo 方向演进](./monorepo/index.md)

package/templates/vitepress/monorepo/commands.md

@@ -1,291 +1,21 @@
 # 命令速查
 
-这一页只保留高频、实用、容易记错的命令。
+repoctl 现在是这套文档的主线。完整命令说明请阅读：
 
-## 最推荐的入口
+- [repoctl 命令速查](../repoctl/commands.md)
+- [repoctl 模板与创建](../repoctl/templates.md)
+- [repoctl 排障与报告](../repoctl/troubleshooting.md)
 
-在模板生成后的仓库里，优先使用根脚本：
+## monorepo 知识点：为什么要统一命令入口
 
-```bash
-pnpm setup
-pnpm doctor
-pnpm new
-pnpm check
-```
+monorepo 的难点通常不是“能不能跑某个工具”，而是团队成员是否能稳定地用同一套入口完成日常动作。
 
-对应关系如下：
+repoctl 把命令分成三层：
 
-| 根脚本        | 实际等价命令  |
-| ------------- | ------------- |
-| `pnpm setup`  | `repo setup`  |
-| `pnpm doctor` | `repo doctor` |
-| `pnpm new`    | `repo new`    |
-| `pnpm check`  | `repo check`  |
+| 层级     | 示例                              | 适合场景             |
+| -------- | --------------------------------- | -------------------- |
+| 根脚本   | `pnpm doctor` / `pnpm new`        | 日常开发和团队教程   |
+| 主 CLI   | `pnpm exec repo doctor`           | CI、脚本、排障和文档 |
+| 分组命令 | `repo ws ls` / `repo env support` | 维护者和自动化       |
 
-## 上手四连
-
-### 新仓库
-
-```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 --yes
-repo setup --preset minimal
-repo setup --preset standard --force
-repo setup --overwrite
-```
-
-用途：
-
-- 初始化当前 workspace 的推荐默认值
-- 默认不覆盖已有 README、package.json、pnpm-workspace.yaml 和 tooling 配置
-- 会追加缺失的 `apps/*`、`packages/*`、`examples/*` workspace patterns
-- `--yes` 用于 CI / 非 TTY 环境，使用安全默认行为
-- 需要重写受管理文件时显式传 `--force` 或 `--overwrite`
-
-### `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 --yes
-repo upgrade --overwrite
-repo upgrade --no-overwrite
-repo upgrade --core
-repo upgrade -i
-repo upgrade -s
-```
-
-用途：
-
-- 同步仓库标准资产与脚本
-
-常见参数：
-
-- `--core`：只同步核心配置，跳过 GitHub 相关资产
-- `-i`：交互式选择
-- `--yes` / `--overwrite`：非交互覆盖 drifted 标准资产，并迁移旧 tooling loader import
-- `--no-overwrite` / `-s`：保留已有 drifted 文件
-- 非 TTY 环境不会弹出选择框，也不会抛 prompt 退出错误
-
-### 兼容命令
-
-```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`     |
-| 我要直接操作更细的模块     | 分组命令       |
+保留这个旧页面，是为了让已有链接继续可用，同时把读者导向新的 repoctl 命令文档。

package/templates/vitepress/monorepo/manage.md

@@ -1,6 +1,8 @@
 # 如何管理 monorepo
 
-这一页只讲一件事：拿到这套模板后，日常到底怎么用，才是最省心的。
+这一页是 repoctl 文档后面的知识库页面。它不再重新解释所有命令参数，而是解释：为什么这些命令能让 monorepo 日常管理变简单。
+
+如果你只想查命令，直接看 [repoctl 工作流与 CI](../repoctl/workflows.md) 或 [repoctl 命令速查](../repoctl/commands.md)。
 
 ## 先记住默认工作流
 
@@ -20,6 +22,16 @@ pnpm build
 pnpm setup
 ```
 
+这个工作流背后的顺序是：
+
+| 阶段 | 目标                                             |
+| ---- | ------------------------------------------------ |
+| 安装 | 让 workspace 依赖和本地包链接完整                |
+| 诊断 | 先确认仓库结构、Node、脚本、配置和提交链路可用   |
+| 创建 | 用模板生成新包，减少手写 package metadata 和配置 |
+| 校验 | 在提交前复现默认 hook 和 workspace typecheck     |
+| 构建 | 最后再跑更重的全仓任务                           |
+
 ## 命令分层
 
 这套模板故意把入口做得很少。
@@ -225,6 +237,7 @@ pnpm test
 
 ## 继续阅读
 
-- [命令速查](./commands.md)
-- [排障指南](./troubleshooting.md)
+- [repoctl 工作流与 CI](../repoctl/workflows.md)
+- [repoctl 命令速查](../repoctl/commands.md)
+- [repoctl 排障与报告](../repoctl/troubleshooting.md)
 - [发包与变更日志](./publish.md)

package/templates/vitepress/monorepo/publish.md

@@ -7,6 +7,31 @@
 - changelog 可以稳定产出
 - 很容易接到 CI 里
 
+repoctl 在发布流程里的位置很明确：它不替代 `changesets` 发布版本，而是在发布前帮你确认仓库状态、模板资产和校验计划。
+
+## repoctl 在发布前做什么
+
+```bash
+pnpm exec repo doctor --strict
+pnpm exec repo check --full
+pnpm exec repo env support --markdown --redact --out reports/support.md
+```
+
+| 命令                   | 发布前价值                                               |
+| ---------------------- | -------------------------------------------------------- |
+| `repo doctor --strict` | 确认仓库结构、Node、脚本、配置和提交链路没有漂移         |
+| `repo check --full`    | 跑根脚本里的 lint/typecheck/test/build 计划              |
+| `repo env support`     | 保存环境、配置、doctor 和 check plan，方便发布失败后回溯 |
+
+发布本身仍交给 `changesets`：
+
+```bash
+pnpm changeset
+pnpm exec repo release stable
+```
+
+正式发布只走 `main`；`alpha`、`beta`、`rc`、`next` 只做 Changesets 的 prerelease，并发布对应 tag 包。
+
 ## 一条务实的发布流程
 
 先把顺序记住：
@@ -90,11 +115,10 @@ changeset 文件本身就是最便宜的“发布预告”。代码评审时顺
 ### 手动流程
 
 ```bash
-pnpm changeset version
-pnpm publish-packages
+pnpm exec repo release stable
 ```
 
-`changeset version` 会做这些事：
+`repo release stable` 会先执行构建、lint 和测试，再调用 `changeset version` 与 `changeset publish`。其中 `changeset version` 会做这些事：
 
 - 更新受影响包的版本号
 - 调整内部依赖版本
@@ -113,6 +137,10 @@ on:
   push:
     branches:
       - main
+      - alpha
+      - beta
+      - rc
+      - next
   workflow_dispatch:
 
 permissions:
@@ -126,6 +154,7 @@ env:
 
 jobs:
   release:
+    if: github.ref_name == 'main'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -139,9 +168,25 @@ jobs:
       - name: Create Release Pull Request or Publish to npm
         uses: changesets/action@v1
         with:
-          publish: pnpm publish-packages
+          publish: pnpm exec repo release stable
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  prerelease:
+    if: github.ref_name != 'main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install
+      - run: git config user.name "github-actions[bot]"
+      - run: git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - name: Publish Prerelease
+        run: pnpm exec repo release pre publish
 ```
 
 ## 关于 npm 鉴权
@@ -209,5 +254,6 @@ permissions:
 ## 继续阅读
 
 - [如何管理 monorepo](./manage.md)
-- [命令速查](./commands.md)
-- [排障指南](./troubleshooting.md)
+- [repoctl 工作流与 CI](../repoctl/workflows.md)
+- [repoctl 排障与报告](../repoctl/troubleshooting.md)
+- [命令别名](../repoctl/aliases.md)