@hydranium/cli 1.0.0-next.10

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

@@ -0,0 +1,68 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/*
+ * Spawned child of the `model-docs` subcommand. Launched by the parent with
+ * `node <this> --services <module> [--out-file <file>]`. It dynamic-imports the
+ * head's services module, runs the framework's `reflectGrammar` (the same
+ * reflection the `reflect` subcommand uses), and delivers a navigable Markdown
+ * reference to stdout or the named file. Read-only — exits 0 unless booting the
+ * head throws. Never imported — only spawned.
+ */
+
+import { emitReport, loadHeadlessContext, OUT_FILE_FLAG } from './headless-harness.js';
+import { formatModelDocs } from './model-docs-report.js';
+
+interface DriverArgs {
+   servicesModule?: string;
+   outFile?: string;
+}
+
+function parseArgs(argv: string[]): DriverArgs {
+   const parsed: DriverArgs = {};
+   for (let index = 0; index < argv.length; index += 1) {
+      const flag = argv[index];
+      if (flag === '--services' || flag === OUT_FILE_FLAG) {
+         const value = argv[index + 1];
+         if (value === undefined) {
+            console.error(`Missing value for ${flag}`);
+            process.exit(1);
+         }
+         if (flag === '--services') {
+            parsed.servicesModule = value;
+         } else {
+            parsed.outFile = value;
+         }
+         index += 1;
+      } else {
+         console.error(`Unknown option: ${flag}`);
+         process.exit(1);
+      }
+   }
+   return parsed;
+}
+
+async function main(argv: string[]): Promise<number> {
+   const args = parseArgs(argv);
+   if (!args.servicesModule) {
+      console.error('model-docs-driver: --services <module> is required.');
+      process.exit(1);
+   }
+   const { createServices, coreNode } = await loadHeadlessContext(args.servicesModule);
+   const reflection = coreNode.reflectGrammar({ createServices });
+   emitReport(formatModelDocs(reflection), args.outFile);
+   return 0;
+}
+
+main(process.argv.slice(2))
+   .then(code => process.exit(code))
+   .catch((error: unknown) => {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+   });

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

@@ -0,0 +1,133 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Type-only import: the CLI is head-neutral and carries no runtime `@hydranium/core`
+// dependency (the head's copy is resolved at run time via `loadHeadlessContext`).
+import type { GrammarReflection, TypeReflection } from '@hydranium/core/node';
+
+/** GitHub-style heading slug: lowercase, non-alphanumerics to hyphens, collapse repeats. */
+function slug(name: string): string {
+   return name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '');
+}
+
+/** A Markdown link to a type's section, when that type has a section; else bare code. */
+function typeLink(name: string, known: ReadonlySet<string>): string {
+   return known.has(name) ? `[${name}](#${slug(name)})` : `\`${name}\``;
+}
+
+/** Escape a value for a Markdown table cell (only `|` and newlines can break a row). */
+function cell(value: string): string {
+   return value.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+}
+
+/** Per-language grammar summary — extensions, entry rule, terminals table. */
+function languageSection(reflection: GrammarReflection): string[] {
+   const lines: string[] = ['## Languages', ''];
+   for (const language of reflection.languages) {
+      lines.push(`### ${language.languageId}`, '');
+      const extensions = language.fileExtensions.length ? language.fileExtensions.map(ext => `\`${ext}\``).join(', ') : '_none_';
+      lines.push(`- File extensions: ${extensions}`);
+      lines.push(`- Entry rule: ${language.entryRule ? `\`${language.entryRule}\`` : '_none_'}`);
+      lines.push('');
+      if (language.terminals.length) {
+         lines.push('| Terminal | Pattern | Hidden |', '| --- | --- | --- |');
+         for (const terminal of language.terminals) {
+            const pattern = terminal.pattern !== undefined ? `\`${cell(terminal.pattern)}\`` : '';
+            lines.push(`| ${cell(terminal.name)} | ${pattern} | ${terminal.hidden ? 'yes' : ''} |`);
+         }
+         lines.push('');
+      }
+   }
+   return lines;
+}
+
+/** The alphabetical type index (TOC), each entry linked, marking abstract vs concrete. */
+function typeIndexSection(reflection: GrammarReflection): string[] {
+   const lines: string[] = [`## Types (${reflection.types.length})`, ''];
+   for (const type of reflection.types) {
+      const kind = type.directSubTypes.length ? ' _(abstract)_' : '';
+      lines.push(`- [${type.name}](#${slug(type.name)})${kind}`);
+   }
+   lines.push('');
+   return lines;
+}
+
+/** Build the reverse index: for each type, the `Type.property` sites that cross-reference it. */
+function referencedByIndex(reflection: GrammarReflection): Map<string, string[]> {
+   const index = new Map<string, string[]>();
+   for (const type of reflection.types) {
+      for (const property of type.properties) {
+         if (property.referenceType !== undefined) {
+            const sites = index.get(property.referenceType) ?? [];
+            sites.push(`${type.name}.${property.name}`);
+            index.set(property.referenceType, sites);
+         }
+      }
+   }
+   return index;
+}
+
+/** One type's detail section — extends / subtypes / referenced-by / property table. */
+function typeSection(type: TypeReflection, known: ReadonlySet<string>, referencedBy: readonly string[]): string[] {
+   const lines: string[] = [`### ${type.name}`, ''];
+   if (type.superTypes.length) {
+      lines.push(`- Extends: ${type.superTypes.map(name => typeLink(name, known)).join(', ')}`);
+   }
+   if (type.directSubTypes.length) {
+      lines.push(`- Known subtypes: ${type.directSubTypes.map(name => typeLink(name, known)).join(', ')}`);
+   }
+   if (referencedBy.length) {
+      // The reverse index is keyed by type, so each `Owner.property` site links to Owner's section.
+      const links = referencedBy.map(site => {
+         const owner = site.slice(0, site.indexOf('.'));
+         return `${typeLink(owner, known)}.${site.slice(site.indexOf('.') + 1)}`;
+      });
+      lines.push(`- Referenced by: ${links.join(', ')}`);
+   }
+   lines.push('');
+   if (type.properties.length) {
+      lines.push('| Property | Kind | Target | Array |', '| --- | --- | --- | --- |');
+      for (const property of type.properties) {
+         const isReference = property.referenceType !== undefined;
+         const target = isReference ? typeLink(property.referenceType!, known) : '';
+         lines.push(`| ${cell(property.name)} | ${isReference ? 'reference' : 'value'} | ${target} | ${property.array ? 'yes' : ''} |`);
+      }
+   } else {
+      lines.push('_No properties._');
+   }
+   lines.push('');
+   return lines;
+}
+
+/**
+ * Render a grammar reflection as a navigable Markdown model reference for adopter
+ * docs: a per-language grammar summary, an anchor-linked type index, and a per-type
+ * section with cross-linked super/sub types, a reverse "referenced by" index, and a
+ * property table. Distinct from `reflect`'s flat dump — this is the publishable
+ * reference (cross-linked, navigable), whereas `reflect --json` is the machine form.
+ */
+export function formatModelDocs(reflection: GrammarReflection): string {
+   const known = new Set(reflection.types.map(type => type.name));
+   const referencedBy = referencedByIndex(reflection);
+   const typeSections = reflection.types.flatMap(type => typeSection(type, known, referencedBy.get(type.name) ?? []));
+   return [
+      '# Model reference',
+      '',
+      'Generated from the grammar reflection. One section per AST node type.',
+      '',
+      ...languageSection(reflection),
+      ...typeIndexSection(reflection),
+      '## Type details',
+      '',
+      ...typeSections
+   ].join('\n');
+}

package/src/commands/model-docs.ts

@@ -0,0 +1,48 @@
+/********************************************************************************
+ * 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 { fileURLToPath } from 'node:url';
+import { OUT_FILE_FLAG, runDriverChild, type DriverSpawnOptions } from './headless-harness.js';
+
+/**
+ * Absolute path to the spawned driver. From `lib/commands/model-docs.js` the
+ * compiled driver sits beside it at `lib/commands/model-docs-driver.js`.
+ */
+const DRIVER = fileURLToPath(new URL('./model-docs-driver.js', import.meta.url));
+
+/** Options for the {@link runModelDocs} subcommand. */
+export interface ModelDocsCommandOptions extends DriverSpawnOptions {
+   /** ESM module exporting a zero-arg `createServices(): { shared }` thunk. */
+   readonly servicesModule: string;
+   /** Write the Markdown to this file instead of stdout. */
+   readonly outFile?: string;
+}
+
+/** Build the argv the driver child parses. Pure → unit-testable. */
+export function buildModelDocsDriverArgs(options: ModelDocsCommandOptions): string[] {
+   const args = ['--services', options.servicesModule];
+   if (options.outFile !== undefined) {
+      args.push(OUT_FILE_FLAG, options.outFile);
+   }
+   return args;
+}
+
+/**
+ * Headless model-surface documentation — emits a navigable Markdown reference of
+ * every AST node type (type index, cross-linked super/sub types, a reverse
+ * "referenced by" index, and a per-language grammar summary), suitable for
+ * publishing into adopter docs. Read-only: no workspace is built (the reflection is
+ * static once the head registers its language), so it takes no `<workspace>`.
+ * There is no `--json` — the machine-readable form is `hydranium-cli reflect --json`.
+ * The work runs in a spawned child that dynamic-imports the head's `createServices`
+ * module, keeping the binary language-agnostic.
+ */
+export function runModelDocs(options: ModelDocsCommandOptions): Promise<void> {
+   return runDriverChild(['--max-old-space-size=8192', DRIVER, ...buildModelDocsDriverArgs(options)], options);
+}

package/src/commands/projects-args.ts

@@ -0,0 +1,62 @@
+/********************************************************************************
+ * 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 {
+   exitWithUsage,
+   helpRequested,
+   parseFlagOptions,
+   parseServerSpawnOptions,
+   printHelp,
+   SERVER_SPAWN_VALUE_FLAGS,
+   type UsageError
+} from './harness-args.js';
+import { runProjects, type ProjectsCommandOptions } from './projects.js';
+
+/**
+ * Every flag `projects` accepts. All three are consumed by the shared spawn
+ * parser; the command declares no options of its own beyond them.
+ */
+export const PROJECTS_FLAGS: readonly string[] = SERVER_SPAWN_VALUE_FLAGS;
+
+/**
+ * The subset that takes a value, so `--help` in a value position reads as data.
+ * Every flag in this family takes one, so the two lists coincide.
+ */
+export const PROJECTS_VALUE_FLAGS: readonly string[] = PROJECTS_FLAGS;
+
+/** The `--help` text, as data, held to {@link PROJECTS_FLAGS} by a test. */
+export const PROJECTS_HELP: readonly string[] = [
+   'Usage: hydranium-cli projects --server "<cmd> [args...]" [--cwd <dir>] [--log-level <level>]',
+   '',
+   'List projects exposed by the data-server subprocess. Output is newline-delimited',
+   'JSON — one project envelope per line.',
+   '',
+   'Options:',
+   '  --server "<cmd>"   Command-line for the data-server subprocess (required).',
+   '  --cwd <dir>        Working directory for the spawned child. Default: cwd.',
+   '  --log-level <lvl>  Log threshold for the spawned server (off|error|warn|info|debug|trace).'
+];
+
+export function parseProjectsArgs(args: string[], onError: UsageError = exitWithUsage): ProjectsCommandOptions {
+   const { serverCommand, serverArgs, cwd, logLevel, extra } = parseServerSpawnOptions(args, 'projects', onError);
+   // `projects` declares no options beyond the shared ones, so nothing may
+   // survive the spawn parser. Draining `extra` against an empty set is what
+   // makes a typo an error here rather than a flag that silently did nothing —
+   // the siblings get this from the option list they pass.
+   parseFlagOptions(extra, 'projects', [], onError);
+   return { serverCommand, serverArgs, cwd, logLevel };
+}
+
+export function runProjectsCommand(args: string[]): Promise<void> {
+   if (helpRequested(args, PROJECTS_VALUE_FLAGS)) {
+      printHelp(PROJECTS_HELP);
+      return Promise.resolve();
+   }
+   return runProjects(parseProjectsArgs(args));
+}

package/src/commands/projects.ts

@@ -0,0 +1,76 @@
+/********************************************************************************
+ * 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 { LogThreshold, Project, TransferElement } from '@hydranium/protocol';
+import type { DataServerProtocol } from '@hydranium/protocol/data';
+import { logLevelEnv } from '../log-level.js';
+import { withDataServer } from '../spawn-data-server.js';
+
+/**
+ * Options for the {@link runProjects} subcommand. `serverCommand` /
+ * `serverArgs` mirror what an adopter would pass to spawn the data-server
+ * subprocess.
+ */
+export interface ProjectsCommandOptions {
+   /**
+    * Command-line tokens used to spawn the data-server child. Mirrors
+    * the `--server "<cmd> [args...]"` shape on the CLI surface — split
+    * into command + args here so callers don't have to handle quoting.
+    */
+   readonly serverCommand: string;
+   readonly serverArgs?: readonly string[];
+   readonly cwd?: string;
+   /** Log threshold for the spawned server, set on its `HYDRANIUM_LOG_LEVEL` env. */
+   readonly logLevel?: LogThreshold;
+   /**
+    * Output sink. Default: `process.stdout.write`. Tests inject a
+    * capturing stub.
+    */
+   readonly write?: (line: string) => void;
+   /**
+    * Test-only injection: skip the spawn + use this proxy directly. The
+    * production CLI never passes this; subcommand unit tests do.
+    */
+   readonly __proxyForTest?: DataServerProtocol<TransferElement>;
+}
+
+/**
+ * Print the projects exposed by the data-server as one JSON object per
+ * line (newline-delimited JSON). Each line is independently parseable —
+ * adopters piping the output into `jq` or another line-oriented tool
+ * don't need to wait for end-of-stream.
+ */
+export async function runProjects(options: ProjectsCommandOptions): Promise<void> {
+   const write = options.write ?? ((line: string) => process.stdout.write(line));
+
+   if (options.__proxyForTest) {
+      const projects = await options.__proxyForTest.getProjects();
+      writeProjects(projects, write);
+      return;
+   }
+
+   await withDataServer(
+      {
+         command: options.serverCommand,
+         args: options.serverArgs,
+         cwd: options.cwd,
+         env: options.logLevel ? logLevelEnv(options.logLevel) : undefined
+      },
+      async server => {
+         const projects = await server.getProjects();
+         writeProjects(projects, write);
+      }
+   );
+}
+
+function writeProjects(projects: readonly Project[], write: (line: string) => void): void {
+   for (const project of projects) {
+      write(`${JSON.stringify(project)}\n`);
+   }
+}

package/src/commands/query-args.ts

@@ -0,0 +1,61 @@
+/********************************************************************************
+ * 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,
+   parseFlagOptions,
+   parseServerSpawnOptions,
+   printHelp,
+   SERVER_SPAWN_VALUE_FLAGS,
+   type UsageError
+} from './harness-args.js';
+import { runQuery, type QueryCommandOptions } from './query.js';
+
+const OWN_FLAGS = ['--uri'] as const;
+
+/**
+ * Every flag `query` accepts, derived from its own list plus the shared spawn
+ * flags, so the list cannot claim a flag the parser would reject.
+ */
+export const QUERY_FLAGS: readonly string[] = [...SERVER_SPAWN_VALUE_FLAGS, ...OWN_FLAGS];
+
+/**
+ * The subset that takes a value, so `--help` in a value position reads as data.
+ * Every flag in this family takes one, so the two lists coincide.
+ */
+export const QUERY_VALUE_FLAGS: readonly string[] = QUERY_FLAGS;
+
+/** The `--help` text, as data, held to {@link QUERY_FLAGS} by a test. */
+export const QUERY_HELP: readonly string[] = [
+   'Usage: hydranium-cli query --server "<cmd> [args...]" --uri <uri> [--cwd <dir>] [--log-level <level>]',
+   '',
+   'Print the data-server document envelope for `<uri>` as a single JSON line.',
+   '',
+   'Options:',
+   '  --server "<cmd>"   Command-line for the data-server subprocess (required).',
+   '  --uri <uri>        Document URI (required).',
+   '  --cwd <dir>        Working directory for the spawned child. Default: cwd.',
+   '  --log-level <lvl>  Log threshold for the spawned server (off|error|warn|info|debug|trace).'
+];
+
+export function parseQueryArgs(args: string[], onError: UsageError = exitWithUsage): QueryCommandOptions {
+   const { serverCommand, serverArgs, cwd, logLevel, extra } = parseServerSpawnOptions(args, 'query', onError);
+   const { uri } = parseFlagOptions(extra, 'query', OWN_FLAGS, onError);
+   return { serverCommand, serverArgs, cwd, logLevel, uri: assertRequired(uri, '--uri', 'query', onError) };
+}
+
+export function runQueryCommand(args: string[]): Promise<void> {
+   if (helpRequested(args, QUERY_VALUE_FLAGS)) {
+      printHelp(QUERY_HELP);
+      return Promise.resolve();
+   }
+   return runQuery(parseQueryArgs(args));
+}

package/src/commands/query.ts

@@ -0,0 +1,58 @@
+/********************************************************************************
+ * 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 { LogThreshold, TransferElement } from '@hydranium/protocol';
+import type { DataServerProtocol } from '@hydranium/protocol/data';
+import { logLevelEnv } from '../log-level.js';
+import { withDataServer } from '../spawn-data-server.js';
+
+/**
+ * Options for the {@link runQuery} subcommand. Prints the data-server's
+ * current view of a document — invokes `getModelDocument({ uri })` on
+ * the spawned subprocess and writes the response envelope as a single
+ * JSON line. Adopters piping the output into `jq` get a complete record
+ * per invocation.
+ *
+ * Test-only `__proxyForTest` bypasses the spawn for unit tests; the
+ * production CLI never passes it.
+ */
+export interface QueryCommandOptions {
+   readonly serverCommand: string;
+   readonly serverArgs?: readonly string[];
+   readonly cwd?: string;
+   /** Log threshold for the spawned server, set on its `HYDRANIUM_LOG_LEVEL` env. */
+   readonly logLevel?: LogThreshold;
+   readonly uri: string;
+   readonly write?: (line: string) => void;
+   readonly __proxyForTest?: DataServerProtocol<TransferElement>;
+}
+
+export async function runQuery(options: QueryCommandOptions): Promise<void> {
+   const write = options.write ?? ((line: string) => process.stdout.write(line));
+
+   if (options.__proxyForTest) {
+      // One-shot, unsubscribed read — request validation so the dumped envelope carries diagnostics.
+      const doc = await options.__proxyForTest.getModelDocument({ uri: options.uri, includeDiagnostics: true });
+      write(`${JSON.stringify(doc)}\n`);
+      return;
+   }
+
+   await withDataServer(
+      {
+         command: options.serverCommand,
+         args: options.serverArgs,
+         cwd: options.cwd,
+         env: options.logLevel ? logLevelEnv(options.logLevel) : undefined
+      },
+      async server => {
+         const doc = await server.getModelDocument({ uri: options.uri, includeDiagnostics: true });
+         write(`${JSON.stringify(doc)}\n`);
+      }
+   );
+}

package/src/commands/reflect-args.ts

@@ -0,0 +1,75 @@
+/********************************************************************************
+ * 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 {
+   exitWithUsage,
+   helpRequested,
+   LOG_LEVEL_FLAG,
+   logLevelHelpLine,
+   logLevelOption,
+   parseHarnessArgs,
+   printHelp,
+   SERVICES_FLAG,
+   type UsageError
+} from './harness-args.js';
+import { OUT_FILE_FLAG } from './headless-harness.js';
+import { runReflect, type ReflectCommandOptions } from './reflect.js';
+
+const VALUE_FLAGS = [OUT_FILE_FLAG, LOG_LEVEL_FLAG] as const;
+const BOOL_FLAGS = ['--json'] as const;
+
+/**
+ * Every flag `reflect` 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.
+ */
+export const REFLECT_FLAGS: readonly string[] = [SERVICES_FLAG, ...VALUE_FLAGS, ...BOOL_FLAGS];
+
+/** The subset that takes a value, so `--help` in a value position reads as data. */
+export const REFLECT_VALUE_FLAGS: readonly string[] = [SERVICES_FLAG, ...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> [--json] [--out-file <file>] [--log-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',
+   'workspace is built (the reflection is static once the head registers its',
+   'language), so `reflect` takes no `<workspace>`. `<module>` is an ESM module',
+   'exporting a zero-arg `createServices(): { shared }` thunk. Needs @hydranium/core.',
+   '',
+   'Options:',
+   '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   '  --json                Emit the raw JSON reflection instead of the Markdown report.',
+   '  --out-file <file>     Write the report to this file instead of stdout. Written',
+   '                        only once the report exists, unlike a shell redirection,',
+   '                        which truncates the file before the head is even booted.',
+   logLevelHelpLine(22)
+];
+
+export function parseReflectArgs(args: string[], onError: UsageError = exitWithUsage): ReflectCommandOptions {
+   const { servicesModule, options } = parseHarnessArgs(args, 'reflect', VALUE_FLAGS, BOOL_FLAGS, {
+      requireWorkspace: false,
+      onError
+   });
+   return {
+      servicesModule,
+      json: options['--json'] === 'true',
+      outFile: options[OUT_FILE_FLAG],
+      logLevel: logLevelOption(options[LOG_LEVEL_FLAG])
+   };
+}
+
+export function runReflectCommand(args: string[]): Promise<void> {
+   if (helpRequested(args, REFLECT_VALUE_FLAGS)) {
+      printHelp(REFLECT_HELP);
+      return Promise.resolve();
+   }
+   return runReflect(parseReflectArgs(args));
+}

package/src/commands/reflect-driver.ts

@@ -0,0 +1,76 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/*
+ * Spawned child of the `reflect` subcommand. Launched by the parent with
+ * `node <this> --services <module> [--json] [--out-file <file>]`. It
+ * dynamic-imports the head's services module, runs the framework's
+ * `reflectGrammar`, and delivers the report (markdown or `--json`) to stdout or
+ * the named file. Read-only — exits 0 unless booting the head throws. Never
+ * imported — only spawned.
+ */
+
+import { emitReport, loadHeadlessContext, OUT_FILE_FLAG } from './headless-harness.js';
+import { formatReflectionReport } from './reflect-report.js';
+
+interface DriverArgs {
+   servicesModule?: string;
+   json: boolean;
+   outFile?: string;
+}
+
+function parseArgs(argv: string[]): DriverArgs {
+   const parsed: DriverArgs = { json: false };
+   for (let index = 0; index < argv.length; index += 1) {
+      const flag = argv[index];
+      const next = (): string => {
+         const value = argv[index + 1];
+         if (value === undefined) {
+            console.error(`Missing value for ${flag}`);
+            process.exit(1);
+         }
+         index += 1;
+         return value;
+      };
+      switch (flag) {
+         case '--services':
+            parsed.servicesModule = next();
+            break;
+         case '--json':
+            parsed.json = true;
+            break;
+         case OUT_FILE_FLAG:
+            parsed.outFile = next();
+            break;
+         default:
+            console.error(`Unknown option: ${flag}`);
+            process.exit(1);
+      }
+   }
+   return parsed;
+}
+
+async function main(argv: string[]): Promise<number> {
+   const args = parseArgs(argv);
+   if (!args.servicesModule) {
+      console.error('reflect-driver: --services <module> is required.');
+      process.exit(1);
+   }
+   const { createServices, coreNode } = await loadHeadlessContext(args.servicesModule);
+   const result = coreNode.reflectGrammar({ createServices });
+   emitReport(formatReflectionReport(result, { json: args.json }), args.outFile);
+   return 0;
+}
+
+main(process.argv.slice(2))
+   .then(code => process.exit(code))
+   .catch((error: unknown) => {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+   });