ziprin-context-optimizer 8.0.0

package/src/mcp-event-stream.js

@@ -0,0 +1,179 @@
+'use strict';
+
+/**
+ * MCP Event Stream — runtime publishes; dashboard only observes.
+ * File: .cursor/context-events.jsonl (append-only JSONL)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const EVENTS_REL = '.cursor/context-events.jsonl';
+const MAX_EVENTS = 400;
+
+const EVENT_TYPES = Object.freeze({
+  server_started: 'server_started',
+  server_connected: 'server_connected',
+  tool_registered: 'tool_registered',
+  context_analysis_started: 'context_analysis_started',
+  context_analysis_finished: 'context_analysis_finished',
+  files_selected: 'files_selected',
+  compression_finished: 'compression_finished',
+  health_changed: 'health_changed',
+  server_failed: 'server_failed',
+  server_recovered: 'server_recovered',
+});
+
+function eventsPath(root) {
+  return path.join(root, EVENTS_REL);
+}
+
+function publishEvent(root, partial) {
+  if (!root) return null;
+  const event = {
+    service: partial.service || 'ziprin-context',
+    type: partial.type || 'unknown',
+    status: partial.status || null,
+    health: partial.health || null,
+    tools: partial.tools ?? null,
+    toolsCount: partial.toolsCount ?? (Array.isArray(partial.tools) ? partial.tools.length : null),
+    timestamp: partial.timestamp || new Date().toISOString(),
+    ...partial,
+  };
+  // Keep payload lean for observer
+  delete event.root;
+
+  try {
+    const file = eventsPath(root);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, JSON.stringify(event) + '\n', 'utf8');
+    trimEvents(file);
+    return event;
+  } catch {
+    return null;
+  }
+}
+
+function trimEvents(file) {
+  try {
+    const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/).filter(Boolean);
+    if (lines.length <= MAX_EVENTS) return;
+    const kept = lines.slice(-MAX_EVENTS);
+    fs.writeFileSync(file, kept.join('\n') + '\n', 'utf8');
+  } catch {
+    /* ignore */
+  }
+}
+
+function readEvents(root, limit = 80) {
+  const file = eventsPath(root);
+  if (!fs.existsSync(file)) return [];
+  try {
+    const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/).filter(Boolean);
+    const slice = lines.slice(-limit);
+    const out = [];
+    for (const line of slice) {
+      try {
+        out.push(JSON.parse(line));
+      } catch {
+        /* skip bad line */
+      }
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+function latestByService(events) {
+  const map = {};
+  for (const e of events) {
+    const name = e.service || 'unknown';
+    map[name] = e;
+  }
+  return map;
+}
+
+/**
+ * Derive observer MCP services model from event stream (+ optional health snapshot).
+ */
+function servicesFromEvents(events, healthReport) {
+  const by = latestByService(events);
+  const healthServers = new Map((healthReport?.servers || []).map((s) => [s.name, s]));
+
+  const names = ['ziprin-context', 'serena', 'TypeUI'];
+  const services = names.map((name) => {
+    const ev = by[name];
+    const hs = healthServers.get(name);
+    const raw =
+      ev?.status ||
+      ev?.health ||
+      hs?.state ||
+      'unknown';
+    const normalized =
+      raw === 'healthy' || raw === 'connected'
+        ? 'connected'
+        : raw === 'failed'
+          ? 'failed'
+          : raw === 'restarting' || raw === 'starting'
+            ? 'restarting'
+            : raw === 'degraded'
+              ? 'degraded'
+              : 'unknown';
+
+    return {
+      name,
+      priority: name === 'TypeUI' ? 'required' : 'critical',
+      state: normalized,
+      label:
+        normalized === 'connected'
+          ? 'Connected'
+          : normalized === 'failed'
+            ? 'Failed'
+            : normalized === 'unknown'
+              ? 'Unknown'
+              : 'Recovering',
+      toolsCount: ev?.toolsCount ?? hs?.toolsCount ?? null,
+      lastHeartbeat: ev?.timestamp || hs?.lastHeartbeat || null,
+      lastRestart: hs?.retry?.lastAttempt || null,
+      lastAnalysis:
+        events
+          .filter((e) => e.service === name && e.type === EVENT_TYPES.context_analysis_finished)
+          .slice(-1)[0]?.timestamp || null,
+      lastError:
+        events
+          .filter((e) => e.service === name && (e.type === EVENT_TYPES.server_failed || e.error))
+          .slice(-1)[0]?.error ||
+        hs?.error ||
+        null,
+      error: hs?.error || (normalized === 'failed' ? ev?.error : null) || null,
+      details: { ...(hs?.details || {}), lastEventType: ev?.type || null },
+    };
+  });
+
+  const critical = services.filter((s) => s.priority === 'critical');
+  const criticalFailed = critical.some((s) => s.state === 'failed');
+  const criticalDegraded = critical.some(
+    (s) => s.state === 'degraded' || s.state === 'restarting' || s.state === 'unknown'
+  );
+  const criticalOk = critical.every((s) => s.state === 'connected');
+
+  return {
+    overall: criticalFailed ? 'failed' : criticalOk ? 'connected' : criticalDegraded ? 'degraded' : 'unknown',
+    checkedAt: new Date().toISOString(),
+    mcpConfigOk: healthReport?.mcpConfigOk !== false,
+    source: 'event-stream',
+    services,
+  };
+}
+
+module.exports = {
+  EVENTS_REL,
+  EVENT_TYPES,
+  MAX_EVENTS,
+  eventsPath,
+  publishEvent,
+  readEvents,
+  latestByService,
+  servicesFromEvents,
+};

package/src/mcp-health-cli.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Plugin-local MCP health CLI (CJS).
+ * node src/mcp-health-cli.js [--json] [--workspace <path>]
+ */
+
+const path = require('path');
+const { runHealthCheck } = require('./mcp-lifecycle-manager');
+
+function parseArgs(argv) {
+  let workspace = process.env.ZIPRIN_WORKSPACE || process.cwd();
+  let json = false;
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--json') json = true;
+    if (argv[i] === '--workspace' && argv[i + 1]) workspace = path.resolve(argv[++i]);
+  }
+  return { workspace, json };
+}
+
+const { workspace, json } = parseArgs(process.argv);
+const report = runHealthCheck(workspace, { persist: true });
+
+if (json) {
+  process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+} else {
+  console.error('[ziprin-mcp-health]', 'overall=', report.overall);
+  for (const s of report.servers) {
+    console.error(`  ${s.name}: ${s.state}${s.error ? ' — ' + s.error : ''}`);
+  }
+}
+
+process.exit(report.overall === 'failed' ? 1 : 0);

package/src/mcp-lifecycle-manager.js

@@ -0,0 +1,427 @@
+'use strict';
+
+/**
+ * MCP Lifecycle Manager — observability + config validation + recovery bookkeeping.
+ * Cursor owns actual MCP process spawn; this module makes failures diagnosable
+ * and drives the Inspector dashboard without replacing Cursor Chat.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const HEALTH_REL = '.cursor/ziprin-mcp-health.json';
+const MCP_JSON_REL = '.cursor/mcp.json';
+
+const STATES = Object.freeze({
+  starting: 'starting',
+  connected: 'connected',
+  degraded: 'degraded',
+  failed: 'failed',
+  restarting: 'restarting',
+  unknown: 'unknown',
+});
+
+const MANAGED = [
+  { name: 'ziprin-context', priority: 'critical' },
+  { name: 'serena', priority: 'critical' },
+  { name: 'TypeUI', priority: 'required', optionalInProject: true },
+];
+
+const DEFAULT_RETRY = {
+  maxRetry: 5,
+  baseDelayMs: 500,
+  strategy: 'exponential_backoff',
+};
+
+function healthPath(root) {
+  return path.join(root, HEALTH_REL);
+}
+
+function loadHealth(root) {
+  const file = healthPath(root);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function saveHealth(root, report) {
+  fs.mkdirSync(path.dirname(healthPath(root)), { recursive: true });
+  fs.writeFileSync(healthPath(root), JSON.stringify(report, null, 2), 'utf8');
+  return report;
+}
+
+function readMcpConfig(root) {
+  const file = path.join(root, MCP_JSON_REL);
+  if (!fs.existsSync(file)) {
+    return { ok: false, error: `Missing ${MCP_JSON_REL}`, servers: {} };
+  }
+  try {
+    const raw = fs.readFileSync(file, 'utf8');
+    if (/C:\/Users\/Ziprin\/Desktop/i.test(raw) || /C:\\\\Users\\\\Ziprin\\\\Desktop/i.test(raw)) {
+      return {
+        ok: false,
+        error: 'mcp.json contains absolute Desktop paths — use ${workspaceFolder}',
+        servers: {},
+        absolutePathLeak: true,
+      };
+    }
+    const json = JSON.parse(raw);
+    return { ok: true, servers: json.mcpServers || {}, path: file };
+  } catch (err) {
+    return { ok: false, error: err.message, servers: {} };
+  }
+}
+
+function expandWorkspaceArg(arg, root) {
+  return String(arg || '').replace(/\$\{workspaceFolder\}/g, root.replace(/\\/g, '/'));
+}
+
+function resolveZiprinPluginRoot(monorepoRoot) {
+  if (process.env.ZIPRIN_CONTEXT_PLUGIN) {
+    return path.resolve(process.env.ZIPRIN_CONTEXT_PLUGIN);
+  }
+  const manifestFile = path.join(os.homedir(), '.ziprin', 'ziprin-context-install.json');
+  if (fs.existsSync(manifestFile)) {
+    try {
+      const m = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+      if (m.pluginRoot && fs.existsSync(path.join(m.pluginRoot, 'src', 'mcp-server.js'))) {
+        return m.pluginRoot;
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  const ziprinHome = path.join(os.homedir(), '.ziprin', 'ziprin-context-optimizer');
+  if (fs.existsSync(path.join(ziprinHome, 'src', 'mcp-server.js'))) return ziprinHome;
+  const sibling = path.resolve(monorepoRoot, '../plugin/ziprin-context-optimizer');
+  if (fs.existsSync(path.join(sibling, 'src', 'mcp-server.js'))) return sibling;
+  const vendored = path.resolve(monorepoRoot, 'tooling/ziprin-context-mcp/vendor');
+  if (fs.existsSync(path.join(vendored, 'src', 'mcp-server.js'))) return vendored;
+  return ziprinHome;
+}
+
+function resolveZiprinLauncher(root, cfgEntry) {
+  const fromCfg = (cfgEntry?.args || []).map((a) => expandWorkspaceArg(a, root)).find((a) =>
+    /ziprin-context/i.test(a),
+  );
+  const candidates = [
+    fromCfg,
+    path.join(root, '.cursor/ziprin-context-mcp.mjs'),
+    path.join(root, 'tooling/ziprin-context-mcp/run.mjs'),
+  ].filter(Boolean);
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return candidates[0] || path.join(root, '.cursor/ziprin-context-mcp.mjs');
+}
+
+function probeZiprinContext(root, cfgEntry) {
+  const result = {
+    name: 'ziprin-context',
+    priority: 'critical',
+    state: STATES.starting,
+    toolsExpected: [
+      'ziprin_optimize_context',
+      'ziprin_health',
+      'ziprin_analyze_task',
+      'ziprin_rank_context',
+    ],
+    toolsCount: null,
+    lastHeartbeat: null,
+    lastRestart: null,
+    error: null,
+    details: {},
+  };
+
+  try {
+    const launcher = resolveZiprinLauncher(root, cfgEntry);
+    const pluginRoot = resolveZiprinPluginRoot(root);
+    const serverEntry = path.join(pluginRoot, 'src', 'mcp-server.js');
+    const sdk = path.join(pluginRoot, 'node_modules', '@modelcontextprotocol', 'sdk');
+
+    result.details = {
+      launcher,
+      pluginRoot,
+      serverEntry,
+      node: process.version,
+      configCommand: cfgEntry?.command || null,
+    };
+
+    if (!fs.existsSync(serverEntry)) {
+      result.state = STATES.failed;
+      result.error = `MCP server missing: ${serverEntry}. Run: npx @ziprin/context-optimizer setup --workspace "${root}"`;
+      return result;
+    }
+    if (!fs.existsSync(sdk)) {
+      result.state = STATES.failed;
+      result.error = `MCP SDK not installed in plugin. Run npm install in ${pluginRoot}`;
+      return result;
+    }
+
+    // Syntax / load probe (does not keep MCP running)
+    const probe = spawnSync(
+      process.execPath,
+      [
+        '-e',
+        `const api=require(${JSON.stringify(path.join(pluginRoot, 'src/gateway-api.js').replace(/\\/g, '/'))});` +
+          `const h=api.healthInfo(${JSON.stringify(root.replace(/\\/g, '/'))});` +
+          `process.stdout.write(JSON.stringify({ok:true,version:h.version,status:h.status}));`,
+      ],
+      { encoding: 'utf8', timeout: 15000, windowsHide: true },
+    );
+
+    if (probe.error || probe.status !== 0) {
+      result.state = STATES.failed;
+      result.error = probe.stderr || probe.error?.message || `probe exit ${probe.status}`;
+      return result;
+    }
+
+    let health;
+    try {
+      health = JSON.parse(probe.stdout.trim());
+    } catch {
+      result.state = STATES.degraded;
+      result.error = 'health probe returned non-JSON';
+      return result;
+    }
+
+    result.details.engineVersion = health.version;
+    result.details.engineStatus = health.status;
+    result.toolsCount = result.toolsExpected.length;
+    result.lastHeartbeat = new Date().toISOString();
+    result.state = health.status === 'ready' ? STATES.connected : STATES.degraded;
+
+    // Session activity as soft heartbeat
+    const sessionsFile = path.join(root, '.cursor/context-inspector-sessions.jsonl');
+    if (fs.existsSync(sessionsFile)) {
+      result.details.lastSessionWrite = fs.statSync(sessionsFile).mtime.toISOString();
+    }
+
+    return result;
+  } catch (err) {
+    result.state = STATES.failed;
+    result.error = err.message;
+    result.details.stack = err.stack;
+    return result;
+  }
+}
+
+function probeSerena(root, cfgEntry) {
+  const result = {
+    name: 'serena',
+    priority: 'critical',
+    state: STATES.unknown,
+    toolsCount: null,
+    lastHeartbeat: null,
+    lastRestart: null,
+    error: null,
+    details: { symbolTools: 'configured_in_mcp_json' },
+  };
+
+  if (!cfgEntry) {
+    result.state = STATES.failed;
+    result.error = 'serena missing from .cursor/mcp.json';
+    return result;
+  }
+
+  result.details.command = cfgEntry.command;
+  result.details.argsPreview = (cfgEntry.args || []).slice(0, 4);
+
+  // Cursor owns the process. Config presence + portable args = connected/config-ready.
+  const argsJoined = JSON.stringify(cfgEntry.args || []);
+  if (/C:\/Users\/Ziprin\/Desktop/i.test(argsJoined)) {
+    result.state = STATES.degraded;
+    result.error = 'Serena args use absolute Desktop paths — prefer ${workspaceFolder}';
+    return result;
+  }
+
+  result.state = STATES.connected;
+  result.lastHeartbeat = new Date().toISOString();
+  result.details.symbolTools = 'available_when_cursor_connected';
+  result.details.note = 'Process lifecycle owned by Cursor MCP host';
+  return result;
+}
+
+function probeTypeUI(root, cfgEntry) {
+  const result = {
+    name: 'TypeUI',
+    priority: 'required',
+    state: STATES.unknown,
+    toolsCount: null,
+    lastHeartbeat: null,
+    lastRestart: null,
+    error: null,
+    details: { note: 'Often registered as user-level MCP (user-TypeUI)' },
+  };
+
+  if (cfgEntry) {
+    result.state = STATES.connected;
+    result.details.inProjectMcp = true;
+    result.lastHeartbeat = new Date().toISOString();
+    return result;
+  }
+
+  // Not in project mcp.json — mark degraded (required but user-scoped)
+  result.state = STATES.degraded;
+  result.error = 'Not in project .cursor/mcp.json — enable in Cursor user MCP if needed';
+  return result;
+}
+
+function applyRetryState(prev, next, policy = DEFAULT_RETRY) {
+  const retries = { ...(prev?.retries || {}) };
+  const name = next.name;
+  const entry = retries[name] || { count: 0, lastAttempt: null };
+
+  if (next.state === STATES.failed || next.state === STATES.degraded) {
+    entry.count = Math.min(policy.maxRetry, (entry.count || 0) + 1);
+    entry.lastAttempt = new Date().toISOString();
+    entry.nextDelayMs = Math.min(30_000, policy.baseDelayMs * 2 ** Math.max(0, entry.count - 1));
+    if (entry.count < policy.maxRetry && next.state === STATES.failed) {
+      next.state = STATES.restarting;
+    }
+  } else if (next.state === STATES.connected) {
+    entry.count = 0;
+    entry.nextDelayMs = 0;
+  }
+  retries[name] = entry;
+  next.retry = entry;
+  return { next, retries };
+}
+
+/**
+ * Full health scan for workspace.
+ */
+function runHealthCheck(root, opts = {}) {
+  const startedAt = new Date().toISOString();
+  const prev = loadHealth(root);
+  const cfg = readMcpConfig(root);
+  const servers = [];
+
+  const ziprinCfg = cfg.servers['ziprin-context'];
+  const serenaCfg = cfg.servers.serena;
+  const typeuiCfg = cfg.servers.TypeUI || cfg.servers.typeui || cfg.servers['user-TypeUI'];
+
+  let retries = prev?.retries || {};
+
+  let z = probeZiprinContext(root, ziprinCfg);
+  ({ next: z, retries } = applyRetryState({ retries }, z, opts.retryPolicy));
+  servers.push(z);
+
+  let s = probeSerena(root, serenaCfg);
+  ({ next: s, retries } = applyRetryState({ retries }, s, opts.retryPolicy));
+  servers.push(s);
+
+  let t = probeTypeUI(root, typeuiCfg);
+  ({ next: t, retries } = applyRetryState({ retries }, t, opts.retryPolicy));
+  servers.push(t);
+
+  const criticalFailed = servers
+    .filter((x) => x.priority === 'critical')
+    .some((x) => x.state === STATES.failed);
+  const anyDegraded = servers.some((x) => x.state === STATES.degraded || x.state === STATES.restarting);
+
+  const report = {
+    version: 1,
+    checkedAt: startedAt,
+    workspace: root,
+    mcpConfigOk: cfg.ok,
+    mcpConfigError: cfg.error || null,
+    overall: !cfg.ok || criticalFailed ? STATES.failed : anyDegraded ? STATES.degraded : STATES.connected,
+    servers,
+    retries,
+    logs: [
+      `node=${process.version}`,
+      `platform=${process.platform}`,
+      `mcp.json ok=${cfg.ok}`,
+      ...servers.map((x) => `${x.name}=${x.state}${x.error ? ' err=' + x.error : ''}`),
+    ],
+  };
+
+  if (opts.persist !== false) saveHealth(root, report);
+
+  // Publish for Inspector observers (extension does not own lifecycle).
+  try {
+    const { publishEvent, EVENT_TYPES } = require('./mcp-event-stream');
+    for (const s of servers) {
+      publishEvent(root, {
+        service: s.name,
+        type: EVENT_TYPES.health_changed,
+        status: s.state,
+        health: s.state === 'connected' ? 'healthy' : s.state,
+        toolsCount: s.toolsCount,
+        error: s.error || null,
+        overall: report.overall,
+      });
+    }
+  } catch {
+    /* observer stream optional */
+  }
+
+  return report;
+}
+
+function dashboardServicesModel(report) {
+  if (!report) {
+    return {
+      overall: STATES.unknown,
+      services: MANAGED.map((m) => ({
+        name: m.name,
+        priority: m.priority,
+        state: STATES.unknown,
+        label: 'Unknown',
+        toolsCount: null,
+        lastHeartbeat: null,
+        lastRestart: null,
+        error: null,
+      })),
+    };
+  }
+
+  const labelFor = (state) => {
+    if (state === STATES.connected) return 'Connected';
+    if (state === STATES.restarting || state === STATES.starting) return 'Recovering';
+    if (state === STATES.degraded) return 'Recovering';
+    if (state === STATES.failed) return 'Failed';
+    return 'Unknown';
+  };
+
+  return {
+    overall: report.overall,
+    checkedAt: report.checkedAt,
+    mcpConfigOk: report.mcpConfigOk,
+    services: report.servers.map((s) => ({
+      name: s.name,
+      priority: s.priority,
+      state: s.state,
+      label: labelFor(s.state),
+      toolsCount: s.toolsCount,
+      lastHeartbeat: s.lastHeartbeat,
+      lastRestart: s.retry?.lastAttempt || null,
+      error: s.error,
+      details: s.details,
+    })),
+  };
+}
+
+module.exports = {
+  HEALTH_REL,
+  MCP_JSON_REL,
+  STATES,
+  MANAGED,
+  DEFAULT_RETRY,
+  loadHealth,
+  saveHealth,
+  readMcpConfig,
+  resolveZiprinPluginRoot,
+  expandWorkspaceArg,
+  probeZiprinContext,
+  probeSerena,
+  probeTypeUI,
+  runHealthCheck,
+  dashboardServicesModel,
+};