donsetch 4.7.3 → 4.7.4

package/README.md

@@ -59,6 +59,7 @@ Downloads the prebuilt binary for your platform from [GitHub Releases](https://g
 
 - **pnpm or bun:** the postinstall needs approval. `pnpm approve-builds` (or the bun equivalent), then reinstall. If scripts were blocked, `npx donsetch` runs the self-healing shim.
 - **`--ignore-scripts`:** postinstall is intentionally skipped. Run `node node_modules/donsetch/install.js`, or use `npx donsetch` to download the binary when network access is available.
+- **System-wide installs:** if the npm prefix is root-owned (for example `/usr/local/lib/node_modules`) and you run donsetch as a normal user, the package copy cannot be written there. donsetch then uses an existing binary from `PATH` or `~/.cargo/bin` automatically; `DONSETCH_BINARY=/path/to/donsetch` points at one explicitly. To keep the package copy instead: `npm config set prefix ~/.npm-global && npm install -g donsetch`.
 - **Proxy:** set `HTTPS_PROXY` (or `https_proxy`, `HTTP_PROXY`, `http_proxy`) to an HTTP CONNECT proxy.
 - **Release mirror:** set `DONSETCH_RELEASES_BASE` to a mirror serving `<tag>/<asset>` paths, for example `https://mirror.example/donsetch/releases`.
 - **Windows:** the installer needs `tar`, included since Windows 10 1803.

package/bin/donsetch.js

@@ -1,48 +1,44 @@
 #!/usr/bin/env node
 'use strict';
 
-// donsetch CLI wrapper: spawn the native binary with forwarded stdio.
+// donsetch CLI wrapper: resolve the binary and spawn it with
+// forwarded stdio.
 //
 // For MCP server usage (`donsetch mcp`), the MCP client spawns this
 // wrapper as a subprocess and communicates via stdin/stdout (JSON-RPC).
 // stdio: 'inherit' pipes the native binary's stdio directly to the
 // parent process, so the MCP protocol passes through unmodified.
 //
+// Resolution goes through resolve-binary.js: package-local binary
+// first, install.js when it can run, then an existing donsetch on
+// PATH / $CARGO_HOME / ~/.cargo/bin (#361: a system-wide package
+// under a root-owned prefix must not kill a working install). All
+// installer chatter and notices go to stderr: stdout belongs to the
+// protocol.
+//
 // Signal forwarding: when the MCP client sends SIGTERM/SIGINT to this
 // wrapper, we forward it to the native binary so it can clean up
 // (close connections, save ghost state, etc.) before exiting.
 
-const { spawn, execFileSync } = require('child_process');
-const { existsSync } = require('fs');
+const { spawn } = require('child_process');
 const { join } = require('path');
+const { resolveBinary } = require('../resolve-binary.js');
 
 // ── resolve binary path ─────────────────────────────────────────
-const binaryName = process.platform === 'win32' ? 'donsetch.exe' : 'donsetch';
-const binDir = join(__dirname, '..', 'binaries');
-const binaryPath = join(binDir, binaryName);
-
-if (!existsSync(binaryPath)) {
-  const installScript = join(__dirname, '..', 'install.js');
-  try {
-    execFileSync(process.execPath, [installScript], {
-      stdio: 'inherit',
-      cwd: join(__dirname, '..'),
-    });
-  } catch (_) {
-    process.stderr.write(
-      `donsetch: native binary missing and download failed. Retry with network access, ` +
-      `or run node ${installScript}; pnpm users: pnpm approve-builds then reinstall.\n`
-    );
-    process.exit(1);
-  }
-  if (!existsSync(binaryPath)) {
-    process.stderr.write(
-      `donsetch: native binary missing and download failed. Retry with network access, ` +
-      `or run node ${installScript}; pnpm users: pnpm approve-builds then reinstall.\n`
-    );
-    process.exit(1);
-  }
+let resolved;
+try {
+  resolved = resolveBinary({
+    pkgDir: join(__dirname, '..'),
+    self: __filename,
+    onOutput: (chunk) => process.stderr.write(chunk),
+  });
+} catch (err) {
+  process.stderr.write(`donsetch: ${err.message || err}\n`);
+  process.exit(1);
 }
+if (resolved.notice) process.stderr.write(resolved.notice + '\n');
+
+const binaryPath = resolved.path;
 
 // ── spawn native binary ─────────────────────────────────────────
 const child = spawn(binaryPath, process.argv.slice(2), {

package/install.js

@@ -11,6 +11,7 @@ const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
+const { findExistingBinary, targetWritable } = require('./resolve-binary.js');
 const { pipeline } = require('stream/promises');
 
 const REPO = 'dondai44423/donsetch';
@@ -269,12 +270,26 @@ async function download(url, dest) {
 }
 
 async function main() {
-  const tarball = path.join(binDir, plat.asset);
-  const checksumFile = path.join(binDir, 'checksum.sha256');
-
-  // Inside main() so an unwritable install dir gets the curated
-  // error below, not a raw Node stack trace from a top-level throw.
-  fs.mkdirSync(binDir, { recursive: true });
+  // Per-pid temp names: two first runs racing (two MCP clients
+  // starting together) must never share a write target. The renames
+  // that land the files are atomic; the temps are invisible until then.
+  const tarball = path.join(binDir, `${plat.asset}.tmp-${process.pid}`);
+  const checksumFile = path.join(binDir, `checksum.sha256.tmp-${process.pid}`);
+  const extractDir = path.join(binDir, `extract.tmp-${process.pid}`);
+
+  // The unwritable install dir (#361: a system-wide npm package under
+  // a root-owned prefix, run by an unprivileged user) is decided
+  // BEFORE any download, so the failure names the directory and the
+  // ways out instead of dying after 19MB of network.
+  try {
+    fs.mkdirSync(binDir, { recursive: true });
+  } catch (err) {
+    settleUnwritable(err);
+  }
+  if (!targetWritable(__dirname)) {
+    settleUnwritable(new Error(`${binDir} is not writable`));
+  }
+  cleanupStaleTemps();
 
   if (process.platform === 'win32') {
     try {
@@ -300,11 +315,22 @@ async function main() {
     }
 
     console.log('donsetch: extracting...');
-    execFileSync('tar', ['xzf', tarball, '-C', binDir], { stdio: 'inherit' });
+    fs.rmSync(extractDir, { recursive: true, force: true });
+    fs.mkdirSync(extractDir, { recursive: true });
+    execFileSync('tar', ['xzf', tarball, '-C', extractDir], { stdio: 'inherit' });
 
-    if (!fs.existsSync(binaryPath)) {
+    const entries = fs.readdirSync(extractDir);
+    if (!entries.includes(plat.binary)) {
       throw new Error(`expected ${plat.binary} not found after extraction in ${binDir}`);
     }
+    // Land each entry with a rename inside binDir: a rename is atomic,
+    // so a concurrent first run can only ever replace a complete file,
+    // never expose a half-written one. The stamp goes last: a crash
+    // before it leaves no stamp, and the next run re-downloads.
+    for (const name of entries) {
+      fs.renameSync(path.join(extractDir, name), path.join(binDir, name));
+    }
+    fs.rmSync(extractDir, { recursive: true, force: true });
     if (process.platform !== 'win32') fs.chmodSync(binaryPath, 0o755);
     fs.writeFileSync(stampPath, `${VERSION}\n`);
     console.log(`donsetch: installed ${plat.binary} to ${binaryPath}`);
@@ -314,13 +340,80 @@ async function main() {
     // and checksum sitting in ./binaries/ forever.
     try { fs.unlinkSync(tarball); } catch (_) {}
     try { fs.unlinkSync(checksumFile); } catch (_) {}
+    try { fs.rmSync(extractDir, { recursive: true, force: true }); } catch (_) {}
+  }
+}
+
+// One existing-binary lookup for the failure paths: an install that
+// cannot succeed must not take a working donsetch down with it (#361).
+// Returns false when there is nothing to fall back on.
+function ackExisting(detail) {
+  let existing = null;
+  try {
+    existing = findExistingBinary({ pkgDir: __dirname });
+  } catch (_) {
+    return false;
+  }
+  if (!existing) return false;
+  console.log(`donsetch: install failed: ${detail}`);
+  console.log(`donsetch: an existing binary was found and will be used: ${existing.path}`);
+  process.exit(0);
+}
+
+// The unwritable install dir: acknowledge an existing binary when one
+// is findable (npm install / postinstall stays green), otherwise fail
+// with every way out named.
+function settleUnwritable(cause) {
+  const detail = cause && cause.message ? cause.message : 'directory is not writable';
+  if (ackExisting(detail)) return;
+  console.error(
+    `donsetch: cannot install into ${binDir} (${detail}) and no existing donsetch binary was found.`
+  );
+  console.error('');
+  console.error('Options:');
+  console.error('  - install under a user-writable prefix:');
+  console.error('      npm config set prefix ~/.npm-global && npm install -g donsetch');
+  console.error('  - point at a donsetch binary you already have:');
+  console.error('      DONSETCH_BINARY=/path/to/donsetch');
+  console.error('  - build from source:');
+  console.error(`      git clone https://github.com/${REPO} && cd donsetch && cargo build --release`);
+  process.exit(1);
+}
+
+// Temp leftovers from crashed runs (this installer is the only writer
+// of `.tmp-<pid>` / `extract.tmp-<pid>` names in binDir). A pid that
+// is still alive keeps its workspace.
+function cleanupStaleTemps() {
+  let names;
+  try {
+    names = fs.readdirSync(binDir);
+  } catch (_) {
+    return;
+  }
+  for (const name of names) {
+    const m = /\.tmp-(\d+)$/.exec(name);
+    if (!m || Number(m[1]) === process.pid) continue;
+    let alive = false;
+    try {
+      process.kill(Number(m[1]), 0);
+      alive = true;
+    } catch (_) {/* not running (or not ours): its temps are stale */}
+    if (!alive) {
+      try { fs.rmSync(path.join(binDir, name), { recursive: true, force: true }); } catch (_) {}
+    }
   }
 }
 
 main().catch((error) => {
+  if (ackExisting(error.message)) return;
   console.error(`donsetch: install failed: ${error.message}`);
   console.error('');
-  console.error('You can build from source:');
+  console.error('Options:');
+  console.error('  - install under a user-writable prefix:');
+  console.error('      npm config set prefix ~/.npm-global && npm install -g donsetch');
+  console.error('  - point at a donsetch binary you already have:');
+  console.error('      DONSETCH_BINARY=/path/to/donsetch');
+  console.error('  - build from source:');
   console.error(`  git clone https://github.com/${REPO} && cd donsetch && cargo build --release`);
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "donsetch",
-  "version": "4.7.3",
+  "version": "4.7.4",
   "description": "MCP server that gives AI agents the web: fetch, search, crawl and screenshot from one local Rust binary. Zero API keys, zero accounts, Chrome-true TLS.",
   "license": "AGPL-3.0-only",
   "author": "Bishesh Bhandari",
@@ -49,10 +49,12 @@
     "donsetch": "bin/donsetch.js"
   },
   "scripts": {
-    "postinstall": "node install.js"
+    "postinstall": "node install.js",
+    "test": "node --test --test-timeout=90000 tests/*.test.js"
   },
   "files": [
     "install.js",
+    "resolve-binary.js",
     "bin/donsetch.js",
     "pi-extension.ts",
     "README.md",

package/pi-extension.ts

@@ -11,8 +11,11 @@
  * them up automatically : no code changes needed here.
  *
  * Auto-download: if the binary is missing (e.g. postinstall was
- * blocked by npm 10+), the extension runs install.js at session_start
- * to fetch it from GitHub Releases.
+ * blocked by npm 10+), the extension resolves through
+ * resolve-binary.js at session_start: the package binary gets
+ * installed when possible, otherwise an existing donsetch
+ * (DONSETCH_BINARY / PATH / cargo bin) is used (#361: system-wide
+ * installs under a root-owned prefix).
  *
  * Custom TUI: each tool has clean renderCall/renderResult showing
  * a compact summary card : not the full raw output. The LLM still
@@ -22,7 +25,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { spawn, execFileSync, type ChildProcess } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Text } from "@earendil-works/pi-tui";
 
@@ -108,32 +112,35 @@ function ensureBinary(): string {
   const binaryPath = getBinaryPath();
   if (existsSync(binaryPath)) return binaryPath;
 
-  const installScript = join(__dirname, "install.js");
-  if (!existsSync(installScript)) {
+  const resolverScript = join(__dirname, "resolve-binary.js");
+  if (!existsSync(resolverScript)) {
     throw new Error(
-      `donsetch binary not found at ${binaryPath} and install.js is missing. ` +
+      `donsetch binary not found at ${binaryPath} and resolve-binary.js is missing. ` +
       `Run \`npm rebuild donsetch\` or \`npm install -g --allow-scripts=donsetch donsetch@latest\`.`
     );
   }
 
+  // The shared resolver installs the package binary when it can and
+  // falls back to an existing donsetch when it cannot. stdio is
+  // inherited so first-run download progress stays visible; the path
+  // arrives via a temp file because stdout belongs to the terminal.
+  const outFile = join(tmpdir(), `donsetch-resolve-${process.pid}.txt`);
   try {
-    execFileSync(process.execPath, [installScript], {
-      stdio: "inherit",
-      cwd: __dirname,
-      timeout: 300_000,
-    });
+    execFileSync(
+      process.execPath,
+      [resolverScript, "--print-file", outFile, "--pkg-dir", __dirname],
+      { stdio: "inherit", cwd: __dirname, timeout: 300_000 }
+    );
+    const resolved = readFileSync(outFile, "utf8").trim();
+    if (!resolved) throw new Error("resolver returned no binary path");
+    return resolved;
   } catch (err: any) {
-    throw new Error(`Failed to download donsetch binary: ${err.message}`);
-  }
-
-  if (!existsSync(binaryPath)) {
     throw new Error(
-      `donsetch binary still missing after install.js ran. ` +
-      `Run \`npm install -g --allow-scripts=donsetch donsetch@latest\` manually.`
+      `Failed to resolve the donsetch binary. The resolver output above names the cause and the ways out (${err.message}).`
     );
+  } finally {
+    try { rmSync(outFile, { force: true }); } catch { /* best effort */ }
   }
-
-  return binaryPath;
 }
 
 // ── MCP JSON-RPC 2.0 over stdio ──

package/resolve-binary.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+'use strict';
+
+// Binary resolution for the npm package, shared by every consumer:
+// bin/donsetch.js (the CLI / MCP wrapper, in-process), install.js
+// (install-time acknowledgement), and pi-extension.ts (spawned as
+// `node resolve-binary.js --print-file <path>`).
+//
+// Order:
+//   1. DONSETCH_BINARY            explicit override, wins over everything
+//   2. <pkg>/binaries/<name>      the pinned copy this package installs
+//   3. install.js                 fetch the pinned copy when it can run
+//   4. an existing binary         PATH, $CARGO_HOME/bin, ~/.cargo/bin
+//   5. hard failure               curated, names every way out
+//
+// The fallback exists because the pinned copy is not always obtainable
+// (issue #361): a system-wide npm package under a root-owned prefix
+// cannot be written by the user running it, and an install that cannot
+// succeed must not take a working donsetch down with it. The wrapper
+// itself is never a candidate: on a global npm install the PATH entry
+// named `donsetch` is a symlink back into this package, so candidates
+// are compared by their real path and anything resolving into the
+// package is skipped.
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const BINARY_NAME = process.platform === 'win32' ? 'donsetch.exe' : 'donsetch';
+
+function isExecutableFile(p) {
+  try {
+    if (!fs.statSync(p).isFile()) return false;
+    if (process.platform !== 'win32') fs.accessSync(p, fs.constants.X_OK);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function real(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch (_) {
+    return p;
+  }
+}
+
+function packageBinary(pkgDir) {
+  return path.join(pkgDir, 'binaries', BINARY_NAME);
+}
+
+// The package-local copy, with a chmod rescue: an executable bit lost
+// in transit (copied tree, artifact download) is repaired in place
+// rather than triggering a re-download.
+function usableLocal(p) {
+  if (!fs.existsSync(p)) return false;
+  if (isExecutableFile(p)) return true;
+  if (process.platform !== 'win32') {
+    try {
+      fs.chmodSync(p, 0o755);
+    } catch (_) {/* fall through to the recheck */}
+  }
+  return isExecutableFile(p);
+}
+
+// True when install.js could write into <pkgDir>/binaries. A missing
+// directory is judged by its parent. Advisory only: the install itself
+// still handles a late failure, but a known-unwritable target skips a
+// doomed 19MB download first (#361).
+function targetWritable(pkgDir) {
+  const binDir = path.join(pkgDir, 'binaries');
+  try {
+    if (fs.existsSync(binDir)) {
+      fs.accessSync(binDir, fs.constants.W_OK);
+      return true;
+    }
+    fs.accessSync(pkgDir, fs.constants.W_OK);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+// The one explicit override. Invalid values fail loudly: a DONSETCH_BINARY
+// that names nothing is a config bug, not a fall-through case.
+function overrideBinary() {
+  const over = process.env.DONSETCH_BINARY;
+  if (!over) return null;
+  const p = path.resolve(over);
+  if (!isExecutableFile(p)) {
+    throw new Error(
+      `DONSETCH_BINARY is set to ${p}, which is not an executable file. ` +
+        `Unset it or point it at a donsetch binary.`
+    );
+  }
+  return { path: p, source: 'env' };
+}
+
+// An already-installed donsetch outside this package: PATH entries
+// (skipping empty ones, which mean the current directory), then the
+// cargo bin directories even when they are not on PATH.
+function findExistingBinary(opts) {
+  const pkgDir = opts.pkgDir;
+
+  const over = overrideBinary();
+  if (over) return over;
+
+  const banned = new Set([real(path.join(pkgDir, 'bin', 'donsetch.js'))]);
+  if (opts.self) banned.add(real(opts.self));
+  const pkgRoot = real(pkgDir);
+  const pkgPrefix = pkgRoot.endsWith(path.sep) ? pkgRoot : pkgRoot + path.sep;
+
+  const candidates = [];
+  const seen = new Set();
+  const add = (p) => {
+    const r = real(p);
+    if (seen.has(r)) return;
+    seen.add(r);
+    candidates.push({ p, r });
+  };
+
+  for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    add(path.join(dir, BINARY_NAME));
+  }
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (process.env.CARGO_HOME) add(path.join(process.env.CARGO_HOME, 'bin', BINARY_NAME));
+  if (home) add(path.join(home, '.cargo', 'bin', BINARY_NAME));
+
+  for (const c of candidates) {
+    if (banned.has(c.r)) continue;
+    if (c.r === pkgRoot || c.r.startsWith(pkgPrefix)) continue;
+    if (!isExecutableFile(c.p)) continue;
+    return { path: c.p, source: 'path' };
+  }
+  return null;
+}
+
+function noBinaryMessage(why) {
+  return [
+    `could not install the donsetch binary and none was found (${why}).`,
+    'Options:',
+    '  - install under a user-writable prefix:',
+    '      npm config set prefix ~/.npm-global && npm install -g donsetch',
+    '  - point at a donsetch binary you already have:',
+    '      DONSETCH_BINARY=/path/to/donsetch',
+    '  - build from source:',
+    '      git clone https://github.com/dondai44423/donsetch && cd donsetch && cargo build --release',
+  ].join('\n');
+}
+
+function runInstaller(pkgDir, onOutput) {
+  const installScript = path.join(pkgDir, 'install.js');
+  if (!fs.existsSync(installScript)) {
+    return { ok: false, error: `installer missing: ${installScript}` };
+  }
+  try {
+    const out = execFileSync(process.execPath, [installScript], {
+      cwd: pkgDir,
+      encoding: 'utf8',
+      timeout: 300_000,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (onOutput && out) onOutput(out);
+    return { ok: true };
+  } catch (err) {
+    if (onOutput) {
+      if (err.stdout) onOutput(String(err.stdout));
+      if (err.stderr) onOutput(String(err.stderr));
+    }
+    const lines = String(err.stderr || err.message || err).trim().split('\n');
+    return { ok: false, error: (lines[0] || 'installer failed').trim() };
+  }
+}
+
+// Resolve the binary for a run. `onOutput` receives installer output
+// chunks; callers point it at stderr (never stdout: an MCP stdio
+// session owns that channel).
+function resolveBinary(opts) {
+  const pkgDir = opts.pkgDir;
+  const onOutput = opts.onOutput;
+
+  const over = overrideBinary();
+  if (over) return over;
+
+  const local = packageBinary(pkgDir);
+  if (usableLocal(local)) return { path: local, source: 'package' };
+
+  let why;
+  if (process.env.DONSETCH_SKIP_DOWNLOAD === '1') {
+    why = 'download skipped (DONSETCH_SKIP_DOWNLOAD=1)';
+  } else if (!targetWritable(pkgDir)) {
+    why = `${path.join(pkgDir, 'binaries')} is not writable`;
+  } else {
+    const result = runInstaller(pkgDir, onOutput);
+    if (usableLocal(local)) return { path: local, source: 'package' };
+    // The installer can also exit 0 without a local binary (its own
+    // existing-binary acknowledgement): name that, never "undefined".
+    why = result.ok ? 'the installer did not produce the binary' : result.error;
+  }
+
+  const existing = findExistingBinary({ pkgDir, self: opts.self });
+  if (existing) {
+    return {
+      path: existing.path,
+      source: existing.source,
+      notice: `donsetch: package binary unavailable (${why}); using existing binary: ${existing.path}`,
+    };
+  }
+  throw new Error(noBinaryMessage(why));
+}
+
+module.exports = { resolveBinary, findExistingBinary, targetWritable, packageBinary };
+
+// ── CLI mode ─────────────────────────────────────────────────────
+// Used by pi-extension.ts. `--print` writes the resolved path to
+// stdout; `--print-file <path>` writes it to a file and keeps stdout
+// free for an inheriting caller. Progress and failures go to stderr.
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const pkgIdx = args.indexOf('--pkg-dir');
+  const fileIdx = args.indexOf('--print-file');
+  if (pkgIdx < 0) {
+    process.stderr.write('usage: resolve-binary.js --pkg-dir <dir> [--print-file <path>]\n');
+    process.exit(2);
+  }
+  const pkgDir = path.resolve(args[pkgIdx + 1] || '');
+  const outFile = fileIdx >= 0 ? args[fileIdx + 1] : null;
+  try {
+    const resolved = resolveBinary({
+      pkgDir,
+      self: process.argv[1],
+      onOutput: (chunk) => process.stderr.write(chunk),
+    });
+    if (resolved.notice) process.stderr.write(resolved.notice + '\n');
+    if (outFile) {
+      fs.writeFileSync(outFile, resolved.path + '\n');
+    } else {
+      process.stdout.write(resolved.path + '\n');
+    }
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(String(err.message || err) + '\n');
+    process.exit(1);
+  }
+}