@hydranium/cli 1.0.0-next.10

package/src/commands/watch-args.ts

@@ -0,0 +1,74 @@
+/********************************************************************************
+ * 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 {
+   assertRequired,
+   exitWithUsage,
+   helpRequested,
+   parseFlagOptions,
+   parseServerSpawnOptions,
+   printHelp,
+   SERVER_SPAWN_VALUE_FLAGS,
+   type UsageError
+} from './harness-args.js';
+import { runWatch, wireSigintAbort, type WatchCommandOptions } from './watch.js';
+
+const OWN_FLAGS = ['--uri', '--client-id'] as const;
+
+/**
+ * Every flag `watch` accepts, derived from its own list plus the shared spawn
+ * flags, so the list cannot claim a flag the parser would reject.
+ */
+export const WATCH_FLAGS: readonly string[] = [...SERVER_SPAWN_VALUE_FLAGS, ...OWN_FLAGS];
+
+/**
+ * The subset that takes a value, so `--help` in a value position reads as data.
+ * Every flag in this family takes one, so the two lists coincide.
+ */
+export const WATCH_VALUE_FLAGS: readonly string[] = WATCH_FLAGS;
+
+/** The `--help` text, as data, held to {@link WATCH_FLAGS} by a test. */
+export const WATCH_HELP: readonly string[] = [
+   'Usage: hydranium-cli watch --server "<cmd>..." --uri <uri> [--client-id <id>] [--cwd <dir>] [--log-level <level>]',
+   '',
+   'Subscribe to document updates at `<uri>` and print events as newline-delimited',
+   'JSON. Long-running — exits cleanly on SIGINT (Ctrl-C).',
+   '',
+   'Options:',
+   '  --server "<cmd>"      Command-line for the data-server subprocess (required).',
+   '  --uri <uri>           Document URI (required).',
+   '  --client-id <id>      Subscriber identity. Default: hydranium-cli.',
+   '  --cwd <dir>           Working directory for the spawned child. Default: cwd.',
+   '  --log-level <lvl>     Log threshold for the spawned server (off|error|warn|info|debug|trace).'
+];
+
+/** Parse the argv; the abort signal is the entry point's to supply, not the command line's. */
+export function parseWatchArgs(args: string[], onError: UsageError = exitWithUsage): WatchCommandOptions {
+   const { serverCommand, serverArgs, cwd, logLevel, extra } = parseServerSpawnOptions(args, 'watch', onError);
+   const { uri, clientId } = parseFlagOptions(extra, 'watch', OWN_FLAGS, onError);
+   return {
+      serverCommand,
+      serverArgs,
+      cwd,
+      logLevel,
+      uri: assertRequired(uri, '--uri', 'watch', onError),
+      clientId
+   };
+}
+
+export function runWatchCommand(args: string[]): Promise<void> {
+   if (helpRequested(args, WATCH_VALUE_FLAGS)) {
+      printHelp(WATCH_HELP);
+      return Promise.resolve();
+   }
+   const options = parseWatchArgs(args);
+   const controller = new AbortController();
+   const unwire = wireSigintAbort(controller);
+   return runWatch({ ...options, signal: controller.signal }).finally(() => unwire());
+}

package/src/commands/watch.ts

@@ -0,0 +1,185 @@
+/********************************************************************************
+ * 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 { LogThreshold, TransferElement } from '@hydranium/protocol';
+import type { DataClientProtocol, DataServerProtocol, TransferDocumentUpdatedEvent } from '@hydranium/protocol/data';
+import { logLevelEnv } from '../log-level.js';
+import { spawnDataServer } from '../spawn-data-server.js';
+
+/**
+ * Options for the {@link runWatch} subcommand. Subscribes to document
+ * updates at `uri` and writes each event as one JSON line. Long-running
+ * — exits on SIGINT (Ctrl-C) or when `signal` aborts. Each event is
+ * line-flushable for `jq` / `tee` pipelines.
+ *
+ * `clientId` defaults to `'hydranium-cli'`. `signal` is the test seam
+ * — production CLI wires SIGINT directly. `__handleForTest` bypasses
+ * the spawn step for unit tests.
+ */
+export interface WatchCommandOptions {
+   readonly serverCommand: string;
+   readonly serverArgs?: readonly string[];
+   readonly cwd?: string;
+   /** Log threshold for the spawned server, set on its `HYDRANIUM_LOG_LEVEL` env. */
+   readonly logLevel?: LogThreshold;
+   readonly uri: string;
+   readonly clientId?: string;
+   readonly write?: (line: string) => void;
+   /**
+    * AbortSignal that cancels the subscription loop. Production wires
+    * SIGINT via {@link wireSigintAbort}; tests pass a controlled signal
+    * to assert deterministic teardown.
+    */
+   readonly signal?: AbortSignal;
+   /**
+    * Test-only injection — supplies the typed server proxy along with a
+    * "fire event" hook that runWatch calls during construction to wire
+    * its local client. Production CLI never passes this; subcommand
+    * unit tests do.
+    */
+   readonly __handleForTest?: WatchTestHandle;
+}
+
+/**
+ * Test seam for {@link runWatch}. Wraps the bits of `DataServerHandle`
+ * the watch loop actually uses — the typed server proxy plus a
+ * `bindClient` hook the test fixture uses to capture the local
+ * `DataClientProtocol` so it can fire events at it.
+ */
+export interface WatchTestHandle {
+   readonly server: Pick<DataServerProtocol<TransferElement>, 'watchModelDocument' | 'unwatchModelDocument'>;
+   /**
+    * Called once during {@link runWatch} startup with the watch loop's
+    * local {@link DataClientProtocol}. Test fixtures stash the reference
+    * and invoke `client.onDocumentUpdated(event)` to simulate the
+    * data-server's notification.
+    */
+   bindClient(client: DataClientProtocol<TransferElement>): void;
+   /** Mirror of `DataServerHandle.shutdown` — tests can stub as a no-op. */
+   shutdown(timeoutMs?: number): Promise<void>;
+   /**
+    * Mirror of `DataServerHandle.whenTerminated`. Omit it for a fixture with no
+    * child to lose; supply it to drive the premature-death race, which is the
+    * only way a test reaches {@link runWatch}'s shutdown filtering.
+    */
+   readonly whenTerminated?: Promise<never>;
+}
+
+/**
+ * Wait for the handle's premature-death rejection, and swallow it once the watch
+ * is being torn down.
+ *
+ * `watch` ends on SIGINT, which a shell delivers to the whole process group, so
+ * the child dies of the same keystroke. Its `unwatchModelDocument` round trip can
+ * then never be answered, leaving the loop pending and the child's exit the only
+ * settled outcome — so unfiltered, every clean Ctrl-C is reported as
+ * `exited before the request completed (… signal=SIGINT)`. Resolving instead
+ * also settles the race the loop can no longer settle.
+ *
+ * The check waits a turn of the event loop rather than reading `aborted` in the
+ * rejection's own turn: the child's death and this process's own SIGINT are
+ * delivered together and their order is the kernel's to choose. A genuine
+ * mid-watch crash pays that one turn before it is reported.
+ */
+async function resolveOnceShuttingDown(whenTerminated: Promise<never> | undefined, signal: AbortSignal | undefined): Promise<void> {
+   if (!whenTerminated) {
+      return new Promise<void>(() => undefined);
+   }
+   try {
+      await whenTerminated;
+   } catch (err: unknown) {
+      await new Promise<void>(resolve => setTimeout(resolve, 0));
+      if (signal?.aborted) {
+         return;
+      }
+      throw err;
+   }
+}
+
+/**
+ * Wire SIGINT to abort the given controller. Returns a function that
+ * un-wires the listener — call it once the subcommand exits so future
+ * SIGINTs don't trigger an already-aborted controller.
+ */
+export function wireSigintAbort(controller: AbortController): () => void {
+   const handler = (): void => controller.abort();
+   process.once('SIGINT', handler);
+   return () => process.removeListener('SIGINT', handler);
+}
+
+export async function runWatch(options: WatchCommandOptions): Promise<void> {
+   const write = options.write ?? ((line: string) => process.stdout.write(line));
+   const clientId = options.clientId ?? 'hydranium-cli';
+
+   // Local client: filters by URI (so multiple watchers on the same wire
+   // don't cross-pollinate) and writes each event as one JSON line.
+   // `onProjectsChanged` and `onDocumentSaved` are no-ops here — `watch`
+   // streams build-phase update events. Project lifecycle and persistence
+   // events are out of band for the CLI's per-URI update view.
+   const localClient: DataClientProtocol<TransferElement> = {
+      onDocumentUpdated(event: TransferDocumentUpdatedEvent<TransferElement>): void {
+         if (event.document.uri !== options.uri) {
+            return;
+         }
+         write(`${JSON.stringify(event)}\n`);
+      },
+      onDocumentSaved(): void {
+         // Persistence is out of band for the per-URI update view.
+      },
+      onProjectsChanged(): void {
+         // Project lifecycle is out of band for the per-URI update view.
+      }
+   };
+
+   // One body for both paths: a test handle that returned before the race would
+   // leave the premature-death branch it stands in for uncoverable.
+   const handle =
+      options.__handleForTest ??
+      spawnDataServer<TransferElement>(
+         {
+            command: options.serverCommand,
+            args: options.serverArgs,
+            cwd: options.cwd,
+            env: options.logLevel ? logLevelEnv(options.logLevel) : undefined
+         },
+         localClient
+      );
+   options.__handleForTest?.bindClient(localClient);
+   try {
+      // Race the subscription loop against the child's premature death so a mid-watch
+      // server crash exits with a clear message instead of hanging until Ctrl-C. Guard
+      // the loop's late rejection (an unwatch write to a dead stream) so it does not
+      // surface as an unhandled rejection when the death wins the race.
+      const loop = runWatchOnce(handle.server, options.uri, clientId, options.signal);
+      void loop.catch(() => undefined);
+      await Promise.race([loop, resolveOnceShuttingDown(handle.whenTerminated, options.signal)]);
+   } finally {
+      await handle.shutdown();
+   }
+}
+
+async function runWatchOnce(
+   server: Pick<DataServerProtocol<TransferElement>, 'watchModelDocument' | 'unwatchModelDocument'>,
+   uri: string,
+   clientId: string,
+   signal: AbortSignal | undefined
+): Promise<void> {
+   await server.watchModelDocument({ uri, clientId });
+   try {
+      await new Promise<void>(resolve => {
+         if (signal?.aborted) {
+            resolve();
+            return;
+         }
+         signal?.addEventListener('abort', () => resolve(), { once: true });
+      });
+   } finally {
+      await server.unwatchModelDocument({ uri, clientId });
+   }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+export * from './commands/generate-transfer-model.js';
+export * from './commands/projects.js';
+export * from './commands/query.js';
+export * from './commands/save.js';
+export * from './commands/watch.js';
+export * from './package-name.js';
+export * from './spawn-data-server.js';

package/src/log-level.ts

@@ -0,0 +1,49 @@
+/********************************************************************************
+ * 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 { DEFAULT_LOG_LEVEL_ENV, LEVEL_ORDER, parseLogLevel, type LogThreshold } from '@hydranium/protocol';
+
+/**
+ * Validate a raw `--log-level` argument into a {@link LogThreshold}. Throws on
+ * an unrecognised value so the CLI's top-level `catch` surfaces a clean error
+ * and exits non-zero (mirroring how the other option parsers fail fast). Use
+ * for the argv-supplied value; the resolved threshold is handed to
+ * {@link logLevelEnv} to target the spawned server.
+ */
+export function parseLogLevelOption(raw: string): LogThreshold {
+   const level = parseLogLevel(raw);
+   if (!level) {
+      throw new Error(`Invalid --log-level: ${raw} (expected one of: ${Object.keys(LEVEL_ORDER).join(', ')})`);
+   }
+   return level;
+}
+
+/**
+ * Build the environment override that targets *only the spawned server's* log
+ * threshold. Passed to `spawnDataServer` as `env`, it sets the same
+ * `HYDRANIUM_LOG_LEVEL` variable the server reads at startup — the CLI's own
+ * logging is unaffected, unlike an ambient `HYDRANIUM_LOG_LEVEL=…` that the
+ * child would inherit alongside the parent. The server owns *how* log level
+ * works; this only routes the CLI's request onto the channel it already reads.
+ *
+ * **The variable is read by `LspLogger`'s constructor**, which is bound on the
+ * `Logger` slot by `createLspServerSharedModule`. A server that overrides that
+ * slot with a logger of its own therefore decides for itself whether this flag
+ * means anything — which is the intended seam, not a gap. A server composing no
+ * head module at all binds `@hydranium/core`'s `NoopLogger` and stays silent
+ * regardless, so the flag is inert against it.
+ *
+ * Output lands on the spawned server's **stderr**, which
+ * `spawnDataServer` inherits to the user by default. It deliberately does
+ * not go to stdout: that is the JSON-RPC channel, so a log line there would
+ * corrupt the very request this flag was set to diagnose.
+ */
+export function logLevelEnv(level: LogThreshold): Record<string, string> {
+   return { [DEFAULT_LOG_LEVEL_ENV]: level };
+}

package/src/package-name.ts

@@ -0,0 +1,39 @@
+/********************************************************************************
+ * 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 { toPascal } from '@hydranium/protocol';
+
+/**
+ * Validates against the npm package-name grammar (scoped or unscoped,
+ * lowercase, etc.).
+ *
+ * Published on this barrel with no caller inside the framework: it is
+ * scaffolding vocabulary for a generator that composes package names of its
+ * own, which is a job an adopter does in its own repository. It lives on the
+ * CLI rather than on the wire-contract package because a package name has no
+ * wire meaning and a client bundle should not carry the pattern.
+ */
+export const NPM_PACKAGE_NAME_REGEX = /^(?:(?:@(?:[a-z0-9-*~][a-z0-9-*._~]*)?\/[a-z0-9-._~])|[a-z0-9-~])[a-z0-9-._~]*$/;
+
+/**
+ * Convert an npm package name to a Pascal-case identifier. The optional scope
+ * prefix is dropped; remaining segments separated by `-`, `.`, or `~` are
+ * Pascal-cased and concatenated.
+ *
+ * `'@my-org/foo-bar'` → `'FooBar'`
+ *
+ * The inverse direction of the `kebab` derivation the scaffolder itself runs:
+ * that one starts from a PascalCase project name and produces the package id,
+ * this one recovers an identifier from a package name that already exists.
+ * Same outside-reader constraint as {@link NPM_PACKAGE_NAME_REGEX}.
+ */
+export function packageNameToId(input: string): string {
+   const unscoped = input.split('/').at(-1)!;
+   return unscoped.split(/[~.-]/).map(toPascal).join('');
+}

package/src/spawn-data-server.ts

@@ -0,0 +1,247 @@
+/********************************************************************************
+ * 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 { createRpcProxy, type TransferDiagnostic, type TransferElement } from '@hydranium/protocol';
+import {
+   DATA_CLIENT_PROTOCOL_METHODS,
+   DATA_SERVER_WIRE_PREFIX,
+   type DataClientProtocol,
+   type DataServerProtocol
+} from '@hydranium/protocol/data';
+import { type ChildProcess, spawn } from 'node:child_process';
+import { StreamMessageReader, StreamMessageWriter, createMessageConnection, type MessageConnection } from 'vscode-jsonrpc/node';
+
+/**
+ * Options for {@link spawnDataServer}. `command` is the binary or script
+ * path; `args` are the command-line arguments passed to it. The adopter's
+ * server is expected to bootstrap a `DataServer` against the supplied
+ * MessageConnection and call `connection.listen()` so its stdin/stdout
+ * carry the JSON-RPC stream.
+ *
+ * `shutdown()` disposes the JSON-RPC connection and waits for the child
+ * to exit with a configurable timeout. Subcommands that take a SIGINT
+ * (e.g. `watch`) call shutdown on the cleanup path so the child doesn't
+ * stay orphaned.
+ */
+export interface SpawnDataServerOptions {
+   readonly command: string;
+   readonly args?: readonly string[];
+   /**
+    * Working directory for the spawned child. Default: current cwd.
+    * Useful when the child resolves model files relative to a workspace
+    * root that differs from where the CLI was invoked.
+    */
+   readonly cwd?: string;
+   /**
+    * Additional environment variables for the child. Merged on top of
+    * `process.env`. Default: no overrides.
+    */
+   readonly env?: Readonly<Record<string, string | undefined>>;
+   /**
+    * Where to pipe the child's stderr. Default: inherited from the
+    * parent (visible to the user). Set to `'ignore'` for quiet
+    * scripted use; set to `'pipe'` to capture for assertion in tests.
+    */
+   readonly stderr?: 'inherit' | 'ignore' | 'pipe';
+}
+
+/**
+ * Lifecycle handle for a spawned data-server. Owns the child process,
+ * the JSON-RPC connection, and the typed protocol proxy. Always pair
+ * {@link spawnDataServer} with {@link DataServerHandle.shutdown} (in a
+ * `try`/`finally` or equivalent) so the child doesn't outlive the CLI
+ * invocation.
+ */
+export interface DataServerHandle<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
+   /** Typed server proxy — the consumer-facing surface for protocol calls. */
+   readonly server: DataServerProtocol<TTransfer, TDiagnostic>;
+   /** Raw child process — for stderr piping in tests; do not write to stdin/stdout directly. */
+   readonly child: ChildProcess;
+   /** vscode-jsonrpc connection — for callers wanting fine-grained lifecycle control. */
+   readonly connection: MessageConnection;
+   /**
+    * Rejects when the child fails to start (e.g. `ENOENT` for a missing
+    * command) or exits before {@link DataServerHandle.shutdown} is
+    * requested — i.e. a premature death that would otherwise leave an
+    * in-flight RPC hanging forever. Never resolves. Race a protocol call
+    * against it (see {@link withDataServer}) to fail fast with a clear
+    * message instead of hanging or crashing on an unhandled `'error'`
+    * event. Always internally handled, so ignoring it never triggers an
+    * unhandled-rejection crash.
+    */
+   readonly whenTerminated: Promise<never>;
+   /**
+    * Tear down the connection + wait for the child to exit. Resolves
+    * once the child has terminated (gracefully or via SIGTERM). Safe
+    * to call multiple times.
+    */
+   shutdown(timeoutMs?: number): Promise<void>;
+}
+
+/**
+ * Spawn a data-server subprocess and wire a typed proxy over its
+ * stdio JSON-RPC. The function returns once the connection is
+ * listening; protocol calls are queued behind the underlying
+ * MessageConnection's ordering guarantees.
+ *
+ * Supplying `localClient` registers its `DataClientProtocol` methods as
+ * inbound-notification handlers on the connection — the data-server's
+ * `data-server/onDocumentUpdated` notifications dispatch to
+ * `localClient.onDocumentUpdated`. Subcommands like `watch` use this to
+ * stream events; subcommands like `projects` / `query` / `save` pass
+ * no localClient.
+ */
+export function spawnDataServer<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic>(
+   options: SpawnDataServerOptions,
+   localClient?: DataClientProtocol<TTransfer, TDiagnostic>
+): DataServerHandle<TTransfer, TDiagnostic> {
+   const child = spawn(options.command, [...(options.args ?? [])], {
+      cwd: options.cwd,
+      env: options.env ? { ...process.env, ...options.env } : process.env,
+      stdio: ['pipe', 'pipe', options.stderr ?? 'inherit']
+   });
+
+   if (!child.stdin || !child.stdout) {
+      // Mirrors the synchronous failure-to-create-pipes case Node surfaces
+      // when stdio isn't 'pipe' on either end. We always request 'pipe'
+      // for stdin/stdout, so this is defensive only.
+      //
+      // Worded for whoever passed the command, not for whoever wrote this
+      // function: the reachable way to arrive here is a `--server` value that
+      // does not start, and naming the internal spawner told that reader
+      // nothing they could act on.
+      child.kill();
+      throw new Error(
+         `Could not start the data server: the command '${options.command}' provided no stdin/stdout pipe. ` +
+            'Check that --server names a runnable command, and that its own entry path resolves from --cwd.'
+      );
+   }
+
+   // Guard stdin against writes that flush after the child has died (spawn failure
+   // or a premature exit). vscode-jsonrpc queues a message write on `setImmediate`;
+   // if the child's stdin is destroyed by the time it flushes, Node's `write` errors
+   // and vscode-jsonrpc orphans that write-queue rejection (it surfaces transport
+   // errors only via `onError`, which we consume separately) — an unhandled
+   // rejection. Reporting the destroyed write as a silent success drops the doomed
+   // message; the child's death is already reported cleanly via `whenTerminated`.
+   const stdin = child.stdin;
+   const originalWrite = stdin.write.bind(stdin) as (...writeArgs: unknown[]) => boolean;
+   stdin.write = ((...writeArgs: unknown[]): boolean => {
+      if (!stdin.destroyed) {
+         return originalWrite(...writeArgs);
+      }
+      const callback = writeArgs.find((arg): arg is (error?: Error | null) => void => typeof arg === 'function');
+      callback?.(null);
+      return true;
+   }) as typeof stdin.write;
+
+   const reader = new StreamMessageReader(child.stdout);
+   const writer = new StreamMessageWriter(child.stdin);
+   const connection = createMessageConnection(reader, writer);
+   // Consume transport error / close so a child that dies mid-stream (its stdout
+   // closing, a write landing on a torn-down stdin) is observed here rather than
+   // escaping as an unhandled error — the death is reported via `whenTerminated`.
+   connection.onError(() => undefined);
+   connection.onClose(() => undefined);
+   connection.listen();
+
+   // One typed proxy over the data-server protocol; when a `localClient` is
+   // supplied its `on*` notification handlers are bound inbound on the same
+   // connection (skipped when absent — subcommands like `projects`/`query`).
+   const server = createRpcProxy<DataServerProtocol<TTransfer, TDiagnostic>, DataClientProtocol<TTransfer, TDiagnostic>>(connection, {
+      methodNamespace: DATA_SERVER_WIRE_PREFIX,
+      localTarget: localClient,
+      localMethods: DATA_CLIENT_PROTOCOL_METHODS
+   });
+
+   // A premature child death (spawn `ENOENT`, a crash, or an exit before we asked
+   // for one) rejects `whenTerminated` so a racing RPC fails fast instead of
+   // hanging on a request that can never be answered. `terminating` gates it so an
+   // expected `shutdown()` exit does NOT reject. The `void .catch` guarantees the
+   // promise is always handled — an ignored failure can never crash the process
+   // with an unhandled 'error' event / rejection.
+   let terminating = false;
+   const whenTerminated = new Promise<never>((_, reject) => {
+      child.once('error', error => {
+         if (!terminating) {
+            reject(new Error(`data-server process failed to start (command='${options.command}'): ${error.message}`));
+         }
+      });
+      child.once('exit', (code, signal) => {
+         if (!terminating) {
+            reject(
+               new Error(
+                  `data-server process exited before the request completed ` +
+                     `(command='${options.command}', code=${code ?? 'null'}, signal=${signal ?? 'null'}).`
+               )
+            );
+         }
+      });
+   });
+   void whenTerminated.catch(() => undefined);
+
+   let shutdownPromise: Promise<void> | undefined;
+   const shutdown = (timeoutMs = 5_000): Promise<void> => {
+      if (shutdownPromise) {
+         return shutdownPromise;
+      }
+      terminating = true;
+      shutdownPromise = new Promise<void>(resolve => {
+         const finalize = (): void => {
+            connection.dispose();
+            resolve();
+         };
+         if (child.exitCode !== null || child.signalCode !== null) {
+            finalize();
+            return;
+         }
+         const onExit = (): void => {
+            clearTimeout(killTimer);
+            finalize();
+         };
+         child.once('exit', onExit);
+         // Polite exit first — most servers handle SIGTERM by closing
+         // their JSON-RPC connection and returning from `connection.listen()`.
+         child.kill('SIGTERM');
+         const killTimer = setTimeout(() => {
+            child.kill('SIGKILL');
+         }, timeoutMs);
+      });
+      return shutdownPromise;
+   };
+
+   return { server, child, connection, whenTerminated, shutdown };
+}
+
+/**
+ * Spawn a data-server, run `use` against its typed proxy, and always shut the
+ * child down afterwards. The `use` call is raced against
+ * {@link DataServerHandle.whenTerminated}, so a spawn failure or a premature child
+ * exit rejects with a clear message instead of hanging on an RPC that can never be
+ * answered. This is the one-shot counterpart the `projects` / `query` / `save`
+ * subcommands compose; `watch` races its own long-running loop against
+ * `whenTerminated` directly.
+ */
+export async function withDataServer<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic, R>(
+   options: SpawnDataServerOptions,
+   use: (server: DataServerProtocol<TTransfer, TDiagnostic>, handle: DataServerHandle<TTransfer, TDiagnostic>) => Promise<R>,
+   localClient?: DataClientProtocol<TTransfer, TDiagnostic>
+): Promise<R> {
+   const handle = spawnDataServer<TTransfer, TDiagnostic>(options, localClient);
+   const usePromise = use(handle.server, handle);
+   // Defensively handle `usePromise` so that if `whenTerminated` wins the race
+   // (the child died), the losing in-flight RPC's later rejection — e.g. a write to
+   // the now-destroyed stdin — does not surface as an unhandled rejection.
+   void usePromise.catch(() => undefined);
+   try {
+      return await Promise.race([usePromise, handle.whenTerminated]);
+   } finally {
+      await handle.shutdown();
+   }
+}