Commit d6aba23
committed
Merge #142: Add builder pattern for StepsMessage and InfoBlockMessage
1a3079b style: apply cargo fmt formatting (copilot-swe-agent[bot])
287f106 feat: add builder patterns for StepsMessage and InfoBlockMessage (copilot-swe-agent[bot])
6b59a68 Initial plan (copilot-swe-agent[bot])
Pull request description:
Adds optional builder patterns for complex message types while maintaining backward compatibility with direct construction.
## Changes
**New message type:**
- `InfoBlockMessage` - displays titled multi-line information blocks
- Implements `OutputMessage` trait, routes to stderr at Normal verbosity
**Builder API:**
- `StepsMessageBuilder` - fluent API for constructing step lists
- `InfoBlockMessageBuilder` - fluent API for constructing info blocks
- Consuming pattern (methods take `self`) enables clean chaining
- Factory methods: `StepsMessage::builder()`, `InfoBlockMessage::builder()`
**Backward compatibility:**
- Added `StepsMessage::new()` and `InfoBlockMessage::new()` constructors
- Existing direct struct construction continues to work
- Updated `UserOutput::info_block()` to use new `InfoBlockMessage` internally
## Usage
```rust
// Builder pattern - dynamic construction, readable
let steps = StepsMessage::builder("Next steps:")
.add("Edit configuration")
.add("Review settings")
.build();
// Simple constructor - all data upfront
let steps = StepsMessage::new("Steps:", vec!["Step 1".to_string()]);
// Info blocks
let info = InfoBlockMessage::builder("Environment")
.add_line("Name: production")
.add_line("Status: running")
.build();
```
**Tests:** 25 new tests covering fluent API, direct construction, empty builders, integration with UserOutput/JSON formatter, and backward compatibility.
<!-- START COPILOT CODING AGENT SUFFIX -->
<details>
<summary>Original prompt</summary>
>
> ----
>
> *This section details on the original issue you should resolve*
>
> <issue_title>Proposal 8: Builder Pattern for Complex Messages</issue_title>
> <issue_description>## Overview
>
> Add optional builder patterns for complex message types in the `UserOutput` module. This proposal introduces builders that provide a fluent API for constructing complex messages while maintaining backward compatibility with simple direct construction.
>
> ## Specification
>
> See detailed specification: [docs/issues/139-builder-pattern-for-complex-messages.md](../docs/issues/139-builder-pattern-for-complex-messages.md)
>
> ## Goals
>
> - [ ] Create builder pattern for `StepsMessage` with fluent API
> - [ ] Create builder pattern for `InfoBlockMessage` with fluent API
> - [ ] Maintain backward compatibility with simple constructors
> - [ ] Enable future extensibility with optional parameters
> - [ ] Provide ergonomic API for common use cases
> - [ ] Document when to use builders vs simple constructors
>
> ## Implementation Plan
>
> ### Phase 1: StepsMessageBuilder Implementation (1 hour)
> - [ ] Create `StepsMessageBuilder` struct
> - [ ] Implement `new()`, `add()`, and `build()` methods
> - [ ] Add `StepsMessage::builder()` convenience method
> - [ ] Keep existing `StepsMessage::new()` constructor
>
> ### Phase 2: InfoBlockMessageBuilder Implementation (1 hour)
> - [ ] Create `InfoBlockMessageBuilder` struct
> - [ ] Implement `new()`, `add_line()`, and `build()` methods
> - [ ] Add `InfoBlockMessage::builder()` convenience method
>
> ### Phase 3: Testing (1.5 hours)
> - [ ] Add tests for fluent API usage
> - [ ] Add tests for direct construction (ensure backward compatibility)
> - [ ] Add tests for empty builders
> - [ ] Add integration tests showing formatting with builders
>
> ### Phase 4: Documentation and Quality (30 minutes)
> - [ ] Update module documentation with builder examples
> - [ ] Document when to use builders vs simple constructors
> - [ ] Run `./scripts/pre-commit.sh` and fix any issues
>
> **Total Estimated Time**: 4 hours
>
> ## Acceptance Criteria
>
> ### Functional Requirements
> - [ ] `StepsMessageBuilder` provides fluent API for step messages
> - [ ] `InfoBlockMessageBuilder` provides fluent API for info blocks
> - [ ] Simple constructors remain available and unchanged
> - [ ] Builders integrate seamlessly with `OutputMessage` trait
> - [ ] Builder pattern is consuming (not mutating)
>
> ### API Design Requirements
> - [ ] Builder API is ergonomic and intuitive
> - [ ] Method names are clear and follow Rust conventions
> - [ ] `builder()` and `new()` methods coexist for different use cases
>
> ### Testing Requirements
> - [ ] Unit tests cover fluent API construction
> - [ ] Tests verify backward compatibility with simple constructors
> - [ ] Tests cover edge cases (empty builders, single item, many items)
>
> ### Quality Requirements
> - [ ] Pre-commit checks pass: `./scripts/pre-commit.sh`
> - [ ] Builder pattern follows Rust idioms
> - [ ] No clippy warnings for builder implementation
>
> ## Related
>
> - **Parent Epic**: #102 - User Output Architecture Improvements
> - **Refactoring Plan**: [docs/refactors/plans/user-output-architecture-improvements.md](../docs/refactors/plans/user-output-architecture-improvements.md)
> - **Depends On**: #127 - Use Message Trait for Extensibility
>
> ## Labels
>
> `enhancement`, `phase-2`, `user-output`, `P2`
>
> ## Priority
>
> P2 (Phase 2 - Polish & Extensions)
>
> ## Estimated Effort
>
> 4 hours
> </issue_description>
>
> ## Comments on the Issue (you are @copilot in this section)
>
> <comments>
> <comment_new><author>@josecelano</author><body>
> **Parent Epic**: #102 - User Output Architecture Improvements
>
> This issue is part of Phase 2: Polish & Extensions of the User Output Architecture refactoring.</body></comment_new>
> </comments>
>
</details>
- Fixes #139
<!-- START COPILOT CODING AGENT TIPS -->
---
✨ Let Copilot coding agent [set things up for you](https://github.com/torrust/torrust-tracker-deployer/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.
ACKs for top commit:
josecelano:
ACK 1a3079b
Tree-SHA512: 034696625cbc0b1122bb5cb6543d534c171da45e76fb624fb3f15a504fce571bd890055ae2c125148a41723734d855bc0f97b8e7907bed06bc863681d8810c371 file changed
+719
-14
lines changed
0 commit comments