roam-research-mcp 1.3.2 → 1.6.0

package/build/cli/commands/search.js

@@ -0,0 +1,79 @@
+import { Command } from 'commander';
+import { initializeGraph } from '@roam-research/roam-api-sdk';
+import { API_TOKEN, GRAPH_NAME } from '../../config/environment.js';
+import { SearchOperations } from '../../tools/operations/search/index.js';
+import { formatSearchResults, printDebug, exitWithError } from '../utils/output.js';
+export function createSearchCommand() {
+    return new Command('search')
+        .description('Search for content in Roam')
+        .argument('[terms...]', 'Search terms (multiple terms use AND logic)')
+        .option('--tag <tag>', 'Filter by tag (e.g., "#TODO" or "[[Project]]")')
+        .option('--page <title>', 'Scope search to a specific page')
+        .option('-i, --case-insensitive', 'Case-insensitive search')
+        .option('-n, --limit <n>', 'Limit number of results (default: 20)', '20')
+        .option('--json', 'Output as JSON')
+        .option('--debug', 'Show query metadata')
+        .action(async (terms, options) => {
+        try {
+            const graph = initializeGraph({
+                token: API_TOKEN,
+                graph: GRAPH_NAME
+            });
+            const limit = parseInt(options.limit || '20', 10);
+            const outputOptions = {
+                json: options.json,
+                debug: options.debug
+            };
+            if (options.debug) {
+                printDebug('Search terms', terms);
+                printDebug('Options', options);
+            }
+            const searchOps = new SearchOperations(graph);
+            // Determine search type based on options
+            if (options.tag && terms.length === 0) {
+                // Tag-only search
+                const tagName = options.tag.replace(/^#?\[?\[?/, '').replace(/\]?\]?$/, '');
+                if (options.debug) {
+                    printDebug('Tag search', { tag: tagName, page: options.page });
+                }
+                const result = await searchOps.searchForTag(tagName, options.page);
+                const limitedMatches = result.matches.slice(0, limit);
+                console.log(formatSearchResults(limitedMatches, outputOptions));
+            }
+            else if (terms.length > 0) {
+                // Text search (with optional tag filter)
+                const searchText = terms.join(' ');
+                if (options.debug) {
+                    printDebug('Text search', { text: searchText, page: options.page, tag: options.tag });
+                }
+                const result = await searchOps.searchByText({
+                    text: searchText,
+                    page_title_uid: options.page
+                });
+                // Apply client-side filters
+                let matches = result.matches;
+                // Case-insensitive filter if requested
+                if (options.caseInsensitive) {
+                    const lowerSearchText = searchText.toLowerCase();
+                    matches = matches.filter(m => m.content.toLowerCase().includes(lowerSearchText));
+                }
+                // Tag filter if provided
+                if (options.tag) {
+                    const tagPattern = options.tag.replace(/^#?\[?\[?/, '').replace(/\]?\]?$/, '');
+                    matches = matches.filter(m => m.content.includes(`[[${tagPattern}]]`) ||
+                        m.content.includes(`#${tagPattern}`) ||
+                        m.content.includes(`#[[${tagPattern}]]`));
+                }
+                // Apply limit
+                console.log(formatSearchResults(matches.slice(0, limit), outputOptions));
+            }
+            else {
+                exitWithError('Please provide search terms or use --tag to search by tag');
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            exitWithError(message);
+        }
+    });
+}

package/build/cli/roam.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { createGetCommand } from './commands/get.js';
+import { createSearchCommand } from './commands/search.js';
+import { createSaveCommand } from './commands/save.js';
+import { createRefsCommand } from './commands/refs.js';
+const program = new Command();
+program
+    .name('roam')
+    .description('CLI for Roam Research')
+    .version('1.6.0');
+// Register subcommands
+program.addCommand(createGetCommand());
+program.addCommand(createSearchCommand());
+program.addCommand(createSaveCommand());
+program.addCommand(createRefsCommand());
+// Parse arguments
+program.parse();

package/build/cli/utils/output.js

@@ -0,0 +1,88 @@
+/**
+ * Convert RoamBlock hierarchy to markdown with proper indentation
+ */
+export function blocksToMarkdown(blocks, level = 0) {
+    return blocks
+        .map(block => {
+        const indent = '  '.repeat(level);
+        let md;
+        // Check block heading level and format accordingly
+        if (block.heading && block.heading > 0) {
+            const hashtags = '#'.repeat(block.heading);
+            md = `${indent}${hashtags} ${block.string}`;
+        }
+        else {
+            md = `${indent}- ${block.string}`;
+        }
+        if (block.children && block.children.length > 0) {
+            md += '\n' + blocksToMarkdown(block.children, level + 1);
+        }
+        return md;
+    })
+        .join('\n');
+}
+/**
+ * Flatten block hierarchy to single-level list
+ */
+export function flattenBlocks(blocks, result = []) {
+    for (const block of blocks) {
+        result.push({ ...block, children: [] });
+        if (block.children && block.children.length > 0) {
+            flattenBlocks(block.children, result);
+        }
+    }
+    return result;
+}
+/**
+ * Format page content for output
+ */
+export function formatPageOutput(title, blocks, options) {
+    if (options.json) {
+        const data = options.flat ? flattenBlocks(blocks) : blocks;
+        return JSON.stringify({ title, children: data }, null, 2);
+    }
+    const displayBlocks = options.flat ? flattenBlocks(blocks) : blocks;
+    return `# ${title}\n\n${blocksToMarkdown(displayBlocks)}`;
+}
+/**
+ * Format block content for output
+ */
+export function formatBlockOutput(block, options) {
+    if (options.json) {
+        const data = options.flat ? flattenBlocks([block]) : block;
+        return JSON.stringify(data, null, 2);
+    }
+    const displayBlocks = options.flat ? flattenBlocks([block]) : [block];
+    return blocksToMarkdown(displayBlocks);
+}
+/**
+ * Format search results for output
+ */
+export function formatSearchResults(results, options) {
+    if (options.json) {
+        return JSON.stringify(results, null, 2);
+    }
+    if (results.length === 0) {
+        return 'No results found.';
+    }
+    let output = `Found ${results.length} result(s):\n\n`;
+    results.forEach((result, index) => {
+        const pageInfo = result.page_title ? ` (${result.page_title})` : '';
+        output += `[${index + 1}] ${result.block_uid}${pageInfo}\n`;
+        output += `    ${result.content}\n\n`;
+    });
+    return output.trim();
+}
+/**
+ * Print debug information
+ */
+export function printDebug(label, data) {
+    console.error(`[DEBUG] ${label}:`, JSON.stringify(data, null, 2));
+}
+/**
+ * Print error message and exit
+ */
+export function exitWithError(message, code = 1) {
+    console.error(`Error: ${message}`);
+    process.exit(code);
+}

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);
+}