run_stack/

cli.rs

//! run-stack: one command to boot a full local stack in Docker.
//!
//! A port of the shell version in ../run. Commands that are not ported yet say
//! so and name the one to use instead, rather than failing as unknown.

use anyhow::Result;
use clap::{Parser, Subcommand};

use crate::compose::Compose;
use crate::generate;
use crate::env::Env;
use crate::workspace::Workspace;

#[derive(Parser)]
#[command(
    name = "run-stack",
    // Anything not defined below is handed to the shell implementation, so the
    // port never takes a command away.
    allow_external_subcommands = true,
    // Says which implementation answered: both are called rst, and which one
    // wins depends on PATH order.
    version = concat!(env!("CARGO_PKG_VERSION"), " (rust)"),
    about = "Dockerised local stacks: API, web apps, mobile, database, dashboard"
)]
struct Cli {
    #[command(subcommand)]
    command: Option<Command>,
}

#[derive(Subcommand)]
enum Command {
    /// Build if needed and start the stack
    #[command(visible_alias = "run")]
    Up {
        /// Only these services
        services: Vec<String>,
        /// Rebuild images first
        #[arg(long)]
        build: bool,
        /// Only services enabled under config `[essentials]`
        #[arg(long)]
        essential: bool,
        /// Create the containers but leave them stopped, to be started elsewhere
        #[arg(long)]
        no_start: bool,
    },
    /// Stop everything, keep data
    Down { services: Vec<String> },
    /// Service status
    #[command(visible_alias = "status")]
    Ps { services: Vec<String> },
    /// Follow logs
    Logs { services: Vec<String> },
    /// Stop then start
    Restart {
        services: Vec<String>,
        #[arg(long)]
        build: bool,
        /// Only services enabled under config `[essentials]`
        #[arg(long)]
        essential: bool,
    },
    /// Open a shell in a container
    #[command(visible_alias = "sh")]
    Shell {
        #[arg(default_value = "backend")]
        service: String,
    },
    /// List the apps this workspace runs
    #[command(visible_alias = "list")]
    Apps,
    /// Host ports and the URLs that must match them
    Ports,
    /// Print the resolved configuration
    Config,
    /// Print the docker compose command instead of running it
    Explain { command: Vec<String> },
    /// Print the environment compose is given: one key, or all of it
    Env { key: Option<String> },
    /// What is ported so far, and what is not
    Ported,
    /// List every CLI command in a table
    Commands {
        /// One canonical command name per line
        #[arg(long)]
        raw: bool,
    },
    /// Install the latest run-stack from crates.io and migrate configs
    #[command(visible_alias = "selfupdate")]
    SelfUpdate {
        /// Pass --verbose to cargo
        #[arg(long, short = 'V')]
        verbose: bool,
    },
    /// Anything the shell implementation still owns
    #[command(external_subcommand)]
    Delegated(Vec<String>),
    /// Write the generated compose overlays without starting anything
    Generate,
    /// Register a folder as an app: in the repo's apps/, or beside the repo
    Add {
        /// Folder name
        folder: String,
    },
    /// Stop running a folder as an app, and drop its settings
    Remove {
        /// Folder or app name
        folder: String,
    },
    /// Check the workspace for faults, and repair the ones that are unambiguous
    Doctor {
        /// Apply the repairs instead of only reporting them
        #[arg(long)]
        fix: bool,
        /// With --fix, show what would change without writing anything
        #[arg(long)]
        dry_run: bool,
    },
}

fn run_add(workspace: &Workspace, folder: &str) -> Result<i32> {
    let mut env = Env::load(&workspace.env_path())?;
    env.derive(&workspace.root);

    let found = crate::add::locate(workspace, &env, folder)?;
    let written = crate::add::record(workspace, &found)?;

    // The overlays are what compose actually reads, so write them now rather
    // than leaving the app registered but unrunnable until the next generate.
    regenerate(workspace)?;

    let where_ = match found.placement {
        crate::add::Placement::Workspace => "in the frontend repo's apps/",
        crate::add::Placement::Root => "beside the frontend repo",
    };
    println!("added {} ({where_})", found.name);
    for line in &written {
        println!("  {line}");
    }
    println!("  start it with: rst up {}", found.name);
    Ok(0)
}

fn run_remove(workspace: &Workspace, folder: &str) -> Result<i32> {
    let mut env = Env::load(&workspace.env_path())?;
    env.derive(&workspace.root);

    let Some(declared) = crate::add::find_declared(&env, folder) else {
        anyhow::bail!("{folder} is not listed in EXTRA_APPS or ROOT_APPS");
    };

    let written = crate::add::forget(workspace, &declared)?;
    regenerate(workspace)?;

    println!("removed {}", declared.entry);
    for line in &written {
        println!("  {line}");
    }
    // The container outlives the config that made it, and nothing else here
    // will notice it again.
    println!("  its container is still there: rst down {}", declared.name);
    Ok(0)
}

fn run_doctor(workspace: &Workspace, fix: bool, dry_run: bool) -> Result<i32> {
    println!("run-stack doctor — {}\n", workspace.root.display());

    let checks = crate::doctor::run(workspace)?;
    println!("{}", crate::doctor::format_checks(&checks));

    if !fix {
        let failed = checks
            .iter()
            .any(|check| check.status == crate::doctor::Status::Fail);
        return Ok(if failed { 1 } else { 0 });
    }

    println!();
    let actions = crate::doctor::fix(workspace, dry_run)?;
    println!("{}", crate::doctor::format_actions(&actions, dry_run));

    let failed = actions
        .iter()
        .any(|action| action.outcome == crate::doctor::Repair::Failed);
    Ok(if failed { 1 } else { 0 })
}

#[allow(dead_code)]
const UNUSED_NOT_PORTED: &[(&str, &str)] = &[
    ("init", "the prompts and the app scan"),
    ("create", "workspace setup"),
    ("migrate", "layout conversion"),
    ("clean", "volume deletion"),
    ("rebuild", "image rebuild"),
    ("dash", "dashboard"),
    ("ios", "simulator launch"),
    ("android", "emulator launch"),
    ("device", "device launch"),
    ("mobile", "metro restart"),
    ("reload", "metro reload"),
    ("prebuild", "expo prebuild"),
    ("desktop", "electron / tauri shell"),
    ("deploy", "deploy targets"),
    ("backend", "commands in the API container"),
    ("artisan", "laravel"),
    ("composer", "laravel"),
    ("pnpm", "workspace package manager"),
    ("seed", "database seeders"),
    ("fresh", "schema rebuild"),
    ("services", "compose service table"),
    ("completion", "shell completion"),
];

pub fn main() {
    let code = match run() {
        Ok(code) => code,
        Err(error) => {
            eprintln!("error: {error:#}");
            1
        }
    };
    std::process::exit(code);
}

fn run() -> Result<i32> {
    let cli = Cli::parse();
    let Some(command) = cli.command else {
        print_status();
        return Ok(0);
    };

    if let Command::Ported = command {
        print_status();
        return Ok(0);
    }

    if let Command::Commands { raw } = command {
        return crate::commands::run(raw);
    }

    if let Command::SelfUpdate { verbose } = command {
        return crate::self_update::run(verbose);
    }

    // The shell version needs to know which workspace, but must be allowed to
    // run outside one: `create` makes the workspace in the first place.
    if let Command::Delegated(argv) = &command {
        let (name, rest) = argv.split_first().expect("clap yields a name");
        let workspace = Workspace::find(&std::env::current_dir()?).ok();
        // An app is a command of its own: `rst mobile-driver` starts it, so a
        // workspace with several apps does not need `up` in front of each.
        if let Some(workspace) = workspace
            .as_ref()
            .filter(|_| !crate::delegate::is_pending(name))
        {
            if is_service(workspace, name) {
                let build = rest.iter().any(|arg| arg == "--build");
                return start(workspace, vec![name.clone()], build);
            }
        }
        return crate::delegate::run(name, rest, workspace.as_ref());
    }

    let workspace = Workspace::find(&std::env::current_dir()?)?;

    match command {
        Command::Ported
        | Command::Commands { .. }
        | Command::Delegated(_)
        | Command::SelfUpdate { .. } => unreachable!("handled above"),
        Command::Config => {
            print!("{}", workspace.config()?.to_toml());
            Ok(0)
        }
        Command::Apps => {
            print_apps(&workspace)?;
            Ok(0)
        }
        Command::Ports => {
            let config = workspace.config()?;
            for key in config.keys().filter(|key| key.ends_with("_PORT")) {
                println!("{:<24} {}", key, config.port(key, 0));
            }
            Ok(0)
        }
        Command::Generate => {
            regenerate(&workspace)?;
            println!("wrote the overlays in {}", workspace.run_dir.display());
            Ok(0)
        }
        Command::Add { folder } => run_add(&workspace, &folder),
        Command::Remove { folder } => run_remove(&workspace, &folder),
        Command::Doctor { fix, dry_run } => run_doctor(&workspace, fix, dry_run),
        Command::Env { key } => {
            let mut env = Env::load(&workspace.env_path())?;
            env.derive(&workspace.root);
            match key {
                Some(key) => println!("{}", env.get(&key).unwrap_or("")),
                None => {
                    for (key, value) in env.iter() {
                        println!("{key}={value}");
                    }
                }
            }
            Ok(0)
        }
        Command::Explain { command } => {
            let compose = compose_for(&workspace)?;
            println!("docker {}", compose.args(&command).join(" "));
            Ok(0)
        }
        Command::Up {
            services,
            build,
            essential,
            no_start,
        } => {
            let services = resolve_services(&workspace, services, essential)?;
            if no_start {
                create(&workspace, services, build)
            } else {
                start(&workspace, services, build)
            }
        }
        Command::Down { services } => {
            crate::compose::require_docker()?;
            let mut args = vec!["down".to_string()];
            args.extend(services);
            compose_for(&workspace)?.run(&args)
        }
        Command::Ps { services } => {
            crate::compose::require_docker()?;
            let mut args = vec!["ps".to_string()];
            args.extend(services);
            compose_for(&workspace)?.run(&args)
        }
        Command::Logs { services } => {
            crate::compose::require_docker()?;
            let mut args = vec![
                "logs".to_string(),
                "-f".to_string(),
                "--tail=100".to_string(),
            ];
            args.extend(services);
            compose_for(&workspace)?.run(&args)
        }
        Command::Restart {
            services,
            build,
            essential,
        } => {
            crate::compose::require_docker()?;
            regenerate(&workspace)?;
            let services = resolve_services(&workspace, services, essential)?;
            let compose = compose_for(&workspace)?;
            let mut down = vec!["down".to_string()];
            down.extend(services.clone());
            compose.run(&down)?;
            let mut up = vec!["up".to_string(), "-d".to_string()];
            if build {
                up.push("--build".into());
            }
            up.extend(services);
            compose.run(&up)
        }
        Command::Shell { service } => {
            crate::compose::require_docker()?;
            let compose = compose_for(&workspace)?;
            let bash = vec!["exec".to_string(), service.clone(), "bash".to_string()];
            match compose.run(&bash)? {
                0 => Ok(0),
                // Plenty of images have no bash.
                _ => compose.run(&["exec".to_string(), service, "sh".to_string()]),
            }
        }
    }
}

/// The overlays depend on what the workspace holds right now, so they are
/// written before every start rather than committed.
fn regenerate(workspace: &Workspace) -> Result<()> {
    let mut env = Env::load(&workspace.env_path())?;
    env.derive(&workspace.root);
    generate::all(&workspace.run_dir, &env, &crate::compose::package_dir()?)
}

fn compose_for(workspace: &Workspace) -> Result<Compose> {
    let mut env = Env::load(&workspace.env_path())?;
    env.derive(&workspace.root);
    Compose::new(workspace, env)
}

/// Build what is missing and bring the services up. An empty list is the whole
/// stack, which is the only case that may sweep orphans.
fn start(workspace: &Workspace, services: Vec<String>, build: bool) -> Result<i32> {
    up(workspace, services, build, false)
}

/// Create the containers and leave them stopped, for a stack started from the
/// dashboard or by hand afterwards.
fn create(workspace: &Workspace, services: Vec<String>, build: bool) -> Result<i32> {
    up(workspace, services, build, true)
}

fn up(workspace: &Workspace, services: Vec<String>, build: bool, no_start: bool) -> Result<i32> {
    crate::compose::require_docker()?;
    regenerate(workspace)?;
    compose_for(workspace)?.run(&up_args(services, build, no_start))
}

fn up_args(services: Vec<String>, build: bool, no_start: bool) -> Vec<String> {
    // --no-start and -d contradict each other: one asks compose to leave the
    // containers alone, the other to run them in the background.
    let mode = if no_start { "--no-start" } else { "-d" };
    let mut args = vec!["up".to_string(), mode.to_string()];
    if build {
        args.push("--build".into());
    }
    if services.is_empty() {
        args.push("--remove-orphans".into());
    }
    args.extend(services);
    args
}

#[cfg(test)]
mod tests {
    use super::*;

    fn args(services: &[&str], build: bool, no_start: bool) -> Vec<String> {
        up_args(services.iter().map(|s| (*s).to_string()).collect(), build, no_start)
    }

    #[test]
    fn up_runs_detached_by_default() {
        let built = args(&[], false, false);

        assert!(built.contains(&"-d".to_string()));
        assert!(!built.contains(&"--no-start".to_string()));
    }

    #[test]
    fn no_start_creates_without_running() {
        let built = args(&[], false, true);

        assert!(built.contains(&"--no-start".to_string()));
        // Passing both asks compose to leave the containers alone and to run
        // them at the same time; it rejects the pair.
        assert!(!built.contains(&"-d".to_string()));
    }

    #[test]
    fn named_services_are_kept_and_orphans_left_alone() {
        let built = args(&["web", "backend"], false, true);

        assert!(built.ends_with(&["web".to_string(), "backend".to_string()]));
        assert!(!built.contains(&"--remove-orphans".to_string()));
    }

    #[test]
    fn a_whole_stack_prunes_orphans() {
        assert!(args(&[], false, false).contains(&"--remove-orphans".to_string()));
    }

    #[test]
    fn build_survives_either_mode() {
        assert!(args(&[], true, false).contains(&"--build".to_string()));
        assert!(args(&[], true, true).contains(&"--build".to_string()));
    }
}



/// Whether the workspace defines a compose service by that name. The registry
/// the last `up` wrote answers without docker; docker itself is the fallback
/// for a workspace that has never been started.
fn is_service(workspace: &Workspace, name: &str) -> bool {
    let cached = crate::compose::cached_services(&workspace.root);
    if !cached.is_empty() {
        return cached.iter().any(|service| service == name);
    }
    compose_for(workspace)
        .map(|compose| compose.service_names().iter().any(|service| service == name))
        .unwrap_or(false)
}

fn resolve_services(
    workspace: &Workspace,
    services: Vec<String>,
    essential: bool,
) -> Result<Vec<String>> {
    if !essential {
        return Ok(services);
    }
    if !services.is_empty() {
        anyhow::bail!("pass service names or --essential, not both");
    }
    let listed = workspace.config()?.essential_services();
    if listed.is_empty() {
        anyhow::bail!(
            "no essential services configured — add them under \"[essentials]\" in run.config.toml"
        );
    }
    Ok(listed)
}

fn print_apps(workspace: &Workspace) -> Result<()> {
    let config = workspace.config()?;
    println!("{:<10} {:<24} {:<6}", "ROLE", "PACKAGE", "PORT");
    println!(
        "{:<10} {:<24} {:<6}",
        "backend",
        config.str_or("BACKEND_STACK", "laravel"),
        config.port("BACKEND_PORT", 8000)
    );
    println!(
        "{:<10} {:<24} {:<6}",
        "web",
        config.str_or("WEB_APP", "web"),
        config.port("WEB_PORT", 5173)
    );
    for (flag, app_key, port_key, role, default_port) in [
        ("RUN_ADMIN", "ADMIN_APP", "ADMIN_PORT", "admin", 5174),
        ("RUN_LANDING", "LANDING_APP", "LANDING_PORT", "landing", 5175),
        ("RUN_MOBILE", "MOBILE_APP", "MOBILE_CLIENT_PORT", "mobile", 8081),
        ("RUN_DESKTOP", "DESKTOP_APP", "DESKTOP_PORT", "desktop", 5176),
    ] {
        if config.bool_or(flag, false) {
            println!(
                "{:<10} {:<24} {:<6}",
                role,
                config.str_or(app_key, role),
                config.port(port_key, default_port)
            );
        }
    }
    for app in config.extra_apps() {
        let port_key = format!("{}_PORT", crate::config::key_of(&app));
        println!("{:<10} {:<24} {:<6}", "extra", app, config.port(&port_key, 0));
    }
    Ok(())
}

fn print_status() {
    println!("run-stack {} (rust port in progress)\n", env!("CARGO_PKG_VERSION"));
    println!("Ported:");
    for line in [
        "up [--build] [--essential] [svc...]  start the stack",
        "down [service...]           stop it, keep data",
        "ps / status [service...]    service status",
        "logs [service...]           follow logs",
        "restart [--build] [--essential] [svc...]  down then up",
        "shell / sh [service]        shell into a container",
        "apps / list                 the apps this workspace runs",
        "ports                       host ports",
        "config                      the resolved configuration",
        "explain <compose args>      print the docker command, run nothing",
        "env [KEY]                   the environment compose is given",
        "generate                    write the compose overlays, start nothing",
        "commands [--raw]            every CLI command in a table",
        "self-update [--verbose]     install latest from crates.io, migrate configs",
    ] {
        println!("  {line}");
    }
    println!("\nHanded to the shell implementation, transparently:");
    let mut line = String::from("  ");
    for (name, _) in crate::delegate::PENDING {
        if line.len() + name.len() + 2 > 76 {
            println!("{line}");
            line = String::from("  ");
        }
        line.push_str(name);
        line.push_str(", ");
    }
    println!("{}", line.trim_end_matches(", "));
}