engrm 0.1.0

package/src/server.ts

@@ -0,0 +1,436 @@
+#!/usr/bin/env bun
+/**
+ * Engrm — MCP Server entry point.
+ *
+ * Registers MCP tools and runs over stdio transport.
+ * Creates a single MemDatabase instance shared across all tools.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import { loadConfig, getDbPath, configExists } from "./config.js";
+import { MemDatabase } from "./storage/sqlite.js";
+import { saveObservation } from "./tools/save.js";
+import { searchObservations } from "./tools/search.js";
+import { getObservations } from "./tools/get.js";
+import { getTimeline } from "./tools/timeline.js";
+import { pinObservation } from "./tools/pin.js";
+import {
+  buildSessionContext,
+  formatContextForInjection,
+} from "./context/inject.js";
+import { runDueJobs } from "./lifecycle/scheduler.js";
+import { SyncEngine } from "./sync/engine.js";
+import { backfillEmbeddings } from "./embeddings/backfill.js";
+
+// --- Bootstrap ---
+
+if (!configExists()) {
+  console.error(
+    "Engrm is not configured. Run: engrm init --manual"
+  );
+  process.exit(1);
+}
+
+const config = loadConfig();
+const db = new MemDatabase(getDbPath());
+
+// Double-injection guard: track whether context has been served this session.
+// Stdio transport = 1 process per session, so module-level flag is safe.
+let contextServed = false;
+
+// Agent auto-detection: resolved lazily from MCP clientInfo on first tool call.
+let _detectedAgent: string | null = null;
+
+/**
+ * Get the detected agent name. Reads from MCP clientInfo (set during initialize).
+ * Resolved lazily because initialize happens after connect().
+ */
+function getDetectedAgent(): string {
+  if (_detectedAgent) return _detectedAgent;
+  try {
+    const clientInfo = server.server.getClientVersion();
+    if (clientInfo?.name) {
+      _detectedAgent = resolveAgentName(clientInfo.name);
+      return _detectedAgent;
+    }
+  } catch {
+    // Not yet initialized — use default
+  }
+  return "claude-code";
+}
+
+/**
+ * Map MCP clientInfo.name to our agent identifiers.
+ */
+function resolveAgentName(clientName: string): string {
+  const name = clientName.toLowerCase();
+  if (name.includes("codex")) return "codex-cli";
+  if (name.includes("cursor")) return "cursor";
+  if (name.includes("windsurf")) return "windsurf";
+  if (name.includes("cline")) return "cline";
+  if (name.includes("copilot")) return "vscode-copilot";
+  if (name.includes("zed")) return "zed";
+  if (name.includes("claude")) return "claude-code";
+  return clientName;
+}
+
+// Sync engine (started in main, needs module-level ref for shutdown)
+let syncEngine: SyncEngine | null = null;
+
+// Graceful shutdown
+process.on("SIGINT", () => {
+  syncEngine?.stop();
+  db.close();
+  process.exit(0);
+});
+process.on("SIGTERM", () => {
+  syncEngine?.stop();
+  db.close();
+  process.exit(0);
+});
+
+// --- MCP Server ---
+
+const server = new McpServer({
+  name: "engrm",
+  version: "0.1.0",
+});
+
+// Tool: save_observation
+server.tool(
+  "save_observation",
+  "Save an observation to memory",
+  {
+    type: z.enum([
+      "bugfix",
+      "discovery",
+      "decision",
+      "pattern",
+      "change",
+      "feature",
+      "refactor",
+      "digest",
+    ]),
+    title: z.string().describe("Brief title"),
+    narrative: z.string().optional().describe("What happened and why"),
+    facts: z.array(z.string()).optional().describe("Key facts"),
+    concepts: z.array(z.string()).optional().describe("Tags"),
+    files_read: z
+      .array(z.string())
+      .optional()
+      .describe("Files read (project-relative)"),
+    files_modified: z
+      .array(z.string())
+      .optional()
+      .describe("Files modified (project-relative)"),
+    sensitivity: z.enum(["shared", "personal", "secret"]).optional(),
+    session_id: z.string().optional(),
+    supersedes: z.number().optional().describe("ID of observation this replaces"),
+  },
+  async (params) => {
+    const result = await saveObservation(db, config, { ...params, agent: getDetectedAgent() });
+
+    if (!result.success) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Not saved: ${result.reason}`,
+          },
+        ],
+      };
+    }
+
+    if (result.merged_into) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Merged into observation #${result.merged_into} (quality: ${result.quality_score?.toFixed(2)})`,
+          },
+        ],
+      };
+    }
+
+    // Handle supersession: archive the old observation
+    let supersessionNote = "";
+    if (params.supersedes && result.observation_id) {
+      const superseded = db.supersedeObservation(
+        params.supersedes,
+        result.observation_id
+      );
+      if (superseded) {
+        supersessionNote = `, supersedes #${params.supersedes}`;
+      }
+    }
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `Saved observation #${result.observation_id} (quality: ${result.quality_score?.toFixed(2)}${supersessionNote})`,
+        },
+      ],
+    };
+  }
+);
+
+// Tool: search
+server.tool(
+  "search",
+  "Search memory for observations",
+  {
+    query: z.string().describe("Search query"),
+    project_scoped: z.boolean().optional().describe("Scope to project (default: true)"),
+    limit: z.number().optional().describe("Max results (default: 10)"),
+  },
+  async (params) => {
+    const result = await searchObservations(db, params);
+
+    if (result.total === 0) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: result.project
+              ? `No observations found for "${params.query}" in project ${result.project}`
+              : `No observations found for "${params.query}"`,
+          },
+        ],
+      };
+    }
+
+    // Format as compact table
+    const header = "| ID | Type | Q | Title | Created |";
+    const separator = "|---|---|---|---|---|";
+    const rows = result.observations.map((obs) => {
+      const qualityDots = qualityIndicator(obs.quality);
+      const date = obs.created_at.split("T")[0];
+      return `| ${obs.id} | ${obs.type} | ${qualityDots} | ${obs.title} | ${date} |`;
+    });
+
+    const projectLine = result.project
+      ? `Project: ${result.project}\n`
+      : "";
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `${projectLine}Found ${result.total} result(s):\n\n${header}\n${separator}\n${rows.join("\n")}`,
+        },
+      ],
+    };
+  }
+);
+
+// Tool: get_observations
+server.tool(
+  "get_observations",
+  "Get observations by ID",
+  {
+    ids: z.array(z.number()).describe("Observation IDs"),
+  },
+  async (params) => {
+    const result = getObservations(db, params);
+
+    if (result.observations.length === 0) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `No observations found for IDs: ${params.ids.join(", ")}`,
+          },
+        ],
+      };
+    }
+
+    const formatted = result.observations.map((obs) => {
+      const parts = [
+        `## Observation #${obs.id}`,
+        `**Type**: ${obs.type} | **Quality**: ${obs.quality.toFixed(2)} | **Lifecycle**: ${obs.lifecycle}`,
+        `**Title**: ${obs.title}`,
+      ];
+      if (obs.narrative) parts.push(`**Narrative**: ${obs.narrative}`);
+      if (obs.facts) parts.push(`**Facts**: ${obs.facts}`);
+      if (obs.concepts) parts.push(`**Concepts**: ${obs.concepts}`);
+      if (obs.files_modified)
+        parts.push(`**Files modified**: ${obs.files_modified}`);
+      if (obs.files_read) parts.push(`**Files read**: ${obs.files_read}`);
+      parts.push(`**Created**: ${obs.created_at}`);
+      return parts.join("\n");
+    });
+
+    let text = formatted.join("\n\n---\n\n");
+    if (result.not_found.length > 0) {
+      text += `\n\nNot found: ${result.not_found.join(", ")}`;
+    }
+
+    return {
+      content: [{ type: "text" as const, text }],
+    };
+  }
+);
+
+// Tool: timeline
+server.tool(
+  "timeline",
+  "Timeline around an observation",
+  {
+    anchor: z.number().describe("Observation ID to centre on"),
+    depth_before: z.number().optional().describe("Before anchor (default: 3)"),
+    depth_after: z.number().optional().describe("After anchor (default: 3)"),
+    project_scoped: z.boolean().optional().describe("Scope to project (default: true)"),
+  },
+  async (params) => {
+    const result = getTimeline(db, {
+      anchor_id: params.anchor,
+      depth_before: params.depth_before,
+      depth_after: params.depth_after,
+      project_scoped: params.project_scoped,
+    });
+
+    if (result.observations.length === 0) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Observation #${params.anchor} not found`,
+          },
+        ],
+      };
+    }
+
+    const lines = result.observations.map((obs, i) => {
+      const marker = i === result.anchor_index ? "→" : " ";
+      const date = obs.created_at.split("T")[0];
+      return `${marker} #${obs.id} [${date}] ${obs.type}: ${obs.title}`;
+    });
+
+    const projectLine = result.project
+      ? `Project: ${result.project}\n`
+      : "";
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `${projectLine}Timeline around #${params.anchor}:\n\n${lines.join("\n")}`,
+        },
+      ],
+    };
+  }
+);
+
+// Tool: pin_observation
+server.tool(
+  "pin_observation",
+  "Pin/unpin observation",
+  {
+    id: z.number().describe("Observation ID"),
+    pinned: z.boolean().describe("true=pin, false=unpin"),
+  },
+  async (params) => {
+    const result = pinObservation(db, params);
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: result.success
+            ? `Observation #${params.id} ${params.pinned ? "pinned" : "unpinned"}`
+            : `Failed: ${result.reason}`,
+        },
+      ],
+    };
+  }
+);
+
+// Tool: session_context
+server.tool(
+  "session_context",
+  "Load project memory for this session",
+  {
+    max_observations: z.number().optional().describe("Max observations (default: token-budgeted)"),
+  },
+  async (params) => {
+    // Double-injection guard
+    if (contextServed) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: "Context already loaded for this session. Use search for specific queries.",
+          },
+        ],
+      };
+    }
+
+    const context = buildSessionContext(
+      db,
+      process.cwd(),
+      params.max_observations
+        ? { maxCount: params.max_observations }
+        : { tokenBudget: 800 }
+    );
+
+    if (!context || context.observations.length === 0) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: context
+              ? `Project: ${context.project_name} — no prior observations found.`
+              : "Could not detect project.",
+          },
+        ],
+      };
+    }
+
+    contextServed = true;
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: formatContextForInjection(context),
+        },
+      ],
+    };
+  }
+);
+
+// --- Helpers ---
+
+function qualityIndicator(quality: number): string {
+  const filled = Math.round(quality * 5);
+  return "●".repeat(filled) + "○".repeat(5 - filled);
+}
+
+// --- Start ---
+
+async function main(): Promise<void> {
+  // Run lifecycle jobs if due (aging, compaction, purge)
+  runDueJobs(db);
+
+  // Backfill embeddings for observations without vectors (non-blocking)
+  if (db.vecAvailable) {
+    backfillEmbeddings(db, 100).catch(() => {});
+  }
+
+  // Start sync engine (no-op if not configured)
+  syncEngine = new SyncEngine(db, config);
+  syncEngine.start();
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((error) => {
+  console.error("Fatal:", error);
+  db.close();
+  process.exit(1);
+});

package/src/storage/migrations.test.ts

@@ -0,0 +1,244 @@
+import { describe, expect, test, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  runMigrations,
+  getSchemaVersion,
+  LATEST_SCHEMA_VERSION,
+} from "./migrations.js";
+
+let tmpDir: string;
+
+afterEach(() => {
+  if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function createDb(): Database {
+  tmpDir = mkdtempSync(join(tmpdir(), "candengo-mem-migration-test-"));
+  const db = new Database(join(tmpDir, "test.db"));
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec("PRAGMA foreign_keys = ON");
+  return db;
+}
+
+describe("migrations", () => {
+  test("runMigrations creates all tables", () => {
+    const db = createDb();
+    runMigrations(db);
+
+    const tables = db
+      .query<{ name: string }, []>(
+        "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name"
+      )
+      .all()
+      .map((r) => r.name);
+
+    expect(tables).toContain("projects");
+    expect(tables).toContain("observations");
+    expect(tables).toContain("sessions");
+    expect(tables).toContain("session_summaries");
+    expect(tables).toContain("sync_outbox");
+    expect(tables).toContain("sync_state");
+
+    db.close();
+  });
+
+  test("runMigrations creates FTS5 virtual table", () => {
+    const db = createDb();
+    runMigrations(db);
+
+    const tables = db
+      .query<{ name: string }, []>(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name='observations_fts'"
+      )
+      .all();
+    expect(tables.length).toBe(1);
+
+    db.close();
+  });
+
+  test("runMigrations creates indexes", () => {
+    const db = createDb();
+    runMigrations(db);
+
+    const indexes = db
+      .query<{ name: string }, []>(
+        "SELECT name FROM sqlite_master WHERE type='index' AND name LIKE 'idx_%'"
+      )
+      .all()
+      .map((r) => r.name);
+
+    expect(indexes).toContain("idx_observations_project");
+    expect(indexes).toContain("idx_observations_project_lifecycle");
+    expect(indexes).toContain("idx_observations_created");
+    expect(indexes).toContain("idx_outbox_status");
+
+    db.close();
+  });
+
+  test("runMigrations is idempotent", () => {
+    const db = createDb();
+    runMigrations(db);
+    runMigrations(db); // second run should be a no-op
+    expect(getSchemaVersion(db)).toBe(LATEST_SCHEMA_VERSION);
+    db.close();
+  });
+
+  test("getSchemaVersion returns 0 for fresh database", () => {
+    const db = createDb();
+    expect(getSchemaVersion(db)).toBe(0);
+    db.close();
+  });
+
+  test("getSchemaVersion returns latest after migrations", () => {
+    const db = createDb();
+    runMigrations(db);
+    expect(getSchemaVersion(db)).toBe(LATEST_SCHEMA_VERSION);
+    expect(LATEST_SCHEMA_VERSION).toBeGreaterThan(0);
+    db.close();
+  });
+
+  test("CHECK constraints enforce valid observation types", () => {
+    const db = createDb();
+    runMigrations(db);
+
+    // Insert a valid project first
+    db.query(
+      "INSERT INTO projects (canonical_id, name, first_seen_epoch, last_active_epoch) VALUES (?, ?, ?, ?)"
+    ).run("test/project", "test", 0, 0);
+
+    // Valid type should work
+    expect(() => {
+      db.query(
+        `INSERT INTO observations (project_id, type, title, quality, user_id, device_id, created_at, created_at_epoch)
+         VALUES (1, 'bugfix', 'test', 0.5, 'user', 'device', '2024-01-01', 0)`
+      ).run();
+    }).not.toThrow();
+
+    // Invalid type should fail
+    expect(() => {
+      db.query(
+        `INSERT INTO observations (project_id, type, title, quality, user_id, device_id, created_at, created_at_epoch)
+         VALUES (1, 'invalid_type', 'test', 0.5, 'user', 'device', '2024-01-01', 0)`
+      ).run();
+    }).toThrow();
+
+    db.close();
+  });
+
+  test("CHECK constraints enforce quality range", () => {
+    const db = createDb();
+    runMigrations(db);
+
+    db.query(
+      "INSERT INTO projects (canonical_id, name, first_seen_epoch, last_active_epoch) VALUES (?, ?, ?, ?)"
+    ).run("test/project", "test", 0, 0);
+
+    // Quality > 1.0 should fail
+    expect(() => {
+      db.query(
+        `INSERT INTO observations (project_id, type, title, quality, user_id, device_id, created_at, created_at_epoch)
+         VALUES (1, 'bugfix', 'test', 1.5, 'user', 'device', '2024-01-01', 0)`
+      ).run();
+    }).toThrow();
+
+    // Quality < 0.0 should fail
+    expect(() => {
+      db.query(
+        `INSERT INTO observations (project_id, type, title, quality, user_id, device_id, created_at, created_at_epoch)
+         VALUES (1, 'bugfix', 'test', -0.1, 'user', 'device', '2024-01-01', 0)`
+      ).run();
+    }).toThrow();
+
+    db.close();
+  });
+
+  test("CHECK constraints enforce valid lifecycle", () => {
+    const db = createDb();
+    runMigrations(db);
+
+    db.query(
+      "INSERT INTO projects (canonical_id, name, first_seen_epoch, last_active_epoch) VALUES (?, ?, ?, ?)"
+    ).run("test/project", "test", 0, 0);
+
+    expect(() => {
+      db.query(
+        `INSERT INTO observations (project_id, type, title, quality, lifecycle, user_id, device_id, created_at, created_at_epoch)
+         VALUES (1, 'bugfix', 'test', 0.5, 'deleted', 'user', 'device', '2024-01-01', 0)`
+      ).run();
+    }).toThrow();
+
+    db.close();
+  });
+
+  test("migration v2 adds superseded_by column", () => {
+    const db = createDb();
+    runMigrations(db);
+
+    const columns = db
+      .query<{ name: string }, []>("PRAGMA table_info(observations)")
+      .all()
+      .map((r) => r.name);
+
+    expect(columns).toContain("superseded_by");
+    expect(getSchemaVersion(db)).toBe(LATEST_SCHEMA_VERSION);
+
+    db.close();
+  });
+
+  test("migration v2 creates superseded index", () => {
+    const db = createDb();
+    runMigrations(db);
+
+    const indexes = db
+      .query<{ name: string }, []>(
+        "SELECT name FROM sqlite_master WHERE type='index' AND name = 'idx_observations_superseded'"
+      )
+      .all();
+
+    expect(indexes.length).toBe(1);
+
+    db.close();
+  });
+
+  test("v1 database upgrades to v2 correctly", () => {
+    const db = createDb();
+
+    // Manually run v1 only by setting version ceiling
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA foreign_keys = ON");
+
+    // Run migrations (will apply both v1 and v2)
+    runMigrations(db);
+    expect(getSchemaVersion(db)).toBe(LATEST_SCHEMA_VERSION);
+
+    // Verify superseded_by works with data
+    db.query(
+      "INSERT INTO projects (canonical_id, name, first_seen_epoch, last_active_epoch) VALUES (?, ?, ?, ?)"
+    ).run("test/proj", "test", 0, 0);
+
+    db.query(
+      `INSERT INTO observations (project_id, type, title, quality, user_id, device_id, created_at, created_at_epoch, superseded_by)
+       VALUES (1, 'decision', 'Old decision', 0.5, 'user', 'dev', '2024-01-01', 0, NULL)`
+    ).run();
+
+    db.query(
+      `INSERT INTO observations (project_id, type, title, quality, user_id, device_id, created_at, created_at_epoch, superseded_by)
+       VALUES (1, 'decision', 'New decision', 0.8, 'user', 'dev', '2024-01-01', 0, NULL)`
+    ).run();
+
+    // Set superseded_by
+    db.query("UPDATE observations SET superseded_by = 2 WHERE id = 1").run();
+
+    const superseded = db
+      .query<{ superseded_by: number | null }, [number]>(
+        "SELECT superseded_by FROM observations WHERE id = ?"
+      )
+      .get(1);
+    expect(superseded!.superseded_by).toBe(2);
+
+    db.close();
+  });
+});