Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Move CLI output formatting guidelines to rules files
Maximilian Roosb31edf21d6f7
diff --git a/.claude/rules/cli-output-formatting.md b/.claude/rules/cli-output-formatting.mdnew file mode 100644index 000000000..771fb3c83--- /dev/null+++ b/.claude/rules/cli-output-formatting.md@@ -0,0 +1,444 @@+# CLI Output Formatting Standards++## User Message Principles++Output messages should acknowledge user-supplied arguments (flags, options,+values) by reflecting those choices in the message text.++```rust+// User runs: wt switch --create feature --base=main+// GOOD - acknowledges the base branch+"Created new worktree for feature from main at /path/to/worktree"+// BAD - ignores the base argument+"Created new worktree for feature at /path/to/worktree"+```++**Avoid second-person ("you", "your"):** Messages should describe actions and+state, not address the user directly.++```rust+// BAD - second-person+"Use 'wt merge' to rebase your changes onto main"+// GOOD - describes the action+"Use 'wt merge' to rebase onto main"++// BAD - second-person+"Add one line to your shell config"+// GOOD - refers to the thing+"Add one line to the shell config"+```++**Avoid redundant parenthesized content:** Parenthesized text should add new+information, not restate what's already said.++```rust+// BAD - parentheses restate "no changes"+"No changes after squashing 3 commits (commits resulted in no net changes)"+// GOOD - clear and concise+"No changes after squashing 3 commits"+// GOOD - parentheses add supplementary info+"Committing with default message... (3 files, +45, -12)"+```++**Avoid pronouns with cross-message referents:** Hints appear as separate+messages from errors. Don't use pronouns like "it" that refer to something+mentioned in the error message.++```rust+// BAD - "it" refers to branch name in error message+// Error: "Branch 'feature' not found"+// Hint: "Use --create to create it"+// GOOD - self-contained hint+// Error: "Branch 'feature' not found"+// Hint: "Use --create to create a new branch"+```++## Message Consistency Patterns++Use consistent punctuation and structure for related messages:++**Semicolon for qualifiers:** Separate the action from a qualifier/reason:++```rust+// Action; qualifier (flag)+"Removing feature worktree in background; retaining branch (--no-delete-branch)"+"Commands approved; not saved (--force)"+```++**Ampersand for conjunctions:** Use `&` for combined actions:++```rust+// Action & additional action+"Removing feature worktree & branch in background"+"Commands approved & saved to config"+```++**Explicit flag acknowledgment:** Show flags in parentheses when they change+behavior:++```rust+// GOOD - shows the flag explicitly+"Removing feature worktree in background; retaining branch (--no-delete-branch)"+// BAD - doesn't acknowledge user's explicit choice+"Removing feature worktree in background; retaining branch"+```++**Parallel structure:** Related messages should follow the same pattern:++```rust+// GOOD - parallel structure with integration reason explaining branch deletion+// Both wt merge and wt remove show integration reason when branch is deleted+"Removing feature worktree & branch in background (already in main)" // Branch is integrated (ancestor)+"Removing feature worktree & branch in background (files match main)" // Branch is integrated (squash/rebase)+"Removing feature worktree & branch in background (all changes in main)" // Branch is integrated (squash + main advanced)+"Removing feature worktree in background; retaining unmerged branch" // Unmerged (system keeps)+"Removing feature worktree in background; retaining branch (--no-delete-branch)" // User flag (user keeps)+```++**Compute decisions once:** For background operations, check conditions upfront,+show the message, then pass the decision explicitly rather than re-checking in+background scripts:++```rust+// GOOD - check once, pass decision+let should_delete = check_if_merged();+show_message_based_on(should_delete);+spawn_background(build_command(should_delete));++// BAD - check twice (once for message, again in background script)+let is_merged = check_if_merged();+show_message_based_on(is_merged);+spawn_background(build_command_that_checks_merge_again()); // Duplicate check!+```++## Message Types++Seven canonical message patterns with their emojis:++1. **Progress**: π (operations in progress)+2. **Success**: β (successful completion)+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)++**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 π‘ | Info βͺ |+| ----------------------------- | ------------------------------------- |+| "Run `wt merge` to continue" | "Already up to date with main" |+| "Use `--force` to override" | "Skipping hooks (--no-verify)" |+| "Branch can be deleted" | "Worktree preserved (main worktree)" |++**Message formatting functions** add emoji AND semantic color. Callers provide+content with optional inner styling (like `<bold>`), then pass to+`output::print()`:++```rust+// Simple message - formatting function adds emoji + 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")))?;+```++**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 an emoji 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 emoji:+`<cyan>SECTION TITLE</>`. This distinguishes organizational headers from status+messages. Currently being trialed β expand to other commands if it works well.++## Blank Line Principles++- **No leading/trailing blanks** β Start immediately, end cleanly+- **One blank after blocks** β Separate multi-line content (gutter blocks,+ sections)+- **One blank after prompts** β Separate user input from results+- **Never double blanks** β One blank line maximum between elements++## stdout vs stderr++**Both modes write all messages to stderr.** stdout is reserved for structured+data:++- **stdout**: JSON output (`--format=json`), shell scripts (directive mode)+- **stderr**: All user-facing messages (progress, success, errors, hints,+ gutter, etc.)++**Directive mode** additionally emits a shell script to stdout at the end.++Use the output system (`output::print()` with message formatting functions) to+handle both modes automatically. Never write directly to stdout/stderr in+command code.++```rust+// GOOD - use output system (handles both modes)+output::print(success_message("Branch created"))?;++// BAD - direct writes bypass output system+println!("Branch created");+```++Interactive prompts must flush stderr before blocking on stdin:++```rust+eprint!("β Allow and remember? [y/N] ");+stderr().flush()?;+io::stdin().read_line(&mut response)?;+```++## Temporal Locality: Output Should Be Close to Operations++Output should appear immediately adjacent to the operations it describes.+Progress messages apply only to slow operations (>400ms): git operations,+network requests, builds.++Sequential operations should show immediate feedback:++```rust+for item in items {+ output::print(progress_message(format!("Removing {item}...")))?;+ perform_operation(item)?;+ output::print(success_message(format!("Removed {item}")))?; // Immediate feedback+}+```++Bad example (output decoupled from operations):++```+π Removing worktree for feature...+π Removing worktree for bugfix...+ β Long delay, no feedback+Removed worktree for feature β All output at the end+Removed worktree for bugfix+```++Signs of poor temporal locality: collecting messages in a buffer, single success+message for batch operations, no progress before slow operations.++## Information Display: Show Once, Not Twice++Progress messages should include all relevant details (what's being done,+counts, stats, context). Success messages should be minimal, confirming+completion with reference info (hash, path).++```rust+// GOOD - detailed progress, minimal success+output::print(progress_message("Squashing 3 commits & working tree changes into a single commit (5 files, +60)..."))?;+perform_squash()?;+output::print(success_message("Squashed @ a1b2c3d"))?;+```++## Style Constants++Style constants in `src/styling/constants.rs` (minimal set for programmatic+styling):++- `ADDITION`: Green (diffs, additions) β used in table rendering+- `DELETION`: Red (diffs, deletions) β used in table rendering+- `GUTTER`: BrightWhite background (quoted content)++Emoji constants: `PROGRESS_EMOJI` (π), `SUCCESS_EMOJI` (β ), `ERROR_EMOJI` (β),+`WARNING_EMOJI` (π‘), `HINT_EMOJI` (π‘), `INFO_EMOJI` (βͺ), `PROMPT_EMOJI` (β)++For all other styling, use color-print tags in `cformat!`: `<red>`, `<green>`,+`<yellow>`, `<cyan>`, `<dim>`, `<bold>`, `<bright-black>`++## Styling in Command Code++Use `output::print()` with message formatting functions. The formatting function+adds the emoji + semantic color, and `cformat!` handles inner styling:++```rust+// GOOD - formatting function handles emoji + outer color, cformat! handles inner styling+output::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>`++**Emoji constants in cformat!:** Use `{ERROR_EMOJI}`, `{HINT_EMOJI}`, etc. for+messages that bypass output:: functions (e.g., GitError Display impl):++```rust+cformat!("{ERROR_EMOJI} <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 Messages++Never quote commands or branch names. Use styling to make them stand out:++- **In normal font context**: Use `<bold>` for commands and branches+- **In hints**: Use `<bright-black>` for commands (hint() already applies+ dimming β no explicit `<dim>` needed)++```rust+// GOOD - bold in normal context+output::info(cformat!("Use <bold>wt merge</> to continue"))?;++// GOOD - bright-black for commands in hints+output::hint(cformat!("Run <bright-black>wt list</> to see worktrees"))?;++// GOOD - plain hint without commands+output::hint("No changes to commit")?;++// BAD - quoted commands+output::hint("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 emoji + 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 emoji and CJK characters (via+ `StyledLine`)+- **Graceful degradation** β Must work without color support++## StyledLine API++For complex table formatting with proper width calculations, use `StyledLine`:++```rust+use worktrunk::styling::StyledLine;+use anstyle::{AnsiColor, Color, Style};++let mut line = StyledLine::new();+line.push_styled("Branch", Style::new().dimmed());+line.push_raw(" ");+line.push_styled("main", Style::new().fg_color(Some(Color::Ansi(AnsiColor::Cyan))));+println!("{}", line.render());+```++See `src/commands/list/render.rs` for advanced usage.++## Gutter Formatting for Quoted Content++Use `format_with_gutter()` for **external data** β anything read from outside+the application: git output, shell commands, commit messages, config values,+cached data. Gutter visually quotes this content to distinguish it from+application-generated output.++**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 external data.++**Linebreaks:** Gutter requires a single newline before it, never double.+`output::print()` adds a trailing newline, so messages should not include `\n`:++```rust+// GOOD - no trailing \n+output::print(progress_message("Merging..."))?;+output::gutter(format_with_gutter(&log, "", None))?;++// BAD - trailing \n creates blank line+output::print(progress_message("Merging...\n"))?;+```++## Error Message Formatting++**Single-line errors with variables are fine:**++```rust+// GOOD - single-line with path variable+.map_err(|e| format!("Failed to read {}: {}", format_path_for_display(path), e))?++// GOOD - using .context() for simple errors+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:++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++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++// BAD - multi-line error embedded inline+β Commit generation command 'llm' 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.++## 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).++## Snapshot Testing Requirement++Every command output must have a snapshot test (`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.mdnew file mode 100644index 000000000..455e68959--- /dev/null+++ b/.claude/rules/output-system-architecture.md@@ -0,0 +1,81 @@+# Output System Architecture++## Two Output Modes++Worktrunk supports two output modes, selected once at program startup:++1. **Interactive Mode** β Human-friendly output with colors, emojis, and hints+2. **Directive Mode** β Shell script on stdout (at end), user messages on stderr++Both modes write all messages to stderr. stdout is reserved for structured data+(JSON, shell scripts).++The mode is determined at initialization in `main()` and never changes during+execution.++## The Cardinal Rule: Never Check Mode in Command Code++Command code must never check which output mode is active. The output system+uses enum dispatch β commands call output functions without knowing the mode.++```rust+// NEVER DO THIS+if mode == OutputMode::Interactive {+ println!("β Success!");+}++// ALWAYS DO THIS+output::print(success_message("Success!"))?;+```++Decide once at the edge (`main()`), initialize globally, trust internally:++```rust+// In main.rs - the only place that knows about modes+output::initialize(if internal { OutputMode::Directive } else { OutputMode::Interactive });++// Everywhere else - just use the output functions+output::print(success_message("Created worktree"))?;+output::change_directory(&path)?;+```++## Available Output Functions++The output module (`src/output/global.rs`) provides:++- `print(message)` β Write message as-is (use with message formatting functions)+- `shell_integration_hint(message)` β Shell integration hints (π‘, suppressed in+ directive)+- `gutter(content)` β Gutter-formatted content (use with `format_with_gutter()`)+- `blank()` β Blank line for visual separation+- `data(content)` β Structured data output without emoji (JSON, for piping)+- `table(content)` β Table/UI output to stderr+- `change_directory(path)` β Request directory change+- `execute(command)` β Execute command or buffer for shell script+- `flush()` β Flush output buffers+- `flush_for_stderr_prompt()` β Flush before interactive prompts+- `terminate_output()` β Emit shell script in directive mode (no-op in+ interactive)++**Message formatting functions** (from `worktrunk::styling`):++- `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++For the complete API, see `src/output/global.rs` and `src/styling/constants.rs`.++## Adding New Output Functions++Add the function to both handlers, add dispatch in `global.rs`, never add mode+parameters. This maintains one canonical path: commands have ONE code path that+works for both modes.++## Architectural Constraint: --internal Commands Must Use Output System++Commands supporting `--internal` must never use direct print macros β use output+system functions to prevent directive leaks. Enforced by+`tests/output_system_guard.rs`.diff --git a/CLAUDE.md b/CLAUDE.mdindex 301b4f46f..e41785220 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -87,455 +87,6 @@ Keep the first line of flag and argument descriptions briefβaim for 3-6 words.The help text should be scannable. Users reading `wt switch --help` need to quickly understand what each flag does without parsing long sentences.-## CLI Output Formatting Standards--### User Message Principles--Output messages should acknowledge user-supplied arguments (flags, options, values) by reflecting those choices in the message text.--```rust-// User runs: wt switch --create feature --base=main-// β GOOD - acknowledges the base branch-"Created new worktree for feature from main at /path/to/worktree"-// β BAD - ignores the base argument-"Created new worktree for feature at /path/to/worktree"-```--**Avoid second-person ("you", "your"):** Messages should describe actions and state, not address the user directly.--```rust-// β BAD - second-person-"Use 'wt merge' to rebase your changes onto main"-// β GOOD - describes the action-"Use 'wt merge' to rebase onto main"--// β BAD - second-person-"Add one line to your shell config"-// β GOOD - refers to the thing-"Add one line to the shell config"-```--**Avoid redundant parenthesized content:** Parenthesized text should add new information, not restate what's already said.--```rust-// β BAD - parentheses restate "no changes"-"No changes after squashing 3 commits (commits resulted in no net changes)"-// β GOOD - clear and concise-"No changes after squashing 3 commits"-// β GOOD - parentheses add supplementary info-"Committing with default message... (3 files, +45, -12)"-```--**Avoid pronouns with cross-message referents:** Hints appear as separate messages from errors. Don't use pronouns like "it" that refer to something mentioned in the error message.--```rust-// β BAD - "it" refers to branch name in error message-// Error: "Branch 'feature' not found"-// Hint: "Use --create to create it"-// β GOOD - self-contained hint-// Error: "Branch 'feature' not found"-// Hint: "Use --create to create a new branch"-```--### Message Consistency Patterns--Use consistent punctuation and structure for related messages:--**Semicolon for qualifiers:** Separate the action from a qualifier/reason:-```rust-// Action; qualifier (flag)-"Removing feature worktree in background; retaining branch (--no-delete-branch)"-"Commands approved; not saved (--force)"-```--**Ampersand for conjunctions:** Use `&` for combined actions:-```rust-// Action & additional action-"Removing feature worktree & branch in background"-"Commands approved & saved to config"-```--**Explicit flag acknowledgment:** Show flags in parentheses when they change behavior:-```rust-// β GOOD - shows the flag explicitly-"Removing feature worktree in background; retaining branch (--no-delete-branch)"-// β BAD - doesn't acknowledge user's explicit choice-"Removing feature worktree in background; retaining branch"-```--**Parallel structure:** Related messages should follow the same pattern:-```rust-// β GOOD - parallel structure with integration reason explaining branch deletion-// Both wt merge and wt remove show integration reason when branch is deleted-"Removing feature worktree & branch in background (already in main)" // Branch is integrated (ancestor)-"Removing feature worktree & branch in background (files match main)" // Branch is integrated (squash/rebase)-"Removing feature worktree & branch in background (all changes in main)" // Branch is integrated (squash + main advanced)-"Removing feature worktree in background; retaining unmerged branch" // Unmerged (system keeps)-"Removing feature worktree in background; retaining branch (--no-delete-branch)" // User flag (user keeps)-```--**Compute decisions once:** For background operations, check conditions upfront, show the message, then pass the decision explicitly rather than re-checking in background scripts:-```rust-// β GOOD - check once, pass decision-let should_delete = check_if_merged();-show_message_based_on(should_delete);-spawn_background(build_command(should_delete));--// β BAD - check twice (once for message, again in background script)-let is_merged = check_if_merged();-show_message_based_on(is_merged);-spawn_background(build_command_that_checks_merge_again()); // Duplicate check!-```--### Message Types--Seven canonical message patterns with their emojis:--1. **Progress**: π (operations in progress)-2. **Success**: β (successful completion)-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)--**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 π‘ | Info βͺ |-|---------|---------|-| "Run `wt merge` to continue" | "Already up to date with main" |-| "Use `--force` to override" | "Skipping hooks (--no-verify)" |-| "Branch can be deleted" | "Worktree preserved (main worktree)" |--**Message formatting functions** add emoji AND semantic color. Callers provide content with optional inner styling (like `<bold>`), then pass to `output::print()`:--```rust-// Simple message - formatting function adds emoji + 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")))?;-```--**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 an emoji 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 emoji: `<cyan>SECTION TITLE</>`. This distinguishes organizational headers from status messages. Currently being trialed β expand to other commands if it works well.--### Blank Line Principles--- **No leading/trailing blanks** - Start immediately, end cleanly-- **One blank after blocks** - Separate multi-line content (gutter blocks, sections)-- **One blank after prompts** - Separate user input from results-- **Never double blanks** - One blank line maximum between elements--### stdout vs stderr--**Both modes write all messages to stderr.** stdout is reserved for structured data:--- **stdout**: JSON output (`--format=json`), shell scripts (directive mode)-- **stderr**: All user-facing messages (progress, success, errors, hints, gutter, etc.)--**Directive mode** additionally emits a shell script to stdout at the end.--Use the output system (`output::print()` with message formatting functions) to handle both modes automatically. Never write directly to stdout/stderr in command code.--```rust-// β GOOD - use output system (handles both modes)-output::print(success_message("Branch created"))?;--// β BAD - direct writes bypass output system-println!("Branch created");-```--Interactive prompts must flush stderr before blocking on stdin:-```rust-eprint!("β Allow and remember? [y/N] ");-stderr().flush()?;-io::stdin().read_line(&mut response)?;-```--### Temporal Locality: Output Should Be Close to Operations--Output should appear immediately adjacent to the operations it describes. Progress messages apply only to slow operations (>400ms): git operations, network requests, builds.--Sequential operations should show immediate feedback:-```rust-for item in items {- output::print(progress_message(format!("Removing {item}...")))?;- perform_operation(item)?;- output::print(success_message(format!("Removed {item}")))?; // Immediate feedback-}-```--Bad example (output decoupled from operations):-```-π Removing worktree for feature...-π Removing worktree for bugfix...- β Long delay, no feedback-Removed worktree for feature β All output at the end-Removed worktree for bugfix-```--Signs of poor temporal locality: collecting messages in a buffer, single success message for batch operations, no progress before slow operations.--### Information Display: Show Once, Not Twice--Progress messages should include all relevant details (what's being done, counts, stats, context). Success messages should be minimal, confirming completion with reference info (hash, path).--```rust-// β GOOD - detailed progress, minimal success-output::print(progress_message("Squashing 3 commits & working tree changes into a single commit (5 files, +60)..."))?;-perform_squash()?;-output::print(success_message("Squashed @ a1b2c3d"))?;-```--### Style Constants--Style constants in `src/styling/constants.rs` (minimal set for programmatic styling):-- `ADDITION`: Green (diffs, additions) - used in table rendering-- `DELETION`: Red (diffs, deletions) - used in table rendering-- `GUTTER`: BrightWhite background (quoted content)--Emoji constants: `PROGRESS_EMOJI` (π), `SUCCESS_EMOJI` (β ), `ERROR_EMOJI` (β), `WARNING_EMOJI` (π‘), `HINT_EMOJI` (π‘), `INFO_EMOJI` (βͺ), `PROMPT_EMOJI` (β)--For all other styling, use color-print tags in `cformat!`: `<red>`, `<green>`, `<yellow>`, `<cyan>`, `<dim>`, `<bold>`, `<bright-black>`--### Styling in Command Code--Use `output::print()` with message formatting functions. The formatting function adds the emoji + semantic color, and `cformat!` handles inner styling:--```rust-// β GOOD - formatting function handles emoji + outer color, cformat! handles inner styling-output::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>`--**Emoji constants in cformat!:** Use `{ERROR_EMOJI}`, `{HINT_EMOJI}`, etc. for messages that bypass output:: functions (e.g., GitError Display impl):--```rust-cformat!("{ERROR_EMOJI} <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 Messages--Never quote commands or branch names. Use styling to make them stand out:--- **In normal font context**: Use `<bold>` for commands and branches-- **In hints**: Use `<bright-black>` for commands (hint() already applies dimmingβno explicit `<dim>` needed)--```rust-// β GOOD - bold in normal context-output::info(cformat!("Use <bold>wt merge</> to continue"))?;--// β GOOD - bright-black for commands in hints-output::hint(cformat!("Run <bright-black>wt list</> to see worktrees"))?;--// β GOOD - plain hint without commands-output::hint("No changes to commit")?;--// β BAD - quoted commands-output::hint("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 emoji + 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 emoji and CJK characters (via `StyledLine`)-- **Graceful degradation** - Must work without color support--### StyledLine API--For complex table formatting with proper width calculations, use `StyledLine`:--```rust-use worktrunk::styling::StyledLine;-use anstyle::{AnsiColor, Color, Style};--let mut line = StyledLine::new();-line.push_styled("Branch", Style::new().dimmed());-line.push_raw(" ");-line.push_styled("main", Style::new().fg_color(Some(Color::Ansi(AnsiColor::Cyan))));-println!("{}", line.render());-```--See `src/commands/list/render.rs` for advanced usage.--### Gutter Formatting for Quoted Content--Use `format_with_gutter()` for **external data** β anything read from outside the application: git output, shell commands, commit messages, config values, cached data. Gutter visually quotes this content to distinguish it from application-generated output.--**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 external data.--**Linebreaks:** Gutter requires a single newline before it, never double. `output::print()` adds a trailing newline, so messages should not include `\n`:--```rust-// β GOOD - no trailing \n-output::print(progress_message("Merging..."))?;-output::gutter(format_with_gutter(&log, "", None))?;--// β BAD - trailing \n creates blank line-output::print(progress_message("Merging...\n"))?;-```--### Error Message Formatting--**Single-line errors with variables are fine:**-```rust-// β GOOD - single-line with path variable-.map_err(|e| format!("Failed to read {}: {}", format_path_for_display(path), e))?--// β GOOD - using .context() for simple errors-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:-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--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--// β BAD - multi-line error embedded inline-β Commit generation command 'llm' 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.--### 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).--### Snapshot Testing Requirement--Every command output must have a snapshot test (`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.--## Output System Architecture--### Two Output Modes--Worktrunk supports two output modes, selected once at program startup:-1. **Interactive Mode** - Human-friendly output with colors, emojis, and hints-2. **Directive Mode** - Shell script on stdout (at end), user messages on stderr--Both modes write all messages to stderr. stdout is reserved for structured data (JSON, shell scripts).--The mode is determined at initialization in `main()` and never changes during execution.--### The Cardinal Rule: Never Check Mode in Command Code--Command code must never check which output mode is active. The output system uses enum dispatch - commands call output functions without knowing the mode.--```rust-// β NEVER DO THIS-if mode == OutputMode::Interactive {- println!("β Success!");-}--// β ALWAYS DO THIS-output::print(success_message("Success!"))?;-```--Decide once at the edge (`main()`), initialize globally, trust internally:--```rust-// In main.rs - the only place that knows about modes-output::initialize(if internal { OutputMode::Directive } else { OutputMode::Interactive });--// Everywhere else - just use the output functions-output::print(success_message("Created worktree"))?;-output::change_directory(&path)?;-```--### Available Output Functions--The output module (`src/output/global.rs`) provides:--- `print(message)` - Write message as-is (use with message formatting functions)-- `shell_integration_hint(message)` - Shell integration hints (π‘, suppressed in directive)-- `gutter(content)` - Gutter-formatted content (use with `format_with_gutter()`)-- `blank()` - Blank line for visual separation-- `data(content)` - Structured data output without emoji (JSON, for piping)-- `table(content)` - Table/UI output to stderr-- `change_directory(path)` - Request directory change-- `execute(command)` - Execute command or buffer for shell script-- `flush()` - Flush output buffers-- `flush_for_stderr_prompt()` - Flush before interactive prompts-- `terminate_output()` - Emit shell script in directive mode (no-op in interactive)--**Message formatting functions** (from `worktrunk::styling`):--- `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--For the complete API, see `src/output/global.rs` and `src/styling/constants.rs`.--### Adding New Output Functions--Add the function to both handlers, add dispatch in `global.rs`, never add mode parameters. This maintains one canonical path: commands have ONE code path that works for both modes.--### Architectural Constraint: --internal Commands Must Use Output System--Commands supporting `--internal` must never use direct print macros - use output system functions to prevent directive leaks. Enforced by `tests/output_system_guard.rs`.-## Command Execution Principles### Real-time Output Streaming