@icebreakers/monorepo-templates 1.1.0 → 1.2.1

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).

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

@@ -1,116 +1,47 @@
 ---
-description: 说明 repoctl 内置模板、templateMap、模板健康检查、创建计划和模板资产维护方式。
+outline: deep
 ---
 
-# repoctl 模板资产治理
+# Template Asset Management
 
-repoctl 的模板能力不只是复制目录。它会把模板元数据、默认生成目录、创建计划、健康检查和配置覆盖串起来。
+Templates are one repoctl capability. `@icebreakers/monorepo-templates` packages built-in project templates and managed repository assets; templates under `templates/*` are private source workspaces and are not published independently.
 
-## 1. 内置模板映射
+## Built-In Mapping
 
-| 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     |
-
-查看实际可用模板：
+Template metadata defines a stable key, category, source directory, default target, and description. The CLI, create commands, and documentation consume the same registry.
 
 ```bash
 repo templates
-repo templates --json
-repo templates --markdown --out docs/templates.md
+repo templates tsdown
+repo templates --category library
 ```
 
-## 2. 创建计划
-
-`repo new` 会先解析创建计划，再决定是否写入文件。计划包含：
-
-| 字段                | 含义                                             |
-| ------------------- | ------------------------------------------------ |
-| `requestedTemplate` | 用户请求的模板 key                               |
-| `template`          | 实际使用的模板 key                               |
-| `sourceDir`         | 模板源目录                                       |
-| `targetDir`         | 输出目录                                         |
-| `targetExists`      | 目标目录是否已存在                               |
-| `packageName`       | 写入 package.json 的包名                         |
-| `renameJson`        | 是否把 `package.json` 输出为 `package.mock.json` |
-
-预览创建：
+## Creation Plans
 
 ```bash
-repo new docs --template vitepress --dry-run
+repo new sdk --template tsdown --dry-run
 repo new docs --template vitepress --json --out plans/docs.json
 ```
 
-`--json` 和 `--out` 都隐含 `--dry-run`，不会写入文件。
+A plan records the selected template, source, destination, package name, workspace pattern, and whether fallback behavior was used. Unknown explicit keys fail with a suggestion.
 
-## 3. 模板选择和报错
-
-显式传入 `--template` 时，repoctl 会先校验模板 key：
-
-```bash
-repo new sdk --template tsdown
-```
-
-如果模板 key 拼错，命令会失败并提示相近 key。它不会静默回退到默认模板，这样 CI 和脚本不会生成错误类型的项目。
-
-## 4. 健康检查
-
-模板资产可以通过 `repo templates --check` 检查：
+## Health Checks
 
 ```bash
 repo templates --check
-repo templates --check --json --out reports/templates.json
+repo templates --check --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',
-        },
-      },
-    },
-  },
-})
-```
+Health checks validate unique sources and targets, source directories, package manifests, metadata, and filtered temporary files.
 
-自定义模板建议遵守同样的治理规则：唯一 source、唯一 target、模板根目录包含 `package.json`，并避免提交构建输出和缓存文件。
+## Managed Assets
 
-## 6. 维护流程
+`repo init` and `repo upgrade` synchronize root scripts, configuration, hooks, and release assets. Existing custom files are preserved unless overwrite behavior is explicitly selected.
 
-更新模板时建议按下面流程验证：
+Repository maintainers refresh packaged copies with:
 
-```txt
-修改 templates/<name>
-  -> repo templates --check
-  -> repo new demo --template <name> --json --out plans/demo.json
-  -> 构建或测试生成后的 workspace
+```bash
+pnpm --filter @icebreakers/monorepo-templates sync:assets
 ```
 
-如果模板文件数量发生变化，维护模板快照的测试也需要同步更新。
+Generated copies should never be edited by hand.

package/templates/vitepress/repoctl/templates.md

@@ -1,21 +1,19 @@
-# 模板与创建
+# Templates
 
-repoctl 的模板由 `@icebreakers/monorepo-templates` 维护。CLI、脚手架和文档都复用同一份模板元数据。
+repoctl templates are maintained by `@icebreakers/monorepo-templates`. The CLI, scaffolder, and docs share the same template metadata.
 
-更偏维护者视角的模板元数据、健康检查和自定义模板说明见：[模板资产治理](./template-assets.md)。
+## Built-In Templates
 
-## 内置模板
+| Key           | Category | Default target     | Use case                |
+| ------------- | -------- | ------------------ | ----------------------- |
+| `tsdown`      | library  | `packages/tsdown`  | TypeScript library      |
+| `vue-lib`     | library  | `packages/vue-lib` | Vue 3 component library |
+| `vue-hono`    | app      | `apps/client`      | Vue 3 + Hono app        |
+| `hono-server` | service  | `apps/server`      | Hono API service        |
+| `vitepress`   | docs     | `apps/website`     | VitePress docs site     |
+| `cli`         | tool     | `apps/cli`         | TypeScript CLI          |
 
-| Key           | Category | 默认目录           | 适合场景                    |
-| ------------- | -------- | ------------------ | --------------------------- |
-| `tsdown`      | library  | `packages/tsdown`  | TypeScript 库包             |
-| `vue-lib`     | library  | `packages/vue-lib` | Vue 3 组件库                |
-| `vue-hono`    | app      | `apps/client`      | Vue 3 + Hono 前后端一体应用 |
-| `hono-server` | service  | `apps/server`      | Hono API 服务               |
-| `vitepress`   | docs     | `apps/website`     | VitePress 文档站            |
-| `cli`         | tool     | `apps/cli`         | TypeScript 命令行工具       |
-
-## 查看模板
+## Discover Templates
 
 ```bash
 repo templates
@@ -25,7 +23,7 @@ repo templates --json
 repo templates --markdown --out docs/templates.md
 ```
 
-## 创建模板
+## Create From A Template
 
 ```bash
 repo new sdk --template tsdown
@@ -35,72 +33,72 @@ repo new website --template vitepress
 repo new toolbox --template cli
 ```
 
-普通名字会自动放到模板约定的目录里，例如库包进入 `packages/`，应用进入 `apps/`。如果你传入带 `/` 的路径，例如 `packages/shared-utils`，repoctl 会尊重这个路径。
+Simple names are placed in the conventional target folder. Library templates go under `packages/`; app templates go under `apps/`. If you pass an explicit path such as `packages/shared-utils`, repoctl respects it.
 
-## 按目标选择模板
+## Choose By Goal
 
-### 要发布 npm 库
+### Publish an npm library
 
 ```bash
 repo new sdk --template tsdown
 ```
 
-生成后先检查：
+Check first:
 
-- `package.json` 的 `name`、`exports`、`types`。
-- `tsdown.config.ts` 是否符合产物格式。
-- 是否需要补 `tsd` 类型测试。
+- `package.json` `name`, `exports`, and `types`.
+- Whether `tsdown.config.ts` matches the desired output format.
+- Whether public types need `tsd` tests.
 
-### 要沉淀 Vue 组件
+### Build reusable Vue components
 
 ```bash
 repo new ui --template vue-lib
 ```
 
-生成后先检查：
+Check first:
 
-- 组件入口是否只导出稳定 API。
-- 样式是否能通过 Stylelint。
-- 文档站或示例应用是否需要同步创建。
+- Component entry points only expose stable APIs.
+- Styles pass Stylelint.
+- A docs site or example app should be created alongside it if needed.
 
-### 要创建应用或服务
+### Create an app or service
 
 ```bash
 repo new web --template vue-hono
 repo new api --template hono-server
 ```
 
-生成后先检查：
+Check first:
 
-- 运行时环境变量和部署平台约束。
-- `dev`、`build`、`typecheck` 脚本是否接入根任务。
-- 是否需要在 CI 里加入 E2E 或集成测试。
+- Runtime environment variables and deployment constraints.
+- `dev`, `build`, and `typecheck` scripts are part of root tasks.
+- CI needs integration or E2E tests.
 
-### 要创建文档站
+### Create a docs site
 
 ```bash
 repo new docs --template vitepress
 ```
 
-生成后先检查：
+Check first:
 
-- 导航和 sidebar 是否围绕产品或包名组织。
-- 是否需要中英文 locale。
-- 是否需要把 `repo templates --markdown` 输出写进文档。
+- Nav and sidebar are organized around the product or package.
+- A second locale is required.
+- `repo templates --markdown` output should be written into docs.
 
-### 要创建 CLI
+### Create a CLI
 
 ```bash
 repo new toolbox --template cli
 ```
 
-生成后先检查：
+Check first:
 
-- `bin` 字段是否符合最终命令名。
-- 参数解析、退出码和帮助信息是否可测试。
-- 是否需要把命令用法写入 README。
+- The `bin` field matches the final command name.
+- Argument parsing, exit codes, and help output are testable.
+- README documents command usage.
 
-## 创建前预览
+## Preview Creation
 
 ```bash
 repo new website --template vitepress --dry-run
@@ -108,52 +106,23 @@ repo new website --template vitepress --json
 repo new website --template vitepress --json --out plans/website.json
 ```
 
-`--dry-run` 不写入磁盘，只展示模板、源目录、目标目录、package name 和输出文件。
-
-`--json` 输出同一份创建计划的结构化数据，隐含 `--dry-run`。
-
-`--out <file>` 可以把文本或 JSON 预览写入文件，也隐含 `--dry-run`。
+`--dry-run` does not write files. It shows the template, source directory, target directory, package name, and output files.
 
-## 固化默认模板
+`--json` emits the same plan as structured data and implies `--dry-run`.
 
-```ts
-import { defineMonorepoConfig } from 'repoctl'
+`--out <file>` persists the preview and also implies `--dry-run`.
 
-export default defineMonorepoConfig({
-  commands: {
-    create: {
-      defaultTemplate: 'tsdown',
-    },
-  },
-})
-```
-
-之后：
-
-```bash
-repo new utils
-```
-
-会直接创建 `tsdown` 库包。
-
-## 检查模板健康状态
+## Check Template Health
 
 ```bash
 repo templates --check
 repo templates --check --json
 ```
 
-模板检查会确认：
-
-- 模板 source 和 target 没有重复。
-- 每个模板 source 目录都存在。
-- 每个模板根目录都有 `package.json`。
-- 每个模板都有 category 和 description。
-- 模板源目录里没有会被脚手架过滤掉的临时或生成文件。
+The check validates duplicate sources and targets, existing source directories, package metadata, categories, descriptions, and temporary files that would be filtered by the scaffolder.
 
-## 继续阅读
+## Keep Reading
 
-- [接入已有仓库](./adopt-existing.md)
-- [工作流与 CI](./workflows.md)
-- [配置文件](./config.md)
-- [模板资产治理](./template-assets.md)
+- [Adopt Existing Repositories](./adopt-existing.md)
+- [Workflows and CI](./workflows.md)
+- [Configuration](./config.md)

package/templates/vitepress/repoctl/troubleshooting.md

@@ -1,34 +1,34 @@
-# 排障与报告
+# Troubleshooting
 
-repoctl 的排障重点不是让你猜错在哪里，而是尽量输出可以复现、可以保存、可以发给同事的报告。
+repoctl focuses on reports that can be reproduced, saved, and shared.
 
-## 先跑 doctor
+## Start With Doctor
 
 ```bash
 repo doctor
 repo doctor --strict
 ```
 
-`doctor` 主要检查：
+`doctor` checks:
 
-- 当前目录是不是仓库根目录。
-- Node 版本是否满足要求。
-- `pnpm-workspace.yaml` 是否存在。
-- `repoctl` 是否作为 CLI 依赖安装。
-- 根脚本是否齐全。
-- 是否仍残留已废弃的 `monorepo.config.ts`。
-- Husky 与 lint-staged 是否都接上。
+- Current directory and repository root.
+- Node.js version.
+- `pnpm-workspace.yaml`.
+- The `repoctl` CLI dependency.
+- Recommended root scripts.
+- Conflicting config files.
+- Husky and lint-staged wiring.
 
-## 保存诊断报告
+## Save A Diagnostic Report
 
 ```bash
 repo doctor --json --out reports/doctor.json
 repo doctor --markdown --redact --out reports/doctor.md
 ```
 
-推荐把 Markdown 报告贴到 issue 或 PR。`--redact` 会脱敏本机路径。
+Markdown reports are useful in issues and PRs. `--redact` removes local absolute paths.
 
-## 查看校验计划
+## Inspect The Verification Plan
 
 ```bash
 repo check --dry-run
@@ -36,9 +36,9 @@ repo check --json --out reports/check-plan.json
 repo check --markdown --redact --out reports/check-plan.md
 ```
 
-当你不确定为什么某个文件触发了 workspace typecheck、pre-push 要跑哪些任务时，先看 check plan。
+Use this when you need to understand why a file triggers a workspace typecheck or which tasks pre-push would run.
 
-## 收集环境信息
+## Collect Environment Information
 
 ```bash
 repo env info
@@ -47,51 +47,41 @@ repo env snapshot --json --out reports/snapshot.json
 repo env paths --markdown --redact --out reports/paths.md
 ```
 
-这些命令适合排查 Node、pnpm、workspace、Git、路径和 CI 环境差异。
+These commands help compare local, CI, Git, Node, pnpm, and workspace differences.
 
-## 先判断问题类型
+## Common Fixes
 
-| 现象                           | 优先命令                                  | 继续阅读                             |
-| ------------------------------ | ----------------------------------------- | ------------------------------------ |
-| 不确定当前目录是不是仓库根目录 | `repo doctor`                             | [doctor 诊断](./doctor.md)           |
-| 不知道 `repo check` 会跑什么   | `repo check --dry-run`                    | [校验链路](./checks.md)              |
-| CI 失败但日志不完整            | `repo env support --markdown --redact`    | [报告与自动化输出](./reports.md)     |
-| 模板创建结果不符合预期         | `repo new <name> --template <key> --json` | [模板资产治理](./template-assets.md) |
-| 模板列表或元数据异常           | `repo templates --check`                  | [模板资产治理](./template-assets.md) |
+### Not At Repository Root
 
-## 常见问题
-
-### 当前目录不是仓库根目录
-
-切回包含 `pnpm-workspace.yaml` 和根 `package.json` 的目录，再运行：
+Change into the directory that contains `pnpm-workspace.yaml` and the root `package.json`, then run:
 
 ```bash
 repo doctor
 ```
 
-### 同时存在两个配置文件
+### Conflicting Config Files
 
-只保留一个：
+Keep only:
 
 ```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`.
 
-### `repo new` 提示模板不存在
+### Unknown Template Key
 
-先查看可用模板：
+List available templates:
 
 ```bash
 repo templates
 ```
 
-显式传入的 `--template` 会先校验。拼错时命令会失败并提示相近 key，不会静默回退。
+Explicit `--template` values are validated first. Invalid keys fail with suggestions.
 
-### 自动化里不希望出现交互
+### Automation Should Not Prompt
 
-使用非交互参数：
+Use non-interactive options:
 
 ```bash
 repo init --yes
@@ -99,12 +89,8 @@ repo upgrade --no-overwrite
 repo check --json --out reports/check-plan.json
 ```
 
-非 TTY 环境下，repoctl 不会弹出交互选择框。
-
-## 继续阅读
+## Keep Reading
 
-- [工作流与 CI](./workflows.md)
-- [命令速查](./commands.md)
-- [doctor 诊断](./doctor.md)
-- [报告与自动化输出](./reports.md)
-- [命令别名](./aliases.md)
+- [Workflows and CI](./workflows.md)
+- [Command Reference](./commands.md)
+- [Command Aliases](./aliases.md)