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

package/lib/log-level.d.ts

@@ -7,20 +7,30 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 import { 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 declare function parseLogLevelOption(raw: string): LogThreshold;
+export declare function parseLogLevelOption(raw: string, flag?: string): LogThreshold;
 /**
  * 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
@@ -35,5 +45,5 @@ export declare 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 declare function logLevelEnv(level: LogThreshold): Record<string, string>;
+export declare function logEnv(options: LogOptions): Record<string, string> | undefined;
 //# sourceMappingURL=log-level.d.ts.map

package/lib/log-level.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log-level.d.ts","sourceRoot":"","sources":["../src/log-level.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAqD,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE3G;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAM7D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEvE"}
+{"version":3,"file":"log-level.d.ts","sourceRoot":"","sources":["../src/log-level.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAMJ,KAAK,YAAY,EACnB,MAAM,qBAAqB,CAAC;AAE7B,uFAAuF;AACvF,MAAM,WAAW,UAAU;IACxB,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACjC,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;CACvC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,SAAgB,GAAG,YAAY,CAMnF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAY9E"}

package/lib/log-level.js

@@ -6,27 +6,28 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { DEFAULT_LOG_LEVEL_ENV, LEVEL_ORDER, parseLogLevel } from '@hydranium/protocol';
+import { DEFAULT_LOG_FILE_ENV, DEFAULT_LOG_FILE_LEVEL_ENV, DEFAULT_LOG_LEVEL_ENV, LEVEL_ORDER, parseLogLevel } from '@hydranium/protocol';
 /**
- * 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) {
+export function parseLogLevelOption(raw, flag = '--log-level') {
     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
@@ -41,7 +42,17 @@ export function parseLogLevelOption(raw) {
  * 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) {
-    return { [DEFAULT_LOG_LEVEL_ENV]: level };
+export function logEnv(options) {
+    const env = {};
+    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;
 }
 //# sourceMappingURL=log-level.js.map

package/lib/log-level.js.map

@@ -1 +1 @@
-{"version":3,"file":"log-level.js","sourceRoot":"","sources":["../src/log-level.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,aAAa,EAAqB,MAAM,qBAAqB,CAAC;AAE3G;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC5C,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,CAAC,KAAK,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,wBAAwB,GAAG,sBAAsB,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5G,CAAC;IACD,OAAO,KAAK,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,WAAW,CAAC,KAAmB;IAC5C,OAAO,EAAE,CAAC,qBAAqB,CAAC,EAAE,KAAK,EAAE,CAAC;AAC7C,CAAC"}
+{"version":3,"file":"log-level.js","sourceRoot":"","sources":["../src/log-level.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,WAAW,EACX,aAAa,EAEf,MAAM,qBAAqB,CAAC;AAY7B;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW,EAAE,IAAI,GAAG,aAAa;IAClE,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,CAAC,KAAK,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,WAAW,IAAI,KAAK,GAAG,sBAAsB,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxG,CAAC;IACD,OAAO,KAAK,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,MAAM,CAAC,OAAmB;IACvC,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAClC,GAAG,CAAC,qBAAqB,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;IACjD,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,GAAG,CAAC,oBAAoB,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAC/C,CAAC;IACD,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACtC,GAAG,CAAC,0BAA0B,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC;IAC1D,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACxD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/cli",
-  "version": "1.0.0-next.189",
+  "version": "1.0.0-next.192",
   "description": "Build-time codegen tools + data-server subcommands for the hydranium framework.",
   "keywords": [
     "cli",
@@ -69,20 +69,20 @@
     "ts-morph": "^25.0.0"
   },
   "devDependencies": {
-    "@hydranium/core": "1.0.0-next.189",
-    "@hydranium/data-server": "1.0.0-next.189",
-    "@hydranium/langium": "1.0.0-next.189",
-    "@hydranium/protocol": "1.0.0-next.189",
+    "@hydranium/core": "1.0.0-next.192",
+    "@hydranium/data-server": "1.0.0-next.192",
+    "@hydranium/langium": "1.0.0-next.192",
+    "@hydranium/protocol": "1.0.0-next.192",
     "rimraf": "^5.0.0",
     "typescript": "^7.0.2",
     "vscode-jsonrpc": "9.0.1",
     "vscode-languageserver": "~10.0.1"
   },
   "peerDependencies": {
-    "@hydranium/core": "1.0.0-next.189",
-    "@hydranium/data-server": "1.0.0-next.189",
-    "@hydranium/langium": "1.0.0-next.189",
-    "@hydranium/protocol": "1.0.0-next.189",
+    "@hydranium/core": "1.0.0-next.192",
+    "@hydranium/data-server": "1.0.0-next.192",
+    "@hydranium/langium": "1.0.0-next.192",
+    "@hydranium/protocol": "1.0.0-next.192",
     "@memlab/core": "^2.0.3",
     "@memlab/heap-analysis": "^2.0.3",
     "vscode-jsonrpc": "9.0.1"

package/src/commands/ast-ground-truth-args.ts

@@ -11,9 +11,9 @@ import { runAstGroundTruth, type AstGroundTruthCommandOptions } from './ast-grou
 import {
    exitWithUsage,
    helpRequested,
-   LOG_LEVEL_FLAG,
-   logLevelHelpLine,
-   logLevelOption,
+   LOG_VALUE_FLAGS,
+   logHelpLines,
+   logOptions,
    parseHarnessArgs,
    printHelp,
    SERVICES_FLAG,
@@ -21,7 +21,7 @@ import {
 } from './harness-args.js';
 import { OUT_FILE_FLAG } from './headless-harness.js';
 
-const VALUE_FLAGS = [OUT_FILE_FLAG, LOG_LEVEL_FLAG] as const;
+const VALUE_FLAGS = [OUT_FILE_FLAG, ...LOG_VALUE_FLAGS] as const;
 
 /**
  * Every flag `ast-ground-truth` accepts, derived from the sets the parser is
@@ -35,7 +35,7 @@ export const AST_GROUND_TRUTH_VALUE_FLAGS: readonly string[] = AST_GROUND_TRUTH_
 
 /** The `--help` text, as data, held to {@link AST_GROUND_TRUTH_FLAGS} by a test. */
 export const AST_GROUND_TRUTH_HELP: readonly string[] = [
-   'Usage: hydranium-cli ast-ground-truth --services <module> <workspace> [--out-file <file>] [--log-level <lvl>]',
+   'Usage: hydranium-cli ast-ground-truth --services <module> <workspace> [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    "Tally a workspace's live-model AST nodes by `$type` — the ground truth that",
    '`analyze-heap --validate <gt.json>` checks a heap snapshot against. `<module>`',
@@ -46,12 +46,12 @@ export const AST_GROUND_TRUTH_HELP: readonly string[] = [
    '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
    '  <workspace>           Workspace root (path or file URI) to build (required).',
    '  --out-file <file>     Write the JSON to this file instead of stdout.',
-   logLevelHelpLine(22)
+   ...logHelpLines(22)
 ];
 
 export function parseAstGroundTruthArgs(args: string[], onError: UsageError = exitWithUsage): AstGroundTruthCommandOptions {
    const { servicesModule, workspace, options } = parseHarnessArgs(args, 'ast-ground-truth', VALUE_FLAGS, [], { onError });
-   return { servicesModule, workspace, outFile: options[OUT_FILE_FLAG], logLevel: logLevelOption(options[LOG_LEVEL_FLAG]) };
+   return { servicesModule, workspace, outFile: options[OUT_FILE_FLAG], ...logOptions(options) };
 }
 
 export function runAstGroundTruthCommand(args: string[]): Promise<void> {

package/src/commands/harness-args.ts

@@ -35,7 +35,7 @@ import type { LogThreshold } from '@hydranium/protocol';
 import { statSync } from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { parseLogLevelOption } from '../log-level.js';
+import { type LogOptions, parseLogLevelOption } from '../log-level.js';
 
 /**
  * How a parser reports a usage problem. It never returns, so a parser can treat
@@ -68,33 +68,57 @@ export const SERVICES_FLAG = '--services';
  * on which command a caller happened to reach for.
  */
 export const LOG_LEVEL_FLAG = '--log-level';
+export const LOG_FILE_FLAG = '--log-file';
+export const LOG_FILE_LEVEL_FLAG = '--log-file-level';
+
+/** The log flags every subcommand takes, read by {@link logOptions}. */
+export const LOG_VALUE_FLAGS = [LOG_LEVEL_FLAG, LOG_FILE_FLAG, LOG_FILE_LEVEL_FLAG] as const;
 
 /** The value flags {@link parseServerSpawnOptions} consumes itself. */
-export const SERVER_SPAWN_VALUE_FLAGS: readonly string[] = ['--server', '--cwd', LOG_LEVEL_FLAG];
+export const SERVER_SPAWN_VALUE_FLAGS: readonly string[] = ['--server', '--cwd', ...LOG_VALUE_FLAGS];
 
 /**
- * The `--help` line every subcommand describes {@link LOG_LEVEL_FLAG} with.
+ * The `--help` lines every subcommand describes {@link LOG_VALUE_FLAGS} with.
  *
  * Shared text, per-command padding: `command-args.test.ts` compares the flags a
  * help block DESCRIBES against the flags the parser accepts, and it recognises a
- * description by the two-space indent — so the line has to be a real option entry
+ * description by the two-space indent — so each line has to be a real option entry
  * in each block, and the column each block aligns its descriptions at is the
- * block's own.
+ * block's own. A flag too wide for that column takes its description on the
+ * next line, at the column.
  */
-export function logLevelHelpLine(padTo: number): string {
-   return `  ${`${LOG_LEVEL_FLAG} <lvl>`.padEnd(padTo)}Log threshold for the head this boots (off|error|warn|info|debug|trace).`;
+export function logHelpLines(padTo: number, head = 'the head this boots'): string[] {
+   const line = (flag: string, text: string): string[] =>
+      flag.length < padTo - 1 ? [`  ${flag.padEnd(padTo)}${text}`] : [`  ${flag}`, `${' '.repeat(padTo + 2)}${text}`];
+   return [
+      line(`${LOG_LEVEL_FLAG} <lvl>`, `Log threshold for ${head} (off|error|warn|info|debug|trace).`),
+      line(`${LOG_FILE_FLAG} <file>`, `Also write ${head}'s log to <file>; {workspace} expands to the workspace.`),
+      line(`${LOG_FILE_LEVEL_FLAG} <lvl>`, `Threshold for that file, which the log-level setting does not change.`)
+   ].flat();
 }
 
 /**
- * Narrow a raw {@link LOG_LEVEL_FLAG} value that {@link parseHarnessArgs}
- * collected, leaving an absent flag absent.
+ * Narrow the raw {@link LOG_VALUE_FLAGS} values a parser collected, leaving
+ * absent flags absent.
+ *
+ * `--log-file` resolves against the caller's directory: the child may run
+ * elsewhere (`--cwd`), and a relative path would land the log there.
  *
  * Throws rather than reaching `onError`, matching {@link parseServerSpawnOptions}:
  * the level vocabulary belongs to the protocol package, which reports it, and the
  * entry point's catch turns that into the same message-and-exit.
  */
-export function logLevelOption(value: string | undefined): LogThreshold | undefined {
-   return value === undefined ? undefined : parseLogLevelOption(value);
+export function logOptions(options: Readonly<Record<string, string | undefined>>): LogOptions {
+   const level = (flag: string): LogThreshold | undefined => {
+      const value = options[flag];
+      return value === undefined ? undefined : parseLogLevelOption(value, flag);
+   };
+   const logFile = options[LOG_FILE_FLAG];
+   return {
+      logLevel: level(LOG_LEVEL_FLAG),
+      logFile: logFile === undefined ? undefined : path.resolve(logFile),
+      logFileLevel: level(LOG_FILE_LEVEL_FLAG)
+   };
 }
 
 /**
@@ -336,11 +360,10 @@ function kebabToCamel(name: string): string {
 }
 
 /** What {@link parseServerSpawnOptions} recovered from an argv. */
-export interface SpawnOptions {
+export interface SpawnOptions extends LogOptions {
    serverCommand: string;
    serverArgs: string[];
    cwd?: string;
-   logLevel?: LogThreshold;
    /** The tokens this parser did not claim, for the subcommand's own options. */
    extra: string[];
 }
@@ -363,10 +386,10 @@ function isRelativePathToken(token: string, isCommand: boolean): boolean {
 
 /**
  * Shared option parser for subcommands that spawn a data-server child. Consumes
- * `--server` / `--cwd` / `--log-level` and returns the surviving tokens as
+ * `--server` / `--cwd` / the {@link LOG_VALUE_FLAGS} and returns the surviving tokens as
  * `extra` for {@link parseFlagOptions} to finish.
  *
- * An unrecognised `--log-level` value throws rather than reaching `onError`: the
+ * An unrecognised log level value throws rather than reaching `onError`: the
  * level vocabulary belongs to the protocol package, which reports it, and the
  * entry point's catch turns that into the same message-and-exit.
  *
@@ -383,7 +406,7 @@ function isRelativePathToken(token: string, isCommand: boolean): boolean {
 export function parseServerSpawnOptions(args: string[], commandName: string, onError: UsageError = exitWithUsage): SpawnOptions {
    let serverSpec: string | undefined;
    let cwd: string | undefined;
-   let logLevel: LogThreshold | undefined;
+   const logFlags: Record<string, string> = {};
    const extra: string[] = [];
    for (let index = 0; index < args.length; index += 1) {
       const flag = args[index];
@@ -399,8 +422,8 @@ export function parseServerSpawnOptions(args: string[], commandName: string, onE
          serverSpec = claim();
       } else if (flag === '--cwd') {
          cwd = claim();
-      } else if (flag === LOG_LEVEL_FLAG) {
-         logLevel = parseLogLevelOption(claim());
+      } else if ((LOG_VALUE_FLAGS as readonly string[]).includes(flag)) {
+         logFlags[flag] = claim();
       } else {
          extra.push(flag);
       }
@@ -425,5 +448,5 @@ export function parseServerSpawnOptions(args: string[], commandName: string, onE
          );
       }
    }
-   return { serverCommand, serverArgs, cwd, logLevel, extra };
+   return { serverCommand, serverArgs, cwd, ...logOptions(logFlags), extra };
 }

package/src/commands/headless-harness.ts

@@ -8,14 +8,13 @@
  ********************************************************************************/
 
 import type * as HydraniumCoreNode from '@hydranium/core/node';
-import type { LogThreshold } from '@hydranium/protocol';
 import { spawn } from 'node:child_process';
 import { statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import * as path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { driverHeapArgs, type HeapReading } from '../driver-heap.js';
-import { logLevelEnv } from '../log-level.js';
+import { logEnv, type LogOptions } from '../log-level.js';
 import { SERVICES_FLAG } from './harness-args.js';
 
 /** The flag every report-producing subcommand names its destination file with. */
@@ -131,14 +130,13 @@ export function spawnNodeChild(execArgs: string[], env?: Record<string, string>)
 /** How a subcommand parent reaches its driver child; the seam `__spawnForTest` replaces. */
 export type SpawnDriverChild = (execArgs: string[], env?: Record<string, string>) => Promise<number>;
 
-/** What every `--services` subcommand carries for the child it spawns, on top of its own options. */
-export interface DriverSpawnOptions {
-   /**
-    * Log threshold for the head the driver boots. Absent leaves the child's
-    * inherited environment alone, so an ambient `HYDRANIUM_LOG_LEVEL` still wins
-    * where a caller set one.
-    */
-   readonly logLevel?: LogThreshold;
+/**
+ * What every `--services` subcommand carries for the child it spawns, on top of
+ * its own options. The log options apply to the head the driver boots; an
+ * absent one leaves the child's inherited environment alone, so an ambient
+ * variable still wins where a caller set one.
+ */
+export interface DriverSpawnOptions extends LogOptions {
    /** Test-only: capture the node argv and env instead of spawning the real child. */
    readonly __spawnForTest?: SpawnDriverChild;
    /**
@@ -154,12 +152,12 @@ export interface DriverSpawnOptions {
  * Parent-side: run a subcommand's driver child and propagate its exit code, so a
  * shell or CI step sees the gate.
  *
- * **The log threshold travels in the child's ENVIRONMENT, not its argv.** The
- * head's logger reads `HYDRANIUM_LOG_LEVEL` while `createServices` constructs it,
- * which is inside the driver's dynamic import — a flag the driver parsed would
- * arrive after the only moment it can be read. Setting it here rather than
- * exporting it also leaves the CLI's own output alone, unlike an ambient
- * `HYDRANIUM_LOG_LEVEL=…` the parent would carry too.
+ * **The log options travel in the child's ENVIRONMENT, not its argv.** The
+ * head's logger reads its `HYDRANIUM_LOG_*` variables while `createServices`
+ * constructs it, which is inside the driver's dynamic import — a flag the driver
+ * parsed would arrive after the only moment it can be read. Setting them here
+ * rather than exporting them also leaves the CLI's own output alone, unlike
+ * ambient variables the parent would carry too.
  *
  * A head that binds a logger of its own decides for itself whether the flag means
  * anything, which is the intended seam: the CLI is language-agnostic and cannot
@@ -173,10 +171,7 @@ export interface DriverSpawnOptions {
  */
 export async function runDriverChild(execArgs: string[], options: DriverSpawnOptions): Promise<void> {
    const spawnChild = options.__spawnForTest ?? spawnNodeChild;
-   const code = await spawnChild(
-      [...driverHeapArgs(options.__heapReadingForTest), ...execArgs],
-      options.logLevel === undefined ? undefined : logLevelEnv(options.logLevel)
-   );
+   const code = await spawnChild([...driverHeapArgs(options.__heapReadingForTest), ...execArgs], logEnv(options));
    if (code) {
       process.exitCode = code;
    }

package/src/commands/lint-grammar-args.ts

@@ -10,9 +10,9 @@
 import {
    exitWithUsage,
    helpRequested,
-   LOG_LEVEL_FLAG,
-   logLevelHelpLine,
-   logLevelOption,
+   LOG_VALUE_FLAGS,
+   logHelpLines,
+   logOptions,
    parseHarnessArgs,
    printHelp,
    SERVICES_FLAG,
@@ -20,7 +20,7 @@ import {
 } from './harness-args.js';
 import { runLintGrammar, type LintGrammarCommandOptions } from './lint-grammar.js';
 
-const VALUE_FLAGS = [LOG_LEVEL_FLAG] as const;
+const VALUE_FLAGS = [...LOG_VALUE_FLAGS] as const;
 const BOOL_FLAGS = ['--strict', '--json'] as const;
 const REPEATABLE_VALUE_FLAGS = ['--name-property'] as const;
 
@@ -36,7 +36,7 @@ export const LINT_GRAMMAR_VALUE_FLAGS: readonly string[] = [SERVICES_FLAG, ...RE
 
 /** The `--help` text, as data, held to {@link LINT_GRAMMAR_FLAGS} by a test. */
 export const LINT_GRAMMAR_HELP: readonly string[] = [
-   'Usage: hydranium-cli lint-grammar --services <module> [--name-property <p>]... [--strict] [--json] [--log-level <lvl>]',
+   'Usage: hydranium-cli lint-grammar --services <module> [--name-property <p>]... [--strict] [--json] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    "Check a head's grammar against the framework's conventions — a CI gate: the",
    'process exits non-zero when a violation is found. Read-only: no workspace is',
@@ -52,7 +52,7 @@ export const LINT_GRAMMAR_HELP: readonly string[] = [
    '                         (repeatable). Default: name.',
    '  --strict               Also fail (non-zero exit) on warnings, not only errors.',
    '  --json                 Emit the raw JSON result instead of the human report.',
-   logLevelHelpLine(23)
+   ...logHelpLines(23)
 ];
 
 export function parseLintGrammarArgs(args: string[], onError: UsageError = exitWithUsage): LintGrammarCommandOptions {
@@ -66,7 +66,7 @@ export function parseLintGrammarArgs(args: string[], onError: UsageError = exitW
       nameProperties: values['--name-property'],
       strict: options['--strict'] === 'true',
       json: options['--json'] === 'true',
-      logLevel: logLevelOption(options[LOG_LEVEL_FLAG])
+      ...logOptions(options)
    };
 }
 

package/src/commands/measure-memory-args.ts

@@ -10,9 +10,10 @@
 import {
    exitWithUsage,
    helpRequested,
-   LOG_LEVEL_FLAG,
-   logLevelHelpLine,
-   logLevelOption,
+   LOG_FILE_FLAG,
+   LOG_VALUE_FLAGS,
+   logHelpLines,
+   logOptions,
    numericOption,
    parseHarnessArgs,
    printHelp,
@@ -29,7 +30,7 @@ const VALUE_FLAGS = [
    '--snapshot-path',
    '--profile',
    '--session-out',
-   LOG_LEVEL_FLAG
+   ...LOG_VALUE_FLAGS
 ] as const;
 const BOOL_FLAGS = ['--snapshot', '--json'] as const;
 
@@ -67,11 +68,13 @@ export const MEASURE_MEMORY_HELP: readonly string[] = [
    '  --profile <dims>      Capture sampled profiles around the build (+churn) into a',
    '                        profiling session. Comma-separated: cpu,alloc,gc,eld,heap.',
    '  --session-out <dir>   Parent directory for the profiling session folder (with --profile).',
+   '                        The session logs to its server.log at --log-file-level, else at',
+   '                        --log-level, else info; --log-file is refused beside --profile.',
    '  --json                Emit the measurement as one JSON document instead of the',
    '                        progress lines: documentCount, buildMs, emptyHeapBytes,',
    '                        afterBuildHeapBytes, and churnGrowthBytes / snapshotPath /',
    '                        profilingSession where the run produced them.',
-   logLevelHelpLine(22)
+   ...logHelpLines(22)
 ];
 
 /**
@@ -98,6 +101,11 @@ function validatedProfile(csv: string | undefined, onError: UsageError): string
 
 export function parseMeasureMemoryArgs(args: string[], onError: UsageError = exitWithUsage): MeasureMemoryCommandOptions {
    const { servicesModule, workspace, options } = parseHarnessArgs(args, 'measure-memory', VALUE_FLAGS, BOOL_FLAGS, { onError });
+   // The profiling session points the log at its own `server.log`, which would
+   // replace the requested file without a word.
+   if (options['--profile'] !== undefined && options[LOG_FILE_FLAG] !== undefined) {
+      onError(`${LOG_FILE_FLAG} cannot be combined with --profile, which logs to the session's server.log`);
+   }
    return {
       servicesModule,
       workspace,
@@ -110,7 +118,7 @@ export function parseMeasureMemoryArgs(args: string[], onError: UsageError = exi
       profile: validatedProfile(options['--profile'], onError),
       sessionOut: options['--session-out'],
       json: options['--json'] === 'true',
-      logLevel: logLevelOption(options[LOG_LEVEL_FLAG])
+      ...logOptions(options)
    };
 }
 

package/src/commands/model-docs-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 { runModelDocs, type ModelDocsCommandOptions } from './model-docs.js';
 
-const VALUE_FLAGS = [OUT_FILE_FLAG, LOG_LEVEL_FLAG] as const;
+const VALUE_FLAGS = [OUT_FILE_FLAG, ...LOG_VALUE_FLAGS] as const;
 
 /**
  * Every flag `model-docs` accepts, derived from the sets the parser is handed so
@@ -35,7 +35,7 @@ export const MODEL_DOCS_VALUE_FLAGS: readonly string[] = MODEL_DOCS_FLAGS;
 
 /** The `--help` text, as data, held to {@link MODEL_DOCS_FLAGS} by a test. */
 export const MODEL_DOCS_HELP: readonly string[] = [
-   'Usage: hydranium-cli model-docs --services <module> [--out-file <file>] [--log-level <lvl>]',
+   'Usage: hydranium-cli model-docs --services <module> [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    'Generate a navigable Markdown reference of every AST node type — a type index,',
    'cross-linked super/sub types, a reverse "referenced by" index, and a per-language',
@@ -49,7 +49,7 @@ export const MODEL_DOCS_HELP: readonly string[] = [
    '  --out-file <file>     Write the Markdown 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 parseModelDocsArgs(args: string[], onError: UsageError = exitWithUsage): ModelDocsCommandOptions {
@@ -57,7 +57,7 @@ export function parseModelDocsArgs(args: string[], onError: UsageError = exitWit
       requireWorkspace: false,
       onError
    });
-   return { servicesModule, outFile: options[OUT_FILE_FLAG], logLevel: logLevelOption(options[LOG_LEVEL_FLAG]) };
+   return { servicesModule, outFile: options[OUT_FILE_FLAG], ...logOptions(options) };
 }
 
 export function runModelDocsCommand(args: string[]): Promise<void> {

package/src/commands/projects-args.ts

@@ -10,6 +10,7 @@
 import {
    exitWithUsage,
    helpRequested,
+   logHelpLines,
    parseFlagOptions,
    parseServerSpawnOptions,
    printHelp,
@@ -32,7 +33,7 @@ export const PROJECTS_VALUE_FLAGS: readonly string[] = PROJECTS_FLAGS;
 
 /** The `--help` text, as data, held to {@link PROJECTS_FLAGS} by a test. */
 export const PROJECTS_HELP: readonly string[] = [
-   'Usage: hydranium-cli projects --server "<cmd> [args...]" [--cwd <dir>] [--log-level <level>]',
+   'Usage: hydranium-cli projects --server "<cmd> [args...]" [--cwd <dir>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    'List projects exposed by the data-server subprocess. Output is newline-delimited',
    'JSON — one project envelope per line.',
@@ -40,17 +41,17 @@ export const PROJECTS_HELP: readonly string[] = [
    'Options:',
    '  --server "<cmd>"   Command-line for the data-server subprocess (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 parseProjectsArgs(args: string[], onError: UsageError = exitWithUsage): ProjectsCommandOptions {
-   const { serverCommand, serverArgs, cwd, logLevel, extra } = parseServerSpawnOptions(args, 'projects', onError);
+   const { serverCommand, serverArgs, cwd, logLevel, logFile, logFileLevel, extra } = parseServerSpawnOptions(args, 'projects', onError);
    // `projects` declares no options beyond the shared ones, so nothing may
    // survive the spawn parser. Draining `extra` against an empty set is what
    // makes a typo an error here rather than a flag that silently did nothing —
    // the siblings get this from the option list they pass.
    parseFlagOptions(extra, 'projects', [], onError);
-   return { serverCommand, serverArgs, cwd, logLevel };
+   return { serverCommand, serverArgs, cwd, logLevel, logFile, logFileLevel };
 }
 
 export function runProjectsCommand(args: string[]): Promise<void> {

package/src/commands/projects.ts

@@ -7,9 +7,9 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { LogThreshold, Project, TransferElement } from '@hydranium/protocol';
+import type { Project, 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';
 
 /**
@@ -17,7 +17,7 @@ import { withDataServer } from '../spawn-data-server.js';
  * `serverArgs` mirror what an adopter would pass to spawn the data-server
  * subprocess.
  */
-export interface ProjectsCommandOptions {
+export interface ProjectsCommandOptions extends LogOptions {
    /**
     * Command-line tokens used to spawn the data-server child. Mirrors
     * the `--server "<cmd> [args...]"` shape on the CLI surface — split
@@ -26,8 +26,6 @@ export interface ProjectsCommandOptions {
    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;
    /**
     * Output sink. Default: `process.stdout.write`. Tests inject a
     * capturing stub.
@@ -60,7 +58,7 @@ export async function runProjects(options: ProjectsCommandOptions): Promise<void
          command: options.serverCommand,
          args: options.serverArgs,
          cwd: options.cwd,
-         env: options.logLevel ? logLevelEnv(options.logLevel) : undefined
+         env: logEnv(options)
       },
       async server => {
          const projects = await server.getProjects();