@hydranium/cli 1.0.0-next.7 → 1.0.0-next.70

package/src/commands/generate-ast-builder.ts

@@ -0,0 +1,246 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type { SourceFile } from 'ts-morph';
+
+/** Inputs for {@link emitAstBuilder}, resolved by the transfer-model command. */
+export interface EmitAstBuilderOptions {
+   /** Destination path for the generated builder module. */
+   outFile: string;
+   /** Path to the Langium-generated AST file the builder imports from. */
+   astFile: string;
+   /** Language id derived from the `<LanguageId>AstReflection` class name. */
+   languageId: string;
+   /** Header line naming the command that regenerates the file. */
+   regenCommand: string;
+}
+
+/**
+ * A single `makeAstNodeBuilder` binding the generator emits.
+ *
+ * `typeMap` is the type expression handed to the generic — the whole-project
+ * alias for the merged binding, `<Namespace>.AstType` for a narrowed one.
+ */
+interface BuilderBinding {
+   exportName: string;
+   typeMap: string;
+   /** Grammar this binding is narrowed to; absent on the merged binding. */
+   namespace?: string;
+}
+
+/**
+ * Langium declares this type alias inside each language's namespace in a
+ * multi-language project. Its presence is what marks a namespace as a grammar's
+ * type registry rather than an incidental one.
+ */
+const NAMESPACED_AST_TYPE_NAME = 'AstType';
+
+/** Export name of the merged, whole-project binding. */
+const MERGED_EXPORT_NAME = 'astNode';
+
+/**
+ * Emit a module binding {@link makeAstNodeBuilder} to a project's reflection,
+ * once per grammar plus once across all of them.
+ *
+ * **The binding is boilerplate with exactly one degree of freedom** — the type
+ * map — so hand-writing it buys nothing and goes stale the moment a grammar is
+ * added. Generating it is also the only way a narrowed binding can exist at all:
+ * the per-grammar type maps live in namespaces Langium emits only on its
+ * multi-language path, so a single-grammar project gets the merged binding alone
+ * and there is nothing to narrow.
+ *
+ * **A narrowed binding is only as narrow as its grammar's import closure.**
+ * Langium's per-grammar `AstType` lists everything REACHABLE from that grammar,
+ * so where one grammar imports all the others its map equals the project's and
+ * its binding checks nothing the merged one does not. The emitted doc says so at
+ * each declaration rather than promising a guarantee the type map cannot give.
+ *
+ * Answers `false` when the AST source declares no whole-project type alias,
+ * which means the file did not come from `langium generate` and the caller
+ * should report rather than write a module that cannot compile.
+ */
+export function emitAstBuilder(astSource: SourceFile, options: EmitAstBuilderOptions): boolean {
+   const content = buildAstBuilderSource(astSource, options);
+   if (content === undefined) {
+      return false;
+   }
+
+   fs.mkdirSync(path.dirname(options.outFile), { recursive: true });
+   if (fs.existsSync(options.outFile) && fs.readFileSync(options.outFile, 'utf-8') === content) {
+      console.log('AST builder is up to date.');
+      return true;
+   }
+   fs.writeFileSync(options.outFile, content, 'utf-8');
+   console.log(`Generated: ${options.outFile}`);
+   return true;
+}
+
+/**
+ * The module text {@link emitAstBuilder} would write, or `undefined` when the
+ * AST source declares no whole-project type alias. Pure over its inputs, so the
+ * emitted shape is testable without touching a filesystem.
+ */
+export function buildAstBuilderSource(astSource: SourceFile, options: EmitAstBuilderOptions): string | undefined {
+   const mergedTypeMap = `${options.languageId}AstType`;
+   if (!astSource.getTypeAlias(mergedTypeMap)) {
+      return undefined;
+   }
+
+   const bindings: BuilderBinding[] = [{ exportName: MERGED_EXPORT_NAME, typeMap: mergedTypeMap }];
+   for (const namespace of findGrammarNamespaces(astSource)) {
+      bindings.push({
+         exportName: builderExportName(namespace),
+         typeMap: `${namespace}.${NAMESPACED_AST_TYPE_NAME}`,
+         namespace
+      });
+   }
+   assertDistinctExportNames(bindings);
+
+   return renderAstBuilder(bindings, {
+      reflectionName: findReflectionConstName(astSource, options.languageId),
+      importPath: relativeImportPath(options.outFile, options.astFile),
+      regenCommand: options.regenCommand
+   });
+}
+
+/**
+ * Namespaces that carry a grammar's type registry, in declaration order.
+ *
+ * Keyed on the nested `AstType` alias rather than on the namespace being
+ * exported, because an adopter's augmentation can add namespaces to the same
+ * file for unrelated reasons and only the ones Langium emits per grammar have
+ * a type map to bind.
+ */
+function findGrammarNamespaces(astSource: SourceFile): string[] {
+   const names: string[] = [];
+   for (const module of astSource.getModules()) {
+      const name = module.getName();
+      if (name && module.getTypeAlias(NAMESPACED_AST_TYPE_NAME)) {
+         names.push(name);
+      }
+   }
+   return names;
+}
+
+/**
+ * `Domain` → `domainNode`. Lower-cases the leading character only, so a grammar
+ * named `OrderFlow` reads as `orderFlowNode` rather than losing its word break.
+ */
+function builderExportName(namespace: string): string {
+   return `${namespace.charAt(0).toLowerCase()}${namespace.slice(1)}Node`;
+}
+
+/**
+ * Two grammars whose names differ only in their leading character collapse to
+ * one export. Emitting anyway would silently drop a binding, so fail with both
+ * names rather than leave the caller to discover it at compile time.
+ */
+function assertDistinctExportNames(bindings: readonly BuilderBinding[]): void {
+   const seen = new Map<string, string>();
+   for (const binding of bindings) {
+      const previous = seen.get(binding.exportName);
+      if (previous !== undefined) {
+         throw new Error(
+            `Cannot emit the AST builder: grammars '${previous}' and '${binding.namespace}' both map to the export ` +
+               `'${binding.exportName}'. Rename one grammar so the generated bindings stay distinct.`
+         );
+      }
+      seen.set(binding.exportName, binding.namespace ?? MERGED_EXPORT_NAME);
+   }
+}
+
+/**
+ * Name of the const holding the project's reflection instance.
+ *
+ * Langium emits `export const reflection = new <LanguageId>AstReflection()`, but
+ * the const is located by its initializer rather than by that name so a renamed
+ * export still resolves. Falls back to the emitted default when no declaration
+ * matches, which keeps the output compiling against a stock Langium file.
+ */
+function findReflectionConstName(astSource: SourceFile, languageId: string): string {
+   const reflectionClass = `${languageId}AstReflection`;
+   for (const declaration of astSource.getVariableDeclarations()) {
+      if (declaration.getInitializer()?.getText().replace(/\s/g, '') === `new${reflectionClass}()`) {
+         return declaration.getName();
+      }
+   }
+   return 'reflection';
+}
+
+/**
+ * Module specifier for the AST file as seen from the generated module's own
+ * directory. Emitted with a `.js` extension and posix separators because the
+ * output is ESM TypeScript, where the specifier names the compiled sibling.
+ */
+function relativeImportPath(outFile: string, astFile: string): string {
+   const relative = path.relative(path.dirname(path.resolve(outFile)), path.resolve(astFile));
+   const posix = relative.split(path.sep).join('/').replace(/\.ts$/, '.js');
+   return posix.startsWith('.') ? posix : `./${posix}`;
+}
+
+function renderAstBuilder(
+   bindings: readonly BuilderBinding[],
+   context: { reflectionName: string; importPath: string; regenCommand: string }
+): string {
+   const imported = [context.reflectionName, ...bindings.map(binding => `type ${binding.namespace ?? binding.typeMap}`)];
+   const out: string[] = [];
+
+   out.push('/******************************************************************************');
+   out.push(' * Generated from the Langium AST — DO NOT EDIT MANUALLY!');
+   out.push(` * ${context.regenCommand}`);
+   out.push(' ******************************************************************************/');
+   out.push('');
+   out.push('/* eslint-disable */');
+   out.push('');
+   out.push("import { makeAstNodeBuilder } from '@hydranium/core';");
+   out.push(`import { ${imported.join(', ')} } from '${context.importPath}';`);
+   out.push('');
+
+   // A single-grammar project has nothing to narrow to, so the merged binding is
+   // simply THE binding there and must not point at a sibling that was not emitted.
+   const narrowed = bindings.some(binding => binding.namespace !== undefined);
+   const guarantee = [
+      ' * Mandatory fields are a type error at the call site, and grammar-declared',
+      ' * containment arrays are materialised from reflection metadata, so a built',
+      ' * node carries `[]` where a cast literal would leave `undefined`.'
+   ];
+
+   for (const binding of bindings) {
+      out.push('/**');
+      if (binding.namespace !== undefined) {
+         out.push(` * AST-node factory narrowed to the '${binding.namespace}' grammar.`);
+         out.push(' *');
+         out.push(' * Narrowed by grammar REACHABILITY, not by ownership: a grammar that');
+         out.push(" * imports another sees that one's types too, so this binding is only as");
+         out.push(` * narrow as '${binding.namespace}'s import closure. Where that closure is the`);
+         out.push(' * whole project, it accepts exactly what the merged binding does and the');
+         out.push(' * choice is documentation rather than a check.');
+         out.push(' *');
+         out.push(...guarantee);
+      } else if (narrowed) {
+         out.push(' * AST-node factory spanning every grammar in this project.');
+         out.push(' *');
+         out.push(' * Prefer the narrowed binding matching the grammar the call site works in:');
+         out.push(" * it rejects a type outside that grammar's import closure, which this one");
+         out.push(' * accepts from anywhere. Reach for this one where a call site genuinely');
+         out.push(' * spans grammars.');
+      } else {
+         out.push(" * AST-node factory for this project's grammar.");
+         out.push(' *');
+         out.push(...guarantee);
+      }
+      out.push(' */');
+      out.push(`export const ${binding.exportName} = makeAstNodeBuilder<${binding.typeMap}>(${context.reflectionName});`);
+      out.push('');
+   }
+
+   return out.join('\n');
+}

package/src/commands/generate-transfer-model-args.ts

@@ -29,6 +29,7 @@ export const GENERATE_TRANSFER_MODEL_FLAGS: readonly string[] = [
    '--ast-file',
    '--augmentation-file',
    '--out-file',
+   '--ast-builder-file',
    '--element-type-name',
    '--terminals-name',
    '--terminals-source-name',
@@ -48,7 +49,8 @@ export const GENERATE_TRANSFER_MODEL_VALUE_FLAGS: readonly string[] = GENERATE_T
 export const GENERATE_TRANSFER_MODEL_HELP: readonly string[] = [
    'Usage: hydranium-cli generate-transfer-model [options]',
    '',
-   'Generate a serializable transfer-model TypeScript file from a Langium AST. The',
+   'Generate a serializable transfer-model TypeScript file from a Langium AST, and',
+   'optionally an AST-node builder module bound to the same reflection. The',
    'required inputs (--ast-file / --augmentation-file / --out-file) may instead come',
    'from a --config JSON file, and --ast-file can be auto-discovered from a Langium',
    "config's `out` directory. Precedence, highest first: explicit flags, then the",
@@ -67,6 +69,11 @@ export const GENERATE_TRANSFER_MODEL_HELP: readonly string[] = [
    '                                directory: it treats that directory as exclusively',
    '                                its own, so every `langium generate` reports this',
    '                                file as unexpected and offers to delete it.',
+   '  --ast-builder-file <path>     Also emit an AST-node builder module here: one',
+   '                                makeAstNodeBuilder binding per grammar, plus one',
+   '                                spanning all of them. Omit if nothing constructs',
+   '                                AST nodes. Same restriction as --out-file: keep it',
+   "                                out of langium-cli's own `out` directory.",
    '  --element-type-name <name>    Base element type name in output. Default: TransferElement.',
    '  --terminals-name <name>       Terminals const name in output. Default: ModelTerminals.',
    '  --terminals-source-name <n>   Source-side terminals variable name. Default: <LanguageId>Terminals.',
@@ -120,6 +127,9 @@ export function parseGenerateOptions(args: string[], onError: UsageError = exitW
          case '--out-file':
             flags.outFile = next();
             break;
+         case '--ast-builder-file':
+            flags.astBuilderFile = next();
+            break;
          case '--element-type-name':
             flags.elementTypeName = next();
             break;

package/src/commands/generate-transfer-model-config.ts

@@ -12,7 +12,7 @@ import * as path from 'node:path';
 import type { GenerateTransferModelOptions } from './generate-transfer-model.js';
 
 /** Path-valued option keys — resolved relative to a config/langium-config file's directory. */
-const PATH_KEYS = ['astFile', 'augmentationFile', 'outFile'] as const;
+const PATH_KEYS = ['astFile', 'augmentationFile', 'outFile', 'astBuilderFile'] as const;
 
 /** Resolve `value` against `baseDir` when it is relative; absolute paths pass through. */
 function resolveAgainst(baseDir: string, value: string): string {
@@ -43,6 +43,7 @@ export function loadTransferModelConfig(configPath: string): Partial<GenerateTra
       'astFile',
       'augmentationFile',
       'outFile',
+      'astBuilderFile',
       'elementTypeName',
       'terminalsName',
       'terminalsSourceName',
@@ -118,6 +119,7 @@ export function mergeTransferModelOptions(...sources: Array<Partial<GenerateTran
       astFile: astFile!,
       augmentationFile: augmentationFile!,
       outFile: outFile!,
+      astBuilderFile: pick('astBuilderFile'),
       elementTypeName: pick('elementTypeName'),
       terminalsName: pick('terminalsName'),
       terminalsSourceName: pick('terminalsSourceName'),

package/src/commands/generate-transfer-model.ts

@@ -9,6 +9,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import { emitAstBuilder } from './generate-ast-builder.js';
 import {
    type Node,
    type ObjectLiteralExpression,
@@ -35,6 +36,15 @@ export interface GenerateTransferModelOptions {
    augmentationFile: string;
    /** Destination path for the generated transfer model. */
    outFile: string;
+   /**
+    * Destination for a generated AST-node builder module. Omitted by consumers
+    * that construct no AST nodes; the transfer model is emitted either way.
+    *
+    * Emitted from this command rather than its own because the AST source is
+    * already parsed here, and because a consumer that regenerates one artefact
+    * and not the other has the two disagreeing about the same grammar.
+    */
+   astBuilderFile?: string;
    /** Name used for the base element type in the output. Defaults to `TransferElement`. */
    elementTypeName?: string;
    /** Name used for the terminal-patterns const in the output. Defaults to `ModelTerminals`. */
@@ -396,10 +406,22 @@ export function generateTransferModel(options: GenerateTransferModelOptions): vo
    fs.mkdirSync(path.dirname(options.outFile), { recursive: true });
    if (fs.existsSync(options.outFile) && fs.readFileSync(options.outFile, 'utf-8') === content) {
       console.log('Transfer model is up to date.');
-      return;
+   } else {
+      fs.writeFileSync(options.outFile, content, 'utf-8');
+      console.log(`Generated: ${options.outFile}`);
+   }
+
+   if (options.astBuilderFile !== undefined) {
+      const emitted = emitAstBuilder(astSource, {
+         outFile: options.astBuilderFile,
+         astFile: options.astFile,
+         languageId,
+         regenCommand
+      });
+      if (!emitted) {
+         console.warn(`Warning: no '${languageId}AstType' alias in ${options.astFile}; skipping the AST builder.`);
+      }
    }
-   fs.writeFileSync(options.outFile, content, 'utf-8');
-   console.log(`Generated: ${options.outFile}`);
 }
 
 // ---------------------------------------------------------------------------

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.
@@ -310,9 +300,9 @@ __BIN__  },
   ],
   "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",
@@ -439,6 +429,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],
@@ -480,7 +475,7 @@ function tsconfigJson(composition: InitComposition): string {
            ];
    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 +493,7 @@ const TSCONFIG_TEST = `{
     "isolatedModules": true,
     "types": ["node"]
   },
-  "include": ["src", "test"]
+  "include": ["src", "test", "src/**/*.json"]
 }
 `;
 
@@ -708,13 +703,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 +741,8 @@ ${returnType}
       sharedModules: {
          generated: __NAME__GeneratedSharedModule,
          adopter: __NAME__SharedModule,
-         extra: [createLspServerSharedModule(fullContext)]
+         extra: [createLspServerSharedModule(fullContext)],
+         overrides: options.extraSharedModules
       },
       languageModules: {
          generated: ${primary.grammar}GeneratedModule,
@@ -980,7 +998,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)}
 `
       : '';
 
@@ -1063,7 +1081,13 @@ 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';\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 } 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}
@@ -1117,7 +1141,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 });
@@ -1247,7 +1271,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 +1440,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',
@@ -1633,8 +1643,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 \`AstDocumentManager.save\` → \`WritableFileSystemProvider\`).
+//
+// 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.
 

package/src/commands/init.ts

@@ -9,7 +9,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { buildInitTemplates, readFrameworkVersion, UNPUBLISHED_FRAMEWORK_VERSION } from './init-templates.js';
+import { buildInitTemplates, readFrameworkVersion } from './init-templates.js';
 import { createNodeWorkspaceProbe, detectWorkspace, type JsonValue, type WorkspaceProbe } from './init-workspace.js';
 
 /**
@@ -536,13 +536,7 @@ export function runInit(options: InitCommandOptions): void {
    write('\n');
    write('Next steps:\n');
    write(`  cd ${options.targetDir}\n`);
-   // The warning is conditional on the pins this scaffold actually carries — see
-   // `UNPUBLISHED_FRAMEWORK_VERSION`.
-   write(
-      composition.frameworkVersion === UNPUBLISHED_FRAMEWORK_VERSION
-         ? '  npm install              # 404s until @hydranium/* is published — see README\n'
-         : '  npm install\n'
-   );
+   write('  npm install\n');
    write('  npm run build            # langium generate + tsc\n');
    write('  npm test                 # the scaffolded DI-composition test\n');
    // `npx`, not a bare invocation: `@hydranium/cli` is a devDependency of the

package/src/commands/watch.ts

@@ -8,7 +8,12 @@
  ********************************************************************************/
 
 import type { LogThreshold, TransferElement } from '@hydranium/protocol';
-import type { DataClientProtocol, DataServerProtocol, TransferDocumentUpdatedEvent } from '@hydranium/protocol/data';
+import type {
+   DataClientProtocol,
+   DataServerProtocol,
+   TransferDocumentDeletedEvent,
+   TransferDocumentUpdatedEvent
+} from '@hydranium/protocol/data';
 import { logLevelEnv } from '../log-level.js';
 import { spawnDataServer } from '../spawn-data-server.js';
 
@@ -132,6 +137,21 @@ export async function runWatch(options: WatchCommandOptions): Promise<void> {
       onDocumentSaved(): void {
          // Persistence is out of band for the per-URI update view.
       },
+      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.
       }

package/src/index.ts

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