nano-brain 2026.7.1102 → 2026.7.1104

package/README.md

@@ -8,6 +8,7 @@ Agent-oriented memory and code intelligence over MCP. AI agents don't read docs
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![GitHub](https://img.shields.io/badge/GitHub-nano--step%2Fnano--brain-181717?logo=github)](https://github.com/nano-step/nano-brain)
 [![npm](https://img.shields.io/badge/npm-@nano--step%2Fnano--brain-CC3533?logo=npm)](https://www.npmjs.com/package/@nano-step/nano-brain)
+[![npm downloads](https://img.shields.io/npm/dw/@nano-step/nano-brain?logo=npm&label=downloads)](https://www.npmjs.com/package/@nano-step/nano-brain)
 [![Docker](https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=white)](https://hub.docker.com/r/nano-step/nano-brain)
 [![Discord](https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/nano-brain)
 

package/npm/postinstall.js

@@ -6,7 +6,7 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 const crypto = require("crypto");
-const { execSync } = require("child_process");
+const { execFileSync } = require("child_process");
 
 const VERSION = require("../package.json").version;
 const REPO = "nano-step/nano-brain";
@@ -24,34 +24,69 @@ function getPlatformKey() {
   const platform = PLATFORM_MAP[os.platform()];
   const arch = ARCH_MAP[os.arch()];
   if (!platform || !arch) {
-    console.error(`Unsupported platform: ${os.platform()}-${os.arch()}`);
-    console.error("Build from source: CGO_ENABLED=0 go build -o nano-brain ./cmd/nano-brain");
-    process.exit(0);
+    // Throw (do not process.exit) so ensureBinary's "throws, never exits"
+    // contract holds: main() turns this into a non-fatal install exit(0),
+    // run.js reports it and exits 1 (#594).
+    throw new Error(`Unsupported platform: ${os.platform()}-${os.arch()}`);
   }
   return `${platform}-${arch}`;
 }
 
+// Remove a partial download without throwing. A socket error can fire before
+// createWriteStream has opened the file, or after a redirect branch already
+// removed it — an unguarded fs.unlinkSync then throws ENOENT *inside* the
+// event callback, which is uncaught and crashes the whole postinstall (#592).
+function safeUnlink(p) {
+  // No existsSync pre-check: the try/catch already swallows ENOENT, and a
+  // check-then-unlink is a TOCTOU race. Best-effort cleanup.
+  try {
+    fs.unlinkSync(p);
+  } catch (_) {
+    /* best-effort cleanup */
+  }
+}
+
+// file.close() is asynchronous; the fd is only released when its callback
+// fires. Every unlink / recursive-redirect / reject is therefore deferred into
+// file.close(() => …) so the partial file is gone (and not re-opened by a
+// racing redirect) before we act — otherwise Windows unlink fails with EPERM
+// while the fd is open, and a raw request error would leak the write stream.
 function download(url, dest) {
   return new Promise((resolve, reject) => {
     const file = fs.createWriteStream(dest);
     https.get(url, (res) => {
       if (res.statusCode === 301 || res.statusCode === 302) {
-        file.close();
-        fs.unlinkSync(dest);
-        return download(res.headers.location, dest).then(resolve).catch(reject);
+        file.close(() => {
+          safeUnlink(dest);
+          download(res.headers.location, dest).then(resolve).catch(reject);
+        });
+        return;
       }
       if (res.statusCode !== 200) {
-        file.close();
-        fs.unlinkSync(dest);
-        return reject(new Error(`Download failed: HTTP ${res.statusCode}`));
+        file.close(() => {
+          safeUnlink(dest);
+          reject(new Error(`Download failed: HTTP ${res.statusCode}`));
+        });
+        return;
       }
       res.pipe(file);
+      // pipe() does NOT forward source 'error' events; without this a socket
+      // reset mid-transfer emits an unhandled 'error' on res and crashes the
+      // postinstall (#592) — mirror downloadWithHash's handler.
+      res.on("error", (err) => {
+        file.close(() => {
+          safeUnlink(dest);
+          reject(err);
+        });
+      });
       file.on("finish", () => {
         file.close(resolve);
       });
     }).on("error", (err) => {
-      fs.unlinkSync(dest);
-      reject(err);
+      file.close(() => {
+        safeUnlink(dest);
+        reject(err);
+      });
     });
   });
 }
@@ -62,14 +97,18 @@ function downloadWithHash(url, dest) {
     const hash = crypto.createHash("sha256");
     https.get(url, (res) => {
       if (res.statusCode === 301 || res.statusCode === 302) {
-        file.close();
-        fs.unlinkSync(dest);
-        return downloadWithHash(res.headers.location, dest).then(resolve).catch(reject);
+        file.close(() => {
+          safeUnlink(dest);
+          downloadWithHash(res.headers.location, dest).then(resolve).catch(reject);
+        });
+        return;
       }
       if (res.statusCode !== 200) {
-        file.close();
-        fs.unlinkSync(dest);
-        return reject(new Error(`Download failed: HTTP ${res.statusCode}`));
+        file.close(() => {
+          safeUnlink(dest);
+          reject(new Error(`Download failed: HTTP ${res.statusCode}`));
+        });
+        return;
       }
       res.on("data", (chunk) => hash.update(chunk));
       res.pipe(file);
@@ -77,13 +116,16 @@ function downloadWithHash(url, dest) {
         file.close(() => resolve(hash.digest("hex")));
       });
       res.on("error", (err) => {
-        file.close();
-        if (fs.existsSync(dest)) fs.unlinkSync(dest);
-        reject(err);
+        file.close(() => {
+          safeUnlink(dest);
+          reject(err);
+        });
       });
     }).on("error", (err) => {
-      if (fs.existsSync(dest)) fs.unlinkSync(dest);
-      reject(err);
+      file.close(() => {
+        safeUnlink(dest);
+        reject(err);
+      });
     });
   });
 }
@@ -110,9 +152,7 @@ async function verifySHA256(tag, assetName, binPath, computedHex) {
     console.warn(`⚠ SHA256SUMS not available for ${tag} (${err.message}); skipping integrity verification.`);
     return;
   } finally {
-    if (fs.existsSync(sumsPath)) {
-      try { fs.unlinkSync(sumsPath); } catch (_) {}
-    }
+    safeUnlink(sumsPath);
   }
 
   const expectedHex = parseSHA256Line(sumsContent, assetName);
@@ -122,7 +162,10 @@ async function verifySHA256(tag, assetName, binPath, computedHex) {
   }
 
   if (expectedHex.toLowerCase() !== computedHex.toLowerCase()) {
-    if (fs.existsSync(binPath)) fs.unlinkSync(binPath);
+    // safeUnlink so an unrelated fs error (e.g. EACCES) can't turn a SHA
+    // mismatch into a non-"SECURITY:" rejection that main() would treat as a
+    // retryable download failure, bypassing the hard-fail fail-safe.
+    safeUnlink(binPath);
     throw new Error(
       `SECURITY: SHA-256 mismatch for ${assetName}\n` +
       `  expected: ${expectedHex}\n` +
@@ -225,84 +268,106 @@ function tryAutoLink(srcBinPath, platform) {
   }
 }
 
-async function main() {
-  const platformKey = getPlatformKey();
+function binaryPath() {
   const binName = os.platform() === "win32" ? "nano-brain.exe" : "nano-brain";
-  const binPath = path.join(__dirname, binName);
+  return path.join(__dirname, binName);
+}
+
+// Download-and-verify the platform binary to binaryPath() and return that path.
+// THROWS on failure (never calls process.exit) so both the install-time caller
+// (main) and the run-time caller (run.js) can choose their own exit behavior.
+// A "SECURITY:"-prefixed error signals an integrity failure that must hard-fail.
+// Progress goes to stderr so it never pollutes a command's stdout when run.js
+// downloads lazily on first invocation (#594).
+async function ensureBinary() {
+  const platformKey = getPlatformKey();
+  const binPath = binaryPath();
 
   const skipVerify = !!process.env.NANO_BRAIN_SKIP_SHA_VERIFY;
   if (skipVerify) {
-    console.warn("⚠ NANO_BRAIN_SKIP_SHA_VERIFY is set; binary integrity check will be skipped.");
+    console.error("⚠ NANO_BRAIN_SKIP_SHA_VERIFY is set; binary integrity check will be skipped.");
   }
 
   if (fs.existsSync(binPath)) {
     try {
-      const output = execSync(`"${binPath}" version --json`, { timeout: 5000 }).toString();
+      const output = execFileSync(binPath, ["version", "--json"], { timeout: 5000 }).toString();
       if (output.includes(VERSION)) {
-        console.log(`nano-brain v${VERSION} already installed.`);
-        return;
+        return binPath;
       }
-    } catch {
-      // Wrong version or can't run — redownload
+      console.error("Existing nano-brain binary is a different version; re-downloading.");
+    } catch (err) {
+      console.error(`Existing nano-brain binary failed verification (${err.message}); re-downloading.`);
     }
+    // Reached only when the existing binary is stale/broken. Unlink before
+    // overwriting: a running process keeps its handle to the old inode, so
+    // this avoids ETXTBSY on re-download (Linux/macOS).
+    safeUnlink(binPath);
   }
 
-  console.log(`Downloading nano-brain v${VERSION} for ${platformKey}...`);
+  console.error(`Downloading nano-brain v${VERSION} for ${platformKey}...`);
 
   const assetName = `nano-brain-${platformKey}`;
   let lastErr;
-  for (const tag of candidateTagsForVersion(VERSION)) {
+
+  const attempt = async (tag, suffix) => {
     const url = `https://github.com/${REPO}/releases/download/${tag}/${assetName}`;
+    if (skipVerify) {
+      await download(url, binPath);
+    } else {
+      const computedHex = await downloadWithHash(url, binPath);
+      await verifySHA256(tag, assetName, binPath, computedHex);
+    }
+    fs.chmodSync(binPath, 0o755);
+    console.error(`nano-brain v${VERSION} installed successfully from ${tag}${suffix || ""}.`);
+    return binPath;
+  };
+
+  for (const tag of candidateTagsForVersion(VERSION)) {
     try {
-      if (skipVerify) {
-        await download(url, binPath);
-      } else {
-        const computedHex = await downloadWithHash(url, binPath);
-        await verifySHA256(tag, assetName, binPath, computedHex);
-      }
-      fs.chmodSync(binPath, 0o755);
-      console.log(`nano-brain v${VERSION} installed successfully from ${tag}.`);
-      tryAutoLink(binPath);
-      return;
+      return await attempt(tag);
     } catch (err) {
-      if (err && typeof err.message === "string" && err.message.startsWith("SECURITY:")) {
-        console.error(err.message);
-        process.exit(1);
-      }
+      if (err && typeof err.message === "string" && err.message.startsWith("SECURITY:")) throw err;
       lastErr = err;
     }
   }
 
+  let apiTag;
   try {
-    const tag = await resolveTagFromAPI(VERSION, assetName);
-    if (tag) {
-      const url = `https://github.com/${REPO}/releases/download/${tag}/${assetName}`;
-      if (skipVerify) {
-        await download(url, binPath);
-      } else {
-        const computedHex = await downloadWithHash(url, binPath);
-        await verifySHA256(tag, assetName, binPath, computedHex);
-      }
-      fs.chmodSync(binPath, 0o755);
-      console.log(`nano-brain v${VERSION} installed successfully from ${tag} (API fallback).`);
-      tryAutoLink(binPath);
-      return;
-    }
+    apiTag = await resolveTagFromAPI(VERSION, assetName);
   } catch (err) {
-    if (err && typeof err.message === "string" && err.message.startsWith("SECURITY:")) {
-      console.error(err.message);
-      process.exit(1);
-    }
     lastErr = err;
   }
+  if (apiTag) {
+    // Not wrapped: a SECURITY error from the API-fallback attempt must propagate.
+    return await attempt(apiTag, " (API fallback)");
+  }
 
-  console.error(`Failed to download binary: ${lastErr && lastErr.message}`);
-  console.error("Build from source: CGO_ENABLED=0 go build -o npm/nano-brain ./cmd/nano-brain");
-  process.exit(0);
+  throw new Error(`Failed to download binary: ${lastErr && lastErr.message}`);
+}
+
+async function main() {
+  try {
+    const bin = await ensureBinary();
+    // Auto-link only at install time — never from run.js's lazy path, so its
+    // console.log chatter can't pollute a command's stdout (#594).
+    tryAutoLink(bin);
+  } catch (err) {
+    const msg = err && err.message ? err.message : String(err);
+    if (msg.startsWith("SECURITY:")) {
+      console.error(msg);
+      process.exit(1); // integrity failure — never leave a bad binary
+    }
+    // Non-fatal at install time: don't fail `npm install`. run.js retries the
+    // download on first invocation, which also covers toolchains that don't
+    // persist postinstall-created files (#594).
+    console.error(msg);
+    console.error("Build from source: CGO_ENABLED=0 go build -o npm/nano-brain ./cmd/nano-brain");
+    process.exit(0);
+  }
 }
 
 if (require.main === module) {
   main();
 }
 
-module.exports = { parseSHA256Line, downloadWithHash, verifySHA256, tryAutoLink };
+module.exports = { parseSHA256Line, download, downloadWithHash, verifySHA256, tryAutoLink, safeUnlink, ensureBinary, binaryPath };

package/npm/postinstall.test.js

@@ -6,7 +6,87 @@ const fs = require("node:fs");
 const path = require("node:path");
 const os = require("node:os");
 const crypto = require("node:crypto");
-const { parseSHA256Line, tryAutoLink } = require("./postinstall");
+const { spawnSync } = require("node:child_process");
+const { parseSHA256Line, tryAutoLink, safeUnlink, download, downloadWithHash, ensureBinary, binaryPath } = require("./postinstall");
+const VERSION = require("../package.json").version;
+const isWin = os.platform() === "win32";
+
+// #594: when a valid binary is already at binaryPath(), ensureBinary() must
+// return it WITHOUT any network download. Stub the binary with a tiny script
+// that echoes the expected `version --json` payload. Any real binary already
+// there is moved aside and restored so the assertion always runs (not skipped).
+test("ensureBinary: returns existing binary without downloading", { skip: isWin }, async () => {
+  const bin = binaryPath();
+  const backup = `${bin}.itest.bak`;
+  const hadReal = fs.existsSync(bin);
+  if (hadReal) fs.renameSync(bin, backup);
+  fs.writeFileSync(bin, `#!/bin/sh\necho '{"version":"${VERSION}"}'\n`);
+  fs.chmodSync(bin, 0o755);
+  try {
+    const resolved = await ensureBinary();
+    assert.strictEqual(resolved, bin);
+  } finally {
+    safeUnlink(bin);
+    if (hadReal) fs.renameSync(backup, bin);
+  }
+});
+
+// #594 BLOCKER regression: an unsupported platform must REJECT (not process.exit),
+// so run.js can report it and exit 1. getPlatformKey throws; ensureBinary propagates.
+test("ensureBinary: rejects (does not exit) on unsupported platform", async () => {
+  const realPlatform = os.platform;
+  os.platform = () => "freebsd";
+  try {
+    await assert.rejects(() => ensureBinary(), /Unsupported platform/);
+  } finally {
+    os.platform = realPlatform;
+  }
+});
+
+// #594: run.js executes the binary NANO_BRAIN_BIN points to (override path),
+// end-to-end via a subprocess — proves the wrapper's exec path works.
+test("run.js: runs NANO_BRAIN_BIN target and exits 0", { skip: isWin }, () => {
+  const stub = path.join(os.tmpdir(), `nb-runjs-stub-${process.pid}-${Date.now()}`);
+  fs.writeFileSync(stub, `#!/bin/sh\necho NB_STUB_OK\n`);
+  fs.chmodSync(stub, 0o755);
+  try {
+    const r = spawnSync(process.execPath, [path.join(__dirname, "run.js"), "anyarg"], {
+      env: { ...process.env, NANO_BRAIN_BIN: stub },
+      encoding: "utf8",
+    });
+    assert.strictEqual(r.status, 0);
+    assert.match(r.stdout, /NB_STUB_OK/);
+  } finally {
+    safeUnlink(stub);
+  }
+});
+
+// #592 regression: a request/socket error must REJECT the promise (so main()'s
+// per-tag retry loop continues), never throw synchronously or crash the
+// process via an unguarded unlink. Point at a closed port → ECONNREFUSED.
+test("download: rejects (not throws) on connection error, no lingering file", async () => {
+  const dest = path.join(os.tmpdir(), `nb-dl-refused-${process.pid}-${Date.now()}`);
+  await assert.rejects(() => download("https://127.0.0.1:1/x", dest));
+  assert.strictEqual(fs.existsSync(dest), false);
+});
+
+test("downloadWithHash: rejects (not throws) on connection error, no lingering file", async () => {
+  const dest = path.join(os.tmpdir(), `nb-dlh-refused-${process.pid}-${Date.now()}`);
+  await assert.rejects(() => downloadWithHash("https://127.0.0.1:1/x", dest));
+  assert.strictEqual(fs.existsSync(dest), false);
+});
+
+test("safeUnlink: does not throw on a nonexistent path (#592 regression)", () => {
+  const missing = path.join(os.tmpdir(), `nb-safeunlink-missing-${process.pid}-${Date.now()}`);
+  assert.doesNotThrow(() => safeUnlink(missing));
+});
+
+test("safeUnlink: removes an existing file", () => {
+  const p = path.join(os.tmpdir(), `nb-safeunlink-${process.pid}-${Date.now()}`);
+  fs.writeFileSync(p, "x");
+  safeUnlink(p);
+  assert.strictEqual(fs.existsSync(p), false);
+});
 
 test("parseSHA256Line: returns hash for matching filename in single-line content", () => {
   const content = "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789  nano-brain-linux-amd64\n";

package/npm/run.js

@@ -9,6 +9,23 @@ const os = require("os");
 const binName = os.platform() === "win32" ? "nano-brain.exe" : "nano-brain";
 const binPath = path.join(__dirname, binName);
 
+function runBinary(bin) {
+  try {
+    execFileSync(bin, process.argv.slice(2), { stdio: "inherit" });
+  } catch (e) {
+    // A numeric status means the binary ran and chose that exit code (it has
+    // already produced its own output). A non-numeric status means we could
+    // not spawn it at all (arch mismatch, missing libc, ETXTBSY, perms) —
+    // surface that, since stdio:"inherit" shows nothing for a spawn failure.
+    if (typeof e.status !== "number") {
+      process.stderr.write(`Error: failed to execute binary at ${bin}: ${e.message}\n`);
+    }
+    process.exit(e.status || 1);
+  }
+  process.exit(0);
+}
+
+// Explicit override wins and skips any download.
 const envBin = process.env.NANO_BRAIN_BIN;
 if (envBin && envBin.trim() !== "") {
   const trimmed = envBin.trim();
@@ -16,26 +33,30 @@ if (envBin && envBin.trim() !== "") {
     process.stderr.write(`Error: NANO_BRAIN_BIN points to ${trimmed} which does not exist. Unset the variable or correct the path.\n`);
     process.exit(1);
   }
-  const mode = fs.statSync(trimmed).mode;
-  if ((mode & 0o111) === 0) {
+  if ((fs.statSync(trimmed).mode & 0o111) === 0) {
     process.stderr.write(`Error: NANO_BRAIN_BIN points to ${trimmed} which is not executable. Run: chmod +x ${trimmed}\n`);
     process.exit(1);
   }
-  try { execFileSync(trimmed, process.argv.slice(2), { stdio: "inherit" }); }
-  catch (e) { process.exit(e.status || 1); }
-  process.exit(0);
+  runBinary(trimmed);
+  return; // runBinary exits; explicit return makes the branches structurally exclusive
 }
 
-if (!fs.existsSync(binPath)) {
-  console.error("nano-brain binary not found at " + binPath + ".");
-  console.error("The postinstall script may have failed during npm install.");
-  console.error("Try: npm install -g @nano-step/nano-brain --foreground-scripts");
-  console.error("Or build from source: CGO_ENABLED=0 go build -o npm/nano-brain ./cmd/nano-brain");
-  process.exit(1);
+if (fs.existsSync(binPath)) {
+  runBinary(binPath);
+  return;
 }
 
-try {
-  execFileSync(binPath, process.argv.slice(2), { stdio: "inherit" });
-} catch (e) {
-  process.exit(e.status || 1);
-}
+// The binary is missing — the postinstall download either failed (offline /
+// proxy) or was not persisted by the package manager (some npm/node versions
+// discard postinstall-created files, #594). Download it now, at run time, where
+// the write always persists, then run. Progress goes to stderr.
+process.stderr.write("nano-brain: binary not present; downloading on first run...\n");
+require("./postinstall")
+  .ensureBinary()
+  .then((bin) => runBinary(bin))
+  .catch((err) => {
+    const msg = err && err.message ? err.message : String(err);
+    process.stderr.write(`nano-brain: could not obtain the binary: ${msg}\n`);
+    process.stderr.write("Fix: set NANO_BRAIN_BIN=/path/to/nano-brain, or build from source: CGO_ENABLED=0 go build -o npm/nano-brain ./cmd/nano-brain\n");
+    process.exit(1);
+  });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nano-brain",
-  "version": "2026.7.1102",
+  "version": "2026.7.1104",
   "description": "Persistent memory and code intelligence for AI coding agents",
   "bin": {
     "nano-brain": "npm/run.js"