run_stack/

commands.rs

//! `rst commands` — every CLI entry in a terminal table.

use anyhow::Result;

/// One row in the command catalogue.
struct Entry {
    command: &'static str,
    aliases: &'static str,
    group: &'static str,
    description: &'static str,
}

const CATALOG: &[Entry] = &[
    Entry {
        command: "create",
        aliases: "new",
        group: "Global",
        description: "Write .run/run.config.toml and run init",
    },
    Entry {
        command: "migrate",
        aliases: "—",
        group: "Global",
        description: "Convert legacy run/ to .run/ (config + env)",
    },
    Entry {
        command: "upgrade",
        aliases: "update",
        group: "Global",
        description: "Refresh legacy run/ or self-update",
    },
    Entry {
        command: "self-update",
        aliases: "—",
        group: "Global",
        description: "Install latest from crates.io and migrate configs",
    },
    Entry {
        command: "completion",
        aliases: "—",
        group: "Global",
        description: "Shell / Kiro autocompletion (bash|zsh|fig|install|services)",
    },
    Entry {
        command: "init",
        aliases: "—",
        group: "Setup",
        description: "Write .run/run.config.toml and .run/.env",
    },
    Entry {
        command: "init --update",
        aliases: "—",
        group: "Setup",
        description: "Find and add apps added to the workspace since setup",
    },
    Entry {
        command: "up",
        aliases: "run",
        group: "Lifecycle",
        description: "Build if needed and start (--essential = config essentials)",
    },
    Entry {
        command: "down",
        aliases: "—",
        group: "Lifecycle",
        description: "Stop everything, or named services (keeps data)",
    },
    Entry {
        command: "restart",
        aliases: "—",
        group: "Lifecycle",
        description: "Stop then start (down + up); --build, --essential",
    },
    Entry {
        command: "rebuild",
        aliases: "—",
        group: "Lifecycle",
        description: "Rebuild images from scratch and recreate containers",
    },
    Entry {
        command: "clean",
        aliases: "—",
        group: "Lifecycle",
        description: "Stop and DELETE all volumes",
    },
    Entry {
        command: "commands",
        aliases: "—",
        group: "Inspection",
        description: "List every CLI command in a table",
    },
    Entry {
        command: "apps",
        aliases: "list",
        group: "Inspection",
        description: "List configured apps (backend, web, mobile, …)",
    },
    Entry {
        command: "services",
        aliases: "—",
        group: "Inspection",
        description: "List compose services (and status when Docker is up)",
    },
    Entry {
        command: "ps",
        aliases: "status",
        group: "Inspection",
        description: "Service status",
    },
    Entry {
        command: "ports",
        aliases: "—",
        group: "Inspection",
        description: "Host ports + env URLs table",
    },
    Entry {
        command: "logs",
        aliases: "—",
        group: "Inspection",
        description: "Follow logs",
    },
    Entry {
        command: "shell",
        aliases: "sh",
        group: "Inspection",
        description: "Shell into a container (default: backend)",
    },
    Entry {
        command: "config",
        aliases: "—",
        group: "Inspection",
        description: "Print the resolved configuration",
    },
    Entry {
        command: "doctor",
        aliases: "—",
        group: "Inspection",
        description: "Report workspace faults; --fix repairs the clear ones",
    },
    Entry {
        command: "explain",
        aliases: "—",
        group: "Inspection",
        description: "Print the docker compose command, run nothing",
    },
    Entry {
        command: "env",
        aliases: "—",
        group: "Inspection",
        description: "Print the environment compose is given",
    },
    Entry {
        command: "generate",
        aliases: "—",
        group: "Inspection",
        description: "Write the compose overlays, start nothing",
    },
    Entry {
        command: "backend",
        aliases: "—",
        group: "Backend",
        description: "Run any command inside the backend container",
    },
    Entry {
        command: "migrate",
        aliases: "—",
        group: "Backend",
        description: "Run pending migrations",
    },
    Entry {
        command: "seed",
        aliases: "—",
        group: "Backend",
        description: "Run database seeders",
    },
    Entry {
        command: "fresh",
        aliases: "—",
        group: "Backend",
        description: "Rebuild the schema and seed it (destroys data)",
    },
    Entry {
        command: "artisan",
        aliases: "—",
        group: "Backend",
        description: "php artisan … (BACKEND_STACK=laravel)",
    },
    Entry {
        command: "composer",
        aliases: "—",
        group: "Backend",
        description: "composer … (BACKEND_STACK=laravel)",
    },
    Entry {
        command: "pnpm",
        aliases: "—",
        group: "Frontend",
        description: "pnpm … inside the frontend workspace",
    },
    Entry {
        command: "ios",
        aliases: "—",
        group: "Mobile",
        description: "Open mobile-client in the iOS Simulator",
    },
    Entry {
        command: "android",
        aliases: "—",
        group: "Mobile",
        description: "Open mobile-client on an Android emulator",
    },
    Entry {
        command: "device",
        aliases: "—",
        group: "Mobile",
        description: "Open on a USB phone, or print the Expo Go URL",
    },
    Entry {
        command: "mobile",
        aliases: "—",
        group: "Mobile",
        description: "Restart mobile-deps / mobile-packages / Metro",
    },
    Entry {
        command: "reload",
        aliases: "—",
        group: "Mobile",
        description: "Metro /status + /reload; --clear wipes caches",
    },
    Entry {
        command: "prebuild",
        aliases: "—",
        group: "Mobile",
        description: "expo prebuild (Expo apps only)",
    },
    Entry {
        command: "sync-mobile-port",
        aliases: "—",
        group: "Mobile",
        description: "Sync MOBILE_CLIENT_PORT into the mobile app configs",
    },
    Entry {
        command: "bundler",
        aliases: "configure-bundler",
        group: "Mobile",
        description: "Point the simulator at Metro",
    },
    Entry {
        command: "desktop",
        aliases: "—",
        group: "Desktop",
        description: "Launch the Electron / Tauri shell on the host",
    },
    Entry {
        command: "deploy",
        aliases: "—",
        group: "Deploy",
        description: "Deploy web, mobile or desktop",
    },
    Entry {
        command: "dash",
        aliases: "dashboard",
        group: "Dashboard",
        description: "Open the status dashboard in a browser",
    },
];

pub fn run(raw: bool) -> Result<i32> {
    if raw {
        let mut seen = std::collections::BTreeSet::new();
        for entry in CATALOG {
            if seen.insert(entry.command) {
                println!("{}", entry.command);
            }
        }
        return Ok(0);
    }
    print_table();
    Ok(0)
}

fn print_table() {
    print!("{}", render());
}

/// The catalogue as a bordered table.
///
/// Column widths count characters, not bytes: the em dash used for "no alias"
/// is three bytes and one column, and Rust pads by characters — measuring in
/// bytes would push every border after it out of line.
fn render() -> String {
    let cmd_w = width(CATALOG.iter().map(|e| e.command), "COMMAND");
    let alias_w = width(CATALOG.iter().map(|e| e.aliases), "ALIASES");
    let group_w = width(CATALOG.iter().map(|e| e.group), "GROUP");
    let desc_w = width(CATALOG.iter().map(|e| e.description), "DESCRIPTION");
    let widths = [cmd_w, alias_w, group_w, desc_w];

    let mut out = String::from("Commands\n");
    out.push_str(&rule('┌', '┬', '┐', &widths));
    out.push_str(&row("COMMAND", "ALIASES", "GROUP", "DESCRIPTION", &widths));
    out.push_str(&rule('├', '┼', '┤', &widths));
    for entry in CATALOG {
        out.push_str(&row(
            entry.command,
            entry.aliases,
            entry.group,
            entry.description,
            &widths,
        ));
    }
    out.push_str(&rule('└', '┴', '┘', &widths));
    out
}

fn rule(left: char, join: char, right: char, widths: &[usize; 4]) -> String {
    let segments: Vec<String> = widths.iter().map(|w| "─".repeat(w + 2)).collect();
    format!("{left}{}{right}\n", segments.join(&join.to_string()))
}

fn row(command: &str, aliases: &str, group: &str, description: &str, widths: &[usize; 4]) -> String {
    let [cmd_w, alias_w, group_w, desc_w] = *widths;
    format!(
        "│ {command:<cmd_w$} │ {aliases:<alias_w$} │ {group:<group_w$} │ {description:<desc_w$} │\n"
    )
}

fn width<'a>(values: impl Iterator<Item = &'a str>, header: &str) -> usize {
    values
        .map(|value| value.chars().count())
        .chain(std::iter::once(header.chars().count()))
        .max()
        .unwrap_or_else(|| header.chars().count())
}

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

    #[test]
    fn doctor_is_in_the_catalogue() {
        assert!(CATALOG.iter().any(|entry| entry.command == "doctor"));
    }

    #[test]
    fn every_row_is_bordered_and_the_same_width() {
        let table = render();
        let lines: Vec<&str> = table.lines().skip(1).collect();

        let expected = lines[0].chars().count();
        for line in &lines {
            assert_eq!(
                line.chars().count(),
                expected,
                "ragged border on line: {line}"
            );
        }
        assert!(lines.first().unwrap().starts_with('┌'));
        assert!(lines.last().unwrap().starts_with('└'));
    }

    #[test]
    fn an_em_dash_alias_does_not_skew_the_border() {
        // Measured in bytes the em dash counts three, and every border after it
        // would shift left by two.
        assert!(CATALOG.iter().any(|entry| entry.aliases == "—"));
        let rows: Vec<usize> = render()
            .lines()
            .filter(|line| line.starts_with('│'))
            .map(|line| line.chars().count())
            .collect();

        assert!(rows.windows(2).all(|pair| pair[0] == pair[1]));
    }

    #[test]
    fn raw_mode_lists_plain_names() {
        // `rst commands --raw` feeds shell completion, so it must stay unadorned.
        assert!(!CATALOG.is_empty());
        assert!(CATALOG.iter().all(|entry| !entry.command.contains('│')));
    }
}