@hydranium/cli 1.0.0-next.4 → 1.0.0-next.400

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-ast-builder.ts

@@ -0,0 +1,236 @@
+/********************************************************************************
+ * 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';
+import { relativeImportPath } from './generated-module-path.js';
+
+/** 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';
+}
+
+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-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-builder.ts

@@ -0,0 +1,101 @@
+/********************************************************************************
+ * 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 { describeError } from '@hydranium/protocol';
+import { relativeImportPath } from './generated-module-path.js';
+
+/** Inputs for {@link emitTransferBuilder}, resolved by the transfer-model command. */
+export interface EmitTransferBuilderOptions {
+   /** Destination path for the generated builder module. */
+   outFile: string;
+   /** Path of the generated transfer model the builder binds to. */
+   transferModelFile: string;
+   /** Language id derived from the `<LanguageId>AstReflection` class name. */
+   languageId: string;
+   /** Header line naming the command that regenerates the file. */
+   regenCommand: string;
+}
+
+/**
+ * Emit a test module binding `makeTransferNodeBuilder` to the transfer model's
+ * reflection and type map, as `transferNode`.
+ *
+ * The module usually sits in a test tree of the server package while the
+ * transfer model sits in a protocol package of its own, and a relative import
+ * would reach into that package's sources. Across packages it therefore imports
+ * the model by the package's name, which relies on the package's main entry
+ * re-exporting the generated model; within one package it imports by path.
+ */
+export function emitTransferBuilder(options: EmitTransferBuilderOptions): void {
+   const content = buildTransferBuilderSource(options);
+   fs.mkdirSync(path.dirname(options.outFile), { recursive: true });
+   if (fs.existsSync(options.outFile) && fs.readFileSync(options.outFile, 'utf-8') === content) {
+      console.log('Transfer builder is up to date.');
+      return;
+   }
+   fs.writeFileSync(options.outFile, content, 'utf-8');
+   console.log(`Generated: ${options.outFile}`);
+}
+
+/** The module text {@link emitTransferBuilder} would write. */
+export function buildTransferBuilderSource(options: EmitTransferBuilderOptions): string {
+   const modelPackage = owningPackage(options.transferModelFile);
+   const specifier =
+      modelPackage !== undefined && modelPackage.dir !== owningPackage(options.outFile)?.dir
+         ? modelPackage.name
+         : relativeImportPath(options.outFile, options.transferModelFile);
+   const reflection = `${options.languageId}TransferReflection`;
+   const typeMap = `${options.languageId}TransferTypes`;
+   return [
+      '/******************************************************************************',
+      ' * Generated from the Langium AST — DO NOT EDIT MANUALLY!',
+      ` * ${options.regenCommand}`,
+      ' ******************************************************************************/',
+      '',
+      '/* eslint-disable */',
+      '',
+      "import { makeTransferNodeBuilder } from '@hydranium/protocol/testing';",
+      `import { ${reflection}, type ${typeMap} } from '${specifier}';`,
+      '',
+      '/**',
+      " * Transfer-node factory for this project's grammar, for tests. It fills the",
+      ' * grammar defaults, so a test names only the fields it cares about;',
+      ' * `transferNode.partial` fills none and types the node as incomplete.',
+      ' */',
+      `export const transferNode = makeTransferNodeBuilder<${typeMap}, typeof ${reflection}>(${reflection});`,
+      ''
+   ].join('\n');
+}
+
+/** The nearest `package.json` at or above `file` that names a package. */
+function owningPackage(file: string): { dir: string; name: string } | undefined {
+   let dir = path.dirname(path.resolve(file));
+   for (;;) {
+      const manifest = path.join(dir, 'package.json');
+      if (fs.existsSync(manifest)) {
+         let parsed: unknown;
+         try {
+            parsed = JSON.parse(fs.readFileSync(manifest, 'utf-8'));
+         } catch (error: unknown) {
+            throw new Error(`Cannot read '${manifest}' to name the transfer model's package: ${describeError(error)}`);
+         }
+         const name = typeof parsed === 'object' && parsed !== null && 'name' in parsed ? parsed.name : undefined;
+         if (typeof name === 'string') {
+            return { dir, name };
+         }
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) {
+         return undefined;
+      }
+      dir = parent;
+   }
+}

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

@@ -29,6 +29,9 @@ export const GENERATE_TRANSFER_MODEL_FLAGS: readonly string[] = [
    '--ast-file',
    '--augmentation-file',
    '--out-file',
+   '--ast-builder-file',
+   '--transfer-builder-file',
+   '--languages-file',
    '--element-type-name',
    '--terminals-name',
    '--terminals-source-name',
@@ -48,11 +51,13 @@ 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',
-   '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",
-   '--config file, then the langium-config-derived --ast-file.',
+   'Generate a serializable transfer-model TypeScript file from a Langium AST, and',
+   'optionally an AST-node builder bound to the same reflection and a transfer-node',
+   'builder for tests. 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 --config file, then the langium-config-derived',
+   '--ast-file.',
    '',
    'Options:',
    '  --config <path>               JSON config supplying any of the options below.',
@@ -67,6 +72,17 @@ 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.",
+   '  --transfer-builder-file <p>   Also emit a test module here binding',
+   '                                makeTransferNodeBuilder to the transfer model as',
+   '                                transferNode. Import it from tests only.',
+   "  --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.',
@@ -120,6 +136,15 @@ export function parseGenerateOptions(args: string[], onError: UsageError = exitW
          case '--out-file':
             flags.outFile = next();
             break;
+         case '--ast-builder-file':
+            flags.astBuilderFile = next();
+            break;
+         case '--transfer-builder-file':
+            flags.transferBuilderFile = 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'] as const;
+const PATH_KEYS = ['astFile', 'augmentationFile', 'outFile', 'astBuilderFile', 'transferBuilderFile', '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.`);
@@ -43,6 +44,9 @@ export function loadTransferModelConfig(configPath: string): Partial<GenerateTra
       'astFile',
       'augmentationFile',
       'outFile',
+      'astBuilderFile',
+      'transferBuilderFile',
+      'languagesFile',
       'elementTypeName',
       'terminalsName',
       'terminalsSourceName',
@@ -74,7 +78,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 +122,9 @@ export function mergeTransferModelOptions(...sources: Array<Partial<GenerateTran
       astFile: astFile!,
       augmentationFile: augmentationFile!,
       outFile: outFile!,
+      astBuilderFile: pick('astBuilderFile'),
+      transferBuilderFile: pick('transferBuilderFile'),
+      languagesFile: pick('languagesFile'),
       elementTypeName: pick('elementTypeName'),
       terminalsName: pick('terminalsName'),
       terminalsSourceName: pick('terminalsSourceName'),