You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Replace verbose technical documentation with outcome-first copy matching the website's goal-oriented direction.
The old README led with feature lists and architectural deep-dives. The new version opens with the core problem statement (VS Code's single event loop limitation), followed by what Cocoon gives you: supervised fiber isolation, automatic timeout/restart, and concurrent extension activation.
References: 4b42f88 (previous README rewrite)
> **VS Code's extension host is a single Node.js event loop. One hung Promise blocks every other extension. There is no way to cancel an in-flight operation, no back-pressure, no preemption.**
43
46
44
-
The Extension Host for Land 🏞️
47
+
_"Every extension runs in its own supervised fiber. One crash doesn't take down the rest."_
Your entire VS Code extension library works out of the box. Cocoon hosts
52
-
Node.js extensions in a managed sidecar process that mirrors the full VS Code
53
-
Extension Host API. Install an extension, activate it, and it works exactly as
54
-
it does in VS Code.
55
-
56
-
Cocoon talks to Mountain over gRPC (Vine protocol). Extension API calls become
57
-
typed Effects that Mountain executes natively. The result: extensions run at
58
-
Rust speed for I/O operations while keeping full Node.js compatibility.
54
+
Cocoon intercepts `require`/`import` at the Node.js module level and routes all VS Code API calls through Effect-TS fibers. Extensions call `vscode.workspace.openTextDocument()` and get back a `Thenable<TextDocument>` exactly as documented. Internally, each call is a typed Effect that can be interrupted, raced with a timeout, and run concurrently. 50+ extensions activate in parallel. Language server crashes are handled in supervised scopes with automatic restart. The full VS Code marketplace works without modification.
59
55
60
56
---
61
57
62
-
## Key Features & Architectural Highlights 🔐
63
-
64
-
-**Effect-TS Native Architecture:** The entire `Cocoon` application is built
65
-
with **Effect-TS**. All services, API shims, and IPC logic are implemented as
66
-
declarative, composable `Layer`s and `Effect`s, ensuring robustness,
67
-
testability, and type safety.
68
-
-**High-Fidelity VSCode API Shims:** Provides a comprehensive set of service
69
-
shims (e.g., for `vscode.workspace`, `vscode.window`, `vscode.commands`) that
70
-
replicate the behavior of the real VS Code Extension Host.
71
-
-**gRPC-Powered Communication:** All communication with the `Mountain` backend
72
-
is handled via gRPC, providing a fast, modern, and strongly-typed contract for
73
-
all IPC operations.
74
-
-**Robust Module Interception:** Implements high-fidelity interceptors for both
75
-
CJS `require()` and ESM `import` statements, ensuring calls to the `'vscode'`
76
-
module are correctly sandboxed and routed to the appropriate,
77
-
extension-specific API instance.
78
-
-**Process Hardening & Lifecycle Management:** Includes process patching to
79
-
handle uncaught exceptions, pipe logs to the host, and automatically terminate
80
-
if the parent `Mountain` process exits, ensuring a stable sidecar.
58
+
## What It Does 🔐
81
59
82
-
---
83
-
84
-
## Deep Dive & Component Breakdown 🔬
85
-
86
-
To understand how `Cocoon`'s internal components interact to provide the
87
-
high-fidelity `vscode` API, see the following source files:
|**Node.js Process**| The runtime environment for Cocoon. |
119
-
|**`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. |
120
-
|**`PatchProcess/`**| Performs very early process hardening (patching `process.exit`, handling exceptions, piping logs), ensuring a stable foundation before any other code runs. |
121
-
|**`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. |
122
-
|**`Services/` Modules**| A comprehensive collection of Effect-TS `Layer`s, 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`. |
123
-
|**`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. |
124
-
|**`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. |
125
-
|**Extension Code**| The JavaScript/TypeScript code of the VS Code extensions being hosted and run within the Cocoon environment. |
0 commit comments