Welcome to the Land project! This document provides a high-level overview of the architecture and the core workflows that drive the application. Our system is composed of three primary components:

• Common 👨🏻‍🏭 (Rust Crate): The abstract core library. It defines the architectural "language" of the application through traits, data structures (DTOs), and a declarative Effect system. It has no knowledge of the final implementation.
• Mountain ⛰️ (Rust Application): The native backend. It is a Tauri application that implements the abstract traits from Common, manages the native OS interactions, runs a gRPC server, and orchestrates the Cocoon sidecar process.
• Wind 🍃 & Sky 🌌 (TypeScript UI): The frontend. Wind is a re-implementation of the VS Code workbench services using Effect-TS, providing the application logic for the UI. Sky is the declarative UI component layer (e.g., React, Vue) that renders the state managed by Wind.
• Cocoon 🦋 (TypeScript Application): A Node.js sidecar process managed by Mountain. It is responsible for running extensions in a sandboxed environment and providing them with a high-fidelity vscode API.

Communication between Mountain and Cocoon is handled via gRPC, while communication between Mountain and Wind/Sky is handled via Tauri Events and Commands.

1. Application Startup & Handshake

   • Describes the complete end-to-end process of launching Mountain, spawning Cocoon, and establishing a stable, initialized state for both the UI and the extension host.

2. Opening a File from the UI

   • Details the flow from a user clicking a file in the explorer to the content being read from disk by Mountain and rendered in an editor by Wind.

3. Invoking a Language Feature (Hover Provider)

   • A key example of bi-directional communication, showing how an extension in Cocoon registers a feature, Mountain orchestrates the request, and the result is displayed in the Wind UI.

4. Saving a File with Save Participants

   • Explains the advanced process of intercepting a save event, allowing an extension in Cocoon to modify a file (e.g., for formatting) before Mountain writes it to disk.

5. Executing a Command from the Command Palette

   • Illustrates the unified command system, showing how Mountain's command registry can seamlessly dispatch execution to either a native Rust handler or a proxied command in Cocoon.

6. Creating and Interacting with a Webview Panel

   • Details the full lifecycle of extension-contributed UI, from Cocoon requesting a panel to Mountain managing the native webview window and proxying messages back and forth.

7. Creating and Interacting with an Integrated Terminal

   • A deep dive into native process management, showing how Mountain spawns a PTY process and streams its I/O to both the Wind frontend and the Cocoon extension host.

8. Source Control Management (SCM)

   • Outlines how the built-in Git extension in Cocoon uses Mountain as a service to run native git commands and then populates the SCM view in the UI with the results.

9. User Data Synchronization

   • Describes the end-to-end process of syncing user settings. It covers user authentication, fetching data from a remote store, performing a three-way merge, applying changes locally, and notifying all parts of the application.

10. Running Extension Tests

    • Explains the "Extension Development Host" model, where a second, isolated instance of the application is launched to run tests, with the test Cocoon instance remote-controlling the main UI.

11. Tier-Gated Implementation Selection

    • Describes how the .env.Land file propagates through Maintain's build script into Mountain's build.rs, Cocoon's esbuild define map, and Sky's Vite define map — allowing each capability with more than one viable implementation (gRPC vs native, JS glob vs globset, etc.) to live in the codebase simultaneously and be selected at build time without duplicating call sites.

The following workflows are implemented in the codebase but are pending detailed documentation.

• Tree View Data Flow
  • Describes how the UI requests children for a tree view node, and how Mountain proxies this request to the correct TreeDataProvider in Cocoon.
• Custom Editor Lifecycle
  • Details the process of opening a file in a custom editor, handling edits, saving custom document data, and managing backups and reverts.
• Debugging Session Lifecycle
  • Outlines the flow from launching a debug configuration to Mountain starting a debug adapter, and how debug events (breakpoints, step, pause) are communicated between the UI, Mountain, and Cocoon.
• Task Execution
  • Explains how tasks defined in tasks.json or by extensions are discovered and executed, including how their output is piped to a terminal view.