logseq/docs/agent-guide/logseq-cli/002-list-node-code-truncation.md

# Plan: Limit All `list` Command Table Output to Three Lines

## Background

A bug was reported in Logseq CLI list rendering:

- In the `list` command, displayed content should not exceed three lines.
- For `list node` entries tagged as code, long code blocks should be truncated to a maximum of three lines.
- This is a **temporary rule**.

Repro step:

- `logseq list node --tags code`

(Reporter wrote `-tags`; current CLI syntax is `--tags`.)

## Current Behavior (Implementation-Aligned)

From current CLI implementation:

- `list node` fetches items in `src/main/logseq/cli/command/list.cljs` (`execute-list-node`), and other list commands follow the same list-command execution pattern.
- Human rendering for all list commands is handled in `src/main/logseq/cli/format.cljs` through shared table formatting helpers.
- Table rendering already supports multi-line cells and title width truncation by display width.
- There is currently **no line-count truncation** for multi-line title/content in list output.

Therefore, long multi-line content (including code blocks in `:block/title`) can expand to many rendered lines in human output across list commands.

## Goal

For human output of `list` family commands, enforce a temporary UI rule:

1. Any displayed multi-line content in list table cells should be limited to **max 3 lines**.
2. Explicitly satisfy the bug scenario for `list node --tags code` where code block titles are long multi-line text.

## Non-Goals

- Do not change structured outputs (`--output json`, `--output edn`).
- Do not alter worker query/filter semantics for any `list` command.
- Do not introduce permanent content-format policy yet; this is temporary.

## Proposed Design

### 1) Apply truncation at human formatting layer

Implement the behavior in `src/main/logseq/cli/format.cljs` because:

- This is a display concern.
- It avoids modifying DB/query payloads.
- It keeps JSON/EDN behavior unchanged.

### 2) Add line-count limiter for list cells

Add a helper that:

- Splits text by `\n`.
- Keeps at most first 3 lines.
- If truncated, append an ellipsis marker to the third line (or as a final marker line), preserving table readability.

Apply this helper before table rendering for list cells where content can be multiline (notably `TITLE` fields).

### 3) Preserve existing display-width truncation behavior

The existing title width truncation (`:list-title-max-display-width`) should remain active.
Recommended order:

1. Apply line-count truncation (max 3 lines).
2. Apply per-line display-width truncation (existing behavior).

This ensures both vertical and horizontal bounds.

### 4) Scope for temporary rule

**Mandatory scope (this plan):**

- All `list-*` human outputs must enforce the max-3-lines rule, including:
  - `:list-page`
  - `:list-tag`
  - `:list-property`
  - `:list-task`
  - `:list-node`
  - `:list-asset`

This is not a `:list-node`-only change. The behavior should be consistent across all list command tables.

## Files to Update

1. `src/main/logseq/cli/format.cljs`

- Introduce max-lines constant for list content (value `3`).
- Add helper to truncate multiline text by line count.
- Integrate helper into list table cell formatting path for all `list-*` commands (at minimum all `TITLE` columns; ideally all multiline-capable list table cells).

2. `src/test/logseq/cli/format_test.cljs`

Add/adjust tests:

- New tests for each list command (`list page/tag/property/task/node/asset`): title/content with 5+ lines renders only first 3 lines in human output.
- Assert output still includes `Count: N` for each command.
- Assert JSON/EDN output keeps full original title/content unchanged.
- Add at least one alignment regression test with multiline truncation enabled to ensure table columns stay aligned.

## Test Plan

### Unit Tests

Run focused tests first:

- `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`
- `bb dev:test -v logseq.cli.format-test/test-human-output-list-task`
- `bb dev:test -v logseq.cli.format-test/test-human-output-list-node`
- `bb dev:test -v logseq.cli.format-test/test-human-output-list-asset`
- Add and run dedicated 3-line truncation test cases covering all list commands.

Then run broader CLI tests:

- `bb dev:test -v logseq.cli.format-test`

### Regression Checks

- Verify existing title-width truncation tests still pass.
- Verify multiline table alignment remains correct after truncation.
- Verify non-human outputs remain unchanged.

## Acceptance Criteria

1. Every `list-*` command human output (`list page/tag/property/task/node/asset`) never shows more than 3 rendered lines for any single multiline list table cell.
2. `logseq list node --tags code` specifically reproduces the bug fix: long code block titles are truncated to max 3 lines.
3. Output remains a valid table with readable alignment and `Count` footer.
4. JSON/EDN outputs are unchanged (no content truncation).
5. Existing list formatting tests pass, with new cross-command truncation test coverage.

## Risks and Mitigations

Risk:

- Applying truncation too broadly may hide meaningful multiline content unexpectedly.

Mitigation:

- Keep change localized to list human formatter.
- Document as temporary rule.
- Enforce one shared truncation path used by all `list-*` formatters to avoid divergence.

Risk:

- Interaction between line-limit and width-limit may produce awkward ellipsis placement.

Mitigation:

- Centralize truncation helpers and add explicit tests for both multi-line and width truncation together.

## Rollback Strategy

Since change is formatter-only:

- Revert modifications in `format.cljs` and corresponding tests.
- No data migration or worker contract rollback needed.

## Follow-up (After Temporary Rule)

When temporary rule is revisited:

- Decide whether 3-line cap should become configurable (e.g., `cli.edn` option).
- Decide if behavior should apply uniformly across all list/search/show human outputs.
- Consider richer code-block preview strategy for CLI (language-aware header + fixed snippet).