@hydranium/cli 1.0.0-next.10

package/src/commands/lint-grammar-driver.ts

@@ -0,0 +1,83 @@
+/********************************************************************************
+ * 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 `lint-grammar` subcommand. Launched by the parent with
+ * `node <this> --services <module> [--name-property <p>]... [--json] [--strict]`.
+ * It dynamic-imports the head's services module, runs the framework's
+ * `lintGrammar`, prints the report (human or `--json`) and exits with the gate
+ * code (non-zero on errors; `--strict` also fails on warnings). Never imported —
+ * only spawned.
+ */
+
+import { loadHeadlessContext } from './headless-harness.js';
+import { formatLintReport, lintExitCode } from './lint-grammar-report.js';
+
+interface DriverArgs {
+   servicesModule?: string;
+   nameProperties: string[];
+   json: boolean;
+   strict: boolean;
+}
+
+function parseArgs(argv: string[]): DriverArgs {
+   const parsed: DriverArgs = { nameProperties: [], 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 '--name-property':
+            parsed.nameProperties.push(next());
+            break;
+         case '--json':
+            parsed.json = true;
+            break;
+         case '--strict':
+            parsed.strict = true;
+            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('lint-grammar-driver: --services <module> is required.');
+      process.exit(1);
+   }
+   const { createServices, coreNode } = await loadHeadlessContext(args.servicesModule);
+   const result = coreNode.lintGrammar({
+      createServices,
+      nameProperties: args.nameProperties.length ? args.nameProperties : undefined
+   });
+   console.log(formatLintReport(result, { json: args.json }));
+   return lintExitCode(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/lint-grammar-report.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
+ ********************************************************************************/
+
+// 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 { GrammarLintResult } from '@hydranium/core/node';
+
+/** `s` when `count !== 1`, else empty. */
+function plural(count: number): string {
+   return count === 1 ? '' : 's';
+}
+
+/**
+ * The exit code for a lint run: non-zero blocks the CI gate. Errors always fail;
+ * `strict` additionally fails on warnings.
+ */
+export function lintExitCode(result: GrammarLintResult, strict = false): number {
+   if (result.counts.error > 0) {
+      return 1;
+   }
+   if (strict && result.counts.warning > 0) {
+      return 1;
+   }
+   return 0;
+}
+
+/** One-line severity tally, or the clean-grammar message. */
+function summaryLine(result: GrammarLintResult): string {
+   const { error, warning } = result.counts;
+   if (error + warning === 0) {
+      // "target type", not "target": the tally counts distinct TYPES reachable
+      // as a cross-reference target, not cross-reference properties. Several
+      // references can share one target type, so the bare word reads as though
+      // the lint had missed the rest.
+      return `No grammar-convention problems found (${result.checkedReferenceTargets} reference target type${plural(
+         result.checkedReferenceTargets
+      )} checked).`;
+   }
+   const parts: string[] = [];
+   if (error) {
+      parts.push(`${error} error${plural(error)}`);
+   }
+   if (warning) {
+      parts.push(`${warning} warning${plural(warning)}`);
+   }
+   return `${parts.join(', ')}.`;
+}
+
+/**
+ * Render a grammar-convention lint result for the terminal. `json` emits the raw
+ * {@link GrammarLintResult} (the machine-readable CI contract); the default is a
+ * human report — one `severity  [rule]  message` line per finding — closing with
+ * the {@link summaryLine} tally.
+ */
+export function formatLintReport(result: GrammarLintResult, options: { json?: boolean } = {}): string {
+   if (options.json) {
+      return JSON.stringify(result, undefined, 2);
+   }
+   const lines: string[] = [];
+   for (const finding of result.findings) {
+      lines.push(`  ${finding.severity.padEnd(7)} [${finding.rule}] ${finding.message}`);
+   }
+   if (result.findings.length > 0) {
+      lines.push('');
+   }
+   lines.push(summaryLine(result));
+   return lines.join('\n');
+}

package/src/commands/lint-grammar.ts

@@ -0,0 +1,57 @@
+/********************************************************************************
+ * 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 { runDriverChild, type DriverSpawnOptions } from './headless-harness.js';
+
+/**
+ * Absolute path to the spawned driver. From `lib/commands/lint-grammar.js` the
+ * compiled driver sits beside it at `lib/commands/lint-grammar-driver.js`.
+ */
+const DRIVER = fileURLToPath(new URL('./lint-grammar-driver.js', import.meta.url));
+
+/** Options for the {@link runLintGrammar} subcommand. */
+export interface LintGrammarCommandOptions extends DriverSpawnOptions {
+   /** ESM module exporting a zero-arg `createServices(): { shared }` thunk. */
+   readonly servicesModule: string;
+   /** Property names that satisfy the nameability convention. Empty → the framework default `name`. */
+   readonly nameProperties?: readonly 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;
+}
+
+/** Build the argv the driver child parses. Pure → unit-testable. */
+export function buildLintGrammarDriverArgs(options: LintGrammarCommandOptions): string[] {
+   const args = ['--services', options.servicesModule];
+   for (const property of options.nameProperties ?? []) {
+      args.push('--name-property', property);
+   }
+   if (options.json) {
+      args.push('--json');
+   }
+   if (options.strict) {
+      args.push('--strict');
+   }
+   return args;
+}
+
+/**
+ * Headless grammar-convention lint — a CI gate that checks a head's grammar against
+ * the framework's expectations (nameable cross-reference targets, an entry rule) and
+ * exits non-zero when a violation is found (`--strict` also fails on warnings).
+ * Read-only: no workspace is built (the reflection is static once the head registers
+ * its language), so this subcommand takes only `--services` and the name-property
+ * overrides. The work runs in a spawned child that dynamic-imports the head's
+ * `createServices` module, keeping the binary language-agnostic.
+ */
+export function runLintGrammar(options: LintGrammarCommandOptions): Promise<void> {
+   return runDriverChild(['--max-old-space-size=8192', DRIVER, ...buildLintGrammarDriverArgs(options)], options);
+}

package/src/commands/measure-memory-args.ts

@@ -0,0 +1,123 @@
+/********************************************************************************
+ * 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,
+   numericOption,
+   parseHarnessArgs,
+   printHelp,
+   SERVICES_FLAG,
+   type UsageError
+} from './harness-args.js';
+import { parseProfileDimensions, runMeasureMemory, type MeasureMemoryCommandOptions } from './measure-memory.js';
+
+const VALUE_FLAGS = [
+   '--edits',
+   '--edit-docs',
+   '--churn-suffix',
+   '--settle',
+   '--snapshot-path',
+   '--profile',
+   '--session-out',
+   LOG_LEVEL_FLAG
+] as const;
+const BOOL_FLAGS = ['--snapshot', '--json'] as const;
+
+/**
+ * Every flag `measure-memory` 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 MEASURE_MEMORY_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 MEASURE_MEMORY_VALUE_FLAGS: readonly string[] = [SERVICES_FLAG, ...VALUE_FLAGS];
+
+/** The `--help` text, as data, held to {@link MEASURE_MEMORY_FLAGS} by a test. */
+export const MEASURE_MEMORY_HELP: readonly string[] = [
+   'Usage: hydranium-cli measure-memory --services <module> <workspace> [options]',
+   '',
+   'Measure model-store memory for a workspace. `<module>` is an ESM module that',
+   'exports a zero-arg `createServices(): { shared }` thunk (the head wires its own',
+   'filesystem inside). Runs in a `--expose-gc` child for post-GC readings; the',
+   'baseline / after-build / churn lines print on stdout. Needs @hydranium/core.',
+   '',
+   'Options:',
+   '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   '  <workspace>           Workspace root (path or file URI) to build (required).',
+   '  --edits <N>           Rebuild-churn cycles to probe for retention. Default: 0 (skip).',
+   '  --edit-docs <N>       Documents to churn per cycle. Default: 25.',
+   '  --churn-suffix <ext>  Only churn documents whose URI ends with this suffix.',
+   '  --settle <ms>         Wait <ms> after the build before measuring, so a',
+   '                        timer-driven residency policy (shed-closed-when-idle)',
+   "                        sheds first. Pass above the policy's idleMs; omit to",
+   '                        measure the pre-shed (always-keep) baseline.',
+   '  --snapshot            Write a `.heapsnapshot` after the build.',
+   '  --snapshot-path <p>   Snapshot path. Default: <cwd>/<workspace-basename>.heapsnapshot.',
+   '  --profile <dims>      Capture sampled profiles around the build (+churn) into a',
+   '                        profiling session. Comma-separated: cpu,alloc,gc,eld,heap.',
+   '  --session-out <dir>   Parent directory for the profiling session folder (with --profile).',
+   '  --json                Emit the measurement as one JSON document instead of the',
+   '                        progress lines: documentCount, buildMs, emptyHeapBytes,',
+   '                        afterBuildHeapBytes, and churnGrowthBytes / snapshotPath /',
+   '                        profilingSession where the run produced them.',
+   logLevelHelpLine(22)
+];
+
+/**
+ * Validate `--profile` in the PARENT, where the numeric flags beside it are
+ * already validated.
+ *
+ * Returns the RAW string rather than the parsed dimensions on purpose: the child
+ * re-parses them, because that is where they are used, and this exists only so a
+ * typo fails as a usage error before a process is spawned and a whole head
+ * imported. Parsing here and passing the result would change what crosses to the
+ * child for no gain.
+ */
+function validatedProfile(csv: string | undefined, onError: UsageError): string | undefined {
+   if (csv === undefined) {
+      return undefined;
+   }
+   try {
+      parseProfileDimensions(csv);
+   } catch (err: unknown) {
+      onError(`Option --profile: ${err instanceof Error ? err.message : String(err)}`);
+   }
+   return csv;
+}
+
+export function parseMeasureMemoryArgs(args: string[], onError: UsageError = exitWithUsage): MeasureMemoryCommandOptions {
+   const { servicesModule, workspace, options } = parseHarnessArgs(args, 'measure-memory', VALUE_FLAGS, BOOL_FLAGS, { onError });
+   return {
+      servicesModule,
+      workspace,
+      editCycles: numericOption(options['--edits'], '--edits', onError),
+      editDocs: numericOption(options['--edit-docs'], '--edit-docs', onError),
+      churnSuffix: options['--churn-suffix'],
+      settleMs: numericOption(options['--settle'], '--settle', onError),
+      writeSnapshot: options['--snapshot'] === 'true',
+      snapshotPath: options['--snapshot-path'],
+      profile: validatedProfile(options['--profile'], onError),
+      sessionOut: options['--session-out'],
+      json: options['--json'] === 'true',
+      logLevel: logLevelOption(options[LOG_LEVEL_FLAG])
+   };
+}
+
+export function runMeasureMemoryCommand(args: string[]): Promise<void> {
+   if (helpRequested(args, MEASURE_MEMORY_VALUE_FLAGS)) {
+      printHelp(MEASURE_MEMORY_HELP);
+      return Promise.resolve();
+   }
+   return runMeasureMemory(parseMeasureMemoryArgs(args));
+}

package/src/commands/measure-memory-driver.ts

@@ -0,0 +1,128 @@
+/********************************************************************************
+ * 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 `measure-memory` subcommand. Launched by the parent with
+ * `node --expose-gc --max-old-space-size=8192 <this> --services <module> <workspace> ...`
+ * so the underlying harness gets post-GC readings. It dynamic-imports the head's
+ * services module and runs the framework's `measureModelMemory`, streaming the
+ * baseline / after-build / churn lines to stdout. Never imported — only spawned.
+ */
+
+import { loadHeadlessContext } from './headless-harness.js';
+import { parseProfileDimensions } from './measure-memory.js';
+
+interface DriverArgs {
+   servicesModule?: string;
+   workspace?: string;
+   editCycles?: number;
+   editDocs?: number;
+   churnDocSuffix?: string;
+   settleMs?: number;
+   writeSnapshot: boolean;
+   snapshotPath?: string;
+   profile?: string;
+   sessionOut?: string;
+   json: boolean;
+}
+
+function parseArgs(argv: string[]): DriverArgs {
+   const parsed: DriverArgs = { writeSnapshot: false, 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 '--edits':
+            parsed.editCycles = Number(next());
+            break;
+         case '--edit-docs':
+            parsed.editDocs = Number(next());
+            break;
+         case '--churn-suffix':
+            parsed.churnDocSuffix = next();
+            break;
+         case '--settle':
+            parsed.settleMs = Number(next());
+            break;
+         case '--snapshot':
+            parsed.writeSnapshot = true;
+            break;
+         case '--snapshot-path':
+            parsed.snapshotPath = next();
+            break;
+         case '--profile':
+            parsed.profile = next();
+            break;
+         case '--session-out':
+            parsed.sessionOut = next();
+            break;
+         case '--json':
+            parsed.json = true;
+            break;
+         default:
+            if (flag.startsWith('--')) {
+               console.error(`Unknown option: ${flag}`);
+               process.exit(1);
+            }
+            parsed.workspace = flag;
+      }
+   }
+   return parsed;
+}
+
+async function main(argv: string[]): Promise<void> {
+   const args = parseArgs(argv);
+   if (!args.servicesModule || !args.workspace) {
+      console.error('measure-memory-driver: --services <module> and a <workspace> are required.');
+      process.exit(1);
+   }
+   const { createServices, coreNode } = await loadHeadlessContext(args.servicesModule);
+   const result = await coreNode.measureModelMemory({
+      createServices,
+      workspace: args.workspace,
+      editCycles: args.editCycles,
+      editDocs: args.editDocs,
+      churnDocSuffix: args.churnDocSuffix,
+      settleMs: args.settleMs,
+      writeSnapshot: args.writeSnapshot,
+      snapshotPath: args.snapshotPath,
+      profile: args.profile ? parseProfileDimensions(args.profile) : undefined,
+      sessionOut: args.sessionOut,
+      // Omitted under `--json` rather than redirected: every progress line would
+      // otherwise land on the same stream as the document, so the caller's
+      // `JSON.parse` would see a preamble it has no way to bound.
+      log: args.json ? undefined : line => console.log(line)
+   });
+   if (args.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+   }
+   console.log(`SUMMARY: docs=${result.documentCount} build=${Math.round(result.buildMs)}ms`);
+   if (result.profilingSession) {
+      console.log(`SESSION: ${result.profilingSession}`);
+   }
+}
+
+main(process.argv.slice(2))
+   .then(() => process.exit(0))
+   .catch((error: unknown) => {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+   });

package/src/commands/measure-memory.ts

@@ -0,0 +1,143 @@
+/********************************************************************************
+ * 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 { ProfileCaptureOptions } from '@hydranium/core/node';
+import { fileURLToPath } from 'node:url';
+import { runDriverChild, type DriverSpawnOptions } from './headless-harness.js';
+
+/**
+ * Absolute path to the spawned driver. From `lib/commands/measure-memory.js`
+ * the compiled driver sits beside it at `lib/commands/measure-memory-driver.js`.
+ */
+const DRIVER = fileURLToPath(new URL('./measure-memory-driver.js', import.meta.url));
+
+/** Options for the {@link runMeasureMemory} subcommand. */
+export interface MeasureMemoryCommandOptions extends DriverSpawnOptions {
+   /** ESM module exporting a zero-arg `createServices(): { shared }` thunk. */
+   readonly servicesModule: string;
+   /** Workspace root (filesystem path or file URI) to build. */
+   readonly workspace: string;
+   /** Rebuild-churn cycles to probe for retention (default 0 = skip). */
+   readonly editCycles?: number;
+   /** Documents to churn per cycle. */
+   readonly editDocs?: number;
+   /** Only churn documents whose URI path ends with this suffix. */
+   readonly churnSuffix?: string;
+   /**
+    * Wait this many milliseconds after the build before measuring, so a
+    * timer-driven residency policy (`CstResidencyService`'s
+    * `shed-closed-when-idle`) sheds before the reading is taken. Pass a value
+    * comfortably above the policy's `idleMs`; omit (or `0`) to measure the
+    * pre-shed heap (the always-keep-equivalent baseline).
+    */
+   readonly settleMs?: number;
+   /** Write a `.heapsnapshot` after the build. */
+   readonly writeSnapshot?: boolean;
+   /** Snapshot path (default `<cwd>/<workspace-basename>.heapsnapshot`). */
+   readonly snapshotPath?: string;
+   /** Comma-separated profile dimensions to capture; see {@link parseProfileDimensions} for the tokens. */
+   readonly profile?: string;
+   /** Parent directory for the profiling session folder. Only used with {@link profile}. */
+   readonly sessionOut?: string;
+   /**
+    * Emit the `MeasureModelMemoryResult` as JSON instead of the progress lines.
+    *
+    * The progress lines are suppressed rather than kept alongside it, because the
+    * flag exists so a script can read stdout as one document — a preamble on the
+    * same stream would leave every caller stripping it by hand.
+    */
+   readonly json?: boolean;
+}
+
+/**
+ * Parse a `--profile` dimension list (`cpu,alloc,gc,eld,heap`) into
+ * {@link ProfileCaptureOptions}. Case- and whitespace-tolerant; throws on an
+ * unknown token so a typo fails loud rather than silently capturing nothing.
+ */
+export function parseProfileDimensions(csv: string): ProfileCaptureOptions {
+   const options: ProfileCaptureOptions = {};
+   for (const raw of csv.split(',')) {
+      const token = raw.trim().toLowerCase();
+      if (!token) {
+         continue;
+      }
+      switch (token) {
+         case 'cpu':
+            options.cpu = true;
+            break;
+         case 'alloc':
+         case 'allocation':
+            options.allocation = true;
+            break;
+         case 'gc':
+            options.gc = true;
+            break;
+         case 'eld':
+         case 'eventloop':
+         case 'event-loop':
+            options.eventLoopDelay = true;
+            break;
+         case 'heap':
+         case 'heapsnapshot':
+            options.heapSnapshot = true;
+            break;
+         default:
+            throw new Error(`Unknown profile dimension: ${token} (expected cpu, alloc, gc, eld, heap)`);
+      }
+   }
+   return options;
+}
+
+/**
+ * Build the argv the driver child parses. Pure → unit-testable; mirrors the
+ * driver's own option names.
+ */
+export function buildDriverArgs(options: MeasureMemoryCommandOptions): string[] {
+   const args = ['--services', options.servicesModule, options.workspace];
+   if (options.editCycles !== undefined) {
+      args.push('--edits', String(options.editCycles));
+   }
+   if (options.editDocs !== undefined) {
+      args.push('--edit-docs', String(options.editDocs));
+   }
+   if (options.churnSuffix !== undefined) {
+      args.push('--churn-suffix', options.churnSuffix);
+   }
+   if (options.settleMs !== undefined) {
+      args.push('--settle', String(options.settleMs));
+   }
+   if (options.writeSnapshot) {
+      args.push('--snapshot');
+   }
+   if (options.snapshotPath !== undefined) {
+      args.push('--snapshot-path', options.snapshotPath);
+   }
+   if (options.profile !== undefined) {
+      args.push('--profile', options.profile);
+   }
+   if (options.sessionOut !== undefined) {
+      args.push('--session-out', options.sessionOut);
+   }
+   if (options.json) {
+      args.push('--json');
+   }
+   return args;
+}
+
+/**
+ * Headless model-store memory measurement. `hydranium-cli` is language-agnostic
+ * and cannot import a head's `create<Lang>Services`, so the head passes a module
+ * that exports a zero-arg `createServices` thunk (`--services`). Because the
+ * underlying `measureModelMemory` harness needs post-GC readings, the work runs
+ * in a spawned child launched with `--expose-gc`; the driver dynamic-imports the
+ * module and reports the baseline / after-build / churn lines on stdout.
+ */
+export function runMeasureMemory(options: MeasureMemoryCommandOptions): Promise<void> {
+   return runDriverChild(['--expose-gc', '--max-old-space-size=8192', DRIVER, ...buildDriverArgs(options)], options);
+}

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

@@ -0,0 +1,69 @@
+/********************************************************************************
+ * 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 { runModelDocs, type ModelDocsCommandOptions } from './model-docs.js';
+
+const VALUE_FLAGS = [OUT_FILE_FLAG, LOG_LEVEL_FLAG] as const;
+
+/**
+ * Every flag `model-docs` 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 MODEL_DOCS_FLAGS: readonly string[] = [SERVICES_FLAG, ...VALUE_FLAGS];
+
+/** The subset that takes a value, so `--help` in a value position reads as data. */
+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> [--out-file <file>] [--log-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',
+   'grammar summary — for publishing into adopter docs. Read-only: no workspace is',
+   'built. Emits Markdown on stdout, or into `--out-file`; the machine-readable form',
+   'is `hydranium-cli reflect --json`. `<module>` is an ESM module exporting a',
+   'zero-arg `createServices(): { shared }` thunk. Needs @hydranium/core.',
+   '',
+   'Options:',
+   '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   '  --out-file <file>     Write the Markdown 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 parseModelDocsArgs(args: string[], onError: UsageError = exitWithUsage): ModelDocsCommandOptions {
+   const { servicesModule, options } = parseHarnessArgs(args, 'model-docs', VALUE_FLAGS, [], {
+      requireWorkspace: false,
+      onError
+   });
+   return { servicesModule, outFile: options[OUT_FILE_FLAG], logLevel: logLevelOption(options[LOG_LEVEL_FLAG]) };
+}
+
+export function runModelDocsCommand(args: string[]): Promise<void> {
+   if (helpRequested(args, MODEL_DOCS_VALUE_FLAGS)) {
+      printHelp(MODEL_DOCS_HELP);
+      return Promise.resolve();
+   }
+   return runModelDocs(parseModelDocsArgs(args));
+}