mecha10_cli_core/

paths.rs

//! Centralized path definitions for the CLI
//!
//! All hardcoded paths should be defined here to ensure consistency
//! and make it easy to update paths across the codebase.
//!
//! # Organization
//!
//! - **Project paths**: Paths relative to project root (mecha10.json location)
//! - **User paths**: Paths in user's home directory (~/.mecha10)
//! - **Docker paths**: Paths used inside Docker containers
//! - **Framework paths**: Paths within the mecha10 framework source

#![allow(dead_code)]

/// Project configuration file
pub const PROJECT_CONFIG: &str = "mecha10.json";

/// Project directories
pub mod project {
    /// Node source code directory
    pub const NODES_DIR: &str = "nodes";

    /// Driver source code directory
    pub const DRIVERS_DIR: &str = "drivers";

    /// Types directory
    pub const TYPES_DIR: &str = "types";

    /// Behavior trees directory - nested under `configs/` (LAB-2072) so `mecha10 config
    /// push`/`pull`/`list` genuinely sync it like any other config, instead of living as a
    /// sibling top-level directory `collect_configs_from_dir` never walked.
    pub const BEHAVIORS_DIR: &str = "configs/behaviors";

    /// Models directory (ONNX models, etc.)
    pub const MODELS_DIR: &str = "models";

    /// Logs directory
    pub const LOGS_DIR: &str = "logs";

    /// Simulation directory - nested under `configs/` (moved from a top-level `simulation/`
    /// sibling) so `mecha10 config push`/`pull` syncs it like any other config, the same reason
    /// `BEHAVIORS_DIR` moved under `configs/` in LAB-2072. Shares its parent directory with the
    /// pre-existing `configs::SIMULATION_CONFIG` sim-settings file (`configs/simulation/
    /// config.json`) - no collision, since that file's fixed name never matches an asset file
    /// (`model.json`/`environment.json`/binary meshes/textures) synced under this tree.
    pub const SIMULATION_DIR: &str = "configs/simulation";

    /// Simulation models directory
    pub const SIMULATION_MODELS_DIR: &str = "configs/simulation/models";

    /// Simulation environments directory
    pub const SIMULATION_ENVIRONMENTS_DIR: &str = "configs/simulation/environments";

    /// Simulation billboard-image assets directory (`type: "image"` `environment.json`/
    /// `task.json` objects' `source` fields point here) - flat, no per-environment nesting: a
    /// project only ever has one pool of these images, so the earlier shared-vs-env-specific
    /// tiering (`mecha10_cli_core::simulation_assets`, now removed) was unneeded complexity.
    /// Nested under `SIMULATION_DIR` (not a top-level `assets/` sibling) so `mecha10 config
    /// push`/`pull` covers it like every other simulation asset - the previous top-level
    /// `<project>/assets/` location was never synced anywhere, which silently broke remote RL
    /// training for any environment with an image billboard.
    pub const SIMULATION_IMAGES_DIR: &str = "configs/simulation/images";

    /// RL task-curriculum configs directory (LAB-2430) - scaffolded from the templates
    /// package's bundled catalog at `mecha10 init` time. Deliberately NOT under
    /// `SIMULATION_MODELS_DIR`/`SIMULATION_ENVIRONMENTS_DIR`'s `simulation/` tree (LAB-2429):
    /// task-curriculum configs are a project's RL configuration (room_size, target_range,
    /// obstacle_count, ...), not a physics/rendering asset, so they live alongside the rest of a
    /// project's RL config (`configs/rl/jobs/`) instead. `mecha10-rl`'s
    /// `AssetResolver` resolves task configs (e.g. `task1`) from here for training
    /// (`mecha10 train`); `mecha10_rl.mujoco.cli serve --assets-path` (supervised by
    /// `packages/nodes/simulator`, live dev-mode physics only) never reads task configs at all.
    pub const RL_TASKS_DIR: &str = "configs/rl/tasks";

    /// Get path to a model's config file
    pub fn model_config(model_name: &str) -> String {
        format!("{}/models/{}/model.json", SIMULATION_DIR, model_name)
    }

    /// Get path to an environment's config file
    pub fn environment_config(env_name: &str) -> String {
        format!("{}/environments/{}/environment.json", SIMULATION_DIR, env_name)
    }

    /// Simulation output directory (generated robot/scene files)
    pub const SIMULATION_OUTPUT_DIR: &str = "configs/simulation/output";

    /// Cargo build target directory
    pub const TARGET_DIR: &str = "target";

    /// Source directory
    pub const SRC_DIR: &str = "src";

    /// Local (gitignored) project-scoped state directory - mirrors the `~/.mecha10`
    /// user-home convention (`user::MECHA10_DIR`) but scoped to this project checkout, for
    /// caches/state that are specific to one clone and shouldn't be committed to git (e.g.
    /// `mecha10 dev`'s Python dependency preflight cache - see
    /// `DEV_PREFLIGHT_CACHE_FILE`/`handlers/dev/ops/preflight.rs` in the `mecha10-cli` crate).
    pub const STATE_DIR: &str = ".mecha10";

    /// Cache file for `mecha10 dev`'s project-level Python dependency preflight gate - see
    /// `handlers/dev/ops/preflight.rs` in the `mecha10-cli` crate. Purely a speed
    /// optimization: a missing or stale-and-discarded cache always falls back to a real
    /// scan, so nothing about correctness depends on this file existing or being fresh.
    pub const DEV_PREFLIGHT_CACHE_FILE: &str = ".mecha10/dev-preflight-cache.json";
}

/// Configuration paths within project
pub mod config {
    use super::project;

    /// Base configs directory
    pub const DIR: &str = "configs";

    /// Node configs base directory
    pub const NODES_DIR: &str = "configs/nodes";

    /// Framework node configs (@mecha10 scope)
    pub const NODES_MECHA10_DIR: &str = "configs/nodes/@mecha10";

    /// Simulation config file. `configs::SIMULATION_DIR` was removed as a duplicate once
    /// `project::SIMULATION_DIR` moved to this same `configs/simulation` value - use that
    /// instead for the directory.
    pub const SIMULATION_CONFIG: &str = "configs/simulation/config.json";

    /// Framework-tier (`@mecha10`) `config.json` path for `name` under `category_dir`.
    fn framework_config(category_dir: &str, name: &str) -> String {
        format!("{category_dir}/@mecha10/{name}/config.json")
    }

    /// Project-tier (plain name) `config.json` path for `name` under `category_dir`.
    fn project_config(category_dir: &str, name: &str) -> String {
        format!("{category_dir}/{name}/config.json")
    }

    /// The 2-tier `config.json` lookup candidates for `name` under `category_dir`, in canonical
    /// resolution order: framework (`@mecha10`) -> project (plain name).
    fn config_candidates(category_dir: &str, name: &str) -> [String; 2] {
        [framework_config(category_dir, name), project_config(category_dir, name)]
    }

    /// Get config path for a framework node
    pub fn framework_node(node_name: &str) -> String {
        framework_config(NODES_DIR, node_name)
    }

    /// Get config path for a project node (plain name)
    pub fn project_node(node_name: &str) -> String {
        project_config(NODES_DIR, node_name)
    }

    /// Get the framework node's config *directory* (no `config.json` suffix) - the `@mecha10`
    /// counterpart to [`framework_node`], for callers that need the directory itself (e.g. to
    /// copy a whole config template tree into it) rather than the `config.json` file path.
    pub fn framework_node_dir(node_name: &str) -> String {
        format!("{}/{}", NODES_MECHA10_DIR, node_name)
    }

    /// The 2-tier `config.json` lookup candidates for a node, in canonical resolution order:
    /// framework (`@mecha10`) -> project (plain name). This is the ONE place that knows the tier
    /// order/naming convention for "does this node have a config.json, and if so which scope is
    /// it in" - callers that need to check both tiers (e.g. "use the first one that exists on
    /// disk") should use this rather than hand-rolling the same `format!()`/literal strings
    /// themselves, which is exactly what caused LAB-1982.
    pub fn node_config_candidates(node_name: &str) -> [String; 2] {
        config_candidates(NODES_DIR, node_name)
    }

    /// Get config path for a framework-default behavior (bundled into the project at scaffold
    /// time under `configs/behaviors/@mecha10/<name>/config.json`).
    pub fn framework_behavior(behavior_name: &str) -> String {
        framework_config(project::BEHAVIORS_DIR, behavior_name)
    }

    /// Get config path for a project behavior (plain name:
    /// `configs/behaviors/<name>/config.json`).
    pub fn project_behavior(behavior_name: &str) -> String {
        project_config(project::BEHAVIORS_DIR, behavior_name)
    }

    /// The 2-tier `config.json` lookup candidates for a behavior, in override-precedence order
    /// (highest first): project (plain name) -> framework (`@mecha10`). A project-committed
    /// override beats the bundled framework default. There is no `@local` tier for behaviors
    /// (LAB-1990). See [`node_config_candidates`] for the sibling helper for nodes.
    pub fn behavior_config_candidates(behavior_name: &str) -> [String; 2] {
        [project_behavior(behavior_name), framework_behavior(behavior_name)]
    }
}

/// Docker-related paths within project
pub mod docker {
    /// Docker directory
    pub const DIR: &str = "docker";

    /// Main docker-compose file
    pub const COMPOSE_FILE: &str = "docker/docker-compose.yml";

    /// Remote nodes docker-compose file
    pub const COMPOSE_REMOTE_FILE: &str = "docker/docker-compose.remote.yml";

    /// Remote nodes Dockerfile
    pub const DOCKERFILE_REMOTE: &str = "docker/Dockerfile.remote";

    /// Remote container entrypoint script (execs mecha10-launcher)
    pub const ENTRYPOINT_REMOTE: &str = "docker/entrypoint.sh";

    /// rl target docker-compose file - runs a trained RL policy in production
    pub const COMPOSE_RL_FILE: &str = "docker/docker-compose.rl.yml";

    /// rl target Dockerfile
    pub const DOCKERFILE_RL: &str = "docker/Dockerfile.rl";

    /// rl target container entrypoint script (execs mecha10-launcher --target rl) - a distinct
    /// filename from `ENTRYPOINT_REMOTE` since both `docker/entrypoint.sh` and this file coexist
    /// in the same project (remote and rl are independent, both-scaffolded targets).
    pub const ENTRYPOINT_RL: &str = "docker/entrypoint-rl.sh";
}

/// Environment files
pub mod env {
    /// Environment example file
    pub const EXAMPLE: &str = ".env.example";

    /// Environment file
    pub const FILE: &str = ".env";
}

/// Meta files (README, gitignore, etc.)
pub mod meta {
    /// README file
    pub const README: &str = "README.md";

    /// Git ignore file
    pub const GITIGNORE: &str = ".gitignore";

    /// Package.json for Node.js tooling
    pub const PACKAGE_JSON: &str = "package.json";

    /// Python requirements
    pub const REQUIREMENTS_TXT: &str = "requirements.txt";

    /// Pinned Python version for `mecha10 setup` to target (see
    /// `find_python_executable` in `packages/cli/src/handlers/setup.rs`) -
    /// matches the exact-version-pin pattern `scripts/dev/setup.py` already
    /// uses for framework-contributor setup, applied here to scaffolded
    /// end-user projects too.
    pub const PYTHON_VERSION: &str = ".python-version";
}

/// Rust project files
pub mod rust {
    /// Cargo workspace manifest
    pub const CARGO_TOML: &str = "Cargo.toml";

    /// Cargo lock file
    pub const CARGO_LOCK: &str = "Cargo.lock";

    /// Main entry point
    pub const MAIN_RS: &str = "src/main.rs";

    /// Library entry point
    pub const LIB_RS: &str = "src/lib.rs";

    /// Build script
    pub const BUILD_RS: &str = "build.rs";

    /// Rustfmt config
    pub const RUSTFMT_TOML: &str = "rustfmt.toml";
}

/// Model files within a model directory
pub mod model {
    /// ONNX model file
    pub const ONNX_FILE: &str = "model.onnx";

    /// Labels file
    pub const LABELS_FILE: &str = "labels.txt";

    /// Model config file
    pub const CONFIG_FILE: &str = "config.json";
}

/// User-level paths in home directory
pub mod user {
    use std::path::PathBuf;

    /// Base mecha10 directory in user home.
    ///
    /// Re-exports `mecha10_core::fs_utils::MECHA10_DIR`, the single source of truth for this
    /// literal shared with `launcher-service` (which can't depend on this crate - see that
    /// constant's doc comment) - kept as a `mecha10-cli-core`-local constant (rather than
    /// requiring callers to reach into `mecha10-core` directly) so existing callers of
    /// `paths::user::MECHA10_DIR` don't need to change (LAB-1999).
    pub const MECHA10_DIR: &str = mecha10_core::fs_utils::MECHA10_DIR;

    /// Credentials file, relative to the user home directory.
    ///
    /// Documentation-only - `mecha10-auth`'s `credentials::default_credentials_path()` is the
    /// actual source of truth for this path (see `credentials_file()` below), since
    /// `mecha10-auth` can't depend back on this crate (`mecha10-cli-core` already depends on
    /// `mecha10-auth`, so the reverse edge would be a dependency cycle).
    pub const CREDENTIALS_FILE: &str = ".mecha10/credentials.json";

    /// Templates cache directory
    pub const TEMPLATES_DIR: &str = ".mecha10/templates";

    /// Binary installation directory
    pub const BIN_DIR: &str = ".mecha10/bin";

    /// Get the base mecha10 directory path
    pub fn mecha10_dir() -> PathBuf {
        dirs::home_dir().unwrap_or_else(|| PathBuf::from(".")).join(MECHA10_DIR)
    }

    /// Get the credentials file path.
    ///
    /// Delegates to `mecha10-auth`'s `credentials::default_credentials_path()`, which is the
    /// single implementation of this resolution logic (see the `CREDENTIALS_FILE` doc comment
    /// for why the dependency runs in this direction).
    pub fn credentials_file() -> PathBuf {
        mecha10_auth::default_credentials_path()
    }

    /// Get the templates cache directory
    pub fn templates_dir() -> PathBuf {
        mecha10_dir().join("templates")
    }

    /// Get the binary directory
    pub fn bin_dir() -> PathBuf {
        mecha10_dir().join("bin")
    }

    /// Get path to a binary in the mecha10 bin directory
    pub fn bin(name: &str) -> PathBuf {
        bin_dir().join(name)
    }

    /// Get path to a binary in cargo bin directory
    pub fn cargo_bin(name: &str) -> PathBuf {
        home_bin_dir(".cargo", name)
    }

    /// Get path to a binary in local bin directory
    pub fn local_bin(name: &str) -> PathBuf {
        home_bin_dir(".local", name)
    }

    /// Get path to a binary in a `bin` subdirectory of the given home-relative directory
    /// (e.g. `~/.cargo/bin/{name}`, `~/.local/bin/{name}`).
    fn home_bin_dir(home_subdir: &str, name: &str) -> PathBuf {
        mecha10_core::fs_utils::home_subpath(&[home_subdir, "bin", name])
    }
}

/// Paths used inside Docker containers
pub mod container {
    /// Project mount point in container
    pub const PROJECT_ROOT: &str = "/project";

    /// Framework mount point in container
    pub const FRAMEWORK_ROOT: &str = "/mecha10";

    /// App directory (for mecha10-remote)
    pub const APP_ROOT: &str = "/app";

    /// Config file in mecha10-remote container
    pub const REMOTE_CONFIG: &str = "/app/mecha10.json";

    /// Get project-relative path inside container
    pub fn project_path(relative: &str) -> String {
        format!("{}/{}", PROJECT_ROOT, relative)
    }

    /// Get framework-relative path inside container
    pub fn framework_path(relative: &str) -> String {
        format!("{}/{}", FRAMEWORK_ROOT, relative)
    }
}

/// Paths within the mecha10 framework source
pub mod framework {
    /// Packages directory
    pub const PACKAGES_DIR: &str = "packages";

    /// Nodes package directory
    pub const NODES_DIR: &str = "packages/nodes";

    /// Drivers package directory
    pub const DRIVERS_DIR: &str = "packages/drivers";

    /// Simulation package directory
    pub const SIMULATION_DIR: &str = "packages/simulation";

    /// Simulation models directory
    pub const SIMULATION_MODELS_DIR: &str = "packages/simulation/models";

    /// Simulation environments directory
    pub const SIMULATION_ENVIRONMENTS_DIR: &str = "packages/simulation/environments";

    /// Simulation billboard-image assets directory - the framework-tree counterpart to
    /// `project::SIMULATION_IMAGES_DIR`.
    pub const SIMULATION_IMAGES_DIR: &str = "packages/simulation/images";

    /// Robot tasks environments directory (for environment matching)
    pub const ROBOT_TASKS_DIR: &str = "packages/simulation/environments/robot-tasks";

    /// Robot tasks catalog file
    pub const ROBOT_TASKS_CATALOG: &str = "packages/simulation/environments/robot-tasks/catalog.json";

    /// Marker directory used to detect the mecha10 framework root
    pub const ROOT_MARKER_DIR: &str = "packages/core";

    /// Release binary
    pub const RELEASE_BINARY: &str = "target/release/mecha10";

    /// Debug binary
    pub const DEBUG_BINARY: &str = "target/debug/mecha10";

    /// Get node config path within framework
    pub fn node_config(node_name: &str) -> String {
        format!("packages/nodes/{}/configs/config.json", node_name)
    }
}

/// External service URLs
pub mod urls {
    /// Default base URL for the public `mecha10-api` service.
    ///
    /// The CLI never talks to the private homelab Minio instance directly - all
    /// framework/runtime artifact downloads (CLI/launcher/node binaries, simulation
    /// assets, templates, remote-image manifests, ML models) are proxied through
    /// `mecha10-api`'s `/api/downloads/*` routes (see `packages/mecha10-api/src/catalog/downloads`),
    /// which run *inside* the private network and stream bytes back out.
    pub const MECHA10_API_URL: &str = "https://mecha.industries/api";

    /// Build the `mecha10-api` base URL (e.g. `https://mecha.industries/api`).
    ///
    /// Override at runtime with the `MECHA10_API_URL` env var (e.g. to point at a
    /// local `mecha10-api` instance during development).
    pub fn mecha10_api_base_url() -> String {
        std::env::var("MECHA10_API_URL")
            .unwrap_or_else(|_| MECHA10_API_URL.to_string())
            .trim_end_matches('/')
            .to_string()
    }

    /// Default authentication URL
    pub const AUTH_URL: &str = "https://mecha.industries/api/auth";
}

/// Build a target output path
pub fn target_path(profile: &str, binary: &str) -> String {
    format!("target/{}/{}", profile, binary)
}

/// Build a target output path with optional target triple
pub fn target_path_with_triple(target: Option<&str>, profile: &str) -> String {
    match target {
        Some(t) => format!("target/{}/{}", t, profile),
        None => format!("target/{}", profile),
    }
}

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

    #[test]
    fn credentials_file_matches_mecha10_auth_source_of_truth() {
        assert_eq!(user::credentials_file(), mecha10_auth::default_credentials_path());
    }

    /// `cargo_bin`/`local_bin` share a `home_bin_dir` helper (LAB-2893) that only differs on
    /// which home-relative directory it joins - pin both ends of that against the home dir so
    /// a future edit to the shared helper can't quietly break one without the other noticing.
    #[test]
    fn cargo_bin_and_local_bin_join_name_under_their_own_home_subdir() {
        let home = dirs::home_dir().expect("home dir must resolve in test environment");
        assert_eq!(
            user::cargo_bin("mecha10"),
            home.join(".cargo").join("bin").join("mecha10")
        );
        assert_eq!(
            user::local_bin("mecha10"),
            home.join(".local").join("bin").join("mecha10")
        );
    }

    #[test]
    fn simulation_project_dirs_share_the_simulation_root() {
        assert_eq!(project::SIMULATION_MODELS_DIR, "configs/simulation/models");
        assert_eq!(project::SIMULATION_ENVIRONMENTS_DIR, "configs/simulation/environments");
        for dir in [project::SIMULATION_MODELS_DIR, project::SIMULATION_ENVIRONMENTS_DIR] {
            assert!(dir.starts_with(&format!("{}/", project::SIMULATION_DIR)));
        }
    }

    /// LAB-2429: task-curriculum configs deliberately live under `configs/rl/`, NOT
    /// `SIMULATION_DIR` - they're a project's RL configuration (room_size, target_range,
    /// obstacle_count, ...), not a physics/rendering asset, so they're not part of the
    /// simulation-root grouping the test above pins.
    #[test]
    fn rl_tasks_dir_lives_under_configs_rl_not_simulation() {
        assert_eq!(project::RL_TASKS_DIR, "configs/rl/tasks");
        assert!(!project::RL_TASKS_DIR.starts_with(&format!("{}/", project::SIMULATION_DIR)));
    }

    #[test]
    fn test_config_paths() {
        assert_eq!(
            config::framework_node("object-detector"),
            "configs/nodes/@mecha10/object-detector/config.json"
        );
        assert_eq!(config::project_node("camera"), "configs/nodes/camera/config.json");
    }

    #[test]
    fn test_framework_node_dir() {
        assert_eq!(config::framework_node_dir("speaker"), "configs/nodes/@mecha10/speaker");
    }

    #[test]
    fn test_node_config_candidates_order() {
        assert_eq!(
            config::node_config_candidates("teleop"),
            [
                "configs/nodes/@mecha10/teleop/config.json".to_string(),
                "configs/nodes/teleop/config.json".to_string(),
            ]
        );
    }

    #[test]
    fn test_behavior_config_paths() {
        assert_eq!(
            config::framework_behavior("idle_wander"),
            "configs/behaviors/@mecha10/idle_wander/config.json"
        );
        assert_eq!(
            config::project_behavior("idle_wander"),
            "configs/behaviors/idle_wander/config.json"
        );
    }

    #[test]
    fn test_behavior_config_candidates_order() {
        assert_eq!(
            config::behavior_config_candidates("idle_wander"),
            [
                "configs/behaviors/idle_wander/config.json".to_string(),
                "configs/behaviors/@mecha10/idle_wander/config.json".to_string(),
            ]
        );
    }

    #[test]
    fn test_target_path() {
        assert_eq!(target_path("release", "my-node"), "target/release/my-node");
        assert_eq!(
            target_path_with_triple(Some("aarch64-unknown-linux-gnu"), "release"),
            "target/aarch64-unknown-linux-gnu/release"
        );
        assert_eq!(target_path_with_triple(None, "debug"), "target/debug");
    }

    #[test]
    fn test_container_paths() {
        assert_eq!(
            container::project_path("configs/test.json"),
            "/project/configs/test.json"
        );
        assert_eq!(container::framework_path("packages/core"), "/mecha10/packages/core");
    }

    #[test]
    fn test_mecha10_api_base_url_default() {
        let _guard = ENV_MUTEX.lock().unwrap();
        std::env::remove_var("MECHA10_API_URL");
        assert_eq!(urls::mecha10_api_base_url(), "https://mecha.industries/api");
    }

    #[test]
    fn test_mecha10_api_base_url_env_override() {
        let _guard = ENV_MUTEX.lock().unwrap();
        std::env::set_var("MECHA10_API_URL", "http://localhost:4000/api/");
        assert_eq!(urls::mecha10_api_base_url(), "http://localhost:4000/api");
        std::env::remove_var("MECHA10_API_URL");
    }

    /// Serializes tests that mutate process-wide env vars, since `cargo test` runs
    /// tests in this module concurrently by default.
    static ENV_MUTEX: std::sync::Mutex<()> = std::sync::Mutex::new(());
}