@hydranium/glsp-server 1.0.0-next.10

package/src/launcher/glsp-framework-overrides.ts

@@ -0,0 +1,51 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, 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 { Logger as GlspLogger, LoggerFactory, getRequestParentName } from '@eclipse-glsp/server';
+import { ContainerModule } from 'inversify';
+import type { ServerSharedServices } from '@hydranium/core';
+import { HydraniumTypes } from '../state/hydranium-shared-core-services.js';
+
+/**
+ * The framework bindings layered on top of GLSP's own app module, shared by
+ * every bringup regardless of transport.
+ *
+ * Two things happen here. GLSP's `Logger` / `LoggerFactory` are replaced with
+ * the adopter's — unbind-then-bind, the same pattern `createAppModule` uses
+ * internally — so GLSP server logs leave through the adopter's sink rather than
+ * a console the host may not own. And `HydraniumTypes.Tracer` is added,
+ * caller-tagged the same way the logger is, so an injected tracer's timing lines
+ * carry the requesting class's component without every call site naming itself.
+ *
+ * **Shared rather than written once per launcher, because the two would drift
+ * silently.** A transport-specific copy that fell behind would still bind
+ * something for each symbol, so nothing would fail — the head would merely log
+ * or trace differently depending on how it was started, which no test asks
+ * about.
+ *
+ * `createLogger` is called once per Inversify resolution, with `caller` set to
+ * the requesting parent's class name, and once per `LoggerFactory` invocation.
+ */
+export function createGlspFrameworkOverrides(createLogger: (caller?: string) => GlspLogger): ContainerModule {
+   return new ContainerModule((bind, unbind, isBound) => {
+      if (isBound(GlspLogger)) {
+         unbind(GlspLogger);
+      }
+      if (isBound(LoggerFactory)) {
+         unbind(LoggerFactory);
+      }
+      bind(GlspLogger).toDynamicValue(ctx => createLogger(getRequestParentName(ctx)));
+      bind(LoggerFactory).toFactory(() => (caller: string) => createLogger(caller));
+      bind(HydraniumTypes.Tracer).toDynamicValue(ctx => {
+         const tracer = ctx.container.get<ServerSharedServices>(HydraniumTypes.SharedCoreServices).Tracer;
+         const caller = getRequestParentName(ctx);
+         return caller ? tracer.for(caller) : tracer;
+      });
+   });
+}

package/src/launcher/glsp-server-overrides.ts

@@ -0,0 +1,46 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, 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 { GLSPServer } from '@eclipse-glsp/server';
+import { ContainerModule } from 'inversify';
+import { HydraniumGlspServer } from './hydranium-glsp-server.js';
+
+/**
+ * The framework bindings layered on top of the adopter's `ServerModule`, in the
+ * SERVER container — one per connected application, a child of the app
+ * container every bringup composes.
+ *
+ * **The tier matters, and the app container cannot stand in for it.** GLSP's
+ * launcher creates the server container as a child and loads the adopter's
+ * `ServerModule` into it, so a `GLSPServer` binding made further up is shadowed
+ * rather than consulted, and inversify refuses to rebind a parent's binding
+ * from a child at all. The framework's app-tier overrides therefore cannot
+ * reach this symbol.
+ *
+ * **Load this AFTER the adopter's `ServerModule`, never beside it.** Both bind
+ * `GLSPServer`, so a plain second binding resolves to an ambiguous-match error
+ * rather than to either one; `rebind` needs the first binding to already be
+ * present.
+ *
+ * Keeping this out of the adopter's hands is the point: an adopter passes their
+ * own `ServerModule` in, so anything they must add themselves is a fix the
+ * adopters who most need it will not have.
+ *
+ * **It also decides what GLSP's own log lines are tagged with.** GLSP resolves
+ * a logger per injecting class and labels it with the bound implementation's
+ * name, so every line upstream's server logs carries
+ * {@link HydraniumGlspServer} rather than `DefaultGLSPServer`. Anything keyed
+ * on that label — a log filter, an assertion — reads the class bound here, and
+ * a further adopter subclass moves it again.
+ */
+export function createGlspServerOverrides(): ContainerModule {
+   return new ContainerModule((_bind, _unbind, _isBound, rebind) => {
+      rebind(GLSPServer).to(HydraniumGlspServer).inSingletonScope();
+   });
+}

package/src/launcher/hydranium-glsp-server.ts

@@ -0,0 +1,104 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, 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 ClientSession,
+   DefaultGLSPServer,
+   GLSPServerError,
+   RejectAction,
+   type RequestAction,
+   type ResponseAction
+} from '@eclipse-glsp/server';
+import { injectable } from 'inversify';
+
+/**
+ * The GLSP server the framework binds in place of upstream's
+ * {@link DefaultGLSPServer}, so a failed REQUEST reaches its reader with the
+ * text the thrower wrote.
+ *
+ * **What breaks without it.** Upstream projects a failing request's detail as
+ * `error.cause?.toString()` whenever the error is a {@link GLSPServerError},
+ * and that one value feeds both the server log and the client's
+ * {@link RejectAction}. A {@link GLSPServerError} carrying no `cause` therefore
+ * reaches no reader at all — not the toast, not the details pane, not the log —
+ * while a plain `Error` survives, because the other branch reads the error
+ * itself. The typed error is the trap, and it is the one upstream's own
+ * `getOrThrow` helper raises: that helper's signature cannot pass a `cause`, so
+ * an adopter using the sanctioned helper has no fix available on their side.
+ * Restating the cause at each throw site is the alternative, and it costs
+ * every adopter a rule they must know and cannot apply to `getOrThrow`.
+ *
+ * Only the REQUEST path needs this. Non-request actions fail through
+ * upstream's `handleProcessError`, which reads `message` directly.
+ *
+ * Adopters who bind their own GLSP server should extend this class rather than
+ * {@link DefaultGLSPServer}; the framework's server-container override replaces
+ * whatever the adopter's `ServerModule` bound, so a subclass of upstream's
+ * server would be discarded.
+ */
+@injectable()
+export class HydraniumGlspServer extends DefaultGLSPServer {
+   /**
+    * The detail projected into the client's {@link RejectAction} and the server
+    * log when a request fails.
+    *
+    * A {@link GLSPServerError} with no `cause` falls back to its `message`; a
+    * nullish `cause` counts as absent, matching the optional chaining upstream
+    * applies. Anything else stringifies as upstream does, so a plain `Error`
+    * keeps its `"Error: …"` prefix and callers that match on it still match.
+    */
+   protected requestFailureDetail(error: unknown): string | undefined {
+      if (error instanceof GLSPServerError) {
+         return error.cause === undefined || error.cause === null ? error.message : String(error.cause);
+      }
+      return error === undefined || error === null ? undefined : String(error);
+   }
+
+   /**
+    * Lifted verbatim from `@eclipse-glsp/server` 2.7.0's
+    * {@link DefaultGLSPServer.handleClientRequest}, with the detail computation
+    * delegated to {@link requestFailureDetail}. Nothing else here — the
+    * timeout branch, the response dispatch, the nested send-failure handling —
+    * relates to that fallback.
+    *
+    * **This body does not track upstream.** A release that changes request
+    * handling would silently not apply, on the path every request takes. There
+    * is no narrower seam to override: upstream computes the detail inline. The
+    * accompanying test pins upstream's own source for this method, so a bump
+    * that changes it fails rather than diverging quietly; re-lift the body when
+    * it does.
+    */
+   protected override async handleClientRequest(
+      clientSession: ClientSession,
+      action: RequestAction<ResponseAction>,
+      clientId: string
+   ): Promise<void> {
+      try {
+         const response =
+            action.timeout !== undefined
+               ? await clientSession.actionDispatcher.requestUntil(action, action.timeout, true)
+               : await clientSession.actionDispatcher.request(action);
+         if (response) {
+            this.sendResponseToClient(clientId, response);
+         }
+      } catch (error: unknown) {
+         const detail = this.requestFailureDetail(error);
+         this.logger.error(`Failed to handle request '${action.kind}' (${action.requestId}):`, detail);
+         try {
+            const reject = RejectAction.create(`Failed to handle request '${action.kind}' (${action.requestId})`, {
+               responseId: action.requestId,
+               detail
+            });
+            this.sendResponseToClient(clientId, reject);
+         } catch (sendError: unknown) {
+            this.logger.error(`Failed to send rejection for request '${action.requestId}':`, sendError);
+         }
+      }
+   }
+}

package/src/launcher/index.ts

@@ -0,0 +1,22 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, 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 './glsp-app-module.js';
+export * from './abstract-hydranium-glsp-diagram-module.js';
+// Exported so an adopter binding their own GLSP server extends the framework's
+// rather than upstream's — the server-container override discards a subclass of
+// `DefaultGLSPServer`.
+export * from './hydranium-glsp-server.js';
+// The socket bringup lives in `@hydranium/glsp-server/node` and the worker
+// bringup in `@hydranium/glsp-server/browser`, not here: each pulls the
+// upstream build for its platform, which the portable `.` entry must stay free
+// of. `glsp-framework-overrides.js` and `glsp-server-overrides.js` are
+// deliberately NOT re-exported — they are the bindings those two bringups share,
+// reached by relative import, and an adopter composing a container by hand wants
+// the launcher rather than its internals.

package/src/logging/glsp-client-logger.ts

@@ -0,0 +1,184 @@
+/********************************************************************************
+ * Copyright (c) 2023-2026 CrossBreeze, 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 Logger as GlspLogger, LogLevel } from '@eclipse-glsp/server';
+import { LspLogger, type LspLoggerOptions, type ServerSharedServices } from '@hydranium/core';
+import { Logger, type LogThreshold } from '@hydranium/protocol';
+
+/**
+ * Options accepted by {@link GlspClientLogger}. Extends
+ * {@link LspLoggerOptions} (which carries the optional `component`
+ * label) with the GLSP-specific per-instance {@link logLevel} threshold.
+ */
+export interface GlspClientLoggerOptions extends LspLoggerOptions {
+   /**
+    * Per-instance NARROWING of the framework threshold. Omit it — the default
+    * tracks `Logger.getLevel()` live, which is what makes one
+    * `HYDRANIUM_LOG_LEVEL` / one LSP setting govern GLSP output too.
+    *
+    * It can only narrow, never widen, and that is not a policy choice:
+    * `AbstractLogger.send` gates every emission on the process-wide threshold
+    * before it reaches the output channel, so a value more verbose than the
+    * global is silently ineffective. Set it only to make ONE component quieter
+    * than the rest.
+    */
+   readonly logLevel?: LogLevel;
+}
+
+/**
+ * Map the framework's {@link LogThreshold} onto GLSP's numeric enum.
+ *
+ * Two vocabularies have to meet here: ours is a string union with `'off'` and
+ * `'trace'`, GLSP's a numeric enum whose most verbose tier is `debug`. `'off'`
+ * becomes `none`, and **`'trace'` also becomes `debug`** — GLSP has no finer
+ * tier, and mapping it to `none` would silence GLSP at the most verbose
+ * framework setting, which is the opposite of what asking for `trace` means.
+ */
+export function glspLogLevelOf(threshold: LogThreshold): LogLevel {
+   switch (threshold) {
+      case 'off':
+         return LogLevel.none;
+      case 'error':
+         return LogLevel.error;
+      case 'warn':
+         return LogLevel.warn;
+      case 'info':
+         return LogLevel.info;
+      case 'debug':
+      case 'trace':
+         return LogLevel.debug;
+   }
+}
+
+/**
+ * Adapter from {@link LspLogger} (the framework's LSP-bound logger in
+ * `@hydranium/core`) to GLSP's server-side {@link GlspLogger}
+ * abstract base. Lets the GLSP container resolve a logger whose output
+ * lines interleave with the LSP head's existing log channel — the only
+ * way to debug request/response flow across the two heads in one place.
+ *
+ * GLSP-specific concerns layered on top of {@link LspLogger}:
+ *
+ * - A {@link logLevel} field, because GLSP's `Logger` contract declares one.
+ *   **It tracks the framework's process-wide threshold by default**, resolving
+ *   `Logger.getLevel()` through {@link glspLogLevelOf} on every read — so
+ *   `HYDRANIUM_LOG_LEVEL`, the LSP log-level setting and the Theia preference
+ *   all reach GLSP output without a second knob. Assigning the field (or
+ *   passing `logLevel`) pins an explicit per-instance NARROWING; see
+ *   {@link GlspClientLoggerOptions.logLevel} for why it cannot widen.
+ *   Resolved lazily rather than captured in the constructor: the root logger is
+ *   built during container setup, before the LSP client has sent its
+ *   configuration, so a captured value would freeze the launch-time default.
+ * - The {@link caller} accessor satisfies GLSP's abstract `Logger.caller`
+ *   contract; it is backed by {@link LspLogger}'s `component` field.
+ * - {@link info} / {@link warn} / {@link error} / {@link debug} accept GLSP's
+ *   `(message, ...params)` shape and {@link combine} the params into the
+ *   message via {@link formatParam} so objects render as JSON and errors
+ *   render with stack. GLSP server code routinely calls
+ *   `logger.error('Failed', error)` expecting the second argument to be
+ *   surfaced in the log line.
+ *
+ * Subclasses can override {@link withUri} to render workspace-relative
+ * paths instead of stringified URIs (the typical adopter customisation,
+ * mirroring what an adopter does in its LSP-side logger).
+ */
+export class GlspClientLogger extends LspLogger implements GlspLogger {
+   /**
+    * Explicit per-instance narrowing, or `undefined` to track the framework
+    * threshold. Kept separate from the resolved value so {@link derive} can pass
+    * the OVERRIDE to children rather than the resolution — passing the resolved
+    * level would pin every child at whatever the global happened to be when the
+    * parent was derived, and container-time derivation is exactly when that
+    * value is still the launch-time default.
+    */
+   protected logLevelOverride?: LogLevel;
+
+   constructor(services: ServerSharedServices, options: GlspClientLoggerOptions = {}) {
+      super(services, options);
+      this.logLevelOverride = options.logLevel;
+   }
+
+   /** GLSP's `Logger.logLevel` contract; the framework threshold unless pinned. */
+   get logLevel(): LogLevel {
+      return this.logLevelOverride ?? glspLogLevelOf(Logger.getLevel());
+   }
+
+   set logLevel(level: LogLevel) {
+      this.logLevelOverride = level;
+   }
+
+   /** GLSP's `Logger.caller` contract; reads {@link LspLogger.component}. */
+   get caller(): string | undefined {
+      return this.component;
+   }
+
+   override info(message: string, ...params: unknown[]): this {
+      if (this.enabled(LogLevel.info)) {
+         super.info(this.combine(message, params));
+      }
+      return this;
+   }
+
+   override warn(message: string, ...params: unknown[]): this {
+      if (this.enabled(LogLevel.warn)) {
+         super.warn(this.combine(message, params));
+      }
+      return this;
+   }
+
+   override error(message: string, ...params: unknown[]): this {
+      if (this.enabled(LogLevel.error)) {
+         super.error(this.combine(message, params));
+      }
+      return this;
+   }
+
+   override debug(message: string, ...params: unknown[]): this {
+      if (this.enabled(LogLevel.debug)) {
+         super.debug(this.combine(message, params));
+      }
+      return this;
+   }
+
+   /** True when {@link logLevel} permits emission at the given level. */
+   protected enabled(level: LogLevel): boolean {
+      return this.logLevel !== LogLevel.none && level <= this.logLevel;
+   }
+
+   /** Concatenate a message with its varargs, formatting each via {@link formatParam}. */
+   protected combine(message: string, params: readonly unknown[]): string {
+      return params.length === 0 ? message : `${message} ${params.map(p => this.formatParam(p)).join(',\n')}`;
+   }
+
+   /** Format a single param: errors → `message\nstack`; everything else → JSON.stringify(p, undefined, 4). */
+   protected formatParam(param: unknown): string {
+      if (param instanceof Error) {
+         return `${param.message}\n${param.stack ?? ''}`;
+      }
+      try {
+         return JSON.stringify(param, undefined, 4);
+      } catch {
+         return '';
+      }
+   }
+
+   /**
+    * Override of {@link LspLogger.derive} that carries the per-instance
+    * narrowing. The base `derive(component)` constructs the subclass with
+    * `{ component }` only, which would drop it.
+    *
+    * It passes {@link logLevelOverride}, NOT `this.logLevel`: an unpinned parent
+    * must yield an unpinned child, or every derived logger freezes at the
+    * threshold in force when the container was built.
+    */
+   protected override derive(component: string): this {
+      const Subclass = this.constructor as new (services: ServerSharedServices, options?: GlspClientLoggerOptions) => this;
+      return new Subclass(this.services, { logLevel: this.logLevelOverride, component });
+   }
+}

package/src/logging/index.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, 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 './glsp-client-logger.js';

package/src/node/index.ts

@@ -0,0 +1,13 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, 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
+ ********************************************************************************/
+
+// Server-only entry (`@hydranium/glsp-server/node`). Holds the socket launcher,
+// which binds GLSP's node `SocketServerLauncher` (`@eclipse-glsp/server/node`).
+// The portable `.` entry stays free of that import so it bundles for the browser.
+export * from './start-glsp-server.js';

package/src/node/start-glsp-server.ts

@@ -0,0 +1,214 @@
+/********************************************************************************
+ * Copyright (c) 2023-2026 CrossBreeze, 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 Logger as GlspLogger,
+   type ServerModule,
+   type SocketLaunchOptions,
+   SocketServerLauncher,
+   createAppModule,
+   defaultSocketLaunchOptions
+} from '@eclipse-glsp/server/node.js';
+import { Container, type ContainerModule } from 'inversify';
+import type { Logger } from '@hydranium/protocol';
+import { Deferred } from '@hydranium/langium';
+import type * as net from 'node:net';
+import type { IntegratedServer } from '@hydranium/core';
+import { createGlspFrameworkOverrides } from '../launcher/glsp-framework-overrides.js';
+import { createGlspServerOverrides } from '../launcher/glsp-server-overrides.js';
+import type { LspConnectionLike } from '@hydranium/core/node';
+
+/**
+ * Options for {@link startGlspServer}.
+ *
+ * @see {@link startGlspServer} for the lifecycle semantics.
+ */
+export interface GlspServerOptions {
+   /**
+    * Port to bind. Default `0` — OS-assigned ephemeral. Resolve the
+    * actual port off {@link StartedGlspServer.port} once `started`
+    * resolves (only then is the address info available).
+    */
+   readonly port?: number;
+   /**
+    * Host to bind. Default `'127.0.0.1'` (LOCAL ONLY) — the GLSP head is
+    * traffic-only-from-the-companion-client by design; rebinding to a
+    * routable address is an explicit opt-in that adopters must do
+    * deliberately.
+    */
+   readonly host?: string;
+   /**
+    * Adopter-supplied logger factory. Called once per Inversify resolution
+    * (with `caller` set to the requesting parent's class name) AND once
+    * per `LoggerFactory` invocation.
+    *
+    * **The threshold belongs in here, not beside it.** GLSP's own log level is
+    * a property of the logger this factory returns — e.g.
+    * `GlspClientLogger` filters
+    * each call against its own `logLevel` option. There is deliberately no
+    * launcher-level `logLevel`: the framework replaces GLSP's `Logger` binding
+    * outright, so anything passed to GLSP's app module would be discarded, and
+    * an option that looks authoritative and is discarded is worse than none.
+    */
+   readonly createLogger: (caller?: string) => GlspLogger;
+   /**
+    * The GLSP {@link ServerModule} with per-diagram modules
+    * pre-configured via `new ServerModule().configureDiagramModule(...)`.
+    */
+   readonly serverModule: ServerModule;
+   /**
+    * Additional Inversify modules to load on the app container AFTER GLSP's
+    * own app module (via `createAppModule`, which binds `InjectionContainer`
+    * plus the GLSP-version-specific app bindings) and the framework overrides
+    * that route GLSP's logger and logger factory through the adopter logger
+    * and add the shared Tracer. Adopters wire language-services bindings
+    * (e.g. their own shared-services symbol) here.
+    */
+   readonly appModules?: ReadonlyArray<ContainerModule>;
+   /**
+    * Optional LSP connection used to register a port-discovery request
+    * handler. When both `lspConnection` and `portCommand` are set, the
+    * framework registers `lspConnection.onRequest(portCommand, () => port)`
+    * after the GLSP socket is listening — the standard handshake adopters
+    * use to bridge LSP clients to the GLSP head.
+    */
+   readonly lspConnection?: LspConnectionLike;
+   /**
+    * LSP request method name to register. Required when `lspConnection` is
+    * set. Adopters define this constant in their own protocol package.
+    */
+   readonly portCommand?: string;
+   /**
+    * Optional framework-lifecycle logger. Receives `listening` / `error`
+    * lifecycle messages from the launcher itself (the GLSP container's
+    * own logger handles application-level GLSP logs).
+    */
+   readonly logger?: Logger;
+   /**
+    * Optional diagnostic hook called for every incoming `net.Socket` the
+    * GLSP server's `net.Server` accepts. Fires as a side-effect of the
+    * framework's own `'connection'` listener — GLSP's per-connection setup
+    * runs independently from its own listener registered by
+    * `SocketServerLauncher`. Adopters typically attach `'data'` / `'close'`
+    * listeners inside the hook for byte-level observability when debugging
+    * wire-level handshake issues.
+    */
+   readonly onClientConnection?: (socket: net.Socket) => void;
+}
+
+/**
+ * Live GLSP server handle returned by {@link startGlspServer}.
+ *
+ * - {@link IntegratedServer.started} resolves once the GLSP socket is
+ *   listening AND (if configured) the port-discovery handler has been
+ *   registered on the LSP connection.
+ * - {@link IntegratedServer.stopped} resolves once GLSP's
+ *   `SocketServerLauncher.start` promise settles (i.e. the underlying
+ *   `net.Server` has closed).
+ * - {@link port} is `undefined` until `started` resolves.
+ */
+export interface StartedGlspServer extends IntegratedServer {
+   readonly port: number | undefined;
+}
+
+/**
+ * Start a GLSP socket head. Builds the GLSP app container with framework-
+ * default `Logger` / `LoggerFactory` bindings, layers adopter modules,
+ * resolves {@link SocketServerLauncher}, configures the adopter
+ * {@link ServerModule}, and starts listening.
+ *
+ * **GLSP launcher coupling.** GLSP's {@link SocketServerLauncher} owns the
+ * `net.Server` and per-connection `MessageConnection` construction;
+ * the framework wrapper composes ABOVE that launcher rather than replacing
+ * it. The framework's own `startSocketServer`
+ * helper is NOT used here — it's designed for stdio/raw-JSON-RPC heads
+ * (data-server's pattern), not GLSP's Inversify-driven per-connection
+ * server-instance model. Bridging the two would lose GLSP's action-handler
+ * registry plumbing.
+ */
+export function startGlspServer(options: GlspServerOptions): StartedGlspServer {
+   const launchOptions: SocketLaunchOptions = {
+      ...defaultSocketLaunchOptions,
+      host: options.host ?? '127.0.0.1',
+      port: options.port ?? 0
+   };
+   const lifecycle = options.logger;
+
+   // Start from GLSP's own app module rather than re-deriving its bindings by
+   // hand. createAppModule binds InjectionContainer + Logger/LoggerFactory and
+   // — crucially — whatever else the resolved GLSP version's app container needs,
+   // so the framework tracks GLSP across versions instead of drifting. consoleLog /
+   // fileLog are forced off so GLSP binds a throwaway NullLogger with no winston
+   // instance; the override module below replaces Logger/LoggerFactory with the
+   // adopter's logger, so GLSP server logs flow through options.createLogger.
+   const glspAppModule = createAppModule({ ...launchOptions, consoleLog: false, fileLog: false });
+
+   const appContainer = new Container();
+   appContainer.load(glspAppModule, createGlspFrameworkOverrides(options.createLogger), ...(options.appModules ?? []));
+
+   const launcher = appContainer.resolve<SocketServerLauncher>(SocketServerLauncher);
+   // Passed as an additional module rather than folded into the app container:
+   // the launcher loads these into the per-connection SERVER container, which is
+   // the only tier where the adopter's `ServerModule` binding of `GLSPServer`
+   // can be rebound.
+   launcher.configure(options.serverModule, createGlspServerOverrides());
+
+   const started = new Deferred<void>();
+   const portHandle: { port: number | undefined } = { port: undefined };
+
+   try {
+      const stoppedPromise = Promise.resolve(launcher.start(launchOptions));
+
+      // GLSP's `SocketServerLauncher.netServer` field is `protected`; we
+      // access it via property indexing. The alternative is to fork the
+      // launcher or add a 'listening' callback to GLSP upstream.
+      const netServer = (launcher as unknown as { netServer: net.Server }).netServer;
+
+      netServer.on('listening', () => {
+         const address = netServer.address();
+         if (address && typeof address !== 'string') {
+            portHandle.port = address.port;
+            if (options.lspConnection && options.portCommand) {
+               options.lspConnection.onRequest(options.portCommand, () => portHandle.port);
+            }
+            lifecycle?.info(`[GlspServer] Ready to accept new client requests on port: ${address.port}`);
+            started.resolve();
+         } else {
+            const message = address === null ? 'address is null' : `bound to non-TCP "${String(address)}"`;
+            lifecycle?.error(`[GlspServer] Could not resolve address info — ${message}. Shutting down.`);
+            started.reject(new Error(`startGlspServer could not resolve address info — ${message}`));
+            netServer.close();
+         }
+      });
+      netServer.on('error', (err: Error) => {
+         lifecycle?.error(`[GlspServer] Error: ${err.message}`);
+         started.reject(err);
+      });
+      if (options.onClientConnection) {
+         netServer.on('connection', options.onClientConnection);
+      }
+
+      return {
+         get port() {
+            return portHandle.port;
+         },
+         started: started.promise,
+         stopped: stoppedPromise
+      };
+   } catch (error) {
+      lifecycle?.error('Error in GLSP server launcher:', error);
+      return {
+         get port() {
+            return portHandle.port;
+         },
+         started: Promise.reject(error),
+         stopped: Promise.resolve()
+      };
+   }
+}