sublime_cli_tools/commands/

clone.rs

//! Clone command implementation.
//!
//! This module implements the repository cloning functionality with automatic
//! workspace setup. It provides a seamless developer onboarding experience by
//! cloning a Git repository and automatically initializing or validating
//! workspace configuration.
//!
//! # What
//!
//! Provides the `clone` command that:
//! - Clones Git repositories (HTTPS and SSH)
//! - Shows progress during clone operations
//! - Supports shallow clones with --depth flag
//! - Supports --force to overwrite existing directories
//! - Automatically detects workspace configuration (Story 11.3)
//! - Validates existing configuration (Story 11.3)
//! - Initializes workspace if no configuration exists (Story 11.4)
//!
//! # How
//!
//! The command follows this flow:
//! 1. Parse URL and determine destination directory
//! 2. Validate destination doesn't exist (unless --force)
//! 3. Remove destination if --force is set
//! 4. Clone repository with progress indication
//! 5. Detect workspace configuration (Story 11.3)
//! 6. Validate configuration or run init (Story 11.3/11.4)
//! 7. Display success message with next steps (Story 11.4)
//!
//! # Why
//!
//! Cloning with automatic setup:
//! - Reduces onboarding friction for new developers
//! - Ensures consistent workspace setup
//! - Validates configuration immediately
//! - Provides clear feedback and next steps
//!
//! # Examples
//!
//! ```bash
//! # Clone to default location (repository name)
//! workspace clone https://github.com/org/repo.git
//!
//! # Clone to specific directory
//! workspace clone https://github.com/org/repo.git ./my-dir
//!
//! # Clone with configuration overrides
//! workspace clone https://github.com/org/repo.git \
//!     --strategy independent \
//!     --environments "dev,staging,prod"
//!
//! # Force clone (remove existing directory)
//! workspace clone https://github.com/org/repo.git --force
//!
//! # Shallow clone
//! workspace clone https://github.com/org/repo.git --depth 1
//! ```

use crate::cli::commands::{CloneArgs, InitArgs};
use crate::error::{CliError, Result};
use crate::output::OutputFormat;
use crate::output::progress::ProgressBar;
use regex::Regex;
use std::fmt;
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex};
use sublime_git_tools::Repo;
use sublime_pkg_tools::config::PackageToolsConfig;
use sublime_pkg_tools::types::VersioningStrategy;
use sublime_standard_tools::config::Configurable;
use sublime_standard_tools::filesystem::{AsyncFileSystem, FileSystemManager};
use tracing::{debug, info};

/// Represents the result of a validation operation.
///
/// Contains the overall validation status, the detected strategy (if any),
/// and a list of individual validation checks.
///
/// # Examples
///
/// ```rust,ignore
/// let result = ValidationResult {
///     is_valid: false,
///     strategy: Some(VersioningStrategy::Independent),
///     checks: vec![
///         ValidationCheck {
///             name: "Configuration file".to_string(),
///             passed: true,
///             error: None,
///             suggestion: None,
///         },
///         ValidationCheck {
///             name: "Changeset directory".to_string(),
///             passed: false,
///             error: Some("Directory does not exist".to_string()),
///             suggestion: Some("Run 'workspace init --force'".to_string()),
///         },
///     ],
/// };
/// ```
#[derive(Debug, Clone)]
pub struct ValidationResult {
    /// Whether all validation checks passed.
    pub is_valid: bool,

    /// The versioning strategy detected from configuration, if available.
    pub strategy: Option<VersioningStrategy>,

    /// List of individual validation checks performed.
    pub checks: Vec<ValidationCheck>,
}

/// Represents an individual validation check.
///
/// Each check has a name, a pass/fail status, and optional error message
/// and suggestion for fixing the issue.
///
/// # Examples
///
/// ```rust,ignore
/// let check = ValidationCheck {
///     name: "Configuration file".to_string(),
///     passed: false,
///     error: Some("File not found".to_string()),
///     suggestion: Some("Run 'workspace init' to create configuration".to_string()),
/// };
/// ```
#[derive(Debug, Clone)]
pub struct ValidationCheck {
    /// The name of the validation check.
    pub name: String,

    /// Whether the check passed.
    pub passed: bool,

    /// Optional error message if the check failed.
    pub error: Option<String>,

    /// Optional suggestion for fixing the issue.
    pub suggestion: Option<String>,
}

impl fmt::Display for ValidationResult {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        writeln!(f, "Validation Results:")?;
        writeln!(f)?;

        if let Some(strategy) = &self.strategy {
            let strategy_str = match strategy {
                VersioningStrategy::Independent => "independent",
                VersioningStrategy::Unified => "unified",
            };
            writeln!(f, "Strategy: {strategy_str}")?;
            writeln!(f)?;
        }

        writeln!(f, "Checks:")?;
        for check in &self.checks {
            let status = if check.passed { "✓" } else { "✗" };
            writeln!(f, "  {status} {}", check.name)?;

            if let Some(error) = &check.error {
                writeln!(f, "    Error: {error}")?;
            }

            if let Some(suggestion) = &check.suggestion {
                writeln!(f, "    Suggestion: {suggestion}")?;
            }
        }

        writeln!(f)?;
        let overall = if self.is_valid { "VALID" } else { "INVALID" };
        writeln!(f, "Overall Status: {overall}")?;

        Ok(())
    }
}

/// Helper function to validate directory existence.
///
/// Creates a `ValidationCheck` for a directory.
///
/// # Arguments
///
/// * `fs` - The filesystem manager
/// * `root` - The root directory
/// * `path` - The relative path to check
/// * `name` - Display name for the check
async fn validate_directory(
    fs: &FileSystemManager,
    root: &Path,
    path: &str,
    name: &str,
) -> ValidationCheck {
    let dir = root.join(path);
    let exists = fs.exists(&dir).await;
    ValidationCheck {
        name: name.to_string(),
        passed: exists,
        error: if exists { None } else { Some(format!("Directory '{path}' does not exist")) },
        suggestion: if exists {
            None
        } else {
            Some("Run 'workspace init --force' to create directory".to_string())
        },
    }
}

/// Validates workspace configuration and directory structure.
///
/// Performs comprehensive validation including:
/// 1. Configuration file existence and loading
/// 2. Configuration structure validation using `Configurable::validate()`
/// 3. Required directory existence checks (.changesets/, .changesets/history/, .workspace-backups/)
/// 4. .gitignore entries verification
///
/// # Arguments
///
/// * `root` - The root directory of the workspace to validate
///
/// # Returns
///
/// Returns a `ValidationResult` containing:
/// - Overall validation status (passed/failed)
/// - Detected versioning strategy
/// - Individual check results with errors and suggestions
///
/// # Errors
///
/// Returns an error if:
/// - File system operations fail
/// - Cannot read .gitignore file
///
/// # Examples
///
/// ```rust,ignore
/// let result = validate_workspace(Path::new("./my-repo")).await?;
/// if result.is_valid {
///     println!("Workspace is valid!");
/// } else {
///     println!("Validation failed:");
///     for check in &result.checks {
///         if !check.passed {
///             println!("  - {}: {}", check.name, check.error.as_ref().unwrap());
///         }
///     }
/// }
/// ```
pub async fn validate_workspace(root: &Path) -> Result<ValidationResult> {
    let mut checks = Vec::new();
    let fs = FileSystemManager::new();

    // Check 1: Load and validate configuration
    let config_result = crate::commands::find_and_load_config(root, None).await?;

    let (config_check, config_opt) = match config_result {
        Some(config) => {
            // Config loaded, now validate it using the Configurable trait
            match config.validate() {
                Ok(()) => (
                    ValidationCheck {
                        name: "Configuration file".to_string(),
                        passed: true,
                        error: None,
                        suggestion: None,
                    },
                    Some(config),
                ),
                Err(e) => (
                    ValidationCheck {
                        name: "Configuration validation".to_string(),
                        passed: false,
                        error: Some(format!("Validation failed: {e}")),
                        suggestion: Some(
                            "Fix configuration errors or run 'workspace init --force'".to_string(),
                        ),
                    },
                    Some(config),
                ),
            }
        }
        None => (
            ValidationCheck {
                name: "Configuration file".to_string(),
                passed: false,
                error: Some("Configuration file not found".to_string()),
                suggestion: Some("Run 'workspace init' to create configuration".to_string()),
            },
            None,
        ),
    };
    checks.push(config_check);

    // Check 2: Changeset directory
    let changeset_path = config_opt.as_ref().map_or(".changesets", |c| c.changeset.path.as_str());
    checks.push(validate_directory(&fs, root, changeset_path, "Changeset directory").await);

    // Check 3: History directory
    let history_path =
        config_opt.as_ref().map_or(".changesets/history", |c| c.changeset.history_path.as_str());
    checks.push(validate_directory(&fs, root, history_path, "History directory").await);

    // Check 4: Backup directory
    let backup_path =
        config_opt.as_ref().map_or(".workspace-backups", |c| c.upgrade.backup.backup_dir.as_str());
    checks.push(validate_directory(&fs, root, backup_path, "Backup directory").await);

    // Check 5: .gitignore entries
    let gitignore_path = root.join(".gitignore");
    let gitignore_check = if fs.exists(&gitignore_path).await {
        let content = fs.read_file_string(&gitignore_path).await.map_err(|e| {
            CliError::io(format!(
                "Failed to read .gitignore file at {}: {e}",
                gitignore_path.display()
            ))
        })?;

        let has_changesets = content.contains(changeset_path);
        let has_backups = content.contains(backup_path);

        ValidationCheck {
            name: ".gitignore entries".to_string(),
            passed: has_changesets && has_backups,
            error: if !has_changesets || !has_backups {
                Some("Missing .gitignore entries for workspace directories".to_string())
            } else {
                None
            },
            suggestion: if !has_changesets || !has_backups {
                Some("Run 'workspace init --force' to update .gitignore".to_string())
            } else {
                None
            },
        }
    } else {
        ValidationCheck {
            name: ".gitignore file".to_string(),
            passed: false,
            error: Some(".gitignore file does not exist".to_string()),
            suggestion: Some("Create .gitignore with workspace directories".to_string()),
        }
    };
    checks.push(gitignore_check);

    // Determine overall validity
    let is_valid = checks.iter().all(|c| c.passed);

    // Extract strategy if configuration loaded successfully
    let strategy = config_opt.map(|c| c.version.strategy);

    Ok(ValidationResult { is_valid, strategy, checks })
}

/// Determines the destination directory for cloning.
///
/// Extracts the repository name from the URL and uses it as the destination
/// if no explicit destination was provided. Supports both HTTPS and SSH URLs.
///
/// # URL Formats Supported
///
/// - HTTPS: `https://github.com/org/repo.git` → `repo`
/// - HTTPS (no .git): `https://github.com/org/repo` → `repo`
/// - SSH: `git@github.com:org/repo.git` → `repo`
/// - SSH (no .git): `git@github.com:org/repo` → `repo`
///
/// # Arguments
///
/// * `url` - The repository URL to clone from
/// * `destination` - Optional explicit destination directory
///
/// # Returns
///
/// Returns the destination `PathBuf` that should be used for cloning.
///
/// # Errors
///
/// Returns an error if:
/// - The URL format is invalid
/// - Cannot extract repository name from URL
///
/// # Examples
///
/// ```rust,ignore
/// // HTTPS URL
/// let dest = determine_destination(
///     "https://github.com/org/repo.git",
///     None
/// )?;
/// assert_eq!(dest, PathBuf::from("repo"));
///
/// // SSH URL
/// let dest = determine_destination(
///     "git@github.com:org/repo.git",
///     None
/// )?;
/// assert_eq!(dest, PathBuf::from("repo"));
///
/// // Explicit destination takes precedence
/// let dest = determine_destination(
///     "https://github.com/org/repo.git",
///     Some(&PathBuf::from("my-dir"))
/// )?;
/// assert_eq!(dest, PathBuf::from("my-dir"));
/// ```
pub(crate) fn determine_destination(url: &str, destination: Option<&PathBuf>) -> Result<PathBuf> {
    // If destination is explicitly provided, use it
    if let Some(dest) = destination {
        return Ok(dest.clone());
    }

    // Extract repository name from URL
    // Supports:
    // - HTTPS: https://github.com/org/repo.git
    // - SSH: git@github.com:org/repo.git
    // - Without .git extension

    // Try HTTPS format first: https://.../org/repo.git or https://.../org/repo
    let https_regex = Regex::new(r"https?://[^/]+/.*/([^/]+?)(\.git)?$")
        .map_err(|e| CliError::validation(format!("Invalid URL regex: {e}")))?;

    if let Some(captures) = https_regex.captures(url)
        && let Some(repo_name) = captures.get(1)
    {
        return Ok(PathBuf::from(repo_name.as_str()));
    }

    // Try SSH format: git@host:org/repo.git or git@host:org/repo
    let ssh_regex = Regex::new(r"^[^@]+@[^:]+:.*/([^/]+?)(\.git)?$")
        .map_err(|e| CliError::validation(format!("Invalid URL regex: {e}")))?;

    if let Some(captures) = ssh_regex.captures(url)
        && let Some(repo_name) = captures.get(1)
    {
        return Ok(PathBuf::from(repo_name.as_str()));
    }

    // If we couldn't parse the URL, return an error
    Err(CliError::validation(format!(
        "Unable to determine repository name from URL: {url}. \
         Please provide an explicit destination directory."
    )))
}

/// Validates that the destination directory is suitable for cloning.
///
/// Checks that the destination either doesn't exist, or can be removed
/// if the --force flag is set.
///
/// # Arguments
///
/// * `destination` - The destination directory path
/// * `force` - Whether to allow overwriting existing directory
///
/// # Returns
///
/// Returns `Ok(())` if the destination is valid, or an error otherwise.
///
/// # Errors
///
/// Returns an error if:
/// - Destination exists and --force is not set
/// - Cannot access destination path
///
/// # Examples
///
/// ```rust,ignore
/// // New directory - should succeed
/// validate_destination(Path::new("./new-dir"), false)?;
///
/// // Existing directory without force - should fail
/// let result = validate_destination(Path::new("./existing"), false);
/// assert!(result.is_err());
///
/// // Existing directory with force - should succeed
/// validate_destination(Path::new("./existing"), true)?;
/// ```
pub(crate) fn validate_destination(destination: &Path, force: bool) -> Result<()> {
    // Check if destination exists
    if destination.exists() {
        if !force {
            return Err(CliError::validation(format!(
                "Destination already exists: {}. Use --force to overwrite.",
                destination.display()
            )));
        }

        // With --force, we'll allow removal (this will be handled by the execute function)
        // Just validate that it's accessible
        if !destination.is_dir() {
            return Err(CliError::validation(format!(
                "Destination exists but is not a directory: {}",
                destination.display()
            )));
        }
    }

    Ok(())
}

/// Clones a Git repository with progress indication.
///
/// This function performs the actual Git clone operation using `sublime_git_tools`,
/// displaying progress feedback to the user via a spinner. It supports both
/// full and shallow clones.
///
/// # Arguments
///
/// * `url` - The repository URL to clone from
/// * `destination` - The local path where the repository should be cloned
/// * `depth` - Optional depth for shallow clone (None for full clone)
/// * `format` - Output format to control progress display
///
/// # Returns
///
/// Returns the cloned `Repo` instance on success.
///
/// # Errors
///
/// Returns an error if:
/// - Network connection fails
/// - Authentication fails (for private repositories)
/// - Insufficient disk space
/// - Permission denied
/// - Invalid URL or destination
///
/// # Examples
///
/// ```rust,ignore
/// // Full clone
/// let repo = clone_with_progress(
///     "https://github.com/org/repo.git",
///     Path::new("./repo"),
///     None,
///     OutputFormat::Human
/// )?;
///
/// // Shallow clone
/// let repo = clone_with_progress(
///     "https://github.com/org/repo.git",
///     Path::new("./repo"),
///     Some(1),
///     OutputFormat::Human
/// )?;
/// ```
///
/// # Implementation Notes
///
/// Uses `Repo::clone_with_progress()` from `sublime_git_tools` which supports
/// progress callbacks for real-time progress tracking. The progress bar displays:
/// - Receiving objects with percentage
/// - Current/total object counts
/// - Completion status
pub(crate) fn clone_with_progress(
    url: &str,
    destination: &Path,
    depth: Option<u32>,
    format: OutputFormat,
) -> Result<Repo> {
    let destination_str = destination.to_str().ok_or_else(|| {
        CliError::validation(format!("Invalid destination path: {}", destination.display()))
    })?;

    // Convert depth from u32 to i32 if specified
    let depth_i32 = if let Some(depth_value) = depth {
        Some(i32::try_from(depth_value).map_err(|_| {
            CliError::validation(format!(
                "Depth value {} is too large (maximum: {})",
                depth_value,
                i32::MAX
            ))
        })?)
    } else {
        None
    };

    // Create progress bar for tracking clone progress
    // Start with 0 total - will be updated when we get the first progress callback
    let progress = Arc::new(Mutex::new(ProgressBar::new_with_format(0, format)));
    let progress_clone = Arc::clone(&progress);

    // Start with a spinner message until we know the total
    {
        let pb = progress
            .lock()
            .map_err(|e| CliError::execution(format!("Failed to lock progress bar: {e}")))?;
        pb.set_message(format!("Cloning repository from {url}..."));
    }

    // Perform clone operation with progress tracking
    let result =
        Repo::clone_with_progress(url, destination_str, depth_i32, move |current, total| {
            if let Ok(pb) = progress_clone.lock()
                && total > 0
            {
                // Update progress bar with current progress
                // Casting is intentional: converting object counts to percentage display
                #[allow(
                    clippy::cast_precision_loss,
                    clippy::cast_possible_truncation,
                    clippy::cast_sign_loss
                )]
                let percentage = (current as f64 / total as f64 * 100.0) as u64;
                pb.set_position(current as u64);
                pb.set_message(format!("Receiving objects: {percentage}% ({current}/{total})"));
            }
        });

    // Handle result
    let repo = match result {
        Ok(repo) => {
            // Clone succeeded
            let pb = progress
                .lock()
                .map_err(|e| CliError::execution(format!("Failed to lock progress bar: {e}")))?;
            pb.finish_with_message("✓ Clone complete");
            repo
        }
        Err(e) => {
            // Clone failed
            let pb = progress
                .lock()
                .map_err(|e| CliError::execution(format!("Failed to lock progress bar: {e}")))?;
            pb.abandon_with_message("✗ Clone failed");
            return Err(map_git_error(&e, url));
        }
    };

    Ok(repo)
}

/// Maps Git errors to user-friendly CLI errors with actionable messages.
///
/// Analyzes the Git error and provides context-specific error messages
/// with suggestions for fixing common issues.
///
/// # Arguments
///
/// * `error` - The Git error from `sublime_git_tools`
/// * `url` - The repository URL that was being cloned
///
/// # Returns
///
/// Returns a `CliError` with a user-friendly message and suggestions.
///
/// # Error Categories
///
/// - Network errors: Connection failed, timeout, DNS resolution
/// - Authentication errors: Invalid credentials, SSH key issues, missing token
/// - Disk space errors: Insufficient space, quota exceeded
/// - Permission errors: Access denied, read-only filesystem
/// - Repository errors: Not found, invalid URL, empty repository
///
/// # Examples
///
/// ```rust,ignore
/// let repo = Repo::clone(url, dest).map_err(|e| map_git_error(e, url))?;
/// ```
fn map_git_error(error: &sublime_git_tools::RepoError, url: &str) -> CliError {
    use sublime_git_tools::RepoError;

    let error_msg = error.to_string();
    let lowercase_msg = error_msg.to_lowercase();

    // Network errors
    if lowercase_msg.contains("failed to resolve")
        || lowercase_msg.contains("could not resolve")
        || lowercase_msg.contains("name or service not known")
    {
        return CliError::git(format!(
            "Network error: Could not resolve host for URL: {url}\n\
             \n\
             Suggestions:\n\
             - Check your internet connection\n\
             - Verify the repository URL is correct\n\
             - Check if the hostname is accessible"
        ));
    }

    if lowercase_msg.contains("connection") || lowercase_msg.contains("timeout") {
        return CliError::git(format!(
            "Network error: Connection failed for URL: {url}\n\
             \n\
             Suggestions:\n\
             - Check your internet connection\n\
             - Verify you can access the repository host\n\
             - Try again later if the service is temporarily unavailable"
        ));
    }

    // Authentication errors
    if lowercase_msg.contains("authentication")
        || lowercase_msg.contains("credential")
        || lowercase_msg.contains("permission denied")
    {
        let suggestion = if url.starts_with("git@") || url.contains("ssh://") {
            "Suggestions:\n\
             - Ensure your SSH key is added to your SSH agent\n\
             - Verify your SSH key is registered with the git hosting service\n\
             - Check SSH key permissions (should be 600 for private key)\n\
             - Try: ssh -T git@<hostname> to test SSH connection"
        } else {
            "Suggestions:\n\
             - Verify you have access to this repository\n\
             - For private repositories, ensure authentication is configured\n\
             - Check if your access token or credentials are valid\n\
             - Try using SSH URL instead of HTTPS"
        };

        return CliError::git(format!(
            "Authentication error: Failed to authenticate for URL: {url}\n\
             \n\
             {suggestion}"
        ));
    }

    // Disk space errors
    if lowercase_msg.contains("no space")
        || lowercase_msg.contains("disk full")
        || lowercase_msg.contains("quota exceeded")
    {
        return CliError::io(
            "Disk space error: Insufficient disk space to clone repository\n\
             \n\
             Suggestions:\n\
             - Free up disk space\n\
             - Choose a different destination with more space\n\
             - Consider using --depth 1 for a shallow clone (requires less space)"
                .to_string(),
        );
    }

    // Repository not found
    if lowercase_msg.contains("not found")
        || lowercase_msg.contains("repository not found")
        || lowercase_msg.contains("404")
    {
        return CliError::git(format!(
            "Repository error: Repository not found: {url}\n\
             \n\
             Suggestions:\n\
             - Verify the repository URL is correct\n\
             - Check if the repository exists\n\
             - Ensure you have access to the repository if it's private"
        ));
    }

    // Generic git error with context
    match &error {
        RepoError::CloneRepoFailure(e) => CliError::git(format!(
            "Failed to clone repository from {url}: {error}\n\
             \n\
             Original error: {e}"
        )),
        _ => CliError::git(format!("Git operation failed: {error}")),
    }
}

/// Executes the clone command.
///
/// This function orchestrates the complete clone workflow including:
/// 1. Determining the destination directory
/// 2. Validating the destination
/// 3. Removing existing destination if --force is set
/// 4. Cloning the repository with progress
/// 5. Detecting and validating workspace configuration (Story 11.3)
/// 6. Initializing workspace if needed (Story 11.4)
///
/// # Arguments
///
/// * `args` - Clone command arguments containing URL, destination, and options
/// * `output` - Output handler for consistent formatting across all commands
/// * `root` - Root directory for the workspace
/// * `config_path` - Optional path to configuration file
///
/// # Returns
///
/// Returns `Ok(())` on successful clone and setup, or an error if any step fails.
///
/// # Errors
///
/// Returns an error if:
/// - URL parsing fails
/// - Destination validation fails
/// - Clone operation fails (network, auth, disk space, etc.)
/// - Workspace setup fails (Stories 11.3/11.4)
///
/// # Examples
///
/// ```rust,ignore
/// use sublime_cli_tools::output::{Output, OutputFormat};
/// use std::io;
///
/// let args = CloneArgs {
///     url: "https://github.com/org/repo.git".to_string(),
///     destination: None,
///     force: false,
///     depth: None,
///     // ... other fields
/// };
///
/// let output = Output::new(OutputFormat::Human, io::stdout(), false);
/// execute_clone(&args, &output, Path::new("."), None).await?;
/// ```
pub async fn execute_clone(
    args: &CloneArgs,
    output: &crate::output::Output,
    root: &Path,
    config_path: Option<&Path>,
) -> Result<()> {
    // Step 1: Determine destination directory
    let destination = determine_destination(&args.url, args.destination.as_ref())?;

    // Step 2: Make destination relative to root (respecting --root global option)
    // Absolute paths are used as-is, relative paths are joined with root
    let final_destination =
        if destination.is_absolute() { destination } else { root.join(destination) };

    debug!("Clone destination: {} (root: {})", final_destination.display(), root.display());

    // Step 3: Validate destination
    validate_destination(&final_destination, args.force)?;

    // Step 4: Remove existing destination if --force is set
    if args.force && final_destination.exists() {
        let fs = FileSystemManager::new();
        fs.remove(&final_destination).await.map_err(|e| {
            CliError::io(format!(
                "Failed to remove existing destination {}: {}",
                final_destination.display(),
                e
            ))
        })?;
    }

    // Step 5: Clone repository with progress
    debug!("Cloning repository from {} to {}", args.url, final_destination.display());
    let _repo = clone_with_progress(&args.url, &final_destination, args.depth, output.format())?;
    info!("Repository cloned successfully to {}", final_destination.display());

    // Step 6: Detect workspace configuration (Story 11.3)
    // Pass config_path parameter to allow custom config file usage
    debug!("Detecting workspace configuration in cloned repository");
    let config_opt = crate::commands::find_and_load_config(&final_destination, config_path).await?;

    // Step 7: Handle based on configuration existence (Story 11.4)
    if let Some(_config) = config_opt {
        info!("Workspace configuration detected");

        // Configuration exists - validate it (unless --skip-validation)
        let validated = if args.skip_validation {
            debug!("Skipping validation (--skip-validation flag)");
            false
        } else {
            debug!("Validating workspace configuration");
            output.info("Validating workspace configuration...")?;

            let validation = validate_workspace(&final_destination).await?;

            if !validation.is_valid {
                // Validation failed - report errors
                return Err(CliError::validation(format!(
                    "Workspace configuration validation failed:\n\n{validation}"
                )));
            }

            info!("Workspace configuration validated successfully");

            // Output validation success details
            output.success("Workspace configuration is valid")?;

            if let Some(strategy) = &validation.strategy {
                let strategy_str = match strategy {
                    VersioningStrategy::Independent => "independent",
                    VersioningStrategy::Unified => "unified",
                };
                output.info(&format!("  Strategy: {strategy_str}"))?;
            }

            output.blank_line()?;
            output.info("  All validation checks passed:")?;
            for check in &validation.checks {
                if check.passed {
                    output.info(&format!("    ✓ {}", check.name))?;
                }
            }
            output.blank_line()?;

            true
        };

        // Output clone completion (without init)
        output_clone_complete_internal(&final_destination, validated, output)?;
    } else {
        info!("No workspace configuration found, initializing workspace");

        // No configuration - run init automatically
        output.info("No workspace configuration found. Starting initialization...")?;
        output.blank_line()?;

        // Convert CloneArgs to InitArgs with configuration merge
        // Note: No workspace config exists yet, so we only use CLI args + defaults
        let init_args = convert_to_init_args(args, None);

        // Execute init command
        debug!("Executing init to create workspace configuration");

        // For JSON output modes, we need to suppress init's output and only output clone's
        // comprehensive JSON. For Human mode, we let init output and then add clone's message.
        match output.format() {
            OutputFormat::Json | OutputFormat::JsonCompact => {
                // Create a quiet output for init to prevent double JSON output
                use std::io::Cursor;
                let buffer = Cursor::new(Vec::new());
                let init_output = crate::output::Output::new(
                    OutputFormat::Quiet,
                    Box::new(buffer),
                    output.no_color(),
                );

                crate::commands::init::execute_init(
                    &init_args,
                    &init_output,
                    &final_destination,
                    None,
                )
                .await?;
            }
            OutputFormat::Human | OutputFormat::Quiet => {
                // For Human and Quiet modes, let init output normally
                crate::commands::init::execute_init(&init_args, output, &final_destination, None)
                    .await?;
            }
        }

        // Output clone completion (with init)
        output_clone_complete_with_init_internal(&final_destination, output)?;
    }

    Ok(())
}

/// Converts CloneArgs to InitArgs with configuration merge logic.
///
/// Implements the merge priority: CLI args > workspace config > defaults.
///
/// This ensures that:
/// - CLI arguments always take precedence when explicitly provided
/// - Workspace configuration is used when no CLI arg is provided
/// - Sensible defaults are used as final fallback
///
/// # Arguments
///
/// * `args` - Clone command arguments
/// * `workspace_config` - Optional workspace configuration from package.json
///
/// # Returns
///
/// Returns an `InitArgs` structure with merged configuration values.
///
/// # Errors
///
/// Returns an error if the merge results in invalid configuration.
///
/// # Examples
///
/// ```rust,ignore
/// // With CLI args only (no workspace config)
/// let clone_args = CloneArgs {
///     strategy: Some("independent".to_string()),
///     environments: Some(vec!["dev".to_string(), "prod".to_string()]),
///     ..Default::default()
/// };
/// let init_args = convert_to_init_args(&clone_args, None)?;
/// assert_eq!(init_args.strategy, Some("independent".to_string()));
///
/// // With workspace config fallback
/// let workspace_config = PackageToolsConfig::default();
/// let init_args = convert_to_init_args(&clone_args, Some(&workspace_config))?;
/// ```
pub(crate) fn convert_to_init_args(
    args: &CloneArgs,
    workspace_config: Option<&PackageToolsConfig>,
) -> InitArgs {
    // Merge changeset_path: CLI > workspace > default
    let changeset_path = if let Some(ref path) = args.changeset_path {
        PathBuf::from(path)
    } else if let Some(config) = workspace_config {
        PathBuf::from(&config.changeset.path)
    } else {
        PathBuf::from(".changesets")
    };

    // Merge environments: CLI > workspace > default
    let environments = if args.environments.is_some() {
        args.environments.clone()
    } else {
        workspace_config.map(|config| config.changeset.available_environments.clone())
    };

    // Merge default_env: CLI > workspace > default
    let default_env = if args.default_env.is_some() {
        args.default_env.clone()
    } else {
        workspace_config.map(|config| config.changeset.default_environments.clone())
    };

    // Merge strategy: CLI > workspace > default
    let strategy = if args.strategy.is_some() {
        args.strategy.clone()
    } else {
        workspace_config.map(|config| match config.version.strategy {
            sublime_pkg_tools::types::VersioningStrategy::Independent => "independent".to_string(),
            sublime_pkg_tools::types::VersioningStrategy::Unified => "unified".to_string(),
        })
    };

    // Merge registry: CLI > workspace > default
    let registry = if let Some(ref reg) = args.registry {
        reg.clone()
    } else if let Some(config) = workspace_config {
        config.upgrade.registry.default_registry.clone()
    } else {
        "https://registry.npmjs.org".to_string()
    };

    // Merge config_format: CLI > workspace > default
    let config_format = if args.config_format.is_some() {
        args.config_format.clone()
    } else {
        None // Will use init's default prompts
    };

    InitArgs {
        changeset_path,
        environments,
        default_env,
        strategy,
        registry,
        config_format,
        force: false, // Never force during clone
        non_interactive: args.non_interactive,
    }
}

/// Outputs clone completion message (without init) using Output methods.
///
/// # Arguments
///
/// * `destination` - Destination directory path
/// * `validated` - Whether workspace configuration was validated
/// * `output` - Output handler for consistent formatting
///
/// # Errors
///
/// Returns an error if output writing fails.
///
/// # Examples
///
/// ```rust,ignore
/// use sublime_cli_tools::output::{Output, OutputFormat};
/// use std::io;
///
/// let output = Output::new(OutputFormat::Human, io::stdout(), false);
/// output_clone_complete_internal(Path::new("./repo"), true, &output)?;
/// ```
fn output_clone_complete_internal(
    destination: &Path,
    validated: bool,
    output: &crate::output::Output,
) -> Result<()> {
    match output.format() {
        OutputFormat::Human => {
            output.blank_line()?;
            output.success("Clone completed successfully!")?;
            output.blank_line()?;
            output.info(&format!("  Location: {}", destination.display()))?;
            output.blank_line()?;
            output.info("Next steps:")?;
            output.info(&format!("  cd {}", destination.display()))?;
            output.info("  workspace changeset add    # Create a changeset")?;
            output.info("  workspace bump --dry-run   # Preview version bump")?;
            output.blank_line()?;
            Ok(())
        }
        OutputFormat::Json | OutputFormat::JsonCompact => {
            #[derive(serde::Serialize)]
            #[allow(non_snake_case)]
            struct CloneResponse {
                success: bool,
                destination: String,
                outcome: CloneOutcome,
            }

            #[derive(serde::Serialize)]
            #[allow(non_snake_case)]
            enum CloneOutcome {
                ExistingConfigValidated,
                ExistingConfigUnvalidated,
            }

            let response = CloneResponse {
                success: true,
                destination: destination.display().to_string(),
                outcome: if validated {
                    CloneOutcome::ExistingConfigValidated
                } else {
                    CloneOutcome::ExistingConfigUnvalidated
                },
            };

            let json_response = crate::output::JsonResponse::success(response);
            output.json(&json_response)?;
            Ok(())
        }
        OutputFormat::Quiet => {
            output.plain(&format!("Clone completed: {}", destination.display()))?;
            Ok(())
        }
    }
}

/// Outputs clone completion message (with init) using Output methods.
///
/// # Arguments
///
/// * `destination` - Destination directory path
/// * `output` - Output handler for consistent formatting
///
/// # Errors
///
/// Returns an error if output writing fails.
///
/// # Examples
///
/// ```rust,ignore
/// use sublime_cli_tools::output::{Output, OutputFormat};
/// use std::io;
///
/// let output = Output::new(OutputFormat::Human, io::stdout(), false);
/// output_clone_complete_with_init_internal(Path::new("./repo"), &output)?;
/// ```
fn output_clone_complete_with_init_internal(
    destination: &Path,
    output: &crate::output::Output,
) -> Result<()> {
    match output.format() {
        OutputFormat::Human => {
            output.blank_line()?;
            output.success("Clone and initialization completed successfully!")?;
            output.blank_line()?;
            output.info(&format!("  Location: {}", destination.display()))?;
            output.blank_line()?;
            output.info("Next steps:")?;
            output.info(&format!("  cd {}", destination.display()))?;
            output.info("  workspace changeset add    # Create your first changeset")?;
            output.info("  workspace bump --dry-run   # Preview version bump")?;
            output.blank_line()?;
            Ok(())
        }
        OutputFormat::Json | OutputFormat::JsonCompact => {
            #[derive(serde::Serialize)]
            #[allow(non_snake_case)]
            struct CloneResponse {
                success: bool,
                destination: String,
                outcome: CloneOutcome,
            }

            #[derive(serde::Serialize)]
            #[allow(non_snake_case)]
            enum CloneOutcome {
                NewWorkspaceInitialized,
            }

            let response = CloneResponse {
                success: true,
                destination: destination.display().to_string(),
                outcome: CloneOutcome::NewWorkspaceInitialized,
            };

            let json_response = crate::output::JsonResponse::success(response);
            output.json(&json_response)?;
            Ok(())
        }
        OutputFormat::Quiet => {
            output.plain(&format!("Clone and init completed: {}", destination.display()))?;
            Ok(())
        }
    }
}