@hydranium/cli 1.0.0-next.189 → 1.0.0-next.192

package/src/commands/query-args.ts

@@ -11,6 +11,7 @@ import {
    assertRequired,
    exitWithUsage,
    helpRequested,
+   logHelpLines,
    parseFlagOptions,
    parseServerSpawnOptions,
    printHelp,
@@ -35,7 +36,7 @@ export const QUERY_VALUE_FLAGS: readonly string[] = QUERY_FLAGS;
 
 /** The `--help` text, as data, held to {@link QUERY_FLAGS} by a test. */
 export const QUERY_HELP: readonly string[] = [
-   'Usage: hydranium-cli query --server "<cmd> [args...]" --uri <uri> [--cwd <dir>] [--log-level <level>]',
+   'Usage: hydranium-cli query --server "<cmd> [args...]" --uri <uri> [--cwd <dir>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    'Print the data-server document envelope for `<uri>` as a single JSON line.',
    '',
@@ -43,13 +44,13 @@ export const QUERY_HELP: readonly string[] = [
    '  --server "<cmd>"   Command-line for the data-server subprocess (required).',
    '  --uri <uri>        Document URI (required).',
    '  --cwd <dir>        Working directory for the spawned child. Default: cwd.',
-   '  --log-level <lvl>  Log threshold for the spawned server (off|error|warn|info|debug|trace).'
+   ...logHelpLines(19, 'the spawned server')
 ];
 
 export function parseQueryArgs(args: string[], onError: UsageError = exitWithUsage): QueryCommandOptions {
-   const { serverCommand, serverArgs, cwd, logLevel, extra } = parseServerSpawnOptions(args, 'query', onError);
+   const { serverCommand, serverArgs, cwd, logLevel, logFile, logFileLevel, extra } = parseServerSpawnOptions(args, 'query', onError);
    const { uri } = parseFlagOptions(extra, 'query', OWN_FLAGS, onError);
-   return { serverCommand, serverArgs, cwd, logLevel, uri: assertRequired(uri, '--uri', 'query', onError) };
+   return { serverCommand, serverArgs, cwd, logLevel, logFile, logFileLevel, uri: assertRequired(uri, '--uri', 'query', onError) };
 }
 
 export function runQueryCommand(args: string[]): Promise<void> {

package/src/commands/query.ts

@@ -7,9 +7,9 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { LogThreshold, TransferElement } from '@hydranium/protocol';
+import type { TransferElement } from '@hydranium/protocol';
 import type { DataServerProtocol } from '@hydranium/protocol/data';
-import { logLevelEnv } from '../log-level.js';
+import { logEnv, type LogOptions } from '../log-level.js';
 import { withDataServer } from '../spawn-data-server.js';
 
 /**
@@ -22,12 +22,10 @@ import { withDataServer } from '../spawn-data-server.js';
  * Test-only `__proxyForTest` bypasses the spawn for unit tests; the
  * production CLI never passes it.
  */
-export interface QueryCommandOptions {
+export interface QueryCommandOptions extends LogOptions {
    readonly serverCommand: string;
    readonly serverArgs?: readonly string[];
    readonly cwd?: string;
-   /** Log threshold for the spawned server, set on its `HYDRANIUM_LOG_LEVEL` env. */
-   readonly logLevel?: LogThreshold;
    readonly uri: string;
    readonly write?: (line: string) => void;
    readonly __proxyForTest?: DataServerProtocol<TransferElement>;
@@ -48,7 +46,7 @@ export async function runQuery(options: QueryCommandOptions): Promise<void> {
          command: options.serverCommand,
          args: options.serverArgs,
          cwd: options.cwd,
-         env: options.logLevel ? logLevelEnv(options.logLevel) : undefined
+         env: logEnv(options)
       },
       async server => {
          const doc = await server.getModelDocument({ uri: options.uri, includeDiagnostics: true });

package/src/commands/reflect-args.ts

@@ -10,9 +10,9 @@
 import {
    exitWithUsage,
    helpRequested,
-   LOG_LEVEL_FLAG,
-   logLevelHelpLine,
-   logLevelOption,
+   LOG_VALUE_FLAGS,
+   logHelpLines,
+   logOptions,
    parseHarnessArgs,
    printHelp,
    SERVICES_FLAG,
@@ -21,7 +21,7 @@ import {
 import { OUT_FILE_FLAG } from './headless-harness.js';
 import { runReflect, type ReflectCommandOptions } from './reflect.js';
 
-const VALUE_FLAGS = [OUT_FILE_FLAG, LOG_LEVEL_FLAG] as const;
+const VALUE_FLAGS = [OUT_FILE_FLAG, ...LOG_VALUE_FLAGS] as const;
 const BOOL_FLAGS = ['--json'] as const;
 
 /**
@@ -36,7 +36,7 @@ export const REFLECT_VALUE_FLAGS: readonly string[] = [SERVICES_FLAG, ...VALUE_F
 
 /** The `--help` text, as data, held to {@link REFLECT_FLAGS} by a test. */
 export const REFLECT_HELP: readonly string[] = [
-   'Usage: hydranium-cli reflect --services <module> [--json] [--out-file <file>] [--log-level <lvl>]',
+   'Usage: hydranium-cli reflect --services <module> [--json] [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    "Dump a head's grammar/AST reflection — the type hierarchy, each language's",
    'terminals and entry rule, and every cross-reference target. Read-only: no',
@@ -50,7 +50,7 @@ export const REFLECT_HELP: readonly string[] = [
    '  --out-file <file>     Write the report to this file instead of stdout. Written',
    '                        only once the report exists, unlike a shell redirection,',
    '                        which truncates the file before the head is even booted.',
-   logLevelHelpLine(22)
+   ...logHelpLines(22)
 ];
 
 export function parseReflectArgs(args: string[], onError: UsageError = exitWithUsage): ReflectCommandOptions {
@@ -62,7 +62,7 @@ export function parseReflectArgs(args: string[], onError: UsageError = exitWithU
       servicesModule,
       json: options['--json'] === 'true',
       outFile: options[OUT_FILE_FLAG],
-      logLevel: logLevelOption(options[LOG_LEVEL_FLAG])
+      ...logOptions(options)
    };
 }
 

package/src/commands/save-args.ts

@@ -11,6 +11,7 @@ import {
    assertRequired,
    exitWithUsage,
    helpRequested,
+   logHelpLines,
    parseFlagOptions,
    parseServerSpawnOptions,
    printHelp,
@@ -36,7 +37,7 @@ export const SAVE_VALUE_FLAGS: readonly string[] = SAVE_FLAGS;
 
 /** The `--help` text, as data, held to {@link SAVE_FLAGS} by a test. */
 export const SAVE_HELP: readonly string[] = [
-   'Usage: hydranium-cli save --server "<cmd>..." --uri <uri> --content <text|@file> [--client-id <id>] [--cwd <dir>] [--log-level <level>]',
+   'Usage: hydranium-cli save --server "<cmd>..." --uri <uri> --content <text|@file> [--client-id <id>] [--cwd <dir>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    'Update the document at `<uri>` with `<content>` and persist via saveModelDocument.',
    'Output is the post-save envelope as a single JSON line.',
@@ -48,17 +49,19 @@ export const SAVE_HELP: readonly string[] = [
    '                        (escape with `\\@` for literal `@`-leading content).',
    '  --client-id <id>      clientId for authorship attribution. Default: hydranium-cli.',
    '  --cwd <dir>           Working directory for the spawned child. Default: cwd.',
-   '  --log-level <lvl>     Log threshold for the spawned server (off|error|warn|info|debug|trace).'
+   ...logHelpLines(22, 'the spawned server')
 ];
 
 export function parseSaveArgs(args: string[], onError: UsageError = exitWithUsage): SaveCommandOptions {
-   const { serverCommand, serverArgs, cwd, logLevel, extra } = parseServerSpawnOptions(args, 'save', onError);
+   const { serverCommand, serverArgs, cwd, logLevel, logFile, logFileLevel, extra } = parseServerSpawnOptions(args, 'save', onError);
    const { uri, content, clientId } = parseFlagOptions(extra, 'save', OWN_FLAGS, onError);
    return {
       serverCommand,
       serverArgs,
       cwd,
       logLevel,
+      logFile,
+      logFileLevel,
       uri: assertRequired(uri, '--uri', 'save', onError),
       content: assertRequired(content, '--content', 'save', onError),
       clientId

package/src/commands/save.ts

@@ -7,10 +7,10 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { LogThreshold, TransferElement } from '@hydranium/protocol';
+import type { TransferElement } from '@hydranium/protocol';
 import type { DataServerProtocol } from '@hydranium/protocol/data';
 import * as fs from 'node:fs/promises';
-import { logLevelEnv } from '../log-level.js';
+import { logEnv, type LogOptions } from '../log-level.js';
 import { withDataServer } from '../spawn-data-server.js';
 
 /**
@@ -29,12 +29,10 @@ import { withDataServer } from '../spawn-data-server.js';
  * opens it otherwise, saves, and ends the session, which leaves nothing open
  * behind it.
  */
-export interface SaveCommandOptions {
+export interface SaveCommandOptions extends LogOptions {
    readonly serverCommand: string;
    readonly serverArgs?: readonly string[];
    readonly cwd?: string;
-   /** Log threshold for the spawned server, set on its `HYDRANIUM_LOG_LEVEL` env. */
-   readonly logLevel?: LogThreshold;
    readonly uri: string;
    /** Literal content text, or `@<path>` to read from a file. */
    readonly content: string;
@@ -60,7 +58,7 @@ export async function runSave(options: SaveCommandOptions): Promise<void> {
          command: options.serverCommand,
          args: options.serverArgs,
          cwd: options.cwd,
-         env: options.logLevel ? logLevelEnv(options.logLevel) : undefined
+         env: logEnv(options)
       },
       async server => {
          write(`${JSON.stringify(await saveOpened(server, options.uri, clientId, model))}\n`);

package/src/commands/validate-args.ts

@@ -10,9 +10,9 @@
 import {
    exitWithUsage,
    helpRequested,
-   LOG_LEVEL_FLAG,
-   logLevelHelpLine,
-   logLevelOption,
+   LOG_VALUE_FLAGS,
+   logHelpLines,
+   logOptions,
    parseHarnessArgs,
    printHelp,
    SERVICES_FLAG,
@@ -21,7 +21,7 @@ import {
 import { OUT_FILE_FLAG } from './headless-harness.js';
 import { runValidate, type ValidateCommandOptions } from './validate.js';
 
-const VALUE_FLAGS = [OUT_FILE_FLAG, LOG_LEVEL_FLAG] as const;
+const VALUE_FLAGS = [OUT_FILE_FLAG, ...LOG_VALUE_FLAGS] as const;
 const BOOL_FLAGS = ['--strict', '--json'] as const;
 
 /**
@@ -36,7 +36,7 @@ export const VALIDATE_VALUE_FLAGS: readonly string[] = [SERVICES_FLAG, ...VALUE_
 
 /** The `--help` text, as data, held to {@link VALIDATE_FLAGS} by a test. */
 export const VALIDATE_HELP: readonly string[] = [
-   'Usage: hydranium-cli validate --services <module> <workspace> [--strict] [--json] [--out-file <file>] [--log-level <lvl>]',
+   'Usage: hydranium-cli validate --services <module> <workspace> [--strict] [--json] [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    'Build a workspace headlessly and report its validation diagnostics — a CI gate:',
    'the process exits non-zero when any error is found. `<module>` is an ESM module',
@@ -52,7 +52,7 @@ export const VALIDATE_HELP: readonly string[] = [
    '                        still decides the exit code, and the file is written only',
    '                        once the report exists, unlike a shell redirection, which',
    '                        truncates the file before the workspace is even built.',
-   logLevelHelpLine(22)
+   ...logHelpLines(22)
 ];
 
 export function parseValidateArgs(args: string[], onError: UsageError = exitWithUsage): ValidateCommandOptions {
@@ -63,7 +63,7 @@ export function parseValidateArgs(args: string[], onError: UsageError = exitWith
       strict: options['--strict'] === 'true',
       json: options['--json'] === 'true',
       outFile: options[OUT_FILE_FLAG],
-      logLevel: logLevelOption(options[LOG_LEVEL_FLAG])
+      ...logOptions(options)
    };
 }
 

package/src/commands/watch-args.ts

@@ -11,6 +11,7 @@ import {
    assertRequired,
    exitWithUsage,
    helpRequested,
+   logHelpLines,
    parseFlagOptions,
    parseServerSpawnOptions,
    printHelp,
@@ -35,7 +36,7 @@ export const WATCH_VALUE_FLAGS: readonly string[] = WATCH_FLAGS;
 
 /** The `--help` text, as data, held to {@link WATCH_FLAGS} by a test. */
 export const WATCH_HELP: readonly string[] = [
-   'Usage: hydranium-cli watch --server "<cmd>..." --uri <uri> [--client-id <id>] [--cwd <dir>] [--log-level <level>]',
+   'Usage: hydranium-cli watch --server "<cmd>..." --uri <uri> [--client-id <id>] [--cwd <dir>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    'Subscribe to document updates at `<uri>` and print events as newline-delimited',
    'JSON. Long-running — exits cleanly on SIGINT (Ctrl-C).',
@@ -45,18 +46,20 @@ export const WATCH_HELP: readonly string[] = [
    '  --uri <uri>           Document URI (required).',
    '  --client-id <id>      Subscriber identity. Default: hydranium-cli.',
    '  --cwd <dir>           Working directory for the spawned child. Default: cwd.',
-   '  --log-level <lvl>     Log threshold for the spawned server (off|error|warn|info|debug|trace).'
+   ...logHelpLines(22, 'the spawned server')
 ];
 
 /** Parse the argv; the abort signal is the entry point's to supply, not the command line's. */
 export function parseWatchArgs(args: string[], onError: UsageError = exitWithUsage): WatchCommandOptions {
-   const { serverCommand, serverArgs, cwd, logLevel, extra } = parseServerSpawnOptions(args, 'watch', onError);
+   const { serverCommand, serverArgs, cwd, logLevel, logFile, logFileLevel, extra } = parseServerSpawnOptions(args, 'watch', onError);
    const { uri, clientId } = parseFlagOptions(extra, 'watch', OWN_FLAGS, onError);
    return {
       serverCommand,
       serverArgs,
       cwd,
       logLevel,
+      logFile,
+      logFileLevel,
       uri: assertRequired(uri, '--uri', 'watch', onError),
       clientId
    };

package/src/commands/watch.ts

@@ -7,14 +7,14 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { LogThreshold, TransferElement } from '@hydranium/protocol';
+import type { TransferElement } from '@hydranium/protocol';
 import type {
    DataClientProtocol,
    DataServerProtocol,
    TransferDocumentDeletedEvent,
    TransferDocumentUpdatedEvent
 } from '@hydranium/protocol/data';
-import { logLevelEnv } from '../log-level.js';
+import { logEnv, type LogOptions } from '../log-level.js';
 import { spawnDataServer } from '../spawn-data-server.js';
 
 /**
@@ -27,12 +27,10 @@ import { spawnDataServer } from '../spawn-data-server.js';
  * — production CLI wires SIGINT directly. `__handleForTest` bypasses
  * the spawn step for unit tests.
  */
-export interface WatchCommandOptions {
+export interface WatchCommandOptions extends LogOptions {
    readonly serverCommand: string;
    readonly serverArgs?: readonly string[];
    readonly cwd?: string;
-   /** Log threshold for the spawned server, set on its `HYDRANIUM_LOG_LEVEL` env. */
-   readonly logLevel?: LogThreshold;
    readonly uri: string;
    readonly clientId?: string;
    readonly write?: (line: string) => void;
@@ -169,7 +167,7 @@ export async function runWatch(options: WatchCommandOptions): Promise<void> {
             command: options.serverCommand,
             args: options.serverArgs,
             cwd: options.cwd,
-            env: options.logLevel ? logLevelEnv(options.logLevel) : undefined
+            env: logEnv(options)
          },
          localClient
       );

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. */
+   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;
 }