mecha10_templates/services/

project_template_service.rs

//! Project template service for generating project files
//!
//! This service coordinates template generation across specialized modules:
//! - Rust templates (Cargo.toml, main.rs, build.rs)
//! - Infrastructure templates (docker-compose.yml, .env)
//! - Meta templates (README.md, .gitignore, package.json)
//!
//! # Architecture
//!
//! Templates are organized into focused modules under `crate::templates`:
//! - **RustTemplates**: Rust-specific files
//! - **InfraTemplates**: Infrastructure files
//! - **MetaTemplates**: Project metadata files
//!
//! Template content is stored in external files at `packages/mecha10-templates/templates/`
//! and embedded at compile time using `include_str!()`.

use crate::paths;
use crate::templates::{InfraTemplates, MetaTemplates, RlBundleTemplates, RustTemplates};
use anyhow::{Context, Result};
use std::path::Path;

// Embedded configuration templates
//
// These two are the last-resort placeholder catalog written by `create_simulation_model_json`/
// `create_simulation_environment_json` (see `mecha10_cli::handlers::init::
// ensure_simulation_catalog_fallback`) when the downloaded templates archive didn't populate the
// real bundled simulation asset catalog. Distinct from the compile-time embedded-fallback *tier*
// removed in LAB-2034 (`create_simulation_configs`/`create_simulation_assets`/
// `create_behavior_templates`/`create_node_configs`, formerly below) - those existed to replace
// the entire downloaded-archive template-resolution path, not just backstop a missing catalog
// within it.
const MODEL_JSON_TEMPLATE: &str = include_str!("../../templates/config/model.json.template");
const ENVIRONMENT_JSON_TEMPLATE: &str = include_str!("../../templates/config/environment.json.template");

/// Service for generating project template files
///
/// # Examples
///
/// ```rust,ignore
/// use mecha10_cli::services::ProjectTemplateService;
///
/// let service = ProjectTemplateService::new();
///
/// // Generate all project files
/// service.create_readme(&project_path, "my-robot").await?;
/// service.create_cargo_toml(&project_path, "my-robot").await?;
/// ```
pub struct ProjectTemplateService {
    rust: RustTemplates,
    infra: InfraTemplates,
    meta: MetaTemplates,
    rl_bundle: RlBundleTemplates,
}

impl ProjectTemplateService {
    /// Create a new ProjectTemplateService
    pub fn new() -> Self {
        Self {
            rust: RustTemplates::new(),
            infra: InfraTemplates::new(),
            meta: MetaTemplates::new(),
            rl_bundle: RlBundleTemplates::new(),
        }
    }

    /// Create README.md for the project
    pub async fn create_readme(&self, path: &Path, project_name: &str) -> Result<()> {
        self.meta.create_readme(path, project_name).await
    }

    /// Create .gitignore for the project
    pub async fn create_gitignore(&self, path: &Path) -> Result<()> {
        self.meta.create_gitignore(path).await
    }

    /// Create Cargo.toml for the project
    ///
    /// # Arguments
    ///
    /// * `path` - Project root path
    /// * `project_name` - Name of the project
    pub async fn create_cargo_toml(&self, path: &Path, project_name: &str) -> Result<()> {
        self.rust.create_cargo_toml(path, project_name).await
    }

    /// Create src/main.rs for the project
    pub async fn create_main_rs(&self, path: &Path, project_name: &str) -> Result<()> {
        self.rust.create_main_rs(path, project_name).await
    }

    /// Create build.rs for the project
    ///
    /// This build script generates:
    /// 1. node_registry.rs - Node dispatcher based on mecha10.json
    pub async fn create_build_rs(&self, path: &Path) -> Result<()> {
        self.rust.create_build_rs(path).await
    }

    /// Create .env.example for the project
    ///
    /// # Arguments
    ///
    /// * `path` - Project root path
    /// * `project_name` - Name of the project
    pub async fn create_env_example(&self, path: &Path, project_name: &str) -> Result<()> {
        self.infra.create_env_example(path, project_name).await
    }

    /// Create rustfmt.toml for the project
    pub async fn create_rustfmt_toml(&self, path: &Path) -> Result<()> {
        self.rust.create_rustfmt_toml(path).await
    }

    /// Create docker-compose.yml for the project
    ///
    /// Generates a Docker Compose file with Redis and optional PostgreSQL services
    /// for local development and deployment.
    ///
    /// # Arguments
    ///
    /// * `path` - Project root path
    /// * `project_name` - Name of the project (used for container naming)
    pub async fn create_docker_compose(&self, path: &Path, project_name: &str) -> Result<()> {
        self.infra.create_docker_compose(path, project_name).await
    }

    /// Create remote node Docker files
    ///
    /// Creates docker-compose.remote.yml and Dockerfile.remote for running
    /// AI/ML nodes in containers. These are used when nodes are configured
    /// in targets.remote in mecha10.json.
    ///
    /// # Arguments
    ///
    /// * `path` - Project root path
    pub async fn create_remote_docker_files(&self, path: &Path) -> Result<()> {
        self.infra.create_remote_docker_files(path).await
    }

    /// Create package.json for npm dependencies
    ///
    /// Includes @mecha10/simulation-models and @mecha10/simulation-environments dependencies,
    /// resolved via node_modules/@mecha10/* (requires npm install).
    ///
    /// # Arguments
    ///
    /// * `path` - Project root path
    /// * `project_name` - Name of the project
    pub async fn create_package_json(&self, path: &Path, project_name: &str) -> Result<()> {
        self.meta.create_package_json(path, project_name).await
    }

    /// Create requirements.txt for Python dependencies
    ///
    /// Includes Python packages needed for AI nodes (onnx, onnxruntime).
    /// Install with: `mecha10 setup` or `pip install -r requirements.txt`
    ///
    /// # Arguments
    ///
    /// * `path` - Project root path
    pub async fn create_requirements_txt(&self, path: &Path) -> Result<()> {
        self.meta.create_requirements_txt(path).await
    }

    /// Create the standard RL training bundle (LAB-1743, Kestra flows added in LAB-1765) for a
    /// `rover` template project
    ///
    /// Bundles the Phase 2 `rover` env / `ppo` algorithm (`packages/rl-trainer`,
    /// `packages/rl-task-runner`, registered via the `mecha10_rl.envs`/`mecha10_rl.algorithms`
    /// entry-points registry, LAB-1732/1733) into three pieces:
    ///
    /// - `configs/rl/local.yml` - the default sentinel-override config for the combination
    ///   (LAB-1734's `rl_task_runner.local_config` pattern).
    /// - `requirements.txt` - appended with the two packages' dependencies, since both already
    ///   register their entry points in their own `pyproject.toml` (nothing else to declare).
    /// - `kestra/README.md` and `kestra/flows/ml-pipeline/*.yml` - the real `train`/`tune`/
    ///   `tune-then-train`/`train-from-tune`/`resume-run` Kestra flows (LAB-1745), embedded and
    ///   bundled by LAB-1765 so new projects get working flows out of the box.
    ///
    /// Callers should invoke `create_requirements_txt` first — this appends to that file rather
    /// than creating it.
    ///
    /// # Arguments
    ///
    /// * `path` - Project root path
    pub async fn create_rl_training_bundle(&self, path: &Path) -> Result<()> {
        self.rl_bundle.create_rl_config(path).await?;
        self.rl_bundle.append_rl_requirements(path).await?;
        self.rl_bundle.create_kestra_flows(path).await?;
        self.rl_bundle.create_rl_jobs(path).await?;
        Ok(())
    }

    /// Create simulation/models/model.json
    ///
    /// Generates the rover robot physical model configuration
    /// from embedded template.
    ///
    /// # Arguments
    ///
    /// * `path` - Project root directory
    pub async fn create_simulation_model_json(&self, path: &Path) -> Result<()> {
        let model_dest = path.join(paths::project::model_config("rover"));

        // Ensure destination directory exists
        if let Some(parent) = model_dest.parent() {
            tokio::fs::create_dir_all(parent).await?;
        }

        // Write embedded model.json template
        tokio::fs::write(&model_dest, MODEL_JSON_TEMPLATE)
            .await
            .context("Failed to write model.json")?;

        Ok(())
    }

    /// Create simulation/environments/basic_arena/environment.json
    ///
    /// Generates the basic arena environment configuration
    /// from embedded template.
    ///
    /// # Arguments
    ///
    /// * `path` - Project root directory
    pub async fn create_simulation_environment_json(&self, path: &Path) -> Result<()> {
        let env_dest = path.join(paths::project::environment_config("basic_arena"));

        // Ensure destination directory exists
        if let Some(parent) = env_dest.parent() {
            tokio::fs::create_dir_all(parent).await?;
        }

        // Write embedded environment.json template
        tokio::fs::write(&env_dest, ENVIRONMENT_JSON_TEMPLATE)
            .await
            .context("Failed to write environment.json")?;

        Ok(())
    }
}

impl Default for ProjectTemplateService {
    fn default() -> Self {
        Self::new()
    }
}

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

    #[tokio::test]
    async fn create_readme_replaces_project_name_placeholder() {
        let temp = TempDir::new().unwrap();
        let service = ProjectTemplateService::new();

        service.create_readme(temp.path(), "my-robot").await.unwrap();

        let content = tokio::fs::read_to_string(temp.path().join("README.md")).await.unwrap();
        assert!(content.contains("my-robot"));
        assert!(!content.contains("{{project_name}}"));
    }

    #[tokio::test]
    async fn create_gitignore_writes_file() {
        let temp = TempDir::new().unwrap();
        let service = ProjectTemplateService::new();

        service.create_gitignore(temp.path()).await.unwrap();

        assert!(temp.path().join(".gitignore").exists());
    }

    #[tokio::test]
    async fn create_cargo_toml_includes_project_name() {
        let temp = TempDir::new().unwrap();
        let service = ProjectTemplateService::new();

        service.create_cargo_toml(temp.path(), "my-robot").await.unwrap();

        let content = tokio::fs::read_to_string(temp.path().join("Cargo.toml")).await.unwrap();
        assert!(content.contains("my-robot"));
    }

    #[tokio::test]
    async fn create_main_rs_writes_file() {
        let temp = TempDir::new().unwrap();
        let service = ProjectTemplateService::new();

        service.create_main_rs(temp.path(), "my-robot").await.unwrap();

        assert!(temp.path().join("src/main.rs").exists());
    }

    #[tokio::test]
    async fn create_simulation_model_json_writes_expected_path() {
        let temp = TempDir::new().unwrap();
        let service = ProjectTemplateService::new();

        service.create_simulation_model_json(temp.path()).await.unwrap();

        let dest = temp.path().join(paths::project::model_config("rover"));
        assert!(dest.exists());
        let content = tokio::fs::read_to_string(&dest).await.unwrap();
        assert_eq!(content, MODEL_JSON_TEMPLATE);
    }

    #[tokio::test]
    async fn create_simulation_environment_json_writes_expected_path() {
        let temp = TempDir::new().unwrap();
        let service = ProjectTemplateService::new();

        service.create_simulation_environment_json(temp.path()).await.unwrap();

        let dest = temp.path().join(paths::project::environment_config("basic_arena"));
        assert!(dest.exists());
        let content = tokio::fs::read_to_string(&dest).await.unwrap();
        assert_eq!(content, ENVIRONMENT_JSON_TEMPLATE);
    }

    #[tokio::test]
    async fn create_simulation_model_json_creates_missing_parent_dirs() {
        // Regression guard: destination is nested (simulation/models/), so the
        // service must create parent directories itself rather than assuming
        // they already exist.
        let temp = TempDir::new().unwrap();
        let service = ProjectTemplateService::new();

        assert!(!temp.path().join("simulation").exists());

        service.create_simulation_model_json(temp.path()).await.unwrap();

        assert!(temp.path().join("simulation/models").is_dir());
    }

    #[tokio::test]
    async fn create_rl_training_bundle_requires_requirements_txt_created_first() {
        // create_rl_training_bundle appends to requirements.txt; per its own
        // doc comment, callers must create_requirements_txt first. Verify the
        // bundle still produces its own files even when that hasn't happened,
        // since append-to-missing-file is handled internally by RlBundleTemplates.
        let temp = TempDir::new().unwrap();
        let service = ProjectTemplateService::new();

        service.create_rl_training_bundle(temp.path()).await.unwrap();

        assert!(temp.path().join("configs/rl/local.yml").exists());
        assert!(temp.path().join("requirements.txt").exists());
        assert!(temp.path().join("kestra/README.md").exists());
    }
}