@icebreakers/monorepo-templates 1.0.4 → 1.0.5

package/templates/vitepress/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
+```
+
+如果模板文件数量发生变化，维护模板快照的测试也需要同步更新。

package/templates/vitepress/repoctl/templates.md

@@ -2,6 +2,8 @@
 
 repoctl 的模板由 `@icebreakers/monorepo-templates` 维护。CLI、脚手架和文档都复用同一份模板元数据。
 
+更偏维护者视角的模板元数据、健康检查和自定义模板说明见：[模板资产治理](./template-assets.md)。
+
 ## 内置模板
 
 | Key           | Category | 默认目录           | 适合场景                    |
@@ -154,3 +156,4 @@ repo templates --check --json
 - [接入已有仓库](./adopt-existing.md)
 - [工作流与 CI](./workflows.md)
 - [配置文件](./config.md)
+- [模板资产治理](./template-assets.md)

package/templates/vitepress/repoctl/troubleshooting.md

@@ -16,7 +16,7 @@ repo doctor --strict
 - `pnpm-workspace.yaml` 是否存在。
 - `repoctl` 是否作为 CLI 依赖安装。
 - 根脚本是否齐全。
-- `repoctl.config.ts` 和 `monorepo.config.ts` 是否冲突。
+- 是否仍残留已废弃的 `monorepo.config.ts`。
 - Husky 与 lint-staged 是否都接上。
 
 ## 保存诊断报告
@@ -49,6 +49,16 @@ repo env paths --markdown --redact --out reports/paths.md
 
 这些命令适合排查 Node、pnpm、workspace、Git、路径和 CI 环境差异。
 
+## 先判断问题类型
+
+| 现象                           | 优先命令                                  | 继续阅读                             |
+| ------------------------------ | ----------------------------------------- | ------------------------------------ |
+| 不确定当前目录是不是仓库根目录 | `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) |
+
 ## 常见问题
 
 ### 当前目录不是仓库根目录
@@ -67,7 +77,7 @@ repo doctor
 repoctl.config.ts
 ```
 
-`monorepo.config.ts` 是兼容旧项目的文件名，新项目不建议继续使用。
+`monorepo.config.ts` 已不再加载。旧项目需要改名为 `repoctl.config.ts`。
 
 ### `repo new` 提示模板不存在
 
@@ -84,7 +94,7 @@ repo templates
 使用非交互参数：
 
 ```bash
-repo setup --yes
+repo init --yes
 repo upgrade --no-overwrite
 repo check --json --out reports/check-plan.json
 ```
@@ -95,4 +105,6 @@ repo check --json --out reports/check-plan.json
 
 - [工作流与 CI](./workflows.md)
 - [命令速查](./commands.md)
+- [doctor 诊断](./doctor.md)
+- [报告与自动化输出](./reports.md)
 - [命令别名](./aliases.md)

package/templates/vitepress/repoctl/workflows.md

@@ -6,27 +6,27 @@ repoctl 的命令可以分成两类：给人用的日常入口，以及给 CI、
 
 ```bash
 pnpm install
-pnpm doctor
-pnpm new sdk --template tsdown
-pnpm check
+pnpm run repo:doctor
+pnpm run repo:new -- sdk --template tsdown
+pnpm run repo:check
 pnpm build
 ```
 
 这条链路适合新成员第一次进入仓库：
 
-| 步骤           | 判断标准                                         |
-| -------------- | ------------------------------------------------ |
-| `pnpm install` | workspace 依赖和本地链接完整                     |
-| `pnpm doctor`  | 仓库根目录、Node、脚本、配置和提交链路可用       |
-| `pnpm new`     | 新包由模板创建，目录和 package metadata 符合约定 |
-| `pnpm check`   | 提交前轻量校验可以复现                           |
-| `pnpm build`   | 全仓构建链路没有明显断点                         |
+| 步骤                   | 判断标准                                         |
+| ---------------------- | ------------------------------------------------ |
+| `pnpm install`         | workspace 依赖和本地链接完整                     |
+| `pnpm run repo:doctor` | 仓库根目录、Node、脚本、配置和提交链路可用       |
+| `pnpm run repo:new`    | 新包由模板创建，目录和 package metadata 符合约定 |
+| `pnpm run repo:check`  | 提交前轻量校验可以复现                           |
+| `pnpm build`           | 全仓构建链路没有明显断点                         |
 
 ## 存量仓库接入
 
 ```bash
 pnpm add -D repoctl
-pnpm exec repo setup --yes
+pnpm exec repo init --yes
 pnpm exec repo doctor --markdown --out reports/doctor.md
 pnpm exec repo upgrade --no-overwrite
 pnpm exec repo doctor
@@ -87,11 +87,23 @@ 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/`，方便失败时复盘实际执行路径。
+
 ## 非交互参数选择
 
 | 场景               | 推荐参数                                           |
 | ------------------ | -------------------------------------------------- |
-| 初始化时接受默认值 | `repo setup --yes`                                 |
+| 初始化时接受默认值 | `repo init --yes`                                  |
 | 同步时保留已有改动 | `repo upgrade --no-overwrite`                      |
 | 明确覆盖标准资产   | `repo upgrade --yes` 或 `repo upgrade --overwrite` |
 | 只看计划不执行     | `--dry-run`                                        |
@@ -101,5 +113,6 @@ repo ws ls --json --out reports/workspaces.json
 ## 下一步
 
 - 查所有参数：[命令速查](./commands.md)
-- 生成排障包：[排障与报告](./troubleshooting.md)
+- 理解校验链路：[校验链路](./checks.md)
+- 生成排障包：[报告与自动化输出](./reports.md)
 - 看短命令：[命令别名](./aliases.md)

package/templates/vitepress/tools/index.md

@@ -0,0 +1,38 @@
+---
+description: repoctl 文档站的工具专题入口，汇总 pnpm、Turborepo、changeset、Husky、lint-staged 和 Renovate。
+---
+
+# 工具专题
+
+工具专题只讲 repoctl 周边工具。repoctl 会把这些工具串成稳定工作流，但每个工具本身仍有独立的配置模型和维护边界。
+
+## 1. 工具地图
+
+| 工具        | 在 repoctl 工作流里的位置                       | 详细页面                        |
+| ----------- | ----------------------------------------------- | ------------------------------- |
+| pnpm        | workspace、依赖安装、根脚本和包内脚本执行       | [pnpm](./pnpm.md)               |
+| Turborepo   | build、lint、typecheck、test 等任务编排         | [turborepo](./turborepo.md)     |
+| changeset   | 多包版本、变更记录和发布准备                    | [changeset](./changeset.md)     |
+| Husky       | Git hook 入口                                   | [husky](./husky.md)             |
+| lint-staged | staged 文件级 lint、stylelint 和 typecheck 路由 | [lint-staged](./lint-staged.md) |
+| Renovate    | 依赖更新和升级 PR 治理                          | [renovate](./renovate.md)       |
+
+## 2. 和 repoctl 的关系
+
+repoctl 不隐藏这些工具。它主要做三件事：
+
+1. 生成推荐配置，减少每个仓库重复复制。
+2. 提供 `doctor` 和 `check`，帮助你验证配置是否接上。
+3. 提供 `upgrade`，在模板标准发生变化时同步资产。
+
+因此排障时不要只看 repoctl 命令。比如 `repo check --full` 失败时，真正失败的任务可能是 `pnpm lint`、`pnpm typecheck`、某个 workspace 的 `build` 或 `test`。
+
+## 3. 按目标阅读
+
+| 目标                      | 建议页面                                               |
+| ------------------------- | ------------------------------------------------------ |
+| 让 workspace 包能互相引用 | [pnpm](./pnpm.md)                                      |
+| 提升整仓任务速度          | [turborepo](./turborepo.md)                            |
+| 建立规范发版链路          | [changeset](./changeset.md)                            |
+| 提交前自动修复格式和 lint | [Husky](./husky.md) 与 [lint-staged](./lint-staged.md) |
+| 降低依赖升级成本          | [Renovate](./renovate.md)                              |

package/templates/vitepress/tools/llms-txt.md

@@ -1,29 +1,9 @@
 ---
-description: 使用 llms.txt 为大语言模型提供更易读取的 repoctl 文档入口。
+description: llms.txt 说明页已移动到独立的 AI 文档栏目。
 ---
 
-# AI 文档入口：llms.txt
+# llms.txt 已移动
 
-`llms.txt` 是面向大语言模型的文档入口文件。它把站点中的关键页面整理成更适合模型读取的 Markdown 索引，便于 AI 工具在回答 repoctl、pnpm workspace、Turborepo 和模板用法相关问题时快速定位上下文。
+llms.txt 现在放在独立的 AI 文档栏目中维护。
 
-本站通过 `vitepress-plugin-llms` 在构建阶段自动生成这些文件：
-
-- `/llms.txt`：文档索引，列出可供模型读取的页面。
-- `/llms-full.txt`：把站点文档合并成单个文本文件。
-- 每个页面对应的 `.md` 文件：保留页面内容的 Markdown 版本。
-
-## 使用方式
-
-访问 `https://repo.icebreaker.top/llms.txt` 可以获取当前文档的 LLM 索引。如果需要一次性提供完整上下文，可以使用 `https://repo.icebreaker.top/llms-full.txt`。
-
-当你在 Cursor、Claude Code、Codex 或其他 AI 编程工具里引用 repoctl 文档时，优先提供 `llms.txt`，再按需要补充具体页面链接。
-
-## 维护约定
-
-新增重要文档页面时，在 frontmatter 中补充 `description`。构建插件会把描述写入 `llms.txt` 的链接说明中，让模型更容易判断每个页面的用途。
-
-```md
----
-description: 说明这个页面解决的问题和适用场景。
----
-```
+请阅读：[AI 文档入口：llms.txt](../ai/llms-txt.md)。