docdex 0.2.29 → 0.2.31

package/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## 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.
 
 ## 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.29 ----
+---- START OF DOCDEX INFO V0.2.31 ----
 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/bin/docdex.js

@@ -6,6 +6,7 @@ const path = require("node:path");
 const { spawn } = require("node:child_process");
 
 const pkg = require("../package.json");
+const { resolveDistBaseDir, resolveDistBaseCandidates } = require("../lib/paths");
 const {
   artifactName,
   detectLibcFromRuntime,
@@ -53,6 +54,30 @@ function formatInstallSource(meta) {
   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;
@@ -81,7 +106,10 @@ function runDoctor() {
     const targetTriple = targetTripleForPlatformKey(platformKey);
     const expectedAssetName = artifactName(platformKey);
     const expectedAssetPattern = assetPatternForPlatformKey(platformKey, { exampleAssetName: expectedAssetName });
-    const basePath = path.join(__dirname, "..", "dist", platformKey);
+    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);
 
@@ -179,11 +207,7 @@ async function run() {
     return;
   }
 
-  const basePath = path.join(__dirname, "..", "dist", platformKey);
-  const binaryPath = path.join(
-    basePath,
-    process.platform === "win32" ? "docdexd.exe" : "docdexd"
-  );
+  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.`);

package/lib/cli_entry.js

@@ -0,0 +1,241 @@
+"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

@@ -8,7 +8,7 @@ const os = require("node:os");
 const path = require("node:path");
 const { pipeline } = require("node:stream/promises");
 const crypto = require("node:crypto");
-const { spawn } = require("node:child_process");
+const { spawn, spawnSync } = require("node:child_process");
 
 const pkg = require("../package.json");
 const {
@@ -21,6 +21,7 @@ const {
 } = require("./platform");
 const { ManifestResolutionError, resolveCanonicalAssetForTargetTriple } = require("./release_manifest");
 const { runPostInstallSetup } = require("./postinstall_setup");
+const { resolveDistBaseDir, resolveDistBaseCandidates } = require("./paths");
 
 const MAX_REDIRECTS = 5;
 const USER_AGENT = "docdex-installer";
@@ -41,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,
@@ -230,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;
@@ -368,6 +441,40 @@ async function extractTarballWithSystemTar(archivePath, targetDir) {
   });
 }
 
+function escapePowerShellLiteral(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+function tryUnblockWindowsBinary(filePath, { logger, fsModule = fs, spawnSyncFn = spawnSync } = {}) {
+  if (process.platform !== "win32") return { ok: false, reason: "not_win32" };
+  if (!filePath) return { ok: false, reason: "missing_path" };
+  const existsSync = typeof fsModule.existsSync === "function" ? fsModule.existsSync.bind(fsModule) : null;
+  if (existsSync && !existsSync(filePath)) return { ok: false, reason: "missing_file" };
+  let unblocked = false;
+  try {
+    const zonePath = `${filePath}:Zone.Identifier`;
+    if (typeof fsModule.rmSync === "function") {
+      fsModule.rmSync(zonePath, { force: true });
+      unblocked = true;
+    } else if (typeof fsModule.unlinkSync === "function") {
+      try {
+        fsModule.unlinkSync(zonePath);
+        unblocked = true;
+      } catch {}
+    }
+  } catch {}
+  try {
+    const result = spawnSyncFn("powershell.exe", [
+      "-NoProfile",
+      "-Command",
+      `Unblock-File -LiteralPath ${escapePowerShellLiteral(filePath)}`
+    ], { stdio: "ignore" });
+    if (result?.status === 0) unblocked = true;
+  } catch {}
+  if (unblocked) return { ok: true, reason: "unblocked" };
+  return { ok: false, reason: "noop" };
+}
+
 async function sha256File(filePath) {
   return new Promise((resolve, reject) => {
     const hash = crypto.createHash("sha256");
@@ -386,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" };
@@ -412,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) {
@@ -570,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);
@@ -688,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;
@@ -830,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) {
@@ -1954,19 +2093,24 @@ async function runInstaller(options) {
         manifestName: manifestAttempt?.manifestName ?? null,
         manifestVersion: manifestAttempt?.resolved?.manifestVersion ?? null,
         fallbackAttempted: source === "fallback",
-        binaryPath: stagedBinaryPath
+        binaryPath: stagedBinaryPath,
+        hint: isWin32 ? "possible_av_quarantine" : null
       });
     }
 
-    await fsModule.promises.chmod(stagedBinaryPath, 0o755);
+    if (isWin32) {
+      tryUnblockWindowsBinary(stagedBinaryPath, { logger, fsModule });
+    } else {
+      await fsModule.promises.chmod(stagedBinaryPath, 0o755);
+    }
 
     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") {
@@ -1974,6 +2118,9 @@ async function runInstaller(options) {
     }
 
     const binaryPath = pathModule.join(distDir, isWin32 ? "docdexd.exe" : "docdexd");
+    if (isWin32) {
+      tryUnblockWindowsBinary(binaryPath, { logger, fsModule });
+    }
     const binarySha256 = await sha256FileFn(binaryPath);
     const metadata = {
       schemaVersion: INSTALL_METADATA_SCHEMA_VERSION,
@@ -2033,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) {
@@ -2091,12 +2238,30 @@ async function runInstaller(options) {
 }
 
 async function main() {
-  const result = await runInstaller();
+  const env = process.env;
+  const distBaseCandidates = resolveDistBaseCandidates({ env });
+  const distBaseDir = resolveDistBaseDir({ env, fsModule: fs });
   try {
-    await runPostInstallSetup({ binaryPath: result?.binaryPath });
+    ensureCliWrappers({ logger: console });
+  } catch (err) {
+    console.warn(`[docdex] CLI wrapper check failed: ${err?.message || err}`);
+  }
+  if (
+    process.platform === "win32" &&
+    !env?.DOCDEX_DIST_DIR &&
+    distBaseCandidates[0] &&
+    distBaseDir !== distBaseCandidates[0]
+  ) {
+    console.warn(
+      `[docdex] LOCALAPPDATA not writable; using fallback dist dir: ${distBaseDir}. Set DOCDEX_DIST_DIR to override.`
+    );
+  }
+  const result = await runInstaller({ env, distBaseDir });
+  try {
+    const skipDaemon = Boolean(env?.npm_lifecycle_event);
+    await runPostInstallSetup({ binaryPath: result?.binaryPath, env, skipDaemon, distBaseDir });
   } catch (err) {
     console.warn(`[docdex] postinstall setup failed: ${err?.message || err}`);
-    throw err;
   }
   try {
     writeAgentInstructions();
@@ -2134,6 +2299,11 @@ function printPostInstallBanner() {
     "\x1b[33mSetup:\x1b[0m configures Ollama/models + browser.",
     "\x1b[34mTip:\x1b[0m after setup, the daemon should auto-start; if not, run \x1b[36m`docdexd daemon`\x1b[0m"
   ];
+  if (process.platform === "win32") {
+    content.push(
+      "\x1b[33mNote:\x1b[0m If PowerShell blocks `docdex`, run `docdex.cmd` or set ExecutionPolicy RemoteSigned."
+    );
+  }
   width = Math.max(72, content.reduce((max, line) => Math.max(max, stripAnsi(line).length), 0));
   const padLine = (text) => {
     const visible = stripAnsi(text).length;
@@ -2361,18 +2531,23 @@ function describeFatalError(err) {
   }
 
   if (err instanceof ArchiveInvalidError) {
+    const lines = [
+      `[docdex] install failed: ${err.message}`,
+      `[docdex] error code: ${err.code}`,
+      err.details?.binaryPath ? `[docdex] Expected binary path: ${err.details.binaryPath}` : null
+    ].filter(Boolean);
+    if (process.platform === "win32" && err.details?.hint === "possible_av_quarantine") {
+      lines.push(
+        "[docdex] Windows Defender/AV may have quarantined the downloaded binary.",
+        "[docdex] Re-run the install or add an exclusion for the Docdex dist directory.",
+        "[docdex] Tip: set DOCDEX_DIST_DIR to a writable directory outside protected paths."
+      );
+    }
     return {
       code: err.code,
       exitCode: err.exitCode || EXIT_CODE_BY_ERROR_CODE[err.code] || 1,
       details: withBaseDetails(err.details),
-      lines: appendInstallSafetyLines(
-        [
-          `[docdex] install failed: ${err.message}`,
-          `[docdex] error code: ${err.code}`,
-          err.details?.binaryPath ? `[docdex] Expected binary path: ${err.details.binaryPath}` : null
-        ].filter(Boolean),
-        err
-      )
+      lines: appendInstallSafetyLines(lines, err)
     };
   }
 
@@ -2414,6 +2589,25 @@ function describeFatalError(err) {
   }
 
   const code = (err && typeof err.code === "string" && err.code) || "DOCDEX_INSTALL_FAILED";
+  if (code === "EACCES" || code === "EPERM") {
+    const location = err?.path ? ` (${err.path})` : "";
+    return {
+      code,
+      exitCode: EXIT_CODE_BY_ERROR_CODE[code] || 1,
+      details: withBaseDetails(err && err.details),
+      lines: appendInstallSafetyLines(
+        [
+          `[docdex] install failed: ${err?.message || "permission denied"}`,
+          `[docdex] error code: ${code}`,
+          `[docdex] Ensure write access${location} or set DOCDEX_DIST_DIR to a writable location.`,
+          process.platform === "win32"
+            ? "[docdex] On Windows, run in an elevated shell if needed."
+            : null
+        ].filter(Boolean),
+        err
+      )
+    };
+  }
   return {
     code,
     exitCode: (err && typeof err.exitCode === "number" && err.exitCode) || EXIT_CODE_BY_ERROR_CODE[code] || 1,

package/lib/paths.js

@@ -0,0 +1,112 @@
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+function resolveUserDataDir({
+  env = process.env,
+  platform = process.platform,
+  homedir = os.homedir,
+  pathModule = path
+} = {}) {
+  const home = typeof homedir === "function" ? homedir() : os.homedir();
+  if (platform === "win32") {
+    const base = env?.LOCALAPPDATA || pathModule.join(home, "AppData", "Local");
+    return pathModule.resolve(base);
+  }
+  if (platform === "darwin") {
+    return pathModule.join(home, "Library", "Application Support");
+  }
+  const xdg = env?.XDG_DATA_HOME;
+  if (xdg && String(xdg).trim()) return pathModule.resolve(String(xdg).trim());
+  return pathModule.join(home, ".local", "share");
+}
+
+function resolveDocdexDataDir(options = {}) {
+  const pathModule = options.pathModule || path;
+  return pathModule.join(resolveUserDataDir({ ...options, pathModule }), "docdex");
+}
+
+function resolveDistBaseCandidates(options = {}) {
+  const env = options.env || process.env;
+  const pathModule = options.pathModule || path;
+  const override = env?.DOCDEX_DIST_DIR;
+  if (override && String(override).trim()) {
+    return [pathModule.resolve(String(override).trim())];
+  }
+  const candidates = [];
+  const primary = pathModule.join(resolveDocdexDataDir({ ...options, pathModule }), "dist");
+  if (primary) candidates.push(primary);
+  const homedir = typeof options.homedir === "function" ? options.homedir : os.homedir;
+  const home = homedir ? homedir() : os.homedir();
+  if (home) {
+    const fallback = pathModule.join(home, ".docdex", "dist");
+    if (!candidates.includes(fallback)) candidates.push(fallback);
+  }
+  return candidates;
+}
+
+function findExistingParent(candidate, fsModule, pathModule) {
+  if (!candidate) return null;
+  let current = pathModule.resolve(candidate);
+  while (current && !fsModule.existsSync(current)) {
+    const parent = pathModule.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+  return current;
+}
+
+function canWritePath(candidate, fsModule) {
+  if (!fsModule?.accessSync) return true;
+  const mode = fsModule.constants?.W_OK ?? 0o2;
+  try {
+    fsModule.accessSync(candidate, mode);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveDistBaseDir(options = {}) {
+  const fsModule = options.fsModule || fs;
+  const pathModule = options.pathModule || path;
+  const candidates = resolveDistBaseCandidates({ ...options, pathModule });
+  if (!candidates.length) {
+    return pathModule.join(resolveDocdexDataDir({ ...options, pathModule }), "dist");
+  }
+  for (const candidate of candidates) {
+    if (!fsModule?.existsSync) return candidate;
+    const parent = findExistingParent(candidate, fsModule, pathModule);
+    if (parent && canWritePath(parent, fsModule)) {
+      return candidate;
+    }
+  }
+  return candidates[0];
+}
+
+function resolveBinDir(options = {}) {
+  const pathModule = options.pathModule || path;
+  if (options.distBaseDir) {
+    return pathModule.join(pathModule.dirname(options.distBaseDir), "bin");
+  }
+  return pathModule.join(resolveDocdexDataDir({ ...options, pathModule }), "bin");
+}
+
+function resolveWindowsRunnerPath(options = {}) {
+  const pathModule = options.pathModule || path;
+  if (options.distBaseDir) {
+    return pathModule.join(pathModule.dirname(options.distBaseDir), "run-daemon.cmd");
+  }
+  return pathModule.join(resolveDocdexDataDir({ ...options, pathModule }), "run-daemon.cmd");
+}
+
+module.exports = {
+  resolveUserDataDir,
+  resolveDocdexDataDir,
+  resolveDistBaseCandidates,
+  resolveDistBaseDir,
+  resolveBinDir,
+  resolveWindowsRunnerPath
+};

package/lib/postinstall_setup.js

@@ -11,6 +11,12 @@ const tty = require("node:tty");
 const { spawn, spawnSync } = require("node:child_process");
 
 const { detectPlatformKey, UnsupportedPlatformError } = require("./platform");
+const {
+  resolveDistBaseDir,
+  resolveDistBaseCandidates,
+  resolveBinDir,
+  resolveWindowsRunnerPath
+} = require("./paths");
 
 const DEFAULT_HOST = "127.0.0.1";
 const DEFAULT_DAEMON_PORT = 28491;
@@ -1391,12 +1397,38 @@ function clientInstructionPaths() {
   }
 }
 
-function resolveBinaryPath({ binaryPath } = {}) {
+function sanitizeVersionForFilename(version) {
+  if (!version) return null;
+  return String(version).replace(/[^0-9A-Za-z._-]/g, "_");
+}
+
+function resolveBinaryPath({ binaryPath, env, distBaseDir, distBaseCandidates } = {}) {
   if (binaryPath && fs.existsSync(binaryPath)) return binaryPath;
   try {
     const platformKey = detectPlatformKey();
-    const candidate = path.join(__dirname, "..", "dist", platformKey, process.platform === "win32" ? "docdexd.exe" : "docdexd");
-    if (fs.existsSync(candidate)) return candidate;
+    const isWin32 = process.platform === "win32";
+    const resolvedVersion = sanitizeVersionForFilename(
+      normalizeVersion(resolvePackageVersion())
+    );
+    const resolvedDistBaseDir = distBaseDir || resolveDistBaseDir({ env, fsModule: fs });
+    const binDir = resolveBinDir({ env, distBaseDir: resolvedDistBaseDir });
+    const baseCandidates = distBaseCandidates || resolveDistBaseCandidates({ env });
+    const candidates = [];
+    if (binDir) {
+      if (isWin32 && resolvedVersion) {
+        candidates.push(path.join(binDir, `docdexd-${resolvedVersion}.exe`));
+      }
+      candidates.push(path.join(binDir, isWin32 ? "docdexd.exe" : "docdexd"));
+    }
+    for (const base of baseCandidates) {
+      candidates.push(path.join(base, platformKey, isWin32 ? "docdexd.exe" : "docdexd"));
+    }
+    candidates.push(
+      path.join(__dirname, "..", "dist", platformKey, isWin32 ? "docdexd.exe" : "docdexd")
+    );
+    for (const candidate of candidates) {
+      if (candidate && fs.existsSync(candidate)) return candidate;
+    }
   } catch (err) {
     if (!(err instanceof UnsupportedPlatformError)) throw err;
   }
@@ -1416,16 +1448,26 @@ function isMacProtectedPath(candidate) {
   return ["Desktop", "Documents", "Downloads"].some((dir) => isPathWithin(path.join(home, dir), candidate));
 }
 
-function ensureStartupBinary(binaryPath, { logger } = {}) {
+function ensureStartupBinary(binaryPath, { logger, env, distBaseDir } = {}) {
   if (!binaryPath) return null;
-  if (!isMacProtectedPath(binaryPath) && !isTempPath(binaryPath)) return binaryPath;
-  const binDir = path.join(os.homedir(), ".docdex", "bin");
-  const target = path.join(binDir, path.basename(binaryPath));
+  const isWin32 = process.platform === "win32";
+  const mustCopy = isWin32 || isMacProtectedPath(binaryPath) || isTempPath(binaryPath);
+  if (!mustCopy) return binaryPath;
+  const binDir = resolveBinDir({ env, distBaseDir });
+  const resolvedVersion = sanitizeVersionForFilename(
+    normalizeVersion(resolvePackageVersion())
+  );
+  const targetName = isWin32 && resolvedVersion
+    ? `docdexd-${resolvedVersion}.exe`
+    : path.basename(binaryPath);
+  const target = path.join(binDir, targetName);
   if (fs.existsSync(target)) return target;
   try {
     fs.mkdirSync(binDir, { recursive: true });
     fs.copyFileSync(binaryPath, target);
-    fs.chmodSync(target, 0o755);
+    if (!isWin32) {
+      fs.chmodSync(target, 0o755);
+    }
     return target;
   } catch (err) {
     logger?.warn?.(`[docdex] failed to stage daemon binary for startup: ${err?.message || err}`);
@@ -1433,8 +1475,8 @@ function ensureStartupBinary(binaryPath, { logger } = {}) {
   }
 }
 
-function resolveStartupBinaryPaths({ binaryPath, logger } = {}) {
-  const resolvedBinary = ensureStartupBinary(binaryPath, { logger });
+function resolveStartupBinaryPaths({ binaryPath, logger, env, distBaseDir } = {}) {
+  const resolvedBinary = ensureStartupBinary(binaryPath, { logger, env, distBaseDir });
   return { binaryPath: resolvedBinary };
 }
 
@@ -2112,7 +2154,32 @@ function buildDaemonEnv() {
   return Object.fromEntries(buildDaemonEnvPairs());
 }
 
-function registerStartup({ binaryPath, port, repoRoot, logger }) {
+function escapeCmdArg(value) {
+  return `"${String(value).replace(/"/g, "\"\"")}"`;
+}
+
+function writeWindowsRunner({ binaryPath, args, envPairs, workingDir, logger, distBaseDir } = {}) {
+  const runnerPath = resolveWindowsRunnerPath({ distBaseDir });
+  const lines = ["@echo off", "setlocal"];
+  for (const [key, value] of envPairs || []) {
+    lines.push(`set "${key}=${value}"`);
+  }
+  if (workingDir) {
+    lines.push(`cd /d ${escapeCmdArg(workingDir)}`);
+  }
+  const argString = (args || []).map((arg) => escapeCmdArg(arg)).join(" ");
+  lines.push(`${escapeCmdArg(binaryPath)} ${argString}`.trim());
+  try {
+    fs.mkdirSync(path.dirname(runnerPath), { recursive: true });
+    fs.writeFileSync(runnerPath, `${lines.join("\r\n")}\r\n`);
+    return runnerPath;
+  } catch (err) {
+    logger?.warn?.(`[docdex] failed to write Windows runner: ${err?.message || err}`);
+    return null;
+  }
+}
+
+function registerStartup({ binaryPath, port, repoRoot, logger, distBaseDir }) {
   if (!binaryPath) return { ok: false, reason: "missing_binary" };
   stopDaemonService({ logger });
   const envPairs = buildDaemonEnvPairs();
@@ -2208,11 +2275,16 @@ function registerStartup({ binaryPath, port, repoRoot, logger }) {
 
   if (process.platform === "win32") {
     const taskName = "Docdex Daemon";
-    const joinedArgs = args.map((arg) => `"${arg}"`).join(" ");
-    const envParts = envPairs.map(([key, value]) => `set "${key}=${value}"`);
-    const cdCommand = workingDir ? `cd /d "${workingDir}"` : null;
-    const taskArgs =
-      `"cmd.exe" /c "${envParts.join(" && ")}${cdCommand ? ` && ${cdCommand}` : ""} && \"${binaryPath}\" ${joinedArgs}"`;
+    const runnerPath = writeWindowsRunner({
+      binaryPath,
+      args,
+      envPairs,
+      workingDir,
+      logger,
+      distBaseDir
+    });
+    if (!runnerPath) return { ok: false, reason: "runner_failed" };
+    const taskArgs = `cmd.exe /c ${escapeCmdArg(runnerPath)}`;
     const create = spawnSync("schtasks", [
       "/Create",
       "/F",
@@ -2236,12 +2308,13 @@ function registerStartup({ binaryPath, port, repoRoot, logger }) {
   return { ok: false, reason: "unsupported_platform" };
 }
 
-async function startDaemonWithHealthCheck({ binaryPath, port, host, logger }) {
+async function startDaemonWithHealthCheck({ binaryPath, port, host, logger, distBaseDir }) {
   const startup = registerStartup({
     binaryPath,
     port,
     repoRoot: daemonRootPath(),
-    logger
+    logger,
+    distBaseDir
   });
   if (!startup.ok) {
     logger?.warn?.(`[docdex] daemon service registration failed (${startup.reason || "unknown"}).`);
@@ -2281,6 +2354,17 @@ function startupFailureReported() {
   return fs.existsSync(path.join(stateDir(), STARTUP_FAILURE_MARKER));
 }
 
+function isNpmLifecycle(env = process.env) {
+  return Boolean(env?.npm_lifecycle_event);
+}
+
+function shouldSkipDaemonSideEffects({ env = process.env, skipDaemon } = {}) {
+  if (skipDaemon) return true;
+  if (isNpmLifecycle(env)) return true;
+  if (parseEnvBool(env?.DOCDEX_DAEMON_SKIP_SETUP)) return true;
+  return false;
+}
+
 function shouldSkipSetup(env = process.env) {
   return parseEnvBool(env.DOCDEX_SETUP_SKIP) === true;
 }
@@ -2381,34 +2465,49 @@ function launchSetupWizard({
   return { ok: false, reason: "unsupported_platform" };
 }
 
-async function runPostInstallSetup({ binaryPath, logger } = {}) {
+async function runPostInstallSetup({ binaryPath, logger, env, skipDaemon, distBaseDir } = {}) {
   const log = logger || console;
+  const effectiveEnv = env || process.env;
+  const distCandidates = resolveDistBaseCandidates({ env: effectiveEnv });
+  const resolvedDistBaseDir = distBaseDir || resolveDistBaseDir({ env: effectiveEnv, fsModule: fs });
+  let allowDaemon = !shouldSkipDaemonSideEffects({ env: effectiveEnv, skipDaemon });
   const configPath = defaultConfigPath();
   let existingConfig = "";
   if (fs.existsSync(configPath)) {
     existingConfig = fs.readFileSync(configPath, "utf8");
   }
   const port = DEFAULT_DAEMON_PORT;
-  const portState = await resolveDaemonPortState({
-    host: DEFAULT_HOST,
-    port,
-    logger: log
-  });
-  if (!portState.available && !portState.reuseExisting) {
-    log.error?.(
-      `[docdex] ${DEFAULT_HOST}:${port} is already in use; docdex requires a fixed port. Stop the process using this port and re-run the install.`
-    );
-    throw new Error(`docdex requires ${DEFAULT_HOST}:${port}, but the port is already in use`);
+  let portState = { available: true, reuseExisting: false };
+  if (allowDaemon) {
+    portState = await resolveDaemonPortState({
+      host: DEFAULT_HOST,
+      port,
+      logger: log
+    });
+    if (!portState.available && !portState.reuseExisting) {
+      log.warn?.(
+        `[docdex] ${DEFAULT_HOST}:${port} is already in use; skipping daemon startup. Run \`docdexd daemon\` after freeing the port.`
+      );
+      recordStartupFailure({ reason: "port_in_use", host: DEFAULT_HOST, port });
+      allowDaemon = false;
+    }
   }
 
   const daemonRoot = ensureDaemonRoot();
-  const resolvedBinary = resolveBinaryPath({ binaryPath });
+  const resolvedBinary = resolveBinaryPath({
+    binaryPath,
+    env: effectiveEnv,
+    distBaseDir: resolvedDistBaseDir,
+    distBaseCandidates: distCandidates
+  });
   const startupBinaries = resolveStartupBinaryPaths({
     binaryPath: resolvedBinary,
-    logger: log
+    logger: log,
+    env: effectiveEnv,
+    distBaseDir: resolvedDistBaseDir
   });
-  let reuseExisting = portState.reuseExisting;
-  if (reuseExisting) {
+  let reuseExisting = allowDaemon ? portState.reuseExisting : false;
+  if (reuseExisting && allowDaemon) {
     const daemonInfo = await fetchDaemonInfo({ host: DEFAULT_HOST, port });
     const daemonVersion = normalizeVersion(daemonInfo?.version);
     const packageVersion = normalizeVersion(resolvePackageVersion());
@@ -2426,22 +2525,29 @@ async function runPostInstallSetup({ binaryPath, logger } = {}) {
           port
         });
         if (!released) {
-          throw new Error("docdex daemon restart failed; port still in use");
+          log.warn?.("[docdex] daemon restart failed; port still in use.");
+          recordStartupFailure({ reason: "restart_failed", host: DEFAULT_HOST, port });
+          allowDaemon = false;
         }
         reuseExisting = false;
       }
     }
   }
-  if (!reuseExisting) {
+  let startupOk = reuseExisting;
+  if (allowDaemon && !reuseExisting) {
     const result = await startDaemonWithHealthCheck({
       binaryPath: startupBinaries.binaryPath,
       port,
       host: DEFAULT_HOST,
-      logger: log
+      logger: log,
+      distBaseDir: resolvedDistBaseDir
     });
     if (!result.ok) {
       log.warn?.(`[docdex] daemon failed to start on ${DEFAULT_HOST}:${port}.`);
-      throw new Error("docdex daemon failed to start");
+      recordStartupFailure({ reason: result.reason || "startup_failed", host: DEFAULT_HOST, port });
+      allowDaemon = false;
+    } else {
+      startupOk = true;
     }
   }
 
@@ -2475,8 +2581,13 @@ async function runPostInstallSetup({ binaryPath, logger } = {}) {
   }
   upsertCodexConfig(paths.codex, codexUrl);
   applyAgentInstructions({ logger: log });
-  clearStartupFailure();
-  const setupLaunch = launchSetupWizard({ binaryPath: startupBinaries.binaryPath, logger: log });
+  if (startupOk) {
+    clearStartupFailure();
+  }
+  const skipWizard = isNpmLifecycle(effectiveEnv) || shouldSkipSetup(effectiveEnv);
+  const setupLaunch = skipWizard
+    ? { ok: false, reason: "skipped" }
+    : launchSetupWizard({ binaryPath: startupBinaries.binaryPath, logger: log });
   if (!setupLaunch.ok && setupLaunch.reason !== "skipped") {
     log.warn?.("[docdex] setup wizard did not launch. Run `docdex setup`.");
     recordSetupPending({ reason: setupLaunch.reason, port, repoRoot: daemonRoot });

package/lib/uninstall.js

@@ -6,6 +6,7 @@ const net = require("node:net");
 const os = require("node:os");
 const path = require("node:path");
 const { spawnSync } = require("node:child_process");
+const { resolveDocdexDataDir } = require("./paths");
 
 const DAEMON_TASK_NAME = "Docdex Daemon";
 const STARTUP_FAILURE_MARKER = "startup_registration_failed.json";
@@ -24,6 +25,10 @@ function daemonRootPath() {
   return path.join(docdexRootPath(), "daemon_root");
 }
 
+function docdexDataDir() {
+  return resolveDocdexDataDir({ env: process.env });
+}
+
 function stateDir() {
   return path.join(docdexRootPath(), "state");
 }
@@ -108,12 +113,15 @@ function manualStopInstructions() {
     ];
   }
   if (process.platform === "win32") {
+    const dataDir = docdexDataDir();
     return [
       "Manual cleanup required:",
       `- schtasks /End /TN "${DAEMON_TASK_NAME}"`,
       "- schtasks /Delete /TN \"Docdex Daemon\" /F",
       "- taskkill /IM docdexd.exe /T /F",
       "- del %USERPROFILE%\\.docdex\\locks\\daemon.lock",
+      `- del "${path.join(dataDir, "run-daemon.cmd")}"`,
+      `- rmdir /S /Q "${dataDir}"`,
       "- netstat -ano | findstr 28491",
     ];
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docdex",
-  "version": "0.2.29",
+  "version": "0.2.31",
   "mcpName": "io.github.bekirdag/docdex",
   "description": "Local-first documentation and code indexer with HTTP/MCP search, AST, and agent memory.",
   "bin": {