mecha10_cli/services/process/

spawn_node.rs

//! Node-oriented spawning for `ProcessService`
//!
//! Higher-level spawning that resolves what a "node" actually is and how to
//! run it: via `mecha10-node-runner` (framework dev mode), or directly in
//! standalone mode (framework nodes via `BinaryManager`, or local project
//! nodes built and run in-place).

use super::ProcessService;
use crate::paths;
use anyhow::{Context, Result};
use mecha10_cli_core::utils::strip_node_scope;
use mecha10_core::wire_identifier::split_wire_identifier;
use std::collections::HashMap;

impl ProcessService {
    /// Spawn a node using mecha10-node-runner, which handles binary resolution, model pulling,
    /// and env setup. Returns the process ID of the spawned node-runner instance, or an error if
    /// it cannot be spawned.
    pub fn spawn_node_runner(
        &mut self,
        node_identifier: &str,
        project_name: &str,
        project_env: Option<HashMap<String, String>>,
    ) -> Result<u32> {
        let runner_path = Self::resolve_node_runner_path();

        let env = project_env.unwrap_or_default();

        let (base_identifier, instance_id, camera_id) = split_wire_identifier(node_identifier);

        let args = node_runner_args(project_name, base_identifier, instance_id, camera_id);
        let args: Vec<&str> = args.iter().map(String::as_str).collect();
        self.spawn_with_env(node_identifier, &runner_path, &args, env)
    }

    /// Spawn a node directly (standalone mode)
    ///
    /// This is used when mecha10-node-runner is not available. Handles both framework nodes
    /// (via BinaryManager) and local project nodes (built and run directly).
    pub fn spawn_node_direct(
        &mut self,
        node_identifier: &str,
        _project_name: &str,
        project_env: Option<HashMap<String, String>>,
    ) -> Result<u32> {
        let (base_identifier, instance_id, camera_id) = split_wire_identifier(node_identifier);
        let node_name = strip_node_scope(base_identifier);

        let is_local_node = self.is_local_project_node(node_name);

        let mut env = HashMap::new();
        env.insert("NODE_NAME".to_string(), base_identifier.to_string());
        if let Some(instance_id) = instance_id {
            env.insert("NODE_INSTANCE_ID".to_string(), instance_id.to_string());
        }
        if let Some(camera_id) = camera_id {
            env.insert("MECHA10_CAMERA_ID".to_string(), camera_id.to_string());
        }
        if let Ok(rust_log) = std::env::var("RUST_LOG") {
            env.insert("RUST_LOG".to_string(), rust_log);
        }

        insert_ort_dylib_path(node_name, &mut env)?;

        if let Some(project_vars) = project_env {
            tracing::debug!(
                "🔀 spawn_node_direct for '{}': merging {} project vars",
                node_name,
                project_vars.len()
            );
            for (key, value) in &project_vars {
                tracing::debug!(
                    "  Adding: {} = {}",
                    key,
                    if key == "ROBOT_API_KEY" { "<redacted>" } else { value }
                );
            }
            env.extend(project_vars);
        } else {
            tracing::warn!("⚠️  spawn_node_direct for '{}': No project_env provided!", node_name);
        }

        tracing::debug!(
            "🏁 spawn_node_direct for '{}': final env has {} vars, is_local: {}",
            node_name,
            env.len(),
            is_local_node
        );

        if is_local_node {
            self.spawn_local_node_with_identifier(node_identifier, node_name, env)
        } else {
            self.spawn_framework_node(node_identifier, node_name, env)
        }
    }

    /// Spawn a framework node using BinaryManager for binary resolution: checks the local
    /// cache (~/.mecha10/bin/) first, then downloads via `mecha10-api` if needed.
    fn spawn_framework_node(
        &mut self,
        node_identifier: &str,
        node_name: &str,
        mut env: HashMap<String, String>,
    ) -> Result<u32> {
        use super::super::binary_manager::BinaryManager;

        insert_ort_dylib_path(node_name, &mut env)?;

        let (base_identifier, _instance_id, _camera_id) = split_wire_identifier(node_identifier);
        let version = self.get_node_version_from_config(base_identifier);

        let binary_manager = BinaryManager::new()?;

        let binary_path = tokio::task::block_in_place(|| {
            tokio::runtime::Handle::current()
                .block_on(binary_manager.resolve_with_version(node_name, version.as_deref()))
        })?;

        tracing::info!(
            "🚀 Spawning framework node '{}' from {}",
            node_name,
            binary_path.display()
        );

        self.spawn_with_env(node_identifier, &binary_path.to_string_lossy(), &[], env)
    }

    /// Spawn a local project node with full identifier for tracking: builds the node with
    /// cargo and runs the binary directly.
    fn spawn_local_node_with_identifier(
        &mut self,
        node_identifier: &str,
        node_name: &str,
        env: HashMap<String, String>,
    ) -> Result<u32> {
        use std::process::Command;

        tracing::info!("🔨 Building local node: {}", node_name);

        let build_output = Command::new("cargo")
            .args(["build", "-p", node_name])
            .output()
            .context("Failed to run cargo build")?;

        if !build_output.status.success() {
            let stderr = String::from_utf8_lossy(&build_output.stderr);
            anyhow::bail!("Failed to build node '{}': {}", node_name, stderr);
        }

        tracing::info!("✅ Built local node: {}", node_name);

        let binary_path = paths::target_path("debug", node_name);

        if !std::path::Path::new(&binary_path).exists() {
            anyhow::bail!(
                "Binary not found at '{}'. Build may have failed or the package name differs from node name.",
                binary_path
            );
        }

        self.spawn_with_env(node_identifier, &binary_path, &[], env)
    }
}

/// Build the argument list passed to `mecha10-node-runner` for a given node.
///
/// `base_identifier` is passed through unchanged (no scope stripping): that's `node-runner`'s
/// own responsibility when it needs the bare name.
fn node_runner_args(
    project_name: &str,
    base_identifier: &str,
    instance_id: Option<&str>,
    camera_id: Option<&str>,
) -> Vec<String> {
    let mut args = vec![
        "--project".to_string(),
        project_name.to_string(),
        base_identifier.to_string(),
    ];
    if let Some(instance_id) = instance_id {
        args.push("--instance-id".to_string());
        args.push(instance_id.to_string());
    }
    if let Some(camera_id) = camera_id {
        args.push("--camera-id".to_string());
        args.push(camera_id.to_string());
    }
    args
}

/// The four `mecha10-nodes` crates that build `ort` with the `load-dynamic` feature (which
/// skips `ort-sys`'s build-time download+static-link step and defers to a runtime
/// `ORT_DYLIB_PATH` lookup in `ort::init()` instead). Every other node name is unaffected by
/// [`insert_ort_dylib_path`].
const ONNX_DEPENDENT_NODES: [&str; 4] = ["image-classifier", "instance-track", "object-detector", "rl"];

/// On macOS, point the four ONNX-dependent nodes at the `libonnxruntime.dylib` cached by
/// `mecha10 setup` (`handlers/setup.rs`'s ONNX Runtime step) by setting `ORT_DYLIB_PATH` in
/// `env` - `ort::init()`'s default env-var lookup then picks it up with no code change needed
/// in `mecha10-nodes` itself.
///
/// Non-ONNX nodes are untouched. For the four ONNX-dependent nodes, a missing dylib is a hard
/// error rather than a silent skip: without this, the child process panics opaquely with a raw
/// `dlopen` failure (see this ticket's repro) instead of a message telling the user what to run.
fn insert_ort_dylib_path(node_name: &str, env: &mut HashMap<String, String>) -> Result<()> {
    if !cfg!(target_os = "macos") {
        return Ok(());
    }

    let dylib_path = paths::user::onnxruntime_dylib_path();
    if dylib_path.exists() {
        env.insert("ORT_DYLIB_PATH".to_string(), dylib_path.to_string_lossy().into_owned());
        return Ok(());
    }

    if is_onnx_dependent_node(node_name) {
        anyhow::bail!(
            "ONNX Runtime not found (needed by node '{}') - run `mecha10 setup` first",
            node_name
        );
    }

    Ok(())
}

/// Whether `node_name` is one of the four `mecha10-nodes` crates that need
/// [`ONNX_DEPENDENT_NODES`]'s `ORT_DYLIB_PATH` wiring to run on macOS.
fn is_onnx_dependent_node(node_name: &str) -> bool {
    ONNX_DEPENDENT_NODES.contains(&node_name)
}

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

    #[test]
    fn node_runner_args_passes_the_scoped_identifier_through_unchanged() {
        let args = node_runner_args("rover-robot", "@mecha10/simulator", None, None);
        assert_eq!(args, ["--project", "rover-robot", "@mecha10/simulator"]);
    }

    #[test]
    fn node_runner_args_leaves_unscoped_node_name_untouched() {
        let args = node_runner_args("rover-robot", "my-node", None, None);
        assert_eq!(args, ["--project", "rover-robot", "my-node"]);
    }

    /// `LAB-4131`: an instance id appends `--instance-id <id>` for node-runner to forward on
    /// to the actual node binary's environment.
    #[test]
    fn node_runner_args_appends_instance_id_flag_when_present() {
        let args = node_runner_args("rover-robot", "@mecha10/camera", Some("real"), None);
        assert_eq!(
            args,
            ["--project", "rover-robot", "@mecha10/camera", "--instance-id", "real"]
        );
    }

    /// `LAB-4747`: a `camera_id` appends `--camera-id <id>` independently of `instance_id`.
    #[test]
    fn node_runner_args_appends_camera_id_flag_when_present() {
        let args = node_runner_args("rover-robot", "@mecha10/video-streamer", None, Some("camera"));
        assert_eq!(
            args,
            [
                "--project",
                "rover-robot",
                "@mecha10/video-streamer",
                "--camera-id",
                "camera"
            ]
        );
    }

    #[test]
    fn is_onnx_dependent_node_matches_only_the_four_onnx_backed_nodes() {
        assert!(is_onnx_dependent_node("image-classifier"));
        assert!(is_onnx_dependent_node("instance-track"));
        assert!(is_onnx_dependent_node("object-detector"));
        assert!(is_onnx_dependent_node("rl"));

        assert!(!is_onnx_dependent_node("simulator"));
        assert!(!is_onnx_dependent_node("video-streamer"));
        assert!(!is_onnx_dependent_node(""));
    }

    /// On every platform `mecha10 dev`/`sim`/`run` actually ships for other than macOS, ONNX
    /// node spawning must behave exactly as it did before this change - no `ORT_DYLIB_PATH`,
    /// no error, regardless of whether the dylib happens to be cached.
    #[cfg(not(target_os = "macos"))]
    #[test]
    fn insert_ort_dylib_path_is_a_complete_no_op_off_macos() {
        let mut env = HashMap::new();
        let result = insert_ort_dylib_path("image-classifier", &mut env);

        assert!(result.is_ok());
        assert!(env.is_empty());
    }

    #[test]
    fn node_runner_args_appends_both_flags_when_both_present() {
        let args = node_runner_args(
            "rover-robot",
            "@mecha10/video-streamer",
            Some("sim-streamer"),
            Some("simulation_camera"),
        );
        assert_eq!(
            args,
            [
                "--project",
                "rover-robot",
                "@mecha10/video-streamer",
                "--instance-id",
                "sim-streamer",
                "--camera-id",
                "simulation_camera"
            ]
        );
    }
}