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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WB13omP6h7YeyJx7GNtUnF

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
+`postinstall`, or on first run when the package manager skips install scripts
-with `pnpm add --global --allow-build=idx-cli idx-cli` or
+(npm 12 under `npx`, pnpm 10+, bun). See
-`bun add --global --trust idx-cli`. See
 [docs/NPM_DISTRIBUTION.md](docs/NPM_DISTRIBUTION.md).
 
 Prebuilt binaries cover Linux x64/arm64 (static musl) and macOS arm64/x64.

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
+npm 12 blocks install scripts of unapproved packages under `npx` and
-binary is never downloaded and `idx` reports that it is missing. Allow the
+`npm install -g` (its `allow-scripts` policy), and pnpm 10+ and bun skip
-postinstall script explicitly:
+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

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`);

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)"

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
+`postinstall`, or on first run when the package manager skips install scripts
-with `pnpm add --global --allow-build=idx-cli idx-cli` or
+(npm 12 under `npx`, pnpm 10+, bun).
-`bun add --global --trust idx-cli`.
 
 </TabItem>
 <TabItem label="Install script">