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

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

@@ -10,32 +10,34 @@
 import { runAstGroundTruth, type AstGroundTruthCommandOptions } from './ast-ground-truth.js';
 import {
    exitWithUsage,
+   HARNESS_VALUE_FLAGS,
    helpRequested,
-   LOG_LEVEL_FLAG,
-   logLevelHelpLine,
-   logLevelOption,
+   importHelpLines,
+   LOG_VALUE_FLAGS,
+   logHelpLines,
+   logOptions,
    parseHarnessArgs,
    printHelp,
-   SERVICES_FLAG,
    type UsageError
 } from './harness-args.js';
 import { OUT_FILE_FLAG } from './headless-harness.js';
 
-const VALUE_FLAGS = [OUT_FILE_FLAG, LOG_LEVEL_FLAG] as const;
+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>]',
+   '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.',
-   logLevelHelpLine(22)
+   ...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], logLevel: logLevelOption(options[LOG_LEVEL_FLAG]) };
+   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/ast-ground-truth-driver.ts

@@ -16,6 +16,7 @@
  */
 
 import * as fs from 'node:fs';
+import { describeError } from '@hydranium/protocol';
 import { loadHeadlessContext, OUT_FILE_FLAG } from './headless-harness.js';
 
 interface DriverArgs {
@@ -76,6 +77,6 @@ async function main(argv: string[]): Promise<void> {
 main(process.argv.slice(2))
    .then(() => process.exit(0))
    .catch((error: unknown) => {
-      console.error(error instanceof Error ? error.message : String(error));
+      console.error(describeError(error));
       process.exit(1);
    });

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

@@ -45,5 +45,5 @@ export function buildGroundTruthDriverArgs(options: AstGroundTruthCommandOptions
  * `--out-file`). No `--expose-gc` needed — this walks the AST, it does not weigh it.
  */
 export function runAstGroundTruth(options: AstGroundTruthCommandOptions): Promise<void> {
-   return runDriverChild(['--max-old-space-size=8192', DRIVER, ...buildGroundTruthDriverArgs(options)], options);
+   return runDriverChild([DRIVER, ...buildGroundTruthDriverArgs(options)], options);
 }

package/src/commands/client-session.ts

@@ -0,0 +1,33 @@
+/********************************************************************************
+ * 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 type { TransferElement } from '@hydranium/protocol';
+import type { DataServerProtocol } from '@hydranium/protocol/data';
+
+/**
+ * Run `fn` as the client session `clientId`, and end the session whether `fn`
+ * succeeded or not, which closes whatever it left open. An end that fails
+ * after a failed `fn` is swallowed: `fn`'s error is the one the user needs.
+ */
+export async function withClientSession<T>(
+   server: Pick<DataServerProtocol<TransferElement>, 'createSession' | 'closeSession'>,
+   clientId: string,
+   fn: () => Promise<T>
+): Promise<T> {
+   await server.createSession({ clientId, label: 'hydranium-cli' });
+   let result: T;
+   try {
+      result = await fn();
+   } catch (error: unknown) {
+      await server.closeSession({ clientId }).catch(() => undefined);
+      throw error;
+   }
+   await server.closeSession({ clientId });
+   return result;
+}

package/src/commands/create-args.ts

@@ -0,0 +1,68 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 {
+   assertRequired,
+   exitWithUsage,
+   helpRequested,
+   logHelpLines,
+   parseFlagOptions,
+   parseServerSpawnOptions,
+   printHelp,
+   SERVER_SPAWN_VALUE_FLAGS,
+   type UsageError
+} from './harness-args.js';
+import { type CreateCommandOptions, runCreate } from './create.js';
+
+const OWN_FLAGS = ['--uri', '--content', '--client-id'] as const;
+
+/** Every flag `create` accepts, each of which takes a value. */
+export const CREATE_FLAGS: readonly string[] = [...SERVER_SPAWN_VALUE_FLAGS, ...OWN_FLAGS];
+
+/** The `--help` text, as data, held to {@link CREATE_FLAGS} by a test. */
+export const CREATE_HELP: readonly string[] = [
+   'Usage: hydranium-cli create --server "<cmd>..." --uri <uri> --content <text|@file> [--client-id <id>] [--cwd <dir>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
+   '',
+   'Create the document at `<uri>` with `<content>` via createModelDocument, and persist it',
+   'as given. Fails when the file exists or a client has it open.',
+   'Output is the post-save envelope as a single JSON line.',
+   '',
+   'Options:',
+   '  --server "<cmd>"      Command-line for the data-server subprocess (required).',
+   '  --uri <uri>           Document URI (required).',
+   '  --content <text>      Content to write (required). Prefix `@` to read from a file',
+   '                        (escape with `\\@` for literal `@`-leading content).',
+   '  --client-id <id>      clientId for authorship attribution. Default: hydranium-cli.',
+   '  --cwd <dir>           Working directory for the spawned child. Default: cwd.',
+   ...logHelpLines(22, 'the spawned server')
+];
+
+export function parseCreateArgs(args: string[], onError: UsageError = exitWithUsage): CreateCommandOptions {
+   const { serverCommand, serverArgs, cwd, logLevel, logFile, logFileLevel, extra } = parseServerSpawnOptions(args, 'create', onError);
+   const { uri, content, clientId } = parseFlagOptions(extra, 'create', OWN_FLAGS, onError);
+   return {
+      serverCommand,
+      serverArgs,
+      cwd,
+      logLevel,
+      logFile,
+      logFileLevel,
+      uri: assertRequired(uri, '--uri', 'create', onError),
+      content: assertRequired(content, '--content', 'create', onError),
+      clientId
+   };
+}
+
+export function runCreateCommand(args: string[]): Promise<void> {
+   if (helpRequested(args, CREATE_FLAGS)) {
+      printHelp(CREATE_HELP);
+      return Promise.resolve();
+   }
+   return runCreate(parseCreateArgs(args));
+}

package/src/commands/create.ts

@@ -0,0 +1,83 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 type { TransferElement } from '@hydranium/protocol';
+import type { DataServerProtocol } from '@hydranium/protocol/data';
+import { logEnv, type LogOptions } from '../log-level.js';
+import { withDataServer } from '../spawn-data-server.js';
+import { withClientSession } from './client-session.js';
+import { resolveContent } from './harness-args.js';
+
+/**
+ * Options for the {@link runCreate} subcommand. Creates the document at `uri`
+ * with `content` (literal text or `@<path>` for a file reference) via the
+ * data-server's `createModelDocument` RPC, and persists that text as it is.
+ * Fails when the file exists or a client has it open. Writes the post-save
+ * envelope as a single JSON line, as `save` does.
+ *
+ * `clientId` defaults to `'hydranium-cli'`. The command creates as a client
+ * session under it: it registers the session, creates the document, persists
+ * it, since a created document reaches disk only with a save, and ends the
+ * session.
+ */
+export interface CreateCommandOptions extends LogOptions {
+   readonly serverCommand: string;
+   readonly serverArgs?: readonly string[];
+   readonly cwd?: string;
+   readonly uri: string;
+   /** Literal content text, or `@<path>` to read from a file. */
+   readonly content: string;
+   readonly clientId?: string;
+   readonly write?: (line: string) => void;
+   readonly __proxyForTest?: DataServerProtocol<TransferElement>;
+   /** Test-only: override the file-reader so unit tests can stub `@<path>` expansion. */
+   readonly __readFileForTest?: (path: string) => Promise<string>;
+}
+
+export async function runCreate(options: CreateCommandOptions): Promise<void> {
+   const write = options.write ?? ((line: string) => process.stdout.write(line));
+   const clientId = options.clientId ?? 'hydranium-cli';
+   const text = await resolveContent(options.content, options.__readFileForTest);
+
+   if (options.__proxyForTest) {
+      write(`${JSON.stringify(await createPersisted(options.__proxyForTest, options.uri, clientId, text))}\n`);
+      return;
+   }
+
+   await withDataServer(
+      {
+         command: options.serverCommand,
+         args: options.serverArgs,
+         cwd: options.cwd,
+         env: logEnv(options)
+      },
+      async server => {
+         write(`${JSON.stringify(await createPersisted(server, options.uri, clientId, text))}\n`);
+      }
+   );
+}
+
+/**
+ * Create `uri` with `text` as the session `clientId` and persist it, then end
+ * the session. The persist is gated on the version the create made, so a
+ * write that landed before the create's answer or after it, another client's
+ * or an integrity repair, fails the command with a conflict and nothing
+ * persists.
+ */
+function createPersisted(
+   server: Pick<DataServerProtocol<TransferElement>, 'createSession' | 'createModelDocument' | 'persistModelDocument' | 'closeSession'>,
+   uri: string,
+   clientId: string,
+   text: string
+): Promise<unknown> {
+   return withClientSession(server, clientId, async () => {
+      const created = await server.createModelDocument({ uri, clientId, text });
+      return server.persistModelDocument({ uri, clientId, baseVersion: created.created.version });
+   });
+}

package/src/commands/delete-args.ts

@@ -0,0 +1,64 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 {
+   assertRequired,
+   exitWithUsage,
+   helpRequested,
+   logHelpLines,
+   parseFlagOptions,
+   parseServerSpawnOptions,
+   printHelp,
+   SERVER_SPAWN_VALUE_FLAGS,
+   type UsageError
+} from './harness-args.js';
+import { type DeleteCommandOptions, runDelete } from './delete.js';
+
+const OWN_FLAGS = ['--uri', '--client-id'] as const;
+
+/** Every flag `delete` accepts, each of which takes a value. */
+export const DELETE_FLAGS: readonly string[] = [...SERVER_SPAWN_VALUE_FLAGS, ...OWN_FLAGS];
+
+/** The `--help` text, as data, held to {@link DELETE_FLAGS} by a test. */
+export const DELETE_HELP: readonly string[] = [
+   'Usage: hydranium-cli delete --server "<cmd>..." --uri <uri> [--client-id <id>] [--cwd <dir>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
+   '',
+   'Delete the document at `<uri>`, its file and then the document, via deleteModelDocument,',
+   'whatever text it holds. Prints nothing.',
+   '',
+   'Options:',
+   '  --server "<cmd>"      Command-line for the data-server subprocess (required).',
+   '  --uri <uri>           Document URI (required).',
+   '  --client-id <id>      clientId the deletion is attributed to. Default: hydranium-cli.',
+   '  --cwd <dir>           Working directory for the spawned child. Default: cwd.',
+   ...logHelpLines(22, 'the spawned server')
+];
+
+export function parseDeleteArgs(args: string[], onError: UsageError = exitWithUsage): DeleteCommandOptions {
+   const { serverCommand, serverArgs, cwd, logLevel, logFile, logFileLevel, extra } = parseServerSpawnOptions(args, 'delete', onError);
+   const { uri, clientId } = parseFlagOptions(extra, 'delete', OWN_FLAGS, onError);
+   return {
+      serverCommand,
+      serverArgs,
+      cwd,
+      logLevel,
+      logFile,
+      logFileLevel,
+      uri: assertRequired(uri, '--uri', 'delete', onError),
+      clientId
+   };
+}
+
+export function runDeleteCommand(args: string[]): Promise<void> {
+   if (helpRequested(args, DELETE_FLAGS)) {
+      printHelp(DELETE_HELP);
+      return Promise.resolve();
+   }
+   return runDelete(parseDeleteArgs(args));
+}

package/src/commands/delete.ts

@@ -0,0 +1,61 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 type { TransferElement } from '@hydranium/protocol';
+import type { DataServerProtocol } from '@hydranium/protocol/data';
+import { logEnv, type LogOptions } from '../log-level.js';
+import { withDataServer } from '../spawn-data-server.js';
+import { withClientSession } from './client-session.js';
+
+/**
+ * Options for the {@link runDelete} subcommand. Deletes the document at `uri`,
+ * its file and then the document, via the data-server's `deleteModelDocument`
+ * RPC, whatever text it holds. Prints nothing; a failed delete rejects.
+ *
+ * `clientId` defaults to `'hydranium-cli'`. The command deletes as a client
+ * session under it: it registers the session, opens the document, deletes it,
+ * and ends the session.
+ */
+export interface DeleteCommandOptions extends LogOptions {
+   readonly serverCommand: string;
+   readonly serverArgs?: readonly string[];
+   readonly cwd?: string;
+   readonly uri: string;
+   readonly clientId?: string;
+   readonly __proxyForTest?: DataServerProtocol<TransferElement>;
+}
+
+export async function runDelete(options: DeleteCommandOptions): Promise<void> {
+   const clientId = options.clientId ?? 'hydranium-cli';
+   if (options.__proxyForTest) {
+      await deleteOpened(options.__proxyForTest, options.uri, clientId);
+      return;
+   }
+   await withDataServer(
+      {
+         command: options.serverCommand,
+         args: options.serverArgs,
+         cwd: options.cwd,
+         env: logEnv(options)
+      },
+      server => deleteOpened(server, options.uri, clientId)
+   );
+}
+
+/** Open `uri` as the session `clientId` and delete it, then end the session. */
+function deleteOpened(
+   server: Pick<DataServerProtocol<TransferElement>, 'createSession' | 'openModelDocument' | 'deleteModelDocument' | 'closeSession'>,
+   uri: string,
+   clientId: string
+): Promise<void> {
+   return withClientSession(server, clientId, async () => {
+      await server.openModelDocument({ uri, clientId });
+      await server.deleteModelDocument({ uri, clientId, baseVersion: 'any' });
+   });
+}

package/src/commands/generate-languages.ts

@@ -0,0 +1,132 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 { kebab } from './kebab.js';
+import { type Expression, type ObjectLiteralExpression, type SourceFile, SyntaxKind } from 'ts-morph';
+
+/** Inputs for {@link emitLanguages}, resolved by the transfer-model command. */
+export interface EmitLanguagesOptions {
+   /** Destination path for the generated languages module. */
+   outFile: string;
+   /** Header line naming the command that regenerates the file. */
+   regenCommand: string;
+}
+
+interface LanguageEntry {
+   constName: string;
+   languageId: string;
+   fileExtensions: string[];
+}
+
+/** Suffix langium-cli gives each grammar's metadata const in `module.ts`. */
+const METADATA_SUFFIX = 'LanguageMetaData';
+
+/**
+ * Emit a module stating each grammar's language id and file extensions for a
+ * package a client can depend on.
+ *
+ * Read from the `<Grammar>LanguageMetaData` consts langium-cli writes into
+ * `module.ts`, which is the only place the ids exist outside `langium-config.json`
+ * and which a client cannot import, since it pulls in Langium. Generating the
+ * copy instead of writing it by hand is what keeps every host's id list in step
+ * with the grammars.
+ */
+export function emitLanguages(moduleSource: SourceFile, options: EmitLanguagesOptions): void {
+   const content = buildLanguagesSource(moduleSource, options);
+   fs.mkdirSync(path.dirname(options.outFile), { recursive: true });
+   if (fs.existsSync(options.outFile) && fs.readFileSync(options.outFile, 'utf-8') === content) {
+      console.log('Languages module is up to date.');
+      return;
+   }
+   fs.writeFileSync(options.outFile, content, 'utf-8');
+   console.log(`Generated: ${options.outFile}`);
+}
+
+/**
+ * The module text {@link emitLanguages} would write. Pure over its inputs, so
+ * the emitted shape is testable without touching a filesystem. Throws when the
+ * source declares no metadata, since an empty list would make every host
+ * register nothing without an error.
+ */
+export function buildLanguagesSource(moduleSource: SourceFile, options: Pick<EmitLanguagesOptions, 'regenCommand'>): string {
+   const entries: LanguageEntry[] = [];
+   const grammarsByConst = new Map<string, string>();
+   for (const declaration of moduleSource.getVariableDeclarations()) {
+      const name = declaration.getName();
+      if (!name.endsWith(METADATA_SUFFIX)) {
+         continue;
+      }
+      const literal = objectLiteralOf(declaration.getInitializer());
+      const grammar = name.slice(0, -METADATA_SUFFIX.length);
+      const constName = `${kebab(grammar).replace(/-/g, '_').toUpperCase()}_LANGUAGE`;
+      const clash = grammarsByConst.get(constName);
+      if (clash !== undefined) {
+         throw new Error(
+            `Cannot emit the languages module: grammars '${clash}' and '${grammar}' both map to '${constName}'. ` +
+               'Rename one grammar so the generated constants stay distinct.'
+         );
+      }
+      grammarsByConst.set(constName, grammar);
+      entries.push({
+         constName,
+         languageId: stringProperty(literal, name, 'languageId'),
+         fileExtensions: stringArrayProperty(literal, name, 'fileExtensions')
+      });
+   }
+   if (entries.length === 0) {
+      throw new Error(`Cannot emit the languages module: ${moduleSource.getFilePath()} declares no '<Grammar>${METADATA_SUFFIX}'.`);
+   }
+
+   const out: string[] = [];
+   out.push('/******************************************************************************');
+   out.push(' * Generated from the Langium language metadata — DO NOT EDIT MANUALLY!');
+   out.push(` * ${options.regenCommand}`);
+   out.push(' ******************************************************************************/');
+   out.push('');
+   for (const entry of entries) {
+      const extensions = entry.fileExtensions.map(extension => JSON.stringify(extension)).join(', ');
+      out.push(
+         `export const ${entry.constName} = { languageId: ${JSON.stringify(entry.languageId)}, fileExtensions: [${extensions}] } as const;`
+      );
+   }
+   out.push('');
+   out.push('/** Every language of the project, in the order langium-cli declares them. */');
+   out.push(`export const ALL_LANGUAGES = [${entries.map(entry => entry.constName).join(', ')}] as const;`);
+   return out.join('\n') + '\n';
+}
+
+/** The object literal under `as const` / `satisfies` wrappers, which langium-cli adds. */
+function objectLiteralOf(initializer: Expression | undefined): ObjectLiteralExpression | undefined {
+   return (
+      initializer?.asKind(SyntaxKind.ObjectLiteralExpression) ?? initializer?.getFirstDescendantByKind(SyntaxKind.ObjectLiteralExpression)
+   );
+}
+
+function stringProperty(literal: ObjectLiteralExpression | undefined, owner: string, key: string): string {
+   const value = literal?.getProperty(key)?.asKind(SyntaxKind.PropertyAssignment)?.getInitializer()?.asKind(SyntaxKind.StringLiteral);
+   if (value === undefined) {
+      throw new Error(`Cannot emit the languages module: ${owner} has no string '${key}'.`);
+   }
+   return value.getLiteralValue();
+}
+
+function stringArrayProperty(literal: ObjectLiteralExpression | undefined, owner: string, key: string): string[] {
+   const array = literal
+      ?.getProperty(key)
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer()
+      ?.asKind(SyntaxKind.ArrayLiteralExpression);
+   const values = array?.getElements().map(element => element.asKind(SyntaxKind.StringLiteral)?.getLiteralValue());
+   if (values === undefined || !values.every((value): value is string => value !== undefined)) {
+      throw new Error(`Cannot emit the languages module: ${owner} has no string array '${key}'.`);
+   }
+   return values;
+}

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

@@ -30,6 +30,7 @@ export const GENERATE_TRANSFER_MODEL_FLAGS: readonly string[] = [
    '--augmentation-file',
    '--out-file',
    '--ast-builder-file',
+   '--languages-file',
    '--element-type-name',
    '--terminals-name',
    '--terminals-source-name',
@@ -74,6 +75,9 @@ export const GENERATE_TRANSFER_MODEL_HELP: readonly string[] = [
    '                                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.",
+   "  --languages-file <path>       Also emit each grammar's language id and file",
+   '                                extensions here, read from the module.ts beside',
+   '                                --ast-file, for a package without Langium.',
    '  --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.',
@@ -130,6 +134,9 @@ export function parseGenerateOptions(args: string[], onError: UsageError = exitW
          case '--ast-builder-file':
             flags.astBuilderFile = next();
             break;
+         case '--languages-file':
+            flags.languagesFile = 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', 'astBuilderFile'] as const;
+const PATH_KEYS = ['astFile', 'augmentationFile', 'outFile', 'astBuilderFile', 'languagesFile'] 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.`);
@@ -44,6 +45,7 @@ export function loadTransferModelConfig(configPath: string): Partial<GenerateTra
       'augmentationFile',
       'outFile',
       'astBuilderFile',
+      'languagesFile',
       'elementTypeName',
       'terminalsName',
       'terminalsSourceName',
@@ -75,7 +77,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') {
@@ -120,6 +122,7 @@ export function mergeTransferModelOptions(...sources: Array<Partial<GenerateTran
       augmentationFile: augmentationFile!,
       outFile: outFile!,
       astBuilderFile: pick('astBuilderFile'),
+      languagesFile: pick('languagesFile'),
       elementTypeName: pick('elementTypeName'),
       terminalsName: pick('terminalsName'),
       terminalsSourceName: pick('terminalsSourceName'),