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::templates::{InfraTemplates, MetaTemplates, RlBundleTemplates, RustTemplates};
use anyhow::Result;
use std::path::Path;

macro_rules! delegate_create {
    ($(#[$meta:meta])* $name:ident($field:ident)) => {
        $(#[$meta])*
        pub async fn $name(&self, path: &Path) -> Result<()> {
            self.$field.$name(path).await
        }
    };
    ($(#[$meta:meta])* $name:ident($field:ident, project_name)) => {
        $(#[$meta])*
        pub async fn $name(&self, path: &Path, project_name: &str) -> Result<()> {
            self.$field.$name(path, project_name).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(),
        }
    }

    delegate_create!(
        /// Create README.md for the project
        create_readme(meta, project_name)
    );

    delegate_create!(
        /// Create .gitignore for the project
        create_gitignore(meta)
    );

    delegate_create!(
        /// Create Cargo.toml for the project
        ///
        /// # Arguments
        ///
        /// * `path` - Project root path
        /// * `project_name` - Name of the project
        create_cargo_toml(rust, project_name)
    );

    delegate_create!(
        /// Create src/main.rs for the project
        create_main_rs(rust, project_name)
    );

    delegate_create!(
        /// Create build.rs for the project
        ///
        /// This build script generates:
        /// 1. node_registry.rs - Node dispatcher based on mecha10.json
        create_build_rs(rust)
    );

    delegate_create!(
        /// Create .env.example for the project
        ///
        /// # Arguments
        ///
        /// * `path` - Project root path
        /// * `project_name` - Name of the project
        create_env_example(infra, project_name)
    );

    delegate_create!(
        /// Create rustfmt.toml for the project
        create_rustfmt_toml(rust)
    );

    delegate_create!(
        /// 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)
        create_docker_compose(infra, project_name)
    );

    delegate_create!(
        /// 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
        create_remote_docker_files(infra)
    );

    delegate_create!(
        /// Create rl target Docker files
        ///
        /// Creates docker-compose.rl.yml, Dockerfile.rl, and entrypoint-rl.sh for running a
        /// trained RL policy in production. Modeled on `create_remote_docker_files`, but
        /// deliberately excludes the simulator - see that method's doc comment.
        ///
        /// # Arguments
        ///
        /// * `path` - Project root path
        create_rl_docker_files(infra)
    );

    delegate_create!(
        /// 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
        create_package_json(meta, project_name)
    );

    delegate_create!(
        /// 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
        create_requirements_txt(meta)
    );

    delegate_create!(
        /// Create `.python-version`, pinning the exact Python version `mecha10 setup`
        /// should target for the RL/simulation venv.
        ///
        /// # Arguments
        ///
        /// * `path` - Project root path
        create_python_version(meta)
    );

    /// Create the standard RL training bundle (LAB-1743) 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 two pieces:
    ///
    /// - `configs/rl/jobs/` - the standard job catalog; each job file is a complete training
    ///   config (job identity plus every `PPOConfig` hyperparameter, LAB-2970) - there's no more
    ///   separate `configs/rl/local.yml` sentinel-override config to layer onto.
    /// - `requirements.txt` - appended with the two packages' dependencies, since both already
    ///   register their entry points in their own `pyproject.toml` (nothing else to declare).
    ///
    /// A project no longer gets its own `kestra/` directory (LAB-2428) - a robot developer
    /// shouldn't need to know Kestra is involved; the canonical `train`/`tune`/`tune-then-train`/
    /// `train-from-tune`/`resume-run` flows live solely in `mecha10-rl`, deployed via its own CI.
    ///
    /// 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.append_rl_requirements(path).await?;
        self.rl_bundle.create_rl_jobs(path).await?;
        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_python_version_writes_a_pin_mecha10_setup_can_read() {
        let temp = TempDir::new().unwrap();
        let service = ProjectTemplateService::new();

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

        let content = tokio::fs::read_to_string(temp.path().join(".python-version"))
            .await
            .unwrap();
        let mut parts = content.trim().split('.');
        assert!(parts.next().unwrap().parse::<u32>().is_ok());
        assert!(parts.next().unwrap().parse::<u32>().is_ok());
        assert!(parts.next().is_none());
    }

    #[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_rl_training_bundle_requires_requirements_txt_created_first() {
        let temp = TempDir::new().unwrap();
        let service = ProjectTemplateService::new();

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

        assert!(temp.path().join("configs/rl/jobs/train.yml").exists());
        assert!(temp.path().join("requirements.txt").exists());
        assert!(!temp.path().join("kestra").exists());
    }
}