docdex 0.2.18 → 0.2.20

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.2.20
+- Prompt for npm updates at CLI start (TTY-only, opt-out via `DOCDEX_UPDATE_CHECK=0`).
+- Export bundled Playwright fetcher for daemon startup (launchd/systemd/schtasks + immediate spawn).
+- Pass `DOCDEX_PLAYWRIGHT_FETCHER` in the npm wrapper when launching the daemon.
+
+## 0.2.19
+- Playwright issue fix
+- Agents md adding command manually
+- Agents md append repeat fix
+
 ## 0.2.16
 - Repo memory now tags items with `repoId` and filters recalls to prevent cross-repo leakage in multi-repo daemons.
 - MCP HTTP requires explicit repo selection when multiple repos are active.

package/bin/docdex.js

@@ -5,6 +5,7 @@ const fs = require("node:fs");
 const path = require("node:path");
 const { spawn } = require("node:child_process");
 
+const pkg = require("../package.json");
 const {
   artifactName,
   detectLibcFromRuntime,
@@ -13,6 +14,7 @@ const {
   assetPatternForPlatformKey,
   UnsupportedPlatformError
 } = require("../lib/platform");
+const { checkForUpdateOnce } = require("../lib/update_check");
 
 function isDoctorCommand(argv) {
   const sub = argv[0];
@@ -139,7 +141,7 @@ function runDoctor() {
   process.exit(report.exitCode);
 }
 
-function run() {
+async function run() {
   const argv = process.argv.slice(2);
   if (isDoctorCommand(argv)) {
     runDoctor();
@@ -164,9 +166,11 @@ function run() {
       }
       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 basePath = path.join(__dirname, "..", "dist", platformKey);
@@ -186,12 +190,25 @@ function run() {
       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 };
   if (!env.DOCDEX_MCP_SERVER_BIN && fs.existsSync(mcpBinaryPath)) {
     env.DOCDEX_MCP_SERVER_BIN = mcpBinaryPath;
   }
+  const fetcherPath = path.join(__dirname, "..", "lib", "playwright_fetch.js");
+  if (!env.DOCDEX_PLAYWRIGHT_FETCHER && fs.existsSync(fetcherPath)) {
+    env.DOCDEX_PLAYWRIGHT_FETCHER = fetcherPath;
+  }
   const child = spawn(binaryPath, process.argv.slice(2), { stdio: "inherit", env });
   child.on("exit", (code) => process.exit(code ?? 1));
   child.on("error", (err) => {
@@ -200,4 +217,7 @@ function run() {
   });
 }
 
-run();
+run().catch((err) => {
+  console.error(`[docdex] unexpected error: ${err?.message || String(err)}`);
+  process.exit(1);
+});

package/lib/postinstall_setup.js

@@ -20,6 +20,8 @@ const DEFAULT_OLLAMA_CHAT_MODEL = "phi3.5:3.8b";
 const DEFAULT_OLLAMA_CHAT_MODEL_SIZE_GIB = 2.2;
 const SETUP_PENDING_MARKER = "setup_pending.json";
 const AGENTS_DOC_FILENAME = "agents.md";
+const DOCDEX_INFO_START_PREFIX = "---- START OF DOCDEX INFO V";
+const DOCDEX_INFO_END = "---- END OF DOCDEX INFO -----";
 
 function defaultConfigPath() {
   return path.join(os.homedir(), ".docdex", "config.toml");
@@ -158,6 +160,18 @@ function agentsDocSourcePath() {
   return path.join(__dirname, "..", "assets", AGENTS_DOC_FILENAME);
 }
 
+function resolvePackageVersion() {
+  const packagePath = path.join(__dirname, "..", "package.json");
+  if (!fs.existsSync(packagePath)) return "unknown";
+  try {
+    const raw = fs.readFileSync(packagePath, "utf8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed.version === "string" && parsed.version.trim() ? parsed.version.trim() : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
 function loadAgentInstructions() {
   const sourcePath = agentsDocSourcePath();
   if (!fs.existsSync(sourcePath)) return "";
@@ -172,13 +186,123 @@ function normalizeInstructionText(value) {
   return String(value || "").trim();
 }
 
-function mergeInstructionText(existing, instructions) {
+function docdexBlockStart(version) {
+  return `${DOCDEX_INFO_START_PREFIX}${version} ----`;
+}
+
+function buildDocdexInstructionBlock(instructions) {
+  const next = normalizeInstructionText(instructions);
+  if (!next) return "";
+  const version = resolvePackageVersion();
+  return `${docdexBlockStart(version)}\n${next}\n${DOCDEX_INFO_END}`;
+}
+
+function extractDocdexBlockBody(text) {
+  const match = String(text || "").match(
+    new RegExp(
+      `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\r\\n]* ----\\r?\\n([\\s\\S]*?)\\r?\\n${escapeRegExp(
+        DOCDEX_INFO_END
+      )}`
+    )
+  );
+  return match ? normalizeInstructionText(match[1]) : "";
+}
+
+function extractDocdexBlockVersion(text) {
+  const match = String(text || "").match(
+    new RegExp(`${escapeRegExp(DOCDEX_INFO_START_PREFIX)}([^\\s]+) ----`)
+  );
+  return match ? match[1] : null;
+}
+
+function hasDocdexBlockVersion(text, version) {
+  if (!version) return false;
+  return String(text || "").includes(docdexBlockStart(version));
+}
+
+function stripDocdexBlocks(text) {
+  const re = new RegExp(
+    `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\r\\n]* ----\\r?\\n[\\s\\S]*?\\r?\\n${escapeRegExp(
+      DOCDEX_INFO_END
+    )}\\r?\\n?`,
+    "g"
+  );
+  return String(text || "").replace(re, "").trim();
+}
+
+function stripDocdexBlocksExcept(text, version) {
+  if (!version) return stripDocdexBlocks(text);
+  const source = String(text || "");
+  const re = new RegExp(
+    `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\r\\n]* ----\\r?\\n[\\s\\S]*?\\r?\\n${escapeRegExp(
+      DOCDEX_INFO_END
+    )}\\r?\\n?`,
+    "g"
+  );
+  let result = "";
+  let lastIndex = 0;
+  let match;
+  while ((match = re.exec(source))) {
+    const before = source.slice(lastIndex, match.index);
+    result += before;
+    const block = match[0];
+    const blockVersion = extractDocdexBlockVersion(block);
+    if (blockVersion === version) {
+      result += block;
+    }
+    lastIndex = match.index + block.length;
+  }
+  result += source.slice(lastIndex);
+  return result;
+}
+
+function stripLegacyDocdexBodySegment(segment, body) {
+  if (!body) return String(segment || "");
+  const normalizedSegment = String(segment || "").replace(/\r\n/g, "\n");
+  const normalizedBody = String(body || "").replace(/\r\n/g, "\n");
+  if (!normalizedBody.trim()) return normalizedSegment;
+  const re = new RegExp(`\\n?${escapeRegExp(normalizedBody)}\\n?`, "g");
+  return normalizedSegment.replace(re, "\n").replace(/\n{3,}/g, "\n\n");
+}
+
+function stripLegacyDocdexBody(text, body) {
+  if (!body) return String(text || "");
+  const source = String(text || "").replace(/\r\n/g, "\n");
+  const re = new RegExp(
+    `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\n]* ----\\n[\\s\\S]*?\\n${escapeRegExp(DOCDEX_INFO_END)}\\n?`,
+    "g"
+  );
+  let result = "";
+  let lastIndex = 0;
+  let match;
+  while ((match = re.exec(source))) {
+    const before = source.slice(lastIndex, match.index);
+    result += stripLegacyDocdexBodySegment(before, body);
+    result += match[0];
+    lastIndex = match.index + match[0].length;
+  }
+  result += stripLegacyDocdexBodySegment(source.slice(lastIndex), body);
+  return result;
+}
+
+function mergeInstructionText(existing, instructions, { prepend = false } = {}) {
   const next = normalizeInstructionText(instructions);
   if (!next) return normalizeInstructionText(existing);
-  const current = normalizeInstructionText(existing);
+  const existingText = String(existing || "");
+  const current = normalizeInstructionText(existingText);
   if (!current) return next;
-  if (current.includes(next)) return current;
-  return `${current}\n\n${next}`;
+  const version = extractDocdexBlockVersion(next);
+  if (version) {
+    const body = extractDocdexBlockBody(next);
+    const cleaned = stripLegacyDocdexBody(existingText, body);
+    const withoutOldBlocks = stripDocdexBlocksExcept(cleaned, version);
+    if (hasDocdexBlockVersion(withoutOldBlocks, version)) return withoutOldBlocks;
+    const remainder = normalizeInstructionText(stripDocdexBlocks(withoutOldBlocks));
+    if (!remainder) return next;
+    return prepend ? `${next}\n\n${remainder}` : `${remainder}\n\n${next}`;
+  }
+  if (existingText.includes(next)) return existingText;
+  return prepend ? `${next}\n\n${current}` : `${current}\n\n${next}`;
 }
 
 function writeTextFile(pathname, contents) {
@@ -199,13 +323,10 @@ function upsertPromptFile(pathname, instructions, { prepend = false } = {}) {
   let current = "";
   if (fs.existsSync(pathname)) {
     current = fs.readFileSync(pathname, "utf8");
-    if (current.includes(next)) return false;
-  }
-  const currentTrimmed = normalizeInstructionText(current);
-  let merged = next;
-  if (currentTrimmed) {
-    merged = prepend ? `${next}\n\n${currentTrimmed}` : `${currentTrimmed}\n\n${next}`;
   }
+  const merged = mergeInstructionText(current, instructions, { prepend });
+  if (!merged) return false;
+  if (merged === current) return false;
   return writeTextFile(pathname, merged);
 }
 
@@ -220,13 +341,51 @@ function upsertYamlInstruction(pathname, key, instructions) {
   if (fs.existsSync(pathname)) {
     current = fs.readFileSync(pathname, "utf8");
   }
-  const keyRe = new RegExp(`^\\s*${escapeRegExp(key)}\\s*:`, "m");
-  if (keyRe.test(current)) {
-    if (current.includes(next)) return false;
-    return false;
+  const lines = current.split(/\r?\n/);
+  const blockRe = new RegExp(`^(\\s*)${escapeRegExp(key)}\\s*:\\s*(\\|[+-]?)?\\s*$`);
+  for (let idx = 0; idx < lines.length; idx += 1) {
+    const match = lines[idx].match(blockRe);
+    if (!match) continue;
+    const indent = match[1] || "";
+    const blockIndent = `${indent}  `;
+    let existingBlock = "";
+    let blockEnd = idx + 1;
+    if (match[2]) {
+      for (let j = idx + 1; j < lines.length; j += 1) {
+        const line = lines[j];
+        if (!line.trim()) {
+          blockEnd = j + 1;
+          continue;
+        }
+        const leading = line.match(/^\s*/)[0].length;
+        if (leading <= indent.length) break;
+        blockEnd = j + 1;
+      }
+      const blockLines = lines.slice(idx + 1, blockEnd);
+      existingBlock = blockLines
+        .map((line) => {
+          if (!line.trim()) return "";
+          return line.startsWith(blockIndent) ? line.slice(blockIndent.length) : line.trimStart();
+        })
+        .join("\n");
+    } else {
+      const inlineMatch = lines[idx].match(new RegExp(`^(\\s*)${escapeRegExp(key)}\\s*:\\s*(.*)$`));
+      existingBlock = inlineMatch ? inlineMatch[2].trim() : "";
+    }
+    const merged = mergeInstructionText(existingBlock, instructions);
+    if (!merged) return false;
+    if (normalizeInstructionText(merged) === normalizeInstructionText(existingBlock) && match[2]) return false;
+    const mergedLines = merged.split(/\r?\n/).map((line) => `${blockIndent}${line}`);
+    const updatedLines = [
+      ...lines.slice(0, idx),
+      `${indent}${key}: |`,
+      ...mergedLines,
+      ...lines.slice(match[2] ? blockEnd : idx + 1)
+    ];
+    return writeTextFile(pathname, updatedLines.join("\n").trimEnd());
   }
-  const lines = next.split(/\r?\n/).map((line) => `  ${line}`);
-  const block = `${key}: |\n${lines.join("\n")}`;
+  const contentLines = next.split(/\r?\n/).map((line) => `  ${line}`);
+  const block = `${key}: |\n${contentLines.join("\n")}`;
   const merged = current.trim() ? `${current.trim()}\n\n${block}` : block;
   return writeTextFile(pathname, merged);
 }
@@ -668,7 +827,7 @@ function resolveBinaryPath({ binaryPath } = {}) {
 }
 
 function applyAgentInstructions({ logger } = {}) {
-  const instructions = loadAgentInstructions();
+  const instructions = buildDocdexInstructionBlock(loadAgentInstructions());
   if (!normalizeInstructionText(instructions)) return { ok: false, reason: "missing_instructions" };
   const paths = clientInstructionPaths();
   let updated = false;
@@ -1305,8 +1464,26 @@ async function maybePromptOllamaModel({
   return { status: "skipped", reason: "invalid_selection" };
 }
 
+function resolvePlaywrightFetcherPath() {
+  const candidate = path.join(__dirname, "playwright_fetch.js");
+  return fs.existsSync(candidate) ? candidate : null;
+}
+
+function buildDaemonEnvPairs({ mcpBinaryPath } = {}) {
+  const pairs = [["DOCDEX_BROWSER_AUTO_INSTALL", "0"]];
+  if (mcpBinaryPath) pairs.push(["DOCDEX_MCP_SERVER_BIN", mcpBinaryPath]);
+  const fetcher = resolvePlaywrightFetcherPath();
+  if (fetcher) pairs.push(["DOCDEX_PLAYWRIGHT_FETCHER", fetcher]);
+  return pairs;
+}
+
+function buildDaemonEnv({ mcpBinaryPath } = {}) {
+  return Object.fromEntries(buildDaemonEnvPairs({ mcpBinaryPath }));
+}
+
 function registerStartup({ binaryPath, mcpBinaryPath, port, repoRoot, logger }) {
   if (!binaryPath) return { ok: false, reason: "missing_binary" };
+  const envPairs = buildDaemonEnvPairs({ mcpBinaryPath });
   const args = [
     "daemon",
     "--repo",
@@ -1319,21 +1496,16 @@ function registerStartup({ binaryPath, mcpBinaryPath, port, repoRoot, logger })
     "warn",
     "--secure-mode=false"
   ];
-  const envMcpBin = mcpBinaryPath ? `DOCDEX_MCP_SERVER_BIN=${mcpBinaryPath}` : null;
 
   if (process.platform === "darwin") {
     const plistPath = path.join(os.homedir(), "Library", "LaunchAgents", "com.docdex.daemon.plist");
     const logDir = path.join(os.homedir(), ".docdex", "logs");
     fs.mkdirSync(logDir, { recursive: true });
     const programArgs = [binaryPath, ...args];
-    const envVars = [
-      "    <key>DOCDEX_BROWSER_AUTO_INSTALL</key>\n",
-      "    <string>0</string>\n"
-    ];
-    if (mcpBinaryPath) {
-      envVars.push("    <key>DOCDEX_MCP_SERVER_BIN</key>\n");
-      envVars.push(`    <string>${mcpBinaryPath}</string>\n`);
-    }
+    const envVars = envPairs.flatMap(([key, value]) => [
+      `    <key>${key}</key>\n`,
+      `    <string>${value}</string>\n`
+    ]);
     const plist = `<?xml version="1.0" encoding="UTF-8"?>\n` +
       `<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n` +
       `<plist version="1.0">\n` +
@@ -1375,6 +1547,7 @@ function registerStartup({ binaryPath, mcpBinaryPath, port, repoRoot, logger })
     const systemdDir = path.join(os.homedir(), ".config", "systemd", "user");
     const unitPath = path.join(systemdDir, "docdexd.service");
     fs.mkdirSync(systemdDir, { recursive: true });
+    const envLines = envPairs.map(([key, value]) => `Environment=${key}=${value}`);
     const unit = [
       "[Unit]",
       "Description=Docdex daemon",
@@ -1382,8 +1555,7 @@ function registerStartup({ binaryPath, mcpBinaryPath, port, repoRoot, logger })
       "",
       "[Service]",
       `ExecStart=${binaryPath} ${args.join(" ")}`,
-      "Environment=DOCDEX_BROWSER_AUTO_INSTALL=0",
-      envMcpBin ? `Environment=${envMcpBin}` : null,
+      ...envLines,
       "Restart=always",
       "RestartSec=2",
       "",
@@ -1402,10 +1574,7 @@ function registerStartup({ binaryPath, mcpBinaryPath, port, repoRoot, logger })
   if (process.platform === "win32") {
     const taskName = "Docdex Daemon";
     const joinedArgs = args.map((arg) => `"${arg}"`).join(" ");
-    const envParts = ['set "DOCDEX_BROWSER_AUTO_INSTALL=0"'];
-    if (mcpBinaryPath) {
-      envParts.push(`set "DOCDEX_MCP_SERVER_BIN=${mcpBinaryPath}"`);
-    }
+    const envParts = envPairs.map(([key, value]) => `set "${key}=${value}"`);
     const taskArgs =
       `"cmd.exe" /c "${envParts.join(" && ")} && \"${binaryPath}\" ${joinedArgs}"`;
     const create = spawnSync("schtasks", [
@@ -1433,10 +1602,7 @@ function registerStartup({ binaryPath, mcpBinaryPath, port, repoRoot, logger })
 
 function startDaemonNow({ binaryPath, mcpBinaryPath, port, repoRoot }) {
   if (!binaryPath) return false;
-  const extraEnv = {};
-  if (mcpBinaryPath) {
-    extraEnv.DOCDEX_MCP_SERVER_BIN = mcpBinaryPath;
-  }
+  const extraEnv = buildDaemonEnv({ mcpBinaryPath });
   const child = spawn(
     binaryPath,
     [
@@ -1456,7 +1622,6 @@ function startDaemonNow({ binaryPath, mcpBinaryPath, port, repoRoot }) {
       detached: true,
       env: {
         ...process.env,
-        DOCDEX_BROWSER_AUTO_INSTALL: "0",
         ...extraEnv
       }
     }
@@ -1688,5 +1853,6 @@ module.exports = {
   canPromptWithTty,
   shouldSkipSetup,
   launchSetupWizard,
-  applyAgentInstructions
+  applyAgentInstructions,
+  buildDaemonEnv
 };

package/lib/update_check.js

@@ -0,0 +1,218 @@
+"use strict";
+
+const https = require("node:https");
+
+const UPDATE_CHECK_ENV = "DOCDEX_UPDATE_CHECK";
+const DEFAULT_REGISTRY_URL = "https://registry.npmjs.org/docdex/latest";
+const DEFAULT_TIMEOUT_MS = 1500;
+const MAX_RESPONSE_BYTES = 128 * 1024;
+
+let hasChecked = false;
+
+function normalizeVersion(value) {
+  if (typeof value !== "string") return "";
+  return value.trim().replace(/^v/i, "");
+}
+
+function parseSemver(value) {
+  const normalized = normalizeVersion(value);
+  const match = normalized.match(
+    /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u
+  );
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ? match[4].split(".") : null
+  };
+}
+
+function compareIdentifiers(left, right) {
+  const leftNum = /^[0-9]+$/.test(left) ? Number(left) : null;
+  const rightNum = /^[0-9]+$/.test(right) ? Number(right) : null;
+
+  if (leftNum != null && rightNum != null) {
+    if (leftNum === rightNum) return 0;
+    return leftNum > rightNum ? 1 : -1;
+  }
+
+  if (leftNum != null) return -1;
+  if (rightNum != null) return 1;
+  if (left === right) return 0;
+  return left > right ? 1 : -1;
+}
+
+function comparePrerelease(left, right) {
+  if (!left && !right) return 0;
+  if (!left) return 1;
+  if (!right) return -1;
+
+  const length = Math.max(left.length, right.length);
+  for (let i = 0; i < length; i += 1) {
+    const leftId = left[i];
+    const rightId = right[i];
+    if (leftId == null) return -1;
+    if (rightId == null) return 1;
+    const result = compareIdentifiers(leftId, rightId);
+    if (result !== 0) return result;
+  }
+  return 0;
+}
+
+function compareSemver(left, right) {
+  if (!left || !right) return null;
+  if (left.major !== right.major) return left.major > right.major ? 1 : -1;
+  if (left.minor !== right.minor) return left.minor > right.minor ? 1 : -1;
+  if (left.patch !== right.patch) return left.patch > right.patch ? 1 : -1;
+  return comparePrerelease(left.prerelease, right.prerelease);
+}
+
+function isDisabledEnv(value) {
+  if (value == null) return false;
+  const normalized = String(value).trim().toLowerCase();
+  return normalized === "0" || normalized === "false" || normalized === "off" || normalized === "no";
+}
+
+function isEnabledEnv(value) {
+  if (value == null) return false;
+  const normalized = String(value).trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "on" || normalized === "yes";
+}
+
+function isInteractive({ stdout, stderr } = {}) {
+  return Boolean(stdout?.isTTY || stderr?.isTTY);
+}
+
+function shouldCheckForUpdate({ env, stdout, stderr } = {}) {
+  const envValue = env?.[UPDATE_CHECK_ENV];
+  if (isDisabledEnv(envValue)) return false;
+  if (env?.CI && !isEnabledEnv(envValue)) return false;
+  if (!isInteractive({ stdout, stderr }) && !isEnabledEnv(envValue)) return false;
+  return true;
+}
+
+function fetchLatestVersion({
+  httpsModule = https,
+  registryUrl = DEFAULT_REGISTRY_URL,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  maxBytes = MAX_RESPONSE_BYTES
+} = {}) {
+  if (!httpsModule || typeof httpsModule.request !== "function") {
+    return Promise.resolve(null);
+  }
+
+  return new Promise((resolve) => {
+    let resolved = false;
+    const finish = (value) => {
+      if (resolved) return;
+      resolved = true;
+      resolve(value);
+    };
+
+    const req = httpsModule.request(
+      registryUrl,
+      {
+        method: "GET",
+        headers: {
+          "User-Agent": "docdex-update-check",
+          Accept: "application/json"
+        }
+      },
+      (res) => {
+        if (!res || res.statusCode !== 200) {
+          res?.resume?.();
+          finish(null);
+          return;
+        }
+        res.setEncoding?.("utf8");
+        let body = "";
+        res.on("data", (chunk) => {
+          body += chunk;
+          if (body.length > maxBytes) {
+            req.destroy?.();
+            finish(null);
+          }
+        });
+        res.on("end", () => {
+          if (!body) {
+            finish(null);
+            return;
+          }
+          try {
+            const parsed = JSON.parse(body);
+            const version = typeof parsed?.version === "string" ? parsed.version : null;
+            finish(version);
+          } catch {
+            finish(null);
+          }
+        });
+      }
+    );
+
+    req.on("error", () => finish(null));
+    if (typeof req.setTimeout === "function") {
+      req.setTimeout(timeoutMs, () => {
+        req.destroy?.();
+        finish(null);
+      });
+    }
+    if (typeof req.end === "function") req.end();
+  });
+}
+
+async function checkForUpdate({
+  currentVersion,
+  env = process.env,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  logger = console,
+  httpsModule = https,
+  registryUrl = DEFAULT_REGISTRY_URL,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  maxBytes = MAX_RESPONSE_BYTES
+} = {}) {
+  if (!shouldCheckForUpdate({ env, stdout, stderr })) {
+    return { checked: false, updateAvailable: false };
+  }
+
+  const current = normalizeVersion(currentVersion);
+  if (!current) {
+    return { checked: true, updateAvailable: false };
+  }
+
+  const latest = normalizeVersion(
+    await fetchLatestVersion({ httpsModule, registryUrl, timeoutMs, maxBytes })
+  );
+  if (!latest) {
+    return { checked: true, updateAvailable: false };
+  }
+
+  const comparison = compareSemver(parseSemver(current), parseSemver(latest));
+  if (comparison == null || comparison >= 0) {
+    return { checked: true, updateAvailable: false, latestVersion: latest };
+  }
+
+  logger?.log?.(`[docdex] Update available: v${current} -> v${latest}`);
+  logger?.log?.("[docdex] Run: npm i -g docdex@latest");
+  logger?.log?.(`[docdex] Disable update checks with ${UPDATE_CHECK_ENV}=0`);
+
+  return { checked: true, updateAvailable: true, latestVersion: latest };
+}
+
+async function checkForUpdateOnce(options) {
+  if (hasChecked) return { checked: false, updateAvailable: false };
+  hasChecked = true;
+  return checkForUpdate(options);
+}
+
+module.exports = {
+  DEFAULT_REGISTRY_URL,
+  DEFAULT_TIMEOUT_MS,
+  MAX_RESPONSE_BYTES,
+  checkForUpdate,
+  checkForUpdateOnce,
+  compareSemver,
+  parseSemver,
+  shouldCheckForUpdate
+};

package/package.json

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