@pawover/kit 0.8.0 → 0.8.1

package/README.md

@@ -108,26 +108,80 @@ pnpm install
 
 ## 发布
 
-发布由 [Changesets](https://changesets.dev) + GitHub Actions 全自动驱动，无需手动登录 npm 或运行发布命令。
+发布由 [Changesets](https://changesets.dev) v3 + GitHub Actions 全自动驱动，push `main` 即触发，全程无需手动登录 npm 或输入 OTP（走 Trusted Publishing / OIDC 认证，发布自动附带 provenance 证明）。
 
-**日常流程**：改动代码后运行 `pnpm changeset`，按提示选择受影响的包与版本级别并填写变更说明，将生成的 `.changeset/*.md` 随 PR 一起提交。合并到 `main` 后：
+### 一图流
 
-1. CI 自动创建 / 更新 **Version Packages** PR（内含各包版本号与 CHANGELOG）
-2. 合并该 PR 后自动构建，并按拓扑序发布（`types` / `zod` / `eslint-rules` → `utils` → `hooks` → 根包 `@pawover/kit`）
-3. 自动打 git tag 并生成 GitHub Release
+```
+push main
+  └─ select-mode（读 .changeset/ + 对比 git tag）
+       ├─ 有 changeset 文件 ───────→ version 通道：自动建/更「Version Packages」PR
+       │                              └─ 合并 PR → push main → 再次 select-mode
+       ├─ 无 changeset，但版本 > git tag ─→ publish 通道：build → pack → 发布 → 打 git tag
+       └─ 无变化 ──────────────────→ unchanged：安全空跑
+```
+
+### 日常发布循环
+
+1. **改代码**——不要手动修改任何 `package.json` 的 `version` 字段，版本号只能由 changesets 生成
+2. **写 changeset**：`pnpm changeset`（交互式勾选受影响包与 bump 级别），生成 `.changeset/*.md` 变更说明；也可手写该文件，示例：
+
+   ```md
+   ---
+   "@pawover/kit-utils": patch
+   "@pawover/kit-hooks": minor
+   ---
+
+   修复 xxx 问题 / 新增 xxx 能力
+   ```
+
+3. **提交 PR**：changeset 文件**必须与代码同 PR**，合并到 `main`
+4. **CI 自动创建 / 更新「Version Packages」PR**：消费 changeset → 计算各包新版本号 → 更新 CHANGELOG（合并前 CI 会先跑 `scripts/verify-release.mjs` 守卫）
+5. **审核并合并 Version Packages PR**：确认版本号符合预期、`@pawover/kit` 根包在发布列表中（有子包变更时必在）
+6. **CI 自动发布**：`select-mode` 进入 publish 通道 → pack job（`pnpm build` + pack，`HUSKY: 0`）→ publish job（`changeset publish --from-pack-dir`，逐包 `npm publish`）→ 成功后自动打 git tag（`@pawover/kit-utils@0.0.0-alpha.5` 等）并推送
+7. **验证**：`npm view @pawover/kit-utils dist-tags --json` 看 tag 落点；Actions 全绿；npmjs 包页出现 Provenance 徽标
+
+### 版本号规则（当前 alpha pre 模式）
 
-**版本策略**：各包独立版本。子包版本变化时，依赖它的包（含根包）自动随同提升——任何子包发布必伴随根包发布（CI 有硬校验守卫）。
+| bump | 子包（当前 `0.0.0-alpha.4`） | 根包（当前 `0.8.0`） |
+| :--- | :--- | :--- |
+| `patch` | `0.0.0-alpha.5` | `0.8.1-alpha.N` |
+| `minor` | `0.1.0-alpha.0` | `0.9.0-alpha.N` |
+| `major` | `1.0.0-alpha.0` | `1.0.0-alpha.N` |
+
+- 子包 A 被发布时，依赖 A 的包（含根包）自动随同 patch 提升——**任何子包发布必伴随根包发布**（CI 硬校验守卫）
+- 已存在于 registry 的版本不会重复发布
+
+### dist-tag 规则
+
+| 包 | 当前 `latest` | `alpha` tag |
+| :--- | :--- | :--- |
+| 5 个子包 | `0.0.0-alpha.4`（only-pre：从未出过稳定版，首个 pre 版本直接挂 latest） | `0.0.0-alpha.3` |
+| 根包 `@pawover/kit` | `0.8.0`（有稳定版历史，pre 版本只发 alpha tag，不碰 latest） | — |
+
+### 转正流程（发布正式版）
 
-**当前阶段**：处于 alpha pre 模式，所有包以 `X.Y.Z-alpha.N` 发布到 `alpha` dist-tag。转正时运行 `pnpm pre:exit` 并删除 CI 中的 `NPM_CONFIG_TAG` 环境变量。
+1. 确认 main 干净（无未合并的 Version PR）
+2. `pnpm pre:exit` → 提交并 push main（`pnpm pre:enter-alpha` 可随时重新进入）
+3. 之后照常走日常循环，此时版本号不再带 `-alpha`，发布到 `latest`
+4. 清理遗留（可选）：`npm dist-tag rm <包> alpha` 移除 5 个子包的旧 alpha tag
 
-**应急手动发布**（一般不使用）：
+### 应急手动发布（一般不使用）
 
 ```bash
-pnpm build && pnpm postbuild   # 构建并同步 entry/metadata.json
-pnpm publish --access public --tag alpha   # 根包
-pnpm --filter @pawover/kit-types public    # 单个子包
+pnpm build && pnpm postbuild            # 构建并同步 entry/metadata.json
+pnpm public                             # 根包（turbo build && pnpm publish）
+pnpm --filter @pawover/kit-utils publish --tag alpha   # 单个子包（本地需登录态，交互式 OTP）
 ```
 
+### 易错点
+
+- **Trusted Publisher**（npmjs 后台）：Repository 必须是 `pawover-kit`（不是包名）、workflow 必须 `.github/workflows/release.yml`、Environment 留空——任何不一致会导致 CI 发布 E404
+- `release.yml` 的 pack / publish job 已设 `HUSKY: 0`，勿删（否则 `npm pack` 触发根包 husky 直接失败）
+- changeset 忘提交 → 不发布；手动改版本号 → 破坏 tag 对比逻辑，**永远不要**
+- `pnpm changeset version` 需要干净工作区，本地跑之前先提交/暂存
+- 只有本地手动发布才需要 OTP；CI 走 OIDC 不需要
+
 ## 测试
 
 - **单元测试**：vitest 双项目（node 环境覆盖 utils / zod / eslint-rules，jsdom 环境覆盖 hooks）

package/entry/eslint-rules.d.cts

@@ -1 +1 @@
-export type * from './eslint-rules.d.ts';
+export type * from './eslint-rules.d.ts';

package/entry/hooks-alova.d.cts

@@ -1 +1 @@
-export type * from './hooks-alova.d.ts';
+export type * from './hooks-alova.d.ts';

package/entry/hooks-react.d.cts

@@ -1 +1 @@
-export type * from './hooks-react.d.ts';
+export type * from './hooks-react.d.ts';

package/entry/index.d.cts

@@ -1 +1 @@
-export type * from './index.d.ts';
+export type * from './index.d.ts';

package/entry/math.d.cts

@@ -1 +1 @@
-export type * from './math.d.ts';
+export type * from './math.d.ts';

package/entry/types-react.d.cts

@@ -1 +1 @@
-export type * from './types-react.d.ts';
+export type * from './types-react.d.ts';

package/entry/types.d.cts

@@ -1 +1 @@
-export type * from './types.d.ts';
+export type * from './types.d.ts';

package/entry/vite.d.cts

@@ -1 +1 @@
-export type * from './vite.d.ts';
+export type * from './vite.d.ts';

package/entry/zod.d.cts

@@ -1 +1 @@
-export type * from './zod.d.ts';
+export type * from './zod.d.ts';

package/package.json

@@ -6,7 +6,7 @@
     "url": "https://github.com/pawover"
   },
   "description": "一个基于 TypeScript 的开发工具包",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "type": "module",
   "engines": {
     "node": ">=22.20.0"
@@ -158,30 +158,32 @@
     "./metadata.json": "./entry/metadata.json"
   },
   "dependencies": {
-    "@pawover/kit-eslint-rules": "0.0.0-alpha.3",
-    "@pawover/kit-hooks": "0.0.0-alpha.3",
-    "@pawover/kit-types": "0.0.0-alpha.3",
-    "@pawover/kit-utils": "0.0.0-alpha.3",
-    "@pawover/kit-zod": "0.0.0-alpha.3"
+    "@pawover/kit-eslint-rules": "0.0.0",
+    "@pawover/kit-types": "0.0.0",
+    "@pawover/kit-hooks": "0.0.0",
+    "@pawover/kit-utils": "0.0.0",
+    "@pawover/kit-zod": "0.0.0"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
     "@changesets/cli": "^3.0.0",
     "@commitlint/cli": "^21.2.1",
     "@commitlint/config-conventional": "^21.2.0",
-    "@eslint-react/eslint-plugin": "^5.18.2",
+    "@eslint-react/eslint-plugin": "^5.18.3",
     "@playwright/test": "^1.62.1",
     "@stylistic/eslint-plugin": "^6.0.0-beta.5",
     "@testing-library/react": "^16.3.2",
     "@types/fs-extra": "^11.0.4",
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",
     "@vitejs/plugin-react": "^6.0.5",
     "@vitest/browser-playwright": "^4.1.10",
     "@vitest/coverage-v8": "^4.1.10",
     "alova": "^3.5.1",
     "commitizen": "^4.3.2",
+    "cross-env": "^10.1.0",
     "cz-customizable": "^7.5.4",
-    "eslint": "^10.8.0",
+    "eslint": "^10.8.1",
     "eslint-plugin-antfu": "^3.2.3",
     "eslint-plugin-import-lite": "^0.6.0",
     "eslint-plugin-react-hooks": "^7.1.1",
@@ -194,9 +196,9 @@
     "react-dom": "19.2.6",
     "rimraf": "^6.1.3",
     "tsdown": "^0.22.14",
-    "turbo": "^2.10.8",
+    "turbo": "^2.10.9",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.66.0",
+    "typescript-eslint": "^8.67.0",
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
@@ -251,7 +253,7 @@
     "package": "pnpm pack",
     "public": "turbo build && pnpm publish --access public",
     "changeset": "changeset",
-    "ci:version": "pnpm changeset version && pnpm install",
+    "ci:version": "pnpm changeset version && node scripts/bump-root.mjs && pnpm install",
     "ci:publish": "pnpm build && pnpm changeset publish",
     "pre:enter-alpha": "pnpm changeset pre enter alpha",
     "pre:exit": "pnpm changeset pre exit",
@@ -259,7 +261,7 @@
     "check:types": "tsc --noEmit",
     "check:eslint": "eslint --fix \"**/*.{js,cjs,mjs,ts,cts,mts,jsx,tsx,vue}\" --cache-location=.cache/eslint.cache.json --cache",
     "check:format": "prettier --write \"**/*.{html,json,jsonc}\" --cache-location=.cache/prettier.cache.json --cache",
-    "check:pack": "pnpm dlx @arethetypeswrong/cli --pack . --profile node16",
+    "check:pack": "cross-env HUSKY=0 node scripts/check-pack.mjs",
     "clean": "pnpm clean:cache & pnpm clean:lib & pnpm clean:output",
     "clean:turbo": "rimraf -g **/.turbo",
     "clean:cache": "rimraf -g .cache",