@yugabytedb/meko-mcp 1.0.3

package/lib/clients/cursor.mjs

@@ -0,0 +1,332 @@
+import {
+  existsSync,
+  lstatSync,
+  readlinkSync,
+  writeFileSync,
+  mkdirSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+import {
+  getClaudeCompatSettingsPath,
+  getCursorHooksPath,
+  getCursorMcpPath,
+  getCursorSkillsDir,
+  readJsonFile,
+  writeJsonFile,
+} from "../config.mjs";
+import {
+  resolveHooksRoot,
+  resolveSkillSource,
+  removePath,
+  symlinkOrCopy,
+} from "./common.mjs";
+
+const SKILLS = [{ name: "meko-mcp-tools" }];
+
+const HOOKS = [
+  { event: "sessionStart", script: "session-start.sh", timeout: 15000 },
+  { event: "preCompact", script: "pre-compact.sh" },
+  { event: "sessionEnd", script: "session-end.sh", timeout: 30000 },
+];
+
+/**
+ * @returns {object}
+ */
+export function createCursorAdapter(customPaths = {}) {
+  const paths = {
+    getMcpPath: customPaths.getMcpPath ?? getCursorMcpPath,
+    getHooksPath: customPaths.getHooksPath ?? getCursorHooksPath,
+    getSkillsDir: customPaths.getSkillsDir ?? getCursorSkillsDir,
+    getClaudeCompatSettingsPath:
+      customPaths.getClaudeCompatSettingsPath ?? getClaudeCompatSettingsPath,
+  };
+
+  return {
+    id: "cursor",
+    displayName: "Cursor",
+    settingsPath() {
+      return "";
+    },
+    async detectPrerequisites() {
+      // No CLI dependency for Cursor config-mode installs.
+    },
+    detectExisting(name, { scope, projectRoot }) {
+      const path = paths.getMcpPath(scope, projectRoot);
+      const cfg = readJsonFile(path);
+      const found = Boolean(cfg?.mcpServers?.[name]);
+      return { found, status: found ? "Configured" : "" };
+    },
+    removeRegistration(name, { scope, projectRoot }) {
+      const mcpPath = paths.getMcpPath(scope, projectRoot);
+      const cfg = readJsonFile(mcpPath);
+      if (!cfg?.mcpServers?.[name]) return;
+      delete cfg.mcpServers[name];
+      writeJsonFile(mcpPath, cfg);
+    },
+    registerServer({ name, url, apiKey, dryRun, log, scope, projectRoot }) {
+      const mcpPath = paths.getMcpPath(scope, projectRoot);
+      if (dryRun) {
+        log.dim(`  Would update ${mcpPath}:`);
+        log.dim(`    mcpServers.${name}.url = ${url}`);
+        if (apiKey) {
+          log.dim("    mcpServers.<name>.headers.API_KEY = <set>");
+        }
+        return;
+      }
+
+      const cfg = readJsonFile(mcpPath);
+      if (!cfg.mcpServers || typeof cfg.mcpServers !== "object") {
+        cfg.mcpServers = {};
+      }
+      const server = { url };
+      if (apiKey) {
+        server.headers = { API_KEY: apiKey };
+      }
+      cfg.mcpServers[name] = server;
+      writeJsonFile(mcpPath, cfg);
+    },
+    setHookEnvironment({ url, apiKey, dryRun, log, scope, projectRoot, cursorHookMode }) {
+      const mode = cursorHookMode || "hybrid";
+      if (dryRun) {
+        if (mode === "native" || mode === "hybrid") {
+          log.dim(`  Would configure Cursor hooks at ${paths.getHooksPath(scope, projectRoot)}`);
+        }
+        if (mode === "claude-compat" || mode === "hybrid") {
+          log.dim(`  Would configure Claude-compatible hooks at ${paths.getClaudeCompatSettingsPath(scope, projectRoot)}`);
+        }
+        return;
+      }
+
+      if (mode === "native" || mode === "hybrid") {
+        installNativeCursorHooks({ scope, projectRoot, url, apiKey, paths });
+      }
+      if (mode === "claude-compat" || mode === "hybrid") {
+        installClaudeCompatHooks({ scope, projectRoot, url, apiKey, paths });
+      }
+    },
+    installSkills({ dryRun, log, scope, projectRoot }) {
+      const skillDir = paths.getSkillsDir(scope, projectRoot);
+      if (dryRun) {
+        log.dim(`  Would install skills into ${skillDir}`);
+        return { marketplace: "skipped", skills: "dry-run" };
+      }
+
+      mkdirSync(skillDir, { recursive: true });
+      for (const skill of SKILLS) {
+        const source = resolveSkillSource(skill.name);
+        const destination = join(skillDir, skill.name);
+        if (existsSync(destination)) continue;
+        const strategy = symlinkOrCopy(source, destination);
+        if (strategy === "copy") {
+          writeFileSync(join(destination, ".meko-installer"), "managed\n", "utf8");
+        }
+      }
+
+      return { marketplace: "skipped", skills: "ok" };
+    },
+    uninstall({ name, scope, projectRoot, cursorHookMode }) {
+      const results = [];
+      try {
+        this.removeRegistration(name, { scope, projectRoot });
+        results.push({ key: "mcp", ok: true, message: `Cursor MCP server "${name}" removed.` });
+      } catch (err) {
+        results.push({ key: "mcp", ok: false, message: `Could not remove Cursor MCP server: ${err.message}` });
+      }
+
+      try {
+        uninstallCursorHooks({
+          scope,
+          projectRoot,
+          mode: cursorHookMode || "hybrid",
+          paths,
+        });
+        results.push({ key: "hooks", ok: true, message: "Cursor hook configuration cleaned up." });
+      } catch (err) {
+        results.push({ key: "hooks", ok: false, message: `Could not clean Cursor hooks: ${err.message}` });
+      }
+
+      try {
+        uninstallCursorSkills({ scope, projectRoot, paths });
+        results.push({ key: "skills", ok: true, message: "Cursor skills cleaned up." });
+      } catch (err) {
+        results.push({ key: "skills", ok: false, message: `Could not remove Cursor skills: ${err.message}` });
+      }
+
+      return results;
+    },
+    async validateConfig({ serverName, scope, projectRoot }) {
+      const mcpPath = paths.getMcpPath(scope, projectRoot);
+      const cfg = readJsonFile(mcpPath);
+      if (cfg?.mcpServers?.[serverName]) {
+        return { ok: true, message: `Server "${serverName}" is registered in ${mcpPath}.` };
+      }
+      return { ok: false, message: `Server "${serverName}" not found in ${mcpPath}.` };
+    },
+  };
+}
+
+// NOTE: URL and API key are NOT embedded in the command string.
+// They live in the settings file's `env` block (see ensureEnvBlock below) so
+// that changing env values — e.g., switching between local and cloud — takes
+// effect without rewriting every hook entry. Shadowing env assignments in the
+// command prefix (`VAR=... bash "..."`) silently override an inherited env,
+// which is exactly the leak we're avoiding (see MEKO-20).
+function buildScriptCommand({ scriptPath }) {
+  return `bash "${scriptPath}"`;
+}
+
+function ensureEnvBlock(cfg, url, apiKey) {
+  if (!cfg.env || typeof cfg.env !== "object") cfg.env = {};
+  cfg.env.MEKO_MCP_URL = url;
+  if (apiKey) {
+    cfg.env.MEKO_API_KEY = apiKey;
+  } else {
+    delete cfg.env.MEKO_API_KEY;
+  }
+}
+
+function installNativeCursorHooks({ scope, projectRoot, url, apiKey, paths }) {
+  const hooksPath = paths.getHooksPath(scope, projectRoot);
+  const cfg = readJsonFile(hooksPath);
+  if (!cfg.version) cfg.version = 1;
+  if (!cfg.hooks || typeof cfg.hooks !== "object") {
+    cfg.hooks = {};
+  }
+
+  const handlersRoot = resolveHooksRoot();
+  for (const hook of HOOKS) {
+    const scriptPath = join(handlersRoot, hook.script);
+    const entry = { command: buildScriptCommand({ scriptPath }) };
+    if (hook.timeout) entry.timeout = hook.timeout;
+    upsertHookEntry(cfg.hooks, hook.event, entry);
+  }
+
+  ensureEnvBlock(cfg, url, apiKey);
+  writeJsonFile(hooksPath, cfg);
+}
+
+function installClaudeCompatHooks({ scope, projectRoot, url, apiKey, paths }) {
+  const settingsPath = paths.getClaudeCompatSettingsPath(scope, projectRoot);
+  const cfg = readJsonFile(settingsPath);
+  if (!cfg.hooks || typeof cfg.hooks !== "object") {
+    cfg.hooks = {};
+  }
+
+  const handlersRoot = resolveHooksRoot();
+  const compatMap = {
+    SessionStart: { script: "session-start.sh", timeout: 15000 },
+    PreCompact: { script: "pre-compact.sh" },
+    SessionEnd: { script: "session-end.sh", timeout: 30000 },
+  };
+
+  for (const [event, data] of Object.entries(compatMap)) {
+    const scriptPath = join(handlersRoot, data.script);
+    const entry = {
+      type: "command",
+      command: buildScriptCommand({ scriptPath }),
+    };
+    if (data.timeout) entry.timeout = data.timeout;
+    upsertClaudeCompatHook(cfg.hooks, event, entry);
+  }
+
+  // On scope=user this file is shared with Claude Code (getClaudeCompatSettingsPath
+  // returns ~/.claude/settings.json), so writing the env block here also feeds the
+  // Claude Code adapter. See MEKO-20 for the leak this closes.
+  ensureEnvBlock(cfg, url, apiKey);
+  writeJsonFile(settingsPath, cfg);
+}
+
+function upsertHookEntry(hooksObj, event, entry) {
+  if (!Array.isArray(hooksObj[event])) hooksObj[event] = [];
+  const exists = hooksObj[event].some((item) => item.command === entry.command);
+  if (!exists) hooksObj[event].push(entry);
+}
+
+function upsertClaudeCompatHook(hooksObj, event, entry) {
+  if (!Array.isArray(hooksObj[event])) hooksObj[event] = [];
+  let bucket = hooksObj[event].find((item) => Array.isArray(item.hooks));
+  if (!bucket) {
+    bucket = { hooks: [] };
+    hooksObj[event].push(bucket);
+  }
+  const exists = bucket.hooks.some((hook) => hook.command === entry.command);
+  if (!exists) bucket.hooks.push(entry);
+}
+
+function uninstallCursorHooks({ scope, projectRoot, mode, paths }) {
+  const handlersRoot = resolveHooksRoot();
+  const scripts = ["session-start.sh", "pre-compact.sh", "session-end.sh"]
+    .map((name) => join(handlersRoot, name));
+
+  if (mode === "native" || mode === "hybrid") {
+    const hooksPath = paths.getHooksPath(scope, projectRoot);
+    const cfg = readJsonFile(hooksPath);
+    if (cfg?.hooks && typeof cfg.hooks === "object") {
+      for (const event of Object.keys(cfg.hooks)) {
+        if (!Array.isArray(cfg.hooks[event])) continue;
+        cfg.hooks[event] = cfg.hooks[event].filter((item) => {
+          if (!item?.command) return true;
+          return !scripts.some((script) => item.command.includes(script));
+        });
+      }
+      writeJsonFile(hooksPath, cfg);
+    }
+  }
+
+  if (mode === "claude-compat" || mode === "hybrid") {
+    // NOTE: we deliberately do NOT strip env.MEKO_MCP_URL / env.MEKO_API_KEY here.
+    // On scope=user, this file is the same ~/.claude/settings.json the Claude Code
+    // adapter owns; the Claude Code uninstall (claude-code.mjs removeKeys call) is
+    // responsible for env cleanup. Stripping here would break a still-active
+    // Claude Code install. See MEKO-20.
+    const settingsPath = paths.getClaudeCompatSettingsPath(scope, projectRoot);
+    const cfg = readJsonFile(settingsPath);
+    if (cfg?.hooks && typeof cfg.hooks === "object") {
+      for (const event of Object.keys(cfg.hooks)) {
+        const arr = cfg.hooks[event];
+        if (!Array.isArray(arr)) continue;
+        cfg.hooks[event] = arr.map((group) => {
+          if (!Array.isArray(group?.hooks)) return group;
+          const filtered = group.hooks.filter((item) => {
+            if (!item?.command) return true;
+            return !scripts.some((script) => item.command.includes(script));
+          });
+          return { ...group, hooks: filtered };
+        }).filter((group) => {
+          if (!Array.isArray(group?.hooks)) return true;
+          return group.hooks.length > 0;
+        });
+      }
+      writeJsonFile(settingsPath, cfg);
+    }
+  }
+}
+
+function uninstallCursorSkills({ scope, projectRoot, paths }) {
+  const skillsDir = paths.getSkillsDir(scope, projectRoot);
+
+  for (const skill of SKILLS) {
+    const dest = join(skillsDir, skill.name);
+    if (!existsSync(dest)) continue;
+
+    const managedCopyMarker = join(dest, ".meko-installer");
+    if (existsSync(managedCopyMarker)) {
+      removePath(dest);
+      continue;
+    }
+
+    try {
+      const stat = lstatSync(dest);
+      if (!stat.isSymbolicLink()) continue;
+      const linkTarget = readlinkSync(dest);
+      const resolvedTarget = resolve(dirname(dest), linkTarget);
+      const expectedTarget = resolveSkillSource(skill.name);
+      if (resolvedTarget === expectedTarget) {
+        removePath(dest);
+      }
+    } catch {
+      // no-op
+    }
+  }
+}

package/lib/clients/index.mjs

@@ -0,0 +1,14 @@
+import { createClaudeCodeAdapter } from "./claude-code.mjs";
+import { createClaudeDesktopAdapter } from "./claude-desktop.mjs";
+import { createCursorAdapter } from "./cursor.mjs";
+
+/**
+ * @returns {Record<string, object>}
+ */
+export function getClientAdapters() {
+  return {
+    "claude-code": createClaudeCodeAdapter(),
+    "claude-desktop": createClaudeDesktopAdapter(),
+    cursor: createCursorAdapter(),
+  };
+}

package/lib/config.mjs

@@ -0,0 +1,369 @@
+/**
+ * config.mjs - Safe JSON file manipulation for installer-managed config.
+ *
+ * Provides generic JSON utilities plus client-specific path helpers used by
+ * Claude Code, Claude Desktop, and Cursor install flows.
+ *
+ * Zero external dependencies - Node.js built-ins only.
+ */
+
+import { readFileSync, writeFileSync, copyFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+
+/** @returns {string} Absolute path to ~/.claude/settings.json */
+export function getClaudeCodeSettingsPath() {
+  return join(homedir(), ".claude", "settings.json");
+}
+
+/**
+ * Compatibility alias used by existing Claude Code paths.
+ * @returns {string}
+ */
+export function getSettingsPath() {
+  return getClaudeCodeSettingsPath();
+}
+
+/**
+ * Return the canonical user-level Claude Desktop config path for this OS.
+ * @returns {string}
+ */
+export function getClaudeDesktopConfigPath() {
+  const home = homedir();
+  switch (process.platform) {
+    case "darwin":
+      return join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    case "win32":
+      return join(home, "AppData", "Roaming", "Claude", "claude_desktop_config.json");
+    default:
+      return join(home, ".config", "Claude", "claude_desktop_config.json");
+  }
+}
+
+/**
+ * Return path to Cursor's MCP config file.
+ * @param {"user"|"project"} scope
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+export function getCursorMcpPath(scope, projectRoot) {
+  if (scope === "project") {
+    return join(projectRoot, ".cursor", "mcp.json");
+  }
+  return join(homedir(), ".cursor", "mcp.json");
+}
+
+/**
+ * Return path to Cursor hooks config file.
+ * @param {"user"|"project"} scope
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+export function getCursorHooksPath(scope, projectRoot) {
+  if (scope === "project") {
+    return join(projectRoot, ".cursor", "hooks.json");
+  }
+  return join(homedir(), ".cursor", "hooks.json");
+}
+
+/**
+ * Return path to Cursor skills directory.
+ * @param {"user"|"project"} scope
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+export function getCursorSkillsDir(scope, projectRoot) {
+  if (scope === "project") {
+    return join(projectRoot, ".cursor", "skills");
+  }
+  return join(homedir(), ".cursor", "skills");
+}
+
+/**
+ * Return path for Claude compatibility settings file.
+ * @param {"user"|"project"} scope
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+export function getClaudeCompatSettingsPath(scope, projectRoot) {
+  if (scope === "project") {
+    return join(projectRoot, ".claude", "settings.json");
+  }
+  return getClaudeCodeSettingsPath();
+}
+
+// ---------------------------------------------------------------------------
+// Read / Write primitives
+// ---------------------------------------------------------------------------
+
+/**
+ * Read and parse a JSON file.
+ *
+ * - Returns `{}` when the file does not exist.
+ * - Returns `{}` when the file exists but is empty (0 bytes or whitespace).
+ * - Throws a descriptive error when the file contains invalid JSON.
+ *
+ * @param {string} filePath - Absolute path to the JSON file.
+ * @returns {Record<string, unknown>} Parsed contents, or empty object.
+ */
+export function readJsonFile(filePath) {
+  let raw;
+  try {
+    raw = readFileSync(filePath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return {};
+    }
+    throw err;
+  }
+
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(trimmed);
+  } catch (parseErr) {
+    throw new Error(
+      `Invalid JSON in ${filePath}: ${parseErr.message}.\n` +
+        "Fix the file manually or delete it and re-run the installer.",
+    );
+  }
+}
+
+/**
+ * Write a JavaScript value as pretty-printed JSON to a file.
+ *
+ * Creates parent directories if they do not exist.
+ * Output uses 2-space indentation and a trailing newline.
+ *
+ * @param {string} filePath - Absolute path to write.
+ * @param {unknown} data - Value to serialize.
+ */
+export function writeJsonFile(filePath, data) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+// ---------------------------------------------------------------------------
+// Deep merge helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively merge `source` into `target`, returning a new object.
+ *
+ * Rules:
+ *  - Plain objects are merged key-by-key (additive).
+ *  - Everything else (arrays, scalars, null) in `source` overwrites `target`.
+ *
+ * @param {Record<string, unknown>} target
+ * @param {Record<string, unknown>} source
+ * @returns {Record<string, unknown>} Merged result (new object, inputs unchanged).
+ */
+function deepMerge(target, source) {
+  const result = { ...target };
+
+  for (const key of Object.keys(source)) {
+    const srcVal = source[key];
+    const tgtVal = result[key];
+
+    if (isPlainObject(srcVal) && isPlainObject(tgtVal)) {
+      result[key] = deepMerge(tgtVal, srcVal);
+    } else {
+      result[key] = srcVal;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * @param {unknown} val
+ * @returns {boolean} True when val is a non-null, non-array plain object.
+ */
+function isPlainObject(val) {
+  return val !== null && typeof val === "object" && !Array.isArray(val);
+}
+
+// ---------------------------------------------------------------------------
+// High-level operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Deep-merge a patch into an existing JSON file.
+ *
+ * - Reads current contents (or `{}` if missing).
+ * - Creates a `.bak` backup of the original file before writing.
+ * - Performs an additive deep merge: existing keys are preserved unless
+ *   explicitly overridden in `patch`.
+ *
+ * @param {string} filePath - Absolute path to the JSON file.
+ * @param {Record<string, unknown>} patch - Object to merge in.
+ * @returns {Record<string, unknown>} The merged result that was written.
+ */
+export function mergeSettings(filePath, patch) {
+  const existing = readJsonFile(filePath);
+
+  // Back up the original file (only if it physically exists on disk).
+  try {
+    copyFileSync(filePath, filePath + ".bak");
+  } catch (err) {
+    // File does not exist yet - nothing to back up.
+    if (err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+
+  const merged = deepMerge(existing, patch);
+  writeJsonFile(filePath, merged);
+  return merged;
+}
+
+/**
+ * Union a list of string entries into an array at a dot-separated key path.
+ *
+ * Use this when the patch is a list (e.g. `permissions.allow`) that must be
+ * merged additively rather than overwritten — plain `mergeSettings` replaces
+ * arrays wholesale, which would clobber user-added entries.
+ *
+ * - Creates intermediate objects if they don't exist.
+ * - Preserves existing entries; deduplicates by exact string match.
+ * - Creates a `.bak` backup before writing.
+ *
+ * @param {string} filePath - Absolute path to the JSON file.
+ * @param {string} keyPath - Dot-separated path to the array (e.g. "permissions.allow").
+ * @param {string[]} entries - Entries to union into the array.
+ * @returns {Record<string, unknown>} The data after the union.
+ */
+export function mergeAllowList(filePath, keyPath, entries) {
+  const data = readJsonFile(filePath);
+
+  try {
+    copyFileSync(filePath, filePath + ".bak");
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+
+  const segments = keyPath.split(".");
+  const leaf = segments.pop();
+  let cursor = data;
+  for (const seg of segments) {
+    if (!isPlainObject(cursor[seg])) {
+      cursor[seg] = {};
+    }
+    cursor = cursor[seg];
+  }
+
+  if (!Array.isArray(cursor[leaf])) {
+    cursor[leaf] = [];
+  }
+
+  const existing = new Set(cursor[leaf]);
+  for (const entry of entries) {
+    if (!existing.has(entry)) {
+      cursor[leaf].push(entry);
+      existing.add(entry);
+    }
+  }
+
+  writeJsonFile(filePath, data);
+  return data;
+}
+
+/**
+ * Remove specific entries from an array at a dot-separated key path.
+ *
+ * Inverse of `mergeAllowList` — used to clean up installer-managed entries
+ * on uninstall without touching user-added ones.
+ *
+ * @param {string} filePath
+ * @param {string} keyPath
+ * @param {string[]} entries
+ * @returns {Record<string, unknown>}
+ */
+export function removeFromAllowList(filePath, keyPath, entries) {
+  const data = readJsonFile(filePath);
+
+  try {
+    copyFileSync(filePath, filePath + ".bak");
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+
+  const segments = keyPath.split(".");
+  const leaf = segments.pop();
+  let cursor = data;
+  for (const seg of segments) {
+    if (!isPlainObject(cursor) || !isPlainObject(cursor[seg])) {
+      return data;
+    }
+    cursor = cursor[seg];
+  }
+
+  if (!Array.isArray(cursor[leaf])) {
+    return data;
+  }
+
+  const toRemove = new Set(entries);
+  cursor[leaf] = cursor[leaf].filter((entry) => !toRemove.has(entry));
+
+  writeJsonFile(filePath, data);
+  return data;
+}
+
+/**
+ * Remove specific nested keys from a JSON file.
+ *
+ * Keys are specified as dot-separated paths (e.g. `"env.MEKO_MCP_URL"`).
+ * Missing intermediate segments are silently skipped.
+ * Creates a `.bak` backup before writing.
+ *
+ * @param {string} filePath - Absolute path to the JSON file.
+ * @param {string[]} keyPaths - Dot-separated key paths to remove.
+ * @returns {Record<string, unknown>} The data after removals.
+ */
+export function removeKeys(filePath, keyPaths) {
+  const data = readJsonFile(filePath);
+
+  // Back up original.
+  try {
+    copyFileSync(filePath, filePath + ".bak");
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+
+  for (const keyPath of keyPaths) {
+    const segments = keyPath.split(".");
+    const leaf = segments.pop();
+    let cursor = data;
+
+    // Walk to the parent of the target key.
+    let reachable = true;
+    for (const seg of segments) {
+      if (isPlainObject(cursor) && Object.prototype.hasOwnProperty.call(cursor, seg)) {
+        cursor = cursor[seg];
+      } else {
+        reachable = false;
+        break;
+      }
+    }
+
+    if (reachable && isPlainObject(cursor)) {
+      delete cursor[leaf];
+    }
+  }
+
+  writeJsonFile(filePath, data);
+  return data;
+}