@hydranium/data-server 1.0.0-next.42 → 1.0.0-next.421

package/src/default-diagnostics.ts

@@ -8,33 +8,14 @@
  ********************************************************************************/
 
 import type { DataServerDiagnosticsProvider } from './diagnostics-provider.js';
-import { nodeDataServerDiagnostics } from './node/node-diagnostics-provider.js';
 
-/**
- * Platform default for `DataServerOptions.diagnostics` — the Node one.
- *
- * # This file is swapped by the bundler, and that is the whole mechanism
- *
- * `package.json`'s `browser` field maps this module to
- * `default-diagnostics.browser.js`, so a `platform: 'browser'` bundler never
- * resolves it and never follows its `@hydranium/core/node` import. Node keeps
- * it, because Node ignores the `browser` field.
- *
- * The alternative — reaching for the Node implementation directly from the head
- * — is what made this package unbundleable for a browser: a static
- * `@hydranium/core/node` import on the portable entry pulls `node:fs`,
- * `node:v8` and `node:perf_hooks` into any browser build, over methods a
- * browser cannot call.
- *
- * **`check:neutral` proves the swap works**, since it bundles this package's `.`
- * entry for the browser and would fail on those imports if the mapping ever
- * stopped applying. That is the same property the gate relies on for
- * `@eclipse-glsp/server`, whose own `browser` field selects its node-free
- * build.
- *
- * A host that wants to be explicit — or to supply its own — passes
- * `diagnostics` and this default is not consulted.
- */
+/** Reject privileged requests until the host explicitly supplies a diagnostics provider. */
 export function defaultDataServerDiagnostics(): DataServerDiagnosticsProvider {
-   return nodeDataServerDiagnostics();
+   const unavailable = (): Promise<never> => Promise.reject(new Error('Server diagnostics are disabled by the host.'));
+   return {
+      dumpServerState: unavailable,
+      writeHeapSnapshot: unavailable,
+      dumpPodMemory: unavailable,
+      startProfiling: unavailable
+   };
 }

package/src/diagnostics-provider.ts

@@ -27,7 +27,7 @@ import type { DumpServerStateArgs, StartProfilingArgs, StopProfilingArgs, WriteS
  *
  * Node hosts get the real implementation from `@hydranium/data-server/node`.
  * Hosts that supply nothing keep the whole rest of the protocol and reject only
- * these four methods, with a message naming the import that would satisfy them.
+ * process-inspection requests until the host explicitly authorizes them.
  */
 export interface DataServerDiagnosticsProvider {
    /**

package/src/messages/index.ts

@@ -16,4 +16,11 @@
  * code is the contract, and renaming one is a breaking change.
  */
 
-export { NO_ACTIVE_PROFILE, NO_ACTIVE_PROFILE_CODE, noActiveProfileError } from '../data-server.js';
+export {
+   NO_ACTIVE_PROFILE,
+   NO_ACTIVE_PROFILE_CODE,
+   noActiveProfileError,
+   REFERENCE_SETTLE_TIMEOUT,
+   REFERENCE_SETTLE_TIMEOUT_CODE,
+   referenceSettleTimeoutError
+} from '../data-server.js';

package/src/node/node-diagnostics-provider.ts

@@ -7,15 +7,13 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+import { mkdirSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
 import type { ServerSharedServices } from '@hydranium/core';
-import {
-   formatPodMemory,
-   formatProfileReport,
-   formatServerState,
-   ProfileCapture,
-   recordServerSummaryEntry,
-   writeHeapSnapshotToDir
-} from '@hydranium/core/node';
+import { formatProfileReport, formatServerState, ProfileCapture, recordServerSummaryEntry } from '@hydranium/core/node';
+import { formatPodMemory, writeHeapSnapshotToDir } from '@hydranium/protocol/node';
 import type { DumpServerStateArgs, StartProfilingArgs, StopProfilingArgs, WriteServerHeapSnapshotArgs } from '@hydranium/protocol';
 import type { DataServerDiagnosticsProvider, DataServerProfileCapture } from '../diagnostics-provider.js';
 
@@ -33,29 +31,45 @@ import type { DataServerDiagnosticsProvider, DataServerProfileCapture } from '..
  * AST/CST — the process that OOMs.
  */
 class NodeProfileCapture implements DataServerProfileCapture {
-   constructor(protected readonly capture: ProfileCapture) {}
+   constructor(
+      protected readonly capture: ProfileCapture,
+      protected readonly directory: string
+   ) {}
 
    async stop(args: StopProfilingArgs): Promise<string> {
-      const report = await this.capture.stop(args.directory, args.label ?? '');
-      // When a directory was given (the profile files land there), also fold this
-      // window's report into `<dir>/server-summary.json` so an interactive/e2e
-      // bundle carries the same per-window summary the headless `ProfilingRun`
-      // writes.
-      if (args.directory) {
-         recordServerSummaryEntry(args.directory, args.label ?? '', report);
-      }
+      const report = await this.capture.stop(this.directory, args.label ?? '');
+      recordServerSummaryEntry(this.directory, args.label ?? '', report);
       return formatProfileReport(report, args.label ? `Profile report (${args.label})` : undefined);
    }
 }
 
+/** Server-controlled destination for diagnostic artifacts. */
+export interface NodeDataServerDiagnosticsOptions {
+   /** A directory owned by the host. Omitted creates a private temporary directory on first use. Client directory arguments are ignored. */
+   readonly directory?: string;
+}
+
 class NodeDataServerDiagnostics implements DataServerDiagnosticsProvider {
+   protected outputDirectory: string | undefined;
+
+   constructor(protected readonly options: NodeDataServerDiagnosticsOptions) {}
+
+   protected directory(): string {
+      const directory = this.outputDirectory ?? this.options.directory ?? mkdtempSync(join(tmpdir(), 'hydranium-diagnostics-'));
+      // Cleanup can remove a previous destination. Prepare it on every use so
+      // artifact writers cannot fall back to the shared temporary directory.
+      mkdirSync(directory, { recursive: true, mode: 0o700 });
+      this.outputDirectory = directory;
+      return directory;
+   }
+
    async dumpServerState(services: ServerSharedServices, args: DumpServerStateArgs): Promise<string> {
       const openDocuments = services.workspace.TextDocuments.openDocuments();
-      return formatServerState(services.workspace.LangiumDocuments, args.label, { openDocuments });
+      return formatServerState(services.workspace, args.label, { openDocuments });
    }
 
    async writeHeapSnapshot(args: WriteServerHeapSnapshotArgs): Promise<string> {
-      return writeHeapSnapshotToDir(args.directory, args.label ?? '');
+      return writeHeapSnapshotToDir(this.directory(), args.label ?? '');
    }
 
    async dumpPodMemory(): Promise<string> {
@@ -66,17 +80,49 @@ class NodeDataServerDiagnostics implements DataServerDiagnosticsProvider {
       // `ProfileCapture` is singleton-guarded — one inspector session per
       // process — so a second concurrent start rejects here rather than in the
       // caller, which is where the constraint actually lives.
-      return new NodeProfileCapture(await ProfileCapture.start(args));
+      const directory = this.directory();
+      return new NodeProfileCapture(await ProfileCapture.start(args), directory);
    }
 }
 
 /**
- * The diagnostics provider a Node-hosted `DataServer` should be constructed
- * with: `new DataServer(connection, shared, { diagnostics: nodeDataServerDiagnostics() })`.
- *
- * Omitting it is not an error — the head runs without it and rejects only the
- * four diagnostics methods — so a host that never calls them can leave it out.
+ * Enable process inspection on a connection the host has authorized for it.
+ * Artifact destinations come from host options. Wire directory arguments cannot
+ * grant filesystem access. The host must keep the output directory private,
+ * since snapshots can contain secrets from every client in this process.
  */
-export function nodeDataServerDiagnostics(): DataServerDiagnosticsProvider {
-   return new NodeDataServerDiagnostics();
+export function nodeDataServerDiagnostics(options: NodeDataServerDiagnosticsOptions = {}): DataServerDiagnosticsProvider {
+   return new NodeDataServerDiagnostics(options);
+}
+
+/**
+ * The provider `--enable-diagnostics` asks for, writing to
+ * `--diagnostics-directory <path>` when given, or `undefined` when the flag is
+ * absent. A directory alone enables nothing. Other arguments are ignored, so
+ * an entry passes its whole command line. An entry that parses `args` strictly
+ * itself must declare both options too.
+ */
+export function diagnosticsFromArgs(args: readonly string[] = process.argv.slice(2)): DataServerDiagnosticsProvider | undefined {
+   const { values, tokens } = parseArgs({
+      args: [...args],
+      options: { 'enable-diagnostics': { type: 'boolean' }, 'diagnostics-directory': { type: 'string' } },
+      strict: false,
+      allowPositionals: true,
+      tokens: true
+   });
+   // Non-strict parsing types every value loosely and takes a following flag
+   // as a value, so the shapes a strict parse rejects are checked here.
+   const enabled = values['enable-diagnostics'];
+   const directory = values['diagnostics-directory'];
+   if (enabled !== undefined && typeof enabled !== 'boolean') {
+      throw new Error('--enable-diagnostics takes no value');
+   }
+   const flagAsDirectory = tokens.some(
+      token => token.kind === 'option' && token.name === 'diagnostics-directory' && !token.inlineValue && token.value?.startsWith('-')
+   );
+   if (flagAsDirectory || directory === '' || (directory !== undefined && typeof directory !== 'string')) {
+      throw new Error('--diagnostics-directory requires a path');
+   }
+   // Resolved once, so a later working-directory change cannot move the output.
+   return enabled ? nodeDataServerDiagnostics({ directory: directory === undefined ? undefined : resolve(directory) }) : undefined;
 }

package/src/testing/data-server-harness.ts

@@ -15,11 +15,12 @@ import {
    type DataServerProtocol,
    type ProjectsChangedEvent,
    type TransferDocumentDeletedEvent,
+   type TransferDocumentDirtyChangedEvent,
    type TransferDocumentSavedEvent,
    type TransferDocumentsBuiltEvent,
    type TransferDocumentUpdatedEvent
 } from '@hydranium/protocol/data';
-import { type Harness, makeCapturingDataClient } from '@hydranium/protocol/testing';
+import { type AdditionalClientMethod, type Harness, makeCapturingDataClient } from '@hydranium/protocol/testing';
 import { makeDuplexConnectionPair, type DuplexConnectionPair } from '@hydranium/protocol/testing/node';
 import type { MessageConnection } from 'vscode-jsonrpc/node';
 
@@ -31,16 +32,17 @@ import type { MessageConnection } from 'vscode-jsonrpc/node';
  * (the "server side" of the duplex pair). The factory is invoked once,
  * synchronously, after the pair is wired.
  *
- * `client` lets tests override individual handlers on the captured
- * {@link DataClientProtocol}. Unspecified handlers default to pushing
- * incoming events into the {@link DataServerHarness} bundle's `events` /
- * `saves` / `projectsChanges` arrays — the typical assertion target.
+ * `client` lets tests override individual handlers on the captured client.
+ * Unspecified handlers default to pushing incoming events into the
+ * {@link DataServerHarness} bundle's `events` / `saves` / `projectsChanges`
+ * arrays — the typical assertion target.
  */
 export interface MakeDataServerHarnessOptions<
    TServer,
    TTransfer extends TransferElement,
    TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
-   TProject extends Project = Project
+   TProject extends Project = Project,
+   TClient extends DataClientProtocol<TTransfer, TDiagnostic, TProject> = DataClientProtocol<TTransfer, TDiagnostic, TProject>
 > {
    /**
     * Construct the `DataServer` (or subclass) under test against
@@ -49,12 +51,19 @@ export interface MakeDataServerHarnessOptions<
     */
    server: (channel: MessageConnection) => TServer;
    /**
-    * Override per-method handlers on the captured {@link DataClientProtocol}.
-    * Each overridden handler REPLACES the default (which pushes into the
-    * bundle's capture arrays); test code wanting to BOTH capture AND
-    * react should push to the array manually inside the override.
+    * Override per-method handlers on the captured client. An additional
+    * method's override needs the method in `additionalClientMethods`, or the
+    * harness throws. Each overridden handler REPLACES the default (which
+    * pushes into the bundle's capture arrays); test code wanting to BOTH
+    * capture AND react should push to the array manually inside the override.
     */
-   client?: Partial<DataClientProtocol<TTransfer, TDiagnostic, TProject>>;
+   client?: Partial<TClient>;
+   /**
+    * Notification methods `TClient` adds to {@link DataClientProtocol}. Each is
+    * bound and captured into `additionalNotifications`; one left out reaches no
+    * handler.
+    */
+   additionalClientMethods?: readonly AdditionalClientMethod<TClient>[];
    /**
     * Wire namespace the proxy addresses the server under. Defaults to
     * {@link DATA_SERVER_WIRE_PREFIX}. Override when the `DataServer`
@@ -80,7 +89,8 @@ export interface DataServerHarness<
    TServer,
    TTransfer extends TransferElement,
    TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
-   TProject extends Project = Project
+   TProject extends Project = Project,
+   TClient extends DataClientProtocol<TTransfer, TDiagnostic, TProject> = DataClientProtocol<TTransfer, TDiagnostic, TProject>
 > extends Harness {
    readonly server: TServer;
    readonly proxy: DataServerProtocol<TTransfer, TDiagnostic, TProject>;
@@ -89,12 +99,18 @@ export interface DataServerHarness<
    readonly events: ReadonlyArray<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>>;
    /** Captured `onDocumentSaved` events. */
    readonly saves: ReadonlyArray<TransferDocumentSavedEvent<TTransfer, TDiagnostic>>;
+   /** Captured `onDocumentDirtyChanged` events. */
+   readonly dirtyChanges: ReadonlyArray<TransferDocumentDirtyChangedEvent>;
    /** Captured `onDocumentDeleted` events. */
    readonly deletions: ReadonlyArray<TransferDocumentDeletedEvent>;
    /** Captured `onDocumentsBuilt` events, one per build that had unwatched documents. */
    readonly builds: ReadonlyArray<TransferDocumentsBuiltEvent>;
    /** Captured `onProjectsChanged` events. */
    readonly projectsChanges: ReadonlyArray<ProjectsChangedEvent<TProject>>;
+   /** Captured events of each `additionalClientMethods` entry, keyed by method. */
+   readonly additionalNotifications: {
+      readonly [K in AdditionalClientMethod<TClient>]: TClient[K] extends (event: infer TEvent) => void ? ReadonlyArray<TEvent> : never;
+   };
    /** Dispose the underlying duplex pair. Idempotent. */
    dispose(): void;
 }
@@ -113,12 +129,14 @@ export function makeDataServerHarness<
    TServer,
    TTransfer extends TransferElement,
    TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
-   TProject extends Project = Project
+   TProject extends Project = Project,
+   TClient extends DataClientProtocol<TTransfer, TDiagnostic, TProject> = DataClientProtocol<TTransfer, TDiagnostic, TProject>
 >(
-   options: MakeDataServerHarnessOptions<TServer, TTransfer, TDiagnostic, TProject>
-): DataServerHarness<TServer, TTransfer, TDiagnostic, TProject> {
+   options: MakeDataServerHarnessOptions<TServer, TTransfer, TDiagnostic, TProject, TClient>
+): DataServerHarness<TServer, TTransfer, TDiagnostic, TProject, TClient> {
    const pair = makeDuplexConnectionPair();
    const server = options.server(pair.left);
+   const additionalClientMethods = options.additionalClientMethods ?? [];
 
    // The capture half is the shared client double, not a local copy: the same
    // recording semantics (every channel, an override replacing rather than
@@ -129,19 +147,18 @@ export function makeDataServerHarness<
       client: localClient,
       updates: events,
       saves,
+      dirtyChanges,
       deletions,
       builds,
-      projectsChanges
-   } = makeCapturingDataClient<TTransfer, TDiagnostic, TProject>(options.client);
+      projectsChanges,
+      additionalNotifications
+   } = makeCapturingDataClient<TTransfer, TDiagnostic, TProject, TClient>(options.client, additionalClientMethods);
 
-   const proxy = createRpcProxy<DataServerProtocol<TTransfer, TDiagnostic, TProject>, DataClientProtocol<TTransfer, TDiagnostic, TProject>>(
-      pair.right,
-      {
-         methodNamespace: options.methodNamespace ?? DATA_SERVER_WIRE_PREFIX,
-         localTarget: localClient,
-         localMethods: DATA_CLIENT_PROTOCOL_METHODS
-      }
-   );
+   const proxy = createRpcProxy<DataServerProtocol<TTransfer, TDiagnostic, TProject>, TClient>(pair.right, {
+      methodNamespace: options.methodNamespace ?? DATA_SERVER_WIRE_PREFIX,
+      localTarget: localClient,
+      localMethods: [...DATA_CLIENT_PROTOCOL_METHODS, ...additionalClientMethods]
+   });
 
    return {
       server,
@@ -149,9 +166,11 @@ export function makeDataServerHarness<
       pair,
       events,
       saves,
+      dirtyChanges,
       deletions,
       builds,
       projectsChanges,
+      additionalNotifications,
       dispose: () => pair.dispose()
    };
 }

package/src/testing/index.ts

@@ -12,8 +12,11 @@
 // real wire. The duplex `MessageConnection` pair lives in
 // `@hydranium/protocol/testing`, which owns the transport; only its TYPE is
 // re-exported here, because `DataServerHarness.pair` names it in a public
-// signature. A test that wires its own server rather than using the harness
-// calls `makeDuplexConnectionPair` from `@hydranium/protocol/testing` directly.
+// signature; `AdditionalClientMethod` is re-exported for the same reason, as
+// the harness options name it. A test that wires its own server rather than
+// using the harness calls `makeDuplexConnectionPair` from
+// `@hydranium/protocol/testing` directly.
 
+export type { AdditionalClientMethod } from '@hydranium/protocol/testing';
 export type { DuplexConnectionPair } from '@hydranium/protocol/testing/node';
 export * from './data-server-harness.js';

package/lib/default-diagnostics.browser.d.ts

@@ -1,18 +0,0 @@
-/********************************************************************************
- * 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 type { DataServerDiagnosticsProvider } from './diagnostics-provider.js';
-/**
- * Platform default for a browser host, selected by `package.json`'s `browser`
- * field in place of `default-diagnostics.js`.
- *
- * Free of Node imports by construction — that is its entire reason for
- * existing, and why the head's portable entry can be bundled at all.
- */
-export declare function defaultDataServerDiagnostics(): DataServerDiagnosticsProvider;
-//# sourceMappingURL=default-diagnostics.browser.d.ts.map

package/lib/default-diagnostics.browser.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"default-diagnostics.browser.d.ts","sourceRoot":"","sources":["../src/default-diagnostics.browser.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,6BAA6B,EAA4B,MAAM,2BAA2B,CAAC;AAiBzG;;;;;;GAMG;AACH,wBAAgB,4BAA4B,IAAI,6BAA6B,CAO5E"}

package/lib/default-diagnostics.browser.js

@@ -1,36 +0,0 @@
-/********************************************************************************
- * 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
- ********************************************************************************/
-/**
- * Message every method of the browser default rejects with.
- *
- * It **throws rather than no-ops** deliberately. A no-op would hand back an
- * empty snapshot, which reads as "the server is fine" — the same shape as a
- * real answer, and the failure mode this whole seam exists to avoid. Saying
- * plainly that the capability is absent is more useful than a plausible lie.
- */
-function unavailable(method) {
-    return new Error(`DataServer.${method} is not available in this host: a browser has no process to inspect. ` +
-        'Heap snapshots, profiling, pod memory and server state are Node-only capabilities.');
-}
-/**
- * Platform default for a browser host, selected by `package.json`'s `browser`
- * field in place of `default-diagnostics.js`.
- *
- * Free of Node imports by construction — that is its entire reason for
- * existing, and why the head's portable entry can be bundled at all.
- */
-export function defaultDataServerDiagnostics() {
-    return {
-        dumpServerState: () => Promise.reject(unavailable('dumpServerState')),
-        writeHeapSnapshot: () => Promise.reject(unavailable('writeHeapSnapshot')),
-        dumpPodMemory: () => Promise.reject(unavailable('dumpPodMemory')),
-        startProfiling: () => Promise.reject(unavailable('startProfiling'))
-    };
-}
-//# sourceMappingURL=default-diagnostics.browser.js.map

package/lib/default-diagnostics.browser.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"default-diagnostics.browser.js","sourceRoot":"","sources":["../src/default-diagnostics.browser.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,MAAc;IAChC,OAAO,IAAI,KAAK,CACb,cAAc,MAAM,uEAAuE;QACxF,oFAAoF,CACzF,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,4BAA4B;IACzC,OAAO;QACJ,eAAe,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC;QACrE,iBAAiB,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,mBAAmB,CAAC,CAAC;QACzE,aAAa,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;QACjE,cAAc,EAAE,GAAsC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,gBAAgB,CAAC,CAAC;KACxG,CAAC;AACL,CAAC"}

package/src/default-diagnostics.browser.ts

@@ -1,41 +0,0 @@
-/********************************************************************************
- * 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 type { DataServerDiagnosticsProvider, DataServerProfileCapture } from './diagnostics-provider.js';
-
-/**
- * Message every method of the browser default rejects with.
- *
- * It **throws rather than no-ops** deliberately. A no-op would hand back an
- * empty snapshot, which reads as "the server is fine" — the same shape as a
- * real answer, and the failure mode this whole seam exists to avoid. Saying
- * plainly that the capability is absent is more useful than a plausible lie.
- */
-function unavailable(method: string): Error {
-   return new Error(
-      `DataServer.${method} is not available in this host: a browser has no process to inspect. ` +
-         'Heap snapshots, profiling, pod memory and server state are Node-only capabilities.'
-   );
-}
-
-/**
- * Platform default for a browser host, selected by `package.json`'s `browser`
- * field in place of `default-diagnostics.js`.
- *
- * Free of Node imports by construction — that is its entire reason for
- * existing, and why the head's portable entry can be bundled at all.
- */
-export function defaultDataServerDiagnostics(): DataServerDiagnosticsProvider {
-   return {
-      dumpServerState: () => Promise.reject(unavailable('dumpServerState')),
-      writeHeapSnapshot: () => Promise.reject(unavailable('writeHeapSnapshot')),
-      dumpPodMemory: () => Promise.reject(unavailable('dumpPodMemory')),
-      startProfiling: (): Promise<DataServerProfileCapture> => Promise.reject(unavailable('startProfiling'))
-   };
-}