engram-mcp-server 1.2.0

package/src/types.ts

@@ -0,0 +1,267 @@
+// ============================================================================
+// Engram MCP Server — Type Definitions
+// ============================================================================
+
+// ─── Database Row Types ─────────────────────────────────────────────────────
+
+export interface SessionRow {
+  id: number;
+  started_at: string;
+  ended_at: string | null;
+  summary: string | null;
+  agent_name: string;
+  project_root: string;
+  tags: string | null;          // JSON array
+  parent_session_id: number | null;
+}
+
+export interface ChangeRow {
+  id: number;
+  session_id: number | null;
+  timestamp: string;
+  file_path: string;
+  change_type: ChangeType;
+  description: string;
+  diff_summary: string | null;
+  impact_scope: ImpactScope;
+}
+
+export interface DecisionRow {
+  id: number;
+  session_id: number | null;
+  timestamp: string;
+  decision: string;
+  rationale: string | null;
+  affected_files: string | null;  // JSON array
+  tags: string | null;            // JSON array
+  status: DecisionStatus;
+  superseded_by: number | null;
+}
+
+export interface FileNoteRow {
+  file_path: string;
+  purpose: string | null;
+  dependencies: string | null;    // JSON array
+  dependents: string | null;      // JSON array
+  layer: ArchLayer | null;
+  last_reviewed: string | null;
+  last_modified_session: number | null;
+  notes: string | null;
+  complexity: Complexity | null;
+}
+
+export interface ConventionRow {
+  id: number;
+  session_id: number | null;
+  timestamp: string;
+  category: ConventionCategory;
+  rule: string;
+  examples: string | null;       // JSON array
+  enforced: boolean;
+}
+
+export interface TaskRow {
+  id: number;
+  session_id: number | null;
+  created_at: string;
+  updated_at: string;
+  title: string;
+  description: string | null;
+  status: TaskStatus;
+  priority: TaskPriority;
+  assigned_files: string | null;  // JSON array
+  tags: string | null;            // JSON array
+  completed_at: string | null;
+  blocked_by: string | null;      // JSON array of task IDs
+}
+
+export interface SnapshotRow {
+  key: string;
+  value: string;
+  updated_at: string;
+  ttl_minutes: number | null;
+}
+
+export interface MilestoneRow {
+  id: number;
+  session_id: number | null;
+  timestamp: string;
+  title: string;
+  description: string | null;
+  version: string | null;
+  tags: string | null;           // JSON array
+}
+
+export interface ScheduledEventRow {
+  id: number;
+  session_id: number | null;
+  created_at: string;
+  title: string;
+  description: string | null;
+  trigger_type: EventTriggerType;
+  trigger_value: string | null;
+  status: EventStatus;
+  triggered_at: string | null;
+  acknowledged_at: string | null;
+  requires_approval: number;       // 0 or 1 (SQLite boolean)
+  action_summary: string | null;
+  action_data: string | null;      // JSON
+  priority: TaskPriority;
+  tags: string | null;             // JSON array
+  recurrence: EventRecurrence | null;
+}
+
+// ─── Enum Types ─────────────────────────────────────────────────────────────
+
+export type ChangeType =
+  | "created"
+  | "modified"
+  | "deleted"
+  | "refactored"
+  | "renamed"
+  | "moved"
+  | "config_changed";
+
+export type ImpactScope =
+  | "local"       // Single file change
+  | "module"      // Affects a module/package
+  | "cross_module"// Affects multiple modules
+  | "global";     // Architecture-level change
+
+export type DecisionStatus =
+  | "active"
+  | "superseded"
+  | "deprecated"
+  | "experimental";
+
+export type ArchLayer =
+  | "ui"
+  | "viewmodel"
+  | "domain"
+  | "data"
+  | "network"
+  | "database"
+  | "di"
+  | "util"
+  | "test"
+  | "config"
+  | "build"
+  | "other";
+
+export type Complexity =
+  | "trivial"
+  | "simple"
+  | "moderate"
+  | "complex"
+  | "critical";
+
+export type ConventionCategory =
+  | "naming"
+  | "architecture"
+  | "styling"
+  | "testing"
+  | "git"
+  | "documentation"
+  | "error_handling"
+  | "performance"
+  | "security"
+  | "other";
+
+export type TaskStatus =
+  | "backlog"
+  | "in_progress"
+  | "blocked"
+  | "review"
+  | "done"
+  | "cancelled";
+
+export type TaskPriority =
+  | "critical"
+  | "high"
+  | "medium"
+  | "low";
+
+export type EventTriggerType =
+  | "next_session"
+  | "datetime"
+  | "task_complete"
+  | "manual";
+
+export type EventStatus =
+  | "pending"
+  | "triggered"
+  | "acknowledged"
+  | "executed"
+  | "cancelled"
+  | "snoozed";
+
+export type EventRecurrence =
+  | "once"
+  | "every_session"
+  | "daily"
+  | "weekly";
+
+// ─── Response Types ─────────────────────────────────────────────────────────
+
+export interface SessionContext {
+  session_id: number;
+  previous_session: {
+    id: number;
+    summary: string | null;
+    ended_at: string | null;
+    agent: string;
+  } | null;
+  changes_since_last: {
+    recorded: ChangeRow[];
+    git_log: string;
+  };
+  active_decisions: DecisionRow[];
+  active_conventions: ConventionRow[];
+  open_tasks: TaskRow[];
+  project_snapshot_age_minutes: number | null;
+  message: string;
+}
+
+export interface ProjectSnapshot {
+  project_root: string;
+  file_tree: string[];
+  total_files: number;
+  file_notes: FileNoteRow[];
+  recent_decisions: DecisionRow[];
+  active_conventions: ConventionRow[];
+  layer_distribution: Record<string, number>;
+  generated_at: string;
+}
+
+export interface MemoryStats {
+  total_sessions: number;
+  total_changes: number;
+  total_decisions: number;
+  total_file_notes: number;
+  total_conventions: number;
+  total_tasks: number;
+  total_milestones: number;
+  oldest_session: string | null;
+  newest_session: string | null;
+  most_changed_files: Array<{ file_path: string; change_count: number }>;
+  database_size_kb: number;
+}
+
+export interface CompactionResult {
+  sessions_compacted: number;
+  changes_summarized: number;
+  storage_freed_kb: number;
+}
+
+export interface ConfigRow {
+  key: string;
+  value: string;
+  updated_at: string;
+}
+
+export interface BackupInfo {
+  path: string;
+  size_kb: number;
+  created_at: string;
+  database_version: number;
+}

package/src/utils.ts

@@ -0,0 +1,216 @@
+// ============================================================================
+// Engram MCP Server — Utilities
+// ============================================================================
+
+import { execSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import {
+  EXCLUDED_DIRS,
+  LAYER_PATTERNS,
+  MAX_FILE_TREE_DEPTH,
+  MAX_FILE_TREE_ENTRIES,
+  PROJECT_MARKERS,
+} from "./constants.js";
+import type { ArchLayer } from "./types.js";
+
+/**
+ * Auto-detect the project root by walking up from cwd looking for marker files.
+ */
+export function findProjectRoot(startDir?: string): string {
+  // 1. Explicit env var
+  if (process.env.ENGRAM_PROJECT_ROOT) return process.env.ENGRAM_PROJECT_ROOT;
+  if (process.env.PROJECT_ROOT) return process.env.PROJECT_ROOT;
+
+  // 2. Walk up directory tree
+  let dir = startDir || process.cwd();
+  while (dir !== path.dirname(dir)) {
+    for (const marker of PROJECT_MARKERS) {
+      if (fs.existsSync(path.join(dir, marker))) {
+        return dir;
+      }
+    }
+    dir = path.dirname(dir);
+  }
+
+  // 3. Fallback to cwd
+  return process.cwd();
+}
+
+/**
+ * Scan the project file tree, respecting exclusions and depth limits.
+ */
+export function scanFileTree(
+  rootDir: string,
+  maxDepth: number = MAX_FILE_TREE_DEPTH,
+  maxEntries: number = MAX_FILE_TREE_ENTRIES
+): string[] {
+  const files: string[] = [];
+
+  // Merge .engramignore entries with the default exclusion set
+  const exclusions = new Set(EXCLUDED_DIRS);
+  try {
+    const ignorePath = path.join(rootDir, ".engramignore");
+    if (fs.existsSync(ignorePath)) {
+      const lines = fs.readFileSync(ignorePath, "utf-8").split("\n");
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed && !trimmed.startsWith("#")) {
+          exclusions.add(trimmed.replace(/\/$/, "")); // Strip trailing slash
+        }
+      }
+    }
+  } catch { /* .engramignore is optional */ }
+
+  function walk(dir: string, depth: number): void {
+    if (depth > maxDepth || files.length >= maxEntries) return;
+
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    // Sort for deterministic output
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+
+    for (const entry of entries) {
+      if (files.length >= maxEntries) break;
+      if (entry.name.startsWith(".") && entry.isDirectory()) continue;
+
+      if (entry.isDirectory()) {
+        if (exclusions.has(entry.name)) continue;
+        const subPath = path.relative(rootDir, path.join(dir, entry.name));
+        files.push(subPath + "/");
+        walk(path.join(dir, entry.name), depth + 1);
+      } else {
+        const relPath = path.relative(rootDir, path.join(dir, entry.name));
+        files.push(relPath);
+      }
+    }
+  }
+
+  walk(rootDir, 0);
+  return files;
+}
+
+/**
+ * Detect the architectural layer of a file based on its path.
+ */
+export function detectLayer(filePath: string): ArchLayer {
+  const normalized = "/" + filePath.replace(/\\/g, "/");
+  for (const [layer, patterns] of Object.entries(LAYER_PATTERNS)) {
+    for (const pattern of patterns) {
+      if (pattern.test(normalized)) {
+        return layer as ArchLayer;
+      }
+    }
+  }
+  return "other";
+}
+
+/**
+ * Run a git command in the project root. Returns empty string on failure.
+ */
+export function gitCommand(projectRoot: string, command: string): string {
+  try {
+    return execSync(`cd "${projectRoot}" && git ${command}`, {
+      encoding: "utf-8",
+      timeout: 10000,
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Check if the project is a git repository.
+ */
+export function isGitRepo(projectRoot: string): boolean {
+  return fs.existsSync(path.join(projectRoot, ".git"));
+}
+
+/**
+ * Get git log since a given timestamp.
+ */
+export function getGitLogSince(projectRoot: string, since: string, limit: number = 50): string {
+  return gitCommand(
+    projectRoot,
+    `log --name-status --since="${since}" --pretty=format:"[%h] %s (%ar)" -${limit}`
+  );
+}
+
+/**
+ * Get git diff stat (files changed, insertions, deletions).
+ */
+export function getGitDiffStat(projectRoot: string, since: string): string {
+  return gitCommand(projectRoot, `diff --stat HEAD@{${since}} 2>/dev/null`);
+}
+
+/**
+ * Get files changed in git since a timestamp.
+ */
+export function getGitFilesChanged(projectRoot: string, since: string): string[] {
+  const result = gitCommand(
+    projectRoot,
+    `log --name-only --since="${since}" --pretty=format:"" 2>/dev/null`
+  );
+  if (!result) return [];
+  return [...new Set(result.split("\n").filter(Boolean))];
+}
+
+/**
+ * Get the current git branch name.
+ */
+export function getGitBranch(projectRoot: string): string {
+  return gitCommand(projectRoot, "rev-parse --abbrev-ref HEAD");
+}
+
+/**
+ * Get the latest git commit hash (short).
+ */
+export function getGitHead(projectRoot: string): string {
+  return gitCommand(projectRoot, "rev-parse --short HEAD");
+}
+
+/**
+ * Safely parse a JSON string, returning a default value on failure.
+ */
+export function safeJsonParse<T>(json: string | null | undefined, fallback: T): T {
+  if (!json) return fallback;
+  try {
+    return JSON.parse(json) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Format a response as either JSON or Markdown.
+ */
+export function formatResponse(data: unknown, format: "json" | "markdown" = "json"): string {
+  if (format === "json") {
+    return JSON.stringify(data, null, 2);
+  }
+  // For markdown, we just pretty-print JSON in a code block
+  return "```json\n" + JSON.stringify(data, null, 2) + "\n```";
+}
+
+/**
+ * Calculate minutes between now and a given ISO timestamp.
+ */
+export function minutesSince(isoTimestamp: string): number {
+  const then = new Date(isoTimestamp).getTime();
+  const diff = Date.now() - then;
+  return Math.floor(diff / 60000);
+}
+
+/**
+ * Truncate a string to a max length with ellipsis.
+ */
+export function truncate(str: string, maxLength: number): string {
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength - 3) + "...";
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}