@ycodium-ai/plugin-browser-workbench 0.2.2098

package/README.md

@@ -0,0 +1,99 @@
+# @ycodium-ai/plugin-browser-workbench
+
+Install the official VS Code CLI on this Ycodium machine and open it in a system
+browser. The CLI runs as `serve-web` on loopback; Ycodium registers that port so
+the desktop app can forward it. You can also point the plugin at a code-server
+you already run.
+
+## What it does
+
+The first time you open the workbench, the plugin:
+
+1. Asks you to confirm the VS Code Server license terms.
+2. Downloads the official `code` CLI if it is not already in the plugin data
+   directory.
+3. Starts `code serve-web` on `127.0.0.1` with a random port.
+4. Waits until the VS Code server payload has finished downloading (the CLI
+   does that lazily on the first HTTP request).
+5. Registers the port with Ycodium.
+
+After that, the process stays up until you stop it, disable the plugin, or
+shut down the server. A later **Open** reuses the running instance. Progress
+for install and start is a stream named `progress`.
+
+If you already run code-server yourself, set its loopback port on the settings
+card or call **attach**. The plugin does not start, stop, or authenticate that
+process. Opening then returns the registered port without a VS Code connection
+token.
+
+## Requirements
+
+A Ycodium server with plugin API version 2, including `process.spawn` for
+`data:bin/code` (at most two processes at once) and `ports.register`. The
+machine needs outbound HTTPS to `update.code.visualstudio.com` (and the CDN it
+redirects to) the first time the CLI is installed, unless you attach an
+external code-server instead.
+
+Supported CLI download platforms: Linux x64/arm64, macOS x64/arm64, Windows
+x64. Other combinations fail with a download error rather than guessing.
+
+## Install
+
+```
+ycodium plugin add @ycodium-ai/plugin-browser-workbench
+```
+
+The plugin ships enabled with Ycodium as `core.browser-workbench`. Disabling it
+stops the managed `serve-web` process and unregisters its port. The downloaded
+CLI, server data, and license acceptance stay in the plugin data directory.
+Uninstalling writes a removal onto the home patch so a restart or upgrade does
+not bring the plugin back; it still does not delete that data directory.
+Reinstalling the unversioned bundled package restores the same entry without
+an npm fetch.
+
+## Read this before installing
+
+`serve-web` is a full VS Code on this machine: terminal, extensions, and file
+access run as the same OS user as the Ycodium server. Opening it from the
+desktop is equivalent in power to using the machine's terminal.
+
+The connection token lives in the plugin data directory with mode `0600`. Logs
+and progress events do not include it. The desktop listens only on
+`127.0.0.1`; other processes on the same computer can still connect to that
+local port, the same way an SSH local forward would.
+
+One machine has one managed instance. Two people using the same machine share
+settings and extensions.
+
+Disable and uninstall do **not** stop a code-server you attached. That process
+is yours.
+
+## Upgrading
+
+```
+ycodium plugin add @ycodium-ai/plugin-browser-workbench@<version>
+```
+
+Installing a newer plugin version replaces the running one without restarting
+the server. Updating the VS Code CLI is a separate **update** command and
+requires the workbench to be stopped first.
+
+## Developing
+
+```
+vp run --filter @ycodium-ai/plugin-browser-workbench build
+vp run --filter @ycodium-ai/plugin-browser-workbench test
+```
+
+The package builds its own code into `dist/index.js`. The host supplies the
+shared `@ycodium-ai/plugin-api` at runtime. The plugin requires plugin API
+version 2. Language catalogs live in `locales/`; only English is authored here.
+
+Known limits: Windows uses `bin/code` (the spawn whitelist), not `code.exe`.
+Server download progress is the size of `cli-data/serve-web/` because the CLI
+does not report bytes. The host does not auto-start the workbench after a
+server restart.
+
+## License
+
+UNLICENSED.