@hydranium/cli 1.0.0-next.31 → 1.0.0-next.312

package/src/commands/validate-args.ts

@@ -9,34 +9,36 @@
 
 import {
    exitWithUsage,
+   HARNESS_VALUE_FLAGS,
    helpRequested,
-   LOG_LEVEL_FLAG,
-   logLevelHelpLine,
-   logLevelOption,
+   importHelpLines,
+   LOG_VALUE_FLAGS,
+   logHelpLines,
+   logOptions,
    parseHarnessArgs,
    printHelp,
-   SERVICES_FLAG,
    type UsageError
 } from './harness-args.js';
 import { OUT_FILE_FLAG } from './headless-harness.js';
 import { runValidate, type ValidateCommandOptions } from './validate.js';
 
-const VALUE_FLAGS = [OUT_FILE_FLAG, LOG_LEVEL_FLAG] as const;
+const VALUE_FLAGS = [OUT_FILE_FLAG, ...LOG_VALUE_FLAGS] as const;
 const BOOL_FLAGS = ['--strict', '--json'] as const;
 
 /**
  * Every flag `validate` accepts, derived from the sets the parser is handed so
- * the list cannot claim a flag the parser would reject. `--services` is consumed
- * by the shared harness parser itself, so it is in neither set.
+ * the list cannot claim a flag the parser would reject.
+ * {@link HARNESS_VALUE_FLAGS} are consumed by the shared harness parser itself,
+ * so they are in neither set.
  */
-export const VALIDATE_FLAGS: readonly string[] = [SERVICES_FLAG, ...VALUE_FLAGS, ...BOOL_FLAGS];
+export const VALIDATE_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS, ...VALUE_FLAGS, ...BOOL_FLAGS];
 
 /** The subset that takes a value, so `--help` in a value position reads as data. */
-export const VALIDATE_VALUE_FLAGS: readonly string[] = [SERVICES_FLAG, ...VALUE_FLAGS];
+export const VALIDATE_VALUE_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS, ...VALUE_FLAGS];
 
 /** The `--help` text, as data, held to {@link VALIDATE_FLAGS} by a test. */
 export const VALIDATE_HELP: readonly string[] = [
-   'Usage: hydranium-cli validate --services <module> <workspace> [--strict] [--json] [--out-file <file>] [--log-level <lvl>]',
+   'Usage: hydranium-cli validate --services <module> [--import <specifier>]... <workspace> [--strict] [--json] [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    'Build a workspace headlessly and report its validation diagnostics — a CI gate:',
    'the process exits non-zero when any error is found. `<module>` is an ESM module',
@@ -45,6 +47,7 @@ export const VALIDATE_HELP: readonly string[] = [
    '',
    'Options:',
    '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   ...importHelpLines(22),
    '  <workspace>           Workspace root (path or file URI) to validate (required).',
    '  --strict              Also fail (non-zero exit) on warnings, not only errors.',
    '  --json                Emit the raw JSON result instead of the human report.',
@@ -52,18 +55,19 @@ export const VALIDATE_HELP: readonly string[] = [
    '                        still decides the exit code, and the file is written only',
    '                        once the report exists, unlike a shell redirection, which',
    '                        truncates the file before the workspace is even built.',
-   logLevelHelpLine(22)
+   ...logHelpLines(22)
 ];
 
 export function parseValidateArgs(args: string[], onError: UsageError = exitWithUsage): ValidateCommandOptions {
-   const { servicesModule, workspace, options } = parseHarnessArgs(args, 'validate', VALUE_FLAGS, BOOL_FLAGS, { onError });
+   const { servicesModule, imports, workspace, options } = parseHarnessArgs(args, 'validate', VALUE_FLAGS, BOOL_FLAGS, { onError });
    return {
       servicesModule,
+      imports,
       workspace,
       strict: options['--strict'] === 'true',
       json: options['--json'] === 'true',
       outFile: options[OUT_FILE_FLAG],
-      logLevel: logLevelOption(options[LOG_LEVEL_FLAG])
+      ...logOptions(options)
    };
 }
 

package/src/commands/validate-driver.ts

@@ -16,6 +16,7 @@
  * `--strict` also fails on warnings). Never imported — only spawned.
  */
 
+import { describeError } from '@hydranium/protocol';
 import { emitReport, loadHeadlessContext, OUT_FILE_FLAG } from './headless-harness.js';
 import { formatValidationReport, validationExitCode } from './validate-report.js';
 
@@ -79,6 +80,6 @@ async function main(argv: string[]): Promise<number> {
 main(process.argv.slice(2))
    .then(code => process.exit(code))
    .catch((error: unknown) => {
-      console.error(error instanceof Error ? error.message : String(error));
+      console.error(describeError(error));
       process.exit(1);
    });

package/src/commands/validate.ts

@@ -54,5 +54,5 @@ export function buildValidateDriverArgs(options: ValidateCommandOptions): string
  * The child's exit code propagates to this process so shells and CI see the gate.
  */
 export function runValidate(options: ValidateCommandOptions): Promise<void> {
-   return runDriverChild(['--max-old-space-size=8192', DRIVER, ...buildValidateDriverArgs(options)], options);
+   return runDriverChild([DRIVER, ...buildValidateDriverArgs(options)], options);
 }

package/src/commands/watch-args.ts

@@ -11,6 +11,7 @@ import {
    assertRequired,
    exitWithUsage,
    helpRequested,
+   logHelpLines,
    parseFlagOptions,
    parseServerSpawnOptions,
    printHelp,
@@ -35,7 +36,7 @@ export const WATCH_VALUE_FLAGS: readonly string[] = WATCH_FLAGS;
 
 /** The `--help` text, as data, held to {@link WATCH_FLAGS} by a test. */
 export const WATCH_HELP: readonly string[] = [
-   'Usage: hydranium-cli watch --server "<cmd>..." --uri <uri> [--client-id <id>] [--cwd <dir>] [--log-level <level>]',
+   'Usage: hydranium-cli watch --server "<cmd>..." --uri <uri> [--client-id <id>] [--cwd <dir>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    'Subscribe to document updates at `<uri>` and print events as newline-delimited',
    'JSON. Long-running — exits cleanly on SIGINT (Ctrl-C).',
@@ -45,18 +46,20 @@ export const WATCH_HELP: readonly string[] = [
    '  --uri <uri>           Document URI (required).',
    '  --client-id <id>      Subscriber identity. 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).'
+   ...logHelpLines(22, 'the spawned server')
 ];
 
 /** Parse the argv; the abort signal is the entry point's to supply, not the command line's. */
 export function parseWatchArgs(args: string[], onError: UsageError = exitWithUsage): WatchCommandOptions {
-   const { serverCommand, serverArgs, cwd, logLevel, extra } = parseServerSpawnOptions(args, 'watch', onError);
+   const { serverCommand, serverArgs, cwd, logLevel, logFile, logFileLevel, extra } = parseServerSpawnOptions(args, 'watch', onError);
    const { uri, clientId } = parseFlagOptions(extra, 'watch', OWN_FLAGS, onError);
    return {
       serverCommand,
       serverArgs,
       cwd,
       logLevel,
+      logFile,
+      logFileLevel,
       uri: assertRequired(uri, '--uri', 'watch', onError),
       clientId
    };

package/src/commands/watch.ts

@@ -7,9 +7,14 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { LogThreshold, TransferElement } from '@hydranium/protocol';
-import type { DataClientProtocol, DataServerProtocol, TransferDocumentUpdatedEvent } from '@hydranium/protocol/data';
-import { logLevelEnv } from '../log-level.js';
+import type { TransferElement } from '@hydranium/protocol';
+import type {
+   DataClientProtocol,
+   DataServerProtocol,
+   TransferDocumentDeletedEvent,
+   TransferDocumentUpdatedEvent
+} from '@hydranium/protocol/data';
+import { logEnv, type LogOptions } from '../log-level.js';
 import { spawnDataServer } from '../spawn-data-server.js';
 
 /**
@@ -22,12 +27,10 @@ import { spawnDataServer } from '../spawn-data-server.js';
  * — production CLI wires SIGINT directly. `__handleForTest` bypasses
  * the spawn step for unit tests.
  */
-export interface WatchCommandOptions {
+export interface WatchCommandOptions extends LogOptions {
    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 clientId?: string;
    readonly write?: (line: string) => void;
@@ -132,6 +135,24 @@ export async function runWatch(options: WatchCommandOptions): Promise<void> {
       onDocumentSaved(): void {
          // Persistence is out of band for the per-URI update view.
       },
+      onDocumentDirtyChanged(): void {
+         // Out of band for the per-URI update view, as persistence is.
+      },
+      onDocumentDeleted(event: TransferDocumentDeletedEvent): void {
+         // In band, unlike the two neighbours: this is the end of the stream
+         // the view exists to show, and a consumer that never hears it waits
+         // forever for an update that cannot come. The line carries no
+         // `document`, so a reader must switch on shape rather than assume one.
+         if (event.uri !== options.uri) {
+            return;
+         }
+         write(`${JSON.stringify(event)}\n`);
+      },
+      onDocumentsBuilt(): void {
+         // Out of band for a per-URI view by construction: this notification
+         // carries only documents nobody watches, and this command watches the
+         // one URI it was given.
+      },
       onProjectsChanged(): void {
          // Project lifecycle is out of band for the per-URI update view.
       }
@@ -146,7 +167,7 @@ export async function runWatch(options: WatchCommandOptions): Promise<void> {
             command: options.serverCommand,
             args: options.serverArgs,
             cwd: options.cwd,
-            env: options.logLevel ? logLevelEnv(options.logLevel) : undefined
+            env: logEnv(options)
          },
          localClient
       );

package/src/driver-heap.ts

@@ -0,0 +1,65 @@
+/********************************************************************************
+ * 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 { heapCeilingArgs } from '@hydranium/core/node';
+
+/**
+ * Heap ceiling in MiB for a driver child on a machine with no cgroup limit.
+ *
+ * The subcommands that spawn one build a whole workspace in that child —
+ * `measure-memory` deliberately so, `analyze-heap` loads an entire heap
+ * snapshot — so the default Node would pick from physical RAM is too low for
+ * the workspaces these are pointed at.
+ */
+export const DRIVER_HEAP_MB = 8192;
+
+/** Environment variable an operator raises or lowers {@link driverHeapArgs} with. */
+export const DRIVER_HEAP_ENV = 'HYDRANIUM_CLI_MAX_OLD_SPACE_MB';
+
+/**
+ * Smallest ceiling {@link DRIVER_HEAP_ENV} may state. A driver child builds a
+ * whole workspace, so a value this far below the default is a unit mistake
+ * rather than a deliberate squeeze.
+ */
+export const MIN_DRIVER_HEAP_MB = 256;
+
+/**
+ * A cgroup reading, so a caller — in practice a test — can decide the ceiling
+ * instead of inheriting the machine's. Omitted fields fall back to this
+ * process's own reading.
+ */
+export interface HeapReading {
+   readonly constrained?: number;
+   readonly total?: number;
+}
+
+/**
+ * The `execArgv` prefix every driver child is spawned under.
+ *
+ * Inside a container this is EMPTY on purpose. {@link DRIVER_HEAP_MB} is sized
+ * for a workstation, and handing it to a process under a smaller cgroup limit
+ * is worse than handing it nothing: V8 has no reason to collect hard below a
+ * ceiling it will never reach, so the kernel OOM-kills the container first and
+ * the failure arrives as a signal against the whole cgroup rather than as a
+ * heap error the parent can attribute. Left to itself, Node sizes the heap from
+ * the limit instead.
+ *
+ * That trades away the ability to use a LARGE container's memory, since Node's
+ * derived default is a fraction of the limit — which is what {@link DRIVER_HEAP_ENV}
+ * is for. An operator who states a number has decided, so it wins in a
+ * container too.
+ */
+export function driverHeapArgs(reading: HeapReading = {}): string[] {
+   return heapCeilingArgs({
+      desktopDefaultMb: DRIVER_HEAP_MB,
+      envValue: process.env[DRIVER_HEAP_ENV],
+      minMb: MIN_DRIVER_HEAP_MB,
+      ...reading
+   });
+}

package/src/index.ts

@@ -7,6 +7,8 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+export * from './commands/create.js';
+export * from './commands/delete.js';
 export * from './commands/generate-ast-builder.js';
 export * from './commands/generate-transfer-model.js';
 export * from './commands/projects.js';

package/src/log-level.ts

@@ -7,29 +7,47 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { DEFAULT_LOG_LEVEL_ENV, LEVEL_ORDER, parseLogLevel, type LogThreshold } from '@hydranium/protocol';
+import {
+   DEFAULT_LOG_FILE_ENV,
+   DEFAULT_LOG_FILE_LEVEL_ENV,
+   DEFAULT_LOG_LEVEL_ENV,
+   LEVEL_ORDER,
+   parseLogLevel,
+   type LogThreshold
+} from '@hydranium/protocol';
+
+/** The log flags every subcommand takes, as the env {@link logEnv} hands its child. */
+export interface LogOptions {
+   /** Threshold for the client sink; the server's log-level setting replaces it. */
+   readonly logLevel?: LogThreshold;
+   /** File the server tees its log to; `{workspace}` expands once it is known, `{pid}` from the start. */
+   readonly logFile?: string;
+   /** The file's own threshold, which the log-level setting does not change. */
+   readonly logFileLevel?: LogThreshold;
+}
 
 /**
- * Validate a raw `--log-level` argument into a {@link LogThreshold}. Throws on
- * an unrecognised value so the CLI's top-level `catch` surfaces a clean error
- * and exits non-zero (mirroring how the other option parsers fail fast). Use
- * for the argv-supplied value; the resolved threshold is handed to
- * {@link logLevelEnv} to target the spawned server.
+ * Validate a raw `--log-level` / `--log-file-level` argument into a
+ * {@link LogThreshold}. Throws on an unrecognised value so the CLI's top-level
+ * `catch` surfaces a clean error and exits non-zero (mirroring how the other
+ * option parsers fail fast). Use for the argv-supplied value; the resolved
+ * threshold is handed to {@link logEnv} to target the spawned server.
  */
-export function parseLogLevelOption(raw: string): LogThreshold {
+export function parseLogLevelOption(raw: string, flag = '--log-level'): LogThreshold {
    const level = parseLogLevel(raw);
    if (!level) {
-      throw new Error(`Invalid --log-level: ${raw} (expected one of: ${Object.keys(LEVEL_ORDER).join(', ')})`);
+      throw new Error(`Invalid ${flag}: ${raw} (expected one of: ${Object.keys(LEVEL_ORDER).join(', ')})`);
    }
    return level;
 }
 
 /**
  * Build the environment override that targets *only the spawned server's* log
- * threshold. Passed to `spawnDataServer` as `env`, it sets the same
- * `HYDRANIUM_LOG_LEVEL` variable the server reads at startup — the CLI's own
- * logging is unaffected, unlike an ambient `HYDRANIUM_LOG_LEVEL=…` that the
- * child would inherit alongside the parent. The server owns *how* log level
+ * configuration, or `undefined` when no log flag was given. Passed to
+ * `spawnDataServer` as `env`, it sets the same `HYDRANIUM_LOG_LEVEL` /
+ * `HYDRANIUM_LOG_FILE` / `HYDRANIUM_LOG_FILE_LEVEL` variables the server reads
+ * at startup — the CLI's own logging is unaffected, unlike ambient variables
+ * that the child would inherit alongside the parent. The server owns *how* log level
  * works; this only routes the CLI's request onto the channel it already reads.
  *
  * **The variable is read by `LspLogger`'s constructor**, which is bound on the
@@ -44,6 +62,16 @@ export function parseLogLevelOption(raw: string): LogThreshold {
  * not go to stdout: that is the JSON-RPC channel, so a log line there would
  * corrupt the very request this flag was set to diagnose.
  */
-export function logLevelEnv(level: LogThreshold): Record<string, string> {
-   return { [DEFAULT_LOG_LEVEL_ENV]: level };
+export function logEnv(options: LogOptions): Record<string, string> | undefined {
+   const env: Record<string, string> = {};
+   if (options.logLevel !== undefined) {
+      env[DEFAULT_LOG_LEVEL_ENV] = options.logLevel;
+   }
+   if (options.logFile !== undefined) {
+      env[DEFAULT_LOG_FILE_ENV] = options.logFile;
+   }
+   if (options.logFileLevel !== undefined) {
+      env[DEFAULT_LOG_FILE_LEVEL_ENV] = options.logFileLevel;
+   }
+   return Object.keys(env).length > 0 ? env : undefined;
 }

package/src/spawn-data-server.ts

@@ -15,7 +15,14 @@ import {
    type DataServerProtocol
 } from '@hydranium/protocol/data';
 import { type ChildProcess, spawn } from 'node:child_process';
-import { StreamMessageReader, StreamMessageWriter, createMessageConnection, type MessageConnection } from 'vscode-jsonrpc/node';
+import {
+   StreamMessageReader,
+   StreamMessageWriter,
+   createMessageConnection,
+   type Logger as ConnectionLogger,
+   type MessageConnection
+} from 'vscode-jsonrpc/node';
+import { STDERR_CONNECTION_LOGGER } from './stderr-connection-logger.js';
 
 /**
  * Options for {@link spawnDataServer}. `command` is the binary or script
@@ -49,6 +56,11 @@ export interface SpawnDataServerOptions {
     * scripted use; set to `'pipe'` to capture for assertion in tests.
     */
    readonly stderr?: 'inherit' | 'ignore' | 'pipe';
+   /**
+    * Where the connection to the child logs its protocol faults, such as a
+    * response that matches no request. Default: this process's stderr.
+    */
+   readonly logger?: ConnectionLogger;
 }
 
 /**
@@ -143,7 +155,7 @@ export function spawnDataServer<TTransfer extends TransferElement, TDiagnostic e
 
    const reader = new StreamMessageReader(child.stdout);
    const writer = new StreamMessageWriter(child.stdin);
-   const connection = createMessageConnection(reader, writer);
+   const connection = createMessageConnection(reader, writer, options.logger ?? STDERR_CONNECTION_LOGGER);
    // Consume transport error / close so a child that dies mid-stream (its stdout
    // closing, a write landing on a torn-down stdin) is observed here rather than
    // escaping as an unhandled error — the death is reported via `whenTerminated`.
@@ -224,9 +236,9 @@ export function spawnDataServer<TTransfer extends TransferElement, TDiagnostic e
  * child down afterwards. The `use` call is raced against
  * {@link DataServerHandle.whenTerminated}, so a spawn failure or a premature child
  * exit rejects with a clear message instead of hanging on an RPC that can never be
- * answered. This is the one-shot counterpart the `projects` / `query` / `save`
- * subcommands compose; `watch` races its own long-running loop against
- * `whenTerminated` directly.
+ * answered. This is the one-shot counterpart the data-server subcommands
+ * compose; `watch` races its own long-running loop against `whenTerminated`
+ * directly.
  */
 export async function withDataServer<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic, R>(
    options: SpawnDataServerOptions,

package/src/stderr-connection-logger.ts

@@ -0,0 +1,18 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 { Logger as ConnectionLogger } from 'vscode-jsonrpc/node';
+
+/** Every connection line goes to stderr: stdout carries the command's output or the protocol stream. */
+export const STDERR_CONNECTION_LOGGER: ConnectionLogger = {
+   error: message => console.error(message),
+   warn: message => console.error(message),
+   info: message => console.error(message),
+   log: message => console.error(message)
+};

package/src/testing/echo-server.ts

@@ -20,8 +20,10 @@
 
 import { DataServer } from '@hydranium/data-server';
 import { makeTestServices } from '@hydranium/core/testing';
+import { describeErrorWithStack } from '@hydranium/protocol';
 import type { AstNode, URI } from '@hydranium/langium';
-import { StreamMessageReader, StreamMessageWriter, createMessageConnection } from 'vscode-jsonrpc/node';
+import { StreamMessageReader, StreamMessageWriter, createMessageConnection, type ResponseMessage } from 'vscode-jsonrpc/node';
+import { STDERR_CONNECTION_LOGGER } from '../stderr-connection-logger.js';
 
 interface FakeRoot extends AstNode {
    readonly $type: 'FakeRoot';
@@ -72,7 +74,14 @@ function main(): void {
       }
    };
 
-   const connection = createMessageConnection(new StreamMessageReader(process.stdin), new StreamMessageWriter(process.stdout));
+   const writer = new StreamMessageWriter(process.stdout);
+   const connection = createMessageConnection(new StreamMessageReader(process.stdin), writer, STDERR_CONNECTION_LOGGER);
+
+   if (process.argv.includes('--send-response-without-id')) {
+      // A response the parent cannot match to a request, for its connection to log.
+      const response: ResponseMessage = { jsonrpc: '2.0', id: null, result: null };
+      writer.write(response).catch((error: unknown) => STDERR_CONNECTION_LOGGER.error(describeErrorWithStack(error)));
+   }
 
    if (process.argv.includes('--exit-on-request')) {
       // Fail-fast fixture mode: read a full request (the reader parses the whole

package/templates/gitignore

@@ -0,0 +1 @@
+node_modules/

package/templates/protocol/gitignore

@@ -0,0 +1,3 @@
+node_modules/
+lib/
+*.tsbuildinfo

package/templates/protocol/src/__GRAMMAR_ID__-diagram-types.ts

@@ -0,0 +1,41 @@
+// GLSP diagram-type and element-type ids for the __GRAMMAR__ diagram, which the
+// server stamps onto the graph and every client registers.
+//
+// Declared once, here, for both ends. A drift between them fails silently:
+// sprotty's registries are exact-key maps with no prefix fallback, so an id the
+// client does not know yields an element with none of a node's features,
+// rendered by `MissingView` with only a `no registered view for type '…'`
+// console warning. Nothing fails server-side.
+//
+// The ids stay namespaced under the GLSP defaults (`node:` / `edge:`) so a
+// reader can tell a node id from an edge id at a glance.
+
+import { DefaultTypes } from '@eclipse-glsp/protocol';
+import { __GRAMMAR_ID_CONST___LANGUAGE } from './generated-hydranium/languages.js';
+
+/**
+ * The GLSP diagram type — the string GLSP routes every per-diagram-type request
+ * by. A mismatch silently DROPS the request rather than reporting an unknown
+ * diagram type. Read from the language id, so renaming the language renames
+ * the diagram type at the next `generate`.
+ */
+export const __GRAMMAR_ID_CONST___DIAGRAM_TYPE = __GRAMMAR_ID_CONST___LANGUAGE.languageId;
+
+/** A `__NODE_RULE__` — the starter grammar's one named, referenceable node. */
+export const __GRAMMAR_ID_CONST___NODE_TYPE = `${DefaultTypes.NODE}:__GRAMMAR_ID__-node`;
+
+/** A resolved `target` reference, drawn as a connection between two nodes. */
+export const __GRAMMAR_ID_CONST___EDGE_TYPE = `${DefaultTypes.EDGE}:__GRAMMAR_ID__-target`;
+
+/**
+ * Every element type id the server stamps.
+ *
+ * A tuple, so {@link __GRAMMAR__ElementType} is a union of the ids rather than
+ * `string`: a client table keyed by that union does not compile while an id
+ * lacks its registration. Nothing holds the tuple to the constants above, so
+ * an id declared without joining it escapes that check.
+ */
+export const __GRAMMAR_ID_CONST___ELEMENT_TYPES = [__GRAMMAR_ID_CONST___NODE_TYPE, __GRAMMAR_ID_CONST___EDGE_TYPE] as const;
+
+/** One of the element type ids in {@link __GRAMMAR_ID_CONST___ELEMENT_TYPES}. */
+export type __GRAMMAR__ElementType = (typeof __GRAMMAR_ID_CONST___ELEMENT_TYPES)[number];

package/templates/server/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+lib/
+*.tsbuildinfo
+
+# Langium-generated TextMate grammar (rewritten by every `langium generate`).
+syntaxes/

package/templates/server/src/glsp/__GRAMMAR_ID__/create-node-operation-handler.ts

@@ -0,0 +1,62 @@
+// The starter operation handler for the __GRAMMAR__ diagram: the tool-palette
+// entry that creates a `__NODE_RULE__`.
+//
+// **Deleting this file and its `configureOperationHandlers` registration in
+// `diagram-module.ts` gives a read-only viewer**, and nothing else has to change
+// — creation is offered through the palette rather than through a type hint, so
+// every hint in `diagram-configuration.ts` is already `false`. The scaffold emits
+// the editable direction because that asymmetry runs one way: editable →
+// read-only is a deletion the compiler checks, while read-only → editable is
+// authoring against a seam you have not used yet.
+//
+// **It edits the operation's working copy.** A handler runs inside an operation,
+// where `sourceRoot` is a copy of the built root: the recording command's
+// runnable appends to the copy, and the operation writes the copy's text through
+// the grammar's `Serializer` once, gated on the version the copy was made at,
+// with undo and redo applying that one change. A command that writes the
+// document itself instead reads no text off the copy, which has no `$document`,
+// and the operation's own write then overwrites it.
+//
+// **The drop location is discarded.** `needsClientLayout` is `true` and the
+// starter grammar persists no bounds, so there is nowhere to put a coordinate: the
+// node is appended at the end of the document and the client places it.
+//
+// Like protocol's `__GRAMMAR_ID__-diagram-types.ts`, `gmodel-factory.ts` and
+// `diagram-configuration.ts`, this file knows the starter grammar's shape — the
+// `nodes` list and the `__NODE_RULE__` it holds. Replacing the grammar means
+// replacing these four together.
+
+import { type Command, type CreateNodeOperation, JsonCreateNodeOperationHandler, type MaybePromise } from '@eclipse-glsp/server';
+import { appendChild } from '@hydranium/core';
+import { HydraniumGlspRecordingCommand } from '@hydranium/glsp-server';
+import { findNextUnique } from '@hydranium/protocol';
+import { __GRAMMAR_ID_CONST___NODE_TYPE } from '__PROTOCOL_PACKAGE__';
+import { injectable } from 'inversify';
+import type { __NODE_RULE__ } from '../../language-server/ast.js';
+import type { __GRAMMAR__GlspState } from './state.js';
+
+/** Proposed name for a new node, uniquified against the ones the document already has. */
+const NODE_NAME_STEM = 'Node';
+
+@injectable()
+export class __GRAMMAR__CreateNodeOperationHandler extends JsonCreateNodeOperationHandler {
+   declare protected modelState: __GRAMMAR__GlspState;
+
+   /** The palette's word for the thing it creates, so a noun rather than an action. */
+   override readonly label = '__NODE_RULE__';
+   elementTypeIds = [__GRAMMAR_ID_CONST___NODE_TYPE];
+
+   override createCommand(operation: CreateNodeOperation): MaybePromise<Command | undefined> {
+      if (!this.elementTypeIds.includes(operation.elementTypeId)) {
+         return undefined;
+      }
+      return new HydraniumGlspRecordingCommand(this.modelState, this.label, () => {
+         const root = this.modelState.sourceRoot;
+         const name = findNextUnique(
+            NODE_NAME_STEM,
+            root.nodes.map(node => node.name)
+         );
+         appendChild(root, 'nodes', root.nodes, { $type: '__NODE_RULE__', name } as __NODE_RULE__);
+      });
+   }
+}

package/templates/server/src/glsp/__GRAMMAR_ID__/gmodel-factory.ts

@@ -0,0 +1,60 @@
+// AST → GModel for the __GRAMMAR__ diagram: one node per `__NODE_RULE__`, one
+// edge per resolved `target` reference.
+//
+// Ids come from the index rather than being composed here, so the id strategy
+// stays in one place. Nodes are emitted before edges, because a GLSP edge
+// pointing at an id that does not exist fails client-side with a far less
+// obvious error than a missing edge. An unresolved reference is SKIPPED rather
+// than treated as an error: a dangling reference is ordinary editing state, and
+// the language already reports it as a diagnostic. A reference into another
+// document is skipped for the same reason: the graph holds only this
+// document's nodes, so its target has no id here.
+
+import { DefaultTypes, GEdge, GGraph, GLabel, type GModelFactory, GNode, ModelState } from '@eclipse-glsp/server';
+import { AstUtils } from '@hydranium/langium';
+import { __GRAMMAR_ID_CONST___EDGE_TYPE, __GRAMMAR_ID_CONST___NODE_TYPE } from '__PROTOCOL_PACKAGE__';
+import { inject, injectable } from 'inversify';
+import type { __ENTRY_RULE__ } from '../../language-server/ast.js';
+import type { __GRAMMAR__GlspState } from './state.js';
+
+@injectable()
+export class __GRAMMAR__GModelFactory implements GModelFactory {
+   @inject(ModelState) protected readonly modelState!: __GRAMMAR__GlspState;
+
+   createModel(): void {
+      const root = this.modelState.sourceRoot;
+      const graph = GGraph.builder().id(this.modelState.sourceUri).build();
+      if (root) {
+         this.buildGraph(root, graph);
+      }
+      this.modelState.updateRoot(graph);
+   }
+
+   protected buildGraph(root: __ENTRY_RULE__, graph: GGraph): void {
+      for (const node of root.nodes) {
+         const id = this.modelState.index.createId(node);
+         graph.children.push(
+            GNode.builder()
+               .id(id)
+               .type(__GRAMMAR_ID_CONST___NODE_TYPE)
+               .add(GLabel.builder().id(`${id}_name`).text(node.name).type(DefaultTypes.LABEL).build())
+               .build()
+         );
+      }
+      for (const node of root.nodes) {
+         const target = node.target?.ref;
+         if (!target || AstUtils.findRootNode(target) !== root) {
+            continue;
+         }
+         const sourceId = this.modelState.index.createId(node);
+         graph.children.push(
+            GEdge.builder()
+               .id(`${sourceId}_target`)
+               .type(__GRAMMAR_ID_CONST___EDGE_TYPE)
+               .sourceId(sourceId)
+               .targetId(this.modelState.index.createId(target))
+               .build()
+         );
+      }
+   }
+}