run_stack/

add.rs

//! `rst add <folder>` - register a folder as an app without answering the
//! whole init questionnaire.
//!
//! Where it lands depends on where it lives: inside the frontend repo's apps/
//! it joins EXTRA_APPS and shares that bind mount, and beside the repo it joins
//! ROOT_APPS and gets a mount of its own.

use std::path::{Path, PathBuf};

use anyhow::{bail, Result};

use crate::config::Config;
use crate::env::Env;
use crate::workspace::Workspace;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Placement {
    /// Inside FRONTEND_DIR/apps - part of the workspace already.
    Workspace,
    /// A sibling of the frontend repo.
    Root,
}

impl Placement {
    pub fn key(self) -> &'static str {
        match self {
            Placement::Workspace => "EXTRA_APPS",
            Placement::Root => "ROOT_APPS",
        }
    }
}

#[derive(Debug, Clone)]
pub struct Found {
    /// What the service is called: what you type after `rst up`.
    pub name: String,
    /// The folder on disk, which is not always what you would call the app.
    pub dir: String,
    pub placement: Placement,
    pub path: PathBuf,
}

impl Found {
    /// `name:dir` when they differ, so the service keeps the short name while
    /// the mount still points at the right folder.
    pub fn entry(&self) -> String {
        if self.name == self.dir {
            self.name.clone()
        } else {
            format!("{}:{}", self.name, self.dir)
        }
    }
}

/// A folder beside the repo is usually named for the project it belongs to -
/// `althaqeel-seeder` in the `althaqeel` workspace. The project prefix says
/// nothing you do not already know, so the service is just `seeder`.
///
/// Apps inside the repo keep their folder name: that is their workspace
/// package name, and `pnpm --filter` needs it exactly.
pub fn service_name(workspace_root: &Path, folder: &str, placement: Placement) -> String {
    if placement == Placement::Workspace {
        return folder.to_string();
    }
    let Some(project) = workspace_root.file_name().map(|name| name.to_string_lossy().to_string())
    else {
        return folder.to_string();
    };

    match folder.strip_prefix(&format!("{project}-")) {
        Some(short) if !short.is_empty() => short.to_string(),
        _ => folder.to_string(),
    }
}

/// Something to run. A folder with no manifest, or a library with only build
/// and test scripts, is not an app.
pub fn runnable(dir: &Path) -> bool {
    let Ok(text) = std::fs::read_to_string(dir.join("package.json")) else {
        return false;
    };
    let Some(scripts) = text.split("\"scripts\"").nth(1) else {
        return false;
    };
    let block = scripts.split('}').next().unwrap_or("");
    block.contains("\"dev\"") || block.contains("\"start\"")
}

/// Resolve a folder name the way a person would mean it: the frontend repo's
/// apps/ first, then beside the repo.
pub fn locate(workspace: &Workspace, env: &Env, name: &str) -> Result<Found> {
    let name = name.trim().trim_end_matches('/');
    if name.is_empty() || name.contains('/') {
        bail!("give a folder name, not a path");
    }

    let frontend = env.get_or("FRONTEND_DIR", "");
    if !frontend.is_empty() {
        let in_apps = Path::new(frontend).join("apps").join(name);
        if in_apps.is_dir() {
            if !runnable(&in_apps) {
                bail!("{name} has no dev or start script - nothing to run");
            }
            return Ok(Found {
                name: name.to_string(),
                dir: name.to_string(),
                placement: Placement::Workspace,
                path: in_apps,
            });
        }
    }

    let beside = workspace.root.join(name);
    if beside.is_dir() {
        if !runnable(&beside) {
            bail!("{name} has no dev or start script - nothing to run");
        }
        return Ok(Found {
            name: service_name(&workspace.root, name, Placement::Root),
            dir: name.to_string(),
            placement: Placement::Root,
            path: beside,
        });
    }

    bail!("no folder called {name} in the frontend repo's apps/ or beside it")
}

/// The first of `wanted` that the folder's package.json defines.
pub fn first_script(dir: &Path, wanted: &[&str]) -> Option<String> {
    let text = std::fs::read_to_string(dir.join("package.json")).ok()?;
    let scripts = text.split("\"scripts\"").nth(1)?;
    let block = scripts.split('}').next().unwrap_or("");
    wanted
        .iter()
        .find(|name| block.contains(&format!("\"{name}\"")))
        .map(|name| (*name).to_string())
}

fn package_manager(dir: &Path) -> &'static str {
    if dir.join("pnpm-lock.yaml").is_file() {
        "pnpm"
    } else if dir.join("yarn.lock").is_file() {
        "yarn"
    } else {
        "npm"
    }
}

/// The command that starts the app.
///
/// An app inside the repo is started through the workspace, the way every
/// other entry in EXTRA_APPS is. One beside the repo has its own directory
/// mounted, so it runs its own package manager there.
pub fn start_command(found: &Found) -> String {
    let wanted: &[&str] = &["dev", "start", "serve"];
    let script = first_script(&found.path, wanted).unwrap_or_else(|| "dev".to_string());

    match found.placement {
        Placement::Workspace => format!("pnpm --filter {} run {script}", found.name),
        Placement::Root => match package_manager(&found.path) {
            "pnpm" => format!("pnpm {script}"),
            "yarn" => format!("yarn {script}"),
            _ => format!("npm run {script}"),
        },
    }
}

/// A port nothing else in the workspace has claimed.
///
/// Ports are the one setting a person cannot be asked for here, and a
/// collision only shows up later as a container that will not bind.
pub fn free_port(env: &Env, placement: Placement) -> u16 {
    let taken: Vec<u16> = env
        .iter()
        .filter(|(key, _)| key.ends_with("_PORT"))
        .filter_map(|(_, value)| value.trim().parse().ok())
        .collect();

    let start = match placement {
        Placement::Workspace => 5180,
        Placement::Root => 4500,
    };
    (start..start + 200)
        .find(|port| !taken.contains(port))
        .unwrap_or(start)
}

pub fn already_listed(current: &str, name: &str) -> bool {
    current
        .split_whitespace()
        .any(|entry| entry == name || entry.split(':').nth(1) == Some(name))
}

/// Append to a space separated list, leaving the order it already has.
pub fn appended(current: &str, name: &str) -> String {
    let mut entries: Vec<&str> = current.split_whitespace().collect();
    entries.push(name);
    entries.join(" ")
}

/// Write the new app to both files: .env is what compose reads, and
/// run.config.toml is what init rewrites .env from. Writing one alone means
/// the next `init --update` either misses it or drops it.
///
/// Listing the app is not enough - it also needs the port and command every
/// other app in the file has. An app already listed but missing either is
/// completed rather than refused, so a half-written entry converges.
pub fn record(workspace: &Workspace, found: &Found) -> Result<Vec<String>> {
    let env = Env::load(&workspace.env_path())?;
    let list_key = found.placement.key();
    let current = env.get_or(list_key, "").to_string();

    // An app listed as `name:dir` keys its settings on the name half, whichever
    // half was typed here.
    let declared = find_declared(&env, &found.name);
    let name = declared
        .as_ref()
        .map(|entry| entry.name.clone())
        .unwrap_or_else(|| found.name.clone());
    let key = crate::config::key_of(&name);

    let mut settings: Vec<(String, String)> = Vec::new();
    let mut notes: Vec<String> = Vec::new();

    if declared.is_none() {
        settings.push((list_key.to_string(), appended(&current, &found.entry())));
    } else {
        notes.push(format!("{list_key} already lists {}", found.name));
    }

    // Only fill what is missing: a command written by hand is the point of
    // writing it by hand.
    let port_key = format!("{key}_PORT");
    if env.get(&port_key).unwrap_or("").trim().is_empty() {
        settings.push((port_key, free_port(&env, found.placement).to_string()));
    } else {
        notes.push(format!("{port_key} already set"));
    }

    let cmd_key = format!("{key}_CMD");
    if env.get(&cmd_key).unwrap_or("").trim().is_empty() {
        settings.push((cmd_key, start_command(found)));
    } else {
        notes.push(format!("{cmd_key} already set"));
    }

    if settings.is_empty() {
        notes.push("nothing left to add".to_string());
        return Ok(notes);
    }

    for (name, value) in &settings {
        crate::doctor::set_env_key(&workspace.env_path(), name, value, NOTE)?;
    }

    let config_path = workspace.config_path();
    if config_path.is_file() {
        let mut config = Config::load(&config_path)?;
        for (name, value) in &settings {
            // A port is a number in the config, like every other port there.
            let parsed = if name.ends_with("_PORT") {
                value
                    .parse::<u64>()
                    .map(|number| serde_json::Value::Number(number.into()))
                    .unwrap_or_else(|_| serde_json::Value::String(value.clone()))
            } else {
                serde_json::Value::String(value.clone())
            };
            config.set(name, parsed);
        }
        config.save(&config_path)?;
    }

    let mut done: Vec<String> = settings
        .into_iter()
        .map(|(name, value)| format!("{name}={value}"))
        .collect();
    done.extend(notes);
    Ok(done)
}

/// An app as it is declared: the entry in the list, plus the name its
/// settings are keyed on. For a `name:dir` pair those differ.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Declared {
    pub entry: String,
    pub name: String,
    pub placement: Placement,
}

/// Find a declared app by either half of a `name:dir` pair, so removing it
/// works whichever half the person remembers.
pub fn find_declared(env: &Env, wanted: &str) -> Option<Declared> {
    let wanted = wanted.trim().trim_end_matches('/');
    for placement in [Placement::Workspace, Placement::Root] {
        for entry in env.get_or(placement.key(), "").split_whitespace() {
            let name = entry.split(':').next().unwrap_or(entry);
            let dir = entry.split(':').nth(1).unwrap_or(name);
            if wanted == entry || wanted == name || wanted == dir {
                return Some(Declared {
                    entry: entry.to_string(),
                    name: name.to_string(),
                    placement,
                });
            }
        }
    }
    None
}

pub fn without(current: &str, entry: &str) -> String {
    current
        .split_whitespace()
        .filter(|candidate| *candidate != entry)
        .collect::<Vec<_>>()
        .join(" ")
}

/// Drop the app from the list and take its port and command with it, from
/// both files. Leaving the settings behind would put them back on the next
/// app that happens to take the same name.
pub fn forget(workspace: &Workspace, declared: &Declared) -> Result<Vec<String>> {
    let env = Env::load(&workspace.env_path())?;
    let list_key = declared.placement.key();
    let remaining = without(env.get_or(list_key, ""), &declared.entry);

    let key = crate::config::key_of(&declared.name);
    let settings = [format!("{key}_PORT"), format!("{key}_CMD")];

    crate::doctor::set_env_key(&workspace.env_path(), list_key, &remaining, NOTE)?;
    for name in &settings {
        crate::doctor::remove_env_key(&workspace.env_path(), name)?;
    }

    let config_path = workspace.config_path();
    if config_path.is_file() {
        let mut config = Config::load(&config_path)?;
        config.set(list_key, serde_json::Value::String(remaining.clone()));
        for name in &settings {
            config.remove(name);
        }
        config.save(&config_path)?;
    }

    let mut done = vec![format!("{list_key}={remaining}")];
    done.extend(settings.iter().map(|name| format!("dropped {name}")));
    Ok(done)
}

const NOTE: &str =
    "Added by `rst add`. Apps beside the frontend repo get their own mount and\ncommand; apps inside its apps/ share the frontend mount.";

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

    fn workspace_at(root: &Path) -> Workspace {
        Workspace {
            root: root.to_path_buf(),
            run_dir: root.join(".run"),
        }
    }

    fn env_with(text: &str, root: &Path) -> Env {
        let path = root.join(".run").join(".env");
        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
        std::fs::write(&path, text).unwrap();
        Env::load(&path).unwrap()
    }

    fn app(dir: &Path, scripts: &str) {
        std::fs::create_dir_all(dir).unwrap();
        std::fs::write(dir.join("package.json"), scripts).unwrap();
    }

    #[test]
    fn a_folder_beside_the_repo_becomes_a_root_app() {
        let tmp = tempfile::tempdir().unwrap();
        let root = tmp.path();
        app(&root.join("seeder"), r#"{"scripts":{"dev":"node server.js"}}"#);
        let env = env_with("FRONTEND_DIR=platform\n", root);

        let found = locate(&workspace_at(root), &env, "seeder").unwrap();

        assert_eq!(found.placement, Placement::Root);
        assert_eq!(found.placement.key(), "ROOT_APPS");
    }

    #[test]
    fn a_folder_in_the_repos_apps_becomes_an_extra_app() {
        let tmp = tempfile::tempdir().unwrap();
        let root = tmp.path();
        app(&root.join("platform/apps/reports"), r#"{"scripts":{"dev":"vite"}}"#);
        let env = env_with(&format!("FRONTEND_DIR={}/platform\n", root.display()), root);

        let found = locate(&workspace_at(root), &env, "reports").unwrap();

        assert_eq!(found.placement, Placement::Workspace);
        assert_eq!(found.placement.key(), "EXTRA_APPS");
    }

    #[test]
    fn the_repos_apps_win_over_a_folder_of_the_same_name_beside_it() {
        let tmp = tempfile::tempdir().unwrap();
        let root = tmp.path();
        app(&root.join("platform/apps/tools"), r#"{"scripts":{"dev":"vite"}}"#);
        app(&root.join("tools"), r#"{"scripts":{"dev":"node ."}}"#);
        let env = env_with(&format!("FRONTEND_DIR={}/platform\n", root.display()), root);

        assert_eq!(
            locate(&workspace_at(root), &env, "tools").unwrap().placement,
            Placement::Workspace
        );
    }

    #[test]
    fn a_folder_with_nothing_to_run_is_refused() {
        let tmp = tempfile::tempdir().unwrap();
        let root = tmp.path();
        app(&root.join("shared"), r#"{"scripts":{"build":"tsc"}}"#);
        let env = env_with("", root);

        let error = locate(&workspace_at(root), &env, "shared").unwrap_err().to_string();

        assert!(error.contains("no dev or start script"), "{error}");
    }

    #[test]
    fn an_unknown_folder_says_where_it_looked() {
        let tmp = tempfile::tempdir().unwrap();
        let env = env_with("", tmp.path());

        let error = locate(&workspace_at(tmp.path()), &env, "ghost").unwrap_err().to_string();

        assert!(error.contains("apps/"), "{error}");
    }

    #[test]
    fn a_path_is_refused_rather_than_guessed_at() {
        let tmp = tempfile::tempdir().unwrap();
        let env = env_with("", tmp.path());

        assert!(locate(&workspace_at(tmp.path()), &env, "a/b").is_err());
    }

    #[test]
    fn appending_keeps_what_is_there() {
        assert_eq!(appended("one two", "three"), "one two three");
        assert_eq!(appended("", "one"), "one");
    }

    #[test]
    fn a_name_dir_pair_counts_as_listed() {
        assert!(already_listed("seeder:althaqeel-seeder", "althaqeel-seeder"));
        assert!(already_listed("tools seeder", "seeder"));
        assert!(!already_listed("tools", "seeder"));
    }

    #[test]
    fn recording_writes_the_env_and_is_idempotent() {
        let tmp = tempfile::tempdir().unwrap();
        let root = tmp.path();
        app(&root.join("seeder"), r#"{"scripts":{"dev":"node server.js"}}"#);
        let env = env_with("FRONTEND_DIR=platform\n", root);
        let workspace = workspace_at(root);
        let found = locate(&workspace, &env, "seeder").unwrap();

        record(&workspace, &found).unwrap();
        let once = std::fs::read_to_string(workspace.env_path()).unwrap();
        let second = record(&workspace, &found).unwrap();

        assert!(once.contains("ROOT_APPS=seeder"), "{once}");
        assert!(once.contains("SEEDER_PORT="), "no port written: {once}");
        assert!(once.contains("SEEDER_CMD="), "no command written: {once}");
        assert!(second.iter().any(|line| line.contains("already lists")));
        assert_eq!(once, std::fs::read_to_string(workspace.env_path()).unwrap());
    }
}

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

    #[test]
    fn a_second_app_is_written_quoted() {
        // Unquoted, `ROOT_APPS=seeder tools` runs `tools` when .env is sourced.
        let tmp = tempfile::tempdir().unwrap();
        let root = tmp.path();
        std::fs::create_dir_all(root.join(".run")).unwrap();
        let env_path = root.join(".run").join(".env");
        std::fs::write(&env_path, "ROOT_APPS=seeder\n").unwrap();

        crate::doctor::set_env_key(&env_path, "ROOT_APPS", "seeder tools", "why").unwrap();

        let text = std::fs::read_to_string(&env_path).unwrap();
        assert!(text.contains("ROOT_APPS=\"seeder tools\""), "{text}");
        assert!(crate::doctor::unquoted_values(&text).is_empty());
    }
}

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

    fn found_at(path: &Path, name: &str, placement: Placement) -> Found {
        Found { name: name.to_string(), dir: name.to_string(), placement, path: path.to_path_buf() }
    }

    fn write_app(dir: &Path, manifest: &str, lock: Option<&str>) {
        std::fs::create_dir_all(dir).unwrap();
        std::fs::write(dir.join("package.json"), manifest).unwrap();
        if let Some(lock) = lock {
            std::fs::write(dir.join(lock), "").unwrap();
        }
    }

    #[test]
    fn a_workspace_app_is_started_through_pnpm_filter() {
        // Matching the shape every other EXTRA_APPS entry already has.
        let tmp = tempfile::tempdir().unwrap();
        write_app(tmp.path(), r#"{"scripts":{"dev":"vite"}}"#, None);

        let command = start_command(&found_at(tmp.path(), "reports", Placement::Workspace));

        assert_eq!(command, "pnpm --filter reports run dev");
    }

    #[test]
    fn a_root_app_runs_its_own_package_manager() {
        let tmp = tempfile::tempdir().unwrap();
        write_app(tmp.path(), r#"{"scripts":{"dev":"node server.js"}}"#, Some("package-lock.json"));

        assert_eq!(start_command(&found_at(tmp.path(), "seeder", Placement::Root)), "npm run dev");
    }

    #[test]
    fn a_root_app_with_a_pnpm_lock_uses_pnpm() {
        let tmp = tempfile::tempdir().unwrap();
        write_app(tmp.path(), r#"{"scripts":{"dev":"node ."}}"#, Some("pnpm-lock.yaml"));

        assert_eq!(start_command(&found_at(tmp.path(), "tools", Placement::Root)), "pnpm dev");
    }

    #[test]
    fn start_is_used_when_there_is_no_dev() {
        let tmp = tempfile::tempdir().unwrap();
        write_app(tmp.path(), r#"{"scripts":{"start":"node ."}}"#, None);

        assert_eq!(start_command(&found_at(tmp.path(), "api", Placement::Root)), "npm run start");
    }

    #[test]
    fn the_port_avoids_one_already_claimed() {
        let tmp = tempfile::tempdir().unwrap();
        let path = tmp.path().join(".env");
        std::fs::write(&path, "SEEDER_PORT=4500\nOTHER_PORT=4501\n").unwrap();
        let env = Env::load(&path).unwrap();

        assert_eq!(free_port(&env, Placement::Root), 4502);
    }

    #[test]
    fn workspace_and_root_apps_start_from_different_ranges() {
        let tmp = tempfile::tempdir().unwrap();
        let path = tmp.path().join(".env");
        std::fs::write(&path, "").unwrap();
        let env = Env::load(&path).unwrap();

        assert_eq!(free_port(&env, Placement::Root), 4500);
        assert_eq!(free_port(&env, Placement::Workspace), 5180);
    }
}

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

    fn env_from(text: &str) -> (tempfile::TempDir, Env) {
        let tmp = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(tmp.path().join(".run")).unwrap();
        let path = tmp.path().join(".run").join(".env");
        std::fs::write(&path, text).unwrap();
        let env = Env::load(&path).unwrap();
        (tmp, env)
    }

    fn workspace_at(root: &Path) -> Workspace {
        Workspace { root: root.to_path_buf(), run_dir: root.join(".run") }
    }

    #[test]
    fn either_half_of_a_name_dir_pair_finds_it() {
        let (_tmp, env) = env_from("ROOT_APPS=seeder:althaqeel-seeder\n");

        for wanted in ["seeder", "althaqeel-seeder", "seeder:althaqeel-seeder"] {
            let found = find_declared(&env, wanted).expect(wanted);
            assert_eq!(found.entry, "seeder:althaqeel-seeder");
            // Settings are keyed on the name, not the directory.
            assert_eq!(found.name, "seeder");
        }
    }

    #[test]
    fn a_workspace_app_is_found_in_extra_apps() {
        let (_tmp, env) = env_from("EXTRA_APPS=reports tools\n");

        let found = find_declared(&env, "tools").unwrap();

        assert_eq!(found.placement, Placement::Workspace);
    }

    #[test]
    fn an_app_that_was_never_added_is_not_found() {
        let (_tmp, env) = env_from("ROOT_APPS=seeder\n");

        assert!(find_declared(&env, "ghost").is_none());
    }

    #[test]
    fn removing_keeps_the_other_entries() {
        assert_eq!(without("one two three", "two"), "one three");
        assert_eq!(without("only", "only"), "");
    }

    #[test]
    fn forgetting_drops_the_entry_and_its_settings() {
        let (tmp, env) = env_from(
            "ROOT_APPS=\"seeder tools\"\nSEEDER_PORT=4500\nSEEDER_CMD=\"npm run dev\"\nKEEP=yes\n",
        );
        let workspace = workspace_at(tmp.path());
        let declared = find_declared(&env, "seeder").unwrap();

        forget(&workspace, &declared).unwrap();

        let text = std::fs::read_to_string(workspace.env_path()).unwrap();
        assert!(text.contains("ROOT_APPS=tools"), "{text}");
        assert!(!text.contains("SEEDER_PORT"), "port left behind: {text}");
        assert!(!text.contains("SEEDER_CMD"), "command left behind: {text}");
        assert!(text.contains("KEEP=yes"), "unrelated setting lost: {text}");
    }

    #[test]
    fn add_then_remove_leaves_the_file_as_it_was() {
        let tmp = tempfile::tempdir().unwrap();
        let root = tmp.path();
        std::fs::create_dir_all(root.join("seeder")).unwrap();
        std::fs::write(
            root.join("seeder").join("package.json"),
            r#"{"scripts":{"dev":"node server.js"}}"#,
        )
        .unwrap();
        std::fs::create_dir_all(root.join(".run")).unwrap();
        let env_path = root.join(".run").join(".env");
        std::fs::write(&env_path, "FRONTEND_DIR=platform\nROOT_APPS=\n").unwrap();
        let workspace = workspace_at(root);

        let env = Env::load(&env_path).unwrap();
        let found = locate(&workspace, &env, "seeder").unwrap();
        record(&workspace, &found).unwrap();

        let env = Env::load(&env_path).unwrap();
        let declared = find_declared(&env, "seeder").unwrap();
        forget(&workspace, &declared).unwrap();

        let text = std::fs::read_to_string(&env_path).unwrap();
        assert!(!text.contains("SEEDER_PORT"), "{text}");
        assert!(!text.contains("SEEDER_CMD"), "{text}");
        assert!(text.contains("ROOT_APPS="), "{text}");
    }
}

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

    fn setup(env_text: &str) -> (tempfile::TempDir, Workspace) {
        let tmp = tempfile::tempdir().unwrap();
        let root = tmp.path();
        std::fs::create_dir_all(root.join("seeder")).unwrap();
        std::fs::write(
            root.join("seeder").join("package.json"),
            r#"{"scripts":{"dev":"node server.js"}}"#,
        )
        .unwrap();
        std::fs::create_dir_all(root.join(".run")).unwrap();
        std::fs::write(root.join(".run").join(".env"), env_text).unwrap();
        let workspace = Workspace { root: root.to_path_buf(), run_dir: root.join(".run") };
        (tmp, workspace)
    }

    fn add(workspace: &Workspace, name: &str) -> Vec<String> {
        let env = Env::load(&workspace.env_path()).unwrap();
        let found = locate(workspace, &env, name).unwrap();
        record(workspace, &found).unwrap()
    }

    #[test]
    fn a_listed_app_missing_its_settings_is_completed() {
        // The list alone is not a working app, and refusing to touch it left
        // a half-written entry half-written.
        let (_tmp, workspace) = setup("ROOT_APPS=seeder\n");

        add(&workspace, "seeder");

        let text = std::fs::read_to_string(workspace.env_path()).unwrap();
        assert!(text.contains("SEEDER_PORT="), "{text}");
        assert!(text.contains("SEEDER_CMD="), "{text}");
    }

    #[test]
    fn a_command_written_by_hand_is_left_alone() {
        let (_tmp, workspace) =
            setup("ROOT_APPS=seeder\nSEEDER_CMD=\"NO_OPEN=1 npm run dev\"\n");

        let done = add(&workspace, "seeder");

        let text = std::fs::read_to_string(workspace.env_path()).unwrap();
        assert!(text.contains("SEEDER_CMD=\"NO_OPEN=1 npm run dev\""), "{text}");
        assert!(done.iter().any(|line| line.contains("SEEDER_CMD already set")));
    }

    #[test]
    fn settings_are_keyed_on_the_name_half_of_a_pair() {
        // Adding by directory must not write a second set of keys under the
        // directory's name.
        let (_tmp, workspace) = setup("ROOT_APPS=short:seeder\n");

        add(&workspace, "seeder");

        let text = std::fs::read_to_string(workspace.env_path()).unwrap();
        assert!(text.contains("SHORT_PORT="), "{text}");
        assert!(!text.contains("SEEDER_PORT="), "keyed on the directory: {text}");
    }

    #[test]
    fn a_fully_configured_app_is_left_untouched() {
        let (_tmp, workspace) =
            setup("ROOT_APPS=seeder\nSEEDER_PORT=4500\nSEEDER_CMD=\"npm run dev\"\n");
        let before = std::fs::read_to_string(workspace.env_path()).unwrap();

        let done = add(&workspace, "seeder");

        assert_eq!(before, std::fs::read_to_string(workspace.env_path()).unwrap());
        assert!(done.iter().any(|line| line.contains("nothing left to add")));
    }
}

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

    #[test]
    fn a_folder_named_for_the_project_loses_the_prefix() {
        // althaqeel-seeder in the althaqeel workspace is just "seeder": the
        // prefix repeats what the workspace already says.
        let name = service_name(Path::new("/w/althaqeel"), "althaqeel-seeder", Placement::Root);

        assert_eq!(name, "seeder");
    }

    #[test]
    fn a_folder_with_no_project_prefix_keeps_its_name() {
        assert_eq!(service_name(Path::new("/w/althaqeel"), "tools", Placement::Root), "tools");
    }

    #[test]
    fn a_folder_named_exactly_after_the_project_keeps_its_name() {
        // Stripping would leave nothing to call it.
        assert_eq!(
            service_name(Path::new("/w/althaqeel"), "althaqeel", Placement::Root),
            "althaqeel"
        );
    }

    #[test]
    fn an_app_inside_the_repo_keeps_its_package_name() {
        // It is the pnpm workspace name, and --filter needs it exactly.
        assert_eq!(
            service_name(Path::new("/w/althaqeel"), "althaqeel-admin", Placement::Workspace),
            "althaqeel-admin"
        );
    }

    #[test]
    fn the_entry_pairs_a_short_name_with_its_folder() {
        let found = Found {
            name: "seeder".into(),
            dir: "althaqeel-seeder".into(),
            placement: Placement::Root,
            path: PathBuf::from("/w/althaqeel/althaqeel-seeder"),
        };

        assert_eq!(found.entry(), "seeder:althaqeel-seeder");
    }

    #[test]
    fn the_entry_is_one_word_when_they_match() {
        let found = Found {
            name: "tools".into(),
            dir: "tools".into(),
            placement: Placement::Root,
            path: PathBuf::from("/w/althaqeel/tools"),
        };

        assert_eq!(found.entry(), "tools");
    }
}