@namewta/speculo 0.1.0

package/speculo/skills/github-npm-ops/references/troubleshooting-playbook.md

@@ -0,0 +1,305 @@
+# Release 故障排查手册
+
+基于真实失败记录的排查流程。遇到问题先按这个顺序走。
+
+## 统一诊断流程
+
+```bash
+# 1. 找到失败的 run
+gh run list --workflow release.yml --limit 5 \
+  --json databaseId,conclusion,displayTitle
+
+# 2. 查看失败步骤的日志
+gh run view <databaseId> --log-failed 2>&1 \
+  | grep -E "npm error|npm warn publish|##\[error\]|Error:" \
+  | head -30
+
+# 3. 按下面的错误表对应修复
+```
+
+## 错误分类与修复
+
+### 1. `E404 Not Found - PUT /<pkg>`
+
+```
+npm error code E404
+npm error 404 Not Found - PUT https://registry.npmjs.org/my-cli
+npm error 404  The requested resource 'my-cli@0.0.2' could not be found
+              or you do not have permission to access it.
+```
+
+**两种原因：**
+
+- **包名被占用**：别人已注册这个名字，你没权限写入
+- **私有包但未创建 scope/org**：scope 不存在
+
+**诊断：**
+
+```bash
+npm view <pkg-name>              # 有内容说明被占
+npm owner ls <pkg-name>          # 看当前 owner
+```
+
+**修复：**
+
+- 改用 scoped 包名：`@yourname/pkg-name`
+- 同步更新 `package.json` 的 `name` 字段
+- 若要用现有名字：联系当前 owner 做 transfer，或走 `npm support`
+
+### 2. `E403 Two-factor authentication required`
+
+```
+npm error code E403
+npm error 403 403 Forbidden - PUT https://registry.npmjs.org/@scope%2fmy-cli
+              - Two-factor authentication or granular access token
+              with bypass 2fa enabled is required to publish packages.
+```
+
+**原因：** 使用了 Classic Token 或未开启 2FA bypass 的 Granular Token。
+
+**修复：**
+
+1. npm → Access Tokens → **Generate New Token** → **Granular Access Token**
+2. 勾选 **Bypass two-factor authentication**
+3. 选择目标包或 scope，permission 为 **Read and write**
+4. 复制新 token，更新 GitHub Secret `NPM_TOKEN`
+5. 重新触发 workflow（删旧 tag 重推）
+
+详见 [setup-npm-token.md](./setup-npm-token.md)。
+
+### 3. `EUSAGE Can't generate provenance for new or private package`
+
+```
+npm error code EUSAGE
+npm error Can't generate provenance for new or private package,
+          you must set `access` to public.
+```
+
+**原因：** Scoped 包默认 private，首次发布未加 `--access public`。
+
+**修复：**
+
+```yaml
+- run: npm publish --provenance --access public
+```
+
+### 4. `E422 Error verifying sigstore provenance bundle`
+
+```
+npm error code E422
+npm error 422 Unprocessable Entity - PUT https://registry.npmjs.org/@scope%2fmy-cli
+              - Error verifying sigstore provenance bundle:
+              Failed to validate repository information:
+              package.json: "repository.url" is "", expected to match
+              "https://github.com/owner/my-cli" from provenance
+```
+
+**原因：** `package.json` 缺 `repository.url`，或值与实际 GitHub 仓库不匹配。
+
+**修复：**
+
+```json
+{
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/owner/my-cli"
+  }
+}
+```
+
+- URL 不要带 `.git` 后缀也能通过（npm 会归一化）
+- 注意大小写：虽然 GitHub 不区分，但 provenance 严格校验，保持与 workflow 运行环境一致
+
+### 5. `Tag version does not match package.json version`
+
+```
+Tag version (0.0.2) does not match package.json version (0.0.1)
+```
+
+**原因：** 打 tag 前忘记 bump `package.json`，或 bump 后没 commit。
+
+**修复：**
+
+```bash
+# 删除错误 tag
+git tag -d v0.0.2
+git push origin :refs/tags/v0.0.2
+
+# 修复 package.json
+npm version 0.0.2 --no-git-tag-version    # 只改文件，不打 tag
+git add package.json && git commit -m "chore: bump version to 0.0.2"
+git push origin main
+
+# 重新打 tag
+git tag v0.0.2
+git push origin v0.0.2
+```
+
+### 6. `npm warn publish "bin[name]" script name ... was invalid and removed`
+
+```
+npm warn publish "bin[my-cli]" script name dist/cli/index.js was invalid and removed
+```
+
+**原因：** `bin` 路径没有 `./` 前缀，或 npm 版本对该路径格式敏感。
+
+**修复：** 确认 `package.json` 已经是 `"./dist/cli/index.js"`。如果已经正确但警告仍在，可能是 npm 的误报——检查 npm publish 最终有没有返回 `+ @scope/pkg@version`，有就成功了。
+
+### 7. Workflow 根本没触发
+
+**诊断：**
+
+```bash
+gh run list --workflow release.yml --limit 3
+# 如果最新的那个不在列表里，就是没触发
+```
+
+**原因：**
+
+- Tag 名不匹配 `v*` 模式
+- Tag 已存在，再次 push 被 Git 拒绝
+- 仓库关闭了 Actions
+
+**修复：**
+
+```bash
+# 确认 tag 推到远端了
+git ls-remote --tags origin | grep v0.0.2
+
+# 如果旧 tag 残留，先删
+git tag -d v0.0.2
+git push origin :refs/tags/v0.0.2
+
+# 重新打
+git tag v0.0.2
+git push origin v0.0.2
+```
+
+### 8. 安装 pnpm 或 Node 失败
+
+```
+Error: Unable to find 'pnpm' executable
+```
+
+**修复：** 在 setup 里加：
+
+```yaml
+- uses: pnpm/action-setup@v2
+  with:
+    version: 9     # 匹配 packageManager 字段或 lockfile 格式
+```
+
+如果 `package.json` 里写了 `packageManager: "pnpm@9.x.x"`，`pnpm/action-setup` 可不传 `version`，它会自动读取。
+
+### 9. `npm ERR! 403 Forbidden - PUT` 但 token 正常
+
+可能是包名大小写问题。npm 内部是小写，但 `package.json` 里写了大写：
+
+```json
+{ "name": "MyCli" }     // ❌
+{ "name": "my-cli" }    // ✅
+```
+
+### 10. GitHub Release 正文为空 / 仅一行 `Full Changelog`
+
+```
+Release v0.0.10 (Latest)
+Full Changelog: v0.0.9...v0.0.10
+[Source code (zip)] [Source code (tar.gz)]
+```
+
+**原因**：`softprops/action-gh-release@v2` 只设了 `generate_release_notes: true`，而 GitHub 自动生成器从 PR 标题 + label 抽取 changelog。直 push main 的仓库没有 PR 流量，生成器只剩 compare 链接可写。
+
+**修复（workflow 改造）**：在 Create GitHub Release 之前加一步从 `CHANGELOGS.md` 抽取段落，再用 `body_path` 注入。完整 YAML 见 [workflow-yaml-reference.md](workflow-yaml-reference.md) 的 `Extract release notes from CHANGELOGS.md` 步骤；模式说明见 [release-notes-injection.md](release-notes-injection.md)。
+
+**修复（事后回填历史 Release，无需重发版）**：
+
+```bash
+VERSION="0.0.10"
+awk -v v="$VERSION" '
+  $0 ~ "^## \\["v"\\]" { found=1; print; next }
+  found && /^## \[/ { exit }
+  found && /^---[[:space:]]*$/ { next }
+  found { print }
+' CHANGELOGS.md > /tmp/notes.md && \
+  gh release edit "v$VERSION" --notes-file /tmp/notes.md && \
+  rm /tmp/notes.md
+```
+
+**诊断**：
+
+```bash
+# Release body 长度过短就是出问题了
+gh release view v0.0.10 --json body --jq '.body | length'
+
+# workflow 里 Extract release notes 步骤是否存在并 success
+gh run view <run-id> --json jobs \
+  --jq '.jobs[].steps[] | select(.name | test("Extract|Release"))'
+```
+
+### 11. `Extract release notes` 步骤报 "release-notes.md is empty"
+
+**根因**：CHANGELOG 段落标题与 tag 不匹配，awk 抽空。
+
+**自查**：
+
+```bash
+# 实际 CHANGELOG 标题
+grep '^## \[' CHANGELOGS.md | head -5
+
+# 当前 tag 应当对应的标题
+echo "## [${GITHUB_REF_NAME#v}]"
+```
+
+常见问题：
+
+- 全角中括号 `【0.0.10】` 而非半角 `[0.0.10]`
+- 版本号有 `v` 前缀（`## [v0.0.10]`）— awk 期望去前缀的纯数字
+- 段落写错位置（`[Unreleased]` 段还没迁移到正式版本段）
+
+## 发布成功但找不到包
+
+典型场景：workflow 显示绿色，但 `npm view @scope/pkg` 返回 404。
+
+- **传播延迟**：npm CDN 有 30–60 秒缓存延迟，等一下再查
+- **日志确认**：`gh run view <id> --log | grep "+ @scope"`——有 `+ @scope/pkg@version` 才算真的成功
+- **provenance 页面**：https://search.sigstore.dev/ 能查到签名日志
+
+```bash
+# 等待 + 轮询
+for i in {1..10}; do
+  npm view @scope/my-cli version 2>/dev/null && break
+  sleep 10
+done
+```
+
+## 已发布但需要撤回
+
+npm **24 小时内**可以 `unpublish`（仅限无依赖项）：
+
+```bash
+npm unpublish @scope/my-cli@0.0.2
+```
+
+超过 24 小时或有依赖者只能 `deprecate`：
+
+```bash
+npm deprecate @scope/my-cli@0.0.2 "Security issue, use 0.0.3+"
+```
+
+**npm 不允许重发同一个 version**——即使 unpublish 过了。必须 bump 版本号。
+
+## 排查 checklist
+
+按顺序检查，90% 的问题在前三项：
+
+1. [ ] `NPM_TOKEN` 是 Granular Token、bypass 2FA、包含目标 scope 的 read+write
+2. [ ] `package.json` 有 `repository.url` 且匹配 GitHub repo
+3. [ ] Workflow 含 `permissions: id-token: write` 和 `--access public`
+4. [ ] Tag 版本与 `package.json` version 字符一致
+5. [ ] Publish step 在 Release step 之前
+6. [ ] Workflow 触发器是 `on.push.tags: ['v*']`，没写 branches
+7. [ ] `bin` 路径以 `./` 开头
+8. [ ] `files` 字段不排除构建产物
+9. [ ] **Workflow 包含 `Extract release notes from CHANGELOGS.md` 步骤，且 `Create GitHub Release` 设了 `body_path: release-notes.md`**
+10. [ ] **CHANGELOGS.md 顶部有当前版本对应的 `## [X.Y.Z]` 段落（半角中括号）**

package/speculo/skills/github-npm-ops/references/version-bump-flow.md

@@ -0,0 +1,232 @@
+# 版本 bump → release commit → tag → push 端到端 SOP
+
+把"想发个新版本"翻译成可复现的几条命令。本文档假设仓库已有 `release.yml`(`v*` tag 触发,含 release-notes 注入)。
+
+## 0. 前置检查
+
+```bash
+# 1. main 干净,没有未提交改动
+git status
+
+# 2. 当前 HEAD 与 origin/main 的关系
+git log origin/main..HEAD --oneline
+
+# 3. 上一次发布的 tag
+git tag --sort=-version:refname | head -3
+
+# 4. CHANGELOG 顶部 [Unreleased] 段落已写好本次内容
+head -30 CHANGELOGS.md
+```
+
+任意一项异常先解决再发版:工作区不干净 → 先提交或暂存;`[Unreleased]` 为空 → 先做 docs-sync。
+
+## 1. 维护 CHANGELOG
+
+`CHANGELOGS.md` 顶部必须始终保留 `[Unreleased]` 段落。新版本发布时:
+
+1. 把 `[Unreleased]` 内容**整段迁移**到新建的 `## [X.Y.Z] — YYYY-MM-DD` 标题下
+2. 重新插入空的 `[Unreleased]` 段落
+3. 在文件末尾的"版本链接"段更新 compare 链接
+
+```diff
+ ## [Unreleased]
++
++---
++
++## [0.0.10] — 2026-05-17
+
+ ### Changed
+ - ...
+```
+
+```diff
+-- [Unreleased](https://github.com/owner/repo/compare/v0.0.9...HEAD)
++- [Unreleased](https://github.com/owner/repo/compare/v0.0.10...HEAD)
++- [0.0.10](https://github.com/owner/repo/releases/tag/v0.0.10)
+ - [0.0.9](https://github.com/owner/repo/releases/tag/v0.0.9)
+```
+
+完整 CHANGELOG 契约见 [docs-sync skill](../../docs-sync/SKILL.md) 或 docs-sync 的 changelog-contract.md。
+
+## 2. bump package.json
+
+**用 `npm version` 还是手改?**
+
+| 场景 | 推荐 |
+|------|------|
+| 单一 package.json,简单 bump | `npm version <major\|minor\|patch> --no-git-tag-version` |
+| Monorepo / 多文件版本号要同步 | 手改 + `pnpm -r`(或脚本) |
+| 已写好 CHANGELOG,只想改 package.json 一处 | 手改 |
+
+`--no-git-tag-version` 的关键作用:**只改文件,不自动打 tag**。我们要把 tag 打在 release commit 上,不是在 bump 这一刻。
+
+```bash
+# 等价于手改 package.json 的 version 字段
+npm version 0.0.10 --no-git-tag-version
+```
+
+## 3. release commit(原子提交)
+
+把 `package.json` + `CHANGELOGS.md` 一并提交,使用 Conventional Commits 的 `chore(release):` 前缀。
+
+```bash
+git add package.json CHANGELOGS.md
+git commit -m "chore(release): v0.0.10" \
+           -m "迁移 [Unreleased] 段落到 0.0.10:<一两句关键变更摘要>"
+```
+
+**为什么必须是同一个 commit**:
+- tag 要精确指向这个 commit
+- workflow 的 `Verify tag matches package version` 步骤会校验该 commit 上的 `package.json` 版本与 tag 一致
+- 利于后续 `git revert` 一键回滚发布
+
+## 4. push main
+
+```bash
+git push origin main
+```
+
+push **必须先于** tag,否则远端 tag 会指向 origin 看不到的 commit,GitHub Release 创建时会找不到对应 commit 树。
+
+## 5. 打 tag 并精确指向 release commit
+
+```bash
+# 显式指定 commit SHA,避免 HEAD 已经向前移动
+RELEASE_COMMIT=$(git log -1 --format=%H --grep="^chore(release): v0.0.10")
+
+git tag v0.0.10 "$RELEASE_COMMIT"
+git push origin v0.0.10
+```
+
+**为什么要指定 SHA 而不是直接 `git tag v0.0.10`**:
+
+如果 release commit 之后又做了几笔 docs / state 推进 commit,`HEAD` 不再是 release commit。直接 `git tag` 会把 tag 打在 docs commit 上,导致:
+
+- `Verify tag matches package version` 仍然通过(版本号对得上)
+- 但 `gh release view --json targetCommitish` 指向 docs commit
+- 长远看 release tag 与"真正的发布动作"脱钩
+
+简单场景下(release commit 就是 HEAD)直接 `git tag v0.0.10` 也对,但养成显式 SHA 的习惯更稳。
+
+## 6. 监控 workflow
+
+```bash
+# 实时跟踪
+gh run watch
+
+# 或周期性查询
+gh run list --workflow release.yml --limit 3 \
+  --json databaseId,status,conclusion,displayTitle,headBranch
+```
+
+预期顺序(11 步,缺一不可):
+
+1. Set up job
+2. Checkout
+3. Setup environment
+4. **Verify tag matches package version**
+5. Run lint
+6. Run tests
+7. Build
+8. **Verify bin entry**
+9. **Extract release notes from CHANGELOGS.md** ← v1.1.0 新增
+10. **Publish to npm**
+11. **Create GitHub Release**
+
+## 7. 三端验证
+
+```bash
+# 1. npm 包已上线(CDN 30–60 秒延迟)
+npm view @scope/pkg version
+npm view @scope/pkg dist-tags
+
+# 2. GitHub Release 存在 + 正文非空
+gh release view v0.0.10 --json name,tagName,isDraft,isPrerelease,body \
+  --jq '{name, tagName, isDraft, isPrerelease, body_length: (.body | length), body_preview: (.body | .[0:200])}'
+
+# 3. workflow conclusion=success 且所有步骤 success
+gh run view <run-id> --json conclusion,jobs \
+  --jq '{conclusion, steps: [.jobs[].steps[] | {name, conclusion}]}'
+```
+
+任一缺失视为发布残次品:
+
+| 缺失项 | 修复 |
+|--------|------|
+| npm 包查不到 | 等 60 秒再查;仍无 → 看 workflow `Publish to npm` 步骤日志 |
+| Release 正文为空 / 仅一行 Full Changelog | 跑 [release-notes-injection.md](release-notes-injection.md) §3 的事后修复 |
+| workflow `Extract release notes` 失败 | CHANGELOG 标题与 tag 不匹配,核对 `## [X.Y.Z]` 是否存在 |
+
+## 8. 失败回滚
+
+### 8.1 publish 前任意步骤失败
+
+最干净:删 tag 重打。
+
+```bash
+git tag -d v0.0.10
+git push origin :refs/tags/v0.0.10
+
+# 修问题 → 重新 commit(若 release commit 也要改,用 amend)
+git commit --amend
+git push origin main --force-with-lease    # 仅当 amend 了已 push 的 commit 时
+
+# 重新打
+git tag v0.0.10 <commit-sha>
+git push origin v0.0.10
+```
+
+### 8.2 publish 已成功但后续步骤失败
+
+npm 已上线 → **不要**改版本号,只补后续动作。
+
+```bash
+# 抽取 CHANGELOG 段落
+awk -v v="0.0.10" '...' CHANGELOGS.md > /tmp/notes.md
+
+# 手动创建 GitHub Release
+gh release create v0.0.10 --notes-file /tmp/notes.md --latest
+
+# 或编辑已有 Release(如果 action 半成品创建过空 Release)
+gh release edit v0.0.10 --notes-file /tmp/notes.md
+```
+
+### 8.3 publish 失败但 npm 上其实有了(罕见)
+
+```bash
+# 确认状态
+npm view @scope/pkg@0.0.10 version
+
+# 如果有,说明上传完但 npm 返回失败码,直接当作 8.2 处理(已发,只补 Release)
+# 如果无,按 8.1 处理(重打 tag)
+```
+
+### 8.4 npm 不允许重发同一 version
+
+铁律:即使 `npm unpublish` 过,**24h 内同一版本号也不能再发**。若 publish 真上传成功但需要修代码:
+
+```bash
+# bump 到下一个补丁
+npm version 0.0.11 --no-git-tag-version
+git add package.json CHANGELOGS.md
+git commit -m "chore(release): v0.0.11"
+git push origin main
+git tag v0.0.11
+git push origin v0.0.11
+```
+
+## 9. CHECKLIST
+
+发版前过一遍:
+
+- [ ] `git status` 干净
+- [ ] CHANGELOG 顶部已迁移 `[Unreleased]` 到新版本段
+- [ ] 底部 compare 链接已更新
+- [ ] `package.json` version 与即将打的 tag 严格一致(去掉 `v` 前缀)
+- [ ] `pnpm check` 本地通过(lint + test + build)
+- [ ] `pnpm build:check-bin` 通过(若是 CLI 包)
+- [ ] release commit 已 push 到 origin/main
+- [ ] tag 指向 release commit(不是 docs commit / HEAD 漂移后的 commit)
+- [ ] tag 已 push,`gh run list` 看到 workflow 触发
+- [ ] workflow 11 步全 success
+- [ ] 三端验证齐全:npm 有 / Release body 非空 / workflow success