mirror of
https://github.com/logseq/logseq.git
synced 2026-05-19 18:32:41 +00:00
123 lines
6.0 KiB
Markdown
123 lines
6.0 KiB
Markdown
# Logseq CLI Help and Show Output Cleanup Implementation Plan
|
|
|
|
Goal: Improve logseq-cli help readability and ensure show JSON and EDN outputs use :db/id without :block/uuid.
|
|
|
|
Architecture: The CLI help text is assembled in logseq.cli.command.core and babashka.cli spec descriptions, while show output is built in logseq.cli.command.show and formatted in logseq.cli.format before returning JSON or EDN.
|
|
|
|
Tech Stack: ClojureScript, logseq-cli, babashka.cli, db-worker-node.
|
|
|
|
Related: Relates to 018-logseq-cli-add-tags-builtin-properties.md.
|
|
|
|
## Problem statement
|
|
|
|
The current help output lists [options] for nearly every command, which clutters the help display and reduces readability.
|
|
|
|
The tags and properties option help text does not clearly state that identifiers can be id, :db/ident, or :block/title across all relevant help contexts.
|
|
|
|
The show command includes :block/uuid in JSON and EDN output, even though :db/id is already present and preferred for programmatic consumers.
|
|
|
|
```
|
|
logseq-cli
|
|
| help text built from babashka.cli specs
|
|
v
|
|
logseq.cli.command.core
|
|
| parse args and build command payloads
|
|
v
|
|
logseq.cli.command.show
|
|
| fetch tree data from db-worker-node
|
|
v
|
|
logseq.cli.format
|
|
| render human, json, edn output
|
|
v
|
|
stdout
|
|
```
|
|
|
|
## Testing Plan
|
|
|
|
I will add or update unit tests that assert help summaries do not include repeated [options] in the command list, and that tags and properties descriptions include the identifier guidance.
|
|
|
|
I will add or update unit tests that verify show JSON and EDN outputs do not include :block/uuid and still include :db/id for root and child nodes.
|
|
|
|
I will add or update integration tests for show JSON output to assert :db/id is present and :block/uuid is absent in root, tags, and linked references where applicable.
|
|
|
|
NOTE: I will write all tests before I add any implementation behavior.
|
|
|
|
## Requirements
|
|
|
|
The top level help output and group summaries must avoid repeating [options] for each command listing while still documenting that options exist in the usage line.
|
|
|
|
The help description for --tags and --properties must explicitly state that identifiers can be id, :db/ident, or :block/title.
|
|
|
|
The show command must omit :block/uuid from JSON and EDN outputs while preserving :db/id for the same entities.
|
|
|
|
The show command human output must be unchanged.
|
|
|
|
## Non-goals
|
|
|
|
Do not change CLI command behavior or supported flags beyond help text updates.
|
|
|
|
Do not change db-worker-node behavior or its API surface.
|
|
|
|
Do not change the structure of human output for show, list, add, or query commands.
|
|
|
|
## Design decisions
|
|
|
|
Limit the help output adjustment to formatting in logseq.cli.command.core so command behavior and parsing remain unchanged.
|
|
|
|
Apply the identifier clarification to all --tags and --properties options in logseq.cli.command.add and any other specs that expose those flags.
|
|
|
|
Strip :block/uuid only for show outputs in JSON and EDN formats by post-processing tree data just before returning payloads.
|
|
|
|
## Implementation plan
|
|
|
|
1. Follow @test-driven-development for every change in this plan.
|
|
|
|
2. Add a unit test in src/test/logseq/cli/commands_test.cljs that asserts command list rows in top level and group help do not contain [options] after the command name.
|
|
|
|
3. Add a unit test in src/test/logseq/cli/commands_test.cljs that asserts the --tags and --properties option descriptions include the text supporting id, :db/ident, and :block/title identifiers.
|
|
|
|
4. Add a unit test in src/test/logseq/cli/format_test.cljs or src/test/logseq/cli/commands_test.cljs that asserts show JSON and EDN outputs strip :block/uuid while retaining :db/id in root and child nodes.
|
|
|
|
5. Update integration tests in src/test/logseq/cli/integration_test.cljs that currently assert :uuid or :block/uuid in show JSON output to instead assert :db/id and absence of :block/uuid.
|
|
|
|
6. Adjust logseq.cli.command.core command listing formatting so only the usage line includes [options], and the command listing uses the bare command path without the suffix.
|
|
|
|
7. Update the --tags and --properties option descriptions in src/main/logseq/cli/command/add.cljs to include the identifier guidance sentence in a consistent phrasing.
|
|
|
|
8. Add a helper in src/main/logseq/cli/command/show.cljs or src/main/logseq/cli/format.cljs that removes :block/uuid keys from show JSON and EDN payloads, and apply it in execute-show when output-format is :json or :edn.
|
|
|
|
9. Run the updated unit tests and integration tests from the Testing Plan and confirm all pass.
|
|
|
|
## Edge cases
|
|
|
|
Command help should still show [options] in the usage line for commands that accept options, but not in the command list table.
|
|
|
|
Multi-id show results should strip :block/uuid from each tree entry without changing the error map shape.
|
|
|
|
Linked references and tag entities should keep :db/id in the output even when :block/uuid is removed.
|
|
|
|
## Testing Details
|
|
|
|
I will add tests that verify help summaries and option descriptions at the command summary level and not by matching the raw babashka.cli output.
|
|
|
|
I will add tests that parse show JSON and EDN output and assert :block/uuid is missing while :db/id remains on block nodes.
|
|
|
|
I will update integration tests that read show JSON output to match the new key expectations without changing the test setup logic.
|
|
|
|
## Implementation Details
|
|
|
|
- Update logseq.cli.command.core formatting to render command rows without [options].
|
|
- Keep usage lines intact so users still see options availability in usage sections.
|
|
- Align help text for --tags and --properties to a single wording that mentions id, :db/ident, and :block/title.
|
|
- Add a show-specific sanitization step for json and edn output only.
|
|
- Keep the show tree data used for human output unchanged to avoid regressions.
|
|
- Ensure strip logic is recursive so :block/uuid is removed from nested children and linked references.
|
|
- Prefer clojure.walk/postwalk for key removal to minimize custom traversal code.
|
|
- Document the new behavior in tests rather than adding new user-facing docs.
|
|
|
|
## Question
|
|
|
|
This is resolved. Only add supports --tags and --properties today, so we will update help text there only.
|
|
|
|
---
|