@indigoai-us/hq-cloud 6.14.28 → 6.14.30

package/src/qmd-reindex.test.ts

@@ -6,9 +6,9 @@
  * is invoked. We assert on the *sequence of qmd commands* the function would
  * run, which is the contract that keeps a teammate's index fresh after sync.
  *
- * The corruption-safety tests (lock serialization, timeout-kill handling, and
- * SQLITE_CORRUPT quarantine) pin the fix for feedback_b9a369ff — the post-sync
- * reindex racing an interactive qmd writer and corrupting the vector store.
+ * Corruption-safety tests pin feedback_b9a369ff + feedback_332c7ccc (resolved
+ * index path, dual-lock, honest quarantine). Path-drift tests pin
+ * feedback_f8e233c6 (detect-only by default; opt-in repair).
  */
 
 import { describe, it, expect } from "vitest";
@@ -20,6 +20,11 @@ import {
   looksCorrupt,
   resolveExecTimeoutMs,
   DEFAULT_QMD_EXEC_TIMEOUT_MS,
+  parseIndexDirFromStatus,
+  parseCollectionPathFromShow,
+  pathsEquivalent,
+  repairPathDriftEnabled,
+  acquireDualReindexLocks,
   type QmdExec,
   type QmdExecResult,
   type AcquireReindexLock,
@@ -29,9 +34,13 @@ import {
 /** A lock acquirer that always succeeds — keeps command-sequence tests pure. */
 const noLock: AcquireReindexLock = () => ({ release() {} });
 
+/** Identity realpath so path-drift comparisons stay deterministic in fakes. */
+const identityRealpath = (p: string) => path.resolve(p);
+
 /** Build a fake exec that returns status 0 for everything and logs calls. */
 function fakeExec(opts?: {
   listStdout?: string;
+  statusStdout?: string;
   failOn?: string;
   resultFor?: (args: string[]) => Partial<QmdExecResult> | undefined;
 }): {
@@ -44,9 +53,20 @@ function fakeExec(opts?: {
     const override = opts?.resultFor?.(args);
     if (override) return { status: 0, stdout: "", ...override };
     if (opts?.failOn && args[0] === opts.failOn) return { status: 1, stdout: "" };
+    if (args[0] === "status") {
+      return { status: 0, stdout: opts?.statusStdout ?? "" };
+    }
     if (args[0] === "collection" && args[1] === "list") {
       return { status: 0, stdout: opts?.listStdout ?? "" };
     }
+    if (args[0] === "collection" && args[1] === "show") {
+      const name = args[2] ?? "unknown";
+      const registered = path.join("/hq", "companies", name, "knowledge");
+      return {
+        status: 0,
+        stdout: `Collection: ${name}\n  Path: ${registered}\n  Pattern: **/*.md\n`,
+      };
+    }
     return { status: 0, stdout: "" };
   };
   return { exec, calls };
@@ -73,8 +93,7 @@ describe("reindexAfterSync", () => {
     });
     expect(r.qmdAvailable).toBe(false);
     expect(r.updated).toBe(false);
-    // Only the availability probe ran, then bailed.
-    expect(calls).toEqual([["collection", "list"]]);
+    expect(calls).toEqual([["status"], ["collection", "list"]]);
   });
 
   it("registers a missing company collection then runs an incremental update", () => {
@@ -91,8 +110,8 @@ describe("reindexAfterSync", () => {
     expect(r.updated).toBe(true);
     expect(r.embedded).toBe(false);
 
-    // Expected command sequence: probe, add, context, update.
     expect(calls).toEqual([
+      ["status"],
       ["collection", "list"],
       ["collection", "add", path.join("/hq", "companies", "acme", "knowledge"), "--name", "acme", "--mask", "**/*.md"],
       ["context", "add", "qmd://acme", "Knowledge base for acme."],
@@ -100,7 +119,7 @@ describe("reindexAfterSync", () => {
     ]);
   });
 
-  it("skips collections that already exist", () => {
+  it("skips collections that already exist at the desired path", () => {
     const { exec, calls } = fakeExec({ listStdout: "acme (qmd://acme/)\n" });
     const r = reindexAfterSync("/hq", {
       exec,
@@ -108,10 +127,102 @@ describe("reindexAfterSync", () => {
       existsSync: () => true,
       readCompanies: () => ["acme"],
       hasIndexableMarkdown: () => true,
+      realpathSync: identityRealpath,
     });
     expect(r.collectionsAdded).toEqual([]);
-    // No `collection add` — straight to update.
-    expect(calls).toEqual([["collection", "list"], ["update"]]);
+    expect(r.pathDriftDetected).toEqual([]);
+    expect(calls).toEqual([
+      ["status"],
+      ["collection", "list"],
+      ["collection", "show", "acme"],
+      ["update"],
+    ]);
+  });
+
+  it("detects path drift without repairing when HQ_QMD_REPAIR_PATH_DRIFT is off", () => {
+    const drifted = path.join("/mirror", "knowledge-acme");
+    const { exec, calls } = fakeExec({
+      listStdout: "acme (qmd://acme/)\n",
+      resultFor: (args) =>
+        args[0] === "collection" && args[1] === "show"
+          ? {
+              status: 0,
+              stdout: `Collection: acme\n  Path: ${drifted}\n`,
+            }
+          : undefined,
+    });
+    const r = reindexAfterSync("/hq", {
+      exec,
+      acquireReindexLock: noLock,
+      existsSync: () => true,
+      readCompanies: () => ["acme"],
+      hasIndexableMarkdown: () => true,
+      realpathSync: identityRealpath,
+      env: {},
+      embed: true,
+    });
+    expect(r.pathDriftDetected).toEqual(["acme"]);
+    expect(r.collectionsRepaired).toEqual([]);
+    expect(calls.some((c) => c[0] === "collection" && c[1] === "remove")).toBe(false);
+    // Detect-only must still allow embed (no repair this cycle).
+    expect(r.embedded).toBe(true);
+  });
+
+  it("repairs path drift when HQ_QMD_REPAIR_PATH_DRIFT=1 and skips embed", () => {
+    const drifted = path.join("/mirror", "knowledge-acme");
+    const desired = path.join("/hq", "companies", "acme", "knowledge");
+    const { exec, calls } = fakeExec({
+      listStdout: "acme (qmd://acme/)\n",
+      resultFor: (args) =>
+        args[0] === "collection" && args[1] === "show"
+          ? { status: 0, stdout: `Collection: acme\n  Path: ${drifted}\n` }
+          : undefined,
+    });
+    const r = reindexAfterSync("/hq", {
+      exec,
+      acquireReindexLock: noLock,
+      existsSync: () => true,
+      readCompanies: () => ["acme"],
+      hasIndexableMarkdown: () => true,
+      realpathSync: identityRealpath,
+      env: { HQ_QMD_REPAIR_PATH_DRIFT: "1" },
+      embed: true,
+    });
+    expect(r.pathDriftDetected).toEqual(["acme"]);
+    expect(r.collectionsRepaired).toEqual(["acme"]);
+    expect(r.embedded).toBe(false);
+    expect(calls).toEqual([
+      ["status"],
+      ["collection", "list"],
+      ["collection", "show", "acme"],
+      ["collection", "remove", "acme"],
+      ["collection", "add", desired, "--name", "acme", "--mask", "**/*.md"],
+      ["context", "add", "qmd://acme", "Knowledge base for acme."],
+      ["update"],
+    ]);
+  });
+
+  it("does not remove a drifted collection when desired path has no indexable markdown", () => {
+    const drifted = path.join("/mirror", "knowledge-acme");
+    const { exec, calls } = fakeExec({
+      listStdout: "acme (qmd://acme/)\n",
+      resultFor: (args) =>
+        args[0] === "collection" && args[1] === "show"
+          ? { status: 0, stdout: `Collection: acme\n  Path: ${drifted}\n` }
+          : undefined,
+    });
+    // hasIndexableMarkdown false → skipped before show/repair (desired empty).
+    const r = reindexAfterSync("/hq", {
+      exec,
+      acquireReindexLock: noLock,
+      existsSync: () => true,
+      readCompanies: () => ["acme"],
+      hasIndexableMarkdown: () => false,
+      env: { HQ_QMD_REPAIR_PATH_DRIFT: "1" },
+    });
+    expect(r.pathDriftDetected).toEqual([]);
+    expect(r.collectionsRepaired).toEqual([]);
+    expect(calls.some((c) => c[1] === "remove")).toBe(false);
   });
 
   it("skips company dirs with no indexable markdown", () => {
@@ -124,7 +235,7 @@ describe("reindexAfterSync", () => {
       hasIndexableMarkdown: () => false,
     });
     expect(r.collectionsAdded).toEqual([]);
-    expect(calls).toEqual([["collection", "list"], ["update"]]);
+    expect(calls).toEqual([["status"], ["collection", "list"], ["update"]]);
   });
 
   it("skips qmd entirely when provided changed paths do not touch knowledge markdown", () => {
@@ -150,14 +261,21 @@ describe("reindexAfterSync", () => {
         exec,
         acquireReindexLock: noLock,
         existsSync: () => true,
+        readCompanies: () => ["acme"],
+        hasIndexableMarkdown: () => true,
         changedPaths: ["companies/acme/knowledge/note.md"],
         debounceMs: 60_000,
         nowMs: 100_000,
         statePath,
+        realpathSync: identityRealpath,
       });
       expect(first.updated).toBe(false);
       expect(first.pendingDirty).toBe(true);
-      expect(calls).toEqual([["collection", "list"]]);
+      expect(calls).toEqual([
+        ["status"],
+        ["collection", "list"],
+        ["collection", "show", "acme"],
+      ]);
 
       const second = reindexAfterSync("/hq", {
         exec,
@@ -171,7 +289,10 @@ describe("reindexAfterSync", () => {
       expect(second.updated).toBe(true);
       expect(second.pendingDirty).toBe(false);
       expect(calls).toEqual([
+        ["status"],
         ["collection", "list"],
+        ["collection", "show", "acme"],
+        ["status"],
         ["collection", "list"],
         ["update"],
       ]);
@@ -190,7 +311,7 @@ describe("reindexAfterSync", () => {
       embed: true,
     });
     expect(r.embedded).toBe(true);
-    expect(calls).toEqual([["collection", "list"], ["update"], ["embed"]]);
+    expect(calls).toEqual([["status"], ["collection", "list"], ["update"], ["embed"]]);
   });
 
   it("never throws even if exec misbehaves", () => {
@@ -224,7 +345,7 @@ describe("reindexAfterSync", () => {
 
   // ── Corruption safety: lock serialization (feedback_b9a369ff) ──────────────
 
-  it("skips the whole cycle without touching qmd when another writer holds the lock", () => {
+  it("skips the cycle after status when another writer holds the lock", () => {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-lockbusy-"));
     try {
       const statePath = path.join(dir, "qmd-state.json");
@@ -236,13 +357,11 @@ describe("reindexAfterSync", () => {
         // Simulate a concurrent qmd writer already holding the lock.
         acquireReindexLock: () => null,
       });
-      // The runner never runs a single qmd command while another writer holds
-      // the lock — this is what prevents the concurrent-writer corruption.
-      expect(calls).toEqual([]);
+      // status is read-only and runs before lock; no write commands follow.
+      expect(calls).toEqual([["status"]]);
       expect(r.lockBusy).toBe(true);
       expect(r.pendingDirty).toBe(true);
       expect(r.updated).toBe(false);
-      // The tree is marked dirty so the next sync retries once the lock frees.
       const persisted = JSON.parse(fs.readFileSync(statePath, "utf8"));
       expect(persisted.pendingDirty).toBe(true);
     } finally {
@@ -250,9 +369,10 @@ describe("reindexAfterSync", () => {
     }
   });
 
-  it("always releases the lock, even when a qmd command throws", () => {
+  it("always releases the lock, even when a qmd command throws after status", () => {
     let released = false;
-    const exec: QmdExec = () => {
+    const exec: QmdExec = (args) => {
+      if (args[0] === "status") return { status: 0, stdout: "" };
       throw new Error("boom");
     };
     reindexAfterSync("/hq", {
@@ -283,15 +403,14 @@ describe("reindexAfterSync", () => {
         acquireReindexLock: noLock,
         existsSync: () => true,
         readCompanies: () => [],
-        embed: true, // would normally run embed after update
+        embed: true,
         statePath,
       });
       expect(r.timedOut).toBe(true);
       expect(r.updated).toBe(false);
       expect(r.embedded).toBe(false);
       expect(r.pendingDirty).toBe(true);
-      // Crucially: no `embed` after a timed-out update — never write further.
-      expect(calls).toEqual([["collection", "list"], ["update"]]);
+      expect(calls).toEqual([["status"], ["collection", "list"], ["update"]]);
       const persisted = JSON.parse(fs.readFileSync(statePath, "utf8"));
       expect(persisted.pendingDirty).toBe(true);
     } finally {
@@ -320,10 +439,11 @@ describe("reindexAfterSync", () => {
 
   // ── Corruption safety: SQLITE_CORRUPT detection + quarantine ────────────────
 
-  it("quarantines the DB and stops writing when update reports SQLITE_CORRUPT", () => {
+  it("quarantines the resolved index dir when update reports SQLITE_CORRUPT", () => {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-corrupt-"));
     try {
       const statePath = path.join(dir, "qmd-state.json");
+      const cacheDir = path.join(dir, "cache-qmd");
       const quarantined: Array<{ qmdDir: string; suffix: string }> = [];
       const quarantine: QuarantineCorruptIndex = (qmdDir, suffix) => {
         quarantined.push({ qmdDir, suffix });
@@ -331,6 +451,7 @@ describe("reindexAfterSync", () => {
       };
       const { exec, calls } = fakeExec({
         listStdout: "",
+        statusStdout: `Index: ${path.join(cacheDir, "index.sqlite")}\nSize: 1 GB\n`,
         resultFor: (args) =>
           args[0] === "update"
             ? { status: 1, stderr: "SqliteError: database disk image is malformed (SQLITE_CORRUPT)" }
@@ -341,24 +462,24 @@ describe("reindexAfterSync", () => {
         acquireReindexLock: noLock,
         existsSync: () => true,
         readCompanies: () => [],
-        embed: true, // must NOT run after corruption
+        embed: true,
         statePath,
         quarantineCorruptIndex: quarantine,
       });
       expect(r.corruptionQuarantined).toBe(true);
+      expect(r.corruptionQuarantineFailed).toBe(false);
       expect(r.embedded).toBe(false);
       expect(r.pendingDirty).toBe(true);
-      expect(calls).toEqual([["collection", "list"], ["update"]]); // no embed
+      expect(calls).toEqual([["status"], ["collection", "list"], ["update"]]);
       expect(quarantined).toHaveLength(1);
-      expect(quarantined[0].qmdDir).toBe(path.join("/hq", ".qmd"));
-      const persisted = JSON.parse(fs.readFileSync(statePath, "utf8"));
-      expect(persisted.pendingDirty).toBe(true);
+      expect(quarantined[0].qmdDir).toBe(cacheDir);
+      expect(r.indexDir).toBe(cacheDir);
     } finally {
       fs.rmSync(dir, { recursive: true, force: true });
     }
   });
 
-  it("quarantines on a corrupt collection-list probe before any write", () => {
+  it("reports quarantine failure when corruption is detected but nothing moves", () => {
     const quarantined: string[] = [];
     const { exec, calls } = fakeExec({
       resultFor: (args) =>
@@ -375,10 +496,10 @@ describe("reindexAfterSync", () => {
         return null;
       },
     });
-    expect(r.corruptionQuarantined).toBe(true);
+    expect(r.corruptionQuarantined).toBe(false);
+    expect(r.corruptionQuarantineFailed).toBe(true);
     expect(r.updated).toBe(false);
-    // Detected on the probe — never runs update/embed onto the corrupt store.
-    expect(calls).toEqual([["collection", "list"]]);
+    expect(calls).toEqual([["status"], ["collection", "list"]]);
     expect(quarantined).toEqual([path.join("/hq", ".qmd")]);
   });
 
@@ -399,12 +520,12 @@ describe("reindexAfterSync", () => {
       embed: true,
       quarantineCorruptIndex: (qmdDir) => {
         quarantined.push(qmdDir);
-        return null;
+        return path.join(qmdDir, "index.sqlite.corrupt-x");
       },
     });
     expect(r.corruptionQuarantined).toBe(true);
     expect(r.embedded).toBe(false);
-    expect(calls).toEqual([["collection", "list"], ["update"], ["embed"]]);
+    expect(calls).toEqual([["status"], ["collection", "list"], ["update"], ["embed"]]);
     expect(quarantined).toEqual([path.join("/hq", ".qmd")]);
   });
 });
@@ -422,8 +543,6 @@ describe("default reindex lock", () => {
       fs.writeFileSync(path.join(hq, "core", "core.yaml"), "v: 1\n");
       fs.writeFileSync(path.join(kdir, "note.md"), "# real\n");
 
-      // While the cycle runs (mid-exec), a naive O_EXCL re-acquire of the same
-      // lock file must fail with EEXIST — proving the lock is genuinely held.
       const lockPath = path.join(hq, ".qmd", ".reindex.lock");
       let reAcquireBlockedWhileHeld = false;
       const { exec } = fakeExec({ listStdout: "" });
@@ -431,7 +550,7 @@ describe("default reindex lock", () => {
         if (args[0] === "update") {
           try {
             fs.closeSync(fs.openSync(lockPath, "wx"));
-            fs.unlinkSync(lockPath); // acquired — NOT what we want
+            fs.unlinkSync(lockPath);
           } catch (err) {
             reAcquireBlockedWhileHeld =
               (err as NodeJS.ErrnoException).code === "EEXIST";
@@ -443,7 +562,6 @@ describe("default reindex lock", () => {
       const r = reindexAfterSync(hq, { exec: observingExec });
       expect(r.updated).toBe(true);
       expect(reAcquireBlockedWhileHeld).toBe(true);
-      // Released after the cycle — the lock file is gone.
       expect(fs.existsSync(lockPath)).toBe(false);
     } finally {
       fs.rmSync(dir, { recursive: true, force: true });
@@ -460,7 +578,6 @@ describe("default reindex lock", () => {
       fs.writeFileSync(path.join(hq, "core", "core.yaml"), "v: 1\n");
       fs.writeFileSync(path.join(kdir, "note.md"), "# real\n");
 
-      // Plant a lock owned by a PID that is certainly not alive.
       const lockPath = path.join(hq, ".qmd", ".reindex.lock");
       fs.mkdirSync(path.dirname(lockPath), { recursive: true });
       fs.writeFileSync(
@@ -470,7 +587,6 @@ describe("default reindex lock", () => {
 
       const { exec, calls } = fakeExec({ listStdout: "" });
       const r = reindexAfterSync(hq, { exec });
-      // The dead holder was reclaimed, so the reindex ran to completion.
       expect(r.updated).toBe(true);
       expect(r.lockBusy).toBe(false);
       expect(calls.some((c) => c[0] === "update")).toBe(true);
@@ -480,6 +596,42 @@ describe("default reindex lock", () => {
   });
 });
 
+describe("acquireDualReindexLocks", () => {
+  it("dedupes identical paths so a process cannot lock itself out", () => {
+    let acquires = 0;
+    const acquire: AcquireReindexLock = () => {
+      acquires++;
+      return { release() {} };
+    };
+    const same = path.join("/hq", ".qmd", ".reindex.lock");
+    const { locks, busy } = acquireDualReindexLocks(acquire, [same, same]);
+    expect(busy).toBe(false);
+    expect(locks).toHaveLength(1);
+    expect(acquires).toBe(1);
+  });
+
+  it("releases the first lock when the second is busy", () => {
+    const released: string[] = [];
+    let n = 0;
+    const acquire: AcquireReindexLock = (lockPath) => {
+      n++;
+      if (n === 2) return null;
+      return {
+        release() {
+          released.push(lockPath);
+        },
+      };
+    };
+    const { locks, busy } = acquireDualReindexLocks(acquire, [
+      "/a/.reindex.lock",
+      "/b/.reindex.lock",
+    ]);
+    expect(busy).toBe(true);
+    expect(locks).toHaveLength(0);
+    expect(released).toEqual(["/a/.reindex.lock"]);
+  });
+});
+
 // ── Pure helpers ─────────────────────────────────────────────────────────────
 
 describe("resolveExecTimeoutMs", () => {
@@ -511,3 +663,37 @@ describe("looksCorrupt", () => {
     expect(looksCorrupt({})).toBe(false);
   });
 });
+
+describe("parseIndexDirFromStatus / parseCollectionPathFromShow", () => {
+  it("parses Index file path into its directory", () => {
+    expect(
+      parseIndexDirFromStatus("Index: C:/Users/me/.cache/qmd/index.sqlite\nSize: 1.3 GB\n"),
+    ).toBe(path.dirname("C:/Users/me/.cache/qmd/index.sqlite"));
+  });
+
+  it("returns null when Index line is missing", () => {
+    expect(parseIndexDirFromStatus("Collections: 2\n")).toBeNull();
+  });
+
+  it("parses Path from collection show", () => {
+    expect(
+      parseCollectionPathFromShow("Collection: indigo\n  Path: /hq/companies/indigo/knowledge\n"),
+    ).toBe("/hq/companies/indigo/knowledge");
+  });
+});
+
+describe("pathsEquivalent / repairPathDriftEnabled", () => {
+  it("treats case and trailing separators as equal", () => {
+    expect(
+      pathsEquivalent("/HQ/Companies/Acme/knowledge/", "/hq/companies/acme/knowledge", (p) => p),
+    ).toBe(true);
+  });
+
+  it("enables repair only for 1/true/yes", () => {
+    expect(repairPathDriftEnabled({})).toBe(false);
+    expect(repairPathDriftEnabled({ HQ_QMD_REPAIR_PATH_DRIFT: "1" })).toBe(true);
+    expect(repairPathDriftEnabled({ HQ_QMD_REPAIR_PATH_DRIFT: "true" })).toBe(true);
+    expect(repairPathDriftEnabled({ HQ_QMD_REPAIR_PATH_DRIFT: "yes" })).toBe(true);
+    expect(repairPathDriftEnabled({ HQ_QMD_REPAIR_PATH_DRIFT: "0" })).toBe(false);
+  });
+});