engrm 0.1.0 → 0.2.1

package/src/server.ts

@@ -1,436 +0,0 @@
-#!/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

@@ -1,244 +0,0 @@
-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();
-  });
-});