docdex 0.2.29 → 0.2.30

package/assets/agents.md

@@ -1,4 +1,4 @@
----- START OF DOCDEX INFO V0.2.29 ----
+---- 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;
@@ -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.30",
   "mcpName": "io.github.bekirdag/docdex",
   "description": "Local-first documentation and code indexer with HTTP/MCP search, AST, and agent memory.",
   "bin": {