@icebreakers/monorepo-templates 1.0.15 → 1.2.0

package/templates/vitepress/repoctl/checks.md

@@ -1,86 +1,39 @@
 ---
-description: 说明 repoctl check 和 verify 的校验模式、pre-commit、staged typecheck、pre-push 与 commit-msg 链路。
+outline: deep
 ---
 
-# repoctl 校验链路
+# repoctl Verification
 
-`repo check` 是给人使用的统一入口，`repo verify` 是给 hook、CI 和脚本复用的底层入口。
+`repo check` provides stable, task-oriented entrypoints for local and CI verification. It preserves the underlying workspace scripts and reports which commands will run before execution.
 
-## 1. 模式速查
+## Modes
 
-| 命令                                         | 模式         | 实际动作                                                       |
-| -------------------------------------------- | ------------ | -------------------------------------------------------------- |
-| `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 校验                                       |
+| Mode           | Command                         | Purpose                                             |
+| -------------- | ------------------------------- | --------------------------------------------------- |
+| Default        | `repo check`                    | Lightweight pre-commit verification                 |
+| Staged         | `repo check --staged`           | lint-staged plus workspace-aware type checking      |
+| Full           | `repo check --full`             | Root lint, typecheck, build, test, and tsd workflow |
+| Commit message | `repo check --edit-file <file>` | Validate a commit message file                      |
 
-预览模式不会真正执行校验：
+Use `--dry-run`, `--json`, or `--markdown` to inspect the plan without running it. `--out <file>` persists the result and `--redact` removes local paths.
 
-```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` |
-| 失败处理     | 任一任务失败时停止并返回失败状态                 |
+## Pre-Commit
 
-如果 CI 想要更明确地复现整仓校验，可以使用：
+`repo verify pre-commit` runs the repository's staged-file policy. JavaScript, TypeScript, Vue, and style files are routed to the configured lint tasks.
 
-```bash
-repo check --full
-```
+## Staged Type Checking
 
-## 5. commit message
+`repo verify staged-typecheck <files...>` maps changed TypeScript and Vue files to their owning workspace. Vue packages use their `vue-tsc` based typecheck script; TypeScript packages use `tsc`.
 
-`repo verify commit-msg <file>` 用于 Git 的 `commit-msg` hook。未配置自定义命令时，它会执行：
+## Pre-Push
 
-```bash
-pnpm exec commitlint --edit <file>
-```
+`repo verify pre-push` is the comprehensive delivery gate. The repository policy builds first, then runs lint, type checks, type-level tests, and test suites against built artifacts.
 
-如果你只是手动验证当前提交信息，可以运行：
+## Automation
 
 ```bash
-repo check --edit-file .git/COMMIT_EDITMSG
+repo check --full --dry-run --json --out reports/check-plan.json
+repo check --staged --markdown --redact --out reports/check-plan.md
 ```
 
-## 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` |
+JSON field names and command IDs do not change with `--lang`; only human-readable descriptions do.

package/templates/vitepress/repoctl/commands.md

@@ -1,8 +1,8 @@
-# 命令速查
+# Command Reference
 
-这一页只保留 repoctl 高频、实用、容易记错的命令。
+This page focuses on high-value repoctl commands and options.
 
-## 最推荐入口
+## Main Entry
 
 ```bash
 pnpm exec repo init
@@ -12,7 +12,7 @@ pnpm exec repo new
 pnpm exec repo check
 ```
 
-模板生成仓库里的推荐根脚本：
+Generated repositories also expose:
 
 ```bash
 pnpm run repo:init
@@ -31,31 +31,20 @@ 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`。
+Use it to initialize recommended workspace defaults. It skips existing managed files by default, appends missing workspace patterns, and supports non-interactive CI usage with `--yes`.
 
 ## `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
 ```
 
-用途：
+Use it to check root workspace files, Node compatibility, CLI dependency presence, `repo:*` root scripts, stale config files, and commit hooks.
 
-- 诊断当前目录是不是可直接开始使用的 monorepo 根目录。
-- 检查 Node 版本、workspace 文件、CLI 依赖、根脚本、遗留配置和提交链路。
-- `--strict` 会把 warning 也视为失败，适合 CI 门禁。
-- `--json` 和 `--markdown` 适合自动化、PR、issue 和外部协作。
-- `--redact` 会脱敏 workspace、cwd、home 等绝对路径。
+`--strict` treats warnings as failures. `--redact` removes local absolute paths from shareable reports.
 
 ## `repo templates`
 
@@ -68,11 +57,7 @@ repo templates --json
 repo templates --markdown --out docs/templates.md
 ```
 
-用途：
-
-- 查看内置模板 key、分类、默认生成目录和用途。
-- 检查模板元数据和源目录健康状态。
-- 给脚本读取 JSON，或生成 Markdown 文档片段。
+Use it to discover built-in template keys, inspect metadata, verify template health, or generate machine-readable output.
 
 ## `repo new`
 
@@ -84,12 +69,7 @@ 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。
+Use it to create packages and apps. Explicit template keys are validated first; invalid keys fail with suggestions instead of silently falling back.
 
 ## `repo check`
 
@@ -103,13 +83,7 @@ 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` 只预览将要执行的校验。
+Use it to preview or run the recommended local verification flow. `--staged` is closer to pre-commit; `--full` is closer to pre-push.
 
 ## `repo upgrade`
 
@@ -123,15 +97,9 @@ repo upgrade -i
 repo upgrade -s
 ```
 
-用途：
+Use it to sync standard assets and scripts. `--core` skips GitHub-related assets. `--no-overwrite` preserves changed files.
 
-- 同步仓库标准资产与脚本。
-- `--core` 只同步核心配置，跳过 GitHub 相关资产。
-- `-i` 交互式选择。
-- `--no-overwrite` / `-s` 保留已有 drifted 文件。
-- `--yes` / `--overwrite` 非交互覆盖 drifted 标准资产。
-
-## 分组命令
+## Grouped Commands
 
 ```bash
 repo ws ls
@@ -145,24 +113,8 @@ 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`                               | 只看计划，不执行校验或写入文件        |
-
-## 继续阅读
+## Keep Reading
 
-- [执行模型](./execution-model.md)
-- [校验链路](./checks.md)
-- [doctor 诊断](./doctor.md)
-- [工作流与 CI](./workflows.md)
-- [报告与自动化输出](./reports.md)
-- [命令别名](./aliases.md)
+- [Workflows and CI](./workflows.md)
+- [Troubleshooting](./troubleshooting.md)
+- [Command Aliases](./aliases.md)

package/templates/vitepress/repoctl/config.md

@@ -1,16 +1,14 @@
-# 配置文件
+# Configuration
 
-repoctl 推荐在仓库根目录使用一个配置文件：
+repoctl recommends one root config file:
 
 ```txt
 repoctl.config.ts
 ```
 
-`monorepo.config.ts` 已不再作为运行时配置入口。迁移旧仓库时请改名为 `repoctl.config.ts`。
+`monorepo.config.ts` is no longer loaded at runtime. Rename it to `repoctl.config.ts` before running repoctl.
 
-repoctl 支持 `ts`、`mts`、`cts`、`js`、`mjs`、`cjs` 等配置文件后缀。新项目优先使用 `repoctl.config.ts`，这样能保留类型提示和更清晰的迁移路径。
-
-## 最小配置
+## Minimal Config
 
 ```ts
 import { defineMonorepoConfig } from 'repoctl'
@@ -24,15 +22,13 @@ export default defineMonorepoConfig({
 })
 ```
 
-设置 `commands.create.defaultTemplate` 后：
+After setting `commands.create.defaultTemplate`, this command can create a package without asking for the template:
 
 ```bash
 repo new utils
 ```
 
-会直接按默认模板创建，不再询问模板类型。
-
-## 常用配置
+## Common Config
 
 ```ts
 import { defineMonorepoConfig } from 'repoctl'
@@ -55,14 +51,14 @@ export default defineMonorepoConfig({
 })
 ```
 
-| 配置                              | 作用                                    |
-| --------------------------------- | --------------------------------------- |
-| `commands.init.preset`            | 控制初始化默认预设                      |
-| `commands.create.defaultTemplate` | 控制 `repo new <name>` 的默认模板       |
-| `commands.clean.autoConfirm`      | 清理命令是否默认确认                    |
-| `commands.upgrade.skipOverwrite`  | 同步标准资产时是否保留已有 drifted 文件 |
+| Option                            | Purpose                                         |
+| --------------------------------- | ----------------------------------------------- |
+| `commands.init.preset`            | Default setup preset                            |
+| `commands.create.defaultTemplate` | Default template for `repo new <name>`          |
+| `commands.clean.autoConfirm`      | Whether clean commands confirm by default       |
+| `commands.upgrade.skipOverwrite`  | Whether upgrade preserves changed managed files |
 
-## 查看当前配置
+## Inspect Config
 
 ```bash
 repo config inspect
@@ -70,21 +66,4 @@ 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)
+Use `--redact` before sharing reports in issues, PRs, or external support channels.

package/templates/vitepress/repoctl/doctor.md

@@ -1,86 +1,46 @@
 ---
-description: 说明 repoctl doctor 的检查项、状态含义、strict 模式和修复建议。
+outline: deep
 ---
 
-# repoctl doctor 诊断
+# repoctl Doctor
 
-`repo doctor` 用来判断当前目录是不是一个可维护、可开发、可接入 repoctl 工作流的 pnpm monorepo 根目录。
+`repo doctor` diagnoses whether the current pnpm workspace is ready for development and release. It does not rewrite files.
 
-## 1. 状态含义
+## Statuses
 
-| 状态   | 含义           | 对退出码的影响                |
-| ------ | -------------- | ----------------------------- |
-| `pass` | 检查通过       | 不影响                        |
-| `warn` | 存在建议修复项 | 默认不失败，`--strict` 下失败 |
-| `fail` | 阻塞项         | 命令返回失败状态              |
+- `pass`: the check is satisfied.
+- `warn`: the repository works, but maintenance or consistency needs attention.
+- `fail`: a required workspace contract is missing or invalid.
 
-CI 中推荐使用：
+## Checks
 
-```bash
-repo doctor --strict
-```
+Doctor covers the root `package.json`, `pnpm-workspace.yaml`, Node compatibility, the `repoctl` dependency, recommended `repo:*` scripts, `repoctl.config.ts`, commit hooks, workspace pattern coverage, tooling imports, and release configuration.
 
-这样 warning 不会长期堆积成隐性风险。
+Check IDs and JSON fields remain stable in every locale.
 
-## 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. 输出报告
+## Reports
 
 ```bash
-repo doctor
 repo doctor --json
-repo doctor --markdown --redact
-repo doctor --json --out reports/doctor.json
+repo doctor --markdown
 repo doctor --markdown --redact --out reports/doctor.md
 ```
 
-自动化脚本推荐使用 `pnpm run repo:doctor -- --json` 或 `pnpm exec repo doctor --json`。
-
-| 输出         | 适合场景                    |
-| ------------ | --------------------------- |
-| 默认交互文本 | 本地直接阅读                |
-| JSON         | CI、编辑器、脚本消费        |
-| Markdown     | 粘贴到 issue、PR 或排障文档 |
-| `--redact`   | 分享报告前隐藏本机绝对路径  |
+`--redact` replaces workspace, current-directory, and home paths before output is shared.
 
-## 4. strict 模式
-
-`--strict` 会把 warning 也视为失败。它适合放在 CI 早期阶段：
+## Strict Mode
 
 ```bash
-pnpm install --frozen-lockfile
 repo doctor --strict
-repo check --full
 ```
 
-如果你正在接入存量仓库，建议先不用 strict，把报告保存下来逐项修复：
+Normal mode exits non-zero for failures. Strict mode also treats warnings as blocking, which is useful for CI policy enforcement.
+
+## Language
 
 ```bash
-repo doctor --markdown --redact --out reports/doctor.md
-repo upgrade --no-overwrite
-repo doctor
+repo --lang zh-CN doctor
+REPOCTL_LANG=zh-CN repo doctor
 ```
 
-## 5. 排查顺序
-
-建议按阻塞程度处理：
-
-1. 先处理 `fail`，否则命令或 CI 很可能无法继续。
-2. 再处理遗留配置和 Node 版本问题。
-3. 然后补根脚本、hook 和 lint-staged。
-4. 最后整理 workspace patterns 与 tooling imports。
-
-如果不确定报告能否安全分享，使用 [报告与自动化输出](./reports.md) 里的 `--redact` 和 `env support`。
+The explicit option wins over `REPOCTL_LANG`; English is the fixed fallback.

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

@@ -1,81 +1,28 @@
 ---
-description: 说明 repoctl CLI 的入口层级、命令懒加载、非交互输出和脚本集成方式。
+outline: deep
 ---
 
-# repoctl 执行模型
+# repoctl Execution Model
 
-repoctl 的核心设计是把日常入口保持短，把细粒度能力放到分组命令里，并让 CI、编辑器和脚本可以读取结构化输出。
+repoctl is a task layer over pnpm, Turborepo, repository scripts, and managed assets. It coordinates those systems without replacing them.
 
-## 1. 入口层级
+## Entrypoints
 
-| 层级        | 示例                                                               | 使用场景                       |
-| ----------- | ------------------------------------------------------------------ | ------------------------------ |
-| 根脚本      | `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`                         | 维护者、自动化和集成工具       |
+The recommended binary is `repo`. `repoctl` is an equivalent public bin. Generated workspaces also expose `repo:init`, `repo:new`, `repo:doctor`, and `repo:check` root scripts.
 
-## 2. 命令执行过程
+## Command Lifecycle
 
-repoctl 启动时只注册命令树。具体实现会在 action 执行时再加载，因此查看帮助和列出命令不会提前扫描所有 workspace、Git 状态和模板文件。
+1. Resolve locale from `--lang`, then `REPOCTL_LANG`, then English.
+2. Find the pnpm workspace root and load `repoctl.config.ts` when present.
+3. Build a deterministic plan from workspace state and command options.
+4. Prompt only when the terminal is interactive and the command needs a choice.
+5. Execute the plan or emit text, Markdown, or JSON output.
+6. Set a non-zero exit code for blocking diagnostics or command failures.
 
-```txt
-repo --help
-  -> 注册命令树
-  -> 输出帮助
+## Output Contracts
 
-repo doctor
-  -> 注册命令树
-  -> 加载 doctor 实现
-  -> 发现 workspace
-  -> 输出诊断报告
-```
+Text and Markdown are localized. JSON keys, status values, check IDs, command names, and option names are stable across locales.
 
-这种模型适合命令数量较多的 monorepo 工具：日常命令保持快，重逻辑只在真正执行时进入。
+## Configuration
 
-## 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)。
+Configuration supplies repository defaults. Explicit CLI options take precedence. Non-interactive automation should use `--yes`, explicit template keys, and report output options instead of relying on prompts.