@shahmilsaari/memory-core 1.0.0 → 1.0.2

package/dist/cli.js

@@ -4,35 +4,23 @@ import {
   OUTPUT_FILES,
   buildContextQuery,
   callChatModel,
-  dedupeMemories,
+  closePool,
   detectProject,
+  findAstDeterministicViolationsForDiff,
   generate,
   getAllowPatterns,
   getChatProviderLabel,
+  getDefaultApplicationContainer,
+  getPool,
   inferProjectArchitectures,
   listProfiles,
-  retrieve,
+  migrateGraphSnapshots,
+  probeGraphSnapshotStore,
   retrieveContextualMemories,
   retrieveMemorySelection,
-  seeds,
-  startWatch
-} from "./chunk-J7SPACA3.js";
-import {
-  embed
-} from "./chunk-HAGRPKR3.js";
-import {
-  closePool,
-  deleteMemories,
-  deleteMemory,
-  getMemory,
-  getPool,
-  listMemories,
   runMigrations,
-  saveMemory,
-  updateMemory,
-  upsertMemory
-} from "./chunk-WUL7HLAA.js";
-import "./chunk-KSLFLWB4.js";
+  seeds
+} from "./chunk-PDQXIKL7.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -40,7 +28,7 @@ import { input, select, confirm } from "@inquirer/prompts";
 import chalk2 from "chalk";
 import ora from "ora";
 import { readFileSync as readFileSync3, writeFileSync as writeFileSync3, existsSync as existsSync3, mkdirSync, appendFileSync, rmSync } from "fs";
-import { join as join3, dirname } from "path";
+import { join as join3, dirname, resolve } from "path";
 import { homedir } from "os";
 
 // src/hook.ts
@@ -173,6 +161,7 @@ function recordViolations(violations, source = "hook") {
 async function promptToSaveViolations(violations) {
   if (!process.stdin.isTTY || violations.length === 0) return;
   try {
+    const app = getDefaultApplicationContainer();
     const { confirm: confirm2, input: input2 } = await import("@inquirer/prompts");
     const save = await confirm2({
       message: "Save a caught violation as a project rule?",
@@ -185,15 +174,12 @@ async function promptToSaveViolations(violations) {
       message: "Why should this rule exist?",
       default: selected.reason ?? selected.issue ?? ""
     });
-    const { embed: embed2 } = await import("./embedding-PAYD2JYW.js");
-    const { upsertMemory: upsertMemory2 } = await import("./db-MF3VKVKH.js");
-    await upsertMemory2({
+    await app.services.memoryEngine.remember({
       type: "rule",
       scope: "project",
       content: selected.rule,
       reason: reason || void 0,
-      tags: ["violation"],
-      embedding: await embed2(selected.rule)
+      tags: ["violation"]
     });
     console.log(chalk.green("  \u2713 Saved as project rule. Run memory-core sync to propagate it.\n"));
   } catch (err) {
@@ -203,9 +189,8 @@ async function promptToSaveViolations(violations) {
 }
 async function loadIgnorePatterns() {
   try {
-    const { listMemories: listMemories2, closePool: closePool2 } = await import("./db-MF3VKVKH.js");
-    const ignores = await listMemories2({ type: "ignore", limit: 1e3 });
-    await closePool2();
+    const app = getDefaultApplicationContainer();
+    const ignores = await app.services.memoryEngine.list({ type: "ignore", limit: 1e3 });
     return ignores.map((ignore) => ignore.content);
   } catch {
     return [];
@@ -526,6 +511,12 @@ Do not include any text outside the JSON object.`;
     console.log(chalk.dim("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
   }
   const deterministicViolations = findDeterministicViolations(diff, rules, avoids, allowPatterns);
+  const astViolations = findAstDeterministicViolationsForDiff(diff, {
+    cwd: process.cwd(),
+    config,
+    rules,
+    reasonLookup: reasonMap
+  });
   let modelViolations = [];
   try {
     const raw = await callChatModel([
@@ -559,7 +550,7 @@ ${diffToSend}` }
     }
   }
   modelViolations = await verifyViolations(diff, modelViolations, allowPatterns, options.debug ?? false);
-  let violations = dedupeViolations([...deterministicViolations, ...modelViolations]);
+  let violations = dedupeViolations([...deterministicViolations, ...astViolations, ...modelViolations]);
   violations = applyAllowPatterns(violations, allowPatterns);
   if (violations.length === 0) {
     console.log(chalk.green("  \u2713 No rule violations \u2014 commit allowed.\n"));
@@ -806,6 +797,7 @@ var GITIGNORE_HEADING = "# memory-core generated files";
 var DEFAULT_OLLAMA_URL = "http://localhost:11434";
 var DEFAULT_EMBEDDING_MODEL = "nomic-embed-text";
 var DEFAULT_CHAT_MODEL = "llama3.2";
+var phase1 = getDefaultApplicationContainer();
 function getEnvPath() {
   const memoryEnv = join3(process.cwd(), ".memory-core.env");
   if (existsSync3(memoryEnv)) return memoryEnv;
@@ -1045,6 +1037,35 @@ function truncate(value, length) {
   if (!value) return "";
   return value.length > length ? `${value.slice(0, Math.max(0, length - 1))}\u2026` : value;
 }
+function toMemoryTableRow(memory) {
+  return {
+    id: memory.id,
+    type: memory.type,
+    scope: memory.scope,
+    title: memory.title,
+    content: memory.content,
+    reason: memory.reason,
+    context: memory.context,
+    tags: memory.tags ?? [],
+    similarity: memory.similarity
+  };
+}
+function toPortableFromRecord(memory) {
+  return toPortableMemory({
+    id: memory.id,
+    type: memory.type,
+    scope: memory.scope,
+    architecture: memory.architecture,
+    project_name: memory.projectName,
+    title: memory.title,
+    content: memory.content,
+    reason: memory.reason,
+    context: memory.context,
+    tags: memory.tags ?? [],
+    content_hash: memory.contentHash,
+    similarity: memory.similarity
+  });
+}
 function printMemoryTable(memories, title = "Rules in memory") {
   console.log(chalk2.bold(`
   ${title} (${memories.length} total)
@@ -1066,6 +1087,23 @@ function getCurrentListArchitectures(config) {
 function printStatusLine(label, value) {
   console.log(`  ${chalk2.dim(label.padEnd(18))} ${value}`);
 }
+function abbreviate(value, max = 96) {
+  return value.length > max ? `${value.slice(0, max - 1)}\u2026` : value;
+}
+function graphStoreFilePath(cwd = process.cwd()) {
+  return join3(cwd, ".memory-core", "graph-snapshots.json");
+}
+function graphBackendLabel(values) {
+  return values.DATABASE_URL ? "postgres (file fallback enabled)" : "file";
+}
+async function getGraphSnapshotCount(cwd = process.cwd()) {
+  try {
+    const snapshots = await phase1.services.graphEngine.listSnapshots(resolve(cwd), 1e4);
+    return snapshots.length;
+  } catch {
+    return null;
+  }
+}
 async function runModelDoctor() {
   const { envPath, values } = readRuntimeEnv();
   const provider2 = getConfiguredProvider(values);
@@ -1151,6 +1189,7 @@ async function printProjectStatus() {
   const statsPath = join3(process.cwd(), ".memory-core-stats.json");
   const dbError = await verifyDatabaseConnection(values.DATABASE_URL ?? "");
   const ollamaError = await verifyOllamaConnection(values.OLLAMA_URL ?? DEFAULT_OLLAMA_URL);
+  const graphCount = await getGraphSnapshotCount(process.cwd());
   console.log(chalk2.bold("\n  memory-core status\n"));
   printStatusLine("Project", config?.projectName ?? process.cwd().split("/").pop() ?? "unknown");
   printStatusLine("Project type", config?.projectType ?? chalk2.yellow("not initialized"));
@@ -1168,6 +1207,9 @@ async function printProjectStatus() {
   printStatusLine("Generated files", String(generatedFiles.length));
   printStatusLine("Hook", existsSync3(hookPath) ? "installed" : "not installed");
   printStatusLine("Stats file", existsSync3(statsPath) ? ".memory-core-stats.json" : chalk2.gray("none"));
+  printStatusLine("Graph backend", graphBackendLabel(values));
+  printStatusLine("Graph store", graphStoreFilePath(process.cwd()));
+  printStatusLine("Graph snapshots", graphCount === null ? chalk2.gray("unavailable") : String(graphCount));
   console.log();
   printStatusLine("Database URL", redactDatabaseUrl(values.DATABASE_URL ?? ""));
   printStatusLine("Ollama URL", values.OLLAMA_URL ?? DEFAULT_OLLAMA_URL);
@@ -1655,8 +1697,7 @@ program.command("remember <text>").description("Save a new memory to the central
   }
   const spinner = ora("Saving memory\u2026").start();
   try {
-    const embedding = await embed(text);
-    await saveMemory({
+    await phase1.services.memoryEngine.remember({
       type: opts.type,
       scope: opts.scope,
       architecture: config?.backendArchitecture ?? config?.frontendFramework,
@@ -1664,8 +1705,7 @@ program.command("remember <text>").description("Save a new memory to the central
       content: text,
       reason: reason || void 0,
       context: buildMemoryContext(opts),
-      tags: parseTags(opts.tags),
-      embedding
+      tags: parseTags(opts.tags)
     });
     const reasonLine = reason ? chalk2.gray(`
   Why: ${reason}`) : "";
@@ -1682,11 +1722,12 @@ program.command("search <query>").description("Search memories using semantic si
   const spinner = ora("Searching\u2026").start();
   try {
     const architectures = inferProjectArchitectures(process.cwd(), config);
-    const results = await retrieve(
-      query,
+    const result = await phase1.services.retrievalEngine.retrieve({
+      text: query,
       architectures,
-      parseInt(opts.limit, 10)
-    );
+      limit: parseInt(opts.limit, 10)
+    });
+    const results = result.items;
     spinner.stop();
     if (results.length === 0) {
       console.log(chalk2.yellow("No memories found."));
@@ -1715,8 +1756,8 @@ program.command("search <query>").description("Search memories using semantic si
 program.command("export").description(`Export DB memories to ${MEMORY_FILE}`).option("-o, --output <file>", `Output file (default: ${MEMORY_FILE})`).action(async (opts) => {
   const spinner = ora("Exporting memories\u2026").start();
   try {
-    const memories = await listMemories({ limit: 1e4 });
-    const portable = memories.map(toPortableMemory);
+    const memories = await phase1.services.memoryEngine.list({ limit: 1e4 });
+    const portable = memories.map(toPortableFromRecord);
     const outputPath = opts.output ? join3(process.cwd(), opts.output) : writeMemoryFile(portable);
     if (opts.output) {
       writeFileSync3(outputPath, JSON.stringify(portable, null, 2) + "\n", "utf-8");
@@ -1738,8 +1779,7 @@ program.command("import").description(`Import memories from ${MEMORY_FILE}`).opt
     let skipped = 0;
     spinner.text = `Importing ${memories.length} memories\u2026`;
     for (const memory of memories) {
-      const embedding = await embed(memory.content);
-      const result = await upsertMemory({
+      const result = await phase1.services.memoryEngine.remember({
         type: memory.type,
         scope: memory.scope,
         architecture: memory.architecture,
@@ -1748,8 +1788,7 @@ program.command("import").description(`Import memories from ${MEMORY_FILE}`).opt
         content: memory.content,
         reason: memory.reason,
         context: memory.context,
-        tags: memory.tags,
-        embedding
+        tags: memory.tags
       });
       if (result === "inserted") inserted++;
       else skipped++;
@@ -1770,7 +1809,7 @@ program.command("list").description("List memories from the local database").opt
     const config = readProjectConfig();
     const architectures = opts.arch ? opts.arch : opts.all ? void 0 : getCurrentListArchitectures(config);
     const projectName = opts.project ? opts.project : opts.all || opts.arch ? void 0 : config?.projectName;
-    const memories = await listMemories({
+    const memories = await phase1.services.memoryEngine.list({
       type: opts.type,
       scope: opts.scope,
       architecture: architectures,
@@ -1779,7 +1818,7 @@ program.command("list").description("List memories from the local database").opt
       limit: parseInt(opts.limit, 10)
     });
     const title = opts.all ? "All memories" : `Current project memories${architectures ? ` (${Array.isArray(architectures) ? architectures.join(", ") : architectures})` : ""}`;
-    printMemoryTable(memories, title);
+    printMemoryTable(memories.map(toMemoryTableRow), title);
     if (!opts.all) {
       console.log(chalk2.gray("  Showing current project context plus shared/global memories. Use --all for the full database.\n"));
     }
@@ -1793,7 +1832,7 @@ program.command("list").description("List memories from the local database").opt
 program.command("remove <id>").description("Remove a memory by ID").option("--no-sync", "Skip automatic agent file sync after removal").action(async (id, opts) => {
   try {
     const config = readProjectConfig();
-    const deleted = await deleteMemory(parseInt(id, 10));
+    const deleted = await phase1.services.memoryEngine.removeById(parseInt(id, 10));
     if (!deleted) {
       console.log(chalk2.yellow(`No memory found with ID ${id}`));
       process.exit(1);
@@ -1810,7 +1849,7 @@ program.command("remove <id>").description("Remove a memory by ID").option("--no
 program.command("forget").description("Bulk-delete memories by tag, scope, type, or architecture").option("--tag <tag>", "Delete memories with this tag").option("--scope <scope>", "Filter by scope").option("--type <type>", "Filter by type").option("--arch <architecture>", "Filter by architecture").option("--no-sync", "Skip automatic agent file sync after deletion").action(async (opts) => {
   try {
     const config = readProjectConfig();
-    const deleted = await deleteMemories({
+    const deleted = await phase1.services.memoryEngine.removeMany({
       tag: opts.tag,
       scope: opts.scope,
       type: opts.type,
@@ -1831,7 +1870,7 @@ program.command("edit <id>").description("Edit a memory interactively").option("
   const memoryId = parseInt(id, 10);
   try {
     const config = readProjectConfig();
-    const existing = await getMemory(memoryId);
+    const existing = await phase1.services.memoryEngine.getById(memoryId);
     if (!existing) {
       console.log(chalk2.yellow(`No memory found with ID ${id}`));
       process.exit(1);
@@ -1846,16 +1885,14 @@ program.command("edit <id>").description("Edit a memory interactively").option("
     const examples = await input({ message: "Examples? (comma-separated)", default: existing.context?.examples?.join(",") ?? "" });
     const source = await input({ message: "Source?", default: existing.context?.source ?? "" });
     const tags = await input({ message: "Tags?", default: existing.tags.join(",") });
-    const embedding = content === existing.content ? void 0 : await embed(content);
-    await updateMemory(memoryId, {
+    await phase1.services.memoryEngine.update(memoryId, {
       type,
       scope,
       title: title || void 0,
       content,
       reason: reason || void 0,
       context: buildMemoryContext({ appliesTo, avoidWhen, example: examples, source }),
-      tags: parseTags(tags),
-      embedding
+      tags: parseTags(tags)
     });
     console.log(chalk2.green(`Updated memory ${id}`));
     await autoSyncGeneratedFiles(config, "edit", opts.sync);
@@ -1870,11 +1907,12 @@ program.command("ignore [pattern]").description("Manage project-scoped false-pos
   try {
     const config = readProjectConfig();
     if (opts.list) {
-      printMemoryTable(await listMemories({ type: "ignore", limit: 1e3 }), "Ignored patterns");
+      const ignores = await phase1.services.memoryEngine.list({ type: "ignore", limit: 1e3 });
+      printMemoryTable(ignores.map(toMemoryTableRow), "Ignored patterns");
       return;
     }
     if (opts.remove) {
-      const deleted = await deleteMemory(parseInt(opts.remove, 10));
+      const deleted = await phase1.services.memoryEngine.removeById(parseInt(opts.remove, 10));
       if (!deleted) {
         console.log(chalk2.yellow(`No ignore pattern found with ID ${opts.remove}`));
         process.exit(1);
@@ -1887,15 +1925,13 @@ program.command("ignore [pattern]").description("Manage project-scoped false-pos
       console.error(chalk2.red("Provide a pattern, --list, or --remove <id>"));
       process.exit(1);
     }
-    const embedding = await embed(pattern);
-    await upsertMemory({
+    await phase1.services.memoryEngine.remember({
       type: "ignore",
       scope: "project",
       architecture: config?.backendArchitecture ?? config?.frontendFramework,
       projectName: config?.projectName,
       content: pattern,
-      tags: ["ignore"],
-      embedding
+      tags: ["ignore"]
     });
     console.log(chalk2.green(`Ignored pattern saved: "${pattern}"`));
     await autoSyncGeneratedFiles(config, "ignore", opts.sync);
@@ -2020,7 +2056,7 @@ program.command("stats").description("Show violation counters recorded by check
   console.log();
 });
 program.command("dashboard").description("Start the live Svelte dashboard with WebSocket watch events").option("-p, --port <port>", "Dashboard port", "5178").option("--path <dir>", "Directory to watch (default: current directory)").option("--no-watch", "Serve the dashboard without starting file watch").action(async (opts) => {
-  const { startDashboard } = await import("./dashboard-server-QMNMSEPJ.js");
+  const { startDashboard } = await import("./dashboard-server-AUX4BQP6.js");
   await startDashboard({
     port: parseInt(opts.port, 10),
     path: opts.path,
@@ -2038,7 +2074,6 @@ program.command("seed").description("Load all predefined memories into the datab
   for (const seed of filtered) {
     const spinner = ora(`[${seed.architecture}] ${seed.title}`).start();
     try {
-      const embedding = await embed(seed.content);
       const payload = {
         type: seed.type,
         scope: seed.scope,
@@ -2046,15 +2081,14 @@ program.command("seed").description("Load all predefined memories into the datab
         title: seed.title,
         content: seed.content,
         reason: seed.reason,
-        tags: seed.tags,
-        embedding
+        tags: seed.tags
       };
       if (opts.force) {
-        await saveMemory(payload);
+        await phase1.services.memoryEngine.rememberForce(payload);
         saved++;
         spinner.succeed(chalk2.gray(`[${seed.architecture}] ${seed.title}`));
       } else {
-        const result = await upsertMemory(payload);
+        const result = await phase1.services.memoryEngine.remember(payload);
         if (result === "inserted") {
           saved++;
           spinner.succeed(chalk2.gray(`[${seed.architecture}] ${seed.title}`));
@@ -2097,7 +2131,11 @@ program.command("global").description("Sync your memory into every AI agent glob
   let memories = [];
   try {
     const architectures = opts.arch ? [opts.arch] : inferProjectArchitectures(process.cwd(), readProjectConfig());
-    memories = dedupeMemories(await retrieve("architecture rules coding standards", architectures, 30));
+    memories = (await phase1.services.retrievalEngine.retrieve({
+      text: "architecture rules coding standards",
+      architectures,
+      limit: 30
+    })).items;
   } catch (err) {
     spinner.fail(`Could not fetch memories: ${err.message}`);
     process.exit(1);
@@ -2256,6 +2294,164 @@ program.command("status").description("Show the current memory-core project and
     process.exit(1);
   }
 });
+var graph = program.command("graph").description("Build and inspect dependency graph snapshots");
+graph.command("migrate").description("Create or update PostgreSQL graph snapshot schema").action(async () => {
+  const { values } = readRuntimeEnv();
+  if (!values.DATABASE_URL) {
+    console.error(chalk2.red("Graph migration requires DATABASE_URL. Configure it in .memory-core.env or .env."));
+    process.exit(1);
+  }
+  const spinner = ora("Migrating graph snapshot schema\u2026").start();
+  try {
+    await migrateGraphSnapshots();
+    spinner.succeed("Graph snapshot schema is ready in PostgreSQL");
+  } catch (err) {
+    spinner.fail(`Graph migration failed: ${err.message}`);
+    process.exit(1);
+  }
+});
+graph.command("doctor").description("Inspect graph storage backend health (PostgreSQL + file fallback)").option("--path <dir>", "Project root path (default: current directory)").action(async (opts) => {
+  const cwd = resolve(opts.path ?? process.cwd());
+  const { values } = readRuntimeEnv();
+  const filePath = graphStoreFilePath(cwd);
+  const usesPostgres = Boolean(values.DATABASE_URL);
+  let ok = true;
+  console.log(chalk2.bold("\n  graph doctor\n"));
+  printStatusLine("Project path", cwd);
+  printStatusLine("Configured backend", usesPostgres ? "postgres + file fallback" : "file");
+  printStatusLine("File store", filePath);
+  console.log();
+  if (!usesPostgres) {
+    console.log(chalk2.yellow("  \u26A0  DATABASE_URL not set \u2014 using file backend only."));
+  } else {
+    try {
+      await migrateGraphSnapshots();
+      const probe = await probeGraphSnapshotStore(cwd);
+      console.log(chalk2.green("  \u2713 Graph PostgreSQL") + chalk2.dim(` ready (${probe.snapshotCount} snapshot records for this root)`));
+    } catch (err) {
+      ok = false;
+      console.log(chalk2.red("  \u2717 Graph PostgreSQL") + chalk2.dim(` ${err.message}`));
+    }
+  }
+  try {
+    const count = await getGraphSnapshotCount(cwd);
+    console.log(chalk2.green("  \u2713 Graph service") + chalk2.dim(` readable (${count ?? 0} snapshots visible)`));
+  } catch (err) {
+    ok = false;
+    console.log(chalk2.red("  \u2717 Graph service") + chalk2.dim(` ${err.message}`));
+  }
+  if (existsSync3(filePath)) {
+    console.log(chalk2.green("  \u2713 File fallback") + chalk2.dim(" store exists"));
+  } else {
+    console.log(chalk2.yellow("  \u26A0  File fallback") + chalk2.dim(" store not created yet (run graph build once)"));
+  }
+  console.log();
+  if (!ok) process.exit(1);
+});
+graph.command("build").description("Build a dependency graph snapshot and persist it").option("--path <dir>", "Project root path (default: current directory)").action(async (opts) => {
+  const cwd = resolve(opts.path ?? process.cwd());
+  const spinner = ora("Building dependency graph\u2026").start();
+  try {
+    const { snapshot } = await phase1.services.graphEngine.buildAndStoreSnapshot({ cwd });
+    spinner.succeed(`Graph snapshot saved: ${snapshot.id}`);
+    console.log(chalk2.gray(`  Root:  ${snapshot.rootPath}`));
+    console.log(chalk2.gray(`  Nodes: ${snapshot.nodes.length}`));
+    console.log(chalk2.gray(`  Edges: ${snapshot.edges.length}
+`));
+  } catch (err) {
+    spinner.fail(`Graph build failed: ${err.message}`);
+    process.exit(1);
+  }
+});
+graph.command("list").description("List saved dependency graph snapshots").option("--path <dir>", "Project root path (default: current directory)").option("-n, --limit <n>", "Number of snapshots to list", "10").action(async (opts) => {
+  const cwd = resolve(opts.path ?? process.cwd());
+  try {
+    const snapshots = await phase1.services.graphEngine.listSnapshots(cwd, parseInt(opts.limit, 10));
+    if (snapshots.length === 0) {
+      console.log(chalk2.yellow("\n  No graph snapshots found. Run: memory-core graph build\n"));
+      return;
+    }
+    console.log(chalk2.bold("\n  Graph snapshots\n"));
+    snapshots.forEach((snapshot, index) => {
+      console.log(`  ${index + 1}. ${snapshot.id}  ${chalk2.dim(snapshot.createdAt)}  nodes=${snapshot.nodes.length} edges=${snapshot.edges.length}`);
+    });
+    console.log();
+  } catch (err) {
+    console.error(chalk2.red(`Graph list failed: ${err.message}`));
+    process.exit(1);
+  }
+});
+graph.command("show [snapshotId]").description("Show a saved graph snapshot (latest by default)").option("--path <dir>", "Project root path (default: current directory)").option("--edges <n>", "Number of edges to print", "25").action(async (snapshotId, opts) => {
+  const cwd = resolve(opts.path ?? process.cwd());
+  try {
+    const snapshot = snapshotId ? await phase1.services.graphEngine.getSnapshot(cwd, snapshotId) : await phase1.services.graphEngine.latest(cwd);
+    if (!snapshot) {
+      console.log(chalk2.yellow("\n  No matching graph snapshot found. Run: memory-core graph build\n"));
+      return;
+    }
+    console.log(chalk2.bold(`
+  Graph ${snapshot.id ?? "(latest)"}
+`));
+    console.log(chalk2.gray(`  Root: ${snapshot.rootPath}`));
+    console.log(chalk2.gray(`  Created: ${snapshot.createdAt ?? "unknown"}`));
+    console.log(chalk2.gray(`  Nodes: ${snapshot.nodes.length}`));
+    console.log(chalk2.gray(`  Edges: ${snapshot.edges.length}
+`));
+    const limit = parseInt(opts.edges, 10);
+    snapshot.edges.slice(0, limit).forEach((edge, index) => {
+      console.log(`  ${index + 1}. ${abbreviate(edge.from)} ${chalk2.dim(`--${edge.kind}-->`)} ${abbreviate(edge.to)}`);
+    });
+    if (snapshot.edges.length > limit) {
+      console.log(chalk2.dim(`
+  \u2026 ${snapshot.edges.length - limit} more edges not shown
+`));
+    } else {
+      console.log();
+    }
+  } catch (err) {
+    console.error(chalk2.red(`Graph show failed: ${err.message}`));
+    process.exit(1);
+  }
+});
+graph.command("diff <leftSnapshotId> [rightSnapshotId]").description("Diff two snapshots (right defaults to latest)").option("--path <dir>", "Project root path (default: current directory)").action(async (leftSnapshotId, rightSnapshotId, opts) => {
+  const cwd = resolve(opts.path ?? process.cwd());
+  try {
+    const left = await phase1.services.graphEngine.getSnapshot(cwd, leftSnapshotId);
+    if (!left) {
+      console.error(chalk2.red(`Left snapshot not found: ${leftSnapshotId}`));
+      process.exit(1);
+    }
+    const right = rightSnapshotId ? await phase1.services.graphEngine.getSnapshot(cwd, rightSnapshotId) : await phase1.services.graphEngine.latest(cwd);
+    if (!right) {
+      console.error(chalk2.red(`Right snapshot not found${rightSnapshotId ? `: ${rightSnapshotId}` : ""}`));
+      process.exit(1);
+    }
+    const diff = phase1.services.graphEngine.diffGraphs(left, right);
+    console.log(chalk2.bold("\n  Graph diff\n"));
+    console.log(chalk2.gray(`  Left:  ${left.id}`));
+    console.log(chalk2.gray(`  Right: ${right.id}`));
+    console.log(chalk2.green(`  + Nodes: ${diff.addedNodes.length}`));
+    console.log(chalk2.red(`  - Nodes: ${diff.removedNodes.length}`));
+    console.log(chalk2.green(`  + Edges: ${diff.addedEdges.length}`));
+    console.log(chalk2.red(`  - Edges: ${diff.removedEdges.length}`));
+    if (diff.addedEdges.length > 0) {
+      console.log(chalk2.green("\n  Added edges"));
+      diff.addedEdges.slice(0, 20).forEach((edge, index) => {
+        console.log(`  ${index + 1}. ${abbreviate(edge.from)} ${chalk2.dim(`--${edge.kind}-->`)} ${abbreviate(edge.to)}`);
+      });
+    }
+    if (diff.removedEdges.length > 0) {
+      console.log(chalk2.red("\n  Removed edges"));
+      diff.removedEdges.slice(0, 20).forEach((edge, index) => {
+        console.log(`  ${index + 1}. ${abbreviate(edge.from)} ${chalk2.dim(`--${edge.kind}-->`)} ${abbreviate(edge.to)}`);
+      });
+    }
+    console.log();
+  } catch (err) {
+    console.error(chalk2.red(`Graph diff failed: ${err.message}`));
+    process.exit(1);
+  }
+});
 var hook = program.command("hook").description("Manage the pre-commit rule enforcement hook");
 hook.command("install").description("Install pre-commit hook (advisory mode by default \u2014 logs violations, never blocks)").option("--advisory", "Log violations but never block commits (default)").option("--strict", "Block commits that violate your rules").action((opts) => {
   const advisory = opts.strict ? false : true;
@@ -2271,7 +2467,11 @@ program.command("check").description("Check staged changes against architecture
   }
   await checkStaged({ verbose: opts.verbose ?? false, debug: opts.debug ?? false });
 });
-program.command("watch").description("Watch source files and check violations in real-time on every save").option("--path <dir>", "Directory to watch (default: current directory)").option("--verbose", "Show diff size and model details per file").option("--debug", "Show prompt, diff, and raw model response").action((opts) => {
-  startWatch({ path: opts.path, verbose: opts.verbose, debug: opts.debug });
+program.command("watch").description("Watch source files and check violations in real-time on every save").option("--path <dir>", "Directory to watch (default: current directory)").option("--verbose", "Show diff size and model details per file").option("--debug", "Show prompt, diff, and raw model response").action(async (opts) => {
+  await phase1.providers.watchService.start({
+    path: opts.path,
+    verbose: opts.verbose,
+    debug: opts.debug
+  });
 });
 program.parseAsync(process.argv);