Skip to content

feat: resolve UUID page references in DB mode#32

Merged
ergut merged 1 commit intoergut:mainfrom
arndjan:feat/resolve-refs
Mar 29, 2026
Merged

feat: resolve UUID page references in DB mode#32
ergut merged 1 commit intoergut:mainfrom
arndjan:feat/resolve-refs

Conversation

@arndjan
Copy link
Copy Markdown
Contributor

@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

@ergut
Copy link
Copy Markdown
Owner

ergut commented Mar 28, 2026

Great work on this — the UUID resolution approach is clean and the batch dedup design is exactly right. We just merged PRs #31 and #33 which touched the same tools.py file, so this branch now has a conflict. Could you rebase on main? The changes don't overlap semantically so it should be straightforward. Thanks @arndjan!

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>
@arndjan arndjan force-pushed the feat/resolve-refs branch from d6761b5 to 9f9ef02 Compare March 29, 2026 10:03
@ergut
Copy link
Copy Markdown
Owner

ergut commented Mar 29, 2026

Really well thought out, @arndjan. The batch dedup design is exactly right — collect all UUIDs first, resolve once, pass the map down. The resolve_refs opt-out and the resolved_refs mapping in JSON format are both thoughtful touches. 345 tests pass. Merging.

@ergut ergut merged commit d639921 into ergut:main Mar 29, 2026
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

2 participants