@yugabytedb/meko-mcp 1.0.3

package/bin/create-meko-setup.mjs

@@ -0,0 +1,499 @@
+#!/usr/bin/env node
+
+import { parseArgs } from 'node:util';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+import { install, uninstall } from '../lib/installer.mjs';
+import { askChoice, askText, askSecret, askYesNo, close as closePrompts } from '../lib/prompt.mjs';
+import { banner, error, dim } from '../lib/logger.mjs';
+import { startMigration, runChildMigration, readStatus, stopMigration } from '../lib/migrate.mjs';
+
+// ---------------------------------------------------------------------------
+// Flag definitions
+// ---------------------------------------------------------------------------
+
+const options = {
+  url:                { type: 'string' },
+  'api-key':          { type: 'string' },
+  local:              { type: 'boolean', default: false },
+  scope:              { type: 'string',  default: 'user' },
+  name:               { type: 'string',  default: 'meko' },
+  client:             { type: 'string',  default: 'claude-code' },
+  'cursor-hook-mode': { type: 'string',  default: 'hybrid' },
+  'skip-skills':      { type: 'boolean', default: false },
+  'skip-validation':  { type: 'boolean', default: false },
+  'dry-run':          { type: 'boolean', default: false },
+  uninstall:          { type: 'boolean', default: false },
+  verbose:            { type: 'boolean', default: false },
+  yes:                { type: 'boolean', default: false },
+  help:               { type: 'boolean', short: 'h', default: false },
+  version:            { type: 'boolean', short: 'v', default: false },
+
+  // --- Migrate subcommand ---
+  migrate:            { type: 'boolean', default: false },
+  'migrate-status':   { type: 'boolean', default: false },
+  'migrate-stop':     { type: 'boolean', default: false },
+  'with-migrate':     { type: 'boolean', default: false },
+  force:              { type: 'boolean', default: false },
+  rate:               { type: 'string' },
+  'no-extract':       { type: 'boolean', default: false },
+  'run-id':           { type: 'string' },
+  '__migrate-child':  { type: 'boolean', default: false },
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = dirname(__filename);
+
+function readVersion() {
+  const pkgPath = join(__dirname, '..', 'package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  return pkg.version;
+}
+
+const ALL_CLIENTS = ['claude-code', 'claude-desktop', 'cursor'];
+
+function printHelp() {
+  const text = `
+Meko Setup for Claude Clients and Cursor
+
+Install and configure Meko MCP Server in one command.
+
+Usage:
+  create-meko-setup [options]
+
+Examples:
+  # Interactive setup (recommended for first-time users):
+  create-meko-setup
+
+  # Cloud Meko for Claude Code (non-interactive):
+  create-meko-setup --url https://your-mcp.mekodev.com/mcp --api-key "$MEKO_API_KEY" --yes
+
+  # Local Meko with Cursor config:
+  create-meko-setup --client cursor --local --scope project --yes
+
+  # Install on both Claude Code and Claude Desktop at once:
+  create-meko-setup --client claude-code,claude-desktop --local --yes
+
+  # Install on every supported client:
+  create-meko-setup --client all --local --yes
+
+  # Local Meko (docker-compose stack, Claude Code):
+  create-meko-setup --local --yes
+
+Options:
+  --client <list>       Target clients: one or more of claude-code, claude-desktop, cursor.
+                        Comma-separated, or "all" to target every supported client (default: claude-code)
+  --url <url>           MCP server URL (from app.mekodev.com > Datapacks > Connect)
+  --api-key <key>       API key for Cloud Meko authentication
+  --local               Use local Meko at http://localhost:8000/mcp
+  --scope <scope>       Config scope: user or project (default: user)
+  --name <name>         MCP server name in config (default: meko)
+  --cursor-hook-mode    Cursor hook mode: native, claude-compat, hybrid (default: hybrid)
+  --skip-skills         Skip plugin and skills installation
+  --skip-validation     Skip post-install validation
+  --dry-run             Show what would be done without making changes
+  --uninstall           Remove Meko MCP server, skills, and env vars
+  --verbose             Show detailed output
+  --yes                 Accept all defaults (non-interactive)
+  -h, --help            Show this help message
+  -v, --version         Show version
+
+Migrate existing conversations and memories into Meko:
+  --migrate             Start a detached migration of existing Claude Code
+                        and Cursor conversations + CLAUDE.md memories.
+                        Honors --scope (user or project) and --dry-run.
+  --with-migrate        When combined with --yes, kick off --migrate at the
+                        end of a successful install without prompting
+                        (CI-friendly: --local --yes --with-migrate).
+  --migrate-status      Print the status of the latest migration run.
+  --migrate-stop        Stop the running migration (SIGTERM, then SIGKILL).
+  --no-extract          Skip memory extraction; replay conversations only.
+  --rate <n>            Max concurrent MCP calls during migration (default 4).
+  --force               Ignore a live lockfile or re-ingest processed items.
+  --run-id <id>         Target a specific run-id for --migrate-status.
+`.trimStart();
+
+  console.log(text);
+}
+
+function isCloudUrl(url) {
+  return url && !url.includes('localhost') && !url.includes('127.0.0.1');
+}
+
+/**
+ * Parse --client into a deduplicated list of client IDs.
+ * Accepts a single value, a comma-separated list, or the keyword "all".
+ * Returns { clients, invalid } where invalid lists any unknown tokens.
+ */
+function parseClients(raw) {
+  const trimmed = (raw ?? '').trim();
+  if (!trimmed) return { clients: ['claude-code'], invalid: [] };
+  if (trimmed.toLowerCase() === 'all') return { clients: [...ALL_CLIENTS], invalid: [] };
+
+  const tokens = trimmed.split(',').map((t) => t.trim()).filter(Boolean);
+  const invalid = tokens.filter((t) => !ALL_CLIENTS.includes(t));
+  const clients = [...new Set(tokens.filter((t) => ALL_CLIENTS.includes(t)))];
+  return { clients, invalid };
+}
+
+function isValidScope(scope) {
+  return ['user', 'project'].includes(scope);
+}
+
+function isValidCursorHookMode(mode) {
+  return ['native', 'claude-compat', 'hybrid'].includes(mode);
+}
+
+/**
+ * Parse --rate as a positive integer, or throw with a helpful message.
+ * `undefined` passes through (= use the default).
+ */
+function parseRate(raw) {
+  if (raw === undefined || raw === null || raw === '') return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 1 || !Number.isInteger(n)) {
+    throw new Error(`Invalid --rate "${raw}": must be a positive integer.`);
+  }
+  return n;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const { values: flags } = parseArgs({ options, strict: true });
+  const projectRoot = process.cwd();
+
+  // --help
+  if (flags.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  // --version
+  if (flags.version) {
+    console.log(readVersion());
+    process.exit(0);
+  }
+
+  // --- Migrate subcommand dispatch ---
+
+  // Detached child branch: re-entry inside the spawned process.
+  if (flags['__migrate-child']) {
+    if (!flags['run-id']) {
+      error('--__migrate-child requires --run-id');
+      process.exit(1);
+    }
+    if (!flags.url) {
+      error('--__migrate-child requires --url');
+      process.exit(1);
+    }
+    let childRate;
+    try { childRate = parseRate(flags.rate); }
+    catch (err) { error(err.message); process.exit(1); }
+    const code = await runChildMigration({
+      runId: flags['run-id'],
+      scope: flags.scope,
+      url: flags.url,
+      apiKey: process.env.MEKO_API_KEY ?? null,
+      projectRoot,
+      noExtract: flags['no-extract'],
+      force: flags.force,
+      rate: childRate,
+    });
+    process.exit(code);
+  }
+
+  if (flags['migrate-status']) {
+    const out = readStatus({ runId: flags['run-id'] });
+    console.log(out.message);
+    process.exit(out.ok ? 0 : 1);
+  }
+
+  if (flags['migrate-stop']) {
+    const out = await stopMigration();
+    console.log(out.message);
+    process.exit(out.ok ? 0 : 1);
+  }
+
+  if (flags.migrate) {
+    if (!isValidScope(flags.scope)) {
+      error(`Unknown scope "${flags.scope}". Valid values: user, project.`);
+      process.exit(1);
+    }
+    let url = flags.url ?? process.env.MEKO_MCP_URL ?? null;
+    let apiKey = flags['api-key'] ?? process.env.MEKO_API_KEY ?? null;
+    if (flags.local) { url = 'http://localhost:8000/mcp'; apiKey = null; }
+
+    let parentRate;
+    try { parentRate = parseRate(flags.rate); }
+    catch (err) { error(err.message); process.exit(1); }
+
+    const out = await startMigration({
+      url,
+      apiKey,
+      scope: flags.scope,
+      projectRoot,
+      scriptPath: __filename,
+      dryRun: flags['dry-run'],
+      noExtract: flags['no-extract'],
+      force: flags.force,
+      rate: parentRate,
+    });
+    console.log(out.message);
+    process.exit(out.ok ? 0 : 1);
+  }
+
+  const { clients, invalid } = parseClients(flags.client);
+  if (invalid.length > 0) {
+    error(`Unknown client(s): ${invalid.join(', ')}. Valid values: ${ALL_CLIENTS.join(', ')}, all.`);
+    process.exit(1);
+  }
+  if (clients.length === 0) {
+    error(`--client must name at least one of: ${ALL_CLIENTS.join(', ')}, all.`);
+    process.exit(1);
+  }
+
+  // --uninstall
+  if (flags.uninstall) {
+    for (const client of clients) {
+      await uninstall({
+        client,
+        name: flags.name,
+        scope: flags.scope,
+        verbose: flags.verbose,
+        projectRoot,
+        cursorHookMode: flags['cursor-hook-mode'],
+      });
+    }
+    process.exit(0);
+  }
+
+  if (!isValidScope(flags.scope)) {
+    error(`Unknown scope "${flags.scope}". Valid values: user, project.`);
+    process.exit(1);
+  }
+  if (!isValidCursorHookMode(flags['cursor-hook-mode'])) {
+    error(`Unknown --cursor-hook-mode "${flags['cursor-hook-mode']}". Valid values: native, claude-compat, hybrid.`);
+    process.exit(1);
+  }
+
+  let url    = flags.url    ?? null;
+  let apiKey = flags['api-key'] ?? null;
+  let skipSkills = flags['skip-skills'];
+
+  // --local shortcut
+  if (flags.local) {
+    url    = 'http://localhost:8000/mcp';
+    apiKey = null;
+  }
+
+  // Interactive mode: URL not provided and not auto-accepting defaults
+  if (!url && !flags.yes) {
+    banner();
+
+    // Step 1 — connection type
+    const connectionType = await askChoice('Connection type:', [
+      { label: 'Cloud Meko', description: 'Hosted at mekodev.com (requires URL + API key)' },
+      { label: 'Local Meko', description: 'Local docker stack at localhost:8000' },
+    ]);
+
+    if (connectionType === 'Cloud Meko') {
+      // Step 2 — MCP URL
+      url = await askText('MCP server URL (from app.mekodev.com > Datapacks > Connect):');
+
+      // Step 3 — API key
+      apiKey = await askSecret('API key:');
+    } else {
+      url    = 'http://localhost:8000/mcp';
+      apiKey = null;
+    }
+
+    // Step 4 — skills
+    const installSkills = await askYesNo(
+      'Install Meko agent skills plugin? (behavioral guides for MCP tools)',
+      true,
+    );
+    if (!installSkills) {
+      skipSkills = true;
+    }
+  }
+
+  // Validation — URL must be set by now
+  if (!url) {
+    error('MCP server URL is required. Provide --url, --local, or run interactively.');
+    process.exit(1);
+  }
+
+  // Validation — Cloud URL requires an API key
+  if (isCloudUrl(url) && !apiKey) {
+    apiKey = process.env.MEKO_API_KEY ?? null;
+    if (!apiKey) {
+      error(
+        'API key is required for Cloud Meko. ' +
+        'Provide --api-key, set MEKO_API_KEY env var, or run interactively.',
+      );
+      process.exit(1);
+    }
+    dim('Using API key from MEKO_API_KEY environment variable.');
+  }
+
+  // Install — loop through each selected client sequentially so failures
+  // for one client don't abort the others.
+  const errors = [];
+  for (const client of clients) {
+    try {
+      await install({
+        url,
+        apiKey,
+        scope:          flags.scope,
+        name:           flags.name,
+        skipSkills,
+        skipValidation: flags['skip-validation'],
+        dryRun:         flags['dry-run'],
+        verbose:        flags.verbose,
+        yes:            flags.yes,
+        client,
+        projectRoot,
+        cursorHookMode: flags['cursor-hook-mode'],
+      });
+    } catch (err) {
+      errors.push({ client, err });
+      error(`Install for ${client} failed: ${err.message ?? err}`);
+    }
+  }
+
+  if (errors.length === clients.length) {
+    process.exit(1);
+  } else if (errors.length > 0) {
+    // Partial success — exit non-zero so CI notices, but keep the successful
+    // installs in place.
+    process.exit(2);
+  }
+
+  // Post-install migration handling:
+  //   - --yes --with-migrate → kick off a detached migration, no prompt
+  //   - --yes (no --with-migrate) → silent; print a one-liner tip
+  //   - interactive (not --yes), TTY → dry-run enumerate, prompt Y/n
+  //   - --dry-run install → skip entirely (we don't want side effects)
+  if (!flags['dry-run']) {
+    if (flags['with-migrate']) {
+      await runUnattendedMigration({
+        url,
+        apiKey,
+        scope: flags.scope,
+        projectRoot,
+      });
+    } else if (flags.yes) {
+      console.log('');
+      dim('Tip: run `create-meko-setup --migrate` to import existing conversations and memories.');
+    } else if (process.stdin.isTTY) {
+      await maybeOfferMigration({
+        url,
+        apiKey,
+        scope: flags.scope,
+        projectRoot,
+      });
+    }
+  }
+}
+
+/**
+ * Unattended migration — used by --yes --with-migrate.
+ * No prompts; errors are surfaced but do not fail the install.
+ */
+async function runUnattendedMigration({ url, apiKey, scope, projectRoot }) {
+  try {
+    const out = await startMigration({
+      url,
+      apiKey,
+      scope,
+      projectRoot,
+      scriptPath: __filename,
+    });
+    console.log('');
+    console.log(out.message);
+    if (!out.ok) {
+      // Don't fail the install; the user can retry with --migrate.
+      dim('Migration did not start cleanly. Install succeeded; try `create-meko-setup --migrate` later.');
+    }
+  } catch (err) {
+    dim(`Migration could not be started: ${err.message ?? err}`);
+  }
+}
+
+/**
+ * Dry-run enumerate the user's local data; if anything is migratable, ask
+ * whether to kick off the detached migration. Any error here is non-fatal —
+ * install has already succeeded.
+ */
+async function maybeOfferMigration({ url, apiKey, scope, projectRoot }) {
+  try {
+    const dry = await startMigration({
+      url,
+      apiKey,
+      scope,
+      projectRoot,
+      scriptPath: __filename,
+      dryRun: true,
+    });
+    const s = dry?.message?.match(/Claude Code sessions: *(\d+)/);
+    const c = dry?.message?.match(/Cursor sessions: *(\d+)/);
+    const m = dry?.message?.match(/Memory items \(MD\): *(\d+)/);
+    const counts = {
+      claude: s ? Number(s[1]) : 0,
+      cursor: c ? Number(c[1]) : 0,
+      memory: m ? Number(m[1]) : 0,
+    };
+    const total = counts.claude + counts.cursor + counts.memory;
+    if (total === 0) return;
+
+    console.log('');
+    dim(
+      `Found existing data to migrate: ` +
+      `${counts.claude} Claude Code sessions, ` +
+      `${counts.cursor} Cursor sessions, ` +
+      `${counts.memory} memory items.`,
+    );
+    const proceed = await askYesNo(
+      'Migrate existing conversations and memories into Meko now? ' +
+      '(runs in the background; check with --migrate-status)',
+      true,
+    );
+    if (!proceed) {
+      dim('Skipped. Run `create-meko-setup --migrate` later when you\'re ready.');
+      return;
+    }
+    const out = await startMigration({
+      url,
+      apiKey,
+      scope,
+      projectRoot,
+      scriptPath: __filename,
+    });
+    console.log(out.message);
+  } catch (err) {
+    // Don't fail the whole install if the migration prompt hiccups.
+    dim(`Skipped migration offer: ${err.message ?? err}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Entry
+// ---------------------------------------------------------------------------
+
+try {
+  await main();
+} catch (err) {
+  error(err.message ?? err);
+  process.exit(1);
+} finally {
+  closePrompts();
+}

package/lib/claude-code.mjs

@@ -0,0 +1,14 @@
+/**
+ * Backward-compatible exports.
+ * Legacy callers importing ./claude-code.mjs continue to work, but all logic
+ * now routes through the multi-client installer with Claude Code selected.
+ */
+import { install as installGeneric, uninstall as uninstallGeneric } from "./installer.mjs";
+
+export async function install(options) {
+  return installGeneric({ ...options, client: "claude-code" });
+}
+
+export async function uninstall(options = {}) {
+  return uninstallGeneric({ ...options, client: "claude-code" });
+}