docdex 0.2.27 → 0.2.29

package/assets/agents.md

@@ -1,4 +1,4 @@
----- START OF DOCDEX INFO V0.2.27 ----
+---- START OF DOCDEX INFO V0.2.29 ----
 Docdex URL: http://127.0.0.1:28491
 Use this base URL for Docdex HTTP endpoints.
 Health check endpoint: `GET /healthz` (not `/v1/health`).
@@ -12,6 +12,11 @@ Health check endpoint: `GET /healthz` (not `/v1/health`).
 - Use Docdex tools intentionally: docdex_search/symbols/ast for repo truth; docdex_stats/files/repo_inspect/index for index health.
 - For folder structure, use docdex_tree instead of raw `rg --files`/`find` to avoid noisy folders.
 - When you do not know something, run docdex_web_research (force_web=true). Web research is encouraged by default for non-repo facts and external APIs.
+- 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 staged-change validation, use `docdexd hook pre-commit`.
+- For MCP client registration, use `docdexd mcp add` (or `--all`) instead of editing configs by hand.
 
 # Docdex Agent Usage Instructions
 
@@ -92,8 +97,23 @@ Use local delegation for low-complexity, code-generation-oriented tasks to reduc
 | docdex_local_completion | Delegate small tasks to a local model with strict output formats. |
 | HTTP /v1/delegate | HTTP endpoint for delegated completions with structured responses. |
 
-Required fields: `task_type`, `instruction`, `context`. Optional: `max_tokens`, `timeout_ms`, `mode` (`draft_only` or `draft_then_refine`), `agent` (local agent id/slug).
+Required fields: `task_type`, `instruction`, `context`. Optional: `max_tokens`, `timeout_ms`, `mode` (`draft_only` or `draft_then_refine`), `agent` (local agent id/slug or `model:<name>` to force an Ollama model; raw model names from `docdexd delegation agents` are also accepted).
 Expensive model library: `docs/expensive_models.json` (match by `agent_id`, `agent_slug`, `model`, or adapter type; case-insensitive).
+To choose a local target, run `docdexd delegation agents` (or `--json`) and prefer:
+- `code_writer` for scaffolding/boilerplate/docstrings.
+- `code_reviewer` for tests/format/refactors.
+- `general_chat` for lightweight Q&A or fallback.
+For mcoda agents, also consider:
+- `max_complexity`: do not assign tasks above this ceiling.
+- `rating`: prefer higher-rated agents for reliability.
+- `cost_per_million`: USD per 1M tokens; prefer lower cost when ratings/complexity match.
+- `usage`: best-fit role (for example `code_writer` or `code_reviewer`); use this for quick matching.
+- `reasoning_rating`: reasoning score out of 10; prefer higher for complex reasoning tasks.
+- `health_status`: only use agents marked `healthy` (treat `-` as unknown).
+Table output shows `USAGE`, `COMPLEXITY`, `RATING`, `REASON`, `COST/$1M`, and `HEALTH` for mcoda agents (`-` means unknown).
+- When `llm.delegation.re_evaluate = true` (default), Docdex reviews successful local mcoda runs using the primary agent when available and writes updated ratings to `~/.mcoda/mcoda.db` (disable with `DOCDEX_DELEGATION_REEVALUATE=0`).
+Use `agent: model:<ollama-model>` to force a specific local model (for example, `model:phi3.5:3.8b`).
+Avoid entries that only advertise `embedding` or `vision`.
 
 ### E. Index Health + File Access
 
@@ -125,6 +145,8 @@ Use these to verify index coverage, repo binding, and to read precise file slice
 - docdex_impact_graph: Mandatory before code changes to review inbound/outbound deps (use MCP/IPC if shell networking is blocked).
 - docdex_dag_export: Export dependency graph to plan change order.
 - HTTP /v1/initialize: Mount/bind a repo for HTTP daemon mode. Request JSON uses rootUri/root_uri (NOT repo_root).
+- HTTP /v1/snippet: Fetch exact line-safe snippets for a doc_id returned by search.
+- HTTP /v1/impact/diagnostics: Inspect unresolved/dynamic imports when impact graphs look incomplete.
 
 ## CLI Fallbacks (when MCP/IPC is unavailable)
 Use these only when MCP tools cannot be called (e.g., blocked sandbox networking). Prefer MCP/IPC otherwise.
@@ -133,11 +155,18 @@ Use these only when MCP tools cannot be called (e.g., blocked sandbox networking
 - `docdexd repo id --repo <path>`: compute repo fingerprint locally.
 - `docdexd repo status --repo <path>` / `docdexd repo dirty --exit-code`: git working tree status.
 - `docdexd impact-graph --repo <path> --file <rel>`: impact graph (HTTP/local).
-- `docdexd dag export --repo <path> <session_id>`: DAG export alias.
+- `docdexd dag view --repo <path> <session_id>` / `docdexd dag export --repo <path> <session_id>`: DAG export/render.
 - `docdexd search --repo <path> --query "<q>"`: /search equivalent (HTTP/local).
+- `docdexd delegation savings`: delegation telemetry (JSON: offloaded count, local/primary tokens & costs, savings).
+- `docdexd delegation agents --json`: list local delegation targets and capabilities (mcoda agents include `max_complexity`, `rating`, `cost_per_million`, `usage`, `reasoning_rating`, `health_status`).
 - `docdexd open --repo <path> --file <rel>`: safe file slice read (head/start/end/clamp).
 - `docdexd file ensure-newline|write --repo <path> --file <rel>`: minimal file edits.
 - `docdexd test run-node --repo <path> --file <rel> --args "..."`: run Node scripts.
+- `docdexd run-tests --repo <path> [--target <file|dir>]`: run repo tests (preferred for test execution).
+- `docdexd hook pre-commit --repo <path>`: run semantic gatekeeper hooks against staged changes.
+- `docdexd impact-diagnostics --repo <path> [--file <rel>]`: list unresolved import diagnostics.
+- `docdexd libs discover|fetch --repo <path> [--sources <file>]`: dependency docs discovery/ingestion.
+- `docdexd mcp add --agent <name> [--transport http|ipc] [--all]`: register Docdex MCP in supported clients.
 
 ## Docdex Usage Cookbook (Mandatory, Exact Schemas)
 

package/lib/postinstall_setup.js

@@ -18,6 +18,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 +122,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/);
@@ -2254,8 +2389,12 @@ async function runPostInstallSetup({ binaryPath, logger } = {}) {
     existingConfig = fs.readFileSync(configPath, "utf8");
   }
   const port = DEFAULT_DAEMON_PORT;
-  const available = await isPortAvailable(port, DEFAULT_HOST);
-  if (!available) {
+  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.`
     );
@@ -2268,19 +2407,42 @@ async function runPostInstallSetup({ binaryPath, logger } = {}) {
     binaryPath: resolvedBinary,
     logger: log
   });
-  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 = portState.reuseExisting;
+  if (reuseExisting) {
+    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) {
+          throw new Error("docdex daemon restart failed; port still in use");
+        }
+        reuseExisting = false;
+      }
+    }
+  }
+  if (!reuseExisting) {
+    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");
+    }
   }
 
   const httpBindAddr = `${DEFAULT_HOST}:${port}`;
@@ -2345,5 +2507,7 @@ module.exports = {
   shouldSkipSetup,
   launchSetupWizard,
   applyAgentInstructions,
-  buildDaemonEnv
+  buildDaemonEnv,
+  resolveDaemonPortState,
+  normalizeVersion
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docdex",
-  "version": "0.2.27",
+  "version": "0.2.29",
   "mcpName": "io.github.bekirdag/docdex",
   "description": "Local-first documentation and code indexer with HTTP/MCP search, AST, and agent memory.",
   "bin": {
@@ -44,7 +44,7 @@
   },
   "homepage": "https://docdex.org",
   "license": "MIT",
-  "author": "bekir dağ",
+  "author": "bekir da\u011f",
   "keywords": [
     "docdex",
     "documentation",