roam-research-mcp 1.4.0 → 2.4.0

package/build/cli/commands/batch.js

@@ -0,0 +1,352 @@
+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';
+/** 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');
+}
+// 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

@@ -0,0 +1,161 @@
+import { Command } from 'commander';
+import { PageOperations } from '../../tools/operations/pages.js';
+import { BlockRetrievalOperations } from '../../tools/operations/block-retrieval.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 { 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 pages, blocks, or TODO/DONE items with optional ref expansion')
+        .argument('[target]', 'Page title, block UID, or relative date (today/yesterday/tomorrow)')
+        .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
+  roam get tomorrow                           # Tomorrow's daily page
+
+  # Fetch blocks
+  roam get abc123def                          # Block by UID
+  roam get "((abc123def))"                    # UID with wrapper
+
+  # 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
+  roam get --todo -i "urgent,blocker"         # TODOs containing these terms
+  roam get --todo -e "someday,maybe"          # Exclude items with terms
+`)
+        .action(async (target, options) => {
+        try {
+            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('Graph', options.graph || 'default');
+                printDebug('Options', { depth, refs: refsDepth || 'off', ...outputOptions });
+            }
+            // Handle --todo or --done flags
+            if (options.todo || options.done) {
+                const status = options.todo ? 'TODO' : 'DONE';
+                if (options.debug) {
+                    printDebug('Status search', { status, page: options.page, include: options.include, exclude: options.exclude });
+                }
+                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;
+            }
+            // For page/block fetching, target is required
+            if (!target) {
+                exitWithError('Target is required. Use: roam get <page-title> or roam get --todo');
+            }
+            // Resolve relative date keywords (today, yesterday, tomorrow)
+            const resolvedTarget = resolveRelativeDate(target);
+            if (options.debug && resolvedTarget !== target) {
+                printDebug('Resolved date', `${target} → ${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, depth });
+                }
+                const blockOps = new BlockRetrievalOperations(graph);
+                let block = await blockOps.fetchBlockWithChildren(blockUid, depth);
+                if (!block) {
+                    exitWithError(`Block with UID "${blockUid}" not found`);
+                }
+                // Resolve block references if requested
+                if (refsDepth > 0) {
+                    block = await resolveBlockRefs(graph, block, refsDepth);
+                }
+                console.log(formatBlockOutput(block, outputOptions));
+            }
+            else {
+                // Fetch page by title
+                if (options.debug) {
+                    printDebug('Fetching page', { title: resolvedTarget, depth });
+                }
+                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)")
+                        console.log(result);
+                        return;
+                    }
+                }
+                else {
+                    blocks = result;
+                }
+                // Resolve block references if requested
+                if (refsDepth > 0) {
+                    blocks = await resolveBlocksRefs(graph, blocks, refsDepth);
+                }
+                console.log(formatPageOutput(resolvedTarget, blocks, outputOptions));
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            exitWithError(message);
+        }
+    });
+}

package/build/cli/commands/refs.js

@@ -0,0 +1,135 @@
+import { Command } from 'commander';
+import { SearchOperations } from '../../tools/operations/search/index.js';
+import { printDebug, exitWithError } from '../utils/output.js';
+import { resolveGraph } from '../utils/graph.js';
+/**
+ * Format results grouped by page (default output)
+ */
+function formatGrouped(matches, maxContentLength = 60) {
+    if (matches.length === 0) {
+        return 'No references found.';
+    }
+    // Group by page title
+    const byPage = new Map();
+    for (const match of matches) {
+        const pageTitle = match.page_title || 'Unknown Page';
+        if (!byPage.has(pageTitle)) {
+            byPage.set(pageTitle, []);
+        }
+        byPage.get(pageTitle).push(match);
+    }
+    // Format output
+    const lines = [];
+    for (const [pageTitle, pageMatches] of byPage) {
+        lines.push(`[[${pageTitle}]]`);
+        for (const match of pageMatches) {
+            const truncated = match.content.length > maxContentLength
+                ? match.content.slice(0, maxContentLength) + '...'
+                : match.content;
+            lines.push(`  ${match.block_uid}   ${truncated}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n').trim();
+}
+/**
+ * Format results as raw lines (UID + content)
+ */
+function formatRaw(matches, maxContentLength = 60) {
+    if (matches.length === 0) {
+        return 'No references found.';
+    }
+    return matches
+        .map(match => {
+        const truncated = match.content.length > maxContentLength
+            ? match.content.slice(0, maxContentLength) + '...'
+            : match.content;
+        return `${match.block_uid}   ${truncated}`;
+    })
+        .join('\n');
+}
+/**
+ * Parse identifier to determine if it's a block UID or page title
+ */
+function parseIdentifier(identifier) {
+    // Check for ((uid)) format
+    const blockRefMatch = identifier.match(/^\(\(([^)]+)\)\)$/);
+    if (blockRefMatch) {
+        return { block_uid: blockRefMatch[1] };
+    }
+    // Check for [[page]] or #[[page]] format - extract page title
+    const pageRefMatch = identifier.match(/^#?\[\[(.+)\]\]$/);
+    if (pageRefMatch) {
+        return { title: pageRefMatch[1] };
+    }
+    // Check for #tag format
+    if (identifier.startsWith('#')) {
+        return { title: identifier.slice(1) };
+    }
+    // Default: treat as page title
+    return { title: identifier };
+}
+export function createRefsCommand() {
+    return new Command('refs')
+        .description('Find all blocks that reference a page, tag, or block')
+        .argument('<identifier>', 'Page title, #tag, [[Page]], or ((block-uid))')
+        .option('-n, --limit <n>', 'Limit number of results', '50')
+        .option('--json', 'Output as JSON array')
+        .option('--raw', 'Output raw UID + content lines (no grouping)')
+        .option('--debug', 'Show query metadata')
+        .option('-g, --graph <name>', 'Target graph key (for multi-graph mode)')
+        .addHelpText('after', `
+Examples:
+  # Page references
+  roam refs "Project Alpha"               # Blocks linking to page
+  roam refs "[[Meeting Notes]]"           # With bracket syntax
+  roam refs "#TODO"                       # Blocks with #TODO tag
+
+  # Block references
+  roam refs "((abc123def))"               # Blocks embedding this block
+
+  # Output options
+  roam refs "Work" --json                 # JSON array output
+  roam refs "Ideas" --raw                 # Raw UID + content (no grouping)
+  roam refs "Tasks" -n 100                # Limit to 100 results
+`)
+        .action(async (identifier, options) => {
+        try {
+            const graph = resolveGraph(options, false);
+            const limit = parseInt(options.limit || '50', 10);
+            const { block_uid, title } = parseIdentifier(identifier);
+            if (options.debug) {
+                printDebug('Identifier', identifier);
+                printDebug('Graph', options.graph || 'default');
+                printDebug('Parsed', { block_uid, title });
+                printDebug('Options', options);
+            }
+            const searchOps = new SearchOperations(graph);
+            const result = await searchOps.searchBlockRefs({ block_uid, title });
+            if (options.debug) {
+                printDebug('Total matches', result.matches.length);
+            }
+            // Apply limit
+            const limitedMatches = result.matches.slice(0, limit);
+            // Format output
+            if (options.json) {
+                const jsonOutput = limitedMatches.map(m => ({
+                    uid: m.block_uid,
+                    content: m.content,
+                    page: m.page_title
+                }));
+                console.log(JSON.stringify(jsonOutput, null, 2));
+            }
+            else if (options.raw) {
+                console.log(formatRaw(limitedMatches));
+            }
+            else {
+                console.log(formatGrouped(limitedMatches));
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            exitWithError(message);
+        }
+    });
+}