clawvault 1.7.0 → 1.8.1

package/bin/clawvault.js

@@ -1186,5 +1186,34 @@ program
     }
   });
 
+// === DASHBOARD ===
+program
+  .command('dashboard')
+  .description('Run local vault graph dashboard')
+  .option('-p, --port <port>', 'Dashboard port', '3377')
+  .option('-v, --vault <path>', 'Vault path')
+  .action(async (options) => {
+    try {
+      const parsedPort = Number.parseInt(options.port, 10);
+      if (Number.isNaN(parsedPort)) {
+        console.error(chalk.red(`Error: Invalid port: ${options.port}`));
+        process.exit(1);
+      }
+
+      const vaultPath = options.vault
+        ? path.resolve(options.vault)
+        : resolveVaultPath(undefined);
+
+      const { startDashboard } = await import('../dashboard/server.js');
+      await startDashboard({
+        port: parsedPort,
+        vaultPath
+      });
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
 // Parse and run
 program.parse();

package/dashboard/lib/graph-diff.js

@@ -0,0 +1,102 @@
+function toNodeSignature(node) {
+  return JSON.stringify({
+    title: node.title,
+    category: node.category,
+    tags: Array.isArray(node.tags) ? [...node.tags].sort() : [],
+    path: node.path,
+    missing: Boolean(node.missing),
+    degree: Number(node.degree ?? 0)
+  });
+}
+
+function toEdgeKey(edge) {
+  return `${edge.source}=>${edge.target}`;
+}
+
+/**
+ * Compute an efficient patch between graph snapshots.
+ * @param {{nodes: Array<object>, edges: Array<object>, stats?: object}} previousGraph
+ * @param {{nodes: Array<object>, edges: Array<object>, stats?: object}} nextGraph
+ */
+export function diffGraphs(previousGraph, nextGraph) {
+  const previousNodes = previousGraph?.nodes ?? [];
+  const nextNodes = nextGraph?.nodes ?? [];
+  const previousEdges = previousGraph?.edges ?? [];
+  const nextEdges = nextGraph?.edges ?? [];
+
+  const previousNodeById = new Map(previousNodes.map((node) => [node.id, node]));
+  const nextNodeById = new Map(nextNodes.map((node) => [node.id, node]));
+
+  const addedNodes = [];
+  const updatedNodes = [];
+  const removedNodeIds = [];
+
+  for (const [nodeId, nextNode] of nextNodeById.entries()) {
+    const previousNode = previousNodeById.get(nodeId);
+    if (!previousNode) {
+      addedNodes.push(nextNode);
+      continue;
+    }
+    if (toNodeSignature(previousNode) !== toNodeSignature(nextNode)) {
+      updatedNodes.push(nextNode);
+    }
+  }
+
+  for (const nodeId of previousNodeById.keys()) {
+    if (!nextNodeById.has(nodeId)) {
+      removedNodeIds.push(nodeId);
+    }
+  }
+
+  const previousEdgeByKey = new Map(previousEdges.map((edge) => [toEdgeKey(edge), edge]));
+  const nextEdgeByKey = new Map(nextEdges.map((edge) => [toEdgeKey(edge), edge]));
+  const addedEdges = [];
+  const removedEdges = [];
+
+  for (const [edgeKey, edge] of nextEdgeByKey.entries()) {
+    if (!previousEdgeByKey.has(edgeKey)) {
+      addedEdges.push(edge);
+    }
+  }
+
+  for (const [edgeKey, edge] of previousEdgeByKey.entries()) {
+    if (!nextEdgeByKey.has(edgeKey)) {
+      removedEdges.push(edge);
+    }
+  }
+
+  const touchedNodeIds = new Set();
+  for (const node of addedNodes) {
+    touchedNodeIds.add(node.id);
+  }
+  for (const node of updatedNodes) {
+    touchedNodeIds.add(node.id);
+  }
+  for (const nodeId of removedNodeIds) {
+    touchedNodeIds.add(nodeId);
+  }
+  for (const edge of addedEdges) {
+    touchedNodeIds.add(edge.source);
+    touchedNodeIds.add(edge.target);
+  }
+  for (const edge of removedEdges) {
+    touchedNodeIds.add(edge.source);
+    touchedNodeIds.add(edge.target);
+  }
+
+  return {
+    addedNodes,
+    updatedNodes,
+    removedNodeIds,
+    addedEdges,
+    removedEdges,
+    changedNodeIds: Array.from(touchedNodeIds).sort((a, b) => a.localeCompare(b)),
+    stats: nextGraph?.stats ?? null,
+    hasChanges:
+      addedNodes.length > 0 ||
+      updatedNodes.length > 0 ||
+      removedNodeIds.length > 0 ||
+      addedEdges.length > 0 ||
+      removedEdges.length > 0
+  };
+}

package/dashboard/lib/graph-diff.test.js

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import { diffGraphs } from './graph-diff.js';
+
+describe('diffGraphs', () => {
+  it('detects node and edge additions, updates, and removals', () => {
+    const previous = {
+      nodes: [
+        { id: 'a', title: 'A', category: 'root', tags: [], path: 'a.md', missing: false, degree: 1 },
+        { id: 'b', title: 'B', category: 'root', tags: ['x'], path: 'b.md', missing: false, degree: 1 },
+        { id: 'c', title: 'C', category: 'root', tags: [], path: null, missing: true, degree: 0 }
+      ],
+      edges: [{ source: 'a', target: 'b' }],
+      stats: { nodeCount: 3, edgeCount: 1 }
+    };
+
+    const next = {
+      nodes: [
+        { id: 'a', title: 'A Updated', category: 'root', tags: [], path: 'a.md', missing: false, degree: 1 },
+        { id: 'b', title: 'B', category: 'root', tags: ['x'], path: 'b.md', missing: false, degree: 2 },
+        { id: 'd', title: 'D', category: 'projects', tags: [], path: 'd.md', missing: false, degree: 1 }
+      ],
+      edges: [
+        { source: 'a', target: 'b' },
+        { source: 'b', target: 'd' }
+      ],
+      stats: { nodeCount: 3, edgeCount: 2 }
+    };
+
+    const patch = diffGraphs(previous, next);
+
+    expect(patch.addedNodes).toEqual([next.nodes[2]]);
+    expect(patch.updatedNodes).toEqual(expect.arrayContaining([next.nodes[0], next.nodes[1]]));
+    expect(patch.removedNodeIds).toEqual(['c']);
+    expect(patch.addedEdges).toEqual([{ source: 'b', target: 'd' }]);
+    expect(patch.removedEdges).toEqual([]);
+    expect(patch.changedNodeIds).toEqual(['a', 'b', 'c', 'd']);
+    expect(patch.hasChanges).toBe(true);
+  });
+
+  it('returns hasChanges=false for equivalent graphs', () => {
+    const graph = {
+      nodes: [{ id: 'a', title: 'A', category: 'root', tags: ['t'], path: 'a.md', missing: false, degree: 0 }],
+      edges: [],
+      stats: { nodeCount: 1, edgeCount: 0 }
+    };
+
+    const patch = diffGraphs(graph, structuredClone(graph));
+
+    expect(patch.hasChanges).toBe(false);
+    expect(patch.addedNodes).toEqual([]);
+    expect(patch.updatedNodes).toEqual([]);
+    expect(patch.removedNodeIds).toEqual([]);
+    expect(patch.addedEdges).toEqual([]);
+    expect(patch.removedEdges).toEqual([]);
+  });
+});

package/dashboard/lib/vault-parser.js

@@ -0,0 +1,252 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import matter from 'gray-matter';
+
+export const WIKI_LINK_REGEX = /\[\[([^\]|]+)(\|[^\]]+)?\]\]/g;
+
+const MARKDOWN_EXT = '.md';
+const IGNORED_DIRECTORIES = new Set([
+  '.git',
+  '.obsidian',
+  '.trash',
+  'node_modules'
+]);
+
+/**
+ * Build a graph from markdown notes in a vault.
+ * @param {string} vaultPath
+ * @param {{ includeDangling?: boolean }} [options]
+ */
+export async function buildVaultGraph(vaultPath, options = {}) {
+  const includeDangling = options.includeDangling !== false;
+  const root = path.resolve(vaultPath);
+  const markdownFiles = await collectMarkdownFiles(root);
+
+  const nodesById = new Map();
+  const edges = [];
+  const edgeSet = new Set();
+
+  for (const absoluteFilePath of markdownFiles) {
+    const raw = await fs.readFile(absoluteFilePath, 'utf8');
+    const parsed = matter(raw);
+    const relativePath = path.relative(root, absoluteFilePath);
+    const id = toNodeId(relativePath);
+    const frontmatter = parsed.data ?? {};
+
+    nodesById.set(id, {
+      id,
+      title: normalizeString(frontmatter.title) || toDisplayTitle(id),
+      category: normalizeString(frontmatter.category) || inferCategory(id),
+      tags: normalizeTags(frontmatter.tags),
+      path: toPosixPath(relativePath),
+      missing: false,
+      _outboundTargets: extractWikiLinks(parsed.content)
+    });
+  }
+
+  const idsByLowercase = new Map();
+  const idsByBaseName = new Map();
+  for (const id of nodesById.keys()) {
+    idsByLowercase.set(id.toLowerCase(), id);
+    const baseName = path.posix.basename(id).toLowerCase();
+    const existing = idsByBaseName.get(baseName) ?? new Set();
+    existing.add(id);
+    idsByBaseName.set(baseName, existing);
+  }
+
+  for (const node of nodesById.values()) {
+    for (const rawTarget of node._outboundTargets) {
+      const targetId = resolveTargetId(rawTarget, {
+        idsByLowercase,
+        idsByBaseName,
+        includeDangling
+      });
+
+      if (!targetId) {
+        continue;
+      }
+
+      if (!nodesById.has(targetId) && includeDangling) {
+        nodesById.set(targetId, {
+          id: targetId,
+          title: toDisplayTitle(targetId),
+          category: 'unresolved',
+          tags: [],
+          path: null,
+          missing: true,
+          _outboundTargets: []
+        });
+      }
+
+      const edgeKey = `${node.id}=>${targetId}`;
+      if (edgeSet.has(edgeKey)) {
+        continue;
+      }
+      edgeSet.add(edgeKey);
+      edges.push({ source: node.id, target: targetId });
+    }
+  }
+
+  const degreeByNodeId = new Map();
+  for (const edge of edges) {
+    degreeByNodeId.set(edge.source, (degreeByNodeId.get(edge.source) ?? 0) + 1);
+    degreeByNodeId.set(edge.target, (degreeByNodeId.get(edge.target) ?? 0) + 1);
+  }
+
+  const nodes = Array.from(nodesById.values())
+    .map(({ _outboundTargets, ...node }) => ({
+      ...node,
+      degree: degreeByNodeId.get(node.id) ?? 0
+    }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  edges.sort((a, b) => {
+    const sourceSort = a.source.localeCompare(b.source);
+    return sourceSort !== 0 ? sourceSort : a.target.localeCompare(b.target);
+  });
+
+  return {
+    nodes,
+    edges,
+    stats: {
+      generatedAt: new Date().toISOString(),
+      nodeCount: nodes.length,
+      edgeCount: edges.length,
+      fileCount: markdownFiles.length
+    }
+  };
+}
+
+async function collectMarkdownFiles(root) {
+  const pending = [root];
+  const files = [];
+
+  while (pending.length > 0) {
+    const currentDir = pending.pop();
+    const entries = await fs.readdir(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const absolutePath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (!IGNORED_DIRECTORIES.has(entry.name)) {
+          pending.push(absolutePath);
+        }
+        continue;
+      }
+
+      if (entry.isFile() && entry.name.toLowerCase().endsWith(MARKDOWN_EXT)) {
+        files.push(absolutePath);
+      }
+    }
+  }
+
+  return files;
+}
+
+function extractWikiLinks(markdown) {
+  const links = [];
+  const regex = new RegExp(WIKI_LINK_REGEX.source, 'g');
+  let match = regex.exec(markdown);
+
+  while (match) {
+    const rawTarget = match[1]?.trim();
+    if (rawTarget) {
+      links.push(rawTarget);
+    }
+    match = regex.exec(markdown);
+  }
+
+  return links;
+}
+
+function resolveTargetId(target, context) {
+  const normalized = normalizeWikiTarget(target);
+  if (!normalized) {
+    return null;
+  }
+
+  const lower = normalized.toLowerCase();
+  const exact = context.idsByLowercase.get(lower);
+  if (exact) {
+    return exact;
+  }
+
+  if (!normalized.includes('/')) {
+    const maybeMatches = context.idsByBaseName.get(lower);
+    if (maybeMatches?.size === 1) {
+      return Array.from(maybeMatches)[0];
+    }
+  }
+
+  return context.includeDangling ? normalized : null;
+}
+
+function normalizeWikiTarget(target) {
+  let value = normalizeString(target);
+  if (!value) {
+    return null;
+  }
+
+  const hashIndex = value.indexOf('#');
+  if (hashIndex >= 0) {
+    value = value.slice(0, hashIndex);
+  }
+
+  const caretIndex = value.indexOf('^');
+  if (caretIndex >= 0) {
+    value = value.slice(0, caretIndex);
+  }
+
+  value = value.replace(/\\/g, '/');
+  value = value.replace(/^\.\//, '');
+  value = value.replace(/^\/+/, '');
+  value = value.replace(/\/+/g, '/');
+
+  if (value.toLowerCase().endsWith(MARKDOWN_EXT)) {
+    value = value.slice(0, -MARKDOWN_EXT.length);
+  }
+
+  return normalizeString(value);
+}
+
+function toNodeId(relativePath) {
+  const normalized = toPosixPath(relativePath);
+  return normalized.toLowerCase().endsWith(MARKDOWN_EXT)
+    ? normalized.slice(0, -MARKDOWN_EXT.length)
+    : normalized;
+}
+
+function inferCategory(id) {
+  const category = id.split('/')[0];
+  return normalizeString(category) || 'root';
+}
+
+function normalizeTags(tags) {
+  if (Array.isArray(tags)) {
+    return tags.map(normalizeString).filter(Boolean);
+  }
+  if (typeof tags === 'string') {
+    return tags
+      .split(',')
+      .map((tag) => normalizeString(tag))
+      .filter(Boolean);
+  }
+  return [];
+}
+
+function normalizeString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function toDisplayTitle(id) {
+  const base = path.posix.basename(id);
+  return base
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\b\w/g, (char) => char.toUpperCase());
+}
+
+function toPosixPath(filePath) {
+  return filePath.split(path.sep).join('/');
+}

package/dashboard/lib/vault-parser.test.js

@@ -0,0 +1,74 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { buildVaultGraph } from './vault-parser.js';
+
+function makeTempVault() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'clawvault-dashboard-'));
+}
+
+function writeVaultFile(root, relativePath, content) {
+  const fullPath = path.join(root, relativePath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, content, 'utf8');
+}
+
+describe('buildVaultGraph', () => {
+  it('builds nodes and edges from markdown wiki-links', async () => {
+    const vaultPath = makeTempVault();
+    try {
+      writeVaultFile(
+        vaultPath,
+        'decisions/use-clawvault.md',
+        `---
+title: Use ClawVault
+tags: [architecture, memory]
+---
+Linked to [[projects/clawvault|ClawVault Project]] and [[missing-note]].
+`
+      );
+      writeVaultFile(vaultPath, 'projects/clawvault.md', '# ClawVault');
+
+      const graph = await buildVaultGraph(vaultPath);
+      const decisionNode = graph.nodes.find((node) => node.id === 'decisions/use-clawvault');
+      const unresolvedNode = graph.nodes.find((node) => node.id === 'missing-note');
+
+      expect(decisionNode).toMatchObject({
+        title: 'Use ClawVault',
+        category: 'decisions',
+        tags: ['architecture', 'memory']
+      });
+      expect(graph.edges).toEqual(
+        expect.arrayContaining([
+          { source: 'decisions/use-clawvault', target: 'projects/clawvault' },
+          { source: 'decisions/use-clawvault', target: 'missing-note' }
+        ])
+      );
+      expect(unresolvedNode).toMatchObject({
+        missing: true,
+        category: 'unresolved'
+      });
+    } finally {
+      fs.rmSync(vaultPath, { recursive: true, force: true });
+    }
+  });
+
+  it('resolves basename links when there is a unique match', async () => {
+    const vaultPath = makeTempVault();
+    try {
+      writeVaultFile(vaultPath, 'research/notes.md', 'See [[clawvault]].');
+      writeVaultFile(vaultPath, 'projects/clawvault.md', '# ClawVault');
+
+      const graph = await buildVaultGraph(vaultPath);
+
+      expect(graph.edges).toEqual(
+        expect.arrayContaining([
+          { source: 'research/notes', target: 'projects/clawvault' }
+        ])
+      );
+    } finally {
+      fs.rmSync(vaultPath, { recursive: true, force: true });
+    }
+  });
+});