@hydranium/cli 1.0.0-next.42 → 1.0.0-next.421

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>`',
@@ -43,15 +45,16 @@ export const AST_GROUND_TRUTH_HELP: readonly string[] = [
    '`{ documents, totalAstNodes, byType }` JSON on stdout (or `--out-file`).',
    '',
    'Options:',
-   '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   '  --services <module>   ESM module exporting `createServices(): { shared }` (required) unless package.json sets hydranium.services.',
+   ...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 {
@@ -67,7 +68,8 @@ async function main(argv: string[]): Promise<void> {
    if (args.outFile) {
       fs.writeFileSync(args.outFile, `${json}\n`);
       // Progress to stderr keeps stdout clean for callers that capture either form.
-      console.error(`Ground truth: ${result.documents} docs, ${result.totalAstNodes} AST nodes -> ${args.outFile}`);
+      // Not `console.error`, which a configured log file records as an error line.
+      process.stderr.write(`Ground truth: ${result.documents} docs, ${result.totalAstNodes} AST nodes -> ${args.outFile}\n`);
    } else {
       console.log(json);
    }
@@ -76,6 +78,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/check-skills-args.ts

@@ -0,0 +1,70 @@
+/********************************************************************************
+ * 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 path from 'node:path';
+import { exitWithUsage, helpRequested, printHelp } from './harness-args.js';
+import { checkSkills } from './skills.js';
+
+export const CHECK_SKILLS_HELP = [
+   'Usage: hydranium-cli check-skills [project-directory] [--from <directory>] [--skill <names>]',
+   '',
+   'Check declared compatibility of installed Hydranium and Langium skills.',
+   'Reads .agents/skills and .claude/skills in the project directory (default: cwd).',
+   'Checks every copy. Does not download, update, or execute skills.',
+   'Exits non-zero for incompatible, missing, malformed, or unverified skills.',
+   '',
+   '  --from <directory>   Resolve installed packages from this directory, relative',
+   '                       to the project. Default: the project directory.',
+   '                       Use the server package for workspace-local dependencies.',
+   '  --skill <names>      Check only these comma-separated skill names.',
+   '                       Default: hydranium-*. Use --skill langium to check upstream.',
+   '',
+   'A compatible result checks declared skill contracts,',
+   'not the accuracy of prose.',
+   'Upstream skills without Hydranium metadata are unverified.'
+];
+
+export function runCheckSkillsCommand(args: string[]): void {
+   if (helpRequested(args, ['--from', '--skill'])) {
+      printHelp(CHECK_SKILLS_HELP);
+      return;
+   }
+   let project: string | undefined;
+   let from: string | undefined;
+   let names: string[] | undefined;
+   for (let index = 0; index < args.length; index++) {
+      const argument = args[index];
+      if (argument === '--from' || argument === '--skill') {
+         const value = args[++index];
+         if (!value || value.startsWith('--')) {
+            exitWithUsage(`Missing value for ${argument}`);
+         }
+         if (argument === '--from') {
+            from = value;
+         } else {
+            names = value.split(',');
+            if (names.some(name => !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name))) {
+               exitWithUsage('Invalid skill name.');
+            }
+         }
+      } else if (argument.startsWith('-') || project !== undefined) {
+         exitWithUsage(`Unexpected argument: ${argument} (hydranium-cli check-skills --help)`);
+      } else {
+         project = argument;
+      }
+   }
+   const root = path.resolve(project ?? '.');
+   const results = checkSkills(root, path.resolve(root, from ?? '.'), names);
+   for (const result of results) {
+      console.log(`${result.status}: ${result.file}: ${result.detail}`);
+   }
+   if (results.some(result => result.status !== 'compatible')) {
+      process.exitCode = 1;
+   }
+}

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, baseEpoch: created.epoch });
+   });
+}

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

@@ -10,6 +10,7 @@
 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 {
@@ -47,7 +48,7 @@ const NAMESPACED_AST_TYPE_NAME = 'AstType';
 const MERGED_EXPORT_NAME = 'astNode';
 
 /**
- * Emit a module binding {@link makeAstNodeBuilder} to a project's reflection,
+ * Emit a module binding `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
@@ -175,17 +176,6 @@ function findReflectionConstName(astSource: SourceFile, languageId: string): str
    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 }

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