Merge #141: Add flush() method to UserOutput for explicit buffering control

b3f98c7 feat: [#138] add buffering control with flush() method (copilot-swe-agent[bot])
b537a8f Initial plan (copilot-swe-agent[bot])

Pull request description:

  Adds explicit buffering control to `UserOutput` following Rust's `Write` trait pattern. While output is line-buffered by default, explicit flush ensures immediate visibility before long-running operations and improves test reliability.

  ## Changes

  **Core API**
  - Added `flush()` method that flushes both stdout and stderr writers
  - Returns `std::io::Result<()>` for error propagation
  - Safe to call multiple times (idempotent)

  **Documentation**
  - Module-level "Buffering Behavior" section explaining when to use `flush()`
  - Rustdoc examples demonstrating usage patterns

  **Tests**
  - 5 tests covering success scenarios, idempotency, empty buffers, dual-channel flushing, and sequential patterns
  - All existing tests pass (101 total in module)

  ## Usage

  ```rust
  let mut output = UserOutput::new(VerbosityLevel::Normal);
  output.progress("Starting long operation...");
  output.flush()?; // Ensure message appears immediately
  perform_long_operation();
  ```

  ## Implementation

  Directly flushes the typed writer wrappers (`StdoutWriter` and `StderrWriter`) maintaining type safety through the newtype pattern:

  ```rust
  pub fn flush(&mut self) -> std::io::Result<()> {
      self.stdout.0.flush()?;
      self.stderr.0.flush()?;
      Ok(())
  }
  ```

  Backward compatible - purely additive change.

  <!-- START COPILOT CODING AGENT SUFFIX -->

  <details>

  <summary>Original prompt</summary>

  >
  > ----
  >
  > *This section details on the original issue you should resolve*
  >
  > <issue_title>Proposal 7: Add Buffering Control</issue_title>
  > <issue_description>## Overview
  >
  > Add explicit buffering control to the `UserOutput` module by providing a `flush()` method. While writes are typically line-buffered by default, explicit flush control ensures output appears immediately when needed and provides better testing capabilities.
  >
  > ## Specification
  >
  > See detailed specification: [docs/issues/138-add-buffering-control.md](../docs/issues/138-add-buffering-control.md)
  >
  > ## Goals
  >
  > - [ ] Add `flush()` method to `UserOutput` for explicit buffer control
  > - [ ] Document buffering behavior in module documentation
  > - [ ] Add tests demonstrating flush behavior
  > - [ ] Maintain backward compatibility with existing API
  > - [ ] Follow Rust standard patterns from `Write` trait
  >
  > ## Implementation Plan
  >
  > ### Phase 1: Core Implementation (30 minutes)
  > - [ ] Add `flush()` method to `UserOutput`
  > - [ ] Implement flush for both `stdout` and `stderr` writers
  > - [ ] Add rustdoc documentation for the method
  >
  > ### Phase 2: Documentation (20 minutes)
  > - [ ] Update module-level documentation with buffering behavior section
  > - [ ] Add usage examples showing when to use `flush()`
  >
  > ### Phase 3: Testing (30 minutes)
  > - [ ] Add unit tests for successful flush
  > - [ ] Add tests for multiple flush calls
  > - [ ] Add tests for empty buffer flushing
  >
  > ### Phase 4: Quality Assurance (20 minutes)
  > - [ ] Run `./scripts/pre-commit.sh` and fix any issues
  > - [ ] Verify all linters pass
  >
  > **Total Estimated Time**: 2 hours
  >
  > ## Acceptance Criteria
  >
  > ### Functional Requirements
  > - [ ] `UserOutput::flush()` method flushes both stdout and stderr
  > - [ ] Flush can be called multiple times safely
  > - [ ] Flush returns `std::io::Result<()>` for error handling
  > - [ ] Existing functionality is not affected
  >
  > ### Testing Requirements
  > - [ ] Unit tests cover successful flush scenarios
  > - [ ] Tests verify idempotency (multiple flushes are safe)
  > - [ ] All existing tests continue to pass
  >
  > ### Quality Requirements
  > - [ ] Pre-commit checks pass: `./scripts/pre-commit.sh`
  > - [ ] Code follows project conventions
  >
  > ## 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**: #135 - Type-Safe Channel Routing
  >
  > ## Labels
  >
  > `enhancement`, `phase-2`, `user-output`, `P2`
  >
  > ## Priority
  >
  > P2 (Phase 2 - Polish & Extensions)
  >
  > ## Estimated Effort
  >
  > 2 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 #138

  <!-- START COPILOT CODING AGENT TIPS -->
  ---

  💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey).

ACKs for top commit:
  josecelano:
    ACK b3f98c7

Tree-SHA512: 0fc84cdba38998b69432de679681c740f4f698f8ad66640fd8ba806c36c659851373097e5a2e1bdaa469cac45174c6d1702e34b9fd18abe6383c1675b16be17c

Author: josecelano

src/presentation/user_output.rs

@@ -23,6 +23,18 @@
 //! The newtype pattern is a zero-cost abstraction - it has the same memory layout and performance
 //! characteristics as the wrapped type, but provides type safety benefits.
 //!
+//! ## Buffering Behavior
+//!
+//! Output is line-buffered by default. Messages are typically flushed automatically
+//! after each newline. For cases where immediate output is critical (e.g., before
+//! long-running operations), call `flush()` explicitly:
+//!
+//! ```rust,ignore
+//! output.progress("Starting long operation...");
+//! output.flush()?; // Ensure message appears before operation starts
+//! perform_long_operation();
+//! ```
+//!
 //! ## Example Usage
 //!
 //! ```rust
@@ -1083,6 +1095,32 @@ impl UserOutput {
         }
     }
 
+    /// Flush all pending output to stdout and stderr
+    ///
+    /// This is typically not needed as writes are line-buffered by default,
+    /// but can be useful for ensuring output appears immediately before
+    /// long-running operations or in test scenarios.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if flushing either stream fails.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use torrust_tracker_deployer_lib::presentation::user_output::{UserOutput, VerbosityLevel};
+    ///
+    /// let mut output = UserOutput::new(VerbosityLevel::Normal);
+    /// output.progress("Starting long operation...");
+    /// output.flush().expect("Failed to flush output");
+    /// // Now perform long operation...
+    /// ```
+    pub fn flush(&mut self) -> std::io::Result<()> {
+        self.stdout.0.flush()?;
+        self.stderr.0.flush()?;
+        Ok(())
+    }
+
     /// Display progress message to stderr (Normal level and above)
     ///
     /// Progress messages go to stderr following cargo/docker patterns.
@@ -2744,4 +2782,106 @@ mod tests {
             assert!(json.is_ok(), "Invalid JSON in stdout");
         }
     }
+
+    // ============================================================================
+    // Buffering Tests
+    // ============================================================================
+
+    mod buffering {
+        use super::super::*;
+        use crate::presentation::user_output::test_support::TestUserOutput;
+
+        #[test]
+        fn it_should_flush_all_writers() {
+            let mut test_output = TestUserOutput::new(VerbosityLevel::Normal);
+            test_output.output.progress("Test message");
+
+            // Flush should succeed
+            test_output.output.flush().expect("Flush should succeed");
+
+            // Verify output is present (flushed)
+            assert!(!test_output.stderr().is_empty());
+            assert!(test_output.stderr().contains("Test message"));
+        }
+
+        #[test]
+        fn it_should_be_safe_to_flush_multiple_times() {
+            let mut test_output = TestUserOutput::new(VerbosityLevel::Normal);
+            test_output.output.progress("Test message");
+
+            // Multiple flushes should be safe
+            test_output
+                .output
+                .flush()
+                .expect("First flush should succeed");
+            test_output
+                .output
+                .flush()
+                .expect("Second flush should succeed");
+            test_output
+                .output
+                .flush()
+                .expect("Third flush should succeed");
+
+            // Output should still be present
+            assert!(!test_output.stderr().is_empty());
+        }
+
+        #[test]
+        fn it_should_flush_empty_buffers_safely() {
+            let mut test_output = TestUserOutput::new(VerbosityLevel::Normal);
+
+            // Flushing with no output should be safe
+            test_output
+                .output
+                .flush()
+                .expect("Flushing empty buffers should succeed");
+
+            // No output should be present
+            assert_eq!(test_output.stderr(), "");
+            assert_eq!(test_output.stdout(), "");
+        }
+
+        #[test]
+        fn it_should_flush_both_stdout_and_stderr() {
+            let mut test_output = TestUserOutput::new(VerbosityLevel::Normal);
+
+            // Write to both channels
+            test_output.output.progress("Progress message");
+            test_output.output.result("Result data");
+
+            // Flush should handle both channels
+            test_output
+                .output
+                .flush()
+                .expect("Flush should succeed for both channels");
+
+            // Verify both outputs are present
+            assert!(test_output.stderr().contains("Progress message"));
+            assert!(test_output.stdout().contains("Result data"));
+        }
+
+        #[test]
+        fn it_should_work_with_sequential_flush_calls() {
+            let mut test_output = TestUserOutput::new(VerbosityLevel::Normal);
+
+            // Write, flush, write, flush pattern
+            test_output.output.progress("Message 1");
+            test_output
+                .output
+                .flush()
+                .expect("First flush should succeed");
+
+            test_output.output.progress("Message 2");
+            test_output
+                .output
+                .flush()
+                .expect("Second flush should succeed");
+
+            // Both messages should be present
+            let stderr = test_output.stderr();
+            assert!(stderr.contains("Message 1"));
+            assert!(stderr.contains("Message 2"));
+        }
+    }
 }