enhance(cli): display width in all list-* cmds

Author: RCmerci

docs/agent-guide/079-logseq-cli-list-title-display-width.md

@@ -0,0 +1,246 @@
+# Logseq CLI List Title Display Width Implementation Plan
+
+Goal: Make every `TITLE` column in `logseq list *` human output use a fixed maximum visual width with correct CJK-aware width handling via `string-width`.
+
+Architecture: Keep list data retrieval unchanged in db-worker-node thread APIs and implement presentation-only changes in the CLI formatter layer.
+
+Architecture: Introduce a display-width-aware truncation and padding path that is applied to list title cells before table rendering.
+
+Tech Stack: ClojureScript, `logseq.cli.format`, `logseq.cli.command.list`, db-worker thread APIs in `frontend.worker.db-core`, JavaScript `string-width`.
+
+Related: Builds on `docs/agent-guide/062-logseq-cli-list-default-sort-updated-at.md`, `docs/agent-guide/066-logseq-cli-list-property-cardinality-column.md`, `docs/agent-guide/078-logseq-cli-task-subcommands.md`, and `docs/cli/logseq-cli.md`.
+
+## Problem statement
+
+Current human table rendering in `src/main/logseq/cli/format.cljs` uses `(count text)` for width calculation and right padding.
+
+`count` is code-point length, not terminal display width.
+
+This breaks alignment when titles contain CJK or mixed-width text.
+
+Current `list` human output also allows unbounded title length, which can push important columns out of view for `list page`, `list tag`, `list property`, and `list task`.
+
+We need a stable, readable table contract where `TITLE` is capped to a reasonable visual width and aligned correctly for mixed-language content.
+
+## Current baseline from implementation
+
+The active CLI stack is the `src/main/logseq/cli/*` implementation, not the legacy `deps/cli` command stack.
+
+List command data is produced by db-worker helpers and returned through thread APIs without formatter concerns.
+
+The relevant path is:
+
+```text
+logseq list <page|tag|property|task>
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs
+  -> transport/invoke :thread-api/cli-list-*
+  -> /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/db_worker.cljs
+  -> /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs
+```
+
+`TITLE` columns are defined in formatter column configs in `src/main/logseq/cli/format.cljs`.
+
+All table rendering goes through `render-table` and `format-counted-table` in the same file.
+
+## Scope
+
+In scope commands are:
+
+| Command | Human output table has `TITLE` column | Source formatter function |
+| --- | --- | --- |
+| `logseq list page` | Yes | `format-list-page` |
+| `logseq list tag` | Yes | `format-list-tag` |
+| `logseq list property` | Yes | `format-list-property` |
+| `logseq list task` | Yes | `format-list-task` |
+
+The default max visual width target for title is `40` columns.
+
+The value is configurable in `cli.edn` via a new CLI config key.
+
+The cap is measured by display width, not character count.
+
+Out of scope commands include `search *`, `query list`, `graph list`, and `server list`.
+
+Out of scope outputs include JSON and EDN payload shape changes.
+
+## Design decisions
+
+### 1) Keep db-worker-node payloads unchanged
+
+No changes are required in `src/main/logseq/cli/common/db_worker.cljs` or thread API wiring in `src/main/frontend/worker/db_core.cljs`.
+
+db-worker should continue returning full `:block/title` values.
+
+Human formatting is the only layer that applies visual truncation.
+
+### 2) Add explicit title max-width policy in formatter
+
+Introduce a formatter default constant such as `list-human-title-max-display-width-default` with value `40`.
+
+Read an optional override from resolved CLI config using a new `cli.edn` key `:list-title-max-display-width`.
+
+Apply this policy only to `TITLE` extractors in list column definitions.
+
+Truncated values append a suffix `…` and remain within the max display width.
+
+### 3) Use `string-width` for display width operations
+
+Add npm interop in `src/main/logseq/cli/format.cljs` for `string-width`.
+
+Use `string-width` for:
+
+- Width measurement during truncation.
+- Width measurement during table column width calculation.
+- Padding logic in `pad-right` or equivalent.
+
+This ensures CJK and mixed-width titles align with other columns.
+
+### 4) Preserve existing list data semantics
+
+Sorting, filtering, `--fields`, `--limit`, and `--offset` behavior in `src/main/logseq/cli/command/list.cljs` remain unchanged.
+
+Only rendered human strings are affected.
+
+### 5) Keep non-list command behavior stable
+
+Prefer implementing title truncation in list-specific extractors.
+
+If `render-table` is upgraded to display-width-aware padding globally, verify non-list tables are unaffected except improved alignment.
+
+## Proposed implementation steps
+
+1. Invoke `@test-driven-development` and add failing formatter tests for long ASCII title truncation in each list command.
+
+2. Add failing formatter tests for long CJK and mixed CJK/ASCII titles in each list command.
+
+3. Add failing config resolution tests in `src/test/logseq/cli/config_test.cljs` for `:list-title-max-display-width`, including default fallback to `40` and valid `cli.edn` override.
+
+4. Add a focused formatter unit test for truncation helper behavior ensuring output display width is `<= 40` and suffix handling is correct.
+
+5. Add a focused formatter unit test for width-aware padding behavior with CJK text so column alignment is deterministic.
+
+6. Add config normalization helpers in `src/main/logseq/cli/config.cljs` to parse and validate `:list-title-max-display-width` as a positive integer.
+
+7. Add `string-width` import and helper functions in `src/main/logseq/cli/format.cljs`.
+
+8. Add title truncation helper and wire it into the `TITLE` extractor entries in `list-page-columns`, `list-tag-columns`, `list-property-columns`, and `list-task-columns`.
+
+9. Replace `(count ...)`-based width and padding internals in table rendering with display-width-aware logic.
+
+10. Run formatter and config tests and update exact spacing snapshots where needed.
+
+11. Update user-facing docs in `docs/cli/logseq-cli.md` to mention that list human `TITLE` uses default width `40`, supports `cli.edn` override, and always truncates with `…`.
+
+12. Optionally add one CLI e2e non-sync human-output case for long mixed-width title rendering if we want package-level regression protection.
+
+## Files to modify
+
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/config.cljs`.
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/config_test.cljs`.
+- `/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs`.
+- `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs`.
+- `/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md`.
+- `/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn` (optional, only if we decide to cover human output end-to-end).
+- `/Users/rcmerci/gh-repos/logseq/package.json` (only if `string-width` is added as an explicit direct dependency).
+
+## Edge cases to cover
+
+A title with only CJK characters that exceeds max width.
+
+A title with alternating CJK and ASCII characters.
+
+A title exactly at width boundary.
+
+A title one display cell over boundary.
+
+A title containing emoji or variation selectors.
+
+A nil title where current logic falls back to `-`.
+
+A title containing newlines where current multiline row rendering is preserved.
+
+A very short title where no extra truncation marker appears.
+
+An invalid `cli.edn` width value such as `0`, negative numbers, or non-numeric values that must fall back to default `40`.
+
+## Risks and mitigation
+
+Risk: Moving width calculations to display width can shift spacing in non-list tables.
+
+Mitigation: Add or adjust tests for affected command outputs and constrain behavioral changes to alignment only.
+
+Risk: `string-width` import style may vary by bundling mode.
+
+Mitigation: Verify in unit tests and CLI runtime, and choose the interop form that matches current CJS usage conventions in the repo.
+
+Risk: New truncation can reduce discoverability of long titles.
+
+Mitigation: Keep JSON and EDN outputs untruncated and document this behavior clearly.
+
+Risk: Invalid `cli.edn` width values can produce inconsistent rendering if not normalized.
+
+Mitigation: Parse as positive integer with fallback to default `40` and add config tests for invalid values.
+
+## Open questions
+
+No open question.
+
+Decisions locked for this plan are default width `40`, `cli.edn` configurability, truncation suffix `…`, and list-only scope.
+
+## Testing Plan
+
+I will add formatter behavior tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs` that verify title truncation and alignment for `list page`, `list tag`, `list property`, and `list task` human output.
+
+I will add helper-level tests in the same test namespace to validate width-aware truncation and padding with CJK and mixed-width samples.
+
+I will add config tests in `/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/config_test.cljs` to validate default value `40`, `cli.edn` override, and invalid-value fallback behavior.
+
+I will run focused tests first with `bb dev:test -v logseq.cli.format-test/test-human-output-list-page`, `bb dev:test -v logseq.cli.format-test/test-human-output-list-tag-property`, and `bb dev:test -v logseq.cli.format-test/test-human-output-list-task`.
+
+I will run broader CLI tests with `bb dev:test -v logseq.cli.format-test` and config tests with `bb dev:test -v logseq.cli.config-test`.
+
+If e2e coverage is added, I will run `bb -f cli-e2e/bb.edn test --skip-build`.
+
+I will finish with `bb dev:lint-and-test`.
+
+NOTE: I will write *all* tests before I add any implementation behavior.
+
+## Step-by-step execution checklist
+
+| Step | Action | Verification |
+| --- | --- | --- |
+| 1 | Add failing list title truncation tests. | Tests fail with current unbounded title output. |
+| 2 | Add failing CJK width alignment tests. | Tests fail due current `count`-based width logic. |
+| 3 | Add failing config tests for `:list-title-max-display-width`. | Tests fail before config parsing is implemented. |
+| 4 | Implement config parsing with default `40` and invalid fallback. | Config tests pass for default and override behavior. |
+| 5 | Implement `string-width` helpers. | Helper tests pass. |
+| 6 | Implement title truncation in list column extractors. | List tests show bounded title width and `…` suffix. |
+| 7 | Switch table padding/width to display-width-aware logic. | CJK alignment tests pass. |
+| 8 | Update docs and optional e2e. | Docs mention truncation behavior and tests stay green. |
+| 9 | Run full regression. | `bb dev:lint-and-test` passes. |
+
+## Testing Details
+
+The tests validate observable CLI behavior by asserting final human output strings for list commands, including truncation marker presence and table alignment under mixed-width input.
+
+The tests do not assert internal helper data structures beyond what is needed to validate final output semantics.
+
+## Implementation Details
+
+- Keep default max title width as formatter constant `40`.
+- Allow override from `cli.edn` key `:list-title-max-display-width`.
+- Parse config width as positive integer and fall back to default on invalid values.
+- Truncate by display width instead of character count.
+- Keep truncation policy limited to list `TITLE` columns.
+- Always use `…` as truncation suffix in human list output.
+- Preserve db-worker payload contracts and thread API names.
+- Preserve JSON and EDN full title output.
+- Ensure multiline table behavior is not regressed.
+- Document human-output-only truncation and config override in CLI docs.
+
+## Question
+
+No blocking question for implementation.
+
+---

docs/cli/logseq-cli.md

@@ -57,6 +57,7 @@ Supported keys include:
 - `:data-dir`
 - `:timeout-ms`
 - `:output-format` (use `:json` or `:edn` for scripting)
+- `:list-title-max-display-width` (human `list *` TITLE max display width, default `40`)
 - sync config persisted via `sync config set|get|unset`: `:ws-url`, `:http-base`
 
 Legacy migration note:
@@ -288,7 +289,7 @@ Output formats:
     139ms     └── cli.execute-action
     129ms         └── transport.invoke:thread-api/cli-list-pages
     ```
-- Human output is plain text. List/search commands render tables with a final `Count: N` line. For list and search subcommands, the ID column uses `:db/id` (not UUID). If `:db/ident` exists, an `IDENT` column is included. `list property` includes dedicated `TYPE` and `CARDINALITY` columns. Search table columns are `ID` and `TITLE`. Block titles can include multiple lines; multi-line rows align additional lines under the `TITLE` column. Times such as list `UPDATED-AT`/`CREATED-AT` and `graph info` `Created at` are shown in human-friendly relative form. Errors include error codes and may include a `Hint:` line. Use `--output json|edn` for structured output.
+- Human output is plain text. List/search commands render tables with a final `Count: N` line. For list and search subcommands, the ID column uses `:db/id` (not UUID). If `:db/ident` exists, an `IDENT` column is included. `list property` includes dedicated `TYPE` and `CARDINALITY` columns. Search table columns are `ID` and `TITLE`. For `list page|tag|property|task` in human output, the `TITLE` column is display-width-aware (CJK-safe), defaults to max width `40`, and truncates overflow with `…`; set `:list-title-max-display-width` in `cli.edn` to override. JSON/EDN outputs keep full titles (no truncation). Block titles can include multiple lines; multi-line rows align additional lines under the `TITLE` column. Times such as list `UPDATED-AT`/`CREATED-AT` and `graph info` `Created at` are shown in human-friendly relative form. Errors include error codes and may include a `Hint:` line. Use `--output json|edn` for structured output.
 - `example` human output includes `Selector`, `Matched commands`, and `Examples` sections. Structured output (`json`/`edn`) includes `selector`, `matched-commands`, `examples`, and `message` fields under `data`.
 - `sync download` progress lines are streamed to stdout only when progress is enabled. In `json`/`edn` mode, progress is disabled by default unless `--progress true` is provided.
 - JSON machine output preserves namespaced keyword semantics:

package.json

@@ -186,6 +186,7 @@
         "remove-accents": "0.5.0",
         "sanitize-filename": "1.6.4",
         "send-intent": "^7.0.0",
+        "string-width": "8.2.0",
         "url": "^0.11.4",
         "util": "^0.12.5"
     },

src/main/logseq/cli/config.cljs

@@ -13,6 +13,23 @@
   (when (and (some? value) (not (string/blank? value)))
     (js/parseInt value 10)))
 
+(def ^:private list-title-max-display-width-default 40)
+
+(defn- parse-positive-int
+  [value]
+  (cond
+    (and (number? value)
+         (integer? value)
+         (pos? value))
+    value
+
+    (string? value)
+    (let [trimmed (string/trim value)]
+      (when (re-matches #"[1-9]\d*" trimmed)
+        (js/parseInt trimmed 10)))
+
+    :else nil))
+
 (def ^:private output-formats
   #{:human :json :edn})
 
@@ -98,6 +115,7 @@
   (let [defaults {:timeout-ms 10000
                   :login-timeout-ms 300000
                   :logout-timeout-ms 120000
+                  :list-title-max-display-width list-title-max-display-width-default
                   :output-format nil
                   :data-dir (common-graph/get-default-graphs-dir)
                   :ws-url "wss://api-staging.logseq.io/sync/%s"
@@ -114,6 +132,9 @@
                           (parse-output-format (:output env))
                           (parse-output-format (:output-format file-config))
                           (parse-output-format (:output file-config)))
-        merged (merge defaults file-config env opts {:config-path config-path})]
+        merged (merge defaults file-config env opts {:config-path config-path})
+        list-title-max-display-width (or (parse-positive-int (:list-title-max-display-width merged))
+                                         list-title-max-display-width-default)]
     (cond-> merged
-      output-format (assoc :output-format output-format))))
+      output-format (assoc :output-format output-format)
+      true (assoc :list-title-max-display-width list-title-max-display-width))))