Init Release Base Relizy And Bumpp

Init Release Base — Relizy + Bumpp Monorepo 发版配置落地技能

本技能是执行型工作流：为 pnpm monorepo 一次性接入 relizy（子包）+ bumpp（根包） 的组合发版方案，从仓库体检、配置落盘、依赖对齐、故障预检，到 dry-run 验证与文档同步，覆盖完整接入链路。

设计理念

1. 本地控制 tag 生成：开发者在本地运行 pnpm release 一条命令完成所有版本管理
2. 云端负责 GitHub Release：GitHub Actions 检测到 tag 推送后，自动从 CHANGELOG.md 提取内容创建 Release
3. 单次 push：串行主链路中的所有 tags（子包 + 根包）在一次 git push --follow-tags 中推送
4. 根包有两种合法入口：串行主链路使用 release:root + --no-push；单独根包发版使用 release:bumpp + --push
5. 两工具协作：relizy 负责子包（independent 模式），bumpp 负责根包，各司其职

与 package-linter 的关系

若同时新建或规范化子包，请先或并行参考仓库内 package-linter 技能，保证 package.json / tsup / tsconfig 与 monorepo 约定一致；本技能聚焦发版域的配置与决策。

Runner：必须使用 @ruan-cat/utils 的 relizy-runner（禁止自建脚本）

兼容层（Windows GNU 工具补齐 + independent 基线 tag 自动准备）由 @ruan-cat/utils 包实现，通过 relizy-runner bin 调用。不得在目标仓库内新建 scripts/relizy-runner.ts 或任何本地 runner 副本。

• 权威说明：以安装到目标仓库的 relizy-runner --help 与 @ruan-cat/utils 包内 relizy-runner 文档为准。
• 调用约定：须使用 package.json 的 bin（如 npx relizy-runner … / pnpm exec relizy-runner …），禁止使用 tsx @ruan-cat/utils/relizy-runner 等绕过 exports 的写法。
• baseline 行为：release / bump 在缺少 independent 基线 tag 时，会按当前 package.json 版本创建 annotated bootstrap tags。带 --no-push 时只保留本地 tag，后续 git push --follow-tags 会携带；不带 --no-push 时使用 atomic push 推送本轮 tags。
• 禁写行为：--dry-run 或 --no-commit 下不会创建 tag，缺少基线时只打印手工兜底命令并停止。

--yes 与非交互发版

relizy 在 release / bump 等流程中可能弹出交互；在无 TTY 或 CI 下会挂起。串行主链路中的 release:sub 与 release:root 须显式写出 --yes，包括 package.json 脚本、README、验证命令。单独入口 release:bumpp 默认保留 bumpp 的交互式版本选择，并通过 --push 立即推送根 tag；若目标仓库确实需要全非交互，再自行显式追加 --yes。

发版流程架构

pnpm release
    │
    ├── 1. pnpm run release:sub（relizy）
    │   ├── 必要时创建本地 annotated baseline tags（--no-push 下不推送）
    │   ├── 分析各子包 commits → bump → CHANGELOG → commit → tag
    │   └── 不 push（--no-push）
    │
    ├── 2. pnpm run release:root（bumpp）
    │   ├── bump 根包 patch → changelogen → commit → tag
    │   └── 不 push（--no-push）
    │
    └── 3. pnpm run git:push
        └── git push --follow-tags（一次性推送）

详细架构说明见 references/release-workflow-architecture.md。

单独根包发版时使用：

pnpm run release:bumpp
    ├── bumpp 交互式选择根包版本
    ├── 生成根包 commit + tag
    └── 立即 push（--push）

一次性落盘的配置文件

依赖清单

接入时须安装以下 devDependencies（版本以 registry 最新为准）：

pnpm add -D bumpp changelogen changelogithub relizy @ruan-cat/commitlint-config @ruan-cat/utils @types/node pnpm-workspace-yaml

根包 scripts 模板

详见 templates/package-scripts.md。关键命令：

{
	"release": "pnpm run release:sub && pnpm run release:root && pnpm run git:push",
	"release:sub": "relizy-runner release --no-publish --no-provider-release --no-push --yes",
	"release:root": "bumpp --no-push --yes --release patch",
	"release:bumpp": "bumpp --push",
	"changelog:root": "changelogen --output CHANGELOG.md",
	"git:push": "git push --follow-tags"
}

三层目录

非目标（必须遵守）

• 不默认执行 npm publish、不默认开启 provider release。
• 不把本技能写成某个私有或固定仓库的专用脚本。
• 在 private 策略未确认、兼容策略未决 时，不盲目落盘。
• 禁止在目标仓库内新建本地 runner 脚本。
• 不将 selective 与「各包独立版本线」混为一谈。

标准六阶段流程

Task Progress:
- [ ] 阶段 1 — 侦察：收集工作区、锁文件、现有发版工具、tag、private、README/CHANGELOG 边界（用 templates/workspace-discovery.md）
- [ ] 阶段 2 — 确认：仅对高风险项确认（versionMode、全量纳管、private、兼容策略）（用 templates/package-eligibility.md）
- [ ] 阶段 3 — 故障预检：检查是否存在 commit-and-tag-version、conventional-changelog-cli 等遗留根包发版工具（见 references/dependency-conflict-precheck.md）
- [ ] 阶段 4 — 落盘：依赖安装、5 个配置文件写入、根 scripts 配置、必要时最小 tsconfig（用 templates/config-writer.md + 各 templates/*.ts）
- [ ] 阶段 5 — 验证：help、changelog dry-run、release dry-run（见 references/verification-matrix.md）
- [ ] 阶段 6 — 收尾：修改清单、破坏性说明、残余风险、下一步（用 templates/docs-sync.md）

显式阻断条件（不得跳过）

以下任一成立时，停止自动落盘，改为只输出方案与用户确认：

• 用户要求「各子包独立版本」，却拟使用 selective 充当独立版本方案。
• 拟纳入 relizy 的包涉及 private: true 变更，但未获确认。
• 确认不使用 relizy-runner，但未完成手工 baseline tag 确认。
• Windows 下已观测到 grep / head / sed 类失败，但未选择兼容策略。
• 检测到遗留根包发版工具（如 commit-and-tag-version、conventional-changelog-cli、standard-version、release-it），但尚未确认是删除还是隔离（见 references/dependency-conflict-precheck.md）。

核心决策（速查）

1. versionMode：「每包独立版本线」→ independent；「只 bump 变更包且共享一次发布语义」≠ 独立版本线。
2. 兼容策略：首选 relizy-runner（Windows GNU 工具 + baseline tag 自动准备）。
3. 文档边界：rootChangelog 与 README 更新是两条链路；formatCmd 不应宽到误改 README。
4. 根包发版：由 bumpp 独立负责，bump.config.ts 不写死 push；串行入口 release:root 用 --no-push，单独入口 release:bumpp 用 --push，并通过 execute 函数调用 changelogen --output CHANGELOG.md -r <newVersion>。
5. GitHub Release：由 CI 使用 gh release create 从 CHANGELOG.md 提取，不依赖 changelogithub / relizy provider-release。

templates/ 索引

references/ 索引

验证命令基线（根目录执行）

详见 references/verification-matrix.md。

relizy 子包验证（使用 relizy-runner）：

pnpm exec relizy-runner --help
pnpm exec relizy-runner changelog --dry-run --yes
pnpm exec relizy-runner release --dry-run --no-publish --no-provider-release --no-push --no-commit --no-clean --yes

bumpp 根包验证：

pnpm exec bumpp --help
pnpm exec bumpp --dry-run --release patch
pnpm exec changelogen --output CHANGELOG.md -r 0.0.1
git ls-remote --tags origin "v0.0.1"

期望根包 changelog 生成版本标题 ## v0.0.1，而不是区间标题 ## v0.0.0...main。

若本地已有根包 tag，但 GitHub Actions 的 release.yaml 未触发，应先检查远程 tag 是否存在，而不是第一时间怀疑工作流的 CHANGELOG 提取逻辑。

若 release:dry 或验证矩阵中的 dry-run 提示缺少 independent 基线 tags，这是预期的禁写保护：dry-run 不会创建 tag。首次接入时应通过真实 release:sub --no-push 自动创建本地 annotated baseline tags，或按提示手工创建后再重新 dry-run。

若输出为「无可 bump 包」且无配置/跨平台错误，应解释为验证通过但当前无变更可发。