@hydranium/cli 1.0.0-next.18 → 1.0.0-next.181

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 {
@@ -260,7 +250,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 +281,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 +291,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,7 +314,7 @@ __DEPENDENCIES__
     "@types/node": "^22.0.0",
     "langium-cli": "4.3.0",
     "rimraf": "^5.0.0",
-    "typescript": "^5.8.0",
+    "typescript": "^7.0.2",
     "vitest": "^4.0.0"
   },
   "engines": {
@@ -359,7 +345,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,13 +360,29 @@ 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('__PRIVATE__', composition.packaging.private ? '  "private": true,\n' : '')
@@ -439,6 +441,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 +487,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 +505,7 @@ const TSCONFIG_TEST = `{
     "isolatedModules": true,
     "types": ["node"]
   },
-  "include": ["src", "test"]
+  "include": ["src", "test", "src/**/*.json"]
 }
 `;
 
@@ -708,13 +715,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 +753,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 +821,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 +1010,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,11 +1093,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';\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 +1153,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 +1272,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 +1283,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 +1452,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 +1655,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-workspace.ts

@@ -186,10 +186,12 @@ export interface WorkspaceDetection {
    readonly baseTsconfig?: string;
    /** That tsconfig's `compilerOptions`, so the emitted one can drop what it inherits. */
    readonly baseCompilerOptions?: Readonly<Record<string, JsonValue>>;
-   /** The root prettier config's `printWidth`, so emitted sources wrap where the repo wraps. */
+   /** The root formatter config's `printWidth`, so emitted sources wrap where the repo wraps. */
    readonly printWidth?: number;
    /** Filename of the root eslint config, when there is one. Absent means the repo does not lint. */
    readonly eslintConfig?: string;
+   /** Filename of the root Oxlint config, when present. */
+   readonly oxlintConfig?: string;
 }
 
 /**
@@ -339,7 +341,7 @@ export function findBaseTsconfig(
 }
 
 /**
- * The repo's prettier `printWidth`, so the emitted sources wrap where the repo
+ * The repo's formatter `printWidth`, so the emitted sources wrap where the repo
  * wraps instead of at the scaffold's own default.
  *
  * **Why this is worth detecting at all.** There is no width that is stable for
@@ -360,19 +362,21 @@ export function findBaseTsconfig(
  * adopter's formatter rewraps on first commit. So a heuristic that is usually
  * right strictly improves on no detection, and can break nothing.
  */
-export function findPrettierPrintWidth(rootDir: string, probe: WorkspaceProbe): number | undefined {
+export function findFormatterPrintWidth(rootDir: string, probe: WorkspaceProbe): number | undefined {
    const manifest = probe.readJson(path.join(rootDir, 'package.json'));
    if (isJsonObject(manifest) && isJsonObject(manifest.prettier) && typeof manifest.prettier.printWidth === 'number') {
       return manifest.prettier.printWidth;
    }
    const present = probe.listFiles(rootDir);
-   for (const file of present.filter(name => name === '.prettierrc' || name === '.prettierrc.json')) {
+   for (const file of present.filter(name => name === '.oxfmtrc.json' || name === '.prettierrc' || name === '.prettierrc.json')) {
       const parsed = probe.readJson(path.join(rootDir, file));
       if (isJsonObject(parsed) && typeof parsed.printWidth === 'number') {
          return parsed.printWidth;
       }
    }
-   for (const file of present.filter(name => /^(\.prettierrc\.[cm]?[jt]s|prettier\.config\.[cm]?[jt]s)$/.test(name))) {
+   for (const file of present.filter(name =>
+      /^(\.prettierrc\.[cm]?[jt]s|prettier\.config\.[cm]?[jt]s|oxfmt\.config\.[cm]?[jt]s)$/.test(name)
+   )) {
       const width = /\bprintWidth\s*:\s*(\d+)/.exec(probe.readText(path.join(rootDir, file)) ?? '');
       if (width) {
          return Number(width[1]);
@@ -398,6 +402,11 @@ export function findEslintConfig(rootDir: string, probe: WorkspaceProbe): string
    return probe.listFiles(rootDir).find(name => /^eslint\.config\.[cm]?[jt]s$/.test(name) || /^\.eslintrc(\..+)?$/.test(name));
 }
 
+/** Detect Oxlint without evaluating executable configuration files. */
+export function findOxlintConfig(rootDir: string, probe: WorkspaceProbe): string | undefined {
+   return probe.listFiles(rootDir).find(name => /^(oxlint\.config\.[cm]?[jt]s|\.oxlintrc\.jsonc?)$/.test(name));
+}
+
 /** POSIX-style relative path, which is what both `extends` and `--prefix` want on every platform. */
 function posixRelative(from: string, to: string): string {
    return path.relative(from, to).split(path.sep).join('/');
@@ -436,7 +445,8 @@ export function detectWorkspace(targetDir: string, probe: WorkspaceProbe): Works
       scope: inferPackageScope(rootDir, workspaces, probe),
       baseTsconfig: base && posixRelative(absoluteTarget, path.join(rootDir, base.file)),
       baseCompilerOptions: base?.compilerOptions,
-      printWidth: findPrettierPrintWidth(rootDir, probe),
-      eslintConfig: findEslintConfig(rootDir, probe)
+      printWidth: findFormatterPrintWidth(rootDir, probe),
+      eslintConfig: findEslintConfig(rootDir, probe),
+      oxlintConfig: findOxlintConfig(rootDir, probe)
    };
 }

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';
 
 /**
@@ -128,10 +128,12 @@ export interface InitWorkspacePlacement {
    readonly baseTsconfig?: string;
    /** That tsconfig's `compilerOptions`, so the emitted one can omit what it would inherit unchanged. */
    readonly baseCompilerOptions?: Readonly<Record<string, JsonValue>>;
-   /** The workspace's prettier `printWidth`, so emitted sources wrap where the repo wraps. */
+   /** The workspace's formatter `printWidth`, so emitted sources wrap where the repo wraps. */
    readonly printWidth?: number;
    /** Filename of the workspace's eslint config; its presence is what makes the scaffold emit a `lint` script. */
    readonly eslintConfig?: string;
+   /** Filename of the workspace Oxlint config, when present. */
+   readonly oxlintConfig?: string;
 }
 
 /**
@@ -466,7 +468,8 @@ export function resolveInitPackaging(targetDir: string, options: InitPackagingOp
          baseTsconfig: detection.baseTsconfig,
          baseCompilerOptions: detection.baseCompilerOptions,
          printWidth: detection.printWidth,
-         eslintConfig: detection.eslintConfig
+         eslintConfig: detection.eslintConfig,
+         oxlintConfig: detection.oxlintConfig
       }
    };
 }
@@ -515,10 +518,12 @@ export function runInit(options: InitCommandOptions): void {
       }
       write("  .gitignore holds `syntaxes/` only — the workspace root's covers the rest.\n");
       if (detection.printWidth !== undefined) {
-         write(`  Sources wrapped at ${detection.printWidth} columns, from ${detection.rootDir}'s prettier config.\n`);
+         write(`  Sources wrapped at ${detection.printWidth} columns, from ${detection.rootDir}'s formatter config.\n`);
       }
-      if (detection.eslintConfig !== undefined) {
-         write(`  A lint script was added — ${detection.eslintConfig} says this repo lints. Adjust it if your invocation differs.\n`);
+      if (detection.oxlintConfig !== undefined || detection.eslintConfig !== undefined) {
+         write(
+            `  A lint script was added — ${detection.oxlintConfig ?? detection.eslintConfig} says this repo lints. Adjust it if your invocation differs.\n`
+         );
       }
       // Printed rather than applied: `init` writes inside the target directory
       // and nowhere else, so a scaffold can never surprise-edit a manifest that
@@ -536,13 +541,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/lint-grammar.ts

@@ -53,5 +53,5 @@ export function buildLintGrammarDriverArgs(options: LintGrammarCommandOptions):
  * `createServices` module, keeping the binary language-agnostic.
  */
 export function runLintGrammar(options: LintGrammarCommandOptions): Promise<void> {
-   return runDriverChild(['--max-old-space-size=8192', DRIVER, ...buildLintGrammarDriverArgs(options)], options);
+   return runDriverChild([DRIVER, ...buildLintGrammarDriverArgs(options)], options);
 }

package/src/commands/measure-memory-driver.ts

@@ -9,8 +9,9 @@
 
 /*
  * Spawned child of the `measure-memory` subcommand. Launched by the parent with
- * `node --expose-gc --max-old-space-size=8192 <this> --services <module> <workspace> ...`
- * so the underlying harness gets post-GC readings. It dynamic-imports the head's
+ * `node [heap ceiling] --expose-gc <this> --services <module> <workspace> ...`
+ * so the underlying harness gets post-GC readings. The ceiling is whatever
+ * `driverHeapArgs` decides, which is nothing at all inside a container. It dynamic-imports the head's
  * services module and runs the framework's `measureModelMemory`, streaming the
  * baseline / after-build / churn lines to stdout. Never imported — only spawned.
  */

package/src/commands/measure-memory.ts

@@ -139,5 +139,5 @@ export function buildDriverArgs(options: MeasureMemoryCommandOptions): string[]
  * module and reports the baseline / after-build / churn lines on stdout.
  */
 export function runMeasureMemory(options: MeasureMemoryCommandOptions): Promise<void> {
-   return runDriverChild(['--expose-gc', '--max-old-space-size=8192', DRIVER, ...buildDriverArgs(options)], options);
+   return runDriverChild(['--expose-gc', DRIVER, ...buildDriverArgs(options)], options);
 }

package/src/commands/model-docs.ts

@@ -44,5 +44,5 @@ export function buildModelDocsDriverArgs(options: ModelDocsCommandOptions): stri
  * module, keeping the binary language-agnostic.
  */
 export function runModelDocs(options: ModelDocsCommandOptions): Promise<void> {
-   return runDriverChild(['--max-old-space-size=8192', DRIVER, ...buildModelDocsDriverArgs(options)], options);
+   return runDriverChild([DRIVER, ...buildModelDocsDriverArgs(options)], options);
 }

package/src/commands/reflect.ts

@@ -47,5 +47,5 @@ export function buildReflectDriverArgs(options: ReflectCommandOptions): string[]
  * the binary language-agnostic.
  */
 export function runReflect(options: ReflectCommandOptions): Promise<void> {
-   return runDriverChild(['--max-old-space-size=8192', DRIVER, ...buildReflectDriverArgs(options)], options);
+   return runDriverChild([DRIVER, ...buildReflectDriverArgs(options)], options);
 }

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 });
-      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 });
-         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

package/src/commands/validate.ts

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

package/src/commands/watch.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,24 @@ export async function runWatch(options: WatchCommandOptions): Promise<void> {
       onDocumentSaved(): void {
          // Persistence is out of band for the per-URI update view.
       },
+      onDocumentDirtyChanged(): void {
+         // Out of band for the per-URI update view, as persistence is.
+      },
+      onDocumentDeleted(event: TransferDocumentDeletedEvent): void {
+         // In band, unlike the two neighbours: this is the end of the stream
+         // the view exists to show, and a consumer that never hears it waits
+         // forever for an update that cannot come. The line carries no
+         // `document`, so a reader must switch on shape rather than assume one.
+         if (event.uri !== options.uri) {
+            return;
+         }
+         write(`${JSON.stringify(event)}\n`);
+      },
+      onDocumentsBuilt(): void {
+         // Out of band for a per-URI view by construction: this notification
+         // carries only documents nobody watches, and this command watches the
+         // one URI it was given.
+      },
       onProjectsChanged(): void {
          // Project lifecycle is out of band for the per-URI update view.
       }