Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Refactor output formatting docs to reduce duplication
Maximilian Roosc1ebc9c9398d
diff --git a/.claude/rules/cli-output-formatting.md b/.claude/rules/cli-output-formatting.mdindex 40205f3f6..f828f2295 100644--- a/.claude/rules/cli-output-formatting.md+++ b/.claude/rules/cli-output-formatting.md@@ -162,18 +162,11 @@ spawn_background(build_command_that_checks_merge_again()); // Duplicate check!## Message Types-Seven canonical message patterns with their symbols:+See `output-system-architecture.md` for the API. This section covers when to use+each type.-1. **Progress**: ◎ (operations in progress)-2. **Success**: ✓ (something was created or changed)-3. **Errors**: ✗ (failures, invalid states)-4. **Warnings**: ▲ (non-blocking issues)-5. **Hints**: ↳ (actionable — user could/should do something)-6. **Info**: ○ (status — acknowledging state or user choices, no action needed)-7. **Prompts**: ❯ (questions requiring user input)--**Success vs Info decision:** Success (✓) means something was created or-changed. Info (○) means acknowledging state without creating/changing anything.+**Success vs Info:** Success (✓) means something was created or changed. Info+(○) acknowledges state without changing anything.| Success ✓ | Info ○ || --------------------------------------- | ------------------------------------- |@@ -181,8 +174,7 @@ changed. Info (○) means acknowledging state without creating/changing anything| "Created new worktree for feature" | "Already on worktree for feature" || "Commands approved & saved" | "All commands already approved" |-**Hint vs Info decision:** If the message suggests the user take an action, it's-a hint. If it's acknowledging what happened (including flag effects), it's info.+**Hint vs Info:** Hints suggest user action. Info acknowledges what happened.| Hint ↳ | Info ○ || ----------------------------- | ------------------------------------- |@@ -190,17 +182,16 @@ a hint. If it's acknowledging what happened (including flag effects), it's info.| "Use `--force` to override" | "Skipping hooks (--no-verify)" || "Branch can be deleted" | "Worktree preserved (main worktree)" |-**Command suggestions in hints:** When suggesting a command the user should run,-use the pattern "To X, run Y" where X describes the goal and Y is the command.-**Always end with the command** so users can easily copy it:+**Command suggestions in hints:** Use "To X, run Y" pattern. End with the+command for easy copying:```rust-// GOOD - "To X, run Y" pattern, command at end for easy copying+// GOOD - command at end for easy copying"To delete the unmerged branch, run wt remove feature -D""To rebase onto main, run wt step rebase or wt merge""To create a new branch, run wt switch feature --create; to list branches, run wt list --branches"-// GOOD - when user needs to modify their command, instruction then command+// GOOD - when user needs to modify their command"To switch to the remote branch, remove --create; run wt switch feature"// BAD - command without context@@ -210,40 +201,12 @@ use the pattern "To X, run Y" where X describes the goal and Y is the command."Run wt switch feature (without --create) to switch to the remote branch"```-Use `suggest_command()` from `worktrunk::styling` to build commands with proper-shell escaping. Include the branch name or other specific arguments so users can-copy-paste.--**Message formatting functions** add symbol AND semantic color. Callers provide-content with optional inner styling (like `<bold>`), then pass to-`output::print()`:+Use `suggest_command()` from `worktrunk::styling` for proper shell escaping.-```rust-// Simple message - formatting function adds symbol + color-output::print(success_message("Created worktree"))?;-output::print(hint_message("Run 'wt config' to configure"))?;--// With inner styling - use cformat! for bold/dim within the message-output::print(success_message(cformat!("Created worktree for <bold>{branch}</>")))?;-output::print(warning_message(cformat!("Branch <bold>{name}</> not found")))?;-```+**Every user-facing message requires either a symbol or a gutter.**-**Semantic colors from formatting functions:**--- `success_message()` → green-- `progress_message()` → cyan-- `hint_message()` → dimmed-- `warning_message()` → yellow-- `info_message()` → no color (neutral status)-- `error_message()` → red--**Every user-facing message requires either a symbol or a gutter** for-consistent visual separation.--**Section titles** (experimental): For output with distinct sections (like-`wt hook show`, `wt config show`), use cyan uppercase text without symbol:-`<cyan>SECTION TITLE</>`. This distinguishes organizational headers from status-messages. Currently being trialed — expand to other commands if it works well.+**Section titles** (experimental): For sectioned output (`wt hook show`,+`wt config show`), use `<cyan>SECTION TITLE</>`.## Blank Line Principles@@ -255,18 +218,7 @@ messages. Currently being trialed — expand to other commands if it works well.## stdout vs stderr-stdout is for the primary output of commands — the data you asked for. stderr-is for status messages about the operation. This separation allows piping-(`wt list | grep foo`) without progress or warnings interfering.--- **stdout**: Primary output (table data, JSON, statusline)-- **stderr**: Status messages (progress, success, errors, hints, warnings)--Shell integration writes directives (cd, exec) to `WORKTRUNK_DIRECTIVE_FILE`, keeping-stdout completely free for data.--Use the output system (`output::print()` with message formatting functions).-Never write directly to stdout/stderr in command code.+See `output-system-architecture.md` for the stream separation. Key rule:```rust// GOOD - use output system@@ -276,7 +228,7 @@ output::print(success_message("Branch created"))?;println!("Branch created");```-Interactive prompts must flush stderr before blocking on stdin:+**Interactive prompts** must flush stderr before blocking on stdin:```rusteprint!("❯ Allow and remember? [y/N] ");@@ -328,48 +280,36 @@ output::print(success_message("Squashed @ a1b2c3d"))?;## Style Constants-Style constants in `src/styling/constants.rs` (minimal set for programmatic-styling):+Only three `anstyle` constants exist for table rendering (`src/styling/constants.rs`):-- `ADDITION`: Green (diffs, additions) — used in table rendering-- `DELETION`: Red (diffs, deletions) — used in table rendering-- `GUTTER`: BrightWhite background (quoted content)+- `ADDITION`: Green (diffs)+- `DELETION`: Red (diffs)+- `GUTTER`: BrightWhite background-Symbol constants: `PROGRESS_SYMBOL` (◎), `SUCCESS_SYMBOL` (✓), `ERROR_SYMBOL` (✗),-`WARNING_SYMBOL` (▲), `HINT_SYMBOL` (↳), `INFO_SYMBOL` (○), `PROMPT_SYMBOL` (❯)--For all other styling, use color-print tags in `cformat!`: `<red>`, `<green>`,-`<yellow>`, `<cyan>`, `<dim>`, `<bold>`, `<bright-black>`+For everything else, use `cformat!` tags.## Styling in Command Code-Use `output::print()` with message formatting functions. The formatting function-adds the symbol + semantic color, and `cformat!` handles inner styling:+Use `output::print()` with formatting functions. Use `cformat!` for inner+styling:```rust-// GOOD - formatting function handles symbol + outer color, cformat! handles inner stylingoutput::print(success_message(cformat!("Created <bold>{branch}</> from <bold>{base}</>")))?;-output::print(warning_message(cformat!("Branch <bold>{name}</> has <dim>uncommitted changes</>")))?;output::print(hint_message(cformat!("Run <bright-black>wt merge</> to continue")))?;--// GOOD - plain strings work too (no inner styling needed)-output::print(progress_message("Rebasing onto main..."))?;-output::print(hint_message("No changes to commit"))?;```-**Available color-print tags:** `<bold>`, `<dim>`, `<bright-black>`, `<red>`,-`<green>`, `<yellow>`, `<cyan>`, `<magenta>`+**color-print tags:** `<bold>`, `<dim>`, `<bright-black>`, `<red>`, `<green>`,+`<yellow>`, `<cyan>`, `<magenta>`++**Branch names** should be bolded in messages.-**Symbol constants in cformat!:** Use `{ERROR_SYMBOL}`, `{HINT_SYMBOL}`, etc. for-messages that bypass output:: functions (e.g., GitError Display impl):+**Symbol constants in cformat!:** For messages that bypass output:: functions+(e.g., `GitError` Display impl), use symbol constants directly:```rustcformat!("{ERROR_SYMBOL} <red>Branch <bold>{branch}</> not found</>")```-Branch names in messages should be bolded. Tables (`wt list`) use `StyledLine`-with conditional styling for branch names.-## Commands and Branches in MessagesNever quote commands or branch names. Use styling to make them stand out:@@ -392,36 +332,15 @@ output::print(hint_message("No changes to commit"))?;output::print(hint_message("Run 'wt list' to see worktrees"))?;```-## Color Detection--Colors automatically adjust based on environment (NO_COLOR, CLICOLOR_FORCE, TTY-detection). When using `output::` functions, this is handled automatically.--For direct terminal I/O (rare — mainly internal output system code), import-print macros from `worktrunk::styling`:--```rust-use worktrunk::styling::eprintln; // Auto-detects color support-```-## Design Principles-- **color-print for all styling** — Use `cformat!` with HTML-like tags- (`<green>`, `<bold>`, etc.). Only use anstyle for `StyledLine` table- rendering.-- **output:: functions over direct printing** — Use output:: for user messages,- which auto-adds symbol + semantic color-- **cformat! for inner styling** — Use `<bold>`, `<dim>` tags within output::- calls-- **Never manual escape codes** — No `\x1b[...` in code-- **YAGNI for presentation** — Most output needs no styling-- **Unicode-aware** — Width calculations respect symbols and CJK characters (via- `StyledLine`)-- **Graceful degradation** — Must work without color support+- **`cformat!` for styling** — Never manual escape codes (`\x1b[...`)+- **`output::` for printing** — Never direct `println!`/`eprintln!`+- **YAGNI** — Most output needs no styling+- **Graceful degradation** — Colors auto-adjust (NO_COLOR, TTY detection)+- **Unicode-aware** — Width calculations respect symbols and CJK (via `StyledLine`)-## StyledLine API--For complex table formatting with proper width calculations, use `StyledLine`:+**StyledLine** for table rendering with proper width calculations:```rustuse worktrunk::styling::StyledLine;@@ -436,23 +355,17 @@ println!("{}", line.render());See `src/commands/list/render.rs` for advanced usage.-## Gutter Formatting for Quoted Content--Use gutter formatting for **quoted content** — anything that should be visually-distinguished from application prose:+## Gutter Formatting-- **External data**: git output, commit messages, config values, cached data-- **Suggested commands**: shell commands the user might run+Use gutter for **quoted content** (git output, commit messages, shell commands):-Use `format_bash_with_gutter()` for shell commands (applies dimming + syntax-highlighting). Use `format_with_gutter()` for other content (no dimming).+- `format_bash_with_gutter()` — shell commands (dimmed + syntax highlighting)+- `format_with_gutter()` — other content-**Gutter vs Table:** Tabular data structured by the application should use-`output::table()` with markdown formatting via `render_markdown_in_help()`.-Tables are artifacts; gutter is for quoting content.+**Gutter vs Table:** Tables for structured app data; gutter for quoting external+content.-**Linebreaks:** Gutter requires a single newline before it, never double.-`output::print()` adds a trailing newline, so messages should not include `\n`:+**No trailing `\n`:** `output::print()` adds newlines automatically:```rust// GOOD - no trailing \n@@ -463,19 +376,17 @@ output::gutter(format_with_gutter(&log, "", None))?;output::print(progress_message("Merging...\n"))?;```-**Avoid bullets in messages:** Use gutter formatting instead of bullet lists-(`- item`) for multi-line content. Bullets add visual noise and don't provide-the same clear separation as gutter formatting.+**Avoid bullets — use gutter instead:**```rust-// BAD - bullet list in warning+// BAD - bullet listlet mut warning = String::from("Some git operations failed:");for error in &errors {warning.push_str(&format!("\n - {}: {}", name, msg));}output::print(warning_message(warning))?;-// GOOD - gutter formatting with bold branch names+// GOOD - gutter formattinglet error_lines: Vec<String> = errors.iter().map(|e| cformat!("<bold>{}</>: {}", e.name, e.msg))@@ -487,13 +398,9 @@ let warning = format!(output::print(warning_message(warning))?;```-The gutter provides consistent visual structure. Branch names should be bolded-for emphasis. If we find cases where bullets are genuinely better than gutter-formatting, we can reconsider this policy.+## Error Formatting-## Error Message Formatting--**Single-line errors with variables are fine:**+**Single-line errors** with variables are fine:```rust// GOOD - single-line with path variable@@ -503,56 +410,29 @@ formatting, we can reconsider this policy.std::fs::read_to_string(&path).context("Failed to read config")?```-**Multi-line external output needs gutter formatting:**--When external commands (git, npm, LLM tools, hooks) produce multi-line stderr,-use gutter formatting:+**Multi-line external output** (git, hooks, LLM) needs gutter:-1. **Show the command that was run** — Include the full command with arguments- so users can debug-2. **Put multi-line output in a gutter** — Don't embed raw stderr inline in the- message+1. Show the command that was run (with arguments)+2. Put multi-line output in a gutter-Use the `format_error_block` helper in `src/git/error.rs` or follow its pattern:--```rust-// GOOD - command shown in header, multi-line error in gutter+```✗ Commit generation command 'llm --model claude' failed- ┃ Error: [Errno 8] nodename nor servname provided, or not known+ ┃ Error: [Errno 8] nodename nor servname provided-// BAD - multi-line error embedded inline-✗ Commit generation command 'llm' failed: LLM command failed: Error: [Errno 8]...+// NOT: ✗ ... failed: LLM command failed: Error: [Errno 8]...```-**Implementation:** See `format_error_block()` in `src/git/error.rs` for the-pattern, and `LlmCommandFailed` variant for an example.+See `format_error_block()` in `src/git/error.rs`.## Table Column Alignment-**Principle: Headers and values align consistently within each column type.**--Column alignment follows standard tabular data conventions:--1. **Text columns** (Branch, Path, Message, Commit):- - Headers: Left-aligned- - Values: Left-aligned--2. **Diff/numeric columns** (HEAD±, main↕, main…±, Remote⇅):- - Headers: Right-aligned- - Values: Right-aligned--**Why:** Right-aligning numeric data allows visual scanning by magnitude-(rightmost digits align vertically). Left-aligning text data prioritizes-readability from the start. Matching header and value alignment within each-column creates a consistent visual grid.--**Implementation:** Headers are positioned within their column width using the-same alignment strategy as their values (render.rs).+- **Text columns** (Branch, Path): left-aligned+- **Numeric columns** (HEAD±, main↕): right-aligned-## Snapshot Testing Requirement+## Snapshot Testing-Every command output must have a snapshot test (`tests/integration_tests/`). See-`tests/integration_tests/remove.rs` for the standard pattern using+Every command output must have snapshot tests (`tests/integration_tests/`).+See `tests/integration_tests/remove.rs` for the standard pattern using`setup_snapshot_settings()`, `make_snapshot_cmd()`, and `assert_cmd_snapshot!()`.Cover success/error states, with/without data, and flag variations.diff --git a/.claude/rules/output-system-architecture.md b/.claude/rules/output-system-architecture.mdindex 82b6af4aa..29d3e34c2 100644--- a/.claude/rules/output-system-architecture.md+++ b/.claude/rules/output-system-architecture.md@@ -12,69 +12,64 @@ Worktrunk uses file-based directive passing for shell integration:When `WORKTRUNK_DIRECTIVE_FILE` is not set (direct binary call), commands executedirectly and shell integration hints are shown.-## The Cardinal Rule: Never Check Mode in Command Code+## Output Functions-Command code must never check whether shell integration is active. The output-system handles this automatically — commands call output functions without-knowing the mode.+The output system handles shell integration automatically. Just call output+functions — they do the right thing regardless of whether shell integration is+active.```rust-// NEVER DO THIS+// NEVER DO THIS - don't check mode in command codeif is_shell_integration_active() {// different behavior}-// ALWAYS DO THIS-output::print(success_message("Success!"))?;-output::change_directory(&path)?;-```--State is lazily initialized on first use — just call output functions anywhere:--```rust+// ALWAYS DO THIS - just call output functionsoutput::print(success_message("Created worktree"))?;-output::change_directory(&path)?;+output::change_directory(&path)?; // Writes to directive file if set, else no-op```-## Available Output Functions+**Output functions** (`src/output/global.rs`):-The output module (`src/output/global.rs`) provides:+| Function | Destination | Purpose |+|----------|-------------|---------|+| `print(message)` | stderr | Status messages (use with formatting functions) |+| `shell_integration_hint(message)` | stderr | Hints suppressed when shell integration active |+| `gutter(content)` | stderr | Gutter-formatted quoted content |+| `blank()` | stderr | Visual separation |+| `table(content)` | stdout | Primary output (pipeable) |+| `data(content)` | stdout | Structured data (JSON) |+| `change_directory(path)` | directive file | Shell cd after wt exits |+| `execute(command)` | directive file | Shell command after wt exits |+| `flush()` | both | Flush buffers |+| `flush_for_stderr_prompt()` | both | Flush before interactive prompts |+| `terminate_output()` | stderr | Reset ANSI state on stderr |+| `is_shell_integration_active()` | — | Check if directive file set (rarely needed) |-- `print(message)` — Status message to stderr (use with message formatting functions)-- `shell_integration_hint(message)` — Shell integration hints (↳, suppressed when- shell integration is active)-- `gutter(content)` — Gutter-formatted content to stderr-- `blank()` — Blank line to stderr-- `data(content)` — Structured data to stdout (JSON)-- `table(content)` — Primary output to stdout (table data, pipeable)-- `change_directory(path)` — Request directory change (writes to directive file- if set)-- `execute(command)` — Execute command directly or write to directive file-- `flush()` — Flush output buffers-- `flush_for_stderr_prompt()` — Flush before interactive prompts-- `terminate_output()` — Reset ANSI state on stderr-- `is_shell_integration_active()` — Check if directive file is set (rarely needed)+**Message formatting functions** (`worktrunk::styling`):-**Message formatting functions** (from `worktrunk::styling`):+| Function | Symbol | Color |+|----------|--------|-------|+| `success_message()` | ✓ | green |+| `progress_message()` | ◎ | cyan |+| `info_message()` | ○ | — |+| `warning_message()` | ▲ | yellow |+| `hint_message()` | ↳ | dim |+| `error_message()` | ✗ | red |-- `success_message(content)` — ✓ green-- `progress_message(content)` — ◎ cyan-- `info_message(content)` — ○ no color-- `warning_message(content)` — ▲ yellow-- `hint_message(content)` — ↳ dimmed-- `error_message(content)` — ✗ red+## stdout vs stderr-For the complete API, see `src/output/global.rs` and `src/styling/constants.rs`.+- **stdout**: Primary output (tables, JSON) — pipeable+- **stderr**: Status messages (progress, success, errors, hints)+- **directive file**: Shell commands (cd, exec)-## Security: Protecting the Directive File+This separation makes `wt list | grep feature` work.-The `WORKTRUNK_DIRECTIVE_FILE` environment variable is automatically removed from all-spawned subprocesses. This prevents hooks from discovering and writing to the-directive file.+## Security-The `shell_exec::run()` function (the canonical way to run external commands)-handles this automatically. Other spawn sites must explicitly call-`.env_remove(DIRECTIVE_FILE_ENV_VAR)`.+`WORKTRUNK_DIRECTIVE_FILE` is automatically removed from spawned subprocesses+(via `shell_exec::run()`). This prevents hooks from writing to the directive+file.## Adding New Output Functions@@ -82,6 +77,3 @@ Add the function to `global.rs`. The pattern:- **Primary output** (data the command produces) → stdout via `table()` or `data()`- **Status messages** (progress, success, errors) → stderr via `print()`- **Directives** (cd, exec) → directive file via `change_directory()`, `execute()`--This separation makes commands pipeable: `wt list | grep feature` works because-the table goes to stdout while progress/warnings go to stderr.