@icebreakers/monorepo-templates 1.0.3 → 1.0.5

package/templates/vitepress/repoctl/reports.md

@@ -0,0 +1,94 @@
+---
+description: 说明 repoctl 的 JSON、Markdown、out、redact、env info、env snapshot 和 env support 报告能力。
+---
+
+# 报告与自动化输出
+
+repoctl 的报告能力用于把本地上下文变成可保存、可脱敏、可给脚本读取的文件。它适合 CI artifact、issue 模板、编辑器集成和跨机器排障。
+
+## 1. 通用输出参数
+
+| 参数           | 支持命令示例                            | 作用                           |
+| -------------- | --------------------------------------- | ------------------------------ |
+| `--json`       | `doctor`、`check`、`templates`、`env`   | 输出结构化数据                 |
+| `--markdown`   | `doctor`、`check`、`templates`、`env`   | 输出便于阅读和粘贴的报告       |
+| `--out <file>` | 多数报告命令                            | 把输出写入文件                 |
+| `--redact`     | `doctor`、`check`、`env`                | 脱敏本机路径                   |
+| `--strict`     | `doctor`、`env snapshot`、`env support` | 有 fail 或 warn 时返回失败状态 |
+
+## 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 示例
+
+```bash
+repo doctor --json --out reports/doctor.json
+repo check --full --json --out reports/check-plan.json
+repo env support --markdown --redact --out reports/support.md
+```
+
+建议把 `reports/` 上传为 artifact。这样 CI 失败时，不需要重新询问维护者使用了什么 Node、pnpm、workspace 根目录和校验计划。
+
+## 4. issue 排障模板
+
+当你需要把问题交给同事或维护者时，可以先生成 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 适合机器判断，不适合人工长时间阅读：
+
+```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
+```
+
+常见消费方式：
+
+| 目标                | 使用方式                             |
+| ------------------- | ------------------------------------ |
+| 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
+```
+
+如果报告要离开本机，默认加 `--redact`。

package/templates/vitepress/repoctl/scenarios.md

@@ -6,14 +6,14 @@
 
 ```bash
 pnpm install
-pnpm doctor
+pnpm run repo:doctor
 ```
 
-如果 `pnpm doctor` 不存在：
+如果 `repo:*` 根脚本还不存在：
 
 ```bash
 pnpm add -D repoctl
-pnpm exec repo setup --yes
+pnpm exec repo init --yes
 pnpm exec repo doctor
 ```
 
@@ -23,7 +23,7 @@ pnpm exec repo doctor
 
 ```bash
 pnpm add -D repoctl
-pnpm exec repo setup --yes
+pnpm exec repo init --yes
 pnpm exec repo doctor --markdown --redact --out reports/doctor-before.md
 pnpm exec repo upgrade --no-overwrite
 pnpm exec repo doctor --markdown --redact --out reports/doctor-after.md
@@ -42,7 +42,7 @@ pnpm exec repo new docs --template vitepress --dry-run
 如果只是日常开发，根脚本也可以：
 
 ```bash
-pnpm new sdk --template tsdown
+pnpm run repo:new -- sdk --template tsdown
 ```
 
 继续看：[模板与创建](./templates.md)。
@@ -50,7 +50,7 @@ pnpm new sdk --template tsdown
 ## 我要提交前自查
 
 ```bash
-pnpm check
+pnpm run repo:check
 pnpm exec repo check --dry-run
 pnpm exec repo check --full
 ```

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

@@ -0,0 +1,9 @@
+---
+description: llms.txt 说明页已移动到独立的 AI 文档栏目。
+---
+
+# llms.txt 已移动
+
+llms.txt 现在放在独立的 AI 文档栏目中维护。
+
+请阅读：[AI 文档入口：llms.txt](../ai/llms-txt.md)。

package/templates/vitepress/why/examples/2.npm-basic-package/README.md

@@ -1 +1 @@
-https://monorepo.icebreaker.top/
+https://repo.icebreaker.top/

package/templates/vitepress/why/examples/3.npm-basic-package/README.md

@@ -1 +1 @@
-https://monorepo.icebreaker.top/
+https://repo.icebreaker.top/

package/templates/vitepress/wrangler.jsonc

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://unpkg.com/wrangler/config-schema.json",
+  "name": "monorepo-template",
+  "pages_build_output_dir": ".vitepress/dist"
+}

package/templates/vue-lib/package.json

@@ -53,7 +53,7 @@
     "@vue/test-utils": "^2.4.10",
     "@vue/tsconfig": "^0.9.1",
     "jsdom": "^29.1.1",
-    "vite": "^8.0.10",
+    "vite": "^8.0.11",
     "vite-plugin-dts": "^5.0.0",
     "vue": "^3.5.34",
     "vue-tsc": "^3.2.8"