@icebreakers/monorepo-templates 1.0.15 → 1.2.0

package/templates/vitepress/zh/repoctl/getting-started.md

@@ -0,0 +1,122 @@
+# 快速开始
+
+这一页按“把 repoctl 接进一个仓库”的顺序写。你不需要先理解所有工具，先让仓库能被诊断、能创建包、能跑提交前校验。
+
+## 准备环境
+
+- Node.js 20 或更高版本。
+- pnpm。推荐通过 Corepack 启用：`corepack enable`。
+- Git。`repo doctor` 会读取仓库信息，用来补全 package metadata 和诊断提交链路。
+
+```bash
+node -v
+pnpm -v
+git --version
+```
+
+## 安装 repoctl
+
+```bash
+pnpm add -D repoctl
+```
+
+如果你使用 `create-repoctl` 创建新仓库，依赖和根脚本通常已经准备好了，可以直接从 `pnpm install` 开始。
+
+## 初始化仓库默认值
+
+```bash
+pnpm install
+pnpm exec repo init
+pnpm exec repo doctor
+```
+
+这三步分别解决：
+
+| 命令           | 作用                                                |
+| -------------- | --------------------------------------------------- |
+| `pnpm install` | 安装 workspace 依赖并创建本地链接                   |
+| `repo init`    | 补齐推荐根脚本、workspace patterns 和基础工具链入口 |
+| `repo doctor`  | 检查根目录、Node 版本、CLI 依赖、遗留配置和提交链路 |
+
+如果 `doctor` 报错，先按输出里的 `fix:` 处理。处理完再跑一次 `pnpm exec repo doctor`。
+
+## 创建第一个包
+
+先看模板列表：
+
+```bash
+pnpm exec repo templates
+```
+
+创建一个 TypeScript 库：
+
+```bash
+pnpm exec repo new sdk --template tsdown
+```
+
+创建前只想预览：
+
+```bash
+pnpm exec repo new sdk --template tsdown --dry-run
+pnpm exec repo new sdk --template tsdown --json --out plans/sdk.json
+```
+
+`--json` 和 `--out` 会隐含 `--dry-run`，适合 CI、编辑器和脚本读取创建计划。
+
+## 使用根脚本
+
+如果仓库已经通过 `repo init` 或模板生成补齐了根脚本，日常可以写得更短：
+
+```bash
+pnpm run repo:init
+pnpm run repo:doctor -- --json
+pnpm run repo:new -- sdk --template tsdown
+pnpm run repo:check
+```
+
+对应关系：
+
+| 根脚本                         | 等价命令                     |
+| ------------------------------ | ---------------------------- |
+| `pnpm run repo:init`           | `pnpm exec repo init`        |
+| `pnpm run repo:doctor -- args` | `pnpm exec repo doctor args` |
+| `pnpm run repo:new -- args`    | `pnpm exec repo new args`    |
+| `pnpm run repo:check`          | `pnpm exec repo check`       |
+
+## 提交前检查
+
+```bash
+pnpm build
+pnpm lint
+pnpm typecheck
+pnpm test
+```
+
+如果只想走 repoctl 推荐的本地检查入口：
+
+```bash
+pnpm run repo:check
+pnpm exec repo check --dry-run
+pnpm exec repo check --json --out reports/check-plan.json
+```
+
+## 同步模板标准资产
+
+当模板升级后，用 `upgrade` 同步新的默认配置和脚本：
+
+```bash
+pnpm exec repo upgrade
+pnpm exec repo upgrade --no-overwrite
+pnpm exec repo upgrade --yes
+```
+
+- `--no-overwrite`：保留已有 drifted 文件。
+- `--yes` / `--overwrite`：适合明确要覆盖标准资产的自动化场景。
+- 非 TTY 环境不会弹出交互提示。
+
+## 常见下一步
+
+- 已有仓库渐进接入：阅读 [接入已有仓库](./adopt-existing.md)。
+- 想固定默认模板：阅读 [配置文件](./config.md)。
+- 想查看所有模板：阅读 [模板与创建](./templates.md)。
+- 想把诊断结果发给同事：阅读 [排障与报告](./troubleshooting.md)。

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

@@ -0,0 +1,102 @@
+# repoctl 概览
+
+`repoctl` 是面向 pnpm 与 Turborepo monorepo 的任务型 CLI。默认命令是 `repo`，目标是把初始化、诊断、创建、校验、升级和发布收敛到一组稳定入口里。
+
+它不替代 pnpm、Turbo 或 pnpm versioning，而是把这些工具在 monorepo 里的常见动作串起来。
+
+## 什么时候使用 repoctl
+
+| 场景                                     | 推荐入口                 |
+| ---------------------------------------- | ------------------------ |
+| 给已有 pnpm workspace 补齐标准脚本和配置 | `pnpm exec repo init`    |
+| 判断当前仓库是不是能顺利开发             | `pnpm exec repo doctor`  |
+| 创建新的包、应用、文档站或 CLI           | `pnpm exec repo new`     |
+| 提交前复现推荐校验链路                   | `pnpm exec repo check`   |
+| 同步模板最新标准资产                     | `pnpm exec repo upgrade` |
+| 给 CI、编辑器或脚本读取结构化结果        | `--json --out <file>`    |
+
+## 推荐命令层级
+
+### 1. 生成仓库里的 repo:\* 根脚本
+
+```bash
+pnpm run repo:init
+pnpm run repo:doctor
+pnpm run repo:new
+pnpm run repo:check
+```
+
+这是给日常开发和团队文档使用的入口。短、稳定、不需要先解释 CLI 包名，也不会和 pnpm 内置命令冲突。
+
+### 2. 明确调用 repo CLI
+
+```bash
+pnpm exec repo init
+pnpm exec repo doctor
+pnpm exec repo templates
+pnpm exec repo new sdk --template tsdown
+pnpm exec repo check --dry-run
+```
+
+这是文档、CI、脚本和排障里最清楚的写法。
+
+### 3. 分组命令
+
+```bash
+pnpm exec repo ws ls
+pnpm exec repo tg init --all
+pnpm exec repo env support --markdown --redact
+pnpm exec repo config inspect
+```
+
+这些入口适合已经熟悉 repoctl 的维护者，用来做更细的 workspace、tooling、环境和配置操作。
+
+## repoctl 管什么
+
+repoctl 把 monorepo 里最容易分散的动作收敛为五条主线：
+
+| 主线   | 代表命令                      | 解决的问题                                                |
+| ------ | ----------------------------- | --------------------------------------------------------- |
+| 初始化 | `repo init` / `repo upgrade`  | 生成或同步 workspace、根脚本、Husky、lint-staged 等资产   |
+| 诊断   | `repo doctor`                 | 判断仓库根目录、运行时、脚本、配置和提交链路是否就绪      |
+| 创建   | `repo templates` / `repo new` | 使用内置模板生成库、应用、服务、文档站和 CLI              |
+| 校验   | `repo check` / `repo verify`  | 统一 pre-commit、staged typecheck、pre-push 和 commit-msg |
+| 报告   | `repo env support`            | 输出可保存、可脱敏、可给 CI 和协作者读取的上下文          |
+
+这几条主线都支持非交互参数。需要自动化时，优先使用 `--json`、`--markdown`、`--out <file>`、`--redact` 和 `--dry-run` 组合。
+
+## 新人和维护者的边界
+
+| 角色       | 推荐只记住                                                         | 需要深入时再看                                              |
+| ---------- | ------------------------------------------------------------------ | ----------------------------------------------------------- |
+| 新成员     | `pnpm run repo:doctor`、`pnpm run repo:new`、`pnpm run repo:check` | [按场景选命令](./scenarios.md)                              |
+| 包维护者   | `repo templates`、`repo new --template`、`repo check --full`       | [模板资产治理](./template-assets.md)                        |
+| CI 维护者  | `repo doctor --strict`、`repo check --full`、`repo env support`    | [报告与自动化输出](./reports.md)                            |
+| 平台维护者 | `repo init`、`repo upgrade`、`repo config inspect`                 | [执行模型](./execution-model.md) 和 [配置文件](./config.md) |
+
+## 命令入口
+
+`repoctl` 包提供多个 bin，例如：
+
+```bash
+pnpm exec repoctl doctor
+pnpm exec repoctl new
+```
+
+文档统一推荐 `repo`，是为了减少新人需要记住的名字。底层实现来自同一套 CLI。
+
+## 下一步
+
+- 第一次接入：[快速开始](./getting-started.md)
+- 不知道用哪个命令：[按场景选命令](./scenarios.md)
+- 理解 CLI 怎么执行：[执行模型](./execution-model.md)
+- 查命令参数：[命令速查](./commands.md)
+- 理解本地校验：[校验链路](./checks.md)
+- 看 doctor 具体检查项：[doctor 诊断](./doctor.md)
+- 固化团队默认值：[配置文件](./config.md)
+- 看可创建的模板：[模板与创建](./templates.md)
+- 治理模板资产：[模板资产治理](./template-assets.md)
+- 接入 CI 和本地流程：[工作流与 CI](./workflows.md)
+- 生成机器可读报告：[报告与自动化输出](./reports.md)
+- 排查常见问题：[排障与报告](./troubleshooting.md)
+- 熟悉短命令：[命令别名](./aliases.md)

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

@@ -0,0 +1,94 @@
+---
+description: 说明 repoctl 的 JSON、Markdown、out、redact、env info、env snapshot 和 env support 报告能力。
+---
+
+# 报告与自动化输出
+
+repoctl 的报告能力用于把本地上下文变成可保存、可脱敏、可给脚本读取的文件。它适合 CI artifact、issue 模板、编辑器集成和跨机器排障。
+
+## 1. 通用输出参数
+
+| 参数           | 支持命令示例                            | 作用                           |
+| -------------- | --------------------------------------- | ------------------------------ |
+| `--json`       | `doctor`、`check`、`templates`、`env`   | 输出结构化数据                 |
+| `--markdown`   | `doctor`、`check`、`templates`、`env`   | 输出便于阅读和粘贴的报告       |
+| `--out <file>` | 多数报告命令                            | 把输出写入文件                 |
+| `--redact`     | `doctor`、`check`、`env`                | 脱敏本机路径                   |
+| `--strict`     | `doctor`、`env snapshot`、`env support` | 有 fail 或 warn 时返回失败状态 |
+
+## 2. env 子命令
+
+| 命令                | 内容                                         | 适合用途         |
+| ------------------- | -------------------------------------------- | ---------------- |
+| `repo env info`     | cwd、workspace、Node、pnpm、包数量等环境摘要 | 快速确认环境     |
+| `repo env paths`    | 关键路径和建议报告路径                       | 统一报告落盘位置 |
+| `repo env snapshot` | 环境、doctor 和 check plan                   | CI 快照          |
+| `repo env support`  | 环境、路径、配置、doctor 和 check plan       | 完整排障包       |
+| `repo env mirror`   | VS Code binary mirror 设置                   | 国内网络环境优化 |
+
+常用组合：
+
+```bash
+repo env info --json --out reports/env.json
+repo env snapshot --markdown --redact --out reports/snapshot.md
+repo env support --markdown --redact --out reports/support.md
+```
+
+## 3. CI artifact 示例
+
+```bash
+repo doctor --json --out reports/doctor.json
+repo check --full --json --out reports/check-plan.json
+repo env support --markdown --redact --out reports/support.md
+```
+
+建议把 `reports/` 上传为 artifact。这样 CI 失败时，不需要重新询问维护者使用了什么 Node、pnpm、workspace 根目录和校验计划。
+
+## 4. issue 排障模板
+
+当你需要把问题交给同事或维护者时，可以先生成 Markdown：
+
+```bash
+repo env support --markdown --redact --out reports/support.md
+```
+
+然后在 issue 里附上：
+
+| 内容          | 来源              |
+| ------------- | ----------------- |
+| 环境摘要      | `env info`        |
+| 配置命中情况  | `config inspect`  |
+| doctor 失败项 | `doctor`          |
+| check 计划    | `check --dry-run` |
+| 推荐报告路径  | `env paths`       |
+
+## 5. 什么时候使用 JSON
+
+JSON 适合机器判断，不适合人工长时间阅读：
+
+```bash
+repo doctor --json --out reports/doctor.json
+repo templates --check --json --out reports/templates.json
+repo new docs --template vitepress --json --out plans/docs.json
+```
+
+常见消费方式：
+
+| 目标                | 使用方式                             |
+| ------------------- | ------------------------------------ |
+| CI 判断是否有阻塞项 | 读取 `doctor.summary.fail`           |
+| 编辑器展示模板列表  | 读取 `repo templates --json`         |
+| 预览创建结果        | 读取 `repo new --json`               |
+| 审计模板健康状态    | 读取 `repo templates --check --json` |
+
+## 6. 什么时候使用 Markdown
+
+Markdown 适合给人看，尤其适合 PR、issue 和协作文档：
+
+```bash
+repo doctor --markdown --redact --out reports/doctor.md
+repo check --markdown --redact --out reports/check-plan.md
+repo templates --markdown --out docs/templates.md
+```
+
+如果报告要离开本机，默认加 `--redact`。

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

@@ -1,15 +1,15 @@
-# Choose By Scenario
+# 按场景选命令
 
-Start here when you know what you want to do, but not which repoctl command to use.
+如果你不确定该用哪个 repoctl 命令，先从这一页开始。
 
-## I Just Opened A Repository
+## 我刚拿到一个仓库
 
 ```bash
 pnpm install
 pnpm run repo:doctor
 ```
 
-If the `repo:*` scripts do not exist yet:
+如果 `repo:*` 根脚本还不存在：
 
 ```bash
 pnpm add -D repoctl
@@ -17,9 +17,9 @@ pnpm exec repo init --yes
 pnpm exec repo doctor
 ```
 
-Keep reading: [Getting Started](./getting-started.md).
+继续看：[快速开始](./getting-started.md)。
 
-## I Want To Adopt repoctl In An Existing Repo
+## 我要把 repoctl 接入旧仓库
 
 ```bash
 pnpm add -D repoctl
@@ -29,9 +29,9 @@ pnpm exec repo upgrade --no-overwrite
 pnpm exec repo doctor --markdown --redact --out reports/doctor-after.md
 ```
 
-Keep reading: [Adopt Existing Repositories](./adopt-existing.md).
+继续看：[接入已有仓库](./adopt-existing.md)。
 
-## I Want To Create A Package Or App
+## 我要创建新包或应用
 
 ```bash
 pnpm exec repo templates
@@ -39,15 +39,15 @@ pnpm exec repo new sdk --template tsdown
 pnpm exec repo new docs --template vitepress --dry-run
 ```
 
-For daily development, root scripts also work:
+如果只是日常开发，根脚本也可以：
 
 ```bash
 pnpm run repo:new -- sdk --template tsdown
 ```
 
-Keep reading: [Templates](./templates.md).
+继续看：[模板与创建](./templates.md)。
 
-## I Want To Check Before Committing
+## 我要提交前自查
 
 ```bash
 pnpm run repo:check
@@ -55,16 +55,16 @@ pnpm exec repo check --dry-run
 pnpm exec repo check --full
 ```
 
-Save the plan when automation needs it:
+如果你想保存计划：
 
 ```bash
 pnpm exec repo check --json --out reports/check-plan.json
 pnpm exec repo check --markdown --redact --out reports/check-plan.md
 ```
 
-Keep reading: [Workflows and CI](./workflows.md).
+继续看：[工作流与 CI](./workflows.md)。
 
-## I Want To Debug CI Or Another Machine
+## 我要调试 CI 或同事机器问题
 
 ```bash
 pnpm exec repo doctor --markdown --redact --out reports/doctor.md
@@ -72,9 +72,9 @@ pnpm exec repo env support --markdown --redact --out reports/support.md
 pnpm exec repo env snapshot --json --out reports/snapshot.json
 ```
 
-Keep reading: [Troubleshooting](./troubleshooting.md).
+继续看：[排障与报告](./troubleshooting.md)。
 
-## I Want To Sync Standard Assets
+## 我要同步模板标准资产
 
 ```bash
 pnpm exec repo upgrade --no-overwrite
@@ -82,13 +82,15 @@ pnpm exec repo upgrade --yes
 pnpm exec repo upgrade --core
 ```
 
-| Goal                                       | Command                       |
-| ------------------------------------------ | ----------------------------- |
-| First adoption pass, preserve local config | `repo upgrade --no-overwrite` |
-| Explicitly overwrite managed assets        | `repo upgrade --yes`          |
-| Sync only core config                      | `repo upgrade --core`         |
+选择建议：
 
-## I Want To Inspect Workspace Structure
+| 目标                     | 命令                          |
+| ------------------------ | ----------------------------- |
+| 第一次接入，保留已有配置 | `repo upgrade --no-overwrite` |
+| 明确要覆盖标准资产       | `repo upgrade --yes`          |
+| 只同步核心配置           | `repo upgrade --core`         |
+
+## 我要看 workspace 结构
 
 ```bash
 pnpm exec repo ws ls
@@ -96,16 +98,16 @@ pnpm exec repo ws ls --json --out reports/workspaces.json
 pnpm exec repo ws ls --markdown --redact --out reports/workspaces.md
 ```
 
-## I Want To Inspect Config
+## 我要看配置是否生效
 
 ```bash
 pnpm exec repo config inspect
 pnpm exec repo cfg i --json --out reports/config.json
 ```
 
-Keep reading: [Configuration](./config.md).
+继续看：[配置文件](./config.md)。
 
-## I Want Shorter Commands
+## 我要写更短的命令
 
 ```bash
 repo tpl
@@ -114,4 +116,4 @@ repo e support --markdown --redact
 repo cfg i
 ```
 
-Keep reading: [Command Aliases](./aliases.md).
+继续看：[命令别名](./aliases.md)。

package/templates/vitepress/zh/repoctl/template-assets.md

@@ -0,0 +1,116 @@
+---
+description: 说明 repoctl 内置模板、templateMap、模板健康检查、创建计划和模板资产维护方式。
+---
+
+# repoctl 模板资产治理
+
+repoctl 的模板能力不只是复制目录。它会把模板元数据、默认生成目录、创建计划、健康检查和配置覆盖串起来。
+
+## 1. 内置模板映射
+
+| key           | source                | 默认 target        | 类型                  |
+| ------------- | --------------------- | ------------------ | --------------------- |
+| `tsdown`      | `templates/tsdown`    | `packages/tsdown`  | TypeScript library    |
+| `vue-lib`     | `templates/vue-lib`   | `packages/vue-lib` | Vue component library |
+| `hono-server` | `templates/server`    | `apps/server`      | Hono service          |
+| `vue-hono`    | `templates/client`    | `apps/client`      | Vue + Hono app        |
+| `vitepress`   | `templates/vitepress` | `apps/website`     | docs site             |
+| `cli`         | `templates/cli`       | `apps/cli`         | command line tool     |
+
+查看实际可用模板：
+
+```bash
+repo templates
+repo templates --json
+repo templates --markdown --out docs/templates.md
+```
+
+## 2. 创建计划
+
+`repo new` 会先解析创建计划，再决定是否写入文件。计划包含：
+
+| 字段                | 含义                                             |
+| ------------------- | ------------------------------------------------ |
+| `requestedTemplate` | 用户请求的模板 key                               |
+| `template`          | 实际使用的模板 key                               |
+| `sourceDir`         | 模板源目录                                       |
+| `targetDir`         | 输出目录                                         |
+| `targetExists`      | 目标目录是否已存在                               |
+| `packageName`       | 写入 package.json 的包名                         |
+| `renameJson`        | 是否把 `package.json` 输出为 `package.mock.json` |
+
+预览创建：
+
+```bash
+repo new docs --template vitepress --dry-run
+repo new docs --template vitepress --json --out plans/docs.json
+```
+
+`--json` 和 `--out` 都隐含 `--dry-run`，不会写入文件。
+
+## 3. 模板选择和报错
+
+显式传入 `--template` 时，repoctl 会先校验模板 key：
+
+```bash
+repo new sdk --template tsdown
+```
+
+如果模板 key 拼错，命令会失败并提示相近 key。它不会静默回退到默认模板，这样 CI 和脚本不会生成错误类型的项目。
+
+## 4. 健康检查
+
+模板资产可以通过 `repo templates --check` 检查：
+
+```bash
+repo templates --check
+repo templates --check --json --out reports/templates.json
+```
+
+检查内容包括：
+
+| 检查           | 目的                                 |
+| -------------- | ------------------------------------ |
+| source 唯一性  | 避免多个模板 key 指向同一源目录      |
+| target 唯一性  | 避免多个模板默认写到同一目标目录     |
+| source 目录    | 确认模板目录存在                     |
+| package.json   | 确认模板根目录包含包元数据           |
+| metadata       | 确认模板有 category 和 description   |
+| filtered files | 避免把临时、缓存或生成文件放入模板源 |
+
+## 5. 自定义模板
+
+可以在 `repoctl.config.ts` 里扩展模板映射：
+
+```ts
+import { defineMonorepoConfig } from 'repoctl'
+
+export default defineMonorepoConfig({
+  commands: {
+    create: {
+      defaultTemplate: 'internal-service',
+      templateMap: {
+        'internal-service': {
+          source: 'templates/internal-service',
+          target: 'apps/internal-service',
+        },
+      },
+    },
+  },
+})
+```
+
+自定义模板建议遵守同样的治理规则：唯一 source、唯一 target、模板根目录包含 `package.json`，并避免提交构建输出和缓存文件。
+
+## 6. 维护流程
+
+更新模板时建议按下面流程验证：
+
+```txt
+修改 templates/<name>
+  -> repo templates --check
+  -> repo new demo --template <name> --json --out plans/demo.json
+  -> 构建或测试生成后的 workspace
+```
+
+如果模板文件数量发生变化，维护模板快照的测试也需要同步更新。