@icebreakers/monorepo-templates 1.0.15 → 1.2.0

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

@@ -1,12 +1,12 @@
-# 快速开始
+# Getting Started
 
-这一页按“把 repoctl 接进一个仓库”的顺序写。你不需要先理解所有工具，先让仓库能被诊断、能创建包、能跑提交前校验。
+This guide follows the order you would use when adding repoctl to a workspace.
 
-## 准备环境
+## Prerequisites
 
-- Node.js 20 或更高版本。
-- pnpm。推荐通过 Corepack 启用：`corepack enable`。
-- Git。`repo doctor` 会读取仓库信息，用来补全 package metadata 和诊断提交链路。
+- Node.js 20 or newer.
+- pnpm. Corepack is recommended: `corepack enable`.
+- Git. `repo doctor` reads repository metadata and checks the commit workflow.
 
 ```bash
 node -v
@@ -14,15 +14,15 @@ pnpm -v
 git --version
 ```
 
-## 安装 repoctl
+## Install
 
 ```bash
 pnpm add -D repoctl
 ```
 
-如果你使用的是这套模板生成的新仓库，依赖和根脚本通常已经准备好了，可以直接从 `pnpm install` 开始。
+If the repository was generated from this template, the dependency and root scripts may already be present.
 
-## 初始化仓库默认值
+## Initialize Defaults
 
 ```bash
 pnpm install
@@ -30,42 +30,40 @@ pnpm exec repo init
 pnpm exec repo doctor
 ```
 
-这三步分别解决：
+| Command        | Purpose                                                                       |
+| -------------- | ----------------------------------------------------------------------------- |
+| `pnpm install` | Install workspace dependencies and local links                                |
+| `repo init`    | Add recommended scripts, workspace patterns, and tooling entries              |
+| `repo doctor`  | Check root files, Node version, CLI dependency, stale config files, and hooks |
 
-| 命令           | 作用                                                |
-| -------------- | --------------------------------------------------- |
-| `pnpm install` | 安装 workspace 依赖并创建本地链接                   |
-| `repo init`    | 补齐推荐根脚本、workspace patterns 和基础工具链入口 |
-| `repo doctor`  | 检查根目录、Node 版本、CLI 依赖、遗留配置和提交链路 |
+Fix blocking issues reported by `doctor`, then run it again.
 
-如果 `doctor` 报错，先按输出里的 `fix:` 处理。处理完再跑一次 `pnpm exec repo doctor`。
+## Create A Package
 
-## 创建第一个包
-
-先看模板列表：
+List templates first:
 
 ```bash
 pnpm exec repo templates
 ```
 
-创建一个 TypeScript 库：
+Create a TypeScript library:
 
 ```bash
 pnpm exec repo new sdk --template tsdown
 ```
 
-创建前只想预览：
+Preview before writing files:
 
 ```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、编辑器和脚本读取创建计划。
+`--json` and `--out` imply `--dry-run`, which makes them suitable for CI, editor integrations, and scripts.
 
-## 使用根脚本
+## Use Root Scripts
 
-如果仓库已经通过 `repo init` 或模板生成补齐了根脚本，日常可以写得更短：
+After `repo init`, daily commands can be shorter:
 
 ```bash
 pnpm run repo:init
@@ -74,16 +72,14 @@ pnpm run repo:new -- sdk --template tsdown
 pnpm run repo:check
 ```
 
-对应关系：
-
-| 根脚本                         | 等价命令                     |
+| Root script                    | Equivalent CLI               |
 | ------------------------------ | ---------------------------- |
 | `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`       |
 
-## 提交前检查
+## Verify Before Committing
 
 ```bash
 pnpm build
@@ -92,7 +88,7 @@ pnpm typecheck
 pnpm test
 ```
 
-如果只想走 repoctl 推荐的本地检查入口：
+Or use the repoctl verification entry:
 
 ```bash
 pnpm run repo:check
@@ -100,9 +96,7 @@ pnpm exec repo check --dry-run
 pnpm exec repo check --json --out reports/check-plan.json
 ```
 
-## 同步模板标准资产
-
-当模板升级后，用 `upgrade` 同步新的默认配置和脚本：
+## Sync Template Assets
 
 ```bash
 pnpm exec repo upgrade
@@ -110,13 +104,13 @@ pnpm exec repo upgrade --no-overwrite
 pnpm exec repo upgrade --yes
 ```
 
-- `--no-overwrite`：保留已有 drifted 文件。
-- `--yes` / `--overwrite`：适合明确要覆盖标准资产的自动化场景。
-- 非 TTY 环境不会弹出交互提示。
+- `--no-overwrite` preserves changed managed files.
+- `--yes` or `--overwrite` is for explicit automated overwrites.
+- Non-TTY environments do not open interactive prompts.
 
-## 常见下一步
+## Next Steps
 
-- 已有仓库渐进接入：阅读 [接入已有仓库](./adopt-existing.md)。
-- 想固定默认模板：阅读 [配置文件](./config.md)。
-- 想查看所有模板：阅读 [模板与创建](./templates.md)。
-- 想把诊断结果发给同事：阅读 [排障与报告](./troubleshooting.md)。
+- Adopt an existing repository: [Adopt Existing Repositories](./adopt-existing.md).
+- Set team defaults: [Configuration](./config.md).
+- Inspect template keys: [Templates](./templates.md).
+- Share diagnostic output: [Troubleshooting](./troubleshooting.md).

package/templates/vitepress/repoctl/index.md

@@ -1,23 +1,23 @@
-# repoctl 概览
+# repoctl Overview
 
-`repoctl` 是这套模板推荐给使用者的包名。默认命令是 `repo`，目标是把 pnpm workspace、Turborepo、模板创建、诊断报告和提交前校验收敛到一组稳定入口里。
+`repoctl` is the user-facing package name for this monorepo toolkit. Its recommended command is `repo`.
 
-它不替代 pnpm、Turbo 或 changesets，而是把这些工具在 monorepo 里的常见动作串起来。
+The CLI does not replace pnpm, Turborepo, or pnpm versioning. It gives teams a stable layer for common monorepo actions: setup, diagnostics, scaffolding, local verification, and template asset upgrades.
 
-## 什么时候使用 repoctl
+## When To Use It
 
-| 场景                                     | 推荐入口                 |
-| ---------------------------------------- | ------------------------ |
-| 给已有 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>`    |
+| Goal                                                  | Command                  |
+| ----------------------------------------------------- | ------------------------ |
+| Add recommended scripts and workspace defaults        | `pnpm exec repo init`    |
+| Check whether a repository is ready to develop        | `pnpm exec repo doctor`  |
+| Create a package, app, docs site, service, or CLI     | `pnpm exec repo new`     |
+| Reproduce the recommended pre-commit or pre-push flow | `pnpm exec repo check`   |
+| Sync newer standard assets from the template          | `pnpm exec repo upgrade` |
+| Persist output for CI, editors, or issue reports      | `--json --out <file>`    |
 
-## 推荐命令层级
+## Recommended Command Layers
 
-### 1. 生成仓库里的 repo:\* 根脚本
+### repo:\* Root Scripts
 
 ```bash
 pnpm run repo:init
@@ -26,9 +26,9 @@ pnpm run repo:new
 pnpm run repo:check
 ```
 
-这是给日常开发和团队文档使用的入口。短、稳定、不需要先解释 CLI 包名，也不会和 pnpm 内置命令冲突。
+These are the best commands for day-to-day team docs. They are short, explicit, and do not collide with pnpm built-in commands.
 
-### 2. 明确调用 repo CLI
+### Explicit CLI Calls
 
 ```bash
 pnpm exec repo init
@@ -38,9 +38,9 @@ pnpm exec repo new sdk --template tsdown
 pnpm exec repo check --dry-run
 ```
 
-这是文档、CI、脚本和排障里最清楚的写法。
+Use this form in CI, scripts, troubleshooting docs, and reproducible examples.
 
-### 3. 分组命令
+### Grouped Commands
 
 ```bash
 pnpm exec repo ws ls
@@ -49,54 +49,26 @@ pnpm exec repo env support --markdown --redact
 pnpm exec repo config inspect
 ```
 
-这些入口适合已经熟悉 repoctl 的维护者，用来做更细的 workspace、tooling、环境和配置操作。
+Grouped commands are for maintainers and automation that need finer control.
 
-## repoctl 管什么
+## Command Entrypoints
 
-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，例如：
+The package exposes multiple bins:
 
 ```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)
+The docs prefer `repo` so new users only need to remember one command name.
+
+## Keep Reading
+
+- [Getting Started](./getting-started.md)
+- [Choose By Scenario](./scenarios.md)
+- [Command Reference](./commands.md)
+- [Configuration](./config.md)
+- [Templates](./templates.md)
+- [Workflows and CI](./workflows.md)
+- [Troubleshooting](./troubleshooting.md)
+- [Command Aliases](./aliases.md)

package/templates/vitepress/repoctl/reports.md

@@ -1,94 +1,40 @@
 ---
-description: 说明 repoctl 的 JSON、Markdown、out、redact、env info、env snapshot 和 env support 报告能力。
+outline: deep
 ---
 
-# 报告与自动化输出
+# Reports and Automation Output
 
-repoctl 的报告能力用于把本地上下文变成可保存、可脱敏、可给脚本读取的文件。它适合 CI artifact、issue 模板、编辑器集成和跨机器排障。
+repoctl commands expose human-readable text for terminals, Markdown for issues and pull requests, and stable JSON for automation.
 
-## 1. 通用输出参数
+## Common Options
 
-| 参数           | 支持命令示例                            | 作用                           |
-| -------------- | --------------------------------------- | ------------------------------ |
-| `--json`       | `doctor`、`check`、`templates`、`env`   | 输出结构化数据                 |
-| `--markdown`   | `doctor`、`check`、`templates`、`env`   | 输出便于阅读和粘贴的报告       |
-| `--out <file>` | 多数报告命令                            | 把输出写入文件                 |
-| `--redact`     | `doctor`、`check`、`env`                | 脱敏本机路径                   |
-| `--strict`     | `doctor`、`env snapshot`、`env support` | 有 fail 或 warn 时返回失败状态 |
+- `--json`: emit structured data with stable field names.
+- `--markdown`: emit a shareable report.
+- `--out <file>`: write output to a file.
+- `--redact`: replace local absolute paths.
+- `--strict`: treat doctor warnings as failures where supported.
 
-## 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 示例
+## Environment Commands
 
 ```bash
-repo doctor --json --out reports/doctor.json
-repo check --full --json --out reports/check-plan.json
+repo env info --json
+repo env paths --markdown
+repo env snapshot --json --out reports/snapshot.json
 repo env support --markdown --redact --out reports/support.md
 ```
 
-建议把 `reports/` 上传为 artifact。这样 CI 失败时，不需要重新询问维护者使用了什么 Node、pnpm、workspace 根目录和校验计划。
-
-## 4. issue 排障模板
+The support bundle combines environment facts, resolved configuration, doctor results, the check plan, and report paths.
 
-当你需要把问题交给同事或维护者时，可以先生成 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 适合机器判断，不适合人工长时间阅读：
+## CI Example
 
 ```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
+repo check --full --dry-run --json --out reports/check-plan.json
+repo env support --markdown --redact --out reports/support.md
 ```
 
-常见消费方式：
+Upload `reports/` as a CI artifact so failures can be inspected without exposing local paths.
 
-| 目标                | 使用方式                             |
-| ------------------- | ------------------------------------ |
-| 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
-```
+## Choosing A Format
 
-如果报告要离开本机，默认加 `--redact`。
+Use JSON when another program consumes the result. Use Markdown when a person will read or paste the report. Locale only changes human-readable strings; JSON field names and status codes stay unchanged.

package/templates/vitepress/repoctl/scenarios.md

@@ -1,15 +1,15 @@
-# 按场景选命令
+# Choose By Scenario
 
-如果你不确定该用哪个 repoctl 命令，先从这一页开始。
+Start here when you know what you want to do, but not which repoctl command to use.
 
-## 我刚拿到一个仓库
+## I Just Opened A Repository
 
 ```bash
 pnpm install
 pnpm run repo:doctor
 ```
 
-如果 `repo:*` 根脚本还不存在：
+If the `repo:*` scripts do not exist yet:
 
 ```bash
 pnpm add -D repoctl
@@ -17,9 +17,9 @@ pnpm exec repo init --yes
 pnpm exec repo doctor
 ```
 
-继续看：[快速开始](./getting-started.md)。
+Keep reading: [Getting Started](./getting-started.md).
 
-## 我要把 repoctl 接入旧仓库
+## I Want To Adopt repoctl In An Existing Repo
 
 ```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
 ```
 
-继续看：[接入已有仓库](./adopt-existing.md)。
+Keep reading: [Adopt Existing Repositories](./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
 ```
 
-继续看：[模板与创建](./templates.md)。
+Keep reading: [Templates](./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
 ```
 
-继续看：[工作流与 CI](./workflows.md)。
+Keep reading: [Workflows and CI](./workflows.md).
 
-## 我要调试 CI 或同事机器问题
+## I Want To Debug CI Or Another Machine
 
 ```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
 ```
 
-继续看：[排障与报告](./troubleshooting.md)。
+Keep reading: [Troubleshooting](./troubleshooting.md).
 
-## 我要同步模板标准资产
+## I Want To Sync Standard Assets
 
 ```bash
 pnpm exec repo upgrade --no-overwrite
@@ -82,15 +82,13 @@ 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`         |
 
-| 目标                     | 命令                          |
-| ------------------------ | ----------------------------- |
-| 第一次接入，保留已有配置 | `repo upgrade --no-overwrite` |
-| 明确要覆盖标准资产       | `repo upgrade --yes`          |
-| 只同步核心配置           | `repo upgrade --core`         |
-
-## 我要看 workspace 结构
+## I Want To Inspect Workspace Structure
 
 ```bash
 pnpm exec repo ws ls
@@ -98,16 +96,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
 ```
 
-继续看：[配置文件](./config.md)。
+Keep reading: [Configuration](./config.md).
 
-## 我要写更短的命令
+## I Want Shorter Commands
 
 ```bash
 repo tpl
@@ -116,4 +114,4 @@ repo e support --markdown --redact
 repo cfg i
 ```
 
-继续看：[命令别名](./aliases.md)。
+Keep reading: [Command Aliases](./aliases.md).