apple-tools-mcp 1.1.4 → 1.2.1

package/lib/indexerLock.js

@@ -0,0 +1,376 @@
+/**
+ * indexer.lock acquire / release / heartbeat.
+ *
+ * A live holder is never displaced, even if the lock timestamp is old
+ * (blocked event loop, long index cycle). Dead-PID takeover never renames
+ * the live lock path. Waiters take a wx mutex, re-read, unlink only if the
+ * contents are still the expected dead lock, wx-create the new lock, then
+ * drop the mutex — so a peer's freshly created lock is never deleted.
+ * An orphaned takeover mutex is never stolen with compare-then-unlink of
+ * the live `.takeover` path: waiters wx a fence named by the dead PID.
+ * Empty or unparsable mutex/lock contents are unknown — do not fence or steal
+ * (covers wx open-then-write and heartbeat truncate-then-write windows).
+ */
+
+import fs from "fs";
+import path from "path";
+
+export const DEFAULT_LOCK_TIMEOUT_MS = 30 * 60 * 1000;
+export const DEFAULT_LOCK_HEARTBEAT_MS = 60 * 1000;
+export const TAKEOVER_MUTEX_SUFFIX = ".takeover";
+export const TAKEOVER_FENCE_DEPTH = 8;
+
+/**
+ * @param {string} lockFile
+ * @returns {string}
+ */
+export function getTakeoverMutexPath(lockFile) {
+  return `${lockFile}${TAKEOVER_MUTEX_SUFFIX}`;
+}
+
+/**
+ * wx fence used when indexer.lock.takeover is orphaned (dead PID).
+ * @param {string} lockFile
+ * @param {...number|string} deadIds
+ * @returns {string}
+ */
+export function getTakeoverFencePath(lockFile, ...deadIds) {
+  let p = getTakeoverMutexPath(lockFile);
+  for (const id of deadIds) {
+    p = `${p}.${id}`;
+  }
+  return p;
+}
+
+/**
+ * @param {unknown} pid
+ * @param {(pid: number, signal: number) => void} [killFn]
+ * @returns {boolean}
+ */
+export function isProcessAlive(pid, killFn = (p, signal) => process.kill(p, signal)) {
+  try {
+    killFn(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} text
+ * @returns {{ pid: number, timestamp: number, raw: string } | null}
+ */
+export function parseLockData(text) {
+  if (typeof text !== "string" || text.length === 0) {
+    return null;
+  }
+  const [pidStr, timestampStr] = text.split(":");
+  const pid = parseInt(pidStr, 10);
+  const timestamp = parseInt(timestampStr, 10);
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return null;
+  }
+  return {
+    pid,
+    timestamp: Number.isInteger(timestamp) ? timestamp : 0,
+    raw: text
+  };
+}
+
+/**
+ * @param {number} pid
+ * @param {number} timestamp
+ * @returns {string}
+ */
+export function formatLockData(pid, timestamp) {
+  return `${pid}:${timestamp}`;
+}
+
+/**
+ * @param {{
+ *   lockFile: string,
+ *   pid?: number,
+ *   now?: () => number,
+ *   timeoutMs?: number,
+ *   isAlive?: (pid: number) => boolean,
+ *   fsApi?: Pick<typeof fs, "existsSync" | "readFileSync" | "writeFileSync" | "unlinkSync" | "mkdirSync">,
+ *   log?: (msg: string) => void,
+ *   setIntervalFn?: typeof setInterval,
+ *   clearIntervalFn?: typeof clearInterval
+ * }} options
+ */
+export function createIndexerLock(options) {
+  const lockFile = options.lockFile;
+  const mutexPath = getTakeoverMutexPath(lockFile);
+  const pid = options.pid ?? process.pid;
+  const now = options.now || (() => Date.now());
+  const timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+  const isAlive = options.isAlive || ((holderPid) => isProcessAlive(holderPid));
+  const fsApi = options.fsApi || fs;
+  const log = options.log || ((msg) => console.error(msg));
+  const setIntervalFn = options.setIntervalFn || setInterval;
+  const clearIntervalFn = options.clearIntervalFn || clearInterval;
+
+  let ownsLock = false;
+  let heartbeatTimer = null;
+  let heldMutexPath = null;
+
+  function readLockFile() {
+    if (!fsApi.existsSync(lockFile)) {
+      return null;
+    }
+    return fsApi.readFileSync(lockFile, "utf8");
+  }
+
+  function skipLiveHolder(parsed) {
+    const lockAge = now() - parsed.timestamp;
+    if (lockAge > timeoutMs) {
+      log(
+        `Lock file is ${Math.round(lockAge / 60000)} minutes old, but PID ${parsed.pid} is still running. Not taking over.`
+      );
+    } else {
+      log(`Another indexing instance running (PID ${parsed.pid}). Skipping indexing.`);
+    }
+    ownsLock = false;
+    return false;
+  }
+
+  function refreshOwned() {
+    ownsLock = true;
+    try {
+      fsApi.writeFileSync(lockFile, formatLockData(pid, now()));
+    } catch {
+      // Heartbeat or the next cycle can retry the write.
+    }
+    return true;
+  }
+
+  function tryAcquireMutex() {
+    const token = formatLockData(pid, now());
+    let candidate = mutexPath;
+    try {
+      for (let depth = 0; depth < TAKEOVER_FENCE_DEPTH; depth++) {
+        let exists = false;
+        for (let spin = 0; spin < 4; spin++) {
+          try {
+            fsApi.writeFileSync(candidate, token, { flag: "wx" });
+            heldMutexPath = candidate;
+            return true;
+          } catch (err) {
+            if (err && err.code === "ENOENT") {
+              continue;
+            }
+            if (!err || err.code !== "EEXIST") {
+              throw err;
+            }
+            exists = true;
+            break;
+          }
+        }
+        if (!exists) {
+          return false;
+        }
+        let data;
+        try {
+          data = fsApi.readFileSync(candidate, "utf8");
+        } catch (err) {
+          if (err && err.code === "ENOENT") {
+            continue;
+          }
+          throw err;
+        }
+        const parsed = parseLockData(data);
+        if (!parsed) {
+          return false;
+        }
+        if (isAlive(parsed.pid)) {
+          return false;
+        }
+        candidate = `${candidate}.${parsed.pid}`;
+      }
+      return false;
+    } catch (err) {
+      if (err && err.code === "EEXIST") {
+        return false;
+      }
+      log(`Takeover mutex error: ${err.message}`);
+      return false;
+    }
+  }
+
+  function dropMutex() {
+    const held = heldMutexPath;
+    heldMutexPath = null;
+    if (!held) {
+      return;
+    }
+    try {
+      if (!fsApi.existsSync(held)) {
+        return;
+      }
+      const data = fsApi.readFileSync(held, "utf8");
+      const parsed = parseLockData(data);
+      if (parsed && parsed.pid === pid) {
+        fsApi.unlinkSync(held);
+      }
+    } catch (err) {
+      log(`Takeover mutex release error: ${err.message}`);
+    }
+  }
+
+  /**
+   * Under the wx mutex: re-read, unlink only the still-expected dead lock,
+   * then wx-create. Never rename the live path.
+   */
+  function finishAcquireUnderMutex(expectedStale) {
+    const current = readLockFile();
+
+    if (current !== null) {
+      const parsed = parseLockData(current);
+      if (!parsed) {
+        ownsLock = false;
+        return false;
+      }
+      if (parsed.pid === pid) {
+        return refreshOwned();
+      }
+      if (isAlive(parsed.pid)) {
+        return skipLiveHolder(parsed);
+      }
+      if (expectedStale === null || current !== expectedStale) {
+        ownsLock = false;
+        return false;
+      }
+      // Re-read immediately before unlink. Never delete a peer's wx lock.
+      const again = readLockFile();
+      if (again !== expectedStale) {
+        ownsLock = false;
+        return false;
+      }
+      try {
+        fsApi.unlinkSync(lockFile);
+      } catch (err) {
+        if (!err || err.code !== "ENOENT") {
+          throw err;
+        }
+      }
+      log(`Removing stale lock file (PID ${parsed ? parsed.pid : "unknown"} not running)`);
+    }
+
+    try {
+      fsApi.writeFileSync(lockFile, formatLockData(pid, now()), { flag: "wx" });
+      ownsLock = true;
+      return true;
+    } catch (err) {
+      if (err.code === "EEXIST") {
+        log("Another process acquired lock during race. Skipping indexing.");
+        ownsLock = false;
+        return false;
+      }
+      throw err;
+    }
+  }
+
+  function acquire() {
+    try {
+      const lockDir = path.dirname(lockFile);
+      if (!fsApi.existsSync(lockDir)) {
+        fsApi.mkdirSync(lockDir, { recursive: true });
+      }
+
+      const existing = readLockFile();
+      if (existing !== null) {
+        const parsed = parseLockData(existing);
+        if (!parsed) {
+          ownsLock = false;
+          return false;
+        }
+        if (parsed.pid === pid) {
+          return refreshOwned();
+        }
+        if (isAlive(parsed.pid)) {
+          return skipLiveHolder(parsed);
+        }
+      }
+
+      if (!tryAcquireMutex()) {
+        log("Another process acquired lock during race. Skipping indexing.");
+        ownsLock = false;
+        return false;
+      }
+      try {
+        return finishAcquireUnderMutex(existing);
+      } finally {
+        dropMutex();
+      }
+    } catch (e) {
+      log(`Lock file error: ${e.message}`);
+      ownsLock = false;
+      return false;
+    }
+  }
+
+  function release() {
+    try {
+      const lockData = readLockFile();
+      if (lockData) {
+        const parsed = parseLockData(lockData);
+        if (parsed && parsed.pid === pid) {
+          fsApi.unlinkSync(lockFile);
+          ownsLock = false;
+          log(`Released lock file (PID ${pid})`);
+        }
+      }
+    } catch (err) {
+      log(`Error releasing lock: ${err.message}`);
+    }
+  }
+
+  function refresh() {
+    try {
+      if (!ownsLock) {
+        return false;
+      }
+      const lockData = readLockFile();
+      if (!lockData) {
+        return false;
+      }
+      const parsed = parseLockData(lockData);
+      if (parsed && parsed.pid === pid) {
+        fsApi.writeFileSync(lockFile, formatLockData(pid, now()));
+        return true;
+      }
+      return false;
+    } catch (err) {
+      log(`Lock heartbeat error: ${err.message}`);
+      return false;
+    }
+  }
+
+  function startHeartbeat(intervalMs = DEFAULT_LOCK_HEARTBEAT_MS) {
+    if (heartbeatTimer) {
+      return;
+    }
+    heartbeatTimer = setIntervalFn(() => {
+      refresh();
+    }, intervalMs);
+  }
+
+  function stopHeartbeat() {
+    if (heartbeatTimer) {
+      clearIntervalFn(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+  }
+
+  return {
+    acquire,
+    release,
+    refresh,
+    startHeartbeat,
+    stopHeartbeat,
+    get ownsLock() {
+      return ownsLock;
+    }
+  };
+}

package/lib/indexerRuntime.js

@@ -0,0 +1,142 @@
+/**
+ * Indexer daemon vs MCP stdio runtime helpers.
+ * Kept separate from index.js so daemon paths can be tested without
+ * starting MCP stdio or loading the embedding model.
+ */
+
+/**
+ * @param {boolean} indexerMode
+ * @returns {boolean}
+ */
+export function shouldConnectMcpStdio(indexerMode) {
+  return !indexerMode;
+}
+
+/**
+ * @param {boolean} indexerMode
+ * @returns {boolean}
+ */
+export function shouldExitOnStdinClose(indexerMode) {
+  return !indexerMode;
+}
+
+/**
+ * Bind stdin `close` → callback only for MCP stdio clients.
+ * Indexer daemons must ignore stdin close (LaunchAgent often uses /dev/null).
+ *
+ * @param {{ on: (event: string, handler: () => void) => void }} stdin
+ * @param {boolean} indexerMode
+ * @param {() => void} onClose
+ * @returns {{ bound: boolean }}
+ */
+export function bindStdinCloseExit(stdin, indexerMode, onClose) {
+  if (!shouldExitOnStdinClose(indexerMode)) {
+    return { bound: false };
+  }
+  stdin.on("close", onClose);
+  return { bound: true };
+}
+
+/**
+ * Start one index cycle, or skip if a cycle is already running.
+ *
+ * @param {boolean} indexingInProgress
+ * @param {(msg: string) => void} [log]
+ * @returns {{ started: boolean, indexingInProgress: boolean }}
+ */
+export function beginIndexCycle(indexingInProgress, log = (msg) => console.error(msg)) {
+  if (indexingInProgress) {
+    log("Indexing already in progress, skipping cycle");
+    return { started: false, indexingInProgress: true };
+  }
+  return { started: true, indexingInProgress: true };
+}
+
+/**
+ * After a cycle: daemon keeps the lock; MCP local-fallback releases it.
+ *
+ * @param {{
+ *   success: boolean,
+ *   indexerMode: boolean,
+ *   cycleEndFlags: (success: boolean) => {
+ *     indexingInProgress: boolean,
+ *     sessionIndexComplete: boolean,
+ *     ownsIndexLock: boolean,
+ *     isFirstEverRun?: boolean
+ *   },
+ *   releaseLock: () => void
+ * }} args
+ */
+export function applyIndexerCycleEnd({ success, indexerMode, cycleEndFlags, releaseLock }) {
+  const flags = cycleEndFlags(success);
+  if (indexerMode) {
+    return {
+      indexingInProgress: flags.indexingInProgress,
+      sessionIndexComplete: flags.sessionIndexComplete,
+      ownsIndexLock: true,
+      isFirstEverRun: flags.isFirstEverRun,
+      released: false
+    };
+  }
+  releaseLock();
+  return {
+    indexingInProgress: flags.indexingInProgress,
+    sessionIndexComplete: flags.sessionIndexComplete,
+    ownsIndexLock: flags.ownsIndexLock,
+    isFirstEverRun: flags.isFirstEverRun,
+    released: true
+  };
+}
+
+/**
+ * MCP stdio startup: index locally only when the lock is free.
+ *
+ * @param {() => boolean} acquireLock
+ * @returns {{ startBackground: boolean, ownsIndexLock: boolean, startHeartbeat: boolean, reason: "local-fallback" | "lock-held" }}
+ */
+export function mcpIndexingStartup(acquireLock) {
+  if (!acquireLock()) {
+    return { startBackground: false, ownsIndexLock: false, startHeartbeat: false, reason: "lock-held" };
+  }
+  return { startBackground: true, ownsIndexLock: true, startHeartbeat: true, reason: "local-fallback" };
+}
+
+/**
+ * Shared path once this process owns indexer.lock: heartbeat + background cycles.
+ * MCP local-fallback must use this too, not only the daemon.
+ *
+ * @param {{ startHeartbeat: () => void, startBackground: () => void }} steps
+ */
+export function beginOwnedIndexing(steps) {
+  steps.startHeartbeat();
+  steps.startBackground();
+}
+
+/**
+ * Retry until the daemon owns indexer.lock, then run onAcquired.
+ *
+ * @param {() => boolean} acquireLock
+ * @param {{
+ *   retryMs: number,
+ *   onAcquired: () => void,
+ *   log?: (msg: string) => void,
+ *   setTimeoutFn?: typeof setTimeout
+ * }} options
+ */
+export function waitForIndexerLock(acquireLock, options) {
+  const retryMs = options.retryMs;
+  const onAcquired = options.onAcquired;
+  const log = options.log || ((msg) => console.error(msg));
+  const setTimeoutFn = options.setTimeoutFn || setTimeout;
+
+  const tryAcquire = () => {
+    if (acquireLock()) {
+      log("Indexer daemon acquired indexer.lock");
+      onAcquired();
+      return;
+    }
+    log("Indexer daemon waiting for indexer.lock...");
+    setTimeoutFn(tryAcquire, retryMs);
+  };
+  tryAcquire();
+}