run_stack/

generate.rs

//! The generated compose overlays.
//!
//! Three files are written into .run/ before every up: one shadowing every
//! workspace package's node_modules with a named volume, one adding a service
//! per extra app, and one carrying optional CPU/memory limits. They depend on
//! what the workspace actually contains, so they are regenerated rather than
//! committed.

use std::fs;
use std::path::Path;

use anyhow::{Context, Result};

use crate::config::key_of;
use crate::env::Env;

/// The built-in services that mount the frontend monorepo.
const FRONTEND_SERVICES: &[&str] = &[
    "frontend-deps",
    "frontend-packages",
    "frontend-sync",
    "web",
    "admin",
    "landing",
    "mobile-deps",
    "mobile-packages",
    "mobile-client",
];

const METRO_SERVICES: &[&str] = &["mobile-deps", "mobile-packages", "mobile-client"];

pub fn all(run_dir: &Path, env: &Env, package_dir: &Path) -> Result<()> {
    packages(run_dir, env)?;
    apps(run_dir, env, package_dir)?;
    root_apps_file(run_dir, env)?;
    resources(run_dir, env)?;
    Ok(())
}

/// An app that lives beside the frontend repo rather than inside its apps/.
///
/// `EXTRA_APPS` cannot reach these: those share the frontend bind mount and are
/// started through `pnpm --filter`, and a sibling directory is in neither the
/// mount nor the workspace. Each one gets its own mount and runs its own
/// command verbatim.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RootApp {
    pub name: String,
    pub dir: String,
}

/// `ROOT_APPS="seeder:althaqeel-seeder other"` - `name:dir`, or a bare name
/// when the directory matches it. Paths are relative to the workspace root.
pub fn root_apps(env: &Env) -> Vec<RootApp> {
    env.get_or("ROOT_APPS", "")
        .split_whitespace()
        .filter_map(|entry| {
            let (name, dir) = match entry.split_once(':') {
                Some((name, dir)) if !name.is_empty() && !dir.is_empty() => (name, dir),
                _ => (entry, entry),
            };
            if name.is_empty() {
                return None;
            }
            Some(RootApp {
                name: name.to_string(),
                dir: dir.trim_end_matches('/').to_string(),
            })
        })
        .collect()
}

fn root_app_port(env: &Env, app: &RootApp, index: usize) -> u16 {
    let key = format!("{}_PORT", key_of(&app.name));
    env.get(&key)
        .and_then(|value| value.trim().parse().ok())
        .unwrap_or(4500 + index as u16)
}

fn root_apps_file(run_dir: &Path, env: &Env) -> Result<()> {
    let apps = root_apps(env);
    let target = run_dir.join("docker-compose.root-apps.yml");
    if apps.is_empty() {
        let _ = fs::remove_file(&target);
        return Ok(());
    }
    // .run/ sits in the workspace root, and the mount has to be absolute:
    // compose resolves a relative path against its own project directory,
    // which is the unpacked package, not this workspace.
    let root = run_dir.parent().unwrap_or(run_dir);
    write(target, &render_root_apps(env, root, &apps))
}

fn render_root_apps(env: &Env, root: &Path, apps: &[RootApp]) -> String {
    let mut out = String::from("# Generated by run-stack - do not edit.\n");
    out.push_str("# One service per ROOT_APPS entry: an app beside the frontend repo,\n");
    out.push_str("# mounted on its own and started with its own command.\n");
    out.push_str("services:\n");

    for (index, app) in apps.iter().enumerate() {
        let key = key_of(&app.name);
        let port = root_app_port(env, app, index);
        let volume = root_volume_name(&app.name);

        out.push_str(&format!("  {}:\n", app.name));
        out.push_str("    build:\n      context: ./docker/frontend\n");
        out.push_str("    image: ${COMPOSE_PROJECT_NAME:-myapp}/frontend:local\n");
        out.push_str("    working_dir: /app\n");
        out.push_str("    environment:\n");
        out.push_str(&format!("      APP_CMD: ${{{key}_CMD:-npm run dev}}\n"));
        out.push_str(&format!("      PORT: \"{port}\"\n"));
        out.push_str("    volumes:\n");
        out.push_str(&format!("      - {}/{}:/app\n", root.display(), app.dir));
        // The same mounts the frontend services get, so an entrypoint edit
        // takes effect on restart instead of needing the image rebuilt.
        out.push_str("      - ./docker/frontend/entrypoint.sh:/usr/local/bin/entrypoint.sh:ro\n");
        out.push_str("      - ./docker/frontend/mobile-stack.sh:/usr/local/bin/mobile-stack.sh:ro\n");
        out.push_str("      - pnpm_store:/pnpm-store\n");
        // A sibling directory brings its own host node_modules, built for the
        // host platform; the volume keeps the container's own copy separate.
        out.push_str(&format!("      - {volume}:/app/node_modules\n"));
        out.push_str(&format!(
            "    command: [\"root-app\", \"{}\", \"{port}\"]\n",
            app.name
        ));
        out.push_str(&format!("    ports:\n      - \"{port}:{port}\"\n"));
        out.push_str("    restart: unless-stopped\n\n");
    }

    // The dashboard lists what the stack runs; without these it never learns
    // these services exist.
    out.push_str("  dashboard:\n    environment:\n");
    out.push_str(&format!(
        "      ROOT_APPS: \"{}\"\n",
        apps.iter()
            .map(|app| if app.name == app.dir {
                app.name.clone()
            } else {
                format!("{}:{}", app.name, app.dir)
            })
            .collect::<Vec<_>>()
            .join(" ")
    ));
    for (index, app) in apps.iter().enumerate() {
        out.push_str(&format!(
            "      {}_PORT: \"{}\"\n",
            key_of(&app.name),
            root_app_port(env, app, index)
        ));
    }
    out.push('\n');

    out.push_str("volumes:\n");
    for app in apps {
        out.push_str(&format!("  {}:\n", root_volume_name(&app.name)));
    }
    out
}

fn root_volume_name(name: &str) -> String {
    format!("root_nm_{}", name.replace(['/', '-'], "_"))
}

/// Every directory holding a package.json, one level under a workspace root.
fn package_dirs(frontend: &Path) -> Vec<String> {
    let mut found = Vec::new();
    for root in ["apps", "packages"] {
        let Ok(entries) = fs::read_dir(frontend.join(root)) else {
            continue;
        };
        for entry in entries.flatten() {
            if entry.path().join("package.json").is_file() {
                found.push(format!(
                    "{root}/{}",
                    entry.file_name().to_string_lossy()
                ));
            }
        }
    }
    found.sort();
    found
}

/// apps/mobile-client -> fe_nm_apps_mobile_client
fn volume_name(dir: &str) -> String {
    format!(
        "fe_nm_{}",
        dir.replace(['/', '-'], "_")
    )
}

fn extra_apps(env: &Env) -> Vec<String> {
    env.get_or("EXTRA_APPS", "")
        .split_whitespace()
        .map(|name| name.split(':').next().unwrap_or(name).to_string())
        .collect()
}

fn mobile_enabled(env: &Env) -> bool {
    env.is_true("RUN_MOBILE", false)
}

/// docker-compose.packages.yml
fn packages(run_dir: &Path, env: &Env) -> Result<()> {
    let frontend = Path::new(env.get_or("FRONTEND_DIR", ""));
    let dirs = package_dirs(frontend);
    let stack = env.get_or("BACKEND_STACK", "laravel").to_string();
    let backend_in_frontend =
        env.get_or("BACKEND_DIR", "").trim_end_matches('/') == env.get_or("FRONTEND_DIR", "").trim_end_matches('/');
    let subdir = env.get_or("BACKEND_SUBDIR", "").trim_end_matches('/').to_string();

    let mut services: Vec<String> = FRONTEND_SERVICES.iter().map(|s| s.to_string()).collect();
    services.extend(extra_apps(env));

    let mut out = String::from("# Generated by run-stack — do not edit.\nservices:\n");

    // A Node backend needs the same treatment; Laravel keeps vendor/ in the
    // bind mount, so there is nothing to shadow there.
    if stack == "node" {
        for service in ["backend", "queue", "scheduler"] {
            out.push_str(&format!("  {service}:\n    volumes:\n"));
            out.push_str("      - pnpm_store:/pnpm-store\n");
            out.push_str("      - fe_nm_root:/app/node_modules\n");
            if backend_in_frontend {
                for dir in &dirs {
                    out.push_str(&format!("      - {}:/app/{dir}/node_modules\n", volume_name(dir)));
                }
                out.push_str("    depends_on:\n      frontend-deps:\n        condition: service_completed_successfully\n");
            } else if !subdir.is_empty() {
                out.push_str(&format!("      - be_node_modules:/app/{subdir}/node_modules\n"));
            }
        }
    }

    for service in &services {
        out.push_str(&format!("  {service}:\n"));
        // With no mobile app, park Metro behind a profile nothing selects. The
        // gate goes in this block: a second mapping for one service in one file
        // is a duplicate key, which compose refuses to parse at all.
        if !mobile_enabled(env) && METRO_SERVICES.contains(&service.as_str()) {
            out.push_str("    profiles: [\"__no_mobile\"]\n");
        }
        if dirs.is_empty() {
            continue;
        }
        out.push_str("    volumes:\n");
        for dir in &dirs {
            out.push_str(&format!("      - {}:/app/{dir}/node_modules\n", volume_name(dir)));
        }
    }

    out.push_str("volumes:\n");
    if stack == "node" && !backend_in_frontend && !subdir.is_empty() {
        out.push_str("  be_node_modules:\n");
    }
    for dir in &dirs {
        out.push_str(&format!("  {}:\n", volume_name(dir)));
    }

    write(run_dir.join("docker-compose.packages.yml"), &out)
}

/// docker-compose.extra.yml — one service per extra app.
///
/// The service definition is not written out by hand: the x-* anchor blocks are
/// copied verbatim out of docker-compose.yml, so an extra app is always built
/// from the same definition as web, admin and landing.
fn apps(run_dir: &Path, env: &Env, package_dir: &Path) -> Result<()> {
    let apps = extra_apps(env);
    let target = run_dir.join("docker-compose.extra.yml");
    if apps.is_empty() {
        let _ = fs::remove_file(&target);
        return Ok(());
    }

    let base = fs::read_to_string(package_dir.join("docker-compose.yml"))
        .with_context(|| format!("reading {}", package_dir.join("docker-compose.yml").display()))?;
    let anchors: String = base
        .lines()
        .skip_while(|line| !line.starts_with("x-"))
        .take_while(|line| !line.starts_with("services:"))
        .map(|line| format!("{line}\n"))
        .collect();

    let frontend = Path::new(env.get_or("FRONTEND_DIR", "")).to_path_buf();
    let mut out = String::from("# Generated by run-stack — do not edit.\n");
    out.push_str("# One service per EXTRA_APPS entry; edit run.config.toml and re-run up.\n");
    out.push_str(&anchors);
    out.push_str("services:\n");

    // The shared install covers the built-in apps; EXTRA_DEPS_APPS is the hook
    // that adds these to it.
    out.push_str("  frontend-deps:\n    environment:\n      <<: *frontend-env\n");
    out.push_str(&format!(
        "      EXTRA_DEPS_APPS: \"${{EXTRA_DEPS_APPS:-}} {} \"\n\n",
        apps.join(" ")
    ));

    let mut metro = Vec::new();
    out.push_str("  dashboard:\n    environment:\n");
    out.push_str(&format!("      EXTRA_APPS: \"{}\"\n", env.get_or("EXTRA_APPS", "")));
    for app in &apps {
        out.push_str(&format!(
            "      {}_PORT: \"{}\"\n",
            key_of(app),
            port_of(env, app, &frontend)
        ));
        if is_metro_app(&frontend, app) {
            metro.push(app.clone());
        }
    }
    out.push_str(&format!("      EXTRA_APPS_MOBILE: \"{}\"\n\n", metro.join(" ")));

    for app in &apps {
        let key = key_of(app);
        let port = port_of(env, app, &frontend);
        out.push_str(&format!("  {app}:\n    <<: *frontend-service\n    environment:\n      <<: *frontend-env\n"));
        out.push_str(&format!("      APP_CMD: ${{{key}_CMD:-}}\n"));
        if metro.contains(app) {
            // A second Metro, run exactly like mobile-client.
            out.push_str(&format!("      MOBILE_APP: \"{app}\"\n"));
            out.push_str(&format!("      MOBILE_STACK: ${{{key}_STACK:-auto}}\n"));
            out.push_str("      EXPO_NO_TELEMETRY: \"1\"\n");
            out.push_str("      EXPO_DEVTOOLS_LISTEN_ADDRESS: 0.0.0.0\n");
            out.push_str("      REACT_NATIVE_PACKAGER_HOSTNAME: ${REACT_NATIVE_PACKAGER_HOSTNAME:-localhost}\n");
            out.push_str(&format!("      RCT_METRO_PORT: \"{port}\"\n"));
            out.push_str("      EXPO_PUBLIC_API_BASE_URL: ${EXPO_PUBLIC_API_BASE_URL:-http://localhost:8000/api}\n");
            out.push_str(&format!("    command: [\"metro\", \"{app}\", \"{port}\"]\n"));
        } else {
            out.push_str(&format!("    command: [\"app\", \"{app}\", \"{port}\"]\n"));
        }
        out.push_str(&format!("    ports:\n      - \"{port}:{port}\"\n\n"));
    }

    write(target, &out)
}

/// An app is a Metro app when its own package.json depends on expo or
/// react-native. Nothing in the config says so.
fn is_metro_app(frontend: &Path, app: &str) -> bool {
    let Some(dir) = app_dir(frontend, app) else {
        return false;
    };
    let Ok(text) = fs::read_to_string(dir.join("package.json")) else {
        return false;
    };
    let Ok(package) = serde_json::from_str::<serde_json::Value>(&text) else {
        return false;
    };
    ["dependencies", "devDependencies"].iter().any(|section| {
        package[section]
            .as_object()
            .is_some_and(|deps| {
                deps.keys().any(|name| {
                    name == "expo"
                        || name.starts_with("expo-")
                        || name == "react-native"
                        || name.starts_with("react-native-")
                })
            })
    })
}

fn app_dir(frontend: &Path, app: &str) -> Option<std::path::PathBuf> {
    for root in ["apps", "packages"] {
        let direct = frontend.join(root).join(app);
        if direct.join("package.json").is_file() {
            return Some(direct);
        }
        // The directory and the workspace name need not match.
        if let Ok(entries) = fs::read_dir(frontend.join(root)) {
            for entry in entries.flatten() {
                let manifest = entry.path().join("package.json");
                let Ok(text) = fs::read_to_string(&manifest) else {
                    continue;
                };
                let named = serde_json::from_str::<serde_json::Value>(&text)
                    .ok()
                    .and_then(|package| package["name"].as_str().map(str::to_string));
                if named.as_deref() == Some(app) {
                    return Some(entry.path());
                }
            }
        }
    }
    None
}

fn port_of(env: &Env, app: &str, frontend: &Path) -> u16 {
    let key = format!("{}_PORT", key_of(app));
    if let Some(port) = env.get(&key).and_then(|value| value.trim().parse().ok()) {
        return port;
    }
    if is_metro_app(frontend, app) {
        8082
    } else {
        5180
    }
}

/// docker-compose.resources.yml — only when limits are actually set.
fn resources(run_dir: &Path, env: &Env) -> Result<()> {
    let target = run_dir.join("docker-compose.resources.yml");
    let pick = |specific: &str, global: &str| -> String {
        let value = env.get_or(specific, "");
        if !value.is_empty() {
            return value.to_string();
        }
        env.get_or(global, "").to_string()
    };
    let frontend = (
        pick("FRONTEND_MEMORY_LIMIT", "DOCKER_MEMORY_LIMIT"),
        pick("FRONTEND_CPU_LIMIT", "DOCKER_CPU_LIMIT"),
    );
    let backend = (
        pick("BACKEND_MEMORY_LIMIT", "DOCKER_MEMORY_LIMIT"),
        pick("BACKEND_CPU_LIMIT", "DOCKER_CPU_LIMIT"),
    );
    let postgres = (
        pick("POSTGRES_MEMORY_LIMIT", "DOCKER_MEMORY_LIMIT"),
        pick("POSTGRES_CPU_LIMIT", "DOCKER_CPU_LIMIT"),
    );
    let mysql = (
        pick("MYSQL_MEMORY_LIMIT", "DOCKER_MEMORY_LIMIT"),
        pick("MYSQL_CPU_LIMIT", "DOCKER_CPU_LIMIT"),
    );

    let nothing_set = [&frontend, &backend, &postgres, &mysql]
        .iter()
        .all(|(memory, cpu)| memory.is_empty() && cpu.is_empty());
    if nothing_set {
        // Compose rejects an empty cpus/mem_limit interpolation, so the file
        // exists only when there is something to put in it.
        let _ = fs::remove_file(&target);
        return Ok(());
    }

    let mut out = String::from("# Generated by run-stack — do not edit.\nservices:\n");
    let mut emit = |service: &str, limits: &(String, String)| {
        if limits.0.is_empty() && limits.1.is_empty() {
            return;
        }
        out.push_str(&format!("  {service}:\n"));
        if !limits.0.is_empty() {
            out.push_str(&format!("    mem_limit: {}\n", limits.0));
        }
        if !limits.1.is_empty() {
            out.push_str(&format!("    cpus: {}\n", limits.1));
        }
    };
    for service in FRONTEND_SERVICES.iter().chain(["desktop"].iter()) {
        emit(service, &frontend);
    }
    for app in extra_apps(env) {
        emit(&app, &frontend);
    }
    for service in ["backend", "queue", "scheduler"] {
        emit(service, &backend);
    }
    emit("postgres", &postgres);
    emit("mysql", &mysql);

    write(target, &out)
}

fn write(path: std::path::PathBuf, contents: &str) -> Result<()> {
    if let Some(parent) = path.parent() {
        fs::create_dir_all(parent).with_context(|| format!("creating {}", parent.display()))?;
    }
    fs::write(&path, contents).with_context(|| format!("writing {}", path.display()))
}

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

    fn env_with(root_apps: &str) -> Env {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join(".env");
        fs::write(&path, format!("ROOT_APPS={root_apps}\n")).unwrap();
        Env::load(&path).unwrap()
    }

    #[test]
    fn a_bare_name_uses_a_directory_of_the_same_name() {
        let apps = root_apps(&env_with("seeder"));

        assert_eq!(apps, vec![RootApp { name: "seeder".into(), dir: "seeder".into() }]);
    }

    #[test]
    fn a_name_and_directory_can_differ() {
        let apps = root_apps(&env_with("seeder:althaqeel-seeder"));

        assert_eq!(apps[0].name, "seeder");
        assert_eq!(apps[0].dir, "althaqeel-seeder");
    }

    #[test]
    fn several_apps_are_read_in_order() {
        let apps = root_apps(&env_with("seeder:althaqeel-seeder tools"));

        assert_eq!(apps.len(), 2);
        assert_eq!(apps[1].name, "tools");
    }

    #[test]
    fn an_empty_setting_yields_nothing() {
        assert!(root_apps(&env_with("")).is_empty());
    }

    #[test]
    fn each_app_is_mounted_from_the_workspace_root() {
        // The frontend bind mount cannot reach a sibling directory, which is
        // the whole reason these are not EXTRA_APPS.
        let env = env_with("seeder:althaqeel-seeder");
        let yaml = render_root_apps(&env, Path::new("/w"), &root_apps(&env));

        assert!(yaml.contains("- /w/althaqeel-seeder:/app"));
    }

    #[test]
    fn the_command_is_not_given_vite_flags() {
        // `node server.js --host 0.0.0.0 --port 4500` passes those to the
        // script, which is not what any plain Node app expects.
        let env = env_with("seeder:althaqeel-seeder");
        let yaml = render_root_apps(&env, Path::new("/w"), &root_apps(&env));

        assert!(yaml.contains(r#"command: ["root-app", "seeder", "4500"]"#));
        assert!(!yaml.contains("--strictPort"));
    }

    #[test]
    fn a_configured_port_wins_over_the_default() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join(".env");
        fs::write(&path, "ROOT_APPS=seeder\nSEEDER_PORT=4600\n").unwrap();
        let env = Env::load(&path).unwrap();

        assert!(render_root_apps(&env, Path::new("/w"), &root_apps(&env)).contains("\"4600:4600\""));
    }

    #[test]
    fn each_app_declares_its_own_node_modules_volume() {
        let env = env_with("seeder:althaqeel-seeder");
        let yaml = render_root_apps(&env, Path::new("/w"), &root_apps(&env));

        assert!(yaml.contains("- root_nm_seeder:/app/node_modules"));
        assert!(yaml.contains("volumes:\n  root_nm_seeder:"));
    }

    #[test]
    fn the_overlay_is_removed_when_no_root_apps_remain() {
        let dir = tempfile::tempdir().unwrap();
        let target = dir.path().join("docker-compose.root-apps.yml");
        fs::write(&target, "stale\n").unwrap();

        root_apps_file(dir.path(), &env_with("")).unwrap();

        assert!(!target.exists());
    }
}

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

    #[test]
    fn a_root_app_mounts_the_entrypoint_like_the_frontend_does() {
        // Without it the container runs whatever entrypoint the image was
        // built with, and a new role looks like a missing command.
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join(".env");
        fs::write(&path, "ROOT_APPS=seeder\n").unwrap();
        let env = Env::load(&path).unwrap();

        let yaml = render_root_apps(&env, Path::new("/w"), &root_apps(&env));

        assert!(yaml.contains("./docker/frontend/entrypoint.sh:/usr/local/bin/entrypoint.sh:ro"));
    }
}