@icebreakers/monorepo-templates 1.0.2 → 1.0.4

package/templates/vitepress/monorepo/templates.md

@@ -1,67 +1,21 @@
 # 模板速查
 
-内置模板由 `@icebreakers/monorepo-templates` 维护，CLI、脚手架和文档都复用同一份模板元数据。
+模板创建已经收敛到 repoctl 文档：
 
-## 模板列表
+- [repoctl 模板与创建](../repoctl/templates.md)
+- [repoctl 快速开始](../repoctl/getting-started.md)
 
-| Key           | Category | Source                | Default target     | Description                         |
-| ------------- | -------- | --------------------- | ------------------ | ----------------------------------- |
-| `tsdown`      | library  | `templates/tsdown`    | `packages/tsdown`  | 使用 tsdown 构建的 TypeScript 库包  |
-| `vue-lib`     | library  | `templates/vue-lib`   | `packages/vue-lib` | Vue 3 组件库模板，适合沉淀可复用 UI |
-| `vue-hono`    | app      | `templates/client`    | `apps/client`      | Vue 3 + Hono 的前后端一体应用模板   |
-| `hono-server` | service  | `templates/server`    | `apps/server`      | Hono API 服务模板                   |
-| `vitepress`   | docs     | `templates/vitepress` | `apps/website`     | VitePress 文档站模板                |
-| `cli`         | tool     | `templates/cli`       | `apps/cli`         | TypeScript 命令行工具模板           |
+## monorepo 知识点：模板为什么重要
 
-## 查看模板
+当仓库里存在多种产物时，模板能把重复选择前置成稳定默认值：
 
-```bash
-repo templates
-repo templates tsdown
-repo templates --category library
-```
+| 产物          | 常见目录                 | 关注点                         |
+| ------------- | ------------------------ | ------------------------------ |
+| TypeScript 库 | `packages/*`             | exports、types、构建和 tsd     |
+| Vue 组件库    | `packages/*`             | SFC、样式校验、类型声明        |
+| 应用          | `apps/*`                 | dev、build、部署资产           |
+| 服务          | `apps/*`                 | API 入口、运行时类型、环境变量 |
+| 文档站        | `apps/*`                 | VitePress 配置、导航、内容结构 |
+| CLI           | `apps/*` 或 `packages/*` | bin 入口、参数解析、发布       |
 
-需要给脚本读取时：
-
-```bash
-repo templates --json
-repo templates tsdown --json
-```
-
-需要同步文档片段时：
-
-```bash
-repo templates --markdown
-repo templates tsdown --markdown
-repo templates --markdown --out docs/templates.md
-```
-
-## 创建前预览
-
-```bash
-repo new sdk --template tsdown --dry-run
-repo new website --template vitepress --dry-run
-repo new website --template vitepress --json
-repo new website --template vitepress --json --out plans/website.json
-```
-
-`--dry-run` 不写入磁盘，只展示模板、源目录、目标目录、package name 和输出的 package json 文件。
-`--json` 输出同一份创建计划的结构化数据，隐含 `--dry-run`，适合 CI、编辑器和自动化脚本。
-`--out <file>` 可以把文本或 JSON 预览写入文件，也隐含 `--dry-run`。
-
-显式传入的 `--template` 会先校验。模板 key 拼错时，命令会失败并提示相近 key，而不是静默回退到默认模板。
-
-## 健康检查
-
-```bash
-repo templates --check
-repo templates --check --json
-```
-
-模板健康检查会确认：
-
-- 模板 source / target 没有重复。
-- 每个模板 source 目录都存在。
-- 每个模板根目录都有 `package.json`。
-- 每个模板都有 category 和 description。
-- 模板源目录里没有会被脚手架过滤掉的临时或生成文件。
+repoctl 的 `repo templates` 和 `repo new` 负责把这些约定落实到文件系统。

package/templates/vitepress/monorepo/troubleshooting.md

@@ -1,226 +1,20 @@
-# 排障指南
+# 常见问题排障
 
-这一页不讲原理，直接讲最常见的问题和对应动作。
+repoctl 排障文档已经集中到：
 
-## 第一反应：先跑 `repo doctor`
+- [repoctl 排障与报告](../repoctl/troubleshooting.md)
+- [repoctl 命令速查](../repoctl/commands.md)
 
-如果你不确定问题在哪，先执行：
+## monorepo 知识点：先区分问题类型
 
-```bash
-pnpm doctor
-```
+排障前先判断问题属于哪一类：
 
-需要把诊断结果交给 CI、编辑器或机器人时：
+| 类型           | 先看什么                              | 常用命令                                |
+| -------------- | ------------------------------------- | --------------------------------------- |
+| 仓库结构问题   | 根目录、workspace 文件、Node 版本     | `repo doctor`                           |
+| 模板创建问题   | 模板 key、目标目录、创建计划          | `repo templates` / `repo new --dry-run` |
+| 提交前校验问题 | staged 文件、workspace 归属、任务路由 | `repo check --dry-run`                  |
+| 环境差异问题   | Node、pnpm、Git、CI、路径             | `repo env support --markdown --redact`  |
+| 配置冲突问题   | `repoctl.config.ts` 与旧配置文件      | `repo config inspect`                   |
 
-```bash
-pnpm exec repo doctor --json --out reports/doctor.json
-pnpm exec repo doctor --markdown --redact --out reports/doctor.md
-```
-
-需要让 CI 对 warning 也失败时：
-
-```bash
-pnpm exec repo doctor --strict --json --out reports/doctor.json
-pnpm exec repo doctor --strict --markdown --redact --out reports/doctor.md
-```
-
-需要把运行环境一起发给同事、CI 或机器人时：
-
-```bash
-pnpm exec repo env paths --json --out reports/paths.json
-pnpm exec repo env paths --markdown --redact --out reports/paths.md
-pnpm exec repo config inspect --json --out reports/config.json
-pnpm exec repo config inspect --markdown --redact --out reports/config.md
-pnpm exec repo env info --json --out reports/env.json
-pnpm exec repo env info --markdown --redact --out reports/env.md
-pnpm exec repo env snapshot --json --out reports/snapshot.json
-pnpm exec repo env snapshot --markdown --redact --out reports/snapshot.md
-pnpm exec repo env snapshot --markdown --redact --strict --out reports/snapshot.md
-pnpm exec repo env support --json --out reports/support.json
-pnpm exec repo env support --markdown --redact --out reports/support.md
-pnpm exec repo env support --markdown --redact --strict --out reports/support.md
-```
-
-`env paths` 会列出 repoctl / monorepo 配置文件的全部候选扩展名，不只检查 `.ts` 文件。
-如果要把环境报告发给外部协作者，优先加 `--redact` 脱敏本机绝对路径；如果是贴到 issue 或 PR 评论里，用 `--markdown` 生成摘要。
-在 CI 中可以再加 `--strict`，这样会先写出排障包，再在 `doctor` 有 fail 或 warn 时返回失败码。
-
-它会优先帮你排这些低成本但高频的问题：
-
-- 当前目录不是仓库根目录
-- 缺少 `pnpm-workspace.yaml`
-- Node 版本不满足要求
-- 根 `package.json` 没装 `repoctl` / `@icebreakers/monorepo`
-- 根快捷脚本没同步齐
-- `repoctl.config.ts` 与 `monorepo.config.ts` 同时存在
-- `.husky/pre-commit` 和 `lint-staged.config.js` 只配了一半
-
-## 常见问题
-
-### 1. 提示当前目录不像 monorepo 根目录
-
-通常是因为你在子包目录里执行了命令，或者根目录缺少这些文件：
-
-```txt
-package.json
-pnpm-workspace.yaml
-```
-
-先回到根目录再执行。
-
-如果要确认 CLI 实际识别到了哪些 workspace 包，可以输出一份列表：
-
-```bash
-pnpm exec repo ws ls --json --out reports/workspaces.json
-pnpm exec repo ws ls --markdown --redact --out reports/workspaces.md
-```
-
-### 2. Node 版本不满足要求
-
-看根 `package.json`：
-
-```json
-{
-  "engines": {
-    "node": ">=20.0.0"
-  }
-}
-```
-
-切到满足要求的 Node 版本后，再跑：
-
-```bash
-pnpm install
-pnpm doctor
-```
-
-### 3. `repoctl.config.ts` 和 `monorepo.config.ts` 同时存在
-
-这是明确的冲突状态，不是“都能读”。
-
-处理方式：
-
-- 保留 `repoctl.config.ts`
-- 删除 `monorepo.config.ts`
-
-除非你在迁移历史仓库，否则没有必要双持。
-
-### 4. 根脚本没有 `setup` / `new` / `check` / `doctor`
-
-先同步一次标准资产：
-
-```bash
-pnpm exec repo upgrade
-```
-
-CI 或非 TTY 环境使用：
-
-```bash
-pnpm exec repo setup --yes
-```
-
-### 5. `repo new --template` 提示未知模板
-
-先运行：
-
-```bash
-pnpm exec repo templates
-```
-
-确认模板 key。`--template` 是严格校验的，拼写错误会直接失败；如果能判断出相近 key，CLI 会额外提示 `did you mean ...`。
-
-如果你只是不想等，也可以手动把这些脚本加回根 `package.json`。
-
-### 5. 提交前校验没有正常工作
-
-先检查这两个文件是不是同时存在：
-
-```txt
-.husky/pre-commit
-lint-staged.config.js
-```
-
-只存在一个，通常就是半残状态。
-
-可选动作：
-
-```bash
-pnpm exec repo upgrade
-pnpm check
-```
-
-### 6. ESLint / Vitest 配置引用 `tooling/load-tooling-module.mjs`
-
-这是旧模板生成的本仓库源码 loader。普通使用者仓库应该直接 import `repoctl/tooling`。
-
-处理方式：
-
-```bash
-pnpm exec repo upgrade --yes
-pnpm doctor
-```
-
-如果自动化里必须保留本地修改，用 `pnpm exec repo upgrade --no-overwrite` 查看 skipped 文件，再手动迁移。
-
-### 7. `repo` 命令不可用
-
-通常是依赖还没安装，或者当前仓库没把 CLI 包放进根依赖。
-
-先执行：
-
-```bash
-pnpm install
-pnpm doctor
-```
-
-如果根本没有安装 CLI 依赖，补一个即可：
-
-```bash
-pnpm add -D repoctl
-```
-
-## `doctor` 和 `check` 的区别
-
-很多人遇到问题会这两个命令来回试，其实职责不同：
-
-| 命令     | 更像什么   |
-| -------- | ---------- |
-| `doctor` | 仓库体检   |
-| `check`  | 提交前校验 |
-
-如果你怀疑是“仓库架子不完整”，先用 `doctor`。
-如果你怀疑是“这次改动过不了 lint / typecheck / test”，先用 `check`。
-
-## 什么时候需要 `upgrade`
-
-下面这些情况，优先考虑 `repo upgrade`：
-
-- 文档里的根脚本在你仓库里没有
-- 默认的 Husky / lint-staged / config 资产缺失
-- 模板最近更新过，而你的仓库还是旧结构
-- 你希望重新同步推荐默认值
-
-## 一个实用排查顺序
-
-大多数问题按这个顺序处理最省时间：
-
-```bash
-pnpm install
-pnpm doctor
-pnpm exec repo upgrade
-pnpm doctor
-pnpm check
-pnpm build
-```
-
-思路是：
-
-1. 先把依赖装齐
-2. 先修仓库架子问题
-3. 再看当前改动的校验问题
-
-## 还有问题时看哪里
-
-- 日常命令边界不清楚：[命令速查](./commands.md)
-- 不确定仓库怎么管理：[如何管理 monorepo](./manage.md)
-- 发包问题：[发包与变更日志](./publish.md)
+旧页面继续保留为知识点索引，具体排查步骤以后优先维护在 repoctl 分区。

package/templates/vitepress/package.json

@@ -2,9 +2,9 @@
   "name": "@icebreakers/website",
   "type": "module",
   "version": "0.0.0",
-  "description": "https://monorepo.icebreaker.top source code",
+  "description": "https://repo.icebreaker.top source code",
   "author": "ice breaker <hi@sonofmagic.top>",
-  "homepage": "https://monorepo.icebreaker.top",
+  "homepage": "https://repo.icebreaker.top",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/sonofmagic/monorepo-template.git",
@@ -35,6 +35,7 @@
     "mermaid": "^11.14.0",
     "tailwindcss": "^4.2.4",
     "vitepress": "^1.6.4",
+    "vitepress-plugin-llms": "^1.12.2",
     "vitepress-plugin-mermaid": "^2.0.17"
   }
 }

package/templates/vitepress/repoctl/adopt-existing.md

@@ -0,0 +1,135 @@
+# 接入已有仓库
+
+repoctl 不只适合新模板仓库。它也可以渐进接入已有 pnpm workspace，用诊断报告和非覆盖同步把风险降下来。
+
+## 适合接入的仓库
+
+优先满足这些条件：
+
+- 已经使用 pnpm 或准备迁移到 pnpm。
+- 有根 `package.json`。
+- 能接受 `apps/*`、`packages/*`、`examples/*` 这类 workspace 目录约定。
+- 希望统一 `setup`、`doctor`、`new`、`check` 这类日常入口。
+
+如果仓库还不是 pnpm workspace，先补最小 `pnpm-workspace.yaml`：
+
+```yaml
+packages:
+  - apps/*
+  - packages/*
+```
+
+## 第一步：安装并初始化
+
+```bash
+pnpm add -D repoctl
+pnpm exec repo setup --yes
+```
+
+`setup --yes` 会使用安全默认值。它会补齐推荐脚本和 workspace patterns，但不会无条件覆盖已有 README、package.json、pnpm-workspace.yaml 或 tooling 配置。
+
+## 第二步：保存第一次诊断
+
+```bash
+pnpm exec repo doctor --markdown --redact --out reports/doctor-before.md
+pnpm exec repo doctor --json --out reports/doctor-before.json
+```
+
+建议把第一次报告提交到 PR 评论或 artifact，而不是只看终端输出。
+
+重点看这些项：
+
+| 检查项                       | 常见问题                                             |
+| ---------------------------- | ---------------------------------------------------- |
+| `package-json`               | 当前目录不是仓库根目录                               |
+| `workspace-manifest`         | 缺少 `pnpm-workspace.yaml`                           |
+| `node-version`               | 根 package 没声明 `engines.node` 或版本不匹配        |
+| `tool-package`               | 没安装 `repoctl`                                     |
+| `root-scripts`               | 缺少 `setup/new/check/doctor`                        |
+| `config-file`                | `repoctl.config.ts` 和 `monorepo.config.ts` 同时存在 |
+| `commit-hooks`               | Husky 和 lint-staged 只接了一半                      |
+| `workspace-package-coverage` | package.json 没被 workspace patterns 覆盖            |
+
+## 第三步：保守同步标准资产
+
+```bash
+pnpm exec repo upgrade --no-overwrite
+pnpm exec repo doctor --markdown --redact --out reports/doctor-after.md
+```
+
+`--no-overwrite` 适合第一次接入：它同步缺失资产，但保留已有 drifted 文件。你可以在 PR diff 里逐项看哪些配置要进一步迁移。
+
+## 第四步：预览校验计划
+
+```bash
+pnpm exec repo check --dry-run
+pnpm exec repo check --json --out reports/check-plan.json
+pnpm exec repo check --markdown --redact --out reports/check-plan.md
+```
+
+先看 plan，再决定要不要接入 hook 或 CI。
+
+## 第五步：接入根脚本
+
+如果 `setup` 已补齐根脚本，团队日常文档就可以改成：
+
+```bash
+pnpm doctor
+pnpm new
+pnpm check
+```
+
+CI 和自动化脚本仍建议写完整 CLI：
+
+```bash
+pnpm exec repo doctor --strict
+pnpm exec repo check --full
+```
+
+## 第六步：处理遗留配置
+
+### 配置文件冲突
+
+只保留：
+
+```txt
+repoctl.config.ts
+```
+
+`monorepo.config.ts` 只是兼容旧项目。
+
+### 本地 tooling loader
+
+如果 `doctor` 提示 tooling 配置引用了本地源码 loader，使用：
+
+```bash
+pnpm exec repo upgrade --yes
+```
+
+这个命令会迁移到 `repoctl/tooling` 入口。
+
+### workspace patterns 不覆盖包
+
+运行：
+
+```bash
+pnpm exec repo setup --yes
+```
+
+或手动扩展 `pnpm-workspace.yaml`。
+
+## 推荐 PR 结构
+
+存量仓库接入建议拆成小 PR：
+
+1. 安装 `repoctl`，补 `setup/doctor/new/check` 根脚本。
+2. 提交 `doctor-before` 和 `doctor-after` 报告。
+3. 同步或迁移 tooling 配置。
+4. 接入 hook 和 CI。
+5. 用 `repo new --dry-run` 验证模板创建路径。
+
+## 下一步
+
+- [工作流与 CI](./workflows.md)
+- [排障与报告](./troubleshooting.md)
+- [配置文件](./config.md)

package/templates/vitepress/repoctl/aliases.md

@@ -0,0 +1,71 @@
+# 命令别名
+
+repoctl 保留了一组短别名，方便熟悉后在终端里少打字。团队文档仍建议优先写完整命令，减少新人理解成本。
+
+## 包入口别名
+
+`repoctl` 包提供多个 bin：
+
+```bash
+repo
+repoctl
+monorepo
+rc
+mo
+```
+
+文档统一推荐 `repo`。
+
+兼容入口仍然可用：
+
+```bash
+repoctl doctor
+monorepo doctor
+rc doctor
+mo doctor
+```
+
+## 顶层命令别名
+
+| 推荐写法         | 兼容或短写  | 说明             |
+| ---------------- | ----------- | ---------------- |
+| `repo setup`     | `repo init` | 初始化仓库默认值 |
+| `repo upgrade`   | `repo sync` | 同步模板标准资产 |
+| `repo templates` | `repo tpl`  | 查看或检查模板   |
+
+## 分组命令别名
+
+| 完整命令                       | 短写            |
+| ------------------------------ | --------------- |
+| `repo workspace`               | `repo ws`       |
+| `repo workspace upgrade`       | `repo ws up`    |
+| `repo workspace list`          | `repo ws ls`    |
+| `repo workspace clean`         | `repo ws rm`    |
+| `repo tooling`                 | `repo tg`       |
+| `repo tooling init`            | `repo tg i`     |
+| `repo package`                 | `repo pkg`      |
+| `repo package create`          | `repo pkg new`  |
+| `repo verify`                  | `repo v`        |
+| `repo verify pre-push`         | `repo v push`   |
+| `repo verify pre-commit`       | `repo v commit` |
+| `repo verify commit-msg`       | `repo v msg`    |
+| `repo verify staged-typecheck` | `repo v tc`     |
+| `repo env`                     | `repo e`        |
+| `repo env info`                | `repo e i`      |
+| `repo env snapshot`            | `repo e s`      |
+| `repo env paths`               | `repo e p`      |
+| `repo env support`             | `repo e b`      |
+| `repo env mirror`              | `repo e m`      |
+| `repo config`                  | `repo cfg`      |
+| `repo config inspect`          | `repo cfg i`    |
+| `repo skills`                  | `repo sk`       |
+| `repo skills sync`             | `repo sk s`     |
+| `repo ai prompt`               | `repo ai p`     |
+| `repo ai prompt create`        | `repo ai p new` |
+
+## 推荐使用原则
+
+- 新手教程写完整命令，例如 `pnpm exec repo doctor`。
+- 团队 README 写根脚本，例如 `pnpm doctor`。
+- 维护者脚本可以写短别名，但要在注释或文档里说明用途。
+- CI 里优先写完整命令，方便日志搜索。

package/templates/vitepress/repoctl/commands.md

@@ -0,0 +1,154 @@
+# 命令速查
+
+这一页只保留 repoctl 高频、实用、容易记错的命令。
+
+## 最推荐入口
+
+```bash
+pnpm exec repo setup
+pnpm exec repo doctor
+pnpm exec repo templates
+pnpm exec repo new
+pnpm exec repo check
+```
+
+模板生成仓库里的短脚本：
+
+```bash
+pnpm setup
+pnpm doctor
+pnpm new
+pnpm check
+```
+
+## `repo setup`
+
+```bash
+repo setup
+repo setup --yes
+repo setup --preset minimal
+repo setup --preset standard --force
+repo setup --overwrite
+```
+
+用途：
+
+- 初始化当前 workspace 的推荐默认值。
+- 默认不覆盖已有 README、package.json、pnpm-workspace.yaml 和 tooling 配置。
+- 追加缺失的 `apps/*`、`packages/*`、`examples/*` workspace patterns。
+- `--yes` 用于 CI 或非 TTY 环境。
+- 需要重写受管理文件时显式传 `--force` 或 `--overwrite`。
+
+## `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
+```
+
+用途：
+
+- 诊断当前目录是不是可直接开始使用的 monorepo 根目录。
+- 检查 Node 版本、workspace 文件、CLI 依赖、根脚本、配置冲突和提交链路。
+- `--strict` 会把 warning 也视为失败，适合 CI 门禁。
+- `--json` 和 `--markdown` 适合自动化、PR、issue 和外部协作。
+- `--redact` 会脱敏 workspace、cwd、home 等绝对路径。
+
+## `repo templates`
+
+```bash
+repo templates
+repo templates tsdown
+repo templates --category library
+repo templates --check
+repo templates --json
+repo templates --markdown --out docs/templates.md
+```
+
+用途：
+
+- 查看内置模板 key、分类、默认生成目录和用途。
+- 检查模板元数据和源目录健康状态。
+- 给脚本读取 JSON，或生成 Markdown 文档片段。
+
+## `repo new`
+
+```bash
+repo new
+repo new sdk --template tsdown
+repo new docs --template vitepress
+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。
+
+## `repo check`
+
+```bash
+repo check
+repo check --staged
+repo check --full
+repo check --edit-file .git/COMMIT_EDITMSG
+repo check --dry-run
+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` 只预览将要执行的校验。
+
+## `repo upgrade`
+
+```bash
+repo upgrade
+repo upgrade --yes
+repo upgrade --overwrite
+repo upgrade --no-overwrite
+repo upgrade --core
+repo upgrade -i
+repo upgrade -s
+```
+
+用途：
+
+- 同步仓库标准资产与脚本。
+- `--core` 只同步核心配置，跳过 GitHub 相关资产。
+- `-i` 交互式选择。
+- `--no-overwrite` / `-s` 保留已有 drifted 文件。
+- `--yes` / `--overwrite` 非交互覆盖 drifted 标准资产。
+
+## 分组命令
+
+```bash
+repo ws ls
+repo ws ls --json --out reports/workspaces.json
+repo ws up
+repo tg init --all
+repo verify pre-commit
+repo verify pre-push
+repo env support --markdown --redact --out reports/support.md
+repo config inspect
+repo skills sync --codex
+```
+
+分组命令适合维护者和自动化脚本。日常开发优先使用顶层命令。
+
+## 继续阅读
+
+- [工作流与 CI](./workflows.md)
+- [排障与报告](./troubleshooting.md)
+- [命令别名](./aliases.md)