fix(npm): improve missing binary diagnostics #18

wangyue111 · 2026-05-19T16:56:58+08:00

wangyue111 commented

2026-05-19 16:56:58 +08:00

背景

README 声明 npm 安装支持 macOS / Linux / Windows，但如果某个发布版本缺少对应平台二进制，用户可能遇到：

npm install -g @gitlink-ai/cli 看起来成功
实际缺少 gitlink-cli / gitlink-cli.exe
执行 gitlink-cli help / gitlink-cli version 时缺少明确诊断

这会让 Windows 用户或其他缺失 release asset 的用户很难判断是 npm 包、平台二进制还是 postinstall 出了问题。

修复内容

npm runtime 诊断

npm/bin/cli.js 启动前先检查 native binary 是否存在。
缺失时输出明确错误：
- binary path
- platform / arch
- 可能原因：release asset 不存在或 postinstall 失败
- 重新安装和 release 页面提示
保留子进程真实退出码传递。
将平台二进制名和错误格式抽成可测试函数。

npm install 诊断

npm/scripts/install.js 支持传入 platform/arch 进行单元测试模拟。
安装失败时输出 expected release asset，例如：

gitlink-cli_0.1.13_windows_amd64.zip

修复 findReleaseAsset() 中 fallback 分支使用 tagName 的作用域问题。

Release workflow

.github/workflows/release.yml 增加 Windows 二进制构建：
- windows/amd64
- windows/arm64
Windows 产物打包为 .zip，非 Windows 仍为 .tar.gz。
Release 上传同时包含 dist/*.tar.gz 和 dist/*.zip。
npm 发布包不再使用 workflow 内联 fallback 脚本，而是复用仓库内 npm/ 目录中的正式 wrapper / install 脚本。

build-npm 脚本

修复 scripts/build-npm.sh 中 chmod 目标错误：
- 原来指向不存在的 npm/bin/gitlink-cli
- 现在改为 npm/bin/cli.js 和 npm/bin/install-skills.js

文档

README / README.zh-CN 增加 npm 安装成功但二进制缺失时的排查说明。

测试

本地已验证：

cd npm && npm test
GOPROXY=https://goproxy.cn,direct go test ./...
go vet ./...
node npm/bin/cli.js version
GOPROXY=https://goproxy.cn,direct ./scripts/build-npm.sh

验证结果：

Node 测试覆盖模拟 win32/x64、win32/arm64、darwin/arm64、linux/x64。
缺少 binary 时会输出明确错误，不再静默失败。
build-npm.sh 可成功构建：
- darwin_amd64.tar.gz
- darwin_arm64.tar.gz
- linux_amd64.tar.gz
- linux_arm64.tar.gz
- windows_amd64.zip
- windows_arm64.zip

不包含

本 PR 不补发历史 release asset。
本 PR 不处理 REST API Token 写操作 401 问题，该问题建议单独确认认证方式后再提独立 PR。

## 背景 README 声明 npm 安装支持 macOS / Linux / Windows，但如果某个发布版本缺少对应平台二进制，用户可能遇到： - `npm install -g @gitlink-ai/cli` 看起来成功 - 实际缺少 `gitlink-cli` / `gitlink-cli.exe` - 执行 `gitlink-cli help` / `gitlink-cli version` 时缺少明确诊断这会让 Windows 用户或其他缺失 release asset 的用户很难判断是 npm 包、平台二进制还是 postinstall 出了问题。 ## 修复内容 ### npm runtime 诊断 - `npm/bin/cli.js` 启动前先检查 native binary 是否存在。 - 缺失时输出明确错误： - binary path - platform / arch - 可能原因：release asset 不存在或 postinstall 失败 - 重新安装和 release 页面提示 - 保留子进程真实退出码传递。 - 将平台二进制名和错误格式抽成可测试函数。 ### npm install 诊断 - `npm/scripts/install.js` 支持传入 platform/arch 进行单元测试模拟。 - 安装失败时输出 expected release asset，例如： ```text gitlink-cli_0.1.13_windows_amd64.zip ``` - 修复 `findReleaseAsset()` 中 fallback 分支使用 `tagName` 的作用域问题。 ### Release workflow - `.github/workflows/release.yml` 增加 Windows 二进制构建： - `windows/amd64` - `windows/arm64` - Windows 产物打包为 `.zip`，非 Windows 仍为 `.tar.gz`。 - Release 上传同时包含 `dist/*.tar.gz` 和 `dist/*.zip`。 - npm 发布包不再使用 workflow 内联 fallback 脚本，而是复用仓库内 `npm/` 目录中的正式 wrapper / install 脚本。 ### build-npm 脚本 - 修复 `scripts/build-npm.sh` 中 chmod 目标错误： - 原来指向不存在的 `npm/bin/gitlink-cli` - 现在改为 `npm/bin/cli.js` 和 `npm/bin/install-skills.js` ### 文档 - README / README.zh-CN 增加 npm 安装成功但二进制缺失时的排查说明。 ## 测试本地已验证： ```bash cd npm && npm test GOPROXY=https://goproxy.cn,direct go test ./... go vet ./... node npm/bin/cli.js version GOPROXY=https://goproxy.cn,direct ./scripts/build-npm.sh ``` 验证结果： - Node 测试覆盖模拟 `win32/x64`、`win32/arm64`、`darwin/arm64`、`linux/x64`。 - 缺少 binary 时会输出明确错误，不再静默失败。 - `build-npm.sh` 可成功构建： - `darwin_amd64.tar.gz` - `darwin_arm64.tar.gz` - `linux_amd64.tar.gz` - `linux_arm64.tar.gz` - `windows_amd64.zip` - `windows_arm64.zip` ## 不包含 - 本 PR 不补发历史 release asset。 - 本 PR 不处理 REST API Token 写操作 401 问题，该问题建议单独确认认证方式后再提独立 PR。

wangyue111 added 1 commit 2026-05-19 16:56:59 +08:00

cdca68ff3e fix(npm): improve missing binary diagnostics

wbtiger merged commit fde322669a into master

2026-05-19 22:29:30 +08:00

wbtiger referenced this issue from a commit

2026-05-19 22:29:32 +08:00

Merge pull request 'fix(npm): improve missing binary diagnostics' (#18) from wangyue111/gitlink-cli:fix/npm-missing-binary-diagnostics into master

dtwdtw referenced this pull request

2026-05-26 17:37:15 +08:00

fix(issue): preserve metadata during updates #51

dtwdtw referenced this pull request

2026-06-08 12:02:44 +08:00