@hydranium/cli 1.0.0-next.27 → 1.0.0-next.270

package/src/commands/init-templates.ts

@@ -82,16 +82,6 @@ export interface InitTemplate {
    content: string;
 }
 
-/**
- * The version every framework package carries before the first release.
- *
- * A scaffold made by a CLI still at this version pins a range the registry
- * cannot serve, so the emitted README keeps its yalc note and `init` keeps its
- * install warning while — and only while — it holds: from a published CLI the
- * derived pins resolve and either note would be false as printed.
- */
-export const UNPUBLISHED_FRAMEWORK_VERSION = '0.0.0';
-
 /**
  * The version `init` pins every `@hydranium/*` dependency at: the scaffolding
  * CLI's own.
@@ -177,7 +167,7 @@ function columnsFor(composition: InitComposition): number {
 
 /**
  * A named import on one line while it fits the column budget, else one symbol
- * per line. Emitted files are supposed to pass a prettier check as-is, and the
+ * per line. Emitted files are supposed to pass a format check as-is, and the
  * generated-module import grows by one symbol per grammar.
  */
 function importList(symbols: readonly string[], from: string, columns: number, typeOnly = false): string {
@@ -228,7 +218,12 @@ const HEAD_FRAMEWORK_DEPENDENCIES: Record<InitHead, readonly string[]> = {
 const HEAD_THIRD_PARTY_DEPENDENCIES: Record<InitHead, Readonly<Record<string, string>>> = {
    lsp: {
       langium: '4.3.1',
-      'vscode-languageserver': '~10.0.1'
+      // Exact, as are the protocol and transport it pins, so Langium and the
+      // framework share their copies; across copies, an error a handler throws
+      // or returns loses its code, and a later patch can pin another protocol.
+      'vscode-languageserver': '10.0.1',
+      'vscode-jsonrpc': '9.0.0',
+      'vscode-languageserver-protocol': '3.18.1'
    },
    data: {},
    glsp: {
@@ -241,6 +236,37 @@ const HEAD_THIRD_PARTY_DEPENDENCIES: Record<InitHead, Readonly<Record<string, st
    }
 };
 
+/**
+ * The exact pins of `heads`, for a workspace root to declare too. npm installs a
+ * root's own dependencies at the top of the tree, so another member's version of
+ * one nests beneath that member instead of taking the place of the copy this
+ * package shares with the framework.
+ */
+export function workspaceRootPins(heads: readonly InitHead[]): ReadonlyArray<readonly [string, string]> {
+   return heads
+      .flatMap(head => Object.entries(HEAD_THIRD_PARTY_DEPENDENCIES[head]))
+      .filter(([, version]) => /^\d+\.\d+\.\d+$/.test(version))
+      .sort(([left], [right]) => left.localeCompare(right));
+}
+
+/** Whether an npm version is 11.6.0 or later, the first that installs `vitest` 4.1's peer set; `11.6.0-rc.1` is earlier. */
+function installsVitest41(npmVersion: string | undefined): boolean {
+   const [release, prerelease] = (npmVersion ?? '0.0.0').split('-', 2);
+   const [major, minor, patch] = release.split('.').map(Number);
+   return major > 11 || (major === 11 && (minor > 6 || (minor === 6 && (patch > 0 || prerelease === undefined))));
+}
+
+/**
+ * Whether the scaffold holds `vitest` below 4.1, whose peer set crashes npm
+ * before 11.6 (every npm a Node 22 release bundles) on the first install. Only a
+ * workspace root declaring a newer npm lifts it, and only when `init` runs under
+ * an npm known to be newer: npm does not enforce `packageManager`.
+ */
+function pinsVitest(composition: InitComposition): boolean {
+   const workspace = composition.packaging.workspace;
+   return !(installsVitest41(workspace?.packageManagerNpm) && installsVitest41(workspace?.npmVersion));
+}
+
 /** The dependency block for a head set, merged and sorted as npm writes it. */
 function dependencyBlock(composition: InitComposition, indent: string): string {
    const merged: Record<string, string> = {};
@@ -260,7 +286,7 @@ function dependencyBlock(composition: InitComposition, indent: string): string {
 // npm convention, and `npm install` rewrites `package.json` at two spaces
 // regardless — so three would not survive the adopter's first install.
 //
-// The KEY ORDER is `prettier-plugin-packagejson`'s canonical one, `private`
+// The KEY ORDER is the one Oxfmt's `sortPackageJson` canonicalises to, `private`
 // before `license` included. Any other order is rewritten by the scaffolded
 // project's own first `format` run — a diff on a file the adopter never touched
 // — and it makes a byte-compare against a formatted copy of this emission
@@ -291,16 +317,9 @@ const PACKAGE_JSON = `{
   "version": "0.0.0",
 __PRIVATE__  "description": "__NAME__ language server, built with the Hydranium framework.",
   "keywords": [
-    "hydranium",
-    "langium",
-    "language-server",
-    "__PROJECT_ID__"
-  ],
+__KEYWORDS__  ],
   "license": "UNLICENSED",
   "author": "",
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
   "bin": {
 __BIN__  },
   "files": [
@@ -308,11 +327,14 @@ __BIN__  },
     "src",
     "syntaxes"
   ],
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "scripts": {
     "build": "npm run generate && tsc",
-    "clean": "rimraf lib syntaxes src/language-server/generated src/language-server/generated-transfer tsconfig.tsbuildinfo",
+    "clean": "rimraf lib syntaxes src/language-server/generated src/language-server/generated-hydranium tsconfig.tsbuildinfo",
     "generate": "npm run langium:generate && npm run generate:transfer-model",
-    "generate:transfer-model": "hydranium-cli generate-transfer-model --ast-file src/language-server/generated/ast.ts --augmentation-file src/language-server/ast.ts --out-file src/language-server/generated-transfer/transfer-model.ts --element-type-name __NAME__Element --terminals-name __NAME__Terminals --regen-command \\"Run: __NPM_RUN__ generate:transfer-model\\"",
+    "generate:transfer-model": "hydranium-cli generate-transfer-model --ast-file src/language-server/generated/ast.ts --augmentation-file src/language-server/ast.ts --out-file src/language-server/generated-hydranium/transfer-model.ts --ast-builder-file src/language-server/generated-hydranium/ast-builder.ts --element-type-name __NAME__Element --terminals-name __NAME__Terminals --regen-command \\"Run: __NPM_RUN__ generate:transfer-model\\"",
     "langium:generate": "langium generate",
     "langium:watch": "langium generate --watch",
 __LINT__    "start": "node lib/main.js --stdio",
@@ -328,8 +350,8 @@ __DEPENDENCIES__
     "@types/node": "^22.0.0",
     "langium-cli": "4.3.0",
     "rimraf": "^5.0.0",
-    "typescript": "^5.8.0",
-    "vitest": "^4.0.0"
+    "typescript": "^7.0.2",
+    "vitest": "__VITEST__"
   },
   "engines": {
     "node": ">=22.13"
@@ -359,7 +381,7 @@ function npmRun(composition: InitComposition): string {
  * name. Without the second key a scaffolded project has no command line that
  * reaches its own data head at all.
  *
- * Alphabetical, because `prettier-plugin-packagejson` sorts `bin` and any other
+ * Alphabetical, because Oxfmt's `sortPackageJson` sorts `bin` and any other
  * order is rewritten by the scaffolded project's first `format` run.
  */
 function binBlock(composition: InitComposition): string {
@@ -374,15 +396,32 @@ function binBlock(composition: InitComposition): string {
 function packageJson(composition: InitComposition): string {
    const { scope } = composition.packaging;
    const packageName = scope === undefined ? composition.projectId : `${scope}/${composition.projectId}`;
-   // Emitted only where a root eslint config says the repo lints. The absence is
+   const keywords =
+      ['hydranium', 'langium', 'language-server', composition.projectId]
+         .sort()
+         .map(keyword => `    ${JSON.stringify(keyword)}`)
+         .join(',\n') + '\n';
+   // Emitted only where a root lint config says the repo lints. The absence is
    // the dangerous direction: a task runner runs a script only where one is
    // declared, so a package with no `lint` is SKIPPED rather than reported, and
    // that reads as a clean lint. A wrong invocation is one visible line to edit.
-   const lint = composition.packaging.workspace?.eslintConfig === undefined ? '' : '    "lint": "eslint src test --max-warnings 0",\n';
+   const workspace = composition.packaging.workspace;
+   const oxlintConfig =
+      workspace?.oxlintConfig === undefined
+         ? undefined
+         : `${'../'.repeat(workspace.targetPath.split('/').length)}${workspace.oxlintConfig}`;
+   const lint =
+      workspace?.oxlintConfig !== undefined
+         ? `    "lint": "oxlint --report-unused-disable-directives --format stylish --config ${oxlintConfig} src test --max-warnings 0",\n`
+         : workspace?.eslintConfig !== undefined
+           ? '    "lint": "eslint src test --max-warnings 0",\n'
+           : '';
    return project(PACKAGE_JSON, composition)
       .replace('__PACKAGE_NAME__', packageName)
+      .replace('__KEYWORDS__', keywords)
       .replace('__BIN__', binBlock(composition))
       .replace('__LINT__', lint)
+      .replace('__VITEST__', pinsVitest(composition) ? '~4.0.18' : '^4.0.0')
       .replace('__PRIVATE__', composition.packaging.private ? '  "private": true,\n' : '')
       .replace('__NPM_RUN__', npmRun(composition))
       .replace('__FRAMEWORK_PIN__', frameworkPin(composition))
@@ -439,6 +478,11 @@ const TSCONFIG_COMPILER_OPTIONS: ReadonlyArray<readonly [string, JsonValue]> = [
    ['outDir', 'lib'],
    ['strict', true],
    ['esModuleInterop', true],
+   // A server that renders its own user-facing messages loads a catalogue, and
+   // a catalogue is JSON. Without this the import does not resolve at all, and
+   // without the `include` glob below a composite project rejects it with
+   // TS6307 naming neither cause.
+   ['resolveJsonModule', true],
    ['skipLibCheck', true],
    ['declaration', true],
    ['experimentalDecorators', true],
@@ -455,9 +499,20 @@ const TSCONFIG_COMPILER_OPTIONS: ReadonlyArray<readonly [string, JsonValue]> = [
  */
 const PACKAGE_LOCAL_OPTIONS: readonly string[] = ['rootDir', 'outDir'];
 
-/** Compare two JSON option values. Sound here because compiler options are scalars and flat arrays. */
-function jsonEquals(left: JsonValue | undefined, right: JsonValue): boolean {
-   return JSON.stringify(left) === JSON.stringify(right);
+/**
+ * The enum-valued options of {@link TSCONFIG_COMPILER_OPTIONS}, whose values
+ * `tsc` reads case-insensitively, so `nodenext` and `NodeNext` are one value.
+ * An enum-valued option added there belongs here too.
+ */
+const CASE_INSENSITIVE_OPTIONS: readonly string[] = ['target', 'lib', 'module', 'moduleResolution'];
+
+/** Compare two option values. Sound here because compiler options are scalars and flat arrays. */
+function optionEquals(key: string, left: JsonValue | undefined, right: JsonValue): boolean {
+   const normalise = (value: JsonValue | undefined) => {
+      const text = JSON.stringify(value);
+      return CASE_INSENSITIVE_OPTIONS.includes(key) ? text?.toLowerCase() : text;
+   };
+   return normalise(left) === normalise(right);
 }
 
 /**
@@ -476,11 +531,13 @@ function tsconfigJson(composition: InitComposition): string {
          ? TSCONFIG_COMPILER_OPTIONS
          : [
               ...TSCONFIG_COMPILER_OPTIONS.filter(([key]) => PACKAGE_LOCAL_OPTIONS.includes(key)),
-              ...TSCONFIG_COMPILER_OPTIONS.filter(([key, value]) => !PACKAGE_LOCAL_OPTIONS.includes(key) && !jsonEquals(base[key], value))
+              ...TSCONFIG_COMPILER_OPTIONS.filter(
+                 ([key, value]) => !PACKAGE_LOCAL_OPTIONS.includes(key) && !optionEquals(key, base[key], value)
+              )
            ];
    const extendsLine = workspace?.baseTsconfig === undefined ? '' : `  "extends": "${workspace.baseTsconfig}",\n`;
    const body = options.map(([key, value]) => `    "${key}": ${JSON.stringify(value)}`).join(',\n');
-   return `{\n${extendsLine}  "compilerOptions": {\n${body}\n  },\n  "include": ["src"]\n}\n`;
+   return `{\n${extendsLine}  "compilerOptions": {\n${body}\n  },\n  "include": ["src", "src/**/*.json"]\n}\n`;
 }
 
 // `isolatedModules` is what makes this check agree with the transform that
@@ -498,7 +555,7 @@ const TSCONFIG_TEST = `{
     "isolatedModules": true,
     "types": ["node"]
   },
-  "include": ["src", "test"]
+  "include": ["src", "test", "src/**/*.json"]
 }
 `;
 
@@ -518,6 +575,11 @@ export default defineConfig({
 });
 `;
 
+/**
+ * The `.gitignore`, written for a workspace member too: its root may not ignore
+ * `lib/` (a `yo langium` root ignores `out/`), and a rule the root repeats
+ * costs nothing.
+ */
 const GITIGNORE = `node_modules/
 lib/
 *.tsbuildinfo
@@ -526,27 +588,6 @@ lib/
 syntaxes/
 `;
 
-/**
- * The workspace-member `.gitignore` — one entry, and the one entry a root
- * cannot be assumed to have.
- *
- * A member inherits the root's rules, and `node_modules/`, `lib/` and
- * `*.tsbuildinfo` are in every monorepo root already, so repeating them here
- * would be three lines to keep in step for no coverage. `syntaxes/` is not like
- * them: it is a Langium artefact, so a root that has never held a Langium
- * package has no rule for it, and the first `langium generate` then offers
- * generated output up for commit with nothing to warn the adopter. Dropping the
- * whole file rather than this subset is the mistake this template exists to
- * undo.
- */
-const GITIGNORE_WORKSPACE_MEMBER = `# The workspace root already covers \`node_modules/\`, \`lib/\` and \`*.tsbuildinfo\`.
-# It has no reason to know about this one: the TextMate grammar is a Langium
-# artefact, rewritten by every \`langium generate\`, so a root that has never held
-# a Langium package ignores nothing here and the generated file is offered for
-# commit.
-syntaxes/
-`;
-
 /** The terminals every grammar needs, shared verbatim by the fragment and the lone-grammar case. */
 const TERMINALS = `hidden terminal WS: /\\s+/;
 terminal ID: /[_a-zA-Z][\\w_]*/;
@@ -708,13 +749,35 @@ export type __NAME__Services = LangiumServices &
    LspServerAddedServices & {
       shared: __NAME__SharedServices;
    };
+
+/** What a host or a test may vary about this composition. */
+export interface __NAME__Options {
+   /**
+    * Shared modules layered in after the framework's own bindings.
+    *
+    * The framework constructs most shared services with no options —
+    * \`DocumentBuilder: services => new HydraniumDocumentBuilder(services)\` — so
+    * rebinding the slot is the only way to boot one configured differently, and
+    * a factory that hard-codes its composition leaves a test nowhere to do it.
+    * That is what this is for: pass a module binding \`workspace.DocumentBuilder\`
+    * to exercise a builder option, or to substitute a subclass.
+    *
+    * Composed LAST, after \`__NAME__SharedModule\`, so it wins over every other
+    * tier including this file's own bindings — which is what makes it usable for
+    * a slot the adopter overrides. Production code should not reach for it.
+    */
+   readonly extraSharedModules?: ReadonlyArray<Module<__NAME__SharedServices, DeepPartial<__NAME__SharedServices>>>;
+}
 ${configurationRoot}
 ${sharedModule}
 
 ${languageModules}
 
 /** Compose the Langium DI tree for __NAME__ — returns the shared + language services. */
-export function create__NAME__Services(context: Partial<ServerModuleContext> = EmptyFileSystem): {
+export function create__NAME__Services(
+   context: Partial<ServerModuleContext> = EmptyFileSystem,
+   options: __NAME__Options = {}
+): {
    shared: __NAME__SharedServices;
 ${returnType}
 } {
@@ -724,7 +787,8 @@ ${returnType}
       sharedModules: {
          generated: __NAME__GeneratedSharedModule,
          adopter: __NAME__SharedModule,
-         extra: [createLspServerSharedModule(fullContext)]
+         extra: [createLspServerSharedModule(fullContext)],
+         overrides: options.extraSharedModules
       },
       languageModules: {
          generated: ${primary.grammar}GeneratedModule,
@@ -791,9 +855,9 @@ const SERIALIZER = `// Concrete-syntax emitter for __GRAMMAR__ — the parser's
 //
 // Without it every structured write fails: the framework's default binding at
 // \`services.serializer.Serializer\` THROWS, because a concrete syntax is
-// language knowledge no framework can derive. \`ModelService.update\` / \`save\`,
-// the data head's \`saveModelDocument\` and a GLSP \`SaveModelAction\` all reach
-// it.
+// language knowledge no framework can derive. A client session's \`update\` /
+// \`save\`, the data head's \`saveModelDocument\` and a GLSP \`SaveModelAction\`
+// all reach it.
 //
 // \`AbstractSerializer\`'s generic property walk lays out FORMAT-structured
 // output — its YAML and JSON subclasses are what it exists for — and cannot
@@ -980,7 +1044,7 @@ import { startGlspServer } from '@hydranium/glsp-server/node';
 // \`TransferElement\` structurally, so naming the AST type here compiles fine and
 // silently tells every typed client that a reference is a resolvable object
 // rather than a name.
-${importList(roots, './language-server/generated-transfer/transfer-model.js', columns, true)}
+${importList(roots, './language-server/generated-hydranium/transfer-model.js', columns, true)}
 `
       : '';
 
@@ -1004,19 +1068,22 @@ const dataServer = startSocketServer({ port: 0, logTag: 'ModelServer', logger: s
    return { dispose: () => undefined };
 });
 dataServer.started
-   .then(() => {
-      const { port } = dataServer;
-      if (port === undefined) {
-         // \`started\` resolves only once the address is resolved, so this is
-         // unreachable; a non-null assertion in its place would publish
-         // \`undefined\`, which the host cannot tell from an unreachable port.
-         throw new Error('the data head started without a resolved port');
-      }
-      publishPortOnLspConnection(shared.lsp.Connection, ${upper}_DATA_SERVER_PORT_COMMAND, port);
-   })
+   .then(
+      () => {
+         const { port } = dataServer;
+         if (port === undefined) {
+            // \`started\` resolves only once the address is resolved, so this is
+            // unreachable; a non-null assertion in its place would publish
+            // \`undefined\`, which the host cannot tell from an unreachable port.
+            throw new Error('the data head started without a resolved port');
+         }
+         publishPortOnLspConnection(shared.lsp.Connection, ${upper}_DATA_SERVER_PORT_COMMAND, port);
+      },
+      // The launcher logged its own bind failure; the rejection is control flow.
+      () => undefined
+   )
    .catch((error: unknown) => {
-      const reason = error instanceof Error ? error.message : String(error);
-      shared.Logger.error(\`[ModelServer] Could not publish the data-server port: \${reason}\`);
+      shared.Logger.error(\`[ModelServer] Could not publish the data-server port: \${describeErrorWithStack(error)}\`);
    });
 `
       : '';
@@ -1063,11 +1130,17 @@ void glspServer;
 // than a library entry — import \`./index.js\` instead to compose the language.
 
 ${reflectImport}${glspImports}${importList(coreNodeSymbols, '@hydranium/core/node', columns)}
-${data ? "import { DataServer } from '@hydranium/data-server';\n" : ''}import { startLanguageServer } from '@hydranium/langium/lsp';
+${data ? "import { DataServer } from '@hydranium/data-server';\nimport { describeErrorWithStack } from '@hydranium/protocol';\n" : ''}// The framework's entry point, NOT Langium's \`@hydranium/langium/lsp\` one. It is
+// signature-compatible and delegates straight through; what it adds first is
+// \`assertLspHeadComposed\`, which fails the start if the LSP head's SHARED module
+// was never composed. Reaching for Langium's is the natural mistake and it is
+// silent: the server boots, links and completes, while echo suppression, the
+// didChangeContent debounce and the last-client-close rebuild are all inert.
+import { startLanguageServer, withHydraniumLspFeatures } from '@hydranium/core/lsp';
 import { ProposedFeatures, createConnection } from 'vscode-languageserver/node';
 ${diagramImports}${transferImports}import { create__NAME__Services } from './language-server/__PROJECT_ID__-module.js';
 ${portCommands === '' ? '' : '\n' + portCommands}
-const connection = createConnection(ProposedFeatures.all);
+const connection = createConnection(withHydraniumLspFeatures(ProposedFeatures.all));
 const { shared } = create__NAME__Services({ connection, ...NodeFileSystem });
 startLanguageServer(shared);
 ${dataBlock}${glspBlock}`;
@@ -1117,7 +1190,7 @@ function dataServerMainFile(composition: InitComposition): string {
 ${importList(['NodeFileSystem', 'startStdioServer'], '@hydranium/core/node', columns)}
 import { DataServer } from '@hydranium/data-server';
 // The TRANSFER root${plural}, not the AST one${plural} — same reasoning as \`main.ts\`.
-${importList(roots, './language-server/generated-transfer/transfer-model.js', columns, true)}
+${importList(roots, './language-server/generated-hydranium/transfer-model.js', columns, true)}
 import { create__NAME__Services } from './language-server/__PROJECT_ID__-module.js';
 
 const { shared } = create__NAME__Services({ ...NodeFileSystem });
@@ -1236,8 +1309,8 @@ function serializationTest(composition: InitComposition): string {
    const transferTypes = composition.grammars.map(grammar => `${grammar.entryRule} as Transfer${grammar.entryRule}`);
    const text = `// Round-trips each grammar through its serializer: parse the source, serialize
 // the model, compare the text. The serializer is the parser's inverse, so this
-// is the assertion that keeps \`ModelService.update\` / \`save\` writing files the
-// language server can read back.
+// is the assertion that keeps a client session's \`update\` / \`save\` writing
+// files the language server can read back.
 //
 // The transfer case is the one that catches the mistake worth catching.
 // \`ModelService.modelToText\` short-circuits only a RAW STRING, so a typed model
@@ -1247,7 +1320,7 @@ function serializationTest(composition: InitComposition): string {
 import { parseHelper } from '@hydranium/core/testing';
 import { describe, expect, it } from 'vitest';
 ${importList(astTypes, '../src/language-server/ast.js', columns, true)}
-${importList(transferTypes, '../src/language-server/generated-transfer/transfer-model.js', columns, true)}
+${importList(transferTypes, '../src/language-server/generated-hydranium/transfer-model.js', columns, true)}
 import { createServices } from '../src/services.js';
 
 ${composition.grammars.map(grammar => render(SERIALIZATION_SUITE, composition, grammar)).join('\n\n')}
@@ -1416,20 +1489,6 @@ function readme(composition: InitComposition): string {
       '',
       '## Getting started',
       '',
-      // Conditional on the pin this scaffold actually carries — see
-      // `UNPUBLISHED_FRAMEWORK_VERSION`.
-      ...(composition.frameworkVersion === UNPUBLISHED_FRAMEWORK_VERSION
-         ? [
-              '> **Pre-publish note.** `@hydranium/*` is not on npm yet, so the `0.0.0`',
-              '> pins below are placeholders and `npm install` will fail with a 404 until',
-              '> the framework is released. Until then, supply the packages from a local',
-              '> framework checkout with [yalc](https://github.com/wclr/yalc) — a plain',
-              '> `file:` path or `npm link` is not enough, because the framework packages',
-              '> depend on each other by version and npm would try to fetch those from the',
-              '> registry too.',
-              ''
-           ]
-         : []),
       '```bash',
       'npm install',
       'npm run langium:generate   # generate the AST from the grammar',
@@ -1543,6 +1602,24 @@ function readme(composition: InitComposition): string {
       'atomic set and depends on a single physical copy, so a floating range can',
       'silently resolve a second one.',
       '',
+      '`vscode-languageserver` is pinned to `10.0.1`, and',
+      '`vscode-languageserver-protocol` and `vscode-jsonrpc` to the `3.18.1` and',
+      '`9.0.0` it pins, so Langium, the LSP connection and the framework share one',
+      'copy of each. With two, an error a Langium handler returns, such as a request',
+      'for a document the server does not have, reaches the client as a result, and a',
+      'framework error your own LSP handler throws loses its code. The Langium 4.4',
+      'upgrade',
+      '([eclipse-emfcloud/hydranium#142](https://github.com/eclipse-emfcloud/hydranium/issues/142))',
+      'replaces these pins.',
+      '',
+      ...(pinsVitest(composition)
+         ? [
+              '`vitest` is held below 4.1, whose peer set crashes the npm every Node 22',
+              'release bundles. Raise it once every npm that installs this project is',
+              '11.6 or later.',
+              ''
+           ]
+         : []),
       '## If your repo gates license headers',
       '',
       'The emitted `.ts` files carry no copyright header — the scaffold cannot know',
@@ -1562,10 +1639,9 @@ function readme(composition: InitComposition): string {
 /**
  * The GLSP files for ONE grammar's diagram.
  *
- * Per grammar rather than per project because a diagram type has exactly one
- * grammar — `AbstractHydraniumGlspDiagramModule.declareLanguage()` returns that
- * grammar's `LanguageMetaData`, and it is bound on the SESSION container so a
- * grammar with no diagram can sit on the same server.
+ * Per grammar rather than per project because the state, storage and GModel
+ * factory are typed over that grammar's model, and a grammar with no diagram
+ * can sit on the same server.
  *
  * The index and the computed-bounds handler are framework classes used
  * unmodified; storage and the submission handler are thin typed subclasses,
@@ -1633,8 +1709,11 @@ export class __GRAMMAR__GlspState extends FullTextHydraniumGlspState<__ENTRY_RUL
 
    const storage = `// Source-model storage for the __GRAMMAR__ diagram, inheriting both framework
 // defaults: \`loadSourceModel\` (open + settle + \`setSourceRoot\`) and
-// \`saveSourceModel\` (through \`ModelService.save\` → the per-URI \`Serializer\` →
-// the multi-client text store → \`WritableFileSystemProvider\`).
+// \`saveSourceModel\` (flush the store's text for the primary and every tracked
+// secondary through the diagram's client session).
+//
+// No serializer runs on the save path — a save persists what the diagram's
+// operations already wrote to the store.
 //
 // The subclass exists so a bespoke load or save has a stable place to land.
 
@@ -1798,27 +1877,28 @@ export class __GRAMMAR__DiagramConfiguration implements DiagramConfiguration {
 // read-only is a deletion the compiler checks, while read-only → editable is
 // authoring against a seam you have not used yet.
 //
-// **It composes TEXT rather than mutating the AST.** The source model of
-// \`FullTextHydraniumGlspState\` is the document text, and reading it back through
-// \`state.sourceModel\` serialises the AST through the per-URI \`Serializer\`, which
-// this scaffold does not bind — so that getter throws until you do. Appending a
-// declaration to the text the parser last read needs no serializer, which is what
-// makes a scaffolded diagram editable on day one. Bind a \`Serializer\` at
-// \`services.serializer.Serializer\` and this becomes a
-// \`HydraniumGlspRecordingCommand\` over \`state.sourceModel\` instead — the same
-// binding the diagram's own save action needs.
+// **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 \`types.ts\`, \`gmodel-factory.ts\` and \`diagram-configuration.ts\`, this file
-// knows the starter grammar's concrete syntax — the \`node\` keyword below is that
-// grammar's. Replacing the grammar means replacing these four together.
+// 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 { injectable } from 'inversify';
+import type { __NODE_RULE__ } from '../../language-server/ast.js';
 import { ${upper}_NODE_TYPE } from './types.js';
 import type { __GRAMMAR__GlspState } from './state.js';
 
@@ -1837,46 +1917,20 @@ export class __GRAMMAR__CreateNodeOperationHandler extends JsonCreateNodeOperati
       if (!this.elementTypeIds.includes(operation.elementTypeId)) {
          return undefined;
       }
-      const state = this.modelState;
-      const before = this.documentText();
-      const after = this.withNode(
-         before,
-         findNextUnique(
+      return new HydraniumGlspRecordingCommand(this.modelState, this.label, () => {
+         const root = this.modelState.sourceRoot;
+         const name = findNextUnique(
             NODE_NAME_STEM,
-            state.sourceRoot.nodes.map(node => node.name)
-         )
-      );
-      // Whole-document undo, which is all a full-text source model can offer: it
-      // has exactly one field, so there is nothing to merge a concurrent edit into.
-      return {
-         execute: () => state.updateSourceModel({ text: after }),
-         undo: () => state.updateSourceModel({ text: before }),
-         redo: () => state.updateSourceModel({ text: after })
-      };
-   }
-
-   /** The text the captured source root was parsed from — the baseline an edit appends to. */
-   protected documentText(): string {
-      return this.modelState.sourceRoot.$document?.textDocument.getText() ?? '';
-   }
-
-   /** \`text\` with one more node declaration, under exactly one trailing newline. */
-   protected withNode(text: string, name: string): string {
-      const body = text.trimEnd();
-      const declaration = \`node \${name}\`;
-      return body.length === 0 ? \`\${declaration}\\n\` : \`\${body}\\n\${declaration}\\n\`;
+            root.nodes.map(node => node.name)
+         );
+         appendChild(root, 'nodes', root.nodes, { $type: '__NODE_RULE__', name } as __NODE_RULE__);
+      });
    }
 }
 `;
 
    const module = `// GLSP diagram module for __GRAMMAR__ — the DI wiring of one diagram type.
 //
-// \`declareLanguage\` is the multi-grammar seam: it binds the grammar this diagram
-// edits on the SESSION container, so \`modelState.diagramLanguage\` and the
-// per-language lookups resolve to __LANGUAGE_ID__. That is what stops one
-// diagram type from fighting over a process-wide binding when a project holds
-// several grammars — a grammar with no diagram is registered on the same server.
-//
 // \`configureActionHandlers\` REBINDS rather than adds: GLSP's own
 // \`DiagramModule\` already registers \`ComputedBoundsActionHandler\`, and two
 // handlers for one action would both run.
@@ -1903,13 +1957,11 @@ ${importList(
    true
 )}
 import { ComputedBoundsActionHandler } from '@eclipse-glsp/server';
-import type { LanguageMetaData } from '@hydranium/langium';
 ${importList(
    ['HydraniumGlspComputedBoundsActionHandler', 'AbstractHydraniumGlspDiagramModule', 'HydraniumGlspIndex'],
    '@hydranium/glsp-server',
    columns
 )}
-import { __GRAMMAR__LanguageMetaData } from '../../language-server/generated/module.js';
 import { __GRAMMAR__CreateNodeOperationHandler } from './create-node-operation-handler.js';
 import { __GRAMMAR__DiagramConfiguration } from './diagram-configuration.js';
 import { __GRAMMAR__GModelFactory } from './gmodel-factory.js';
@@ -1921,10 +1973,6 @@ import { ${upper}_DIAGRAM_TYPE } from './types.js';
 export class __GRAMMAR__DiagramModule extends AbstractHydraniumGlspDiagramModule {
    readonly diagramType = ${upper}_DIAGRAM_TYPE;
 
-   protected override declareLanguage(): LanguageMetaData {
-      return __GRAMMAR__LanguageMetaData;
-   }
-
    protected override bindModelState(): BindingTarget<ModelState> {
       return { service: __GRAMMAR__GlspState };
    }
@@ -1960,6 +2008,76 @@ export class __GRAMMAR__DiagramModule extends AbstractHydraniumGlspDiagramModule
       binding.add(__GRAMMAR__CreateNodeOperationHandler);
    }
 }
+`;
+
+   const diagramTest = `// The starter create-node handler, run the way a client runs it: an in-process
+// GLSP server opens a document, a create-node operation adds a node, and an undo
+// and a redo take it out and put it back. Every step must keep the nodes the
+// document already had, and its comments: the diagram writes the document from
+// its AST, which carries none.
+
+import 'reflect-metadata';
+import { type Action, CreateNodeOperation, RedoAction, ServerModule, SetDirtyStateAction, UndoAction } from '@eclipse-glsp/server';
+import { initializeWorkspaceProgrammatically } from '@hydranium/core';
+import { makeScratchWorkspace, type ScratchWorkspace } from '@hydranium/core/testing/node';
+import { HydraniumGlspAppModule } from '@hydranium/glsp-server';
+import { type GlspHarness, makeGlspHarness } from '@hydranium/glsp-server/testing';
+import { waitFor } from '@hydranium/protocol/testing';
+import { afterEach, describe, expect, it } from 'vitest';
+import { __GRAMMAR__DiagramModule } from '../src/glsp/__GRAMMAR_ID__/diagram-module.js';
+import type { __GRAMMAR__GlspState } from '../src/glsp/__GRAMMAR_ID__/state.js';
+import { ${upper}_DIAGRAM_TYPE, ${upper}_NODE_TYPE } from '../src/glsp/__GRAMMAR_ID__/types.js';
+import { createServices } from '../src/services.js';
+
+let workspace: ScratchWorkspace | undefined;
+let diagram: GlspHarness<__GRAMMAR__GlspState> | undefined;
+
+afterEach(() => {
+   diagram?.dispose();
+   workspace?.dispose();
+   diagram = undefined;
+   workspace = undefined;
+});
+
+/** Send \`action\` and wait for the dirty state the server answers it with, which it sends once the edit is written. */
+async function send(harness: GlspHarness<__GRAMMAR__GlspState>, action: Action, reason: string): Promise<void> {
+   const before = harness.actions.length;
+   harness.dispatch(action);
+   await waitFor(() => harness.actions.slice(before).some(sent => SetDirtyStateAction.is(sent) && sent.reason === reason), {
+      message: \`no '\${reason}' dirty state\`
+   });
+}
+
+describe('__GRAMMAR__ diagram', () => {
+   it('creates a node after the existing ones, keeping their comments, and undoes and redoes it', async () => {
+      workspace = makeScratchWorkspace({ prefix: '__GRAMMAR_ID__-diagram-' });
+      const original = '// keep this comment\\nnode first -> second\\n// about second\\nnode second';
+      const file = workspace.write('model.__EXTENSION__', original);
+      const { shared } = createServices();
+      await initializeWorkspaceProgrammatically(shared, workspace.root);
+      diagram = makeGlspHarness<__GRAMMAR__GlspState>({
+         serverModule: new ServerModule().configureDiagramModule(new __GRAMMAR__DiagramModule()),
+         diagramType: ${upper}_DIAGRAM_TYPE,
+         appModules: [new HydraniumGlspAppModule({ shared })]
+      });
+      await diagram.start();
+      await diagram.openDocument(file);
+      const uri = workspace.uri('model.__EXTENSION__');
+      const text = (): string | undefined => shared.workspace.TextDocuments.get(uri)?.getText();
+
+      await send(diagram, CreateNodeOperation.create(${upper}_NODE_TYPE), 'operation');
+      const created = text();
+      await send(diagram, UndoAction.create(), 'undo');
+      const undone = text();
+      await send(diagram, RedoAction.create(), 'redo');
+
+      expect({ created, undone, redone: text() }).toEqual({
+         created: \`\${original}\\nnode Node\`,
+         undone: original,
+         redone: \`\${original}\\nnode Node\`
+      });
+   });
+});
 `;
 
    return [
@@ -1970,7 +2088,8 @@ export class __GRAMMAR__DiagramModule extends AbstractHydraniumGlspDiagramModule
       { path: `${dir}/gmodel-factory.ts`, content: render(factory) },
       { path: `${dir}/diagram-configuration.ts`, content: render(configuration) },
       { path: `${dir}/create-node-operation-handler.ts`, content: render(createHandler) },
-      { path: `${dir}/diagram-module.ts`, content: render(module) }
+      { path: `${dir}/diagram-module.ts`, content: render(module) },
+      { path: `test/${grammar.grammarId}-diagram.test.ts`, content: render(diagramTest) }
    ];
 }
 
@@ -1999,10 +2118,7 @@ export function buildInitTemplates(composition: InitComposition): InitFile[] {
       { path: 'tsconfig.json', content: tsconfigJson(composition) },
       { path: 'tsconfig.test.json', content: TSCONFIG_TEST },
       { path: 'vitest.config.ts', content: VITEST_CONFIG },
-      {
-         path: '.gitignore',
-         content: composition.packaging.workspace === undefined ? GITIGNORE : GITIGNORE_WORKSPACE_MEMBER
-      },
+      { path: '.gitignore', content: GITIGNORE },
       { path: 'README.md', content: readme(composition) },
       ...grammarFiles,
       { path: `src/language-server/${composition.projectId}-module.ts`, content: moduleFile(composition) },