update lsp docs

Author: bajrangCoder

docs/advanced-apis/lsp.md

@@ -1,67 +1,210 @@
 # LSP API
 
-Use this API to register/manage language servers used by Acode's CodeMirror LSP client.
+Use this API to register and manage language servers for Acode's CodeMirror LSP integration.
 
 ## Import
 
 ```js
 const lsp = acode.require("lsp");
 ```
 
-## Important Transport Reality
+## Current API Shape
 
-CodeMirror's LSP client in Acode communicates via **WebSocket** transport.
+The public API is intentionally small:
 
-- `transport.kind: "websocket"` is the recommended and practical mode.
-- `transport.kind: "stdio"` is **not a direct stdio pipe** to the editor.
-- In this codebase, `stdio` mode still expects a **WebSocket bridge URL**.
+- `lsp.defineServer(...)`
+- `lsp.defineBundle(...)`
+- `lsp.register(entry, options?)`
+- `lsp.upsert(entry)`
+- `lsp.installers.*`
+- `lsp.servers.*`
+- `lsp.bundles.*`
 
-For local stdio language servers, use an **AXS bridge** (`launcher.bridge`) and keep transport as websocket.
+`bundle` is the public name for what the internal runtime still calls a provider:
+
+- a bundle can own one or more server definitions
+- a bundle can also provide install/check behavior hooks
+- most plugins only need a single server
+- use a bundle when you ship a family of related servers or custom install logic
+
+## Transport Reality
+
+Acode's LSP client still speaks WebSocket to the transport layer.
+
+- `transport.kind: "websocket"` is the normal and recommended setup
+- local stdio servers should usually be launched through `launcher.bridge`
+- `transport.kind: "stdio"` still expects a WebSocket bridge URL
+- `transport.kind: "external"` is available for custom transport factories
+
+For local servers, prefer `transport.kind: "websocket"` plus an AXS bridge.
 
 ::: warning
-`stdio` with only `transport.command` is not enough in Acode.  
-You still need a WebSocket bridge endpoint (AXS or equivalent) for the client connection.
+`transport.kind: "stdio"` is not a direct pipe from the editor to the server.
+It still resolves to the WebSocket transport layer and requires a bridge URL.
 :::
 
-## Recommended Setup (Local Server via AXS Bridge)
+## Recommended Single-Server Setup
+
+Use `defineServer()` and `upsert()` for idempotent registration.
+
+```js
+const lsp = acode.require("lsp");
+
+const typescriptServer = lsp.defineServer({
+  id: "typescript-custom",
+  label: "TypeScript (Custom)",
+  languages: [
+    "javascript",
+    "javascriptreact",
+    "typescript",
+    "typescriptreact",
+    "tsx",
+    "jsx",
+  ],
+  useWorkspaceFolders: true,
+  transport: {
+    kind: "websocket",
+  },
+  command: "typescript-language-server",
+  args: ["--stdio"],
+  checkCommand: "which typescript-language-server",
+  installer: lsp.installers.npm({
+    executable: "typescript-language-server",
+    packages: ["typescript-language-server", "typescript"],
+  }),
+  initializationOptions: {
+    provideFormatter: true,
+  },
+});
+
+lsp.upsert(typescriptServer);
+```
+
+## Bundle Setup
+
+Use a bundle when one plugin contributes multiple servers or needs custom install behavior.
+
+```js
+const lsp = acode.require("lsp");
+
+const htmlServer = lsp.defineServer({
+  id: "my-html",
+  label: "My HTML Server",
+  languages: ["html"],
+  transport: {
+    kind: "websocket",
+  },
+  command: "vscode-html-language-server",
+  args: ["--stdio"],
+  installer: lsp.installers.npm({
+    executable: "vscode-html-language-server",
+    packages: ["vscode-langservers-extracted"],
+  }),
+});
+
+const cssServer = lsp.defineServer({
+  id: "my-css",
+  label: "My CSS Server",
+  languages: ["css", "scss", "less"],
+  transport: {
+    kind: "websocket",
+  },
+  command: "vscode-css-language-server",
+  args: ["--stdio"],
+  installer: lsp.installers.npm({
+    executable: "vscode-css-language-server",
+    packages: ["vscode-langservers-extracted"],
+  }),
+});
+
+const webBundle = lsp.defineBundle({
+  id: "my-web-bundle",
+  label: "My Web Bundle",
+  servers: [htmlServer, cssServer],
+});
+
+lsp.upsert(webBundle);
+```
+
+## Bundle Hooks
+
+Bundles can own behavior, not just server lists.
+
+Available hooks:
+
+- `getExecutable(serverId, manifest)`
+- `checkInstallation(serverId, manifest)`
+- `installServer(serverId, manifest, mode, options?)`
+
+Example:
 
 ```js
-lsp.registerServer(
-  {
-    id: "typescript-custom",
-    label: "TypeScript (Custom)",
-    languages: ["javascript", "javascriptreact", "typescript", "typescriptreact", "tsx", "jsx"],
-    transport: {
-      kind: "websocket",
-      // url can be omitted when using launcher.bridge auto-port mode
+const bundle = lsp.defineBundle({
+  id: "my-bundle",
+  label: "My Bundle",
+  servers: [myServer],
+  hooks: {
+    getExecutable(serverId, manifest) {
+      return manifest.launcher?.install?.binaryPath || null;
     },
-    launcher: {
-      bridge: {
-        kind: "axs",
-        command: "typescript-language-server",
-        args: ["--stdio"],
-      },
-      checkCommand: "which typescript-language-server",
-      install: {
-        command:
-          "apk add --no-cache nodejs npm && npm install -g typescript-language-server typescript",
-      },
+    async checkInstallation(serverId, manifest) {
+      return {
+        status: "present",
+        version: null,
+        canInstall: true,
+        canUpdate: true,
+      };
     },
-    enabled: true,
-    initializationOptions: {
-      provideFormatter: true,
+    async installServer(serverId, manifest, mode) {
+      console.log("install", serverId, mode);
+      return true;
     },
   },
-  { replace: true },
-);
+});
 ```
 
-## Remote/External WebSocket Server
+## Structured Installers
+
+Prefer structured installers over raw shell whenever possible.
+
+Available installer builders:
+
+- `lsp.installers.apk(...)`
+- `lsp.installers.npm(...)`
+- `lsp.installers.pip(...)`
+- `lsp.installers.cargo(...)`
+- `lsp.installers.githubRelease(...)`
+- `lsp.installers.manual(...)`
+- `lsp.installers.shell(...)`
+
+Example:
 
 ```js
-lsp.registerServer({
-  id: "remote-lsp",
-  label: "Remote LSP",
+const server = lsp.defineServer({
+  id: "python-custom",
+  label: "Python (pylsp)",
+  languages: ["python"],
+  command: "pylsp",
+  installer: lsp.installers.pip({
+    executable: "pylsp",
+    packages: ["python-lsp-server[all]"],
+  }),
+});
+```
+
+### Installer Notes
+
+- managed installers should declare the executable they provide
+- `githubRelease()` is intended for arch-aware downloaded binaries
+- `manual()` is useful when the binary already exists at a known path
+- `shell()` should be treated as the advanced fallback, not the default path
+
+## Remote WebSocket Server
+
+```js
+lsp.upsert({
+  id: "remote-json-lsp",
+  label: "Remote JSON LSP",
   languages: ["json"],
   transport: {
     kind: "websocket",
@@ -75,66 +218,89 @@ lsp.registerServer({
 });
 ```
 
-## API Reference
-
-### `registerServer(definition, options?)`
-
-- `options.replace?: boolean` (default `false`)
-  - `false`: existing server with same id is kept
-  - `true`: existing server is replaced
-
-Definition fields commonly used:
-
-- `id` (required): normalized to lowercase
-- `label` (optional)
-- `languages` (required): non-empty array, normalized to lowercase
-- `enabled` (optional, default `true`)
-- `transport` (required)
-  - `kind`: `"websocket"` or `"stdio"` (see transport note above)
-  - `url?: string`
-  - `command?: string` (required by registry validation when using `stdio`)
-  - `args?: string[]`
-  - `options?: { binary?, timeout?, reconnect?, maxReconnectAttempts? }`
-- `launcher` (optional)
-  - `startCommand?: string | string[]`
-  - `command?: string`
-  - `args?: string[]`
-  - `checkCommand?: string`
-  - `install?: { command?: string }`
-  - `bridge?: { kind: "axs", command: string, args?: string[], port?: number, session?: string }`
-- `initializationOptions?: object`
-- `clientConfig?: object`
-- `startupTimeout?: number`
-- `capabilityOverrides?: object`
-- `rootUri?: (uri, context) => string | null`
-- `resolveLanguageId?: (context) => string | null`
-- `useWorkspaceFolders?: boolean`
-
-### Other Registry Methods
-
-- `unregisterServer(id)`
-- `updateServer(id, updater)`
-- `getServer(id)`
-- `listServers()`
-- `getServersForLanguage(languageId, options?)`
+## Definition API
+
+### `lsp.defineServer(options)`
+
+Builds a normalized server manifest for later registration.
+
+Common fields:
+
+- `id`: required, normalized to lowercase by the registry
+- `label`: optional display label
+- `languages`: required non-empty array
+- `enabled`: defaults to `true`
+- `transport`
+- `command` and `args`: used to create an AXS launcher bridge
+- `installer`: structured installer config
+- `checkCommand`
+- `versionCommand`
+- `updateCommand`
+- `initializationOptions`
+- `clientConfig`
+- `startupTimeout`
+- `capabilityOverrides`
+- `rootUri`
+- `resolveLanguageId`
+- `useWorkspaceFolders`
+
+### `lsp.defineBundle(options)`
+
+Creates a bundle record.
+
+Fields:
+
+- `id`: required bundle id
+- `label`: optional
+- `servers`: array returned by `lsp.defineServer(...)`
+- `hooks?`: optional behavioral hooks
+
+## Registration API
+
+### `lsp.register(entry, options?)`
+
+Registers either a server or bundle if the id is free.
+
+- `options.replace?: boolean` defaults to `false`
+
+### `lsp.upsert(entry)`
+
+Registers or replaces either a server or bundle. This is the preferred method for plugin startup code.
+
+## Server Inspection API
+
+- `lsp.servers.get(id)`
+- `lsp.servers.list()`
+- `lsp.servers.listForLanguage(languageId, options?)`
+- `lsp.servers.update(id, updater)`
+- `lsp.servers.unregister(id)`
+- `lsp.servers.onChange(listener)`
+
+Example:
 
 ```js
-const jsServers = lsp.getServersForLanguage("javascript");
+const jsServers = lsp.servers.listForLanguage("javascript");
 
-lsp.updateServer("typescript-custom", (current) => ({
+lsp.servers.update("typescript-custom", (current) => ({
   ...current,
   enabled: false,
 }));
 ```
 
-`getServersForLanguage` options:
+`listForLanguage()` options:
 
-- `includeDisabled?: boolean` (default `false`)
+- `includeDisabled?: boolean` default `false`
+
+## Bundle Inspection API
+
+- `lsp.bundles.list()`
+- `lsp.bundles.getForServer(serverId)`
+- `lsp.bundles.unregister(id)`
 
 ## Client Manager
 
-- `clientManager.setOptions(options)`
-- `clientManager.getActiveClients()`
+- `lsp.clientManager.setOptions(options)`
+- `lsp.clientManager.getActiveClients()`
 
 ```js
 lsp.clientManager.setOptions({
@@ -144,3 +310,11 @@ lsp.clientManager.setOptions({
 const activeClients = lsp.clientManager.getActiveClients();
 console.log(activeClients);
 ```
+
+## Best Practices
+
+- Prefer `lsp.upsert(...)` during plugin init.
+- Prefer `defineServer()` and `defineBundle()` instead of hand-assembling objects everywhere.
+- Prefer structured installers over raw shell commands.
+- Use a bundle when your plugin owns a family of related servers or custom install logic.
+- Use `useWorkspaceFolders: true` for heavy workspace-aware servers like TypeScript or Rust.