coderaft 0.0.6 → 0.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +256 -0
  2. package/ThirdPartyNotices.txt +3596 -0
  3. package/code.tar.zst +0 -0
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -0,0 +1,256 @@
1
+ # 🛶 coderaft
2
+
3
+ [![npm version](https://img.shields.io/npm/v/coderaft?color=blue)](https://npmx.dev/package/coderaft)
4
+ [![install size](https://packagephobia.com/badge?p=coderaft)](https://packagephobia.com/result?p=coderaft)
5
+
6
+ Run VS Code on any machine anywhere and access it in the browser.
7
+
8
+ A redistribution of [coder/code-server](https://github.com/coder/code-server) bundled into a single zero-dependency package (**~25 MB**). Native modules are shimmed with better alternatives ([zigpty](https://github.com/pithings/zigpty), [ripgrep-node](https://github.com/pithings/ripgrep-node), [...more](./shims/README.md)).
9
+
10
+ - **Installs in under a second** — no build tools, post-install scripts, or C/C++ toolchain needed
11
+ - **Fully portable** across platforms and architectures, unlike `code-server` (platform-specific binaries) and `openvscode-server` (Linux only)
12
+ - **Works everywhere** Node.js runs, including minimal images like `node:slim` and `node:alpine`
13
+
14
+ <details>
15
+ <summary>Detailed comparison</summary>
16
+
17
+ Compared to [`code-server`](https://www.npmjs.com/package/code-server) and [`openvscode-server`](https://github.com/gitpod-io/openvscode-server):
18
+
19
+ | | **coderaft** | **code-server** | **openvscode-server** | **VS Code (DMG)** |
20
+ | --------------------------- | ------------ | ----------------------------------------- | -------------------------------- | -------------------------------- |
21
+ | Distribution | **npm** | npm | GitHub tarball (not on npm) | Platform installer (DMG/EXE/deb) |
22
+ | Network download | **31 MB** | 273 MB | ~73 MB | 155 MB |
23
+ | Install size on disk\* | **32 MB** | 776 MB | 224 MB | 529 MB |
24
+ | Install time | **~0.5s** | ~15s | ~1.2s | N/A |
25
+ | Dependencies | **0** | 462 | Bundled | Bundled |
26
+ | Build tools required | **No** | Yes (`node-gyp`, `gcc`, `make`, `python`) | No (pre-built) | No (pre-built) |
27
+ | Post-install scripts | **None** | Yes (`--unsafe-perm` required as root) | N/A | N/A |
28
+ | Works on `node:slim` images | **Yes** | No | N/A (bundles own Node.js) | N/A (desktop app) |
29
+ | Fully portable | **Yes** | No (platform-specific compiled binaries) | No (Linux only, x64/arm64/armhf) | No (platform-specific) |
30
+
31
+ > Measured with `npm i` inside a fresh `node:22` Docker container.
32
+ >
33
+ > \*Before temporary decompression on first server start (~200 MB decompressed in a temp directory < 2s).
34
+
35
+ </details>
36
+
37
+ ## CLI Usage
38
+
39
+ Start a an instance:
40
+
41
+ ```sh
42
+ npx coderaft -o .
43
+ ```
44
+
45
+ ## Programmatic Usage
46
+
47
+ ```ts
48
+ import { startCodeServer } from "coderaft";
49
+
50
+ const instance = await startCodeServer({
51
+ port: 8080,
52
+ host: "127.0.0.1",
53
+ defaultFolder: "/path/to/workspace",
54
+ // connectionToken: "my-secret", // auto-generated if omitted
55
+ });
56
+
57
+ console.log(`Ready at ${instance.url}`);
58
+
59
+ // Later:
60
+ await instance.close();
61
+ ```
62
+
63
+ ### Middleware
64
+
65
+ Use `createCodeServer` to get a request handler without starting a listener. This lets you integrate code-server into any existing Node.js HTTP server or framework:
66
+
67
+ ```ts
68
+ import { createServer } from "node:http";
69
+ import { createCodeServer } from "coderaft";
70
+
71
+ const handler = await createCodeServer({
72
+ defaultFolder: "/path/to/workspace",
73
+ });
74
+
75
+ const server = createServer((req, res) => {
76
+ handler.handleRequest(req, res);
77
+ });
78
+
79
+ server.on("upgrade", (req, socket) => {
80
+ handler.handleUpgrade(req, socket);
81
+ });
82
+
83
+ server.listen(3000);
84
+ ```
85
+
86
+ ### `createCodeServer(options)`
87
+
88
+ Creates a code-server handler without binding to a port.
89
+
90
+ | Option | Type | Description |
91
+ | ----------------- | --------------------- | --------------------------------------------------------------- |
92
+ | `defaultFolder` | `string` | Workspace folder opened when no input is given in the URL. |
93
+ | `connectionToken` | `string` | Shared auth secret. Auto-generated if omitted. |
94
+ | `vscode` | `VSCodeServerOptions` | Extra options forwarded to VS Code's internal `createServer()`. |
95
+
96
+ Returns a `CodeServerHandler`:
97
+
98
+ ```ts
99
+ interface CodeServerHandler {
100
+ handleRequest(req: IncomingMessage, res: ServerResponse): void;
101
+ handleUpgrade(req: IncomingMessage, socket: Duplex): void;
102
+ connectionToken: string;
103
+ dispose(): Promise<void>;
104
+ }
105
+ ```
106
+
107
+ ### `startCodeServer(options)`
108
+
109
+ Convenience wrapper around `createCodeServer` that creates an HTTP server and starts listening.
110
+
111
+ Accepts all `createCodeServer` options plus:
112
+
113
+ | Option | Type | Description |
114
+ | ------ | -------- | -------------------------------------------------------------------- |
115
+ | `port` | `number` | TCP port to listen on. Defaults to `$PORT` or `8080`. |
116
+ | `host` | `string` | Host/interface to bind. Defaults to Node's default (all interfaces). |
117
+
118
+ Returns a `CodeServerHandle`:
119
+
120
+ ```ts
121
+ interface CodeServerHandle {
122
+ server: http.Server;
123
+ port: number;
124
+ url: string;
125
+ connectionToken: string;
126
+ close(): Promise<void>;
127
+ }
128
+ ```
129
+
130
+ ## CLI Options
131
+
132
+ ### Server
133
+
134
+ | Option | Description |
135
+ | ----------------------------- | ---------------------------------------------- |
136
+ | `-p, --port <port>` | Port to listen on (default: `$PORT` or `8080`) |
137
+ | `-H, --host <host>` | Host/interface to bind |
138
+ | `--server-base-path <path>` | Base path for the web UI (default: `/`) |
139
+ | `--socket-path <path>` | Path to a socket file to listen on |
140
+ | `--print-startup-performance` | Print startup timing to stdout |
141
+
142
+ ### Auth
143
+
144
+ | Option | Description |
145
+ | -------------------------------- | ----------------------------------------------------- |
146
+ | `--connection-token <token>` | Connection token for auth (auto-generated if omitted) |
147
+ | `--connection-token-file <path>` | Path to file containing the connection token |
148
+ | `--without-connection-token` | Disable connection token auth |
149
+ | `--auth <type>` | Auth type |
150
+ | `--github-auth <token>` | GitHub auth token |
151
+
152
+ ### Defaults
153
+
154
+ | Option | Description |
155
+ | ---------------------------- | -------------------------------- |
156
+ | `--default-folder <path>` | Default workspace folder |
157
+ | `--default-workspace <path>` | Default workspace file |
158
+ | `--locale <locale>` | The locale to use (e.g. `en-US`) |
159
+
160
+ ### Data Directories
161
+
162
+ | Option | Description |
163
+ | ---------------------------------- | ----------------------------- |
164
+ | `--server-data-dir <path>` | Server data directory |
165
+ | `--user-data-dir <path>` | User data directory |
166
+ | `--extensions-dir <path>` | Extensions directory |
167
+ | `--extensions-download-dir <path>` | Extensions download directory |
168
+ | `--builtin-extensions-dir <path>` | Built-in extensions directory |
169
+ | `--agent-plugins-dir <path>` | Agent plugins directory |
170
+
171
+ ### Logging
172
+
173
+ | Option | Description |
174
+ | -------------------- | ------------------------------------------------------------------------ |
175
+ | `--log <level>` | Log level (`off`, `critical`, `error`, `warn`, `info`, `debug`, `trace`) |
176
+ | `--logs-path <path>` | Logs output directory |
177
+
178
+ ### Network
179
+
180
+ | Option | Description |
181
+ | --------------------------------- | ----------------------------- |
182
+ | `--disable-websocket-compression` | Disable WebSocket compression |
183
+ | `--use-host-proxy` | Enable host proxy |
184
+
185
+ ### Files
186
+
187
+ | Option | Description |
188
+ | ----------------------------- | ----------------------------- |
189
+ | `--disable-file-downloads` | Disable file downloads |
190
+ | `--disable-file-uploads` | Disable file uploads |
191
+ | `--file-watcher-polling <ms>` | File watcher polling interval |
192
+
193
+ ### Telemetry
194
+
195
+ | Option | Description |
196
+ | --------------------------- | ------------------------------------------------ |
197
+ | `--telemetry-level <level>` | Telemetry level (`off`, `crash`, `error`, `all`) |
198
+ | `--disable-telemetry` | Disable telemetry |
199
+ | `--disable-update-check` | Disable update check |
200
+ | `--disable-experiments` | Disable experiments |
201
+
202
+ ### Features
203
+
204
+ | Option | Description |
205
+ | ------------------------------------ | ------------------------------------------------- |
206
+ | `--enable-sync` | Enable settings sync |
207
+ | `--enable-proposed-api <ext-id>` | Enable proposed API for an extension (repeatable) |
208
+ | `--disable-workspace-trust` | Disable workspace trust |
209
+ | `--disable-getting-started-override` | Disable getting started override |
210
+
211
+ ### Remote
212
+
213
+ | Option | Description |
214
+ | -------------------------------------- | ----------------------------------------------------- |
215
+ | `--enable-remote-auto-shutdown` | Enable remote auto shutdown |
216
+ | `--remote-auto-shutdown-without-delay` | Auto shutdown without delay |
217
+ | `--without-browser-env-var` | Disable browser env var |
218
+ | `--reconnection-grace-time <sec>` | Reconnection grace time in seconds (default: `10800`) |
219
+
220
+ ### Agent Host
221
+
222
+ | Option | Description |
223
+ | -------------------------- | -------------------------------- |
224
+ | `--agent-host-path <path>` | Agent host WebSocket socket path |
225
+ | `--agent-host-port <port>` | Agent host WebSocket port |
226
+
227
+ ### Shell
228
+
229
+ | Option | Description |
230
+ | -------------------------- | --------------------------------------- |
231
+ | `--force-disable-user-env` | Force disable user shell env resolution |
232
+ | `--force-user-env` | Force user shell env resolution |
233
+
234
+ ### Debugging
235
+
236
+ | Option | Description |
237
+ | ---------------------------------- | ----------------------------------- |
238
+ | `--inspect-ptyhost <port>` | Inspect pty host |
239
+ | `--inspect-brk-ptyhost <port>` | Inspect pty host (break on start) |
240
+ | `--inspect-agenthost <port>` | Inspect agent host |
241
+ | `--inspect-brk-agenthost <port>` | Inspect agent host (break on start) |
242
+ | `--enable-smoke-test-driver` | Enable smoke test driver |
243
+ | `--crash-reporter-directory <dir>` | Crash reporter directory |
244
+ | `--crash-reporter-id <id>` | Crash reporter ID |
245
+
246
+ ## Sponsors
247
+
248
+ <p align="center">
249
+ <a href="https://sponsors.pi0.io/">
250
+ <img src="https://sponsors.pi0.io/sponsors.svg?xyz">
251
+ </a>
252
+ </p>
253
+
254
+ ## License
255
+
256
+ MIT, with bundled third-party packages. See [lib/LICENSE.md](./lib/LICENSE.md).