mecha10_cli/types/
project.rs

1//! Project configuration types
2//!
3//! Types for loading and managing mecha10.json project configuration files.
4
5use anyhow::{Context, Result};
6use serde::{Deserialize, Serialize};
7use std::path::PathBuf;
8
9#[derive(Debug, Serialize, Deserialize)]
10pub struct ProjectConfig {
11    pub name: String,
12    pub version: String,
13    pub robot: RobotConfig,
14    #[serde(default, skip_serializing_if = "Option::is_none")]
15    pub simulation: Option<ProjectSimulationConfig>,
16    #[serde(default, skip_serializing_if = "Option::is_none")]
17    pub lifecycle: Option<LifecycleConfig>,
18    #[serde(default)]
19    pub nodes: NodesConfig,
20    #[serde(default, skip_serializing_if = "Option::is_none")]
21    pub behaviors: Option<BehaviorsConfig>,
22    #[serde(default)]
23    pub services: ServicesConfig,
24    #[serde(default)]
25    pub docker: DockerServicesConfig,
26    #[serde(default)]
27    pub environments: EnvironmentsConfig,
28}
29
30// ============================================================================
31// Node Configuration Types
32// ============================================================================
33
34/// Node source type based on namespace prefix
35#[derive(Debug, Clone, PartialEq)]
36pub enum NodeSource {
37    /// Framework node bundled in CLI (@mecha10/*)
38    Framework,
39    /// Local project node (@local/*)
40    Project,
41    /// Third-party registry node (@<org>/*)
42    Registry(String),
43}
44
45/// Parsed node specification from namespaced string format
46///
47/// Node identifiers follow this format:
48/// - `@mecha10/listener` - Framework node (bundled in CLI)
49/// - `@local/my-custom` - Project node (built from local workspace)
50/// - `@someorg/cool-node` - Registry node (future, from npm-like registry)
51///
52/// Config paths follow the identifier:
53/// - `configs/nodes/@mecha10/listener/config.json`
54/// - `configs/nodes/@local/my-custom/config.json`
55#[derive(Debug, Clone)]
56pub struct NodeSpec {
57    /// Node name (derived from identifier, used in lifecycle modes)
58    pub name: String,
59    /// Full namespaced identifier
60    #[allow(dead_code)] // API for future use (registry lookups)
61    pub identifier: String,
62    /// Node source type
63    pub source: NodeSource,
64}
65
66impl NodeSpec {
67    /// Parse a node identifier string into a NodeSpec
68    ///
69    /// # Examples
70    ///
71    /// ```
72    /// let spec = NodeSpec::parse("@mecha10/listener").unwrap();
73    /// assert_eq!(spec.name, "listener");
74    /// assert_eq!(spec.source, NodeSource::Framework);
75    ///
76    /// let spec = NodeSpec::parse("@local/my-custom").unwrap();
77    /// assert_eq!(spec.name, "my-custom");
78    /// assert_eq!(spec.source, NodeSource::Project);
79    /// ```
80    pub fn parse(identifier: &str) -> Result<Self> {
81        let identifier = identifier.trim();
82
83        if !identifier.starts_with('@') {
84            anyhow::bail!(
85                "Invalid node identifier '{}'. Expected @mecha10/<name>, @local/<name>, or @<org>/<name>",
86                identifier
87            );
88        }
89
90        let without_at = identifier.strip_prefix('@').unwrap();
91        let parts: Vec<&str> = without_at.splitn(2, '/').collect();
92
93        if parts.len() != 2 {
94            anyhow::bail!(
95                "Invalid node identifier '{}'. Expected @<scope>/<name> format",
96                identifier
97            );
98        }
99
100        let scope = parts[0];
101        let name = parts[1].to_string();
102
103        if scope.is_empty() || name.is_empty() {
104            anyhow::bail!("Empty scope or name in identifier: {}", identifier);
105        }
106
107        let source = match scope {
108            "mecha10" => NodeSource::Framework,
109            "local" => NodeSource::Project,
110            org => NodeSource::Registry(org.to_string()),
111        };
112
113        Ok(Self {
114            name,
115            identifier: identifier.to_string(),
116            source,
117        })
118    }
119
120    /// Check if this is a framework node
121    pub fn is_framework(&self) -> bool {
122        matches!(self.source, NodeSource::Framework)
123    }
124
125    /// Check if this is a project node
126    #[allow(dead_code)] // API for future use
127    pub fn is_project(&self) -> bool {
128        matches!(self.source, NodeSource::Project)
129    }
130
131    /// Get the package/crate path for this node
132    ///
133    /// - Framework: mecha10-nodes-{name}
134    /// - Project: nodes/{name}
135    /// - Registry: node_modules/@{org}/{name} (future)
136    pub fn package_path(&self) -> String {
137        match &self.source {
138            NodeSource::Framework => format!("mecha10-nodes-{}", self.name),
139            NodeSource::Project => format!("nodes/{}", self.name),
140            NodeSource::Registry(org) => format!("node_modules/@{}/{}", org, self.name),
141        }
142    }
143
144    /// Get the config directory path for this node (relative to project root)
145    ///
146    /// Config path follows the identifier structure:
147    /// - `@mecha10/listener` → `configs/nodes/@mecha10/listener/`
148    /// - `@local/my-custom` → `configs/nodes/@local/my-custom/`
149    /// - `@someorg/node` → `configs/nodes/@someorg/node/`
150    #[allow(dead_code)] // API for future use
151    pub fn config_dir(&self) -> String {
152        format!("configs/nodes/{}", self.identifier)
153    }
154}
155
156/// Nodes configuration - array of namespaced node identifiers
157///
158/// Node identifiers follow this format:
159/// - `@mecha10/listener` - Framework node (bundled in CLI)
160/// - `@local/my-custom` - Project node (built from local workspace)
161/// - `@someorg/cool-node` - Registry node (future, from npm-like registry)
162///
163/// Example:
164/// ```json
165/// {
166///   "nodes": [
167///     "@mecha10/listener",
168///     "@mecha10/speaker",
169///     "@local/my-custom"
170///   ]
171/// }
172/// ```
173#[derive(Debug, Serialize, Deserialize, Default, Clone)]
174#[serde(transparent)]
175pub struct NodesConfig(pub Vec<String>);
176
177impl NodesConfig {
178    /// Create a new empty nodes config
179    #[allow(dead_code)] // API for future use
180    pub fn new() -> Self {
181        Self(Vec::new())
182    }
183
184    /// Get all node specs from the configuration
185    pub fn get_node_specs(&self) -> Vec<NodeSpec> {
186        self.0.iter().filter_map(|id| NodeSpec::parse(id).ok()).collect()
187    }
188
189    /// Get all node names (for lifecycle mode validation)
190    pub fn get_node_names(&self) -> Vec<String> {
191        self.get_node_specs().iter().map(|s| s.name.clone()).collect()
192    }
193
194    /// Find a node by name
195    pub fn find_by_name(&self, name: &str) -> Option<NodeSpec> {
196        self.get_node_specs().into_iter().find(|s| s.name == name)
197    }
198
199    /// Check if a node exists
200    pub fn contains(&self, name: &str) -> bool {
201        self.find_by_name(name).is_some()
202    }
203
204    /// Add a node to the configuration
205    pub fn add_node(&mut self, identifier: &str) {
206        if !self.0.contains(&identifier.to_string()) {
207            self.0.push(identifier.to_string());
208        }
209    }
210
211    /// Remove a node from the configuration
212    #[allow(dead_code)] // API for future use
213    pub fn remove_node(&mut self, name: &str) {
214        self.0
215            .retain(|id| NodeSpec::parse(id).map(|s| s.name != name).unwrap_or(true));
216    }
217
218    /// Get the raw list of identifiers
219    #[allow(dead_code)] // API for future use
220    pub fn identifiers(&self) -> &[String] {
221        &self.0
222    }
223
224    /// Check if empty
225    #[allow(dead_code)] // API for future use
226    pub fn is_empty(&self) -> bool {
227        self.0.is_empty()
228    }
229
230    /// Get count of nodes
231    #[allow(dead_code)] // API for future use
232    pub fn len(&self) -> usize {
233        self.0.len()
234    }
235}
236
237/// Behavior tree configuration
238///
239/// Controls behavior tree execution for autonomous robot behaviors.
240#[derive(Debug, Serialize, Deserialize, Clone)]
241pub struct BehaviorsConfig {
242    /// Name of the active behavior to run (e.g., "idle_wander")
243    pub active: String,
244
245    /// Directory containing behavior tree templates (relative to project root)
246    #[serde(default = "default_behaviors_templates_dir")]
247    pub templates_dir: String,
248
249    /// Directory containing behavior configuration files (relative to project root)
250    #[serde(default = "default_behaviors_configs_dir")]
251    pub configs_dir: String,
252
253    /// Executor configuration
254    #[serde(default)]
255    pub executor: BehaviorExecutorConfig,
256}
257
258/// Behavior executor configuration
259///
260/// Controls how the behavior tree executor runs.
261#[derive(Debug, Serialize, Deserialize, Clone)]
262pub struct BehaviorExecutorConfig {
263    /// Tick rate in Hz (how many times per second to tick the behavior tree)
264    #[serde(default = "default_tick_rate_hz")]
265    pub tick_rate_hz: f32,
266
267    /// Maximum number of ticks before stopping (None = run forever)
268    #[serde(default)]
269    pub max_ticks: Option<usize>,
270
271    /// Whether to log execution statistics
272    #[serde(default = "default_log_stats")]
273    pub log_stats: bool,
274}
275
276impl Default for BehaviorExecutorConfig {
277    fn default() -> Self {
278        Self {
279            tick_rate_hz: default_tick_rate_hz(),
280            max_ticks: None,
281            log_stats: default_log_stats(),
282        }
283    }
284}
285
286fn default_behaviors_templates_dir() -> String {
287    "behaviors".to_string()
288}
289
290fn default_behaviors_configs_dir() -> String {
291    "configs".to_string()
292}
293
294fn default_tick_rate_hz() -> f32 {
295    10.0
296}
297
298fn default_log_stats() -> bool {
299    true
300}
301
302#[derive(Debug, Serialize, Deserialize, Default)]
303pub struct ServicesConfig {
304    #[serde(default)]
305    pub http_api: Option<HttpApiServiceConfig>,
306    #[serde(default)]
307    pub database: Option<DatabaseServiceConfig>,
308    #[serde(default)]
309    pub job_processor: Option<JobProcessorServiceConfig>,
310    #[serde(default)]
311    pub scheduler: Option<SchedulerServiceConfig>,
312}
313
314#[derive(Debug, Serialize, Deserialize, Clone)]
315pub struct HttpApiServiceConfig {
316    pub host: String,
317    pub port: u16,
318    #[serde(default = "default_enable_cors")]
319    pub _enable_cors: bool,
320}
321
322#[derive(Debug, Serialize, Deserialize, Clone)]
323pub struct DatabaseServiceConfig {
324    pub url: String,
325    #[serde(default = "default_max_connections")]
326    pub max_connections: u32,
327    #[serde(default = "default_timeout_seconds")]
328    pub timeout_seconds: u64,
329}
330
331#[derive(Debug, Serialize, Deserialize, Clone)]
332pub struct JobProcessorServiceConfig {
333    #[serde(default = "default_worker_count")]
334    pub worker_count: usize,
335    #[serde(default = "default_max_queue_size")]
336    pub max_queue_size: usize,
337}
338
339#[derive(Debug, Serialize, Deserialize, Clone)]
340pub struct SchedulerServiceConfig {
341    pub tasks: Vec<ScheduledTaskConfig>,
342}
343
344#[derive(Debug, Serialize, Deserialize, Clone)]
345#[allow(dead_code)]
346pub struct ScheduledTaskConfig {
347    pub name: String,
348    pub cron: String,
349    pub topic: String,
350    pub payload: String,
351}
352
353#[derive(Debug, Serialize, Deserialize)]
354pub struct RobotConfig {
355    pub id: String,
356    #[serde(default)]
357    pub platform: Option<String>,
358    #[serde(default)]
359    pub description: Option<String>,
360}
361
362/// Project-level simulation configuration stored in mecha10.json
363///
364/// This controls simulation settings for the project, distinct from
365/// the runtime simulation config loaded from configs/{profile}/simulation/.
366#[derive(Debug, Serialize, Deserialize, Clone)]
367pub struct ProjectSimulationConfig {
368    /// Whether simulation is enabled for this project
369    #[serde(default = "default_simulation_enabled")]
370    pub enabled: bool,
371
372    /// Config profile to use (dev, production, staging, etc.)
373    #[serde(default = "default_config_profile")]
374    pub config_profile: String,
375
376    /// Optional scenario name (loads configs/{profile}/simulation/{scenario}.json)
377    /// If not specified, loads configs/{profile}/simulation/config.json
378    #[serde(default, skip_serializing_if = "Option::is_none")]
379    pub scenario: Option<String>,
380
381    // DEPRECATED: Legacy fields for backwards compatibility
382    // These are ignored if config_profile is set
383    #[serde(default, skip_serializing_if = "Option::is_none")]
384    pub model: Option<String>,
385    #[serde(default, skip_serializing_if = "Option::is_none")]
386    pub model_config: Option<String>,
387    #[serde(default, skip_serializing_if = "Option::is_none")]
388    pub environment: Option<String>,
389    #[serde(default, skip_serializing_if = "Option::is_none")]
390    pub environment_config: Option<String>,
391}
392
393fn default_simulation_enabled() -> bool {
394    true
395}
396
397fn default_config_profile() -> String {
398    "dev".to_string()
399}
400
401/// Lifecycle configuration for mode-based node management
402///
403/// Enables dynamic node lifecycle based on operational modes.
404/// Each mode defines which nodes should run in that context.
405#[derive(Debug, Serialize, Deserialize, Clone)]
406pub struct LifecycleConfig {
407    /// Available operational modes
408    pub modes: std::collections::HashMap<String, ModeConfig>,
409
410    /// Default mode on startup
411    #[serde(default = "default_lifecycle_mode")]
412    pub default_mode: String,
413}
414
415/// Configuration for a single operational mode
416///
417/// Defines which nodes should run in this mode.
418#[derive(Debug, Serialize, Deserialize, Clone)]
419pub struct ModeConfig {
420    /// Human-readable description of this mode
421    #[serde(default, skip_serializing_if = "Option::is_none")]
422    pub description: Option<String>,
423
424    /// Nodes that should run in this mode
425    pub nodes: Vec<String>,
426}
427
428fn default_lifecycle_mode() -> String {
429    "startup".to_string()
430}
431
432// Validation for lifecycle configuration
433impl LifecycleConfig {
434    /// Validate lifecycle configuration against available nodes
435    ///
436    /// # Arguments
437    ///
438    /// * `available_nodes` - List of node names defined in project config
439    ///
440    /// # Errors
441    ///
442    /// Returns error if:
443    /// - Default mode doesn't exist in modes
444    /// - Any mode references undefined nodes
445    #[allow(dead_code)] // Will be used in Phase 3
446    pub fn validate(&self, available_nodes: &[String]) -> Result<()> {
447        // Check that default mode exists
448        if !self.modes.contains_key(&self.default_mode) {
449            return Err(anyhow::anyhow!(
450                "Default mode '{}' not found in modes. Available modes: {}",
451                self.default_mode,
452                self.modes.keys().map(|k| k.as_str()).collect::<Vec<_>>().join(", ")
453            ));
454        }
455
456        // Validate each mode
457        for (mode_name, mode_config) in &self.modes {
458            mode_config.validate(mode_name, available_nodes)?;
459        }
460
461        Ok(())
462    }
463}
464
465impl ModeConfig {
466    /// Validate mode configuration against available nodes
467    ///
468    /// # Arguments
469    ///
470    /// * `mode_name` - Name of this mode (for error messages)
471    /// * `available_nodes` - List of node names defined in project config
472    ///
473    /// # Errors
474    ///
475    /// Returns error if any referenced node doesn't exist in project config
476    #[allow(dead_code)] // Will be used in Phase 3
477    pub fn validate(&self, mode_name: &str, available_nodes: &[String]) -> Result<()> {
478        // Check all nodes exist
479        for node in &self.nodes {
480            if !available_nodes.contains(node) {
481                return Err(anyhow::anyhow!(
482                    "Mode '{}': node '{}' not found in project configuration. Available nodes: {}",
483                    mode_name,
484                    node,
485                    available_nodes.join(", ")
486                ));
487            }
488        }
489
490        Ok(())
491    }
492}
493
494/// Docker services configuration for project-level Docker Compose management
495#[derive(Debug, Serialize, Deserialize, Default, Clone)]
496pub struct DockerServicesConfig {
497    /// Services needed for on-robot execution (typically just Redis for message passing)
498    #[serde(default)]
499    pub robot: Vec<String>,
500
501    /// Services needed for edge/remote execution (Redis + databases, etc.)
502    #[serde(default)]
503    pub edge: Vec<String>,
504
505    /// Path to docker-compose.yml relative to project root
506    #[serde(default = "default_compose_file")]
507    pub compose_file: String,
508
509    /// Whether to auto-start services in dev mode
510    #[serde(default = "default_auto_start")]
511    pub auto_start: bool,
512}
513
514/// Environment-specific configuration
515///
516/// Allows configuring different URLs for dev, staging, and production environments.
517/// The active environment is determined by:
518/// 1. `MECHA10_ENV` environment variable
519/// 2. `--env` CLI flag
520/// 3. Default: "dev" when running `mecha10 dev`, "prod" otherwise
521#[derive(Debug, Serialize, Deserialize, Clone)]
522pub struct EnvironmentsConfig {
523    /// Development environment (local control plane)
524    #[serde(default = "default_dev_environment")]
525    pub dev: EnvironmentConfig,
526
527    /// Staging environment (optional)
528    #[serde(default, skip_serializing_if = "Option::is_none")]
529    pub staging: Option<EnvironmentConfig>,
530
531    /// Production environment (cloud control plane)
532    #[serde(default = "default_prod_environment")]
533    pub prod: EnvironmentConfig,
534}
535
536impl Default for EnvironmentsConfig {
537    fn default() -> Self {
538        Self {
539            dev: default_dev_environment(),
540            staging: None,
541            prod: default_prod_environment(),
542        }
543    }
544}
545
546impl EnvironmentsConfig {
547    /// Get the environment config for the given environment name
548    pub fn get(&self, env: &str) -> Option<&EnvironmentConfig> {
549        match env {
550            "dev" | "development" => Some(&self.dev),
551            "staging" => self.staging.as_ref(),
552            "prod" | "production" => Some(&self.prod),
553            _ => None,
554        }
555    }
556
557    /// Get the current environment config based on MECHA10_ENV
558    pub fn current(&self) -> &EnvironmentConfig {
559        let env = std::env::var("MECHA10_ENV").unwrap_or_else(|_| "dev".to_string());
560        self.get(&env).unwrap_or(&self.dev)
561    }
562
563    /// Get the control plane URL for the current environment
564    pub fn control_plane_url(&self) -> String {
565        std::env::var("MECHA10_CONTROL_PLANE_URL").unwrap_or_else(|_| self.current().control_plane.clone())
566    }
567
568    /// Get the API URL for the current environment
569    /// Derived: {control_plane}/api
570    #[allow(dead_code)]
571    pub fn api_url(&self) -> String {
572        format!("{}/api", self.control_plane_url())
573    }
574
575    /// Get the dashboard URL for the current environment
576    /// Derived: {control_plane}/dashboard
577    pub fn dashboard_url(&self) -> String {
578        std::env::var("MECHA10_DASHBOARD_URL").unwrap_or_else(|_| format!("{}/dashboard", self.control_plane_url()))
579    }
580
581    /// Get the WebRTC relay URL for the current environment
582    /// Derived: ws(s)://{control_plane_host}/webrtc-relay
583    pub fn relay_url(&self) -> String {
584        if let Ok(url) = std::env::var("WEBRTC_RELAY_URL") {
585            return url;
586        }
587
588        let control_plane = self.control_plane_url();
589        // Convert http(s) to ws(s)
590        let ws_url = if control_plane.starts_with("https://") {
591            control_plane.replace("https://", "wss://")
592        } else if control_plane.starts_with("http://") {
593            control_plane.replace("http://", "ws://")
594        } else {
595            control_plane
596        };
597        format!("{}/webrtc-relay", ws_url)
598    }
599
600    /// Get the Redis URL (always local, env var override)
601    pub fn redis_url(&self) -> String {
602        std::env::var("REDIS_URL").unwrap_or_else(|_| "redis://localhost:6379".to_string())
603    }
604}
605
606/// Configuration for a specific environment
607#[derive(Debug, Serialize, Deserialize, Clone)]
608pub struct EnvironmentConfig {
609    /// Control plane base URL (e.g., "http://localhost:8100" or "https://mecha.industries")
610    pub control_plane: String,
611}
612
613fn default_dev_environment() -> EnvironmentConfig {
614    EnvironmentConfig {
615        control_plane: "http://localhost:8100".to_string(),
616    }
617}
618
619fn default_prod_environment() -> EnvironmentConfig {
620    EnvironmentConfig {
621        control_plane: "https://mecha.industries".to_string(),
622    }
623}
624
625// Default value functions
626fn default_enable_cors() -> bool {
627    true
628}
629
630fn default_max_connections() -> u32 {
631    10
632}
633
634fn default_timeout_seconds() -> u64 {
635    30
636}
637
638fn default_worker_count() -> usize {
639    4
640}
641
642fn default_max_queue_size() -> usize {
643    100
644}
645
646fn default_compose_file() -> String {
647    "docker-compose.yml".to_string()
648}
649
650fn default_auto_start() -> bool {
651    true
652}
653
654/// Load robot_id from mecha10.json
655#[allow(dead_code)]
656pub async fn load_robot_id(config_path: &PathBuf) -> Result<String> {
657    let content = tokio::fs::read_to_string(config_path)
658        .await
659        .context("Failed to read mecha10.json")?;
660
661    let config: ProjectConfig = serde_json::from_str(&content).context("Failed to parse mecha10.json")?;
662
663    Ok(config.robot.id)
664}
665
666/// Load full project config from mecha10.json
667pub async fn load_project_config(config_path: &PathBuf) -> Result<ProjectConfig> {
668    let content = tokio::fs::read_to_string(config_path)
669        .await
670        .context("Failed to read mecha10.json")?;
671
672    let config: ProjectConfig = serde_json::from_str(&content).context("Failed to parse mecha10.json")?;
673
674    Ok(config)
675}
mecha10_cli/types/project.rs

mecha10_cli/types/
project.rs
