@icebreakers/monorepo-templates 1.0.14 → 1.1.0

package/templates/vitepress/monorepo/publish.md

@@ -1,47 +1,10 @@
 # monorepo 发包与变更日志
 
-这套模板默认推荐用 `changesets` 管理版本和 changelog。原因不是“它很流行”，而是它对 monorepo 的工作方式最顺手：
+这套模板默认使用 pnpm 原生 versioning。它保留 Changesets 格式的变更意图，同时把版本计算、依赖传播、changelog 和发布收进 pnpm 本身。
 
-- 变更是按包记录的
-- 版本升级能自动联动内部依赖
-- changelog 可以稳定产出
-- 很容易接到 CI 里
+## 日常流程
 
-repoctl 在发布流程里的位置很明确：它不替代 `changesets` 发布版本，而是在发布前帮你确认仓库状态、模板资产和校验计划。
-
-## repoctl 在发布前做什么
-
-```bash
-pnpm exec repo doctor --strict
-pnpm exec repo check --full
-pnpm exec repo env support --markdown --redact --out reports/support.md
-```
-
-| 命令                   | 发布前价值                                               |
-| ---------------------- | -------------------------------------------------------- |
-| `repo doctor --strict` | 确认仓库结构、Node、脚本、配置和提交链路没有漂移         |
-| `repo check --full`    | 跑根脚本里的 lint/typecheck/test/build 计划              |
-| `repo env support`     | 保存环境、配置、doctor 和 check plan，方便发布失败后回溯 |
-
-发布本身仍交给 `changesets`：
-
-```bash
-pnpm changeset
-pnpm exec repo release stable
-```
-
-正式发布只走 `main`；`alpha`、`beta`、`rc`、`next` 只做 Changesets 的 prerelease，并发布对应 tag 包。
-
-## 一条务实的发布流程
-
-先把顺序记住：
-
-1. 写代码
-2. 跑校验
-3. 生成 changeset
-4. 合并后 version / publish
-
-对应到命令，一般是：
+先完成质量校验，再记录变更：
 
 ```bash
 pnpm build
@@ -49,211 +12,76 @@ pnpm lint
 pnpm typecheck
 pnpm tsd
 pnpm test
-pnpm changeset
+pnpm change
+pnpm change status
 ```
 
-如果你改的是公开类型或类库 API，`tsd` 不要省。
-
-## 为什么推荐 `changesets`
-
-| 需求           | `changesets` 的做法                       |
-| -------------- | ----------------------------------------- |
-| 记录哪些包变了 | 每次变更生成单独的 `.changeset/*.md` 文件 |
-| 控制版本类型   | 明确选择 `patch` / `minor` / `major`      |
-| 自动生成日志   | `changeset version` 统一产出 changelog    |
-| 联动内部包版本 | 自动改内部依赖引用                        |
-| CI 自动发布    | 可接 `changesets/action`                  |
+变更意图文件放在 `.changeset/*.md`，描述受影响包和 patch/minor/major。不要手动修改包版本。
 
-## 日常开发阶段怎么做
+## Release PR
 
-### 1. 本地先把质量门过掉
+main push 会运行：
 
 ```bash
-pnpm build
-pnpm lint
-pnpm typecheck
-pnpm tsd
-pnpm test
+pnpm version -r --dry-run
+pnpm version -r
 ```
 
-这一点和仓库的提交要求是一致的。
-
-### 2. 记录 changeset
+CI 将版本号、各包 `CHANGELOG.md` 和 `.changeset/ledger.yaml` 提交到 Release PR。合并 Release PR 后，下一次 main push 执行：
 
 ```bash
-pnpm changeset
+pnpm publish -r --report-summary --provenance --no-git-checks
 ```
 
-按提示选择：
+pnpm 根据 registry 中已有的版本自动跳过已发布包。CI 读取 `pnpm-publish-summary.json` 创建 `package@version` tag 和 GitHub Release，发布操作可以安全重试。
 
-1. 哪些包受影响
-2. 这些包分别是 `patch` / `minor` / `major`
-3. 这次改动怎么写进 changelog
+## Workspace versioning 配置
 
-示例：
-
-```md
----
-"@my/utils": minor
-"@my/ui": patch
----
-
-- feat(utils): 新增时间格式化工具
-- fix(ui): 修复按钮禁用态样式
-```
-
-### 3. 合并前看一眼影响面
-
-changeset 文件本身就是最便宜的“发布预告”。代码评审时顺手看一下，通常就能避免：
-
-- 漏记某个包
-- 版本类型选错
-- changelog 写得太含糊
-
-## 发布阶段怎么做
-
-### 手动流程
-
-```bash
-pnpm exec repo release stable
-```
-
-`repo release stable` 会先执行构建、lint 和测试，再调用 `changeset version` 与 `changeset publish`。其中 `changeset version` 会做这些事：
-
-- 更新受影响包的版本号
-- 调整内部依赖版本
-- 生成或更新每个包的 `CHANGELOG.md`
-
-### CI 自动流程
-
-模板推荐结合 `changesets/action`。
-
-一个常见的工作流结构如下：
+根 `pnpm-workspace.yaml` 中的关键配置：
 
 ```yaml
-name: Release
-
-on:
-  push:
-    branches:
-      - main
-      - alpha
-      - beta
-      - rc
-      - next
-  workflow_dispatch:
-
-permissions:
-  contents: write
-  pull-requests: write
-  issues: write
-  id-token: write
-
-env:
-  HUSKY: 0
-
-jobs:
-  release:
-    if: github.ref_name == 'main'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 24
-          cache: pnpm
-          registry-url: https://registry.npmjs.org
-      - run: pnpm install
-      - name: Create Release Pull Request or Publish to npm
-        uses: changesets/action@v1
-        with:
-          publish: pnpm exec repo release stable
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-  prerelease:
-    if: github.ref_name != 'main'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 24
-          cache: pnpm
-      - run: pnpm install
-      - run: git config user.name "github-actions[bot]"
-      - run: git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-      - name: Publish Prerelease
-        run: pnpm exec repo release pre publish
+versioning:
+  fixed:
+    - ['@icebreakers/monorepo', repoctl]
+  ignore:
+    - '@icebreakers/client'
+  changelog:
+    storage: repository
 ```
 
-## 关于 npm 鉴权
+`fixed` 保证组内包同版本；`ignore` 排除 private 包；`repository` 让 changelog 作为源代码提交。
 
-现在更推荐在 CI 里使用 OIDC，而不是长期保存一个会过期的 `NPM_TOKEN`。
+## Prerelease lanes
 
-原因很现实：
+预发布使用 pnpm lanes：
 
-- token 会过期
-- token 泄漏风险更高
-- OIDC 更适合自动化发布
-
-所以工作流里建议保留：
-
-```yaml
-permissions:
-  id-token: write
+```bash
+pnpm exec repo release pre enter beta
+git add pnpm-workspace.yaml && git commit -m "chore(release): enter beta lane"
+git push
+pnpm exec repo release pre publish
 ```
 
-## 常见发布约束
-
-### 私有包不会被发布
+预发布版本为 `X.Y.Z-beta.N`，并使用 npm `beta` dist-tag。退出时运行：
 
-如果一个包是：
-
-```json
-{
-  "private": true
-}
+```bash
+pnpm exec repo release pre exit
+git add pnpm-workspace.yaml && git commit -m "chore(release): exit prerelease lane"
 ```
 
-那么它通常不会进入 npm 发布流程。
-
-### 没有 changeset 就不会有版本 PR
-
-如果你改了公开包，却没有提交 `.changeset/*.md`，那么后续版本流转通常会断掉。
-
-### 先 build 再发
-
-这个仓库的约定很明确：先 build，再 lint / typecheck / tsd / test，再谈发布。不要跳步。
-
-## 常见问题
-
-### 为什么没有生成 changelog？
-
-通常是下面几种原因：
-
-- 没有执行 `pnpm changeset version`
-- `.changeset/*.md` 没有提交
-- 受影响包实际没有进入版本计算
-
-### 如何跳过某个包的发布？
-
-- 在 changeset 里不要勾选它
-- 或者把它标记为 `private: true`
-
-### 为什么要在 PR 阶段就看 changeset？
+fixed group 必须整体切换 lane，不能只移动其中一个包。
 
-因为它本质上是在回答一个非常具体的问题：
+## 恢复未发布版本
 
-“这次改动准备怎么影响发布面？”
+如果版本提交已合并但 npm 发布失败，在 Release workflow 手动选择 `publish-unpublished`，填入 package 和 version。CI 会校验 main 上的 manifest 版本，使用 pnpm 发布并重新生成 tag 和 GitHub Release 元数据。
 
-这个问题越早看，越不容易在合并后补救。
+## repoctl 的边界
 
-## 继续阅读
+生成的 GitHub Actions 只保留环境准备和一个 `pnpm exec repo release ci` 调用。
+repoctl 负责发布前 build/lint/test、lane 一致性检查、Release PR、npm
+发布、package tag 与 GitHub Release；pnpm 负责变更意图、版本计算、changelog、
+ledger 和 registry 发布细节。
 
-- [如何管理 monorepo](./manage.md)
-- [repoctl 工作流与 CI](../repoctl/workflows.md)
-- [repoctl 排障与报告](../repoctl/troubleshooting.md)
-- [命令别名](../repoctl/aliases.md)
+存量项目首次迁移运行 `pnpm dlx repoctl@latest upgrade --yes`，后续使用
+`pnpm exec repo upgrade --yes` 即可跟随 repoctl 升级。未标记的自定义 release
+workflow 默认不会被覆盖，确认后可使用 `repo upgrade --overwrite-release`。

package/templates/vitepress/package.json

@@ -23,19 +23,19 @@
     "typecheck": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "vue": "^3.5.40"
+    "vue": "^3.5.41"
   },
   "devDependencies": {
     "@braintree/sanitize-url": "^7.1.2",
     "@tailwindcss/vite": "^4.3.3",
-    "cytoscape": "^3.34.0",
+    "cytoscape": "^3.34.1",
     "cytoscape-cose-bilkent": "^4.1.0",
     "dayjs": "^1.11.21",
     "debug": "^4.4.3",
-    "mermaid": "^11.16.0",
+    "mermaid": "^11.16.1",
     "tailwindcss": "^4.3.3",
     "vitepress": "^1.6.4",
-    "vitepress-plugin-llms": "^1.13.3",
+    "vitepress-plugin-llms": "^1.13.5",
     "vitepress-plugin-mermaid": "^2.0.17"
   }
 }

package/templates/vitepress/repoctl/index.md

@@ -2,7 +2,7 @@
 
 `repoctl` 是这套模板推荐给使用者的包名。默认命令是 `repo`，目标是把 pnpm workspace、Turborepo、模板创建、诊断报告和提交前校验收敛到一组稳定入口里。
 
-它不替代 pnpm、Turbo 或 changesets，而是把这些工具在 monorepo 里的常见动作串起来。
+它不替代 pnpm、Turbo 或 pnpm versioning，而是把这些工具在 monorepo 里的常见动作串起来。
 
 ## 什么时候使用 repoctl
 

package/templates/vitepress/thinking.md

@@ -61,7 +61,7 @@
 
 ### 发包流程
 
-我采用了 `changesets`，它在 `monorepo` 环境下发布非常方便。功能非常的多，具体可以查看官方文档。
+现在使用 pnpm 原生 versioning：用 `pnpm change` 记录意图，用 `pnpm version -r` 生成版本和 changelog，再用 `pnpm publish -r` 发布。版本计划保留在 `.changeset/ledger.yaml`，预发布则由 pnpm lanes 管理。
 
 ### Github 相关配置
 

package/templates/vitepress/tools/changeset.md

@@ -1,98 +1,75 @@
-# Changesets
+# pnpm Versioning
 
-[Changesets](https://github.com/changesets/changesets)。它帮助你在 **monorepo** 或多包项目中更有条理地维护变更日志（changelog）、版本号升级策略以及自动化发布流程。
+本模板使用 pnpm 11 原生 versioning 管理 monorepo 的变更意图、版本号、changelog 和发布。变更意图仍然使用 `.changeset/*.md` 格式，因此每次改动可以独立提交，不会直接修改包版本。
 
-在 repoctl 体系里，Changesets 负责“版本和发布”，repoctl 负责“发布前仓库是否健康”。
+## 日常开发
 
 ```bash
-pnpm exec repo doctor --strict
-pnpm exec repo check --full
-pnpm changeset
-pnpm exec repo release stable
+pnpm change
+pnpm change status
 ```
 
-继续看：[monorepo 发包与变更日志](../monorepo/publish.md)。
-
-## 1. 什么是 Changeset？
-
-- **核心思想**：每一次改动，不直接修改 `package.json` 里的版本号，而是通过写一个 `changeset` 文件（通常放在 `.changeset` 文件夹下）。
-- **作用**：
-  - 记录每次改动影响了哪些包（哪些需要 bump 版本）。
-  - 指定改动类型（`patch`、`minor`、`major`）。
-  - 自动生成 **Changelog**。
-  - 自动修改 `package.json` 的版本号。
-  - 与 CI/CD 集成后，可以实现一键自动发版。
-
-## 2. 如何使用 Changesets？
-
-### 安装
+`pnpm change` 会询问受影响的包、patch/minor/major 类型和 changelog 摘要。脚本或自动化场景可以直接指定：
 
 ```bash
-npm install --save-dev @changesets/cli
+pnpm change --bump patch --summary "修复空输入崩溃" repoctl
 ```
 
-### 初始化
-
-```bash
-npx changeset init
-```
+变更意图会写入 `.changeset/`，与代码一起提交。`pnpm change status` 只预览计划，不会修改文件。
 
-会生成一个 `.changeset` 文件夹，里面包含配置文件。
+## 版本与 changelog
 
-### 添加变更
-
-当你完成某个功能或修复后，运行：
+在 Release PR 中由 CI 消费变更意图：
 
 ```bash
-npx changeset
+pnpm version -r --dry-run
+pnpm version -r
 ```
 
-它会问：
+`pnpm version -r` 会更新受影响包、传播 workspace 依赖、生成 `CHANGELOG.md`，并把消费记录追加到 `.changeset/ledger.yaml`。仓库配置使用 `versioning.changelog.storage: repository`，所以 changelog 会和版本提交一起审查。
 
-1. 哪些包受影响？
-2. 这是 **patch**（补丁）、**minor**（新功能）、还是 **major**（重大变更）？
-3. 变更的描述是什么？
+`@icebreakers/monorepo` 与 `repoctl` 属于 pnpm fixed group，任一包需要发布时两者始终使用同一个版本。
 
-这会生成一个类似这样的文件：
+## 发布
 
-```yaml
-# .changeset/sweet-pandas-sing.md
----
-my-package: patch
----
+正式发布由 Release PR 合并后的 main workflow 完成：
 
-修复了登录时的 bug
+```bash
+pnpm publish -r --report-summary --provenance --no-git-checks
 ```
 
-### 应用版本更新
+pnpm 会跳过 registry 中已经存在的版本，并把新发布包写入 `pnpm-publish-summary.json`。CI 根据 summary 创建 `package@version` Git tag 和 GitHub Release，因此重复执行不会重新发布已存在版本。
 
-当积累了多个 changeset 后，可以执行：
+本地推荐使用 repoctl 包装命令：
 
 ```bash
-npx changeset version
+pnpm exec repo release stable prepare
+pnpm exec repo release stable publish
 ```
 
-它会根据 changeset 文件：
-
-- 更新对应包的版本号。
-- 生成/更新 `CHANGELOG.md`。
+## Prerelease lanes
 
-### 发布
-
-最后可以发布：
+alpha、beta、rc、next 是 pnpm lanes，而不是 Changesets pre 状态：
 
 ```bash
-npx changeset publish
-```
+pnpm exec repo release pre enter alpha
+git add pnpm-workspace.yaml && git commit -m "chore(release): enter alpha lane"
+git push
 
-会自动调用 `npm publish`，把包发到 npm registry。
+pnpm exec repo release pre publish
+```
 
-## 3. 在 Monorepo 中的优势
+退出预发布轨道时执行 `pnpm exec repo release pre exit`，提交 `pnpm-workspace.yaml` 后合并回 main。lane 切换必须覆盖 fixed group 的全部包。
 
-- 避免多人协作时冲突：大家都往 `.changeset` 添加文件，不会直接改 `package.json`。
-- 统一生成 changelog：自动保证每个版本的改动都被记录。
-- 自动化发布：和 GitHub Actions 等 CI 工具结合，可在合并到主分支后自动发版。
+## CI 约定
 
-## 总结
+- 生成的 release workflow 只负责 checkout、安装依赖和权限声明，全部业务统一由 `pnpm exec repo release ci` 执行。
+- main push 先生成或更新 Release PR；Release PR 合并后才发布 npm。
+- alpha、beta、rc、next 分支要求所有可发布包位于对应 lane。
+- npm 发布使用 GitHub OIDC provenance，不需要长期保存 `NPM_TOKEN`。
+- 未发布版本恢复使用 workflow dispatch 的 `publish-unpublished` 模式，并按 package/version 校验后发布。
+- repoctl 通过 GitHub REST API 幂等创建或更新 Release PR、package tag 和 GitHub Release，重复执行不会重复创建元数据。
 
-**Changeset 就是一个版本管理与发版工具**，它通过“先记录再统一处理”的方式，帮助 npm 包（尤其是 monorepo）保持版本升级和 changelog 的一致性与可追溯性。
+存量项目首次迁移运行 `pnpm dlx repoctl@latest upgrade --yes`。带有
+`repoctl-managed: release/v2` 的 workflow 会自动升级；未标记的自定义
+workflow 默认保留，可在确认后使用 `repo upgrade --overwrite-release`。

package/templates/vitepress/tools/index.md

@@ -1,5 +1,5 @@
 ---
-description: repoctl 文档站的工具专题入口，汇总 pnpm、Turborepo、changeset、Husky、lint-staged 和 Renovate。
+description: repoctl 文档站的工具专题入口，汇总 pnpm、Turborepo、版本管理、Husky、lint-staged 和 Renovate。
 ---
 
 # 工具专题
@@ -8,14 +8,14 @@ description: repoctl 文档站的工具专题入口，汇总 pnpm、Turborepo、
 
 ## 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)       |
+| 工具            | 在 repoctl 工作流里的位置                       | 详细页面                        |
+| --------------- | ----------------------------------------------- | ------------------------------- |
+| pnpm            | workspace、依赖安装、根脚本和包内脚本执行       | [pnpm](./pnpm.md)               |
+| Turborepo       | build、lint、typecheck、test 等任务编排         | [turborepo](./turborepo.md)     |
+| pnpm versioning | 多包版本、变更记录和发布准备                    | [versioning](./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 的关系
 
@@ -33,6 +33,6 @@ repoctl 不隐藏这些工具。它主要做三件事：
 | ------------------------- | ------------------------------------------------------ |
 | 让 workspace 包能互相引用 | [pnpm](./pnpm.md)                                      |
 | 提升整仓任务速度          | [turborepo](./turborepo.md)                            |
-| 建立规范发版链路          | [changeset](./changeset.md)                            |
+| 建立规范发版链路          | [pnpm versioning](./changeset.md)                      |
 | 提交前自动修复格式和 lint | [Husky](./husky.md) 与 [lint-staged](./lint-staged.md) |
 | 降低依赖升级成本          | [Renovate](./renovate.md)                              |

package/templates/vue-lib/package.json

@@ -52,10 +52,10 @@
     "@vitejs/plugin-vue": "^6.0.8",
     "@vue/test-utils": "^2.4.11",
     "@vue/tsconfig": "^0.9.1",
-    "jsdom": "^29.1.1",
-    "vite": "^8.1.5",
+    "jsdom": "^30.0.1",
+    "vite": "^8.2.1",
     "vite-plugin-dts": "^5.0.3",
-    "vue": "^3.5.40",
-    "vue-tsc": "^3.3.7"
+    "vue": "^3.5.41",
+    "vue-tsc": "^3.3.9"
   }
 }

package/templates/vue-lib/vitest.config.ts

@@ -1,7 +1,7 @@
 import Vue from '@vitejs/plugin-vue'
 import { defineVitestProjectConfig } from 'repoctl/tooling'
 import { mergeConfig } from 'vitest/config'
-import { sharedConfig } from './vite.shared.config'
+import { sharedConfig } from './vite.shared.config.ts'
 
 export default mergeConfig(sharedConfig, {
   ...await defineVitestProjectConfig({

package/assets/.changeset/config.json

@@ -1,21 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@changesets/config@3.0.2/schema.json",
-  "changelog": [
-    "@icebreakers/changelog-github",
-    {
-      "repo": "sonofmagic/monorepo-template"
-    }
-  ],
-  "commit": false,
-  "fixed": [],
-  "linked": [
-    [
-      "@icebreakers/monorepo",
-      "repoctl"
-    ]
-  ],
-  "access": "public",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "ignore": []
-}