@hydranium/cli 1.0.0-next.10

package/lib/testing/echo-server.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Test fixture: a standalone Node script that boots a {@link DataServer} over
+ * stdio JSON-RPC. Run as an actual child process, so the wire crossing goes
+ * through real OS pipes rather than the in-process Duplex pair the data-server's
+ * own unit tests use.
+ *
+ * The services tree comes from {@link makeTestServices}; the one behaviour this
+ * fixture adds on top of the stubs is the re-parse seam below.
+ */
+import { DataServer } from '@hydranium/data-server';
+import { makeTestServices } from '@hydranium/core/testing';
+import { StreamMessageReader, StreamMessageWriter, createMessageConnection } from 'vscode-jsonrpc/node';
+function parseFakeRoot(text) {
+    const match = /^name:(.+)$/.exec(text);
+    return { $type: 'FakeRoot', name: match ? match[1] : 'unknown' };
+}
+function main() {
+    const bundle = makeTestServices({
+        serialize: (_uri, root) => `name:${root.name}`,
+        seedDocuments: [
+            {
+                uri: 'file:///fixture/A.fake',
+                root: { $type: 'FakeRoot', name: 'initial' }
+            },
+            {
+                // Echoes the log-level env var the child was spawned with, so the
+                // subprocess-integration test can assert the CLI's `--log-level`
+                // flag actually reaches the spawned server's environment.
+                uri: 'file:///fixture/env.fake',
+                root: { $type: 'FakeRoot', name: process.env.HYDRANIUM_LOG_LEVEL ?? 'unset' }
+            }
+        ],
+        seedProjects: [
+            { id: 'fixture-p1', referenceName: 'fixture-p1', version: '1.0.0', dependencies: undefined },
+            { id: 'fixture-p2', referenceName: 'fixture-p2', version: undefined, dependencies: ['fixture-p1'] }
+        ]
+    });
+    // Re-parse seam: when DataServer.saveModelDocument fires DocumentBuilder.update
+    // for a changed URI, replay the latest text into the LangiumDocuments registry
+    // so the post-save `getModelDocument` return reflects the new content. A real
+    // adopter's DocumentBuilder does this via Langium itself; the stub doesn't, so
+    // the fixture supplies the equivalent here.
+    const originalUpdate = bundle.documentBuilder.update.bind(bundle.documentBuilder);
+    bundle.documentBuilder.update = async (changed, deleted) => {
+        await originalUpdate(changed, deleted);
+        for (const uri of changed) {
+            const uriStr = uri.toString();
+            const recent = [...bundle.textDocuments.changes].reverse().find(change => change.uri === uriStr);
+            if (recent) {
+                bundle.documents.set(uri, parseFakeRoot(recent.text));
+            }
+        }
+    };
+    const connection = createMessageConnection(new StreamMessageReader(process.stdin), new StreamMessageWriter(process.stdout));
+    if (process.argv.includes('--exit-on-request')) {
+        // Fail-fast fixture mode: read a full request (the reader parses the whole
+        // message, so the parent's write completed — no partial-write race) then die
+        // without replying. Exercises the CLI's `whenTerminated` premature-exit gate.
+        connection.onRequest(() => process.exit(0));
+        connection.listen();
+        return;
+    }
+    new DataServer(connection, bundle.services);
+    connection.listen();
+    // The connection holds the event loop open via its message reader; we
+    // don't need to wait on anything explicitly. SIGTERM from the parent
+    // (the CLI's `shutdown()`) ends the process.
+}
+main();
+//# sourceMappingURL=echo-server.js.map

package/lib/testing/echo-server.js.map

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

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@hydranium/cli",
+  "version": "1.0.0-next.10",
+  "description": "Build-time codegen tools + data-server subcommands for the hydranium framework.",
+  "keywords": [
+    "hydranium",
+    "langium",
+    "language-server",
+    "lsp",
+    "cli",
+    "codegen"
+  ],
+  "homepage": "https://github.com/eclipse-emfcloud/hydranium/tree/main/packages/cli",
+  "bugs": {
+    "url": "https://github.com/eclipse-emfcloud/hydranium/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eclipse-emfcloud/hydranium.git",
+    "directory": "packages/cli"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Hydranium Team"
+  },
+  "sideEffects": [
+    "./lib/cli.js",
+    "./lib/commands/*-driver.js",
+    "./lib/testing/echo-server.js"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./lib/cli.js": {
+      "types": "./lib/cli.d.ts",
+      "default": "./lib/cli.js"
+    }
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "bin": {
+    "hydranium-cli": "lib/cli.js"
+  },
+  "files": [
+    "lib",
+    "src",
+    "heap-analysis",
+    "!lib/**/*.tsbuildinfo"
+  ],
+  "scripts": {
+    "build": "tsc -b && node -e \"require('node:fs').chmodSync('lib/cli.js',0o755)\"",
+    "clean": "rimraf lib tsconfig.tsbuildinfo",
+    "lint": "eslint src test --max-warnings 0",
+    "prepack": "node -e \"const m=require('./package.json'),fs=require('node:fs');const missing=[m.main,...Object.values(m.bin||{})].filter(entry=>entry&&!fs.existsSync(entry));if(missing.length){console.error('prepack '+m.name+': not built ('+missing.join(', ')+' missing). Run the build before packing: a files entry that matches nothing is skipped silently, so the tarball would ship src only.');process.exit(1);}\"",
+    "test": "npm run typecheck:test && vitest run",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
+    "watch": "tsc -b -w --preserveWatchOutput"
+  },
+  "dependencies": {
+    "@clack/prompts": "~1.7.0",
+    "commander": "^14.0.3",
+    "ts-morph": "^25.0.0"
+  },
+  "devDependencies": {
+    "@hydranium/core": "1.0.0-next.10",
+    "@hydranium/data-server": "1.0.0-next.10",
+    "@hydranium/langium": "1.0.0-next.10",
+    "@hydranium/protocol": "1.0.0-next.10",
+    "rimraf": "^5.0.0",
+    "typescript": "^5.8.0",
+    "vscode-jsonrpc": "9.0.1",
+    "vscode-languageserver": "~10.0.1"
+  },
+  "peerDependencies": {
+    "@hydranium/core": "1.0.0-next.10",
+    "@hydranium/data-server": "1.0.0-next.10",
+    "@hydranium/langium": "1.0.0-next.10",
+    "@hydranium/protocol": "1.0.0-next.10",
+    "@memlab/core": "^2.0.3",
+    "@memlab/heap-analysis": "^2.0.3",
+    "vscode-jsonrpc": "^8.0.0 || ^9.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@memlab/core": {
+      "optional": true
+    },
+    "@memlab/heap-analysis": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "//build": "The chmod is load-bearing, not cruft. npm sets a bin's executable bit through bin-links' fixBin, but ONLY when it first creates the link — and `tsc` never sets it, so after `npm run clean` (which deletes lib/) a rebuild leaves lib/cli.js at 0644 and the node_modules/.bin/hydranium-cli symlink resolves to a non-executable target. Every example's `generate` step then dies with `sh: hydranium-cli: Permission denied`, surfacing as an opaque npm error code 127 during `turbo run build`. npm rebuild, npm rebuild @hydranium/cli AND a full npm install all fail to restore it, because npm will not revisit an existing workspace symlink; only a from-scratch `rm -rf node_modules` install does. Written as `node -e` rather than `chmod +x` so it stays portable — on Windows npm generates .cmd/.ps1 shims where the bit is irrelevant and chmodSync is harmless. The example packages' bins need no such step: their tests spawn them via process.execPath, never through the shim.",
+  "//exports": "Two keys, and the SHORT list is the point: `files` ships the whole compiled tree, so without a map every `lib/commands/*.js`, every internal helper and `lib/testing/echo-server.js` is deep-importable the moment this publishes, and semver then applies to all of it. `.` is the library barrel (the data-server subcommands an adopter calls as functions). `./lib/cli.js` is the BINARY ARTEFACT, and it is declared because a consumer that spawns the CLI resolves it BY SPECIFIER — `createRequire(import.meta.url).resolve('@hydranium/cli/lib/cli.js')` — to get the path npx would run; `bin` gives a shim on PATH, not a path, so dropping this key breaks that resolution and the failure surfaces as \"hydranium-cli is not built\", naming the wrong cause. It is declared in the `/lib/` spelling ONLY: that spelling already resolves under both of this repo's module resolvers, so the twin rule (which exists so a BARE subpath is reachable from node10) has nothing to add here and a bare twin would only be a second name for one artefact. `heap-analysis/` needs no key even though `files` ships it — `analyze-heap` reaches the analyzer through a `new URL(..., import.meta.url)` file URL, which `exports` does not gate, and the package's own tests reach it relatively. `./testing` is deliberately absent: `echo-server` is a spawnable stdio fixture, not a reusable export.",
+  "//memlab": "@memlab/core and @memlab/heap-analysis are OPTIONAL PEER dependencies, not optionalDependencies, and the distinction is the whole point: npm installs optionalDependencies BY DEFAULT, both memlab packages pin puppeteer exactly, and puppeteer's postinstall downloads a Chrome binary — so every adopter of this CLI paid ~86 MB and a browser download for the one subcommand almost none of them run, and the download can fail and be walked past as a warning. An optional peer is not auto-installed, so `analyze-heap` documents `npm install @memlab/core @memlab/heap-analysis` as the opt-in and every other subcommand is unaffected. Taken pre-publish deliberately: after publish the install shape is what adopters already have.",
+  "//prepack": "The publish guard, and it deliberately is NOT a `prepare`: npm runs a workspace `prepare` BEFORE the root `postinstall` that applies patches/vscode-jsonrpc+9.0.1.patch, so building there fails on a cold clone and npm rolls the entire install back. `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. It FAILS rather than rebuilds, because the rebuild is exactly the part that ordering defeats. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error.",
+  "//sideEffects": "The listed modules RUN on load rather than exporting anything: `cli.js` is the `bin`, each `*-driver.js` is spawned as its own process and calls `main(process.argv)` at top level, and `echo-server.js` starts a server. Their whole purpose is the effect, so a bundler must never treat them as prunable. Everything else here is library code with no module-level state beyond `new URL(..., import.meta.url)` constants."
+}

package/src/cli-version.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 { readFileSync } from 'node:fs';
+
+/** This package's own manifest, reachable at the same relative path from `src/` and `lib/`. */
+const CLI_MANIFEST = new URL('../package.json', import.meta.url);
+
+/**
+ * The version of the running binary.
+ *
+ * Read from the manifest rather than emitted as a constant at build time: a
+ * generated constant is a second copy of a number the manifest already carries,
+ * and nothing goes red while the two disagree.
+ *
+ * Throws rather than reporting `unknown`: every caller turns the number into a
+ * claim someone else acts on — a pinned dependency range, a version in a bug
+ * report — where a placeholder is worse than a failure.
+ */
+export function readCliVersion(): string {
+   const manifest = JSON.parse(readFileSync(CLI_MANIFEST, 'utf-8')) as { version?: unknown };
+   if (typeof manifest.version !== 'string' || manifest.version === '') {
+      throw new Error('hydranium-cli cannot read its own version from its package manifest.');
+   }
+   return manifest.version;
+}

package/src/cli.ts

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/********************************************************************************
+ * 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 { Command } from 'commander';
+import { readCliVersion } from './cli-version.js';
+import { runAnalyzeHeapCommand } from './commands/analyze-heap-args.js';
+import { runAstGroundTruthCommand } from './commands/ast-ground-truth-args.js';
+import { runGenerateTransferModelCommand } from './commands/generate-transfer-model-args.js';
+import { runInitCommand } from './commands/init-args.js';
+import { InitWizardCancelled } from './commands/init-prompt.js';
+import { runLintGrammarCommand } from './commands/lint-grammar-args.js';
+import { runMeasureMemoryCommand } from './commands/measure-memory-args.js';
+import { runModelDocsCommand } from './commands/model-docs-args.js';
+import { runProjectsCommand } from './commands/projects-args.js';
+import { runQueryCommand } from './commands/query-args.js';
+import { runReflectCommand } from './commands/reflect-args.js';
+import { runSaveCommand } from './commands/save-args.js';
+import { runValidateCommand } from './commands/validate-args.js';
+import { runWatchCommand } from './commands/watch-args.js';
+
+/**
+ * The subcommand table, as name → handler over that command's own argv tail.
+ *
+ * Each handler owns its own flag parsing, in a sibling `<name>-args` module that
+ * also holds the command's flag list and its help text as data. `commander`
+ * provides the dispatch, the command list and the top-level help, but NOT the
+ * option parsing: it would generate the per-command help from declared options,
+ * at the price of its own error vocabulary replacing the messages scripts match
+ * on. `init` could not follow it there in any case — its grammar-scoped flags
+ * (`--extensions` applies to the PRECEDING `--grammar`) depend on the relative
+ * order of two DIFFERENT option names, which no declarative option model
+ * expresses.
+ */
+const COMMANDS: Record<string, { readonly summary: string; readonly run: (args: string[]) => void | Promise<void> }> = {
+   'analyze-heap': { summary: 'Analyze a V8 heap snapshot (needs optional @memlab/heap-analysis).', run: runAnalyzeHeapCommand },
+   'ast-ground-truth': {
+      summary: "Tally a workspace's live-model $types (analyze-heap --validate input).",
+      run: runAstGroundTruthCommand
+   },
+   'generate-transfer-model': {
+      summary: 'Generate a transfer-model TypeScript file from a Langium AST.',
+      run: runGenerateTransferModelCommand
+   },
+   init: { summary: 'Scaffold a new Hydranium language project (grammar + server head).', run: runInitCommand },
+   'lint-grammar': { summary: 'Check a grammar against framework conventions (CI gate).', run: runLintGrammarCommand },
+   'measure-memory': { summary: 'Measure model-store memory for a workspace (needs @hydranium/core).', run: runMeasureMemoryCommand },
+   'model-docs': { summary: 'Generate a navigable Markdown model reference for adopter docs.', run: runModelDocsCommand },
+   projects: { summary: 'List projects exposed by a data-server subprocess.', run: runProjectsCommand },
+   query: { summary: 'Print the data-server document envelope for a URI.', run: runQueryCommand },
+   reflect: { summary: "Dump a head's grammar/AST reflection (types, terminals, refs).", run: runReflectCommand },
+   save: { summary: 'Update + persist a document via a data-server subprocess.', run: runSaveCommand },
+   validate: { summary: 'Validate a workspace headlessly; non-zero exit on errors (CI gate).', run: runValidateCommand },
+   watch: { summary: 'Subscribe to data-server document updates; print events as NDJSON.', run: runWatchCommand }
+};
+
+/**
+ * The `commander` program.
+ *
+ * `.usage()` and the help formatter are pinned to the shape scripts already
+ * read — `Usage: hydranium-cli <command> [options]` with a two-space-indented
+ * command list — because a CI step that greps the usage line is a contract, not
+ * cosmetics. Each subcommand passes its raw tail through to its own handler
+ * (`.allowUnknownOption()` plus a variadic operand), so commander owns dispatch
+ * and discovery while the handlers keep the exact flag semantics they had.
+ */
+function buildProgram(): Command {
+   const program = new Command();
+   program
+      .name('hydranium-cli')
+      .usage('<command> [options]')
+      .addHelpText('after', '\nRun `hydranium-cli <command> --help` for command-specific options.')
+      .helpOption('-h, --help', 'Show this help.')
+      // Declared so the top-level help lists it; the dispatch below answers it,
+      // because commander would otherwise never see the token — an argv whose
+      // first word is not a known subcommand is rejected before `parseAsync`.
+      .version(readCliVersion(), '-V, --version', 'Show the version.')
+      // No `help <command>` alias: the surface stays exactly the COMMANDS
+      // table, and `<command> --help` already covers what it would offer.
+      .helpCommand(false)
+      .configureHelp({ subcommandTerm: command => command.name() });
+   for (const [name, { summary, run }] of Object.entries(COMMANDS)) {
+      program
+         .command(name)
+         .summary(summary)
+         .description(summary)
+         .allowUnknownOption()
+         .allowExcessArguments()
+         .helpOption(false)
+         .argument('[args...]')
+         .action(async (args: string[]) => {
+            await run(args);
+         });
+   }
+   return program;
+}
+
+async function main(argv: string[]): Promise<void> {
+   const [command] = argv;
+   // Handled ahead of commander so the three shapes a script can depend on keep
+   // their exact contract: a bare invocation prints usage on STDOUT and exits 1,
+   // `--help` prints the same on stdout and exits 0, and an unknown command
+   // names itself on STDERR with the usage still on stdout.
+   const program = buildProgram();
+   if (!command || command === '--help' || command === '-h') {
+      program.outputHelp();
+      process.exit(command ? 0 : 1);
+   }
+   // Ahead of the unknown-command branch, which claims every first token the
+   // COMMANDS table does not name and would report the flag as a misspelt
+   // subcommand on stderr with a non-zero exit.
+   if (command === '--version' || command === '-V') {
+      console.log(readCliVersion());
+      process.exit(0);
+   }
+   if (!Object.hasOwn(COMMANDS, command)) {
+      console.error(`Unknown command: ${command}`);
+      program.outputHelp();
+      process.exit(1);
+   }
+   await program.parseAsync(argv, { from: 'user' });
+}
+
+main(process.argv.slice(2)).catch(err => {
+   // Ctrl-C out of the wizard is a choice, not a failure: clack has already
+   // drawn its cancel line, so printing a stack trace over it would report the
+   // user's own decision back to them as an error.
+   if (err instanceof InitWizardCancelled) {
+      process.exit(130);
+   }
+   console.error(err instanceof Error ? err.message : String(err));
+   process.exit(1);
+});

package/src/commands/analyze-heap-args.ts

@@ -0,0 +1,184 @@
+/********************************************************************************
+ * 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 { DIFF_FLAG, runAnalyzeHeap, type AnalyzeHeapDeps } from './analyze-heap.js';
+import { exitWithUsage, helpRequested, printHelp, type UsageError } from './harness-args.js';
+import { OUT_FILE_FLAG } from './headless-harness.js';
+
+/**
+ * Flags whose value is mandatory. `--diff` is here for
+ * {@link helpRequested}'s benefit — it takes TWO values, which the parser below
+ * handles as its own case.
+ */
+const VALUE_FLAGS = [DIFF_FLAG, OUT_FILE_FLAG, '--validate', '--json', '--threshold', '--classifier'] as const;
+
+/**
+ * Flags whose value may be omitted: each names a top-N the analyzer defaults
+ * when the token is bare, so a following token is a value only when it is not
+ * itself a flag.
+ */
+const OPTIONAL_VALUE_FLAGS = ['--breakdown-depth', '--top-concepts', '--strings', '--cutpoints', '--docs', '--holders'] as const;
+
+/** Presence-only flags. */
+const BOOL_FLAGS = ['--cutpoints-all', '--renderer'] as const;
+
+/**
+ * Every flag `analyze-heap` accepts, derived from the three sets the parser
+ * scans so the list cannot claim a flag the parser would reject. `--help` is
+ * absent because it selects the help block rather than describing a run.
+ */
+export const ANALYZE_HEAP_FLAGS: readonly string[] = [...VALUE_FLAGS, ...OPTIONAL_VALUE_FLAGS, ...BOOL_FLAGS];
+
+/** The subset whose value is mandatory, so `--help` in a value position reads as data. */
+export const ANALYZE_HEAP_VALUE_FLAGS: readonly string[] = VALUE_FLAGS;
+
+/**
+ * The `--help` text, as data, held to {@link ANALYZE_HEAP_FLAGS} by a test.
+ *
+ * The analyzer is a standalone ESM asset spawned as a child, so this is the only
+ * copy: a second one beside its argv reads is what let its flags and its help
+ * drift apart with nothing able to see it.
+ */
+export const ANALYZE_HEAP_HELP: readonly string[] = [
+   'Usage: hydranium-cli analyze-heap <snapshot> [options]',
+   '       hydranium-cli analyze-heap --diff <baseline.json> <current.json> [--threshold <pct>]',
+   '',
+   'Langium-aware V8 heap-snapshot analyzer (memlab-based). A default run (just',
+   '<snapshot>) prints a Markdown report to stdout: concept table, a hierarchical',
+   'breakdown (each concept group drilled into its colon-delimited sub-levels, e.g.',
+   'AST node -> $type, GModel -> kind -> subtype), the duplicate-string / cut-point /',
+   'per-document drill-downs, and sample retainer paths. Loading is the only real',
+   'cost, so the drill-downs run by default; tune or disable them with the flags',
+   'below. The Markdown reads fine as text, saves as a .md file (--out-file), and',
+   'is ideal input for the memory-analysis skill.',
+   '',
+   'Reading a snapshot needs the optional @memlab/core + @memlab/heap-analysis peer',
+   'dependencies (`npm install @memlab/core @memlab/heap-analysis`); --diff and',
+   '--help need neither.',
+   '',
+   'Options:',
+   '  <snapshot>               the .heapsnapshot to read; omit only with --diff (required).',
+   '  --out-file <file.md>     also write the Markdown report to a file',
+   '  --breakdown-depth [N]    max DISPLAY depth of the hierarchical breakdown',
+   '                           (default: full depth). Aggregation is always',
+   '                           depth-agnostic; a cap only hides deeper rows — their',
+   '                           bytes still roll up into the deepest shown row.',
+   '  --top-concepts [N]       how many of the biggest anchor concepts get a',
+   '                           retainer-path sample and are the default --holders',
+   '                           targets (default 6)',
+   '  --strings [N]            duplicate plain strings, top N (default 20; 0 = off)',
+   '  --cutpoints [N]          lightweight sole owners, top N (default 10; 0 = off)',
+   '  --cutpoints-all          include Node/V8/server runtime owners (default: model only)',
+   '  --docs [N]               heaviest documents, top N (default 15; 0 = off).',
+   '                           Langium/server-only — skipped in --renderer mode (a',
+   '                           renderer heap has no documents).',
+   '  --holders [a,b,c]        who holds each concept: dominator + referrer tallies,',
+   '                           comma-separated, one heap pass (e.g. CST,Range,Map);',
+   '                           no value = the top model concepts',
+   "  --validate <gt.json>     validate the snapshot's $type classification against",
+   '                           the live model (ground truth from the',
+   '                           hydranium-cli ast-ground-truth subcommand); flags',
+   '                           drift and computed/derived types',
+   '  --json <file>            write the analysis as JSON (baseline artifact for --diff)',
+   '  --diff <base> <cur>      diff two analysis JSONs; prints deltas + verdict,',
+   '                           exits non-zero on regression (no snapshot needed)',
+   '  --threshold <pct>        regression threshold for --diff, % growth of total',
+   '                           shallow (default 5)',
+   '  --renderer               analyze a BROWSER/renderer heap (the browser-heap',
+   '                           artefact, from CDP) instead of a Langium server heap:',
+   '                           buckets by DOM vocabulary (Detached DOM / DOM node /',
+   '                           Event listener) and the retainer paths to each detached',
+   '                           concept ARE the listener-retainer analysis. Skips the',
+   '                           Langium/GLSP classifiers + --validate (no ground truth).',
+   '  --classifier <file>      ESM module default-exporting a ConceptClassifier',
+   '                           (classify(node) -> a colon-delimited label path, +',
+   '                           optional anchorConcepts/grammarTypes/isAnchor) to label',
+   "                           a head's own concepts; repeatable. Tried BEFORE the",
+   '                           built-in Langium + GLSP defaults (return undefined to',
+   '                           defer), so a more specific classifier overrides a',
+   '                           default. Order = precedence.',
+   '  -h, --help               show this help',
+   '',
+   'Notes: snapshot is the language-server process only (no other processes, native',
+   'memory, or browser heap).'
+];
+
+/** What {@link parseAnalyzeHeapArgs} recovered from an argv. */
+export interface AnalyzeHeapArgs {
+   /** `true` when the argv selects the JSON-vs-JSON diff, which reads no snapshot. */
+   readonly diff: boolean;
+   /** The `.heapsnapshot` to read; absent only on the {@link diff} path. */
+   readonly snapshot?: string;
+}
+
+/**
+ * Validate the argv the analyzer will be handed.
+ *
+ * The values themselves stay the analyzer's to read — it is a standalone ESM
+ * asset spawned as a child, and duplicating its numeric coercions here would be
+ * a second place for them to drift. What this pass adds is the rejection every
+ * sibling subcommand performs: an unrecognised token left inert makes a typo'd
+ * `--treshold 0` apply the default silently, so the caller believes a threshold
+ * is in force.
+ */
+export function parseAnalyzeHeapArgs(args: string[], onError: UsageError = exitWithUsage): AnalyzeHeapArgs {
+   const mandatoryValue = new Set<string>(VALUE_FLAGS);
+   const optionalValue = new Set<string>(OPTIONAL_VALUE_FLAGS);
+   const presenceOnly = new Set<string>(BOOL_FLAGS);
+   let diff = false;
+   let snapshot: string | undefined;
+   for (let index = 0; index < args.length; index += 1) {
+      const flag = args[index];
+      if (flag === DIFF_FLAG) {
+         diff = true;
+         if (args[index + 1] === undefined || args[index + 2] === undefined) {
+            onError(`Missing value for ${DIFF_FLAG}`);
+         }
+         index += 2;
+      } else if (mandatoryValue.has(flag)) {
+         if (args[index + 1] === undefined) {
+            onError(`Missing value for ${flag}`);
+         }
+         index += 1;
+      } else if (optionalValue.has(flag)) {
+         if (args[index + 1] !== undefined && !args[index + 1].startsWith('-')) {
+            index += 1;
+         }
+      } else if (presenceOnly.has(flag)) {
+         // Nothing to claim; the analyzer reads its presence.
+      } else if (flag.startsWith('-')) {
+         onError(`Unknown option: ${flag} (hydranium-cli analyze-heap --help)`);
+      } else if (snapshot === undefined) {
+         snapshot = flag;
+      } else {
+         onError(`Unexpected argument: ${flag} (hydranium-cli analyze-heap --help)`);
+      }
+   }
+   if (!diff && snapshot === undefined) {
+      onError('Missing required option: <snapshot> (hydranium-cli analyze-heap --help)');
+   }
+   return { diff, snapshot };
+}
+
+export function runAnalyzeHeapCommand(args: string[], deps: AnalyzeHeapDeps = {}): Promise<void> {
+   if (args.length === 0) {
+      // Usage on stdout and a non-zero exit, matching the parent binary's bare
+      // invocation: a CI step that forgot its snapshot argument must fail rather
+      // than read a help page as a completed analysis.
+      printHelp(ANALYZE_HEAP_HELP);
+      process.exitCode = 1;
+      return Promise.resolve();
+   }
+   if (helpRequested(args, ANALYZE_HEAP_VALUE_FLAGS)) {
+      printHelp(ANALYZE_HEAP_HELP);
+      return Promise.resolve();
+   }
+   parseAnalyzeHeapArgs(args);
+   return runAnalyzeHeap(args, deps);
+}

package/src/commands/analyze-heap.ts

@@ -0,0 +1,76 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { fileURLToPath } from 'node:url';
+import { spawnNodeChild } from './headless-harness.js';
+
+/**
+ * Absolute path to the bundled memlab-based analyzer (a standalone ESM script
+ * shipped under the package's `heap-analysis/` assets, not the compiled `lib/`).
+ * From `lib/commands/analyze-heap.js` that is `../../heap-analysis/analyze-heap.mjs`.
+ */
+const ANALYZER = fileURLToPath(new URL('../../heap-analysis/analyze-heap.mjs', import.meta.url));
+
+/** `true` when the optional `@memlab/heap-analysis` dependency is installed and resolvable. */
+function memlabInstalled(): boolean {
+   const resolve = (import.meta as { resolve?: (specifier: string) => string }).resolve;
+   try {
+      resolve?.('@memlab/heap-analysis');
+      return resolve !== undefined;
+   } catch {
+      return false;
+   }
+}
+
+/**
+ * Selects the JSON-vs-JSON comparison, which reads two analysis artifacts and
+ * needs neither a snapshot nor memlab. Declared here rather than in the args
+ * module so the guard below and the flag list read the same constant.
+ */
+export const DIFF_FLAG = '--diff';
+
+/** Test-only injection seam for {@link runAnalyzeHeap}, mirroring the sibling harness commands. */
+export interface AnalyzeHeapDeps {
+   /** Capture the node argv instead of spawning the real analyzer child. */
+   readonly __spawnForTest?: (execArgs: string[]) => Promise<number>;
+   /** Override the memlab-availability check. */
+   readonly __memlabInstalledForTest?: () => boolean;
+}
+
+/**
+ * Run the heap-snapshot analyzer. Memlab is an OPTIONAL PEER dependency and a
+ * heavy one — it drags in a browser download — so an install of this package
+ * pulls in nothing, and a caller that wants heap analysis opts in with the
+ * install line the guard below prints. This subcommand loads it only when
+ * invoked, by spawning the bundled analyzer in a child process with the large
+ * heap memlab needs. All arguments are forwarded verbatim — the analyzer owns
+ * how it reads them.
+ *
+ * The guard is skipped for {@link DIFF_FLAG}, which the analyzer short-circuits
+ * before any memlab import: refusing it would demand ~86 MB of dependency for a
+ * run that reads two JSON files. Help is intercepted earlier still, by the args
+ * module, so it never reaches this function.
+ */
+export async function runAnalyzeHeap(args: string[], deps: AnalyzeHeapDeps = {}): Promise<void> {
+   const isMemlabInstalled = deps.__memlabInstalledForTest ?? memlabInstalled;
+   if (!args.includes(DIFF_FLAG) && !isMemlabInstalled()) {
+      console.error(
+         'analyze-heap needs the optional @memlab/heap-analysis dependency (heavy: ~86 MB).\n' +
+            'It is an optional peer dependency, so it is not installed by default; add it with:\n' +
+            '  npm install @memlab/core @memlab/heap-analysis'
+      );
+      process.exitCode = 1;
+      return;
+   }
+   const spawnChild = deps.__spawnForTest ?? spawnNodeChild;
+   const code = await spawnChild(['--max-old-space-size=8192', ANALYZER, ...args]);
+   if (code) {
+      process.exitCode = code;
+   }
+}