@hydranium/cli 1.0.0-next.277 → 1.0.0-next.279

package/src/commands/harness-args.ts

@@ -33,6 +33,7 @@
 
 import { describeError, type LogThreshold } from '@hydranium/protocol';
 import { statSync } from 'node:fs';
+import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { type LogOptions, parseLogLevelOption } from '../log-level.js';
@@ -472,3 +473,21 @@ export function parseServerSpawnOptions(args: string[], commandName: string, onE
    }
    return { serverCommand, serverArgs, cwd, ...logOptions(logFlags), extra };
 }
+
+/**
+ * Resolve the `--content` argument to its textual form. The `@<path>`
+ * prefix reads from a file (parses as UTF-8); anything else is taken
+ * literally. The leading `@` can be escaped as `\@` for content that
+ * legitimately starts with `@`.
+ */
+export async function resolveContent(content: string, readFile?: (path: string) => Promise<string>): Promise<string> {
+   if (content.startsWith('@')) {
+      const file = content.slice(1);
+      const reader = readFile ?? ((target: string) => fs.readFile(target, 'utf8'));
+      return reader(file);
+   }
+   if (content.startsWith('\\@')) {
+      return content.slice(1);
+   }
+   return content;
+}

package/src/commands/init-templates.ts

@@ -1130,9 +1130,9 @@ void glspServer;
       data
          ? `
 //
-// NOT the entry \`hydranium-cli query\` / \`save\` / \`projects\` / \`watch\` speak to:
-// stdio here carries LSP, and the data head is a socket whose port is published
-// over the LSP connection. Those subcommands spawn \`data-server-main.js\`.`
+// NOT the entry the data-server subcommands of \`hydranium-cli\` speak to: stdio
+// here carries LSP, and the data head is a socket whose port is published over
+// the LSP connection. Those subcommands spawn \`data-server-main.js\`.`
          : ''
    }
 //
@@ -1163,11 +1163,11 @@ ${dataBlock}${glspBlock}`;
  * Emitted with the `data` head because it is the ONLY command line that reaches
  * that head from outside the editor. `main.ts` gives stdio to LSP and publishes
  * the data head's socket port over the LSP connection, so a client that is not
- * an LSP client cannot discover it — which is every one of `hydranium-cli`'s
- * `query` / `save` / `projects` / `watch`, all of which drive the data protocol
- * over a spawned child's stdin/stdout. Without this file a scaffolded project
- * has no `--server` value, and the closest guess — the LSP entry — fails as an
- * unrecognised method rather than as a missing head.
+ * an LSP client cannot discover it — which is every data-server subcommand of
+ * `hydranium-cli`, since each drives the data protocol over a spawned child's
+ * stdin/stdout. Without this file a scaffolded project has no `--server` value,
+ * and the closest guess — the LSP entry — fails as an unrecognised method
+ * rather than as a missing head.
  *
  * A separate process rather than a flag on `main.ts`: only one protocol can own
  * stdio, so the two entries are mutually exclusive by construction.
@@ -1178,10 +1178,9 @@ function dataServerMainFile(composition: InitComposition): string {
    const plural = roots.length > 1 ? 's' : '';
 
    const text = `${SHEBANG}// Standalone entry point: a data-server head on **stdio**, with no LSP head in
-// the process. This is the transport \`hydranium-cli\` speaks — \`query\`, \`save\`,
-// \`projects\` and \`watch\` all spawn a server command and drive JSON-RPC over its
-// stdin/stdout — so it is what makes those subcommands usable against this
-// language.
+// the process. This is the transport \`hydranium-cli\` speaks — its data-server
+// subcommands spawn a server command and drive JSON-RPC over its stdin/stdout —
+// so it is what makes those subcommands usable against this language.
 //
 // Invocation: \`node lib/data-server-main.js [<workspace-path>]\`, or the
 // package's \`__PROJECT_ID__-data-server\` bin script. The workspace path defaults to

package/src/commands/save-args.ts

@@ -40,6 +40,7 @@ export const SAVE_HELP: readonly string[] = [
    'Usage: hydranium-cli save --server "<cmd>..." --uri <uri> --content <text|@file> [--client-id <id>] [--cwd <dir>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    'Update the document at `<uri>` with `<content>` and persist via saveModelDocument.',
+   'Fails when the file does not exist; `create` writes a new one.',
    'Output is the post-save envelope as a single JSON line.',
    '',
    'Options:',

package/src/commands/save.ts

@@ -7,11 +7,12 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { describeError, type TransferElement } from '@hydranium/protocol';
+import type { TransferElement } from '@hydranium/protocol';
 import type { DataServerProtocol } from '@hydranium/protocol/data';
-import * as fs from 'node:fs/promises';
 import { logEnv, type LogOptions } from '../log-level.js';
 import { withDataServer } from '../spawn-data-server.js';
+import { withClientSession } from './client-session.js';
+import { resolveContent } from './harness-args.js';
 
 /**
  * Options for the {@link runSave} subcommand. Updates the document at
@@ -25,9 +26,9 @@ import { withDataServer } from '../spawn-data-server.js';
  * 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.
+ * session, opens the document, saves, and ends the session, which leaves
+ * nothing open behind it. A missing file fails the open; `runCreate` writes a
+ * new one.
  */
 export interface SaveCommandOptions extends LogOptions {
    readonly serverCommand: string;
@@ -66,56 +67,15 @@ export async function runSave(options: SaveCommandOptions): Promise<void> {
    );
 }
 
-/**
- * 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'
-   >,
+/** Open `uri` as the session `clientId` and save `model` to it, then end the session. */
+function saveOpened(
+   server: Pick<DataServerProtocol<TransferElement>, 'createSession' | 'openModelDocument' | '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}: ${describeError(opened)} (creating it failed first: ${describeError(created)})`, {
-               cause: created
-            });
-         })
-      );
-      saved = await server.saveModelDocument({ uri, clientId, model, baseVersion: 'any' });
-   } catch (error: unknown) {
-      await server.closeSession({ clientId }).catch(() => undefined);
-      throw error;
-   }
-   await server.closeSession({ clientId });
-   return saved;
-}
-
-/**
- * Resolve the `--content` argument to its textual form. The `@<path>`
- * prefix reads from a file (parses as UTF-8); anything else is taken
- * literally. The leading `@` can be escaped as `\@` for content that
- * legitimately starts with `@`.
- */
-async function resolveContent(content: string, readFile?: (path: string) => Promise<string>): Promise<string> {
-   if (content.startsWith('@')) {
-      const path = content.slice(1);
-      const reader = readFile ?? ((target: string) => fs.readFile(target, 'utf8'));
-      return reader(path);
-   }
-   if (content.startsWith('\\@')) {
-      return content.slice(1);
-   }
-   return content;
+   return withClientSession(server, clientId, async () => {
+      await server.openModelDocument({ uri, clientId });
+      return server.saveModelDocument({ uri, clientId, model, baseVersion: 'any' });
+   });
 }

package/src/index.ts

@@ -7,6 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+export * from './commands/create.js';
 export * from './commands/delete.js';
 export * from './commands/generate-ast-builder.js';
 export * from './commands/generate-transfer-model.js';

package/src/spawn-data-server.ts

@@ -236,9 +236,9 @@ export function spawnDataServer<TTransfer extends TransferElement, TDiagnostic e
  * 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.
+ * answered. This is the one-shot counterpart the data-server 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,