@hydranium/cli 1.0.0-next.117 → 1.0.0-next.123

package/lib/commands/init-templates.js

@@ -743,9 +743,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
@@ -1172,8 +1172,8 @@ function serializationTest(composition) {
     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

package/lib/commands/save.d.ts

@@ -18,6 +18,11 @@ import type { DataServerProtocol } from '@hydranium/protocol/data';
  *
  * `clientId` defaults to `'hydranium-cli'` — adopters wanting a richer
  * identity (per-user, per-script) override.
+ *
+ * The command saves as a client session under `clientId`: it registers the
+ * session, creates the document from the content when there is no file,
+ * opens it otherwise, saves, and ends the session, which leaves nothing open
+ * behind it.
  */
 export interface SaveCommandOptions {
     readonly serverCommand: string;

package/lib/commands/save.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"save.d.ts","sourceRoot":"","sources":["../../src/commands/save.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAKnE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,cAAc,CAAC,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;IAC9D,sFAAsF;IACtF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACjE;AAED,wBAAsB,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBxE"}
+{"version":3,"file":"save.d.ts","sourceRoot":"","sources":["../../src/commands/save.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAKnE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,kBAAkB;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,cAAc,CAAC,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;IAC9D,sFAAsF;IACtF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACjE;AAED,wBAAsB,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBxE"}

package/lib/commands/save.js

@@ -14,8 +14,7 @@ export async function runSave(options) {
     const clientId = options.clientId ?? 'hydranium-cli';
     const model = await resolveContent(options.content, options.__readFileForTest);
     if (options.__proxyForTest) {
-        const doc = await options.__proxyForTest.saveModelDocument({ uri: options.uri, clientId, model, basedOn: 'anything' });
-        write(`${JSON.stringify(doc)}\n`);
+        write(`${JSON.stringify(await saveOpened(options.__proxyForTest, options.uri, clientId, model))}\n`);
         return;
     }
     await withDataServer({
@@ -24,10 +23,36 @@ export async function runSave(options) {
         cwd: options.cwd,
         env: options.logLevel ? logLevelEnv(options.logLevel) : undefined
     }, async (server) => {
-        const doc = await server.saveModelDocument({ uri: options.uri, clientId, model, basedOn: 'anything' });
-        write(`${JSON.stringify(doc)}\n`);
+        write(`${JSON.stringify(await saveOpened(server, options.uri, clientId, model))}\n`);
     });
 }
+/**
+ * Save `model` to `uri` as the session `clientId`, and end the session whether
+ * the save succeeded or not. An end that fails after a failed save is
+ * swallowed: the save's error is the one the user needs.
+ */
+async function saveOpened(server, uri, clientId, model) {
+    await server.createSession({ clientId, label: 'hydranium-cli' });
+    let saved;
+    try {
+        // The server creates a document only when it finds no file and no
+        // client has it open; anything else is opened. An open that fails
+        // reports why the create failed too, since that may be the real cause.
+        await server.createModelDocument({ uri, clientId, text: model }).catch((created) => server.openModelDocument({ uri, clientId }).catch((opened) => {
+            throw new Error(`Cannot save ${uri}: ${describe(opened)} (creating it failed first: ${describe(created)})`, { cause: created });
+        }));
+        saved = await server.saveModelDocument({ uri, clientId, model, basedOn: 'anything' });
+    }
+    catch (error) {
+        await server.closeSession({ clientId }).catch(() => undefined);
+        throw error;
+    }
+    await server.closeSession({ clientId });
+    return saved;
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 /**
  * Resolve the `--content` argument to its textual form. The `@<path>`
  * prefix reads from a file (parses as UTF-8); anything else is taken

package/lib/commands/save.js.map

@@ -1 +1 @@
-{"version":3,"file":"save.js","sourceRoot":"","sources":["../../src/commands/save.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AA6BzD,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,OAA2B;IACtD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9E,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,eAAe,CAAC;IACrD,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE/E,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,iBAAiB,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;QACvH,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClC,OAAO;IACV,CAAC;IAED,MAAM,cAAc,CACjB;QACG,OAAO,EAAE,OAAO,CAAC,aAAa;QAC9B,IAAI,EAAE,OAAO,CAAC,UAAU;QACxB,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS;KACnE,EACD,KAAK,EAAC,MAAM,EAAC,EAAE;QACZ,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;QACvG,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC,CACH,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,cAAc,CAAC,OAAe,EAAE,QAA4C;IACxF,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC9B,MAAM,MAAM,GAAG,QAAQ,IAAI,CAAC,CAAC,MAAc,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAC7E,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,OAAO,CAAC;AAClB,CAAC"}
+{"version":3,"file":"save.js","sourceRoot":"","sources":["../../src/commands/save.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/cli",
-  "version": "1.0.0-next.117",
+  "version": "1.0.0-next.123",
   "description": "Build-time codegen tools + data-server subcommands for the hydranium framework.",
   "keywords": [
     "hydranium",
@@ -65,20 +65,20 @@
     "ts-morph": "^25.0.0"
   },
   "devDependencies": {
-    "@hydranium/core": "1.0.0-next.117",
-    "@hydranium/data-server": "1.0.0-next.117",
-    "@hydranium/langium": "1.0.0-next.117",
-    "@hydranium/protocol": "1.0.0-next.117",
+    "@hydranium/core": "1.0.0-next.123",
+    "@hydranium/data-server": "1.0.0-next.123",
+    "@hydranium/langium": "1.0.0-next.123",
+    "@hydranium/protocol": "1.0.0-next.123",
     "rimraf": "^5.0.0",
     "typescript": "^5.8.0",
     "vscode-jsonrpc": "9.0.1",
     "vscode-languageserver": "~10.0.1"
   },
   "peerDependencies": {
-    "@hydranium/core": "1.0.0-next.117",
-    "@hydranium/data-server": "1.0.0-next.117",
-    "@hydranium/langium": "1.0.0-next.117",
-    "@hydranium/protocol": "1.0.0-next.117",
+    "@hydranium/core": "1.0.0-next.123",
+    "@hydranium/data-server": "1.0.0-next.123",
+    "@hydranium/langium": "1.0.0-next.123",
+    "@hydranium/protocol": "1.0.0-next.123",
     "@memlab/core": "^2.0.3",
     "@memlab/heap-analysis": "^2.0.3",
     "vscode-jsonrpc": "9.0.1"

package/src/commands/init-templates.ts

@@ -809,9 +809,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
@@ -1260,8 +1260,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

package/src/commands/save.ts

@@ -23,6 +23,11 @@ import { withDataServer } from '../spawn-data-server.js';
  *
  * `clientId` defaults to `'hydranium-cli'` — adopters wanting a richer
  * identity (per-user, per-script) override.
+ *
+ * The command saves as a client session under `clientId`: it registers the
+ * session, creates the document from the content when there is no file,
+ * opens it otherwise, saves, and ends the session, which leaves nothing open
+ * behind it.
  */
 export interface SaveCommandOptions {
    readonly serverCommand: string;
@@ -46,8 +51,7 @@ export async function runSave(options: SaveCommandOptions): Promise<void> {
    const model = await resolveContent(options.content, options.__readFileForTest);
 
    if (options.__proxyForTest) {
-      const doc = await options.__proxyForTest.saveModelDocument({ uri: options.uri, clientId, model, basedOn: 'anything' });
-      write(`${JSON.stringify(doc)}\n`);
+      write(`${JSON.stringify(await saveOpened(options.__proxyForTest, options.uri, clientId, model))}\n`);
       return;
    }
 
@@ -59,12 +63,49 @@ export async function runSave(options: SaveCommandOptions): Promise<void> {
          env: options.logLevel ? logLevelEnv(options.logLevel) : undefined
       },
       async server => {
-         const doc = await server.saveModelDocument({ uri: options.uri, clientId, model, basedOn: 'anything' });
-         write(`${JSON.stringify(doc)}\n`);
+         write(`${JSON.stringify(await saveOpened(server, options.uri, clientId, model))}\n`);
       }
    );
 }
 
+/**
+ * Save `model` to `uri` as the session `clientId`, and end the session whether
+ * the save succeeded or not. An end that fails after a failed save is
+ * swallowed: the save's error is the one the user needs.
+ */
+async function saveOpened(
+   server: Pick<
+      DataServerProtocol<TransferElement>,
+      'createSession' | 'openModelDocument' | 'createModelDocument' | 'saveModelDocument' | 'closeSession'
+   >,
+   uri: string,
+   clientId: string,
+   model: string
+): Promise<unknown> {
+   await server.createSession({ clientId, label: 'hydranium-cli' });
+   let saved: unknown;
+   try {
+      // The server creates a document only when it finds no file and no
+      // client has it open; anything else is opened. An open that fails
+      // reports why the create failed too, since that may be the real cause.
+      await server.createModelDocument({ uri, clientId, text: model }).catch((created: unknown) =>
+         server.openModelDocument({ uri, clientId }).catch((opened: unknown) => {
+            throw new Error(`Cannot save ${uri}: ${describe(opened)} (creating it failed first: ${describe(created)})`, { cause: created });
+         })
+      );
+      saved = await server.saveModelDocument({ uri, clientId, model, basedOn: 'anything' });
+   } catch (error: unknown) {
+      await server.closeSession({ clientId }).catch(() => undefined);
+      throw error;
+   }
+   await server.closeSession({ clientId });
+   return saved;
+}
+
+function describe(error: unknown): string {
+   return error instanceof Error ? error.message : String(error);
+}
+
 /**
  * Resolve the `--content` argument to its textual form. The `@<path>`
  * prefix reads from a file (parses as UTF-8); anything else is taken