@hydranium/cli 1.0.0-next.28 → 1.0.0-next.280

package/src/commands/generate-ast-builder.ts

@@ -0,0 +1,246 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type { SourceFile } from 'ts-morph';
+
+/** Inputs for {@link emitAstBuilder}, resolved by the transfer-model command. */
+export interface EmitAstBuilderOptions {
+   /** Destination path for the generated builder module. */
+   outFile: string;
+   /** Path to the Langium-generated AST file the builder imports from. */
+   astFile: string;
+   /** Language id derived from the `<LanguageId>AstReflection` class name. */
+   languageId: string;
+   /** Header line naming the command that regenerates the file. */
+   regenCommand: string;
+}
+
+/**
+ * A single `makeAstNodeBuilder` binding the generator emits.
+ *
+ * `typeMap` is the type expression handed to the generic — the whole-project
+ * alias for the merged binding, `<Namespace>.AstType` for a narrowed one.
+ */
+interface BuilderBinding {
+   exportName: string;
+   typeMap: string;
+   /** Grammar this binding is narrowed to; absent on the merged binding. */
+   namespace?: string;
+}
+
+/**
+ * Langium declares this type alias inside each language's namespace in a
+ * multi-language project. Its presence is what marks a namespace as a grammar's
+ * type registry rather than an incidental one.
+ */
+const NAMESPACED_AST_TYPE_NAME = 'AstType';
+
+/** Export name of the merged, whole-project binding. */
+const MERGED_EXPORT_NAME = 'astNode';
+
+/**
+ * Emit a module binding {@link makeAstNodeBuilder} to a project's reflection,
+ * once per grammar plus once across all of them.
+ *
+ * **The binding is boilerplate with exactly one degree of freedom** — the type
+ * map — so hand-writing it buys nothing and goes stale the moment a grammar is
+ * added. Generating it is also the only way a narrowed binding can exist at all:
+ * the per-grammar type maps live in namespaces Langium emits only on its
+ * multi-language path, so a single-grammar project gets the merged binding alone
+ * and there is nothing to narrow.
+ *
+ * **A narrowed binding is only as narrow as its grammar's import closure.**
+ * Langium's per-grammar `AstType` lists everything REACHABLE from that grammar,
+ * so where one grammar imports all the others its map equals the project's and
+ * its binding checks nothing the merged one does not. The emitted doc says so at
+ * each declaration rather than promising a guarantee the type map cannot give.
+ *
+ * Answers `false` when the AST source declares no whole-project type alias,
+ * which means the file did not come from `langium generate` and the caller
+ * should report rather than write a module that cannot compile.
+ */
+export function emitAstBuilder(astSource: SourceFile, options: EmitAstBuilderOptions): boolean {
+   const content = buildAstBuilderSource(astSource, options);
+   if (content === undefined) {
+      return false;
+   }
+
+   fs.mkdirSync(path.dirname(options.outFile), { recursive: true });
+   if (fs.existsSync(options.outFile) && fs.readFileSync(options.outFile, 'utf-8') === content) {
+      console.log('AST builder is up to date.');
+      return true;
+   }
+   fs.writeFileSync(options.outFile, content, 'utf-8');
+   console.log(`Generated: ${options.outFile}`);
+   return true;
+}
+
+/**
+ * The module text {@link emitAstBuilder} would write, or `undefined` when the
+ * AST source declares no whole-project type alias. Pure over its inputs, so the
+ * emitted shape is testable without touching a filesystem.
+ */
+export function buildAstBuilderSource(astSource: SourceFile, options: EmitAstBuilderOptions): string | undefined {
+   const mergedTypeMap = `${options.languageId}AstType`;
+   if (!astSource.getTypeAlias(mergedTypeMap)) {
+      return undefined;
+   }
+
+   const bindings: BuilderBinding[] = [{ exportName: MERGED_EXPORT_NAME, typeMap: mergedTypeMap }];
+   for (const namespace of findGrammarNamespaces(astSource)) {
+      bindings.push({
+         exportName: builderExportName(namespace),
+         typeMap: `${namespace}.${NAMESPACED_AST_TYPE_NAME}`,
+         namespace
+      });
+   }
+   assertDistinctExportNames(bindings);
+
+   return renderAstBuilder(bindings, {
+      reflectionName: findReflectionConstName(astSource, options.languageId),
+      importPath: relativeImportPath(options.outFile, options.astFile),
+      regenCommand: options.regenCommand
+   });
+}
+
+/**
+ * Namespaces that carry a grammar's type registry, in declaration order.
+ *
+ * Keyed on the nested `AstType` alias rather than on the namespace being
+ * exported, because an adopter's augmentation can add namespaces to the same
+ * file for unrelated reasons and only the ones Langium emits per grammar have
+ * a type map to bind.
+ */
+function findGrammarNamespaces(astSource: SourceFile): string[] {
+   const names: string[] = [];
+   for (const module of astSource.getModules()) {
+      const name = module.getName();
+      if (name && module.getTypeAlias(NAMESPACED_AST_TYPE_NAME)) {
+         names.push(name);
+      }
+   }
+   return names;
+}
+
+/**
+ * `Domain` → `domainNode`. Lower-cases the leading character only, so a grammar
+ * named `OrderFlow` reads as `orderFlowNode` rather than losing its word break.
+ */
+function builderExportName(namespace: string): string {
+   return `${namespace.charAt(0).toLowerCase()}${namespace.slice(1)}Node`;
+}
+
+/**
+ * Two grammars whose names differ only in their leading character collapse to
+ * one export. Emitting anyway would silently drop a binding, so fail with both
+ * names rather than leave the caller to discover it at compile time.
+ */
+function assertDistinctExportNames(bindings: readonly BuilderBinding[]): void {
+   const seen = new Map<string, string>();
+   for (const binding of bindings) {
+      const previous = seen.get(binding.exportName);
+      if (previous !== undefined) {
+         throw new Error(
+            `Cannot emit the AST builder: grammars '${previous}' and '${binding.namespace}' both map to the export ` +
+               `'${binding.exportName}'. Rename one grammar so the generated bindings stay distinct.`
+         );
+      }
+      seen.set(binding.exportName, binding.namespace ?? MERGED_EXPORT_NAME);
+   }
+}
+
+/**
+ * Name of the const holding the project's reflection instance.
+ *
+ * Langium emits `export const reflection = new <LanguageId>AstReflection()`, but
+ * the const is located by its initializer rather than by that name so a renamed
+ * export still resolves. Falls back to the emitted default when no declaration
+ * matches, which keeps the output compiling against a stock Langium file.
+ */
+function findReflectionConstName(astSource: SourceFile, languageId: string): string {
+   const reflectionClass = `${languageId}AstReflection`;
+   for (const declaration of astSource.getVariableDeclarations()) {
+      if (declaration.getInitializer()?.getText().replace(/\s/g, '') === `new${reflectionClass}()`) {
+         return declaration.getName();
+      }
+   }
+   return 'reflection';
+}
+
+/**
+ * Module specifier for the AST file as seen from the generated module's own
+ * directory. Emitted with a `.js` extension and posix separators because the
+ * output is ESM TypeScript, where the specifier names the compiled sibling.
+ */
+function relativeImportPath(outFile: string, astFile: string): string {
+   const relative = path.relative(path.dirname(path.resolve(outFile)), path.resolve(astFile));
+   const posix = relative.split(path.sep).join('/').replace(/\.ts$/, '.js');
+   return posix.startsWith('.') ? posix : `./${posix}`;
+}
+
+function renderAstBuilder(
+   bindings: readonly BuilderBinding[],
+   context: { reflectionName: string; importPath: string; regenCommand: string }
+): string {
+   const imported = [context.reflectionName, ...bindings.map(binding => `type ${binding.namespace ?? binding.typeMap}`)];
+   const out: string[] = [];
+
+   out.push('/******************************************************************************');
+   out.push(' * Generated from the Langium AST — DO NOT EDIT MANUALLY!');
+   out.push(` * ${context.regenCommand}`);
+   out.push(' ******************************************************************************/');
+   out.push('');
+   out.push('/* eslint-disable */');
+   out.push('');
+   out.push("import { makeAstNodeBuilder } from '@hydranium/core';");
+   out.push(`import { ${imported.join(', ')} } from '${context.importPath}';`);
+   out.push('');
+
+   // A single-grammar project has nothing to narrow to, so the merged binding is
+   // simply THE binding there and must not point at a sibling that was not emitted.
+   const narrowed = bindings.some(binding => binding.namespace !== undefined);
+   const guarantee = [
+      ' * Mandatory fields are a type error at the call site, and grammar-declared',
+      ' * containment arrays are materialised from reflection metadata, so a built',
+      ' * node carries `[]` where a cast literal would leave `undefined`.'
+   ];
+
+   for (const binding of bindings) {
+      out.push('/**');
+      if (binding.namespace !== undefined) {
+         out.push(` * AST-node factory narrowed to the '${binding.namespace}' grammar.`);
+         out.push(' *');
+         out.push(' * Narrowed by grammar REACHABILITY, not by ownership: a grammar that');
+         out.push(" * imports another sees that one's types too, so this binding is only as");
+         out.push(` * narrow as '${binding.namespace}'s import closure. Where that closure is the`);
+         out.push(' * whole project, it accepts exactly what the merged binding does and the');
+         out.push(' * choice is documentation rather than a check.');
+         out.push(' *');
+         out.push(...guarantee);
+      } else if (narrowed) {
+         out.push(' * AST-node factory spanning every grammar in this project.');
+         out.push(' *');
+         out.push(' * Prefer the narrowed binding matching the grammar the call site works in:');
+         out.push(" * it rejects a type outside that grammar's import closure, which this one");
+         out.push(' * accepts from anywhere. Reach for this one where a call site genuinely');
+         out.push(' * spans grammars.');
+      } else {
+         out.push(" * AST-node factory for this project's grammar.");
+         out.push(' *');
+         out.push(...guarantee);
+      }
+      out.push(' */');
+      out.push(`export const ${binding.exportName} = makeAstNodeBuilder<${binding.typeMap}>(${context.reflectionName});`);
+      out.push('');
+   }
+
+   return out.join('\n');
+}

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

@@ -29,6 +29,7 @@ export const GENERATE_TRANSFER_MODEL_FLAGS: readonly string[] = [
    '--ast-file',
    '--augmentation-file',
    '--out-file',
+   '--ast-builder-file',
    '--element-type-name',
    '--terminals-name',
    '--terminals-source-name',
@@ -48,7 +49,8 @@ export const GENERATE_TRANSFER_MODEL_VALUE_FLAGS: readonly string[] = GENERATE_T
 export const GENERATE_TRANSFER_MODEL_HELP: readonly string[] = [
    'Usage: hydranium-cli generate-transfer-model [options]',
    '',
-   'Generate a serializable transfer-model TypeScript file from a Langium AST. The',
+   'Generate a serializable transfer-model TypeScript file from a Langium AST, and',
+   'optionally an AST-node builder module bound to the same reflection. The',
    'required inputs (--ast-file / --augmentation-file / --out-file) may instead come',
    'from a --config JSON file, and --ast-file can be auto-discovered from a Langium',
    "config's `out` directory. Precedence, highest first: explicit flags, then the",
@@ -67,6 +69,11 @@ export const GENERATE_TRANSFER_MODEL_HELP: readonly string[] = [
    '                                directory: it treats that directory as exclusively',
    '                                its own, so every `langium generate` reports this',
    '                                file as unexpected and offers to delete it.',
+   '  --ast-builder-file <path>     Also emit an AST-node builder module here: one',
+   '                                makeAstNodeBuilder binding per grammar, plus one',
+   '                                spanning all of them. Omit if nothing constructs',
+   '                                AST nodes. Same restriction as --out-file: keep it',
+   "                                out of langium-cli's own `out` directory.",
    '  --element-type-name <name>    Base element type name in output. Default: TransferElement.',
    '  --terminals-name <name>       Terminals const name in output. Default: ModelTerminals.',
    '  --terminals-source-name <n>   Source-side terminals variable name. Default: <LanguageId>Terminals.',
@@ -120,6 +127,9 @@ export function parseGenerateOptions(args: string[], onError: UsageError = exitW
          case '--out-file':
             flags.outFile = next();
             break;
+         case '--ast-builder-file':
+            flags.astBuilderFile = next();
+            break;
          case '--element-type-name':
             flags.elementTypeName = next();
             break;

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

@@ -9,10 +9,11 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { describeError } from '@hydranium/protocol';
 import type { GenerateTransferModelOptions } from './generate-transfer-model.js';
 
 /** Path-valued option keys — resolved relative to a config/langium-config file's directory. */
-const PATH_KEYS = ['astFile', 'augmentationFile', 'outFile'] as const;
+const PATH_KEYS = ['astFile', 'augmentationFile', 'outFile', 'astBuilderFile'] as const;
 
 /** Resolve `value` against `baseDir` when it is relative; absolute paths pass through. */
 function resolveAgainst(baseDir: string, value: string): string {
@@ -31,7 +32,7 @@ export function loadTransferModelConfig(configPath: string): Partial<GenerateTra
    try {
       raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
    } catch (error: unknown) {
-      throw new Error(`Cannot read transfer-model config '${configPath}': ${error instanceof Error ? error.message : String(error)}`);
+      throw new Error(`Cannot read transfer-model config '${configPath}': ${describeError(error)}`);
    }
    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
       throw new Error(`Transfer-model config '${configPath}' must be a JSON object.`);
@@ -43,6 +44,7 @@ export function loadTransferModelConfig(configPath: string): Partial<GenerateTra
       'astFile',
       'augmentationFile',
       'outFile',
+      'astBuilderFile',
       'elementTypeName',
       'terminalsName',
       'terminalsSourceName',
@@ -74,7 +76,7 @@ export function deriveAstFileFromLangiumConfig(langiumConfigPath: string): strin
    try {
       raw = JSON.parse(fs.readFileSync(langiumConfigPath, 'utf-8'));
    } catch (error: unknown) {
-      throw new Error(`Cannot read langium-config '${langiumConfigPath}': ${error instanceof Error ? error.message : String(error)}`);
+      throw new Error(`Cannot read langium-config '${langiumConfigPath}': ${describeError(error)}`);
    }
    const out = (raw as { out?: unknown })?.out;
    if (typeof out !== 'string') {
@@ -118,6 +120,7 @@ export function mergeTransferModelOptions(...sources: Array<Partial<GenerateTran
       astFile: astFile!,
       augmentationFile: augmentationFile!,
       outFile: outFile!,
+      astBuilderFile: pick('astBuilderFile'),
       elementTypeName: pick('elementTypeName'),
       terminalsName: pick('terminalsName'),
       terminalsSourceName: pick('terminalsSourceName'),

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

@@ -9,6 +9,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import { emitAstBuilder } from './generate-ast-builder.js';
 import {
    type Node,
    type ObjectLiteralExpression,
@@ -18,6 +19,7 @@ import {
    type InterfaceDeclaration,
    type SourceFile
 } from 'ts-morph';
+import { describeError } from '@hydranium/protocol';
 
 /**
  * Options for the transfer-model generator.
@@ -35,6 +37,15 @@ export interface GenerateTransferModelOptions {
    augmentationFile: string;
    /** Destination path for the generated transfer model. */
    outFile: string;
+   /**
+    * Destination for a generated AST-node builder module. Omitted by consumers
+    * that construct no AST nodes; the transfer model is emitted either way.
+    *
+    * Emitted from this command rather than its own because the AST source is
+    * already parsed here, and because a consumer that regenerates one artefact
+    * and not the other has the two disagreeing about the same grammar.
+    */
+   astBuilderFile?: string;
    /** Name used for the base element type in the output. Defaults to `TransferElement`. */
    elementTypeName?: string;
    /** Name used for the terminal-patterns const in the output. Defaults to `ModelTerminals`. */
@@ -99,7 +110,7 @@ export function watchTransferModel(options: GenerateTransferModelOptions, contex
       try {
          generateTransferModel(options);
       } catch (error: unknown) {
-         console.error(`Transfer-model generation failed: ${error instanceof Error ? error.message : String(error)}`);
+         console.error(`Transfer-model generation failed: ${describeError(error)}`);
       }
    };
    runSafely();
@@ -396,10 +407,22 @@ export function generateTransferModel(options: GenerateTransferModelOptions): vo
    fs.mkdirSync(path.dirname(options.outFile), { recursive: true });
    if (fs.existsSync(options.outFile) && fs.readFileSync(options.outFile, 'utf-8') === content) {
       console.log('Transfer model is up to date.');
-      return;
+   } else {
+      fs.writeFileSync(options.outFile, content, 'utf-8');
+      console.log(`Generated: ${options.outFile}`);
+   }
+
+   if (options.astBuilderFile !== undefined) {
+      const emitted = emitAstBuilder(astSource, {
+         outFile: options.astBuilderFile,
+         astFile: options.astFile,
+         languageId,
+         regenCommand
+      });
+      if (!emitted) {
+         console.warn(`Warning: no '${languageId}AstType' alias in ${options.astFile}; skipping the AST builder.`);
+      }
    }
-   fs.writeFileSync(options.outFile, content, 'utf-8');
-   console.log(`Generated: ${options.outFile}`);
 }
 
 // ---------------------------------------------------------------------------

package/src/commands/harness-args.ts

@@ -31,11 +31,12 @@
  * parser rejects is an invocation that fails for no visible reason.
  */
 
-import type { LogThreshold } from '@hydranium/protocol';
+import { describeError, type LogThreshold } from '@hydranium/protocol';
 import { statSync } from 'node:fs';
+import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { parseLogLevelOption } from '../log-level.js';
+import { type LogOptions, parseLogLevelOption } from '../log-level.js';
 
 /**
  * How a parser reports a usage problem. It never returns, so a parser can treat
@@ -56,9 +57,18 @@ export function exitWithUsage(message: string): never {
    process.exit(2);
 }
 
-/** The value flag {@link parseHarnessArgs} consumes itself, before any the subcommand declares. */
+/** Names the head's services module; every harness subcommand requires it. */
 export const SERVICES_FLAG = '--services';
 
+/**
+ * Registers a loader in the driver child that imports the head. The child is a
+ * fresh `node`, so a loader registered on the CLI's own process never reaches it.
+ */
+export const IMPORT_FLAG = '--import';
+
+/** The value flags {@link parseHarnessArgs} consumes itself, before any the subcommand declares. */
+export const HARNESS_VALUE_FLAGS = [SERVICES_FLAG, IMPORT_FLAG] as const;
+
 /**
  * The one spelling of the log threshold, shared by both subcommand families.
  *
@@ -68,33 +78,64 @@ export const SERVICES_FLAG = '--services';
  * on which command a caller happened to reach for.
  */
 export const LOG_LEVEL_FLAG = '--log-level';
+export const LOG_FILE_FLAG = '--log-file';
+export const LOG_FILE_LEVEL_FLAG = '--log-file-level';
+
+/** The log flags every subcommand takes, read by {@link logOptions}. */
+export const LOG_VALUE_FLAGS = [LOG_LEVEL_FLAG, LOG_FILE_FLAG, LOG_FILE_LEVEL_FLAG] as const;
 
 /** The value flags {@link parseServerSpawnOptions} consumes itself. */
-export const SERVER_SPAWN_VALUE_FLAGS: readonly string[] = ['--server', '--cwd', LOG_LEVEL_FLAG];
+export const SERVER_SPAWN_VALUE_FLAGS: readonly string[] = ['--server', '--cwd', ...LOG_VALUE_FLAGS];
 
 /**
- * The `--help` line every subcommand describes {@link LOG_LEVEL_FLAG} with.
+ * The `--help` lines every subcommand describes {@link LOG_VALUE_FLAGS} with.
  *
  * Shared text, per-command padding: `command-args.test.ts` compares the flags a
  * help block DESCRIBES against the flags the parser accepts, and it recognises a
- * description by the two-space indent — so the line has to be a real option entry
+ * description by the two-space indent — so each line has to be a real option entry
  * in each block, and the column each block aligns its descriptions at is the
- * block's own.
+ * block's own. A flag too wide for that column takes its description on the
+ * next line, at the column.
  */
-export function logLevelHelpLine(padTo: number): string {
-   return `  ${`${LOG_LEVEL_FLAG} <lvl>`.padEnd(padTo)}Log threshold for the head this boots (off|error|warn|info|debug|trace).`;
+export function logHelpLines(padTo: number, head = 'the head this boots'): string[] {
+   return [
+      helpLine(`${LOG_LEVEL_FLAG} <lvl>`, `Log threshold for ${head} (off|error|warn|info|debug|trace).`, padTo),
+      helpLine(`${LOG_FILE_FLAG} <file>`, `Also write ${head}'s log to <file>; {workspace} expands to the workspace.`, padTo),
+      helpLine(`${LOG_FILE_LEVEL_FLAG} <lvl>`, `Threshold for that file, which the log-level setting does not change.`, padTo)
+   ].flat();
+}
+
+/** The `--help` lines every `--services` subcommand describes {@link IMPORT_FLAG} with, aligned as {@link logHelpLines}. */
+export function importHelpLines(padTo: number): string[] {
+   return helpLine(`${IMPORT_FLAG} <specifier>`, 'Loader to register before importing <module>, e.g. tsx (repeatable).', padTo);
+}
+
+function helpLine(flag: string, text: string, padTo: number): string[] {
+   return flag.length < padTo - 1 ? [`  ${flag.padEnd(padTo)}${text}`] : [`  ${flag}`, `${' '.repeat(padTo + 2)}${text}`];
 }
 
 /**
- * Narrow a raw {@link LOG_LEVEL_FLAG} value that {@link parseHarnessArgs}
- * collected, leaving an absent flag absent.
+ * Narrow the raw {@link LOG_VALUE_FLAGS} values a parser collected, leaving
+ * absent flags absent.
+ *
+ * `--log-file` resolves against the caller's directory: the child may run
+ * elsewhere (`--cwd`), and a relative path would land the log there.
  *
  * Throws rather than reaching `onError`, matching {@link parseServerSpawnOptions}:
  * the level vocabulary belongs to the protocol package, which reports it, and the
  * entry point's catch turns that into the same message-and-exit.
  */
-export function logLevelOption(value: string | undefined): LogThreshold | undefined {
-   return value === undefined ? undefined : parseLogLevelOption(value);
+export function logOptions(options: Readonly<Record<string, string | undefined>>): LogOptions {
+   const level = (flag: string): LogThreshold | undefined => {
+      const value = options[flag];
+      return value === undefined ? undefined : parseLogLevelOption(value, flag);
+   };
+   const logFile = options[LOG_FILE_FLAG];
+   return {
+      logLevel: level(LOG_LEVEL_FLAG),
+      logFile: logFile === undefined ? undefined : path.resolve(logFile),
+      logFileLevel: level(LOG_FILE_LEVEL_FLAG)
+   };
 }
 
 /**
@@ -134,6 +175,8 @@ export function printHelp(lines: readonly string[]): void {
 /** What {@link parseHarnessArgs} recovered from an argv. */
 export interface ParsedHarnessArgs {
    servicesModule: string;
+   /** The {@link IMPORT_FLAG} values in the order given, absent when there were none. */
+   imports?: string[];
    /**
     * An absolute directory path, resolved by {@link resolveWorkspaceArgument} and
     * checked to exist. `''` when the subcommand declared `requireWorkspace: false`.
@@ -163,12 +206,12 @@ export interface HarnessArgsConfig {
 
 /**
  * Shared parser for the headless-harness subcommands. Consumes the required
- * `--services <module>` value flag and a single positional `<workspace>`, plus
- * the `valueFlags` (each takes a value) and `boolFlags` (presence-only, recorded
- * as `'true'`) the subcommand recognises. Unknown flags or a missing
- * `--services`/`<workspace>` are usage errors, and so is a `<workspace>` that
- * reaches no directory — see {@link resolveWorkspaceArgument} for why that cannot
- * be left to the run.
+ * `--services <module>` value flag, the repeatable `--import <specifier>` and a
+ * single positional `<workspace>`, plus the `valueFlags` (each takes a value)
+ * and `boolFlags` (presence-only, recorded as `'true'`) the subcommand
+ * recognises. Unknown flags or a missing `--services`/`<workspace>` are usage
+ * errors, and so is a `<workspace>` that reaches no directory — see
+ * {@link resolveWorkspaceArgument} for why that cannot be left to the run.
  */
 export function parseHarnessArgs(
    args: string[],
@@ -185,6 +228,7 @@ export function parseHarnessArgs(
    const options: Record<string, string | undefined> = {};
    const values: Record<string, string[]> = {};
    let servicesModule: string | undefined;
+   let imports: string[] | undefined;
    let workspace: string | undefined;
    for (let index = 0; index < args.length; index += 1) {
       const flag = args[index];
@@ -196,8 +240,10 @@ export function parseHarnessArgs(
          index += 1;
          return value;
       };
-      if (flag === '--services') {
+      if (flag === SERVICES_FLAG) {
          servicesModule = next();
+      } else if (flag === IMPORT_FLAG) {
+         (imports ??= []).push(next());
       } else if (boolSet.has(flag)) {
          options[flag] = 'true';
       } else if (repeatableSet.has(flag)) {
@@ -213,7 +259,8 @@ export function parseHarnessArgs(
       }
    }
    return {
-      servicesModule: assertRequired(servicesModule, '--services', commandName, onError),
+      servicesModule: assertRequired(servicesModule, SERVICES_FLAG, commandName, onError),
+      imports,
       workspace: requireWorkspace
          ? resolveWorkspaceArgument(assertRequired(workspace, '<workspace>', commandName, onError), commandName, onError)
          : (workspace ?? ''),
@@ -257,7 +304,7 @@ export function resolveWorkspaceArgument(workspace: string, commandName: string,
    try {
       stats = statSync(resolved, { throwIfNoEntry: false });
    } catch (err: unknown) {
-      const detail = err instanceof Error ? err.message : String(err);
+      const detail = describeError(err);
       onError(`<workspace> is not reachable: '${workspace}' resolved to ${resolved} (${detail}) ${help}`);
    }
    if (stats === undefined) {
@@ -276,7 +323,7 @@ function toWorkspacePath(workspace: string, commandName: string, onError: UsageE
    try {
       return fileURLToPath(workspace);
    } catch (err: unknown) {
-      const detail = err instanceof Error ? err.message : String(err);
+      const detail = describeError(err);
       onError(`<workspace> is not a usable file URI: '${workspace}' (${detail}) (hydranium-cli ${commandName} --help)`);
    }
 }
@@ -336,11 +383,10 @@ function kebabToCamel(name: string): string {
 }
 
 /** What {@link parseServerSpawnOptions} recovered from an argv. */
-export interface SpawnOptions {
+export interface SpawnOptions extends LogOptions {
    serverCommand: string;
    serverArgs: string[];
    cwd?: string;
-   logLevel?: LogThreshold;
    /** The tokens this parser did not claim, for the subcommand's own options. */
    extra: string[];
 }
@@ -363,10 +409,10 @@ function isRelativePathToken(token: string, isCommand: boolean): boolean {
 
 /**
  * Shared option parser for subcommands that spawn a data-server child. Consumes
- * `--server` / `--cwd` / `--log-level` and returns the surviving tokens as
+ * `--server` / `--cwd` / the {@link LOG_VALUE_FLAGS} and returns the surviving tokens as
  * `extra` for {@link parseFlagOptions} to finish.
  *
- * An unrecognised `--log-level` value throws rather than reaching `onError`: the
+ * An unrecognised log level value throws rather than reaching `onError`: the
  * level vocabulary belongs to the protocol package, which reports it, and the
  * entry point's catch turns that into the same message-and-exit.
  *
@@ -383,7 +429,7 @@ function isRelativePathToken(token: string, isCommand: boolean): boolean {
 export function parseServerSpawnOptions(args: string[], commandName: string, onError: UsageError = exitWithUsage): SpawnOptions {
    let serverSpec: string | undefined;
    let cwd: string | undefined;
-   let logLevel: LogThreshold | undefined;
+   const logFlags: Record<string, string> = {};
    const extra: string[] = [];
    for (let index = 0; index < args.length; index += 1) {
       const flag = args[index];
@@ -399,8 +445,8 @@ export function parseServerSpawnOptions(args: string[], commandName: string, onE
          serverSpec = claim();
       } else if (flag === '--cwd') {
          cwd = claim();
-      } else if (flag === LOG_LEVEL_FLAG) {
-         logLevel = parseLogLevelOption(claim());
+      } else if ((LOG_VALUE_FLAGS as readonly string[]).includes(flag)) {
+         logFlags[flag] = claim();
       } else {
          extra.push(flag);
       }
@@ -425,5 +471,23 @@ export function parseServerSpawnOptions(args: string[], commandName: string, onE
          );
       }
    }
-   return { serverCommand, serverArgs, cwd, logLevel, extra };
+   return { serverCommand, serverArgs, cwd, ...logOptions(logFlags), extra };
+}
+
+/**
+ * Resolve the `--content` argument to its textual form. The `@<path>`
+ * prefix reads from a file (parses as UTF-8); anything else is taken
+ * literally. The leading `@` can be escaped as `\@` for content that
+ * legitimately starts with `@`.
+ */
+export async function resolveContent(content: string, readFile?: (path: string) => Promise<string>): Promise<string> {
+   if (content.startsWith('@')) {
+      const file = content.slice(1);
+      const reader = readFile ?? ((target: string) => fs.readFile(target, 'utf8'));
+      return reader(file);
+   }
+   if (content.startsWith('\\@')) {
+      return content.slice(1);
+   }
+   return content;
 }