ci(release): fix app token git auth recovery

- Use a Basic x-access-token git auth header for App token git pushes.

- Allow manual recovery of the current npm latest version after partial release.

- Document the recovery path and cover the workflow/version policy with tests.

- Verified with targeted tests, full tests, lint, build, format, and actionlint.

Author: 529951164

.github/workflows/release.yml

@@ -493,7 +493,8 @@ jobs:
         env:
           GH_TOKEN: ${{ steps.write-app-token.outputs.token }}
         run: |
-          git config --local http.https://github.com/.extraheader "AUTHORIZATION: bearer ${GH_TOKEN}"
+          GIT_AUTH_HEADER=$(printf "x-access-token:%s" "$GH_TOKEN" | base64 | tr -d '\n')
+          git config --local http.https://github.com/.extraheader "AUTHORIZATION: basic ${GIT_AUTH_HEADER}"
 
       - name: Resolve existing release PR
         id: release_pr
@@ -778,7 +779,8 @@ jobs:
           MERGE_COMMIT=${{ steps.wait_for_merge.outputs.merge_commit }}
 
           # PR 已合并，检出该 release PR 的 merge commit，避免 main 后续推进影响 tag 目标。
-          git config --local http.https://github.com/.extraheader "AUTHORIZATION: bearer ${GH_TOKEN}"
+          GIT_AUTH_HEADER=$(printf "x-access-token:%s" "$GH_TOKEN" | base64 | tr -d '\n')
+          git config --local http.https://github.com/.extraheader "AUTHORIZATION: basic ${GIT_AUTH_HEADER}"
           git fetch origin main
           git checkout -B main "$MERGE_COMMIT"
           git config user.name "github-actions[bot]"

docs/RELEASE_PR_GUARDS.md

@@ -235,6 +235,16 @@ GitHub App installation token 有固定有效期。release job 等待 PR 合并
 同理，lint、build、test 和 npm publish 完成后，创建 release 分支、PR 和 auto-merge 前也
 需要重新生成 write token，并刷新 Git 的 auth header，缩短 token 实际使用窗口。
 
+GitHub App token 同时会被 `gh` 和 `git` 使用，但两者的认证形态不同：
+
+- `gh` 命令通过 `GH_TOKEN` 使用 token。
+- `git push` / `git fetch` 使用 HTTPS Git 凭据，需要配置成 Basic auth header，
+  即 `x-access-token:<token>` 的 base64 形式。
+
+不要把 Git 的 `http.https://github.com/.extraheader` 配置成 `AUTHORIZATION: bearer ...`。
+这种写法可能让 `gh` API 正常工作，但 HTTPS Git push 会在认证阶段失败，表现为
+`could not read Username for 'https://github.com'`。
+
 ### 6.5 增强 release job 的可恢复性
 
 release job 应允许在超时或中断后重跑：
@@ -249,6 +259,9 @@ release job 应允许在超时或中断后重跑：
 - 如果 release PR 仍是 OPEN 且已经启用 auto-merge，重跑时直接复用该状态，不重复调用
   `gh pr merge --auto` 导致失败。
 - 如果 npm 版本已经存在，校验并重置 `latest` dist-tag，不重复发布。
+- 如果 npm 已发布但 release 分支、release PR、tag 或 GitHub Release 还没有完成，维护者
+  可以手动重跑主包 release workflow，并显式输入当前 npm latest 版本继续恢复。此时 workflow
+  不应自动递增到下一个 patch，也不应因为 npm 上已有该版本而提前失败。
 - 如果 tag 或 GitHub Release 已经存在，校验或补充 assets，不重复创建。
 
 这样 release PR 检查较慢时，不需要新建第二个 workflow。维护者可以在同一个 release PR

scripts/resolve-main-release-version.js

@@ -113,9 +113,9 @@ function resolveManualVersion(currentVersion) {
   const version = readEnv('MAIN_MANUAL_VERSION').trim();
   assertStableVersion(version);
 
-  if (compareStableVersions(version, currentVersion) <= 0) {
+  if (compareStableVersions(version, currentVersion) < 0) {
     throw new Error(
-      `Manual target version ${version} must be greater than current online latest ${currentVersion}.`
+      `Manual target version ${version} must be greater than or equal to current online latest ${currentVersion}.`
     );
   }
 
@@ -142,7 +142,7 @@ function main() {
     ? resolveManualVersion(currentVersion)
     : resolveAutoVersion(currentVersion, publishedVersions);
 
-  if (npmVersionExists(version)) {
+  if (!manualVersion && npmVersionExists(version)) {
     throw new Error(`${PACKAGE_NAME}@${version} already exists on npm.`);
   }
 

src/__tests__/mainReleaseVersionPolicy.test.ts

@@ -106,6 +106,34 @@ describe('main package release version policy', () => {
     expect(result.stdout).toContain('Major/minor changed: true');
   });
 
+  it('allows manual recovery of the current npm latest version', () => {
+    const fakeBin = createFakeNpm('1.24.11');
+    const result = runResolver({
+      PATH: fakeBin,
+      GITHUB_REF_NAME: 'main',
+      MAIN_MANUAL_VERSION: '1.24.11',
+    });
+
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain('Resolved @taptap/instant-games-open-mcp version: 1.24.11');
+    expect(result.stdout).toContain('Version mode: manual');
+    expect(result.stdout).toContain('Major/minor changed: false');
+  });
+
+  it('rejects manual versions below the current npm latest version', () => {
+    const fakeBin = createFakeNpm('1.24.11');
+    const result = runResolver({
+      PATH: fakeBin,
+      GITHUB_REF_NAME: 'main',
+      MAIN_MANUAL_VERSION: '1.24.10',
+    });
+
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain(
+      'Manual target version 1.24.10 must be greater than or equal to current online latest 1.24.11.'
+    );
+  });
+
   it('rejects latest publishing outside main', () => {
     const fakeBin = createFakeNpm('1.24.5');
     const result = runResolver({

src/__tests__/releaseWorkflowGuards.test.ts

@@ -130,7 +130,7 @@ describe('release PR required workflow guards', () => {
       "if: success() && steps.wait_for_merge.outputs.state == 'MERGED'"
     );
     expect(releaseStep).toContain('GH_TOKEN: ${{ steps.final-app-token.outputs.token }}');
-    expect(releaseStep).toContain('AUTHORIZATION: bearer ${GH_TOKEN}');
+    expect(releaseStep).toContain('AUTHORIZATION: basic ${GIT_AUTH_HEADER}');
     expect(releaseStep).not.toContain('for i in $(seq 1 360)');
   });
 
@@ -148,7 +148,9 @@ describe('release PR required workflow guards', () => {
 
     const configureStep = getStepBody(workflow, 'Configure release write app token');
     expect(configureStep).toContain('GH_TOKEN: ${{ steps.write-app-token.outputs.token }}');
-    expect(configureStep).toContain('AUTHORIZATION: bearer ${GH_TOKEN}');
+    expect(configureStep).toContain('x-access-token:%s');
+    expect(configureStep).toContain('AUTHORIZATION: basic ${GIT_AUTH_HEADER}');
+    expect(configureStep).not.toContain('AUTHORIZATION: bearer');
 
     for (const stepName of [
       'Resolve existing release PR',