@namewta/speculo 1.0.19 → 1.0.21

package/template/skills/github-npm-ops/references/setup-npm-token.md

@@ -1,63 +0,0 @@
-# 配置 npm Token 与 GitHub Secret
-
-npm 现在强制要求发布时通过 2FA 或等效机制。Classic token 在多数账号设置下会返回 `E403`，必须改用 **Granular Access Token**。
-
-## 生成 Granular Access Token
-
-1. 登录 [npmjs.com](https://www.npmjs.com)，点头像 → **Access Tokens**
-2. 点 **Generate New Token** → 选择 **Granular Access Token**
-3. 关键字段：
-
-   | 字段                    | 推荐值                                                                                     |
-   | ----------------------- | ------------------------------------------------------------------------------------------ |
-   | Token name              | `<package>-ci-release`（可识别用途）                                                       |
-   | Expiration              | 90–365 天；设提醒到期前轮换                                                                 |
-   | Packages and scopes     | 选 `Only select packages and scopes`，勾选目标包或整个 scope（如 `@scope`）                |
-   | Permissions             | **Read and write**                                                                         |
-   | Allowed organizations   | 如果在组织下发布，勾选对应组织                                                             |
-   | Bypass two-factor auth  | 勾选（CI 无法交互完成 2FA）                                                                |
-   | Allowed IP ranges       | 留空（GitHub Actions runner IP 不固定）                                                    |
-
-4. 点 **Generate**，**立刻复制** token，关掉页面就再也看不到了
-
-## 配置到 GitHub Secret
-
-1. 仓库 → **Settings** → **Secrets and variables** → **Actions**
-2. 点 **New repository secret**
-3. `Name: NPM_TOKEN`，`Value: <粘贴 token>`
-4. 点 **Add secret**
-
-## 在 workflow 中引用
-
-```yaml
-- name: Publish to npm
-  run: npm publish --provenance --access public
-  env:
-    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-```
-
-重点：变量名必须是 `NODE_AUTH_TOKEN`（`actions/setup-node` 约定），不是 `NPM_TOKEN`。Secret 的名字可以是 `NPM_TOKEN`，但要映射过来。
-
-## 验证 token 生效
-
-本地不需要这个 token，它只在 CI 使用。如果想本地预演：
-
-```bash
-echo "//registry.npmjs.org/:_authToken=<token>" >> ~/.npmrc
-npm whoami   # 应返回你的 npm 用户名
-npm publish --dry-run --access public
-```
-
-预演完记得把 `.npmrc` 里的这行删掉。
-
-## 轮换策略
-
-- Token 到期前 7 天收到邮件提醒
-- 轮换步骤：生成新 token → 更新 GitHub Secret → 在 npm 上 revoke 旧 token
-- 如果怀疑泄露：立即在 npm Access Tokens 页面点 **Revoke**，workflow 会在下次运行时失败，再补生成新 token
-
-## 常见误区
-
-- **不要用 Classic Token 的 `Automation` 类型** — 某些账号策略下仍会触发 2FA 检查
-- **不要把 token 写进 `.npmrc` 提交** — 只能走 `secrets`
-- **不要与个人 publish token 混用** — CI 用专用 token，出问题可独立撤销

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

@@ -1,293 +0,0 @@
-# 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 之前加一步从 `CHANGELOG.md` 抽取段落，再用 `body_path` 注入。完整 YAML 见 [workflow-yaml-reference.md](workflow-yaml-reference.md) 的 `Extract release notes from CHANGELOG.md` 步骤；模式说明见 [release-notes-injection.md](release-notes-injection.md)。
-
-**修复（事后回填历史 Release，无需重发版）**：按 [release-notes-injection.md](release-notes-injection.md) 抽取 CHANGELOG 段落，再 `gh release edit "v$VERSION" --notes-file "$notes_file"`。
-
-**诊断**：
-
-```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 '^## \[' CHANGELOG.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 CHANGELOG.md` 步骤，且 `Create GitHub Release` 设了 `body_path: release-notes.md`**
-10. [ ] **CHANGELOG.md 顶部有当前版本对应的 `## [X.Y.Z]` 段落（半角中括号）**

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

@@ -1,217 +0,0 @@
-# 版本 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 CHANGELOG.md
-```
-
-任意一项异常先解决再发版：工作区不干净 → 先提交，或调用 docs-sync 按其清洁契约处理；`[Unreleased]` 为空 → 先做 docs-sync。禁止用 stash 隐藏待发布改动。
-
-## 1. 维护 CHANGELOG
-
-`CHANGELOG.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 契约见 `<Path>{roots.skills}/docs-sync/references/changelog-contract.md</Path>`。
-
-## 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` + `CHANGELOG.md` 一并提交,使用 Conventional Commits 的 `chore(release):` 前缀。
-
-```bash
-git add package.json CHANGELOG.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 CHANGELOG.md** ← v1.1.0 新增
-10. **Publish to npm**
-11. **Create GitHub Release**
-
-## 7. 三端验证
-
-完整命令与判定见 [release-pipeline.md](release-pipeline.md) Phase 5（`npm view` / `gh release view` / `gh run view`）。任一缺失视为发布残次品；Release 正文为空时按 [release-notes-injection.md](release-notes-injection.md) 事后修复。
-
-## 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 已上线 → **不要**改版本号,只补后续动作。
-
-下面的 `notes_file` 只是一次性传给 `gh --notes-file` 的中间文件；若需要保留发布摘要或 release notes，由调用方写入 `<Path>{roots.state}/commands/{command}/{date}-{scope}-{topic}[-NN].md</Path>`。
-
-```bash
-notes_file="$(mktemp -t speculo-release-notes.XXXXXX)"
-trap 'rm -f "$notes_file"' EXIT
-
-# 抽取 CHANGELOG 段落
-awk -v v="0.0.10" '...' CHANGELOG.md > "$notes_file"
-
-# 手动创建 GitHub Release
-gh release create v0.0.10 --notes-file "$notes_file" --latest
-
-# 或编辑已有 Release(如果 action 半成品创建过空 Release)
-gh release edit v0.0.10 --notes-file "$notes_file"
-```
-
-### 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 CHANGELOG.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