@hydranium/cli 1.0.0-next.10

package/lib/commands/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/commands/query.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAuBzD,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,OAA4B;IACxD,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,+FAA+F;QAC/F,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,gBAAgB,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1G,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClC,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,GAAG,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1F,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC,CACH,CAAC;AACL,CAAC"}

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

@@ -0,0 +1,23 @@
+/********************************************************************************
+ * 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 ReflectCommandOptions } from './reflect.js';
+/**
+ * Every flag `reflect` accepts, derived from the sets the parser is handed so
+ * the list cannot claim a flag the parser would reject. `--services` is consumed
+ * by the shared harness parser itself, so it is in neither set.
+ */
+export declare const REFLECT_FLAGS: readonly string[];
+/** The subset that takes a value, so `--help` in a value position reads as data. */
+export declare const REFLECT_VALUE_FLAGS: readonly string[];
+/** The `--help` text, as data, held to {@link REFLECT_FLAGS} by a test. */
+export declare const REFLECT_HELP: readonly string[];
+export declare function parseReflectArgs(args: string[], onError?: UsageError): ReflectCommandOptions;
+export declare function runReflectCommand(args: string[]): Promise<void>;
+//# sourceMappingURL=reflect-args.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reflect-args.d.ts","sourceRoot":"","sources":["../../src/commands/reflect-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EASJ,KAAK,UAAU,EACjB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAc,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAKtE;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAAmD,CAAC;AAE/F,oFAAoF;AACpF,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAAoC,CAAC;AAEtF,2EAA2E;AAC3E,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAgBzC,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,UAA0B,GAAG,qBAAqB,CAW3G;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAM/D"}

package/lib/commands/reflect-args.js

@@ -0,0 +1,59 @@
+/********************************************************************************
+ * 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 } from './harness-args.js';
+import { OUT_FILE_FLAG } from './headless-harness.js';
+import { runReflect } from './reflect.js';
+const VALUE_FLAGS = [OUT_FILE_FLAG, LOG_LEVEL_FLAG];
+const BOOL_FLAGS = ['--json'];
+/**
+ * Every flag `reflect` accepts, derived from the sets the parser is handed so
+ * the list cannot claim a flag the parser would reject. `--services` is consumed
+ * by the shared harness parser itself, so it is in neither set.
+ */
+export const REFLECT_FLAGS = [SERVICES_FLAG, ...VALUE_FLAGS, ...BOOL_FLAGS];
+/** The subset that takes a value, so `--help` in a value position reads as data. */
+export const REFLECT_VALUE_FLAGS = [SERVICES_FLAG, ...VALUE_FLAGS];
+/** The `--help` text, as data, held to {@link REFLECT_FLAGS} by a test. */
+export const REFLECT_HELP = [
+    'Usage: hydranium-cli reflect --services <module> [--json] [--out-file <file>] [--log-level <lvl>]',
+    '',
+    "Dump a head's grammar/AST reflection — the type hierarchy, each language's",
+    'terminals and entry rule, and every cross-reference target. Read-only: no',
+    'workspace is built (the reflection is static once the head registers its',
+    'language), so `reflect` takes no `<workspace>`. `<module>` is an ESM module',
+    'exporting a zero-arg `createServices(): { shared }` thunk. Needs @hydranium/core.',
+    '',
+    'Options:',
+    '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+    '  --json                Emit the raw JSON reflection instead of the Markdown report.',
+    '  --out-file <file>     Write the report to this file instead of stdout. Written',
+    '                        only once the report exists, unlike a shell redirection,',
+    '                        which truncates the file before the head is even booted.',
+    logLevelHelpLine(22)
+];
+export function parseReflectArgs(args, onError = exitWithUsage) {
+    const { servicesModule, options } = parseHarnessArgs(args, 'reflect', VALUE_FLAGS, BOOL_FLAGS, {
+        requireWorkspace: false,
+        onError
+    });
+    return {
+        servicesModule,
+        json: options['--json'] === 'true',
+        outFile: options[OUT_FILE_FLAG],
+        logLevel: logLevelOption(options[LOG_LEVEL_FLAG])
+    };
+}
+export function runReflectCommand(args) {
+    if (helpRequested(args, REFLECT_VALUE_FLAGS)) {
+        printHelp(REFLECT_HELP);
+        return Promise.resolve();
+    }
+    return runReflect(parseReflectArgs(args));
+}
+//# sourceMappingURL=reflect-args.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reflect-args.js","sourceRoot":"","sources":["../../src/commands/reflect-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,aAAa,EACb,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,SAAS,EACT,aAAa,EAEf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,UAAU,EAA8B,MAAM,cAAc,CAAC;AAEtE,MAAM,WAAW,GAAG,CAAC,aAAa,EAAE,cAAc,CAAU,CAAC;AAC7D,MAAM,UAAU,GAAG,CAAC,QAAQ,CAAU,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAsB,CAAC,aAAa,EAAE,GAAG,WAAW,EAAE,GAAG,UAAU,CAAC,CAAC;AAE/F,oFAAoF;AACpF,MAAM,CAAC,MAAM,mBAAmB,GAAsB,CAAC,aAAa,EAAE,GAAG,WAAW,CAAC,CAAC;AAEtF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,YAAY,GAAsB;IAC5C,mGAAmG;IACnG,EAAE;IACF,4EAA4E;IAC5E,2EAA2E;IAC3E,0EAA0E;IAC1E,6EAA6E;IAC7E,mFAAmF;IACnF,EAAE;IACF,UAAU;IACV,yFAAyF;IACzF,sFAAsF;IACtF,kFAAkF;IAClF,kFAAkF;IAClF,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,UAAU,gBAAgB,CAAC,IAAc,EAAE,UAAsB,aAAa;IACjF,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE;QAC5F,gBAAgB,EAAE,KAAK;QACvB,OAAO;KACT,CAAC,CAAC;IACH,OAAO;QACJ,cAAc;QACd,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,MAAM;QAClC,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC;QAC/B,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;KACnD,CAAC;AACL,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAc;IAC7C,IAAI,aAAa,CAAC,IAAI,EAAE,mBAAmB,CAAC,EAAE,CAAC;QAC5C,SAAS,CAAC,YAAY,CAAC,CAAC;QACxB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO,UAAU,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;AAC7C,CAAC"}

package/lib/commands/reflect-driver.d.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+export {};
+//# sourceMappingURL=reflect-driver.d.ts.map

package/lib/commands/reflect-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflect-driver.d.ts","sourceRoot":"","sources":["../../src/commands/reflect-driver.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF"}

package/lib/commands/reflect-driver.js

@@ -0,0 +1,66 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+/*
+ * Spawned child of the `reflect` subcommand. Launched by the parent with
+ * `node <this> --services <module> [--json] [--out-file <file>]`. It
+ * dynamic-imports the head's services module, runs the framework's
+ * `reflectGrammar`, and delivers the report (markdown or `--json`) to stdout or
+ * the named file. Read-only — exits 0 unless booting the head throws. Never
+ * imported — only spawned.
+ */
+import { emitReport, loadHeadlessContext, OUT_FILE_FLAG } from './headless-harness.js';
+import { formatReflectionReport } from './reflect-report.js';
+function parseArgs(argv) {
+    const parsed = { json: false };
+    for (let index = 0; index < argv.length; index += 1) {
+        const flag = argv[index];
+        const next = () => {
+            const value = argv[index + 1];
+            if (value === undefined) {
+                console.error(`Missing value for ${flag}`);
+                process.exit(1);
+            }
+            index += 1;
+            return value;
+        };
+        switch (flag) {
+            case '--services':
+                parsed.servicesModule = next();
+                break;
+            case '--json':
+                parsed.json = true;
+                break;
+            case OUT_FILE_FLAG:
+                parsed.outFile = next();
+                break;
+            default:
+                console.error(`Unknown option: ${flag}`);
+                process.exit(1);
+        }
+    }
+    return parsed;
+}
+async function main(argv) {
+    const args = parseArgs(argv);
+    if (!args.servicesModule) {
+        console.error('reflect-driver: --services <module> is required.');
+        process.exit(1);
+    }
+    const { createServices, coreNode } = await loadHeadlessContext(args.servicesModule);
+    const result = coreNode.reflectGrammar({ createServices });
+    emitReport(formatReflectionReport(result, { json: args.json }), args.outFile);
+    return 0;
+}
+main(process.argv.slice(2))
+    .then(code => process.exit(code))
+    .catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});
+//# sourceMappingURL=reflect-driver.js.map

package/lib/commands/reflect-driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflect-driver.js","sourceRoot":"","sources":["../../src/commands/reflect-driver.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAQ7D,SAAS,SAAS,CAAC,IAAc;IAC9B,MAAM,MAAM,GAAe,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAC3C,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,MAAM,IAAI,GAAG,GAAW,EAAE;YACvB,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,KAAK,IAAI,CAAC,CAAC;YACX,OAAO,KAAK,CAAC;QAChB,CAAC,CAAC;QACF,QAAQ,IAAI,EAAE,CAAC;YACZ,KAAK,YAAY;gBACd,MAAM,CAAC,cAAc,GAAG,IAAI,EAAE,CAAC;gBAC/B,MAAM;YACT,KAAK,QAAQ;gBACV,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;gBACnB,MAAM;YACT,KAAK,aAAa;gBACf,MAAM,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC;gBACxB,MAAM;YACT;gBACG,OAAO,CAAC,KAAK,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC;gBACzC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACtB,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,kDAAkD,CAAC,CAAC;QAClE,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,MAAM,GAAG,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC;IAC3D,UAAU,CAAC,sBAAsB,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9E,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/reflect-report.d.ts

@@ -0,0 +1,20 @@
+/********************************************************************************
+ * 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 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 declare function formatReflectionReport(reflection: GrammarReflection, options?: {
+    json?: boolean;
+}): string;
+//# sourceMappingURL=reflect-report.d.ts.map

package/lib/commands/reflect-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflect-report.d.ts","sourceRoot":"","sources":["../../src/commands/reflect-report.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,KAAK,EAAE,iBAAiB,EAAkB,MAAM,sBAAsB,CAAC;AA2G9E;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,iBAAiB,EAAE,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CAY9G"}

package/lib/commands/reflect-report.js

@@ -0,0 +1,127 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/** 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, ' ');
+}
+/** Wrap a value in inline-code backticks, escaping any embedded backtick run. */
+function code(value) {
+    return `\`${value}\``;
+}
+/** The Markdown for each language's grammar surface — 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(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) {
+    const byName = new Map(reflection.types.map(type => [type.name, type]));
+    const roots = reflection.types.filter(type => type.superTypes.length === 0);
+    const lines = ['## Type hierarchy', ''];
+    const walk = (type, depth, path) => {
+        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) {
+    const lines = ['## 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) {
+    const lines = [`## 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, options = {}) {
+    if (options.json) {
+        return JSON.stringify(reflection, undefined, 2);
+    }
+    return [
+        '# Grammar reflection',
+        '',
+        ...languageSection(reflection),
+        ...hierarchySection(reflection),
+        ...crossReferenceSection(reflection),
+        ...typeDetailSection(reflection)
+    ].join('\n');
+}
+//# sourceMappingURL=reflect-report.js.map

package/lib/commands/reflect-report.js.map

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

package/lib/commands/reflect.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 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 declare function buildReflectDriverArgs(options: ReflectCommandOptions): string[];
+/**
+ * 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 declare function runReflect(options: ReflectCommandOptions): Promise<void>;
+//# sourceMappingURL=reflect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reflect.d.ts","sourceRoot":"","sources":["../../src/commands/reflect.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAGlF,OAAO,EAAiC,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAQ/F,qDAAqD;AACrD,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC9D,4EAA4E;IAC5E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,oEAAoE;AACpE,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,EAAE,CAS/E;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAExE"}

package/lib/commands/reflect.js

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

package/lib/commands/reflect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflect.js","sourceRoot":"","sources":["../../src/commands/reflect.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,qBAAqB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAY9E,oEAAoE;AACpE,MAAM,UAAU,sBAAsB,CAAC,OAA8B;IAClE,MAAM,IAAI,GAAG,CAAC,YAAY,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACpD,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QAChB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACvB,CAAC;IACD,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;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,OAA8B;IACtD,OAAO,cAAc,CAAC,CAAC,2BAA2B,EAAE,MAAM,EAAE,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AAC7G,CAAC"}

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

@@ -0,0 +1,26 @@
+/********************************************************************************
+ * 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 SaveCommandOptions } from './save.js';
+/**
+ * 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 declare const SAVE_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 — and `--content`
+ * is the one where a caller plausibly writes that literal text.
+ */
+export declare const SAVE_VALUE_FLAGS: readonly string[];
+/** The `--help` text, as data, held to {@link SAVE_FLAGS} by a test. */
+export declare const SAVE_HELP: readonly string[];
+export declare function parseSaveArgs(args: string[], onError?: UsageError): SaveCommandOptions;
+export declare function runSaveCommand(args: string[]): Promise<void>;
+//# sourceMappingURL=save-args.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"save-args.d.ts","sourceRoot":"","sources":["../../src/commands/save-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAQJ,KAAK,UAAU,EACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAW,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAI7D;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,MAAM,EAAgD,CAAC;AAEzF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAAe,CAAC;AAE9D,wEAAwE;AACxE,eAAO,MAAM,SAAS,EAAE,SAAS,MAAM,EActC,CAAC;AAEF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,UAA0B,GAAG,kBAAkB,CAYrG;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAM5D"}

package/lib/commands/save-args.js

@@ -0,0 +1,59 @@
+/********************************************************************************
+ * 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 { runSave } from './save.js';
+const OWN_FLAGS = ['--uri', '--content', '--client-id'];
+/**
+ * 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 = [...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 = SAVE_FLAGS;
+/** The `--help` text, as data, held to {@link SAVE_FLAGS} by a test. */
+export const SAVE_HELP = [
+    '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, onError = exitWithUsage) {
+    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) {
+    if (helpRequested(args, SAVE_VALUE_FLAGS)) {
+        printHelp(SAVE_HELP);
+        return Promise.resolve();
+    }
+    return runSave(parseSaveArgs(args));
+}
+//# sourceMappingURL=save-args.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"save-args.js","sourceRoot":"","sources":["../../src/commands/save-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,OAAO,EAA2B,MAAM,WAAW,CAAC;AAE7D,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,aAAa,CAAU,CAAC;AAEjE;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAsB,CAAC,GAAG,wBAAwB,EAAE,GAAG,SAAS,CAAC,CAAC;AAEzF;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAsB,UAAU,CAAC;AAE9D,wEAAwE;AACxE,MAAM,CAAC,MAAM,SAAS,GAAsB;IACzC,yIAAyI;IACzI,EAAE;IACF,oFAAoF;IACpF,yDAAyD;IACzD,EAAE;IACF,UAAU;IACV,iFAAiF;IACjF,kDAAkD;IAClD,qFAAqF;IACrF,8EAA8E;IAC9E,sFAAsF;IACtF,gFAAgF;IAChF,iGAAiG;CACnG,CAAC;AAEF,MAAM,UAAU,aAAa,CAAC,IAAc,EAAE,UAAsB,aAAa;IAC9E,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3G,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IACvF,OAAO;QACJ,aAAa;QACb,UAAU;QACV,GAAG;QACH,QAAQ;QACR,GAAG,EAAE,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC;QAClD,OAAO,EAAE,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC;QAC9D,QAAQ;KACV,CAAC;AACL,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAc;IAC1C,IAAI,aAAa,CAAC,IAAI,EAAE,gBAAgB,CAAC,EAAE,CAAC;QACzC,SAAS,CAAC,SAAS,CAAC,CAAC;QACrB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;AACvC,CAAC"}

package/lib/commands/save.d.ts

@@ -0,0 +1,38 @@
+/********************************************************************************
+ * 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 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 declare function runSave(options: SaveCommandOptions): Promise<void>;
+//# sourceMappingURL=save.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"save.d.ts","sourceRoot":"","sources":["../../src/commands/save.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;AAKnE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IAChC,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,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,cAAc,CAAC,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;IAC9D,sFAAsF;IACtF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACjE;AAED,wBAAsB,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBxE"}

package/lib/commands/save.js

@@ -0,0 +1,48 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import * as fs from 'node:fs/promises';
+import { logLevelEnv } from '../log-level.js';
+import { withDataServer } from '../spawn-data-server.js';
+export async function runSave(options) {
+    const write = options.write ?? ((line) => 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, readFile) {
+    if (content.startsWith('@')) {
+        const path = content.slice(1);
+        const reader = readFile ?? ((target) => fs.readFile(target, 'utf8'));
+        return reader(path);
+    }
+    if (content.startsWith('\\@')) {
+        return content.slice(1);
+    }
+    return content;
+}
+//# sourceMappingURL=save.js.map

package/lib/commands/save.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"save.js","sourceRoot":"","sources":["../../src/commands/save.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AA6BzD,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,OAA2B;IACtD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9E,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,eAAe,CAAC;IACrD,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE/E,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,iBAAiB,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;QAClG,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClC,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,GAAG,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;QAClF,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC,CACH,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,cAAc,CAAC,OAAe,EAAE,QAA4C;IACxF,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC9B,MAAM,MAAM,GAAG,QAAQ,IAAI,CAAC,CAAC,MAAc,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAC7E,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,OAAO,CAAC;AAClB,CAAC"}