@icebreakers/monorepo-templates 1.0.2 → 1.0.3

package/templates/vitepress/repoctl/workflows.md

@@ -0,0 +1,105 @@
+# 工作流与 CI
+
+repoctl 的命令可以分成两类：给人用的日常入口，以及给 CI、脚本、编辑器用的可保存输出。
+
+## 本地日常工作流
+
+```bash
+pnpm install
+pnpm doctor
+pnpm new sdk --template tsdown
+pnpm check
+pnpm build
+```
+
+这条链路适合新成员第一次进入仓库：
+
+| 步骤           | 判断标准                                         |
+| -------------- | ------------------------------------------------ |
+| `pnpm install` | workspace 依赖和本地链接完整                     |
+| `pnpm doctor`  | 仓库根目录、Node、脚本、配置和提交链路可用       |
+| `pnpm new`     | 新包由模板创建，目录和 package metadata 符合约定 |
+| `pnpm check`   | 提交前轻量校验可以复现                           |
+| `pnpm build`   | 全仓构建链路没有明显断点                         |
+
+## 存量仓库接入
+
+```bash
+pnpm add -D repoctl
+pnpm exec repo setup --yes
+pnpm exec repo doctor --markdown --out reports/doctor.md
+pnpm exec repo upgrade --no-overwrite
+pnpm exec repo doctor
+```
+
+推荐先用 `--no-overwrite` 保守接入。确认标准资产差异后，再决定是否使用 `--yes` 或 `--overwrite`。
+
+## CI 快速门禁
+
+```bash
+pnpm install --frozen-lockfile
+pnpm exec repo doctor --strict
+pnpm exec repo check --full
+```
+
+适合小仓库或早期项目。`doctor --strict` 会把 warning 也当成失败，能避免配置漂移慢慢积累。
+
+## CI 报告模式
+
+```bash
+pnpm exec repo doctor --json --out reports/doctor.json
+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。
+
+## pre-commit 与 pre-push
+
+repoctl 暴露了底层 verify 命令，方便 hook 和脚本复用：
+
+```bash
+repo verify pre-commit
+repo verify staged-typecheck packages/app/src/main.ts
+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。
+
+## 非交互参数选择
+
+| 场景               | 推荐参数                                           |
+| ------------------ | -------------------------------------------------- |
+| 初始化时接受默认值 | `repo setup --yes`                                 |
+| 同步时保留已有改动 | `repo upgrade --no-overwrite`                      |
+| 明确覆盖标准资产   | `repo upgrade --yes` 或 `repo upgrade --overwrite` |
+| 只看计划不执行     | `--dry-run`                                        |
+| 输出给脚本         | `--json --out <file>`                              |
+| 输出给人看并脱敏   | `--markdown --redact --out <file>`                 |
+
+## 下一步
+
+- 查所有参数：[命令速查](./commands.md)
+- 生成排障包：[排障与报告](./troubleshooting.md)
+- 看短命令：[命令别名](./aliases.md)

package/templates/vitepress/tools/changeset.md

@@ -2,6 +2,17 @@
 
 [Changesets](https://github.com/changesets/changesets)。它帮助你在 **monorepo** 或多包项目中更有条理地维护变更日志（changelog）、版本号升级策略以及自动化发布流程。
 
+在 repoctl 体系里，Changesets 负责“版本和发布”，repoctl 负责“发布前仓库是否健康”。
+
+```bash
+pnpm exec repo doctor --strict
+pnpm exec repo check --full
+pnpm changeset
+pnpm exec repo release stable
+```
+
+继续看：[monorepo 发包与变更日志](../monorepo/publish.md)。
+
 ## 1. 什么是 Changeset？
 
 - **核心思想**：每一次改动，不直接修改 `package.json` 里的版本号，而是通过写一个 `changeset` 文件（通常放在 `.changeset` 文件夹下）。

package/templates/vitepress/tools/husky.md

@@ -1,5 +1,22 @@
 # Husky
 
+在 repoctl 体系里，Husky 是 Git hook 触发器；真正的校验逻辑尽量收口到 repoctl 命令，方便本地、CI 和手动复现使用同一套入口。
+
+```bash
+repo verify pre-commit
+repo verify commit-msg .git/COMMIT_EDITMSG
+repo verify pre-push
+```
+
+如果你只想手动复现推荐校验，用：
+
+```bash
+repo check --staged
+repo check --full
+```
+
+继续看：[repoctl 工作流与 CI](../repoctl/workflows.md)。
+
 ## 1. 什么是 Husky？
 
 **Husky** 是一个用于在 **Git hooks**（如 `pre-commit`、`pre-push`、`commit-msg` 等）中运行脚本的工具。

package/templates/vitepress/tools/lint-staged.md

@@ -1,5 +1,15 @@
 # lint-staged
 
+在 repoctl 体系里，lint-staged 负责把 staged 文件交给合适的工具；repoctl 的 `verify staged-typecheck` 会根据文件所在 workspace 路由 typecheck。
+
+```bash
+repo verify pre-commit
+repo verify staged-typecheck packages/app/src/main.ts
+repo check --staged
+```
+
+继续看：[repoctl 工作流与 CI](../repoctl/workflows.md)。
+
 ## 1. 什么是 lint-staged？
 
 **lint-staged** 是一个工具，主要功能是：

package/templates/vitepress/tools/pnpm.md

@@ -1,5 +1,31 @@
 # pnpm
 
+repoctl 默认围绕 pnpm workspace 设计。你不需要先掌握 pnpm 的所有细节，但要理解这三个事实：
+
+- `pnpm-workspace.yaml` 决定哪些目录属于 workspace。
+- `pnpm install` 会把 workspace 包链接起来。
+- 根脚本，例如 `pnpm doctor`、`pnpm new`、`pnpm check`，最终会调用 repoctl 的 `repo` CLI。
+
+## 在 repoctl 项目里怎么用 pnpm
+
+```bash
+pnpm install
+pnpm add -D repoctl
+pnpm doctor
+pnpm new sdk --template tsdown
+pnpm check
+```
+
+| 命令                  | 在 repoctl 工作流里的作用     |
+| --------------------- | ----------------------------- |
+| `pnpm install`        | 安装依赖并创建 workspace link |
+| `pnpm add -D repoctl` | 给已有仓库接入 repoctl CLI    |
+| `pnpm doctor`         | 通过根脚本运行 `repo doctor`  |
+| `pnpm new`            | 通过根脚本运行 `repo new`     |
+| `pnpm check`          | 通过根脚本运行 `repo check`   |
+
+继续看：[repoctl 快速开始](../repoctl/getting-started.md)。
+
 ## 1. 什么是 pnpm？
 
 **pnpm** 是一种 Node.js 的包管理器（类似于 **npm** 和 **yarn**）。

package/templates/vitepress/tools/turborepo.md

@@ -1,5 +1,22 @@
 # Turborepo
 
+在 repoctl 体系里，Turborepo 负责“任务编排和缓存”，repoctl 负责“什么时候该跑哪些任务”。你日常通常不需要直接调用 `turbo`，而是通过根脚本或 `repo check` 间接触发。
+
+```bash
+pnpm build
+pnpm test
+pnpm exec repo check --full
+pnpm exec repo check --json --out reports/check-plan.json
+```
+
+| 层级                              | 作用                                      |
+| --------------------------------- | ----------------------------------------- |
+| `repo check`                      | 决定校验模式，输出可读或可保存的计划      |
+| 根脚本 `pnpm build` / `pnpm test` | 调用 `turbo run build` / `turbo run test` |
+| `turbo.json`                      | 定义任务依赖、缓存输出和执行策略          |
+
+继续看：[repoctl 工作流与 CI](../repoctl/workflows.md)。
+
 ## 1. 什么是 Turborepo？
 
 **Turborepo** 是由 **Vercel** 推出的一个 **高性能 JavaScript/TypeScript monorepo 构建系统**。