mecha10_templates/services/

init_service.rs

//! Init service for project initialization
//!
//! Handles business logic for creating new Mecha10 projects.

use crate::paths;
use anyhow::{Context, Result};
use mecha10_cli_core::types::project::NodeEntry;
use mecha10_cli_core::utils::build_client;
use std::path::Path;

/// crates.io requests a descriptive User-Agent identifying the caller and a contact point
/// (https://crates.io/data-access) - this mirrors the one `scripts/release/publish-crates.sh`
/// already uses for its own crates.io API calls.
const CRATES_IO_USER_AGENT: &str = "mecha10-cli (+https://github.com/mecha10/mecha10; contact: releases@mecha10.dev)";

/// Body of a successful `GET https://crates.io/api/v1/crates/{name}` response - only the one
/// field this module needs out of the much larger payload.
#[derive(serde::Deserialize)]
struct CratesIoCrateResponse {
    #[serde(rename = "crate")]
    krate: CratesIoCrateMeta,
}

#[derive(serde::Deserialize)]
struct CratesIoCrateMeta {
    max_version: String,
}

/// Look up the latest published version of `package_name` on crates.io.
///
/// This is the same source of truth `scripts/release/publish-crates.sh::get_published_version`
/// queries when publishing, so `mecha10 add <component>` never writes a node crate version into
/// a project's `Cargo.toml` that can silently go stale (unlike a hand-maintained literal in the
/// component catalog).
async fn latest_published_crate_version(package_name: &str) -> Result<String> {
    let url = format!("https://crates.io/api/v1/crates/{}", package_name);

    let client = build_client()?;
    let response = client
        .get(&url)
        .header("User-Agent", CRATES_IO_USER_AGENT)
        .send()
        .await
        .with_context(|| format!("Failed to query crates.io for latest version of {}", package_name))?;

    if !response.status().is_success() {
        anyhow::bail!(
            "Failed to look up latest published version of {} on crates.io: HTTP {}\nURL: {}",
            package_name,
            response.status(),
            url
        );
    }

    let body = response
        .text()
        .await
        .with_context(|| format!("Failed to read crates.io response body for {}", package_name))?;

    parse_max_version(&body, package_name)
}

/// Pull `.crate.max_version` out of a `GET https://crates.io/api/v1/crates/{name}` response
/// body, split out from [`latest_published_crate_version`] so the parsing logic can be unit
/// tested without a live network call.
fn parse_max_version(body: &str, package_name: &str) -> Result<String> {
    let parsed: CratesIoCrateResponse = serde_json::from_str(body)
        .with_context(|| format!("Failed to parse crates.io response for {}", package_name))?;

    Ok(parsed.krate.max_version)
}

pub struct InitService;

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

    /// Create all the necessary directories for a new Mecha10 project.
    pub async fn create_project_directories(&self, path: &Path) -> Result<()> {
        let dirs = vec![
            paths::project::NODES_DIR,
            paths::project::DRIVERS_DIR,
            paths::project::TYPES_DIR,
            paths::project::BEHAVIORS_DIR,
            paths::project::LOGS_DIR,
            paths::project::MODELS_DIR,
            paths::project::MODELS_CATALOG_DIR,
            paths::project::SIMULATION_DIR,
            paths::project::SIMULATION_MODELS_DIR,
            paths::project::SIMULATION_ENVIRONMENTS_DIR,
            paths::project::SIMULATION_IMAGES_DIR,
            paths::project::RL_TASKS_DIR,
            paths::config::NODES_DIR,
        ];

        for dir in dirs {
            let dir_path = path.join(dir);
            tokio::fs::create_dir_all(&dir_path).await?;
        }

        Ok(())
    }

    /// Add an example node from the catalog to the project, updating Cargo.toml and
    /// mecha10.json as needed.
    ///
    /// Per-node `capabilities` no longer exist - the caller (`handlers/init.rs`) is responsible
    /// for recomputing `ProjectConfig::capabilities` (the flattened top-level field) once, after
    /// its whole node-add loop finishes, via `mecha10_cli_core::types::project::recompute_capabilities`.
    pub async fn add_example_node(&self, project_root: &Path, component_name: &str) -> Result<()> {
        use crate::component_catalog::ComponentCatalog;

        let catalog = ComponentCatalog::new();
        let components = catalog.search(component_name);

        if components.is_empty() {
            return Err(anyhow::anyhow!("Component '{}' not found in catalog", component_name));
        }

        let component = &components[0];

        for file_template in &component.files {
            let file_path = project_root.join(&file_template.path);

            if let Some(parent) = file_path.parent() {
                tokio::fs::create_dir_all(parent).await?;
            }

            tokio::fs::write(&file_path, &file_template.content).await?;
        }

        if !component.files.is_empty() {
            self.add_workspace_member(project_root, component_name).await?;
        }

        let is_monorepo_node = component.files.is_empty();
        if is_monorepo_node {
            self.add_dependency(project_root, component).await?;
        }

        self.add_node_to_config(project_root, component_name, is_monorepo_node)
            .await?;

        Ok(())
    }

    /// Ensure a node that's already fully scaffolded on disk (component files already written,
    /// Cargo.toml/workspace member already present) also has a `nodes` map entry in
    /// `mecha10.json`, without re-running any of [`Self::add_example_node`]'s file-writing
    /// steps.
    ///
    /// `mecha10 init --update` needs this: re-running the full `add_example_node` scaffold for
    /// a node that already has a local `config.json` would needlessly rewrite its component
    /// files (clobbering anything the project author customized) just to ensure one entry in
    /// `mecha10.json`. This only touches the `nodes` map entry, via
    /// [`Self::add_node_to_config`]'s upsert rules.
    pub async fn sync_node_capabilities(
        &self,
        project_root: &Path,
        component_name: &str,
        is_monorepo_node: bool,
    ) -> Result<()> {
        self.add_node_to_config(project_root, component_name, is_monorepo_node)
            .await
    }

    /// Add a workspace member to Cargo.toml
    async fn add_workspace_member(&self, project_root: &Path, component_name: &str) -> Result<()> {
        let cargo_toml_path = project_root.join(paths::rust::CARGO_TOML);
        let content = tokio::fs::read_to_string(&cargo_toml_path).await?;

        let new_member = format!("nodes/{}", component_name);
        let updated_content = if content.contains("members = []") {
            content.replace("members = []", &format!("members = [\n    \"{}\",\n]", new_member))
        } else if let Some(start) = content.find("members = [") {
            if let Some(end) = content[start..].find(']') {
                let insert_pos = start + end;
                let members_section = &content[start..insert_pos];
                if members_section.contains('\"') {
                    format!(
                        "{}\n    \"{}\",{}",
                        &content[..insert_pos],
                        new_member,
                        &content[insert_pos..]
                    )
                } else {
                    format!(
                        "{}\n    \"{}\",\n{}",
                        &content[..insert_pos],
                        new_member,
                        &content[insert_pos..]
                    )
                }
            } else {
                content
            }
        } else {
            content
        };

        tokio::fs::write(&cargo_toml_path, updated_content).await?;
        Ok(())
    }

    /// The crate names `add_dependency` must resolve/add for a component.
    ///
    /// Walks every entry in `component.cargo_dependencies`, not just the first one - driver
    /// components (see `component_catalog/drivers.rs`) list their local `mecha10-core` path
    /// dependency first and their real third-party crate (e.g. `realsense-rust`, `serialport`)
    /// second, so stopping at `.first()` silently resolved to `mecha10-core` - which is always
    /// already present in a scaffolded Cargo.toml - and skipped adding the driver's actual
    /// crate dependency entirely. Local workspace path dependencies (`dep.path.is_some()`, e.g.
    /// `mecha10-core`) are already present via the project's own scaffolding and must not be
    /// touched here - only real external crates need resolving/adding.
    ///
    /// Also always excludes a component's own `mecha10-nodes-<id>` crate (e.g.
    /// `mecha10-nodes-pan-tilt`), which every `Package`-type component (see
    /// `component_catalog/packages.rs`) lists as its sole `cargo_dependencies` entry. These
    /// crates are deliberately never published to crates.io - `mecha10-nodes` builds and
    /// uploads prebuilt binaries to mecha10-api, and nodes are downloaded as prebuilt binaries
    /// at runtime (`mecha10-deploy/src/services/binary_manager.rs`) keyed by the version already
    /// stored in `mecha10.json` (see PR #1384/#1488's `node_versions`/`build_node_placement`
    /// wiring, which is the actual source of truth for that version - never Cargo.toml).
    /// Resolving/adding this name against crates.io either 404s (for most nodes) or resolves a
    /// stale orphaned version (for a handful of leftovers), and either way the resulting error
    /// used to abort `add_example_node` before `add_node_to_config` ever ran, so no `Package`
    /// node ever landed in `mecha10.json` at all. Nothing in the build or runtime path reads
    /// this Cargo.toml entry back.
    fn external_dependency_names(component: &crate::component_catalog::Component) -> Vec<String> {
        if component.cargo_dependencies.is_empty() {
            return vec![];
        }

        let own_node_crate = format!("mecha10-nodes-{}", component.id);

        component
            .cargo_dependencies
            .iter()
            .filter(|dep| dep.path.is_none())
            .map(|dep| dep.name.clone())
            .filter(|name| *name != own_node_crate)
            .collect()
    }

    /// Insert `package_name = "version"` into `content` right after the
    /// `mecha10-core = "0.1"` anchor line that every scaffolded project's Cargo.toml has.
    /// Returns `content` unchanged if the anchor line isn't found.
    fn insert_dependency_version(content: &str, package_name: &str, version: &str) -> String {
        let Some(pos) = content.find("mecha10-core = \"0.1\"") else {
            return content.to_string();
        };
        let Some(newline_pos) = content[pos..].find('\n') else {
            return content.to_string();
        };
        let insert_pos = pos + newline_pos + 1;
        format!(
            "{}{} = \"{}\"\n{}",
            &content[..insert_pos],
            package_name,
            version,
            &content[insert_pos..]
        )
    }

    /// Add a dependency to Cargo.toml.
    ///
    /// Only ever resolves/adds the names `external_dependency_names` returns, which already
    /// excludes a component's own `mecha10-nodes-<id>` binary-distributed crate - so for every
    /// `Package`-type node this is a guaranteed no-op (empty `Vec` to iterate: no network call,
    /// no Cargo.toml write). Driver components' genuine third-party crates (e.g.
    /// `realsense-rust`, `serialport`) still resolve against crates.io exactly as before.
    async fn add_dependency(&self, project_root: &Path, component: &crate::component_catalog::Component) -> Result<()> {
        let cargo_toml_path = project_root.join(paths::rust::CARGO_TOML);
        let mut content = tokio::fs::read_to_string(&cargo_toml_path).await?;

        let mut changed = false;

        for package_name in Self::external_dependency_names(component) {
            if content.contains(&package_name) {
                continue;
            }

            let version = latest_published_crate_version(&package_name).await?;
            content = Self::insert_dependency_version(&content, &package_name, &version);
            changed = true;
        }

        if changed {
            tokio::fs::write(&cargo_toml_path, content).await?;
        }

        Ok(())
    }

    /// Mint this node's entry in mecha10.json's `nodes` map if it's not already present;
    /// `targets` placement and the top-level `capabilities` recomputation are both handled
    /// separately by `handlers/init.rs`.
    ///
    /// Writes the plain [`NodeEntry::Version`] pinned-version string, matching every other
    /// template-rendered entry in `mecha10.json` - a freshly-minted node is always enabled, so
    /// there's nothing the expanded [`NodeEntry::Detailed`] form would add here. If an entry
    /// already exists for this node identifier (in either form), it's left completely untouched:
    /// this is a pure insert-if-absent, no upsert rules needed now that there's no per-node field
    ///   left to backfill.
    async fn add_node_to_config(
        &self,
        project_root: &Path,
        component_name: &str,
        is_monorepo_node: bool,
    ) -> Result<()> {
        use crate::services::ConfigService;

        let config_path = project_root.join(paths::PROJECT_CONFIG);
        let mut config = ConfigService::load_from(&config_path).await?;

        let (node_identifier, version) = if is_monorepo_node {
            (
                format!("@mecha10/{}", component_name),
                env!("CARGO_PKG_VERSION").to_string(),
            )
        } else {
            (component_name.to_string(), "0.1.0".to_string())
        };

        if config.nodes.0.contains_key(&node_identifier) {
            return Ok(());
        }

        config.nodes.0.insert(node_identifier, NodeEntry::Version(version));

        let config_json = serde_json::to_string_pretty(&config)?;
        tokio::fs::write(&config_path, config_json).await?;

        Ok(())
    }
}

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

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

    #[test]
    fn reads_max_version_out_of_a_real_shaped_crates_io_payload() {
        let body = r#"{
            "crate": {
                "id": "mecha10-nodes-behavior-executor",
                "max_version": "0.4.2",
                "max_stable_version": "0.4.2"
            },
            "versions": []
        }"#;

        let version = parse_max_version(body, "mecha10-nodes-behavior-executor").expect("parse version");
        assert_eq!(version, "0.4.2");
    }

    #[test]
    fn errors_instead_of_silently_falling_back_on_malformed_body() {
        let result = parse_max_version("not json", "mecha10-nodes-behavior-executor");
        assert!(result.is_err());
    }
}

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

    /// Minimal workspace `Cargo.toml` shaped like what `mecha10 init` scaffolds, with the
    /// `mecha10-core = "0.1"` anchor line `add_dependency` inserts after.
    fn minimal_cargo_toml() -> &'static str {
        "[workspace]\nmembers = []\n\n[workspace.dependencies]\nmecha10-core = \"0.1\"\n"
    }

    #[tokio::test]
    async fn does_not_query_crates_io_when_the_dependency_is_already_present() {
        // If the package name is already in Cargo.toml, `add_dependency` must return early
        // before ever resolving a version - this must be able to run with no network access.
        let temp_dir = tempfile::tempdir().expect("create temp dir");
        let project_root = temp_dir.path();
        let cargo_toml_path = project_root.join(paths::rust::CARGO_TOML);

        let existing = format!("{}realsense-rust = \"0.3.0\"\n", minimal_cargo_toml());
        tokio::fs::write(&cargo_toml_path, &existing)
            .await
            .expect("write Cargo.toml");

        let catalog = crate::component_catalog::ComponentCatalog::new();
        let component = catalog
            .get("realsense-camera")
            .expect("realsense-camera is in the catalog")
            .clone();

        let service = InitService::new();
        service
            .add_dependency(project_root, &component)
            .await
            .expect("add_dependency should no-op without touching the network");

        let updated = tokio::fs::read_to_string(&cargo_toml_path)
            .await
            .expect("read Cargo.toml");
        assert_eq!(
            updated, existing,
            "an already-present dependency must be left untouched"
        );
    }

    #[tokio::test]
    async fn is_a_complete_no_op_for_a_package_node_regardless_of_cargo_toml_content() {
        // Package-type nodes (behavior-executor, camera, servo, pan-tilt, ...) list only their
        // own `mecha10-nodes-<id>` crate in `cargo_dependencies`, which `external_dependency_names`
        // now always excludes - so `add_dependency`'s loop has nothing to iterate. This must be
        // provable without any network access: no crates.io call, no Cargo.toml write, even
        // though the dependency name is nowhere in the file.
        let temp_dir = tempfile::tempdir().expect("create temp dir");
        let project_root = temp_dir.path();
        let cargo_toml_path = project_root.join(paths::rust::CARGO_TOML);

        let existing = minimal_cargo_toml().to_string();
        tokio::fs::write(&cargo_toml_path, &existing)
            .await
            .expect("write Cargo.toml");

        let catalog = crate::component_catalog::ComponentCatalog::new();
        let component = catalog.get("pan-tilt").expect("pan-tilt is in the catalog").clone();

        let service = InitService::new();
        service
            .add_dependency(project_root, &component)
            .await
            .expect("add_dependency should no-op without touching the network");

        let updated = tokio::fs::read_to_string(&cargo_toml_path)
            .await
            .expect("read Cargo.toml");
        assert_eq!(
            updated, existing,
            "a Package node's own mecha10-nodes-<id> crate must never be added to Cargo.toml"
        );
    }

    #[tokio::test]
    async fn does_not_query_crates_io_for_a_driver_when_both_its_dependencies_are_already_present() {
        // Same no-network guarantee as the Package-type test above, but for a Driver-type
        // component whose `cargo_dependencies` has two entries (local `mecha10-core` path dep
        // first, real third-party crate second) - both already present must mean no network
        // calls and no changes at all.
        let temp_dir = tempfile::tempdir().expect("create temp dir");
        let project_root = temp_dir.path();
        let cargo_toml_path = project_root.join(paths::rust::CARGO_TOML);

        let existing = format!("{}realsense-rust = \"0.6\"\n", minimal_cargo_toml());
        tokio::fs::write(&cargo_toml_path, &existing)
            .await
            .expect("write Cargo.toml");

        let catalog = crate::component_catalog::ComponentCatalog::new();
        let component = catalog
            .get("realsense-camera")
            .expect("realsense-camera is in the catalog")
            .clone();

        let service = InitService::new();
        service
            .add_dependency(project_root, &component)
            .await
            .expect("add_dependency should no-op without touching the network");

        let updated = tokio::fs::read_to_string(&cargo_toml_path)
            .await
            .expect("read Cargo.toml");
        assert_eq!(
            updated, existing,
            "a driver whose real crate (and local mecha10-core) are already present must be left untouched"
        );
    }

    /// `external_dependency_names` is the pure piece of `add_dependency` that decides which
    /// crate names need resolving/adding - covering it directly avoids a live crates.io call in
    /// this test suite while still proving the fix for the underlying bug.
    mod external_dependency_names_tests {
        use super::*;

        #[test]
        fn excludes_a_package_components_own_node_crate() {
            // Package-type catalog entries (behavior-executor, camera, servo, pan-tilt, ...)
            // have exactly one `cargo_dependencies` entry, for their own `mecha10-nodes-<id>`
            // crate. That crate is never published to crates.io - it's distributed as a
            // prebuilt binary via mecha10-api, keyed by the version already in `mecha10.json` -
            // so resolving/adding it here must never happen. This is the actual bug fix: before
            // it, this returned `vec!["mecha10-nodes-pan-tilt"]`, which 404'd against crates.io
            // and aborted `add_example_node` before the node ever landed in `mecha10.json`.
            let catalog = crate::component_catalog::ComponentCatalog::new();
            let component = catalog.get("pan-tilt").expect("pan-tilt is in the catalog");

            let names = InitService::external_dependency_names(component);

            assert_eq!(
                names,
                Vec::<String>::new(),
                "a Package component must never resolve its own mecha10-nodes-<id> crate"
            );
        }

        #[test]
        fn excludes_every_package_components_own_node_crate() {
            // Belt-and-suspenders: assert the exclusion holds across the whole catalog, not just
            // one hand-picked component - every Package-type component must resolve to an empty
            // Vec, never its own `mecha10-nodes-<id>` name.
            let catalog = crate::component_catalog::ComponentCatalog::new();

            for component in catalog.get_all() {
                let own_node_crate = format!("mecha10-nodes-{}", component.id);
                let names = InitService::external_dependency_names(component);
                assert!(
                    !names.contains(&own_node_crate),
                    "{} must never resolve its own node crate {}, got {:?}",
                    component.id,
                    own_node_crate,
                    names
                );
            }
        }

        #[test]
        fn resolves_the_real_third_party_crate_and_skips_the_local_mecha10_core_path_dep_for_a_driver() {
            // This is the bug: `realsense-camera` lists `mecha10-core` (a local path dep) first
            // and `realsense-rust` (its real third-party crate) second. The fixed logic must
            // skip the path dependency and resolve only the real crate - not stop at `.first()`
            // and silently resolve to `mecha10-core`, which is always already present.
            let catalog = crate::component_catalog::ComponentCatalog::new();
            let component = catalog
                .get("realsense-camera")
                .expect("realsense-camera is in the catalog");

            let names = InitService::external_dependency_names(component);

            assert_eq!(
                names,
                vec!["realsense-rust".to_string()],
                "a Driver component must resolve its real third-party crate, not its local mecha10-core path dep"
            );
        }
    }

    mod insert_dependency_version_tests {
        use super::*;

        #[test]
        fn inserts_right_after_the_mecha10_core_anchor_line() {
            let content = minimal_cargo_toml();

            let updated = InitService::insert_dependency_version(content, "realsense-rust", "0.6.1");

            assert_eq!(
                updated,
                "[workspace]\nmembers = []\n\n[workspace.dependencies]\nmecha10-core = \"0.1\"\nrealsense-rust = \"0.6.1\"\n"
            );
        }
    }

    #[tokio::test]
    async fn adds_the_drivers_real_crate_with_a_pre_resolved_version_and_leaves_mecha10_core_alone() {
        // End-to-end (minus the network hop) check that `add_dependency`'s loop, when the
        // driver's real crate is missing but its local mecha10-core dep is already present,
        // adds the real crate and does not duplicate/touch mecha10-core.
        let temp_dir = tempfile::tempdir().expect("create temp dir");
        let project_root = temp_dir.path();
        let cargo_toml_path = project_root.join(paths::rust::CARGO_TOML);
        tokio::fs::write(&cargo_toml_path, minimal_cargo_toml())
            .await
            .expect("write Cargo.toml");

        let catalog = crate::component_catalog::ComponentCatalog::new();
        let component = catalog
            .get("realsense-camera")
            .expect("realsense-camera is in the catalog")
            .clone();

        // Exercise the same package-name resolution `add_dependency` uses, but substitute a
        // fixed version in place of the live crates.io lookup so this test has no network
        // dependency.
        let names = InitService::external_dependency_names(&component);
        assert_eq!(names, vec!["realsense-rust".to_string()]);

        let content = tokio::fs::read_to_string(&cargo_toml_path)
            .await
            .expect("read Cargo.toml");
        let updated = InitService::insert_dependency_version(&content, &names[0], "0.6.1");
        tokio::fs::write(&cargo_toml_path, &updated)
            .await
            .expect("write Cargo.toml");

        let final_content = tokio::fs::read_to_string(&cargo_toml_path)
            .await
            .expect("read Cargo.toml");
        assert!(
            final_content.contains("realsense-rust = \"0.6.1\""),
            "the driver's real third-party crate must be added, got: {}",
            final_content
        );
        assert_eq!(
            final_content.matches("mecha10-core").count(),
            1,
            "mecha10-core must not be duplicated, got: {}",
            final_content
        );
    }
}

#[cfg(test)]
mod add_node_to_config_tests {
    use super::*;
    use mecha10_cli_core::services::ConfigService;

    /// Minimal valid mecha10.json content for a freshly-initialized project.
    fn minimal_project_config_json() -> &'static str {
        r#"{
            "name": "test-project",
            "version": "0.1.0",
            "robot_id": "test-robot"
        }"#
    }

    #[tokio::test]
    async fn mints_project_nodes_with_plain_identifier() {
        let temp_dir = tempfile::tempdir().expect("create temp dir");
        let project_root = temp_dir.path();
        tokio::fs::write(project_root.join(paths::PROJECT_CONFIG), minimal_project_config_json())
            .await
            .expect("write mecha10.json");

        let service = InitService::new();

        service
            .add_node_to_config(project_root, "my-custom", false)
            .await
            .expect("add_node_to_config should succeed");

        let config = ConfigService::load_from(&project_root.join(paths::PROJECT_CONFIG))
            .await
            .expect("reload config");

        assert!(
            config.nodes.identifiers().contains(&"my-custom"),
            "expected plain identifier 'my-custom' in nodes, got: {:?}",
            config.nodes.identifiers()
        );
        assert!(
            !config.nodes.identifiers().contains(&"@local/my-custom"),
            "new project nodes must not be minted with the legacy @local/ prefix, got: {:?}",
            config.nodes.identifiers()
        );
    }

    /// `add_node_to_config` must preserve `template_version` across its save, since it runs for
    /// every default/selected node on every `mecha10 init`.
    #[tokio::test]
    async fn preserves_template_version_written_by_mecha10_init() {
        let temp_dir = tempfile::tempdir().expect("create temp dir");
        let project_root = temp_dir.path();
        tokio::fs::write(
            project_root.join(paths::PROJECT_CONFIG),
            r#"{
                "name": "test-project",
                "version": "0.6.5",
                "template_version": "0.6.5",
                "robot_id": "test-robot"
            }"#,
        )
        .await
        .expect("write mecha10.json");

        let service = InitService::new();

        service
            .add_node_to_config(project_root, "speaker", true)
            .await
            .expect("add_node_to_config should succeed");

        let config = ConfigService::load_from(&project_root.join(paths::PROJECT_CONFIG))
            .await
            .expect("reload config");

        assert_eq!(
            config.template_version,
            Some("0.6.5".to_string()),
            "template_version written at `mecha10 init` time must survive add_node_to_config's save"
        );
    }

    #[tokio::test]
    async fn mints_framework_nodes_with_mecha10_scope() {
        let temp_dir = tempfile::tempdir().expect("create temp dir");
        let project_root = temp_dir.path();
        tokio::fs::write(project_root.join(paths::PROJECT_CONFIG), minimal_project_config_json())
            .await
            .expect("write mecha10.json");

        let service = InitService::new();

        service
            .add_node_to_config(project_root, "speaker", true)
            .await
            .expect("add_node_to_config should succeed");

        let config = ConfigService::load_from(&project_root.join(paths::PROJECT_CONFIG))
            .await
            .expect("reload config");

        assert!(
            config.nodes.identifiers().contains(&"@mecha10/speaker"),
            "expected framework identifier '@mecha10/speaker' in nodes, got: {:?}",
            config.nodes.identifiers()
        );
    }

    /// Capabilities no longer live per-node, and a freshly-minted node is always enabled - so
    /// `add_node_to_config` mints a plain pinned-version string, matching every other
    /// template-rendered entry, not the expanded `Detailed` object form.
    #[tokio::test]
    async fn mints_plain_version_string() {
        let temp_dir = tempfile::tempdir().expect("create temp dir");
        let project_root = temp_dir.path();
        tokio::fs::write(project_root.join(paths::PROJECT_CONFIG), minimal_project_config_json())
            .await
            .expect("write mecha10.json");

        let service = InitService::new();

        service
            .add_node_to_config(project_root, "speaker", true)
            .await
            .expect("add_node_to_config should succeed");

        let raw = tokio::fs::read_to_string(project_root.join(paths::PROJECT_CONFIG))
            .await
            .expect("read mecha10.json");
        let raw: serde_json::Value = serde_json::from_str(&raw).expect("parse mecha10.json");

        assert_eq!(
            raw["nodes"]["@mecha10/speaker"],
            serde_json::json!(env!("CARGO_PKG_VERSION"))
        );
    }

    /// `handlers/init.rs`'s `build_node_placement` runs before this and already pins a
    /// selected framework node to its own live-catalog version. `add_node_to_config` must not
    /// clobber that back to this crate's own `CARGO_PKG_VERSION`.
    #[tokio::test]
    async fn does_not_overwrite_a_version_already_pinned_by_build_node_placement() {
        let temp_dir = tempfile::tempdir().expect("create temp dir");
        let project_root = temp_dir.path();
        let config_with_pinned_node = r#"{
            "name": "test-project",
            "version": "0.1.0",
            "robot_id": "test-robot",
            "nodes": { "@mecha10/speaker": "0.7.0" }
        }"#;
        tokio::fs::write(project_root.join(paths::PROJECT_CONFIG), config_with_pinned_node)
            .await
            .expect("write mecha10.json");

        let service = InitService::new();

        service
            .add_node_to_config(project_root, "speaker", true)
            .await
            .expect("add_node_to_config should succeed");

        let config = ConfigService::load_from(&project_root.join(paths::PROJECT_CONFIG))
            .await
            .expect("reload config");

        assert_eq!(
            config.nodes.get_version("@mecha10/speaker"),
            Some("0.7.0"),
            "the live-catalog-pinned version must survive add_node_to_config's save, not be \
             reset to this crate's own CARGO_PKG_VERSION"
        );
    }

    /// An entry that already exists (in either form) must be left completely untouched - no
    /// upsert rules apply now that there's no per-node field left to backfill.
    #[tokio::test]
    async fn does_not_touch_an_already_present_entry() {
        let temp_dir = tempfile::tempdir().expect("create temp dir");
        let project_root = temp_dir.path();
        let config_with_existing_entry = r#"{
            "name": "test-project",
            "version": "0.1.0",
            "robot_id": "test-robot",
            "nodes": { "@mecha10/speaker": { "version": "0.7.0", "enabled": false } }
        }"#;
        tokio::fs::write(project_root.join(paths::PROJECT_CONFIG), config_with_existing_entry)
            .await
            .expect("write mecha10.json");

        let service = InitService::new();

        service
            .add_node_to_config(project_root, "speaker", true)
            .await
            .expect("add_node_to_config should succeed");

        let config = ConfigService::load_from(&project_root.join(paths::PROJECT_CONFIG))
            .await
            .expect("reload config");

        let entry = config.nodes.0.get("@mecha10/speaker").expect("entry must still exist");
        assert_eq!(entry.version(), "0.7.0", "version must be preserved");
        assert!(!entry.enabled(), "enabled: false must be preserved, not clobbered");
    }

    /// `add_node_to_config` must not touch `targets` at all - that placement is already
    /// written by `handlers/init.rs`'s `build_node_placement` before this ever runs.
    #[tokio::test]
    async fn does_not_touch_targets_at_all() {
        let temp_dir = tempfile::tempdir().expect("create temp dir");
        let project_root = temp_dir.path();
        let config_with_targets = r#"{
            "name": "test-project",
            "version": "0.1.0",
            "robot_id": "test-robot",
            "targets": {
                "robot": { "nodes": ["@mecha10/camera"] }
            }
        }"#;
        tokio::fs::write(project_root.join(paths::PROJECT_CONFIG), config_with_targets)
            .await
            .expect("write mecha10.json");

        let service = InitService::new();

        service
            .add_node_to_config(project_root, "image-classifier", true)
            .await
            .expect("add_node_to_config should succeed");

        let config = ConfigService::load_from(&project_root.join(paths::PROJECT_CONFIG))
            .await
            .expect("reload config");

        assert!(
            config.targets.simulation.is_none(),
            "add_node_to_config must not synthesize any targets.* entry anymore"
        );
        let robot = config
            .targets
            .robot
            .expect("pre-existing targets.robot must be preserved");
        assert_eq!(
            robot.nodes.iter().map(|n| n.name().to_string()).collect::<Vec<_>>(),
            vec!["@mecha10/camera".to_string()],
            "add_node_to_config must leave pre-existing targets.robot.nodes untouched, got {:?}",
            robot.nodes
        );
    }
}