@hydranium/cli 1.0.0-next.30 → 1.0.0-next.301

package/src/log-level.ts

@@ -7,29 +7,47 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { DEFAULT_LOG_LEVEL_ENV, LEVEL_ORDER, parseLogLevel, type LogThreshold } from '@hydranium/protocol';
+import {
+   DEFAULT_LOG_FILE_ENV,
+   DEFAULT_LOG_FILE_LEVEL_ENV,
+   DEFAULT_LOG_LEVEL_ENV,
+   LEVEL_ORDER,
+   parseLogLevel,
+   type LogThreshold
+} from '@hydranium/protocol';
+
+/** The log flags every subcommand takes, as the env {@link logEnv} hands its child. */
+export interface LogOptions {
+   /** Threshold for the client sink; the server's log-level setting replaces it. */
+   readonly logLevel?: LogThreshold;
+   /** File the server tees its log to; `{workspace}` expands once it is known, `{pid}` from the start. */
+   readonly logFile?: string;
+   /** The file's own threshold, which the log-level setting does not change. */
+   readonly logFileLevel?: LogThreshold;
+}
 
 /**
- * Validate a raw `--log-level` argument into a {@link LogThreshold}. Throws on
- * an unrecognised value so the CLI's top-level `catch` surfaces a clean error
- * and exits non-zero (mirroring how the other option parsers fail fast). Use
- * for the argv-supplied value; the resolved threshold is handed to
- * {@link logLevelEnv} to target the spawned server.
+ * Validate a raw `--log-level` / `--log-file-level` argument into a
+ * {@link LogThreshold}. Throws on an unrecognised value so the CLI's top-level
+ * `catch` surfaces a clean error and exits non-zero (mirroring how the other
+ * option parsers fail fast). Use for the argv-supplied value; the resolved
+ * threshold is handed to {@link logEnv} to target the spawned server.
  */
-export function parseLogLevelOption(raw: string): LogThreshold {
+export function parseLogLevelOption(raw: string, flag = '--log-level'): LogThreshold {
    const level = parseLogLevel(raw);
    if (!level) {
-      throw new Error(`Invalid --log-level: ${raw} (expected one of: ${Object.keys(LEVEL_ORDER).join(', ')})`);
+      throw new Error(`Invalid ${flag}: ${raw} (expected one of: ${Object.keys(LEVEL_ORDER).join(', ')})`);
    }
    return level;
 }
 
 /**
  * Build the environment override that targets *only the spawned server's* log
- * threshold. Passed to `spawnDataServer` as `env`, it sets the same
- * `HYDRANIUM_LOG_LEVEL` variable the server reads at startup — the CLI's own
- * logging is unaffected, unlike an ambient `HYDRANIUM_LOG_LEVEL=…` that the
- * child would inherit alongside the parent. The server owns *how* log level
+ * configuration, or `undefined` when no log flag was given. Passed to
+ * `spawnDataServer` as `env`, it sets the same `HYDRANIUM_LOG_LEVEL` /
+ * `HYDRANIUM_LOG_FILE` / `HYDRANIUM_LOG_FILE_LEVEL` variables the server reads
+ * at startup — the CLI's own logging is unaffected, unlike ambient variables
+ * that the child would inherit alongside the parent. The server owns *how* log level
  * works; this only routes the CLI's request onto the channel it already reads.
  *
  * **The variable is read by `LspLogger`'s constructor**, which is bound on the
@@ -44,6 +62,16 @@ export function parseLogLevelOption(raw: string): LogThreshold {
  * not go to stdout: that is the JSON-RPC channel, so a log line there would
  * corrupt the very request this flag was set to diagnose.
  */
-export function logLevelEnv(level: LogThreshold): Record<string, string> {
-   return { [DEFAULT_LOG_LEVEL_ENV]: level };
+export function logEnv(options: LogOptions): Record<string, string> | undefined {
+   const env: Record<string, string> = {};
+   if (options.logLevel !== undefined) {
+      env[DEFAULT_LOG_LEVEL_ENV] = options.logLevel;
+   }
+   if (options.logFile !== undefined) {
+      env[DEFAULT_LOG_FILE_ENV] = options.logFile;
+   }
+   if (options.logFileLevel !== undefined) {
+      env[DEFAULT_LOG_FILE_LEVEL_ENV] = options.logFileLevel;
+   }
+   return Object.keys(env).length > 0 ? env : undefined;
 }

package/src/spawn-data-server.ts

@@ -15,7 +15,14 @@ import {
    type DataServerProtocol
 } from '@hydranium/protocol/data';
 import { type ChildProcess, spawn } from 'node:child_process';
-import { StreamMessageReader, StreamMessageWriter, createMessageConnection, type MessageConnection } from 'vscode-jsonrpc/node';
+import {
+   StreamMessageReader,
+   StreamMessageWriter,
+   createMessageConnection,
+   type Logger as ConnectionLogger,
+   type MessageConnection
+} from 'vscode-jsonrpc/node';
+import { STDERR_CONNECTION_LOGGER } from './stderr-connection-logger.js';
 
 /**
  * Options for {@link spawnDataServer}. `command` is the binary or script
@@ -49,6 +56,11 @@ export interface SpawnDataServerOptions {
     * scripted use; set to `'pipe'` to capture for assertion in tests.
     */
    readonly stderr?: 'inherit' | 'ignore' | 'pipe';
+   /**
+    * Where the connection to the child logs its protocol faults, such as a
+    * response that matches no request. Default: this process's stderr.
+    */
+   readonly logger?: ConnectionLogger;
 }
 
 /**
@@ -143,7 +155,7 @@ export function spawnDataServer<TTransfer extends TransferElement, TDiagnostic e
 
    const reader = new StreamMessageReader(child.stdout);
    const writer = new StreamMessageWriter(child.stdin);
-   const connection = createMessageConnection(reader, writer);
+   const connection = createMessageConnection(reader, writer, options.logger ?? STDERR_CONNECTION_LOGGER);
    // Consume transport error / close so a child that dies mid-stream (its stdout
    // closing, a write landing on a torn-down stdin) is observed here rather than
    // escaping as an unhandled error — the death is reported via `whenTerminated`.
@@ -224,9 +236,9 @@ export function spawnDataServer<TTransfer extends TransferElement, TDiagnostic e
  * child down afterwards. The `use` call is raced against
  * {@link DataServerHandle.whenTerminated}, so a spawn failure or a premature child
  * exit rejects with a clear message instead of hanging on an RPC that can never be
- * answered. This is the one-shot counterpart the `projects` / `query` / `save`
- * subcommands compose; `watch` races its own long-running loop against
- * `whenTerminated` directly.
+ * answered. This is the one-shot counterpart the data-server subcommands
+ * compose; `watch` races its own long-running loop against `whenTerminated`
+ * directly.
  */
 export async function withDataServer<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic, R>(
    options: SpawnDataServerOptions,

package/src/stderr-connection-logger.ts

@@ -0,0 +1,18 @@
+/********************************************************************************
+ * 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 { Logger as ConnectionLogger } from 'vscode-jsonrpc/node';
+
+/** Every connection line goes to stderr: stdout carries the command's output or the protocol stream. */
+export const STDERR_CONNECTION_LOGGER: ConnectionLogger = {
+   error: message => console.error(message),
+   warn: message => console.error(message),
+   info: message => console.error(message),
+   log: message => console.error(message)
+};

package/src/testing/echo-server.ts

@@ -20,8 +20,10 @@
 
 import { DataServer } from '@hydranium/data-server';
 import { makeTestServices } from '@hydranium/core/testing';
+import { describeErrorWithStack } from '@hydranium/protocol';
 import type { AstNode, URI } from '@hydranium/langium';
-import { StreamMessageReader, StreamMessageWriter, createMessageConnection } from 'vscode-jsonrpc/node';
+import { StreamMessageReader, StreamMessageWriter, createMessageConnection, type ResponseMessage } from 'vscode-jsonrpc/node';
+import { STDERR_CONNECTION_LOGGER } from '../stderr-connection-logger.js';
 
 interface FakeRoot extends AstNode {
    readonly $type: 'FakeRoot';
@@ -72,7 +74,14 @@ function main(): void {
       }
    };
 
-   const connection = createMessageConnection(new StreamMessageReader(process.stdin), new StreamMessageWriter(process.stdout));
+   const writer = new StreamMessageWriter(process.stdout);
+   const connection = createMessageConnection(new StreamMessageReader(process.stdin), writer, STDERR_CONNECTION_LOGGER);
+
+   if (process.argv.includes('--send-response-without-id')) {
+      // A response the parent cannot match to a request, for its connection to log.
+      const response: ResponseMessage = { jsonrpc: '2.0', id: null, result: null };
+      writer.write(response).catch((error: unknown) => STDERR_CONNECTION_LOGGER.error(describeErrorWithStack(error)));
+   }
 
    if (process.argv.includes('--exit-on-request')) {
       // Fail-fast fixture mode: read a full request (the reader parses the whole