feat(reports): add --max-width and --max-col-width to report get (swamp-club#347)

[stack72]

Summary

• Add --max-width and --max-col-width flags to swamp report get so wide report tables fit laptop terminals without wrapping into illegible noise
• --max-width N caps total output width (tables + reflowed text) via marked-terminal's reflowText option
• --max-col-width N pre-processes markdown tables to truncate individual cells with … before rendering — works for both log and markdown output modes
• Both flags combine (--max-col-width truncates cells first, then --max-width constrains total width) and support env var defaults (SWAMP_REPORT_MAX_WIDTH, SWAMP_REPORT_MAX_COL_WIDTH)
• Input validation rejects values below minimum thresholds (20 for max-width, 5 for max-col-width)
• JSON mode is completely unaffected
• Updated swamp-report skill with new flag documentation

Test plan

• 12 new unit tests for truncateMarkdownTableCells (cell truncation, ellipsis, non-table preservation, separator row skipping, pipes in code spans)
• 8 new unit tests for renderMarkdownToTerminal with width options and renderer factory threading
• All 5948 existing tests pass — no regressions
• deno check, deno lint, deno fmt all pass
• Binary compiles successfully
• UAT issue filed: systeminit/swamp-uat#221

Closes swamp-club#347

🤖 Generated with Claude Code

[github-actions]

CLI UX Review

Blocking

None.

Suggestions

1. Terminology inconsistency in flag descriptions (report_get.ts lines 90, 94): --max-width says "in columns" while --max-col-width says "in characters". Both measure character widths — using consistent phrasing (e.g. both say "characters") would reduce confusion.

2. Silent discard of invalid env var values (report_get.ts parseEnvInt): If a user sets SWAMP_REPORT_MAX_WIDTH=wide (non-numeric), the function returns undefined and the flag is silently ignored. A UserError or at least a log-level warning would help the user notice the misconfiguration.

Verdict

PASS — flags are well-named and consistent with existing (env: VAR) documentation style, error messages are clear and actionable, JSON mode is correctly unaffected, and validation covers both CLI and env var paths.

[github-actions]

CLI UX Review

Blocking

None.

Suggestions

1. --max-width / --max-col-width are silently ignored with --json — a user who has SWAMP_REPORT_MAX_WIDTH set in their environment and then runs --json won't get a warning that the flag did nothing. Consider noting the scope in the flag descriptions, e.g. Cap total output width in columns; no-op in JSON mode (env: SWAMP_REPORT_MAX_WIDTH). Not blocking since JSON output is intentionally unaffected and the SKILL.md documents it.

2. Example for --max-col-width omits --model — the existing --markdown example includes --model my-server as context; the new examples use bare cost-summary with no scope flag. Minor inconsistency that could confuse users who wonder how the report is resolved. Just a cosmetic suggestion.

3. Non-numeric env var is silently ignored — if SWAMP_REPORT_MAX_WIDTH=abc is set, parseEnvInt returns undefined and the value is dropped without any diagnostic. A debug-level log message (logger.debug) noting the invalid env var would help users troubleshooting misconfigured environments, but this is low priority.

Verdict

PASS — flags are well-named, description format matches the existing env: SWAMP_REPO_DIR convention, error messages are clear and actionable, JSON mode is correctly unaffected, and the feature composes cleanly with --markdown.

[github-actions]

Code Review

Well-structured PR. The new --max-width and --max-col-width flags are cleanly layered: CLI parses + validates, WidthOptions flows through the renderer factory, and the markdown rendering functions apply truncation/reflow. JSON mode is correctly unaffected.

Blocking Issues

None.

Suggestions

1. renderMarkdownPlain silently ignores maxWidth — If a user passes --max-width 80 --markdown, the maxWidth option has no effect since renderMarkdownPlain only handles maxColWidth. This is technically correct (maxWidth is a terminal-rendering concern), but could surprise users. A debug-level log or a note in the --max-width help text ("applies to log mode only") would make the boundary clearer.

2. truncateMarkdownTableCells counts characters, not display width — stripped.length measures UTF-16 code units, not visual columns. CJK characters (e.g., 你好) occupy 2 terminal columns each but count as 1 in .length, so a maxColWidth of 10 could render wider than expected. This is an edge case unlikely to affect typical report tables, and fixing it would require a display-width library — fine to leave as-is, just noting it.

3. Per-call Marked() allocation when maxWidth is set — renderMarkdownToTerminal creates a new Marked instance on every invocation when options.maxWidth is present (line 44). For a CLI that renders one report this is negligible, but if this function ever gets called in a loop, caching by width value would avoid repeated setup.

4. Skill doc trimming — The SKILL.md changes removed the JSON output shape example and the _error format note. These were useful for agents consuming --json output. Consider keeping a brief pointer to where agents can find the JSON schema (e.g., "see ReportGetEvent type in libswamp").

All four are non-blocking.