feat(Common): Implement abstract core architecture with traits and effects

This commit establishes the entire abstract core of the Land project as defined in the final architecture. It includes:
1. **Effect System**: Added `ActionEffect` struct and `ApplicationRunTime` trait for declarative effect handling
2. **Environment**: Implemented `Environment`, `HasEnvironment`, and `Requires` traits for capability-based dependency injection
3. **Service Contracts**: Defined traits for all 20+ services (Command, Configuration, Document, FileSystem, IPC, etc.) with:
   - Abstract service traits (e.g., `CommandExecutor`, `DocumentProvider`)
   - Data Transfer Objects (DTOs) for cross-boundary communication
   - `ActionEffect` constructors for all operations
4. **Error Handling**: Added comprehensive `CommonError` enum with IO, configuration, and service-specific variants

These changes create the architectural foundation for:
- The `Mountain` backend to implement Rust-native service handlers
- The `Cocoon` sidecar to communicate via gRPC using these contracts
- The `Wind`/`Sky` UI layer to execute effects via Tauri commands

The implementation enables type-safe, declarative programming across the entire stack using the effects-based paradigm.

Author: NikolaRHristov

CONTRIBUTING.md

@@ -47,7 +47,7 @@ response to any behavior that they deem inappropriate, threatening, offensive,
 or harmful. Community leaders have the right and responsibility to remove, edit,
 or reject comments, commits, code, wiki edits, issues, and other contributions
 that are not aligned with this Code of Conduct, and will communicate reasons for
-moderation decisions when appropriate.
+pub moderation decisions when appropriate.
 
 ## Scope
 

Cargo.toml

@@ -6,6 +6,7 @@ toml = { version = "0.8.20" }
 async-trait = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
+thiserror.workspace = true
 url = { workspace = true }
 
 

Source/Command/CommandExecutor.rs

@@ -0,0 +1,48 @@
+//! # CommandExecutor Trait
+//!
+//! Defines the abstract service trait for command management and execution
+//! capabilities.
+
+use async_trait::async_trait;
+use serde_json::Value;
+
+use crate::{Environment::Environment::Environment, Error::CommonError::CommonError};
+
+/// An abstract service contract for an environment component that can execute
+/// and manage commands within the application.
+///
+/// This trait is implemented by the concrete `MountainEnvironment` and provides
+/// the core logic for the command palette and programmatic command execution.
+/// It is designed to handle both native commands implemented in Rust and
+/// proxied commands implemented in external sidecars.
+#[async_trait]
+pub trait CommandExecutor: Environment + Send + Sync {
+	/// Executes a command with the given identifier and arguments.
+	///
+	/// # Parameters
+	///
+	/// * `CommandIdentifier`: The unique ID of the command to execute.
+	/// * `Argument`: A `serde_json::Value` containing the arguments for the
+	///   command.
+	///
+	/// # Returns
+	///
+	/// A `Result` containing the command's return value as a
+	/// `serde_json::Value` on success, or a `CommonError` on failure.
+	async fn ExecuteCommand(&self, CommandIdentifier:String, Argument:Value) -> Result<Value, CommonError>;
+
+	/// Registers a command that is implemented in an external sidecar process.
+	///
+	/// # Parameters
+	///
+	/// * `SidecarIdentifier`: The unique ID of the sidecar where the command
+	///   logic resides.
+	/// * `CommandIdentifier`: The unique ID of the command being registered.
+	async fn RegisterCommand(&self, SidecarIdentifier:String, CommandIdentifier:String) -> Result<(), CommonError>;
+
+	/// Unregisters a previously registered command.
+	async fn UnregisterCommand(&self, SidecarIdentifier:String, CommandIdentifier:String) -> Result<(), CommonError>;
+
+	/// Retrieves a list of all currently registered command identifiers.
+	async fn GetAllCommands(&self) -> Result<Vec<String>, CommonError>;
+}

Source/Command/ExecuteCommand.rs

@@ -0,0 +1,52 @@
+//! # ExecuteCommand Effect
+//!
+//! Defines the `ActionEffect` for executing a registered command.
+
+use std::sync::Arc;
+
+use serde_json::Value;
+
+use super::CommandExecutor::CommandExecutor;
+use crate::{
+	Effect::{ActionEffect::ActionEffect, ApplicationRunTime::ApplicationRunTime},
+	Environment::Requires::Requires,
+	Error::CommonError::CommonError,
+};
+
+/// Creates an effect that, when executed, will run a command by its unique
+/// identifier.
+///
+/// It uses the `CommandExecutor` capability from the environment to dispatch
+/// the command to the appropriate handler, whether that handler is a native
+
+/// Rust function or a proxied function in an external sidecar process.
+///
+/// # Parameters
+///
+/// * `CommandIdentifier`: The unique ID of the command to execute (e.g.,
+///   "FileSystem.ReadFile").
+/// * `Argument`: A `serde_json::Value` containing the arguments for the
+///   command.
+///
+/// # Returns
+///
+/// An `ActionEffect` that resolves with the command's return value as a
+/// `serde_json::Value`, or a `CommonError` if the command is not found or fails
+/// during execution.
+pub fn ExecuteCommand<TRunTime>(
+	CommandIdentifier:String,
+	Argument:Value,
+) -> ActionEffect<Arc<TRunTime>, CommonError, Value>
+where
+	TRunTime: ApplicationRunTime + Send + Sync + 'static,
+	TRunTime::EnvironmentType: Requires<Arc<dyn CommandExecutor>>, {
+	ActionEffect::New(Arc::new(move |RunTime:Arc<TRunTime>| {
+		let CommandIdentifierClone = CommandIdentifier.clone();
+		let ArgumentClone = Argument.clone();
+		Box::pin(async move {
+			let Environment = RunTime.GetEnvironment();
+			let Executor:Arc<dyn CommandExecutor> = Environment.Require();
+			Executor.ExecuteCommand(CommandIdentifierClone, ArgumentClone).await
+		})
+	}))
+}

Source/Command/GetAllCommands.rs

@@ -0,0 +1,37 @@
+//! # GetAllCommands Effect
+//!
+//! Defines the `ActionEffect` for retrieving all registered command
+//! identifiers.
+
+use std::sync::Arc;
+
+use super::CommandExecutor::CommandExecutor;
+use crate::{
+	Effect::{ActionEffect::ActionEffect, ApplicationRunTime::ApplicationRunTime},
+	Environment::Requires::Requires,
+	Error::CommonError::CommonError,
+};
+
+/// Creates an effect that, when executed, will retrieve a list of all currently
+/// registered command identifiers.
+///
+/// This includes both native commands implemented in Rust and proxied commands
+/// contributed by external sidecars. It uses the `CommandExecutor` capability
+/// from the environment to perform the operation.
+///
+/// # Returns
+///
+/// An `ActionEffect` that resolves with a `Vec<String>` of command
+/// identifiers.
+pub fn GetAllCommands<TRunTime>() -> ActionEffect<Arc<TRunTime>, CommonError, Vec<String>>
+where
+	TRunTime: ApplicationRunTime + Send + Sync + 'static,
+	TRunTime::EnvironmentType: Requires<Arc<dyn CommandExecutor>>, {
+	ActionEffect::New(Arc::new(move |RunTime:Arc<TRunTime>| {
+		Box::pin(async move {
+			let Environment = RunTime.GetEnvironment();
+			let Executor:Arc<dyn CommandExecutor> = Environment.Require();
+			Executor.GetAllCommands().await
+		})
+	}))
+}

Source/Command/RegisterCommand.rs

@@ -0,0 +1,49 @@
+//! # RegisterCommand Effect
+//!
+//! Defines the `ActionEffect` for registering a command that is implemented in
+//! an external sidecar process.
+
+use std::sync::Arc;
+
+use super::CommandExecutor::CommandExecutor;
+use crate::{
+	Effect::{ActionEffect::ActionEffect, ApplicationRunTime::ApplicationRunTime},
+	Environment::Requires::Requires,
+	Error::CommonError::CommonError,
+};
+
+/// Creates an effect that, when executed, will register a command that is
+/// implemented in a sidecar process like Cocoon.
+///
+/// This allows the host application (`Mountain`) to know about commands
+/// contributed by extensions so they can be displayed in the command palette
+/// and invoked correctly. The `CommandExecutor` implementation will typically
+/// store this as a `Proxied` command handler.
+///
+/// # Parameters
+///
+/// * `SidecarIdentifier`: The unique ID of the sidecar where the command logic
+///   resides.
+/// * `CommandIdentifier`: The unique ID of the command itself (e.g.,
+///   "MyExtension.DoSomething").
+///
+/// # Returns
+///
+/// An `ActionEffect` that resolves to `()` on success.
+pub fn RegisterCommand<TRunTime>(
+	SidecarIdentifier:String,
+	CommandIdentifier:String,
+) -> ActionEffect<Arc<TRunTime>, CommonError, ()>
+where
+	TRunTime: ApplicationRunTime + Send + Sync + 'static,
+	TRunTime::EnvironmentType: Requires<Arc<dyn CommandExecutor>>, {
+	ActionEffect::New(Arc::new(move |RunTime:Arc<TRunTime>| {
+		let SidecarIdentifierClone = SidecarIdentifier.clone();
+		let CommandIdentifierClone = CommandIdentifier.clone();
+		Box::pin(async move {
+			let Environment = RunTime.GetEnvironment();
+			let Executor:Arc<dyn CommandExecutor> = Environment.Require();
+			Executor.RegisterCommand(SidecarIdentifierClone, CommandIdentifierClone).await
+		})
+	}))
+}

Source/Command/UnregisterCommand.rs

@@ -0,0 +1,46 @@
+//! # UnregisterCommand Effect
+//!
+//! Defines the `ActionEffect` for unregistering a previously registered
+//! command.
+
+use std::sync::Arc;
+
+use super::CommandExecutor::CommandExecutor;
+use crate::{
+	Effect::{ActionEffect::ActionEffect, ApplicationRunTime::ApplicationRunTime},
+	Environment::Requires::Requires,
+	Error::CommonError::CommonError,
+};
+
+/// Creates an effect that, when executed, will unregister a command from the
+/// host's command registry.
+///
+/// This is typically called when an extension is deactivated or explicitly
+/// disposes of a command registration.
+///
+/// # Parameters
+///
+/// * `SidecarIdentifier`: The unique ID of the sidecar that originally
+///   registered the command.
+/// * `CommandIdentifier`: The unique ID of the command to unregister.
+///
+/// # Returns
+///
+/// An `ActionEffect` that resolves to `()` on success.
+pub fn UnregisterCommand<TRunTime>(
+	SidecarIdentifier:String,
+	CommandIdentifier:String,
+) -> ActionEffect<Arc<TRunTime>, CommonError, ()>
+where
+	TRunTime: ApplicationRunTime + Send + Sync + 'static,
+	TRunTime::EnvironmentType: Requires<Arc<dyn CommandExecutor>>, {
+	ActionEffect::New(Arc::new(move |RunTime:Arc<TRunTime>| {
+		let SidecarIdentifierClone = SidecarIdentifier.clone();
+		let CommandIdentifierClone = CommandIdentifier.clone();
+		Box::pin(async move {
+			let Environment = RunTime.GetEnvironment();
+			let Executor:Arc<dyn CommandExecutor> = Environment.Require();
+			Executor.UnregisterCommand(SidecarIdentifierClone, CommandIdentifierClone).await
+		})
+	}))
+}

Source/Command/mod.rs

@@ -0,0 +1,23 @@
+//! # Command Service
+//!
+//! This module defines the abstract contract for the Command service. It
+//! includes the `CommandExecutor` trait, which outlines the capabilities for
+//! command management, and the `ActionEffect` constructors for all
+//! command-related operations.
+
+#![allow(non_snake_case, non_camel_case_types)]
+
+// --- Trait Definition ---
+pub mod CommandExecutor;
+// pub use self::CommandExecutor::CommandExecutor;
+
+// --- Effect Constructors ---
+pub mod ExecuteCommand;
+pub mod GetAllCommands;
+pub mod RegisterCommand;
+pub mod UnregisterCommand;
+
+// pub use self::ExecuteCommand::ExecuteCommand;
+// pub use self::GetAllCommands::GetAllCommands;
+// pub use self::RegisterCommand::RegisterCommand;
+// pub use self::UnregisterCommand::UnregisterCommand;

Source/Configuration/ConfigurationInspector.rs

@@ -0,0 +1,38 @@
+//! # ConfigurationInspector Trait
+//!
+//! Defines the abstract service trait for inspecting the sources of
+//! configuration values.
+
+use async_trait::async_trait;
+
+use super::DTO::{ConfigurationOverridesDTO::ConfigurationOverridesDTO, InspectResultDataDTO::InspectResultDataDTO};
+use crate::{Environment::Environment::Environment, Error::CommonError::CommonError};
+
+/// An abstract service contract for an environment component that can inspect
+/// a configuration key to provide details about its value in all relevant
+/// scopes (e.g., default, user, workspace) and its final effective value.
+///
+/// This capability is used to power UIs like the "Settings" editor, which
+/// often shows where a particular setting is defined and allows the user to
+/// see inherited values.
+#[async_trait]
+pub trait ConfigurationInspector: Environment + Send + Sync {
+	/// Inspects a configuration key to get its value from all relevant scopes.
+	///
+	/// # Parameters
+	///
+	/// * `Key`: The dot-separated configuration key to inspect.
+	/// * `Overrides`: A DTO specifying scope overrides (e.g., for a specific
+	///   resource or language).
+	///
+	/// # Returns
+	///
+	/// A `Result` containing an `Option<InspectResultDataDTO>`, which holds
+	/// the detailed breakdown of the key's values across all scopes. Returns
+	/// `None` if the key is not found in any configuration source.
+	async fn InspectConfigurationValue(
+		&self,
+		Key:String,
+		Overrides:ConfigurationOverridesDTO,
+	) -> Result<Option<InspectResultDataDTO>, CommonError>;
+}

Source/Configuration/ConfigurationProvider.rs

@@ -0,0 +1,61 @@
+//! # ConfigurationProvider Trait
+//!
+//! Defines the abstract service trait for providing and updating configuration
+//! values.
+
+use async_trait::async_trait;
+use serde_json::Value;
+
+use super::DTO::{ConfigurationOverridesDTO::ConfigurationOverridesDTO, ConfigurationTarget::ConfigurationTarget};
+use crate::{Environment::Environment::Environment, Error::CommonError::CommonError};
+
+/// An abstract service contract for an environment component that can provide
+/// the final, merged configuration values and handle requests to update those
+/// values in their persistent storage (e.g., `settings.json` files).
+#[async_trait]
+pub trait ConfigurationProvider: Environment + Send + Sync {
+	/// Retrieves a configuration value for a given section or key, applying
+	/// specified overrides.
+	///
+	/// This method should return the final, effective value after merging all
+	/// configuration sources (e.g., default, user, workspace) in the correct
+	/// order of precedence.
+	///
+	/// # Parameters
+	///
+	/// * `Section`: An optional, dot-separated key to a specific configuration
+	///   section. If `None`, the entire configuration object should be
+	///   returned.
+	/// * `Overrides`: A DTO specifying scope overrides (e.g., for a specific
+	///   resource or language).
+	///
+	/// # Returns
+	///
+	/// A `Result` containing the requested configuration as a
+	/// `serde_json::Value`.
+	async fn GetConfigurationValue(
+		&self,
+		Section:Option<String>,
+		Overrides:ConfigurationOverridesDTO,
+	) -> Result<Value, CommonError>;
+
+	/// Updates a configuration value at a specific key and target scope.
+	///
+	/// # Parameters
+	///
+	/// * `Key`: The dot-separated configuration key to update.
+	/// * `ValueToSet`: The new `serde_json::Value` to set for the key.
+	/// * `Target`: The `ConfigurationTarget` enum specifying which scope to
+	///   write to (e.g., User, WorkSpace).
+	/// * `Overrides`: A DTO for scope overrides.
+	/// * `ScopeToLanguage`: An optional flag related to language-specific
+	///   settings.
+	async fn UpdateConfigurationValue(
+		&self,
+		Key:String,
+		ValueToSet:Value,
+		Target:ConfigurationTarget,
+		Overrides:ConfigurationOverridesDTO,
+		ScopeToLanguage:Option<bool>,
+	) -> Result<(), CommonError>;
+}