@hydranium/cli 1.0.0-next.304 → 1.0.0-next.305

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,61 @@
+// 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 `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 { injectable } from 'inversify';
+import type { __NODE_RULE__ } from '../../language-server/ast.js';
+import { __GRAMMAR_ID_CONST___NODE_TYPE } from './types.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,57 @@
+// 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 LSP head already reports it as a diagnostic.
+
+import { DefaultTypes, GEdge, GGraph, GLabel, type GModelFactory, GNode, ModelState } from '@eclipse-glsp/server';
+import { inject, injectable } from 'inversify';
+import type { __ENTRY_RULE__ } from '../../language-server/ast.js';
+import { __GRAMMAR_ID_CONST___EDGE_TYPE, __GRAMMAR_ID_CONST___NODE_TYPE } from './types.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) {
+            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()
+         );
+      }
+   }
+}

package/templates/server/src/glsp/__GRAMMAR_ID__/state.ts

@@ -0,0 +1,18 @@
+// GLSP state for the __GRAMMAR__ diagram.
+//
+// `FullTextHydraniumGlspState` is the simplest of the framework source-model
+// strategies (the others project a structured transfer model, over one document
+// or several): the source model is the whole document text, serialised through
+// the per-URI `Serializer` and round-tripped by re-parsing. Both seams resolve
+// through shared services, so narrowing the root type is all an adopter adds.
+//
+// It cannot field-merge — every concurrent edit on a whole-document model is a
+// same-document collision, so undo / redo degrade to drop-on-divergence. Move to
+// `ReconcilingTransferHydraniumGlspState` when you need field-level undo.
+
+import { FullTextHydraniumGlspState } from '@hydranium/glsp-server';
+import { injectable } from 'inversify';
+import type { __ENTRY_RULE__ } from '../../language-server/ast.js';
+
+@injectable()
+export class __GRAMMAR__GlspState extends FullTextHydraniumGlspState<__ENTRY_RULE__> {}

package/templates/server/src/glsp/__GRAMMAR_ID__/storage.ts

@@ -0,0 +1,16 @@
+// Source-model storage for the __GRAMMAR__ diagram, inheriting both framework
+// defaults: `loadSourceModel` (open + settle + `setSourceRoot`) and
+// `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.
+
+import { type FullTextSourceModel, HydraniumGlspStorage } from '@hydranium/glsp-server';
+import { injectable } from 'inversify';
+import type { __ENTRY_RULE__ } from '../../language-server/ast.js';
+
+@injectable()
+export class __GRAMMAR__GlspStorage extends HydraniumGlspStorage<__ENTRY_RULE__, FullTextSourceModel> {}

package/templates/server/src/glsp/__GRAMMAR_ID__/submission-handler.ts

@@ -0,0 +1,24 @@
+// Submission handler for the __GRAMMAR__ diagram.
+//
+// Inherits the framework's `readyEvent = IntegrityService.SettledState`, which
+// is load-bearing rather than incidental: the GModel factory resolves
+// `target.ref`, so it needs a fully-linked AST. Without the gate those reads
+// fire mid-build and warn about resolution before scopes are computed.
+//
+// Only `formatSourceRoot` is overridden, so the submit log names the model and
+// its node count instead of a bare `$type`.
+
+import { ModelState } from '@eclipse-glsp/server';
+import { type FullTextSourceModel, HydraniumGlspSubmissionHandler } from '@hydranium/glsp-server';
+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__SubmissionHandler extends HydraniumGlspSubmissionHandler<__ENTRY_RULE__, FullTextSourceModel> {
+   @inject(ModelState) declare protected modelState: __GRAMMAR__GlspState;
+
+   protected override formatSourceRoot(root: __ENTRY_RULE__ | undefined): string {
+      return root ? `__ENTRY_RULE__ nodes=${root.nodes.length}` : 'none';
+   }
+}

package/templates/server/src/glsp/__GRAMMAR_ID__/types.ts

@@ -0,0 +1,26 @@
+// GLSP diagram-type and element-type ids for the __GRAMMAR__ diagram.
+//
+// **Authoritative half of a client/server contract.** Every id here has to be
+// registered on the client too: 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/server';
+
+/**
+ * The GLSP diagram type — the string GLSP routes every per-diagram-type request
+ * by. Mirrored by the client; a mismatch silently DROPS the request rather than
+ * reporting an unknown diagram type. Same value as the language id, so the two
+ * cannot drift apart as a diagram gains element types.
+ */
+export const __GRAMMAR_ID_CONST___DIAGRAM_TYPE = '__LANGUAGE_ID__';
+
+/** 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`;

package/templates/server/src/grammar/common.langium

@@ -0,0 +1,12 @@
+// Shared lexical basis for this project's grammars. Imported, never registered:
+// it has no entry rule and no `langium-config.json` entry, so it is a fragment
+// rather than a language.
+//
+// Keeping the tokens here rather than in one of the languages means a grammar
+// imports `common` for its TOKENS and another language only when it needs that
+// language's TYPES — separate reasons that are worth keeping separate.
+
+hidden terminal WS: /\s+/;
+terminal ID: /[_a-zA-Z][\w_]*/;
+hidden terminal SL_COMMENT: /\/\/[^\n\r]*/;
+hidden terminal ML_COMMENT: /\/\*[\s\S]*?\*\//;

package/templates/server/src/language-server/__GRAMMAR_ID__-serializer.ts

@@ -0,0 +1,53 @@
+// Concrete-syntax emitter for __GRAMMAR__ — the parser's inverse, turning a
+// model back into text this grammar accepts. Derived from the starter grammar
+// exactly as `generated/ast.ts` is, so replacing the grammar replaces this too.
+//
+// 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. 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
+// produce a keyword-delimited syntax like `node a -> b`. So `serializeNode` is
+// a per-`$type` emitter here and the two array hooks are unreachable.
+
+import { AbstractSerializer } from '@hydranium/core';
+import type { AstNode } from '@hydranium/langium';
+import { type __ENTRY_RULE__, type __NODE_RULE__, is__ENTRY_RULE__, is__NODE_RULE__ } from './ast.js';
+
+export class __GRAMMAR__Serializer extends AbstractSerializer<__ENTRY_RULE__> {
+   protected override serializeNode(node: AstNode | Record<string, unknown>): string {
+      if (is__ENTRY_RULE__(node)) {
+         return node.nodes.map(child => this.emitNode(child)).join('\n');
+      }
+      if (is__NODE_RULE__(node)) {
+         return this.emitNode(node);
+      }
+      // Defensive: a rule added to the grammar with no emitter added here.
+      throw new Error(`__GRAMMAR__Serializer: no emitter for $type ${(node as AstNode).$type}`);
+   }
+
+   /** Unreachable — this grammar's one list is emitted by its `__ENTRY_RULE__` parent. */
+   protected override serializeArray(): string {
+      throw new Error('__GRAMMAR__Serializer: arrays are emitted by the per-$type parent, not the generic dispatch.');
+   }
+
+   /** Unreachable — same reasoning as {@link serializeArray}. */
+   protected override serializeReferenceArray(): string {
+      throw new Error('__GRAMMAR__Serializer: reference arrays are emitted by the per-$type parent, not the generic dispatch.');
+   }
+
+   /**
+    * `serializeReferenceText` rather than `node.target?.$refText`: it is the one
+    * read that spans BOTH input shapes. A transfer model reaching
+    * `serializeTransfer` carries `target` as a plain string rather than a
+    * `Reference`, and a serializer that reaches for `$refText` directly emits
+    * the AST correctly and drops every reference on the transfer path.
+    */
+   private emitNode(node: __NODE_RULE__): string {
+      const target = this.serializeReferenceText(node.target);
+      return target === undefined ? `node ${node.name}` : `node ${node.name} -> ${target}`;
+   }
+}

package/templates/server/src/language-server/ast.ts

@@ -0,0 +1,23 @@
+// The language's AST entry point: a re-export of what `langium generate`
+// emits, plus anywhere you augment those types.
+//
+// Import the AST from HERE rather than from `./generated/ast.js`, so any
+// augmentation below travels with every import. One `langium-cli` run over N
+// grammars emits ONE combined AST module sharing one reflection, so a further
+// grammar needs no change here.
+//
+// `generate:transfer-model` reads this file as its `--augmentation-file`: the
+// generated wire types are derived from the AST *as augmented*, not from the
+// raw generated module. Augment a type here and the transfer model follows.
+//
+// A `@derived` property is computed at build time rather than parsed, so it is
+// declared here and populated by an AST-extension contribution:
+//
+// declare module './generated/ast.js' {
+//    interface __ENTRY_RULE__ {
+//       /** @derived Populated by an `ast.extensions.computedProperties` contribution. */
+//       readonly _summary?: string;
+//    }
+// }
+
+export * from './generated/ast.js';

package/templates/server/src/services.ts

@@ -0,0 +1,12 @@
+// Zero-arg service factory for the headless `hydranium-cli` tooling: the
+// `reflect` / `lint-grammar` / `validate` subcommands import this via
+// `--services ./lib/services.js`. The head wires its own filesystem here.
+//
+// The contract is language-count-agnostic — a second grammar needs no edit here.
+
+import { NodeFileSystem } from '@hydranium/core/node';
+import { create__NAME__Services } from './language-server/__PROJECT_ID__-module.js';
+
+export function createServices(): ReturnType<typeof create__NAME__Services> {
+   return create__NAME__Services({ ...NodeFileSystem });
+}

package/templates/server/test/__GRAMMAR_ID__-diagram.test.ts

@@ -0,0 +1,68 @@
+// 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 { __GRAMMAR_ID_CONST___DIAGRAM_TYPE, __GRAMMAR_ID_CONST___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: __GRAMMAR_ID_CONST___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(__GRAMMAR_ID_CONST___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`
+      });
+   });
+});

package/templates/server/test/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.test.json",
+  "include": ["../src", ".", "../src/**/*.json"]
+}

package/templates/server/tsconfig.test.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "noEmit": true,
+    "isolatedModules": true,
+    "types": ["node"]
+  },
+  "include": ["src", "test", "src/**/*.json"]
+}

package/templates/server/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config';
+
+// Vitest transforms TypeScript itself and resolves `.js` specifiers to their
+// `.ts` source, so tests import from `../src/` with the same specifiers the
+// compiled output uses. `include` is scoped to `test/` so `lib/` is never
+// scanned; `npm test` runs `typecheck:test` first, because vitest's
+// transform strips types without checking them.
+
+export default defineConfig({
+   test: {
+      environment: 'node',
+      include: ['test/**/*.{test,spec}.ts']
+   }
+});