@yugabytedb/meko-mcp 2.3.0 → 2.5.1

package/bin/create-meko-setup.mjs

@@ -7,8 +7,10 @@ import { dirname, join } from 'node:path';
 
 import { install, uninstall } from '../lib/installer.mjs';
 import { askChoice, askMultiChoice, askText, askSecret, askYesNo, close as closePrompts } from '../lib/prompt.mjs';
-import { banner, error, dim, info, warn } from '../lib/logger.mjs';
+import { banner, error, dim, info, success, warn } from '../lib/logger.mjs';
+import { BrowserLoginError, consoleUrlFor, loginAndCreateApiKey } from '../lib/browser-login.mjs';
 import {
+  isLocalUrl,
   isPackagedInstall,
   MEKO_PRODUCTION_CONSOLE_URL,
   selfInvocation,
@@ -20,6 +22,7 @@ import { startMigration, runChildMigration, readStatus, stopMigration } from '..
 import { checkLatest } from '../lib/version-check.mjs';
 import { runCaptureStatus } from '../lib/capture-status.mjs';
 import { captureCleanupArgs, runCaptureCleanup } from '../lib/capture-cleanup.mjs';
+import { applyAutofixSetting, describeAutofix } from '../lib/autofix.mjs';
 
 // ---------------------------------------------------------------------------
 // Flag definitions
@@ -28,6 +31,7 @@ import { captureCleanupArgs, runCaptureCleanup } from '../lib/capture-cleanup.mj
 const options = {
   url:                { type: 'string' },
   'api-key':          { type: 'string' },
+  'no-browser':       { type: 'boolean', default: false },
   local:              { type: 'boolean', default: false },
   scope:              { type: 'string',  default: 'user' },
   name:               { type: 'string',  default: 'meko' },
@@ -37,6 +41,8 @@ const options = {
   'skip-validation':  { type: 'boolean', default: false },
   statusline:         { type: 'boolean', default: false },
   'no-statusline':    { type: 'boolean', default: false },
+  autofix:            { type: 'boolean', default: false },
+  'no-autofix':       { type: 'boolean', default: false },
   'no-canary':        { type: 'boolean', default: false },
   'dry-run':          { type: 'boolean', default: false },
   'check-updates':    { type: 'boolean', default: false },
@@ -81,6 +87,9 @@ function readVersion() {
   return pkg.version;
 }
 
+// The docker-compose dev stack that --local points at. It takes no API key.
+const LOCAL_DEV_MCP_URL = 'http://localhost:8000/mcp';
+
 const ALL_CLIENTS = ['claude-code', 'claude-desktop', 'cursor', 'codex', 'kiro', 'opencode'];
 
 function printHelp() {
@@ -96,7 +105,10 @@ Examples:
   # Interactive setup (recommended for first-time users):
   create-meko-setup
 
-  # Cloud Meko for Claude Code (non-interactive):
+  # Cloud Meko for Claude Code (signs in through your browser):
+  create-meko-setup --url https://mcp.mekodata.ai/mcp --client claude-code
+
+  # Cloud Meko with an existing API key (unattended, e.g. CI):
   create-meko-setup --url https://mcp.mekodata.ai/mcp --api-key "$MEKO_API_KEY" --yes
 
   # Local Meko with Cursor config:
@@ -131,8 +143,13 @@ Options:
                         untrusted IDE workspaces and non-managed CLI agents fall
                         back to agent-driven persistence.
   --url <url>           MCP server URL (from cloud.mekodata.ai > Datapacks > Connect)
-  --api-key <key>       API key for Cloud Meko authentication
-  --local               Use local Meko at http://localhost:8000/mcp
+  --api-key <key>       Use an existing Meko API key (Cloud, or Meko Local's
+                        client token) instead of signing in through the
+                        browser. Also read from $MEKO_API_KEY for any URL
+                        (ignored with --local). Required for Cloud when no
+                        terminal is attached (CI, scripts).
+  --no-browser          Print the sign-in URL instead of opening a browser
+  --local               Use local Meko at http://localhost:8000/mcp (no API key)
   --scope <scope>       Config scope: user or project (default: user)
                         codex always installs at user scope (no project-level
                         config); --scope=project degrades with a warning.
@@ -144,8 +161,13 @@ Options:
                         Default: ON under --yes, prompted otherwise.
                         Claude Code only.
   --no-statusline       Skip statusline wiring even under --yes.
+  --no-autofix          Turn off automatic capture repair: the capture timer
+                        otherwise runs --capture-cleanup fix every 30 minutes
+                        (MEKO_AUTOFIX_INTERVAL) when a session is stuck.
+  --autofix             Turn automatic capture repair back on.
   --skip-validation     Skip post-install validation
-  --no-canary           Skip the canary datapack_list call. The
+  --no-canary           Skip the canary datapack_search (or, on older
+                        servers, datapack_list) call. The
                         connectivity + tools/list checks still run.
   --dry-run             Show what would be done without making changes
   --check-updates       Compare installed version against npm registry and exit
@@ -167,6 +189,10 @@ Capture health (durable outbox / recovery):
                         Clean up stuck capture on this machine:
                           status   list sessions with unsent work and the
                                    background capture processes (read-only)
+                          fix      diagnose each stuck session and fix it:
+                                   repair, drain, or move unsent turns to a
+                                   new conversation; reports what only you
+                                   can fix (start here)
                           stop     stop SessionEnd workers and in-flight
                                    drains, and park all unsent work so no
                                    hook retries it (nothing is deleted)
@@ -205,10 +231,6 @@ Migrate existing conversations and memories into Meko:
   console.log(text);
 }
 
-function isCloudUrl(url) {
-  return url && !url.includes('localhost') && !url.includes('127.0.0.1');
-}
-
 /**
  * Sanitize a raw API key from any source (CLI flag, env var, askSecret prompt).
  *
@@ -295,6 +317,32 @@ function parseRate(raw) {
   return n;
 }
 
+// Placeholder shown in --dry-run output in place of a key that browser
+// sign-in would create. Never sent anywhere: dry runs make no changes.
+const DRY_RUN_SIGN_IN_KEY = 'mko_tkn_<created-by-browser-sign-in>';
+
+/**
+ * Sign in through the browser and create an API key for this install.
+ * Returns the key, or null after printing why sign-in failed.
+ */
+async function signInWithBrowser({ url, noBrowser, dryRun }) {
+  if (dryRun) {
+    dim('Would sign in with your browser and create an API key (skipped: --dry-run).');
+    return DRY_RUN_SIGN_IN_KEY;
+  }
+  info('Signing in to Meko with your browser to create an API key...');
+  try {
+    const key = await loginAndCreateApiKey({ url, noBrowser, notify: (msg) => dim(msg) });
+    const expires = key.expiresAt ? ` (expires ${String(key.expiresAt).slice(0, 10)})` : '';
+    success(`Signed in. Created API key "${key.name}"${expires}.`);
+    dim(`Manage or revoke it at ${consoleUrlFor(url)} > Settings > API Keys.`);
+    return key.apiKey;
+  } catch (err) {
+    error(err instanceof BrowserLoginError ? err.message : `Browser sign-in failed: ${err?.message ?? err}`);
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -340,7 +388,7 @@ async function main() {
     if (out.stderr) process.stderr.write(out.stderr);
     process.exit(out.code);
   }
-  // --capture-cleanup <action>: inspect, stop, park, drain, or discard
+  // --capture-cleanup <action>: inspect, fix, stop, park, drain, or discard
   // stuck capture sessions. Exit codes: 0 done, 1 error, 2 partly done.
   if (flags['capture-cleanup'] !== undefined) {
     const out = runCaptureCleanup(
@@ -433,7 +481,7 @@ async function main() {
     }
     let url = flags.url ?? process.env.MEKO_MCP_URL ?? null;
     let apiKey = normalizeApiKey(flags['api-key'] ?? process.env.MEKO_API_KEY);
-    if (flags.local) { url = 'http://localhost:8000/mcp'; apiKey = null; }
+    if (flags.local) { url = LOCAL_DEV_MCP_URL; apiKey = null; }
 
     let parentRate;
     try { parentRate = parseRate(flags.rate); }
@@ -508,11 +556,21 @@ async function main() {
   // submitting an empty value at the full-flow prompt would re-ask the
   // same question.
   let promptedForApiKey = false;
+  // Set when the user picked "Sign in with browser" at the interactive auth
+  // prompt. Someone answered that prompt, so sign-in runs even when stdin
+  // is not a TTY (e.g. piped answers in the smoke harness).
+  let choseBrowserSignIn = false;
+  // Set for --local, the interactive "Local Meko" choice, and a --yes run
+  // that reuses an existing LOCAL_DEV_MCP_URL entry: the docker-compose dev
+  // stack takes no key, so $MEKO_API_KEY is not read for it. An explicit
+  // --url, local or not, still reads it.
+  let keylessLocal = false;
 
   // --local shortcut
   if (flags.local) {
-    url    = 'http://localhost:8000/mcp';
+    url    = LOCAL_DEV_MCP_URL;
     apiKey = null;
+    keylessLocal = true;
   }
 
   // Client picker — runs for any interactive invocation (including
@@ -578,6 +636,11 @@ async function main() {
         process.exit(1);
       }
       url = suggestedUrl.url;
+      // Reusing the dev stack an earlier --local install registered: keep it
+      // keyless, as --local would.
+      if (suggestedUrl.source === 'existing' && url === LOCAL_DEV_MCP_URL) {
+        keylessLocal = true;
+      }
     }
   }
 
@@ -591,7 +654,7 @@ async function main() {
     // When only Cloud is available, skip the prompt entirely — asking to
     // pick between one option is pointless UX.
     const connectionOptions = [
-      { label: 'Cloud Meko', description: 'Hosted at mekodata.ai (requires an API key)' },
+      { label: 'Cloud Meko', description: 'Hosted at mekodata.ai (sign in with your browser)' },
     ];
     if (!isPackagedInstall()) {
       connectionOptions.push({
@@ -620,14 +683,28 @@ async function main() {
         suggestedUrl?.url ?? undefined,
       );
 
-      // Step 3 — API key. Normalize: terminal paste can drag in trailing
-      // whitespace/CR or accidental surrounding quotes, all of which would
-      // sail straight into `Authorization: Bearer ...` and 401.
-      apiKey = normalizeApiKey(await askSecret('API key:'));
-      promptedForApiKey = true;
+      // Step 3 — authentication. Browser sign-in is the default and runs
+      // in the Cloud-URL check below; pasting a key is the advanced path.
+      // An existing --api-key or $MEKO_API_KEY skips the question.
+      if (!apiKey && !normalizeApiKey(process.env.MEKO_API_KEY)) {
+        const authChoice = await askChoice('How do you want to authenticate?', [
+          { label: 'Sign in with browser', description: 'Recommended. Creates an API key for you' },
+          { label: 'Paste an API key', description: `From ${consoleUrlFor(url)} > Settings > API Keys` },
+        ]);
+        if (authChoice === 'Paste an API key') {
+          // Normalize: terminal paste can drag in trailing whitespace/CR or
+          // accidental surrounding quotes, all of which would sail straight
+          // into `Authorization: Bearer ...` and 401.
+          apiKey = normalizeApiKey(await askSecret('API key:'));
+          promptedForApiKey = true;
+        } else {
+          choseBrowserSignIn = true;
+        }
+      }
     } else {
-      url    = 'http://localhost:8000/mcp';
+      url    = LOCAL_DEV_MCP_URL;
       apiKey = null;
+      keylessLocal = true;
     }
 
     // Step 4 — skills
@@ -661,27 +738,50 @@ async function main() {
     process.exit(1);
   }
 
-  // Validation — Cloud URL requires an API key.
-  // Resolution order: --api-key (already in `apiKey`) → $MEKO_API_KEY →
-  // interactive prompt (only on a TTY, not under --yes, and only if the
-  // full interactive flow above didn't already ask). The prompt fallback
-  // exists so a user who pastes the cloud one-liner from the UI (which
-  // only shows --url and --client) isn't dead-ended on a hard error when
-  // they forgot to supply the key. Skipping it after a full-flow prompt
-  // avoids re-asking the same question when the user submitted empty.
-  if (isCloudUrl(url) && !apiKey) {
+  // API key resolution order: --api-key (already in `apiKey`) →
+  // $MEKO_API_KEY → browser sign-in (Cloud only).
+  //
+  // $MEKO_API_KEY applies to every URL, local ones included: Meko Local
+  // (the `meko` server, MCP on 127.0.0.1:7778) requires its client token,
+  // and AgentK passes that token only through the environment so it stays
+  // out of `ps`. Only the keyless dev stack (see `keylessLocal`) skips it.
+  if (!apiKey && !keylessLocal) {
     apiKey = normalizeApiKey(process.env.MEKO_API_KEY);
     if (apiKey) {
       dim('Using API key from MEKO_API_KEY environment variable.');
-    } else if (!flags.yes && !promptedForApiKey && process.stdin.isTTY) {
-      dim('No --api-key or MEKO_API_KEY env var found; prompting for API key.');
-      apiKey = normalizeApiKey(await askSecret('API key:'));
+    }
+  }
+
+  // Validation — Cloud URL requires an API key. Browser sign-in creates one
+  // through the server's POST /api-keys. Sign-in also covers the cloud
+  // one-liner from the UI, which only shows --url and --client. It is
+  // skipped when the full interactive flow already took a pasted key (an
+  // empty paste is an error, not a silent switch to the browser), and
+  // whenever stdin is not a terminal, with or without --yes: a script or CI
+  // step may have nobody at the browser, and a 5-minute callback wait would
+  // stall it. The one exception is an explicit "Sign in with browser" answer
+  // at the prompt. A local URL with no key installs without one.
+  if (!isLocalUrl(url) && !apiKey) {
+    let signInFailed = false;
+    if (!promptedForApiKey && (process.stdin.isTTY || choseBrowserSignIn)) {
+      apiKey = await signInWithBrowser({
+        url,
+        noBrowser: flags['no-browser'],
+        dryRun: flags['dry-run'],
+      });
+      signInFailed = !apiKey;
     }
     if (!apiKey) {
-      error(
-        'API key is required for Cloud Meko. ' +
-        'Provide --api-key, set MEKO_API_KEY env var, or run interactively.',
-      );
+      let message;
+      if (signInFailed) {
+        message = `Browser sign-in did not complete. To use an existing key instead, create one at ${consoleUrlFor(url)} > Settings > API Keys and rerun with --api-key, or set MEKO_API_KEY.`;
+      } else if (promptedForApiKey) {
+        message = 'No API key entered. Rerun and choose Sign in with browser, or pass --api-key.';
+      } else {
+        message = 'API key is required for Cloud Meko. ' +
+          'Provide --api-key, set MEKO_API_KEY env var, or run in a terminal to sign in with your browser.';
+      }
+      error(message);
       process.exit(1);
     }
   }
@@ -716,6 +816,23 @@ async function main() {
     }
   }
 
+  // Automatic capture repair runs inside the capture timer the hooks start,
+  // so installing the hooks deploys it. Save --autofix / --no-autofix once,
+  // for every client (they share one capture directory).
+  if (errors.length < clients.length) {
+    if (flags.autofix && flags['no-autofix']) {
+      warn('Both --autofix and --no-autofix were given; keeping the current setting.');
+    }
+    const enable =
+      flags['no-autofix'] && !flags.autofix ? false : flags.autofix && !flags['no-autofix'] ? true : undefined;
+    try {
+      const res = applyAutofixSetting({ enable, dryRun: flags['dry-run'], projectRoot });
+      info(describeAutofix(res.enabled));
+    } catch (err) {
+      warn(`Could not save the automatic repair setting: ${err.message}`);
+    }
+  }
+
   if (errors.length === clients.length) {
     process.exit(1);
   } else if (errors.length > 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.";
+}