@hydranium/cli 1.0.0-next.31 → 1.0.0-next.312

package/src/commands/generate-transfer-model.ts

@@ -10,6 +10,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { emitAstBuilder } from './generate-ast-builder.js';
+import { emitLanguages } from './generate-languages.js';
 import {
    type Node,
    type ObjectLiteralExpression,
@@ -19,6 +20,7 @@ import {
    type InterfaceDeclaration,
    type SourceFile
 } from 'ts-morph';
+import { describeError } from '@hydranium/protocol';
 
 /**
  * Options for the transfer-model generator.
@@ -45,6 +47,13 @@ export interface GenerateTransferModelOptions {
     * and not the other has the two disagreeing about the same grammar.
     */
    astBuilderFile?: string;
+   /**
+    * Destination for a generated module stating each grammar's language id and
+    * file extensions, read from the `module.ts` beside {@link astFile}. Lets a
+    * package without Langium, such as one shared with clients, name the ids
+    * without copying them by hand.
+    */
+   languagesFile?: string;
    /** Name used for the base element type in the output. Defaults to `TransferElement`. */
    elementTypeName?: string;
    /** Name used for the terminal-patterns const in the output. Defaults to `ModelTerminals`. */
@@ -98,38 +107,67 @@ const DEFAULT_REGEN_COMMAND = 'Run the hydranium-cli generate-transfer-model com
  */
 const NAMESPACED_TERMINALS_NAME = 'Terminals';
 
+/** How often `--watch` polls its input files. */
+const WATCH_POLL_INTERVAL_MS = 250;
+
 /**
- * Generate once, then re-generate whenever the AST or augmentation file changes,
+ * Generate once, then re-generate whenever an input file changes (the AST, the
+ * augmentation file, and `module.ts` when a languages file is written),
  * until `signal` aborts (the CLI wires this to SIGINT). Regeneration is debounced
  * so an editor's multi-event save fires a single run, and a generation error is
  * logged without tearing down the watch. Resolves when the signal aborts.
+ *
+ * Polled by path rather than watched through OS events: langium-cli removes
+ * its output directory and writes the files back, which an event watch, Node's
+ * and chokidar's alike, stops hearing after the first run. A run that finds an
+ * input missing is skipped, since the file's return is a change of its own, so
+ * nothing generates from a half-written output.
  */
 export function watchTransferModel(options: GenerateTransferModelOptions, context: { signal: AbortSignal }): Promise<void> {
    const runSafely = (): void => {
       try {
          generateTransferModel(options);
       } catch (error: unknown) {
-         console.error(`Transfer-model generation failed: ${error instanceof Error ? error.message : String(error)}`);
+         console.error(`Transfer-model generation failed: ${describeError(error)}`);
       }
    };
    runSafely();
-   console.log(`Watching ${options.astFile} and ${options.augmentationFile} for changes. Press Ctrl-C to stop.`);
+   // A grammar's language id and extensions reach only `module.ts`, so the
+   // languages module would go stale without it.
+   const watched = [
+      options.astFile,
+      options.augmentationFile,
+      ...(options.languagesFile !== undefined ? [languagesModuleFile(options)] : [])
+   ];
 
    let timer: NodeJS.Timeout | undefined;
-   const scheduleRerun = (): void => {
+   const rerun = (): void => {
+      if (watched.every(file => fs.existsSync(file))) {
+         runSafely();
+      }
+   };
+   // The poll reports every stat it takes; a replaced file has a new inode, a
+   // rewritten one a new mtime, a removed or returning one zeroed stats.
+   const onPoll = (current: fs.Stats, previous: fs.Stats): void => {
+      if (current.ino === previous.ino && current.mtimeMs === previous.mtimeMs && current.size === previous.size) {
+         return;
+      }
       if (timer) {
          clearTimeout(timer);
       }
-      timer = setTimeout(runSafely, 150);
+      timer = setTimeout(rerun, 150);
    };
-   const watchers = [options.astFile, options.augmentationFile].map(file => fs.watch(file, scheduleRerun));
+   for (const file of watched) {
+      fs.watchFile(file, { interval: WATCH_POLL_INTERVAL_MS }, onPoll);
+   }
+   console.log(`Watching ${watched.join(', ')} for changes. Press Ctrl-C to stop.`);
 
    return new Promise<void>(resolve => {
       context.signal.addEventListener(
          'abort',
          () => {
-            for (const watcher of watchers) {
-               watcher.close();
+            for (const file of watched) {
+               fs.unwatchFile(file, onPoll);
             }
             if (timer) {
                clearTimeout(timer);
@@ -141,6 +179,11 @@ export function watchTransferModel(options: GenerateTransferModelOptions, contex
    });
 }
 
+/** The langium-cli `module.ts` beside the AST file, which the languages module is read from. */
+function languagesModuleFile(options: GenerateTransferModelOptions): string {
+   return path.join(path.dirname(options.astFile), 'module.ts');
+}
+
 /** Run the transfer-model generator. */
 export function generateTransferModel(options: GenerateTransferModelOptions): void {
    const elementTypeName = options.elementTypeName ?? DEFAULT_ELEMENT_TYPE_NAME;
@@ -422,6 +465,11 @@ export function generateTransferModel(options: GenerateTransferModelOptions): vo
          console.warn(`Warning: no '${languageId}AstType' alias in ${options.astFile}; skipping the AST builder.`);
       }
    }
+
+   if (options.languagesFile !== undefined) {
+      const moduleSource = project.addSourceFileAtPath(languagesModuleFile(options));
+      emitLanguages(moduleSource, { outFile: options.languagesFile, regenCommand });
+   }
 }
 
 // ---------------------------------------------------------------------------

package/src/commands/harness-args.ts

@@ -31,11 +31,12 @@
  * parser rejects is an invocation that fails for no visible reason.
  */
 
-import type { LogThreshold } from '@hydranium/protocol';
+import { describeError, type LogThreshold } from '@hydranium/protocol';
 import { statSync } from 'node:fs';
+import * as fs from 'node:fs/promises';
 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
@@ -56,9 +57,18 @@ export function exitWithUsage(message: string): never {
    process.exit(2);
 }
 
-/** The value flag {@link parseHarnessArgs} consumes itself, before any the subcommand declares. */
+/** Names the head's services module; every harness subcommand requires it. */
 export const SERVICES_FLAG = '--services';
 
+/**
+ * Registers a loader in the driver child that imports the head. The child is a
+ * fresh `node`, so a loader registered on the CLI's own process never reaches it.
+ */
+export const IMPORT_FLAG = '--import';
+
+/** The value flags {@link parseHarnessArgs} consumes itself, before any the subcommand declares. */
+export const HARNESS_VALUE_FLAGS = [SERVICES_FLAG, IMPORT_FLAG] as const;
+
 /**
  * The one spelling of the log threshold, shared by both subcommand families.
  *
@@ -68,33 +78,68 @@ 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[] {
+   return [
+      helpLine(`${LOG_LEVEL_FLAG} <lvl>`, `Log threshold for ${head} (off|error|warn|info|debug|trace).`, padTo),
+      helpLine(
+         `${LOG_FILE_FLAG} <file>`,
+         `Also write ${head}'s log to <file>; {workspace} expands to the workspace, {pid} to the process id.`,
+         padTo
+      ),
+      helpLine(`${LOG_FILE_LEVEL_FLAG} <lvl>`, `Threshold for that file, which the log-level setting does not change.`, padTo)
+   ].flat();
+}
+
+/** The `--help` lines every `--services` subcommand describes {@link IMPORT_FLAG} with, aligned as {@link logHelpLines}. */
+export function importHelpLines(padTo: number): string[] {
+   return helpLine(`${IMPORT_FLAG} <specifier>`, 'Loader to register before importing <module>, e.g. tsx (repeatable).', padTo);
+}
+
+function helpLine(flag: string, text: string, padTo: number): string[] {
+   return flag.length < padTo - 1 ? [`  ${flag.padEnd(padTo)}${text}`] : [`  ${flag}`, `${' '.repeat(padTo + 2)}${text}`];
 }
 
 /**
- * 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)
+   };
 }
 
 /**
@@ -134,6 +179,8 @@ export function printHelp(lines: readonly string[]): void {
 /** What {@link parseHarnessArgs} recovered from an argv. */
 export interface ParsedHarnessArgs {
    servicesModule: string;
+   /** The {@link IMPORT_FLAG} values in the order given, absent when there were none. */
+   imports?: string[];
    /**
     * An absolute directory path, resolved by {@link resolveWorkspaceArgument} and
     * checked to exist. `''` when the subcommand declared `requireWorkspace: false`.
@@ -163,12 +210,12 @@ export interface HarnessArgsConfig {
 
 /**
  * Shared parser for the headless-harness subcommands. Consumes the required
- * `--services <module>` value flag and a single positional `<workspace>`, plus
- * the `valueFlags` (each takes a value) and `boolFlags` (presence-only, recorded
- * as `'true'`) the subcommand recognises. Unknown flags or a missing
- * `--services`/`<workspace>` are usage errors, and so is a `<workspace>` that
- * reaches no directory — see {@link resolveWorkspaceArgument} for why that cannot
- * be left to the run.
+ * `--services <module>` value flag, the repeatable `--import <specifier>` and a
+ * single positional `<workspace>`, plus the `valueFlags` (each takes a value)
+ * and `boolFlags` (presence-only, recorded as `'true'`) the subcommand
+ * recognises. Unknown flags or a missing `--services`/`<workspace>` are usage
+ * errors, and so is a `<workspace>` that reaches no directory — see
+ * {@link resolveWorkspaceArgument} for why that cannot be left to the run.
  */
 export function parseHarnessArgs(
    args: string[],
@@ -185,6 +232,7 @@ export function parseHarnessArgs(
    const options: Record<string, string | undefined> = {};
    const values: Record<string, string[]> = {};
    let servicesModule: string | undefined;
+   let imports: string[] | undefined;
    let workspace: string | undefined;
    for (let index = 0; index < args.length; index += 1) {
       const flag = args[index];
@@ -196,8 +244,10 @@ export function parseHarnessArgs(
          index += 1;
          return value;
       };
-      if (flag === '--services') {
+      if (flag === SERVICES_FLAG) {
          servicesModule = next();
+      } else if (flag === IMPORT_FLAG) {
+         (imports ??= []).push(next());
       } else if (boolSet.has(flag)) {
          options[flag] = 'true';
       } else if (repeatableSet.has(flag)) {
@@ -213,7 +263,8 @@ export function parseHarnessArgs(
       }
    }
    return {
-      servicesModule: assertRequired(servicesModule, '--services', commandName, onError),
+      servicesModule: assertRequired(servicesModule, SERVICES_FLAG, commandName, onError),
+      imports,
       workspace: requireWorkspace
          ? resolveWorkspaceArgument(assertRequired(workspace, '<workspace>', commandName, onError), commandName, onError)
          : (workspace ?? ''),
@@ -257,7 +308,7 @@ export function resolveWorkspaceArgument(workspace: string, commandName: string,
    try {
       stats = statSync(resolved, { throwIfNoEntry: false });
    } catch (err: unknown) {
-      const detail = err instanceof Error ? err.message : String(err);
+      const detail = describeError(err);
       onError(`<workspace> is not reachable: '${workspace}' resolved to ${resolved} (${detail}) ${help}`);
    }
    if (stats === undefined) {
@@ -276,7 +327,7 @@ function toWorkspacePath(workspace: string, commandName: string, onError: UsageE
    try {
       return fileURLToPath(workspace);
    } catch (err: unknown) {
-      const detail = err instanceof Error ? err.message : String(err);
+      const detail = describeError(err);
       onError(`<workspace> is not a usable file URI: '${workspace}' (${detail}) (hydranium-cli ${commandName} --help)`);
    }
 }
@@ -336,11 +387,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 +413,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 +433,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 +449,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 +475,23 @@ export function parseServerSpawnOptions(args: string[], commandName: string, onE
          );
       }
    }
-   return { serverCommand, serverArgs, cwd, logLevel, extra };
+   return { serverCommand, serverArgs, cwd, ...logOptions(logFlags), extra };
+}
+
+/**
+ * Resolve the `--content` argument to its textual form. The `@<path>`
+ * prefix reads from a file (parses as UTF-8); anything else is taken
+ * literally. The leading `@` can be escaped as `\@` for content that
+ * legitimately starts with `@`.
+ */
+export async function resolveContent(content: string, readFile?: (path: string) => Promise<string>): Promise<string> {
+   if (content.startsWith('@')) {
+      const file = content.slice(1);
+      const reader = readFile ?? ((target: string) => fs.readFile(target, 'utf8'));
+      return reader(file);
+   }
+   if (content.startsWith('\\@')) {
+      return content.slice(1);
+   }
+   return content;
 }

package/src/commands/headless-harness.ts

@@ -8,14 +8,14 @@
  ********************************************************************************/
 
 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 { logLevelEnv } from '../log-level.js';
-import { SERVICES_FLAG } from './harness-args.js';
+import { driverHeapArgs, type HeapReading } from '../driver-heap.js';
+import { logEnv, type LogOptions } from '../log-level.js';
+import { IMPORT_FLAG, SERVICES_FLAG } from './harness-args.js';
 
 /** The flag every report-producing subcommand names its destination file with. */
 export const OUT_FILE_FLAG = '--out-file';
@@ -43,13 +43,15 @@ export interface HeadlessContext {
  * its `createServices` thunk AND the `@hydranium/core/node` harness, both
  * resolved from the HEAD's location rather than the CLI's.
  *
- * The module is an ESM file (typically a compiled `lib/*.js`) exporting a
- * ZERO-ARG `createServices(): { shared }`. `hydranium-cli` is language-agnostic
+ * The module is an ESM file exporting a ZERO-ARG `createServices(): { shared }`:
+ * a compiled `lib/*.js`, or the TypeScript source when the child was started
+ * with a loader through {@link IMPORT_FLAG}. `hydranium-cli` is language-agnostic
  * and cannot statically import a head's `create<Lang>Services`, so the dynamic
  * import is the seam that keeps the binary head-neutral. Resolving the harness
- * from the head's graph (via `createRequire` rooted at the head module) means the
- * CLI itself needs no `@hydranium/core` dependency — the head always has it — and
- * guarantees the harness runs against the SAME core copy as `createServices`.
+ * from the head's graph (via `createRequire` rooted at the head module) rather
+ * than from the CLI's guarantees it runs against the SAME core copy as
+ * `createServices`, which a second copy of the module would break even where
+ * both resolve.
  *
  * Throws a clear error when the path names no file, and when the export is
  * missing or not a function.
@@ -64,12 +66,17 @@ export async function loadHeadlessContext(servicesModule: string): Promise<Headl
    if (stats === undefined || !stats.isFile()) {
       throw new Error(
          `${SERVICES_FLAG} must name an existing ESM file; '${servicesModule}' resolved to ${modulePath}, ` +
-            `which is not one. Pass the head's COMPILED entry, e.g. \`${SERVICES_FLAG} ./lib/services.js\` — ` +
-            'not the TypeScript source and not a package name.'
+            "which is not one. Pass the path of the server package's built `lib/node/services.js` from where you run this — " +
+            'not a package name.'
       );
    }
    const moduleUrl = pathToFileURL(modulePath).href;
-   const imported = (await import(moduleUrl)) as Record<string, unknown>;
+   let imported: Record<string, unknown>;
+   try {
+      imported = (await import(moduleUrl)) as Record<string, unknown>;
+   } catch (err: unknown) {
+      throw withLoaderHint(err, modulePath);
+   }
    const createServices = imported.createServices;
    if (typeof createServices !== 'function') {
       throw new Error(
@@ -84,6 +91,32 @@ export async function loadHeadlessContext(servicesModule: string): Promise<Headl
    return { createServices: createServices as ServicesFactory, coreNode };
 }
 
+/** The codes Node fails a TypeScript entry with when no loader handled it, depending on its version. */
+const UNLOADED_TYPESCRIPT_CODES: ReadonlySet<string> = new Set([
+   'ERR_UNKNOWN_FILE_EXTENSION',
+   'ERR_MODULE_NOT_FOUND',
+   'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX'
+]);
+
+/**
+ * Append a loader hint to a TypeScript entry's import failure, unless the child
+ * was started with {@link IMPORT_FLAG}, where the hint would only repeat the
+ * caller's own command. Appended rather than substituted: a loader set through
+ * `NODE_OPTIONS` does not show in `execArgv`, and under it the failure can be a
+ * missing module that only Node's own message names.
+ */
+function withLoaderHint(err: unknown, modulePath: string): unknown {
+   if (!(err instanceof Error) || !/\.[cm]?ts$/.test(modulePath) || !('code' in err) || typeof err.code !== 'string') {
+      return err;
+   }
+   if (!UNLOADED_TYPESCRIPT_CODES.has(err.code) || process.execArgv.some(arg => arg.startsWith(IMPORT_FLAG))) {
+      return err;
+   }
+   return new Error(`${err.message}\nA TypeScript head needs a loader registered with \`${IMPORT_FLAG}\`, e.g. \`${IMPORT_FLAG} tsx\`.`, {
+      cause: err
+   });
+}
+
 /**
  * Child-side: deliver a finished report — to `outFile` when one was named, else
  * to stdout.
@@ -129,37 +162,64 @@ 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 {
+   /** Specifiers the driver child registers with Node's `--import`, in order, before it imports the head. */
+   readonly imports?: readonly string[];
    /** Test-only: capture the node argv and env instead of spawning the real child. */
    readonly __spawnForTest?: SpawnDriverChild;
+   /**
+    * Test-only: decide the heap ceiling from a stated cgroup reading rather
+    * than the machine's. Without it an argv assertion means one thing on a
+    * workstation and nothing at all under a memory limit, so a suite that
+    * asserts the ceiling is present passes vacuously in a container.
+    */
+   readonly __heapReadingForTest?: HeapReading;
 }
 
 /**
  * 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
  * reach past `createServices`.
+ *
+ * **The heap ceiling is prepended HERE rather than passed by each subcommand.**
+ * Every caller wants the same answer to the same question, and the answer is not
+ * a constant — see {@link driverHeapArgs}. A literal at the call site is a place
+ * the container case can be missed, and the caller that misses it takes the whole
+ * cgroup down with it rather than failing on its own.
  */
 export async function runDriverChild(execArgs: string[], options: DriverSpawnOptions): Promise<void> {
    const spawnChild = options.__spawnForTest ?? spawnNodeChild;
-   const code = await spawnChild(execArgs, options.logLevel === undefined ? undefined : logLevelEnv(options.logLevel));
+   const importArgs = (options.imports ?? []).map(specifier => `${IMPORT_FLAG}=${loaderSpecifier(specifier)}`);
+   const code = await spawnChild([...driverHeapArgs(options.__heapReadingForTest), ...importArgs, ...execArgs], logEnv(options));
    if (code) {
       process.exitCode = code;
    }
 }
+
+/**
+ * A path, absolute or `./`/`../` relative with either separator, becomes a file
+ * URL resolved against the caller's directory. Node reads `--import` as a URL or
+ * package specifier, so it would take a Windows `C:\…` for the URL scheme `c:`
+ * and a `.\…` for a package name. Any other specifier passes through as Node
+ * reads it.
+ */
+function loaderSpecifier(specifier: string): string {
+   const isPath = path.isAbsolute(specifier) || /^\.\.?[\\/]/.test(specifier);
+   return isPath ? pathToFileURL(path.resolve(specifier)).href : specifier;
+}