@hydranium/client-vscode 0.0.0-stage → 1.0.0-next.315

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# `@hydranium/client-vscode`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The cross-head VS Code side of a
+[Hydranium](https://github.com/eclipse-emfcloud/hydranium) host. Install it
+when a VS Code extension starts your language server and a socket head (data
+or GLSP) runs beside it: it finds each head's port from the extension host,
+and publishes the ports to a Theia app that sideloads the extension.
+
+## What it gives you
+
+- A head's port, asked from the running language client and polled until the
+  server answers, bounded so a request the server never publishes fails
+  instead of waiting forever.
+- One host command per head that answers its port, which is how a Theia app's
+  backend reaches the heads of a server the extension started.
+
+## Install
+
+```bash
+npm install @hydranium/client-vscode
+```
+
+No peer dependencies; the extension host provides `vscode`.
+
+## Wiring
+
+After the language client has started, register the port commands a Theia
+host polls, and ask for a port where a head's client connects. Ask once per
+connection rather than caching the answer: a restarted server binds a fresh
+port.
+
+<!-- snippet-preamble
+import type { ExtensionContext } from 'vscode';
+import type { LanguageClient } from 'vscode-languageclient/node.js';
+declare const context: ExtensionContext;
+declare const client: LanguageClient;
+-->
+
+```ts
+import { findPort, registerPortCommands } from '@hydranium/client-vscode/node';
+
+registerPortCommands(context, client, {
+   'my-language.port.dataServer': 'my-language/data-server/port',
+   'my-language.port.glsp': 'my-language/glsp-server/port'
+});
+const glspPort = await findPort(client, 'my-language/glsp-server/port');
+```
+
+`@hydranium/data-client-vscode` and `@hydranium/glsp-client-vscode` take the
+lookup as their `findPort` option. For the whole setup, see *Host in VS
+Code* in
+[Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
+
+## Entry points
+
+| Subpath  | Use it for                            | Runs in                    |
+| -------- | ------------------------------------- | -------------------------- |
+| `.`      | Nothing yet                           | anywhere                   |
+| `./node` | The port lookup and the port commands | the VS Code extension host |
+
+The subpaths need a TypeScript `moduleResolution` that reads `exports`
+(`NodeNext` or `Bundler`); see *Requirements* in
+[Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
+
+## Status
+
+Alpha: every release is a prerelease that may break the API, so pin an exact
+version. Guides and known limitations:
+[Adopting Hydranium](https://github.com/eclipse-emfcloud/hydranium/blob/main/docs/ADOPTING.md).
+
+## License
+
+`MIT` — see this package's [`LICENSE`](./LICENSE), and the repository
+[`NOTICE.md`](https://github.com/eclipse-emfcloud/hydranium/blob/main/NOTICE.md)
+for third-party notices.

package/lib/index.d.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAKlF,OAAO,EAAE,CAAC"}

package/lib/index.js

@@ -0,0 +1,11 @@
+"use strict";
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF"}

package/lib/node/find-port.d.ts

@@ -0,0 +1,40 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+/** Options for {@link findPort}. */
+export interface FindPortOptions {
+    /**
+     * How many requests to send before giving up, the first included, so at
+     * least 1. The Theia handler's `findPortAttempts` counts the retries after
+     * the first instead.
+     */
+    readonly attempts?: number;
+    /** The wait after each failed attempt. */
+    readonly intervalMs?: number;
+}
+/** {@link FindPortOptions.attempts} when none is given. */
+export declare const DEFAULT_FIND_PORT_ATTEMPTS = 40;
+/** {@link FindPortOptions.intervalMs} when none is given. */
+export declare const DEFAULT_FIND_PORT_INTERVAL_MS = 500;
+/**
+ * Ask the language server for a socket head's listening port.
+ *
+ * The server registers its port requests after the heads bind their sockets,
+ * so the first requests legitimately fail and this polls. The poll is bounded,
+ * unlike the Theia handler's default, so a request the server never publishes
+ * surfaces as an error instead of a connection that waits forever.
+ *
+ * Call it once per connection rather than caching the answer: a restarted
+ * server binds a fresh ephemeral port. `client` is typed by the one method
+ * used, which `vscode-languageclient`'s `LanguageClient` has, so this package
+ * does not pin the adopter's copy.
+ */
+export declare function findPort(client: {
+    sendRequest<R>(method: string): Promise<R>;
+}, request: string, options?: FindPortOptions): Promise<number>;
+//# sourceMappingURL=find-port.d.ts.map

package/lib/node/find-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-port.d.ts","sourceRoot":"","sources":["../../src/node/find-port.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,2DAA2D;AAC3D,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAC7C,6DAA6D;AAC7D,eAAO,MAAM,6BAA6B,MAAM,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,wBAAsB,QAAQ,CAC3B,MAAM,EAAE;IAAE,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;CAAE,EACtD,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,eAAoB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAwBjB"}

package/lib/node/find-port.js

@@ -0,0 +1,54 @@
+"use strict";
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_FIND_PORT_INTERVAL_MS = exports.DEFAULT_FIND_PORT_ATTEMPTS = void 0;
+exports.findPort = findPort;
+/** {@link FindPortOptions.attempts} when none is given. */
+exports.DEFAULT_FIND_PORT_ATTEMPTS = 40;
+/** {@link FindPortOptions.intervalMs} when none is given. */
+exports.DEFAULT_FIND_PORT_INTERVAL_MS = 500;
+/**
+ * Ask the language server for a socket head's listening port.
+ *
+ * The server registers its port requests after the heads bind their sockets,
+ * so the first requests legitimately fail and this polls. The poll is bounded,
+ * unlike the Theia handler's default, so a request the server never publishes
+ * surfaces as an error instead of a connection that waits forever.
+ *
+ * Call it once per connection rather than caching the answer: a restarted
+ * server binds a fresh ephemeral port. `client` is typed by the one method
+ * used, which `vscode-languageclient`'s `LanguageClient` has, so this package
+ * does not pin the adopter's copy.
+ */
+async function findPort(client, request, options = {}) {
+    const attempts = options.attempts ?? exports.DEFAULT_FIND_PORT_ATTEMPTS;
+    const intervalMs = options.intervalMs ?? exports.DEFAULT_FIND_PORT_INTERVAL_MS;
+    if (!Number.isInteger(attempts) || attempts < 1) {
+        throw new RangeError(`findPort: attempts must be a whole number of at least 1, got ${attempts}`);
+    }
+    let lastError;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        try {
+            const port = await client.sendRequest(request);
+            if (typeof port === 'number' && port > 0) {
+                return port;
+            }
+        }
+        catch (error) {
+            lastError = error;
+        }
+        if (attempt + 1 < attempts) {
+            await new Promise(resolve => setTimeout(resolve, intervalMs));
+        }
+    }
+    const detail = lastError instanceof Error ? ` The last attempt failed: ${lastError.message}` : '';
+    throw new Error(`No port answered '${request}' after ${attempts} ${attempts === 1 ? 'attempt' : 'attempts'}. Check that the server publishes it.${detail}`);
+}
+//# sourceMappingURL=find-port.js.map

package/lib/node/find-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-port.js","sourceRoot":"","sources":["../../src/node/find-port.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;AAclF,2DAA2D;AAC9C,QAAA,0BAA0B,GAAG,EAAE,CAAC;AAC7C,6DAA6D;AAChD,QAAA,6BAA6B,GAAG,GAAG,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACI,KAAK,mBACT,MAAsD,EACtD,OAAe,EACf,OAAO,GAAoB,EAAE;IAE7B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,QAAA,0BAA0B,CAAC;IAChE,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,QAAA,6BAA6B,CAAC;IACvE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,UAAU,CAAC,gEAAgE,QAAQ,EAAE,CAAC,CAAC;IACpG,CAAC;IACD,IAAI,SAAkB,CAAC;IACvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,QAAQ,EAAE,OAAO,EAAE,EAAE,CAAC;QACnD,IAAI,CAAC;YACF,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,WAAW,CAAU,OAAO,CAAC,CAAC;YACxD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;gBACxC,OAAO,IAAI,CAAC;YACf,CAAC;QACJ,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACvB,SAAS,GAAG,KAAK,CAAC;QACrB,CAAC;QACD,IAAI,OAAO,GAAG,CAAC,GAAG,QAAQ,EAAE,CAAC;YAC1B,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;QACjE,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,YAAY,KAAK,CAAC,CAAC,CAAC,6BAA6B,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAClG,MAAM,IAAI,KAAK,CACZ,qBAAqB,OAAO,WAAW,QAAQ,IAAI,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,wCAAwC,MAAM,EAAE,CAC5I,CAAC;AACL,CAAC"}

package/lib/node/index.d.ts

@@ -0,0 +1,11 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+export * from './find-port';
+export * from './port-commands';
+//# sourceMappingURL=index.d.ts.map

package/lib/node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}

package/lib/node/index.js

@@ -0,0 +1,27 @@
+"use strict";
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./find-port"), exports);
+__exportStar(require("./port-commands"), exports);
+//# sourceMappingURL=index.js.map

package/lib/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,8CAA4B;AAC5B,kDAAgC"}

package/lib/node/port-commands.d.ts

@@ -0,0 +1,25 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { type ExtensionContext } from 'vscode';
+/**
+ * Register a host command per socket head that answers the head's port, keyed
+ * command id to the LSP request the server publishes the port under.
+ *
+ * A Theia app that sideloads the extension reaches each port through these
+ * commands, since its backend has no language client of its own, and its
+ * connection handler retries a command nobody registered forever.
+ *
+ * Each command hands back the request's promise and nothing else. Awaiting a
+ * notification there would make the answer wait for a user to dismiss it,
+ * which hangs the Theia backend with nothing logged.
+ */
+export declare function registerPortCommands(context: Pick<ExtensionContext, 'subscriptions'>, client: {
+    sendRequest<R>(method: string): Promise<R>;
+}, portCommands: Readonly<Record<string, string>>): void;
+//# sourceMappingURL=port-commands.d.ts.map

package/lib/node/port-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-commands.d.ts","sourceRoot":"","sources":["../../src/node/port-commands.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAY,KAAK,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAEzD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CACjC,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,eAAe,CAAC,EAChD,MAAM,EAAE;IAAE,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;CAAE,EACtD,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAC9C,IAAI,CAIN"}

package/lib/node/port-commands.js

@@ -0,0 +1,30 @@
+"use strict";
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerPortCommands = registerPortCommands;
+const vscode_1 = require("vscode");
+/**
+ * Register a host command per socket head that answers the head's port, keyed
+ * command id to the LSP request the server publishes the port under.
+ *
+ * A Theia app that sideloads the extension reaches each port through these
+ * commands, since its backend has no language client of its own, and its
+ * connection handler retries a command nobody registered forever.
+ *
+ * Each command hands back the request's promise and nothing else. Awaiting a
+ * notification there would make the answer wait for a user to dismiss it,
+ * which hangs the Theia backend with nothing logged.
+ */
+function registerPortCommands(context, client, portCommands) {
+    for (const [commandId, request] of Object.entries(portCommands)) {
+        context.subscriptions.push(vscode_1.commands.registerCommand(commandId, () => client.sendRequest(request)));
+    }
+}
+//# sourceMappingURL=port-commands.js.map

package/lib/node/port-commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-commands.js","sourceRoot":"","sources":["../../src/node/port-commands.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF,mCAAyD;AAEzD;;;;;;;;;;;GAWG;AACH,8BACG,OAAgD,EAChD,MAAsD,EACtD,YAA8C;IAE9C,KAAK,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QAC/D,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,iBAAQ,CAAC,eAAe,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,WAAW,CAAS,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9G,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@hydranium/client-vscode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-next.315",
+  "description": "Cross-head VS Code client primitives for a hydranium host: the extension host asks the language server for each socket head's port, bounded, and registers the host commands through which a Theia app that sideloads the extension reaches those ports.",
+  "keywords": [
+    "hydranium",
+    "langium",
+    "language-server",
+    "lsp",
+    "vscode",
+    "vscode-extension"
+  ],
+  "homepage": "https://github.com/eclipse-emfcloud/hydranium/tree/main/packages/client-vscode",
+  "bugs": {
+    "url": "https://github.com/eclipse-emfcloud/hydranium/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Hydranium Team"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eclipse-emfcloud/hydranium.git",
+    "directory": "packages/client-vscode"
+  },
+  "files": [
+    "lib",
+    "src",
+    "!lib/**/*.tsbuildinfo"
+  ],
+  "sideEffects": false,
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./node": {
+      "types": "./lib/node/index.d.ts",
+      "default": "./lib/node/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rimraf lib tsconfig.tsbuildinfo",
+    "lint": "oxlint --format stylish --config ../../oxlint.config.cjs src test --max-warnings 0",
+    "prepack": "node -e \"const m=require('./package.json'),fs=require('node:fs');const missing=[m.main,...Object.values(m.bin||{})].filter(entry=>entry&&!fs.existsSync(entry));if(missing.length){console.error('prepack '+m.name+': not built ('+missing.join(', ')+' missing). Run the build before packing: a files entry that matches nothing is skipped silently, so the tarball would ship src only.');process.exit(1);}\"",
+    "test": "npm run typecheck:test && vitest run",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
+    "watch": "tsc -b -w --preserveWatchOutput"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/vscode": "^1.101.0",
+    "rimraf": "^5.0.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=22.13",
+    "vscode": "^1.101.0"
+  },
+  "//prepack": "The publish guard, a `prepack` rather than a `prepare`: `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error."
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+// Nothing here is neutral yet: every export needs the extension host and sits
+// behind `./node`, so a webview bundle importing the bare specifier pulls in
+// neither `vscode` nor Node.
+export {};

package/src/node/find-port.ts

@@ -0,0 +1,68 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/** Options for {@link findPort}. */
+export interface FindPortOptions {
+   /**
+    * How many requests to send before giving up, the first included, so at
+    * least 1. The Theia handler's `findPortAttempts` counts the retries after
+    * the first instead.
+    */
+   readonly attempts?: number;
+   /** The wait after each failed attempt. */
+   readonly intervalMs?: number;
+}
+
+/** {@link FindPortOptions.attempts} when none is given. */
+export const DEFAULT_FIND_PORT_ATTEMPTS = 40;
+/** {@link FindPortOptions.intervalMs} when none is given. */
+export const DEFAULT_FIND_PORT_INTERVAL_MS = 500;
+
+/**
+ * Ask the language server for a socket head's listening port.
+ *
+ * The server registers its port requests after the heads bind their sockets,
+ * so the first requests legitimately fail and this polls. The poll is bounded,
+ * unlike the Theia handler's default, so a request the server never publishes
+ * surfaces as an error instead of a connection that waits forever.
+ *
+ * Call it once per connection rather than caching the answer: a restarted
+ * server binds a fresh ephemeral port. `client` is typed by the one method
+ * used, which `vscode-languageclient`'s `LanguageClient` has, so this package
+ * does not pin the adopter's copy.
+ */
+export async function findPort(
+   client: { sendRequest<R>(method: string): Promise<R> },
+   request: string,
+   options: FindPortOptions = {}
+): Promise<number> {
+   const attempts = options.attempts ?? DEFAULT_FIND_PORT_ATTEMPTS;
+   const intervalMs = options.intervalMs ?? DEFAULT_FIND_PORT_INTERVAL_MS;
+   if (!Number.isInteger(attempts) || attempts < 1) {
+      throw new RangeError(`findPort: attempts must be a whole number of at least 1, got ${attempts}`);
+   }
+   let lastError: unknown;
+   for (let attempt = 0; attempt < attempts; attempt++) {
+      try {
+         const port = await client.sendRequest<unknown>(request);
+         if (typeof port === 'number' && port > 0) {
+            return port;
+         }
+      } catch (error: unknown) {
+         lastError = error;
+      }
+      if (attempt + 1 < attempts) {
+         await new Promise(resolve => setTimeout(resolve, intervalMs));
+      }
+   }
+   const detail = lastError instanceof Error ? ` The last attempt failed: ${lastError.message}` : '';
+   throw new Error(
+      `No port answered '${request}' after ${attempts} ${attempts === 1 ? 'attempt' : 'attempts'}. Check that the server publishes it.${detail}`
+   );
+}

package/src/node/index.ts

@@ -0,0 +1,11 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+export * from './find-port';
+export * from './port-commands';

package/src/node/port-commands.ts

@@ -0,0 +1,32 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { commands, type ExtensionContext } from 'vscode';
+
+/**
+ * Register a host command per socket head that answers the head's port, keyed
+ * command id to the LSP request the server publishes the port under.
+ *
+ * A Theia app that sideloads the extension reaches each port through these
+ * commands, since its backend has no language client of its own, and its
+ * connection handler retries a command nobody registered forever.
+ *
+ * Each command hands back the request's promise and nothing else. Awaiting a
+ * notification there would make the answer wait for a user to dismiss it,
+ * which hangs the Theia backend with nothing logged.
+ */
+export function registerPortCommands(
+   context: Pick<ExtensionContext, 'subscriptions'>,
+   client: { sendRequest<R>(method: string): Promise<R> },
+   portCommands: Readonly<Record<string, string>>
+): void {
+   for (const [commandId, request] of Object.entries(portCommands)) {
+      context.subscriptions.push(commands.registerCommand(commandId, () => client.sendRequest<number>(request)));
+   }
+}