Mountain/Environment/

DebugProvider.rs

//! # DebugProvider (Environment)
//!
//! RESPONSIBILITIES:
//! - Implements [`DebugService`](CommonLibrary::Debug::DebugService) for
//!   [`MountainEnvironment`]
//! - Manages complete debugging session lifecycle from configuration to
//!   termination
//! - Orchestrates between extension host (Cocoon), debug adapter, and UI
//! - Handles DAP (Debug Adapter Protocol) message mediation
//!
//! ARCHITECTURAL ROLE:
//! - Core provider for debugging functionality, analogous to VSCode's debug
//!   service
//! - Uses two-stage registration: configuration providers and adapter
//!   descriptor factories
//! - Each debug type (node, java, rust) can have its own configuration and
//!   adapter
//! - Integrates with [`IPCProvider`](CommonLibrary::IPC::IPCProvider) for RPC
//!   to Cocoon
//!
//! DEBUG SESSION FLOW:
//! 1. UI calls `StartDebugging` with folder URI and configuration
//! 2. Mountain RPCs to Cocoon to resolve debug configuration (variable
//!    substitution)
//! 3. Mountain RPCs to Cocoon to create debug adapter descriptor
//! 4. Mountain spawns debug adapter process or connects to TCP server
//! 5. Mountain mediates DAP messages between UI and debug adapter
//! 6. UI sends DAP commands via `SendCommand` which forwards to adapter
//! 7. Debug adapter sends DAP events/notifications back through Mountain to UI
//! 8. Session ends on stop request or adapter process exit
//!
//! ERROR HANDLING:
//! - Uses [`CommonError`](CommonLibrary::Error::CommonError) for all operations
//! - Validates debug type is non-empty (InvalidArgument error)
//! - TODO: Implement proper session lookup, timeout handling, and error
//!   recovery
//!
//! PERFORMANCE:
//! - Debug adapter spawning should be async with timeout protection (5000ms in
//!   current RPC)
//! - DAP message routing needs efficient session lookup (TODO: O(1) hash map)
//! - Multiple simultaneous debug sessions require careful resource management
//!
//! VS CODE REFERENCE:
//! - `vs/workbench/contrib/debug/browser/debugService.ts` - debug service main
//!   logic
//! - `vs/workbench/contrib/debug/common/debug.ts` - debug interfaces and models
//! - `vs/workbench/contrib/debug/browser/adapter/descriptorFactory.ts` -
//!   adapter descriptor factories
//! - `vs/debugAdapter/common/debugProtocol.ts` - DAP protocol specification
//!
//! TODO:
//! - Store debug adapter registrations in ApplicationState
//! - Implement proper debug session tracking and management
//! - Add debug adapter process spawning and lifecycle management
//! - Implement proper DAP message routing and serialization
//! - Add debug session state persistence across UI reloads
//! - Implement debug console and variable inspection integration
//! - Add support for multiple simultaneous debug sessions
//! - Implement debug adapter termination and cleanup
//! - Add debug session metrics and telemetry
//! - Consider implementing debug configuration validation
//! - Add support for debug adapters that communicate via TCP sockets
//! - Implement debug adapter crash detection and recovery
//!
//! MODULE CONTENTS:
//! - [`DebugService`](CommonLibrary::Debug::DebugService) implementation:
//! - `RegisterDebugConfigurationProvider` - register config resolver
//! - `RegisterDebugAdapterDescriptorFactory` - register adapter factory
//! - `StartDebugging` - start debug session (partial)
//! - `SendCommand` - send DAP command to adapter (stub)

use std::sync::Arc;

use CommonLibrary::{
	Debug::DebugService::DebugService,
	Environment::Requires::Requires,
	Error::CommonError::CommonError,
	IPC::{DTO::ProxyTarget::ProxyTarget, IPCProvider::IPCProvider},
};
use async_trait::async_trait;
use serde_json::{Value, json};
use url::Url;

use super::MountainEnvironment::MountainEnvironment;
use crate::dev_log;

#[async_trait]
impl DebugService for MountainEnvironment {
	async fn RegisterDebugConfigurationProvider(
		&self,

		DebugType:String,

		ProviderHandle:u32,

		SideCarIdentifier:String,
	) -> Result<(), CommonError> {
		// Validate debug type is non-empty
		if DebugType.is_empty() {
			return Err(CommonError::InvalidArgument {
				ArgumentName:"DebugType".to_string(),
				Reason:"DebugType cannot be empty".to_string(),
			});
		}

		dev_log!(
			"exthost",
			"[DebugProvider] Registering DebugConfigurationProvider for type '{}' (handle: {}, sidecar: {})",
			DebugType,
			ProviderHandle,
			SideCarIdentifier
		);

		// Store debug configuration provider registration in ApplicationState
		self.ApplicationState
			.Feature
			.Debug
			.RegisterDebugConfigurationProvider(DebugType, ProviderHandle, SideCarIdentifier)
			.map_err(|e| CommonError::Unknown { Description:e })?;

		Ok(())
	}

	async fn RegisterDebugAdapterDescriptorFactory(
		&self,

		DebugType:String,

		FactoryHandle:u32,

		SideCarIdentifier:String,
	) -> Result<(), CommonError> {
		// Validate debug type is non-empty
		if DebugType.is_empty() {
			return Err(CommonError::InvalidArgument {
				ArgumentName:"DebugType".to_string(),
				Reason:"DebugType cannot be empty".to_string(),
			});
		}

		dev_log!(
			"exthost",
			"[DebugProvider] Registering DebugAdapterDescriptorFactory for type '{}' (handle: {}, sidecar: {})",
			DebugType,
			FactoryHandle,
			SideCarIdentifier
		);

		// Store debug adapter descriptor factory registration in ApplicationState
		self.ApplicationState
			.Feature
			.Debug
			.RegisterDebugAdapterDescriptorFactory(DebugType, FactoryHandle, SideCarIdentifier)
			.map_err(|e| CommonError::Unknown { Description:e })?;

		Ok(())
	}

	async fn StartDebugging(&self, _FolderURI:Option<Url>, Configuration:Value) -> Result<String, CommonError> {
		let SessionID = uuid::Uuid::new_v4().to_string();
		dev_log!(
			"exthost",
			"[DebugProvider] Starting debug session '{}' with config: {:?}",
			SessionID,
			Configuration
		);

		let IPCProvider:Arc<dyn IPCProvider> = self.Require();
		let DebugType = Configuration
			.get("type")
			.and_then(Value::as_str)
			.ok_or_else(|| {
				CommonError::InvalidArgument {
					ArgumentName:"Configuration".into(),

					Reason:"Missing 'type' field in debug configuration.".into(),
				}
			})?
			.to_string();

		// TODO: Look up which sidecar (extension) handles this debug type using
		// the registration stored in ApplicationState. The mapping should be based
		// on previous RegisterDebugConfigurationProvider calls. Initial stub uses
		// hardcoded "cocoon-main" until proper registration tracking is implemented.
		let TargetSideCar = "cocoon-main".to_string();

		// 1. Resolve configuration (Reverse-RPC to Cocoon)
		dev_log!(
			"exthost",
			"[DebugProvider] Resolving debug configuration for type '{}'",
			DebugType
		);
		dev_log!("exthost", "[DebugProvider] Resolving debug configuration...");
		let ResolveConfigMethod = format!("{}$resolveDebugConfiguration", ProxyTarget::ExtHostDebug.GetTargetPrefix());
		let ResolvedConfig = IPCProvider
			.SendRequestToSideCar(
				TargetSideCar.clone(),
				ResolveConfigMethod,
				json!([DebugType.clone(), Configuration]),
				5000,
			)
			.await?;

		// 2. Get the Debug Adapter Descriptor (Reverse-RPC to Cocoon)
		dev_log!("exthost", "[DebugProvider] Creating debug adapter descriptor...");
		let CreateDescriptorMethod =
			format!("{}$createDebugAdapterDescriptor", ProxyTarget::ExtHostDebug.GetTargetPrefix());
		let Descriptor = IPCProvider
			.SendRequestToSideCar(
				TargetSideCar.clone(),
				CreateDescriptorMethod,
				json!([DebugType, &ResolvedConfig]),
				5000,
			)
			.await?;

		// 3. Spawn the Debug Adapter process based on the descriptor.
		dev_log!(
			"exthost",
			"[DebugProvider] Spawning Debug Adapter based on descriptor: {:?}",
			Descriptor
		);

		// TODO: Implement full debug adapter spawning based on the descriptor.
		// A complete implementation would:
		// - Parse the DebugAdapterDescriptor (executable path, command args,
		//   environment variables, or server port for TCP connection)
		// - Spawn a new OS process with stdio pipes using Command or connect to a TCP
		//   socket if using debug adapter server mode
		// - Create a new DebugSession struct to manage the DAP (Debug Adapter Protocol)
		//   communication stream, handling JSON-RPC message framing
		// - Establish bidirectional JSON-RPC communication with the debug adapter
		// - Store the active session in ApplicationState keyed by session_id for later
		//   command routing and session management
		// - Implement proper session cleanup on termination (kill process, close
		//   sockets, remove from ApplicationState, emit exit events)
		// - Handle adapter launch failures with descriptive error messages and proper
		//   session state cleanup

		dev_log!("exthost", "[DebugProvider] Debug session '{}' started (simulation).", SessionID);
		Ok(SessionID)
	}

	async fn SendCommand(&self, SessionID:String, Command:String, Arguments:Value) -> Result<Value, CommonError> {
		dev_log!(
			"exthost",
			"[DebugProvider] SendCommand for session '{}' (command: '{}', args: {:?})",
			SessionID,
			Command,
			Arguments
		);

		// TODO: Implement proper debug session management to route commands to
		// active debug adapters. Should:
		// - Look up session by SessionID in ApplicationState's debug session registry
		// - Validate session exists and is in active state (not terminated or crashed)
		// - Serialize command and arguments to JSON-RPC 2.0 format with proper request
		//   sequencing (seq number)
		// - Send the request to debug adapter via stdio pipes or TCP socket
		// - Wait for response with appropriate timeout, handle cancellation requests
		// - Deserialize JSON-RPC response and return the result body to the caller
		// - Handle timeouts, adapter crashes, and protocol errors gracefully with
		//   informative error messages and session cleanup as needed

		// For now, return a placeholder response indicating debug session is active
		let response = serde_json::json!({
			"success": true,
			"session_id": SessionID,
			"command": Command,
			"response": {
				"type": "response",
				"request_seq": 1,
				"success": true,
				"command": Command,
				"body": {}
			}
		});

		Ok(response)
	}
}