logseq/docs/agent-guide/logseq-cli/003-cli-block-ref-rendering.md

CLI Block Ref Rendering Implementation Plan

Goal: Make list, search, and show render user-visible :block/title text through one shared block-ref replacement path, including show property values whose effective text is stored as default string content.

Architecture: Keep the current command-specific query semantics for list, search, and show, but route every user-visible block-title-like string through one shared CLI helper that replaces [[block-uuid]] with stable labels fetched through the same lookup strategy that show already uses. Architecture: Extract the existing show UUID replacement logic into a CLI-shared namespace, then reuse it for list and search result normalization and for show-specific tree and property rendering so there is one visible block-ref rendering behavior across commands.

Tech Stack: ClojureScript, Datascript, db-worker-node, Transit transport, CLI formatter code, CLI unit tests, and CLI e2e specs.

Related: Builds on docs/agent-guide/logseq-cli/001-logseq-cli.md.

Problem statement

The CLI currently renders user-visible block title text through multiple independent paths.

search block returns raw :block/title values from src/main/logseq/cli/command/search.cljs and sends them straight to src/main/logseq/cli/format.cljs.

The list family returns raw :block/title values from worker helpers in src/main/logseq/cli/common/db_worker.cljs and also sends them to src/main/logseq/cli/format.cljs.

The show command has its own richer rendering flow in src/main/logseq/cli/command/show.cljs, where it extracts UUID refs from visible text, fetches entities for those UUIDs, and rewrites visible strings before printing.

Because these paths are separate, visible output can diverge.

The reported bug is one instance of that divergence, where logseq search block -c foo can show foo [[UUID]] instead of foo [[bar]].

The same architectural inconsistency also risks divergence in list command title columns and in show output when block-title-like strings appear in property values.

A particularly important case is show rendering for a block property whose value is effectively default string content, because property-value->string currently returns string values directly and does not run them through the same block-ref replacement path used by block-label and tree node resolution.

The implementation should unify visible block-ref rendering behavior across list, search, and show without changing each command family's existing query, filtering, sorting, or transport semantics beyond the additional UUID label lookups needed for rendering.

Testing Plan

Implementation should follow @Test-Driven Development.

I will add failing unit tests in src/test/logseq/cli/command/search_test.cljs that stub raw search results containing [[block-uuid]] in :block/title, then stub follow-up UUID lookups, and assert that execute-search-block returns foo [[bar]] instead of the raw UUID form.

I will add failing unit tests for the list command family in a suitable existing or new list-command test namespace under src/test/logseq/cli/command/, and those tests will verify that command execution normalizes user-visible :block/title values before they reach the formatter.

I will add a focused unit test for the shared UUID replacement helper namespace so direct text replacement, multiple refs in one string, and recursive replacement behavior are locked down independently of any one command.

I will add or update show command tests so the extracted helper remains behavior-compatible with current show output for node titles.

I will add a specific show regression test for property rendering where a property value is a plain string containing [[block-uuid]], and I will assert that the rendered property line shows the resolved label rather than the raw UUID.

I will add a second show regression for a property map whose visible text comes from :block/title or string :logseq.property/value, because both of those cases can represent user-visible default string content and both should use the same replacement path.

I will add formatter regressions in src/test/logseq/cli/format_test.cljs that prove normalized list and search titles still satisfy the existing table output contract.

I will add CLI e2e coverage in cli-e2e/spec/non_sync_cases.edn for at least one search block scenario and one list scenario that both expose a visible [[page-ref]] title and verify stdout contains the label form and not the UUID form.

If there is already an appropriate CLI e2e place for show, I will add a case that verifies a property line with string content containing a block ref also renders the label form.

I will run bb dev:test -v logseq.cli.command.search-test after writing the search failing tests and expect the new assertions to fail before implementation.

I will run the targeted list and show test namespaces after adding their failing tests and expect the new assertions to fail before implementation.

I will run bb dev:test -v logseq.cli.format-test after adding the formatter regressions and expect the new visible-output assertions to fail before implementation if raw UUIDs are still printed.

I will run bb -f cli-e2e/bb.edn test --skip-build after the unit tests pass and expect the new CLI scenarios to pass with human-readable labels.

NOTE: I will write all tests before I add any implementation behavior.

Current implementation snapshot

The current rendering topology is:

list page|tag|property|task|node|asset
  -> src/main/logseq/cli/command/list.cljs
  -> transport/invoke :thread-api/cli-list-*
  -> src/main/logseq/cli/common/db_worker.cljs returns raw :block/title
  -> src/main/logseq/cli/format.cljs TITLE column prints it

search block|page|property|tag
  -> src/main/logseq/cli/command/search.cljs
  -> transport/invoke :thread-api/q
  -> Datascript pull returns raw :block/title
  -> src/main/logseq/cli/format.cljs TITLE column prints it

show
  -> src/main/logseq/cli/command/show.cljs
  -> collects visible UUID refs from node text
  -> transport/invoke :thread-api/pull for uuid labels
  -> replace-uuid-refs / resolve-uuid-refs-in-node
  -> tree and block labels render resolved text

The list formatter path is centralized in src/main/logseq/cli/format.cljs through list-page-columns, list-tag-columns, list-property-columns, list-task-columns, list-node-columns, and list-asset-columns.

Those columns use :block/title directly as their visible TITLE content.

The list command data comes from src/main/logseq/cli/common/db_worker.cljs, where helpers such as minimal-list-item and minimal-node-item return raw :block/title strings.

The search command data comes from src/main/logseq/cli/command/search.cljs, where search-block-query and the other search queries return raw :block/title strings and normalize-items preserves those strings for output.

The show command already contains the CLI-side block-ref replacement logic in src/main/logseq/cli/command/show.cljs.

The relevant show functions are extract-uuid-refs, collect-uuid-refs, fetch-uuid-entities, replace-uuid-refs, resolve-uuid-refs-in-node, and resolve-uuid-refs-in-tree-data.

The show command also has a separate property rendering path through property-value->string, normalize-property-values, node-user-property-entries, and node-property-lines.

That property rendering path currently treats plain strings as final text and therefore does not inherently share the same block-ref replacement behavior as block-label.

Recommended approach

Create one CLI-shared block-ref rendering helper and make every visible :block/title rendering path use it.

Do not keep separate ad hoc text replacement logic in show, list, and search.

Do not switch search or list to unrelated worker APIs just to get rendering behavior.

The preferred shape is:

visible title-like string
  -> collect UUID refs from text
  -> fetch uuid labels through shared pull strategy
  -> replace UUID refs through shared pure helper
  -> hand normalized value to list/search/show formatter logic

The comparison is:

Option	Benefit	Risk	Recommendation
Extract show block-ref replacement helpers and reuse them everywhere visible block-title text is rendered.	One CLI source of truth for visible block-ref rendering.	Requires helper extraction plus per-command lookup integration.	Recommended.
Keep separate implementations in show, list, and search.	Lowest local edit count per file.	Guarantees long-term divergence and repeated bugs.	Reject.
Reuse lower-level DB/frontend title conversion helpers for some commands and show helpers for others.	Short-term convenience.	Still leaves multiple user-visible rendering semantics in the CLI.	Reject.
Switch list or search to different worker APIs just to get title rendering.	May reuse existing worker display paths.	Changes query semantics, ranking, or payload contracts.	Reject.

Execution steps

1. Write the failing shared-helper unit tests first.

Create or update a test namespace that locks the extracted helper behavior for direct [[uuid]] replacement, multiple refs in one string, and replacement stability when an entity label is missing.

2. Extract the pure block-ref text helpers from src/main/logseq/cli/command/show.cljs.

Move uuid-ref-pattern, extract-uuid-refs, replace-uuid-refs-once, and replace-uuid-refs into a CLI-shared namespace such as src/main/logseq/cli/uuid_refs.cljs.

Keep the extracted API small and obviously reusable for both top-level node titles and property values.

3. Extract or share the UUID entity lookup path that show already uses.

Reuse the :thread-api/pull lookup shape currently implemented in fetch-uuid-entities with selector [:db/id :block/uuid :block/title :block/name] on [:block/uuid uuid].

Decide whether fetch-uuid-entities itself should move into the shared namespace or whether a small command-local wrapper should call a shared pure helper after performing the transport lookups.

4. Update src/main/logseq/cli/command/show.cljs to consume the shared helpers.

Keep show block label rendering behavior unchanged.

Update resolve-uuid-refs-in-node and resolve-uuid-refs-in-tree-data to call the shared replacement helper rather than a private local implementation.

5. Fix the show property rendering path.

Update property-value->string and any surrounding helper signatures so plain string values, :block/title values coming from maps, and string :logseq.property/value values are also passed through the shared block-ref replacement helper before formatting.

This is the special case that must not be missed, because a block property with default string content is user-visible text but is currently outside the main block-label replacement path.

6. Update src/main/logseq/cli/command/search.cljs to normalize visible titles through the shared helper.

Keep search block on :thread-api/q.

Collect UUID refs from the raw :block/title values returned by search results.

Fetch UUID labels through the same lookup strategy used by show.

Replace block refs in the visible :block/title values before normalize-items strips helper-only data.

Apply the same normalization rule to other search subcommands when they render :block/title, :title, or :name as user-visible title text and the underlying source can contain block refs.

7. Update src/main/logseq/cli/command/list.cljs to normalize visible titles through the shared helper.

Keep the existing :thread-api/cli-list-* worker calls and all current filtering, sorting, and pagination semantics.

After raw items are returned and before apply-fields, collect UUID refs from every user-visible :block/title field that can be printed by the list formatters.

Fetch UUID labels once per result set and rewrite the relevant title fields through the shared helper.

8. Ensure the formatter layer does not become a second rendering source of truth.

src/main/logseq/cli/format.cljs should keep treating provided :block/title values as already-rendered visible strings.

Do not add formatter-only UUID replacement logic for list or search, because that would diverge from JSON and EDN output and from the show command path.

9. Add and run targeted tests for show property rendering.

Verify a plain string property value containing [[uuid]] renders as [[label]].

Verify a property map whose visible text comes from :block/title also renders through the same helper.

Verify string :logseq.property/value rendering also uses the same helper when that string contains block refs.

10. Add and run CLI e2e regressions.

Add a search block case that reproduces the original bug and verifies visible label output.

Add a list case that verifies a visible title containing a page ref is rendered with labels.

Add a show case if the current e2e coverage model can express property output cleanly, otherwise make the unit tests exhaustive for the property-value scenarios.

Files to inspect and likely update

/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/show.cljs is the current source of truth for CLI-side UUID replacement and the main file for the show property-value fix.

/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/search.cljs is the primary search implementation file that should normalize visible title output while preserving the current query path.

/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs is the primary list implementation file that should normalize visible title output after worker data returns.

/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/db_worker.cljs should be inspected to confirm which list payload fields carry raw :block/title values today.

/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs should be inspected to verify that all list and search TITLE columns are downstream consumers of already-rendered title strings.

/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/uuid_refs.cljs is the recommended destination for extracted shared block-ref rendering helpers.

/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/search_test.cljs should hold the search command regressions.

/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs should hold the visible table regressions for list and search.

A list-command test namespace under /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/ should hold command-level list regressions if one does not already exist.

A show-command test namespace under /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/ should hold the property-value rendering regressions if one does not already exist.

/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn should hold the end-to-end CLI regressions.

Acceptance criteria

All list, search, and show paths that render user-visible :block/title text use one shared block-ref replacement implementation.

logseq search block -c foo shows foo [[bar]] rather than foo [[UUID]] for raw stored titles that contain serialized refs.

The list command family does not print raw block UUID refs in visible TITLE output when the source title contains block refs.

The show command keeps its current visible node-title behavior after helper extraction.

The show command also resolves block refs inside property values when the visible property text is a plain string, a map :block/title, or a string :logseq.property/value.

Existing search sorting and recycle filtering semantics remain unchanged.

Existing list filtering, sorting, pagination, and worker API usage remain unchanged.

Formatter output contracts for list and search tables remain intact.

Risks and mitigations

The main design risk is extracting helpers incompletely and leaving show property rendering on a different path from show block-label rendering.

Mitigate that risk by writing explicit property-string and property-map regressions before extracting helpers.

A second risk is accidentally creating a formatter-only solution for list and search while show continues to normalize earlier.

Mitigate that risk by normalizing in command execution or shared rendering helpers before data reaches format.cljs.

A third risk is broadening the command payload shape or changing query semantics while trying to fix a rendering problem.

Mitigate that risk by preserving :thread-api/q for search and :thread-api/cli-list-* for list and by limiting new transport work to UUID label lookups.

A fourth risk is missing secondary visible strings that conceptually represent block titles, especially show property values stored as default strings.

Mitigate that risk by explicitly auditing property-value->string, normalize-property-values, and node-property-lines and by adding direct regressions for each relevant branch.

Rollback plan

If the change behaves incorrectly, revert the list and search normalization integrations and the show property-value updates while preserving the new tests that document the intended unified behavior.

If helper extraction causes too much churn, keep the extraction commit separate from the command integration commits so the move can be reverted cleanly without losing the behavioral tests.

Do not add fallback branches that silently print raw UUIDs for some command families and labels for others.

Testing Details

The most important tests are behavior tests that observe final visible command output rather than helper implementation details.

The shared-helper tests should lock the block-ref replacement rules themselves.

The command tests should prove that list and search normalize visible titles before formatting and that show property rendering uses the same replacement behavior as show block labels.

The formatter tests should only verify table layout and visible rendered text after normalization.

The e2e tests should validate the reported search bug and at least one list and one show scenario that exercise the unified rendering path.

Implementation Details

• Extract one shared CLI helper for block-ref text replacement from show.cljs.
• Keep show, list, and search on their current data-retrieval semantics.
• Reuse show's UUID entity lookup strategy for list and search normalization.
• Normalize visible title text before handing it to formatter code.
• Keep format.cljs as a presentation layer, not as a second rendering engine.
• Audit every visible :block/title rendering site in list, search, and show.
• Treat show property values as first-class visible title-like strings when they contain block refs.
• Cover plain strings, map :block/title, and string :logseq.property/value in tests.
• Preserve existing sorting, filtering, pagination, and recycle-filter behavior.

Question

Should the shared helper namespace own only the pure text replacement helpers, or should it also own the transport-backed UUID label lookup helper so list, search, and show all call the exact same lookup orchestration entrypoint.

The preferred answer is to share the pure replacement helpers for sure and to share the lookup orchestration as well if that can be done without forcing awkward dependencies between command namespaces.

---