@icebreakers/monorepo-templates 1.0.15 → 1.2.0

package/templates/vitepress/{en → zh}/repoctl/aliases.md

@@ -1,10 +1,10 @@
-# Command Aliases
+# 命令别名
 
-repoctl keeps several aliases for terminal convenience. Team docs should still prefer full commands because they are easier for new users to read.
+repoctl 保留了一组短别名，方便熟悉后在终端里少打字。团队文档仍建议优先写完整命令，减少新人理解成本。
 
-## Binary Aliases
+## 包入口别名
 
-The `repoctl` package exposes these bins:
+`repoctl` 包提供多个 bin：
 
 ```bash
 repo
@@ -14,9 +14,9 @@ rc
 mo
 ```
 
-The docs recommend `repo`.
+文档统一推荐 `repo`。
 
-These bins all enter the same command implementation:
+这些 bin 都进入同一套命令实现：
 
 ```bash
 repoctl doctor
@@ -25,16 +25,16 @@ rc doctor
 mo doctor
 ```
 
-## Top-Level Aliases
+## 顶层命令别名
 
-| Recommended      | Alias       | Purpose                       |
-| ---------------- | ----------- | ----------------------------- |
-| `repo init`      | `repo init` | Initialize workspace defaults |
-| `repo templates` | `repo tpl`  | Inspect or check templates    |
+| 推荐写法         | 短写        | 说明             |
+| ---------------- | ----------- | ---------------- |
+| `repo init`      | `repo init` | 初始化仓库默认值 |
+| `repo templates` | `repo tpl`  | 查看或检查模板   |
 
-## Group Aliases
+## 分组命令别名
 
-| Full Command                   | Alias           |
+| 完整命令                       | 短写            |
 | ------------------------------ | --------------- |
 | `repo workspace`               | `repo ws`       |
 | `repo workspace upgrade`       | `repo ws up`    |
@@ -62,9 +62,9 @@ mo doctor
 | `repo ai prompt`               | `repo ai p`     |
 | `repo ai prompt create`        | `repo ai p new` |
 
-## Recommendation
+## 推荐使用原则
 
-- Use full commands in onboarding docs.
-- Use `repo:*` root scripts in project README files, for example `pnpm run repo:doctor`.
-- Use short aliases in maintainer scripts only when the surrounding docs explain them.
-- Prefer full commands in CI logs.
+- 新手教程写完整命令，例如 `pnpm exec repo doctor`。
+- 团队 README 写根脚本，例如 `pnpm run repo:doctor`。
+- 维护者脚本可以写短别名，但要在注释或文档里说明用途。
+- CI 里优先写完整命令，方便日志搜索。

package/templates/vitepress/zh/repoctl/checks.md

@@ -0,0 +1,86 @@
+---
+description: 说明 repoctl check 和 verify 的校验模式、pre-commit、staged typecheck、pre-push 与 commit-msg 链路。
+---
+
+# repoctl 校验链路
+
+`repo check` 是给人使用的统一入口，`repo verify` 是给 hook、CI 和脚本复用的底层入口。
+
+## 1. 模式速查
+
+| 命令                                         | 模式         | 实际动作                                                       |
+| -------------------------------------------- | ------------ | -------------------------------------------------------------- |
+| `repo check`                                 | `default`    | 执行 `repo verify pre-commit`                                  |
+| `repo check --staged`                        | `staged`     | 执行 pre-commit，并按 staged TypeScript/Vue 文件路由 typecheck |
+| `repo check --full`                          | `full`       | 按根脚本执行 `lint`、`typecheck`、`test`、`build` 中存在的任务 |
+| `repo check --edit-file .git/COMMIT_EDITMSG` | `commit-msg` | 执行 commit message 校验                                       |
+
+预览模式不会真正执行校验：
+
+```bash
+repo check --dry-run
+repo check --full --json --out reports/check-plan.json
+repo check --markdown --redact --out reports/check-plan.md
+```
+
+## 2. pre-commit
+
+`repo verify pre-commit` 默认执行 lint-staged。适合在提交前只处理 staged 文件，避免每次提交都跑整仓校验。
+
+推荐的 lint-staged 行为包括：
+
+| 文件类型                   | 推荐处理                                 |
+| -------------------------- | ---------------------------------------- |
+| JS、TS、Vue                | ESLint 自动修复                          |
+| CSS、SCSS、Less、Vue style | Stylelint 自动修复                       |
+| TS、TSX、MTS、CTS、Vue     | 路由到最近 workspace 的 `typecheck` 脚本 |
+
+## 3. staged typecheck
+
+`repo verify staged-typecheck <files...>` 会根据文件路径向上查找最近的 workspace，并执行该 workspace 的 `typecheck`。
+
+```bash
+repo verify staged-typecheck packages/ui/src/button.ts templates/client/src/App.vue
+```
+
+它解决的是 monorepo 里常见的问题：一个提交只改了某个包，不应该让所有 Vue 和 TypeScript workspace 都重复跑类型检查。
+
+## 4. pre-push
+
+`repo verify pre-push` 面向推送前的完整保护。默认策略是：
+
+| 阶段         | 行为                                             |
+| ------------ | ------------------------------------------------ |
+| 根任务       | 强制执行整仓 `lint` 与 `typecheck`               |
+| 变更范围任务 | 按 workspace 改动范围补跑 `build`、`test`、`tsd` |
+| 失败处理     | 任一任务失败时停止并返回失败状态                 |
+
+如果 CI 想要更明确地复现整仓校验，可以使用：
+
+```bash
+repo check --full
+```
+
+## 5. commit message
+
+`repo verify commit-msg <file>` 用于 Git 的 `commit-msg` hook。未配置自定义命令时，它会执行：
+
+```bash
+pnpm exec commitlint --edit <file>
+```
+
+如果你只是手动验证当前提交信息，可以运行：
+
+```bash
+repo check --edit-file .git/COMMIT_EDITMSG
+```
+
+## 6. 选择建议
+
+| 场景               | 推荐命令                                          |
+| ------------------ | ------------------------------------------------- |
+| 本地提交前快速复现 | `repo check`                                      |
+| lint-staged 调试   | `repo check --staged --dry-run`                   |
+| 推送前完整检查     | `repo check --full`                               |
+| CI 门禁            | `repo doctor --strict` 后接 `repo check --full`   |
+| 只生成计划         | `repo check --json --out reports/check-plan.json` |

package/templates/vitepress/zh/repoctl/commands.md

@@ -0,0 +1,168 @@
+# 命令速查
+
+这一页只保留 repoctl 高频、实用、容易记错的命令。
+
+## 最推荐入口
+
+```bash
+pnpm exec repo init
+pnpm exec repo doctor
+pnpm exec repo templates
+pnpm exec repo new
+pnpm exec repo check
+```
+
+模板生成仓库里的推荐根脚本：
+
+```bash
+pnpm run repo:init
+pnpm run repo:doctor
+pnpm run repo:new
+pnpm run repo:check
+```
+
+## `repo init`
+
+```bash
+repo init
+repo init --yes
+repo init --preset minimal
+repo init --preset standard --force
+repo init --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 --redact --out reports/doctor.md
+```
+
+用途：
+
+- 诊断当前目录是不是可直接开始使用的 monorepo 根目录。
+- 检查 Node 版本、workspace 文件、CLI 依赖、根脚本、遗留配置和提交链路。
+- `--strict` 会把 warning 也视为失败，适合 CI 门禁。
+- `--json` 和 `--markdown` 适合自动化、PR、issue 和外部协作。
+- `--redact` 会脱敏 workspace、cwd、home 等绝对路径。
+
+## `repo templates`
+
+```bash
+repo templates
+repo templates tsdown
+repo templates --category library
+repo templates --check
+repo templates --json
+repo templates --markdown --out docs/templates.md
+```
+
+用途：
+
+- 查看内置模板 key、分类、默认生成目录和用途。
+- 检查模板元数据和源目录健康状态。
+- 给脚本读取 JSON，或生成 Markdown 文档片段。
+
+## `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 --out plans/docs.json
+```
+
+用途：
+
+- 交互式或直接创建新的 package、app、service、docs 或 CLI。
+- `--dry-run` 只预览模板、目标目录、package name 和输出文件。
+- `--json` 输出结构化创建计划，隐含 `--dry-run`。
+- 显式传入的 `--template` 会先校验，拼错时会失败并提示相近 key。
+
+## `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 --redact --out reports/check-plan.md
+```
+
+用途：
+
+- 运行推荐的本地校验入口。
+- `--staged` 偏 pre-commit。
+- `--full` 偏 pre-push。
+- `--edit-file` 用于 commit message 校验。
+- `--dry-run` 只预览将要执行的校验。
+
+## `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` 交互式选择。
+- `--no-overwrite` / `-s` 保留已有 drifted 文件。
+- `--yes` / `--overwrite` 非交互覆盖 drifted 标准资产。
+
+## 分组命令
+
+```bash
+repo ws ls
+repo ws ls --json --out reports/workspaces.json
+repo ws up
+repo tg init --all
+repo verify pre-commit
+repo verify pre-push
+repo env support --markdown --redact --out reports/support.md
+repo config inspect
+repo skills sync --codex
+```
+
+分组命令适合维护者和自动化脚本。日常开发优先使用顶层命令。
+
+## 输出参数速查
+
+| 参数           | 适用命令                                     | 说明                                  |
+| -------------- | -------------------------------------------- | ------------------------------------- |
+| `--json`       | `doctor`、`check`、`templates`、`new`、`env` | 输出机器可读数据                      |
+| `--markdown`   | `doctor`、`check`、`templates`、`env`        | 输出适合 PR 和 issue 的 Markdown      |
+| `--out <file>` | 多数报告和计划命令                           | 写入文件，便于 CI artifact 或脚本读取 |
+| `--redact`     | `doctor`、`check`、`env`                     | 分享报告前脱敏本机路径                |
+| `--strict`     | `doctor`、`env snapshot`、`env support`      | warning 也会导致失败                  |
+| `--dry-run`    | `check`、`new`                               | 只看计划，不执行校验或写入文件        |
+
+## 继续阅读
+
+- [执行模型](./execution-model.md)
+- [校验链路](./checks.md)
+- [doctor 诊断](./doctor.md)
+- [工作流与 CI](./workflows.md)
+- [报告与自动化输出](./reports.md)
+- [命令别名](./aliases.md)

package/templates/vitepress/zh/repoctl/config.md

@@ -0,0 +1,90 @@
+# 配置文件
+
+repoctl 推荐在仓库根目录使用一个配置文件：
+
+```txt
+repoctl.config.ts
+```
+
+`monorepo.config.ts` 已不再作为运行时配置入口。迁移旧仓库时请改名为 `repoctl.config.ts`。
+
+repoctl 支持 `ts`、`mts`、`cts`、`js`、`mjs`、`cjs` 等配置文件后缀。新项目优先使用 `repoctl.config.ts`，这样能保留类型提示和更清晰的迁移路径。
+
+## 最小配置
+
+```ts
+import { defineMonorepoConfig } from 'repoctl'
+
+export default defineMonorepoConfig({
+  commands: {
+    create: {
+      defaultTemplate: 'tsdown',
+    },
+  },
+})
+```
+
+设置 `commands.create.defaultTemplate` 后：
+
+```bash
+repo new utils
+```
+
+会直接按默认模板创建，不再询问模板类型。
+
+## 常用配置
+
+```ts
+import { defineMonorepoConfig } from 'repoctl'
+
+export default defineMonorepoConfig({
+  commands: {
+    init: {
+      preset: 'standard',
+    },
+    create: {
+      defaultTemplate: 'tsdown',
+    },
+    clean: {
+      autoConfirm: true,
+    },
+    upgrade: {
+      skipOverwrite: true,
+    },
+  },
+})
+```
+
+| 配置                              | 作用                                    |
+| --------------------------------- | --------------------------------------- |
+| `commands.init.preset`            | 控制初始化默认预设                      |
+| `commands.create.defaultTemplate` | 控制 `repo new <name>` 的默认模板       |
+| `commands.clean.autoConfirm`      | 清理命令是否默认确认                    |
+| `commands.upgrade.skipOverwrite`  | 同步标准资产时是否保留已有 drifted 文件 |
+
+## 查看当前配置
+
+```bash
+repo config inspect
+repo cfg i --json --out reports/config.json
+repo cfg i --markdown --redact --out reports/config.md
+```
+
+`--redact` 适合把报告发到 issue、PR 或外部协作渠道。
+
+## 配置的定位
+
+配置文件只负责团队默认值，不建议把一次性命令参数都写进去。
+
+推荐做法：
+
+- 团队长期一致的选择写进 `repoctl.config.ts`。
+- 临时行为用命令参数表达，例如 `--dry-run`、`--json`、`--out`。
+- 自动化脚本优先使用显式参数，减少隐藏状态。
+
+## 继续阅读
+
+- [执行模型](./execution-model.md)
+- [模板与创建](./templates.md)
+- [模板资产治理](./template-assets.md)
+- [报告与自动化输出](./reports.md)

package/templates/vitepress/zh/repoctl/doctor.md

@@ -0,0 +1,86 @@
+---
+description: 说明 repoctl doctor 的检查项、状态含义、strict 模式和修复建议。
+---
+
+# repoctl doctor 诊断
+
+`repo doctor` 用来判断当前目录是不是一个可维护、可开发、可接入 repoctl 工作流的 pnpm monorepo 根目录。
+
+## 1. 状态含义
+
+| 状态   | 含义           | 对退出码的影响                |
+| ------ | -------------- | ----------------------------- |
+| `pass` | 检查通过       | 不影响                        |
+| `warn` | 存在建议修复项 | 默认不失败，`--strict` 下失败 |
+| `fail` | 阻塞项         | 命令返回失败状态              |
+
+CI 中推荐使用：
+
+```bash
+repo doctor --strict
+```
+
+这样 warning 不会长期堆积成隐性风险。
+
+## 2. 核心检查项
+
+| 检查项                       | 通过标准                                                         | 常见修复                     |
+| ---------------------------- | ---------------------------------------------------------------- | ---------------------------- |
+| `package-json`               | 当前 workspace 根目录存在 `package.json`                         | 回到仓库根目录或先初始化项目 |
+| `workspace-manifest`         | 存在 `pnpm-workspace.yaml`                                       | `repo init --yes`            |
+| `node-version`               | 当前 Node 满足 `engines.node`                                    | 切换 Node 版本或补充 engines |
+| `tool-package`               | 根依赖包含 `repoctl`                                             | `pnpm add -D repoctl`        |
+| `root-scripts`               | 存在 `repo:init`、`repo:new`、`repo:check`、`repo:doctor` 根脚本 | `repo init --yes`            |
+| `config-file`                | 使用 `repoctl.config.ts`，且没有残留 `monorepo.config.ts`        | 保留 `repoctl.config.ts`     |
+| `commit-hooks`               | Husky 和 lint-staged 同时就绪                                    | `repo upgrade --yes`         |
+| `tooling-imports`            | 配置不再引用本地源码 loader 或旧 config wrapper                  | `repo upgrade --yes`         |
+| `workspace-patterns`         | 常见目录被 workspace patterns 覆盖                               | `repo init --yes`            |
+| `workspace-package-coverage` | 常见目录下的包都被 pnpm 覆盖                                     | `repo init --yes`            |
+
+## 3. 输出报告
+
+```bash
+repo doctor
+repo doctor --json
+repo doctor --markdown --redact
+repo doctor --json --out reports/doctor.json
+repo doctor --markdown --redact --out reports/doctor.md
+```
+
+自动化脚本推荐使用 `pnpm run repo:doctor -- --json` 或 `pnpm exec repo doctor --json`。
+
+| 输出         | 适合场景                    |
+| ------------ | --------------------------- |
+| 默认交互文本 | 本地直接阅读                |
+| JSON         | CI、编辑器、脚本消费        |
+| Markdown     | 粘贴到 issue、PR 或排障文档 |
+| `--redact`   | 分享报告前隐藏本机绝对路径  |
+
+## 4. strict 模式
+
+`--strict` 会把 warning 也视为失败。它适合放在 CI 早期阶段：
+
+```bash
+pnpm install --frozen-lockfile
+repo doctor --strict
+repo check --full
+```
+
+如果你正在接入存量仓库，建议先不用 strict，把报告保存下来逐项修复：
+
+```bash
+repo doctor --markdown --redact --out reports/doctor.md
+repo upgrade --no-overwrite
+repo doctor
+```
+
+## 5. 排查顺序
+
+建议按阻塞程度处理：
+
+1. 先处理 `fail`，否则命令或 CI 很可能无法继续。
+2. 再处理遗留配置和 Node 版本问题。
+3. 然后补根脚本、hook 和 lint-staged。
+4. 最后整理 workspace patterns 与 tooling imports。
+
+如果不确定报告能否安全分享，使用 [报告与自动化输出](./reports.md) 里的 `--redact` 和 `env support`。

package/templates/vitepress/zh/repoctl/execution-model.md

@@ -0,0 +1,81 @@
+---
+description: 说明 repoctl CLI 的入口层级、命令懒加载、非交互输出和脚本集成方式。
+---
+
+# repoctl 执行模型
+
+repoctl 的核心设计是把日常入口保持短，把细粒度能力放到分组命令里，并让 CI、编辑器和脚本可以读取结构化输出。
+
+## 1. 入口层级
+
+| 层级        | 示例                                                               | 使用场景                       |
+| ----------- | ------------------------------------------------------------------ | ------------------------------ |
+| 根脚本      | `pnpm run repo:doctor`、`pnpm run repo:new`、`pnpm run repo:check` | 团队日常开发、README、贡献指南 |
+| `repo` 命令 | `pnpm exec repo doctor`                                            | 文档、CI、脚本、排障           |
+| 分组命令    | `repo env support`、`repo verify pre-push`                         | 维护者、自动化和集成工具       |
+
+## 2. 命令执行过程
+
+repoctl 启动时只注册命令树。具体实现会在 action 执行时再加载，因此查看帮助和列出命令不会提前扫描所有 workspace、Git 状态和模板文件。
+
+```txt
+repo --help
+  -> 注册命令树
+  -> 输出帮助
+
+repo doctor
+  -> 注册命令树
+  -> 加载 doctor 实现
+  -> 发现 workspace
+  -> 输出诊断报告
+```
+
+这种模型适合命令数量较多的 monorepo 工具：日常命令保持快，重逻辑只在真正执行时进入。
+
+## 3. 输出模式
+
+很多 repoctl 命令都同时服务人和机器：
+
+| 参数           | 行为                             | 典型用途                 |
+| -------------- | -------------------------------- | ------------------------ |
+| `--json`       | 输出结构化 JSON                  | CI、编辑器、脚本         |
+| `--markdown`   | 输出 Markdown 报告               | issue、PR、协作文档      |
+| `--out <file>` | 写入文件                         | 保存 artifact 或生成计划 |
+| `--redact`     | 脱敏 cwd、workspace、home 等路径 | 分享本机报告             |
+| `--dry-run`    | 只生成计划，不写入业务文件       | 审查创建和校验动作       |
+
+`--json`、`--markdown`、`--out` 在 `repo check` 和 `repo new` 这类命令里会隐含预览语义，避免自动化读取计划时意外执行写入。
+
+## 4. 失败状态
+
+repoctl 的失败状态遵循阻塞优先：
+
+| 命令                     | 什么时候失败                                          |
+| ------------------------ | ----------------------------------------------------- |
+| `repo doctor`            | 存在 `fail` 检查项；加 `--strict` 时 warning 也会失败 |
+| `repo templates --check` | 模板健康检查出现 fail                                 |
+| `repo new`               | 模板不存在、目标校验失败或写入失败                    |
+| `repo check --full`      | 任一 root script 校验失败                             |
+| `repo verify *`          | 对应 hook 或校验命令失败                              |
+
+如果只是想知道会发生什么，先加 `--dry-run` 或输出计划：
+
+```bash
+repo new docs --template vitepress --json --out plans/docs.json
+repo check --markdown --out reports/check-plan.md
+```
+
+## 5. 和配置文件的关系
+
+repoctl 会从 workspace 根目录加载 `repoctl.config.*`。`monorepo.config.*` 已不再加载。
+
+配置加载后会影响具体命令，例如：
+
+| 配置区域           | 影响命令                                                            |
+| ------------------ | ------------------------------------------------------------------- |
+| `commands.init`    | `repo init`                                                         |
+| `commands.create`  | `repo new`                                                          |
+| `commands.upgrade` | `repo upgrade`                                                      |
+| `tooling`          | `repoctl/tooling` wrapper 生成的 ESLint、Vitest、lint-staged 等配置 |
+
+更多配置示例见：[配置文件](./config.md)。