zoi_cli/

utils.rs

//! Utility functions for the Zoi CLI.

use std::fmt::Display;
use std::fs;
use std::io::{Write, stdin, stdout};
use std::path::Path;
use std::process::Command;
use std::str::FromStr;

use anyhow::anyhow;
use colored::Colorize;
use crossterm::tty::IsTty;

use crate::pkg::types::Scope;

/// Prints information with a key and value.
pub fn print_info<T: Display>(key: &str, value: T) {
    println!("{key}: {value}");
}

/// Formats a version summary with branch, status, and number.
///
/// The fields come from the `BRANCH`, `STATUS`, and `NUMBER` constants in
/// `cli.rs`, so they are ZFVM identifiers rather than long-form names. Parsing
/// through the `zfvm` crate validates them and yields the canonical spelling,
/// which means a bad `bump.sh` run shows up as a visible fallback rather than
/// a silently mangled label.
pub fn format_version_summary(
    branch: &str,
    status: &str,
    number: &str
) -> String {
    let branch_display = match zfvm::Branch::from_str(branch) {
        Ok(parsed) => parsed.as_str(),
        // Long-form names are tolerated so an un-bumped build still renders
        // something readable.
        Err(_) => match branch {
            "Production" => "Prod",
            "Development" => "Dev",
            "Special" => "Spec",
            "Public" => "Pub",
            other => other
        }
    };

    format!(
        "{} {} {}",
        format!("{branch_display}.").blue().bold().italic(),
        status,
        number,
    )
}

/// Formats a full version string including the commit hash.
///
/// This renders the ZFVM Canonical Form followed by the commit, which stands
/// in for the `[Build]` component.
pub fn format_version_full(
    branch: &str,
    status: &str,
    number: &str,
    commit: &str
) -> String {
    format!(
        "{} {}",
        format_version_summary(branch, status, number),
        commit.green()
    )
}

/// Prints information aligned with a fixed width for the key.
pub fn print_aligned_info(key: &str, value: &str) {
    let key_with_colon = format!("{key}:");
    println!("{:<18}{}", key_with_colon.cyan(), value);
}

/// Prints a warning if the package is from a non-standard repository.
pub fn print_repo_warning(repo_name: &str) {
    if crate::pkg::utils::is_mini_mode() {
        if let Ok(index) = crate::pkg::mini_resolve::fetch_registry_index()
            && let Some(pkg_info) =
                index.packages.values().find(|p| p.repo == repo_name)
        {
            let warning_message = match pkg_info.repo_type.as_str() {
                "unofficial" => Some(
                    "This package is from an unofficial repository and is not \
                     trusted."
                ),
                "community" => Some(
                    "This package is from a community repository. Use with \
                     caution."
                ),
                "test" => Some(
                    "This package is from a testing repository and may not \
                     function correctly."
                ),
                "archive" => Some(
                    "This package is from an archive repository and is no \
                     longer maintained."
                ),
                _ => None
            };

            if let Some(message) = warning_message {
                println!("\n{}: {}", "NOTE".yellow().bold(), message.yellow());
            }
        }
        return;
    }

    if let Ok(db_path) = crate::pkg::resolve::get_db_root()
        && let Ok(repo_config) = crate::pkg::config::read_repo_config(&db_path)
    {
        let major_repo = repo_name.split('/').next().unwrap_or_default();
        if let Some(repo_entry) =
            repo_config.repos.iter().find(|r| r.name == major_repo)
        {
            let warning_message = match repo_entry.repo_type.as_str() {
                "unofficial" => Some(
                    "This package is from an unofficial repository and is not \
                     trusted."
                ),
                "community" => Some(
                    "This package is from a community repository. Use with \
                     caution."
                ),
                "test" => Some(
                    "This package is from a testing repository and may not \
                     function correctly."
                ),
                "archive" => Some(
                    "This package is from an archive repository and is no \
                     longer maintained."
                ),
                _ => None
            };

            if let Some(message) = warning_message {
                println!("\n{}: {}", "NOTE".yellow().bold(), message.yellow());
            }
        }
    }
}

/// Gets all packages for shell completion.
pub fn get_all_packages_for_completion() -> Vec<PackageCompletion> {
    let mut completions = Vec::new();
    let Ok(config) = crate::pkg::config::read_config() else {
        return completions;
    };

    let mut registries = Vec::new();
    if let Some(default) = &config.default_registry {
        registries.push(default.handle.clone());
    }
    for reg in &config.added_registries {
        registries.push(reg.handle.clone());
    }

    let default_handle = config.default_registry.as_ref().map(|r| &r.handle);

    for handle in registries {
        if handle.is_empty() {
            continue;
        }
        if let Ok(entries) =
            crate::pkg::db::get_packages_for_completion(&handle)
        {
            let is_default = default_handle == Some(&handle);
            for entry in entries {
                let base_name = if is_default {
                    format!("@{}/{}", entry.repo, entry.name)
                } else {
                    format!("#{}@{}/{}", handle, entry.repo, entry.name)
                };

                let display = if let Some(sub) = entry.sub_package {
                    format!("{base_name}:{sub}")
                } else {
                    base_name
                };

                completions.push(PackageCompletion {
                    display,
                    repo: entry.repo,
                    description: entry.description
                });
            }
        }
    }

    completions.sort_by(|a, b| a.display.cmp(&b.display));
    completions
}

/// Represents a package completion entry.
pub struct PackageCompletion {
    /// The display name for the completion.
    pub display: String,
    /// The repository name.
    pub repo: String,
    /// The package description.
    pub description: String
}

/// Creates a symlink to a file, replacing any existing file or symlink.
///
/// # Errors
///
/// Returns an error if:
/// - The existing file or symlink cannot be removed.
/// - The symlink, hard link, or file copy fails.
pub fn symlink_file(target: &Path, link: &Path) -> std::io::Result<()> {
    if link.exists() || link.is_symlink() {
        fs::remove_file(link)?;
    }

    #[cfg(unix)]
    {
        std::os::unix::fs::symlink(target, link)
    }
    #[cfg(windows)]
    {
        if std::os::windows::fs::symlink_file(target, link).is_err() {
            if fs::hard_link(target, link).is_err() {
                fs::copy(target, link)?;
            }
        }
        Ok(())
    }
}

/// Checks if the current process has administrative or root privileges.
pub fn is_admin() -> bool {
    #[cfg(windows)]
    {
        use std::{mem, ptr};

        use winapi::um::handleapi::CloseHandle;
        use winapi::um::processthreadsapi::{
            GetCurrentProcess, OpenProcessToken
        };
        use winapi::um::securitybaseapi::CheckTokenMembership;
        use winapi::um::winnt::{PSID, TOKEN_QUERY};

        let mut token = ptr::null_mut();
        let process = unsafe { GetCurrentProcess() };
        if unsafe { OpenProcessToken(process, TOKEN_QUERY, &mut token) } == 0 {
            return false;
        }

        let mut sid: [u8; 8] = [0; 8];
        let mut sid_size = mem::size_of_val(&sid) as u32;
        if unsafe {
            winapi::um::securitybaseapi::CreateWellKnownSid(
                winapi::um::winnt::WinBuiltinAdministratorsSid,
                ptr::null_mut(),
                sid.as_mut_ptr() as PSID,
                &mut sid_size
            )
        } == 0
        {
            unsafe { CloseHandle(token) };
            return false;
        }

        let mut is_member = 0;
        let result = unsafe {
            CheckTokenMembership(
                token,
                sid.as_mut_ptr() as PSID,
                &mut is_member
            )
        };
        unsafe { CloseHandle(token) };

        result != 0 && is_member != 0
    }
    #[cfg(unix)]
    {
        nix::unistd::getuid().is_root()
    }
}

/// Checks the license of a package and prints warnings if it's not OSI-approved
/// or has issues.
pub fn check_license(license: &str) {
    if license.is_empty() {
        println!(
            "{} Package does not have a license specified.",
            "Warning:".yellow()
        );
        return;
    }

    if license.eq_ignore_ascii_case("None") {
        println!(
            "{} Package does not provide a license.",
            "Warning:".yellow()
        );
        return;
    }

    if license.eq_ignore_ascii_case("Proprietary") {
        println!(
            "{} Package is using a proprietary license.",
            "Warning:".red()
        );
        return;
    }

    if license.eq_ignore_ascii_case("Unknown") {
        println!("{} Package license is unknown.", "Warning:".red());
        return;
    }

    if is_external_license_link(license) {
        println!(
            "{} The license is available at: {}",
            "Warning:".yellow(),
            license.cyan().bold()
        );
        return;
    }

    match spdx::Expression::parse(license) {
        Ok(expr) => {
            if !expr.evaluate(|req| match req.license {
                spdx::LicenseItem::Spdx { id, .. } => id.is_osi_approved(),
                spdx::LicenseItem::Other { .. } => false
            }) {
                println!(
                    "{} License expression '{}' does not evaluate to an OSI \
                     approved license.",
                    "Warning:".yellow(),
                    license.yellow().bold()
                );
            }
        }
        Err(_) => {
            println!(
                "{} Could not parse license expression '{}'. It may not be a \
                 valid SPDX identifier.",
                "Warning:".yellow(),
                license.yellow().bold()
            );
        }
    }
}

/// Returns `true` if the license value is an external link (a URL) pointing to
/// the license text hosted elsewhere instead of an SPDX identifier.
fn is_external_license_link(license: &str) -> bool {
    let trimmed = license.trim();
    trimmed.starts_with("http://") || trimmed.starts_with("https://")
}

/// Asks the user for confirmation with a prompt.
pub fn ask_for_confirmation(prompt: &str, yes: bool) -> bool {
    if yes {
        return true;
    }

    if std::env::var("ZOI_TEST").is_ok() || !stdin().is_tty() {
        return false;
    }

    print!("{prompt} [y/N]: ");
    let _ = stdout().flush();
    let mut input = String::new();
    if stdin().read_line(&mut input).is_err() {
        return false;
    }
    input.trim().eq_ignore_ascii_case("y")
}

/// Escapes a string for use inside an Elvish double-quoted string literal.
///
/// Backslashes are escaped first so that escaping the double quotes
/// afterwards cannot produce double-escaped sequences.
#[cfg(any(unix, test))]
fn elvish_quote(value: &str) -> String {
    value.replace('\\', "\\\\").replace('"', "\\\"")
}

/// Sets up the PATH environment variable for the given scope.
///
/// # Errors
///
/// Returns an error if:
/// - The home directory cannot be found for the user scope.
/// - The directory for binaries cannot be created.
/// - The shell configuration file cannot be read, created, or written to.
/// - On Windows, the registry key for environment variables cannot be opened or
///   modified.
/// - Administrator privileges are missing for system scope on Windows.
pub fn setup_path(scope: Scope) -> anyhow::Result<()> {
    if scope == Scope::Project {
        return Ok(());
    }

    let zoi_bin_dir = match scope {
        Scope::User => crate::pkg::utils::get_user_bin_dir()?,
        Scope::System => crate::pkg::utils::get_system_bin_dir(),
        Scope::Project => return Ok(())
    };

    if !zoi_bin_dir.exists() {
        fs::create_dir_all(&zoi_bin_dir)?;
    }

    if scope == Scope::System && cfg!(unix) {
        println!(
            "{}",
            "System-wide installation complete. Binaries are in the system \
             PATH."
                .green()
        );
        return Ok(());
    }

    #[cfg(unix)]
    {
        use std::fs::{File, OpenOptions};
        let home = crate::pkg::utils::get_user_home()
            .ok_or_else(|| anyhow!("Could not find home directory."))?;
        let zoi_bin_str = zoi_bin_dir.to_string_lossy();

        let shell_name = std::env::var("SHELL").unwrap_or_default();
        let (profile_file_path, cmd_to_write) = if shell_name.contains("bash") {
            let path = if cfg!(target_os = "macos") {
                home.join(".bash_profile")
            } else {
                home.join(".bashrc")
            };
            let cmd = format!(
                "\n# Added by Zoi\nexport PATH=\"{}:{}\"\n",
                zoi_bin_str, "$PATH"
            );
            (path, cmd)
        } else if shell_name.contains("zsh") {
            let path = home.join(".zshrc");
            let cmd = format!(
                "\n# Added by Zoi\nexport PATH=\"{}:{}\"\n",
                zoi_bin_str, "$PATH"
            );
            (path, cmd)
        } else if shell_name.contains("fish") {
            let path = home.join(".config/fish/config.fish");
            let cmd =
                format!("\n# Added by Zoi\nfish_add_path \"{zoi_bin_str}\"\n");
            (path, cmd)
        } else if shell_name.contains("elvish") {
            let path = home.join(".config/elvish/rc.elv");
            // Escape the path so it parses as one literal string value even
            // when it contains whitespace, quotes, or backslashes.
            let cmd = format!(
                "\n# Added by Zoi\nset paths = [ \"{}\" $paths... ]\n",
                elvish_quote(&zoi_bin_str)
            );
            (path, cmd)
        } else if shell_name.contains("csh") || shell_name.contains("tcsh") {
            let path = home.join(".cshrc");
            let cmd = format!(
                "\n# Added by Zoi\nsetenv PATH=\"{}:{}\"\n",
                zoi_bin_str, "$PATH"
            );
            (path, cmd)
        } else {
            let path = home.join(".profile");
            let cmd = format!(
                "\n# Added by Zoi\nexport PATH=\"{}:{}\"\n",
                zoi_bin_str, "$PATH"
            );
            (path, cmd)
        };

        if !profile_file_path.exists() {
            if let Some(parent) = profile_file_path.parent() {
                fs::create_dir_all(parent)?;
            }
            File::create(&profile_file_path)?;
        }

        let content =
            crate::pkg::utils::read_file_within(&home, &profile_file_path)?;
        if content.contains(zoi_bin_str.as_ref()) {
            println!("Zoi bin directory is already in your shell's config.");
            return Ok(());
        }

        let mut file =
            OpenOptions::new().append(true).open(&profile_file_path)?;

        file.write_all(cmd_to_write.as_bytes())?;

        println!(
            "{} Zoi bin directory has been added to your PATH in '{}'.",
            "Success:".green(),
            profile_file_path.display()
        );
        println!(
            "Please restart your shell or run `source {}` for the changes to \
             take effect.",
            profile_file_path.display()
        );
    }

    #[cfg(windows)]
    {
        use winreg::RegKey;
        use winreg::enums::*;

        let zoi_bin_path_str = zoi_bin_dir
            .to_str()
            .ok_or_else(|| anyhow!("Invalid path string"))?;

        let (root, subkey, scope_name) = if scope == Scope::System {
            if !is_admin() {
                return Err(anyhow!(
                    "Administrator privileges required to modify system PATH."
                ));
            }
            (
                HKEY_LOCAL_MACHINE,
                "System\\CurrentControlSet\\Control\\Session \
                 Manager\\Environment",
                "system"
            )
        } else {
            (HKEY_CURRENT_USER, "Environment", "user")
        };

        let key = RegKey::predef(root);
        let env = key.open_subkey_with_flags(subkey, KEY_READ | KEY_WRITE)?;
        let current_path: String = env.get_value("Path")?;

        if current_path
            .split(';')
            .any(|p| p.eq_ignore_ascii_case(zoi_bin_path_str))
        {
            println!("Zoi bin directory is already in your PATH.");
            return Ok(());
        }

        let new_path = if current_path.is_empty() {
            zoi_bin_path_str.to_string()
        } else {
            format!("{};{}", current_path, zoi_bin_path_str)
        };
        env.set_value("Path", &new_path)?;

        println!(
            "{} Zoi bin directory has been added to your {} PATH environment \
             variable.",
            "Success:".green(),
            scope_name
        );
        println!(
            "Please restart your shell or log out and log back in for the \
             changes to take effect."
        );
    }

    Ok(())
}

/// Checks if the Zoi bin directory is in the current PATH and prints a warning
/// if not.
pub fn check_path() {
    let Ok(zoi_bin_dir) = crate::pkg::utils::get_user_bin_dir() else {
        return;
    };
    if !zoi_bin_dir.exists() {
        return;
    }

    let command_output = if cfg!(target_os = "windows") {
        Command::new("pwsh")
            .arg("-Command")
            .arg("echo $env:Path")
            .output()
    } else {
        Command::new("bash").arg("-c").arg("echo $PATH").output()
    };

    let is_in_path = match command_output {
        Ok(output) => {
            if output.status.success() {
                let path_var = String::from_utf8_lossy(&output.stdout);
                std::env::split_paths(path_var.as_ref())
                    .any(|path| path == zoi_bin_dir)
            } else {
                false
            }
        }
        Err(_) => false
    };

    if !is_in_path {
        eprintln!(
            "Please run 'zoi shell <shell>' or add it to your PATH manually \
             for commands to be available."
        );
    }
}