From bdbcf62a7b17939f07185adc59461c6dfb860554 Mon Sep 17 00:00:00 2001 From: hermes Date: Fri, 16 Oct 2026 04:40:40 +0000 Subject: [PATCH] fix(npm): install the binary on first run when postinstall was skipped npm 12 blocks install scripts of unapproved packages under `npx` and `npm install -g` (its allow-scripts policy). The postinstall download never ran, so `npx -y idx-mcp` exited with "installed binary not found" and MCP clients saw only "Connection closed". Hermes Agent hits this by default: it runs a bare `npx` with its own npm 12. The launcher now runs the installer itself when the binary is missing, logging to stderr so the idx-mcp stdout channel stays clean. This also covers pnpm 10+ and bun, which skip dependency scripts by default. npm-smoke installs idx-mcp with --ignore-scripts and checks that the first run still starts cleanly. Fixes #41 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WB13omP6h7YeyJx7GNtUnF --- README.md | 5 ++--- docs/NPM_DISTRIBUTION.md | 21 ++++++++++++++------- scripts/idx.js | 11 ++++++++++- scripts/npm-smoke.sh | 17 ++++++++++++++++- web/src/content/docs/start/install.mdx | 5 ++--- 5 files changed, 44 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 1313308..f4bf29a 100644 --- a/README.md +++ b/README.md @@ -23,9 +23,8 @@ npm install --global idx-cli ``` The npm package downloads the same checksum-verified release binary during -`postinstall`. pnpm 10+ and bun skip install scripts by default; allow them -with `pnpm add --global --allow-build=idx-cli idx-cli` or -`bun add --global --trust idx-cli`. See +`postinstall`, or on first run when the package manager skips install scripts +(npm 12 under `npx`, pnpm 10+, bun). See [docs/NPM_DISTRIBUTION.md](docs/NPM_DISTRIBUTION.md). Prebuilt binaries cover Linux x64/arm64 (static musl) and macOS arm64/x64. diff --git a/docs/NPM_DISTRIBUTION.md b/docs/NPM_DISTRIBUTION.md index 6a218e1..0f46d3d 100644 --- a/docs/NPM_DISTRIBUTION.md +++ b/docs/NPM_DISTRIBUTION.md @@ -43,11 +43,16 @@ version `0.3.1` downloads assets from the `v0.3.1` GitHub Release. The postinstall script downloads `SHA256SUMS` from the same release and refuses to install a binary whose checksum does not match. -### pnpm and bun +### When postinstall does not run -pnpm 10+ and bun do not run dependency lifecycle scripts by default, so the -binary is never downloaded and `idx` reports that it is missing. Allow the -postinstall script explicitly: +npm 12 blocks install scripts of unapproved packages under `npx` and +`npm install -g` (its `allow-scripts` policy), and pnpm 10+ and bun skip +dependency lifecycle scripts by default. The launcher then runs the installer +itself on first start, logging to stderr so the `idx-mcp` stdout channel stays +clean; it fails only when that download fails too. Hermes Agent runs `npx` with +its own npm 12, which is how 0.3.1 broke there (issue #41). + +To install the binary up front instead, allow the script explicitly: ```bash # pnpm @@ -55,15 +60,17 @@ pnpm add --global --allow-build=idx-cli idx-cli # bun bun add --global --trust idx-cli -``` -Plain `npm install` and `npx` run the postinstall script normally. +# npm 12 +npm install --global --allow-scripts=idx-cli idx-cli +``` ## Local smoke test The smoke script builds or reuses `target/release/idx`, packs the npm wrapper, installs the tarball into a new temporary directory, and runs the installed -`idx` command. It uses `IDX_BINARY_URL` with a local `file:` URL, so the test +`idx` command, then installs `idx-mcp` again with `--ignore-scripts` to check +the launcher's first-run install. It uses `IDX_BINARY_URL` with a local `file:` URL, so the test does not need a registry publish or a network download. ```bash diff --git a/scripts/idx.js b/scripts/idx.js index 86006ef..50232d8 100755 --- a/scripts/idx.js +++ b/scripts/idx.js @@ -3,7 +3,7 @@ const fs = require("node:fs"); const path = require("node:path"); -const { spawn } = require("node:child_process"); +const { spawn, spawnSync } = require("node:child_process"); const packageManifest = JSON.parse( fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8"), @@ -13,6 +13,15 @@ const packageName = packageManifest.name; const binaryName = process.platform === "win32" ? `${nativeBinary}.exe` : nativeBinary; const binaryPath = path.join(__dirname, "..", "bin", binaryName); +// postinstall never ran (ignore-scripts) or its download failed: install now. +// Its log goes to stderr, since stdout is the MCP channel for idx-mcp. +if (!fs.existsSync(binaryPath)) { + console.error(`${packageName}: binary not installed; running the installer`); + spawnSync(process.execPath, [path.join(__dirname, "install.js")], { + stdio: ["ignore", 2, 2], + }); +} + if (!fs.existsSync(binaryPath)) { console.error(`${packageName}: installed binary not found at ${binaryPath}`); console.error(`${packageName}: rerun npm install or set IDX_BINARY_URL for a local binary`); diff --git a/scripts/npm-smoke.sh b/scripts/npm-smoke.sh index a39301b..d09ea0a 100755 --- a/scripts/npm-smoke.sh +++ b/scripts/npm-smoke.sh @@ -80,4 +80,19 @@ mkdir -p "$npm_cache" smoke_package "$repo_root" idx "Usage: idx" "${smoke_dir}/idx/install/node_modules/.bin/idx" config --help >/dev/null smoke_package "${repo_root}/npm/idx-mcp" idx-mcp "Usage: idx-mcp" -echo "npm smoke: PASS (idx-cli and idx-mcp: pack, install, --help)" + +# Without postinstall (ignore-scripts, or a failed download) the wrapper +# installs the binary on first run, logging only to stderr: stdout is the MCP +# channel, and a client sees an early exit as "Connection closed". +echo "npm smoke: installing idx-mcp with --ignore-scripts" +no_scripts_dir="${smoke_dir}/idx-mcp-no-scripts" +npm_config_cache="$npm_cache" npm install --prefix "$no_scripts_dir" "${smoke_dir}"/idx-mcp/idx-mcp-*.tgz \ + --no-save --no-package-lock --no-audit --no-fund --ignore-scripts +IDX_BINARY_URL="${repo_root}/target/release/idx-mcp" \ + "${no_scripts_dir}/node_modules/.bin/idx-mcp" --help > "${smoke_dir}/no-scripts-help.txt" +if ! head -n 1 "${smoke_dir}/no-scripts-help.txt" | grep -q "MCP server"; then + echo "npm smoke: idx-mcp without postinstall did not start cleanly:" >&2 + cat "${smoke_dir}/no-scripts-help.txt" >&2 + exit 1 +fi +echo "npm smoke: PASS (idx-cli and idx-mcp: pack, install, --help; idx-mcp without postinstall)" diff --git a/web/src/content/docs/start/install.mdx b/web/src/content/docs/start/install.mdx index 6c3dfa4..6a51ee5 100644 --- a/web/src/content/docs/start/install.mdx +++ b/web/src/content/docs/start/install.mdx @@ -25,9 +25,8 @@ npx idx-cli --help # or run without installing ``` The package downloads the checksum-verified release binary during -`postinstall`. pnpm 10+ and bun skip install scripts by default; allow them -with `pnpm add --global --allow-build=idx-cli idx-cli` or -`bun add --global --trust idx-cli`. +`postinstall`, or on first run when the package manager skips install scripts +(npm 12 under `npx`, pnpm 10+, bun).