roam-research-mcp 1.6.0 → 2.4.3

package/build/cli/commands/batch.js

@@ -0,0 +1,345 @@
+import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { BatchOperations } from '../../tools/operations/batch.js';
+import { PageOperations } from '../../tools/operations/pages.js';
+import { printDebug, exitWithError } from '../utils/output.js';
+import { resolveGraph } from '../utils/graph.js';
+import { collectPageTitles, resolveAllPages, resolveDailyPageUid, needsDailyPage, createResolutionContext, getDailyPageTitle } from '../batch/resolver.js';
+import { translateAllCommands } from '../batch/translator.js';
+import { readStdin } from '../utils/input.js';
+// Required params per command type
+const REQUIRED_PARAMS = {
+    todo: ['text'],
+    create: ['parent', 'text'],
+    update: ['uid'],
+    delete: ['uid'],
+    move: ['uid', 'parent'],
+    page: ['title'],
+    outline: ['parent', 'items'],
+    table: ['parent', 'headers', 'rows'],
+    remember: ['text'],
+    codeblock: ['parent', 'code']
+};
+const VALID_COMMAND_TYPES = Object.keys(REQUIRED_PARAMS);
+/**
+ * Validate command structure and required params
+ */
+function validateCommands(commands) {
+    const validated = [];
+    for (let i = 0; i < commands.length; i++) {
+        const cmd = commands[i];
+        if (!cmd || typeof cmd !== 'object') {
+            throw new Error(`[${i}] Command must be an object`);
+        }
+        if (!cmd.command || typeof cmd.command !== 'string') {
+            throw new Error(`[${i}] Missing 'command' field`);
+        }
+        const cmdType = cmd.command;
+        if (!VALID_COMMAND_TYPES.includes(cmdType)) {
+            throw new Error(`[${i}] Unknown command type '${cmdType}'. Valid: ${VALID_COMMAND_TYPES.join(', ')}`);
+        }
+        if (!cmd.params || typeof cmd.params !== 'object') {
+            throw new Error(`[${i}] Missing 'params' field`);
+        }
+        // Check required params
+        const params = cmd.params;
+        const required = REQUIRED_PARAMS[cmdType];
+        for (const param of required) {
+            if (params[param] === undefined) {
+                throw new Error(`[${i}] ${cmdType}: missing required param '${param}'`);
+            }
+        }
+        validated.push(cmd);
+    }
+    return validated;
+}
+/**
+ * Validate placeholder references are defined before use
+ * Returns list of errors (empty = valid)
+ */
+function validatePlaceholders(commands) {
+    const errors = [];
+    const definedPlaceholders = new Set();
+    for (let i = 0; i < commands.length; i++) {
+        const cmd = commands[i];
+        const params = cmd.params;
+        // Collect placeholder definitions from 'as' params
+        if (typeof params.as === 'string') {
+            definedPlaceholders.add(params.as);
+        }
+        // Check placeholder references in 'parent' param
+        if (typeof params.parent === 'string') {
+            const match = params.parent.match(/^\{\{(\w+)\}\}$/);
+            if (match) {
+                const refName = match[1];
+                if (!definedPlaceholders.has(refName)) {
+                    errors.push(`[${i}] ${cmd.command}: placeholder "{{${refName}}}" used before definition`);
+                }
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Output partial results when a failure occurs mid-batch
+ * Helps user know what was created and may need manual cleanup
+ */
+function outputPartialResults(pageResults, failedPage, batchError) {
+    const output = {
+        success: false,
+        partial: true,
+        pages_created: pageResults.length,
+        ...(failedPage && { failed_at: `page: ${failedPage}` }),
+        ...(batchError && { failed_at: `batch: ${batchError}` })
+    };
+    if (pageResults.length > 0) {
+        output.created_pages = pageResults.map(p => ({
+            title: p.title,
+            uid: p.uid
+        }));
+        output.cleanup_hint = 'Pages listed above were created before failure. Delete manually if needed.';
+    }
+    console.error(JSON.stringify(output, null, 2));
+    process.exit(1);
+}
+/** Format action for dry-run display */
+function formatAction(action, index) {
+    const lines = [`  ${index + 1}. ${action.action}`];
+    if (action.string) {
+        const text = String(action.string);
+        const preview = text.length > 60 ? text.slice(0, 60) + '...' : text;
+        lines.push(`     text: "${preview}"`);
+    }
+    if (action.location) {
+        const loc = action.location;
+        lines.push(`     parent: ${loc['parent-uid']}`);
+    }
+    if (action.uid) {
+        lines.push(`     uid: ${action.uid}`);
+    }
+    return lines.join('\n');
+}
+export function createBatchCommand() {
+    return new Command('batch')
+        .description('Execute multiple block operations efficiently in a single API call')
+        .argument('[file]', 'JSON file with commands (or pipe via stdin)')
+        .option('--debug', 'Show debug information')
+        .option('--dry-run', 'Validate and show planned actions without executing')
+        .option('--simulate', 'Validate structure offline (no API calls)')
+        .option('-g, --graph <name>', 'Target graph key (for multi-graph mode)')
+        .option('--write-key <key>', 'Write confirmation key (for non-default graphs)')
+        .addHelpText('after', `
+Examples:
+  # From file
+  roam batch commands.json                # Execute commands from file
+  roam batch commands.json --dry-run      # Preview without executing (resolves pages)
+  roam batch commands.json --simulate     # Validate offline (no API calls)
+
+  # From stdin
+  cat commands.json | roam batch          # Pipe commands
+  echo '[{"command":"todo","params":{"text":"Task 1"}}]' | roam batch
+
+Command schemas:
+  todo:      {text}
+  create:    {parent, text, as?, heading?, order?}
+  update:    {uid, text?, heading?, open?}
+  delete:    {uid}
+  move:      {uid, parent, order?}
+  page:      {title, as?, content?: [{text, level, heading?}...]}
+  outline:   {parent, items: [string...]}
+  table:     {parent, headers: [string...], rows: [{label, cells: [string...]}...]}
+  remember:  {text, categories?: [string...]}
+  codeblock: {parent, code, language?}
+
+Parent accepts: block UID, "daily", page title, or {{placeholder}}
+
+Example:
+  [
+    {"command": "page", "params": {"title": "Project X", "as": "proj"}},
+    {"command": "create", "params": {"parent": "{{proj}}", "text": "# Overview", "as": "overview"}},
+    {"command": "outline", "params": {"parent": "{{overview}}", "items": ["Goal 1", "Goal 2"]}},
+    {"command": "todo", "params": {"text": "Review project"}}
+  ]
+`)
+        .action(async (file, options) => {
+        try {
+            // Read input
+            let rawInput;
+            if (file) {
+                try {
+                    rawInput = readFileSync(file, 'utf-8');
+                }
+                catch {
+                    exitWithError(`Could not read file: ${file}`);
+                }
+            }
+            else if (process.stdin.isTTY) {
+                exitWithError('No file specified and no input piped. Use: roam batch commands.json or cat commands.json | roam batch');
+            }
+            else {
+                rawInput = await readStdin();
+            }
+            // Parse JSON
+            let parsed;
+            try {
+                parsed = JSON.parse(rawInput);
+            }
+            catch (err) {
+                exitWithError(`Invalid JSON: ${err instanceof SyntaxError ? err.message : 'parse error'}`);
+            }
+            if (!Array.isArray(parsed)) {
+                exitWithError('Input must be a JSON array of commands');
+            }
+            if (parsed.length === 0) {
+                console.log('No commands to execute');
+                return;
+            }
+            // Validate and get typed commands
+            const commands = validateCommands(parsed);
+            // Upfront validation: check placeholder references
+            const placeholderErrors = validatePlaceholders(commands);
+            if (placeholderErrors.length > 0) {
+                exitWithError(`Placeholder validation failed:\n  ${placeholderErrors.join('\n  ')}`);
+            }
+            if (options.debug) {
+                printDebug('Commands', commands.length);
+                printDebug('Graph', options.graph || 'default');
+                printDebug('Mode', options.simulate ? 'simulate' : options.dryRun ? 'dry-run' : 'execute');
+            }
+            // Simulate mode: validate structure without connecting to Roam
+            if (options.simulate) {
+                const context = createResolutionContext();
+                const { actions, pageCommands } = translateAllCommands(commands, context);
+                console.log('\n[SIMULATE] Validation passed\n');
+                console.log(`Commands: ${commands.length}`);
+                console.log(`  Pages to create: ${pageCommands.length}`);
+                console.log(`  Batch actions: ${actions.length}`);
+                if (pageCommands.length > 0) {
+                    console.log('\nPage creations:');
+                    for (const pc of pageCommands) {
+                        const as = pc.params.as ? ` → {{${pc.params.as}}}` : '';
+                        console.log(`  - "${pc.params.title}"${as}`);
+                    }
+                }
+                console.log('\nNo API calls made. Use --dry-run to resolve page UIDs.');
+                return;
+            }
+            const graph = resolveGraph(options, true);
+            // Phase 1: Collect and resolve page titles
+            const context = createResolutionContext();
+            const pageTitles = collectPageTitles(commands);
+            if (pageTitles.size > 0) {
+                if (options.debug) {
+                    printDebug('Pages to resolve', Array.from(pageTitles));
+                }
+                const resolved = await resolveAllPages(graph, pageTitles);
+                for (const [title, uid] of resolved) {
+                    context.pageUids.set(title, uid);
+                }
+                // Check for unresolved pages
+                const unresolved = Array.from(pageTitles).filter(t => !context.pageUids.has(t));
+                if (unresolved.length > 0) {
+                    exitWithError(`Page(s) not found: ${unresolved.map(t => `"${t}"`).join(', ')}`);
+                }
+                if (options.debug) {
+                    printDebug('Resolved pages', Object.fromEntries(context.pageUids));
+                }
+            }
+            // Resolve daily page if needed
+            if (needsDailyPage(commands)) {
+                const dailyUid = await resolveDailyPageUid(graph);
+                if (!dailyUid) {
+                    exitWithError(`Daily page not found: "${getDailyPageTitle()}"`);
+                }
+                context.dailyPageUid = dailyUid;
+                context.pageUids.set(getDailyPageTitle(), dailyUid);
+                if (options.debug) {
+                    printDebug('Daily page UID', dailyUid);
+                }
+            }
+            // Phase 2: Translate commands to batch actions
+            const { actions, pageCommands } = translateAllCommands(commands, context);
+            if (options.debug) {
+                printDebug('Batch actions', actions.length);
+                printDebug('Page commands', pageCommands.length);
+            }
+            // Dry run: show actions and exit
+            if (options.dryRun) {
+                console.log('\n[DRY RUN] Planned actions:\n');
+                if (pageCommands.length > 0) {
+                    console.log('Page creations:');
+                    for (const pc of pageCommands) {
+                        const as = pc.params.as ? ` (as: {{${pc.params.as}}})` : '';
+                        console.log(`  - "${pc.params.title}"${as}`);
+                    }
+                    console.log('');
+                }
+                if (actions.length > 0) {
+                    console.log('Batch actions:');
+                    console.log(actions.map((a, i) => formatAction(a, i)).join('\n'));
+                }
+                console.log(`\nTotal: ${pageCommands.length} page(s), ${actions.length} action(s)`);
+                return;
+            }
+            // Phase 3: Execute page commands (in parallel where possible)
+            const pageResults = [];
+            if (pageCommands.length > 0) {
+                const pageOps = new PageOperations(graph);
+                // Execute page creations - must be sequential if they reference each other
+                for (const pc of pageCommands) {
+                    const result = await pageOps.createPage(pc.params.title, pc.params.content?.map(item => ({
+                        text: item.text,
+                        level: item.level,
+                        heading: item.heading
+                    })));
+                    if (!result.success) {
+                        // Report partial results before exiting
+                        outputPartialResults(pageResults, pc.params.title);
+                    }
+                    pageResults.push({ title: pc.params.title, uid: result.uid });
+                    if (pc.params.as) {
+                        context.placeholders.set(pc.params.as, result.uid);
+                    }
+                    if (options.debug) {
+                        printDebug(`Created "${pc.params.title}"`, result.uid);
+                    }
+                }
+            }
+            // Phase 4: Execute batch actions
+            let batchResult = { success: true, actions_attempted: 0 };
+            if (actions.length > 0) {
+                const batchOps = new BatchOperations(graph);
+                batchResult = await batchOps.processBatch(actions);
+                if (!batchResult.success) {
+                    const errorMsg = typeof batchResult.error === 'string'
+                        ? batchResult.error
+                        : batchResult.error?.message || 'Unknown error';
+                    // Report partial results (pages created before batch failed)
+                    outputPartialResults(pageResults, undefined, errorMsg);
+                }
+            }
+            // Build output
+            const uidMap = {};
+            for (const pr of pageResults) {
+                const pageCmd = pageCommands.find(pc => pc.params.title === pr.title);
+                if (pageCmd?.params.as) {
+                    uidMap[pageCmd.params.as] = pr.uid;
+                }
+            }
+            if (batchResult.uid_map) {
+                Object.assign(uidMap, batchResult.uid_map);
+            }
+            const output = {
+                success: true,
+                pages_created: pageResults.length,
+                actions_executed: actions.length,
+                ...(Object.keys(uidMap).length > 0 && { uid_map: uidMap })
+            };
+            console.log(JSON.stringify(output, null, 2));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            exitWithError(message);
+        }
+    });
+}

package/build/cli/commands/get.js

@@ -1,74 +1,187 @@
 import { Command } from 'commander';
-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 { BlockRetrievalOperations } from '../../tools/operations/block-retrieval.js';
-import { formatPageOutput, formatBlockOutput, printDebug, exitWithError } from '../utils/output.js';
+import { SearchOperations } from '../../tools/operations/search/index.js';
+import { formatPageOutput, formatBlockOutput, formatTodoOutput, printDebug, exitWithError } from '../utils/output.js';
+import { resolveGraph } from '../utils/graph.js';
+import { readStdin } from '../utils/input.js';
+import { resolveRefs } from '../../tools/helpers/refs.js';
+import { resolveRelativeDate } from '../../utils/helpers.js';
 // Block UID pattern: 9 alphanumeric characters, optionally wrapped in (( ))
 const BLOCK_UID_PATTERN = /^(?:\(\()?([a-zA-Z0-9_-]{9})(?:\)\))?$/;
+/**
+ * Recursively resolve block references in a RoamBlock tree
+ */
+async function resolveBlockRefs(graph, block, maxDepth) {
+    const resolvedString = await resolveRefs(graph, block.string, 0, maxDepth);
+    const resolvedChildren = await Promise.all((block.children || []).map(child => resolveBlockRefs(graph, child, maxDepth)));
+    return {
+        ...block,
+        string: resolvedString,
+        children: resolvedChildren
+    };
+}
+/**
+ * Resolve refs in an array of blocks
+ */
+async function resolveBlocksRefs(graph, blocks, maxDepth) {
+    return Promise.all(blocks.map(block => resolveBlockRefs(graph, block, maxDepth)));
+}
 export function createGetCommand() {
     return new Command('get')
-        .description('Fetch a page or block from Roam')
-        .argument('<target>', 'Page title or block UID (e.g., "Page Title" or "((AbCdEfGhI))")')
-        .option('--json', 'Output as JSON instead of markdown')
-        .option('--depth <n>', 'Child levels to fetch (default: 4)', '4')
-        .option('--refs <n>', 'Block ref expansion depth (default: 1)', '1')
-        .option('--flat', 'Flatten hierarchy to single-level list')
+        .description('Fetch pages, blocks, or TODO/DONE items with optional ref expansion')
+        .argument('[target]', 'Page title, block UID, or relative date. Reads from stdin if "-" or omitted.')
+        .option('-j, --json', 'Output as JSON instead of markdown')
+        .option('-d, --depth <n>', 'Child levels to fetch (default: 4)', '4')
+        .option('-r, --refs [n]', 'Expand ((uid)) refs in output (default depth: 1, max: 4)')
+        .option('-f, --flat', 'Flatten hierarchy to single-level list')
+        .option('--todo', 'Fetch TODO items')
+        .option('--done', 'Fetch DONE items')
+        .option('-p, --page <ref>', 'Filter TODOs/DONEs by page title or UID')
+        .option('-i, --include <terms>', 'Include items matching these terms (comma-separated)')
+        .option('-e, --exclude <terms>', 'Exclude items matching these terms (comma-separated)')
+        .option('-g, --graph <name>', 'Target graph key (multi-graph mode)')
         .option('--debug', 'Show query metadata')
+        .addHelpText('after', `
+Examples:
+  # Fetch pages
+  roam get "Project Notes"                    # Page by title
+  roam get today                              # Today's daily page
+  roam get yesterday                          # Yesterday's daily page
+
+  # Fetch blocks
+  roam get abc123def                          # Block by UID
+  roam get "((abc123def))"                    # UID with wrapper
+
+  # Stdin / Batch Retrieval
+  echo "Project A" | roam get                 # Pipe page title
+  echo "abc123def" | roam get                 # Pipe block UID
+  cat uids.txt | roam get --json              # Fetch multiple blocks (NDJSON output)
+
+  # Output options
+  roam get "Page" -j                          # JSON output
+  roam get "Page" -f                          # Flat list (no hierarchy)
+  roam get abc123def -d 2                     # Limit depth to 2 levels
+  roam get "Page" -r                          # Expand block refs (depth 1)
+  roam get "Page" -r 3                        # Expand refs up to 3 levels deep
+
+  # TODO/DONE items (refs auto-expanded)
+  roam get --todo                             # All TODOs across graph
+  roam get --done                             # All completed items
+  roam get --todo -p "Work"                   # TODOs on "Work" page
+`)
         .action(async (target, options) => {
         try {
-            const graph = initializeGraph({
-                token: API_TOKEN,
-                graph: GRAPH_NAME
-            });
+            const graph = resolveGraph(options, false);
             const depth = parseInt(options.depth || '4', 10);
+            // Parse refs: true/string means enabled, number sets max depth (default 1, max 4)
+            const refsDepth = options.refs !== undefined
+                ? Math.min(4, Math.max(1, parseInt(options.refs, 10) || 1))
+                : 0;
             const outputOptions = {
                 json: options.json,
                 flat: options.flat,
                 debug: options.debug
             };
             if (options.debug) {
-                printDebug('Target', target);
-                printDebug('Options', { depth, refs: options.refs, ...outputOptions });
+                printDebug('Target', target || 'stdin');
+                printDebug('Graph', options.graph || 'default');
+                printDebug('Options', { depth, refs: refsDepth || 'off', ...outputOptions });
             }
-            // Check if target is a block UID
-            const uidMatch = target.match(BLOCK_UID_PATTERN);
-            if (uidMatch) {
-                // Fetch block by UID
-                const blockUid = uidMatch[1];
+            // Handle --todo or --done flags (these ignore target arg usually, but could filter by page if target is used as page?)
+            // The help says "-p" is for page. So we strictly follow flags.
+            if (options.todo || options.done) {
+                const status = options.todo ? 'TODO' : 'DONE';
                 if (options.debug) {
-                    printDebug('Fetching block', { uid: blockUid, depth });
+                    printDebug('Status search', { status, page: options.page, include: options.include, exclude: options.exclude });
                 }
-                const blockOps = new BlockRetrievalOperations(graph);
-                const block = await blockOps.fetchBlockWithChildren(blockUid, depth);
-                if (!block) {
-                    exitWithError(`Block with UID "${blockUid}" not found`);
-                }
-                console.log(formatBlockOutput(block, outputOptions));
+                const searchOps = new SearchOperations(graph);
+                const result = await searchOps.searchByStatus(status, options.page, options.include, options.exclude);
+                console.log(formatTodoOutput(result.matches, status, outputOptions));
+                return;
+            }
+            // Determine targets
+            let targets = [];
+            if (target && target !== '-') {
+                targets = [target];
             }
             else {
-                // Fetch page by title
-                if (options.debug) {
-                    printDebug('Fetching page', { title: target, depth });
+                // Read from stdin if no target or explicit '-'
+                if (process.stdin.isTTY && target !== '-') {
+                    // If TTY and no target, show error
+                    exitWithError('Target is required. Use: roam get <page-title>, roam get --todo, or pipe targets via stdin');
+                }
+                const input = await readStdin();
+                if (input) {
+                    targets = input.split('\n').map(t => t.trim()).filter(Boolean);
                 }
-                const pageOps = new PageOperations(graph);
-                const result = await pageOps.fetchPageByTitle(target, 'raw');
-                // Parse the raw result
-                let blocks;
-                if (typeof result === 'string') {
-                    try {
-                        blocks = JSON.parse(result);
+            }
+            if (targets.length === 0) {
+                exitWithError('No targets provided');
+            }
+            // Helper to process a single target
+            const processTarget = async (item) => {
+                // Resolve relative date keywords (today, yesterday, tomorrow)
+                const resolvedTarget = resolveRelativeDate(item);
+                if (options.debug && resolvedTarget !== item) {
+                    printDebug('Resolved date', `${item} → ${resolvedTarget}`);
+                }
+                // Check if target is a block UID
+                const uidMatch = resolvedTarget.match(BLOCK_UID_PATTERN);
+                if (uidMatch) {
+                    // Fetch block by UID
+                    const blockUid = uidMatch[1];
+                    if (options.debug)
+                        printDebug('Fetching block', { uid: blockUid });
+                    const blockOps = new BlockRetrievalOperations(graph);
+                    let block = await blockOps.fetchBlockWithChildren(blockUid, depth);
+                    if (!block) {
+                        // If fetching multiple, maybe warn instead of exit?
+                        // For now, consistent behavior: print error message to stderr but continue?
+                        // Or simpler: just return a "not found" string/object.
+                        // formatBlockOutput doesn't handle null.
+                        return options.json ? JSON.stringify({ error: `Block ${blockUid} not found` }) : `Block ${blockUid} not found`;
                     }
-                    catch {
-                        // Result is already formatted as string (e.g., "Page Title (no content found)")
-                        console.log(result);
-                        return;
+                    // Resolve block references if requested
+                    if (refsDepth > 0) {
+                        block = await resolveBlockRefs(graph, block, refsDepth);
                     }
+                    return formatBlockOutput(block, outputOptions);
                 }
                 else {
-                    blocks = result;
+                    // Fetch page by title
+                    if (options.debug)
+                        printDebug('Fetching page', { title: resolvedTarget });
+                    const pageOps = new PageOperations(graph);
+                    const result = await pageOps.fetchPageByTitle(resolvedTarget, 'raw');
+                    // Parse the raw result
+                    let blocks;
+                    if (typeof result === 'string') {
+                        try {
+                            blocks = JSON.parse(result);
+                        }
+                        catch {
+                            // Result is already formatted as string (e.g., "Page Title (no content found)")
+                            // But wait, fetchPageByTitle returns string if not found or empty?
+                            // Actually fetchPageByTitle 'raw' returns JSON string of blocks OR empty array JSON string?
+                            // Let's assume result is valid JSON or error message string.
+                            return options.json ? JSON.stringify({ title: resolvedTarget, error: result }) : result;
+                        }
+                    }
+                    else {
+                        blocks = result;
+                    }
+                    // Resolve block references if requested
+                    if (refsDepth > 0) {
+                        blocks = await resolveBlocksRefs(graph, blocks, refsDepth);
+                    }
+                    return formatPageOutput(resolvedTarget, blocks, outputOptions);
                 }
-                console.log(formatPageOutput(target, blocks, outputOptions));
+            };
+            // Execute sequentially
+            for (const t of targets) {
+                const output = await processTarget(t);
+                console.log(output);
             }
         }
         catch (error) {