@yugabytedb/meko-mcp 2.3.0 → 2.5.0

package/bin/create-meko-setup.mjs

@@ -7,7 +7,8 @@ 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 {
   isPackagedInstall,
   MEKO_PRODUCTION_CONSOLE_URL,
@@ -20,6 +21,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 +30,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 +40,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 },
@@ -96,7 +101,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,7 +139,10 @@ 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
+  --api-key <key>       Use an existing Cloud Meko API key instead of signing in
+                        through the browser. Also read from $MEKO_API_KEY.
+                        Required 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
   --scope <scope>       Config scope: user or project (default: user)
                         codex always installs at user scope (no project-level
@@ -144,8 +155,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 +183,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)
@@ -295,6 +315,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 +386,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(
@@ -508,6 +554,10 @@ 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;
 
   // --local shortcut
   if (flags.local) {
@@ -591,7 +641,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,11 +670,24 @@ 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';
       apiKey = null;
@@ -663,25 +726,38 @@ async function main() {
 
   // 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.
+  // browser sign-in, which creates a key 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.
   if (isCloudUrl(url) && !apiKey) {
     apiKey = normalizeApiKey(process.env.MEKO_API_KEY);
+    let signInFailed = false;
     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:'));
+    } else 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 +792,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.";
+}