docdex 0.2.30 → 0.2.32

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 - Remove legacy stdio MCP (`docdexd mcp` / `docdex-mcp-server`); MCP is served only over HTTP/SSE.
+- Ensure npm tarballs include CLI wrapper entrypoints and restore missing wrappers during postinstall.
+- Retry Windows file operations during install to reduce EPERM/EACCES failures.
+- Nightly HTTP soak waits for index readiness before load testing.
+- Windows CLI shims now target stable `lib/` entrypoints to avoid missing `bin/docdex.js`.
 
 ## 0.2.23
 - Add Smithery session config schema metadata (titles/descriptions, defaults, example config) for local MCP sessions.

package/assets/agents.md

@@ -1,4 +1,4 @@
----- START OF DOCDEX INFO V0.2.30 ----
+---- START OF DOCDEX INFO V0.2.32 ----
 Docdex URL: http://127.0.0.1:28491
 Use this base URL for Docdex HTTP endpoints.
 Health check endpoint: `GET /healthz` (not `/v1/health`).

package/lib/cli_entry.js

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+
+const pkg = require("../package.json");
+const { resolveDistBaseDir, resolveDistBaseCandidates } = require("./paths");
+const {
+  artifactName,
+  detectLibcFromRuntime,
+  detectPlatformKey,
+  targetTripleForPlatformKey,
+  assetPatternForPlatformKey,
+  UnsupportedPlatformError
+} = require("./platform");
+const { checkForUpdateOnce } = require("./update_check");
+
+function isDoctorCommand(argv) {
+  const sub = argv[0];
+  return sub === "doctor" || sub === "diagnostics";
+}
+
+function printLines(lines, { stderr } = {}) {
+  for (const line of lines) {
+    if (!line) continue;
+    if (stderr) console.error(line);
+    else console.log(line);
+  }
+}
+
+function envBool(value) {
+  if (!value) return false;
+  const normalized = String(value).trim().toLowerCase();
+  return ["1", "true", "t", "yes", "y", "on"].includes(normalized);
+}
+
+function readInstallMetadata({ fsModule, pathModule, basePath }) {
+  if (!fsModule || typeof fsModule.readFileSync !== "function") return null;
+  const metadataPath = pathModule.join(basePath, "docdexd-install.json");
+  try {
+    const raw = fsModule.readFileSync(metadataPath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function formatInstallSource(meta) {
+  const source = meta?.archive?.source;
+  if (!source || typeof source !== "string") return "unknown";
+  if (source === "local") return "local binary";
+  return `release (${source})`;
+}
+
+function resolveInstallPaths(platformKey) {
+  const binaryName = process.platform === "win32" ? "docdexd.exe" : "docdexd";
+  const candidates = [];
+  for (const distBase of resolveDistBaseCandidates({ env: process.env })) {
+    candidates.push(path.join(distBase, platformKey));
+  }
+  candidates.push(path.join(__dirname, "..", "dist", platformKey));
+  const seen = new Set();
+  const unique = candidates.filter((candidate) => {
+    if (!candidate || seen.has(candidate)) return false;
+    seen.add(candidate);
+    return true;
+  });
+  for (const basePath of unique) {
+    const binaryPath = path.join(basePath, binaryName);
+    if (fs.existsSync(binaryPath)) {
+      return { basePath, binaryPath };
+    }
+  }
+  const fallbackBase =
+    unique[0] || path.join(resolveDistBaseDir({ env: process.env, fsModule: fs }), platformKey);
+  return { basePath: fallbackBase, binaryPath: path.join(fallbackBase, binaryName) };
+}
+
+function runDoctor() {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  let libc = null;
+  if (platform === "linux") {
+    try {
+      libc = detectLibcFromRuntime();
+    } catch (err) {
+      printLines(
+        [
+          "[docdex] doctor failed: could not detect libc",
+          `[docdex] Detected platform: ${platform}/${arch}`,
+          `[docdex] Error: ${err?.message || String(err)}`
+        ],
+        { stderr: true }
+      );
+      process.exit(1);
+      return;
+    }
+  }
+
+  let report;
+  try {
+    const platformKey = detectPlatformKey();
+    const targetTriple = targetTripleForPlatformKey(platformKey);
+    const expectedAssetName = artifactName(platformKey);
+    const expectedAssetPattern = assetPatternForPlatformKey(platformKey, { exampleAssetName: expectedAssetName });
+    const distCandidates = resolveDistBaseCandidates({ env: process.env });
+    const distBase =
+      distCandidates[0] || resolveDistBaseDir({ env: process.env, fsModule: null });
+    const basePath = path.join(distBase, platformKey);
+    const installMeta = readInstallMetadata({ fsModule: fs, pathModule: path, basePath });
+    const installSource = formatInstallSource(installMeta);
+
+    report = {
+      exitCode: 0,
+      stderr: false,
+      lines: [
+        "[docdex] doctor",
+        `[docdex] Detected platform: ${platform}/${arch}${libc ? `/${libc}` : ""}`,
+        "[docdex] Supported: yes",
+        `[docdex] Platform key: ${platformKey}`,
+        `[docdex] Expected target triple: ${targetTriple}`,
+        `[docdex] Expected release asset: ${expectedAssetName}`,
+        `[docdex] Asset naming pattern: ${expectedAssetPattern}`,
+        `[docdex] Install source: ${installSource}`
+      ]
+    };
+  } catch (err) {
+    if (err instanceof UnsupportedPlatformError) {
+      const detected = `${err.details?.platform ?? platform}/${err.details?.arch ?? arch}`;
+      const libcSuffix = err.details?.libc ? `/${err.details.libc}` : "";
+      const candidatePlatformKey =
+        typeof err.details?.candidatePlatformKey === "string" ? err.details.candidatePlatformKey : null;
+      const candidateTargetTriple =
+        typeof err.details?.candidateTargetTriple === "string" ? err.details.candidateTargetTriple : null;
+      const supportedKeys = Array.isArray(err.details?.supportedPlatformKeys) ? err.details.supportedPlatformKeys : [];
+
+      const candidateAssetName = candidatePlatformKey ? artifactName(candidatePlatformKey) : null;
+      const candidateAssetPattern = candidatePlatformKey
+        ? assetPatternForPlatformKey(candidatePlatformKey, { exampleAssetName: candidateAssetName })
+        : null;
+
+      report = {
+        exitCode: err.exitCode || 3,
+        stderr: true,
+        lines: [
+          "[docdex] doctor",
+          `[docdex] Detected platform: ${detected}${libcSuffix}`,
+          "[docdex] Supported: no",
+          `[docdex] error code: ${err.code}`,
+          "[docdex] No download/install is attempted for this platform.",
+          candidatePlatformKey ? `[docdex] Platform key: ${candidatePlatformKey}` : null,
+          candidateTargetTriple ? `[docdex] Target triple: ${candidateTargetTriple}` : null,
+          candidateAssetPattern ? `[docdex] Asset naming pattern: ${candidateAssetPattern}` : null,
+          supportedKeys.length ? `[docdex] Supported platforms: ${supportedKeys.join(", ")}` : null,
+          "[docdex] Next steps: use a supported platform or build from source (Rust)."
+        ]
+      };
+    } else {
+      report = {
+        exitCode: 1,
+        stderr: true,
+        lines: [
+          "[docdex] doctor failed: unexpected error",
+          `[docdex] Detected platform: ${platform}/${arch}${libc ? `/${libc}` : ""}`,
+          `[docdex] Error: ${err?.message || String(err)}`
+        ]
+      };
+    }
+  }
+
+  printLines(report.lines, { stderr: report.stderr });
+  process.exit(report.exitCode);
+}
+
+async function run() {
+  const argv = process.argv.slice(2);
+  if (isDoctorCommand(argv)) {
+    runDoctor();
+    return;
+  }
+
+  let platformKey;
+  try {
+    platformKey = detectPlatformKey();
+  } catch (err) {
+    if (err instanceof UnsupportedPlatformError) {
+      const detected = `${err.details?.platform ?? process.platform}/${err.details?.arch ?? process.arch}`;
+      const libc = err.details?.libc ? `/${err.details.libc}` : "";
+      console.error(`[docdex] unsupported platform (${detected}${libc})`);
+      console.error(`[docdex] error code: ${err.code}`);
+      console.error("[docdex] No download/run was attempted for this platform.");
+      if (Array.isArray(err.details?.supportedPlatformKeys) && err.details.supportedPlatformKeys.length) {
+        console.error(`[docdex] Supported platforms: ${err.details.supportedPlatformKeys.join(", ")}`);
+      }
+      if (typeof err.details?.candidatePlatformKey === "string") {
+        console.error(`[docdex] Asset naming pattern: ${assetPatternForPlatformKey(err.details.candidatePlatformKey)}`);
+      }
+      console.error("[docdex] Next steps: use a supported platform or build from source (Rust).");
+      process.exit(err.exitCode || 3);
+      return;
+    }
+    console.error(`[docdex] failed to detect platform: ${err?.message || String(err)}`);
+    process.exit(1);
+    return;
+  }
+
+  const { binaryPath } = resolveInstallPaths(platformKey);
+
+  if (!fs.existsSync(binaryPath)) {
+    console.error(`[docdex] Missing binary for ${platformKey}. Try reinstalling or set DOCDEX_DOWNLOAD_REPO to a repo with release assets.`);
+    try {
+      console.error(`[docdex] Expected target triple: ${targetTripleForPlatformKey(platformKey)}`);
+      console.error(`[docdex] Asset naming pattern: ${assetPatternForPlatformKey(platformKey)}`);
+    } catch {}
+    process.exit(1);
+    return;
+  }
+
+  await checkForUpdateOnce({
+    currentVersion: pkg.version,
+    env: process.env,
+    stdout: process.stdout,
+    stderr: process.stderr,
+    logger: console
+  });
+
+  const env = { ...process.env };
+  const child = spawn(binaryPath, process.argv.slice(2), { stdio: "inherit", env });
+  child.on("exit", (code) => process.exit(code ?? 1));
+  child.on("error", (err) => {
+    console.error(`[docdex] failed to launch binary: ${err.message}`);
+    process.exit(1);
+  });
+}
+
+run().catch((err) => {
+  console.error(`[docdex] unexpected error: ${err?.message || String(err)}`);
+  process.exit(1);
+});

package/lib/install.js

@@ -42,6 +42,31 @@ const DEFAULT_INTEGRITY_CONFIG = Object.freeze({
 const LOCAL_FALLBACK_ENV = "DOCDEX_LOCAL_FALLBACK";
 const LOCAL_BINARY_ENV = "DOCDEX_LOCAL_BINARY";
 const AGENTS_DOC_FILENAME = "agents.md";
+const CLI_WRAPPER_SCRIPT = [
+  "#!/usr/bin/env node",
+  "\"use strict\";",
+  "",
+  "require(\"../lib/cli_entry\");",
+  ""
+].join("\n");
+const MCP_STDIO_WRAPPER_SCRIPT = [
+  "#!/usr/bin/env node",
+  "\"use strict\";",
+  "",
+  "const { runBridge } = require(\"../lib/mcp_stdio_bridge\");",
+  "",
+  "async function main() {",
+  "  try {",
+    "    await runBridge({ stdin: process.stdin, stdout: process.stdout, stderr: process.stderr });",
+  "  } catch (err) {",
+  "    process.stderr.write(`[docdex-mcp-stdio] fatal: ${err}\\n`);",
+  "    process.exit(1);",
+  "  }",
+  "}",
+  "",
+  "main();",
+  ""
+].join("\n");
 
 const EXIT_CODE_BY_ERROR_CODE = Object.freeze({
   DOCDEX_INSTALLER_CONFIG: 2,
@@ -231,6 +256,53 @@ function writeAgentInstructions() {
   }
 }
 
+function shouldWriteWrapper(fsModule, filePath) {
+  if (!fsModule?.existsSync) return true;
+  if (!fsModule.existsSync(filePath)) return true;
+  try {
+    const stat = fsModule.statSync(filePath);
+    if (!stat.isFile()) return true;
+    return stat.size < 8;
+  } catch {
+    return true;
+  }
+}
+
+function ensureCliWrappers({ fsModule = fs, pathModule = path, logger } = {}) {
+  const log = logger || console;
+  const binDir = pathModule.join(__dirname, "..", "bin");
+  const wrappers = [
+    { path: pathModule.join(binDir, "docdex.js"), contents: CLI_WRAPPER_SCRIPT },
+    { path: pathModule.join(binDir, "docdex-mcp-stdio.js"), contents: MCP_STDIO_WRAPPER_SCRIPT }
+  ];
+
+  try {
+    fsModule.mkdirSync(binDir, { recursive: true });
+  } catch (err) {
+    log?.warn?.(`[docdex] unable to ensure CLI wrappers (mkdir failed): ${err?.message || err}`);
+    return false;
+  }
+
+  let repaired = 0;
+  for (const wrapper of wrappers) {
+    if (!shouldWriteWrapper(fsModule, wrapper.path)) continue;
+    try {
+      fsModule.writeFileSync(wrapper.path, wrapper.contents, "utf8");
+      if (process.platform !== "win32" && fsModule.chmodSync) {
+        fsModule.chmodSync(wrapper.path, 0o755);
+      }
+      repaired += 1;
+    } catch (err) {
+      log?.warn?.(`[docdex] unable to write CLI wrapper at ${wrapper.path}: ${err?.message || err}`);
+    }
+  }
+
+  if (repaired > 0) {
+    log?.warn?.(`[docdex] restored ${repaired} CLI wrapper(s) under ${binDir}`);
+  }
+  return repaired > 0;
+}
+
 function selectHttpClient(url) {
   try {
     const protocol = new URL(url).protocol;
@@ -421,6 +493,38 @@ function nowIso() {
   return new Date().toISOString();
 }
 
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isRetryableFsError(err) {
+  if (!err || typeof err !== "object") return false;
+  const code = err.code;
+  return code === "EPERM" || code === "EACCES" || code === "EBUSY" || code === "ENOTEMPTY";
+}
+
+async function withWindowsRetry(fn, { attempts = 6, delayMs = 50 } = {}) {
+  if (process.platform !== "win32") {
+    return fn();
+  }
+  let lastErr = null;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (!isRetryableFsError(err)) throw err;
+      const waitMs = delayMs * Math.pow(2, attempt);
+      await sleep(waitMs);
+    }
+  }
+  throw lastErr;
+}
+
+async function renameWithRetry(fsModule, fromPath, toPath) {
+  return withWindowsRetry(() => fsModule.promises.rename(fromPath, toPath));
+}
+
 async function readJsonFileIfPossible({ fsModule, filePath }) {
   if (!fsModule?.promises?.readFile) {
     return { value: null, error: "readFile_unavailable", errorCode: "READFILE_UNAVAILABLE" };
@@ -447,7 +551,7 @@ async function writeJsonFileAtomic({ fsModule, pathModule, filePath, value }) {
   const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
   const payload = `${JSON.stringify(value, null, 2)}\n`;
   await fsModule.promises.writeFile(tmp, payload, "utf8");
-  await fsModule.promises.rename(tmp, filePath);
+  await renameWithRetry(fsModule, tmp, filePath);
 }
 
 function isValidInstallMetadata(meta) {
@@ -605,7 +709,7 @@ async function installFromLocalBinary({
   writeJsonFileAtomicFn,
   logger
 }) {
-  await fsModule.promises.rm(distDir, { recursive: true, force: true });
+  await withWindowsRetry(() => fsModule.promises.rm(distDir, { recursive: true, force: true }));
   await fsModule.promises.mkdir(distDir, { recursive: true });
   const filename = isWin32 ? "docdexd.exe" : "docdexd";
   const destPath = pathModule.join(distDir, filename);
@@ -723,7 +827,7 @@ function failedDirName({ distDir, nonce }) {
 async function removeDirSafe(fsModule, dirPath) {
   if (!dirPath) return false;
   try {
-    await fsModule.promises.rm(dirPath, { recursive: true, force: true });
+    await withWindowsRetry(() => fsModule.promises.rm(dirPath, { recursive: true, force: true }));
     return true;
   } catch {
     return false;
@@ -865,7 +969,7 @@ async function recoverInterruptedInstall({ fsModule, pathModule, distDir, isWin3
     const candidate = await selectLatestCandidate(fsModule, backups);
     if (candidate) {
       try {
-        await fsModule.promises.rename(candidate.path, distDir);
+        await renameWithRetry(fsModule, candidate.path, distDir);
         recoveredFrom = candidate.path;
         action = "recovered";
       } catch (err) {
@@ -2002,11 +2106,11 @@ async function runInstaller(options) {
 
     if (existsSync && existsSync(distDir)) {
       await fsModule.promises.rm(backupDir, { recursive: true, force: true }).catch(() => {});
-      await fsModule.promises.rename(distDir, backupDir);
+      await renameWithRetry(fsModule, distDir, backupDir);
       backupMoved = true;
     }
 
-    await fsModule.promises.rename(stagingDir, distDir);
+    await renameWithRetry(fsModule, stagingDir, distDir);
     promoted = true;
 
     if (typeof restartFn === "function") {
@@ -2076,7 +2180,7 @@ async function runInstaller(options) {
         if (existsSync(distDir)) {
           await fsModule.promises.rm(distDir, { recursive: true, force: true });
         }
-        await fsModule.promises.rename(backupDir, distDir);
+        await renameWithRetry(fsModule, backupDir, distDir);
         rollbackStatus = "restored previous installation";
         rollbackSucceeded = true;
       } else if (promoted && !backupMoved) {
@@ -2137,6 +2241,11 @@ async function main() {
   const env = process.env;
   const distBaseCandidates = resolveDistBaseCandidates({ env });
   const distBaseDir = resolveDistBaseDir({ env, fsModule: fs });
+  try {
+    ensureCliWrappers({ logger: console });
+  } catch (err) {
+    console.warn(`[docdex] CLI wrapper check failed: ${err?.message || err}`);
+  }
   if (
     process.platform === "win32" &&
     !env?.DOCDEX_DIST_DIR &&

package/lib/mcp_stdio_cli.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+"use strict";
+
+const { runBridge } = require("./mcp_stdio_bridge");
+
+async function main() {
+  try {
+    await runBridge({ stdin: process.stdin, stdout: process.stdout, stderr: process.stderr });
+  } catch (err) {
+    process.stderr.write(`[docdex-mcp-stdio] fatal: ${err}\n`);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "docdex",
-  "version": "0.2.30",
+  "version": "0.2.32",
   "mcpName": "io.github.bekirdag/docdex",
   "description": "Local-first documentation and code indexer with HTTP/MCP search, AST, and agent memory.",
   "bin": {
-    "docdex": "bin/docdex.js",
-    "docdexd": "bin/docdex.js",
-    "docdex-mcp-stdio": "bin/docdex-mcp-stdio.js"
+    "docdex": "lib/cli_entry.js",
+    "docdexd": "lib/cli_entry.js",
+    "docdex-mcp-stdio": "lib/mcp_stdio_cli.js"
   },
   "files": [
     "bin",