Mountain/Workspace/
mod.rs

1//! # Workspace Module
2//!
3//! Provides workspace-related services including workspace folder management,
4//! `.code-workspace` file parsing, and multi-root workspace support.
5//!
6//! ## RESPONSIBILITIES
7//!
8//! ### 1. Workspace Folder Management
9//! - Track currently open workspace folders
10//! - Support adding, removing, and reordering folders
11//! - Validate folder paths and permissions
12//! - Persist workspace state across sessions
13//!
14//! ### 2. Workspace File Parsing
15//! - Parse `.code-workspace` JSON files
16//! - Extract workspace configuration and settings
17//! - Resolve workspace folder paths
18//! - Validate workspace file structure
19//!
20//! ### 3. Multi-Root Workspace Support
21//! - Manage workspaces with multiple root folders
22//! - Handle folder-specific configuration overrides
23//! - Support workspace-scoped settings
24//! - Merge configuration from multiple sources
25//!
26//! ### 4. Workspace Configuration
27//! - Provide merged workspace configuration
28//! - Support workspace-specific settings
29//! - Integrate with global configuration system
30//! - Handle configuration precedence (workspace > folder > global)
31//!
32//! ### 5. Workspace Trust & Security
33//! - Implement workspace trust validation
34//! - Mark untrusted workspaces with restricted capabilities
35//! - Provide prompt for user to trust/untrust workspaces
36//!
37//! ## ARCHITECTURAL ROLE
38//!
39//! The Workspace module is the **workspace management layer**:
40//!
41//! ```text
42//! UI (Explorer) ──► WorkspaceService ──► ApplicationState ──► Disk
43//!                      │
44//!                      └─► ConfigurationProvider
45//! ```
46//!
47//! ### Position in Mountain
48//! - `Workspace` module: Workspace lifecycle and configuration
49//! - Implements `CommonLibrary::Workspace::WorkspaceProvider` trait
50//! - Accessible via `Environment.Require<dyn WorkspaceProvider>()`
51//!
52//! ### Dependencies
53//! - `ApplicationState`: Stores workspace state
54//! - `ConfigurationProvider`: For workspace settings
55//! - `FileSystemReader`: For reading `.code-workspace` files
56//!
57//! ### Dependents
58//! - `InitializationData`: Uses workspace data for Cocoon initialization
59//! - `ApplicationState`: Stores workspace folders and configuration path
60//! - `Binary::Main`: Sets up workspace from CLI args
61//!
62//! ## WORKSPACE STATE
63//!
64//! Stored in `ApplicationState`:
65//! - `WorkspaceFolders`: `Vec<WorkspaceFolderStateDTO>`
66//! - `WorkspaceConfigurationPath`: Optional PathBuf to `.code-workspace` file
67//! - `IsTrusted`: Trust status flag
68//! - `WindowState`: Window geometry and placement
69//!
70//! ## MULTI-ROOT SUPPORT
71//!
72//! Mountain supports VS Code-style multi-root workspaces:
73//! - Multiple folders can be opened simultaneously
74//! - Each folder has a URI and display name
75//! - Folders are indexed (0-based) for ordering
76//! - Workspace configuration applies to all folders
77//!
78//! ## CONFIGURATION PRECEDENCE
79//!
80//! Configuration sources are merged in this order (later overrides earlier):
81//! 1. Default settings (built-in)
82//! 2. Global user settings (`settings.json`)
83//! 3. Workspace settings (`.code-workspace` file)
84//! 4. Folder settings (`folder/.vscode/settings.json`)
85//! 5. Workspace-specific overrides per folder
86//!
87//! ## VS CODE REFERENCE
88//!
89//! Patterns from VS Code:
90//! - `vs/platform/workspace/common/workspace.ts` - Workspace service
91//! - `vs/platform/workspace/common/workspaceFolders.ts` - Workspace folder
92//!   operations
93//! - `vs/platform/configuration/common/configuration.ts` - Configuration
94//!   merging
95//!
96//! ## ERROR HANDLING
97//!
98//! - Invalid workspace files: Return `CommonError::ConfigurationLoad`
99//! - Permission errors: `CommonError::FileSystemIO`
100//! - Unauthorized workspace: `CommonError::SecurityViolation`
101//! - Missing folders: `CommonError::FileSystemNotFound`
102//!
103//! ## TODO
104//!
105//! - [ ] Implement workspace trust management with user prompts
106//! - [ ] Add workspace template creation and management
107//! - [ ] Support workspace sharing and collaboration features
108//! - [ ] Add workspace statistics (folder count, file count, size)
109//! - [ ] Implement workspace snapshots for quick restore
110//! - [ ] Add workspace local history (file changes over time)
111//! - [ ] Create workspace migration tools for version upgrades
112//! - [ ] Support virtual workspaces (non-file URIs)
113//! - [ ] Add workspace search across all folders
114//! - [ ] Implement workspace-specific extensions
115//!
116//! ## MODULE CONTENTS
117//!
118//! - [`WorkspaceFileService`]: Parsing and serialization of `.code-workspace`
119//!   files
120
121pub mod WorkspaceFileService;