docdex 0.2.28 → 0.2.30

package/assets/agents.md

@@ -1,4 +1,4 @@
----- START OF DOCDEX INFO V0.2.27 ----
+---- START OF DOCDEX INFO V0.2.30 ----
 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/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";
@@ -368,6 +369,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");
@@ -1954,11 +1989,16 @@ 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(() => {});
@@ -1974,6 +2014,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,
@@ -2091,12 +2134,25 @@ 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 });
+  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 {
-    await runPostInstallSetup({ binaryPath: result?.binaryPath });
+    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 +2190,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 +2422,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 +2480,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;
@@ -18,6 +24,8 @@ const DAEMON_HEALTH_TIMEOUT_MS = 8000;
 const DAEMON_HEALTH_REQUEST_TIMEOUT_MS = 1000;
 const DAEMON_HEALTH_POLL_INTERVAL_MS = 200;
 const DAEMON_HEALTH_PATH = "/healthz";
+const DAEMON_INFO_PATH = "/ai-help";
+const DAEMON_PORT_RELEASE_TIMEOUT_MS = 5000;
 const STARTUP_FAILURE_MARKER = "startup_registration_failed.json";
 const DEFAULT_OLLAMA_MODEL = "nomic-embed-text";
 const DEFAULT_OLLAMA_CHAT_MODEL = "phi3.5:3.8b";
@@ -120,6 +128,139 @@ async function waitForDaemonHealthy({ host, port, timeoutMs = DAEMON_HEALTH_TIME
   return false;
 }
 
+async function waitForPortAvailable({
+  host,
+  port,
+  timeoutMs = DAEMON_PORT_RELEASE_TIMEOUT_MS
+}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isPortAvailable(port, host)) {
+      return true;
+    }
+    await sleep(DAEMON_HEALTH_POLL_INTERVAL_MS);
+  }
+  return false;
+}
+
+function isPidRunning(pid) {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === "EPERM";
+  }
+}
+
+function readDaemonLockMetadataForPort(port) {
+  for (const lockPath of daemonLockPaths()) {
+    if (!lockPath || !fs.existsSync(lockPath)) continue;
+    try {
+      const raw = fs.readFileSync(lockPath, "utf8");
+      if (!raw.trim()) continue;
+      const payload = JSON.parse(raw);
+      const lockPort = Number(payload?.port);
+      const pid = Number(payload?.pid);
+      if (!Number.isFinite(lockPort) || lockPort !== port) continue;
+      return { pid, port: lockPort };
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+function normalizeVersion(value) {
+  return String(value || "")
+    .trim()
+    .replace(/^v/i, "");
+}
+
+function fetchDaemonInfo({ host, port, timeoutMs = DAEMON_HEALTH_REQUEST_TIMEOUT_MS }) {
+  return new Promise((resolve) => {
+    const req = http.request(
+      {
+        host,
+        port,
+        path: DAEMON_INFO_PATH,
+        method: "GET",
+        timeout: timeoutMs
+      },
+      (res) => {
+        let body = "";
+        res.setEncoding("utf8");
+        res.on("data", (chunk) => {
+          body += chunk;
+        });
+        res.on("end", () => {
+          if (res.statusCode !== 200) return resolve(null);
+          try {
+            const payload = JSON.parse(body);
+            resolve(payload);
+          } catch {
+            resolve(null);
+          }
+        });
+      }
+    );
+    req.on("timeout", () => {
+      req.destroy();
+      resolve(null);
+    });
+    req.on("error", () => resolve(null));
+    req.end();
+  });
+}
+
+function checkDocdexIdentity({ host, port, timeoutMs = DAEMON_HEALTH_REQUEST_TIMEOUT_MS }) {
+  return fetchDaemonInfo({ host, port, timeoutMs }).then((payload) => payload?.product === "Docdex");
+}
+
+async function resolveDaemonPortState({ host, port, logger, deps } = {}) {
+  const log = logger || console;
+  const helpers = {
+    isPortAvailable,
+    checkDaemonHealth,
+    checkDocdexIdentity,
+    stopDaemonService,
+    stopDaemonFromLock,
+    stopDaemonByName,
+    clearDaemonLocks,
+    sleep,
+    readDaemonLockMetadataForPort,
+    isPidRunning,
+    normalizeVersion
+  };
+  if (deps && typeof deps === "object") {
+    Object.assign(helpers, deps);
+  }
+
+  let available = await helpers.isPortAvailable(port, host);
+  if (available) return { available: true, reuseExisting: false, stopped: false };
+
+  helpers.stopDaemonService({ logger: log });
+  helpers.stopDaemonFromLock({ logger: log });
+  helpers.stopDaemonByName({ logger: log });
+  await helpers.sleep(DAEMON_HEALTH_POLL_INTERVAL_MS);
+
+  available = await helpers.isPortAvailable(port, host);
+  if (available) {
+    helpers.clearDaemonLocks();
+    return { available: true, reuseExisting: false, stopped: true };
+  }
+
+  const lockMeta = helpers.readDaemonLockMetadataForPort(port);
+  const lockRunning = lockMeta ? helpers.isPidRunning(lockMeta.pid) : false;
+  const healthy = await helpers.checkDaemonHealth({ host, port });
+  const identity = lockRunning ? true : await helpers.checkDocdexIdentity({ host, port });
+  const reuseExisting = Boolean(lockRunning || healthy || identity);
+  if (reuseExisting) {
+    log.warn?.(`[docdex] ${host}:${port} already in use by a running docdex daemon; reusing it.`);
+  }
+  return { available: false, reuseExisting, stopped: false };
+}
+
 function parseServerBind(contents) {
   let inServer = false;
   const lines = contents.split(/\r?\n/);
@@ -1256,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;
   }
@@ -1281,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}`);
@@ -1298,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 };
 }
 
@@ -1977,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();
@@ -2073,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",
@@ -2101,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"}).`);
@@ -2146,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;
 }
@@ -2246,41 +2465,90 @@ 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 available = await isPortAvailable(port, DEFAULT_HOST);
-  if (!available) {
-    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
   });
-  stopDaemonService({ logger: log });
-  stopDaemonFromLock({ logger: log });
-  stopDaemonByName({ logger: log });
-  clearDaemonLocks();
-  const result = await startDaemonWithHealthCheck({
-    binaryPath: startupBinaries.binaryPath,
-    port,
-    host: DEFAULT_HOST,
-    logger: log
-  });
-  if (!result.ok) {
-    log.warn?.(`[docdex] daemon failed to start on ${DEFAULT_HOST}:${port}.`);
-    throw new Error("docdex daemon failed to start");
+  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());
+    if (daemonInfo?.product === "Docdex" && daemonVersion && packageVersion) {
+      if (daemonVersion !== packageVersion) {
+        log.warn?.(
+          `[docdex] daemon version ${daemonVersion} differs from package ${packageVersion}; restarting daemon.`
+        );
+        stopDaemonService({ logger: log });
+        stopDaemonFromLock({ logger: log });
+        stopDaemonByName({ logger: log });
+        clearDaemonLocks();
+        const released = await waitForPortAvailable({
+          host: DEFAULT_HOST,
+          port
+        });
+        if (!released) {
+          log.warn?.("[docdex] daemon restart failed; port still in use.");
+          recordStartupFailure({ reason: "restart_failed", host: DEFAULT_HOST, port });
+          allowDaemon = false;
+        }
+        reuseExisting = false;
+      }
+    }
+  }
+  let startupOk = reuseExisting;
+  if (allowDaemon && !reuseExisting) {
+    const result = await startDaemonWithHealthCheck({
+      binaryPath: startupBinaries.binaryPath,
+      port,
+      host: DEFAULT_HOST,
+      logger: log,
+      distBaseDir: resolvedDistBaseDir
+    });
+    if (!result.ok) {
+      log.warn?.(`[docdex] daemon failed to start on ${DEFAULT_HOST}:${port}.`);
+      recordStartupFailure({ reason: result.reason || "startup_failed", host: DEFAULT_HOST, port });
+      allowDaemon = false;
+    } else {
+      startupOk = true;
+    }
   }
 
   const httpBindAddr = `${DEFAULT_HOST}:${port}`;
@@ -2313,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 });
@@ -2345,5 +2618,7 @@ module.exports = {
   shouldSkipSetup,
   launchSetupWizard,
   applyAgentInstructions,
-  buildDaemonEnv
+  buildDaemonEnv,
+  resolveDaemonPortState,
+  normalizeVersion
 };

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.28",
+  "version": "0.2.30",
   "mcpName": "io.github.bekirdag/docdex",
   "description": "Local-first documentation and code indexer with HTTP/MCP search, AST, and agent memory.",
   "bin": {