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

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.210",
+  "version": "1.0.0-next.213",
   "description": "Build-time codegen tools + data-server subcommands for the hydranium framework.",
   "keywords": [
     "cli",
@@ -69,23 +69,23 @@
     "ts-morph": "^25.0.0"
   },
   "devDependencies": {
-    "@hydranium/core": "1.0.0-next.210",
-    "@hydranium/data-server": "1.0.0-next.210",
-    "@hydranium/langium": "1.0.0-next.210",
-    "@hydranium/protocol": "1.0.0-next.210",
+    "@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.1",
-    "vscode-languageserver": "~10.0.1"
+    "vscode-jsonrpc": "9.0.0",
+    "vscode-languageserver": "10.0.1"
   },
   "peerDependencies": {
-    "@hydranium/core": "1.0.0-next.210",
-    "@hydranium/data-server": "1.0.0-next.210",
-    "@hydranium/langium": "1.0.0-next.210",
-    "@hydranium/protocol": "1.0.0-next.210",
+    "@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.1"
+    "vscode-jsonrpc": "^9.0.0"
   },
   "peerDependenciesMeta": {
     "@memlab/core": {
@@ -100,7 +100,7 @@
   },
   "//exports": "Two keys, and the SHORT list is the point: `files` ships the whole compiled tree, so without a map every `lib/commands/*.js`, every internal helper and `lib/testing/echo-server.js` is deep-importable the moment this publishes, and semver then applies to all of it. `.` is the library barrel (the data-server subcommands an adopter calls as functions). `./lib/cli.js` is the BINARY ARTEFACT, and it is declared because a consumer that spawns the CLI resolves it BY SPECIFIER — `createRequire(import.meta.url).resolve('@hydranium/cli/lib/cli.js')` — to get the path npx would run; `bin` gives a shim on PATH, not a path, so dropping this key breaks that resolution and the failure surfaces as \"hydranium-cli is not built\", naming the wrong cause. It is declared in the `/lib/` spelling ONLY: that spelling already resolves under both of this repo's module resolvers, so the twin rule (which exists so a BARE subpath is reachable from node10) has nothing to add here and a bare twin would only be a second name for one artefact. `heap-analysis/` needs no key even though `files` ships it — `analyze-heap` reaches the analyzer through a `new URL(..., import.meta.url)` file URL, which `exports` does not gate, and the package's own tests reach it relatively. `./testing` is deliberately absent: `echo-server` is a spawnable stdio fixture, not a reusable export.",
   "//memlab": "@memlab/core and @memlab/heap-analysis are OPTIONAL PEER dependencies, not optionalDependencies, and the distinction is the whole point: npm installs optionalDependencies BY DEFAULT, both memlab packages pin puppeteer exactly, and puppeteer's postinstall downloads a Chrome binary — so every adopter of this CLI paid ~86 MB and a browser download for the one subcommand almost none of them run, and the download can fail and be walked past as a warning. An optional peer is not auto-installed, so `analyze-heap` documents `npm install @memlab/core @memlab/heap-analysis` as the opt-in and every other subcommand is unaffected. Taken pre-publish deliberately: after publish the install shape is what adopters already have.",
-  "//peerDependencies": "`vscode-jsonrpc` is EXACT rather than a range, because it is one link of an atomic chain with no independently movable link: `vscode-languageserver-protocol` depends on it at exactly 9.0.1, so any other value an adopter supplies is a SECOND physical copy rather than an upgrade. This wire stack breaks on copy identity rather than on structure — `ParameterStructures.auto` is a singleton compared by `===` in connection.js, so a request type built by one copy and sent over a connection owned by the other throws `Unknown parameter structure auto`. A caret or union range was rejected because npm then resolves a `vscode-jsonrpc@8.2.0` tree SILENTLY, with no diagnostic at all, and the failure surfaces only later at server init. Exact does not fail the install either — npm downgrades an unsatisfiable peer to a warning — but it is a NAMED ERESOLVE warning printing the required version beside the found one, and a hard error for anyone installing with `--strict-peer-deps`. It does NOT prevent a NESTED copy — `@eclipse-glsp/*` carries its own exact `vscode-jsonrpc@8.2.0` dependency and root `overrides` do not ship — so a consumer of the GLSP head must pin the chain in its own manifest, and docs/adopting/requirements.md carries the block to paste.",
-  "//prepack": "The publish guard, and it deliberately is NOT a `prepare`: npm runs a workspace `prepare` BEFORE the root `postinstall` that applies patches/vscode-jsonrpc+9.0.1.patch, so building there fails on a cold clone and npm rolls the entire install back. `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. It FAILS rather than rebuilds, because the rebuild is exactly the part that ordering defeats. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error.",
+  "//peerDependencies": "`vscode-jsonrpc` takes a caret, so the framework shares the transport the LSP connection resolves, which an `init` scaffold pins: each `vscode-languageserver-protocol` release pins its transport exactly, so an exact peer would name a copy a fresh install rarely holds. The caret excludes 8.x, so a tree whose top holds GLSP's copy fails the peer with a named ERESOLVE warning, an error under `--strict-peer-deps`, rather than resolving silently. No peer reaches a NESTED copy, such as GLSP's or one the LSP packages nest; docs/adopting/requirements.md has the chain. The wire compares message types and `ResponseError`s by copy identity, so the framework sends typed messages by method name and recognises errors with `isResponseError` rather than `instanceof`.",
+  "//prepack": "The publish guard, a `prepack` rather than a `prepare`: `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error.",
   "//sideEffects": "The listed modules RUN on load rather than exporting anything: `cli.js` is the `bin`, each `*-driver.js` is spawned as its own process and calls `main(process.argv)` at top level, and `echo-server.js` starts a server. Their whole purpose is the effect, so a bundler must never treat them as prunable. Everything else here is library code with no module-level state beyond `new URL(..., import.meta.url)` constants."
 }

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;
+}

package/src/commands/init-templates.ts

@@ -218,7 +218,12 @@ const HEAD_FRAMEWORK_DEPENDENCIES: Record<InitHead, readonly string[]> = {
 const HEAD_THIRD_PARTY_DEPENDENCIES: Record<InitHead, Readonly<Record<string, string>>> = {
    lsp: {
       langium: '4.3.1',
-      'vscode-languageserver': '~10.0.1'
+      // Exact, as are the protocol and transport it pins, so Langium and the
+      // framework share their copies; across copies, an error a handler throws
+      // or returns loses its code, and a later patch can pin another protocol.
+      'vscode-languageserver': '10.0.1',
+      'vscode-jsonrpc': '9.0.0',
+      'vscode-languageserver-protocol': '3.18.1'
    },
    data: {},
    glsp: {
@@ -231,6 +236,24 @@ const HEAD_THIRD_PARTY_DEPENDENCIES: Record<InitHead, Readonly<Record<string, st
    }
 };
 
+/** Whether an npm version is 11.6.0 or later, the first that installs `vitest` 4.1's peer set; `11.6.0-rc.1` is earlier. */
+function installsVitest41(npmVersion: string | undefined): boolean {
+   const [release, prerelease] = (npmVersion ?? '0.0.0').split('-', 2);
+   const [major, minor, patch] = release.split('.').map(Number);
+   return major > 11 || (major === 11 && (minor > 6 || (minor === 6 && (patch > 0 || prerelease === undefined))));
+}
+
+/**
+ * Whether the scaffold holds `vitest` below 4.1, whose peer set crashes npm
+ * before 11.6 (every npm a Node 22 release bundles) on the first install. Only a
+ * workspace root declaring a newer npm lifts it, and only when `init` runs under
+ * an npm known to be newer: npm does not enforce `packageManager`.
+ */
+function pinsVitest(composition: InitComposition): boolean {
+   const workspace = composition.packaging.workspace;
+   return !(installsVitest41(workspace?.packageManagerNpm) && installsVitest41(workspace?.npmVersion));
+}
+
 /** The dependency block for a head set, merged and sorted as npm writes it. */
 function dependencyBlock(composition: InitComposition, indent: string): string {
    const merged: Record<string, string> = {};
@@ -315,7 +338,7 @@ __DEPENDENCIES__
     "langium-cli": "4.3.0",
     "rimraf": "^5.0.0",
     "typescript": "^7.0.2",
-    "vitest": "^4.0.0"
+    "vitest": "__VITEST__"
   },
   "engines": {
     "node": ">=22.13"
@@ -385,6 +408,7 @@ function packageJson(composition: InitComposition): string {
       .replace('__KEYWORDS__', keywords)
       .replace('__BIN__', binBlock(composition))
       .replace('__LINT__', lint)
+      .replace('__VITEST__', pinsVitest(composition) ? '~4.0.18' : '^4.0.0')
       .replace('__PRIVATE__', composition.packaging.private ? '  "private": true,\n' : '')
       .replace('__NPM_RUN__', npmRun(composition))
       .replace('__FRAMEWORK_PIN__', frameworkPin(composition))
@@ -1565,6 +1589,24 @@ function readme(composition: InitComposition): string {
       'atomic set and depends on a single physical copy, so a floating range can',
       'silently resolve a second one.',
       '',
+      '`vscode-languageserver` is pinned to `10.0.1`, and',
+      '`vscode-languageserver-protocol` and `vscode-jsonrpc` to the `3.18.1` and',
+      '`9.0.0` it pins, so Langium, the LSP connection and the framework share one',
+      'copy of each. With two, an error a Langium handler returns, such as a request',
+      'for a document the server does not have, reaches the client as a result, and a',
+      'framework error your own LSP handler throws loses its code. The Langium 4.4',
+      'upgrade',
+      '([eclipse-emfcloud/hydranium#142](https://github.com/eclipse-emfcloud/hydranium/issues/142))',
+      'replaces these pins.',
+      '',
+      ...(pinsVitest(composition)
+         ? [
+              '`vitest` is held below 4.1, whose peer set crashes the npm every Node 22',
+              'release bundles. Raise it once every npm that installs this project is',
+              '11.6 or later.',
+              ''
+           ]
+         : []),
       '## If your repo gates license headers',
       '',
       'The emitted `.ts` files carry no copyright header — the scaffold cannot know',

package/src/commands/init-workspace.ts

@@ -192,6 +192,8 @@ export interface WorkspaceDetection {
    readonly eslintConfig?: string;
    /** Filename of the root Oxlint config, when present. */
    readonly oxlintConfig?: string;
+   /** The npm version the root's `packageManager` field declares, when it names npm. */
+   readonly packageManagerNpm?: string;
 }
 
 /**
@@ -407,6 +409,17 @@ export function findOxlintConfig(rootDir: string, probe: WorkspaceProbe): string
    return probe.listFiles(rootDir).find(name => /^(oxlint\.config\.[cm]?[jt]s|\.oxlintrc\.jsonc?)$/.test(name));
 }
 
+/** The npm version the root's `packageManager` field declares (`npm@11.15.0` gives `11.15.0`), when it names npm. */
+export function findPackageManagerNpm(rootDir: string, probe: WorkspaceProbe): string | undefined {
+   const manifest = probe.readJson(path.join(rootDir, 'package.json'));
+   return parseNpmVersion(isJsonObject(manifest) && typeof manifest.packageManager === 'string' ? manifest.packageManager : undefined);
+}
+
+/** The npm version, prerelease included, of a `packageManager` field (`npm@…`) or a user agent (`npm/…`); undefined for another tool. */
+export function parseNpmVersion(spec: string | undefined): string | undefined {
+   return /^npm[@/](\d+\.\d+\.\d+(?:-[\w.]+)?)/.exec(spec ?? '')?.[1];
+}
+
 /** POSIX-style relative path, which is what both `extends` and `--prefix` want on every platform. */
 function posixRelative(from: string, to: string): string {
    return path.relative(from, to).split(path.sep).join('/');
@@ -447,6 +460,7 @@ export function detectWorkspace(targetDir: string, probe: WorkspaceProbe): Works
       baseCompilerOptions: base?.compilerOptions,
       printWidth: findFormatterPrintWidth(rootDir, probe),
       eslintConfig: findEslintConfig(rootDir, probe),
-      oxlintConfig: findOxlintConfig(rootDir, probe)
+      oxlintConfig: findOxlintConfig(rootDir, probe),
+      packageManagerNpm: findPackageManagerNpm(rootDir, probe)
    };
 }