@hydranium/cli 1.0.0-next.10

package/lib/commands/model-docs-driver.js

@@ -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
+ ********************************************************************************/
+/*
+ * 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';
+function parseArgs(argv) {
+    const parsed = {};
+    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) {
+    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) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});
+//# sourceMappingURL=model-docs-driver.js.map

package/lib/commands/model-docs-driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-docs-driver.js","sourceRoot":"","sources":["../../src/commands/model-docs-driver.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAOzD,SAAS,SAAS,CAAC,IAAc;IAC9B,MAAM,MAAM,GAAe,EAAE,CAAC;IAC9B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,IAAI,KAAK,YAAY,IAAI,IAAI,KAAK,aAAa,EAAE,CAAC;YACnD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;YAC9B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACvB,OAAO,CAAC,KAAK,CAAC,qBAAqB,IAAI,EAAE,CAAC,CAAC;gBAC3C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACnB,CAAC;YACD,IAAI,IAAI,KAAK,YAAY,EAAE,CAAC;gBACzB,MAAM,CAAC,cAAc,GAAG,KAAK,CAAC;YACjC,CAAC;iBAAM,CAAC;gBACL,MAAM,CAAC,OAAO,GAAG,KAAK,CAAC;YAC1B,CAAC;YACD,KAAK,IAAI,CAAC,CAAC;QACd,CAAC;aAAM,CAAC;YACL,OAAO,CAAC,KAAK,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC;YACzC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACnB,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,IAAI,CAAC,IAAc;IAC/B,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;QACxB,OAAO,CAAC,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACrE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC;IACD,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,GAAG,MAAM,mBAAmB,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IACpF,MAAM,UAAU,GAAG,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC;IAC/D,UAAU,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACtD,OAAO,CAAC,CAAC;AACZ,CAAC;AAED,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;KACvB,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;KAChC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IACvB,OAAO,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACnB,CAAC,CAAC,CAAC"}

package/lib/commands/model-docs-report.d.ts

@@ -0,0 +1,18 @@
+/********************************************************************************
+ * 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 { GrammarReflection } from '@hydranium/core/node';
+/**
+ * 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 declare function formatModelDocs(reflection: GrammarReflection): string;
+//# sourceMappingURL=model-docs-report.d.ts.map

package/lib/commands/model-docs-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-docs-report.d.ts","sourceRoot":"","sources":["../../src/commands/model-docs-report.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,KAAK,EAAE,iBAAiB,EAAkB,MAAM,sBAAsB,CAAC;AAmG9E;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,CAerE"}

package/lib/commands/model-docs-report.js

@@ -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
+ ********************************************************************************/
+/** GitHub-style heading slug: lowercase, non-alphanumerics to hyphens, collapse repeats. */
+function slug(name) {
+    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, known) {
+    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) {
+    return value.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+}
+/** Per-language grammar summary — extensions, entry rule, terminals table. */
+function languageSection(reflection) {
+    const lines = ['## 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) {
+    const lines = [`## 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) {
+    const index = new Map();
+    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, known, referencedBy) {
+    const lines = [`### ${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) {
+    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');
+}
+//# sourceMappingURL=model-docs-report.js.map

package/lib/commands/model-docs-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-docs-report.js","sourceRoot":"","sources":["../../src/commands/model-docs-report.ts"],"names":[],"mappings":"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"}

package/lib/commands/model-docs.d.ts

@@ -0,0 +1,30 @@
+/********************************************************************************
+ * 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 DriverSpawnOptions } from './headless-harness.js';
+/** 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 declare function buildModelDocsDriverArgs(options: ModelDocsCommandOptions): string[];
+/**
+ * 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 declare function runModelDocs(options: ModelDocsCommandOptions): Promise<void>;
+//# sourceMappingURL=model-docs.d.ts.map

package/lib/commands/model-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-docs.d.ts","sourceRoot":"","sources":["../../src/commands/model-docs.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAGlF,OAAO,EAAiC,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAQ/F,uDAAuD;AACvD,MAAM,WAAW,uBAAwB,SAAQ,kBAAkB;IAChE,4EAA4E;IAC5E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,yDAAyD;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,oEAAoE;AACpE,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,EAAE,CAMnF;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5E"}

package/lib/commands/model-docs.js

@@ -0,0 +1,37 @@
+/********************************************************************************
+ * 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 } 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));
+/** Build the argv the driver child parses. Pure → unit-testable. */
+export function buildModelDocsDriverArgs(options) {
+    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) {
+    return runDriverChild(['--max-old-space-size=8192', DRIVER, ...buildModelDocsDriverArgs(options)], options);
+}
+//# sourceMappingURL=model-docs.js.map

package/lib/commands/model-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-docs.js","sourceRoot":"","sources":["../../src/commands/model-docs.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,cAAc,EAA2B,MAAM,uBAAuB,CAAC;AAE/F;;;GAGG;AACH,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,wBAAwB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAUjF,oEAAoE;AACpE,MAAM,UAAU,wBAAwB,CAAC,OAAgC;IACtE,MAAM,IAAI,GAAG,CAAC,YAAY,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACpD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,IAAI,CAAC;AACf,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,OAAgC;IAC1D,OAAO,cAAc,CAAC,CAAC,2BAA2B,EAAE,MAAM,EAAE,GAAG,wBAAwB,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AAC/G,CAAC"}

package/lib/commands/projects-args.d.ts

@@ -0,0 +1,25 @@
+/********************************************************************************
+ * 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 UsageError } from './harness-args.js';
+import { 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 declare const PROJECTS_FLAGS: readonly string[];
+/**
+ * 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 declare const PROJECTS_VALUE_FLAGS: readonly string[];
+/** The `--help` text, as data, held to {@link PROJECTS_FLAGS} by a test. */
+export declare const PROJECTS_HELP: readonly string[];
+export declare function parseProjectsArgs(args: string[], onError?: UsageError): ProjectsCommandOptions;
+export declare function runProjectsCommand(args: string[]): Promise<void>;
+//# sourceMappingURL=projects-args.d.ts.map

package/lib/commands/projects-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projects-args.d.ts","sourceRoot":"","sources":["../../src/commands/projects-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAOJ,KAAK,UAAU,EACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAe,KAAK,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAEzE;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAA6B,CAAC;AAE1E;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAAmB,CAAC;AAEtE,4EAA4E;AAC5E,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAU1C,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,UAA0B,GAAG,sBAAsB,CAQ7G;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhE"}

package/lib/commands/projects-args.js

@@ -0,0 +1,49 @@
+/********************************************************************************
+ * 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 } from './harness-args.js';
+import { runProjects } 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 = 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 = PROJECTS_FLAGS;
+/** The `--help` text, as data, held to {@link PROJECTS_FLAGS} by a test. */
+export const PROJECTS_HELP = [
+    '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, onError = exitWithUsage) {
+    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) {
+    if (helpRequested(args, PROJECTS_VALUE_FLAGS)) {
+        printHelp(PROJECTS_HELP);
+        return Promise.resolve();
+    }
+    return runProjects(parseProjectsArgs(args));
+}
+//# sourceMappingURL=projects-args.js.map

package/lib/commands/projects-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projects-args.js","sourceRoot":"","sources":["../../src/commands/projects-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,uBAAuB,EACvB,SAAS,EACT,wBAAwB,EAE1B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,WAAW,EAA+B,MAAM,eAAe,CAAC;AAEzE;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAsB,wBAAwB,CAAC;AAE1E;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAsB,cAAc,CAAC;AAEtE,4EAA4E;AAC5E,MAAM,CAAC,MAAM,aAAa,GAAsB;IAC7C,8FAA8F;IAC9F,EAAE;IACF,kFAAkF;IAClF,uCAAuC;IACvC,EAAE;IACF,UAAU;IACV,8EAA8E;IAC9E,6EAA6E;IAC7E,8FAA8F;CAChG,CAAC;AAEF,MAAM,UAAU,iBAAiB,CAAC,IAAc,EAAE,UAAsB,aAAa;IAClF,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,uBAAuB,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IAC/G,wEAAwE;IACxE,0EAA0E;IAC1E,4EAA4E;IAC5E,wDAAwD;IACxD,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;IACjD,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAc;IAC9C,IAAI,aAAa,CAAC,IAAI,EAAE,oBAAoB,CAAC,EAAE,CAAC;QAC7C,SAAS,CAAC,aAAa,CAAC,CAAC;QACzB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO,WAAW,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/C,CAAC"}

package/lib/commands/projects.d.ts

@@ -0,0 +1,45 @@
+/********************************************************************************
+ * 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';
+/**
+ * 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 declare function runProjects(options: ProjectsCommandOptions): Promise<void>;
+//# sourceMappingURL=projects.d.ts.map

package/lib/commands/projects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projects.d.ts","sourceRoot":"","sources":["../../src/commands/projects.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,YAAY,EAAW,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAInE;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACpC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;CAChE;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBhF"}

package/lib/commands/projects.js

@@ -0,0 +1,39 @@
+/********************************************************************************
+ * 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 { logLevelEnv } from '../log-level.js';
+import { withDataServer } from '../spawn-data-server.js';
+/**
+ * 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) {
+    const write = options.write ?? ((line) => 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, write) {
+    for (const project of projects) {
+        write(`${JSON.stringify(project)}\n`);
+    }
+}
+//# sourceMappingURL=projects.js.map

package/lib/commands/projects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projects.js","sourceRoot":"","sources":["../../src/commands/projects.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AA8BzD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAA+B;IAC9D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IAE9E,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;QAC1B,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,WAAW,EAAE,CAAC;QAC5D,aAAa,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC/B,OAAO;IACV,CAAC;IAED,MAAM,cAAc,CACjB;QACG,OAAO,EAAE,OAAO,CAAC,aAAa;QAC9B,IAAI,EAAE,OAAO,CAAC,UAAU;QACxB,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS;KACnE,EACD,KAAK,EAAC,MAAM,EAAC,EAAE;QACZ,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,WAAW,EAAE,CAAC;QAC5C,aAAa,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC,CACH,CAAC;AACL,CAAC;AAED,SAAS,aAAa,CAAC,QAA4B,EAAE,KAA6B;IAC/E,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC9B,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;AACJ,CAAC"}

package/lib/commands/query-args.d.ts

@@ -0,0 +1,25 @@
+/********************************************************************************
+ * 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 UsageError } from './harness-args.js';
+import { type QueryCommandOptions } from './query.js';
+/**
+ * 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 declare const QUERY_FLAGS: readonly string[];
+/**
+ * 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 declare const QUERY_VALUE_FLAGS: readonly string[];
+/** The `--help` text, as data, held to {@link QUERY_FLAGS} by a test. */
+export declare const QUERY_HELP: readonly string[];
+export declare function parseQueryArgs(args: string[], onError?: UsageError): QueryCommandOptions;
+export declare function runQueryCommand(args: string[]): Promise<void>;
+//# sourceMappingURL=query-args.d.ts.map

package/lib/commands/query-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-args.d.ts","sourceRoot":"","sources":["../../src/commands/query-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAQJ,KAAK,UAAU,EACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAY,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAIhE;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,MAAM,EAAgD,CAAC;AAE1F;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAAgB,CAAC;AAEhE,yEAAyE;AACzE,eAAO,MAAM,UAAU,EAAE,SAAS,MAAM,EAUvC,CAAC;AAEF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,UAA0B,GAAG,mBAAmB,CAIvG;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAM7D"}

package/lib/commands/query-args.js

@@ -0,0 +1,46 @@
+/********************************************************************************
+ * 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 } from './harness-args.js';
+import { runQuery } from './query.js';
+const OWN_FLAGS = ['--uri'];
+/**
+ * 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 = [...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 = QUERY_FLAGS;
+/** The `--help` text, as data, held to {@link QUERY_FLAGS} by a test. */
+export const QUERY_HELP = [
+    '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, onError = exitWithUsage) {
+    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) {
+    if (helpRequested(args, QUERY_VALUE_FLAGS)) {
+        printHelp(QUERY_HELP);
+        return Promise.resolve();
+    }
+    return runQuery(parseQueryArgs(args));
+}
+//# sourceMappingURL=query-args.js.map

package/lib/commands/query-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-args.js","sourceRoot":"","sources":["../../src/commands/query-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,cAAc,EACd,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,uBAAuB,EACvB,SAAS,EACT,wBAAwB,EAE1B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,QAAQ,EAA4B,MAAM,YAAY,CAAC;AAEhE,MAAM,SAAS,GAAG,CAAC,OAAO,CAAU,CAAC;AAErC;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAsB,CAAC,GAAG,wBAAwB,EAAE,GAAG,SAAS,CAAC,CAAC;AAE1F;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAsB,WAAW,CAAC;AAEhE,yEAAyE;AACzE,MAAM,CAAC,MAAM,UAAU,GAAsB;IAC1C,uGAAuG;IACvG,EAAE;IACF,4EAA4E;IAC5E,EAAE;IACF,UAAU;IACV,8EAA8E;IAC9E,+CAA+C;IAC/C,6EAA6E;IAC7E,8FAA8F;CAChG,CAAC;AAEF,MAAM,UAAU,cAAc,CAAC,IAAc,EAAE,UAAsB,aAAa;IAC/E,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,uBAAuB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC5G,MAAM,EAAE,GAAG,EAAE,GAAG,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IACrE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC;AAC5G,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAc;IAC3C,IAAI,aAAa,CAAC,IAAI,EAAE,iBAAiB,CAAC,EAAE,CAAC;QAC1C,SAAS,CAAC,UAAU,CAAC,CAAC;QACtB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;AACzC,CAAC"}

package/lib/commands/query.d.ts

@@ -0,0 +1,32 @@
+/********************************************************************************
+ * 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';
+/**
+ * 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 declare function runQuery(options: QueryCommandOptions): Promise<void>;
+//# sourceMappingURL=query.d.ts.map

package/lib/commands/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/commands/query.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAInE;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,cAAc,CAAC,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;CAChE;AAED,wBAAsB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB1E"}

package/lib/commands/query.js

@@ -0,0 +1,29 @@
+/********************************************************************************
+ * 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 { logLevelEnv } from '../log-level.js';
+import { withDataServer } from '../spawn-data-server.js';
+export async function runQuery(options) {
+    const write = options.write ?? ((line) => 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`);
+    });
+}
+//# sourceMappingURL=query.js.map