@hydranium/cli 1.0.0-next.42 → 1.0.0-next.421

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

@@ -9,34 +9,36 @@
 
 import {
    exitWithUsage,
+   HARNESS_VALUE_FLAGS,
    helpRequested,
-   LOG_LEVEL_FLAG,
-   logLevelHelpLine,
-   logLevelOption,
+   importHelpLines,
+   LOG_VALUE_FLAGS,
+   logHelpLines,
+   logOptions,
    parseHarnessArgs,
    printHelp,
-   SERVICES_FLAG,
    type UsageError
 } 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;
 
 /**
  * Every flag `lint-grammar` accepts, derived from the sets the parser is handed
- * so the list cannot claim a flag the parser would reject. `--services` is
- * consumed by the shared harness parser itself, so it is in neither set.
+ * so the list cannot claim a flag the parser would reject.
+ * {@link HARNESS_VALUE_FLAGS} are consumed by the shared harness parser itself,
+ * so they are in neither set.
  */
-export const LINT_GRAMMAR_FLAGS: readonly string[] = [SERVICES_FLAG, ...REPEATABLE_VALUE_FLAGS, ...VALUE_FLAGS, ...BOOL_FLAGS];
+export const LINT_GRAMMAR_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS, ...REPEATABLE_VALUE_FLAGS, ...VALUE_FLAGS, ...BOOL_FLAGS];
 
 /** The subset that takes a value, so `--help` in a value position reads as data. */
-export const LINT_GRAMMAR_VALUE_FLAGS: readonly string[] = [SERVICES_FLAG, ...REPEATABLE_VALUE_FLAGS, ...VALUE_FLAGS];
+export const LINT_GRAMMAR_VALUE_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS, ...REPEATABLE_VALUE_FLAGS, ...VALUE_FLAGS];
 
 /** 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>] [--import <specifier>]... [--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',
@@ -47,26 +49,28 @@ export const LINT_GRAMMAR_HELP: readonly string[] = [
    'zero-arg `createServices(): { shared }` thunk. Needs @hydranium/core.',
    '',
    'Options:',
-   '  --services <module>    ESM module exporting `createServices(): { shared }` (required).',
+   '  --services <module>    ESM module exporting `createServices(): { shared }` (required) unless package.json sets hydranium.services.',
+   ...importHelpLines(23),
    '  --name-property <p>    Property that satisfies the nameability convention',
    '                         (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 {
-   const { servicesModule, options, values } = parseHarnessArgs(args, 'lint-grammar', VALUE_FLAGS, BOOL_FLAGS, {
+   const { servicesModule, imports, options, values } = parseHarnessArgs(args, 'lint-grammar', VALUE_FLAGS, BOOL_FLAGS, {
       requireWorkspace: false,
       repeatableValueFlags: REPEATABLE_VALUE_FLAGS,
       onError
    });
    return {
       servicesModule,
+      imports,
       nameProperties: values['--name-property'],
       strict: options['--strict'] === 'true',
       json: options['--json'] === 'true',
-      logLevel: logLevelOption(options[LOG_LEVEL_FLAG])
+      ...logOptions(options)
    };
 }
 

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

@@ -16,6 +16,7 @@
  * only spawned.
  */
 
+import { describeError } from '@hydranium/protocol';
 import { loadHeadlessContext } from './headless-harness.js';
 import { formatLintReport, lintExitCode } from './lint-grammar-report.js';
 
@@ -78,6 +79,6 @@ async function main(argv: string[]): Promise<number> {
 main(process.argv.slice(2))
    .then(code => process.exit(code))
    .catch((error: unknown) => {
-      console.error(error instanceof Error ? error.message : String(error));
+      console.error(describeError(error));
       process.exit(1);
    });

package/src/commands/lint-grammar.ts

@@ -53,5 +53,5 @@ export function buildLintGrammarDriverArgs(options: LintGrammarCommandOptions):
  * `createServices` module, keeping the binary language-agnostic.
  */
 export function runLintGrammar(options: LintGrammarCommandOptions): Promise<void> {
-   return runDriverChild(['--max-old-space-size=8192', DRIVER, ...buildLintGrammarDriverArgs(options)], options);
+   return runDriverChild([DRIVER, ...buildLintGrammarDriverArgs(options)], options);
 }

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

@@ -7,16 +7,19 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+import { describeError } from '@hydranium/protocol';
 import {
    exitWithUsage,
+   HARNESS_VALUE_FLAGS,
    helpRequested,
-   LOG_LEVEL_FLAG,
-   logLevelHelpLine,
-   logLevelOption,
+   importHelpLines,
+   LOG_FILE_FLAG,
+   LOG_VALUE_FLAGS,
+   logHelpLines,
+   logOptions,
    numericOption,
    parseHarnessArgs,
    printHelp,
-   SERVICES_FLAG,
    type UsageError
 } from './harness-args.js';
 import { parseProfileDimensions, runMeasureMemory, type MeasureMemoryCommandOptions } from './measure-memory.js';
@@ -29,23 +32,24 @@ const VALUE_FLAGS = [
    '--snapshot-path',
    '--profile',
    '--session-out',
-   LOG_LEVEL_FLAG
+   ...LOG_VALUE_FLAGS
 ] as const;
 const BOOL_FLAGS = ['--snapshot', '--json'] as const;
 
 /**
  * Every flag `measure-memory` accepts, derived from the sets the parser is
- * handed so the list cannot claim a flag the parser would reject. `--services`
- * is consumed by the shared harness parser itself, so it is in neither set.
+ * handed so the list cannot claim a flag the parser would reject.
+ * {@link HARNESS_VALUE_FLAGS} are consumed by the shared harness parser itself,
+ * so they are in neither set.
  */
-export const MEASURE_MEMORY_FLAGS: readonly string[] = [SERVICES_FLAG, ...VALUE_FLAGS, ...BOOL_FLAGS];
+export const MEASURE_MEMORY_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS, ...VALUE_FLAGS, ...BOOL_FLAGS];
 
 /** The subset that takes a value, so `--help` in a value position reads as data. */
-export const MEASURE_MEMORY_VALUE_FLAGS: readonly string[] = [SERVICES_FLAG, ...VALUE_FLAGS];
+export const MEASURE_MEMORY_VALUE_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS, ...VALUE_FLAGS];
 
 /** The `--help` text, as data, held to {@link MEASURE_MEMORY_FLAGS} by a test. */
 export const MEASURE_MEMORY_HELP: readonly string[] = [
-   'Usage: hydranium-cli measure-memory --services <module> <workspace> [options]',
+   'Usage: hydranium-cli measure-memory [--services <module>] [--import <specifier>]... <workspace> [options]',
    '',
    'Measure model-store memory for a workspace. `<module>` is an ESM module that',
    'exports a zero-arg `createServices(): { shared }` thunk (the head wires its own',
@@ -53,7 +57,8 @@ export const MEASURE_MEMORY_HELP: readonly string[] = [
    'baseline / after-build / churn lines print on stdout. Needs @hydranium/core.',
    '',
    'Options:',
-   '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   '  --services <module>   ESM module exporting `createServices(): { shared }` (required) unless package.json sets hydranium.services.',
+   ...importHelpLines(22),
    '  <workspace>           Workspace root (path or file URI) to build (required).',
    '  --edits <N>           Rebuild-churn cycles to probe for retention. Default: 0 (skip).',
    '  --edit-docs <N>       Documents to churn per cycle. Default: 25.',
@@ -64,14 +69,17 @@ export const MEASURE_MEMORY_HELP: readonly string[] = [
    '                        measure the pre-shed (always-keep) baseline.',
    '  --snapshot            Write a `.heapsnapshot` after the build.',
    '  --snapshot-path <p>   Snapshot path. Default: <cwd>/<workspace-basename>.heapsnapshot.',
-   '  --profile <dims>      Capture sampled profiles around the build (+churn) into a',
-   '                        profiling session. Comma-separated: cpu,alloc,gc,eld,heap.',
+   '  --profile <dims>      Capture profiles around the build (+churn) into a',
+   '                        profiling session. Comma-separated: cpu,alloc,gc,eld,heap,framework.',
+   '                        framework instruments named passes and adds timing overhead.',
    '  --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)
 ];
 
 /**
@@ -91,15 +99,21 @@ function validatedProfile(csv: string | undefined, onError: UsageError): string
    try {
       parseProfileDimensions(csv);
    } catch (err: unknown) {
-      onError(`Option --profile: ${err instanceof Error ? err.message : String(err)}`);
+      onError(`Option --profile: ${describeError(err)}`);
    }
    return csv;
 }
 
 export function parseMeasureMemoryArgs(args: string[], onError: UsageError = exitWithUsage): MeasureMemoryCommandOptions {
-   const { servicesModule, workspace, options } = parseHarnessArgs(args, 'measure-memory', VALUE_FLAGS, BOOL_FLAGS, { onError });
+   const { servicesModule, imports, 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,
+      imports,
       workspace,
       editCycles: numericOption(options['--edits'], '--edits', onError),
       editDocs: numericOption(options['--edit-docs'], '--edit-docs', onError),
@@ -110,7 +124,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/measure-memory-driver.ts

@@ -9,12 +9,14 @@
 
 /*
  * Spawned child of the `measure-memory` subcommand. Launched by the parent with
- * `node --expose-gc --max-old-space-size=8192 <this> --services <module> <workspace> ...`
- * so the underlying harness gets post-GC readings. It dynamic-imports the head's
+ * `node [heap ceiling] --expose-gc <this> --services <module> <workspace> ...`
+ * so the underlying harness gets post-GC readings. The ceiling is whatever
+ * `driverHeapArgs` decides, which is nothing at all inside a container. It dynamic-imports the head's
  * services module and runs the framework's `measureModelMemory`, streaming the
  * baseline / after-build / churn lines to stdout. Never imported — only spawned.
  */
 
+import { describeError } from '@hydranium/protocol';
 import { loadHeadlessContext } from './headless-harness.js';
 import { parseProfileDimensions } from './measure-memory.js';
 
@@ -123,6 +125,6 @@ async function main(argv: string[]): Promise<void> {
 main(process.argv.slice(2))
    .then(() => process.exit(0))
    .catch((error: unknown) => {
-      console.error(error instanceof Error ? error.message : String(error));
+      console.error(describeError(error));
       process.exit(1);
    });

package/src/commands/measure-memory.ts

@@ -56,7 +56,7 @@ export interface MeasureMemoryCommandOptions extends DriverSpawnOptions {
 }
 
 /**
- * Parse a `--profile` dimension list (`cpu,alloc,gc,eld,heap`) into
+ * Parse a `--profile` dimension list (`cpu,alloc,gc,eld,heap,framework`) into
  * {@link ProfileCaptureOptions}. Case- and whitespace-tolerant; throws on an
  * unknown token so a typo fails loud rather than silently capturing nothing.
  */
@@ -68,6 +68,9 @@ export function parseProfileDimensions(csv: string): ProfileCaptureOptions {
          continue;
       }
       switch (token) {
+         case 'framework':
+            options.frameworkPasses = true;
+            break;
          case 'cpu':
             options.cpu = true;
             break;
@@ -88,7 +91,7 @@ export function parseProfileDimensions(csv: string): ProfileCaptureOptions {
             options.heapSnapshot = true;
             break;
          default:
-            throw new Error(`Unknown profile dimension: ${token} (expected cpu, alloc, gc, eld, heap)`);
+            throw new Error(`Unknown profile dimension: ${token} (expected cpu, alloc, gc, eld, heap, framework)`);
       }
    }
    return options;
@@ -139,5 +142,5 @@ export function buildDriverArgs(options: MeasureMemoryCommandOptions): string[]
  * module and reports the baseline / after-build / churn lines on stdout.
  */
 export function runMeasureMemory(options: MeasureMemoryCommandOptions): Promise<void> {
-   return runDriverChild(['--expose-gc', '--max-old-space-size=8192', DRIVER, ...buildDriverArgs(options)], options);
+   return runDriverChild(['--expose-gc', DRIVER, ...buildDriverArgs(options)], options);
 }

package/src/commands/message-catalogue-args.ts

@@ -0,0 +1,55 @@
+/********************************************************************************
+ * 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 { assertRequired, exitWithUsage, helpRequested, printHelp, type UsageError } from './harness-args.js';
+import { runMessageCatalogue, type MessageCatalogueCommandOptions } from './message-catalogue.js';
+
+export const MESSAGE_CATALOGUE_FLAGS: readonly string[] = ['--barrel', '--out-file'];
+export const MESSAGE_CATALOGUE_VALUE_FLAGS = MESSAGE_CATALOGUE_FLAGS;
+export const MESSAGE_CATALOGUE_HELP: readonly string[] = [
+   'Usage: hydranium-cli message-catalogue --barrel <module>... [--out-file <file>]',
+   '',
+   'Emit a flat JSON starter catalogue mapping message codes to English defaults.',
+   'Modules are resolved from the current project and must be built first.',
+   'Repeat --barrel for each framework head and your own messages. No server starts.',
+   '',
+   'Options:',
+   '  --barrel <module>    Messages package specifier or ESM file (required). Repeatable.',
+   '  --out-file <file>   Write JSON here instead of stdout, after all imports succeed.'
+];
+
+export function parseMessageCatalogueArgs(args: string[], onError: UsageError = exitWithUsage): MessageCatalogueCommandOptions {
+   const barrels: string[] = [];
+   let outFile: string | undefined;
+   for (let index = 0; index < args.length; index++) {
+      const flag = args[index];
+      if (!MESSAGE_CATALOGUE_FLAGS.includes(flag)) {
+         return onError(`Unexpected argument: ${flag} (hydranium-cli message-catalogue --help)`);
+      }
+      const value = args[++index];
+      if (value === undefined || value.startsWith('--')) {
+         return onError(`Missing value for ${flag}`);
+      }
+      if (flag === '--barrel') {
+         barrels.push(value);
+      } else {
+         outFile = value;
+      }
+   }
+   assertRequired(barrels[0], '--barrel', 'message-catalogue', onError);
+   return { barrels, outFile };
+}
+
+export async function runMessageCatalogueCommand(args: string[]): Promise<void> {
+   if (helpRequested(args, MESSAGE_CATALOGUE_VALUE_FLAGS)) {
+      printHelp(MESSAGE_CATALOGUE_HELP);
+      return;
+   }
+   await runMessageCatalogue(parseMessageCatalogueArgs(args));
+}

package/src/commands/message-catalogue.ts

@@ -0,0 +1,56 @@
+/********************************************************************************
+ * 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 { collectMessages, type MessageCatalogue } from '@hydranium/protocol';
+import { resolve as resolveModule } from 'import-meta-resolve';
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { emitReport } from './headless-harness.js';
+
+/**
+ * Enumerate declarations rather than scanning source. Conflicting defaults
+ * must fail before any output is written, or import order chooses the English.
+ */
+export function createMessageCatalogue(barrels: readonly object[]): MessageCatalogue {
+   const entries = new Map<string, string>();
+   for (const barrel of barrels) {
+      for (const message of collectMessages(barrel)) {
+         const previous = entries.get(message.code);
+         if (previous !== undefined && previous !== message.text) {
+            throw new Error(`Conflicting English defaults for message '${message.code}'.`);
+         }
+         entries.set(message.code, message.text);
+      }
+   }
+   return Object.fromEntries([...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+
+export interface MessageCatalogueCommandOptions {
+   readonly barrels: readonly string[];
+   readonly outFile?: string;
+}
+
+/** Resolve against the caller's project, including when the CLI is installed globally. */
+export async function runMessageCatalogue(options: MessageCatalogueCommandOptions): Promise<void> {
+   const projectUrl = pathToFileURL(resolve('package.json')).href;
+   const barrels: object[] = [];
+   for (const specifier of options.barrels) {
+      const target =
+         specifier.startsWith('.') || isAbsolute(specifier) ? pathToFileURL(resolve(specifier)).href : resolveModule(specifier, projectUrl);
+      const barrel = (await import(target)) as object;
+      if (collectMessages(barrel).length === 0) {
+         throw new Error(`Message barrel '${specifier}' exports no declarations. Pass a built messages module.`);
+      }
+      barrels.push(barrel);
+   }
+   if (barrels.length === 0) {
+      throw new Error('Pass at least one --barrel messages module.');
+   }
+   emitReport(JSON.stringify(createMessageCatalogue(barrels), undefined, 2), options.outFile);
+}

package/src/commands/model-docs-args.ts

@@ -9,33 +9,35 @@
 
 import {
    exitWithUsage,
+   HARNESS_VALUE_FLAGS,
    helpRequested,
-   LOG_LEVEL_FLAG,
-   logLevelHelpLine,
-   logLevelOption,
+   importHelpLines,
+   LOG_VALUE_FLAGS,
+   logHelpLines,
+   logOptions,
    parseHarnessArgs,
    printHelp,
-   SERVICES_FLAG,
    type UsageError
 } from './harness-args.js';
 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
- * the list cannot claim a flag the parser would reject. `--services` is consumed
- * by the shared harness parser itself, so it is in neither set.
+ * Every flag `model-docs` accepts, derived from the sets the parser is handed
+ * so the list cannot claim a flag the parser would reject.
+ * {@link HARNESS_VALUE_FLAGS} are consumed by the shared harness parser itself,
+ * so they are in neither set.
  */
-export const MODEL_DOCS_FLAGS: readonly string[] = [SERVICES_FLAG, ...VALUE_FLAGS];
+export const MODEL_DOCS_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS, ...VALUE_FLAGS];
 
 /** The subset that takes a value, so `--help` in a value position reads as data. */
 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>] [--import <specifier>]... [--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',
@@ -45,19 +47,20 @@ export const MODEL_DOCS_HELP: readonly string[] = [
    'zero-arg `createServices(): { shared }` thunk. Needs @hydranium/core.',
    '',
    'Options:',
-   '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   '  --services <module>   ESM module exporting `createServices(): { shared }` (required) unless package.json sets hydranium.services.',
+   ...importHelpLines(22),
    '  --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 {
-   const { servicesModule, options } = parseHarnessArgs(args, 'model-docs', VALUE_FLAGS, [], {
+   const { servicesModule, imports, options } = parseHarnessArgs(args, 'model-docs', VALUE_FLAGS, [], {
       requireWorkspace: false,
       onError
    });
-   return { servicesModule, outFile: options[OUT_FILE_FLAG], logLevel: logLevelOption(options[LOG_LEVEL_FLAG]) };
+   return { servicesModule, imports, outFile: options[OUT_FILE_FLAG], ...logOptions(options) };
 }
 
 export function runModelDocsCommand(args: string[]): Promise<void> {

package/src/commands/model-docs-driver.ts

@@ -16,6 +16,7 @@
  * head throws. Never imported — only spawned.
  */
 
+import { describeError } from '@hydranium/protocol';
 import { emitReport, loadHeadlessContext, OUT_FILE_FLAG } from './headless-harness.js';
 import { formatModelDocs } from './model-docs-report.js';
 
@@ -63,6 +64,6 @@ async function main(argv: string[]): Promise<number> {
 main(process.argv.slice(2))
    .then(code => process.exit(code))
    .catch((error: unknown) => {
-      console.error(error instanceof Error ? error.message : String(error));
+      console.error(describeError(error));
       process.exit(1);
    });

package/src/commands/model-docs.ts

@@ -44,5 +44,5 @@ export function buildModelDocsDriverArgs(options: ModelDocsCommandOptions): stri
  * module, keeping the binary language-agnostic.
  */
 export function runModelDocs(options: ModelDocsCommandOptions): Promise<void> {
-   return runDriverChild(['--max-old-space-size=8192', DRIVER, ...buildModelDocsDriverArgs(options)], options);
+   return runDriverChild([DRIVER, ...buildModelDocsDriverArgs(options)], options);
 }

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();

package/src/commands/query-args.ts

@@ -11,6 +11,7 @@ import {
    assertRequired,
    exitWithUsage,
    helpRequested,
+   logHelpLines,
    parseFlagOptions,
    parseServerSpawnOptions,
    printHelp,
@@ -35,21 +36,22 @@ 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.',
+   'Fails when the server holds no document at `<uri>`.',
    '',
    'Options:',
    '  --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> {