@hydranium/cli 1.0.0-next.10

package/src/commands/reflect-report.ts

@@ -0,0 +1,138 @@
+/********************************************************************************
+ * 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';
+
+/** 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, ' ');
+}
+
+/** Wrap a value in inline-code backticks, escaping any embedded backtick run. */
+function code(value: string): string {
+   return `\`${value}\``;
+}
+
+/** The Markdown for each language's grammar surface — 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(code).join(', ') : '_none_';
+      lines.push(`- File extensions: ${extensions}`);
+      lines.push(`- Entry rule: ${language.entryRule ? code(language.entryRule) : '_none_'}`);
+      lines.push(`- Terminals: ${language.terminals.length}`, '');
+      if (language.terminals.length) {
+         lines.push('| Terminal | Pattern | Hidden |', '| --- | --- | --- |');
+         for (const terminal of language.terminals) {
+            const pattern = terminal.pattern !== undefined ? code(terminal.pattern) : '';
+            lines.push(`| ${cell(terminal.name)} | ${cell(pattern)} | ${terminal.hidden ? 'yes' : ''} |`);
+         }
+         lines.push('');
+      }
+   }
+   return lines;
+}
+
+/**
+ * A depth-first hierarchy tree from the roots (types with no super types) down
+ * through `directSubTypes`. A type reachable from several supertypes appears under
+ * each; a cycle (should not occur in a grammar) is broken by not re-descending a
+ * type already on the current path.
+ */
+function hierarchySection(reflection: GrammarReflection): string[] {
+   const byName = new Map(reflection.types.map(type => [type.name, type]));
+   const roots = reflection.types.filter(type => type.superTypes.length === 0);
+   const lines: string[] = ['## Type hierarchy', ''];
+   const walk = (type: TypeReflection, depth: number, path: ReadonlySet<string>): void => {
+      lines.push(`${'  '.repeat(depth)}- ${type.name}`);
+      const nextPath = new Set(path).add(type.name);
+      for (const childName of type.directSubTypes) {
+         const child = byName.get(childName);
+         if (child && !nextPath.has(childName)) {
+            walk(child, depth + 1, nextPath);
+         }
+      }
+   };
+   for (const root of roots) {
+      walk(root, 0, new Set());
+   }
+   lines.push('');
+   return lines;
+}
+
+/** The `Type.property → TargetType` list of every cross-reference in the grammar. */
+function crossReferenceSection(reflection: GrammarReflection): string[] {
+   const lines: string[] = ['## Cross-reference targets', ''];
+   let hasCrossReferences = false;
+   for (const type of reflection.types) {
+      for (const property of type.properties) {
+         if (property.referenceType !== undefined) {
+            lines.push(`- ${code(`${type.name}.${property.name}`)} → ${code(property.referenceType)}`);
+            hasCrossReferences = true;
+         }
+      }
+   }
+   if (!hasCrossReferences) {
+      lines.push('_No cross-references._');
+   }
+   lines.push('');
+   return lines;
+}
+
+/** Per-type detail: super types plus a property table (name, reference target, array, default). */
+function typeDetailSection(reflection: GrammarReflection): string[] {
+   const lines: string[] = [`## Types (${reflection.types.length})`, ''];
+   for (const type of reflection.types) {
+      lines.push(`### ${type.name}`, '');
+      if (type.superTypes.length) {
+         lines.push(`- Super types: ${type.superTypes.map(code).join(', ')}`);
+      }
+      if (type.directSubTypes.length) {
+         lines.push(`- Sub types: ${type.directSubTypes.map(code).join(', ')}`);
+      }
+      lines.push('');
+      if (type.properties.length) {
+         lines.push('| Property | Reference target | Array | Default |', '| --- | --- | --- | --- |');
+         for (const property of type.properties) {
+            const reference = property.referenceType !== undefined ? code(property.referenceType) : '';
+            lines.push(
+               `| ${cell(property.name)} | ${cell(reference)} | ${property.array ? 'yes' : ''} | ${property.hasDefault ? 'yes' : ''} |`
+            );
+         }
+      } else {
+         lines.push('_No properties._');
+      }
+      lines.push('');
+   }
+   return lines;
+}
+
+/**
+ * Render a grammar reflection for the terminal. `json` emits the raw
+ * {@link GrammarReflection} (the machine-readable contract); the default is a
+ * Markdown reference — a per-language grammar surface (terminals, entry rule), the
+ * type-hierarchy tree, the cross-reference target list, and a per-type property
+ * table — suitable for piping into a `.md` file.
+ */
+export function formatReflectionReport(reflection: GrammarReflection, options: { json?: boolean } = {}): string {
+   if (options.json) {
+      return JSON.stringify(reflection, undefined, 2);
+   }
+   return [
+      '# Grammar reflection',
+      '',
+      ...languageSection(reflection),
+      ...hierarchySection(reflection),
+      ...crossReferenceSection(reflection),
+      ...typeDetailSection(reflection)
+   ].join('\n');
+}

package/src/commands/reflect.ts

@@ -0,0 +1,51 @@
+/********************************************************************************
+ * 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/reflect.js` the
+ * compiled driver sits beside it at `lib/commands/reflect-driver.js`.
+ */
+const DRIVER = fileURLToPath(new URL('./reflect-driver.js', import.meta.url));
+
+/** Options for the {@link runReflect} subcommand. */
+export interface ReflectCommandOptions extends DriverSpawnOptions {
+   /** ESM module exporting a zero-arg `createServices(): { shared }` thunk. */
+   readonly servicesModule: string;
+   /** Emit the raw JSON reflection instead of the human markdown report. */
+   readonly json?: boolean;
+   /** Write the report to this file instead of stdout. */
+   readonly outFile?: string;
+}
+
+/** Build the argv the driver child parses. Pure → unit-testable. */
+export function buildReflectDriverArgs(options: ReflectCommandOptions): string[] {
+   const args = ['--services', options.servicesModule];
+   if (options.json) {
+      args.push('--json');
+   }
+   if (options.outFile !== undefined) {
+      args.push(OUT_FILE_FLAG, options.outFile);
+   }
+   return args;
+}
+
+/**
+ * Headless grammar/AST reflection — dumps a head's type hierarchy, terminals and
+ * cross-reference targets. Read-only: no workspace is built (the reflection is
+ * available as soon as the head's services register a language), so unlike the
+ * sibling harnesses this subcommand takes only `--services`. The work runs in a
+ * spawned child that dynamic-imports the head's `createServices` module, keeping
+ * the binary language-agnostic.
+ */
+export function runReflect(options: ReflectCommandOptions): Promise<void> {
+   return runDriverChild(['--max-old-space-size=8192', DRIVER, ...buildReflectDriverArgs(options)], options);
+}

package/src/commands/save-args.ts

@@ -0,0 +1,74 @@
+/********************************************************************************
+ * 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 { runSave, type SaveCommandOptions } from './save.js';
+
+const OWN_FLAGS = ['--uri', '--content', '--client-id'] as const;
+
+/**
+ * Every flag `save` accepts, derived from its own list plus the shared spawn
+ * flags, so the list cannot claim a flag the parser would reject.
+ */
+export const SAVE_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 — and `--content`
+ * is the one where a caller plausibly writes that literal text.
+ */
+export const SAVE_VALUE_FLAGS: readonly string[] = SAVE_FLAGS;
+
+/** The `--help` text, as data, held to {@link SAVE_FLAGS} by a test. */
+export const SAVE_HELP: readonly string[] = [
+   'Usage: hydranium-cli save --server "<cmd>..." --uri <uri> --content <text|@file> [--client-id <id>] [--cwd <dir>] [--log-level <level>]',
+   '',
+   'Update the document at `<uri>` with `<content>` and persist via saveModelDocument.',
+   '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.',
+   '  --log-level <lvl>     Log threshold for the spawned server (off|error|warn|info|debug|trace).'
+];
+
+export function parseSaveArgs(args: string[], onError: UsageError = exitWithUsage): SaveCommandOptions {
+   const { serverCommand, serverArgs, cwd, logLevel, extra } = parseServerSpawnOptions(args, 'save', onError);
+   const { uri, content, clientId } = parseFlagOptions(extra, 'save', OWN_FLAGS, onError);
+   return {
+      serverCommand,
+      serverArgs,
+      cwd,
+      logLevel,
+      uri: assertRequired(uri, '--uri', 'save', onError),
+      content: assertRequired(content, '--content', 'save', onError),
+      clientId
+   };
+}
+
+export function runSaveCommand(args: string[]): Promise<void> {
+   if (helpRequested(args, SAVE_VALUE_FLAGS)) {
+      printHelp(SAVE_HELP);
+      return Promise.resolve();
+   }
+   return runSave(parseSaveArgs(args));
+}

package/src/commands/save.ts

@@ -0,0 +1,84 @@
+/********************************************************************************
+ * 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 * as fs from 'node:fs/promises';
+import { logLevelEnv } from '../log-level.js';
+import { withDataServer } from '../spawn-data-server.js';
+
+/**
+ * Options for the {@link runSave} subcommand. Updates the document at
+ * `uri` with `content` (literal text or `@<path>` for a file reference)
+ * and persists it via the data-server's `saveModelDocument` RPC. Writes
+ * the post-save envelope as a single JSON line — the same shape
+ * `query` emits, so a save's output is consumable by the same `jq`
+ * pipelines.
+ *
+ * `clientId` defaults to `'hydranium-cli'` — adopters wanting a richer
+ * identity (per-user, per-script) override.
+ */
+export interface SaveCommandOptions {
+   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;
+   /** 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 runSave(options: SaveCommandOptions): Promise<void> {
+   const write = options.write ?? ((line: string) => process.stdout.write(line));
+   const clientId = options.clientId ?? 'hydranium-cli';
+   const model = await resolveContent(options.content, options.__readFileForTest);
+
+   if (options.__proxyForTest) {
+      const doc = await options.__proxyForTest.saveModelDocument({ uri: options.uri, clientId, model });
+      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.saveModelDocument({ uri: options.uri, clientId, model });
+         write(`${JSON.stringify(doc)}\n`);
+      }
+   );
+}
+
+/**
+ * Resolve the `--content` argument to its textual form. The `@<path>`
+ * prefix reads from a file (parses as UTF-8); anything else is taken
+ * literally. The leading `@` can be escaped as `\@` for content that
+ * legitimately starts with `@`.
+ */
+async function resolveContent(content: string, readFile?: (path: string) => Promise<string>): Promise<string> {
+   if (content.startsWith('@')) {
+      const path = content.slice(1);
+      const reader = readFile ?? ((target: string) => fs.readFile(target, 'utf8'));
+      return reader(path);
+   }
+   if (content.startsWith('\\@')) {
+      return content.slice(1);
+   }
+   return content;
+}

package/src/commands/validate-args.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 {
+   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 { runValidate, type ValidateCommandOptions } from './validate.js';
+
+const VALUE_FLAGS = [OUT_FILE_FLAG, LOG_LEVEL_FLAG] as const;
+const BOOL_FLAGS = ['--strict', '--json'] as const;
+
+/**
+ * Every flag `validate` 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 VALIDATE_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 VALIDATE_VALUE_FLAGS: readonly string[] = [SERVICES_FLAG, ...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> <workspace> [--strict] [--json] [--out-file <file>] [--log-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',
+   'exporting a zero-arg `createServices(): { shared }` thunk (the head wires its own',
+   'filesystem inside). Needs @hydranium/core.',
+   '',
+   'Options:',
+   '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   '  <workspace>           Workspace root (path or file URI) to validate (required).',
+   '  --strict              Also fail (non-zero exit) on warnings, not only errors.',
+   '  --json                Emit the raw JSON result instead of the human report.',
+   '  --out-file <file>     Write the report to this file instead of stdout. The gate',
+   '                        still decides the exit code, and the file is written only',
+   '                        once the report exists, unlike a shell redirection, which',
+   '                        truncates the file before the workspace is even built.',
+   logLevelHelpLine(22)
+];
+
+export function parseValidateArgs(args: string[], onError: UsageError = exitWithUsage): ValidateCommandOptions {
+   const { servicesModule, workspace, options } = parseHarnessArgs(args, 'validate', VALUE_FLAGS, BOOL_FLAGS, { onError });
+   return {
+      servicesModule,
+      workspace,
+      strict: options['--strict'] === 'true',
+      json: options['--json'] === 'true',
+      outFile: options[OUT_FILE_FLAG],
+      logLevel: logLevelOption(options[LOG_LEVEL_FLAG])
+   };
+}
+
+export function runValidateCommand(args: string[]): Promise<void> {
+   if (helpRequested(args, VALIDATE_VALUE_FLAGS)) {
+      printHelp(VALIDATE_HELP);
+      return Promise.resolve();
+   }
+   return runValidate(parseValidateArgs(args));
+}

package/src/commands/validate-driver.ts

@@ -0,0 +1,84 @@
+/********************************************************************************
+ * 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 `validate` subcommand. Launched by the parent with
+ * `node <this> --services <module> <workspace> [--json] [--strict]
+ * [--out-file <file>]`. It dynamic-imports the head's services module, runs the
+ * framework's `validateWorkspace`, delivers the report (human or `--json`) to
+ * stdout or the named file, and exits with the gate code (non-zero on errors;
+ * `--strict` also fails on warnings). Never imported — only spawned.
+ */
+
+import { emitReport, loadHeadlessContext, OUT_FILE_FLAG } from './headless-harness.js';
+import { formatValidationReport, validationExitCode } from './validate-report.js';
+
+interface DriverArgs {
+   servicesModule?: string;
+   workspace?: string;
+   json: boolean;
+   strict: boolean;
+   outFile?: string;
+}
+
+function parseArgs(argv: string[]): DriverArgs {
+   const parsed: DriverArgs = { json: false, strict: 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 '--strict':
+            parsed.strict = true;
+            break;
+         case OUT_FILE_FLAG:
+            parsed.outFile = next();
+            break;
+         default:
+            if (flag.startsWith('--')) {
+               console.error(`Unknown option: ${flag}`);
+               process.exit(1);
+            }
+            parsed.workspace = flag;
+      }
+   }
+   return parsed;
+}
+
+async function main(argv: string[]): Promise<number> {
+   const args = parseArgs(argv);
+   if (!args.servicesModule || !args.workspace) {
+      console.error('validate-driver: --services <module> and a <workspace> are required.');
+      process.exit(1);
+   }
+   const { createServices, coreNode } = await loadHeadlessContext(args.servicesModule);
+   const result = await coreNode.validateWorkspace({ createServices, workspace: args.workspace });
+   emitReport(formatValidationReport(result, { json: args.json }), args.outFile);
+   return validationExitCode(result, args.strict);
+}
+
+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/validate-report.ts

@@ -0,0 +1,95 @@
+/********************************************************************************
+ * 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 { WorkspaceValidationResult } from '@hydranium/core/node';
+
+/** `s` when `count !== 1`, else empty. */
+function plural(count: number): string {
+   return count === 1 ? '' : 's';
+}
+
+/** `<n> file` / `<n> files`. */
+function fileCount(documents: number): string {
+   return `${documents} file${plural(documents)}`;
+}
+
+/**
+ * The exit code for a validation run: non-zero blocks the CI gate.
+ * Errors always fail; `strict` additionally fails on warnings. Info/hint
+ * findings are advisory and never affect the exit code.
+ */
+export function validationExitCode(result: WorkspaceValidationResult, strict = false): number {
+   if (result.counts.error > 0) {
+      return 1;
+   }
+   if (strict && result.counts.warning > 0) {
+      return 1;
+   }
+   return 0;
+}
+
+/** One-line severity tally over the file count, or the clean-workspace message. */
+function summaryLine(result: WorkspaceValidationResult): string {
+   const { error, warning, info, hint } = result.counts;
+   if (error + warning + info + hint === 0) {
+      return `No problems found in ${fileCount(result.documents)}.`;
+   }
+   const parts: string[] = [];
+   if (error) {
+      parts.push(`${error} error${plural(error)}`);
+   }
+   if (warning) {
+      parts.push(`${warning} warning${plural(warning)}`);
+   }
+   if (info) {
+      parts.push(`${info} info`);
+   }
+   if (hint) {
+      parts.push(`${hint} hint${plural(hint)}`);
+   }
+   return `${parts.join(', ')} in ${fileCount(result.documents)}.`;
+}
+
+/**
+ * Render a validation result for the terminal. `json` emits the raw
+ * {@link WorkspaceValidationResult} (the machine-readable CI contract); the
+ * default is a human report that groups findings by document — one header per
+ * file followed by `line:col  severity  message  (code)` lines — and closes
+ * with the {@link summaryLine} tally.
+ *
+ * Findings arrive already grouped contiguously by document (the framework
+ * collector iterates per document), so a header is emitted whenever the URI
+ * changes rather than pre-bucketing.
+ */
+export function formatValidationReport(result: WorkspaceValidationResult, options: { json?: boolean } = {}): string {
+   if (options.json) {
+      return JSON.stringify(result, undefined, 2);
+   }
+   const lines: string[] = [];
+   let currentUri: string | undefined;
+   for (const finding of result.findings) {
+      if (finding.uri !== currentUri) {
+         if (currentUri !== undefined) {
+            lines.push('');
+         }
+         lines.push(finding.uri);
+         currentUri = finding.uri;
+      }
+      const location = `${finding.line + 1}:${finding.character + 1}`;
+      const code = finding.code !== undefined ? `  (${finding.code})` : '';
+      lines.push(`  ${location.padEnd(7)} ${finding.severity.padEnd(7)} ${finding.message}${code}`);
+   }
+   if (result.findings.length > 0) {
+      lines.push('');
+   }
+   lines.push(summaryLine(result));
+   return lines.join('\n');
+}

package/src/commands/validate.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 { fileURLToPath } from 'node:url';
+import { OUT_FILE_FLAG, runDriverChild, type DriverSpawnOptions } from './headless-harness.js';
+
+/**
+ * Absolute path to the spawned driver. From `lib/commands/validate.js` the
+ * compiled driver sits beside it at `lib/commands/validate-driver.js`.
+ */
+const DRIVER = fileURLToPath(new URL('./validate-driver.js', import.meta.url));
+
+/** Options for the {@link runValidate} subcommand. */
+export interface ValidateCommandOptions extends DriverSpawnOptions {
+   /** ESM module exporting a zero-arg `createServices(): { shared }` thunk. */
+   readonly servicesModule: string;
+   /** Workspace root (filesystem path or file URI) to build and validate. */
+   readonly workspace: string;
+   /** Emit the raw JSON result instead of the human report. */
+   readonly json?: boolean;
+   /** Also fail (non-zero exit) on warnings, not only errors. */
+   readonly strict?: boolean;
+   /** Write the report to this file instead of stdout; the gate still sets the exit code. */
+   readonly outFile?: string;
+}
+
+/** Build the argv the driver child parses. Pure → unit-testable. */
+export function buildValidateDriverArgs(options: ValidateCommandOptions): string[] {
+   const args = ['--services', options.servicesModule, options.workspace];
+   if (options.json) {
+      args.push('--json');
+   }
+   if (options.strict) {
+      args.push('--strict');
+   }
+   if (options.outFile !== undefined) {
+      args.push(OUT_FILE_FLAG, options.outFile);
+   }
+   return args;
+}
+
+/**
+ * Headless workspace validation — a CI gate that builds a workspace, runs the
+ * language's validation checks, prints the diagnostics, and exits non-zero when
+ * any error is found (`--strict` also fails on warnings). Like the other headless
+ * harnesses the binary is language-agnostic, so the head passes a `createServices`
+ * module (`--services`); the work runs in a spawned child that dynamic-imports it.
+ * The child's exit code propagates to this process so shells and CI see the gate.
+ */
+export function runValidate(options: ValidateCommandOptions): Promise<void> {
+   return runDriverChild(['--max-old-space-size=8192', DRIVER, ...buildValidateDriverArgs(options)], options);
+}