@hydranium/cli 1.0.0-next.212 → 1.0.0-next.213

package/lib/commands/measure-memory-args.js.map

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

package/lib/commands/model-docs-args.d.ts

@@ -9,9 +9,10 @@
 import { type UsageError } from './harness-args.js';
 import { type ModelDocsCommandOptions } from './model-docs.js';
 /**
- * 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 declare const MODEL_DOCS_FLAGS: readonly string[];
 /** The subset that takes a value, so `--help` in a value position reads as data. */

package/lib/commands/model-docs-args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-docs-args.d.ts","sourceRoot":"","sources":["../../src/commands/model-docs-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EASJ,KAAK,UAAU,EACjB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAgB,KAAK,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAI7E;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAAoC,CAAC;AAEnF,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAAqB,CAAC;AAE1E,8EAA8E;AAC9E,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAgB5C,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,UAA0B,GAAG,uBAAuB,CAM/G;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAMjE"}
+{"version":3,"file":"model-docs-args.d.ts","sourceRoot":"","sources":["../../src/commands/model-docs-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAUJ,KAAK,UAAU,EACjB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAgB,KAAK,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAI7E;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAA6C,CAAC;AAE5F,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAAqB,CAAC;AAE1E,8EAA8E;AAC9E,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAiB5C,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,UAA0B,GAAG,uBAAuB,CAM/G;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAMjE"}

package/lib/commands/model-docs-args.js

@@ -6,21 +6,22 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { exitWithUsage, helpRequested, LOG_VALUE_FLAGS, logHelpLines, logOptions, parseHarnessArgs, printHelp, SERVICES_FLAG } from './harness-args.js';
+import { exitWithUsage, HARNESS_VALUE_FLAGS, helpRequested, importHelpLines, LOG_VALUE_FLAGS, logHelpLines, logOptions, parseHarnessArgs, printHelp } from './harness-args.js';
 import { OUT_FILE_FLAG } from './headless-harness.js';
 import { runModelDocs } from './model-docs.js';
 const VALUE_FLAGS = [OUT_FILE_FLAG, ...LOG_VALUE_FLAGS];
 /**
- * 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 = [SERVICES_FLAG, ...VALUE_FLAGS];
+export const MODEL_DOCS_FLAGS = [...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 = MODEL_DOCS_FLAGS;
 /** The `--help` text, as data, held to {@link MODEL_DOCS_FLAGS} by a test. */
 export const MODEL_DOCS_HELP = [
-    'Usage: hydranium-cli model-docs --services <module> [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-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',
@@ -31,17 +32,18 @@ export const MODEL_DOCS_HELP = [
     '',
     '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.',
     ...logHelpLines(22)
 ];
 export function parseModelDocsArgs(args, onError = exitWithUsage) {
-    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], ...logOptions(options) };
+    return { servicesModule, imports, outFile: options[OUT_FILE_FLAG], ...logOptions(options) };
 }
 export function runModelDocsCommand(args) {
     if (helpRequested(args, MODEL_DOCS_VALUE_FLAGS)) {

package/lib/commands/model-docs-args.js.map

@@ -1 +1 @@
-{"version":3,"file":"model-docs-args.js","sourceRoot":"","sources":["../../src/commands/model-docs-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,aAAa,EACb,aAAa,EACb,eAAe,EACf,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,SAAS,EACT,aAAa,EAEf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAgC,MAAM,iBAAiB,CAAC;AAE7E,MAAM,WAAW,GAAG,CAAC,aAAa,EAAE,GAAG,eAAe,CAAU,CAAC;AAEjE;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAsB,CAAC,aAAa,EAAE,GAAG,WAAW,CAAC,CAAC;AAEnF,oFAAoF;AACpF,MAAM,CAAC,MAAM,sBAAsB,GAAsB,gBAAgB,CAAC;AAE1E,8EAA8E;AAC9E,MAAM,CAAC,MAAM,eAAe,GAAsB;IAC/C,0IAA0I;IAC1I,EAAE;IACF,gFAAgF;IAChF,mFAAmF;IACnF,gFAAgF;IAChF,kFAAkF;IAClF,4EAA4E;IAC5E,uEAAuE;IACvE,EAAE;IACF,UAAU;IACV,yFAAyF;IACzF,oFAAoF;IACpF,kFAAkF;IAClF,kFAAkF;IAClF,GAAG,YAAY,CAAC,EAAE,CAAC;CACrB,CAAC;AAEF,MAAM,UAAU,kBAAkB,CAAC,IAAc,EAAE,OAAO,GAAe,aAAa;IACnF,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,EAAE,EAAE;QACvF,gBAAgB,EAAE,KAAK;QACvB,OAAO;KACT,CAAC,CAAC;IACH,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,EAAE,GAAG,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;AACtF,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAc;IAC/C,IAAI,aAAa,CAAC,IAAI,EAAE,sBAAsB,CAAC,EAAE,CAAC;QAC/C,SAAS,CAAC,eAAe,CAAC,CAAC;QAC3B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO,YAAY,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;AACjD,CAAC"}
+{"version":3,"file":"model-docs-args.js","sourceRoot":"","sources":["../../src/commands/model-docs-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,eAAe,EACf,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,SAAS,EAEX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAgC,MAAM,iBAAiB,CAAC;AAE7E,MAAM,WAAW,GAAG,CAAC,aAAa,EAAE,GAAG,eAAe,CAAU,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAsB,CAAC,GAAG,mBAAmB,EAAE,GAAG,WAAW,CAAC,CAAC;AAE5F,oFAAoF;AACpF,MAAM,CAAC,MAAM,sBAAsB,GAAsB,gBAAgB,CAAC;AAE1E,8EAA8E;AAC9E,MAAM,CAAC,MAAM,eAAe,GAAsB;IAC/C,oKAAoK;IACpK,EAAE;IACF,gFAAgF;IAChF,mFAAmF;IACnF,gFAAgF;IAChF,kFAAkF;IAClF,4EAA4E;IAC5E,uEAAuE;IACvE,EAAE;IACF,UAAU;IACV,yFAAyF;IACzF,GAAG,eAAe,CAAC,EAAE,CAAC;IACtB,oFAAoF;IACpF,kFAAkF;IAClF,kFAAkF;IAClF,GAAG,YAAY,CAAC,EAAE,CAAC;CACrB,CAAC;AAEF,MAAM,UAAU,kBAAkB,CAAC,IAAc,EAAE,OAAO,GAAe,aAAa;IACnF,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,EAAE,EAAE;QAChG,gBAAgB,EAAE,KAAK;QACvB,OAAO;KACT,CAAC,CAAC;IACH,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,EAAE,GAAG,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;AAC/F,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAc;IAC/C,IAAI,aAAa,CAAC,IAAI,EAAE,sBAAsB,CAAC,EAAE,CAAC;QAC/C,SAAS,CAAC,eAAe,CAAC,CAAC;QAC3B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO,YAAY,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;AACjD,CAAC"}

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

@@ -10,8 +10,9 @@ import { type UsageError } from './harness-args.js';
 import { type ReflectCommandOptions } from './reflect.js';
 /**
  * Every flag `reflect` 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.
+ * 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 declare const REFLECT_FLAGS: readonly string[];
 /** The subset that takes a value, so `--help` in a value position reads as data. */

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

@@ -1 +1 @@
-{"version":3,"file":"reflect-args.d.ts","sourceRoot":"","sources":["../../src/commands/reflect-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EASJ,KAAK,UAAU,EACjB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAc,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAKtE;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAAmD,CAAC;AAE/F,oFAAoF;AACpF,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAAoC,CAAC;AAEtF,2EAA2E;AAC3E,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAgBzC,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,UAA0B,GAAG,qBAAqB,CAW3G;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAM/D"}
+{"version":3,"file":"reflect-args.d.ts","sourceRoot":"","sources":["../../src/commands/reflect-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAUJ,KAAK,UAAU,EACjB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAc,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAKtE;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAA4D,CAAC;AAExG,oFAAoF;AACpF,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAA6C,CAAC;AAE/F,2EAA2E;AAC3E,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAiBzC,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,UAA0B,GAAG,qBAAqB,CAY3G;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAM/D"}

package/lib/commands/reflect-args.js

@@ -6,22 +6,23 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { exitWithUsage, helpRequested, LOG_VALUE_FLAGS, logHelpLines, logOptions, parseHarnessArgs, printHelp, SERVICES_FLAG } from './harness-args.js';
+import { exitWithUsage, HARNESS_VALUE_FLAGS, helpRequested, importHelpLines, LOG_VALUE_FLAGS, logHelpLines, logOptions, parseHarnessArgs, printHelp } from './harness-args.js';
 import { OUT_FILE_FLAG } from './headless-harness.js';
 import { runReflect } from './reflect.js';
 const VALUE_FLAGS = [OUT_FILE_FLAG, ...LOG_VALUE_FLAGS];
 const BOOL_FLAGS = ['--json'];
 /**
  * Every flag `reflect` 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.
+ * 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 REFLECT_FLAGS = [SERVICES_FLAG, ...VALUE_FLAGS, ...BOOL_FLAGS];
+export const REFLECT_FLAGS = [...HARNESS_VALUE_FLAGS, ...VALUE_FLAGS, ...BOOL_FLAGS];
 /** The subset that takes a value, so `--help` in a value position reads as data. */
-export const REFLECT_VALUE_FLAGS = [SERVICES_FLAG, ...VALUE_FLAGS];
+export const REFLECT_VALUE_FLAGS = [...HARNESS_VALUE_FLAGS, ...VALUE_FLAGS];
 /** The `--help` text, as data, held to {@link REFLECT_FLAGS} by a test. */
 export const REFLECT_HELP = [
-    'Usage: hydranium-cli reflect --services <module> [--json] [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
+    'Usage: hydranium-cli reflect --services <module> [--import <specifier>]... [--json] [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
     '',
     "Dump a head's grammar/AST reflection — the type hierarchy, each language's",
     'terminals and entry rule, and every cross-reference target. Read-only: no',
@@ -31,6 +32,7 @@ export const REFLECT_HELP = [
     '',
     'Options:',
     '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+    ...importHelpLines(22),
     '  --json                Emit the raw JSON reflection instead of the Markdown report.',
     '  --out-file <file>     Write the report to this file instead of stdout. Written',
     '                        only once the report exists, unlike a shell redirection,',
@@ -38,12 +40,13 @@ export const REFLECT_HELP = [
     ...logHelpLines(22)
 ];
 export function parseReflectArgs(args, onError = exitWithUsage) {
-    const { servicesModule, options } = parseHarnessArgs(args, 'reflect', VALUE_FLAGS, BOOL_FLAGS, {
+    const { servicesModule, imports, options } = parseHarnessArgs(args, 'reflect', VALUE_FLAGS, BOOL_FLAGS, {
         requireWorkspace: false,
         onError
     });
     return {
         servicesModule,
+        imports,
         json: options['--json'] === 'true',
         outFile: options[OUT_FILE_FLAG],
         ...logOptions(options)

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

@@ -1 +1 @@
-{"version":3,"file":"reflect-args.js","sourceRoot":"","sources":["../../src/commands/reflect-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,aAAa,EACb,aAAa,EACb,eAAe,EACf,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,SAAS,EACT,aAAa,EAEf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,UAAU,EAA8B,MAAM,cAAc,CAAC;AAEtE,MAAM,WAAW,GAAG,CAAC,aAAa,EAAE,GAAG,eAAe,CAAU,CAAC;AACjE,MAAM,UAAU,GAAG,CAAC,QAAQ,CAAU,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAsB,CAAC,aAAa,EAAE,GAAG,WAAW,EAAE,GAAG,UAAU,CAAC,CAAC;AAE/F,oFAAoF;AACpF,MAAM,CAAC,MAAM,mBAAmB,GAAsB,CAAC,aAAa,EAAE,GAAG,WAAW,CAAC,CAAC;AAEtF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,YAAY,GAAsB;IAC5C,gJAAgJ;IAChJ,EAAE;IACF,4EAA4E;IAC5E,2EAA2E;IAC3E,0EAA0E;IAC1E,6EAA6E;IAC7E,mFAAmF;IACnF,EAAE;IACF,UAAU;IACV,yFAAyF;IACzF,sFAAsF;IACtF,kFAAkF;IAClF,kFAAkF;IAClF,kFAAkF;IAClF,GAAG,YAAY,CAAC,EAAE,CAAC;CACrB,CAAC;AAEF,MAAM,UAAU,gBAAgB,CAAC,IAAc,EAAE,OAAO,GAAe,aAAa;IACjF,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE;QAC5F,gBAAgB,EAAE,KAAK;QACvB,OAAO;KACT,CAAC,CAAC;IACH,OAAO;QACJ,cAAc;QACd,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,MAAM;QAClC,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC;QAC/B,GAAG,UAAU,CAAC,OAAO,CAAC;KACxB,CAAC;AACL,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAc;IAC7C,IAAI,aAAa,CAAC,IAAI,EAAE,mBAAmB,CAAC,EAAE,CAAC;QAC5C,SAAS,CAAC,YAAY,CAAC,CAAC;QACxB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO,UAAU,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;AAC7C,CAAC"}
+{"version":3,"file":"reflect-args.js","sourceRoot":"","sources":["../../src/commands/reflect-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,eAAe,EACf,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,SAAS,EAEX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,UAAU,EAA8B,MAAM,cAAc,CAAC;AAEtE,MAAM,WAAW,GAAG,CAAC,aAAa,EAAE,GAAG,eAAe,CAAU,CAAC;AACjE,MAAM,UAAU,GAAG,CAAC,QAAQ,CAAU,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAsB,CAAC,GAAG,mBAAmB,EAAE,GAAG,WAAW,EAAE,GAAG,UAAU,CAAC,CAAC;AAExG,oFAAoF;AACpF,MAAM,CAAC,MAAM,mBAAmB,GAAsB,CAAC,GAAG,mBAAmB,EAAE,GAAG,WAAW,CAAC,CAAC;AAE/F,2EAA2E;AAC3E,MAAM,CAAC,MAAM,YAAY,GAAsB;IAC5C,0KAA0K;IAC1K,EAAE;IACF,4EAA4E;IAC5E,2EAA2E;IAC3E,0EAA0E;IAC1E,6EAA6E;IAC7E,mFAAmF;IACnF,EAAE;IACF,UAAU;IACV,yFAAyF;IACzF,GAAG,eAAe,CAAC,EAAE,CAAC;IACtB,sFAAsF;IACtF,kFAAkF;IAClF,kFAAkF;IAClF,kFAAkF;IAClF,GAAG,YAAY,CAAC,EAAE,CAAC;CACrB,CAAC;AAEF,MAAM,UAAU,gBAAgB,CAAC,IAAc,EAAE,OAAO,GAAe,aAAa;IACjF,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE;QACrG,gBAAgB,EAAE,KAAK;QACvB,OAAO;KACT,CAAC,CAAC;IACH,OAAO;QACJ,cAAc;QACd,OAAO;QACP,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,MAAM;QAClC,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC;QAC/B,GAAG,UAAU,CAAC,OAAO,CAAC;KACxB,CAAC;AACL,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAc;IAC7C,IAAI,aAAa,CAAC,IAAI,EAAE,mBAAmB,CAAC,EAAE,CAAC;QAC5C,SAAS,CAAC,YAAY,CAAC,CAAC;QACxB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO,UAAU,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;AAC7C,CAAC"}

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

@@ -10,8 +10,9 @@ import { type UsageError } from './harness-args.js';
 import { type ValidateCommandOptions } from './validate.js';
 /**
  * Every flag `validate` 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.
+ * 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 declare const VALIDATE_FLAGS: readonly string[];
 /** The subset that takes a value, so `--help` in a value position reads as data. */

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

@@ -1 +1 @@
-{"version":3,"file":"validate-args.d.ts","sourceRoot":"","sources":["../../src/commands/validate-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EASJ,KAAK,UAAU,EACjB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAe,KAAK,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAKzE;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAAmD,CAAC;AAEhG,oFAAoF;AACpF,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAAoC,CAAC;AAEvF,4EAA4E;AAC5E,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAkB1C,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,UAA0B,GAAG,sBAAsB,CAU7G;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhE"}
+{"version":3,"file":"validate-args.d.ts","sourceRoot":"","sources":["../../src/commands/validate-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAUJ,KAAK,UAAU,EACjB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAe,KAAK,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAKzE;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAA4D,CAAC;AAEzG,oFAAoF;AACpF,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAA6C,CAAC;AAEhG,4EAA4E;AAC5E,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAmB1C,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,UAA0B,GAAG,sBAAsB,CAW7G;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhE"}

package/lib/commands/validate-args.js

@@ -6,22 +6,23 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { exitWithUsage, helpRequested, LOG_VALUE_FLAGS, logHelpLines, logOptions, parseHarnessArgs, printHelp, SERVICES_FLAG } from './harness-args.js';
+import { exitWithUsage, HARNESS_VALUE_FLAGS, helpRequested, importHelpLines, LOG_VALUE_FLAGS, logHelpLines, logOptions, parseHarnessArgs, printHelp } from './harness-args.js';
 import { OUT_FILE_FLAG } from './headless-harness.js';
 import { runValidate } from './validate.js';
 const VALUE_FLAGS = [OUT_FILE_FLAG, ...LOG_VALUE_FLAGS];
 const BOOL_FLAGS = ['--strict', '--json'];
 /**
  * Every flag `validate` 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.
+ * 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 VALIDATE_FLAGS = [SERVICES_FLAG, ...VALUE_FLAGS, ...BOOL_FLAGS];
+export const VALIDATE_FLAGS = [...HARNESS_VALUE_FLAGS, ...VALUE_FLAGS, ...BOOL_FLAGS];
 /** The subset that takes a value, so `--help` in a value position reads as data. */
-export const VALIDATE_VALUE_FLAGS = [SERVICES_FLAG, ...VALUE_FLAGS];
+export const VALIDATE_VALUE_FLAGS = [...HARNESS_VALUE_FLAGS, ...VALUE_FLAGS];
 /** The `--help` text, as data, held to {@link VALIDATE_FLAGS} by a test. */
 export const VALIDATE_HELP = [
-    'Usage: hydranium-cli validate --services <module> <workspace> [--strict] [--json] [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
+    'Usage: hydranium-cli validate --services <module> [--import <specifier>]... <workspace> [--strict] [--json] [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
     '',
     'Build a workspace headlessly and report its validation diagnostics — a CI gate:',
     'the process exits non-zero when any error is found. `<module>` is an ESM module',
@@ -30,6 +31,7 @@ export const VALIDATE_HELP = [
     '',
     'Options:',
     '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+    ...importHelpLines(22),
     '  <workspace>           Workspace root (path or file URI) to validate (required).',
     '  --strict              Also fail (non-zero exit) on warnings, not only errors.',
     '  --json                Emit the raw JSON result instead of the human report.',
@@ -40,9 +42,10 @@ export const VALIDATE_HELP = [
     ...logHelpLines(22)
 ];
 export function parseValidateArgs(args, onError = exitWithUsage) {
-    const { servicesModule, workspace, options } = parseHarnessArgs(args, 'validate', VALUE_FLAGS, BOOL_FLAGS, { onError });
+    const { servicesModule, imports, workspace, options } = parseHarnessArgs(args, 'validate', VALUE_FLAGS, BOOL_FLAGS, { onError });
     return {
         servicesModule,
+        imports,
         workspace,
         strict: options['--strict'] === 'true',
         json: options['--json'] === 'true',

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

@@ -1 +1 @@
-{"version":3,"file":"validate-args.js","sourceRoot":"","sources":["../../src/commands/validate-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,aAAa,EACb,aAAa,EACb,eAAe,EACf,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,SAAS,EACT,aAAa,EAEf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,WAAW,EAA+B,MAAM,eAAe,CAAC;AAEzE,MAAM,WAAW,GAAG,CAAC,aAAa,EAAE,GAAG,eAAe,CAAU,CAAC;AACjE,MAAM,UAAU,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAU,CAAC;AAEnD;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAsB,CAAC,aAAa,EAAE,GAAG,WAAW,EAAE,GAAG,UAAU,CAAC,CAAC;AAEhG,oFAAoF;AACpF,MAAM,CAAC,MAAM,oBAAoB,GAAsB,CAAC,aAAa,EAAE,GAAG,WAAW,CAAC,CAAC;AAEvF,4EAA4E;AAC5E,MAAM,CAAC,MAAM,aAAa,GAAsB;IAC7C,wKAAwK;IACxK,EAAE;IACF,iFAAiF;IACjF,iFAAiF;IACjF,mFAAmF;IACnF,4CAA4C;IAC5C,EAAE;IACF,UAAU;IACV,yFAAyF;IACzF,mFAAmF;IACnF,iFAAiF;IACjF,+EAA+E;IAC/E,mFAAmF;IACnF,mFAAmF;IACnF,mFAAmF;IACnF,gFAAgF;IAChF,GAAG,YAAY,CAAC,EAAE,CAAC;CACrB,CAAC;AAEF,MAAM,UAAU,iBAAiB,CAAC,IAAc,EAAE,OAAO,GAAe,aAAa;IAClF,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IACxH,OAAO;QACJ,cAAc;QACd,SAAS;QACT,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,MAAM;QACtC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,MAAM;QAClC,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC;QAC/B,GAAG,UAAU,CAAC,OAAO,CAAC;KACxB,CAAC;AACL,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAc;IAC9C,IAAI,aAAa,CAAC,IAAI,EAAE,oBAAoB,CAAC,EAAE,CAAC;QAC7C,SAAS,CAAC,aAAa,CAAC,CAAC;QACzB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO,WAAW,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"validate-args.js","sourceRoot":"","sources":["../../src/commands/validate-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,eAAe,EACf,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,SAAS,EAEX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,WAAW,EAA+B,MAAM,eAAe,CAAC;AAEzE,MAAM,WAAW,GAAG,CAAC,aAAa,EAAE,GAAG,eAAe,CAAU,CAAC;AACjE,MAAM,UAAU,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAU,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAsB,CAAC,GAAG,mBAAmB,EAAE,GAAG,WAAW,EAAE,GAAG,UAAU,CAAC,CAAC;AAEzG,oFAAoF;AACpF,MAAM,CAAC,MAAM,oBAAoB,GAAsB,CAAC,GAAG,mBAAmB,EAAE,GAAG,WAAW,CAAC,CAAC;AAEhG,4EAA4E;AAC5E,MAAM,CAAC,MAAM,aAAa,GAAsB;IAC7C,kMAAkM;IAClM,EAAE;IACF,iFAAiF;IACjF,iFAAiF;IACjF,mFAAmF;IACnF,4CAA4C;IAC5C,EAAE;IACF,UAAU;IACV,yFAAyF;IACzF,GAAG,eAAe,CAAC,EAAE,CAAC;IACtB,mFAAmF;IACnF,iFAAiF;IACjF,+EAA+E;IAC/E,mFAAmF;IACnF,mFAAmF;IACnF,mFAAmF;IACnF,gFAAgF;IAChF,GAAG,YAAY,CAAC,EAAE,CAAC;CACrB,CAAC;AAEF,MAAM,UAAU,iBAAiB,CAAC,IAAc,EAAE,OAAO,GAAe,aAAa;IAClF,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IACjI,OAAO;QACJ,cAAc;QACd,OAAO;QACP,SAAS;QACT,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,MAAM;QACtC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,MAAM;QAClC,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC;QAC/B,GAAG,UAAU,CAAC,OAAO,CAAC;KACxB,CAAC;AACL,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAc;IAC9C,IAAI,aAAa,CAAC,IAAI,EAAE,oBAAoB,CAAC,EAAE,CAAC;QAC7C,SAAS,CAAC,aAAa,CAAC,CAAC;QACzB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO,WAAW,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/C,CAAC"}

package/package.json

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

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

@@ -10,13 +10,14 @@
 import { runAstGroundTruth, type AstGroundTruthCommandOptions } from './ast-ground-truth.js';
 import {
    exitWithUsage,
+   HARNESS_VALUE_FLAGS,
    helpRequested,
+   importHelpLines,
    LOG_VALUE_FLAGS,
    logHelpLines,
    logOptions,
    parseHarnessArgs,
    printHelp,
-   SERVICES_FLAG,
    type UsageError
 } from './harness-args.js';
 import { OUT_FILE_FLAG } from './headless-harness.js';
@@ -25,17 +26,18 @@ const VALUE_FLAGS = [OUT_FILE_FLAG, ...LOG_VALUE_FLAGS] as const;
 
 /**
  * Every flag `ast-ground-truth` 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 AST_GROUND_TRUTH_FLAGS: readonly string[] = [SERVICES_FLAG, ...VALUE_FLAGS];
+export const AST_GROUND_TRUTH_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 AST_GROUND_TRUTH_VALUE_FLAGS: readonly string[] = AST_GROUND_TRUTH_FLAGS;
 
 /** The `--help` text, as data, held to {@link AST_GROUND_TRUTH_FLAGS} by a test. */
 export const AST_GROUND_TRUTH_HELP: readonly string[] = [
-   'Usage: hydranium-cli ast-ground-truth --services <module> <workspace> [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
+   'Usage: hydranium-cli ast-ground-truth --services <module> [--import <specifier>]... <workspace> [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    "Tally a workspace's live-model AST nodes by `$type` — the ground truth that",
    '`analyze-heap --validate <gt.json>` checks a heap snapshot against. `<module>`',
@@ -44,14 +46,15 @@ export const AST_GROUND_TRUTH_HELP: readonly string[] = [
    '',
    'Options:',
    '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   ...importHelpLines(22),
    '  <workspace>           Workspace root (path or file URI) to build (required).',
    '  --out-file <file>     Write the JSON to this file instead of stdout.',
    ...logHelpLines(22)
 ];
 
 export function parseAstGroundTruthArgs(args: string[], onError: UsageError = exitWithUsage): AstGroundTruthCommandOptions {
-   const { servicesModule, workspace, options } = parseHarnessArgs(args, 'ast-ground-truth', VALUE_FLAGS, [], { onError });
-   return { servicesModule, workspace, outFile: options[OUT_FILE_FLAG], ...logOptions(options) };
+   const { servicesModule, imports, workspace, options } = parseHarnessArgs(args, 'ast-ground-truth', VALUE_FLAGS, [], { onError });
+   return { servicesModule, imports, workspace, outFile: options[OUT_FILE_FLAG], ...logOptions(options) };
 }
 
 export function runAstGroundTruthCommand(args: string[]): Promise<void> {

package/src/commands/harness-args.ts

@@ -56,9 +56,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.
  *
@@ -88,15 +97,22 @@ export const SERVER_SPAWN_VALUE_FLAGS: readonly string[] = ['--server', '--cwd',
  * next line, at the column.
  */
 export function logHelpLines(padTo: number, head = 'the head this boots'): string[] {
-   const line = (flag: string, text: string): string[] =>
-      flag.length < padTo - 1 ? [`  ${flag.padEnd(padTo)}${text}`] : [`  ${flag}`, `${' '.repeat(padTo + 2)}${text}`];
    return [
-      line(`${LOG_LEVEL_FLAG} <lvl>`, `Log threshold for ${head} (off|error|warn|info|debug|trace).`),
-      line(`${LOG_FILE_FLAG} <file>`, `Also write ${head}'s log to <file>; {workspace} expands to the workspace.`),
-      line(`${LOG_FILE_LEVEL_FLAG} <lvl>`, `Threshold for that file, which the log-level setting does not change.`)
+      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: 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 the raw {@link LOG_VALUE_FLAGS} values a parser collected, leaving
  * absent flags absent.
@@ -158,6 +174,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`.
@@ -187,12 +205,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[],
@@ -209,6 +227,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];
@@ -220,8 +239,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)) {
@@ -237,7 +258,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 ?? ''),

package/src/commands/headless-harness.ts

@@ -15,7 +15,7 @@ import * as path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { driverHeapArgs, type HeapReading } from '../driver-heap.js';
 import { logEnv, type LogOptions } from '../log-level.js';
-import { SERVICES_FLAG } from './harness-args.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,8 +43,9 @@ 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) rather
@@ -65,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 head's entry, e.g. \`${SERVICES_FLAG} ./lib/services.js\` — ` +
+            '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(
@@ -85,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.
@@ -137,6 +169,8 @@ export type SpawnDriverChild = (execArgs: string[], env?: Record<string, string>
  * 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;
    /**
@@ -171,8 +205,21 @@ export interface DriverSpawnOptions extends LogOptions {
  */
 export async function runDriverChild(execArgs: string[], options: DriverSpawnOptions): Promise<void> {
    const spawnChild = options.__spawnForTest ?? spawnNodeChild;
-   const code = await spawnChild([...driverHeapArgs(options.__heapReadingForTest), ...execArgs], logEnv(options));
+   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;
+}