apple-tools-mcp 1.1.3 → 1.2.0

package/lib/config.js

@@ -0,0 +1,312 @@
+/**
+ * User config for apple-tools-mcp.
+ *
+ * Path is fixed at ~/.apple-tools-mcp/config.json (or $HOME). Arbitrary paths
+ * from config contents are ignored — config is treated as data, not as
+ * instructions or path overrides.
+ *
+ * Interval precedence (highest wins):
+ *   1. INDEX_INTERVAL_MS environment variable
+ *   2. config.json `indexInterval` (or `indexIntervalMs`)
+ *   3. Product default (5 minutes)
+ *
+ * Values are clamped to [15s, 6h]. Human forms like `30s`, `1m`, `1h` are accepted.
+ */
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+export const APPLE_TOOLS_DIR_NAME = ".apple-tools-mcp";
+export const CONFIG_FILE_NAME = "config.json";
+
+/** MacBook / MCP local-fallback default. */
+export const DEFAULT_INDEX_INTERVAL_MS = 5 * 60 * 1000;
+
+/** Documented floor: 15 seconds (30s remains allowed). */
+export const MIN_INDEX_INTERVAL_MS = 15 * 1000;
+
+/** Documented ceiling: 6 hours. */
+export const MAX_INDEX_INTERVAL_MS = 6 * 60 * 60 * 1000;
+
+/** Recommended Mini always-on value (set in config.json, not the product default). */
+export const MINI_RECOMMENDED_INDEX_INTERVAL_MS = 60 * 1000;
+
+const KNOWN_CONFIG_KEYS = new Set(["indexInterval", "indexIntervalMs"]);
+
+const MAX_DURATION_STRING_LENGTH = 32;
+
+function defaultWarn(message) {
+  console.error(message);
+}
+
+/**
+ * Directory that holds config.json, indexer.lock, and vector-index.
+ * Always under the user home directory — never a path from config contents.
+ *
+ * @param {{ env?: NodeJS.ProcessEnv, homedir?: () => string }} [options]
+ * @returns {string}
+ */
+export function getAppleToolsDir(options = {}) {
+  const env = options.env || process.env;
+  const homedir = options.homedir || (() => os.homedir());
+  const home = env.HOME || homedir();
+  return path.join(home, APPLE_TOOLS_DIR_NAME);
+}
+
+/**
+ * @param {{ env?: NodeJS.ProcessEnv, homedir?: () => string }} [options]
+ * @returns {string}
+ */
+export function getConfigPath(options = {}) {
+  return path.join(getAppleToolsDir(options), CONFIG_FILE_NAME);
+}
+
+/**
+ * Parse a millisecond count or human duration (`500ms`, `30s`, `1m`, `1h`).
+ * @param {unknown} value
+ * @returns {number|null} milliseconds, or null if unparseable
+ */
+export function parseDuration(value) {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      return null;
+    }
+    return value;
+  }
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed.length > MAX_DURATION_STRING_LENGTH) {
+    return null;
+  }
+  if (/^\d+$/.test(trimmed)) {
+    const n = Number(trimmed);
+    if (!Number.isSafeInteger(n)) {
+      return null;
+    }
+    return n;
+  }
+  const match = /^(\d+)(ms|s|m|h)$/i.exec(trimmed);
+  if (!match) {
+    return null;
+  }
+  const n = Number(match[1]);
+  if (!Number.isSafeInteger(n)) {
+    return null;
+  }
+  const unit = match[2].toLowerCase();
+  const multiplier = unit === "ms" ? 1
+    : unit === "s" ? 1000
+    : unit === "m" ? 60 * 1000
+    : 60 * 60 * 1000;
+  const result = n * multiplier;
+  if (!Number.isSafeInteger(result)) {
+    return null;
+  }
+  return result;
+}
+
+/**
+ * Compact human form for logs (`1m`, `30s`, `6h`, or `1500ms`).
+ * @param {number} ms
+ * @returns {string}
+ */
+export function formatIntervalMs(ms) {
+  if (!Number.isFinite(ms)) {
+    return String(ms);
+  }
+  const rounded = Math.round(ms);
+  if (rounded % (60 * 60 * 1000) === 0) {
+    return `${rounded / (60 * 60 * 1000)}h`;
+  }
+  if (rounded % (60 * 1000) === 0) {
+    return `${rounded / (60 * 1000)}m`;
+  }
+  if (rounded % 1000 === 0) {
+    return `${rounded / 1000}s`;
+  }
+  return `${rounded}ms`;
+}
+
+/**
+ * Clamp a parsed millisecond value. Invalid input yields the default (not the min).
+ *
+ * @param {unknown} raw
+ * @param {{ defaultMs?: number, minMs?: number, maxMs?: number }} [bounds]
+ * @returns {{ ms: number, human: string, clamped: boolean, invalid: boolean, requestedMs: number|null }}
+ */
+export function clampIndexInterval(raw, bounds = {}) {
+  const defaultMs = bounds.defaultMs ?? DEFAULT_INDEX_INTERVAL_MS;
+  const minMs = bounds.minMs ?? MIN_INDEX_INTERVAL_MS;
+  const maxMs = bounds.maxMs ?? MAX_INDEX_INTERVAL_MS;
+  const requestedMs = parseDuration(raw);
+
+  if (requestedMs === null) {
+    return {
+      ms: defaultMs,
+      human: formatIntervalMs(defaultMs),
+      clamped: false,
+      invalid: true,
+      requestedMs: null
+    };
+  }
+
+  const clampedMs = Math.min(maxMs, Math.max(minMs, requestedMs));
+  return {
+    ms: clampedMs,
+    human: formatIntervalMs(clampedMs),
+    clamped: clampedMs !== requestedMs,
+    invalid: false,
+    requestedMs
+  };
+}
+
+/**
+ * Load ~/.apple-tools-mcp/config.json. Missing file is fine. Invalid JSON
+ * does not throw — callers get empty data plus a warn log.
+ *
+ * @param {{
+ *   configPath?: string,
+ *   env?: NodeJS.ProcessEnv,
+ *   readFile?: (p: string) => string,
+ *   exists?: (p: string) => boolean,
+ *   warn?: (msg: string) => void
+ * }} [options]
+ * @returns {{ data: Record<string, unknown>, missing: boolean, invalid: boolean, path: string }}
+ */
+export function loadConfigFile(options = {}) {
+  const warn = options.warn || defaultWarn;
+  const configPath = options.configPath || getConfigPath({ env: options.env });
+  const exists = options.exists || ((p) => fs.existsSync(p));
+  const readFile = options.readFile || ((p) => fs.readFileSync(p, "utf8"));
+
+  if (!exists(configPath)) {
+    return { data: {}, missing: true, invalid: false, path: configPath };
+  }
+
+  try {
+    const raw = readFile(configPath);
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      warn("Invalid config.json: expected a JSON object. Using defaults.");
+      return { data: {}, missing: false, invalid: true, path: configPath };
+    }
+    for (const key of Object.keys(parsed)) {
+      if (!KNOWN_CONFIG_KEYS.has(key)) {
+        warn(`Ignoring unknown config key: ${key}`);
+      }
+    }
+    return { data: parsed, missing: false, invalid: false, path: configPath };
+  } catch (err) {
+    const message = err && err.message ? err.message : "parse error";
+    warn(`Invalid config.json (${message}). Using defaults.`);
+    return { data: {}, missing: false, invalid: true, path: configPath };
+  }
+}
+
+function fileIntervalRaw(data) {
+  if (!data || typeof data !== "object") {
+    return undefined;
+  }
+  if (Object.prototype.hasOwnProperty.call(data, "indexInterval")) {
+    return data.indexInterval;
+  }
+  if (Object.prototype.hasOwnProperty.call(data, "indexIntervalMs")) {
+    return data.indexIntervalMs;
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the index refresh interval once at process start.
+ *
+ * @param {{
+ *   env?: NodeJS.ProcessEnv,
+ *   configPath?: string,
+ *   fileData?: Record<string, unknown>,
+ *   warn?: (msg: string) => void
+ * }} [options]
+ * @returns {{
+ *   ms: number,
+ *   human: string,
+ *   source: "env" | "config" | "default",
+ *   clamped: boolean,
+ *   invalid: boolean,
+ *   requestedMs: number|null,
+ *   raw: unknown
+ * }}
+ */
+export function resolveIndexInterval(options = {}) {
+  const env = options.env || process.env;
+  const warn = options.warn || defaultWarn;
+  const envRaw = env.INDEX_INTERVAL_MS;
+  const envSet = envRaw !== undefined && envRaw !== "";
+
+  let source = "default";
+  let raw = DEFAULT_INDEX_INTERVAL_MS;
+
+  if (envSet) {
+    source = "env";
+    raw = envRaw;
+  } else {
+    const data = options.fileData !== undefined
+      ? options.fileData
+      : loadConfigFile({ configPath: options.configPath, env, warn }).data;
+    const fromFile = fileIntervalRaw(data);
+    if (fromFile !== undefined) {
+      source = "config";
+      raw = fromFile;
+    }
+  }
+
+  const clamped = clampIndexInterval(raw);
+  if (clamped.invalid && source !== "default") {
+    warn(`Invalid index interval ${JSON.stringify(raw)} from ${source}; using default ${clamped.human} (${clamped.ms} ms)`);
+  } else if (clamped.clamped) {
+    const fromHuman = formatIntervalMs(clamped.requestedMs);
+    warn(
+      `Index interval ${fromHuman} (${clamped.requestedMs} ms) from ${source} is outside ${formatIntervalMs(MIN_INDEX_INTERVAL_MS)}–${formatIntervalMs(MAX_INDEX_INTERVAL_MS)}; clamped to ${clamped.human} (${clamped.ms} ms)`
+    );
+  }
+
+  return {
+    ms: clamped.ms,
+    human: clamped.human,
+    source: clamped.invalid && source !== "default" ? "default" : source,
+    clamped: clamped.clamped,
+    invalid: clamped.invalid,
+    requestedMs: clamped.requestedMs,
+    raw
+  };
+}
+
+/**
+ * Load config from disk (if present) and resolve the interval.
+ * @param {{ env?: NodeJS.ProcessEnv, configPath?: string, warn?: (msg: string) => void }} [options]
+ */
+export function loadResolvedIndexInterval(options = {}) {
+  const warn = options.warn || defaultWarn;
+  const loaded = loadConfigFile({
+    configPath: options.configPath,
+    env: options.env,
+    warn
+  });
+  return resolveIndexInterval({
+    env: options.env,
+    fileData: loaded.data,
+    warn
+  });
+}
+
+/**
+ * Log the effective interval once. Human form and milliseconds.
+ * @param {{ ms: number, human: string, source: string, clamped: boolean }} resolved
+ * @param {{ log?: (msg: string) => void }} [options]
+ */
+export function logResolvedInterval(resolved, options = {}) {
+  const log = options.log || defaultWarn;
+  const clampedNote = resolved.clamped ? ", clamped" : "";
+  log(`Effective index refresh interval: ${resolved.human} (${resolved.ms} ms) [source=${resolved.source}${clampedNote}]`);
+}

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;
+    }
+  };
+}