@hydranium/cli 1.0.0-next.25 → 1.0.0-next.251

package/lib/commands/harness-args.d.ts

@@ -6,30 +6,7 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-/**
- * The argv machinery the subcommands share, and the error vocabulary they all
- * speak.
- *
- * Its own module rather than functions in the CLI entry point, because the entry
- * point runs `main()` on import: a test that wants to read an argv the way a
- * command does would otherwise have to spawn the whole binary, so flag handling
- * and exit codes could only be covered through a subprocess.
- *
- * The messages here are a contract — scripts and CI steps match on them — so
- * changing one is a breaking change for a caller nobody in this repo can see.
- *
- * Every parser takes an `onError` defaulting to report-and-exit, which is what a
- * command line wants; a caller that would rather handle the problem passes its
- * own and the parser hands control to it instead of ending the process.
- *
- * Each subcommand lives in a sibling `<name>-args` module exporting three things
- * a test can hold against each other: its flag list, its `--help` text as data,
- * and the parser that turns an argv into the runner's options. Help that drifts
- * from the parser is worse than none — it reads as authoritative, so a flag
- * missing from it is a capability nobody finds, and one it describes but the
- * parser rejects is an invocation that fails for no visible reason.
- */
-import type { LogThreshold } from '@hydranium/protocol';
+import { type LogOptions } from '../log-level.js';
 /**
  * How a parser reports a usage problem. It never returns, so a parser can treat
  * the call as a dead end and keep narrowing the value it was about to reject.
@@ -44,8 +21,15 @@ export type UsageError = (message: string) => never;
  * bundled heap analyzer exits with for a usage error.
  */
 export declare function exitWithUsage(message: string): never;
-/** The value flag {@link parseHarnessArgs} consumes itself, before any the subcommand declares. */
+/** Names the head's services module; every harness subcommand requires it. */
 export declare 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 declare const IMPORT_FLAG = "--import";
+/** The value flags {@link parseHarnessArgs} consumes itself, before any the subcommand declares. */
+export declare const HARNESS_VALUE_FLAGS: readonly ["--services", "--import"];
 /**
  * The one spelling of the log threshold, shared by both subcommand families.
  *
@@ -55,27 +39,37 @@ export declare const SERVICES_FLAG = "--services";
  * on which command a caller happened to reach for.
  */
 export declare const LOG_LEVEL_FLAG = "--log-level";
+export declare const LOG_FILE_FLAG = "--log-file";
+export declare const LOG_FILE_LEVEL_FLAG = "--log-file-level";
+/** The log flags every subcommand takes, read by {@link logOptions}. */
+export declare const LOG_VALUE_FLAGS: readonly ["--log-level", "--log-file", "--log-file-level"];
 /** The value flags {@link parseServerSpawnOptions} consumes itself. */
 export declare const SERVER_SPAWN_VALUE_FLAGS: readonly string[];
 /**
- * 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 declare function logLevelHelpLine(padTo: number): string;
+export declare function logHelpLines(padTo: number, head?: string): string[];
+/** The `--help` lines every `--services` subcommand describes {@link IMPORT_FLAG} with, aligned as {@link logHelpLines}. */
+export declare function importHelpLines(padTo: number): string[];
 /**
- * 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 declare function logLevelOption(value: string | undefined): LogThreshold | undefined;
+export declare function logOptions(options: Readonly<Record<string, string | undefined>>): LogOptions;
 /**
  * Whether the argv asks for the command's help rather than describing a run.
  *
@@ -95,6 +89,8 @@ export declare 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`.
@@ -122,12 +118,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 declare function parseHarnessArgs(args: string[], commandName: string, valueFlags: readonly string[], boolFlags: readonly string[], config?: HarnessArgsConfig): ParsedHarnessArgs;
 /**
@@ -167,20 +163,19 @@ export declare function numericOption(value: string | undefined, flag: string, o
  */
 export declare function parseFlagOptions(extra: string[], commandName: string, recognised: readonly string[], onError?: UsageError): Record<string, string | undefined>;
 /** 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[];
 }
 /**
  * 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.
  *

package/lib/commands/harness-args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"harness-args.d.ts","sourceRoot":"","sources":["../../src/commands/harness-args.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"harness-args.d.ts","sourceRoot":"","sources":["../../src/commands/harness-args.ts"],"names":[],"mappings":"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"}

package/lib/commands/harness-args.js

@@ -22,8 +22,15 @@ export function exitWithUsage(message) {
     console.error(message);
     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];
 /**
  * The one spelling of the log threshold, shared by both subcommand families.
  *
@@ -33,30 +40,58 @@ 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];
 /** The value flags {@link parseServerSpawnOptions} consumes itself. */
-export const SERVER_SPAWN_VALUE_FLAGS = ['--server', '--cwd', LOG_LEVEL_FLAG];
+export const SERVER_SPAWN_VALUE_FLAGS = ['--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) {
-    return `  ${`${LOG_LEVEL_FLAG} <lvl>`.padEnd(padTo)}Log threshold for the head this boots (off|error|warn|info|debug|trace).`;
+export function logHelpLines(padTo, head = 'the head this boots') {
+    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.`, 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) {
+    return helpLine(`${IMPORT_FLAG} <specifier>`, 'Loader to register before importing <module>, e.g. tsx (repeatable).', padTo);
+}
+function helpLine(flag, text, padTo) {
+    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) {
-    return value === undefined ? undefined : parseLogLevelOption(value);
+export function logOptions(options) {
+    const level = (flag) => {
+        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)
+    };
 }
 /**
  * Whether the argv asks for the command's help rather than describing a run.
@@ -92,12 +127,12 @@ export function printHelp(lines) {
 }
 /**
  * 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, commandName, valueFlags, boolFlags, config = {}) {
     const requireWorkspace = config.requireWorkspace ?? true;
@@ -108,6 +143,7 @@ export function parseHarnessArgs(args, commandName, valueFlags, boolFlags, confi
     const options = {};
     const values = {};
     let servicesModule;
+    let imports;
     let workspace;
     for (let index = 0; index < args.length; index += 1) {
         const flag = args[index];
@@ -119,9 +155,12 @@ export function parseHarnessArgs(args, commandName, valueFlags, boolFlags, confi
             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';
         }
@@ -142,7 +181,8 @@ export function parseHarnessArgs(args, commandName, valueFlags, boolFlags, confi
         }
     }
     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 ?? ''),
@@ -271,10 +311,10 @@ function isRelativePathToken(token, isCommand) {
 }
 /**
  * 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.
  *
@@ -291,7 +331,7 @@ function isRelativePathToken(token, isCommand) {
 export function parseServerSpawnOptions(args, commandName, onError = exitWithUsage) {
     let serverSpec;
     let cwd;
-    let logLevel;
+    const logFlags = {};
     const extra = [];
     for (let index = 0; index < args.length; index += 1) {
         const flag = args[index];
@@ -309,8 +349,8 @@ export function parseServerSpawnOptions(args, commandName, onError = exitWithUsa
         else if (flag === '--cwd') {
             cwd = claim();
         }
-        else if (flag === LOG_LEVEL_FLAG) {
-            logLevel = parseLogLevelOption(claim());
+        else if (LOG_VALUE_FLAGS.includes(flag)) {
+            logFlags[flag] = claim();
         }
         else {
             extra.push(flag);
@@ -334,6 +374,6 @@ export function parseServerSpawnOptions(args, commandName, onError = exitWithUsa
                 `give the workspace to the entry as its own argument (hydranium-cli ${commandName} --help)`);
         }
     }
-    return { serverCommand, serverArgs, cwd, logLevel, extra };
+    return { serverCommand, serverArgs, cwd, ...logOptions(logFlags), extra };
 }
 //# sourceMappingURL=harness-args.js.map

package/lib/commands/harness-args.js.map

@@ -1 +1 @@
-{"version":3,"file":"harness-args.js","sourceRoot":"","sources":["../../src/commands/harness-args.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"harness-args.js","sourceRoot":"","sources":["../../src/commands/harness-args.ts"],"names":[],"mappings":"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"}

package/lib/commands/headless-harness.d.ts

@@ -7,7 +7,8 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 import type * as HydraniumCoreNode from '@hydranium/core/node';
-import type { LogThreshold } from '@hydranium/protocol';
+import { type HeapReading } from '../driver-heap.js';
+import { type LogOptions } from '../log-level.js';
 /** The flag every report-producing subcommand names its destination file with. */
 export declare const OUT_FILE_FLAG = "--out-file";
 /** The `@hydranium/core/node` module surface the drivers use (type only). */
@@ -30,13 +31,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.
@@ -66,31 +69,45 @@ export declare function emitReport(report: string, outFile: string | undefined):
 export declare function spawnNodeChild(execArgs: string[], env?: Record<string, string>): Promise<number>;
 /** 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 declare function runDriverChild(execArgs: string[], options: DriverSpawnOptions): Promise<void>;
 export {};

package/lib/commands/headless-harness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"headless-harness.d.ts","sourceRoot":"","sources":["../../src/commands/headless-harness.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,KAAK,iBAAiB,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AASxD,kFAAkF;AAClF,eAAO,MAAM,aAAa,eAAe,CAAC;AAE1C,6EAA6E;AAC7E,KAAK,cAAc,GAAG,OAAO,iBAAiB,CAAC;AAE/C;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAC,yBAAyB,CAAC,gBAAgB,CAAC,CAAC;AAE5F,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC7B,gEAAgE;IAChE,cAAc,EAAE,eAAe,CAAC;IAChC,yEAAyE;IACzE,QAAQ,EAAE,cAAc,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CA4B1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAS5E;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAShG;AAED,4FAA4F;AAC5F,MAAM,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAErG,qGAAqG;AACrG,MAAM,WAAW,kBAAkB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACjC,mFAAmF;IACnF,QAAQ,CAAC,cAAc,CAAC,EAAE,gBAAgB,CAAC;CAC7C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMnG"}
+{"version":3,"file":"headless-harness.d.ts","sourceRoot":"","sources":["../../src/commands/headless-harness.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,KAAK,iBAAiB,MAAM,sBAAsB,CAAC;AAM/D,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAAU,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG1D,kFAAkF;AAClF,eAAO,MAAM,aAAa,eAAe,CAAC;AAE1C,6EAA6E;AAC7E,KAAK,cAAc,GAAG,OAAO,iBAAiB,CAAC;AAE/C;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAC,yBAAyB,CAAC,gBAAgB,CAAC,CAAC;AAE5F,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC7B,gEAAgE;IAChE,cAAc,EAAE,eAAe,CAAC;IAChC,yEAAyE;IACzE,QAAQ,EAAE,cAAc,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAiC1F;AA4BD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAS5E;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAShG;AAED,4FAA4F;AAC5F,MAAM,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAErG;;;;;GAKG;AACH,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACnD,0GAA0G;IAC1G,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,mFAAmF;IACnF,QAAQ,CAAC,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,WAAW,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOnG"}

package/lib/commands/headless-harness.js

@@ -11,8 +11,9 @@ 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 } from '../driver-heap.js';
+import { logEnv } 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';
 /**
@@ -20,13 +21,15 @@ export const OUT_FILE_FLAG = '--out-file';
  * 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.
@@ -40,11 +43,17 @@ export async function loadHeadlessContext(servicesModule) {
     const stats = statSync(modulePath, { throwIfNoEntry: false });
     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 head's entry, e.g. \`${SERVICES_FLAG} ./lib/services.js\` — ` +
+            'not a package name.');
     }
     const moduleUrl = pathToFileURL(modulePath).href;
-    const imported = (await import(moduleUrl));
+    let imported;
+    try {
+        imported = (await import(moduleUrl));
+    }
+    catch (err) {
+        throw withLoaderHint(err, modulePath);
+    }
     const createServices = imported.createServices;
     if (typeof createServices !== 'function') {
         throw new Error(`Services module '${servicesModule}' must export a zero-arg 'createServices(): { shared }' ` +
@@ -56,6 +65,30 @@ export async function loadHeadlessContext(servicesModule) {
     const coreNode = (await import(pathToFileURL(coreNodePath).href));
     return { createServices: createServices, coreNode };
 }
+/** The codes Node fails a TypeScript entry with when no loader handled it, depending on its version. */
+const UNLOADED_TYPESCRIPT_CODES = 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, modulePath) {
+    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.
@@ -100,22 +133,40 @@ export function spawnNodeChild(execArgs, env) {
  * 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, options) {
     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) {
+    const isPath = path.isAbsolute(specifier) || /^\.\.?[\\/]/.test(specifier);
+    return isPath ? pathToFileURL(path.resolve(specifier)).href : specifier;
+}
 //# sourceMappingURL=headless-harness.js.map