mecha10_templates/services/

behavior_generator.rs

//! Behavior generator service
//!
//! Generates custom project-authored behavior trees for Mecha10 projects (LAB-2069).
//!
//! Unlike `NodeGeneratorService`/`DriverGeneratorService`, a behavior is **not** a Rust crate —
//! investigation of `packages/nodes/behavior-executor` confirmed that a behavior is a purely
//! declarative `configs/behaviors/<name>/config.json` behavior-tree composition (a `$schema` +
//! `root`/`type`/`node`/`children` document, see `packages/mecha10-templates/templates/configs/
//! behaviors/@mecha10/{idle-wander,patrol-simple}/config.json` for the bundled framework
//! examples - moved under `configs/` in LAB-2072 so `mecha10 config push` actually syncs
//! behaviors), loaded at runtime by `mecha10_behavior_runtime::resolve_behavior_config_path` /
//! `BehaviorLoader` and executed by the `behavior-executor` node against its registered built-in
//! action nodes (`wander`, `move`, `timer`, `sensor_check`, ...) — there is no per-behavior Rust
//! code to scaffold. So this service only ever writes a single `config.json` file; it does not
//! create a `src/` tree, does not touch `Cargo.toml` workspace members, and does not touch
//! `mecha10.json` (a behavior is selected by name from a node's own
//! `configs/nodes/<behavior-executor-instance>/config.json` `behavior_name` field, not from a
//! project-wide registry — mirrors why `DriverGeneratorService` doesn't touch `mecha10.json`
//! either, see that service's module doc).
//!
//! Still uses the same `.template`-file + `include_str!()` + `{{var}}`-substitution rendering
//! pattern as `NodeGeneratorService`/`DriverGeneratorService` (see `crate::templates::render`),
//! for consistency and to keep the generated content out of hand-rolled `format!()` builders.

use crate::paths;
use crate::templates::render::render;
use anyhow::{Context, Result};
use std::path::Path;

/// `configs/behaviors/<name>/config.json` for a generated behavior — a minimal single-node
/// behavior tree (the built-in `wander` action) with `{{name}}`/`{{description}}` placeholders.
const CONFIG_JSON_TEMPLATE: &str = include_str!("../../templates/configs/behaviors/config.json.template");

/// Service for generating custom project-authored behavior trees
pub struct BehaviorGeneratorService;

impl BehaviorGeneratorService {
    /// Create a new BehaviorGeneratorService
    pub fn new() -> Self {
        Self
    }

    /// Generate a new behavior in the project
    ///
    /// Creates the following structure:
    /// ```text
    /// configs/behaviors/<name>/
    /// └── config.json
    /// ```
    pub async fn generate_behavior(&self, project_root: &Path, name: &str, description: Option<&str>) -> Result<()> {
        // Validate name
        self.validate_behavior_name(name)?;

        // Check if behavior already exists
        let behavior_dir = project_root.join(paths::project::BEHAVIORS_DIR).join(name);
        if behavior_dir.exists() {
            anyhow::bail!("Behavior '{}' already exists at {}", name, behavior_dir.display());
        }

        tokio::fs::create_dir_all(&behavior_dir)
            .await
            .context("Failed to create behavior directory")?;

        self.create_config_json(&behavior_dir, name, description).await?;

        Ok(())
    }

    /// Validate behavior name — same rules as node/driver names: it becomes both a directory
    /// name and the behavior tree's own `name` field.
    fn validate_behavior_name(&self, name: &str) -> Result<()> {
        if name.is_empty() {
            anyhow::bail!("Behavior name cannot be empty");
        }

        if !name.chars().all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_') {
            anyhow::bail!(
                "Behavior name '{}' contains invalid characters. Use only letters, numbers, hyphens, and underscores.",
                name
            );
        }

        if !name.chars().next().map(|c| c.is_ascii_alphabetic()).unwrap_or(false) {
            anyhow::bail!("Behavior name must start with a letter");
        }

        Ok(())
    }

    /// Create configs/behaviors/<name>/config.json with the rendered behavior-tree composition
    async fn create_config_json(&self, behavior_dir: &Path, name: &str, description: Option<&str>) -> Result<()> {
        let description = description.unwrap_or("TODO: describe this behavior");
        let content = render(CONFIG_JSON_TEMPLATE, &[("name", name), ("description", description)]);

        tokio::fs::write(behavior_dir.join("config.json"), content).await?;
        Ok(())
    }
}

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

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

    async fn setup_project() -> TempDir {
        TempDir::new().unwrap()
    }

    #[test]
    fn validate_behavior_name_rejects_empty() {
        let service = BehaviorGeneratorService::new();
        let err = service.validate_behavior_name("").unwrap_err();
        assert!(err.to_string().contains("cannot be empty"));
    }

    #[test]
    fn validate_behavior_name_rejects_invalid_characters() {
        let service = BehaviorGeneratorService::new();
        let err = service.validate_behavior_name("my behavior!").unwrap_err();
        assert!(err.to_string().contains("invalid characters"));
    }

    #[test]
    fn validate_behavior_name_rejects_leading_digit() {
        let service = BehaviorGeneratorService::new();
        let err = service.validate_behavior_name("1patrol").unwrap_err();
        assert!(err.to_string().contains("must start with a letter"));
    }

    #[test]
    fn validate_behavior_name_accepts_kebab_and_snake_case() {
        let service = BehaviorGeneratorService::new();
        assert!(service.validate_behavior_name("my-patrol_behavior").is_ok());
        assert!(service.validate_behavior_name("Patrol2").is_ok());
    }

    #[tokio::test]
    async fn generate_behavior_rejects_invalid_name_before_touching_disk() {
        let temp = setup_project().await;
        let service = BehaviorGeneratorService::new();

        let err = service
            .generate_behavior(temp.path(), "1-bad-name", None)
            .await
            .unwrap_err();

        assert!(err.to_string().contains("must start with a letter"));
        assert!(!temp.path().join("configs/behaviors").exists());
    }

    #[tokio::test]
    async fn generate_behavior_creates_expected_file_structure() {
        let temp = setup_project().await;
        let service = BehaviorGeneratorService::new();

        service
            .generate_behavior(temp.path(), "patrol", Some("desc"))
            .await
            .unwrap();

        let behavior_dir = temp.path().join("configs/behaviors").join("patrol");
        assert!(behavior_dir.join("config.json").exists());
        // Behaviors are not Rust crates — no src/ tree, no Cargo.toml.
        assert!(!behavior_dir.join("src").exists());
        assert!(!behavior_dir.join("Cargo.toml").exists());
    }

    #[tokio::test]
    async fn generate_behavior_fails_if_behavior_already_exists() {
        let temp = setup_project().await;
        let service = BehaviorGeneratorService::new();

        service.generate_behavior(temp.path(), "patrol", None).await.unwrap();
        let err = service
            .generate_behavior(temp.path(), "patrol", None)
            .await
            .unwrap_err();

        assert!(err.to_string().contains("already exists"));
    }

    #[tokio::test]
    async fn generate_behavior_does_not_touch_cargo_workspace_or_mecha10_json() {
        // Behaviors are declarative config, not code — generating one must not require (or
        // write) a Cargo.toml or mecha10.json, unlike `NodeGeneratorService::generate_node`.
        let temp = setup_project().await;
        let service = BehaviorGeneratorService::new();

        service.generate_behavior(temp.path(), "patrol", None).await.unwrap();

        assert!(!temp.path().join("Cargo.toml").exists());
        assert!(!temp.path().join("mecha10.json").exists());
    }

    #[tokio::test]
    async fn generate_behavior_output_content_uses_rendered_name_and_description() {
        let temp = setup_project().await;
        let service = BehaviorGeneratorService::new();

        service
            .generate_behavior(temp.path(), "my-patrol", Some("Patrols the perimeter"))
            .await
            .unwrap();

        let config_json = tokio::fs::read_to_string(temp.path().join("configs/behaviors/my-patrol/config.json"))
            .await
            .unwrap();
        assert_eq!(
            config_json,
            r#"{
  "$schema": "https://mecha10.dev/schemas/behavior-composition-v1.json",
  "name": "my-patrol",
  "description": "Patrols the perimeter",
  "root": {
    "type": "node",
    "node": "wander",
    "config": {
      "topic": "/motor/cmd_vel",
      "linear_speed": 0.3,
      "angular_speed": 0.5,
      "change_interval_secs": 3.0
    }
  }
}
"#
        );
    }

    #[tokio::test]
    async fn generate_behavior_uses_placeholder_description_when_none_given() {
        let temp = setup_project().await;
        let service = BehaviorGeneratorService::new();

        service.generate_behavior(temp.path(), "patrol", None).await.unwrap();

        let config_json = tokio::fs::read_to_string(temp.path().join("configs/behaviors/patrol/config.json"))
            .await
            .unwrap();
        assert!(config_json.contains("\"description\": \"TODO: describe this behavior\""));
    }

    #[tokio::test]
    async fn generate_behavior_config_json_is_valid_json() {
        let temp = setup_project().await;
        let service = BehaviorGeneratorService::new();

        service.generate_behavior(temp.path(), "patrol", None).await.unwrap();

        let config_json = tokio::fs::read_to_string(temp.path().join("configs/behaviors/patrol/config.json"))
            .await
            .unwrap();
        let _: serde_json::Value =
            serde_json::from_str(&config_json).expect("generated config.json must be valid JSON");
    }
}