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.
- Effect-TS Native Architecture: The entire
Cocoonapplication is built with Effect-TS. All services, API shims, and IPC logic are implemented as declarative, composableLayers andEffects, 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
Mountainbackend 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 ESMimportstatements, 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
Mountainprocess exits, ensuring a stable and well-behaved sidecar.
To understand how Cocoon's internal components interact to provide the
high-fidelity vscode API, please refer to the detailed technical breakdown in
docs/Deep Dive.md. This document explains the roles of
the Core services (like ApiFactory and ExtensionHost), the Service
shims, and the gRPC-based IpcProvider.
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. |
Index.ts (Main Orchestrator) |
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. |
Core/ Modules |
Manages the extension runtime itself. ExtensionHost.ts activates extensions, RequireInterceptor.ts patches require, and ApiFactory.ts constructs the vscode object given to each extension. |
Service/ 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. |
Service/Ipc.ts |
Implements both the gRPC client (to call Mountain) and server (to receive calls from Mountain), managing the entire bi-directional communication lifecycle. |
Type/ & TypeConverter/ |
Type/ contains the concrete TypeScript class and enum definitions for the vscode API (e.g., Uri, Range). TypeConverter/ provides pure functions to serialize these rich types into plain DTOs for gRPC transport. |
| Extension Code | The JavaScript/TypeScript code of the VS Code extensions being hosted and run within the Cocoon environment. |
MountainlaunchesCocoonwith initialization data.Cocoon'sIndex.tsbootstraps the application:PatchProcesshardens the environment.IpcProviderestablishes the gRPC connection and performs a handshake.- The main
AppLayeris built, composing all services. - The real VS Code
ExtHostExtensionServiceis instantiated within this Effect-TS environment.
ExtHostExtensionServiceactivates an extension. The extension receives avscodeAPI object constructed by theApiFactoryProvider.- The extension calls
vscode.window.showInformationMessage("Hello"). - The call is routed to the
MessageProviderservice. - The
MessageProvidercreates anEffectthat sends ashowMessagegRPC request toMountain. Mountain'sVinelayer receives the request. ItsTrackdispatcher routes it to the native UI handler.Mountaindisplays the native UI notification and waits for user interaction.- The result is sent back to
Cocoonvia a gRPC response. - The
EffectinCocooncompletes, resolving the promise returned to the extension's API call.
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
Index["Index.ts (Main Entry)"]:::effectts
AppLayer["Cocoon AppLayer"]:::effectts
CoreServices["Core Services (ApiFactory, ExtensionHost)"]:::cocoon
APIServices["API Service Shims (Workspace, Window, etc.)"]:::cocoon
IPCService["IpcProvider (gRPC Client & Server)"]:::cocoon
Index -- Builds & Runs --> AppLayer
AppLayer -- Composes --> CoreServices
AppLayer -- Composes --> APIServices
AppLayer -- Composes --> IPCService
CoreServices -- Use --> APIServices
APIServices -- Use --> IPCService
end
subgraph "Mountain ⛰️ (Rust/Tauri Backend)"
VineGRPC["Vine gRPC Server"]:::mountain
end
subgraph "VS Code Extension"
ExtensionCode["Extension Code"]:::vscode
end
CoreServices -- Provides `vscode` object to --> ExtensionCode
ExtensionCode -- Makes API calls to --> CoreServices
IPCService -- gRPC <--> VineGRPC
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: The core library for the entire application structure.@grpc/grpc-js&@grpc/proto-loader: For gRPC communication.- VS Code platform code (e.g.,
vs/base,vs/platform), sourced from theLand/Dependencysubmodule.
Debugging Cocoon:
- Since Cocoon is a Node.js process, it can be debugged by attaching a standard
Node.js debugger.
Mountainmust launch the Cocoon process with the appropriate Node.js debug flags (e.g.,--inspect-brk=PORT_NUMBER). - Logs from
Cocoonare automatically piped to the parentMountainprocess thanks to thePatchProcessmodule and will appear inMountain's console output or log files.
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.
Stay updated with our progress! See CHANGELOG.md for a history
of changes specific to Cocoon.
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