gitmem-mcp 0.2.0

package/bin/gitmem.js

@@ -0,0 +1,383 @@
+#!/usr/bin/env node
+
+/**
+ * GitMem CLI
+ *
+ * Commands:
+ *   gitmem setup     — Output SQL to paste into Supabase SQL Editor (pro/dev)
+ *   gitmem init      — Load starter scars (local JSON or Supabase)
+ *   gitmem configure — Generate .mcp.json entry for Claude Code
+ *   gitmem server    — Start MCP server (default)
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const command = process.argv[2];
+
+function printUsage() {
+  console.log(`
+GitMem — Institutional Memory for AI Coding
+
+Usage:
+  npx gitmem setup      Output SQL for Supabase schema setup (pro/dev tier)
+  npx gitmem init       Load starter scars (auto-detects tier)
+  npx gitmem configure  Generate .mcp.json config for Claude Code
+  npx gitmem server     Start MCP server (default)
+  npx gitmem help       Show this help message
+
+Free Tier (zero config):
+  1. npx gitmem init
+  2. npx gitmem configure
+  3. Copy CLAUDE.md.template into your project
+  4. Start coding — memory is active!
+
+Pro Tier (with Supabase):
+  1. Create free Supabase project → database.new
+  2. npx gitmem setup   (copy SQL → Supabase SQL Editor)
+  3. Get API key for embeddings (OpenAI, OpenRouter, or Ollama)
+  4. npx gitmem configure
+  5. npx gitmem init    (load starter scars into Supabase)
+  6. Copy CLAUDE.md.template into your project
+  7. Start coding — memory is active!
+`);
+}
+
+async function cmdSetup() {
+  try {
+    const sqlPath = join(__dirname, "..", "schema", "setup.sql");
+    const sql = readFileSync(sqlPath, "utf-8");
+    console.log("-- GitMem Schema Setup (Pro/Dev Tier)");
+    console.log("-- Copy and paste this SQL into your Supabase SQL Editor");
+    console.log("-- (Dashboard → SQL Editor → New query → Paste → Run)");
+    console.log("");
+    console.log(sql);
+  } catch {
+    console.error("Error: Could not read setup.sql. Ensure the package is installed correctly.");
+    process.exit(1);
+  }
+}
+
+async function cmdInit() {
+  const supabaseUrl = process.env.SUPABASE_URL;
+  const supabaseKey = process.env.SUPABASE_SERVICE_ROLE_KEY;
+
+  let starterScars;
+  try {
+    const scarsPath = join(__dirname, "..", "schema", "starter-scars.json");
+    starterScars = JSON.parse(readFileSync(scarsPath, "utf-8"));
+  } catch {
+    console.error("Error: Could not read starter-scars.json.");
+    process.exit(1);
+  }
+
+  if (!supabaseUrl || !supabaseKey) {
+    // Free tier: copy starter scars to local .gitmem/ directory
+    console.log("No Supabase credentials found — initializing free tier (local storage).");
+    console.log("");
+
+    const gitmemDir = join(process.cwd(), ".gitmem");
+    if (!existsSync(gitmemDir)) {
+      mkdirSync(gitmemDir, { recursive: true });
+    }
+
+    const learningsPath = join(gitmemDir, "learnings.json");
+    let existing = [];
+    if (existsSync(learningsPath)) {
+      try {
+        existing = JSON.parse(readFileSync(learningsPath, "utf-8"));
+      } catch {
+        existing = [];
+      }
+    }
+
+    // Merge: skip scars that already exist by id
+    const existingIds = new Set(existing.map((s) => s.id));
+    let added = 0;
+    for (const scar of starterScars) {
+      if (!existingIds.has(scar.id)) {
+        existing.push(scar);
+        added++;
+        console.log(`  + ${scar.title}`);
+      } else {
+        console.log(`  = ${scar.title} (already exists)`);
+      }
+    }
+
+    writeFileSync(learningsPath, JSON.stringify(existing, null, 2));
+
+    // Create empty files for other collections
+    for (const file of ["sessions.json", "decisions.json", "scar-usage.json"]) {
+      const filePath = join(gitmemDir, file);
+      if (!existsSync(filePath)) {
+        writeFileSync(filePath, "[]");
+      }
+    }
+
+    console.log("");
+    console.log(`Done: ${added} new scars added to .gitmem/learnings.json`);
+    console.log("");
+    console.log("Add .gitmem/ to your .gitignore:");
+    console.log("  echo '.gitmem/' >> .gitignore");
+    console.log("");
+    console.log("To upgrade to Pro tier (semantic search + Supabase persistence):");
+    console.log("  Set SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY, then run init again.");
+    return;
+  }
+
+  // Pro/Dev tier: load into Supabase via REST API
+  const tablePrefix = process.env.GITMEM_TABLE_PREFIX || "gitmem_";
+  const restUrl = `${supabaseUrl}/rest/v1/${tablePrefix}learnings`;
+
+  console.log(`Loading ${starterScars.length} starter scars into Supabase (${tablePrefix}learnings)...`);
+
+  let loaded = 0;
+  let failed = 0;
+
+  for (const scar of starterScars) {
+    try {
+      const response = await fetch(restUrl, {
+        method: "POST",
+        headers: {
+          apikey: supabaseKey,
+          Authorization: `Bearer ${supabaseKey}`,
+          "Content-Type": "application/json",
+          Prefer: "return=representation,resolution=merge-duplicates",
+          "Content-Profile": "public",
+        },
+        body: JSON.stringify(scar),
+      });
+
+      if (response.ok) {
+        loaded++;
+        console.log(`  ✓ ${scar.title}`);
+      } else {
+        const text = await response.text();
+        failed++;
+        console.error(`  ✗ ${scar.title}: ${text.slice(0, 100)}`);
+      }
+    } catch (err) {
+      failed++;
+      console.error(`  ✗ ${scar.title}: ${err}`);
+    }
+  }
+
+  console.log("");
+  console.log(`Done: ${loaded} loaded, ${failed} failed`);
+
+  if (loaded > 0) {
+    console.log("");
+    console.log("Starter scars are ready! Start a session and try:");
+    console.log('  recall({ plan: "deploy to production" })');
+  }
+}
+
+function cmdConfigure() {
+  const supabaseUrl = process.env.SUPABASE_URL;
+
+  if (!supabaseUrl) {
+    // Free tier config — no env vars needed
+    const config = {
+      mcpServers: {
+        gitmem: {
+          command: "npx",
+          args: ["-y", "@nteg-dev/gitmem"],
+        },
+      },
+    };
+
+    console.log("Free tier — no API keys needed!");
+    console.log("");
+    console.log("Add this to your .mcp.json (Claude Code) or settings (Cursor):");
+    console.log("");
+    console.log(JSON.stringify(config, null, 2));
+    console.log("");
+    console.log("To upgrade to Pro tier (semantic search + cloud persistence):");
+    console.log("  Set SUPABASE_URL and an embedding API key in the env block.");
+  } else {
+    // Pro/Dev tier config
+    const config = {
+      mcpServers: {
+        gitmem: {
+          command: "npx",
+          args: ["-y", "@nteg-dev/gitmem"],
+          env: {
+            SUPABASE_URL: "https://YOUR_PROJECT.supabase.co",
+            SUPABASE_SERVICE_ROLE_KEY: "eyJ...",
+            OPENAI_API_KEY: "sk-...",
+          },
+        },
+      },
+    };
+
+    console.log("Add this to your .mcp.json (Claude Code) or settings (Cursor):");
+    console.log("");
+    console.log(JSON.stringify(config, null, 2));
+    console.log("");
+    console.log("Replace the placeholder values with your actual keys:");
+    console.log("  SUPABASE_URL            — From Supabase Dashboard → Settings → API");
+    console.log("  SUPABASE_SERVICE_ROLE_KEY — From Supabase Dashboard → Settings → API");
+    console.log("  OPENAI_API_KEY          — From platform.openai.com/api-keys");
+    console.log("");
+    console.log("Alternative embedding providers:");
+    console.log("  OPENROUTER_API_KEY=sk-or-...  (instead of OPENAI_API_KEY)");
+    console.log("  OLLAMA_URL=http://localhost:11434  (local, no API key needed)");
+  }
+}
+
+/**
+ * Run session-start directly (for hook scripts that need context without MCP)
+ *
+ * Outputs formatted session context to stdout.
+ * Used by gitmem-hooks SessionStart hook to provide immediate context
+ * without requiring ToolSearch → session_start two-step dance.
+ *
+ * Args: --project <project> --agent <agent>
+ */
+async function cmdSessionStart() {
+  const args = process.argv.slice(3);
+  let project = "orchestra_dev";
+  let agentIdentity = undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--project" && args[i + 1]) project = args[i + 1];
+    if (args[i] === "--agent" && args[i + 1]) agentIdentity = args[i + 1];
+  }
+
+  try {
+    const { sessionStart } = await import("../dist/tools/session-start.js");
+    const result = await sessionStart({ project, agent_identity: agentIdentity });
+
+    // Use pre-formatted display from formatStartDisplay() — single source of truth
+    console.log(result.display || "GITMEM SESSION ACTIVE");
+  } catch (error) {
+    console.error("[gitmem session-start]", error.message || error);
+    process.exit(1);
+  }
+}
+
+/**
+ * Run session-refresh directly (re-surface context without new session)
+ *
+ * Args: --project <project>
+ */
+async function cmdSessionRefresh() {
+  const args = process.argv.slice(3);
+  let project = undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--project" && args[i + 1]) project = args[i + 1];
+  }
+
+  try {
+    const { sessionRefresh } = await import("../dist/tools/session-start.js");
+    const result = await sessionRefresh({ project });
+
+    if (!result.session_id) {
+      console.error(result.message || "No active session");
+      process.exit(1);
+    }
+
+    // Format as readable text (same structure as session-start output)
+    const lines = [];
+    lines.push(`GITMEM CONTEXT REFRESHED`);
+    lines.push(``);
+    lines.push(`Session: ${result.session_id} | Agent: ${result.agent} | Refreshed`);
+
+    if (result.last_session) {
+      lines.push(``);
+      lines.push(`Last session: "${result.last_session.title}" (${result.last_session.date})`);
+      if (result.last_session.key_decisions?.length) {
+        lines.push(`  Decisions: ${result.last_session.key_decisions.slice(0, 3).join("; ")}`);
+      }
+    }
+
+    if (result.open_threads?.length) {
+      lines.push(``);
+      lines.push(`Open threads (${result.open_threads.length}):`);
+      for (const thread of result.open_threads.slice(0, 5)) {
+        const text = typeof thread === "string" ? thread : thread.text;
+        const truncated = text && text.length > 80 ? text.slice(0, 77) + "..." : text;
+        lines.push(`  - ${truncated || "[unnamed thread]"}`);
+      }
+      if (result.open_threads.length > 5) {
+        lines.push(`  ... and ${result.open_threads.length - 5} more`);
+      }
+    }
+
+    if (result.relevant_scars?.length) {
+      lines.push(``);
+      lines.push(`Relevant scars (${result.relevant_scars.length}):`);
+      for (const scar of result.relevant_scars) {
+        const sev = (scar.severity || "medium").toUpperCase();
+        lines.push(`  [${sev}] ${scar.title}`);
+        if (scar.description) {
+          lines.push(`    ${scar.description.slice(0, 150)}`);
+        }
+      }
+    }
+
+    if (result.recent_decisions?.length) {
+      lines.push(``);
+      lines.push(`Recent decisions (${result.recent_decisions.length}):`);
+      for (const d of result.recent_decisions) {
+        lines.push(`  - ${d.title} (${d.date})`);
+      }
+    }
+
+    if (result.recent_wins?.length) {
+      lines.push(``);
+      lines.push(`Recent wins (${result.recent_wins.length}):`);
+      for (const w of result.recent_wins) {
+        lines.push(`  - ${w.title} (${w.date})`);
+      }
+    }
+
+    if (result.project_state) {
+      lines.push(``);
+      lines.push(`Project state: ${result.project_state}`);
+    }
+
+    console.log(lines.join("\n"));
+  } catch (error) {
+    console.error("[gitmem session-refresh]", error.message || error);
+    process.exit(1);
+  }
+}
+
+switch (command) {
+  case "setup":
+    cmdSetup();
+    break;
+  case "init":
+    cmdInit();
+    break;
+  case "configure":
+    cmdConfigure();
+    break;
+  case "session-start":
+    cmdSessionStart();
+    break;
+  case "session-refresh":
+    cmdSessionRefresh();
+    break;
+  case "server":
+  case "--stdio":
+    import("../dist/index.js");
+    break;
+  case "help":
+  case "--help":
+  case "-h":
+    printUsage();
+    break;
+  case undefined:
+    // Default: start MCP server (npx @nteg-dev/gitmem should start serving)
+    import("../dist/index.js");
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    printUsage();
+    process.exit(1);
+}

package/dist/commands/check.d.ts

@@ -0,0 +1,33 @@
+/**
+ * GitMem Check Command
+ *
+ * Diagnostic CLI command for health checks and benchmarks.
+ *
+ * Usage:
+ *   npx gitmem check           — Quick health check (~5s)
+ *   npx gitmem check --full    — Full diagnostic (~30s)
+ *   npx gitmem check --output report.json
+ *
+ * Issue: OD-584
+ */
+/**
+ * Command options
+ */
+interface CheckOptions {
+    full: boolean;
+    output?: string;
+}
+/**
+ * Parse command line arguments
+ */
+export declare function parseArgs(args: string[]): CheckOptions;
+/**
+ * Main check command
+ */
+export declare function runCheck(options: CheckOptions): Promise<void>;
+/**
+ * Entry point for CLI
+ */
+export declare function main(args: string[]): Promise<void>;
+export {};
+//# sourceMappingURL=check.d.ts.map

package/dist/commands/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAqBH;;GAEG;AACH,UAAU,YAAY;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,YAAY,CAgBtD;AAkZD;;GAEG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAiFnE;AAED;;GAEG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAGxD"}