@hydranium/cli 1.0.0-next.17 → 1.0.0-next.173

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.
       }

package/src/driver-heap.ts

@@ -0,0 +1,65 @@
+/********************************************************************************
+ * 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 { heapCeilingArgs } from '@hydranium/core/node';
+
+/**
+ * Heap ceiling in MiB for a driver child on a machine with no cgroup limit.
+ *
+ * The subcommands that spawn one build a whole workspace in that child —
+ * `measure-memory` deliberately so, `analyze-heap` loads an entire heap
+ * snapshot — so the default Node would pick from physical RAM is too low for
+ * the workspaces these are pointed at.
+ */
+export const DRIVER_HEAP_MB = 8192;
+
+/** Environment variable an operator raises or lowers {@link driverHeapArgs} with. */
+export const DRIVER_HEAP_ENV = 'HYDRANIUM_CLI_MAX_OLD_SPACE_MB';
+
+/**
+ * Smallest ceiling {@link DRIVER_HEAP_ENV} may state. A driver child builds a
+ * whole workspace, so a value this far below the default is a unit mistake
+ * rather than a deliberate squeeze.
+ */
+export const MIN_DRIVER_HEAP_MB = 256;
+
+/**
+ * A cgroup reading, so a caller — in practice a test — can decide the ceiling
+ * instead of inheriting the machine's. Omitted fields fall back to this
+ * process's own reading.
+ */
+export interface HeapReading {
+   readonly constrained?: number;
+   readonly total?: number;
+}
+
+/**
+ * The `execArgv` prefix every driver child is spawned under.
+ *
+ * Inside a container this is EMPTY on purpose. {@link DRIVER_HEAP_MB} is sized
+ * for a workstation, and handing it to a process under a smaller cgroup limit
+ * is worse than handing it nothing: V8 has no reason to collect hard below a
+ * ceiling it will never reach, so the kernel OOM-kills the container first and
+ * the failure arrives as a signal against the whole cgroup rather than as a
+ * heap error the parent can attribute. Left to itself, Node sizes the heap from
+ * the limit instead.
+ *
+ * That trades away the ability to use a LARGE container's memory, since Node's
+ * derived default is a fraction of the limit — which is what {@link DRIVER_HEAP_ENV}
+ * is for. An operator who states a number has decided, so it wins in a
+ * container too.
+ */
+export function driverHeapArgs(reading: HeapReading = {}): string[] {
+   return heapCeilingArgs({
+      desktopDefaultMb: DRIVER_HEAP_MB,
+      envValue: process.env[DRIVER_HEAP_ENV],
+      minMb: MIN_DRIVER_HEAP_MB,
+      ...reading
+   });
+}

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';