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

Author: yunbowang328

.github/workflows/release.yml

@@ -27,171 +27,68 @@ jobs:
         run: |
           mkdir -p dist
           VERSION=${GITHUB_REF#refs/tags/v}
-          
-          for pair in "darwin amd64" "darwin arm64" "linux amd64" "linux arm64"; do
-            GOOS=$(echo $pair | cut -d' ' -f1)
-            GOARCH=$(echo $pair | cut -d' ' -f2)
+          MODULE="github.com/gitlink-org/gitlink-cli"
+          LDFLAGS="-s -w -X ${MODULE}/cmd.Version=${VERSION}"
+
+          for pair in \
+            "darwin amd64" \
+            "darwin arm64" \
+            "linux amd64" \
+            "linux arm64" \
+            "windows amd64" \
+            "windows arm64"; do
+            GOOS=$(echo "$pair" | cut -d' ' -f1)
+            GOARCH=$(echo "$pair" | cut -d' ' -f2)
+            OUT="gitlink-cli"
+            if [ "$GOOS" = "windows" ]; then
+              OUT="gitlink-cli.exe"
+            fi
+
             echo "Building ${GOOS}-${GOARCH}..."
-            GOOS=$GOOS GOARCH=$GOARCH go build -ldflags "-s -w -X 'github.com/gitlink-org/gitlink-cli/cmd.Version=${VERSION}'" -o dist/gitlink-cli .
-            cd dist
-            tar -czf "gitlink-cli_${VERSION}_${GOOS}_${GOARCH}.tar.gz" gitlink-cli
-            rm gitlink-cli
-            cd ..
+            BUILD_DIR="dist/gitlink-cli_${VERSION}_${GOOS}_${GOARCH}"
+            mkdir -p "$BUILD_DIR"
+            CGO_ENABLED=0 GOOS=$GOOS GOARCH=$GOARCH go build -ldflags "$LDFLAGS" -o "$BUILD_DIR/$OUT" .
+
+            if [ "$GOOS" = "windows" ]; then
+              (cd "$BUILD_DIR" && zip -q "../gitlink-cli_${VERSION}_${GOOS}_${GOARCH}.zip" "$OUT")
+            else
+              tar -czf "dist/gitlink-cli_${VERSION}_${GOOS}_${GOARCH}.tar.gz" -C "$BUILD_DIR" "$OUT"
+            fi
+            rm -rf "$BUILD_DIR"
           done
 
+          ls -lh dist
+
       - name: Create Release
         uses: softprops/action-gh-release@v2
         with:
-          files: dist/*.tar.gz
+          files: |
+            dist/*.tar.gz
+            dist/*.zip
           generate_release_notes: true
 
       - name: Build npm package
         run: |
           VERSION=${GITHUB_REF#refs/tags/v}
-          mkdir -p npm-pkg/bin npm-pkg/scripts npm-pkg/skills
-          
-          # Copy skills
-          cp -r skills/* npm-pkg/skills/
-          
-          # Copy bin wrappers
-          cp bin/cli.js npm-pkg/bin/ 2>/dev/null || cat > npm-pkg/bin/cli.js << 'NODEEOF'
-          #!/usr/bin/env node
-          const {execFileSync} = require("child_process");
-          const path = require("path");
-          const bin = path.join(__dirname, "..", "bin", "gitlink-cli");
-          try { process.exit(execFileSync(bin, process.argv.slice(2), {stdio:"inherit"}).status); }
-          catch(e) { process.exit(e.status || 1); }
-          NODEEOF
-          
-          cat > npm-pkg/bin/install-skills.js << 'NODEEOF'
-          #!/usr/bin/env node
-          const {execSync} = require("child_process");
-          const path = require("path");
-          const skillsDir = path.join(__dirname, "..", "skills");
-          try {
-            execSync(`npx skills add "${skillsDir}" -y -g`, {stdio:"inherit"});
-          } catch(e) {
-            console.error("Failed to install skills:", e.message);
-            process.exit(1);
-          }
-          NODEEOF
-          
-          # Copy install.js
-          cp scripts/install.js npm-pkg/scripts/ 2>/dev/null || cat > npm-pkg/scripts/install.js << 'NODEEOF'
-          #!/usr/bin/env node
-          "use strict";
-          const os = require("os");
-          const path = require("path");
-          const fs = require("fs");
-          const https = require("https");
-          const http = require("http");
-          const {execSync} = require("child_process");
-          
-          const PACKAGE = require("../package.json");
-          const VERSION = PACKAGE.version;
-          const BINARY_NAME = "gitlink-cli";
-          const RELEASE_BASE = "https://github.com";
-          const REPO_OWNER = "ccfos";
-          const REPO_NAME = "gitlink-cli";
-          
-          function getPlatformInfo() {
-            const platform = os.platform();
-            const arch = os.arch();
-            const pmap = {darwin:"darwin",linux:"linux",win32:"windows"};
-            const amap = {x64:"amd64",arm64:"arm64"};
-            const p=pmap[platform], a=amap[arch];
-            if(!p||!a) throw new Error(`Unsupported: ${platform}-${arch}`);
-            return {platform:p,arch:a};
-          }
-          
-          function fetch(url) {
-            return new Promise((resolve,reject) => {
-              const mod=url.startsWith("https")?https:http;
-              let count=0;
-              function req(u) {
-                if(++count>5) return reject(new Error("Too many redirects"));
-                mod.get(u,(res) => {
-                  if([301,302,307,308].includes(res.statusCode)&&res.headers.location){
-                    let loc=res.headers.location;
-                    if(loc.startsWith("/")){const p=new URL(u);loc=p.protocol+"//"+p.host+loc}
-                    return req(loc);
-                  }
-                  if(res.statusCode!==200) return reject(new Error(`HTTP ${res.statusCode}`));
-                  const c=[];res.on("data",d=>c.push(d));res.on("end",()=>resolve(Buffer.concat(c)));
-                }).on("error",reject);
-              }
-              req(url);
-            });
-          }
-          
-          async function main() {
-            try {
-              const {platform,arch} = getPlatformInfo();
-              const binDir = path.join(__dirname,"..","bin");
-              if(!fs.existsSync(binDir)) fs.mkdirSync(binDir,{recursive:true});
-              const binaryPath = path.join(binDir,BINARY_NAME);
-              
-              if(fs.existsSync(binaryPath)) {
-                try {
-                  const out = execSync(`"${binaryPath}" version`,{encoding:"utf-8",timeout:5000});
-                  if(out.includes(VERSION)) { console.log(`${BINARY_NAME} v${VERSION} already installed.`); return; }
-                } catch(e) {}
-                fs.unlinkSync(binaryPath);
-              }
-              
-              const assetName = `gitlink-cli_${VERSION}_${platform}_${arch}.tar.gz`;
-              const url = `${RELEASE_BASE}/${REPO_OWNER}/${REPO_NAME}/releases/download/v${VERSION}/${assetName}`;
-              console.log(`Downloading ${url}...`);
-              const data = await fetch(url);
-              const tmp = path.join(binDir,"dl.tar.gz");
-              fs.writeFileSync(tmp,data);
-              execSync(`tar -xzf "${tmp}" -C "${binDir}"`,{stdio:"pipe"});
-              fs.unlinkSync(tmp);
-              fs.chmodSync(binaryPath,0o755);
-              console.log(`${BINARY_NAME} v${VERSION} installed.`);
-            } catch(err) {
-              console.warn(`⚠ Binary download failed: ${err.message}`);
-              console.warn(`Skills are installed. Install binary manually:`);
-              console.warn(`npm run postinstall`);
-            }
-          }
-          main();
-          NODEEOF
-          
-          # Create README
-          cp README.md npm-pkg/
-          
-          # Create package.json
-          cat > npm-pkg/package.json << PKGEOF
-          {
-            "name": "@gitlink-ai/cli",
-            "version": "${VERSION}",
-            "description": "GitLink CLI — 面向 AI Agent 的 GitLink 命令行工具",
-            "main": "bin/cli.js",
-            "bin": {
-              "gitlink-cli": "./bin/cli.js",
-              "gitlink-cli-install-skills": "./bin/install-skills.js"
-            },
-            "scripts": {
-              "postinstall": "node scripts/install.js"
-            },
-            "files": [
-              "bin/",
-              "scripts/",
-              "skills/",
-              "README.md",
-              "package.json"
-            ],
-            "repository": {
-              "type": "git",
-              "url": "https://github.com/ccfos/gitlink-cli.git"
-            },
-            "keywords": ["gitlink", "cli", "ai-agent", "skills"],
-            "author": "",
-            "license": "MulanPSL-2.0"
-          }
-          PKGEOF
-          
+          export VERSION
+          rm -rf npm-pkg
+          mkdir -p npm-pkg
+          cp -R npm/. npm-pkg/
+          cp README.md npm-pkg/README.md
+          rm -rf npm-pkg/skills
+          cp -R skills npm-pkg/skills
+
+          node <<'NODE'
+          const fs = require('fs');
+          const pkgPath = 'npm-pkg/package.json';
+          const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+          pkg.version = process.env.VERSION;
+          fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+          NODE
+
+          chmod +x npm-pkg/bin/cli.js
+          chmod +x npm-pkg/bin/install-skills.js
+
           cd npm-pkg
           npm publish --access public
         env:

README.md

@@ -407,6 +407,16 @@ gitlink-cli auth status   # Shows "✓ Logged in via GITLINK_TOKEN environment v
 
 Priority: `GITLINK_TOKEN` env var > keyring/file stored token. When the env var is not set, the original interactive login flow works as before.
 
+### Q: What if npm installs successfully but `gitlink-cli` reports a missing binary?
+
+Reinstall first:
+
+```bash
+npm install -g @gitlink-ai/cli
+```
+
+If the error persists, check whether the release page contains the asset for your platform, for example `gitlink-cli_<version>_windows_amd64.zip` on Windows x64. You can also download the binary manually from the release page or build from source with `go install .`.
+
 ### Q: Where are credentials stored on Windows?
 
 gitlink-cli uses Windows Credential Manager for secure token storage. If Credential Manager is unavailable, it automatically falls back to file storage (`~/.config/gitlink-cli/credentials`).

README.zh-CN.md

@@ -386,6 +386,16 @@ gitlink-cli auth status   # 显示 "✓ Logged in via GITLINK_TOKEN environment
 
 Token 优先级：`GITLINK_TOKEN` 环境变量 > keyring/文件存储的 token。不设置环境变量时完全兼容原有交互式登录。
 
+### Q: npm 安装成功但 `gitlink-cli` 提示缺少二进制怎么办？
+
+先尝试重新安装：
+
+```bash
+npm install -g @gitlink-ai/cli
+```
+
+如果仍然失败，请检查 Release 页面是否包含当前平台的资产，例如 Windows x64 对应 `gitlink-cli_<version>_windows_amd64.zip`。也可以从 Release 页面手动下载二进制，或使用 `go install .` 从源码构建。
+
 ### Q: Windows 上凭证存储在哪里？
 
 gitlink-cli 使用 Windows Credential Manager 安全存储 Token。如果 Credential Manager 不可用，会自动降级到文件存储（`~/.config/gitlink-cli/credentials`）。

npm/bin/cli.js

@@ -2,21 +2,78 @@
 
 "use strict";
 
+const fs = require("fs");
 const path = require("path");
 const { execFileSync } = require("child_process");
 
-const ext = process.platform === "win32" ? ".exe" : "";
-const binaryPath = path.join(__dirname, "gitlink-cli" + ext);
+const BINARY_NAME = "gitlink-cli";
 
-try {
-  execFileSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
-} catch (err) {
-  if (err.status !== undefined) {
-    process.exit(err.status);
+function getBinaryName(platform = process.platform) {
+  return platform === "win32" ? `${BINARY_NAME}.exe` : BINARY_NAME;
+}
+
+function getBinaryPath(platform = process.platform, baseDir = __dirname) {
+  return path.join(baseDir, getBinaryName(platform));
+}
+
+function formatMissingBinaryError(
+  binaryPath,
+  platform = process.platform,
+  arch = process.arch
+) {
+  return [
+    `Error: ${BINARY_NAME} binary not found at ${binaryPath}`,
+    `Platform: ${platform}/${arch}`,
+    "",
+    "The npm package was installed, but the native binary is missing.",
+    "This usually means the release asset for your platform is unavailable or postinstall failed.",
+    "",
+    "Try reinstalling:",
+    "  npm install -g @gitlink-ai/cli",
+    "",
+    "If the problem persists, check the GitLink CLI release assets:",
+    "  https://www.gitlink.org.cn/Gitlink/gitlink-cli/releases",
+  ].join("\n");
+}
+
+function run(args = process.argv.slice(2), options = {}) {
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  const binaryPath = options.binaryPath || getBinaryPath(platform);
+  const execFile = options.execFileSync || execFileSync;
+  const stderr = options.stderr || process.stderr;
+  const exit = options.exit || process.exit;
+
+  function failMissingBinary() {
+    stderr.write(`${formatMissingBinaryError(binaryPath, platform, arch)}\n`);
+    return exit(1);
+  }
+
+  if (!fs.existsSync(binaryPath)) {
+    return failMissingBinary();
+  }
+
+  try {
+    execFile(binaryPath, args, { stdio: "inherit" });
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return failMissingBinary();
+    }
+    if (err.status !== undefined) {
+      return exit(err.status);
+    }
+    stderr.write(`Failed to run ${BINARY_NAME}: ${err.message}\n`);
+    return exit(1);
   }
-  console.error(`Failed to run gitlink-cli: ${err.message}`);
-  console.error(
-    "Binary may not be installed. Try reinstalling: npm install -g @gitlink-ai/cli"
-  );
-  process.exit(1);
 }
+
+if (require.main === module) {
+  run();
+}
+
+module.exports = {
+  getBinaryName,
+  getBinaryPath,
+  formatMissingBinaryError,
+  run,
+};

npm/bin/install-skills.js

@@ -7,7 +7,8 @@
     "gitlink-cli-install-skills": "bin/install-skills.js"
   },
   "scripts": {
-    "postinstall": "node scripts/install.js"
+    "postinstall": "node scripts/install.js",
+    "test": "node test/install.test.js && node test/cli.test.js"
   },
   "keywords": [
     "gitlink",