Cocoon 🦋

---

Cocoon 🦋 The Extension Host for Land 🏞️

Welcome to Cocoon, a core component of the Land Code Editor. Cocoon is a specialized Node.js sidecar process meticulously designed to host and execute existing Visual Studio Code extensions. It achieves this by providing a comprehensive, Effect-TS native environment that faithfully replicates the VS Code Extension Host API. This allows Land to leverage the vast and mature VS Code extension ecosystem, offering users a rich and familiar feature set from day one.

Cocoon's primary goal is to enable high compatibility with Node.js-based VS Code extensions. It communicates with the main Rust-based Land backend (Mountain) via gRPC (Vine protocol), ensuring a performant and strongly-typed IPC channel. Cocoon translates extension API calls into declarative Effects that are sent to Mountain for native execution.

---

Key Features & Architectural Highlights 🔐

• Effect-TS Native Architecture: The entire Cocoon application is built with Effect-TS. All services, API shims, and IPC logic are implemented as declarative, composable Layers and Effects, ensuring maximum robustness, testability, and type safety.
• High-Fidelity VSCode API Shims: Provides a comprehensive set of service shims (e.g., for vscode.workspace, vscode.window, vscode.commands) that replicate the behavior of the real VS Code Extension Host.
• gRPC-Powered Communication: All communication with the Mountain backend is handled via gRPC, providing a fast, modern, and strongly-typed contract for all IPC operations.
• Robust Module Interception: Implements high-fidelity interceptors for both CJS require() and ESM import statements, ensuring that calls to the 'vscode' module are correctly sandboxed and routed to the appropriate, extension-specific API instance.
• Process Hardening & Lifecycle Management: Includes sophisticated process patching to handle uncaught exceptions, pipe logs to the host, and automatically terminate if the parent Mountain process exits, ensuring a stable and well-behaved sidecar.

---

Deep Dive & Component Breakdown 🔬

To understand how Cocoon's internal components interact to provide the high-fidelity vscode API, see the following source files:

• Bootstrap/Implementation/CocoonMain.ts - Main entry point and bootstrap orchestration
• Effect/Bootstrap.ts - Effect-TS bootstrap stages (Environment, Configuration, Mountain Connection, Module Interceptor, RPC Server, Extensions, Health Check)
• ServiceMapping.ts - Dependency injection and service composition
• Services/APIFactory.ts - Constructs the vscode API object for extensions
• Services/ExtensionHostService.ts - Extension activation and lifecycle management
• Services/IPCService.ts - Bi-directional gRPC communication
• Services/MountainGRPCClient.ts - gRPC client for Mountain backend
• PatchProcess/ - Process hardening and security
• TypeConverter/ - DTO serialization for gRPC transport

---

Cocoon in the Land Ecosystem 🦋 + 🏞️

Cocoon operates as a standalone Node.js process, carefully orchestrated by and communicating with Mountain.

Component within Cocoon	Role & Key Responsibilities
Node.js Process	The runtime environment for Cocoon.
Bootstrap/Implementation/CocoonMain.ts	The primary entry point. It composes all Effect-TS layers, establishes the gRPC connection, performs the initialization handshake with Mountain, and starts the extension host services.
PatchProcess/	Performs very early process hardening (patching process.exit, handling exceptions, piping logs), ensuring a stable foundation before any other code runs.
Effect/ Modules	Orchestrates the bootstrap process. Bootstrap.ts coordinates initialization stages, Extension.ts manages extension lifecycle, ModuleInterceptor.ts patches require and import, and Telemetry.ts provides logging and tracing.
Services/ Modules	A comprehensive collection of Effect-TS Layers, each implementing a specific VS Code IExtHost... service interface (e.g., CommandsProvider, WorkspaceProvider, WebviewProvider). These shims are the core of the compatibility layer. Key services include APIFactory.ts, ExtensionHostService.ts, IPCService.ts, and MountainGRPCClient.ts.
IPC/ & Services/IPC.ts	IPC/ contains the protocol layer (Channel.ts, Handler.ts, Message.ts, Protocol.ts). Services/IPC.ts implements both the gRPC client (to call Mountain) and server (to receive calls from Mountain), managing the entire bi-directional communication lifecycle.
TypeConverter/	Provides pure functions to serialize TypeScript types into plain DTOs for gRPC transport. Organized by feature: Main/ (URI, Range, TextEdit), Dialog/, TreeView/, Webview/, Task/, WorkspaceEdit/. The actual vscode API class definitions are in the Services/ modules that use them.
Extension Code	The JavaScript/TypeScript code of the VS Code extensions being hosted and run within the Cocoon environment.

Interaction Flow (Example: vscode.window.showInformationMessage)

1. Mountain launches Cocoon with initialization data.
2. Cocoon's Bootstrap/Implementation/CocoonMain.ts bootstraps the application:
   • PatchProcess hardens the environment.
   • Effect/Bootstrap.ts orchestrates the initialization stages (environment detection, configuration, gRPC connection, module interceptor, RPC server, extensions, health check).
   • The main AppLayer is built via ServiceMapping.ts, composing all Effect-TS services.
   • The real VS Code ExtHostExtensionService is instantiated within this Effect-TS environment.
3. ExtHostExtensionService (in Services/ExtensionHostService.ts) activates an extension. The extension receives a vscode API object constructed by the APIFactory service.
4. The extension calls vscode.window.showInformationMessage("Hello").
5. The call is routed to the Window service.
6. The Window service creates an Effect that sends a showMessage gRPC request to Mountain via MountainGRPCClient.
7. Mountain's Vine layer receives the request. Its Track dispatcher routes it to the native UI handler.
8. Mountain displays the native UI notification and waits for user interaction.
9. The result is sent back to Cocoon via a gRPC response.
10. The Effect in Cocoon completes, resolving the promise returned to the extension's API call.

---

System Architecture Diagram

This diagram illustrates the internal architecture of Cocoon and its place within the broader Land ecosystem.

graph LR
classDef mountain fill:#f9f,stroke:#333,stroke-width:2px;
classDef cocoon fill:#ccf,stroke:#333,stroke-width:2px;
classDef effectts fill:#cfc,stroke:#333,stroke-width:1px;
classDef vscode fill:#ddd,stroke:#666,stroke-width:1px,stroke-dasharray: 5 5;

subgraph "Cocoon 🦋 (Node.js SideCar)"
direction TB
Bootstrap["Bootstrap/Implementation/CocoonMain.ts"]:::effectts
AppLayer["Cocoon AppLayer"]:::effectts
EffectModules["Effect/ Modules (Bootstrap, Telemetry, Extension)"]:::effectts
PatchProcess["PatchProcess/ (Process Hardening)"]:::cocoon
APIServices["Services/ (APIFactory, ExtensionHost, Window, Workspace, etc.)"]:::cocoon
IPCService["Services/IPCService.ts + IPC/ Protocol"]:::cocoon
GRPCClient["Services/MountainGRPCClient.ts"]:::cocoon
TypeConverter["TypeConverter/ (DTO Serialization)"]:::cocoon

Bootstrap -- Builds & Runs --> AppLayer
AppLayer -- Composes --> EffectModules
AppLayer -- Composes --> APIServices
AppLayer -- Composes --> IPCService
APIServices -- Use --> GRPCClient
APIServices -- Use --> TypeConverter
GRPCClient -- Use --> IPCService
PatchProcess -- Hardens --> Bootstrap
end

subgraph "Mountain ⛰️ (Rust/Tauri Backend)"
VineGRPC["Vine gRPC Server"]:::mountain
end

subgraph "VS Code Extension"
ExtensionCode["Extension Code"]:::vscode
end

APIServices -- Provides `vscode` object to --> ExtensionCode
ExtensionCode -- Makes API calls to --> APIServices

GRPCClient -- gRPC <--> VineGRPC

Loading

---

Getting Started with Cocoon Development 🚀

Cocoon is developed as a core component of the main Land project. To work on or run Cocoon, please follow the instructions in the main Land Repository README. The Bundle=true build variable is essential, as it triggers the Rest element to prepare the necessary VS Code platform code for Cocoon to consume.

Key Dependencies:

• effect (v3.19.18): The core library for the entire application structure.
• @effect/platform & @effect/platform-node: Effect-TS platform abstractions.
• @grpc/grpc-js & @grpc/proto-loader: For gRPC communication.
• google-protobuf & protobufjs: Protocol buffers for gRPC.
• VS Code platform code (e.g., vs/base, vs/platform), sourced from the Land/Dependency submodule.

Current Version: 0.0.1 (see package.json)

Debugging Cocoon:

• Since Cocoon is a Node.js process, it can be debugged by attaching a standard Node.js debugger. Mountain must launch the Cocoon process with the appropriate Node.js debug flags (e.g., --inspect-brk=PORT_NUMBER).
• Logs from Cocoon are automatically piped to the parent Mountain process thanks to the PatchProcess module and will appear in Mountain's console output or log files.

---

License ⚖️

This project is released into the public domain under the Creative Commons CC0 Universal license. You are free to use, modify, distribute, and build upon this work for any purpose, without any restrictions. For the full legal text, see the LICENSE file.

---

Changelog 📜

Stay updated with our progress! See CHANGELOG.md for a history of changes specific to Cocoon.

---

Funding & Acknowledgements 🙏🏻

Cocoon is a core element of the Land ecosystem. This project is funded through NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program. Learn more at the NLnet project page.

Land	PlayForm	NLnet	NGI0 Commons Fund

---

Project Maintainers: Source Open (Source/Open@Editor.Land) | GitHub Repository | Report an Issue | Security Policy