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 mecha10_core::node::Capability;
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.
    ///
    /// `capabilities` is this node's declared [`Capability`] set as resolved by the caller from
    /// the live node catalog (`catalog_client::fetch_node_catalog`'s
    /// `NodeCatalogEntry::capabilities`) - threaded straight through to
    /// [`Self::add_node_to_config`] rather than read back off a local `config.json`, so
    /// `mecha10 init`/`mecha10 init --update` no longer depend on
    /// `mecha10_robot_config::pull_node_catalog_configs` having already written that file (it
    /// silently no-ops if one already exists there, which could otherwise strand capabilities
    /// at `[]` forever).
    pub async fn add_example_node(
        &self,
        project_root: &Path,
        component_name: &str,
        capabilities: Vec<Capability>,
    ) -> 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, capabilities)
            .await?;

        Ok(())
    }

    /// Backfill `capabilities` onto a node that's already fully scaffolded on disk (component
    /// files already written, Cargo.toml/workspace member already present), 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 upsert one field 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,
        capabilities: Vec<Capability>,
    ) -> Result<()> {
        self.add_node_to_config(project_root, component_name, is_monorepo_node, capabilities)
            .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 or upsert this node's entry in mecha10.json's `nodes` map; `targets` placement is
    /// handled separately by `handlers/init.rs`.
    ///
    /// Writes the expanded [`NodeEntry::Detailed`] form (LAB-5021) rather than a bare
    /// pinned-version string, with `capabilities` exactly as given by the caller (the live
    /// node-catalog response's `NodeCatalogEntry::capabilities`, resolved by `handlers/init.rs`
    /// before this runs) - otherwise `NodesConfig::aggregated_capabilities()` has nothing to see
    /// for a node added this way.
    ///
    /// Three cases, in order:
    /// - No entry yet for this node identifier -> mint a fresh `NodeEntry::Detailed`.
    /// - An entry already exists but declares no capabilities (either the plain
    ///   `NodeEntry::Version` form, or a `Detailed` entry with an empty `capabilities` list) and
    ///   the caller has a non-empty `capabilities` to give -> backfill capabilities onto the
    ///   existing entry in place, preserving its pinned version (and, for an existing `Detailed`
    ///   entry, its `enabled` value too). This is what lets `mecha10 init --update` backfill
    ///   capabilities onto a node that was added before the live-catalog capability wiring
    ///   existed, without clobbering a deliberate `enabled: false`.
    /// - Otherwise (the entry already has capabilities, or the caller has none to give) -> leave
    ///   the entry untouched.
    async fn add_node_to_config(
        &self,
        project_root: &Path,
        component_name: &str,
        is_monorepo_node: bool,
        capabilities: Vec<Capability>,
    ) -> 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())
        };

        let new_entry = match config.nodes.0.get(&node_identifier) {
            None => Some(NodeEntry::Detailed {
                version,
                enabled: true,
                capabilities,
            }),
            Some(NodeEntry::Version(existing_version)) if !capabilities.is_empty() => Some(NodeEntry::Detailed {
                version: existing_version.clone(),
                enabled: true,
                capabilities,
            }),
            Some(NodeEntry::Detailed {
                version: existing_version,
                enabled: existing_enabled,
                capabilities: existing_capabilities,
            }) if existing_capabilities.is_empty() && !capabilities.is_empty() => Some(NodeEntry::Detailed {
                version: existing_version.clone(),
                enabled: *existing_enabled,
                capabilities,
            }),
            _ => None,
        };

        if let Some(entry) = new_entry {
            config.nodes.0.insert(node_identifier, entry);

            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, Vec::new())
            .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, Vec::new())
            .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, Vec::new())
            .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()
        );
    }

    /// Follow-up to LAB-5021: `capabilities` must be written exactly as the caller passes it in
    /// (resolved by `handlers/init.rs` from the live node-catalog response) into the expanded
    /// `NodeEntry::Detailed` form, rather than minting a bare pinned-version string or reading
    /// any local `config.json` back off disk.
    #[tokio::test]
    async fn mints_detailed_entry_with_capabilities_given_by_the_caller() {
        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, vec![Capability::Audio])
            .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!({
                "version": env!("CARGO_PKG_VERSION"),
                "enabled": true,
                "capabilities": ["audio"],
            })
        );
    }

    /// No local `config.json` exists for this node anywhere - `add_node_to_config` must still
    /// write the caller-given `capabilities`, proving it no longer reads any file off disk to
    /// resolve them (the old `read_local_node_capabilities` behavior this superseded).
    #[tokio::test]
    async fn mints_detailed_entry_with_capabilities_even_with_no_local_config_json_on_disk() {
        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");

        assert!(
            !project_root.join("configs/nodes/@mecha10/speaker/config.json").exists(),
            "precondition: no local config.json for this node"
        );

        let service = InitService::new();

        service
            .add_node_to_config(project_root, "speaker", true, vec![Capability::Audio])
            .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.0.get("@mecha10/speaker").map(|n| n.capabilities()),
            Some([Capability::Audio].as_slice()),
            "capabilities must come from the caller-given value, not a local file read-back"
        );
    }

    /// `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, Vec::new())
            .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"
        );
    }

    /// `mecha10 init --update` backfill case: the node already exists as a bare pinned-version
    /// string (implicitly no capabilities) and the caller now has a non-empty capabilities list
    /// for it (resolved off the live catalog) - `add_node_to_config` must upgrade the entry to
    /// the expanded `Detailed` form in place, preserving the existing pinned version.
    #[tokio::test]
    async fn upgrades_a_bare_version_entry_to_detailed_when_backfilling_capabilities() {
        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, vec![Capability::Audio])
            .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"),
            "existing pinned version must be preserved when upgrading to the Detailed form"
        );
        assert_eq!(
            config.nodes.0.get("@mecha10/speaker").map(|n| n.capabilities()),
            Some([Capability::Audio].as_slice()),
            "capabilities must be backfilled onto the upgraded entry"
        );
    }

    /// `mecha10 init --update` backfill case: the node already exists as a `Detailed` entry
    /// but with an empty `capabilities` list (e.g. added before live-catalog capability
    /// wiring existed) - `add_node_to_config` must backfill just the `capabilities` field,
    /// leaving `version`/`enabled` untouched.
    #[tokio::test]
    async fn backfills_capabilities_onto_a_detailed_entry_with_empty_capabilities() {
        let temp_dir = tempfile::tempdir().expect("create temp dir");
        let project_root = temp_dir.path();
        let config_with_empty_capabilities = r#"{
            "name": "test-project",
            "version": "0.1.0",
            "robot_id": "test-robot",
            "nodes": { "@mecha10/speaker": { "version": "0.7.0", "enabled": false, "capabilities": [] } }
        }"#;
        tokio::fs::write(project_root.join(paths::PROJECT_CONFIG), config_with_empty_capabilities)
            .await
            .expect("write mecha10.json");

        let service = InitService::new();

        service
            .add_node_to_config(project_root, "speaker", true, vec![Capability::Audio])
            .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");
        assert_eq!(
            entry.capabilities(),
            &[Capability::Audio],
            "capabilities must be backfilled"
        );
    }

    /// If the node already has a non-empty `capabilities` list, `add_node_to_config` must not
    /// clobber it with a different caller-given list - the existing, presumably
    /// deliberately-declared value wins.
    #[tokio::test]
    async fn does_not_clobber_an_existing_non_empty_capabilities_list() {
        let temp_dir = tempfile::tempdir().expect("create temp dir");
        let project_root = temp_dir.path();
        let config_with_existing_capabilities = r#"{
            "name": "test-project",
            "version": "0.1.0",
            "robot_id": "test-robot",
            "nodes": { "@mecha10/speaker": { "version": "0.7.0", "capabilities": ["vision"] } }
        }"#;
        tokio::fs::write(
            project_root.join(paths::PROJECT_CONFIG),
            config_with_existing_capabilities,
        )
        .await
        .expect("write mecha10.json");

        let service = InitService::new();

        service
            .add_node_to_config(project_root, "speaker", true, vec![Capability::Audio])
            .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.0.get("@mecha10/speaker").map(|n| n.capabilities()),
            Some([Capability::Vision].as_slice()),
            "an already-populated capabilities list must not be overwritten by a later call"
        );
    }

    /// `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, Vec::new())
            .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
        );
    }
}