docdex 0.2.44 → 0.2.45

package/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 0.2.45
+- Update packaged agent docs with FD-hardening guidance and bump release metadata to 0.2.45.
+
 ## 0.2.44
 - Fix MCP tool schema compatibility with Claude Code by removing top-level anyOf from `docdex_dag_export`.
 - Bump release metadata to 0.2.44.

package/assets/agents.md

@@ -1,4 +1,4 @@
----- START OF DOCDEX INFO V0.2.44 ----
+---- START OF DOCDEX INFO V0.2.45 ----
 Docdex URL: http://127.0.0.1:28491
 Use this base URL for Docdex HTTP endpoints.
 Health check endpoint: `GET /healthz` (not `/v1/health`).
@@ -16,6 +16,7 @@ Health check endpoint: `GET /healthz` (not `/v1/health`).
 - When a Docdex feature makes a task easier/safer, you MUST use it instead of ad-hoc inspection. Examples: `docdex_search` for context, `docdex_open`/`/v1/snippet` for file slices, `docdex_symbols`/`docdex_ast` for structure, `docdex_impact_graph`/`docdex_impact_diagnostics` for dependency safety, and `docdex_dag_export` to review session traces.
 - For dependency/library docs, run `docdexd libs discover`/`docdexd libs fetch` and search with `include_libs` rather than web searching.
 - For test execution, use `docdexd run-tests` (or `docdexd test run-node`) instead of ad-hoc commands when feasible.
+- For daemon stability triage, prioritize FD hardening checks: startup nofile warning threshold (`DOCDEX_MIN_NOFILE_SOFT`), profile lock retry knobs (`DOCDEX_PROFILE_LOCK_MAX_ATTEMPTS`, `DOCDEX_PROFILE_LOCK_RETRY_BASE_MS`), installer pressure defaults (`DOCDEX_REPO_IDLE_SECONDS`, `DOCDEX_REPO_HIBERNATE_SECONDS`, `DOCDEX_REPO_CLEANUP_INTERVAL_SECONDS`), and `docs/ops/fd_exhaustion_playbook.md`.
 - For staged-change validation, use `docdexd hook pre-commit`.
 - For MCP client registration, use `docdexd mcp add` (or `--all`) instead of editing configs by hand.
 

package/lib/postinstall_setup.js

@@ -36,6 +36,16 @@ const AGENTS_DOC_FILENAME = "agents.md";
 const DOCDEX_INFO_START_PREFIX = "---- START OF DOCDEX INFO V";
 const DOCDEX_INFO_END = "---- END OF DOCDEX INFO -----";
 const DOCDEX_INFO_END_LEGACY = "---- END OF DOCDEX INFO ----";
+const LAUNCHD_NOFILE_SOFT = "65536";
+const LAUNCHD_NOFILE_HARD = "200000";
+const DAEMON_ENV_DEFAULTS = Object.freeze([
+  ["DOCDEX_BROWSER_AUTO_INSTALL", "0"],
+  ["DOCDEX_REPO_IDLE_SECONDS", "300"],
+  ["DOCDEX_REPO_HIBERNATE_SECONDS", "1800"],
+  ["DOCDEX_REPO_CLEANUP_INTERVAL_SECONDS", "60"],
+  ["DOCDEX_WEB_MAX_CONCURRENT_BROWSER_FETCHES", "1"],
+  ["DOCDEX_WEB_MAX_CONCURRENT_LLM", "1"]
+]);
 
 function defaultConfigPath() {
   return path.join(os.homedir(), ".docdex", "config.toml");
@@ -2247,13 +2257,65 @@ function isTempPath(value, osModule = os) {
 }
 
 function buildDaemonEnvPairs() {
-  return [["DOCDEX_BROWSER_AUTO_INSTALL", "0"]];
+  return DAEMON_ENV_DEFAULTS.map(([key, value]) => [key, value]);
 }
 
 function buildDaemonEnv() {
   return Object.fromEntries(buildDaemonEnvPairs());
 }
 
+function buildLaunchAgentPlist({
+  programArgs,
+  envPairs,
+  workingDir,
+  logDir,
+  nofileSoft = LAUNCHD_NOFILE_SOFT,
+  nofileHard = LAUNCHD_NOFILE_HARD
+} = {}) {
+  const envVars = (envPairs || []).flatMap(([key, value]) => [
+    `    <key>${key}</key>\n`,
+    `    <string>${value}</string>\n`
+  ]);
+  const args = (programArgs || []).map((arg) => `    <string>${arg}</string>\n`).join("");
+  return `<?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` +
+    `<dict>\n` +
+    `  <key>Label</key>\n` +
+    `  <string>com.docdex.daemon</string>\n` +
+    `  <key>EnvironmentVariables</key>\n` +
+    `  <dict>\n` +
+    envVars.join("") +
+    `  </dict>\n` +
+    `  <key>ProgramArguments</key>\n` +
+    `  <array>\n` +
+    args +
+    `  </array>\n` +
+    (workingDir
+      ? `  <key>WorkingDirectory</key>\n` + `  <string>${workingDir}</string>\n`
+      : "") +
+    `  <key>RunAtLoad</key>\n` +
+    `  <true/>\n` +
+    `  <key>KeepAlive</key>\n` +
+    `  <true/>\n` +
+    `  <key>SoftResourceLimits</key>\n` +
+    `  <dict>\n` +
+    `    <key>NumberOfFiles</key>\n` +
+    `    <integer>${nofileSoft}</integer>\n` +
+    `  </dict>\n` +
+    `  <key>HardResourceLimits</key>\n` +
+    `  <dict>\n` +
+    `    <key>NumberOfFiles</key>\n` +
+    `    <integer>${nofileHard}</integer>\n` +
+    `  </dict>\n` +
+    `  <key>StandardOutPath</key>\n` +
+    `  <string>${path.join(logDir, "daemon.out.log")}</string>\n` +
+    `  <key>StandardErrorPath</key>\n` +
+    `  <string>${path.join(logDir, "daemon.err.log")}</string>\n` +
+    `</dict>\n` +
+    `</plist>\n`;
+}
+
 function escapeCmdArg(value) {
   return `"${String(value).replace(/"/g, "\"\"")}"`;
 }
@@ -2323,37 +2385,12 @@ function registerStartup({ binaryPath, port, repoRoot, logger, distBaseDir, star
     const logDir = path.join(os.homedir(), ".docdex", "logs");
     fs.mkdirSync(logDir, { recursive: true });
     const programArgs = [binaryPath, ...args];
-    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` +
-      `<dict>\n` +
-      `  <key>Label</key>\n` +
-      `  <string>com.docdex.daemon</string>\n` +
-      `  <key>EnvironmentVariables</key>\n` +
-      `  <dict>\n` +
-      envVars.join("") +
-      `  </dict>\n` +
-      `  <key>ProgramArguments</key>\n` +
-      `  <array>\n` +
-      programArgs.map((arg) => `    <string>${arg}</string>\n`).join("") +
-      `  </array>\n` +
-      (workingDir
-        ? `  <key>WorkingDirectory</key>\n` + `  <string>${workingDir}</string>\n`
-        : "") +
-      `  <key>RunAtLoad</key>\n` +
-      `  <true/>\n` +
-      `  <key>KeepAlive</key>\n` +
-      `  <true/>\n` +
-      `  <key>StandardOutPath</key>\n` +
-      `  <string>${path.join(logDir, "daemon.out.log")}</string>\n` +
-      `  <key>StandardErrorPath</key>\n` +
-      `  <string>${path.join(logDir, "daemon.err.log")}</string>\n` +
-      `</dict>\n` +
-      `</plist>\n`;
+    const plist = buildLaunchAgentPlist({
+      programArgs,
+      envPairs,
+      workingDir,
+      logDir
+    });
     fs.mkdirSync(path.dirname(plistPath), { recursive: true });
     fs.writeFileSync(plistPath, plist);
     if (!startNow) return { ok: true };
@@ -2820,6 +2857,7 @@ module.exports = {
   launchSetupWizard,
   applyAgentInstructions,
   buildDaemonEnv,
+  buildLaunchAgentPlist,
   resolveDaemonPortState,
   normalizeVersion
 };

package/package.json

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