@hydranium/cli 1.0.0-next.408 → 1.0.0-next.411

package/src/commands/message-catalogue-args.ts

@@ -0,0 +1,55 @@
+/********************************************************************************
+ * 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 { assertRequired, exitWithUsage, helpRequested, printHelp, type UsageError } from './harness-args.js';
+import { runMessageCatalogue, type MessageCatalogueCommandOptions } from './message-catalogue.js';
+
+export const MESSAGE_CATALOGUE_FLAGS: readonly string[] = ['--barrel', '--out-file'];
+export const MESSAGE_CATALOGUE_VALUE_FLAGS = MESSAGE_CATALOGUE_FLAGS;
+export const MESSAGE_CATALOGUE_HELP: readonly string[] = [
+   'Usage: hydranium-cli message-catalogue --barrel <module>... [--out-file <file>]',
+   '',
+   'Emit a flat JSON starter catalogue mapping message codes to English defaults.',
+   'Modules are resolved from the current project and must be built first.',
+   'Repeat --barrel for each framework head and your own messages. No server starts.',
+   '',
+   'Options:',
+   '  --barrel <module>    Messages package specifier or ESM file (required). Repeatable.',
+   '  --out-file <file>   Write JSON here instead of stdout, after all imports succeed.'
+];
+
+export function parseMessageCatalogueArgs(args: string[], onError: UsageError = exitWithUsage): MessageCatalogueCommandOptions {
+   const barrels: string[] = [];
+   let outFile: string | undefined;
+   for (let index = 0; index < args.length; index++) {
+      const flag = args[index];
+      if (!MESSAGE_CATALOGUE_FLAGS.includes(flag)) {
+         return onError(`Unexpected argument: ${flag} (hydranium-cli message-catalogue --help)`);
+      }
+      const value = args[++index];
+      if (value === undefined || value.startsWith('--')) {
+         return onError(`Missing value for ${flag}`);
+      }
+      if (flag === '--barrel') {
+         barrels.push(value);
+      } else {
+         outFile = value;
+      }
+   }
+   assertRequired(barrels[0], '--barrel', 'message-catalogue', onError);
+   return { barrels, outFile };
+}
+
+export async function runMessageCatalogueCommand(args: string[]): Promise<void> {
+   if (helpRequested(args, MESSAGE_CATALOGUE_VALUE_FLAGS)) {
+      printHelp(MESSAGE_CATALOGUE_HELP);
+      return;
+   }
+   await runMessageCatalogue(parseMessageCatalogueArgs(args));
+}

package/src/commands/message-catalogue.ts

@@ -0,0 +1,56 @@
+/********************************************************************************
+ * 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 { collectMessages, type MessageCatalogue } from '@hydranium/protocol';
+import { resolve as resolveModule } from 'import-meta-resolve';
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { emitReport } from './headless-harness.js';
+
+/**
+ * Enumerate declarations rather than scanning source. Conflicting defaults
+ * must fail before any output is written, or import order chooses the English.
+ */
+export function createMessageCatalogue(barrels: readonly object[]): MessageCatalogue {
+   const entries = new Map<string, string>();
+   for (const barrel of barrels) {
+      for (const message of collectMessages(barrel)) {
+         const previous = entries.get(message.code);
+         if (previous !== undefined && previous !== message.text) {
+            throw new Error(`Conflicting English defaults for message '${message.code}'.`);
+         }
+         entries.set(message.code, message.text);
+      }
+   }
+   return Object.fromEntries([...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+
+export interface MessageCatalogueCommandOptions {
+   readonly barrels: readonly string[];
+   readonly outFile?: string;
+}
+
+/** Resolve against the caller's project, including when the CLI is installed globally. */
+export async function runMessageCatalogue(options: MessageCatalogueCommandOptions): Promise<void> {
+   const projectUrl = pathToFileURL(resolve('package.json')).href;
+   const barrels: object[] = [];
+   for (const specifier of options.barrels) {
+      const target =
+         specifier.startsWith('.') || isAbsolute(specifier) ? pathToFileURL(resolve(specifier)).href : resolveModule(specifier, projectUrl);
+      const barrel = (await import(target)) as object;
+      if (collectMessages(barrel).length === 0) {
+         throw new Error(`Message barrel '${specifier}' exports no declarations. Pass a built messages module.`);
+      }
+      barrels.push(barrel);
+   }
+   if (barrels.length === 0) {
+      throw new Error('Pass at least one --barrel messages module.');
+   }
+   emitReport(JSON.stringify(createMessageCatalogue(barrels), undefined, 2), options.outFile);
+}

package/src/commands/model-docs-args.ts

@@ -37,7 +37,7 @@ export const MODEL_DOCS_VALUE_FLAGS: readonly string[] = MODEL_DOCS_FLAGS;
 
 /** The `--help` text, as data, held to {@link MODEL_DOCS_FLAGS} by a test. */
 export const MODEL_DOCS_HELP: readonly string[] = [
-   'Usage: hydranium-cli model-docs --services <module> [--import <specifier>]... [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
+   'Usage: hydranium-cli model-docs [--services <module>] [--import <specifier>]... [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    'Generate a navigable Markdown reference of every AST node type — a type index,',
    'cross-linked super/sub types, a reverse "referenced by" index, and a per-language',
@@ -47,7 +47,7 @@ export const MODEL_DOCS_HELP: readonly string[] = [
    'zero-arg `createServices(): { shared }` thunk. Needs @hydranium/core.',
    '',
    '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),
    '  --out-file <file>     Write the Markdown to this file instead of stdout. Written',
    '                        only once the report exists, unlike a shell redirection,',

package/src/commands/reflect-args.ts

@@ -38,7 +38,7 @@ export const REFLECT_VALUE_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS, .
 
 /** The `--help` text, as data, held to {@link REFLECT_FLAGS} by a test. */
 export const REFLECT_HELP: readonly string[] = [
-   'Usage: hydranium-cli reflect --services <module> [--import <specifier>]... [--json] [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
+   'Usage: hydranium-cli reflect [--services <module>] [--import <specifier>]... [--json] [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    "Dump a head's grammar/AST reflection — the type hierarchy, each language's",
    'terminals and entry rule, and every cross-reference target. Read-only: no',
@@ -47,7 +47,7 @@ export const REFLECT_HELP: readonly string[] = [
    'exporting a zero-arg `createServices(): { shared }` thunk. Needs @hydranium/core.',
    '',
    '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),
    '  --json                Emit the raw JSON reflection instead of the Markdown report.',
    '  --out-file <file>     Write the report to this file instead of stdout. Written',

package/src/commands/validate-args.ts

@@ -38,7 +38,7 @@ export const VALIDATE_VALUE_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS,
 
 /** The `--help` text, as data, held to {@link VALIDATE_FLAGS} by a test. */
 export const VALIDATE_HELP: readonly string[] = [
-   'Usage: hydranium-cli validate --services <module> [--import <specifier>]... <workspace> [--strict] [--json] [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
+   'Usage: hydranium-cli validate [--services <module>] [--import <specifier>]... <workspace> [--strict] [--json] [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    'Build a workspace headlessly and report its validation diagnostics — a CI gate:',
    'the process exits non-zero when any error is found. `<module>` is an ESM module',
@@ -46,7 +46,7 @@ export const VALIDATE_HELP: readonly string[] = [
    'filesystem inside). Needs @hydranium/core.',
    '',
    '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 validate (required).',
    '  --strict              Also fail (non-zero exit) on warnings, not only errors.',

package/src/index.ts

@@ -17,3 +17,4 @@ export * from './commands/save.js';
 export * from './commands/watch.js';
 export * from './package-name.js';
 export * from './spawn-data-server.js';
+export * from './commands/message-catalogue.js';