@yugabytedb/meko-mcp 1.0.8 → 1.1.0

package/lib/clients/codex.mjs

@@ -0,0 +1,977 @@
+/**
+ * codex.mjs - OpenAI Codex (CLI + Desktop App) adapter for the Meko MCP installer.
+ *
+ * The CLI and the Desktop App share the same on-disk state — `~/.codex/config.toml`,
+ * `~/.codex/AGENTS.md`, `~/.agents/skills/` — so a single adapter handles both
+ * surfaces. We prefer `codex mcp add` when the CLI is available (forward-compatible
+ * with future schema fields) and fall back to direct TOML editing when only the
+ * App is installed.
+ */
+
+import { execSync } from "node:child_process";
+import {
+  appendFileSync,
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+import { askYesNo } from "../prompt.mjs";
+import {
+  getCodexAgentsMdPath,
+  getCodexConfigPath,
+  getCodexSkillsRoot,
+} from "../config.mjs";
+import {
+  getInstallerVersion,
+  markerIsStale,
+  readInstallerMarker,
+  removePath,
+  resolveSkillSource,
+  shellQuote,
+  symlinkOrCopy,
+  writeInstallerMarker,
+} from "./common.mjs";
+
+const CODEX_INSTALL_URL = "https://github.com/openai/codex";
+const CODEX_APP_INSTALL_URL = "https://openai.com/index/codex";
+
+// AGENTS.md sentinel markers. Idempotent upsert/strip relies on these being
+// stable across versions — never rename without a migration story.
+const AGENTS_MD_START = "<!-- meko:start -->";
+const AGENTS_MD_END = "<!-- meko:end -->";
+
+// Shell rc fence used by maybeOfferRcAppend. Mirrors well-known conventions
+// (homebrew, asdf, etc.) so a user grepping their rc can see at a glance
+// which tool added the block.
+const RC_FENCE_START = "# >>> meko mcp >>>";
+const RC_FENCE_END = "# <<< meko mcp <<<";
+
+const SKILLS = [{ name: "meko-mcp-tools" }];
+
+/**
+ * @param {{
+ *   getConfigPath?: () => string,
+ *   getAgentsMdPath?: () => string,
+ *   getSkillsRoot?: () => string,
+ *   runCommand?: (cmd: string) => string,
+ *   probeCodex?: () => {found: boolean, version: string, path: string},
+ *   probeCodexApp?: () => {found: boolean, path: string, platform: string, version: string} | null,
+ *   detectShellRc?: () => string | null,
+ *   promptUser?: (question: string, defaultYes?: boolean) => Promise<boolean>,
+ * }} [options]
+ * @returns {object}
+ */
+export function createCodexAdapter(options = {}) {
+  const resolveConfigPath = options.getConfigPath ?? getCodexConfigPath;
+  const resolveAgentsMdPath = options.getAgentsMdPath ?? getCodexAgentsMdPath;
+  const resolveSkillsRoot = options.getSkillsRoot ?? getCodexSkillsRoot;
+  const runCommand = options.runCommand ?? defaultRunCommand;
+  const probeCodex = options.probeCodex ?? defaultProbeCodex;
+  const probeCodexApp = options.probeCodexApp ?? defaultProbeCodexApp;
+  const detectShellRc = options.detectShellRc ?? defaultDetectShellRc;
+  const promptUser = options.promptUser ?? askYesNo;
+
+  /** @type {{cli: object|null, app: object|null}} */
+  const surfaces = { cli: null, app: null };
+
+  let scopeWarned = false;
+
+  /** Returns the resolved config.toml path; warns once on project scope. */
+  function settingsPathFor(scope, log) {
+    if (scope === "project" && !scopeWarned) {
+      scopeWarned = true;
+      log?.warn?.(
+        "Codex has no project-scope config; installing into the user-level ~/.codex/config.toml.",
+      );
+    }
+    return resolveConfigPath();
+  }
+
+  return {
+    id: "codex",
+    displayName: "OpenAI Codex (CLI + App)",
+    settingsPath() {
+      // The scope arg is intentionally ignored: Codex has no project scope.
+      // The first call site with a logger (registerServer / installSkills)
+      // emits the degrade warning.
+      return resolveConfigPath();
+    },
+    async detectPrerequisites({ verbose, log } = { verbose: false, log: console }) {
+      const cli = probeCodex();
+      const app = probeCodexApp();
+      surfaces.cli = cli?.found ? cli : null;
+      surfaces.app = app?.found ? app : null;
+      if (!surfaces.cli && !surfaces.app) {
+        throw new Error(
+          `OpenAI Codex not found. Install the CLI (${CODEX_INSTALL_URL}) ` +
+            `or the desktop app (${CODEX_APP_INSTALL_URL}).`,
+        );
+      }
+      if (verbose) {
+        if (surfaces.cli) {
+          log.dim?.(`  Codex CLI: ${surfaces.cli.path} (${surfaces.cli.version})`);
+        }
+        if (surfaces.app) {
+          log.dim?.(
+            `  Codex App: ${surfaces.app.path} (${surfaces.app.platform}${
+              surfaces.app.version ? `, ${surfaces.app.version}` : ""
+            })`,
+          );
+        }
+      }
+    },
+    isInstalled() {
+      // Cheap check used by the picker — full prereq probing happens in
+      // detectPrerequisites. We re-probe here because the picker runs before
+      // detectPrerequisites and we want it to reflect reality.
+      const cli = probeCodex();
+      const app = probeCodexApp();
+      return Boolean((cli && cli.found) || (app && app.found));
+    },
+    detectExisting(name, { scope } = {}) {
+      // Force a probe if we haven't yet — picker may not have called
+      // detectPrerequisites.
+      if (surfaces.cli === null && surfaces.app === null) {
+        const cli = probeCodex();
+        const app = probeCodexApp();
+        surfaces.cli = cli?.found ? cli : null;
+        surfaces.app = app?.found ? app : null;
+      }
+
+      if (surfaces.cli) {
+        try {
+          runCommand(`codex mcp get ${shellQuote(name)}`);
+          return { found: true, status: "Configured" };
+        } catch {
+          // fall through to TOML grep — `codex mcp get` exits non-zero when
+          // the entry isn't present, but might also fail for unrelated
+          // reasons (very old CLI, syntax error in config.toml). The TOML
+          // grep is authoritative.
+        }
+      }
+      const path = settingsPathFor(scope, null);
+      const raw = safeReadFile(path);
+      if (raw === null) return { found: false, status: "" };
+      return parseCodexConfigForServer(raw, name).found
+        ? { found: true, status: "Configured" }
+        : { found: false, status: "" };
+    },
+    removeRegistration(name, { scope, log } = {}) {
+      const path = settingsPathFor(scope, log);
+      if (surfaces.cli) {
+        try {
+          runCommand(`codex mcp remove ${shellQuote(name)}`);
+          return;
+        } catch {
+          // CLI doesn't know `mcp remove`, or the entry wasn't present.
+          // Fall through to direct TOML edit — idempotent on a missing
+          // block.
+        }
+      }
+      const raw = safeReadFile(path);
+      if (raw === null) return;
+      const next = removeCodexConfigBlock(raw, name);
+      if (next !== raw) writeWithBackup(path, next);
+    },
+    async registerServer({ name, url, apiKey, dryRun, verbose, log, scope, yes }) {
+      const path = settingsPathFor(scope, log);
+      const useApiKey = apiKey ? "MEKO_API_KEY" : null;
+      const cliCmd = buildCliRegisterCommand(name, url, useApiKey);
+
+      if (dryRun) {
+        if (surfaces.cli) {
+          log.dim?.(`  Would run: ${cliCmd}`);
+        } else {
+          log.dim?.(`  Would upsert [mcp_servers.${name}] in ${path}`);
+        }
+        if (apiKey) {
+          log.dim?.(
+            "  Codex resolves the bearer token from $MEKO_API_KEY at runtime; the key is not written to config.toml.",
+          );
+        }
+        return;
+      }
+
+      let usedCliPath = false;
+      if (surfaces.cli) {
+        try {
+          const output = runCommand(cliCmd);
+          if (verbose && output) log.dim?.(`  ${output.trim()}`);
+          usedCliPath = true;
+        } catch (err) {
+          const msg = (err && (err.stderr || err.message)) || "";
+          const lower = msg.toLowerCase();
+          // Old CLI (no `mcp add` subcommand) — fall through to TOML write.
+          if (
+            lower.includes("unknown command") ||
+            lower.includes("unrecognized") ||
+            lower.includes("invalid command")
+          ) {
+            log.warn?.(
+              "  codex mcp add not supported by this CLI version — writing config.toml directly.",
+            );
+          } else {
+            throw err;
+          }
+        }
+      }
+
+      if (!usedCliPath) {
+        const raw = safeReadFile(path) ?? "";
+        const next = upsertCodexConfigBlock(raw, name, {
+          url,
+          bearer_token_env_var: useApiKey,
+        });
+        writeWithBackup(path, next);
+        if (verbose) log.dim?.(`  Wrote [mcp_servers.${name}] to ${path}`);
+      }
+
+      // Cloud auth UX: env-var-only model. The key is never written to
+      // config.toml; the user's runtime env supplies it. Print actionable
+      // instructions and (when interactive) offer to wire things up.
+      if (apiKey) {
+        const platform = surfaces.app?.platform ?? process.platform;
+        const hasApp = Boolean(surfaces.app);
+        const shellRc = detectShellRc();
+        printCloudAuthInstructions({ shellRc, hasApp, platform, log });
+        if (!yes) {
+          await maybeOfferRcAppend({
+            apiKey,
+            shellRc,
+            promptUser,
+            log,
+          });
+          if (hasApp && platform === "darwin") {
+            await maybeOfferLaunchctlSetenv({
+              apiKey,
+              promptUser,
+              runCommand,
+              log,
+            });
+          }
+        }
+      }
+
+      if (surfaces.app) {
+        log.dim?.("  Restart Codex.app to attach the new MCP server.");
+      }
+    },
+    async maybeConfirmOverwrite({ existingFound, name, yes }) {
+      if (!existingFound) return true;
+      if (yes) return true;
+      return promptUser(`${name} MCP is already configured. Overwrite?`, false);
+    },
+    setHookEnvironment({ log, dryRun }) {
+      if (!dryRun) {
+        log?.dim?.(
+          "  Codex does not expose user-installable session hooks; auto-capture is unavailable.",
+        );
+      }
+    },
+    installSkills({ dryRun, log, scope, name }) {
+      void scope; // Codex skills are user-scope only.
+      const serverName = name ?? "meko";
+      const skillsRoot = resolveSkillsRoot();
+      const agentsMdPath = resolveAgentsMdPath();
+      const currentVersion = getInstallerVersion();
+
+      if (dryRun) {
+        log.dim?.(`  Would install skills into ${skillsRoot}`);
+        log.dim?.(`  Would upsert Meko block in ${agentsMdPath}`);
+        return { marketplace: "skipped", skills: "dry-run" };
+      }
+
+      mkdirSync(skillsRoot, { recursive: true });
+      for (const skill of SKILLS) {
+        const source = resolveSkillSource(skill.name);
+        const destination = join(skillsRoot, skill.name);
+
+        if (existsSync(destination)) {
+          // A symlink we own already points at the latest source — nothing
+          // to refresh. Mirrors the cursor adapter's isOwnSymlink branch.
+          if (isOwnSymlink(destination, source)) continue;
+
+          const marker = readInstallerMarker(destination);
+          if (!marker) {
+            log.dim?.(
+              `  Skipping ${destination}: no .meko-installer marker (user-managed).`,
+            );
+            continue;
+          }
+          if (markerIsStale(destination, currentVersion)) {
+            const from = marker.version ?? "pre-1.0.9";
+            log.dim?.(
+              `  Upgrading codex skill from ${from} -> ${currentVersion}`,
+            );
+            removePath(destination);
+          } else {
+            continue;
+          }
+        }
+
+        const strategy = symlinkOrCopy(source, destination);
+        if (strategy === "copy") writeInstallerMarker(destination);
+      }
+
+      upsertAgentsMdBlock(agentsMdPath, currentVersion, { name: serverName });
+
+      if (surfaces.app) {
+        log.dim?.("  Restart Codex.app to pick up the new skill / AGENTS.md.");
+      }
+
+      return { marketplace: "skipped", skills: "ok" };
+    },
+    uninstall({ name, scope, log = console }) {
+      const results = [];
+      try {
+        this.removeRegistration(name, { scope, log });
+        results.push({
+          key: "mcp",
+          ok: true,
+          message: `Codex MCP server "${name}" removed.`,
+        });
+      } catch (err) {
+        results.push({
+          key: "mcp",
+          ok: false,
+          message: `Could not remove Codex MCP server: ${err.message}`,
+        });
+      }
+
+      try {
+        const skillsRoot = resolveSkillsRoot();
+        for (const skill of SKILLS) {
+          const dest = join(skillsRoot, skill.name);
+          if (!existsSync(dest)) continue;
+          // Remove the dest if it's either a marker-stamped copy (we own it)
+          // or a symlink pointing at our shipped source (also us).
+          const markerPath = join(dest, ".meko-installer");
+          if (existsSync(markerPath)) {
+            removePath(dest);
+            continue;
+          }
+          const expectedSource = resolveSkillSource(skill.name);
+          if (isOwnSymlink(dest, expectedSource)) removePath(dest);
+        }
+        results.push({
+          key: "skills",
+          ok: true,
+          message: "Codex skills cleaned up.",
+        });
+      } catch (err) {
+        results.push({
+          key: "skills",
+          ok: false,
+          message: `Could not remove Codex skills: ${err.message}`,
+        });
+      }
+
+      try {
+        const agentsMdPath = resolveAgentsMdPath();
+        const raw = safeReadFile(agentsMdPath);
+        if (raw !== null) {
+          const next = removeAgentsMdBlock(raw);
+          if (next !== raw) writeWithBackup(agentsMdPath, next);
+        }
+        results.push({
+          key: "agents-md",
+          ok: true,
+          message: "Meko block stripped from AGENTS.md.",
+        });
+      } catch (err) {
+        results.push({
+          key: "agents-md",
+          ok: false,
+          message: `Could not update AGENTS.md: ${err.message}`,
+        });
+      }
+
+      if (surfaces.app) {
+        log.dim?.("  Restart Codex.app to apply the removal.");
+      }
+
+      return results;
+    },
+    async validateConfig({ serverName, scope, url }) {
+      const path = settingsPathFor(scope, null);
+      if (surfaces.cli) {
+        try {
+          runCommand(`codex mcp get ${shellQuote(serverName)}`);
+          return {
+            ok: true,
+            message: `Server "${serverName}" registered (codex mcp get succeeded).`,
+          };
+        } catch {
+          // fall through to TOML inspection
+        }
+      }
+      const raw = safeReadFile(path);
+      if (raw === null) {
+        return { ok: false, message: `Codex config not found at ${path}.` };
+      }
+      const parsed = parseCodexConfigForServer(raw, serverName);
+      if (!parsed.found) {
+        return {
+          ok: false,
+          message: `Server "${serverName}" not found in ${path}.`,
+        };
+      }
+      if (url && parsed.url && parsed.url !== url) {
+        return {
+          ok: false,
+          message: `Server "${serverName}" in ${path} points at ${parsed.url}, expected ${url}.`,
+        };
+      }
+      return { ok: true, message: `Server "${serverName}" is registered in ${path}.` };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Probes (default impls; tests inject stubs)
+// ---------------------------------------------------------------------------
+
+function defaultRunCommand(cmd) {
+  return execSync(cmd, { encoding: "utf8", stdio: "pipe" }).toString();
+}
+
+function defaultProbeCodex() {
+  const result = { found: false, version: "", path: "" };
+  let path = "";
+  try {
+    path = execSync("which codex", { encoding: "utf8", stdio: "pipe" }).trim();
+  } catch {
+    return result;
+  }
+  if (!path) return result;
+  result.path = path;
+  try {
+    result.version = execSync("codex --version", {
+      encoding: "utf8",
+      stdio: "pipe",
+      timeout: 10_000,
+    }).trim();
+  } catch {
+    return result;
+  }
+  result.found = true;
+  return result;
+}
+
+function defaultProbeCodexApp() {
+  const home = homedir();
+  if (process.platform === "darwin") {
+    for (const candidate of [
+      "/Applications/Codex.app",
+      join(home, "Applications", "Codex.app"),
+    ]) {
+      if (existsSync(candidate)) {
+        return {
+          found: true,
+          path: candidate,
+          platform: "darwin",
+          version: readMacAppVersion(candidate) ?? "",
+        };
+      }
+    }
+    return null;
+  }
+  if (process.platform === "linux") {
+    // Best-effort. Codex Linux distribution shape is fluid; check the most
+    // common landing spots and return null otherwise.
+    const linuxCandidates = [
+      join(home, ".local", "share", "applications", "codex.desktop"),
+      "/usr/share/applications/codex.desktop",
+    ];
+    for (const candidate of linuxCandidates) {
+      if (existsSync(candidate)) {
+        return { found: true, path: candidate, platform: "linux", version: "" };
+      }
+    }
+    return null;
+  }
+  // Windows desktop app detection is out of scope for v1.
+  return null;
+}
+
+function readMacAppVersion(appPath) {
+  const plist = join(appPath, "Contents", "Info.plist");
+  let raw;
+  try {
+    raw = readFileSync(plist, "utf8");
+  } catch {
+    return null;
+  }
+  const m = raw.match(
+    /<key>CFBundleShortVersionString<\/key>\s*<string>([^<]+)<\/string>/,
+  );
+  return m ? m[1] : null;
+}
+
+function defaultDetectShellRc() {
+  const shell = process.env.SHELL || "";
+  const home = homedir();
+  if (shell.endsWith("/zsh")) return join(home, ".zshrc");
+  if (shell.endsWith("/bash")) {
+    // macOS: bash users typically edit ~/.bash_profile (login shell);
+    // Linux: ~/.bashrc.
+    return process.platform === "darwin"
+      ? join(home, ".bash_profile")
+      : join(home, ".bashrc");
+  }
+  if (shell.endsWith("/fish")) {
+    return join(home, ".config", "fish", "config.fish");
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// CLI command builders
+// ---------------------------------------------------------------------------
+
+function buildCliRegisterCommand(name, url, bearerEnv) {
+  let cmd = `codex mcp add ${shellQuote(name)} --url ${shellQuote(url)}`;
+  if (bearerEnv) {
+    cmd += ` --bearer-token-env-var ${shellQuote(bearerEnv)}`;
+  }
+  return cmd;
+}
+
+// ---------------------------------------------------------------------------
+// TOML helpers (App-only fallback path)
+// ---------------------------------------------------------------------------
+
+/**
+ * Locate `[mcp_servers.<name>]` and return its raw block text.
+ * Read-only — no parsing into a structured object.
+ *
+ * @param {string} raw
+ * @param {string} name
+ * @returns {{found: boolean, start?: number, end?: number, url?: string}}
+ */
+export function parseCodexConfigForServer(raw, name) {
+  const header = `[mcp_servers.${name}]`;
+  const headerIdx = findHeader(raw, header);
+  if (headerIdx === -1) return { found: false };
+  const blockEnd = findNextHeader(raw, headerIdx + header.length);
+  const block = raw.slice(headerIdx, blockEnd);
+  const urlMatch = block.match(/^\s*url\s*=\s*"([^"]*)"/m);
+  return {
+    found: true,
+    start: headerIdx,
+    end: blockEnd,
+    url: urlMatch ? urlMatch[1] : undefined,
+  };
+}
+
+/**
+ * Insert or replace `[mcp_servers.<name>]` block. `fields` keys must be
+ * string-valued (we don't need numbers / arrays / inline tables for the
+ * MCP fields we write). Pass `null`/`undefined` to omit a field.
+ *
+ * Emission contract:
+ *   - The rendered block always ends with a single "\n" so the last
+ *     field line is terminated.
+ *   - When something follows the block in the existing TOML (another
+ *     table header at `existing.end`), we add one additional "\n" so
+ *     there is exactly one blank line separating the two tables —
+ *     matching canonical `taplo` / `dprint-toml` formatting.
+ *   - When the block is the last thing in the file we emit just the
+ *     terminator "\n" — no trailing blank line.
+ *
+ * Without these terminators the replacement path glued the next
+ * top-level header onto the last field, e.g.
+ *   bearer_token_env_var = "MEKO_API_KEY"[final]
+ * which is invalid TOML.
+ *
+ * @param {string} raw
+ * @param {string} name
+ * @param {Record<string, string|null|undefined>} fields
+ * @returns {string}
+ */
+export function upsertCodexConfigBlock(raw, name, fields) {
+  const blockBody = renderBlock(name, fields);
+  const existing = parseCodexConfigForServer(raw, name);
+
+  if (!existing.found) {
+    // Fresh insert appended to the end of file.
+    if (raw.length === 0) return blockBody + "\n";
+    const sep = raw.endsWith("\n") ? "\n" : "\n\n";
+    return raw + sep + blockBody + "\n";
+  }
+
+  // In-place replacement. parseCodexConfigForServer's `end` is the index
+  // of the next `[` (top-level table) or raw.length when our block is
+  // last. Pick the trailing separator accordingly.
+  const tail = raw.slice(existing.end);
+  const trailing = tail.length === 0 ? "\n" : "\n\n";
+  return raw.slice(0, existing.start) + blockBody + trailing + tail;
+}
+
+/**
+ * Excise the `[mcp_servers.<name>]` block. Collapses extra blank lines
+ * left behind by the cut so we don't accumulate `\n\n\n` runs across
+ * round-trips.
+ *
+ * @param {string} raw
+ * @param {string} name
+ * @returns {string}
+ */
+export function removeCodexConfigBlock(raw, name) {
+  const existing = parseCodexConfigForServer(raw, name);
+  if (!existing.found) return raw;
+  let next = raw.slice(0, existing.start) + raw.slice(existing.end);
+  next = next.replace(/\n{3,}/g, "\n\n");
+  return next;
+}
+
+/**
+ * Render a `[mcp_servers.<name>]` block. The returned string is the
+ * header line plus one line per non-null field, joined with "\n" and
+ * with NO trailing newline. Callers (upsertCodexConfigBlock) append
+ * their own terminator and any blank-line separation.
+ */
+function renderBlock(name, fields) {
+  const lines = [`[mcp_servers.${name}]`];
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === null || value === undefined) continue;
+    lines.push(`${key} = "${escapeTomlString(value)}"`);
+  }
+  return lines.join("\n");
+}
+
+function escapeTomlString(value) {
+  return String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+/**
+ * Find the first occurrence of `header` at the start of a line, ignoring
+ * comments and indented (subtable) headers like `[mcp_servers.meko.tools]`.
+ *
+ * @param {string} raw
+ * @param {string} header
+ * @returns {number} index of the `[`, or -1
+ */
+function findHeader(raw, header) {
+  // Match `[mcp_servers.<name>]` exactly (no subkey appended). Anchored to
+  // the start of a line and must be followed by a newline or end-of-string.
+  const re = new RegExp(
+    `^${escapeRegex(header)}\\s*$`,
+    "m",
+  );
+  const m = re.exec(raw);
+  return m ? m.index : -1;
+}
+
+/**
+ * Starting from `from`, return the index of the next top-level `[...]`
+ * header, or raw.length if none.
+ */
+function findNextHeader(raw, from) {
+  const re = /^\[[^\]]+\]/m;
+  re.lastIndex = from;
+  const slice = raw.slice(from);
+  const m = re.exec(slice);
+  return m ? from + m.index : raw.length;
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// ---------------------------------------------------------------------------
+// AGENTS.md sentinel-block helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Upsert the Meko-managed AGENTS.md block fenced by sentinel comments.
+ * Idempotent: a second call with the same version + name produces a
+ * byte-identical file. Preserves user content outside the fence
+ * byte-for-byte.
+ *
+ * Block-ownership contract (what `upsertAgentsMdBlock` writes and what
+ * `removeAgentsMdBlock` is allowed to remove):
+ *
+ *   - The block we own is exactly `block + "\n"` — the start fence
+ *     line, the body, the end fence line, and a single trailing "\n".
+ *   - On fresh insert into non-empty content, the block is appended
+ *     immediately after the user's existing bytes. We do NOT add a
+ *     separator "\n" — markdown rendering survives just fine with the
+ *     fence sitting on the line right after the user's last line, and
+ *     the user's last newline (if present) belongs to them, not us.
+ *   - For visual separation, callers can include `\n\n` at the START
+ *     of the rendered block (we don't, to keep the block self-contained
+ *     and removable byte-faithfully).
+ *
+ * `removeAgentsMdBlock` strips exactly the bytes we own (`block` plus
+ * the trailing `"\n"` we wrote) and nothing else.
+ *
+ * Round-trip: a non-empty input ending in "\n" survives upsert → remove
+ * unchanged. An input that does NOT end in "\n" gets a "\n" appended on
+ * upsert (markdown best practice), which the round-trip cannot undo —
+ * this is an explicit and documented exception.
+ *
+ * @param {string} filePath
+ * @param {string} version
+ * @param {{name?: string}} [opts]
+ */
+export function upsertAgentsMdBlock(filePath, version, opts = {}) {
+  const name = opts.name ?? "meko";
+  const block = renderAgentsMdBlock(version, name);
+  const raw = safeReadFile(filePath) ?? "";
+  const startIdx = raw.indexOf(AGENTS_MD_START);
+  const endIdx = raw.indexOf(AGENTS_MD_END);
+  if (startIdx === -1) {
+    // Fresh insert. Append `block + "\n"` immediately after the user's
+    // bytes. If the user's content does not end in "\n", insert one
+    // first so our fence appears on its own line — that prepended "\n"
+    // is treated as user content (markdown convention) and is NOT
+    // removed by removeAgentsMdBlock.
+    const userTerminator = raw.length > 0 && !raw.endsWith("\n") ? "\n" : "";
+    writeWithBackup(filePath, raw + userTerminator + block + "\n");
+    return;
+  }
+  if (endIdx === -1 || endIdx < startIdx) {
+    // Malformed (start fence without matching end fence). Append a fresh
+    // block; the orphan start fence is left in place for the user to
+    // notice / clean up.
+    const userTerminator = raw.length > 0 && !raw.endsWith("\n") ? "\n" : "";
+    writeWithBackup(filePath, raw + userTerminator + block + "\n");
+    return;
+  }
+  // In-place replacement: just swap the body between start and end fences.
+  const next =
+    raw.slice(0, startIdx) +
+    block +
+    raw.slice(endIdx + AGENTS_MD_END.length);
+  if (next === raw) return;
+  writeWithBackup(filePath, next);
+}
+
+/**
+ * Strip the Meko-managed block from AGENTS.md content. Returns the next
+ * content string. Removes only:
+ *
+ *   - The bytes from AGENTS_MD_START through AGENTS_MD_END (inclusive).
+ *   - A single trailing "\n" immediately after the end fence (the
+ *     newline upsert wrote to terminate the block).
+ *
+ * Bytes BEFORE the start fence are preserved exactly, so a user's
+ * trailing newline survives byte-for-byte.
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+export function removeAgentsMdBlock(raw) {
+  const startIdx = raw.indexOf(AGENTS_MD_START);
+  const endIdx = raw.indexOf(AGENTS_MD_END);
+  if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) return raw;
+  let cutEnd = endIdx + AGENTS_MD_END.length;
+  if (raw[cutEnd] === "\n") cutEnd += 1;
+  return raw.slice(0, startIdx) + raw.slice(cutEnd);
+}
+
+function renderAgentsMdBlock(version, name) {
+  const toolPrefix = `mcp__${name}__`;
+  return [
+    `${AGENTS_MD_START} v${version}`,
+    "## Meko memory (auto-managed by meko installer)",
+    "",
+    `You have a persistent memory store via the \`${name}\` MCP server. At the start of every conversation, call \`${toolPrefix}memory_search\` for relevant context. When the user shares facts, preferences, or decisions worth remembering, call \`${toolPrefix}memory_add\`. Skill details: ~/.agents/skills/meko-mcp-tools/SKILL.md`,
+    "",
+    "Cloud auth requires `MEKO_API_KEY` exported in your shell (or, for the desktop app on macOS, set via `launchctl setenv`).",
+    AGENTS_MD_END,
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Cloud auth helpers
+// ---------------------------------------------------------------------------
+
+function printCloudAuthInstructions({ shellRc, hasApp, platform, log }) {
+  // Never echo the key value here — these instructions are advisory and may
+  // be captured in terminal scrollback, screenshares, CI logs, etc. The
+  // interactive rc-append / launchctl helpers receive the key directly when
+  // the user opts in.
+  log.warn?.(
+    "Codex resolves MEKO_API_KEY from your runtime env. The key was NOT written to ~/.codex/config.toml.",
+  );
+  const flavor = shellRc ? rcFlavor(shellRc) : null;
+  if (shellRc) {
+    log.dim?.(`  Add to ${shellRc}:`);
+    if (flavor === "fish") {
+      log.dim?.(`    set -gx MEKO_API_KEY '<your-meko-api-key>'`);
+    } else {
+      log.dim?.(`    export MEKO_API_KEY='<your-meko-api-key>'`);
+    }
+  } else {
+    log.dim?.("  Add to your shell rc:");
+    log.dim?.(`    bash/zsh:  export MEKO_API_KEY='<your-meko-api-key>'`);
+    log.dim?.(`    fish:      set -gx MEKO_API_KEY '<your-meko-api-key>'`);
+  }
+  log.dim?.(`  Then open a new terminal (or run "exec $SHELL" / "exec fish").`);
+  if (hasApp && platform === "darwin") {
+    log.warn?.(
+      "macOS Codex.app launched from Finder/Dock does NOT inherit shell rc — set it via launchctl too:",
+    );
+    log.dim?.(
+      `    launchctl setenv MEKO_API_KEY '<your-meko-api-key>'  # current login session`,
+    );
+    log.dim?.(
+      "    (For permanence across reboots, add a ~/Library/LaunchAgents/com.meko.env.plist.)",
+    );
+  }
+}
+
+/**
+ * Pick the right env-export syntax for the rc file we're writing to.
+ * fish uses `set -gx`; everything else (zsh, bash, sh, ksh) uses
+ * POSIX `export`. The detection key is the path: detectShellRc maps
+ * fish to a `.../fish/config.fish` path, which is the only shell whose
+ * rc file fish actually reads. (User-supplied paths flow through this
+ * same check, so a user passing `~/.config/fish/config.fish` from any
+ * shell still gets fish syntax.)
+ *
+ * @param {string} shellRc
+ * @returns {"fish"|"posix"}
+ */
+function rcFlavor(shellRc) {
+  return shellRc.endsWith(".fish") ? "fish" : "posix";
+}
+
+function buildExportLine(flavor, apiKey) {
+  if (flavor === "fish") {
+    // fish quoting is single-quote-only; no $-interpolation inside, and no
+    // way to escape a single quote inside a single-quoted string. Disallow
+    // single quotes outright rather than emit something that won't parse.
+    if (String(apiKey).includes("'")) {
+      throw new Error(
+        "MEKO_API_KEY contains a single quote; cannot safely write to a fish rc.",
+      );
+    }
+    return `set -gx MEKO_API_KEY '${apiKey}'`;
+  }
+  return `export MEKO_API_KEY=${shellQuote(apiKey)}`;
+}
+
+/**
+ * Interactive: append a sentinel-fenced env-export block to the user's
+ * shell rc. Picks `set -gx` for fish, POSIX `export` otherwise. Skipped
+ * silently when shellRc is null. Idempotent: re-running a second time
+ * finds the existing block and is a no-op.
+ *
+ * @returns {Promise<{appended: boolean, flavor?: "fish"|"posix"}>}
+ */
+export async function maybeOfferRcAppend({ apiKey, shellRc, promptUser, log }) {
+  if (!shellRc) return { appended: false };
+  const existing = safeReadFile(shellRc) ?? "";
+  if (existing.includes(RC_FENCE_START)) {
+    log?.dim?.(`  ${shellRc} already contains a meko-mcp block; skipping.`);
+    return { appended: false };
+  }
+  const flavor = rcFlavor(shellRc);
+  const exportLine = buildExportLine(flavor, apiKey);
+  const promptVerb = flavor === "fish" ? "set -gx" : "export";
+  const accept = await promptUser(
+    `Append "${promptVerb} MEKO_API_KEY ..." to ${shellRc}?`,
+    false,
+  );
+  if (!accept) return { appended: false };
+  const block = [
+    "",
+    RC_FENCE_START,
+    exportLine,
+    RC_FENCE_END,
+    "",
+  ].join("\n");
+  mkdirSync(dirname(shellRc), { recursive: true });
+  appendFileSync(shellRc, block, "utf8");
+  log?.dim?.(`  Appended meko block to ${shellRc}.`);
+  return { appended: true, flavor };
+}
+
+/**
+ * Interactive: run `launchctl setenv MEKO_API_KEY <key>` so the macOS
+ * Codex.app (launched from Finder/Dock) sees the env var for the current
+ * login session.
+ *
+ * @returns {Promise<{set: boolean}>}
+ */
+export async function maybeOfferLaunchctlSetenv({
+  apiKey,
+  promptUser,
+  runCommand,
+  log,
+}) {
+  const accept = await promptUser(
+    "Run `launchctl setenv MEKO_API_KEY ...` so Codex.app sees the key now?",
+    false,
+  );
+  if (!accept) return { set: false };
+  try {
+    runCommand(`launchctl setenv MEKO_API_KEY ${shellQuote(apiKey)}`);
+    log?.dim?.("  Set MEKO_API_KEY via launchctl (current login session).");
+    return { set: true };
+  } catch (err) {
+    log?.warn?.(`  launchctl setenv failed: ${err.message}`);
+    return { set: false };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// File helpers
+// ---------------------------------------------------------------------------
+
+function safeReadFile(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+/**
+ * True when `destination` is a symlink that resolves to `expectedSource`.
+ * Used to recognize in-place symlink installs on re-run / uninstall.
+ */
+function isOwnSymlink(destination, expectedSource) {
+  try {
+    const stat = lstatSync(destination);
+    if (!stat.isSymbolicLink()) return false;
+    const linkTarget = readlinkSync(destination);
+    const resolvedTarget = resolve(dirname(destination), linkTarget);
+    return resolvedTarget === expectedSource;
+  } catch {
+    return false;
+  }
+}
+
+function writeWithBackup(path, content) {
+  mkdirSync(dirname(path), { recursive: true });
+  if (existsSync(path)) {
+    try {
+      copyFileSync(path, path + ".bak");
+    } catch {
+      // best-effort
+    }
+  }
+  writeFileSync(path, content, "utf8");
+}
+
+// re-export for tests / outside use of the resolved-source helper
+export const __TEST__ = {
+  RC_FENCE_START,
+  RC_FENCE_END,
+  AGENTS_MD_START,
+  AGENTS_MD_END,
+  defaultDetectShellRc,
+  buildCliRegisterCommand,
+};