@yugabytedb/meko-mcp 2.2.0 → 2.5.0

package/lib/autofix.mjs

@@ -0,0 +1,100 @@
+/**
+ * autofix.mjs: the installer side of automatic capture repair.
+ *
+ * The checkpoint timer runs `--capture-cleanup fix --auto` every
+ * MEKO_AUTOFIX_INTERVAL seconds. The on/off choice lives in
+ * autofix-config.json in the capture directory, which capture-state.js
+ * autofixSetting() reads. MEKO_AUTOFIX in the hook environment overrides it.
+ *
+ * Most clients share one capture directory, but OpenCode hooks keep the one
+ * saved in their hook env file at first install, so the file is written to
+ * every capture directory the installer knows about.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+import { getCaptureRoot, getOpenCodeHookEnvPath } from "./config.mjs";
+
+const CONFIG_FILE = "autofix-config.json";
+
+function savedOpenCodeRoot(scope, projectRoot) {
+  try {
+    const file = getOpenCodeHookEnvPath(scope, projectRoot);
+    if (!existsSync(file)) return null;
+    const value = JSON.parse(readFileSync(file, "utf8")).MEKO_WATERMARK_DIR;
+    if (typeof value !== "string" || !value) return null;
+    return isAbsolute(value) ? value : resolve(value);
+  } catch {
+    return null;
+  }
+}
+
+/** Every capture directory a client's timer may read the setting from. */
+export function captureRoots({ projectRoot = process.cwd() } = {}) {
+  const roots = [getCaptureRoot()];
+  for (const scope of ["user", "project"]) {
+    const saved = savedOpenCodeRoot(scope, projectRoot);
+    if (saved && !roots.includes(saved)) roots.push(saved);
+  }
+  return roots;
+}
+
+export function autofixConfigPath() {
+  return join(getCaptureRoot(), CONFIG_FILE);
+}
+
+/** @returns {boolean|null} the saved choice in the main capture directory, or null. */
+export function readAutofixSetting() {
+  try {
+    const cfg = JSON.parse(readFileSync(autofixConfigPath(), "utf8"));
+    return typeof cfg.enabled === "boolean" ? cfg.enabled : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save --autofix / --no-autofix in every capture directory. `enable`
+ * undefined keeps an earlier choice, so a plain reinstall doesn't turn
+ * repair back on.
+ *
+ * @param {{ enable?: boolean, dryRun?: boolean, projectRoot?: string }} opts
+ * @returns {{ enabled: boolean, changed: boolean, paths: string[] }}
+ */
+export function applyAutofixSetting({ enable, dryRun = false, projectRoot } = {}) {
+  const saved = readAutofixSetting();
+  const paths = captureRoots({ projectRoot }).map((root) => join(root, CONFIG_FILE));
+  if (enable === undefined) {
+    return { enabled: saved === null ? true : saved, changed: false, paths };
+  }
+  if (!dryRun) {
+    for (const file of paths) {
+      mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+      writeFileSync(
+        file,
+        `${JSON.stringify({ enabled: enable, updated_at: new Date().toISOString() })}\n`,
+        { mode: 0o600 },
+      );
+    }
+  }
+  return { enabled: enable, changed: saved !== enable, paths };
+}
+
+/** Same rule as capture-state.js autofixIntervalSeconds(). */
+function intervalSeconds(env) {
+  const n = Number.parseInt(env.MEKO_AUTOFIX_INTERVAL || "", 10);
+  return Math.max(60, Number.isFinite(n) ? n : 1800);
+}
+
+/** One line for the end of an install. */
+export function describeAutofix(enabled, env = process.env) {
+  const envOverride = env.MEKO_AUTOFIX;
+  if (envOverride != null && envOverride !== "") {
+    return `Automatic capture repair follows MEKO_AUTOFIX=${envOverride} in this environment.`;
+  }
+  const minutes = Math.max(1, Math.round(intervalSeconds(env) / 60));
+  return enabled
+    ? `Automatic capture repair is on: every ${minutes} minute${minutes === 1 ? "" : "s"} the capture timer fixes stuck sessions (--capture-cleanup fix). Turn it off with --no-autofix.`
+    : "Automatic capture repair is off. Turn it on with --autofix, or run --capture-cleanup fix yourself.";
+}

package/lib/browser-login.mjs

@@ -0,0 +1,495 @@
+/**
+ * Browser sign-in for Cloud Meko: OAuth once, then trade the session for an
+ * API key.
+ *
+ * The flow is the MCP authorization spec, ported from
+ * yugabyte/meko-cli lib/oauth.mjs:
+ *
+ *   1. Probe the MCP endpoint unauthenticated and read WWW-Authenticate.
+ *   2. Discover protected-resource and authorization-server metadata.
+ *   3. Register a public client (DCR) with a loopback redirect_uri.
+ *   4. Open the browser on /authorize with PKCE (S256) and wait for the
+ *      callback on 127.0.0.1.
+ *   5. Exchange the code for an access token.
+ *   6. POST it to <server>/api-keys, which creates an `mko_tkn_` key for the
+ *      signed-in user.
+ *
+ * Only the API key leaves this module. The OAuth tokens are discarded: the
+ * client configs and capture hooks all authenticate with the key, so nothing
+ * here needs refreshing.
+ */
+
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import http from "node:http";
+import os from "node:os";
+import { spawn } from "node:child_process";
+
+import { MEKO_PRODUCTION_CONSOLE_URL } from "./clients/common.mjs";
+
+const PROTOCOL_VERSION = "2025-03-26";
+const USER_AGENT = "meko-installer/1.0 (+https://github.com/yugabyte/meko-mcp-server)";
+export const DEFAULT_LOGIN_TIMEOUT_MS = 5 * 60_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const MAX_KEY_NAME_LEN = 100;
+
+export class BrowserLoginError extends Error {
+  constructor(message, { code = "login_failed", status = null } = {}) {
+    super(message);
+    this.name = "BrowserLoginError";
+    this.code = code;
+    this.status = status;
+  }
+}
+
+/**
+ * Sign in through the browser and return a freshly created API key.
+ *
+ * @param {object} params
+ * @param {string} params.url             MCP endpoint, e.g. https://mcp.mekodata.ai/mcp
+ * @param {string} [params.keyName]       Label for the new key (default: installer + hostname + time)
+ * @param {boolean} [params.noBrowser]    Print the URL instead of opening a browser
+ * @param {number} [params.loginTimeoutMs]
+ * @param {(msg: string) => void} [params.notify]
+ * @param {typeof fetch} [params.fetchImpl]
+ * @param {(url: string) => Promise<boolean>} [params.openBrowser]
+ * @returns {Promise<{apiKey: string, id: string|null, name: string, expiresAt: string|null}>}
+ */
+export async function loginAndCreateApiKey({
+  url,
+  keyName = defaultKeyName(),
+  noBrowser = false,
+  loginTimeoutMs = DEFAULT_LOGIN_TIMEOUT_MS,
+  notify = () => {},
+  fetchImpl = globalThis.fetch,
+  openBrowser = openDefaultBrowser,
+} = {}) {
+  const accessToken = await loginOAuth({
+    url,
+    noBrowser,
+    loginTimeoutMs,
+    notify,
+    fetchImpl,
+    openBrowser,
+  });
+  return createApiKey({ url, accessToken, keyName, fetchImpl });
+}
+
+export async function loginOAuth({
+  url,
+  noBrowser = false,
+  loginTimeoutMs = DEFAULT_LOGIN_TIMEOUT_MS,
+  notify = () => {},
+  fetchImpl = globalThis.fetch,
+  openBrowser = openDefaultBrowser,
+}) {
+  const callback = await createCallbackServer();
+  try {
+    const discovery = await discoverOAuth(url, fetchImpl);
+    const client = await registerClient(discovery, callback.redirectUri, fetchImpl);
+    const state = base64url(randomBytes(32));
+    const verifier = base64url(randomBytes(48));
+    const challenge = base64url(createHash("sha256").update(verifier).digest());
+    const authorizationUrl = buildAuthorizationUrl({
+      discovery,
+      client,
+      redirectUri: callback.redirectUri,
+      state,
+      challenge,
+    });
+
+    if (noBrowser) {
+      notify(`Open this URL in a browser to sign in:\n  ${authorizationUrl}`);
+    } else {
+      const opened = await openBrowser(authorizationUrl);
+      notify(
+        opened
+          ? `Opened your browser to sign in. If it didn't open, use this URL:\n  ${authorizationUrl}`
+          : `Could not open a browser. Open this URL to sign in:\n  ${authorizationUrl}`,
+      );
+    }
+
+    const returned = await callback.wait(loginTimeoutMs);
+    if (returned.error) {
+      throw new BrowserLoginError(
+        `Sign-in failed: ${returned.error_description ?? returned.error}`,
+        { code: "authorization_denied" },
+      );
+    }
+    if (!safeEqual(returned.state, state)) {
+      throw new BrowserLoginError("Sign-in callback state did not match. Run the installer again.");
+    }
+    if (!returned.code) {
+      throw new BrowserLoginError("Sign-in callback did not include an authorization code.");
+    }
+
+    const tokens = await exchangeAuthorizationCode({
+      discovery,
+      client,
+      redirectUri: callback.redirectUri,
+      code: returned.code,
+      verifier,
+      fetchImpl,
+    });
+    return tokens.access_token;
+  } finally {
+    await callback.close();
+  }
+}
+
+/**
+ * Trade an OAuth access token for an `mko_tkn_` key via POST <server>/api-keys.
+ */
+export async function createApiKey({ url, accessToken, keyName = defaultKeyName(), fetchImpl = globalThis.fetch }) {
+  const endpoint = apiKeysEndpoint(url);
+  const response = await timedFetch(fetchImpl, endpoint, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      "User-Agent": USER_AGENT,
+    },
+    body: JSON.stringify({ name: keyName }),
+  });
+  const body = await response.json().catch(() => null);
+  const console = consoleUrlFor(url);
+
+  if (response.status === 404 || response.status === 405) {
+    throw new BrowserLoginError(
+      "This Meko server does not support browser sign-in yet. " +
+        `Create an API key at ${console} > Settings > API Keys, then rerun with --api-key.`,
+      { code: "unsupported", status: response.status },
+    );
+  }
+  if (response.status === 429) {
+    throw new BrowserLoginError(
+      "You already have the maximum number of active API keys. " +
+        `Revoke one at ${console} > Settings > API Keys, then run the installer again.`,
+      { code: "token_cap_reached", status: 429 },
+    );
+  }
+  if (response.status === 403 && body?.error?.code === "account_not_provisioned") {
+    // The browser signed in as a Cognito identity with no Meko account, e.g.
+    // Google in the browser but email and password in the console. The
+    // server refuses rather than minting a key for a new, empty account.
+    throw new BrowserLoginError(
+      `You signed in as a user that has no Meko account. Sign in at ${console} with the ` +
+        "method you normally use (for example Google, or email and password), then run the " +
+        "installer again and pick that same method. If the browser chose an account " +
+        `automatically, sign out at ${console} first. Or create a key at ${console} > ` +
+        "Settings > API Keys and rerun with --api-key.",
+      { code: "account_not_provisioned", status: 403 },
+    );
+  }
+  if (!response.ok || typeof body?.api_key !== "string" || !body.api_key.startsWith("mko_tkn_")) {
+    const detail = body?.error?.message ? `: ${body.error.message}` : "";
+    throw new BrowserLoginError(
+      `Could not create an API key (HTTP ${response.status})${detail}`,
+      { code: body?.error?.code ?? "create_failed", status: response.status },
+    );
+  }
+  return {
+    apiKey: body.api_key,
+    id: body.id ?? null,
+    name: body.name ?? keyName,
+    expiresAt: body.expires_at ?? null,
+  };
+}
+
+/** `https://mcp.mekodata.ai/mcp` → `https://mcp.mekodata.ai/api-keys`. */
+export function apiKeysEndpoint(mcpUrl) {
+  const parsed = new URL(mcpUrl);
+  const base = parsed.pathname.replace(/\/+$/, "").replace(/\/mcp$/, "");
+  return `${parsed.origin}${base}/api-keys`;
+}
+
+/** Console that issues keys for this MCP host. Dev keys only work on dev. */
+export function consoleUrlFor(mcpUrl) {
+  try {
+    const host = new URL(mcpUrl).hostname;
+    if (host === "mekodev.com" || host.endsWith(".mekodev.com")) return "https://app.mekodev.com";
+  } catch {
+    // fall through
+  }
+  return MEKO_PRODUCTION_CONSOLE_URL;
+}
+
+export function defaultKeyName({ hostname = os.hostname(), now = new Date() } = {}) {
+  const stamp = now.toISOString().replace(/\.\d{3}Z$/, "Z");
+  const host = String(hostname || "unknown-host").replace(/\.local$/, "");
+  const name = `Meko installer (${host}) ${stamp}`;
+  if (name.length <= MAX_KEY_NAME_LEN) return name;
+  const room = MAX_KEY_NAME_LEN - `Meko installer () ${stamp}`.length;
+  return `Meko installer (${host.slice(0, Math.max(room, 0))}) ${stamp}`;
+}
+
+// ---------------------------------------------------------------------------
+// OAuth plumbing
+// ---------------------------------------------------------------------------
+
+export async function discoverOAuth(serverUrl, fetchImpl = globalThis.fetch) {
+  const challenge = await probeChallenge(serverUrl, fetchImpl);
+  const resourceMetadata = await firstJson(
+    protectedResourceUrls(serverUrl, challenge.resourceMetadata),
+    fetchImpl,
+  );
+  const authorizationServer = resourceMetadata?.authorization_servers?.[0] ?? new URL(serverUrl).origin;
+  const metadata = await firstJson(authorizationMetadataUrls(authorizationServer, serverUrl), fetchImpl);
+  if (!metadata?.authorization_endpoint || !metadata?.token_endpoint) {
+    throw new BrowserLoginError(
+      "This Meko endpoint does not advertise OAuth sign-in. Use --api-key instead.",
+      { code: "unsupported" },
+    );
+  }
+  return {
+    authorization_endpoint: metadata.authorization_endpoint,
+    token_endpoint: metadata.token_endpoint,
+    registration_endpoint: metadata.registration_endpoint ?? new URL("/register", authorizationServer).toString(),
+    scope: challenge.scope
+      ?? resourceMetadata?.scopes_supported?.join(" ")
+      ?? metadata.scopes_supported?.join(" ")
+      ?? null,
+    resource: resourceMetadata?.resource ?? null,
+  };
+}
+
+async function probeChallenge(serverUrl, fetchImpl) {
+  const response = await timedFetch(fetchImpl, serverUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json, text/event-stream",
+      "MCP-Protocol-Version": PROTOCOL_VERSION,
+      "User-Agent": USER_AGENT,
+    },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: "oauth-discovery",
+      method: "initialize",
+      params: {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: "meko-installer", version: "1.0.0" },
+      },
+    }),
+  });
+  const header = response.headers.get("www-authenticate") ?? "";
+  return {
+    resourceMetadata: challengeField(header, "resource_metadata"),
+    scope: challengeField(header, "scope"),
+  };
+}
+
+async function registerClient(discovery, redirectUri, fetchImpl) {
+  const response = await timedFetch(fetchImpl, discovery.registration_endpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
+    body: JSON.stringify({
+      redirect_uris: [redirectUri],
+      token_endpoint_auth_method: "none",
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      client_name: "Meko installer",
+      software_id: "meko-installer",
+      software_version: "1.0.0",
+      ...(discovery.scope ? { scope: discovery.scope } : {}),
+    }),
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok || !body?.client_id) {
+    throw new BrowserLoginError(
+      `OAuth client registration failed (HTTP ${response.status}). Use --api-key instead.`,
+      { code: "registration_failed", status: response.status },
+    );
+  }
+  return body;
+}
+
+function buildAuthorizationUrl({ discovery, client, redirectUri, state, challenge }) {
+  const url = new URL(discovery.authorization_endpoint);
+  url.search = new URLSearchParams({
+    response_type: "code",
+    client_id: client.client_id,
+    redirect_uri: redirectUri,
+    state,
+    code_challenge: challenge,
+    code_challenge_method: "S256",
+    ...(discovery.scope ? { scope: discovery.scope } : {}),
+    ...(discovery.resource ? { resource: discovery.resource } : {}),
+  }).toString();
+  return url.toString();
+}
+
+async function exchangeAuthorizationCode({ discovery, client, redirectUri, code, verifier, fetchImpl }) {
+  const form = new URLSearchParams({
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri,
+    client_id: client.client_id,
+    code_verifier: verifier,
+    ...(discovery.resource ? { resource: discovery.resource } : {}),
+  });
+  const headers = { "Content-Type": "application/x-www-form-urlencoded", "User-Agent": USER_AGENT };
+  const method = client.token_endpoint_auth_method ?? "none";
+  if (method === "client_secret_basic") {
+    const id = encodeURIComponent(client.client_id);
+    const secret = encodeURIComponent(client.client_secret ?? "");
+    headers.Authorization = `Basic ${Buffer.from(`${id}:${secret}`).toString("base64")}`;
+  } else if (method === "client_secret_post" && client.client_secret) {
+    form.set("client_secret", client.client_secret);
+  }
+  const response = await timedFetch(fetchImpl, discovery.token_endpoint, { method: "POST", headers, body: form });
+  const body = await response.json().catch(() => null);
+  if (!response.ok || !body?.access_token) {
+    throw new BrowserLoginError(
+      `OAuth token exchange failed (HTTP ${response.status}). Run the installer again.`,
+      { code: "token_exchange_failed", status: response.status },
+    );
+  }
+  return body;
+}
+
+const CALLBACK_PAGE =
+  "<!doctype html><meta charset=utf-8><title>Meko sign-in</title>" +
+  "<body style=\"font-family:system-ui,sans-serif;max-width:32rem;margin:4rem auto\">" +
+  "<h1>Signed in to Meko</h1><p>You can close this window and return to the terminal.</p></body>";
+
+async function createCallbackServer() {
+  let settle;
+  let fail;
+  const result = new Promise((resolve, reject) => {
+    settle = resolve;
+    fail = reject;
+  });
+  const server = http.createServer((req, res) => {
+    const requestUrl = new URL(req.url, "http://localhost");
+    if (requestUrl.pathname !== "/callback") {
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end("Not found");
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+    res.end(CALLBACK_PAGE);
+    settle(Object.fromEntries(requestUrl.searchParams));
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  server.on("error", (err) => fail(err));
+  const { port } = server.address();
+  return {
+    redirectUri: `http://localhost:${port}/callback`,
+    wait: (timeoutMs) => {
+      const timer = setTimeout(
+        () =>
+          fail(
+            new BrowserLoginError(
+              `Timed out after ${Math.round(timeoutMs / 1000)}s waiting for browser sign-in. ` +
+                "Run the installer again, or use --api-key.",
+              { code: "timeout" },
+            ),
+          ),
+        timeoutMs,
+      );
+      timer.unref?.();
+      return result.finally(() => clearTimeout(timer));
+    },
+    close: () =>
+      new Promise((resolve) => {
+        server.closeAllConnections?.();
+        server.close(() => resolve());
+      }),
+  };
+}
+
+export async function openDefaultBrowser(url, { platform = process.platform, spawnImpl = spawn } = {}) {
+  const command = platform === "darwin" ? "open" : platform === "win32" ? "rundll32" : "xdg-open";
+  const args = platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
+  try {
+    const child = spawnImpl(command, args, { detached: true, stdio: "ignore" });
+    return await new Promise((resolve) => {
+      child.once("error", () => resolve(false));
+      child.once("spawn", () => {
+        child.unref();
+        resolve(true);
+      });
+    });
+  } catch {
+    return false;
+  }
+}
+
+function protectedResourceUrls(serverUrl, advertised) {
+  const parsed = new URL(serverUrl);
+  const urls = [];
+  if (advertised) urls.push(advertised);
+  if (parsed.pathname && parsed.pathname !== "/") {
+    urls.push(`${parsed.origin}/.well-known/oauth-protected-resource${parsed.pathname}`);
+  }
+  urls.push(`${parsed.origin}/.well-known/oauth-protected-resource`);
+  return [...new Set(urls)];
+}
+
+function authorizationMetadataUrls(authServer, serverUrl) {
+  const parsed = new URL(authServer || serverUrl);
+  if (parsed.pathname && parsed.pathname !== "/") {
+    const path = parsed.pathname.replace(/\/$/, "");
+    return [
+      `${parsed.origin}/.well-known/oauth-authorization-server${path}`,
+      `${parsed.origin}/.well-known/openid-configuration${path}`,
+      `${parsed.origin}${path}/.well-known/openid-configuration`,
+    ];
+  }
+  return [
+    `${parsed.origin}/.well-known/oauth-authorization-server`,
+    `${parsed.origin}/.well-known/openid-configuration`,
+  ];
+}
+
+async function firstJson(urls, fetchImpl) {
+  for (const url of urls) {
+    const response = await timedFetch(fetchImpl, url, {
+      headers: { "MCP-Protocol-Version": PROTOCOL_VERSION, "User-Agent": USER_AGENT },
+    });
+    if (!response.ok) continue;
+    try {
+      return await response.json();
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+async function timedFetch(fetchImpl, url, options) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), DEFAULT_REQUEST_TIMEOUT_MS);
+  timer.unref?.();
+  try {
+    return await fetchImpl(url, { ...options, signal: controller.signal });
+  } catch (err) {
+    if (err?.name === "AbortError") {
+      throw new BrowserLoginError(`Request timed out: ${url}`, { code: "network" });
+    }
+    throw new BrowserLoginError(`Request failed: ${err?.message ?? String(err)}`, { code: "network" });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function challengeField(header, field) {
+  const match = new RegExp(`${field}=(?:"([^"]+)"|([^\\s,]+))`, "i").exec(header);
+  return match?.[1] ?? match?.[2] ?? null;
+}
+
+function safeEqual(left, right) {
+  if (typeof left !== "string" || typeof right !== "string") return false;
+  const a = Buffer.from(left);
+  const b = Buffer.from(right);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+function base64url(value) {
+  return Buffer.from(value).toString("base64url");
+}

package/lib/capture-cleanup.mjs

@@ -0,0 +1,63 @@
+/**
+ * capture-cleanup.mjs: installer helper that invokes capture-cleanup-cli.js.
+ *
+ * Resolves the CLI the same way capture-status.mjs does, so a published
+ * package runs the bundled copy next to the capture.js it drains with.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { resolveCaptureStatusCli } from "./capture-status.mjs";
+
+/**
+ * Absolute path to capture-cleanup-cli.js under the active asset root.
+ * @returns {string}
+ */
+export function resolveCaptureCleanupCli() {
+  return join(dirname(resolveCaptureStatusCli()), "capture-cleanup-cli.js");
+}
+
+/**
+ * Build the CLI argument list from parsed installer flags.
+ *
+ * @param {string} action
+ * @param {{ session?: string[], all?: boolean, 'dry-run'?: boolean,
+ *   json?: boolean, yes?: boolean, 'max-exchanges'?: string,
+ *   'pace-ms'?: string }} flags
+ * @returns {string[]}
+ */
+export function captureCleanupArgs(action, flags = {}) {
+  const args = [action];
+  for (const id of flags.session || []) args.push("--session", id);
+  if (flags.all) args.push("--all");
+  if (flags["dry-run"]) args.push("--dry-run");
+  if (flags.json) args.push("--json");
+  if (flags.yes) args.push("--yes");
+  if (flags["max-exchanges"] != null) args.push("--max-exchanges", String(flags["max-exchanges"]));
+  if (flags["pace-ms"] != null) args.push("--pace-ms", String(flags["pace-ms"]));
+  return args;
+}
+
+/**
+ * Run the capture-cleanup CLI with inherited stdio (drain prints progress)
+ * and return its exit code.
+ *
+ * @param {string[]} args
+ * @param {{ env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {{ code: number, cliPath: string, error?: string }}
+ */
+export function runCaptureCleanup(args, opts = {}) {
+  const cliPath = resolveCaptureCleanupCli();
+  if (!existsSync(cliPath)) {
+    return { code: 1, cliPath, error: `capture-cleanup CLI not found at ${cliPath}` };
+  }
+  const result = spawnSync(process.execPath, [cliPath, ...args], {
+    stdio: "inherit",
+    env: opts.env ? { ...process.env, ...opts.env } : process.env,
+  });
+  const code =
+    typeof result.status === "number" && result.status >= 0 ? result.status : 1;
+  return { code, cliPath };
+}

package/lib/clients/claude-code.mjs

@@ -65,6 +65,7 @@ const MEKO_MARKETPLACE_NAME = "meko-agent-skills";
 const MEKO_ALWAYS_AVAILABLE_TOOLS = [
   "mcp__meko__memory_add",
   "mcp__meko__memory_search",
+  "mcp__meko__context_search",
   "mcp__meko__memory_get_all",
   "mcp__meko__memory_get_by_id",
   "mcp__meko__memory_update",