@git-stunts/git-warp 10.4.2 → 10.8.0

package/bin/warp-graph.js

@@ -25,16 +25,15 @@ import {
 } from '../src/domain/utils/RefLayout.js';
 import CasSeekCacheAdapter from '../src/infrastructure/adapters/CasSeekCacheAdapter.js';
 import { HookInstaller, classifyExistingHook } from '../src/domain/services/HookInstaller.js';
-import { renderInfoView } from '../src/visualization/renderers/ascii/info.js';
-import { renderCheckView } from '../src/visualization/renderers/ascii/check.js';
-import { renderHistoryView, summarizeOps } from '../src/visualization/renderers/ascii/history.js';
-import { renderPathView } from '../src/visualization/renderers/ascii/path.js';
-import { renderMaterializeView } from '../src/visualization/renderers/ascii/materialize.js';
+import { summarizeOps } from '../src/visualization/renderers/ascii/history.js';
 import { parseCursorBlob } from '../src/domain/utils/parseCursorBlob.js';
-import { renderSeekView } from '../src/visualization/renderers/ascii/seek.js';
+import { diffStates } from '../src/domain/services/StateDiff.js';
 import { renderGraphView } from '../src/visualization/renderers/ascii/graph.js';
 import { renderSvg } from '../src/visualization/renderers/svg/index.js';
 import { layoutGraph, queryResultToGraphData, pathResultToGraphData } from '../src/visualization/layouts/index.js';
+import { present } from './presenters/index.js';
+import { stableStringify, compactStringify } from './presenters/json.js';
+import { renderError } from './presenters/text.js';
 
 /**
  * @typedef {Object} Persistence
@@ -63,6 +62,7 @@ import { layoutGraph, queryResultToGraphData, pathResultToGraphData } from '../s
  * @property {() => Promise<Map<string, any>>} getFrontier
  * @property {() => {totalTombstones: number, tombstoneRatio: number}} getGCMetrics
  * @property {() => Promise<number>} getPropertyCount
+ * @property {() => Promise<import('../src/domain/services/JoinReducer.js').WarpStateV5 | null>} getStateSnapshot
  * @property {() => Promise<{ticks: number[], maxTick: number, perWriter: Map<string, WriterTickInfo>}>} discoverTicks
  * @property {(sha: string) => Promise<{ops?: any[]}>} loadPatchBySha
  * @property {(cache: any) => void} setSeekCache
@@ -91,6 +91,7 @@ import { layoutGraph, queryResultToGraphData, pathResultToGraphData } from '../s
  * @typedef {Object} CliOptions
  * @property {string} repo
  * @property {boolean} json
+ * @property {boolean} ndjson
  * @property {string|null} view
  * @property {string|null} graph
  * @property {string} writer
@@ -113,6 +114,8 @@ import { layoutGraph, queryResultToGraphData, pathResultToGraphData } from '../s
  * @property {string|null} tickValue
  * @property {string|null} name
  * @property {boolean} noPersistentCache
+ * @property {boolean} diff
+ * @property {number} diffLimit
  */
 
 const EXIT_CODES = {
@@ -138,7 +141,8 @@ Commands:
 
 Options:
   --repo <path>     Path to git repo (default: cwd)
-  --json            Emit JSON output
+  --json            Emit JSON output (pretty-printed, sorted keys)
+  --ndjson          Emit compact single-line JSON (for piping/scripting)
   --view [mode]     Visual output (ascii, browser, svg:FILE, html:FILE)
   --graph <name>    Graph name (required if repo has multiple graphs)
   --writer <id>     Writer id (default: cli)
@@ -171,6 +175,8 @@ Seek options:
   --load <name>         Restore a saved cursor
   --list                List all saved cursors
   --drop <name>         Delete a saved cursor
+  --diff                Show structural diff (added/removed nodes, edges, props)
+  --diff-limit <N>      Max diff entries (default 2000)
 `;
 
 /**
@@ -202,27 +208,6 @@ function notFoundError(message) {
   return new CliError(message, { code: 'E_NOT_FOUND', exitCode: EXIT_CODES.NOT_FOUND });
 }
 
-/** @param {*} value */
-function stableStringify(value) {
-  /** @param {*} input @returns {*} */
-  const normalize = (input) => {
-    if (Array.isArray(input)) {
-      return input.map(normalize);
-    }
-    if (input && typeof input === 'object') {
-      /** @type {Record<string, *>} */
-      const sorted = {};
-      for (const key of Object.keys(input).sort()) {
-        sorted[key] = normalize(input[key]);
-      }
-      return sorted;
-    }
-    return input;
-  };
-
-  return JSON.stringify(normalize(value), null, 2);
-}
-
 /** @param {string[]} argv */
 function parseArgs(argv) {
   const options = createDefaultOptions();
@@ -250,6 +235,7 @@ function createDefaultOptions() {
   return {
     repo: process.cwd(),
     json: false,
+    ndjson: false,
     view: null,
     graph: null,
     writer: 'cli',
@@ -278,6 +264,11 @@ function consumeBaseArg({ argv, index, options, optionDefs, positionals }) {
     return { consumed: 0 };
   }
 
+  if (arg === '--ndjson') {
+    options.ndjson = true;
+    return { consumed: 0 };
+  }
+
   if (arg === '--view') {
     // Valid view modes: ascii, browser, svg:FILE, html:FILE
     // Don't consume known commands as modes
@@ -787,299 +778,6 @@ function patchTouchesNode(patch, nodeId) {
   return false;
 }
 
-/** @param {*} payload */
-function renderInfo(payload) {
-  const lines = [`Repo: ${payload.repo}`];
-  lines.push(`Graphs: ${payload.graphs.length}`);
-  for (const graph of payload.graphs) {
-    const writers = graph.writers ? ` writers=${graph.writers.count}` : '';
-    lines.push(`- ${graph.name}${writers}`);
-    if (graph.checkpoint?.sha) {
-      lines.push(`  checkpoint: ${graph.checkpoint.sha}`);
-    }
-    if (graph.coverage?.sha) {
-      lines.push(`  coverage: ${graph.coverage.sha}`);
-    }
-    if (graph.cursor?.active) {
-      lines.push(`  cursor: tick ${graph.cursor.tick} (${graph.cursor.mode})`);
-    }
-  }
-  return `${lines.join('\n')}\n`;
-}
-
-/** @param {*} payload */
-function renderQuery(payload) {
-  const lines = [
-    `Graph: ${payload.graph}`,
-    `State: ${payload.stateHash}`,
-    `Nodes: ${payload.nodes.length}`,
-  ];
-
-  for (const node of payload.nodes) {
-    const id = node.id ?? '(unknown)';
-    lines.push(`- ${id}`);
-    if (node.props && Object.keys(node.props).length > 0) {
-      lines.push(`  props: ${JSON.stringify(node.props)}`);
-    }
-  }
-
-  return `${lines.join('\n')}\n`;
-}
-
-/** @param {*} payload */
-function renderPath(payload) {
-  const lines = [
-    `Graph: ${payload.graph}`,
-    `From: ${payload.from}`,
-    `To: ${payload.to}`,
-    `Found: ${payload.found ? 'yes' : 'no'}`,
-    `Length: ${payload.length}`,
-  ];
-
-  if (payload.path && payload.path.length > 0) {
-    lines.push(`Path: ${payload.path.join(' -> ')}`);
-  }
-
-  return `${lines.join('\n')}\n`;
-}
-
-const ANSI_GREEN = '\x1b[32m';
-const ANSI_YELLOW = '\x1b[33m';
-const ANSI_RED = '\x1b[31m';
-const ANSI_DIM = '\x1b[2m';
-const ANSI_RESET = '\x1b[0m';
-
-/** @param {string} state */
-function colorCachedState(state) {
-  if (state === 'fresh') {
-    return `${ANSI_GREEN}${state}${ANSI_RESET}`;
-  }
-  if (state === 'stale') {
-    return `${ANSI_YELLOW}${state}${ANSI_RESET}`;
-  }
-  return `${ANSI_RED}${ANSI_DIM}${state}${ANSI_RESET}`;
-}
-
-/** @param {*} payload */
-function renderCheck(payload) {
-  const lines = [
-    `Graph: ${payload.graph}`,
-    `Health: ${payload.health.status}`,
-  ];
-
-  if (payload.status) {
-    lines.push(`Cached State: ${colorCachedState(payload.status.cachedState)}`);
-    lines.push(`Patches Since Checkpoint: ${payload.status.patchesSinceCheckpoint}`);
-    lines.push(`Tombstone Ratio: ${payload.status.tombstoneRatio.toFixed(2)}`);
-    lines.push(`Writers: ${payload.status.writers}`);
-  }
-
-  if (payload.checkpoint?.sha) {
-    lines.push(`Checkpoint: ${payload.checkpoint.sha}`);
-    if (payload.checkpoint.ageSeconds !== null) {
-      lines.push(`Checkpoint Age: ${payload.checkpoint.ageSeconds}s`);
-    }
-  } else {
-    lines.push('Checkpoint: none');
-  }
-
-  if (!payload.status) {
-    lines.push(`Writers: ${payload.writers.count}`);
-  }
-  for (const head of payload.writers.heads) {
-    lines.push(`- ${head.writerId}: ${head.sha}`);
-  }
-
-  if (payload.coverage?.sha) {
-    lines.push(`Coverage: ${payload.coverage.sha}`);
-    lines.push(`Coverage Missing: ${payload.coverage.missingWriters.length}`);
-  } else {
-    lines.push('Coverage: none');
-  }
-
-  if (payload.gc) {
-    lines.push(`Tombstones: ${payload.gc.totalTombstones}`);
-    if (!payload.status) {
-      lines.push(`Tombstone Ratio: ${payload.gc.tombstoneRatio}`);
-    }
-  }
-
-  if (payload.hook) {
-    lines.push(formatHookStatusLine(payload.hook));
-  }
-
-  return `${lines.join('\n')}\n`;
-}
-
-/** @param {*} hook */
-function formatHookStatusLine(hook) {
-  if (!hook.installed && hook.foreign) {
-    return "Hook: foreign hook present — run 'git warp install-hooks'";
-  }
-  if (!hook.installed) {
-    return "Hook: not installed — run 'git warp install-hooks'";
-  }
-  if (hook.current) {
-    return `Hook: installed (v${hook.version}) — up to date`;
-  }
-  return `Hook: installed (v${hook.version}) — upgrade available, run 'git warp install-hooks'`;
-}
-
-/** @param {*} payload */
-function renderHistory(payload) {
-  const lines = [
-    `Graph: ${payload.graph}`,
-    `Writer: ${payload.writer}`,
-    `Entries: ${payload.entries.length}`,
-  ];
-
-  if (payload.nodeFilter) {
-    lines.push(`Node Filter: ${payload.nodeFilter}`);
-  }
-
-  for (const entry of payload.entries) {
-    lines.push(`- ${entry.sha} (lamport: ${entry.lamport}, ops: ${entry.opCount})`);
-  }
-
-  return `${lines.join('\n')}\n`;
-}
-
-/** @param {*} payload */
-function renderError(payload) {
-  return `Error: ${payload.error.message}\n`;
-}
-
-/**
- * Wraps SVG content in a minimal HTML document and writes it to disk.
- * @param {string} filePath - Destination file path
- * @param {string} svgContent - SVG markup to embed
- */
-function writeHtmlExport(filePath, svgContent) {
-  const html = `<!DOCTYPE html>\n<html><head><meta charset="utf-8"><title>git-warp</title></head><body>\n${svgContent}\n</body></html>`;
-  fs.writeFileSync(filePath, html);
-}
-
-/**
- * Writes a command result to stdout/stderr in the appropriate format.
- * Dispatches to JSON, SVG file, HTML file, ASCII view, or plain text
- * based on the combination of flags.
- * @param {*} payload - Command result payload
- * @param {{json: boolean, command: string, view: string|null}} options
- */
-function emit(payload, { json, command, view }) {
-  if (json) {
-    process.stdout.write(`${stableStringify(payload)}\n`);
-    return;
-  }
-
-  if (command === 'info') {
-    if (view) {
-      process.stdout.write(renderInfoView(payload));
-    } else {
-      process.stdout.write(renderInfo(payload));
-    }
-    return;
-  }
-
-  if (command === 'query') {
-    if (view && typeof view === 'string' && view.startsWith('svg:')) {
-      const svgPath = view.slice(4);
-      if (!payload._renderedSvg) {
-        process.stderr.write('No graph data — skipping SVG export.\n');
-      } else {
-        fs.writeFileSync(svgPath, payload._renderedSvg);
-        process.stderr.write(`SVG written to ${svgPath}\n`);
-      }
-    } else if (view && typeof view === 'string' && view.startsWith('html:')) {
-      const htmlPath = view.slice(5);
-      if (!payload._renderedSvg) {
-        process.stderr.write('No graph data — skipping HTML export.\n');
-      } else {
-        writeHtmlExport(htmlPath, payload._renderedSvg);
-        process.stderr.write(`HTML written to ${htmlPath}\n`);
-      }
-    } else if (view) {
-      process.stdout.write(`${payload._renderedAscii}\n`);
-    } else {
-      process.stdout.write(renderQuery(payload));
-    }
-    return;
-  }
-
-  if (command === 'path') {
-    if (view && typeof view === 'string' && view.startsWith('svg:')) {
-      const svgPath = view.slice(4);
-      if (!payload._renderedSvg) {
-        process.stderr.write('No path found — skipping SVG export.\n');
-      } else {
-        fs.writeFileSync(svgPath, payload._renderedSvg);
-        process.stderr.write(`SVG written to ${svgPath}\n`);
-      }
-    } else if (view && typeof view === 'string' && view.startsWith('html:')) {
-      const htmlPath = view.slice(5);
-      if (!payload._renderedSvg) {
-        process.stderr.write('No path found — skipping HTML export.\n');
-      } else {
-        writeHtmlExport(htmlPath, payload._renderedSvg);
-        process.stderr.write(`HTML written to ${htmlPath}\n`);
-      }
-    } else if (view) {
-      process.stdout.write(renderPathView(payload));
-    } else {
-      process.stdout.write(renderPath(payload));
-    }
-    return;
-  }
-
-  if (command === 'check') {
-    if (view) {
-      process.stdout.write(renderCheckView(payload));
-    } else {
-      process.stdout.write(renderCheck(payload));
-    }
-    return;
-  }
-
-  if (command === 'history') {
-    if (view) {
-      process.stdout.write(renderHistoryView(payload));
-    } else {
-      process.stdout.write(renderHistory(payload));
-    }
-    return;
-  }
-
-  if (command === 'materialize') {
-    if (view) {
-      process.stdout.write(renderMaterializeView(payload));
-    } else {
-      process.stdout.write(renderMaterialize(payload));
-    }
-    return;
-  }
-
-  if (command === 'seek') {
-    if (view) {
-      process.stdout.write(renderSeekView(payload));
-    } else {
-      process.stdout.write(renderSeek(payload));
-    }
-    return;
-  }
-
-  if (command === 'install-hooks') {
-    process.stdout.write(renderInstallHooks(payload));
-    return;
-  }
-
-  if (payload?.error) {
-    process.stderr.write(renderError(payload));
-    return;
-  }
-
-  process.stdout.write(`${stableStringify(payload)}\n`);
-}
-
 /**
  * Handles the `info` command: summarizes graphs in the repository.
  * @param {{options: CliOptions}} params
@@ -1583,38 +1281,6 @@ async function handleMaterialize({ options }) {
   };
 }
 
-/** @param {*} payload */
-function renderMaterialize(payload) {
-  if (payload.graphs.length === 0) {
-    return 'No graphs found in repo.\n';
-  }
-
-  const lines = [];
-  for (const entry of payload.graphs) {
-    if (entry.error) {
-      lines.push(`${entry.graph}: error — ${entry.error}`);
-    } else {
-      lines.push(`${entry.graph}: ${entry.nodes} nodes, ${entry.edges} edges, checkpoint ${entry.checkpoint}`);
-    }
-  }
-  return `${lines.join('\n')}\n`;
-}
-
-/** @param {*} payload */
-function renderInstallHooks(payload) {
-  if (payload.action === 'up-to-date') {
-    return `Hook: already up to date (v${payload.version}) at ${payload.hookPath}\n`;
-  }
-  if (payload.action === 'skipped') {
-    return 'Hook: installation skipped\n';
-  }
-  const lines = [`Hook: ${payload.action} (v${payload.version})`, `Path: ${payload.hookPath}`];
-  if (payload.backupPath) {
-    lines.push(`Backup: ${payload.backupPath}`);
-  }
-  return `${lines.join('\n')}\n`;
-}
-
 function createHookInstaller() {
   const __filename = new URL(import.meta.url).pathname;
   const __dirname = path.dirname(__filename);
@@ -1953,9 +1619,64 @@ function handleSeekBooleanFlag(arg, spec) {
     spec.action = 'clear-cache';
   } else if (arg === '--no-persistent-cache') {
     spec.noPersistentCache = true;
+  } else if (arg === '--diff') {
+    spec.diff = true;
   }
 }
 
+/**
+ * Parses --diff-limit / --diff-limit=N into the seek spec.
+ * @param {string} arg
+ * @param {string[]} args
+ * @param {number} i
+ * @param {SeekSpec} spec
+ */
+function handleDiffLimitFlag(arg, args, i, spec) {
+  let raw;
+  if (arg.startsWith('--diff-limit=')) {
+    raw = arg.slice('--diff-limit='.length);
+  } else {
+    raw = args[i + 1];
+    if (raw === undefined) {
+      throw usageError('Missing value for --diff-limit');
+    }
+  }
+  const n = Number(raw);
+  if (!Number.isFinite(n) || !Number.isInteger(n) || n < 1) {
+    throw usageError(`Invalid --diff-limit value: ${raw}. Must be a positive integer.`);
+  }
+  spec.diffLimit = n;
+}
+
+/**
+ * Parses a named action flag (--save, --load, --drop) with its value.
+ * @param {string} flagName - e.g. 'save'
+ * @param {string} arg - Current arg token
+ * @param {string[]} args - All args
+ * @param {number} i - Current index
+ * @param {SeekSpec} spec
+ * @returns {number} Number of extra args consumed (0 or 1)
+ */
+function parseSeekNamedAction(flagName, arg, args, i, spec) {
+  if (spec.action !== 'status') {
+    throw usageError(`--${flagName} cannot be combined with other seek flags`);
+  }
+  spec.action = flagName;
+  if (arg === `--${flagName}`) {
+    const val = args[i + 1];
+    if (val === undefined || val.startsWith('-')) {
+      throw usageError(`Missing name for --${flagName}`);
+    }
+    spec.name = val;
+    return 1;
+  }
+  spec.name = arg.slice(`--${flagName}=`.length);
+  if (!spec.name) {
+    throw usageError(`Missing name for --${flagName}`);
+  }
+  return 0;
+}
+
 /**
  * Parses CLI arguments for the `seek` command into a structured spec.
  * @param {string[]} args - Raw CLI arguments following the `seek` subcommand
@@ -1968,7 +1689,10 @@ function parseSeekArgs(args) {
     tickValue: null,
     name: null,
     noPersistentCache: false,
+    diff: false,
+    diffLimit: 2000,
   };
+  let diffLimitProvided = false;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -1995,78 +1719,39 @@ function parseSeekArgs(args) {
         throw usageError('--latest cannot be combined with other seek flags');
       }
       spec.action = 'latest';
-    } else if (arg === '--save') {
-      if (spec.action !== 'status') {
-        throw usageError('--save cannot be combined with other seek flags');
-      }
-      spec.action = 'save';
-      const val = args[i + 1];
-      if (val === undefined || val.startsWith('-')) {
-        throw usageError('Missing name for --save');
-      }
-      spec.name = val;
-      i += 1;
-    } else if (arg.startsWith('--save=')) {
-      if (spec.action !== 'status') {
-        throw usageError('--save cannot be combined with other seek flags');
-      }
-      spec.action = 'save';
-      spec.name = arg.slice('--save='.length);
-      if (!spec.name) {
-        throw usageError('Missing name for --save');
-      }
-    } else if (arg === '--load') {
-      if (spec.action !== 'status') {
-        throw usageError('--load cannot be combined with other seek flags');
-      }
-      spec.action = 'load';
-      const val = args[i + 1];
-      if (val === undefined || val.startsWith('-')) {
-        throw usageError('Missing name for --load');
-      }
-      spec.name = val;
-      i += 1;
-    } else if (arg.startsWith('--load=')) {
-      if (spec.action !== 'status') {
-        throw usageError('--load cannot be combined with other seek flags');
-      }
-      spec.action = 'load';
-      spec.name = arg.slice('--load='.length);
-      if (!spec.name) {
-        throw usageError('Missing name for --load');
-      }
+    } else if (arg === '--save' || arg.startsWith('--save=')) {
+      i += parseSeekNamedAction('save', arg, args, i, spec);
+    } else if (arg === '--load' || arg.startsWith('--load=')) {
+      i += parseSeekNamedAction('load', arg, args, i, spec);
     } else if (arg === '--list') {
       if (spec.action !== 'status') {
         throw usageError('--list cannot be combined with other seek flags');
       }
       spec.action = 'list';
-    } else if (arg === '--drop') {
-      if (spec.action !== 'status') {
-        throw usageError('--drop cannot be combined with other seek flags');
-      }
-      spec.action = 'drop';
-      const val = args[i + 1];
-      if (val === undefined || val.startsWith('-')) {
-        throw usageError('Missing name for --drop');
-      }
-      spec.name = val;
-      i += 1;
-    } else if (arg.startsWith('--drop=')) {
-      if (spec.action !== 'status') {
-        throw usageError('--drop cannot be combined with other seek flags');
-      }
-      spec.action = 'drop';
-      spec.name = arg.slice('--drop='.length);
-      if (!spec.name) {
-        throw usageError('Missing name for --drop');
-      }
-    } else if (arg === '--clear-cache' || arg === '--no-persistent-cache') {
+    } else if (arg === '--drop' || arg.startsWith('--drop=')) {
+      i += parseSeekNamedAction('drop', arg, args, i, spec);
+    } else if (arg === '--clear-cache' || arg === '--no-persistent-cache' || arg === '--diff') {
       handleSeekBooleanFlag(arg, spec);
+    } else if (arg === '--diff-limit' || arg.startsWith('--diff-limit=')) {
+      handleDiffLimitFlag(arg, args, i, spec);
+      diffLimitProvided = true;
+      if (arg === '--diff-limit') {
+        i += 1;
+      }
     } else if (arg.startsWith('-')) {
       throw usageError(`Unknown seek option: ${arg}`);
     }
   }
 
+  // --diff is only meaningful for actions that navigate to a tick
+  const DIFF_ACTIONS = new Set(['tick', 'latest', 'load']);
+  if (spec.diff && !DIFF_ACTIONS.has(spec.action)) {
+    throw usageError(`--diff cannot be used with --${spec.action}`);
+  }
+  if (diffLimitProvided && !spec.diff) {
+    throw usageError('--diff-limit requires --diff');
+  }
+
   return spec;
 }
 
@@ -2189,8 +1874,16 @@ async function handleSeek({ options, args }) {
     };
   }
   if (seekSpec.action === 'latest') {
+    const prevTick = activeCursor ? activeCursor.tick : null;
+    let sdResult = null;
+    if (seekSpec.diff) {
+      sdResult = await computeStructuralDiff({ graph, prevTick, currentTick: maxTick, diffLimit: seekSpec.diffLimit });
+    }
     await clearActiveCursor(persistence, graphName);
-    await graph.materialize();
+    // When --diff already materialized at maxTick, skip redundant re-materialize
+    if (!sdResult) {
+      await graph.materialize({ ceiling: maxTick });
+    }
     const nodes = await graph.getNodes();
     const edges = await graph.getEdges();
     const diff = computeSeekStateDiff(activeCursor, { nodes: nodes.length, edges: edges.length }, frontierHash);
@@ -2209,6 +1902,7 @@ async function handleSeek({ options, args }) {
         diff,
         tickReceipt,
         cursor: { active: false },
+        ...sdResult,
       },
       exitCode: EXIT_CODES.OK,
     };
@@ -2234,7 +1928,15 @@ async function handleSeek({ options, args }) {
     if (!saved) {
       throw notFoundError(`Saved cursor not found: ${loadName}`);
     }
-    await graph.materialize({ ceiling: saved.tick });
+    const prevTick = activeCursor ? activeCursor.tick : null;
+    let sdResult = null;
+    if (seekSpec.diff) {
+      sdResult = await computeStructuralDiff({ graph, prevTick, currentTick: saved.tick, diffLimit: seekSpec.diffLimit });
+    }
+    // When --diff already materialized at saved.tick, skip redundant call
+    if (!sdResult) {
+      await graph.materialize({ ceiling: saved.tick });
+    }
     const nodes = await graph.getNodes();
     const edges = await graph.getEdges();
     await writeActiveCursor(persistence, graphName, { tick: saved.tick, mode: saved.mode ?? 'lamport', nodes: nodes.length, edges: edges.length, frontierHash });
@@ -2255,6 +1957,7 @@ async function handleSeek({ options, args }) {
         diff,
         tickReceipt,
         cursor: { active: true, mode: saved.mode, tick: saved.tick, maxTick, name: seekSpec.name },
+        ...sdResult,
       },
       exitCode: EXIT_CODES.OK,
     };
@@ -2262,7 +1965,14 @@ async function handleSeek({ options, args }) {
   if (seekSpec.action === 'tick') {
     const currentTick = activeCursor ? activeCursor.tick : null;
     const resolvedTick = resolveTickValue(/** @type {string} */ (seekSpec.tickValue), currentTick, ticks, maxTick);
-    await graph.materialize({ ceiling: resolvedTick });
+    let sdResult = null;
+    if (seekSpec.diff) {
+      sdResult = await computeStructuralDiff({ graph, prevTick: currentTick, currentTick: resolvedTick, diffLimit: seekSpec.diffLimit });
+    }
+    // When --diff already materialized at resolvedTick, skip redundant call
+    if (!sdResult) {
+      await graph.materialize({ ceiling: resolvedTick });
+    }
     const nodes = await graph.getNodes();
     const edges = await graph.getEdges();
     await writeActiveCursor(persistence, graphName, { tick: resolvedTick, mode: 'lamport', nodes: nodes.length, edges: edges.length, frontierHash });
@@ -2282,12 +1992,22 @@ async function handleSeek({ options, args }) {
         diff,
         tickReceipt,
         cursor: { active: true, mode: 'lamport', tick: resolvedTick, maxTick, name: 'active' },
+        ...sdResult,
       },
       exitCode: EXIT_CODES.OK,
     };
   }
 
   // status (bare seek)
+  return await handleSeekStatus({ graph, graphName, persistence, activeCursor, ticks, maxTick, perWriter, frontierHash });
+}
+
+/**
+ * Handles the `status` sub-action of `seek` (bare seek with no action flag).
+ * @param {{graph: WarpGraphInstance, graphName: string, persistence: Persistence, activeCursor: CursorBlob|null, ticks: number[], maxTick: number, perWriter: Map<string, WriterTickInfo>, frontierHash: string}} params
+ * @returns {Promise<{payload: *, exitCode: number}>}
+ */
+async function handleSeekStatus({ graph, graphName, persistence, activeCursor, ticks, maxTick, perWriter, frontierHash }) {
   if (activeCursor) {
     await graph.materialize({ ceiling: activeCursor.tick });
     const nodes = await graph.getNodes();
@@ -2469,132 +2189,76 @@ async function buildTickReceipt({ tick, perWriter, graph }) {
 }
 
 /**
- * Renders a seek command payload as a human-readable string for terminal output.
+ * Computes a structural diff between the state at a previous tick and
+ * the state at the current tick.
  *
- * Handles all seek actions: list, drop, save, latest, load, tick, and status.
+ * Materializes the baseline tick first, snapshots the state, then
+ * materializes the target tick and calls diffStates() between the two.
+ * Applies diffLimit truncation when the total change count exceeds the cap.
  *
- * @param {*} payload - Seek result payload from handleSeek
- * @returns {string} Formatted output string (includes trailing newline)
+ * @param {{graph: WarpGraphInstance, prevTick: number|null, currentTick: number, diffLimit: number}} params
+ * @returns {Promise<{structuralDiff: *, diffBaseline: string, baselineTick: number|null, truncated: boolean, totalChanges: number, shownChanges: number}>}
  */
-function renderSeek(payload) {
-  const formatDelta = (/** @type {*} */ n) => { // TODO(ts-cleanup): type CLI payload
-    if (typeof n !== 'number' || !Number.isFinite(n) || n === 0) {
-      return '';
-    }
-    const sign = n > 0 ? '+' : '';
-    return ` (${sign}${n})`;
-  };
-
-  const formatOpSummaryPlain = (/** @type {*} */ summary) => { // TODO(ts-cleanup): type CLI payload
-    const order = [
-      ['NodeAdd', '+', 'node'],
-      ['EdgeAdd', '+', 'edge'],
-      ['PropSet', '~', 'prop'],
-      ['NodeTombstone', '-', 'node'],
-      ['EdgeTombstone', '-', 'edge'],
-      ['BlobValue', '+', 'blob'],
-    ];
-
-    const parts = [];
-    for (const [opType, symbol, label] of order) {
-      const n = summary?.[opType];
-      if (typeof n === 'number' && Number.isFinite(n) && n > 0) {
-        parts.push(`${symbol}${n}${label}`);
-      }
-    }
-    return parts.length > 0 ? parts.join(' ') : '(empty)';
-  };
-
-  const appendReceiptSummary = (/** @type {string} */ baseLine) => {
-    const tickReceipt = payload?.tickReceipt;
-    if (!tickReceipt || typeof tickReceipt !== 'object') {
-      return `${baseLine}\n`;
-    }
-
-    const entries = Object.entries(tickReceipt)
-      .filter(([writerId, entry]) => writerId && entry && typeof entry === 'object')
-      .sort(([a], [b]) => a.localeCompare(b));
-
-    if (entries.length === 0) {
-      return `${baseLine}\n`;
-    }
-
-    const maxWriterLen = Math.max(5, ...entries.map(([writerId]) => writerId.length));
-    const receiptLines = [`  Tick ${payload.tick}:`];
-    for (const [writerId, entry] of entries) {
-      const sha = typeof entry.sha === 'string' ? entry.sha.slice(0, 7) : '';
-      const opSummary = entry.opSummary && typeof entry.opSummary === 'object' ? entry.opSummary : entry;
-      receiptLines.push(`    ${writerId.padEnd(maxWriterLen)}  ${sha.padEnd(7)}  ${formatOpSummaryPlain(opSummary)}`);
-    }
-
-    return `${baseLine}\n${receiptLines.join('\n')}\n`;
-  };
-
-  const buildStateStrings = () => {
-    const nodeLabel = payload.nodes === 1 ? 'node' : 'nodes';
-    const edgeLabel = payload.edges === 1 ? 'edge' : 'edges';
-    const patchLabel = payload.patchCount === 1 ? 'patch' : 'patches';
-    return {
-      nodesStr: `${payload.nodes} ${nodeLabel}${formatDelta(payload.diff?.nodes)}`,
-      edgesStr: `${payload.edges} ${edgeLabel}${formatDelta(payload.diff?.edges)}`,
-      patchesStr: `${payload.patchCount} ${patchLabel}`,
-    };
-  };
-
-  if (payload.action === 'clear-cache') {
-    return `${payload.message}\n`;
-  }
-
-  if (payload.action === 'list') {
-    if (payload.cursors.length === 0) {
-      return 'No saved cursors.\n';
-    }
-    const lines = [];
-    for (const c of payload.cursors) {
-      const active = c.tick === payload.activeTick ? ' (active)' : '';
-      lines.push(`  ${c.name}: tick ${c.tick}${active}`);
-    }
-    return `${lines.join('\n')}\n`;
-  }
+async function computeStructuralDiff({ graph, prevTick, currentTick, diffLimit }) {
+  let beforeState = null;
+  let diffBaseline = 'empty';
+  let baselineTick = null;
 
-  if (payload.action === 'drop') {
-    return `Dropped cursor "${payload.name}" (was at tick ${payload.tick}).\n`;
+  // Short-circuit: same tick produces an empty diff
+  if (prevTick !== null && prevTick === currentTick) {
+    const empty = { nodes: { added: [], removed: [] }, edges: { added: [], removed: [] }, props: { set: [], removed: [] } };
+    return { structuralDiff: empty, diffBaseline: 'tick', baselineTick: prevTick, truncated: false, totalChanges: 0, shownChanges: 0 };
   }
 
-  if (payload.action === 'save') {
-    return `Saved cursor "${payload.name}" at tick ${payload.tick}.\n`;
+  if (prevTick !== null && prevTick > 0) {
+    await graph.materialize({ ceiling: prevTick });
+    beforeState = await graph.getStateSnapshot();
+    diffBaseline = 'tick';
+    baselineTick = prevTick;
   }
 
-  if (payload.action === 'latest') {
-    const { nodesStr, edgesStr } = buildStateStrings();
-    return appendReceiptSummary(
-      `${payload.graph}: returned to present (tick ${payload.maxTick}, ${nodesStr}, ${edgesStr})`,
-    );
-  }
+  await graph.materialize({ ceiling: currentTick });
+  const afterState = /** @type {*} */ (await graph.getStateSnapshot()); // TODO(ts-cleanup): narrow WarpStateV5
+  const diff = diffStates(beforeState, afterState);
 
-  if (payload.action === 'load') {
-    const { nodesStr, edgesStr } = buildStateStrings();
-    return appendReceiptSummary(
-      `${payload.graph}: loaded cursor "${payload.name}" at tick ${payload.tick} of ${payload.maxTick} (${nodesStr}, ${edgesStr})`,
-    );
-  }
+  return applyDiffLimit(diff, diffBaseline, baselineTick, diffLimit);
+}
 
-  if (payload.action === 'tick') {
-    const { nodesStr, edgesStr, patchesStr } = buildStateStrings();
-    return appendReceiptSummary(
-      `${payload.graph}: tick ${payload.tick} of ${payload.maxTick} (${nodesStr}, ${edgesStr}, ${patchesStr})`,
-    );
-  }
+/**
+ * Applies truncation limits to a structural diff result.
+ *
+ * @param {*} diff
+ * @param {string} diffBaseline
+ * @param {number|null} baselineTick
+ * @param {number} diffLimit
+ * @returns {{structuralDiff: *, diffBaseline: string, baselineTick: number|null, truncated: boolean, totalChanges: number, shownChanges: number}}
+ */
+function applyDiffLimit(diff, diffBaseline, baselineTick, diffLimit) {
+  const totalChanges =
+    diff.nodes.added.length + diff.nodes.removed.length +
+    diff.edges.added.length + diff.edges.removed.length +
+    diff.props.set.length + diff.props.removed.length;
+
+  if (totalChanges <= diffLimit) {
+    return { structuralDiff: diff, diffBaseline, baselineTick, truncated: false, totalChanges, shownChanges: totalChanges };
+  }
+
+  // Truncate sequentially (nodes → edges → props), keeping sort order within each category
+  let remaining = diffLimit;
+  const cap = (/** @type {any[]} */ arr) => {
+    const take = Math.min(arr.length, remaining);
+    remaining -= take;
+    return arr.slice(0, take);
+  };
 
-  // status
-  if (payload.cursor && payload.cursor.active) {
-    const { nodesStr, edgesStr, patchesStr } = buildStateStrings();
-    return appendReceiptSummary(
-      `${payload.graph}: tick ${payload.tick} of ${payload.maxTick} (${nodesStr}, ${edgesStr}, ${patchesStr})`,
-    );
-  }
+  const capped = {
+    nodes: { added: cap(diff.nodes.added), removed: cap(diff.nodes.removed) },
+    edges: { added: cap(diff.edges.added), removed: cap(diff.edges.removed) },
+    props: { set: cap(diff.props.set), removed: cap(diff.props.removed) },
+  };
 
-  return `${payload.graph}: no cursor active, ${payload.ticks.length} ticks available\n`;
+  const shownChanges = diffLimit - remaining;
+  return { structuralDiff: capped, diffBaseline, baselineTick, truncated: true, totalChanges, shownChanges };
 }
 
 /**
@@ -2701,6 +2365,12 @@ async function main() {
   if (options.json && options.view) {
     throw usageError('--json and --view are mutually exclusive');
   }
+  if (options.ndjson && options.view) {
+    throw usageError('--ndjson and --view are mutually exclusive');
+  }
+  if (options.json && options.ndjson) {
+    throw usageError('--json and --ndjson are mutually exclusive');
+  }
 
   const command = positionals[0];
   if (!command) {
@@ -2731,7 +2401,8 @@ async function main() {
     : { payload: result, exitCode: EXIT_CODES.OK };
 
   if (normalized.payload !== undefined) {
-    emit(normalized.payload, { json: options.json, command, view: options.view });
+    const format = options.ndjson ? 'ndjson' : options.json ? 'json' : 'text';
+    present(normalized.payload, { format, command, view: options.view });
   }
   // Use process.exit() to avoid waiting for fire-and-forget I/O (e.g. seek cache writes).
   process.exit(normalized.exitCode ?? EXIT_CODES.OK);
@@ -2748,8 +2419,9 @@ main().catch((error) => {
     payload.error.cause = error.cause instanceof Error ? error.cause.message : error.cause;
   }
 
-  if (process.argv.includes('--json')) {
-    process.stdout.write(`${stableStringify(payload)}\n`);
+  if (process.argv.includes('--json') || process.argv.includes('--ndjson')) {
+    const stringify = process.argv.includes('--ndjson') ? compactStringify : stableStringify;
+    process.stdout.write(`${stringify(payload)}\n`);
   } else {
     process.stderr.write(renderError(payload));
   }