feat: add instance_ip to Environment context (Proposal #0)

Add instance_ip as optional field in Environment struct to simplify command API
by eliminating tuple return types.

Changes:
- Add instance_ip: Option<IpAddr> field to Environment<S> struct
- Add instance_ip() getter and with_instance_ip() builder method
- Update ProvisionCommand to return Environment<Provisioned> instead of tuple
- Store IP in environment context using .with_instance_ip(ip)
- Update all call sites to extract IP from environment when needed
- Preserve instance_ip through state transitions and type erasure
- Automatic serde serialization/deserialization support

Benefits:
- Simplified API: Result<Environment<T>, Error> vs Result<(Environment<T>, IpAddr), Error>
- Better cohesion: IP is execution context, belongs with environment
- Extensible: Easy to add more optional outputs without API changes
- Consistent: Follows pattern of data_dir, build_dir in Environment

Implementation of Proposal #0 from command-code-quality-improvements.md
All tests pass, all linters pass.

Author: josecelano

src/application/commands/provision.rs

@@ -192,7 +192,7 @@ impl ProvisionCommand {
     pub async fn execute(
         &self,
         environment: Environment<Created>,
-    ) -> Result<(Environment<Provisioned>, IpAddr), ProvisionCommandError> {
+    ) -> Result<Environment<Provisioned>, ProvisionCommandError> {
         info!(
             command = "provision",
             environment = %environment.name(),
@@ -212,17 +212,20 @@ impl ProvisionCommand {
         // This allows us to know exactly which step failed if an error occurs
         match self.execute_provisioning_with_tracking(&environment).await {
             Ok((provisioned, instance_ip)) => {
+                // Store instance IP in the environment context
+                let provisioned = provisioned.with_instance_ip(instance_ip);
+
                 // Persist final state
                 self.persist_provisioned_state(&provisioned);
 
                 info!(
                     command = "provision",
                     environment = %provisioned.name(),
-                    instance_ip = %instance_ip,
+                    instance_ip = ?provisioned.instance_ip(),
                     "Infrastructure provisioning completed successfully"
                 );
 
-                Ok((provisioned, instance_ip))
+                Ok(provisioned)
             }
             Err((e, current_step)) => {
                 // Transition to error state with structured context

src/bin/e2e_provision_tests.rs

@@ -198,7 +198,11 @@ async fn run_provisioning_test(env: &TestContext) -> Result<IpAddr> {
         "Starting infrastructure provisioning E2E test"
     );
 
-    let (_provisioned_env, instance_ip) = run_provision_command(env).await?;
+    let provisioned_env = run_provision_command(env).await?;
+
+    let instance_ip = provisioned_env
+        .instance_ip()
+        .expect("Instance IP must be set after successful provisioning");
 
     info!(
         status = "success",

src/bin/e2e_tests_full.rs

@@ -218,7 +218,12 @@ async fn run_full_deployment_test(env: &TestContext) -> Result<IpAddr> {
     );
 
     // Provision infrastructure - returns typed Environment<Provisioned>
-    let (provisioned_env, instance_ip) = run_provision_command(env).await?;
+    let provisioned_env = run_provision_command(env).await?;
+
+    // Extract instance IP from the provisioned environment
+    let instance_ip = provisioned_env
+        .instance_ip()
+        .expect("Instance IP must be set after successful provisioning");
 
     // Configure infrastructure - requires Environment<Provisioned>, returns Environment<Configured>
     // This demonstrates compile-time type safety: cannot call configure without provisioning first

src/domain/environment/mod.rs

@@ -68,6 +68,7 @@ pub use state::{
 use crate::domain::{InstanceName, ProfileName};
 use crate::shared::{ssh::SshCredentials, Username};
 use serde::{Deserialize, Serialize};
+use std::net::IpAddr;
 use std::path::PathBuf;
 
 /// Directory name for trace files within an environment's data directory
@@ -125,6 +126,13 @@ pub struct Environment<S = Created> {
     /// Data directory for this environment (auto-generated)
     data_dir: PathBuf,
 
+    /// Instance IP address (populated after provisioning)
+    ///
+    /// This field stores the IP address of the provisioned instance and is
+    /// `None` until the environment has been successfully provisioned.
+    /// Once set, it's carried through all subsequent state transitions.
+    instance_ip: Option<IpAddr>,
+
     /// Current state of the environment in the deployment lifecycle
     state: S,
 }
@@ -194,6 +202,7 @@ impl Environment {
             ssh_credentials,
             build_dir,
             data_dir,
+            instance_ip: None,
             state: Created,
         }
     }
@@ -238,6 +247,7 @@ impl<S> Environment<S> {
             ssh_credentials: self.ssh_credentials,
             build_dir: self.build_dir,
             data_dir: self.data_dir,
+            instance_ip: self.instance_ip,
             state: new_state,
         }
     }
@@ -318,6 +328,92 @@ impl<S> Environment<S> {
         &self.data_dir
     }
 
+    /// Returns the instance IP address if available
+    ///
+    /// The instance IP is populated after successful provisioning and is
+    /// `None` for environments that haven't been provisioned yet.
+    ///
+    /// # Returns
+    ///
+    /// - `Some(IpAddr)` if the environment has been provisioned
+    /// - `None` if the environment hasn't been provisioned yet
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use torrust_tracker_deploy::domain::{Environment, EnvironmentName};
+    /// use torrust_tracker_deploy::shared::{Username, ssh::SshCredentials};
+    /// use std::path::PathBuf;
+    /// use std::net::{IpAddr, Ipv4Addr};
+    ///
+    /// let env_name = EnvironmentName::new("test".to_string())?;
+    /// let ssh_username = Username::new("torrust".to_string())?;
+    /// let ssh_credentials = SshCredentials::new(
+    ///     PathBuf::from("keys/test_rsa"),
+    ///     PathBuf::from("keys/test_rsa.pub"),
+    ///     ssh_username,
+    /// );
+    /// let environment = Environment::new(env_name, ssh_credentials);
+    ///
+    /// // Before provisioning
+    /// assert_eq!(environment.instance_ip(), None);
+    ///
+    /// // After provisioning (simulated)
+    /// let ip = IpAddr::V4(Ipv4Addr::new(192, 168, 1, 100));
+    /// let environment = environment.with_instance_ip(ip);
+    /// assert_eq!(environment.instance_ip(), Some(ip));
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[must_use]
+    pub fn instance_ip(&self) -> Option<IpAddr> {
+        self.instance_ip
+    }
+
+    /// Sets the instance IP address for this environment
+    ///
+    /// This method is typically called by the `ProvisionCommand` after successfully
+    /// provisioning the infrastructure and obtaining the instance's IP address.
+    ///
+    /// # Arguments
+    ///
+    /// * `ip` - The IP address of the provisioned instance
+    ///
+    /// # Returns
+    ///
+    /// A new Environment instance with the IP address set
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use torrust_tracker_deploy::domain::{Environment, EnvironmentName};
+    /// use torrust_tracker_deploy::shared::{Username, ssh::SshCredentials};
+    /// use std::path::PathBuf;
+    /// use std::net::{IpAddr, Ipv4Addr};
+    ///
+    /// let env_name = EnvironmentName::new("production".to_string())?;
+    /// let ssh_username = Username::new("torrust".to_string())?;
+    /// let ssh_credentials = SshCredentials::new(
+    ///     PathBuf::from("keys/prod_rsa"),
+    ///     PathBuf::from("keys/prod_rsa.pub"),
+    ///     ssh_username,
+    /// );
+    /// let environment = Environment::new(env_name, ssh_credentials);
+    ///
+    /// // Set IP after provisioning
+    /// let ip = IpAddr::V4(Ipv4Addr::new(10, 0, 0, 42));
+    /// let environment = environment.with_instance_ip(ip);
+    ///
+    /// assert_eq!(environment.instance_ip(), Some(ip));
+    ///
+    /// # Ok::<(), Box<dyn std::error::Error>>(())
+    /// ```
+    #[must_use]
+    pub fn with_instance_ip(mut self, ip: IpAddr) -> Self {
+        self.instance_ip = Some(ip);
+        self
+    }
+
     /// Returns the templates directory for this environment
     ///
     /// The templates directory is located at `data/{env_name}/templates/`
@@ -643,6 +739,7 @@ mod tests {
                 ssh_credentials,
                 data_dir: data_dir.clone(),
                 build_dir: build_dir.clone(),
+                instance_ip: None,
                 state: Created,
             };
 

src/domain/environment/testing.rs

@@ -136,6 +136,7 @@ impl EnvironmentTestBuilder {
             ssh_credentials,
             data_dir: data_dir.clone(),
             build_dir: build_dir.clone(),
+            instance_ip: None,
             state: Created,
         };
 

src/e2e/tasks/virtual_machine/run_provision_command.rs

@@ -23,7 +23,6 @@
 //! the foundation infrastructure for all subsequent testing operations.
 
 use anyhow::{Context, Result};
-use std::net::IpAddr;
 use std::sync::Arc;
 use tracing::info;
 
@@ -32,8 +31,8 @@ use crate::e2e::context::TestContext;
 
 /// Provision infrastructure using `OpenTofu` and prepare for configuration
 ///
-/// Returns both the provisioned environment (for type-safe command chaining) and
-/// the IP address (for validation tasks).
+/// Returns the provisioned environment with the instance IP stored in its context.
+/// Callers can extract the IP address using `environment.instance_ip()`.
 ///
 /// # Errors
 ///
@@ -43,10 +42,7 @@ use crate::e2e::context::TestContext;
 /// - IP address cannot be obtained from `OpenTofu` outputs
 pub async fn run_provision_command(
     test_context: &TestContext,
-) -> Result<(
-    crate::domain::Environment<crate::domain::environment::Provisioned>,
-    IpAddr,
-)> {
+) -> Result<crate::domain::Environment<crate::domain::environment::Provisioned>> {
     info!("Provisioning test infrastructure");
 
     // Create repository for this environment
@@ -63,7 +59,7 @@ pub async fn run_provision_command(
     );
 
     // Execute provisioning with environment in Created state
-    let (provisioned_env, instance_ip) = provision_command
+    let provisioned_env = provision_command
         .execute(test_context.environment.clone())
         .await
         .map_err(anyhow::Error::from)
@@ -72,9 +68,9 @@ pub async fn run_provision_command(
     info!(
         status = "complete",
         environment = %provisioned_env.name(),
-        instance_ip = %instance_ip,
+        instance_ip = ?provisioned_env.instance_ip(),
         "Instance provisioned successfully"
     );
 
-    Ok((provisioned_env, instance_ip))
+    Ok(provisioned_env)
 }