docdex 0.2.37 → 0.2.40

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.39
+- Bump release metadata to 0.2.39.
+
+## 0.2.38
+- Bump release metadata to 0.2.38.
+
 ## 0.2.37
 - Bump release metadata to 0.2.37.
 

package/assets/agents.md

@@ -1,4 +1,4 @@
----- START OF DOCDEX INFO V0.2.37 ----
+---- START OF DOCDEX INFO V0.2.40 ----
 Docdex URL: http://127.0.0.1:28491
 Use this base URL for Docdex HTTP endpoints.
 Health check endpoint: `GET /healthz` (not `/v1/health`).
@@ -177,7 +177,7 @@ This section is the authoritative source for how to call Docdex. Do not guess fi
 
 - Default HTTP base URL: http://127.0.0.1:28491 (override with DOCDEX_HTTP_BASE_URL).
 - Single-repo HTTP daemon: `docdexd serve --repo /abs/path`. /v1/initialize is NOT used. repo_id is optional, but must match the serving repo if provided.
-- Multi-repo HTTP daemon: `docdexd daemon`. You MUST call /v1/initialize before repo-scoped HTTP endpoints. When multiple repos are mounted, repo_id is required on every repo-scoped request.
+- Multi-repo HTTP daemon: `docdexd daemon` (alias: `docdex start`). You MUST call /v1/initialize before repo-scoped HTTP endpoints. When multiple repos are mounted, repo_id is required on every repo-scoped request.
 
 ### 1) Initialize (HTTP) - exact request payload
 
@@ -305,9 +305,10 @@ When answering a complex coding query, follow this "Reasoning Trace":
 Save more memories for both lobes during the task, not just at the end.
 
 1. Repo memory: After each meaningful discovery or code change, save at least one durable fact (file location, behavior, config, gotcha) via `docdex_memory_save`.
-2. Profile memory: When the user expresses a preference, constraint, or workflow correction, call `docdex_save_preference` immediately with the right category.
-3. Keep it crisp: 1-3 short sentences, include file paths when relevant, avoid raw code blobs.
-4. Safety: Never store secrets, tokens, or sensitive user data. Skip transient or speculative info.
+2. Memory overrides: When a new repo memory replaces older facts, include `metadata.supersedes` with the prior memory id(s). Docdex marks the superseded entries with `supersededBy`/`supersededAtMs`, down-ranks them during recall, and they can be removed via `docdex memory compact` (dry-run unless `--apply`).
+3. Profile memory: When the user expresses a preference, constraint, or workflow correction, call `docdex_save_preference` immediately with the right category.
+4. Keep it crisp: 1-3 short sentences, include file paths when relevant, avoid raw code blobs.
+5. Safety: Never store secrets, tokens, or sensitive user data. Skip transient or speculative info.
 
 ### 3. Index Health + Diff-Aware Search (Mandatory)
 

package/lib/install.js

@@ -2286,6 +2286,14 @@ function printPostInstallBanner() {
       return false;
     }
   };
+  const writeStderr = (message) => {
+    try {
+      process.stderr.write(message);
+      return true;
+    } catch {
+      return false;
+    }
+  };
   let width = 0;
   const content = [
     "\x1b[31m      _               _           \x1b[0m",
@@ -2320,7 +2328,9 @@ function printPostInstallBanner() {
   lines.push(bottom);
   const banner = `\r\x1b[2K${lines.join("\n")}\n`;
   if (!writeDirect(banner)) {
-    console.log(banner);
+    if (!writeStderr(banner)) {
+      console.log(banner);
+    }
   }
 }
 

package/lib/paths.js

@@ -102,11 +102,20 @@ function resolveWindowsRunnerPath(options = {}) {
   return pathModule.join(resolveDocdexDataDir({ ...options, pathModule }), "run-daemon.cmd");
 }
 
+function resolveWindowsSetupRunnerPath(options = {}) {
+  const pathModule = options.pathModule || path;
+  if (options.distBaseDir) {
+    return pathModule.join(pathModule.dirname(options.distBaseDir), "run-setup.cmd");
+  }
+  return pathModule.join(resolveDocdexDataDir({ ...options, pathModule }), "run-setup.cmd");
+}
+
 module.exports = {
   resolveUserDataDir,
   resolveDocdexDataDir,
   resolveDistBaseCandidates,
   resolveDistBaseDir,
   resolveBinDir,
-  resolveWindowsRunnerPath
+  resolveWindowsRunnerPath,
+  resolveWindowsSetupRunnerPath
 };

package/lib/postinstall_setup.js

@@ -15,7 +15,8 @@ const {
   resolveDistBaseDir,
   resolveDistBaseCandidates,
   resolveBinDir,
-  resolveWindowsRunnerPath
+  resolveWindowsRunnerPath,
+  resolveWindowsSetupRunnerPath
 } = require("./paths");
 
 const DEFAULT_HOST = "127.0.0.1";
@@ -2261,9 +2262,32 @@ function writeWindowsRunner({ binaryPath, args, envPairs, workingDir, logger, di
   }
 }
 
-function registerStartup({ binaryPath, port, repoRoot, logger, distBaseDir }) {
+function writeWindowsSetupRunner({ binaryPath, args, logger, distBaseDir } = {}) {
+  if (!binaryPath) return null;
+  const runnerPath = resolveWindowsSetupRunnerPath({ distBaseDir });
+  const lines = [
+    "@echo off",
+    "setlocal",
+    "set \"DOCDEX_SETUP_AUTO=1\"",
+    "set \"DOCDEX_SETUP_MODE=auto\""
+  ];
+  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 setup runner: ${err?.message || err}`);
+    return null;
+  }
+}
+
+function registerStartup({ binaryPath, port, repoRoot, logger, distBaseDir, startNow = true }) {
   if (!binaryPath) return { ok: false, reason: "missing_binary" };
-  stopDaemonService({ logger });
+  if (startNow) {
+    stopDaemonService({ logger });
+  }
   const envPairs = buildDaemonEnvPairs();
   const workingDir = repoRoot ? path.resolve(repoRoot) : null;
   const args = [
@@ -2315,6 +2339,7 @@ function registerStartup({ binaryPath, port, repoRoot, logger, distBaseDir }) {
       `</plist>\n`;
     fs.mkdirSync(path.dirname(plistPath), { recursive: true });
     fs.writeFileSync(plistPath, plist);
+    if (!startNow) return { ok: true };
     const uid = typeof process.getuid === "function" ? process.getuid() : null;
     const bootstrap = uid != null
       ? spawnSync("launchctl", ["bootstrap", `gui/${uid}`, plistPath])
@@ -2349,7 +2374,11 @@ function registerStartup({ binaryPath, port, repoRoot, logger, distBaseDir }) {
     ].filter(Boolean).join("\n");
     fs.writeFileSync(unitPath, unit);
     const reload = spawnSync("systemctl", ["--user", "daemon-reload"]);
-    const enable = spawnSync("systemctl", ["--user", "enable", "--now", "docdexd.service"]);
+    const enableArgs = startNow
+      ? ["--user", "enable", "--now", "docdexd.service"]
+      : ["--user", "enable", "docdexd.service"];
+    const enable = spawnSync("systemctl", enableArgs);
+    ensureSystemdUserLinger({ logger });
     if (reload.status === 0 && enable.status === 0) return { ok: true };
     logger?.warn?.(`[docdex] systemd failed: ${enable.stderr || reload.stderr || "unknown error"}`);
     return { ok: false, reason: "systemd_failed" };
@@ -2380,7 +2409,9 @@ function registerStartup({ binaryPath, port, repoRoot, logger, distBaseDir }) {
       taskArgs
     ]);
     if (create.status === 0) {
-      spawnSync("schtasks", ["/Run", "/TN", taskName]);
+      if (startNow) {
+        spawnSync("schtasks", ["/Run", "/TN", taskName]);
+      }
       return { ok: true };
     }
     logger?.warn?.(`[docdex] schtasks failed: ${create.stderr || "unknown error"}`);
@@ -2390,18 +2421,22 @@ function registerStartup({ binaryPath, port, repoRoot, logger, distBaseDir }) {
   return { ok: false, reason: "unsupported_platform" };
 }
 
-async function startDaemonWithHealthCheck({ binaryPath, port, host, logger, distBaseDir }) {
+async function startDaemonWithHealthCheck({ binaryPath, port, host, logger, distBaseDir, startNow = true }) {
   const startup = registerStartup({
     binaryPath,
     port,
     repoRoot: daemonRootPath(),
     logger,
-    distBaseDir
+    distBaseDir,
+    startNow
   });
   if (!startup.ok) {
     logger?.warn?.(`[docdex] daemon service registration failed (${startup.reason || "unknown"}).`);
     return { ok: false, reason: "startup_failed" };
   }
+  if (!startNow) {
+    return { ok: true, reason: "registered" };
+  }
   startDaemonService({ logger });
   const healthy = await waitForDaemonHealthy({ host, port });
   if (healthy) {
@@ -2456,6 +2491,25 @@ function commandExists(cmd, spawnSyncFn) {
   return true;
 }
 
+function currentUsername() {
+  try {
+    const info = os.userInfo();
+    if (info && info.username) return info.username;
+  } catch {}
+  return process.env.USER || process.env.LOGNAME || process.env.USERNAME || null;
+}
+
+function ensureSystemdUserLinger({ logger } = {}) {
+  if (process.platform !== "linux") return { ok: false, reason: "unsupported_platform" };
+  if (!commandExists("loginctl", spawnSync)) return { ok: false, reason: "loginctl_missing" };
+  const username = currentUsername();
+  if (!username) return { ok: false, reason: "username_missing" };
+  const result = spawnSync("loginctl", ["enable-linger", username]);
+  if (result.status === 0) return { ok: true };
+  logger?.warn?.(`[docdex] loginctl enable-linger failed: ${result.stderr || "unknown error"}`);
+  return { ok: false, reason: "loginctl_failed" };
+}
+
 function launchMacTerminal({ binaryPath, args, spawnSyncFn, logger }) {
   const command = [
     "DOCDEX_SETUP_AUTO=1",
@@ -2514,7 +2568,8 @@ function launchSetupWizard({
   spawnFn = spawn,
   spawnSyncFn = spawnSync,
   platform = process.platform,
-  canPrompt = canPromptWithTty
+  canPrompt = canPromptWithTty,
+  distBaseDir
 }) {
   if (!binaryPath) return { ok: false, reason: "missing_binary" };
   if (shouldSkipSetup(env)) return { ok: false, reason: "skipped" };
@@ -2535,9 +2590,21 @@ function launchSetupWizard({
   }
 
   if (platform === "win32") {
-    const quoted = `"${binaryPath}" ${args.map((arg) => `"${arg}"`).join(" ")}`;
-    const cmdline = `set DOCDEX_SETUP_AUTO=1 && set DOCDEX_SETUP_MODE=auto && ${quoted}`;
-    const result = spawnSyncFn("cmd", ["/c", "start", "", "cmd", "/c", cmdline]);
+    const runnerPath = writeWindowsSetupRunner({
+      binaryPath,
+      args,
+      logger,
+      distBaseDir
+    });
+    if (!runnerPath) return { ok: false, reason: "runner_failed" };
+    const result = spawnSyncFn("cmd", [
+      "/c",
+      "start",
+      "",
+      "cmd",
+      "/c",
+      escapeCmdArg(runnerPath)
+    ]);
     if (result.status === 0) return { ok: true };
     logger?.warn?.(`[docdex] cmd start failed: ${result.stderr || "unknown error"}`);
     return { ok: false, reason: "terminal_launch_failed" };
@@ -2630,14 +2697,15 @@ async function runPostInstallSetup({ binaryPath, logger, env, skipDaemon, distBa
       }
     }
   }
-  let startupOk = reuseExisting;
-  if (allowDaemon && !reuseExisting) {
+  let startupOk = false;
+  if (allowDaemon) {
     const result = await startDaemonWithHealthCheck({
       binaryPath: startupBinaries.binaryPath,
       port,
       host: DEFAULT_HOST,
       logger: log,
-      distBaseDir: resolvedDistBaseDir
+      distBaseDir: resolvedDistBaseDir,
+      startNow: !reuseExisting
     });
     if (!result.ok) {
       log.warn?.(`[docdex] daemon failed to start on ${DEFAULT_HOST}:${port}.`);
@@ -2681,13 +2749,20 @@ async function runPostInstallSetup({ binaryPath, logger, env, skipDaemon, distBa
   if (startupOk) {
     clearStartupFailure();
   }
-  const skipWizard = isNpmLifecycle(effectiveEnv) || shouldSkipSetup(effectiveEnv);
+  const skipExplicit = shouldSkipSetup(effectiveEnv);
+  const skipWizard = isNpmLifecycle(effectiveEnv) || skipExplicit;
   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 });
+    ? { ok: false, reason: skipExplicit ? "skipped" : "npm_lifecycle" }
+    : launchSetupWizard({
+        binaryPath: startupBinaries.binaryPath,
+        logger: log,
+        distBaseDir: resolvedDistBaseDir
+      });
+  if (!setupLaunch.ok) {
+    if (setupLaunch.reason !== "skipped") {
+      log.warn?.("[docdex] setup wizard did not launch. Run `docdex setup`.");
+      recordSetupPending({ reason: setupLaunch.reason, port, repoRoot: daemonRoot });
+    }
   }
   return { port, url, configPath };
 }

package/package.json

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