Skip to content

feat: resolve UUID page references in DB mode#32

Open
arndjan wants to merge 1 commit intoergut:mainfrom
arndjan:feat/resolve-refs
Open

feat: resolve UUID page references in DB mode#32
arndjan wants to merge 1 commit intoergut:mainfrom
arndjan:feat/resolve-refs

Conversation

@arndjan
Copy link

@arndjan arndjan commented Mar 23, 2026

Summary

Fixes #21get_page_content in DB mode returns [[uuid]] instead of [[Page Name]] for page references, making output unreadable.

This PR adds automatic UUID-to-name resolution:

  • Text format: [[69133208-...]][[Administratie]] (default behavior)
  • JSON format: adds a resolved_refs mapping (uuid → name) alongside raw content, so agents can read names but use UUIDs for write operations
  • resolve_refs parameter: opt-out with resolve_refs=false when raw UUIDs are needed

How it works

  1. After fetching blocks, a regex (\[\[([0-9a-f-]{36})\]\]) extracts all UUID references
  2. Unique UUIDs are batch-resolved via logseq.Editor.getPage, preferring originalName over name
  3. A pre-built map is passed through _format_block_tree to replace refs during formatting

Design decisions

  • Gated behind LOGSEQ_DB_MODE — markdown-mode users see zero change in behavior or performance
  • Batch with dedup — duplicate UUIDs across blocks result in a single API call per unique UUID
  • Graceful degradation — if a UUID can't be resolved (deleted page, API error), it's left as-is
  • Resolution happens in run_tool, not _format_block_tree — collect all UUIDs first, resolve once, then pass the map down

Test plan

  • 23 new tests covering:
    • UUID regex pattern matching (valid, invalid, bare UUIDs)
    • _collect_block_uuids (flat, nested, dedup)
    • _resolve_block_refs (replace, keep unresolved, mixed)
    • _format_block_tree with uuid_map (root, children, without map)
    • resolve_page_uuids API method (success, originalName preference, not found, dedup, API error, multiple)
    • Integration: resolve_refs enabled, disabled, markdown-mode skip, JSON format
  • All 323 tests pass

🤖 Generated with Claude Code

In DB-mode, Logseq stores page references as internal UUIDs, making
get_page_content output unreadable for agents and users. This adds
automatic UUID-to-name resolution:

- Text format: [[uuid]] replaced with [[Page Name]] (default on)
- JSON format: resolved_refs mapping added alongside raw content
- New resolve_refs parameter (default true) for opt-out
- Batch resolution with deduplication to minimize API calls
- Gated behind LOGSEQ_DB_MODE — zero impact on markdown-mode users

Closes ergut#21

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

get_page_content returns UUIDs instead of page names for page references

1 participant