@icebreakers/monorepo-templates 1.0.15 → 1.2.0

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)

package/templates/vitepress/repoctl/workflows.md

@@ -1,8 +1,8 @@
-# 工作流与 CI
+# Workflows and CI
 
-repoctl 的命令可以分成两类：给人用的日常入口，以及给 CI、脚本、编辑器用的可保存输出。
+repoctl commands have two audiences: humans using short daily commands, and automation consuming stable reports.
 
-## 本地日常工作流
+## Local Daily Workflow
 
 ```bash
 pnpm install
@@ -12,17 +12,15 @@ pnpm run repo:check
 pnpm build
 ```
 
-这条链路适合新成员第一次进入仓库：
+| Step                   | What It Proves                                          |
+| ---------------------- | ------------------------------------------------------- |
+| `pnpm install`         | Workspace dependencies and local links are ready        |
+| `pnpm run repo:doctor` | Root files, Node, scripts, config, and hooks are usable |
+| `pnpm run repo:new`    | New packages follow template conventions                |
+| `pnpm run repo:check`  | The lightweight local verification flow is reproducible |
+| `pnpm build`           | The workspace build graph has no obvious breakage       |
 
-| 步骤                   | 判断标准                                         |
-| ---------------------- | ------------------------------------------------ |
-| `pnpm install`         | workspace 依赖和本地链接完整                     |
-| `pnpm run repo:doctor` | 仓库根目录、Node、脚本、配置和提交链路可用       |
-| `pnpm run repo:new`    | 新包由模板创建，目录和 package metadata 符合约定 |
-| `pnpm run repo:check`  | 提交前轻量校验可以复现                           |
-| `pnpm build`           | 全仓构建链路没有明显断点                         |
-
-## 存量仓库接入
+## Adopt An Existing Repository
 
 ```bash
 pnpm add -D repoctl
@@ -32,9 +30,9 @@ pnpm exec repo upgrade --no-overwrite
 pnpm exec repo doctor
 ```
 
-推荐先用 `--no-overwrite` 保守接入。确认标准资产差异后，再决定是否使用 `--yes` 或 `--overwrite`。
+Start conservatively with `--no-overwrite`. After reviewing asset drift, decide whether `--yes` or `--overwrite` is appropriate.
 
-## CI 快速门禁
+## Fast CI Gate
 
 ```bash
 pnpm install --frozen-lockfile
@@ -42,9 +40,9 @@ pnpm exec repo doctor --strict
 pnpm exec repo check --full
 ```
 
-适合小仓库或早期项目。`doctor --strict` 会把 warning 也当成失败，能避免配置漂移慢慢积累。
+This is a simple gate for small repositories or early projects. `doctor --strict` treats warnings as failures.
 
-## CI 报告模式
+## CI Report Mode
 
 ```bash
 pnpm exec repo doctor --json --out reports/doctor.json
@@ -52,15 +50,13 @@ pnpm exec repo check --json --out reports/check-plan.json
 pnpm exec repo env support --markdown --redact --out reports/support.md
 ```
 
-这组命令适合想保存构建上下文的 CI：
-
-- `doctor.json` 给脚本判断仓库健康状态。
-- `check-plan.json` 记录本次会跑哪些校验。
-- `support.md` 适合上传为 artifact，或贴进 issue / PR。
+Use these outputs as CI artifacts:
 
-## pre-commit 与 pre-push
+- `doctor.json` for scripts.
+- `check-plan.json` to explain verification routing.
+- `support.md` for issues, PRs, and external collaboration.
 
-repoctl 暴露了底层 verify 命令，方便 hook 和脚本复用：
+## Hooks
 
 ```bash
 repo verify pre-commit
@@ -69,50 +65,25 @@ repo verify commit-msg .git/COMMIT_EDITMSG
 repo verify pre-push
 ```
 
-默认建议：
-
-| 阶段       | 推荐行为                                                |
-| ---------- | ------------------------------------------------------- |
-| pre-commit | 聚焦 staged 文件，运行格式、lint 和 workspace typecheck |
-| commit-msg | 校验 Conventional Commit 格式                           |
-| pre-push   | 跑整仓 lint/typecheck，并按变更范围补 build/test/tsd    |
-
-## 自动化创建预览
-
-```bash
-repo new dashboard --template vue-hono --json --out plans/dashboard.json
-repo templates --markdown --out docs/templates.md
-repo ws ls --json --out reports/workspaces.json
-```
-
-这些命令都不会要求人工选择，适合编辑器插件、脚本和 CI bot。
-
-## 推荐流水线拆分
-
-| 阶段 | 命令                                                            | 失败后先看                           |
-| ---- | --------------------------------------------------------------- | ------------------------------------ |
-| 安装 | `pnpm install --frozen-lockfile`                                | lockfile、Node、pnpm 版本            |
-| 诊断 | `repo doctor --strict`                                          | [doctor 诊断](./doctor.md)           |
-| 计划 | `repo check --full --json --out reports/check-plan.json`        | [报告与自动化输出](./reports.md)     |
-| 执行 | `repo check --full`                                             | 失败的 root script 或 workspace 任务 |
-| 留证 | `repo env support --markdown --redact --out reports/support.md` | CI artifact                          |
-
-早期项目可以把计划和执行合并。成熟项目建议保留 `reports/`，方便失败时复盘实际执行路径。
+| Stage      | Recommended Behavior                                      |
+| ---------- | --------------------------------------------------------- |
+| pre-commit | Focus on staged files, lint, and workspace typecheck      |
+| commit-msg | Enforce Conventional Commit messages                      |
+| pre-push   | Run root lint/typecheck and affected build/test/tsd tasks |
 
-## 非交互参数选择
+## Non-Interactive Options
 
-| 场景               | 推荐参数                                           |
-| ------------------ | -------------------------------------------------- |
-| 初始化时接受默认值 | `repo init --yes`                                  |
-| 同步时保留已有改动 | `repo upgrade --no-overwrite`                      |
-| 明确覆盖标准资产   | `repo upgrade --yes` 或 `repo upgrade --overwrite` |
-| 只看计划不执行     | `--dry-run`                                        |
-| 输出给脚本         | `--json --out <file>`                              |
-| 输出给人看并脱敏   | `--markdown --redact --out <file>`                 |
+| Scenario                              | Option                                             |
+| ------------------------------------- | -------------------------------------------------- |
+| Accept setup defaults                 | `repo init --yes`                                  |
+| Preserve changed files during upgrade | `repo upgrade --no-overwrite`                      |
+| Explicitly overwrite standard assets  | `repo upgrade --yes` or `repo upgrade --overwrite` |
+| Preview only                          | `--dry-run`                                        |
+| Output for scripts                    | `--json --out <file>`                              |
+| Share a redacted report               | `--markdown --redact --out <file>`                 |
 
-## 下一步
+## Keep Reading
 
-- 查所有参数：[命令速查](./commands.md)
-- 理解校验链路：[校验链路](./checks.md)
-- 生成排障包：[报告与自动化输出](./reports.md)
-- 看短命令：[命令别名](./aliases.md)
+- [Command Reference](./commands.md)
+- [Troubleshooting](./troubleshooting.md)
+- [Command Aliases](./aliases.md)