roam-research-mcp 1.4.0 → 2.4.0

package/build/cli/commands/rename.js

@@ -0,0 +1,58 @@
+import { Command } from 'commander';
+import { updatePage } from '@roam-research/roam-api-sdk';
+import { printDebug, exitWithError } from '../utils/output.js';
+import { resolveGraph } from '../utils/graph.js';
+export function createRenameCommand() {
+    return new Command('rename')
+        .description('Rename a page')
+        .argument('<old-title>', 'Current page title (or use --uid for UID)')
+        .argument('<new-title>', 'New page title')
+        .option('-u, --uid <uid>', 'Use page UID instead of title')
+        .option('-g, --graph <name>', 'Target graph key (multi-graph mode)')
+        .option('--write-key <key>', 'Write confirmation key (non-default graphs)')
+        .option('--debug', 'Show debug information')
+        .addHelpText('after', `
+Examples:
+  # Rename by title
+  roam rename "Old Page Name" "New Page Name"
+
+  # Rename by UID
+  roam rename --uid abc123def "New Page Name"
+
+  # Multi-graph
+  roam rename "Draft" "Published" -g work --write-key confirm
+`)
+        .action(async (oldTitle, newTitle, options) => {
+        try {
+            if (options.debug) {
+                printDebug('Old title', oldTitle);
+                printDebug('New title', newTitle);
+                printDebug('UID', options.uid || 'none (using title)');
+                printDebug('Graph', options.graph || 'default');
+            }
+            const graph = resolveGraph(options, true); // Write operation
+            // Build the page identifier
+            const pageIdentifier = options.uid
+                ? { uid: options.uid }
+                : { title: oldTitle };
+            if (options.debug) {
+                printDebug('Page identifier', pageIdentifier);
+            }
+            const success = await updatePage(graph, {
+                page: pageIdentifier,
+                title: newTitle
+            });
+            if (success) {
+                const identifier = options.uid ? `((${options.uid}))` : `"${oldTitle}"`;
+                console.log(`Renamed ${identifier} → "${newTitle}"`);
+            }
+            else {
+                exitWithError('Failed to rename page (API returned false)');
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            exitWithError(message);
+        }
+    });
+}

package/build/cli/commands/save.js

@@ -0,0 +1,498 @@
+import { Command } from 'commander';
+import { existsSync, readFileSync } from 'fs';
+import { basename } from 'path';
+import { PageOperations } from '../../tools/operations/pages.js';
+import { TodoOperations } from '../../tools/operations/todos.js';
+import { BatchOperations } from '../../tools/operations/batch.js';
+import { parseMarkdown, generateBlockUid, parseMarkdownHeadingLevel } from '../../markdown-utils.js';
+import { printDebug, exitWithError } from '../utils/output.js';
+import { resolveGraph } from '../utils/graph.js';
+import { formatRoamDate } from '../../utils/helpers.js';
+import { q, createPage as roamCreatePage } from '@roam-research/roam-api-sdk';
+/**
+ * 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');
+}
+/**
+ * Check if a string looks like a Roam block UID (9 alphanumeric chars with _ or -)
+ */
+function isBlockUid(value) {
+    // Strip (( )) wrapper if present
+    const cleaned = value.replace(/^\(\(|\)\)$/g, '');
+    return /^[a-zA-Z0-9_-]{9}$/.test(cleaned);
+}
+/**
+ * Check if content looks like a JSON array
+ */
+function looksLikeJsonArray(content) {
+    const trimmed = content.trim();
+    return trimmed.startsWith('[') && trimmed.endsWith(']');
+}
+/**
+ * Find or create a page by title, returns UID
+ */
+async function findOrCreatePage(graph, title) {
+    const findQuery = `[:find ?uid :in $ ?title :where [?e :node/title ?title] [?e :block/uid ?uid]]`;
+    const findResults = await q(graph, findQuery, [title]);
+    if (findResults && findResults.length > 0) {
+        return findResults[0][0];
+    }
+    // Create the page if it doesn't exist
+    await roamCreatePage(graph, {
+        action: 'create-page',
+        page: { title }
+    });
+    const results = await q(graph, findQuery, [title]);
+    if (!results || results.length === 0) {
+        throw new Error(`Could not find created page: ${title}`);
+    }
+    return results[0][0];
+}
+/**
+ * Get or create today's daily page UID
+ */
+async function getDailyPageUid(graph) {
+    const today = new Date();
+    const dateStr = formatRoamDate(today);
+    return findOrCreatePage(graph, dateStr);
+}
+/**
+ * Find or create a heading block on a page
+ */
+async function findOrCreateHeading(graph, pageUid, heading, headingLevel) {
+    // Search for existing heading block
+    const headingQuery = `[:find ?uid
+                        :in $ ?page-uid ?text
+                        :where
+                        [?page :block/uid ?page-uid]
+                        [?page :block/children ?block]
+                        [?block :block/string ?text]
+                        [?block :block/uid ?uid]]`;
+    const headingResults = await q(graph, headingQuery, [pageUid, heading]);
+    if (headingResults && headingResults.length > 0) {
+        return headingResults[0][0];
+    }
+    // Create the heading block
+    const batchOps = new BatchOperations(graph);
+    const headingUid = generateBlockUid();
+    await batchOps.processBatch([{
+            action: 'create-block',
+            location: { 'parent-uid': pageUid, order: 'last' },
+            string: heading,
+            uid: headingUid,
+            ...(headingLevel && { heading: headingLevel })
+        }]);
+    return headingUid;
+}
+/**
+ * Parse JSON content blocks
+ */
+function parseJsonContent(content) {
+    const parsed = JSON.parse(content);
+    if (!Array.isArray(parsed)) {
+        throw new Error('JSON content must be an array of {text, level, heading?} objects');
+    }
+    return parsed.map((item, index) => {
+        if (typeof item.text !== 'string' || typeof item.level !== 'number') {
+            throw new Error(`Invalid item at index ${index}: must have "text" (string) and "level" (number)`);
+        }
+        // If heading not explicitly provided, detect from text and strip hashes
+        if (item.heading) {
+            return {
+                text: item.text,
+                level: item.level,
+                heading: item.heading
+            };
+        }
+        const { heading_level, content: strippedText } = parseMarkdownHeadingLevel(item.text);
+        return {
+            text: strippedText,
+            level: item.level,
+            ...(heading_level > 0 && { heading: heading_level })
+        };
+    });
+}
+export function createSaveCommand() {
+    return new Command('save')
+        .description('Save text, files, or JSON to pages/blocks. Auto-detects format.')
+        .argument('[input]', 'Text, file path, or "-" for stdin (auto-detected)')
+        .option('--title <title>', 'Create a new page with this title')
+        .option('--update', 'Update existing page using smart diff (preserves block UIDs)')
+        .option('-p, --page <ref>', 'Target page by title or UID (default: daily page, creates if missing)')
+        .option('--parent <ref>', 'Nest under block UID ((uid)) or heading text (creates if missing). Use # prefix for heading level: "## Section"')
+        .option('-c, --categories <tags>', 'Comma-separated tags appended to first block')
+        .option('-t, --todo [text]', 'Add TODO item(s) to daily page. Accepts inline text or stdin')
+        .option('--json', 'Force JSON array format: [{text, level, heading?}, ...]')
+        .option('-g, --graph <name>', 'Target graph key (multi-graph mode)')
+        .option('--write-key <key>', 'Write confirmation key (non-default graphs)')
+        .option('--debug', 'Show debug information')
+        .addHelpText('after', `
+Examples:
+  # Quick saves to daily page
+  roam save "Quick note"                          # Single block
+  roam save "# Important" -c "work,urgent"        # H1 heading with tags
+  roam save --todo "Buy groceries"                # TODO item
+
+  # Save under heading (creates if missing)
+  roam save --parent "## Notes" "My note"         # Under H2 "Notes" heading
+  roam save --parent "((blockUid9))" "Child"      # Under specific block
+
+  # Target specific page
+  roam save -p "Project X" "Status update"        # By title (creates if missing)
+  roam save -p "pageUid123" "Note"                # By UID
+
+  # File operations
+  roam save notes.md --title "My Notes"           # Create page from file
+  roam save notes.md --title "My Notes" --update  # Smart update (preserves UIDs)
+  cat data.json | roam save --json                # Pipe JSON blocks
+
+  # Combine options
+  roam save -p "Work" --parent "## Today" "Done with task" -c "wins"
+
+JSON format (--json):
+  Array of blocks with text, level, and optional heading:
+  [
+    {"text": "# Main Title", "level": 1},           # Auto-detects H1
+    {"text": "Subheading", "level": 1, "heading": 2}, # Explicit H2
+    {"text": "Nested content", "level": 2},         # Child block
+    {"text": "Sibling", "level": 2}
+  ]
+`)
+        .action(async (input, options) => {
+        try {
+            // TODO mode: add a TODO item to today's daily page
+            if (options.todo !== undefined) {
+                let todoText;
+                if (typeof options.todo === 'string' && options.todo.length > 0) {
+                    todoText = options.todo;
+                }
+                else {
+                    if (process.stdin.isTTY) {
+                        exitWithError('No TODO text. Use: roam save --todo "text" or echo "text" | roam save --todo');
+                    }
+                    todoText = (await readStdin()).trim();
+                }
+                if (!todoText) {
+                    exitWithError('Empty TODO text');
+                }
+                const todos = todoText.split('\n').map(t => t.trim()).filter(Boolean);
+                if (options.debug) {
+                    printDebug('TODO mode', true);
+                    printDebug('Graph', options.graph || 'default');
+                    printDebug('TODO items', todos);
+                }
+                const graph = resolveGraph(options, true);
+                const todoOps = new TodoOperations(graph);
+                const result = await todoOps.addTodos(todos);
+                if (result.success) {
+                    console.log(`Added ${todos.length} TODO item(s) to today's daily page`);
+                }
+                else {
+                    exitWithError('Failed to save TODO');
+                }
+                return;
+            }
+            // Determine content source: file, text argument, or stdin
+            let content;
+            let isFile = false;
+            let sourceFilename;
+            if (input) {
+                // Check if input is a file path that exists
+                if (existsSync(input)) {
+                    isFile = true;
+                    sourceFilename = input;
+                    try {
+                        content = readFileSync(input, 'utf-8');
+                    }
+                    catch (err) {
+                        exitWithError(`Could not read file: ${input}`);
+                    }
+                }
+                else {
+                    // Treat as text content
+                    content = input;
+                }
+            }
+            else {
+                // Read from stdin
+                if (process.stdin.isTTY) {
+                    exitWithError('No input. Use: roam save "text", roam save <file>, or pipe content');
+                }
+                content = await readStdin();
+            }
+            content = content.trim();
+            if (!content) {
+                exitWithError('Empty content');
+            }
+            // Determine format: JSON or markdown/text
+            const isJson = options.json || (isFile && sourceFilename?.endsWith('.json')) || looksLikeJsonArray(content);
+            // Parse content into blocks
+            let contentBlocks;
+            if (isJson) {
+                try {
+                    contentBlocks = parseJsonContent(content);
+                }
+                catch (err) {
+                    exitWithError(err instanceof Error ? err.message : 'Invalid JSON');
+                }
+            }
+            else if (isFile || content.includes('\n')) {
+                // Multi-line content: parse as markdown
+                const nodes = parseMarkdown(content);
+                contentBlocks = flattenNodes(nodes);
+            }
+            else {
+                // Single line text: detect heading syntax and strip hashes
+                const { heading_level, content: strippedContent } = parseMarkdownHeadingLevel(content);
+                contentBlocks = [{
+                        text: strippedContent,
+                        level: 1,
+                        ...(heading_level > 0 && { heading: heading_level })
+                    }];
+            }
+            if (contentBlocks.length === 0) {
+                exitWithError('No content blocks parsed');
+            }
+            // Parse categories
+            const categories = options.categories
+                ? options.categories.split(',').map(c => c.trim()).filter(Boolean)
+                : undefined;
+            // Determine parent type if specified
+            let parentUid;
+            let parentHeading;
+            let parentHeadingLevel;
+            if (options.parent) {
+                const cleanedParent = options.parent.replace(/^\(\(|\)\)$/g, '');
+                if (isBlockUid(cleanedParent)) {
+                    parentUid = cleanedParent;
+                }
+                else {
+                    // Parse heading syntax from parent text
+                    const { heading_level, content } = parseMarkdownHeadingLevel(options.parent);
+                    parentHeading = content;
+                    if (heading_level > 0) {
+                        parentHeadingLevel = heading_level;
+                    }
+                }
+            }
+            if (options.debug) {
+                printDebug('Input', input || 'stdin');
+                printDebug('Is file', isFile);
+                printDebug('Is JSON', isJson);
+                printDebug('Graph', options.graph || 'default');
+                printDebug('Content blocks', contentBlocks.length);
+                printDebug('Parent UID', parentUid || 'none');
+                printDebug('Parent heading', parentHeading || 'none');
+                printDebug('Target page', options.page || 'daily page');
+                printDebug('Categories', categories || 'none');
+                printDebug('Title', options.title || 'none');
+            }
+            const graph = resolveGraph(options, true);
+            // Determine operation mode based on options
+            const hasParent = parentUid || parentHeading;
+            const hasTitle = options.title;
+            const wantsPage = hasTitle && !hasParent;
+            if (wantsPage || (isFile && !hasParent)) {
+                // PAGE MODE: create a page
+                const pageTitle = options.title || (sourceFilename ? basename(sourceFilename, '.md').replace('.json', '') : undefined);
+                if (!pageTitle) {
+                    exitWithError('--title required for page creation from stdin');
+                }
+                const pageOps = new PageOperations(graph);
+                if (options.update) {
+                    if (isJson) {
+                        exitWithError('--update is not supported with JSON content');
+                    }
+                    const result = await pageOps.updatePageMarkdown(pageTitle, content, false);
+                    if (result.success) {
+                        console.log(`Updated page '${pageTitle}'`);
+                        console.log(`  ${result.summary}`);
+                        if (result.preservedUids.length > 0) {
+                            console.log(`  Preserved ${result.preservedUids.length} block UID(s)`);
+                        }
+                    }
+                    else {
+                        exitWithError(`Failed to update page '${pageTitle}'`);
+                    }
+                }
+                else {
+                    const result = await pageOps.createPage(pageTitle, contentBlocks);
+                    if (result.success) {
+                        console.log(`Created page '${pageTitle}' (uid: ${result.uid})`);
+                    }
+                    else {
+                        exitWithError(`Failed to create page '${pageTitle}'`);
+                    }
+                }
+                return;
+            }
+            // BLOCK MODE: add content under parent or to daily page
+            if (parentUid) {
+                // Direct parent UID: use batch operations
+                const batchOps = new BatchOperations(graph);
+                // Build batch actions for all content blocks
+                const actions = [];
+                const uidMap = {};
+                for (let i = 0; i < contentBlocks.length; i++) {
+                    const block = contentBlocks[i];
+                    const uidPlaceholder = `block-${i}`;
+                    uidMap[i] = uidPlaceholder;
+                    // Determine parent for this block
+                    let blockParent;
+                    if (block.level === 1) {
+                        blockParent = parentUid;
+                    }
+                    else {
+                        // Find the closest ancestor at level - 1
+                        let ancestorIndex = i - 1;
+                        while (ancestorIndex >= 0 && contentBlocks[ancestorIndex].level >= block.level) {
+                            ancestorIndex--;
+                        }
+                        if (ancestorIndex >= 0) {
+                            blockParent = `{{uid:${uidMap[ancestorIndex]}}}`;
+                        }
+                        else {
+                            blockParent = parentUid;
+                        }
+                    }
+                    actions.push({
+                        action: 'create-block',
+                        location: {
+                            'parent-uid': blockParent,
+                            order: 'last'
+                        },
+                        string: block.text,
+                        uid: `{{uid:${uidPlaceholder}}}`,
+                        ...(block.heading && { heading: block.heading })
+                    });
+                }
+                const result = await batchOps.processBatch(actions);
+                if (result.success && result.uid_map) {
+                    // Output the first block's UID
+                    console.log(result.uid_map['block-0']);
+                }
+                else {
+                    const errorMsg = typeof result.error === 'string'
+                        ? result.error
+                        : result.error?.message || 'Unknown error';
+                    exitWithError(`Failed to save: ${errorMsg}`);
+                }
+                return;
+            }
+            // Parent heading or target page: get target page UID first
+            let pageUid;
+            if (options.page) {
+                // Strip (( )) wrapper if UID, but NOT [[ ]] (that's valid page title syntax)
+                const cleanedPage = options.page.replace(/^\(\(|\)\)$/g, '');
+                if (isBlockUid(cleanedPage)) {
+                    pageUid = cleanedPage;
+                }
+                else {
+                    pageUid = await findOrCreatePage(graph, options.page);
+                }
+            }
+            else {
+                pageUid = await getDailyPageUid(graph);
+            }
+            if (options.debug) {
+                printDebug('Target page UID', pageUid);
+            }
+            // Resolve heading to parent UID if specified
+            let targetParentUid;
+            if (parentHeading) {
+                targetParentUid = await findOrCreateHeading(graph, pageUid, parentHeading, parentHeadingLevel);
+            }
+            else {
+                targetParentUid = pageUid;
+            }
+            // Format categories as Roam tags if provided
+            const categoryTags = categories?.map(cat => {
+                return cat.includes(' ') ? `#[[${cat}]]` : `#${cat}`;
+            }).join(' ') || '';
+            // Create all blocks using batch operations
+            const batchOps = new BatchOperations(graph);
+            const actions = [];
+            const uidMap = {};
+            for (let i = 0; i < contentBlocks.length; i++) {
+                const block = contentBlocks[i];
+                const uidPlaceholder = `block-${i}`;
+                uidMap[i] = uidPlaceholder;
+                // Determine parent for this block
+                let blockParent;
+                if (block.level === 1) {
+                    blockParent = targetParentUid;
+                }
+                else {
+                    // Find the closest ancestor at level - 1
+                    let ancestorIndex = i - 1;
+                    while (ancestorIndex >= 0 && contentBlocks[ancestorIndex].level >= block.level) {
+                        ancestorIndex--;
+                    }
+                    if (ancestorIndex >= 0) {
+                        blockParent = `{{uid:${uidMap[ancestorIndex]}}}`;
+                    }
+                    else {
+                        blockParent = targetParentUid;
+                    }
+                }
+                // Append category tags to first block only
+                const blockText = i === 0 && categoryTags
+                    ? `${block.text} ${categoryTags}`
+                    : block.text;
+                actions.push({
+                    action: 'create-block',
+                    location: {
+                        'parent-uid': blockParent,
+                        order: 'last'
+                    },
+                    string: blockText,
+                    uid: `{{uid:${uidPlaceholder}}}`,
+                    ...(block.heading && { heading: block.heading })
+                });
+            }
+            const result = await batchOps.processBatch(actions);
+            if (result.success && result.uid_map) {
+                // Output first block UID (and parent if heading was used)
+                if (parentHeading) {
+                    console.log(`${result.uid_map['block-0']} ${targetParentUid}`);
+                }
+                else {
+                    console.log(result.uid_map['block-0']);
+                }
+            }
+            else {
+                const errorMsg = typeof result.error === 'string'
+                    ? result.error
+                    : result.error?.message || 'Unknown error';
+                exitWithError(`Failed to save: ${errorMsg}`);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            exitWithError(message);
+        }
+    });
+}