@coderule/mcp 2.0.2 → 2.1.0

package/dist/mcp-cli.cjs

@@ -543,7 +543,10 @@ var FilesRepo = class {
       `UPDATE files
      SET content_sha256 = ?, service_file_hash = ?, hash_state = 'clean',
          hash_owner = NULL, hash_lease_expires_at = NULL, hash_started_at = NULL
-     WHERE id = ?`
+     WHERE id = ?
+       AND hash_state = 'hashing'
+       AND hash_owner = ?
+       AND hash_started_at = ?`
     );
     this.requeueExpiredHashingStmt = this.db.prepare(
       `UPDATE files
@@ -674,13 +677,30 @@ var FilesRepo = class {
     tx(ids);
   }
   applyHashResults(results) {
-    if (!results.length) return;
+    if (!results.length) return 0;
+    let applied = 0;
     const tx = this.db.transaction((batch) => {
-      for (const { id, contentSha256, serviceFileHash } of batch) {
-        this.applyHashesStmt.run(contentSha256, serviceFileHash, id);
+      for (const {
+        id,
+        contentSha256,
+        serviceFileHash,
+        hashOwner,
+        hashStartedAt
+      } of batch) {
+        const result = this.applyHashesStmt.run(
+          contentSha256,
+          serviceFileHash,
+          id,
+          hashOwner,
+          hashStartedAt
+        );
+        if ((result.changes ?? 0) > 0) {
+          applied += 1;
+        }
       }
     });
     tx(results);
+    return applied;
   }
   getCleanFilesForSnapshot() {
     return this.selectCleanSnapshotStmt.all();
@@ -730,7 +750,7 @@ var Outbox = class {
     this.log = logger2.child({ scope: "outbox" });
     this.queue = new qulite.Qulite(db, {
       logger: this.log,
-      defaultLeaseMs: 3e4,
+      defaultLeaseMs: 6e5,
       defaultMaxAttempts: 10
     });
     this.markKindStmt = db.prepare(
@@ -788,7 +808,7 @@ var Outbox = class {
       this.log.debug({ rootId }, "Enqueued heartbeat job");
     }
   }
-  claimFsControlJob(leaseOwner, leaseMs = 3e4) {
+  claimFsControlJob(leaseOwner, leaseMs = 6e5) {
     return this.queue.claimNext({ type: "fs_control", leaseOwner, leaseMs });
   }
   ack(jobId, leaseOwner) {
@@ -1104,7 +1124,9 @@ var Hasher = class {
         successes.push({
           id: record.id,
           contentSha256: result.contentSha256,
-          serviceFileHash: result.serviceFileHash
+          serviceFileHash: result.serviceFileHash,
+          hashOwner: record.hash_owner ?? this.ownerId,
+          hashStartedAt: record.hash_started_at ?? 0
         });
       } catch (error) {
         if (error?.code === "ENOENT") {
@@ -1263,6 +1285,42 @@ async function runInventory(opts) {
 async function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+var SnapshotStaleError = class extends Error {
+  constructor(message = "snapshot became stale") {
+    super(message);
+    this.name = "SnapshotStaleError";
+  }
+};
+function assertNotStale(opts) {
+  if (opts?.isStale?.()) {
+    throw new SnapshotStaleError();
+  }
+}
+function assertBeforeDeadline(opts) {
+  if (opts?.deadlineMs !== void 0 && Date.now() >= opts.deadlineMs) {
+    throw new Error("snapshot publish deadline exceeded");
+  }
+}
+function assertValid(opts) {
+  assertNotStale(opts);
+  assertBeforeDeadline(opts);
+}
+function withDeadline(promise, opts) {
+  if (opts?.deadlineMs === void 0) return promise;
+  const remaining = opts.deadlineMs - Date.now();
+  if (remaining <= 0) {
+    return Promise.reject(new Error("snapshot publish deadline exceeded"));
+  }
+  return Promise.race([
+    promise,
+    new Promise(
+      (_, reject) => setTimeout(
+        () => reject(new Error("snapshot publish deadline exceeded")),
+        remaining
+      )
+    )
+  ]);
+}
 function computeSnapshot(filesRepo) {
   const files = filesRepo.getCleanFilesForSnapshot();
   const hashes = files.map((file) => file.service_file_hash).filter((hash) => typeof hash === "string");
@@ -1278,12 +1336,17 @@ function computeSnapshot(filesRepo) {
     totalSize
   };
 }
-async function withRetries(op, logger2, context, maxAttempts) {
+async function withRetries(op, logger2, context, maxAttempts, opts) {
   let attempt = 0;
   while (true) {
+    assertValid(opts);
     try {
-      return await op();
+      return await withDeadline(op(), opts);
     } catch (err) {
+      if (err instanceof SnapshotStaleError) throw err;
+      if (typeof err?.message === "string" && err.message.includes("deadline exceeded")) {
+        throw err;
+      }
       attempt += 1;
       if (attempt >= maxAttempts) {
         logger2.error(
@@ -1301,7 +1364,14 @@ async function withRetries(op, logger2, context, maxAttempts) {
     }
   }
 }
-async function uploadMissing(rootPath, missing, syncClient, logger2, maxAttempts, chunkSize = 1) {
+function computeServiceFileHash(relPath, content) {
+  const hash = crypto.createHash("sha256");
+  hash.update(relPath);
+  hash.update("\n");
+  hash.update(content);
+  return hash.digest("hex");
+}
+async function uploadMissing(rootPath, missing, syncClient, logger2, maxAttempts, chunkSize = 1, opts) {
   if (!missing || missing.length === 0) return;
   const total = missing.length;
   const chunks = [];
@@ -1309,17 +1379,36 @@ async function uploadMissing(rootPath, missing, syncClient, logger2, maxAttempts
     chunks.push(missing.slice(i, i + chunkSize));
   }
   for (let idx = 0; idx < chunks.length; idx++) {
+    assertValid(opts);
     const list = chunks[idx];
     const map = /* @__PURE__ */ new Map();
     for (const missingFile of list) {
       const absPath = path2__default.default.join(rootPath, missingFile.file_path);
       try {
         const buffer = await fs5__default.default.readFile(absPath);
+        const serviceHash = computeServiceFileHash(
+          missingFile.file_path,
+          buffer
+        );
+        if (serviceHash !== missingFile.file_hash) {
+          logger2.warn(
+            {
+              relPath: missingFile.file_path,
+              expected: missingFile.file_hash,
+              got: serviceHash
+            },
+            "File content changed during upload; snapshot is stale"
+          );
+          throw new SnapshotStaleError(
+            `file hash mismatch for ${missingFile.file_path}`
+          );
+        }
         map.set(missingFile.file_hash, {
           path: missingFile.file_path,
           content: buffer
         });
       } catch (error) {
+        if (error instanceof SnapshotStaleError) throw error;
         logger2.warn(
           { err: error, relPath: missingFile.file_path },
           "Failed to read missing file content"
@@ -1327,6 +1416,7 @@ async function uploadMissing(rootPath, missing, syncClient, logger2, maxAttempts
       }
     }
     if (map.size === 0) continue;
+    assertValid(opts);
     await withRetries(
       () => syncClient.uploadFileContent(map),
       logger2,
@@ -1336,65 +1426,76 @@ async function uploadMissing(rootPath, missing, syncClient, logger2, maxAttempts
         chunks: chunks.length,
         files: map.size
       },
-      maxAttempts
+      maxAttempts,
+      opts
     );
   }
 }
-async function ensureSnapshotCreated(rootPath, computation, syncClient, logger2, options) {
+async function ensureSnapshotCreated(rootPath, computation, syncClient, logger2, opts) {
   const { snapshotHash, files } = computation;
-  const maxAttempts = options?.maxAttempts ?? 5;
-  const uploadChunkSize = options?.uploadChunkSize ?? 1;
+  const maxAttempts = opts?.maxAttempts ?? 5;
+  const uploadChunkSize = opts?.uploadChunkSize ?? 1;
+  assertValid(opts);
   let status = await withRetries(
     () => syncClient.checkSnapshotStatus(snapshotHash),
     logger2,
     { op: "checkSnapshotStatus", snapshotHash },
-    maxAttempts
+    maxAttempts,
+    opts
   );
   if (status.status === "READY") {
     logger2.info({ snapshotHash }, "Snapshot already READY");
     return;
   }
-  if (status.status === "NOT_FOUND" || status.status === "MISSING_CONTENT") {
-    status = await withRetries(
-      () => syncClient.createSnapshot(snapshotHash, files),
-      logger2,
-      { op: "createSnapshot", snapshotHash },
-      maxAttempts
-    );
-  }
-  if (status.status === "MISSING_CONTENT" && status.missing_files?.length) {
-    logger2.info(
-      { missing: status.missing_files.length },
-      "Uploading missing file content"
-    );
-    await uploadMissing(
-      rootPath,
-      status.missing_files,
-      syncClient,
-      logger2,
-      maxAttempts,
-      uploadChunkSize
-    );
-    status = await withRetries(
-      () => syncClient.createSnapshot(snapshotHash, files),
-      logger2,
-      { op: "createSnapshot", snapshotHash },
-      maxAttempts
-    );
-  }
   let attempt = 0;
   while (status.status !== "READY") {
+    assertValid(opts);
     if (status.status === "FAILED") {
       throw new Error(`Snapshot failed processing: ${JSON.stringify(status)}`);
     }
+    if (status.status === "NOT_FOUND" || status.status === "MISSING_CONTENT") {
+      status = await withRetries(
+        () => syncClient.createSnapshot(snapshotHash, files),
+        logger2,
+        { op: "createSnapshot", snapshotHash },
+        maxAttempts,
+        opts
+      );
+    }
+    if (status.status === "MISSING_CONTENT" && status.missing_files?.length) {
+      logger2.info(
+        { missing: status.missing_files.length },
+        "Uploading missing file content"
+      );
+      await uploadMissing(
+        rootPath,
+        status.missing_files,
+        syncClient,
+        logger2,
+        maxAttempts,
+        uploadChunkSize,
+        opts
+      );
+      status = await withRetries(
+        () => syncClient.createSnapshot(snapshotHash, files),
+        logger2,
+        { op: "createSnapshot", snapshotHash },
+        maxAttempts,
+        opts
+      );
+      continue;
+    }
+    if (status.status === "READY") break;
     const delay = Math.min(5e3, 1e3 * Math.max(1, 2 ** attempt));
     await sleep(delay);
     attempt += 1;
+    assertValid(opts);
     status = await withRetries(
       () => syncClient.checkSnapshotStatus(snapshotHash),
       logger2,
       { op: "checkSnapshotStatus", snapshotHash },
-      maxAttempts
+      maxAttempts,
+      opts
     );
   }
   logger2.info({ snapshotHash }, "Snapshot READY");
@@ -1561,12 +1662,14 @@ async function sendHeartbeat(rootId, snapshotsRepo, syncClient, logger2) {
 // src/service/State.ts
 var ServiceState = class {
   constructor() {
+    this.changeSeq = 0;
     this.lastChangeAt = Date.now();
     this.lastSnapshotReadyAt = Date.now();
     this.lastHeartbeatEnqueuedAt = 0;
   }
   updateChange(timestamp = Date.now()) {
     this.lastChangeAt = timestamp;
+    this.changeSeq += 1;
   }
   updateSnapshotReady(timestamp = Date.now()) {
     this.lastSnapshotReadyAt = timestamp;
@@ -1592,6 +1695,7 @@ function computeBackoff(attempts) {
   const delay = 1e3 * 2 ** base;
   return Math.min(delay, 6e4);
 }
+var PUBLISH_MAX_MS = 5 * 6e4;
 async function readSymlinkTarget2(absPath) {
   try {
     return await fs5__default.default.readlink(absPath);
@@ -1870,9 +1974,10 @@ var ServiceRunner = class {
     if (this.runtime.filesRepo.countByState("dirty") > 0 || this.runtime.filesRepo.countByState("hashing") > 0) {
       const delay = computeBackoff(job.attempts);
       this.runtime.outbox.retry(job.id, this.fsControlLeaseOwner, delay);
-      await sleep2(200);
       return;
     }
+    const publishSeq = this.state.changeSeq;
+    const isStale = () => this.state.changeSeq !== publishSeq || this.runtime.filesRepo.countByState("dirty") > 0 || this.runtime.filesRepo.countByState("hashing") > 0;
     try {
       const result = await publishSnapshot(
         this.runtime.config.rootPath,
@@ -1882,17 +1987,40 @@ var ServiceRunner = class {
         log,
         {
           maxAttempts: this.runtime.config.maxSnapshotAttempts,
-          uploadChunkSize: this.runtime.config.uploadChunkSize
+          uploadChunkSize: this.runtime.config.uploadChunkSize,
+          deadlineMs: Date.now() + PUBLISH_MAX_MS,
+          isStale
         }
       );
-      this.runtime.outbox.ack(job.id, this.fsControlLeaseOwner);
+      const acked = this.runtime.outbox.ack(job.id, this.fsControlLeaseOwner);
+      if (!acked) {
+        log.warn(
+          { jobId: job.id },
+          "Snapshot job ack failed (lease may have expired)"
+        );
+      }
       this.state.updateSnapshotReady(result.createdAt);
       log.info({ snapshotHash: result.snapshotHash }, "Snapshot job completed");
+      if (this.runtime.filesRepo.countByState("dirty") > 0 || this.runtime.filesRepo.countByState("hashing") > 0) {
+        this.runtime.outbox.enqueueSnapshot(this.runtime.config.rootId, 0);
+        return;
+      }
+      const nowHash = computeSnapshot(this.runtime.filesRepo).snapshotHash;
+      if (nowHash !== result.snapshotHash) {
+        this.runtime.outbox.enqueueSnapshot(this.runtime.config.rootId, 0);
+      }
     } catch (error) {
+      if (error instanceof SnapshotStaleError) {
+        log.debug(
+          { err: error },
+          "Snapshot publish aborted (stale); quick retry"
+        );
+        this.runtime.outbox.retry(job.id, this.fsControlLeaseOwner, 250);
+        return;
+      }
       log.warn({ err: error }, "Snapshot job failed");
       const delay = computeBackoff(job.attempts);
       this.runtime.outbox.retry(job.id, this.fsControlLeaseOwner, delay);
-      await sleep2(delay);
     }
   }
   async handleHeartbeatJob(job, log) {
@@ -2101,33 +2229,20 @@ function createMcpServer({
   async function sleep3(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
-  async function waitForLocalSnapshot(deadlineMs) {
-    let latest = runtime.snapshotsRepo.getLatest();
-    while (!latest && Date.now() < deadlineMs) {
-      await sleep3(250);
-      latest = runtime.snapshotsRepo.getLatest();
-    }
-    return latest;
+  function isLocalStable() {
+    return runtime.filesRepo.countByState("dirty") === 0 && runtime.filesRepo.countByState("hashing") === 0;
   }
-  async function waitForServerReady(initialHash, deadlineMs) {
-    let currentHash = initialHash;
-    while (Date.now() < deadlineMs) {
-      try {
-        const status = await runtime.clients.sync.checkSnapshotStatus(currentHash);
-        if (status.status === "READY") {
-          return currentHash;
-        }
-        if (status.status === "FAILED") {
-        }
-      } catch {
-      }
-      await sleep3(500);
-      const latest = runtime.snapshotsRepo.getLatest();
-      if (latest && latest.snapshot_hash !== currentHash) {
-        currentHash = latest.snapshot_hash;
-      }
+  async function withDeadline2(promise, deadlineMs) {
+    const remaining = deadlineMs - Date.now();
+    if (remaining <= 0) {
+      throw new Error("deadline exceeded");
     }
-    return void 0;
+    return Promise.race([
+      promise,
+      new Promise(
+        (_, reject) => setTimeout(() => reject(new Error("deadline exceeded")), remaining)
+      )
+    ]);
   }
   const server = new mcp_js.McpServer({
     name: SERVER_NAME,
@@ -2161,20 +2276,26 @@ function createMcpServer({
       title: "Semantic Code Retrieval",
       description: "USE THIS before code exploration. Graph-based RAG for semantic code search using AST relationships and embeddings. Returns 30-50 code segments with file paths and line numbers. After initial query, you may query again with refined keywords or use conventional tools (Read, Glob, Grep) for specific files.",
       inputSchema: {
-        query: zod.z.string().min(1, "Query text is required").describe(`Keyword-rich query using technical terms (NOT natural language questions).
+        query: zod.z.string().min(1, "Query text is required").describe(`Short docstring-style description of what the code does + specific technical terms and identifiers (NOT natural language questions, NOT bare keyword lists).
 
-STRATEGY: Use space-separated technical keywords that describe what you're looking for.
+STRATEGY: Start with a mini-docstring (what the code does), then append concrete identifiers, API names, error types, and domain terms.
 
 \u2705 GOOD EXAMPLES:
-- "JWT authentication middleware token validation security handler FastAPI"
-- "file indexing worker celery queue job AST parser embedding chunker"
-- "database schema SQLAlchemy model migration table column relationship"
-- "error handling exception try catch logging traceback"
+- "Validate JWT access token and extract user claims FastAPI dependency AuthMiddleware jose jwt decode RS256 audience issuer"
+- "Index repository files into embedding store Celery worker chunker AST parse imports calls graph propagate batch upsert vector_index"
+- "Create Alembic migration for SQLAlchemy relationship add foreign key backfill existing rows cascade ondelete constraint naming"
+- "Capture exception with traceback and structured context logging logger.exception request_id correlation_id retryable errors"
+- "Load cache from file using shelve.open handle OSError fallback recreate cache file path validation"
+- "Find call sites of verify_jwt decode_jwt get_current_user where used FastAPI router dependency tests pytest"
 
 \u274C BAD EXAMPLES:
 - "How does authentication work?" (natural language question)
 - "Show me the login code" (conversational)
 - "auth" (too vague, needs more context)
+- "JWT authentication middleware token validation security handler FastAPI" (bare keyword list without intent \u2014 add a docstring prefix describing what the code does)
+
+NON-ENGLISH QUERIES: Translate to English before querying.
+- "validate JWT signature and extract claims FastAPI jose RS256 issuer audience"
 
 RETRIEVAL MECHANISM:
 Combines multiple strategies: Seeds (semantic similarity), Flood (AST graph propagation through imports/calls/inheritance), Neighbors (adjacent chunks), and Calls (function relationships).
@@ -2202,53 +2323,94 @@ WHEN TO USE THIS TOOL:
       budgetTokens
     }) => {
       const deadline = Date.now() + runtime.config.maxQueryWaitMs;
-      const latest = await waitForLocalSnapshot(deadline);
-      if (!latest) {
-        const statusText = formatStatus(
-          await collectIndexingStatus(runtime, runner)
-        );
-        const text = `Indexer not ready. Current status:
-
-${statusText}`;
-        return { content: [{ type: "text", text }] };
+      while (Date.now() < deadline) {
+        if (isLocalStable()) break;
+        await sleep3(250);
       }
-      const readyHash = await waitForServerReady(
-        latest.snapshot_hash,
-        deadline
-      );
-      if (!readyHash) {
-        const statusText = formatStatus(
+      if (!isLocalStable()) {
+        const statusText2 = formatStatus(
           await collectIndexingStatus(runtime, runner)
         );
-        const text = `Snapshot not ready on server. Current status:
+        const text2 = `Indexer not ready (local hashing/dirty). Current status:
 
-${statusText}`;
-        return { content: [{ type: "text", text }] };
+${statusText2}`;
+        return { content: [{ type: "text", text: text2 }] };
       }
-      const effectiveBudget = Math.max(100, budgetTokens ?? 1e4);
-      try {
-        const result = await runtime.clients.retrieval.query(
-          readyHash,
-          query,
-          effectiveBudget,
-          { formatter: runtime.config.retrievalFormatter }
-        );
-        return {
-          content: [
-            {
-              type: "text",
-              text: result.formatted_output ?? "(no formatted output)"
+      let currentHash = computeSnapshot(runtime.filesRepo).snapshotHash;
+      let lastStatus;
+      while (Date.now() < deadline) {
+        if (!isLocalStable()) {
+          while (Date.now() < deadline) {
+            if (isLocalStable()) break;
+            await sleep3(250);
+          }
+          if (!isLocalStable()) break;
+          currentHash = computeSnapshot(runtime.filesRepo).snapshotHash;
+          continue;
+        }
+        try {
+          const status = await withDeadline2(
+            runtime.clients.sync.checkSnapshotStatus(currentHash),
+            deadline
+          );
+          lastStatus = status.status;
+          if (status.status === "READY") {
+            const effectiveBudget = Math.max(100, budgetTokens ?? 1e4);
+            try {
+              const result = await withDeadline2(
+                runtime.clients.retrieval.query(
+                  currentHash,
+                  query,
+                  effectiveBudget,
+                  { formatter: runtime.config.retrievalFormatter }
+                ),
+                deadline
+              );
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text: result.formatted_output ?? "(no formatted output)"
+                  }
+                ]
+              };
+            } catch (error) {
+              const message = error instanceof Error ? error.message : "Unknown retrieval error";
+              runtime.logger.error({ err: error }, "Retrieval query failed");
+              return {
+                content: [
+                  { type: "text", text: `Retrieval error: ${message}` }
+                ],
+                isError: true
+              };
             }
-          ]
-        };
-      } catch (error) {
-        const message = error instanceof Error ? error.message : "Unknown retrieval error";
-        runtime.logger.error({ err: error }, "Retrieval query failed");
-        return {
-          content: [{ type: "text", text: `Retrieval error: ${message}` }],
-          isError: true
-        };
+          }
+          if (status.status === "FAILED") {
+            while (Date.now() < deadline) {
+              if (isLocalStable()) break;
+              await sleep3(250);
+            }
+            if (!isLocalStable()) break;
+            currentHash = computeSnapshot(runtime.filesRepo).snapshotHash;
+            continue;
+          }
+          runtime.outbox.enqueueSnapshot(runtime.config.rootId, 0);
+        } catch {
+        }
+        const newHash = computeSnapshot(runtime.filesRepo).snapshotHash;
+        if (newHash !== currentHash) {
+          currentHash = newHash;
+          continue;
+        }
+        await sleep3(500);
       }
+      const statusText = formatStatus(
+        await collectIndexingStatus(runtime, runner)
+      );
+      const text = `Snapshot not READY before deadline (last status: ${lastStatus ?? "unknown"}). Current status:
+
+${statusText}`;
+      return { content: [{ type: "text", text }] };
     }
   );
   return server;