roam-research-mcp 1.6.0 → 2.4.0

package/build/cli/commands/save.js

@@ -1,11 +1,14 @@
 import { Command } from 'commander';
-import { readFileSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { basename } from 'path';
-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';
+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
  */
@@ -33,85 +36,459 @@ async function readStdin() {
     }
     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('Import markdown to Roam')
-        .argument('[file]', 'Markdown file to import (or pipe content to stdin)')
-        .option('--title <title>', 'Page title (defaults to filename without .md)')
-        .option('--update', 'Update existing page using smart diff')
+        .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')
-        .action(async (file, options) => {
+        .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 {
-            let markdownContent;
-            let pageTitle;
-            if (file) {
-                // Read from file
-                try {
-                    markdownContent = readFileSync(file, 'utf-8');
+            // 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;
                 }
-                catch (err) {
-                    exitWithError(`Could not read file: ${file}`);
+                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;
                 }
-                // Derive title from filename if not provided
-                pageTitle = options.title || basename(file, '.md');
             }
             else {
                 // Read from stdin
                 if (process.stdin.isTTY) {
-                    exitWithError('No file specified and no input piped. Use: roam save <file.md> or cat file.md | roam save --title "Title"');
+                    exitWithError('No input. Use: roam save "text", roam save <file>, or pipe content');
                 }
-                if (!options.title) {
-                    exitWithError('--title is required when piping from stdin');
+                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');
                 }
-                markdownContent = await readStdin();
-                pageTitle = options.title;
             }
-            if (!markdownContent.trim()) {
-                exitWithError('Empty content received');
+            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('Page title', pageTitle);
-                printDebug('Content length', markdownContent.length);
-                printDebug('Update mode', options.update || false);
-            }
-            const graph = initializeGraph({
-                token: API_TOKEN,
-                graph: GRAPH_NAME
-            });
-            const pageOps = new PageOperations(graph);
-            if (options.update) {
-                // Use smart diff to update existing page
-                const result = await pageOps.updatePageMarkdown(pageTitle, markdownContent, false // not dry run
-                );
-                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)`);
+                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 {
-                    exitWithError(`Failed to update page '${pageTitle}'`);
+                    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 {
-                // Create new page (or add content to existing empty page)
-                const nodes = parseMarkdown(markdownContent);
-                const contentBlocks = flattenNodes(nodes);
-                if (contentBlocks.length === 0) {
-                    exitWithError('No content blocks parsed from input');
+                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;
                 }
-                if (options.debug) {
-                    printDebug('Parsed blocks', contentBlocks.length);
+                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;
+                    }
                 }
-                const result = await pageOps.createPage(pageTitle, contentBlocks);
-                if (result.success) {
-                    console.log(`Created page '${pageTitle}' (uid: ${result.uid})`);
+                // 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 {
-                    exitWithError(`Failed to create page '${pageTitle}'`);
+                    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);