@icebreakers/monorepo-templates 1.0.2 → 1.0.3

package/templates/vitepress/repoctl/config.md

@@ -0,0 +1,81 @@
+# 配置文件
+
+repoctl 推荐在仓库根目录使用一个配置文件：
+
+```txt
+repoctl.config.ts
+```
+
+旧文件名 `monorepo.config.ts` 继续兼容，但两者不能同时存在。`repo doctor` 会把冲突配置标记为阻塞问题。
+
+## 最小配置
+
+```ts
+import { defineMonorepoConfig } from 'repoctl'
+
+export default defineMonorepoConfig({
+  commands: {
+    create: {
+      defaultTemplate: 'tsdown',
+    },
+  },
+})
+```
+
+设置 `commands.create.defaultTemplate` 后：
+
+```bash
+repo new utils
+```
+
+会直接按默认模板创建，不再询问模板类型。
+
+## 常用配置
+
+```ts
+import { defineMonorepoConfig } from 'repoctl'
+
+export default defineMonorepoConfig({
+  commands: {
+    init: {
+      preset: 'standard',
+    },
+    create: {
+      defaultTemplate: 'tsdown',
+    },
+    clean: {
+      autoConfirm: true,
+    },
+    upgrade: {
+      skipOverwrite: true,
+    },
+  },
+})
+```
+
+| 配置                              | 作用                                    |
+| --------------------------------- | --------------------------------------- |
+| `commands.init.preset`            | 控制初始化默认预设                      |
+| `commands.create.defaultTemplate` | 控制 `repo new <name>` 的默认模板       |
+| `commands.clean.autoConfirm`      | 清理命令是否默认确认                    |
+| `commands.upgrade.skipOverwrite`  | 同步标准资产时是否保留已有 drifted 文件 |
+
+## 查看当前配置
+
+```bash
+repo config inspect
+repo cfg i --json --out reports/config.json
+repo cfg i --markdown --redact --out reports/config.md
+```
+
+`--redact` 适合把报告发到 issue、PR 或外部协作渠道。
+
+## 配置的定位
+
+配置文件只负责团队默认值，不建议把一次性命令参数都写进去。
+
+推荐做法：
+
+- 团队长期一致的选择写进 `repoctl.config.ts`。
+- 临时行为用命令参数表达，例如 `--dry-run`、`--json`、`--out`。
+- 自动化脚本优先使用显式参数，减少隐藏状态。

package/templates/vitepress/repoctl/getting-started.md

@@ -0,0 +1,122 @@
+# 快速开始
+
+这一页按“把 repoctl 接进一个仓库”的顺序写。你不需要先理解所有工具，先让仓库能被诊断、能创建包、能跑提交前校验。
+
+## 准备环境
+
+- Node.js 20 或更高版本。
+- pnpm。推荐通过 Corepack 启用：`corepack enable`。
+- Git。`repo doctor` 会读取仓库信息，用来补全 package metadata 和诊断提交链路。
+
+```bash
+node -v
+pnpm -v
+git --version
+```
+
+## 安装 repoctl
+
+```bash
+pnpm add -D repoctl
+```
+
+如果你使用的是这套模板生成的新仓库，依赖和根脚本通常已经准备好了，可以直接从 `pnpm install` 开始。
+
+## 初始化仓库默认值
+
+```bash
+pnpm install
+pnpm exec repo setup
+pnpm exec repo doctor
+```
+
+这三步分别解决：
+
+| 命令           | 作用                                                |
+| -------------- | --------------------------------------------------- |
+| `pnpm install` | 安装 workspace 依赖并创建本地链接                   |
+| `repo setup`   | 补齐推荐根脚本、workspace patterns 和基础工具链入口 |
+| `repo doctor`  | 检查根目录、Node 版本、CLI 依赖、配置冲突和提交链路 |
+
+如果 `doctor` 报错，先按输出里的 `fix:` 处理。处理完再跑一次 `pnpm exec repo doctor`。
+
+## 创建第一个包
+
+先看模板列表：
+
+```bash
+pnpm exec repo templates
+```
+
+创建一个 TypeScript 库：
+
+```bash
+pnpm exec repo new sdk --template tsdown
+```
+
+创建前只想预览：
+
+```bash
+pnpm exec repo new sdk --template tsdown --dry-run
+pnpm exec repo new sdk --template tsdown --json --out plans/sdk.json
+```
+
+`--json` 和 `--out` 会隐含 `--dry-run`，适合 CI、编辑器和脚本读取创建计划。
+
+## 使用短脚本
+
+如果仓库已经通过 `repo setup` 或模板生成补齐了根脚本，日常可以写得更短：
+
+```bash
+pnpm setup
+pnpm doctor
+pnpm new sdk --template tsdown
+pnpm check
+```
+
+对应关系：
+
+| 短脚本        | 等价命令                |
+| ------------- | ----------------------- |
+| `pnpm setup`  | `pnpm exec repo setup`  |
+| `pnpm doctor` | `pnpm exec repo doctor` |
+| `pnpm new`    | `pnpm exec repo new`    |
+| `pnpm check`  | `pnpm exec repo check`  |
+
+## 提交前检查
+
+```bash
+pnpm build
+pnpm lint
+pnpm typecheck
+pnpm test
+```
+
+如果只想走 repoctl 推荐的本地检查入口：
+
+```bash
+pnpm check
+pnpm exec repo check --dry-run
+pnpm exec repo check --json --out reports/check-plan.json
+```
+
+## 同步模板标准资产
+
+当模板升级后，用 `upgrade` 同步新的默认配置和脚本：
+
+```bash
+pnpm exec repo upgrade
+pnpm exec repo upgrade --no-overwrite
+pnpm exec repo upgrade --yes
+```
+
+- `--no-overwrite`：保留已有 drifted 文件。
+- `--yes` / `--overwrite`：适合明确要覆盖标准资产的自动化场景。
+- 非 TTY 环境不会弹出交互提示。
+
+## 常见下一步
+
+- 已有仓库渐进接入：阅读 [接入已有仓库](./adopt-existing.md)。
+- 想固定默认模板：阅读 [配置文件](./config.md)。
+- 想查看所有模板：阅读 [模板与创建](./templates.md)。
+- 想把诊断结果发给同事：阅读 [排障与报告](./troubleshooting.md)。

package/templates/vitepress/repoctl/index.md

@@ -0,0 +1,74 @@
+# repoctl 概览
+
+`repoctl` 是这套模板推荐给使用者的包名。默认命令是 `repo`，目标是把 pnpm workspace、Turborepo、模板创建、诊断报告和提交前校验收敛到一组稳定入口里。
+
+它不替代 pnpm、Turbo 或 changesets，而是把这些工具在 monorepo 里的常见动作串起来。
+
+## 什么时候使用 repoctl
+
+| 场景                                     | 推荐入口                 |
+| ---------------------------------------- | ------------------------ |
+| 给已有 pnpm workspace 补齐标准脚本和配置 | `pnpm exec repo setup`   |
+| 判断当前仓库是不是能顺利开发             | `pnpm exec repo doctor`  |
+| 创建新的包、应用、文档站或 CLI           | `pnpm exec repo new`     |
+| 提交前复现推荐校验链路                   | `pnpm exec repo check`   |
+| 同步模板最新标准资产                     | `pnpm exec repo upgrade` |
+| 给 CI、编辑器或脚本读取结构化结果        | `--json --out <file>`    |
+
+## 推荐命令层级
+
+### 1. 生成仓库里的短脚本
+
+```bash
+pnpm setup
+pnpm doctor
+pnpm new
+pnpm check
+```
+
+这是给日常开发和团队文档使用的入口。短、稳定、不需要先解释 CLI 包名。
+
+### 2. 明确调用 repo CLI
+
+```bash
+pnpm exec repo setup
+pnpm exec repo doctor
+pnpm exec repo templates
+pnpm exec repo new sdk --template tsdown
+pnpm exec repo check --dry-run
+```
+
+这是文档、CI、脚本和排障里最清楚的写法。
+
+### 3. 分组命令
+
+```bash
+pnpm exec repo ws ls
+pnpm exec repo tg init --all
+pnpm exec repo env support --markdown --redact
+pnpm exec repo config inspect
+```
+
+这些入口适合已经熟悉 repoctl 的维护者，用来做更细的 workspace、tooling、环境和配置操作。
+
+## 和旧入口的关系
+
+`repoctl` 包仍然提供兼容入口，例如：
+
+```bash
+pnpm exec repoctl doctor
+pnpm exec repoctl new
+```
+
+文档统一推荐 `repo`，是为了减少新人需要记住的名字。底层实现仍来自同一套 CLI。
+
+## 下一步
+
+- 第一次接入：[快速开始](./getting-started.md)
+- 不知道用哪个命令：[按场景选命令](./scenarios.md)
+- 查命令参数：[命令速查](./commands.md)
+- 固化团队默认值：[配置文件](./config.md)
+- 看可创建的模板：[模板与创建](./templates.md)
+- 接入 CI 和本地流程：[工作流与 CI](./workflows.md)
+- 生成排障报告：[排障与报告](./troubleshooting.md)
+- 熟悉短命令：[命令别名](./aliases.md)

package/templates/vitepress/repoctl/scenarios.md

@@ -0,0 +1,119 @@
+# 按场景选命令
+
+如果你不确定该用哪个 repoctl 命令，先从这一页开始。
+
+## 我刚拿到一个仓库
+
+```bash
+pnpm install
+pnpm doctor
+```
+
+如果 `pnpm doctor` 不存在：
+
+```bash
+pnpm add -D repoctl
+pnpm exec repo setup --yes
+pnpm exec repo doctor
+```
+
+继续看：[快速开始](./getting-started.md)。
+
+## 我要把 repoctl 接入旧仓库
+
+```bash
+pnpm add -D repoctl
+pnpm exec repo setup --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
+```
+
+继续看：[接入已有仓库](./adopt-existing.md)。
+
+## 我要创建新包或应用
+
+```bash
+pnpm exec repo templates
+pnpm exec repo new sdk --template tsdown
+pnpm exec repo new docs --template vitepress --dry-run
+```
+
+如果只是日常开发，根脚本也可以：
+
+```bash
+pnpm new sdk --template tsdown
+```
+
+继续看：[模板与创建](./templates.md)。
+
+## 我要提交前自查
+
+```bash
+pnpm check
+pnpm exec repo check --dry-run
+pnpm exec repo check --full
+```
+
+如果你想保存计划：
+
+```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)。
+
+## 我要调试 CI 或同事机器问题
+
+```bash
+pnpm exec repo doctor --markdown --redact --out reports/doctor.md
+pnpm exec repo env support --markdown --redact --out reports/support.md
+pnpm exec repo env snapshot --json --out reports/snapshot.json
+```
+
+继续看：[排障与报告](./troubleshooting.md)。
+
+## 我要同步模板标准资产
+
+```bash
+pnpm exec repo upgrade --no-overwrite
+pnpm exec repo upgrade --yes
+pnpm exec repo upgrade --core
+```
+
+选择建议：
+
+| 目标                     | 命令                          |
+| ------------------------ | ----------------------------- |
+| 第一次接入，保留已有配置 | `repo upgrade --no-overwrite` |
+| 明确要覆盖标准资产       | `repo upgrade --yes`          |
+| 只同步核心配置           | `repo upgrade --core`         |
+
+## 我要看 workspace 结构
+
+```bash
+pnpm exec repo ws ls
+pnpm exec repo ws ls --json --out reports/workspaces.json
+pnpm exec repo ws ls --markdown --redact --out reports/workspaces.md
+```
+
+## 我要看配置是否生效
+
+```bash
+pnpm exec repo config inspect
+pnpm exec repo cfg i --json --out reports/config.json
+```
+
+继续看：[配置文件](./config.md)。
+
+## 我要写更短的命令
+
+```bash
+repo tpl
+repo ws ls
+repo e support --markdown --redact
+repo cfg i
+```
+
+继续看：[命令别名](./aliases.md)。

package/templates/vitepress/repoctl/templates.md

@@ -0,0 +1,156 @@
+# 模板与创建
+
+repoctl 的模板由 `@icebreakers/monorepo-templates` 维护。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 命令行工具       |
+
+## 查看模板
+
+```bash
+repo templates
+repo templates tsdown
+repo templates --category library
+repo templates --json
+repo templates --markdown --out docs/templates.md
+```
+
+## 创建模板
+
+```bash
+repo new sdk --template tsdown
+repo new ui --template vue-lib
+repo new api --template hono-server
+repo new website --template vitepress
+repo new toolbox --template cli
+```
+
+普通名字会自动放到模板约定的目录里，例如库包进入 `packages/`，应用进入 `apps/`。如果你传入带 `/` 的路径，例如 `packages/shared-utils`，repoctl 会尊重这个路径。
+
+## 按目标选择模板
+
+### 要发布 npm 库
+
+```bash
+repo new sdk --template tsdown
+```
+
+生成后先检查：
+
+- `package.json` 的 `name`、`exports`、`types`。
+- `tsdown.config.ts` 是否符合产物格式。
+- 是否需要补 `tsd` 类型测试。
+
+### 要沉淀 Vue 组件
+
+```bash
+repo new ui --template vue-lib
+```
+
+生成后先检查：
+
+- 组件入口是否只导出稳定 API。
+- 样式是否能通过 Stylelint。
+- 文档站或示例应用是否需要同步创建。
+
+### 要创建应用或服务
+
+```bash
+repo new web --template vue-hono
+repo new api --template hono-server
+```
+
+生成后先检查：
+
+- 运行时环境变量和部署平台约束。
+- `dev`、`build`、`typecheck` 脚本是否接入根任务。
+- 是否需要在 CI 里加入 E2E 或集成测试。
+
+### 要创建文档站
+
+```bash
+repo new docs --template vitepress
+```
+
+生成后先检查：
+
+- 导航和 sidebar 是否围绕产品或包名组织。
+- 是否需要中英文 locale。
+- 是否需要把 `repo templates --markdown` 输出写进文档。
+
+### 要创建 CLI
+
+```bash
+repo new toolbox --template cli
+```
+
+生成后先检查：
+
+- `bin` 字段是否符合最终命令名。
+- 参数解析、退出码和帮助信息是否可测试。
+- 是否需要把命令用法写入 README。
+
+## 创建前预览
+
+```bash
+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 和输出文件。
+
+`--json` 输出同一份创建计划的结构化数据，隐含 `--dry-run`。
+
+`--out <file>` 可以把文本或 JSON 预览写入文件，也隐含 `--dry-run`。
+
+## 固化默认模板
+
+```ts
+import { defineMonorepoConfig } from 'repoctl'
+
+export default defineMonorepoConfig({
+  commands: {
+    create: {
+      defaultTemplate: 'tsdown',
+    },
+  },
+})
+```
+
+之后：
+
+```bash
+repo new utils
+```
+
+会直接创建 `tsdown` 库包。
+
+## 检查模板健康状态
+
+```bash
+repo templates --check
+repo templates --check --json
+```
+
+模板检查会确认：
+
+- 模板 source 和 target 没有重复。
+- 每个模板 source 目录都存在。
+- 每个模板根目录都有 `package.json`。
+- 每个模板都有 category 和 description。
+- 模板源目录里没有会被脚手架过滤掉的临时或生成文件。
+
+## 继续阅读
+
+- [接入已有仓库](./adopt-existing.md)
+- [工作流与 CI](./workflows.md)
+- [配置文件](./config.md)

package/templates/vitepress/repoctl/troubleshooting.md

@@ -0,0 +1,98 @@
+# 排障与报告
+
+repoctl 的排障重点不是让你猜错在哪里，而是尽量输出可以复现、可以保存、可以发给同事的报告。
+
+## 先跑 doctor
+
+```bash
+repo doctor
+repo doctor --strict
+```
+
+`doctor` 主要检查：
+
+- 当前目录是不是仓库根目录。
+- Node 版本是否满足要求。
+- `pnpm-workspace.yaml` 是否存在。
+- `repoctl` 是否作为 CLI 依赖安装。
+- 根脚本是否齐全。
+- `repoctl.config.ts` 和 `monorepo.config.ts` 是否冲突。
+- Husky 与 lint-staged 是否都接上。
+
+## 保存诊断报告
+
+```bash
+repo doctor --json --out reports/doctor.json
+repo doctor --markdown --redact --out reports/doctor.md
+```
+
+推荐把 Markdown 报告贴到 issue 或 PR。`--redact` 会脱敏本机路径。
+
+## 查看校验计划
+
+```bash
+repo check --dry-run
+repo check --json --out reports/check-plan.json
+repo check --markdown --redact --out reports/check-plan.md
+```
+
+当你不确定为什么某个文件触发了 workspace typecheck、pre-push 要跑哪些任务时，先看 check plan。
+
+## 收集环境信息
+
+```bash
+repo env info
+repo env support --markdown --redact --out reports/support.md
+repo env snapshot --json --out reports/snapshot.json
+repo env paths --markdown --redact --out reports/paths.md
+```
+
+这些命令适合排查 Node、pnpm、workspace、Git、路径和 CI 环境差异。
+
+## 常见问题
+
+### 当前目录不是仓库根目录
+
+切回包含 `pnpm-workspace.yaml` 和根 `package.json` 的目录，再运行：
+
+```bash
+repo doctor
+```
+
+### 同时存在两个配置文件
+
+只保留一个：
+
+```txt
+repoctl.config.ts
+```
+
+`monorepo.config.ts` 是兼容旧项目的文件名，新项目不建议继续使用。
+
+### `repo new` 提示模板不存在
+
+先查看可用模板：
+
+```bash
+repo templates
+```
+
+显式传入的 `--template` 会先校验。拼错时命令会失败并提示相近 key，不会静默回退。
+
+### 自动化里不希望出现交互
+
+使用非交互参数：
+
+```bash
+repo setup --yes
+repo upgrade --no-overwrite
+repo check --json --out reports/check-plan.json
+```
+
+非 TTY 环境下，repoctl 不会弹出交互选择框。
+
+## 继续阅读
+
+- [工作流与 CI](./workflows.md)
+- [命令速查](./commands.md)
+- [命令别名](./aliases.md)