@icebreakers/monorepo-templates 1.1.0 → 1.2.1

package/templates/vitepress/zh/monorepo/troubleshooting.md

@@ -0,0 +1,20 @@
+# 常见问题排障
+
+repoctl 排障文档已经集中到：
+
+- [repoctl 排障与报告](../repoctl/troubleshooting.md)
+- [repoctl 命令速查](../repoctl/commands.md)
+
+## monorepo 知识点：先区分问题类型
+
+排障前先判断问题属于哪一类：
+
+| 类型           | 先看什么                              | 常用命令                                |
+| -------------- | ------------------------------------- | --------------------------------------- |
+| 仓库结构问题   | 根目录、workspace 文件、Node 版本     | `repo doctor`                           |
+| 模板创建问题   | 模板 key、目标目录、创建计划          | `repo templates` / `repo new --dry-run` |
+| 提交前校验问题 | staged 文件、workspace 归属、任务路由 | `repo check --dry-run`                  |
+| 环境差异问题   | Node、pnpm、Git、CI、路径             | `repo env support --markdown --redact`  |
+| 遗留配置问题   | `repoctl.config.ts` 与旧配置文件      | `repo config inspect`                   |
+
+旧页面继续保留为知识点索引，具体排查步骤以后优先维护在 repoctl 分区。

package/templates/vitepress/zh/repoctl/adopt-existing.md

@@ -0,0 +1,135 @@
+# 接入已有仓库
+
+repoctl 不只适合新模板仓库。它也可以渐进接入已有 pnpm workspace，用诊断报告和非覆盖同步把风险降下来。
+
+## 适合接入的仓库
+
+优先满足这些条件：
+
+- 已经使用 pnpm 或准备迁移到 pnpm。
+- 有根 `package.json`。
+- 能接受 `apps/*`、`packages/*`、`examples/*` 这类 workspace 目录约定。
+- 希望统一 `repo:init`、`repo:doctor`、`repo:new`、`repo:check` 这类日常入口。
+
+如果仓库还不是 pnpm workspace，先补最小 `pnpm-workspace.yaml`：
+
+```yaml
+packages:
+  - apps/*
+  - packages/*
+```
+
+## 第一步：安装并初始化
+
+```bash
+pnpm add -D repoctl
+pnpm exec repo init --yes
+```
+
+`repo init --yes` 会使用安全默认值。它会补齐推荐脚本和 workspace patterns，但不会无条件覆盖已有 README、package.json、pnpm-workspace.yaml 或 tooling 配置。
+
+## 第二步：保存第一次诊断
+
+```bash
+pnpm exec repo doctor --markdown --redact --out reports/doctor-before.md
+pnpm exec repo doctor --json --out reports/doctor-before.json
+```
+
+建议把第一次报告提交到 PR 评论或 artifact，而不是只看终端输出。
+
+重点看这些项：
+
+| 检查项                       | 常见问题                                         |
+| ---------------------------- | ------------------------------------------------ |
+| `package-json`               | 当前目录不是仓库根目录                           |
+| `workspace-manifest`         | 缺少 `pnpm-workspace.yaml`                       |
+| `node-version`               | 根 package 没声明 `engines.node` 或版本不匹配    |
+| `tool-package`               | 没安装 `repoctl`                                 |
+| `root-scripts`               | 缺少 `repo:init/repo:new/repo:check/repo:doctor` |
+| `config-file`                | 残留已废弃的 `monorepo.config.ts`                |
+| `commit-hooks`               | Husky 和 lint-staged 只接了一半                  |
+| `workspace-package-coverage` | package.json 没被 workspace patterns 覆盖        |
+
+## 第三步：保守同步标准资产
+
+```bash
+pnpm exec repo upgrade --no-overwrite
+pnpm exec repo doctor --markdown --redact --out reports/doctor-after.md
+```
+
+`--no-overwrite` 适合第一次接入：它同步缺失资产，但保留已有 drifted 文件。你可以在 PR diff 里逐项看哪些配置要进一步迁移。
+
+## 第四步：预览校验计划
+
+```bash
+pnpm exec repo check --dry-run
+pnpm exec repo check --json --out reports/check-plan.json
+pnpm exec repo check --markdown --redact --out reports/check-plan.md
+```
+
+先看 plan，再决定要不要接入 hook 或 CI。
+
+## 第五步：接入根脚本
+
+如果 `repo init` 已补齐根脚本，团队日常文档优先改成：
+
+```bash
+pnpm run repo:doctor
+pnpm run repo:new -- sdk
+pnpm run repo:check
+```
+
+CI 和自动化脚本仍建议写完整 CLI：
+
+```bash
+pnpm exec repo doctor --strict
+pnpm exec repo check --full
+```
+
+## 第六步：处理遗留配置
+
+### 遗留配置文件
+
+只保留：
+
+```txt
+repoctl.config.ts
+```
+
+`monorepo.config.ts` 已不再加载；请改名为 `repoctl.config.ts`。
+
+### 本地 tooling loader
+
+如果 `doctor` 提示 tooling 配置引用了本地源码 loader，使用：
+
+```bash
+pnpm exec repo upgrade --yes
+```
+
+这个命令会迁移到 `repoctl/tooling` 入口。简单的 `@icebreakers/commitlint-config`、`@icebreakers/eslint-config`、`@icebreakers/stylelint-config` wrapper 也会被保守转换为 `repoctl/tooling`，复杂 ESLint 配置会保留原有 rules、ignores、overrides 和额外 flat config 语义。
+
+### workspace patterns 不覆盖包
+
+运行：
+
+```bash
+pnpm exec repo init --yes
+```
+
+或手动扩展 `pnpm-workspace.yaml`。
+
+## 推荐 PR 结构
+
+存量仓库接入建议拆成小 PR：
+
+1. 安装 `repoctl`，补 `init/doctor/new/check` 根脚本。
+2. 提交 `doctor-before` 和 `doctor-after` 报告。
+3. 同步或迁移 tooling 配置。
+4. 接入 hook 和 CI。
+5. 用 `repo new --dry-run` 验证模板创建路径。
+
+## 下一步
+
+- [工作流与 CI](./workflows.md)
+- [排障与报告](./troubleshooting.md)
+- [配置文件](./config.md)

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`。