@yugabytedb/meko-mcp 1.0.3

package/lib/migrate/claude-parser.mjs

@@ -0,0 +1,306 @@
+/**
+ * claude-parser.mjs — Pure-ESM, streaming Claude Code transcript parser.
+ *
+ * Ported from skills/hooks-handlers/lib/capture.js, but:
+ *   - no CLI / side effects; only exports
+ *   - streaming via readline so sessions larger than available RAM
+ *     don't need to be loaded whole
+ *   - filters isSidechain / isMeta / attachment-type entries up front
+ *     (the hook-side version doesn't need to because it runs live)
+ *
+ * Kept deliberately independent of `skills/hooks-handlers/lib/capture.js`:
+ * installer packages ship without that sibling directory, and mixing
+ * CommonJS side-effect-heavy hook code into an ESM installer costs more
+ * than the ~150 LOC of parser logic duplicated here.
+ */
+
+import fs from "node:fs";
+import readline from "node:readline";
+
+export const MAX_THINKING_LEN = Number(process.env.MEKO_MAX_THINKING_LEN ?? 2000);
+export const MAX_TOOL_INPUT_LEN = Number(process.env.MEKO_MAX_TOOL_INPUT_LEN ?? 500);
+export const MAX_TOOL_RESULT_LEN = Number(process.env.MEKO_MAX_TOOL_RESULT_LEN ?? 3000);
+
+const SKIP_INPUT_PATTERN =
+  /^<(system-reminder|command-|local-command|available-deferred)/;
+
+export function truncate(str, max) {
+  if (!str || str.length <= max) return str;
+  return str.slice(0, max) + "... [truncated]";
+}
+
+export function extractText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts = [];
+  for (const b of content) {
+    if (typeof b === "string") { parts.push(b); continue; }
+    if (b && b.type === "text" && typeof b.text === "string") parts.push(b.text);
+  }
+  return parts.join("\n");
+}
+
+export function extractThinking(content) {
+  if (!Array.isArray(content)) return "";
+  const parts = [];
+  for (const b of content) {
+    if (b && b.type === "thinking" && typeof b.thinking === "string") {
+      parts.push(truncate(b.thinking, MAX_THINKING_LEN));
+    }
+  }
+  return parts.join("\n");
+}
+
+export function extractToolCalls(content) {
+  if (!Array.isArray(content)) return "";
+  const parts = [];
+  for (const b of content) {
+    if (!b || b.type !== "tool_use") continue;
+    const name = b.name || "unknown";
+    let inputStr = "";
+    if (b.input && typeof b.input === "object") {
+      try {
+        inputStr = truncate(JSON.stringify(b.input), MAX_TOOL_INPUT_LEN);
+      } catch {
+        inputStr = "(unserializable)";
+      }
+    }
+    parts.push(`TOOL CALL: ${name}(${inputStr})`);
+  }
+  return parts.join("\n");
+}
+
+export function isToolResultMessage(msg) {
+  if (msg?.toolUseResult != null) return true;
+  const content = msg?.message?.content;
+  if (Array.isArray(content)) {
+    return content.some((b) => b && b.type === "tool_result");
+  }
+  return false;
+}
+
+export function extractToolResultContent(msg) {
+  const parts = [];
+  const content = msg?.message?.content;
+  if (Array.isArray(content)) {
+    for (const b of content) {
+      if (!b || b.type !== "tool_result") continue;
+      const inner = b.content;
+      if (typeof inner === "string") {
+        parts.push(truncate(inner, MAX_TOOL_RESULT_LEN));
+      } else if (Array.isArray(inner)) {
+        for (const ib of inner) {
+          if (ib && ib.type === "text" && typeof ib.text === "string") {
+            parts.push(truncate(ib.text, MAX_TOOL_RESULT_LEN));
+          }
+        }
+      }
+    }
+  }
+  if (!parts.length && typeof msg?.toolUseResult === "string") {
+    parts.push(truncate(msg.toolUseResult, MAX_TOOL_RESULT_LEN));
+  }
+  if (parts.length === 0) return "";
+  return "TOOL RESULT:\n" + parts.join("\n---\n");
+}
+
+/**
+ * Should this JSON entry be dropped before we start pairing turns?
+ * Mirrors the plan: skip sidechains, meta turns, and the non-message types.
+ *
+ * @param {any} obj
+ * @returns {boolean}
+ */
+export function isSkippable(obj) {
+  if (!obj || typeof obj !== "object") return true;
+  if (obj.isSidechain === true) return true;
+  if (obj.isMeta === true) return true;
+  const t = obj.type;
+  if (t === "attachment" || t === "file-history-snapshot" || t === "custom-title") {
+    return true;
+  }
+  if (t !== "user" && t !== "assistant") return true;
+  return false;
+}
+
+/**
+ * Stream a JSONL session and emit paired user↔assistant exchanges.
+ *
+ * Uses `readline.createInterface` with a file read stream — the file
+ * is never fully materialized in memory, even at 100+ MB.
+ *
+ * Truncated-trailing-line handling: readline drops a trailing partial
+ * line silently when the input stream ends without a newline. That is
+ * exactly the behaviour we want for "in-progress" session files: the
+ * partial JSON gets dropped rather than failing the whole run.
+ *
+ * @param {string} sessionPath
+ * @returns {Promise<{
+ *   sessionUuid: string,
+ *   firstUserText: string,
+ *   cwd: string,
+ *   gitBranch: string|null,
+ *   startedAt: string|null,
+ *   messageCount: number,
+ *   exchanges: Array<{user_uuid: string, input: string, output: string, reasoning: string, timestamp: string}>,
+ *   partial: boolean,
+ * }>}
+ */
+export async function parseSessionStream(sessionPath) {
+  let stat;
+  try { stat = fs.statSync(sessionPath); } catch { stat = null; }
+  let partial = false;
+  if (stat) {
+    try {
+      const fd = fs.openSync(sessionPath, "r");
+      const buf = Buffer.alloc(1);
+      if (stat.size > 0) fs.readSync(fd, buf, 0, 1, stat.size - 1);
+      fs.closeSync(fd);
+      const recent = stat.mtimeMs > Date.now() - 60_000;
+      const endsNL = stat.size === 0 || buf[0] === 0x0a;
+      partial = recent && !endsNL;
+    } catch { /* ignore */ }
+  }
+
+  const rl = readline.createInterface({
+    input: fs.createReadStream(sessionPath, { encoding: "utf8" }),
+    crlfDelay: Infinity,
+  });
+
+  // Metadata we collect in a single streaming pass.
+  let firstUserText = "";
+  let cwd = "";
+  let gitBranch = null;
+  let startedAt = null;
+  let messageCount = 0;
+
+  // Turn-assembly state.
+  const exchanges = [];
+  let current = null;
+
+  for await (const raw of rl) {
+    const line = raw.trim();
+    if (!line) continue;
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    messageCount++;
+    if (!cwd && typeof obj.cwd === "string") cwd = obj.cwd;
+    if (!gitBranch && typeof obj.gitBranch === "string") gitBranch = obj.gitBranch;
+    if (!startedAt && typeof obj.timestamp === "string") startedAt = obj.timestamp;
+    if (!firstUserText && obj.type === "user" && !isSkippable(obj) && !isToolResultMessage(obj)) {
+      const txt = extractText(obj.message?.content);
+      if (txt && !SKIP_INPUT_PATTERN.test(txt)) firstUserText = txt.slice(0, 240);
+    }
+
+    if (isSkippable(obj)) continue;
+
+    if (obj.type === "user" && !isToolResultMessage(obj)) {
+      if (current) {
+        const built = buildExchange(current);
+        if (built) exchanges.push(built);
+      }
+      current = { userMsg: obj, assistantEntries: [], toolResultEntries: [] };
+    } else if (current) {
+      if (obj.type === "assistant") {
+        current.assistantEntries.push(obj);
+      } else if (obj.type === "user" && isToolResultMessage(obj)) {
+        current.toolResultEntries.push(obj);
+      }
+    }
+  }
+  if (current) {
+    const built = buildExchange(current);
+    if (built) exchanges.push(built);
+  }
+
+  return {
+    sessionUuid: baseName(sessionPath),
+    firstUserText,
+    cwd,
+    gitBranch,
+    startedAt,
+    messageCount,
+    exchanges,
+    partial,
+  };
+}
+
+function baseName(p) {
+  const i = p.lastIndexOf("/");
+  const file = i >= 0 ? p.slice(i + 1) : p;
+  return file.replace(/\.jsonl$/, "");
+}
+
+function buildExchange(ex) {
+  const input = extractText(ex.userMsg.message?.content);
+  if (!input || SKIP_INPUT_PATTERN.test(input)) return null;
+  if (ex.assistantEntries.length === 0) return null;
+
+  const outputParts = [];
+  const reasoningParts = [];
+
+  for (const a of ex.assistantEntries) {
+    const content = a.message?.content;
+    if (!Array.isArray(content)) continue;
+    const t = extractText(content);
+    if (t) outputParts.push(t);
+    const thinking = extractThinking(content);
+    if (thinking) reasoningParts.push("THINKING:\n" + thinking);
+    const tc = extractToolCalls(content);
+    if (tc) reasoningParts.push(tc);
+  }
+  for (const tr of ex.toolResultEntries) {
+    const trText = extractToolResultContent(tr);
+    if (trText) reasoningParts.push(trText);
+  }
+
+  return {
+    user_uuid: ex.userMsg.uuid || "unknown",
+    input,
+    output: outputParts.join("\n\n"),
+    reasoning: reasoningParts.join("\n---\n"),
+    timestamp:
+      ex.assistantEntries[ex.assistantEntries.length - 1].timestamp ||
+      ex.userMsg.timestamp ||
+      "",
+  };
+}
+
+/**
+ * Peek just enough of a JSONL session to harvest its metadata
+ * (cwd, gitBranch, startedAt, sessionId). Cheap — stops at the first
+ * parseable line.
+ *
+ * @param {string} sessionPath
+ * @returns {Promise<{cwd: string, gitBranch: string|null, startedAt: string|null, sessionId: string|null}>}
+ */
+export async function peekSessionMetadata(sessionPath) {
+  const rl = readline.createInterface({
+    input: fs.createReadStream(sessionPath, { encoding: "utf8" }),
+    crlfDelay: Infinity,
+  });
+  try {
+    for await (const raw of rl) {
+      const line = raw.trim();
+      if (!line) continue;
+      try {
+        const obj = JSON.parse(line);
+        return {
+          cwd: typeof obj.cwd === "string" ? obj.cwd : "",
+          gitBranch: typeof obj.gitBranch === "string" ? obj.gitBranch : null,
+          startedAt: typeof obj.timestamp === "string" ? obj.timestamp : null,
+          sessionId: typeof obj.sessionId === "string" ? obj.sessionId : null,
+        };
+      } catch {
+        continue;
+      }
+    }
+  } finally {
+    rl.close();
+  }
+  return { cwd: "", gitBranch: null, startedAt: null, sessionId: null };
+}

package/lib/migrate/daemon.mjs

@@ -0,0 +1,67 @@
+/**
+ * daemon.mjs — Detached-child spawn helper and run-id utilities.
+ */
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+/**
+ * `YYYYMMDD-HHMMSS-<6-hex>`.
+ */
+export function generateRunId() {
+  const d = new Date();
+  const pad = (n, w = 2) => String(n).padStart(w, "0");
+  const stamp =
+    d.getUTCFullYear() +
+    pad(d.getUTCMonth() + 1) +
+    pad(d.getUTCDate()) +
+    "-" +
+    pad(d.getUTCHours()) +
+    pad(d.getUTCMinutes()) +
+    pad(d.getUTCSeconds());
+  const rand = crypto.randomBytes(3).toString("hex");
+  return `${stamp}-${rand}`;
+}
+
+/**
+ * Root directory for all migrate runs.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.home]
+ */
+export function migrateRoot(opts = {}) {
+  const home = opts.home ?? process.env.HOME;
+  return path.join(home, ".meko", "migrate");
+}
+
+/**
+ * Spawn a detached child running the installer binary with `--__migrate-child`.
+ *
+ * @param {object} opts
+ * @param {string} opts.scriptPath   Absolute path to create-meko-setup.mjs.
+ * @param {string} opts.runId
+ * @param {string[]} opts.args       Pass-through CLI args (e.g., ["--scope","user"]).
+ * @param {string} opts.logFilePath  File to redirect child stdout+stderr to.
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ * @param {string} [opts.cwd]
+ * @returns {number}                 The detached child's PID.
+ */
+export function forkDetached(opts) {
+  fs.mkdirSync(path.dirname(opts.logFilePath), { recursive: true });
+  const logFd = fs.openSync(opts.logFilePath, "a");
+
+  const child = spawn(
+    process.execPath,
+    [opts.scriptPath, "--__migrate-child", "--run-id", opts.runId, ...opts.args],
+    {
+      detached: true,
+      stdio: ["ignore", logFd, logFd],
+      env: opts.env ?? process.env,
+      cwd: opts.cwd ?? process.cwd(),
+    },
+  );
+  child.unref();
+  return child.pid;
+}

package/lib/migrate/id.mjs

@@ -0,0 +1,83 @@
+/**
+ * id.mjs — Agent-id derivation and seed computation for the migrator.
+ */
+
+import { createHash } from "node:crypto";
+
+/**
+ * Slugify an absolute path the way Claude Code stores project sessions:
+ * `/Users/foo/bar` → `-Users-foo-bar`.
+ *
+ * Matches the on-disk folder names under `~/.claude/projects/`.
+ *
+ * @param {string} cwd - Absolute path.
+ * @returns {string}
+ */
+export function slugifyCwd(cwd) {
+  if (!cwd) return "";
+  return cwd.replace(/[^A-Za-z0-9]/g, "-");
+}
+
+/**
+ * Reverse-derive an absolute path from a Claude-style slug. Used when
+ * scanning `~/.claude/projects/` and matching a session's `cwd` field
+ * against a slugged directory name.
+ *
+ * Note: the slugify is lossy (multiple different paths can collide);
+ * prefer matching on the session's embedded `cwd` field when available.
+ *
+ * @param {string} slug
+ * @returns {string}
+ */
+export function unslugifyCwd(slug) {
+  return slug.replace(/-/g, "/");
+}
+
+/**
+ * @param {string} cwd - Absolute project path.
+ * @returns {string} Agent id, e.g. `claude-code:-Users-foo-bar`.
+ */
+export function agentIdForClaude(cwd) {
+  return `claude-code:${slugifyCwd(cwd)}`;
+}
+
+/**
+ * User-scope agent id for artifacts that aren't tied to a specific project
+ * (e.g., `~/.claude/CLAUDE.md`).
+ */
+export const CLAUDE_CODE_USER_AGENT_ID = "claude-code:user";
+
+/**
+ * @param {string} projectName - Cursor's human-readable project folder name.
+ * @returns {string}
+ */
+export function agentIdForCursor(projectName) {
+  return `cursor:${projectName}`;
+}
+
+/**
+ * Deterministic seed for `conversation_add_message` dedup.
+ * sha256(agentId + ":" + sessionUuid + ":" + messageUuid), truncated.
+ *
+ * @param {string} agentId
+ * @param {string} sessionUuid
+ * @param {string} messageUuid
+ * @returns {string} 32-char hex
+ */
+export function seedFor(agentId, sessionUuid, messageUuid) {
+  return createHash("sha256")
+    .update(`${agentId}:${sessionUuid}:${messageUuid}`)
+    .digest("hex")
+    .slice(0, 32);
+}
+
+/**
+ * Dedup hash for a memory-MD entry.
+ *
+ * @param {string} text
+ * @param {string} [name]
+ * @returns {string} 64-char hex
+ */
+export function memoryHash(text, name = "") {
+  return createHash("sha256").update(`${name}\0${text}`).digest("hex");
+}

package/lib/migrate/lockfile.mjs

@@ -0,0 +1,121 @@
+/**
+ * lockfile.mjs — PID-based lockfile for migration runs.
+ *
+ * Lock contents: {pid, runId, startedAt}. A lock is considered stale
+ * if the PID it names no longer has a live process.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * @typedef {Object} LockInfo
+ * @property {number} pid
+ * @property {string} runId
+ * @property {string} startedAt  ISO timestamp.
+ */
+
+/**
+ * Acquire a lock at `lockPath`. Returns `{acquired: true}` on success,
+ * or `{acquired: false, holder: LockInfo, stale: boolean}` if another
+ * process already holds it.
+ *
+ * @param {string} lockPath
+ * @param {{pid?: number, runId: string}} info
+ * @param {{force?: boolean}} [opts]
+ * @returns {{acquired: true} | {acquired: false, holder: LockInfo, stale: boolean}}
+ */
+export function acquire(lockPath, info, opts = {}) {
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+
+  const existing = read(lockPath);
+  if (existing) {
+    const stale = isStale(existing);
+    if (!stale && !opts.force) {
+      return { acquired: false, holder: existing, stale: false };
+    }
+    // Stale or force — clobber.
+    try {
+      fs.unlinkSync(lockPath);
+    } catch {
+      /* ignore */
+    }
+  }
+
+  const payload = {
+    pid: info.pid ?? process.pid,
+    runId: info.runId,
+    startedAt: new Date().toISOString(),
+  };
+
+  // O_WRONLY | O_CREAT | O_EXCL — fail if another process got here first.
+  try {
+    const fd = fs.openSync(lockPath, "wx");
+    fs.writeSync(fd, JSON.stringify(payload));
+    fs.closeSync(fd);
+    return { acquired: true };
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      const holder = read(lockPath);
+      return {
+        acquired: false,
+        holder: holder ?? { pid: -1, runId: "?", startedAt: "?" },
+        stale: false,
+      };
+    }
+    throw err;
+  }
+}
+
+/**
+ * Release a lock held by this process. Safe to call multiple times.
+ *
+ * @param {string} lockPath
+ */
+export function release(lockPath) {
+  try {
+    const holder = read(lockPath);
+    if (holder && holder.pid !== process.pid) {
+      // Not ours — don't clobber.
+      return;
+    }
+    fs.unlinkSync(lockPath);
+  } catch {
+    /* best effort */
+  }
+}
+
+/**
+ * Read a lockfile, returning null if missing or unreadable.
+ *
+ * @param {string} lockPath
+ * @returns {LockInfo | null}
+ */
+export function read(lockPath) {
+  try {
+    const raw = fs.readFileSync(lockPath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Is the process named in `info` no longer alive?
+ *
+ * Uses `process.kill(pid, 0)` which throws ESRCH for dead PIDs and
+ * succeeds (or throws EPERM) for live ones.
+ *
+ * @param {LockInfo} info
+ * @returns {boolean}
+ */
+export function isStale(info) {
+  if (!info || typeof info.pid !== "number" || info.pid <= 0) return true;
+  try {
+    process.kill(info.pid, 0);
+    return false; // live
+  } catch (err) {
+    if (err.code === "EPERM") return false; // live, owned by another user
+    return true; // ESRCH or similar
+  }
+}

package/lib/migrate/logger.mjs

@@ -0,0 +1,79 @@
+/**
+ * logger.mjs — NDJSON event logger for migration runs.
+ *
+ * One JSON object per line. No dependency on the node logger used by
+ * the installer (this one writes to a file fd on disk, not stderr).
+ */
+
+import fs from "node:fs";
+
+/**
+ * @typedef {Object} Logger
+ * @property {(event: string, fields?: object) => void} info
+ * @property {(event: string, fields?: object) => void} warn
+ * @property {(event: string, fields?: object) => void} error
+ * @property {() => void} close
+ */
+
+/**
+ * Create a logger that appends NDJSON to `logPath`. Also forwards to
+ * `process.stderr` when `tee` is true (useful in foreground dry-runs).
+ *
+ * @param {string} logPath - Absolute file path.
+ * @param {object} [opts]
+ * @param {string} [opts.runId]
+ * @param {boolean} [opts.tee]
+ * @returns {Logger}
+ */
+export function createLogger(logPath, opts = {}) {
+  const fd = fs.openSync(logPath, "a");
+  const runId = opts.runId;
+  const tee = !!opts.tee;
+
+  function emit(level, event, fields) {
+    const line =
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        level,
+        event,
+        runId,
+        ...(fields || {}),
+      }) + "\n";
+    try {
+      fs.writeSync(fd, line);
+    } catch {
+      /* best effort */
+    }
+    if (tee) {
+      process.stderr.write(line);
+    }
+  }
+
+  return {
+    info: (event, fields) => emit("info", event, fields),
+    warn: (event, fields) => emit("warn", event, fields),
+    error: (event, fields) => emit("error", event, fields),
+    close() {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        /* best effort */
+      }
+    },
+  };
+}
+
+/**
+ * Create a no-op logger. Useful in tests or `--dry-run` before the
+ * run directory exists.
+ *
+ * @returns {Logger}
+ */
+export function nullLogger() {
+  return {
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    close: () => {},
+  };
+}