@hydranium/core 1.0.0-next.10

package/lib/node/server-state-snapshot.js

@@ -0,0 +1,139 @@
+/********************************************************************************
+ * 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 { Format } from '@hydranium/protocol';
+import { DocumentState } from '@hydranium/langium';
+import { isCstShed } from '../langium/residency/cst-residency-service.js';
+import { performance } from 'node:perf_hooks';
+import * as v8 from 'node:v8';
+let lastSample;
+/** Default for {@link ServerStateSnapshotOptions.openDocumentsListCap}. */
+export const DEFAULT_OPEN_DOCUMENTS_LIST_CAP = 25;
+/**
+ * Format a multi-line server-state snapshot — heap, rss, V8 stats, event-loop
+ * utilisation, CPU usage, and document counts — and return it. Pure (the caller
+ * logs the result, e.g. `tracer.info(formatServerState(...))`), matching
+ * `formatProcessMemory` / `formatPodMemory`. Tracks deltas across calls so
+ * subsequent snapshots show "since last snapshot" rates. Optional sections are
+ * requested via `options` ({@link ServerStateSnapshotOptions}).
+ */
+export function formatServerState(documents, label, options) {
+    const now = performance.now();
+    const mem = process.memoryUsage();
+    const heap = v8.getHeapStatistics();
+    const cpu = process.cpuUsage();
+    const elu = performance.eventLoopUtilization?.() ?? {
+        idle: 0,
+        active: 0
+    };
+    const heapPercent = Math.round((mem.heapUsed / heap.heap_size_limit) * 100);
+    const lines = [];
+    lines.push(label ? `Server state snapshot (${label}):` : 'Server state snapshot:');
+    lines.push(`  uptime    ${formatDuration(process.uptime() * 1000)}`);
+    lines.push(`  heap      ${Format.bytes(mem.heapUsed)} used / ${Format.bytes(mem.heapTotal)} total / ` +
+        `${Format.bytes(heap.heap_size_limit)} limit (${heapPercent}% of limit)`);
+    lines.push(`  rss       ${Format.bytes(mem.rss)}, external ${Format.bytes(mem.external)}, arrayBuffers ${Format.bytes(mem.arrayBuffers)}`);
+    lines.push(`  v8        malloced ${Format.bytes(heap.malloced_memory)}, peak ${Format.bytes(heap.peak_malloced_memory)}, ` +
+        `native contexts ${heap.number_of_native_contexts}, detached contexts ${heap.number_of_detached_contexts}`);
+    if (lastSample) {
+        const wallMs = now - lastSample.atMs;
+        const userMs = (cpu.user - lastSample.cpu.user) / 1000;
+        const systemMs = (cpu.system - lastSample.cpu.system) / 1000;
+        const cpuPct = wallMs > 0 ? Math.round(((userMs + systemMs) / wallMs) * 100) : 0;
+        const idleDelta = elu.idle - lastSample.elu.idle;
+        const activeDelta = elu.active - lastSample.elu.active;
+        const eluTotal = idleDelta + activeDelta;
+        const eluPct = eluTotal > 0 ? Math.round((activeDelta / eluTotal) * 100) : 0;
+        lines.push(`  cpu       user ${Math.round(userMs)}ms, system ${Math.round(systemMs)}ms ` + `in last ${Math.round(wallMs)}ms (${cpuPct}%)`);
+        lines.push(`  loop      utilization ${eluPct}% (active ${Math.round(activeDelta)}ms / ` +
+            `idle ${Math.round(idleDelta)}ms since last snapshot)`);
+    }
+    else {
+        lines.push(`  cpu       user ${Math.round(cpu.user / 1000)}ms, system ${Math.round(cpu.system / 1000)}ms ` +
+            '(cumulative since process start)');
+        const eluTotal = elu.idle + elu.active;
+        const eluPct = eluTotal > 0 ? Math.round((elu.active / eluTotal) * 100) : 0;
+        lines.push(`  loop      utilization ${eluPct}% (cumulative since process start)`);
+    }
+    if (documents) {
+        const counts = countDocumentsByState(documents);
+        const total = Object.values(counts).reduce((sum, n) => sum + n, 0);
+        const breakdown = Object.entries(counts)
+            .filter(([, n]) => n > 0)
+            .map(([state, n]) => `${state}: ${n}`)
+            .join(', ');
+        lines.push(`  documents ${total} tracked${breakdown ? ` (${breakdown})` : ''}`);
+        // CST-residency breakdown — only meaningful (and only emitted) once a residency
+        // policy has shed at least one document; silent under the always-keep default.
+        const residency = countCstResidency(documents);
+        if (residency.shed > 0) {
+            lines.push(`  cst       ${residency.resident} resident, ${residency.shed} shed`);
+        }
+    }
+    const openDocuments = options?.openDocuments;
+    if (openDocuments !== undefined) {
+        const listCap = options?.openDocumentsListCap ?? DEFAULT_OPEN_DOCUMENTS_LIST_CAP;
+        lines.push(`  open      ${openDocuments.length} document(s) held by a client (excluded from CST shedding)`);
+        for (const { uri, clients } of openDocuments.slice(0, listCap)) {
+            lines.push(`            ${uri} [${clients.join(', ')}]`);
+        }
+        if (openDocuments.length > listCap) {
+            lines.push(`            … and ${openDocuments.length - listCap} more`);
+        }
+    }
+    lastSample = { atMs: now, cpu, elu };
+    return lines.join('\n');
+}
+/**
+ * Count documents whose CST is resident vs. shed by a residency policy
+ * ({@link isCstShed}). A document can also be in neither bucket — not-yet-parsed
+ * or a synthetic placeholder with no `$cstNode` at all (nothing to be "resident"
+ * or "shed") — which is intentionally counted as neither; `resident + shed` is
+ * therefore ≤ total tracked, with the remainder explained by the state breakdown
+ * on the preceding `documents` line.
+ */
+function countCstResidency(documents) {
+    let resident = 0;
+    let shed = 0;
+    for (const doc of documents.all) {
+        if (isCstShed(doc)) {
+            shed++;
+        }
+        else if (doc.parseResult?.value?.$cstNode !== undefined) {
+            resident++;
+        }
+        // else: unparsed / synthetic — no CST, so neither resident nor shed.
+    }
+    return { resident, shed };
+}
+function countDocumentsByState(documents) {
+    const counts = {};
+    for (const doc of documents.all) {
+        const stateName = DocumentState[doc.state] ?? `Unknown(${doc.state})`;
+        counts[stateName] = (counts[stateName] ?? 0) + 1;
+    }
+    return counts;
+}
+function formatDuration(ms) {
+    if (ms < 1000) {
+        return `${Math.round(ms)}ms`;
+    }
+    const totalSeconds = Math.floor(ms / 1000);
+    const seconds = totalSeconds % 60;
+    const totalMinutes = Math.floor(totalSeconds / 60);
+    const minutes = totalMinutes % 60;
+    const hours = Math.floor(totalMinutes / 60);
+    if (hours > 0) {
+        return `${hours}h ${minutes}m ${seconds}s`;
+    }
+    if (minutes > 0) {
+        return `${minutes}m ${seconds}s`;
+    }
+    return `${seconds}s`;
+}
+//# sourceMappingURL=server-state-snapshot.js.map

package/lib/node/server-state-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-state-snapshot.js","sourceRoot":"","sources":["../../src/node/server-state-snapshot.ts"],"names":[],"mappings":"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"}

package/lib/node/socket-launcher.d.ts

@@ -0,0 +1,106 @@
+/********************************************************************************
+ * 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 { Disposable, Logger } from '@hydranium/protocol';
+import type { MessageConnection } from 'vscode-jsonrpc';
+import type { IntegratedServer } from '../launcher/integrated-server.js';
+/**
+ * Construction-time options for {@link startSocketServer}.
+ */
+export interface SocketServerOptions {
+    /**
+     * Port to bind. Default `0` — OS-assigned ephemeral. Resolve the
+     * actual port off {@link StartedSocketServer.port} once `started`
+     * resolves (only then is the address info available).
+     */
+    readonly port?: number;
+    /**
+     * Optional logger. If omitted, the launcher runs silently — the
+     * adopter is expected to surface lifecycle events through their own
+     * logging in {@link OnClientConnection} if needed.
+     */
+    readonly logger?: Logger;
+    /** Tag included in lifecycle log lines. Default `"SocketServer"`. */
+    readonly logTag?: string;
+}
+/**
+ * Adopter callback fired per inbound client. Receives the already-
+ * constructed {@link MessageConnection} (created from the socket via
+ * vscode-jsonrpc's `SocketMessageReader`/`SocketMessageWriter`) BEFORE
+ * `connection.listen()` is called — the launcher invokes `listen()`
+ * after the callback returns so adopters that need to register handlers
+ * before message dispatch starts can do so.
+ *
+ * Adopters construct their per-client servers here and return a
+ * {@link Disposable}. The launcher invokes the disposable on socket
+ * close AND on server shutdown — adopters need not register their own
+ * teardown listeners.
+ *
+ * Returning a no-op `{ dispose() {} }` is valid for heads whose servers
+ * self-clean via `connection.onClose` (the framework's `DataServer`
+ * being the canonical example).
+ */
+export type OnClientConnection = (connection: MessageConnection) => Disposable;
+/**
+ * Live socket server handle returned by {@link startSocketServer}.
+ *
+ * - {@link IntegratedServer.started} resolves once `listen` resolves
+ *   AND `port` is populated.
+ * - {@link IntegratedServer.stopped} resolves when the underlying
+ *   `net.Server` emits `close`.
+ * - {@link port} is undefined until `started` resolves.
+ * - {@link close} triggers shutdown: disposes all active client
+ *   connections and closes the underlying `net.Server`.
+ */
+export interface StartedSocketServer extends IntegratedServer {
+    readonly port: number | undefined;
+    close(): void;
+}
+/**
+ * Start a socket-based protocol head. Wraps `net.createServer` with the
+ * boilerplate adopters used to write per-head: address resolution,
+ * error/close lifecycle, per-client `MessageConnection` construction,
+ * connection tracking, and shutdown cleanup.
+ *
+ * **Multi-client semantics are framework-owned.** The launcher tracks
+ * every accepted connection, invokes the adopter's `onClientConnection`
+ * callback to wire per-client services, and disposes both the returned
+ * adopter disposable AND the underlying `MessageConnection` on socket
+ * close / server shutdown. Adopters keep per-client instance creation
+ * (their server objects) but don't re-implement the tracking machinery.
+ *
+ * The port is only known once {@link StartedSocketServer.started} has
+ * resolved, so announcing it — via {@link publishPortOnLspConnection} —
+ * belongs after that await, not beside the call.
+ */
+export declare function startSocketServer(options: SocketServerOptions, onClientConnection: OnClientConnection): StartedSocketServer;
+/**
+ * The shape the launcher needs from an LSP connection to publish a
+ * port. Matches `vscode-languageserver`'s `Connection.onRequest` —
+ * captured as a structural type here so the launcher doesn't take a
+ * heavy `vscode-languageserver` dep just for the type.
+ */
+export interface LspConnectionLike {
+    onRequest<TParams, TResult>(method: string, handler: (...params: TParams[]) => TResult): Disposable;
+}
+/**
+ * Register a `<command>` request handler on the language-server LSP
+ * connection that returns the port. Adopter clients call this command
+ * to discover the head's port after the LSP handshake.
+ *
+ * No-op (returns a `{ dispose() {} }` disposable) when `lspConnection`
+ * is `undefined` — Langium leaves `shared.lsp.Connection` optional and
+ * adopters running headless (no LSP wire) want the same launcher
+ * helpers to work.
+ *
+ * Adopters typically pass `services.shared.lsp.Connection`; both
+ * `services.shared.lsp.Connection?` and the structural `LspConnectionLike`
+ * shape are accepted.
+ */
+export declare function publishPortOnLspConnection(lspConnection: LspConnectionLike | undefined, command: string, port: number): Disposable;
+//# sourceMappingURL=socket-launcher.d.ts.map

package/lib/node/socket-launcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-launcher.d.ts","sourceRoot":"","sources":["../../src/node/socket-launcher.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,UAAU,EAAE,iBAAiB,KAAK,UAAU,CAAC;AAE/E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,KAAK,IAAI,IAAI,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,kBAAkB,GAAG,mBAAmB,CA0F3H;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAC/B,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,UAAU,CAAC;CACtG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,iBAAiB,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CAKlI"}

package/lib/node/socket-launcher.js

@@ -0,0 +1,138 @@
+/********************************************************************************
+ * 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 { Deferred } from '@hydranium/langium';
+import * as net from 'node:net';
+import { createMessageConnection, SocketMessageReader, SocketMessageWriter } from 'vscode-jsonrpc/node';
+/**
+ * Start a socket-based protocol head. Wraps `net.createServer` with the
+ * boilerplate adopters used to write per-head: address resolution,
+ * error/close lifecycle, per-client `MessageConnection` construction,
+ * connection tracking, and shutdown cleanup.
+ *
+ * **Multi-client semantics are framework-owned.** The launcher tracks
+ * every accepted connection, invokes the adopter's `onClientConnection`
+ * callback to wire per-client services, and disposes both the returned
+ * adopter disposable AND the underlying `MessageConnection` on socket
+ * close / server shutdown. Adopters keep per-client instance creation
+ * (their server objects) but don't re-implement the tracking machinery.
+ *
+ * The port is only known once {@link StartedSocketServer.started} has
+ * resolved, so announcing it — via {@link publishPortOnLspConnection} —
+ * belongs after that await, not beside the call.
+ */
+export function startSocketServer(options, onClientConnection) {
+    const port = options.port ?? 0;
+    const logger = options.logger;
+    const tag = options.logTag ?? 'SocketServer';
+    const started = new Deferred();
+    const stopped = new Deferred();
+    const handle = { port: undefined };
+    // Tracks per-connection cleanup: the adopter's returned Disposable for
+    // its per-client server objects PLUS the underlying MessageConnection
+    // (so shutdown drains both at once).
+    const activeConnections = [];
+    const netServer = net.createServer(socket => {
+        const connection = createMessageConnection(new SocketMessageReader(socket), new SocketMessageWriter(socket));
+        const adopterDisposable = onClientConnection(connection);
+        const entry = { connection, adopterDisposable };
+        activeConnections.push(entry);
+        // Cleanup hook fires once per connection — covers both socket-side
+        // close and server-shutdown forced close.
+        let disposed = false;
+        const dispose = () => {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            try {
+                adopterDisposable.dispose();
+            }
+            catch (err) {
+                logger?.warn(`[${tag}] Adopter disposable threw on cleanup: ${err?.message ?? err}`);
+            }
+            connection.dispose();
+            const idx = activeConnections.indexOf(entry);
+            if (idx >= 0) {
+                activeConnections.splice(idx, 1);
+            }
+        };
+        socket.on('close', dispose);
+        connection.onClose(() => dispose());
+        connection.listen();
+    });
+    netServer.listen(port);
+    netServer.on('listening', () => {
+        const addressInfo = netServer.address();
+        if (!addressInfo) {
+            logger?.error(`[${tag}] Could not resolve address info. Shutting down.`);
+            started.reject(new Error(`${tag} could not resolve address info`));
+            netServer.close();
+            return;
+        }
+        if (typeof addressInfo === 'string') {
+            logger?.error(`[${tag}] Unexpectedly listening to pipe or domain socket "${addressInfo}". Shutting down.`);
+            started.reject(new Error(`${tag} bound to pipe/domain socket "${addressInfo}", expected TCP`));
+            netServer.close();
+            return;
+        }
+        handle.port = addressInfo.port;
+        logger?.info(`[${tag}] Ready to accept new client requests on port: ${addressInfo.port}`);
+        started.resolve();
+    });
+    netServer.on('error', err => {
+        logger?.error(`[${tag}] Error: ${err.message}`);
+        started.reject(err);
+    });
+    netServer.on('close', () => {
+        // Active client cleanup. Snapshot first since `dispose()` mutates
+        // the array.
+        for (const entry of activeConnections.slice()) {
+            try {
+                entry.adopterDisposable.dispose();
+            }
+            catch (err) {
+                logger?.warn(`[${tag}] Adopter disposable threw on shutdown: ${err?.message ?? err}`);
+            }
+            entry.connection.dispose();
+        }
+        activeConnections.length = 0;
+        stopped.resolve();
+    });
+    return {
+        get port() {
+            return handle.port;
+        },
+        started: started.promise,
+        stopped: stopped.promise,
+        close() {
+            netServer.close();
+        }
+    };
+}
+/**
+ * Register a `<command>` request handler on the language-server LSP
+ * connection that returns the port. Adopter clients call this command
+ * to discover the head's port after the LSP handshake.
+ *
+ * No-op (returns a `{ dispose() {} }` disposable) when `lspConnection`
+ * is `undefined` — Langium leaves `shared.lsp.Connection` optional and
+ * adopters running headless (no LSP wire) want the same launcher
+ * helpers to work.
+ *
+ * Adopters typically pass `services.shared.lsp.Connection`; both
+ * `services.shared.lsp.Connection?` and the structural `LspConnectionLike`
+ * shape are accepted.
+ */
+export function publishPortOnLspConnection(lspConnection, command, port) {
+    if (!lspConnection) {
+        return { dispose: () => undefined };
+    }
+    return lspConnection.onRequest(command, () => port);
+}
+//# sourceMappingURL=socket-launcher.js.map

package/lib/node/socket-launcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-launcher.js","sourceRoot":"","sources":["../../src/node/socket-launcher.ts"],"names":[],"mappings":"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"}

package/lib/node/stdio-launcher.d.ts

@@ -0,0 +1,88 @@
+/********************************************************************************
+ * 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 { Disposable, Logger } from '@hydranium/protocol';
+import type { MessageConnection } from 'vscode-jsonrpc';
+import type { IntegratedServer } from '../launcher/integrated-server.js';
+import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
+import { type WorkspaceFolderInput } from '../langium/workspace/initialize-workspace.js';
+/** Construction-time options for {@link startStdioServer}. */
+export interface StdioServerOptions {
+    /**
+     * Shared services tree whose workspace is brought up before the first
+     * request is dispatched. Required, because the ordering guarantee this
+     * launcher exists to provide is stated in terms of it.
+     */
+    readonly shared: ServerSharedServicesMinimal;
+    /**
+     * Workspace root(s) to initialize — a filesystem path or a `URI`. Omit when
+     * the caller has already initialized the workspace itself, in which case the
+     * launcher only wires the transport.
+     */
+    readonly workspace?: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>;
+    /**
+     * Optional logger for lifecycle lines. Omitted means silent — note that a
+     * logger writing to **stdout** would corrupt this head's protocol stream, so
+     * anything passed here must sink elsewhere. The framework's own `LspLogger`
+     * writes to stderr when no LSP connection is bound, which is correct here.
+     */
+    readonly logger?: Logger;
+    /** Tag included in lifecycle log lines. Default `"StdioServer"`. */
+    readonly logTag?: string;
+    /**
+     * Input stream carrying inbound JSON-RPC. Default `process.stdin`. Overriding
+     * it is what lets a test drive the launcher over an in-memory duplex pair
+     * instead of spawning a process.
+     */
+    readonly input?: NodeJS.ReadableStream;
+    /** Output stream for outbound JSON-RPC. Default `process.stdout`. */
+    readonly output?: NodeJS.WritableStream;
+}
+/**
+ * Live stdio server handle returned by {@link startStdioServer}.
+ *
+ * - {@link IntegratedServer.started} resolves once the workspace is initialized
+ *   AND the connection is listening — i.e. once the head can actually answer.
+ *   It rejects if workspace initialization throws, so a caller awaiting it sees
+ *   a failed startup rather than a server that is listening but empty.
+ * - {@link IntegratedServer.stopped} resolves when the connection closes.
+ */
+export interface StartedStdioServer extends IntegratedServer {
+    /** The underlying connection, for callers wanting fine-grained control. */
+    readonly connection: MessageConnection;
+    /** Dispose the adopter's per-connection state and close the connection. */
+    close(): void;
+}
+/**
+ * Start a **stdio**-based protocol head — the transport `hydranium-cli` speaks,
+ * since `query` / `save` / `projects` / `watch` all spawn a server command and
+ * drive JSON-RPC over its stdin/stdout. The socket counterpart is
+ * `startSocketServer`; the two differ more
+ * than the transport swap suggests, and the differences are the reason this is
+ * a launcher rather than four lines in each adopter's entry.
+ *
+ * **One client, not N.** A socket head accepts arbitrarily many connections and
+ * tracks them; a stdio head has exactly one peer — the process that spawned it
+ * — for its whole lifetime. There is no accept loop and no connection registry.
+ *
+ * **Workspace initialization is the launcher's job, and its ordering is the
+ * guarantee.** A stdio data head typically has no LSP connection, so it never
+ * receives `initialize` / `initialized` and nothing else will bring the
+ * workspace up. Worse, the ordering is easy to get subtly wrong: initialization
+ * must complete **before** `connection.listen()`, because nothing reads the
+ * input stream until the reader is attached, so a request that arrives during
+ * startup waits in the pipe buffer. Listening first and initializing
+ * concurrently instead leaves the outcome to whichever internal lock happened
+ * to be held when the request landed — a race, not a guarantee, and one that
+ * shows up as an empty project registry under load rather than as an error.
+ *
+ * The `onConnection` callback runs BEFORE initialization so handlers are
+ * registered first, matching `startSocketServer`'s pre-`listen()` contract.
+ */
+export declare function startStdioServer(options: StdioServerOptions, onConnection: (connection: MessageConnection) => Disposable): StartedStdioServer;
+//# sourceMappingURL=stdio-launcher.d.ts.map

package/lib/node/stdio-launcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-launcher.d.ts","sourceRoot":"","sources":["../../src/node/stdio-launcher.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAGlF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AACjF,OAAO,EAAuC,KAAK,oBAAoB,EAAE,MAAM,8CAA8C,CAAC;AAE9H,8DAA8D;AAC9D,MAAM,WAAW,kBAAkB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,oBAAoB,GAAG,aAAa,CAAC,oBAAoB,CAAC,CAAC;IAChF;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IACvC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;CAC1C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IACzD,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC,2EAA2E;IAC3E,KAAK,IAAI,IAAI,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,CAC7B,OAAO,EAAE,kBAAkB,EAC3B,YAAY,EAAE,CAAC,UAAU,EAAE,iBAAiB,KAAK,UAAU,GAC3D,kBAAkB,CAsDpB"}

package/lib/node/stdio-launcher.js

@@ -0,0 +1,83 @@
+/********************************************************************************
+ * 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 { Deferred } from '@hydranium/langium';
+import { createMessageConnection, StreamMessageReader, StreamMessageWriter } from 'vscode-jsonrpc/node';
+import { initializeWorkspaceProgrammatically } from '../langium/workspace/initialize-workspace.js';
+/**
+ * Start a **stdio**-based protocol head — the transport `hydranium-cli` speaks,
+ * since `query` / `save` / `projects` / `watch` all spawn a server command and
+ * drive JSON-RPC over its stdin/stdout. The socket counterpart is
+ * `startSocketServer`; the two differ more
+ * than the transport swap suggests, and the differences are the reason this is
+ * a launcher rather than four lines in each adopter's entry.
+ *
+ * **One client, not N.** A socket head accepts arbitrarily many connections and
+ * tracks them; a stdio head has exactly one peer — the process that spawned it
+ * — for its whole lifetime. There is no accept loop and no connection registry.
+ *
+ * **Workspace initialization is the launcher's job, and its ordering is the
+ * guarantee.** A stdio data head typically has no LSP connection, so it never
+ * receives `initialize` / `initialized` and nothing else will bring the
+ * workspace up. Worse, the ordering is easy to get subtly wrong: initialization
+ * must complete **before** `connection.listen()`, because nothing reads the
+ * input stream until the reader is attached, so a request that arrives during
+ * startup waits in the pipe buffer. Listening first and initializing
+ * concurrently instead leaves the outcome to whichever internal lock happened
+ * to be held when the request landed — a race, not a guarantee, and one that
+ * shows up as an empty project registry under load rather than as an error.
+ *
+ * The `onConnection` callback runs BEFORE initialization so handlers are
+ * registered first, matching `startSocketServer`'s pre-`listen()` contract.
+ */
+export function startStdioServer(options, onConnection) {
+    const logger = options.logger;
+    const tag = options.logTag ?? 'StdioServer';
+    const started = new Deferred();
+    const stopped = new Deferred();
+    const connection = createMessageConnection(new StreamMessageReader(options.input ?? process.stdin), new StreamMessageWriter(options.output ?? process.stdout));
+    const adopterDisposable = onConnection(connection);
+    let disposed = false;
+    const close = () => {
+        if (disposed) {
+            return;
+        }
+        disposed = true;
+        try {
+            adopterDisposable.dispose();
+        }
+        catch (err) {
+            logger?.warn(`[${tag}] Adopter disposable threw on cleanup: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        connection.dispose();
+        stopped.resolve();
+    };
+    connection.onClose(() => close());
+    const begin = async () => {
+        if (options.workspace !== undefined) {
+            logger?.info(`[${tag}] Initializing workspace`);
+            await initializeWorkspaceProgrammatically(options.shared, options.workspace);
+        }
+        // Only now attach the reader — see the ordering note in the doc above.
+        connection.listen();
+        logger?.info(`[${tag}] Listening on stdio`);
+    };
+    begin().then(() => started.resolve(), (err) => {
+        // A failed startup must not leave a half-live head: report it on
+        // `started` and tear the connection down rather than listening over an
+        // uninitialized workspace.
+        logger?.error(`[${tag}] Startup failed: ${err instanceof Error ? err.message : String(err)}`);
+        started.reject(err);
+        close();
+    });
+    // `started` is always observed internally, so a caller that ignores it can
+    // never crash the process with an unhandled rejection.
+    void started.promise.catch(() => undefined);
+    return { started: started.promise, stopped: stopped.promise, connection, close };
+}
+//# sourceMappingURL=stdio-launcher.js.map

package/lib/node/stdio-launcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-launcher.js","sourceRoot":"","sources":["../../src/node/stdio-launcher.ts"],"names":[],"mappings":"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"}