Common/Terminal/
TerminalProvider.rs

1// File: Common/Source/Terminal/TerminalProvider.rs
2// Role: Defines the abstract service trait for creating and managing integrated
3// terminal instances. Responsibilities:
4//   - Provide a contract for creating, showing, hiding, and disposing of
5//     terminals.
6//   - Provide a contract for sending input to terminals and querying their
7//     state.
8
9//! # TerminalProvider Trait
10//!
11//! Defines the abstract service trait for creating and managing integrated
12//! terminal instances.
13
14use async_trait::async_trait;
15use serde_json::Value;
16
17use crate::{Environment::Environment::Environment, Error::CommonError::CommonError};
18
19/// An abstract service contract for an environment component that can manage
20/// integrated terminal processes.
21///
22/// This trait is implemented by `MountainEnvironment`, and its methods are
23/// responsible for spawning and managing native pseudo-terminal (PTY)
24/// processes, handling their I/O, and managing their lifecycle.
25#[async_trait]
26pub trait TerminalProvider: Environment + Send + Sync {
27	/// Creates a new terminal instance with the given options.
28	///
29	/// # Parameters
30	/// * `OptionsValue`: A `serde_json::Value` DTO representing
31	///   `TerminalOptions`, which can specify the name, shell path, arguments,
32
33	///   etc.
34	///
35	/// # Returns
36	/// A `Result` containing a JSON `Value` with details of the created
37	/// terminal (e.g., its ID and process ID), or a `CommonError` on failure.
38	async fn CreateTerminal(&self, OptionsValue:Value) -> Result<Value, CommonError>;
39
40	/// Sends a string of text as input to a specific terminal instance's
41	/// underlying pseudo-terminal process.
42	///
43	/// # Parameters
44	/// * `TerminalId`: The unique identifier of the target terminal.
45	/// * `Text`: The text to send to the terminal's standard input.
46	async fn SendTextToTerminal(&self, TerminalId:u64, Text:String) -> Result<(), CommonError>;
47
48	/// Disposes of a specific terminal instance. This involves terminating the
49	/// underlying shell process and cleaning up any associated resources.
50	///
51	/// # Parameters
52	/// * `TerminalId`: The unique identifier of the terminal to dispose of.
53	async fn DisposeTerminal(&self, TerminalId:u64) -> Result<(), CommonError>;
54
55	/// Shows a terminal in the UI, optionally giving it focus.
56	///
57	/// # Parameters
58	/// * `TerminalId`: The unique identifier of the terminal to show.
59	/// * `PreserveFocus`: If `true`, the terminal panel is revealed but focus
60	///   is not given to it.
61	async fn ShowTerminal(&self, TerminalId:u64, PreserveFocus:bool) -> Result<(), CommonError>;
62
63	/// Hides the terminal panel if the specified terminal is active.
64	///
65	/// # Parameters
66	/// * `TerminalId`: The unique identifier of the terminal to hide.
67	async fn HideTerminal(&self, TerminalId:u64) -> Result<(), CommonError>;
68
69	/// Gets the process ID (PID) of the underlying shell process for a
70	/// terminal.
71	///
72	/// # Parameters
73	/// * `TerminalId`: The unique identifier of the terminal to query.
74	/// # Returns
75	/// An `Option<u32>` with the PID if the process is running, or `None`.
76	async fn GetTerminalProcessId(&self, TerminalId:u64) -> Result<Option<u32>, CommonError>;
77}
Common/Terminal/TerminalProvider.rs

Common/Terminal/
TerminalProvider.rs
