roam-research-mcp 1.0.0 → 1.4.0

package/build/cache/page-uid-cache.js

@@ -0,0 +1,55 @@
+/**
+ * Simple in-memory cache for page title -> UID mappings.
+ * Pages are stable entities that rarely get deleted, making them safe to cache.
+ * This reduces redundant API queries when looking up the same page multiple times.
+ */
+class PageUidCache {
+    constructor() {
+        this.cache = new Map(); // title (lowercase) -> UID
+    }
+    /**
+     * Get a cached page UID by title.
+     * @param title - Page title (case-insensitive)
+     * @returns The cached UID or undefined if not cached
+     */
+    get(title) {
+        return this.cache.get(title.toLowerCase());
+    }
+    /**
+     * Cache a page title -> UID mapping.
+     * @param title - Page title (will be stored lowercase)
+     * @param uid - Page UID
+     */
+    set(title, uid) {
+        this.cache.set(title.toLowerCase(), uid);
+    }
+    /**
+     * Check if a page title is cached.
+     * @param title - Page title (case-insensitive)
+     */
+    has(title) {
+        return this.cache.has(title.toLowerCase());
+    }
+    /**
+     * Called when a page is created - immediately add to cache.
+     * @param title - Page title
+     * @param uid - Page UID
+     */
+    onPageCreated(title, uid) {
+        this.set(title, uid);
+    }
+    /**
+     * Clear the cache (useful for testing or session reset).
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get the current cache size.
+     */
+    get size() {
+        return this.cache.size;
+    }
+}
+// Singleton instance - shared across all operations
+export const pageUidCache = new PageUidCache();

package/build/cli/import-markdown.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { initializeGraph } from '@roam-research/roam-api-sdk';
+import { API_TOKEN, GRAPH_NAME } from '../config/environment.js';
+import { PageOperations } from '../tools/operations/pages.js';
+import { parseMarkdown } from '../markdown-utils.js';
+/**
+ * Flatten nested MarkdownNode[] to flat array with absolute levels
+ */
+function flattenNodes(nodes, baseLevel = 1) {
+    const result = [];
+    for (const node of nodes) {
+        result.push({
+            text: node.content,
+            level: baseLevel,
+            ...(node.heading_level && { heading: node.heading_level })
+        });
+        if (node.children.length > 0) {
+            result.push(...flattenNodes(node.children, baseLevel + 1));
+        }
+    }
+    return result;
+}
+/**
+ * Read all input from stdin
+ */
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}
+/**
+ * Show usage help
+ */
+function showUsage() {
+    console.error('Usage: roam-import <page-title>');
+    console.error('');
+    console.error('Reads markdown from stdin and imports to Roam Research.');
+    console.error('');
+    console.error('Examples:');
+    console.error('  cat document.md | roam-import "Meeting Notes"');
+    console.error('  pbpaste | roam-import "Ideas"');
+    console.error('  echo "- Item 1\\n- Item 2" | roam-import "Quick Note"');
+    console.error('');
+    console.error('Environment variables required:');
+    console.error('  ROAM_API_TOKEN   Your Roam Research API token');
+    console.error('  ROAM_GRAPH_NAME  Your Roam graph name');
+}
+async function main() {
+    // Parse CLI arguments
+    const args = process.argv.slice(2);
+    const pageTitle = args[0];
+    if (!pageTitle || pageTitle === '--help' || pageTitle === '-h') {
+        showUsage();
+        process.exit(pageTitle ? 0 : 1);
+    }
+    // Check if stdin is a TTY (no input piped)
+    if (process.stdin.isTTY) {
+        console.error('Error: No input received. Pipe markdown content to this command.');
+        console.error('');
+        showUsage();
+        process.exit(1);
+    }
+    // Read markdown from stdin
+    const markdownContent = await readStdin();
+    if (!markdownContent.trim()) {
+        console.error('Error: Empty input received.');
+        process.exit(1);
+    }
+    // Initialize Roam graph
+    const graph = initializeGraph({
+        token: API_TOKEN,
+        graph: GRAPH_NAME
+    });
+    // Parse markdown to nodes
+    const nodes = parseMarkdown(markdownContent);
+    // Flatten nested structure to content blocks
+    const contentBlocks = flattenNodes(nodes);
+    if (contentBlocks.length === 0) {
+        console.error('Error: No content blocks parsed from input.');
+        process.exit(1);
+    }
+    // Create page with content
+    const pageOps = new PageOperations(graph);
+    const result = await pageOps.createPage(pageTitle, contentBlocks);
+    if (result.success) {
+        console.log(`Created page '${pageTitle}' (uid: ${result.uid})`);
+    }
+    else {
+        console.error(`Failed to create page '${pageTitle}'`);
+        process.exit(1);
+    }
+}
+main().catch((error) => {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+});

package/build/config/environment.js

@@ -42,5 +42,7 @@ if (!API_TOKEN || !GRAPH_NAME) {
         '   ROAM_GRAPH_NAME=your-graph-name');
 }
 const HTTP_STREAM_PORT = process.env.HTTP_STREAM_PORT || '8088'; // Default to 8088
-const CORS_ORIGIN = process.env.CORS_ORIGIN || 'http://localhost:5678';
-export { API_TOKEN, GRAPH_NAME, HTTP_STREAM_PORT, CORS_ORIGIN };
+const CORS_ORIGINS = (process.env.CORS_ORIGIN || 'http://localhost:5678,https://roamresearch.com')
+    .split(',')
+    .map(origin => origin.trim());
+export { API_TOKEN, GRAPH_NAME, HTTP_STREAM_PORT, CORS_ORIGINS };

package/build/diff/actions.js

@@ -0,0 +1,93 @@
+/**
+ * Action Generator
+ *
+ * Generates correctly ordered batch actions from a DiffResult.
+ * The order is critical for Roam API correctness:
+ * 1. Creates (top-down to ensure parents exist before children)
+ * 2. Moves (reposition existing blocks)
+ * 3. Updates (text/heading changes)
+ * 4. Deletes (bottom-up; reverse order to delete children before parents)
+ */
+/**
+ * Generate a correctly ordered array of batch actions from a DiffResult.
+ *
+ * The ordering ensures:
+ * - Parent blocks are created before their children
+ * - Blocks are moved before text updates (in case moves affect siblings)
+ * - Children are deleted before their parents
+ *
+ * @param diff - The DiffResult containing categorized actions
+ * @returns Ordered array of batch actions ready for Roam API
+ */
+export function generateBatchActions(diff) {
+    const actions = [];
+    // 1. Creates (in markdown order, parents before children)
+    // The creates are already in the correct order from diffBlockTrees
+    actions.push(...diff.creates);
+    // 2. Moves (reposition existing blocks)
+    actions.push(...diff.moves);
+    // 3. Updates (text/heading changes)
+    actions.push(...diff.updates);
+    // 4. Deletes (reversed to delete children before parents)
+    // This is important because Roam will fail if you try to delete
+    // a parent block while it still has children
+    actions.push(...[...diff.deletes].reverse());
+    return actions;
+}
+/**
+ * Filter actions to only include specific action types.
+ * Useful for dry-run analysis or debugging.
+ */
+export function filterActions(actions, types) {
+    const typeSet = new Set(types);
+    return actions.filter((a) => typeSet.has(a.action));
+}
+/**
+ * Group actions by their type for analysis.
+ */
+export function groupActionsByType(actions) {
+    const creates = [];
+    const updates = [];
+    const moves = [];
+    const deletes = [];
+    for (const action of actions) {
+        switch (action.action) {
+            case 'create-block':
+                creates.push(action);
+                break;
+            case 'update-block':
+                updates.push(action);
+                break;
+            case 'move-block':
+                moves.push(action);
+                break;
+            case 'delete-block':
+                deletes.push(action);
+                break;
+        }
+    }
+    return { creates, updates, moves, deletes };
+}
+/**
+ * Summarize actions for logging purposes.
+ */
+export function summarizeActions(actions) {
+    const grouped = groupActionsByType(actions);
+    const parts = [];
+    if (grouped.creates.length > 0) {
+        parts.push(`${grouped.creates.length} create(s)`);
+    }
+    if (grouped.moves.length > 0) {
+        parts.push(`${grouped.moves.length} move(s)`);
+    }
+    if (grouped.updates.length > 0) {
+        parts.push(`${grouped.updates.length} update(s)`);
+    }
+    if (grouped.deletes.length > 0) {
+        parts.push(`${grouped.deletes.length} delete(s)`);
+    }
+    if (parts.length === 0) {
+        return 'No changes';
+    }
+    return parts.join(', ');
+}

package/build/diff/actions.test.js

@@ -0,0 +1,125 @@
+import { describe, it, expect } from 'vitest';
+import { generateBatchActions, filterActions, groupActionsByType, summarizeActions, } from './actions.js';
+describe('generateBatchActions', () => {
+    function createDiffResult(creates = [], updates = [], moves = [], deletes = []) {
+        return {
+            creates,
+            updates,
+            moves,
+            deletes,
+            preservedUids: new Set(),
+        };
+    }
+    it('returns actions in correct order: creates, moves, updates, deletes', () => {
+        const diff = createDiffResult([{ action: 'create-block', block: { string: 'new' }, location: { 'parent-uid': 'p', order: 0 } }], [{ action: 'update-block', block: { uid: 'u1', string: 'updated' } }], [{ action: 'move-block', block: { uid: 'u2' }, location: { 'parent-uid': 'p', order: 1 } }], [{ action: 'delete-block', block: { uid: 'u3' } }]);
+        const actions = generateBatchActions(diff);
+        expect(actions[0].action).toBe('create-block');
+        expect(actions[1].action).toBe('move-block');
+        expect(actions[2].action).toBe('update-block');
+        expect(actions[3].action).toBe('delete-block');
+    });
+    it('reverses delete order for child-before-parent deletion', () => {
+        const diff = createDiffResult([], [], [], [
+            { action: 'delete-block', block: { uid: 'parent' } },
+            { action: 'delete-block', block: { uid: 'child' } },
+        ]);
+        const actions = generateBatchActions(diff);
+        // Deletes should be reversed
+        expect(actions[0].block.uid).toBe('child');
+        expect(actions[1].block.uid).toBe('parent');
+    });
+    it('returns empty array for empty diff', () => {
+        const diff = createDiffResult();
+        const actions = generateBatchActions(diff);
+        expect(actions).toEqual([]);
+    });
+    it('preserves all actions without modification', () => {
+        const createAction = {
+            action: 'create-block',
+            block: { uid: 'new1', string: 'Test', heading: 2 },
+            location: { 'parent-uid': 'page', order: 0 },
+        };
+        const diff = createDiffResult([createAction]);
+        const actions = generateBatchActions(diff);
+        expect(actions[0]).toEqual(createAction);
+    });
+});
+describe('filterActions', () => {
+    const allActions = [
+        { action: 'create-block', block: { string: 'new' }, location: { 'parent-uid': 'p', order: 0 } },
+        { action: 'update-block', block: { uid: 'u1', string: 'updated' } },
+        { action: 'move-block', block: { uid: 'u2' }, location: { 'parent-uid': 'p', order: 1 } },
+        { action: 'delete-block', block: { uid: 'u3' } },
+    ];
+    it('filters to only specified action types', () => {
+        const creates = filterActions(allActions, ['create-block']);
+        expect(creates.length).toBe(1);
+        expect(creates[0].action).toBe('create-block');
+    });
+    it('supports multiple action types', () => {
+        const modifying = filterActions(allActions, ['create-block', 'update-block']);
+        expect(modifying.length).toBe(2);
+    });
+    it('returns empty array when no matches', () => {
+        const emptyActions = [];
+        const result = filterActions(emptyActions, ['create-block']);
+        expect(result).toEqual([]);
+    });
+});
+describe('groupActionsByType', () => {
+    it('groups actions by their type', () => {
+        const actions = [
+            { action: 'create-block', block: { string: 'a' }, location: { 'parent-uid': 'p', order: 0 } },
+            { action: 'create-block', block: { string: 'b' }, location: { 'parent-uid': 'p', order: 1 } },
+            { action: 'update-block', block: { uid: 'u1', string: 'c' } },
+            { action: 'delete-block', block: { uid: 'u2' } },
+        ];
+        const grouped = groupActionsByType(actions);
+        expect(grouped.creates.length).toBe(2);
+        expect(grouped.updates.length).toBe(1);
+        expect(grouped.moves.length).toBe(0);
+        expect(grouped.deletes.length).toBe(1);
+    });
+    it('returns empty arrays for missing types', () => {
+        const actions = [];
+        const grouped = groupActionsByType(actions);
+        expect(grouped.creates).toEqual([]);
+        expect(grouped.updates).toEqual([]);
+        expect(grouped.moves).toEqual([]);
+        expect(grouped.deletes).toEqual([]);
+    });
+});
+describe('summarizeActions', () => {
+    it('summarizes action counts', () => {
+        const actions = [
+            { action: 'create-block', block: { string: 'a' }, location: { 'parent-uid': 'p', order: 0 } },
+            { action: 'create-block', block: { string: 'b' }, location: { 'parent-uid': 'p', order: 1 } },
+            { action: 'update-block', block: { uid: 'u1', string: 'c' } },
+            { action: 'delete-block', block: { uid: 'u2' } },
+        ];
+        const summary = summarizeActions(actions);
+        expect(summary).toBe('2 create(s), 1 update(s), 1 delete(s)');
+    });
+    it('returns "No changes" for empty actions', () => {
+        const summary = summarizeActions([]);
+        expect(summary).toBe('No changes');
+    });
+    it('only includes non-zero counts', () => {
+        const actions = [
+            { action: 'update-block', block: { uid: 'u1', string: 'updated' } },
+        ];
+        const summary = summarizeActions(actions);
+        expect(summary).toBe('1 update(s)');
+        expect(summary).not.toContain('create');
+        expect(summary).not.toContain('move');
+        expect(summary).not.toContain('delete');
+    });
+    it('includes moves when present', () => {
+        const actions = [
+            { action: 'move-block', block: { uid: 'u1' }, location: { 'parent-uid': 'p', order: 0 } },
+            { action: 'move-block', block: { uid: 'u2' }, location: { 'parent-uid': 'p', order: 1 } },
+        ];
+        const summary = summarizeActions(actions);
+        expect(summary).toBe('2 move(s)');
+    });
+});

package/build/diff/diff.js

@@ -0,0 +1,155 @@
+/**
+ * Diff Computation
+ *
+ * Computes the minimal set of batch actions needed to transform
+ * existing blocks into the desired new block structure.
+ */
+import { flattenExistingBlocks } from './parser.js';
+import { matchBlocks, normalizeText } from './matcher.js';
+/**
+ * Compute the diff between existing blocks and desired new blocks.
+ *
+ * This function:
+ * 1. Matches new blocks to existing blocks by content similarity
+ * 2. For matched blocks: generates update/move actions as needed
+ * 3. For unmatched new blocks: generates create actions
+ * 4. For unmatched existing blocks: generates delete actions
+ *
+ * @param existing - Array of existing block trees
+ * @param newBlocks - Flat array of new blocks (desired state)
+ * @param parentUid - UID of the parent page/block
+ * @returns DiffResult with categorized actions
+ */
+export function diffBlockTrees(existing, newBlocks, parentUid) {
+    const result = {
+        creates: [],
+        updates: [],
+        moves: [],
+        deletes: [],
+        preservedUids: new Set(),
+    };
+    // Flatten existing blocks for matching
+    const existingFlat = flattenExistingBlocks(existing);
+    // Step 1: Match blocks by content
+    const matches = matchBlocks(existingFlat, newBlocks);
+    // Build uid -> ExistingBlock mapping
+    const existingByUid = new Map(existingFlat.map((eb) => [eb.uid, eb]));
+    /**
+     * Resolve the desired parent UID for a new block.
+     * If the parent was matched to an existing block, use that UID.
+     */
+    function desiredParentUid(newBlock) {
+        if (!newBlock.parentRef)
+            return parentUid;
+        const parentNewUid = newBlock.parentRef.blockUid;
+        if (parentNewUid === parentUid)
+            return parentUid;
+        // If parent is matched, target the existing parent UID
+        return matches.get(parentNewUid) ?? parentNewUid;
+    }
+    // Build desired structure: map each new block to its desired parent
+    // and group siblings by their desired parent
+    const newUidToDesiredParent = new Map();
+    const siblingsByDesiredParent = new Map();
+    for (const newBlock of newBlocks) {
+        const newUid = newBlock.ref.blockUid;
+        const targetUid = matches.get(newUid) ?? newUid;
+        const dParent = desiredParentUid(newBlock);
+        newUidToDesiredParent.set(newUid, dParent);
+        if (!siblingsByDesiredParent.has(dParent)) {
+            siblingsByDesiredParent.set(dParent, []);
+        }
+        siblingsByDesiredParent.get(dParent).push(targetUid);
+    }
+    // Step 2: Process each new block
+    for (const newBlock of newBlocks) {
+        const newUid = newBlock.ref.blockUid;
+        if (matches.has(newUid)) {
+            // Block matched to an existing block
+            const existUid = matches.get(newUid);
+            const existBlock = existingByUid.get(existUid);
+            const currentParent = existBlock.parentUid ?? parentUid;
+            const dParent = newUidToDesiredParent.get(newUid);
+            result.preservedUids.add(existUid);
+            // Check for text/heading changes -> update-block
+            let needsUpdate = false;
+            const updateAction = {
+                action: 'update-block',
+                block: { uid: existUid },
+            };
+            if (normalizeText(newBlock.text) !== normalizeText(existBlock.text)) {
+                updateAction.block.string = newBlock.text;
+                needsUpdate = true;
+            }
+            if (newBlock.heading !== existBlock.heading) {
+                if (newBlock.heading !== null) {
+                    updateAction.block.heading = newBlock.heading;
+                    needsUpdate = true;
+                }
+                else if (existBlock.heading !== null) {
+                    // Remove heading by setting to 0
+                    updateAction.block.heading = 0;
+                    needsUpdate = true;
+                }
+            }
+            if (needsUpdate) {
+                result.updates.push(updateAction);
+            }
+            // Check for parent/order changes -> move-block
+            const desiredSiblings = siblingsByDesiredParent.get(dParent) ?? [];
+            const desiredOrder = desiredSiblings.indexOf(existUid);
+            if (currentParent !== dParent || existBlock.order !== desiredOrder) {
+                result.moves.push({
+                    action: 'move-block',
+                    block: { uid: existUid },
+                    location: { 'parent-uid': dParent, order: desiredOrder },
+                });
+            }
+        }
+        else {
+            // No match -> create-block
+            const dParent = newUidToDesiredParent.get(newUid);
+            const desiredSiblings = siblingsByDesiredParent.get(dParent) ?? [];
+            const desiredOrder = desiredSiblings.indexOf(newUid);
+            const createAction = {
+                action: 'create-block',
+                location: {
+                    'parent-uid': dParent,
+                    order: desiredOrder >= 0 ? desiredOrder : 'last',
+                },
+                block: {
+                    uid: newBlock.ref.blockUid,
+                    string: newBlock.text,
+                },
+            };
+            if (newBlock.heading !== null) {
+                createAction.block.heading = newBlock.heading;
+            }
+            if (newBlock.open !== undefined) {
+                createAction.block.open = newBlock.open;
+            }
+            result.creates.push(createAction);
+        }
+    }
+    // Step 3: Find unmatched existing blocks -> delete
+    const matchedExistingUids = new Set(matches.values());
+    for (const existBlock of existingFlat) {
+        if (!matchedExistingUids.has(existBlock.uid)) {
+            result.deletes.push({
+                action: 'delete-block',
+                block: { uid: existBlock.uid },
+            });
+        }
+    }
+    return result;
+}
+/**
+ * Diff blocks at a specific level (for hierarchical diffing).
+ * Used internally for recursive tree comparison.
+ */
+export function diffBlockLevel(existing, newBlocks, parentUid) {
+    // Filter to only blocks at this level (direct children of parentUid)
+    const existingAtLevel = existing.filter((e) => e.parentUid === parentUid || e.parentUid === null);
+    const newAtLevel = newBlocks.filter((n) => n.parentRef?.blockUid === parentUid || (!n.parentRef && parentUid === parentUid));
+    return diffBlockTrees(existingAtLevel, newAtLevel, parentUid);
+}