refactor: [#116] improve container test utilities structure

- Implement ContainerId newtype with validation for type safety
- Split container utilities into independent modules:
  - container_id.rs: validated container ID type
  - running_binary_container.rs: running container with binary
  - ubuntu_container_builder.rs: builder pattern for container creation
- Remove helpers.rs by moving functions to type methods
- Remove ubuntu.rs re-export module for direct imports
- Rename types for semantic clarity:
  - UbuntuTestContainer → RunningBinaryContainer
  - UbuntuContainerWithBinary → UbuntuContainerBuilder
- Add 'hexdigit' to project dictionary for spell checking

This refactoring improves modularity, type safety, and maintainability
while preserving all existing functionality. All tests remain passing.

Author: josecelano

packages/dependency-installer/tests/containers/container_id.rs

@@ -0,0 +1,62 @@
+//! Docker container identifier type
+
+use std::ffi::OsStr;
+use std::fmt;
+
+/// Docker container identifier
+///
+/// A validated Docker container ID, which is a hexadecimal string.
+/// Docker generates these IDs and guarantees they contain only hex characters (0-9, a-f).
+///
+/// # Examples
+///
+/// ```
+/// # use std::path::PathBuf;
+/// // Container IDs come from Docker/testcontainers and are always valid hex strings
+/// let id = ContainerId::new("a1b2c3d4e5f6".to_string()).expect("valid hex string");
+/// ```
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ContainerId(String);
+
+impl ContainerId {
+    /// Create a new container ID with validation
+    ///
+    /// # Arguments
+    ///
+    /// * `id` - The container ID string (must be hexadecimal)
+    ///
+    /// # Returns
+    ///
+    /// `Ok(ContainerId)` if valid, `Err` with error message if invalid
+    ///
+    /// # Validation Rules
+    ///
+    /// - Must not be empty
+    /// - Must contain only hexadecimal characters (0-9, a-f, A-F)
+    /// - Typically 12 characters (short form) or 64 characters (full SHA256)
+    pub fn new(id: String) -> Result<Self, String> {
+        if id.is_empty() {
+            return Err("Container ID cannot be empty".to_string());
+        }
+
+        if !id.chars().all(|c| c.is_ascii_hexdigit()) {
+            return Err(format!(
+                "Container ID must contain only hexadecimal characters, got: '{id}'"
+            ));
+        }
+
+        Ok(Self(id))
+    }
+}
+
+impl fmt::Display for ContainerId {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+impl AsRef<OsStr> for ContainerId {
+    fn as_ref(&self) -> &OsStr {
+        OsStr::new(&self.0)
+    }
+}

packages/dependency-installer/tests/containers/helpers.rs

@@ -2,5 +2,6 @@
 //!
 //! This module provides helper types and functions for managing test containers.
 
-pub mod helpers;
-pub mod ubuntu;
+pub(super) mod container_id;
+pub(super) mod running_binary_container;
+pub mod ubuntu_container_builder;

packages/dependency-installer/tests/containers/mod.rs

@@ -0,0 +1,118 @@
+//! Running container with an installed binary
+
+use std::path::Path;
+use std::process::Command;
+
+use testcontainers::{ContainerAsync, GenericImage};
+
+use super::container_id::ContainerId;
+
+/// A running Ubuntu container with a binary installed and ready to execute
+///
+/// This struct provides methods for executing commands and managing a running
+/// Ubuntu container that has been prepared with a binary. It handles the container
+/// lifecycle, ensuring the container stays alive while tests run, and provides
+/// convenient methods for command execution and file operations.
+pub struct RunningBinaryContainer {
+    // Keep a reference to the container so it stays alive
+    #[allow(dead_code)]
+    container: ContainerAsync<GenericImage>,
+    container_id: ContainerId,
+}
+
+impl RunningBinaryContainer {
+    /// Create a new running binary container
+    ///
+    /// # Arguments
+    ///
+    /// * `container` - The running Docker container
+    /// * `container_id` - The validated container ID
+    pub(super) fn new(container: ContainerAsync<GenericImage>, container_id: ContainerId) -> Self {
+        Self {
+            container,
+            container_id,
+        }
+    }
+
+    /// Execute a command in the container and return stdout
+    ///
+    /// # Arguments
+    ///
+    /// * `command` - Command and arguments to execute
+    ///
+    /// # Returns
+    ///
+    /// The combined stdout and stderr output as a string
+    ///
+    /// # Note
+    ///
+    /// The output combines stderr and stdout because the CLI uses tracing which writes
+    /// logs to stderr, while user-facing messages go to stdout. We need both for
+    /// comprehensive test assertions. Stderr is placed first to maintain chronological
+    /// order of log messages relative to output.
+    pub fn exec(&self, command: &[&str]) -> String {
+        let output = Command::new("docker")
+            .arg("exec")
+            .arg(&self.container_id)
+            .args(command)
+            .output()
+            .expect("Failed to execute docker exec command");
+
+        // Combine stderr (logs) and stdout (user messages) to capture all output
+        let stdout = String::from_utf8_lossy(&output.stdout);
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        format!("{stderr}{stdout}")
+    }
+
+    /// Execute a command and return the exit code
+    ///
+    /// # Arguments
+    ///
+    /// * `command` - Command and arguments to execute
+    ///
+    /// # Returns
+    ///
+    /// The exit code of the command, or 1 if the process was terminated by a signal
+    ///
+    /// # Note
+    ///
+    /// If the process was terminated by a signal (returns None from `code()`), we return 1
+    /// to indicate failure rather than 0, which would incorrectly suggest success.
+    pub fn exec_with_exit_code(&self, command: &[&str]) -> i32 {
+        let status = Command::new("docker")
+            .arg("exec")
+            .arg(&self.container_id)
+            .args(command)
+            .status()
+            .expect("Failed to execute docker exec command");
+
+        // Return 1 (failure) if terminated by signal, otherwise use actual exit code
+        status.code().unwrap_or(1)
+    }
+
+    /// Copy a file from the host into this running container
+    ///
+    /// This method uses Docker CLI to copy files into the running container.
+    ///
+    /// # Arguments
+    ///
+    /// * `source_path` - Path to the file on the host system
+    /// * `dest_path` - Destination path inside the container
+    ///
+    /// # Panics
+    ///
+    /// Panics if the Docker copy command fails
+    pub(super) fn copy_file_to_container(&self, source_path: &Path, dest_path: &str) {
+        let output = Command::new("docker")
+            .arg("cp")
+            .arg(source_path)
+            .arg(format!("{}:{dest_path}", self.container_id))
+            .output()
+            .expect("Failed to execute docker cp command");
+
+        if !output.status.success() {
+            let stderr = String::from_utf8_lossy(&output.stderr);
+            panic!("Failed to copy file to container: {stderr}");
+        }
+    }
+}