@hydranium/cli 1.0.0-next.27 → 1.0.0-next.271

package/src/commands/init-wizard.ts

@@ -219,10 +219,10 @@ async function askHeads(prompt: PromptPort): Promise<InitHead[]> {
 /**
  * Mark the grammar a scaffolded diagram edits.
  *
- * Only a real question with `glsp` on AND several grammars: a diagram type
- * binds exactly ONE grammar, and with a single grammar the scaffolder derives
- * that answer already — so asking would offer a choice whose "no" it would
- * silently overrule.
+ * Only a real question with `glsp` on AND several grammars: the scaffolded
+ * diagram is typed over one grammar's model, and with a single grammar the
+ * scaffolder derives that answer already — so asking would offer a choice
+ * whose "no" it would silently overrule.
  */
 async function askDiagramGrammar(
    prompt: PromptPort,

package/src/commands/init-workspace.ts

@@ -186,10 +186,14 @@ export interface WorkspaceDetection {
    readonly baseTsconfig?: string;
    /** That tsconfig's `compilerOptions`, so the emitted one can drop what it inherits. */
    readonly baseCompilerOptions?: Readonly<Record<string, JsonValue>>;
-   /** The root prettier config's `printWidth`, so emitted sources wrap where the repo wraps. */
+   /** The root formatter config's `printWidth`, so emitted sources wrap where the repo wraps. */
    readonly printWidth?: number;
    /** Filename of the root eslint config, when there is one. Absent means the repo does not lint. */
    readonly eslintConfig?: string;
+   /** Filename of the root Oxlint config, when present. */
+   readonly oxlintConfig?: string;
+   /** The npm version the root's `packageManager` field declares, when it names npm. */
+   readonly packageManagerNpm?: string;
 }
 
 /**
@@ -339,7 +343,7 @@ export function findBaseTsconfig(
 }
 
 /**
- * The repo's prettier `printWidth`, so the emitted sources wrap where the repo
+ * The repo's formatter `printWidth`, so the emitted sources wrap where the repo
  * wraps instead of at the scaffold's own default.
  *
  * **Why this is worth detecting at all.** There is no width that is stable for
@@ -360,19 +364,21 @@ export function findBaseTsconfig(
  * adopter's formatter rewraps on first commit. So a heuristic that is usually
  * right strictly improves on no detection, and can break nothing.
  */
-export function findPrettierPrintWidth(rootDir: string, probe: WorkspaceProbe): number | undefined {
+export function findFormatterPrintWidth(rootDir: string, probe: WorkspaceProbe): number | undefined {
    const manifest = probe.readJson(path.join(rootDir, 'package.json'));
    if (isJsonObject(manifest) && isJsonObject(manifest.prettier) && typeof manifest.prettier.printWidth === 'number') {
       return manifest.prettier.printWidth;
    }
    const present = probe.listFiles(rootDir);
-   for (const file of present.filter(name => name === '.prettierrc' || name === '.prettierrc.json')) {
+   for (const file of present.filter(name => name === '.oxfmtrc.json' || name === '.prettierrc' || name === '.prettierrc.json')) {
       const parsed = probe.readJson(path.join(rootDir, file));
       if (isJsonObject(parsed) && typeof parsed.printWidth === 'number') {
          return parsed.printWidth;
       }
    }
-   for (const file of present.filter(name => /^(\.prettierrc\.[cm]?[jt]s|prettier\.config\.[cm]?[jt]s)$/.test(name))) {
+   for (const file of present.filter(name =>
+      /^(\.prettierrc\.[cm]?[jt]s|prettier\.config\.[cm]?[jt]s|oxfmt\.config\.[cm]?[jt]s)$/.test(name)
+   )) {
       const width = /\bprintWidth\s*:\s*(\d+)/.exec(probe.readText(path.join(rootDir, file)) ?? '');
       if (width) {
          return Number(width[1]);
@@ -398,6 +404,22 @@ export function findEslintConfig(rootDir: string, probe: WorkspaceProbe): string
    return probe.listFiles(rootDir).find(name => /^eslint\.config\.[cm]?[jt]s$/.test(name) || /^\.eslintrc(\..+)?$/.test(name));
 }
 
+/** Detect Oxlint without evaluating executable configuration files. */
+export function findOxlintConfig(rootDir: string, probe: WorkspaceProbe): string | undefined {
+   return probe.listFiles(rootDir).find(name => /^(oxlint\.config\.[cm]?[jt]s|\.oxlintrc\.jsonc?)$/.test(name));
+}
+
+/** The npm version the root's `packageManager` field declares (`npm@11.15.0` gives `11.15.0`), when it names npm. */
+export function findPackageManagerNpm(rootDir: string, probe: WorkspaceProbe): string | undefined {
+   const manifest = probe.readJson(path.join(rootDir, 'package.json'));
+   return parseNpmVersion(isJsonObject(manifest) && typeof manifest.packageManager === 'string' ? manifest.packageManager : undefined);
+}
+
+/** The npm version, prerelease included, of a `packageManager` field (`npm@…`) or a user agent (`npm/…`); undefined for another tool. */
+export function parseNpmVersion(spec: string | undefined): string | undefined {
+   return /^npm[@/](\d+\.\d+\.\d+(?:-[\w.]+)?)/.exec(spec ?? '')?.[1];
+}
+
 /** POSIX-style relative path, which is what both `extends` and `--prefix` want on every platform. */
 function posixRelative(from: string, to: string): string {
    return path.relative(from, to).split(path.sep).join('/');
@@ -436,7 +458,9 @@ export function detectWorkspace(targetDir: string, probe: WorkspaceProbe): Works
       scope: inferPackageScope(rootDir, workspaces, probe),
       baseTsconfig: base && posixRelative(absoluteTarget, path.join(rootDir, base.file)),
       baseCompilerOptions: base?.compilerOptions,
-      printWidth: findPrettierPrintWidth(rootDir, probe),
-      eslintConfig: findEslintConfig(rootDir, probe)
+      printWidth: findFormatterPrintWidth(rootDir, probe),
+      eslintConfig: findEslintConfig(rootDir, probe),
+      oxlintConfig: findOxlintConfig(rootDir, probe),
+      packageManagerNpm: findPackageManagerNpm(rootDir, probe)
    };
 }

package/src/commands/init.ts

@@ -9,8 +9,8 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { buildInitTemplates, readFrameworkVersion, UNPUBLISHED_FRAMEWORK_VERSION } from './init-templates.js';
-import { createNodeWorkspaceProbe, detectWorkspace, type JsonValue, type WorkspaceProbe } from './init-workspace.js';
+import { buildInitTemplates, readFrameworkVersion, workspaceRootPins } from './init-templates.js';
+import { createNodeWorkspaceProbe, detectWorkspace, parseNpmVersion, type JsonValue, type WorkspaceProbe } from './init-workspace.js';
 
 /**
  * The protocol heads a scaffold can start, in composition order.
@@ -55,10 +55,9 @@ export interface InitGrammarSpec {
    /**
     * Scaffold a GLSP diagram for this grammar. Requires the `glsp` head.
     *
-    * Per grammar rather than per project because
-    * `AbstractHydraniumGlspDiagramModule.declareLanguage()` returns ONE grammar's
-    * `LanguageMetaData` — a diagram type has exactly one grammar, and a grammar
-    * with no diagram sitting on the same server is the normal case.
+    * Per grammar rather than per project because the scaffolded diagram is typed
+    * over one grammar's model, and a grammar with no diagram sitting on the same
+    * server is the normal case.
     */
    readonly diagram?: boolean;
 }
@@ -128,10 +127,16 @@ export interface InitWorkspacePlacement {
    readonly baseTsconfig?: string;
    /** That tsconfig's `compilerOptions`, so the emitted one can omit what it would inherit unchanged. */
    readonly baseCompilerOptions?: Readonly<Record<string, JsonValue>>;
-   /** The workspace's prettier `printWidth`, so emitted sources wrap where the repo wraps. */
+   /** The workspace's formatter `printWidth`, so emitted sources wrap where the repo wraps. */
    readonly printWidth?: number;
    /** Filename of the workspace's eslint config; its presence is what makes the scaffold emit a `lint` script. */
    readonly eslintConfig?: string;
+   /** Filename of the workspace Oxlint config, when present. */
+   readonly oxlintConfig?: string;
+   /** The npm version the workspace root's `packageManager` declares; with {@link npmVersion} it decides the scaffold's `vitest` range. */
+   readonly packageManagerNpm?: string;
+   /** The npm running `init`, when known. npm does not enforce `packageManager`, so a declaration alone cannot lift `vitest`. */
+   readonly npmVersion?: string;
 }
 
 /**
@@ -226,10 +231,9 @@ export interface InitCommandOptions {
    readonly force?: boolean;
    /**
     * Scaffold a member of the surrounding npm workspace: extend its base
-    * tsconfig, leave `.gitignore` to the root, and address the package by
-    * `--prefix` in the scripts it prints back at itself. Errors when no ancestor
-    * declares `workspaces`, rather than silently degrading to a standalone
-    * project the caller did not ask for.
+    * tsconfig and address the package by `--prefix` in the scripts it prints
+    * back at itself. Errors when no ancestor declares `workspaces`, rather than
+    * silently degrading to a standalone project the caller did not ask for.
     */
    readonly monorepo?: boolean;
    /** npm scope for the package name, e.g. `@acme`. */
@@ -298,8 +302,9 @@ function resolveGrammar(spec: InitGrammarSpec, projectId: string, qualify: boole
  *
  * With the `glsp` head on and nothing marked, a lone grammar is unambiguous and
  * is taken as the diagram's; with several it is a real choice, so it is required
- * rather than guessed — binding a diagram to the wrong grammar surfaces much
- * later as references resolving against the wrong scope.
+ * rather than guessed — the scaffolded state, storage and GModel factory are
+ * typed over the chosen grammar's model, so a wrong guess emits a diagram of
+ * the wrong model.
  */
 function resolveDiagrams(specs: readonly InitGrammarSpec[], heads: readonly InitHead[]): boolean[] {
    const marked = specs.map(spec => spec.diagram === true);
@@ -432,6 +437,8 @@ export interface InitPackagingOptions {
    readonly scope?: string;
    readonly public?: boolean;
    readonly probe?: WorkspaceProbe;
+   /** The npm running `init`. Defaults to the one `npm_config_user_agent` names, which `npx` and `npm run` set. */
+   readonly npmVersion?: string;
 }
 
 /**
@@ -466,7 +473,10 @@ export function resolveInitPackaging(targetDir: string, options: InitPackagingOp
          baseTsconfig: detection.baseTsconfig,
          baseCompilerOptions: detection.baseCompilerOptions,
          printWidth: detection.printWidth,
-         eslintConfig: detection.eslintConfig
+         eslintConfig: detection.eslintConfig,
+         oxlintConfig: detection.oxlintConfig,
+         packageManagerNpm: detection.packageManagerNpm,
+         npmVersion: options.npmVersion ?? parseNpmVersion(process.env.npm_config_user_agent)
       }
    };
 }
@@ -513,12 +523,13 @@ export function runInit(options: InitCommandOptions): void {
       } else {
          write('  No root tsconfig carries compilerOptions, so the emitted one stands alone.\n');
       }
-      write("  .gitignore holds `syntaxes/` only — the workspace root's covers the rest.\n");
       if (detection.printWidth !== undefined) {
-         write(`  Sources wrapped at ${detection.printWidth} columns, from ${detection.rootDir}'s prettier config.\n`);
+         write(`  Sources wrapped at ${detection.printWidth} columns, from ${detection.rootDir}'s formatter config.\n`);
       }
-      if (detection.eslintConfig !== undefined) {
-         write(`  A lint script was added — ${detection.eslintConfig} says this repo lints. Adjust it if your invocation differs.\n`);
+      if (detection.oxlintConfig !== undefined || detection.eslintConfig !== undefined) {
+         write(
+            `  A lint script was added — ${detection.oxlintConfig ?? detection.eslintConfig} says this repo lints. Adjust it if your invocation differs.\n`
+         );
       }
       // Printed rather than applied: `init` writes inside the target directory
       // and nowhere else, so a scaffold can never surprise-edit a manifest that
@@ -527,8 +538,13 @@ export function runInit(options: InitCommandOptions): void {
          write(`  Add this to "workspaces" in ${path.join(detection.rootDir, 'package.json')}:\n`);
          write(`    "${detection.targetPath}"\n`);
       } else {
-         write(`  Already covered by the "${detection.coveredBy}" workspaces entry — no root manifest change needed.\n`);
+         write(`  Already covered by the "${detection.coveredBy}" workspaces entry.\n`);
       }
+      const pins = workspaceRootPins(composition.heads).map(([name, version]) => `    "${name}": "${version}"`);
+      write(
+         `  Add these to "devDependencies" in ${path.join(detection.rootDir, 'package.json')}, so another member's version of one ` +
+            `cannot displace the copy this package shares with the framework:\n${pins.join(',\n')}\n`
+      );
       if (composition.packaging.scope === undefined && detection.scope !== undefined) {
          write(`  Sibling packages all use the "${detection.scope}" scope; pass --scope ${detection.scope} to match them.\n`);
       }
@@ -536,13 +552,7 @@ export function runInit(options: InitCommandOptions): void {
    write('\n');
    write('Next steps:\n');
    write(`  cd ${options.targetDir}\n`);
-   // The warning is conditional on the pins this scaffold actually carries — see
-   // `UNPUBLISHED_FRAMEWORK_VERSION`.
-   write(
-      composition.frameworkVersion === UNPUBLISHED_FRAMEWORK_VERSION
-         ? '  npm install              # 404s until @hydranium/* is published — see README\n'
-         : '  npm install\n'
-   );
+   write('  npm install\n');
    write('  npm run build            # langium generate + tsc\n');
    write('  npm test                 # the scaffolded DI-composition test\n');
    // `npx`, not a bare invocation: `@hydranium/cli` is a devDependency of the

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',
@@ -48,25 +50,27 @@ export const LINT_GRAMMAR_HELP: readonly string[] = [
    '',
    'Options:',
    '  --services <module>    ESM module exporting `createServices(): { shared }` (required).',
+   ...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',
@@ -54,6 +58,7 @@ export const MEASURE_MEMORY_HELP: readonly string[] = [
    '',
    'Options:',
    '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   ...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.',
@@ -67,11 +72,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)
 ];
 
 /**
@@ -91,15 +98,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 +123,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

@@ -139,5 +139,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/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',
@@ -46,18 +48,19 @@ export const MODEL_DOCS_HELP: readonly string[] = [
    '',
    'Options:',
    '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   ...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> {