@hydranium/cli 1.0.0-next.30 → 1.0.0-next.301

package/package.json

@@ -1,34 +1,46 @@
 {
   "name": "@hydranium/cli",
-  "version": "1.0.0-next.30",
+  "version": "1.0.0-next.301",
   "description": "Build-time codegen tools + data-server subcommands for the hydranium framework.",
   "keywords": [
+    "cli",
+    "codegen",
     "hydranium",
     "langium",
     "language-server",
-    "lsp",
-    "cli",
-    "codegen"
+    "lsp"
   ],
   "homepage": "https://github.com/eclipse-emfcloud/hydranium/tree/main/packages/cli",
   "bugs": {
     "url": "https://github.com/eclipse-emfcloud/hydranium/issues"
   },
+  "license": "MIT",
+  "author": {
+    "name": "Hydranium Team"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/eclipse-emfcloud/hydranium.git",
     "directory": "packages/cli"
   },
-  "license": "MIT",
-  "author": {
-    "name": "Hydranium Team"
+  "bin": {
+    "hydranium-cli": "bin/hydranium-cli.js"
   },
+  "files": [
+    "bin",
+    "lib",
+    "src",
+    "heap-analysis",
+    "!lib/**/*.tsbuildinfo"
+  ],
+  "type": "module",
   "sideEffects": [
     "./lib/cli.js",
     "./lib/commands/*-driver.js",
     "./lib/testing/echo-server.js"
   ],
-  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
@@ -39,21 +51,13 @@
       "default": "./lib/cli.js"
     }
   },
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
-  "bin": {
-    "hydranium-cli": "lib/cli.js"
+  "publishConfig": {
+    "access": "public"
   },
-  "files": [
-    "lib",
-    "src",
-    "heap-analysis",
-    "!lib/**/*.tsbuildinfo"
-  ],
   "scripts": {
-    "build": "tsc -b && node -e \"require('node:fs').chmodSync('lib/cli.js',0o755)\"",
+    "build": "tsc -b",
     "clean": "rimraf lib tsconfig.tsbuildinfo",
-    "lint": "eslint src test --max-warnings 0",
+    "lint": "oxlint --format stylish --config ../../oxlint.config.cjs src test --max-warnings 0",
     "prepack": "node -e \"const m=require('./package.json'),fs=require('node:fs');const missing=[m.main,...Object.values(m.bin||{})].filter(entry=>entry&&!fs.existsSync(entry));if(missing.length){console.error('prepack '+m.name+': not built ('+missing.join(', ')+' missing). Run the build before packing: a files entry that matches nothing is skipped silently, so the tarball would ship src only.');process.exit(1);}\"",
     "test": "npm run typecheck:test && vitest run",
     "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
@@ -65,23 +69,33 @@
     "ts-morph": "^25.0.0"
   },
   "devDependencies": {
-    "@hydranium/core": "1.0.0-next.30",
-    "@hydranium/data-server": "1.0.0-next.30",
-    "@hydranium/langium": "1.0.0-next.30",
-    "@hydranium/protocol": "1.0.0-next.30",
+    "@eclipse-glsp/graph": "2.7.0",
+    "@eclipse-glsp/server": "2.7.0",
+    "@hydranium/core": "1.0.0-next.301",
+    "@hydranium/data-server": "1.0.0-next.301",
+    "@hydranium/glsp-server": "1.0.0-next.301",
+    "@hydranium/langium": "1.0.0-next.301",
+    "@hydranium/protocol": "1.0.0-next.301",
+    "@types/node": "^22.0.0",
+    "inversify": "6.2.2",
+    "langium": "4.3.1",
+    "langium-cli": "4.3.0",
+    "reflect-metadata": "0.2.2",
     "rimraf": "^5.0.0",
-    "typescript": "^5.8.0",
-    "vscode-jsonrpc": "9.0.1",
-    "vscode-languageserver": "~10.0.1"
+    "typescript": "^7.0.2",
+    "vitest": "^4.0.0",
+    "vscode-jsonrpc": "9.0.0",
+    "vscode-languageserver": "10.0.1",
+    "vscode-languageserver-protocol": "3.18.1"
   },
   "peerDependencies": {
-    "@hydranium/core": "1.0.0-next.30",
-    "@hydranium/data-server": "1.0.0-next.30",
-    "@hydranium/langium": "1.0.0-next.30",
-    "@hydranium/protocol": "1.0.0-next.30",
+    "@hydranium/core": "1.0.0-next.301",
+    "@hydranium/data-server": "1.0.0-next.301",
+    "@hydranium/langium": "1.0.0-next.301",
+    "@hydranium/protocol": "1.0.0-next.301",
     "@memlab/core": "^2.0.3",
     "@memlab/heap-analysis": "^2.0.3",
-    "vscode-jsonrpc": "9.0.1"
+    "vscode-jsonrpc": "^9.0.0"
   },
   "peerDependenciesMeta": {
     "@memlab/core": {
@@ -94,13 +108,10 @@
   "engines": {
     "node": ">=22.13"
   },
-  "publishConfig": {
-    "access": "public"
-  },
-  "//build": "The chmod is load-bearing, not cruft. npm sets a bin's executable bit through bin-links' fixBin, but ONLY when it first creates the link — and `tsc` never sets it, so after `npm run clean` (which deletes lib/) a rebuild leaves lib/cli.js at 0644 and the node_modules/.bin/hydranium-cli symlink resolves to a non-executable target. Every example's `generate` step then dies with `sh: hydranium-cli: Permission denied`, surfacing as an opaque npm error code 127 during `turbo run build`. npm rebuild, npm rebuild @hydranium/cli AND a full npm install all fail to restore it, because npm will not revisit an existing workspace symlink; only a from-scratch `rm -rf node_modules` install does. Written as `node -e` rather than `chmod +x` so it stays portable — on Windows npm generates .cmd/.ps1 shims where the bit is irrelevant and chmodSync is harmless. The example packages' bins need no such step: their tests spawn them via process.execPath, never through the shim.",
-  "//exports": "Two keys, and the SHORT list is the point: `files` ships the whole compiled tree, so without a map every `lib/commands/*.js`, every internal helper and `lib/testing/echo-server.js` is deep-importable the moment this publishes, and semver then applies to all of it. `.` is the library barrel (the data-server subcommands an adopter calls as functions). `./lib/cli.js` is the BINARY ARTEFACT, and it is declared because a consumer that spawns the CLI resolves it BY SPECIFIER — `createRequire(import.meta.url).resolve('@hydranium/cli/lib/cli.js')` — to get the path npx would run; `bin` gives a shim on PATH, not a path, so dropping this key breaks that resolution and the failure surfaces as \"hydranium-cli is not built\", naming the wrong cause. It is declared in the `/lib/` spelling ONLY: that spelling already resolves under both of this repo's module resolvers, so the twin rule (which exists so a BARE subpath is reachable from node10) has nothing to add here and a bare twin would only be a second name for one artefact. `heap-analysis/` needs no key even though `files` ships it — `analyze-heap` reaches the analyzer through a `new URL(..., import.meta.url)` file URL, which `exports` does not gate, and the package's own tests reach it relatively. `./testing` is deliberately absent: `echo-server` is a spawnable stdio fixture, not a reusable export.",
+  "//devDependencies": "Every package an `init` scaffold declares, other than this one, is declared here, whether or not `src` uses it: the scaffold-compiles test compiles and runs scaffolds inside this package, so their imports and tools resolve through these declarations. `check:init-provenance` holds this list and its versions to the scaffold's manifest.",
+  "//exports": "Two keys, and the SHORT list is the point: `files` ships the whole compiled tree, so without a map every `lib/commands/*.js`, every internal helper and `lib/testing/echo-server.js` is deep-importable the moment this publishes, and semver then applies to all of it. `.` is the library barrel (the data-server subcommands an adopter calls as functions). `./lib/cli.js` is the BINARY ARTEFACT, and it is declared because a consumer that spawns the CLI resolves it BY SPECIFIER — `createRequire(import.meta.url).resolve('@hydranium/cli/lib/cli.js')` — to get the path npx would run; `bin` gives a shim on PATH, not a path, so dropping this key breaks that resolution and the failure surfaces as \"hydranium-cli is not built\", naming the wrong cause. `heap-analysis/` needs no key even though `files` ships it — `analyze-heap` reaches the analyzer through a `new URL(..., import.meta.url)` file URL, which `exports` does not gate, and the package's own tests reach it relatively. `./testing` is deliberately absent: `echo-server` is a spawnable stdio fixture, not a reusable export.",
   "//memlab": "@memlab/core and @memlab/heap-analysis are OPTIONAL PEER dependencies, not optionalDependencies, and the distinction is the whole point: npm installs optionalDependencies BY DEFAULT, both memlab packages pin puppeteer exactly, and puppeteer's postinstall downloads a Chrome binary — so every adopter of this CLI paid ~86 MB and a browser download for the one subcommand almost none of them run, and the download can fail and be walked past as a warning. An optional peer is not auto-installed, so `analyze-heap` documents `npm install @memlab/core @memlab/heap-analysis` as the opt-in and every other subcommand is unaffected. Taken pre-publish deliberately: after publish the install shape is what adopters already have.",
-  "//peerDependencies": "`vscode-jsonrpc` is EXACT rather than a range, because it is one link of an atomic chain with no independently movable link: `vscode-languageserver-protocol` depends on it at exactly 9.0.1, so any other value an adopter supplies is a SECOND physical copy rather than an upgrade. This wire stack breaks on copy identity rather than on structure — `ParameterStructures.auto` is a singleton compared by `===` in connection.js, so a request type built by one copy and sent over a connection owned by the other throws `Unknown parameter structure auto`. A caret or union range was rejected because npm then resolves a `vscode-jsonrpc@8.2.0` tree SILENTLY, with no diagnostic at all, and the failure surfaces only later at server init. Exact does not fail the install either — npm downgrades an unsatisfiable peer to a warning — but it is a NAMED ERESOLVE warning printing the required version beside the found one, and a hard error for anyone installing with `--strict-peer-deps`. It does NOT prevent a NESTED copy — `@eclipse-glsp/*` carries its own exact `vscode-jsonrpc@8.2.0` dependency and root `overrides` do not ship — so a consumer of the GLSP head must pin the chain in its own manifest.",
-  "//prepack": "The publish guard, and it deliberately is NOT a `prepare`: npm runs a workspace `prepare` BEFORE the root `postinstall` that applies patches/vscode-jsonrpc+9.0.1.patch, so building there fails on a cold clone and npm rolls the entire install back. `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. It FAILS rather than rebuilds, because the rebuild is exactly the part that ordering defeats. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error.",
+  "//peerDependencies": "`vscode-jsonrpc` takes a caret, so the framework shares the transport the LSP connection resolves, which an `init` scaffold pins: each `vscode-languageserver-protocol` release pins its transport exactly, so an exact peer would name a copy a fresh install rarely holds. The caret excludes 8.x, so a tree whose top holds GLSP's copy fails the peer with a named ERESOLVE warning, an error under `--strict-peer-deps`, rather than resolving silently. No peer reaches a NESTED copy, such as GLSP's or one the LSP packages nest. The wire compares message types and `ResponseError`s by copy identity, so the framework sends typed messages by method name and recognises errors with `isResponseError` rather than `instanceof`.",
+  "//prepack": "The publish guard, a `prepack` rather than a `prepare`: `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error.",
   "//sideEffects": "The listed modules RUN on load rather than exporting anything: `cli.js` is the `bin`, each `*-driver.js` is spawned as its own process and calls `main(process.argv)` at top level, and `echo-server.js` starts a server. Their whole purpose is the effect, so a bundler must never treat them as prunable. Everything else here is library code with no module-level state beyond `new URL(..., import.meta.url)` constants."
 }

package/src/cli.ts

@@ -9,9 +9,12 @@
  ********************************************************************************/
 
 import { Command } from 'commander';
+import { describeError } from '@hydranium/protocol';
 import { readCliVersion } from './cli-version.js';
 import { runAnalyzeHeapCommand } from './commands/analyze-heap-args.js';
 import { runAstGroundTruthCommand } from './commands/ast-ground-truth-args.js';
+import { runCreateCommand } from './commands/create-args.js';
+import { runDeleteCommand } from './commands/delete-args.js';
 import { runGenerateTransferModelCommand } from './commands/generate-transfer-model-args.js';
 import { runInitCommand } from './commands/init-args.js';
 import { InitWizardCancelled } from './commands/init-prompt.js';
@@ -44,6 +47,8 @@ const COMMANDS: Record<string, { readonly summary: string; readonly run: (args:
       summary: "Tally a workspace's live-model $types (analyze-heap --validate input).",
       run: runAstGroundTruthCommand
    },
+   create: { summary: 'Create a new document and its file via a data-server subprocess.', run: runCreateCommand },
+   delete: { summary: 'Delete a document, its file included, via a data-server subprocess.', run: runDeleteCommand },
    'generate-transfer-model': {
       summary: 'Generate a transfer-model TypeScript file from a Langium AST.',
       run: runGenerateTransferModelCommand
@@ -55,7 +60,7 @@ const COMMANDS: Record<string, { readonly summary: string; readonly run: (args:
    projects: { summary: 'List projects exposed by a data-server subprocess.', run: runProjectsCommand },
    query: { summary: 'Print the data-server document envelope for a URI.', run: runQueryCommand },
    reflect: { summary: "Dump a head's grammar/AST reflection (types, terminals, refs).", run: runReflectCommand },
-   save: { summary: 'Update + persist a document via a data-server subprocess.', run: runSaveCommand },
+   save: { summary: 'Update + persist an existing document via a data-server subprocess.', run: runSaveCommand },
    validate: { summary: 'Validate a workspace headlessly; non-zero exit on errors (CI gate).', run: runValidateCommand },
    watch: { summary: 'Subscribe to data-server document updates; print events as NDJSON.', run: runWatchCommand }
 };
@@ -134,6 +139,6 @@ main(process.argv.slice(2)).catch(err => {
    if (err instanceof InitWizardCancelled) {
       process.exit(130);
    }
-   console.error(err instanceof Error ? err.message : String(err));
+   console.error(describeError(err));
    process.exit(1);
 });

package/src/commands/analyze-heap.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 import { fileURLToPath } from 'node:url';
+import { driverHeapArgs, type HeapReading } from '../driver-heap.js';
 import { spawnNodeChild } from './headless-harness.js';
 
 /**
@@ -41,6 +42,8 @@ export interface AnalyzeHeapDeps {
    readonly __spawnForTest?: (execArgs: string[]) => Promise<number>;
    /** Override the memlab-availability check. */
    readonly __memlabInstalledForTest?: () => boolean;
+   /** Decide the heap ceiling from a stated cgroup reading rather than the machine's. */
+   readonly __heapReadingForTest?: HeapReading;
 }
 
 /**
@@ -69,7 +72,7 @@ export async function runAnalyzeHeap(args: string[], deps: AnalyzeHeapDeps = {})
       return;
    }
    const spawnChild = deps.__spawnForTest ?? spawnNodeChild;
-   const code = await spawnChild(['--max-old-space-size=8192', ANALYZER, ...args]);
+   const code = await spawnChild([...driverHeapArgs(deps.__heapReadingForTest), ANALYZER, ...args]);
    if (code) {
       process.exitCode = code;
    }

package/src/commands/ast-ground-truth-args.ts

@@ -10,32 +10,34 @@
 import { runAstGroundTruth, type AstGroundTruthCommandOptions } from './ast-ground-truth.js';
 import {
    exitWithUsage,
+   HARNESS_VALUE_FLAGS,
    helpRequested,
-   LOG_LEVEL_FLAG,
-   logLevelHelpLine,
-   logLevelOption,
+   importHelpLines,
+   LOG_VALUE_FLAGS,
+   logHelpLines,
+   logOptions,
    parseHarnessArgs,
    printHelp,
-   SERVICES_FLAG,
    type UsageError
 } from './harness-args.js';
 import { OUT_FILE_FLAG } from './headless-harness.js';
 
-const VALUE_FLAGS = [OUT_FILE_FLAG, LOG_LEVEL_FLAG] as const;
+const VALUE_FLAGS = [OUT_FILE_FLAG, ...LOG_VALUE_FLAGS] as const;
 
 /**
  * Every flag `ast-ground-truth` accepts, derived from the sets the parser is
- * handed so the list cannot claim a flag the parser would reject. `--services`
- * is consumed by the shared harness parser itself, so it is in neither set.
+ * handed so the list cannot claim a flag the parser would reject.
+ * {@link HARNESS_VALUE_FLAGS} are consumed by the shared harness parser itself,
+ * so they are in neither set.
  */
-export const AST_GROUND_TRUTH_FLAGS: readonly string[] = [SERVICES_FLAG, ...VALUE_FLAGS];
+export const AST_GROUND_TRUTH_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS, ...VALUE_FLAGS];
 
 /** The subset that takes a value, so `--help` in a value position reads as data. */
 export const AST_GROUND_TRUTH_VALUE_FLAGS: readonly string[] = AST_GROUND_TRUTH_FLAGS;
 
 /** The `--help` text, as data, held to {@link AST_GROUND_TRUTH_FLAGS} by a test. */
 export const AST_GROUND_TRUTH_HELP: readonly string[] = [
-   'Usage: hydranium-cli ast-ground-truth --services <module> <workspace> [--out-file <file>] [--log-level <lvl>]',
+   'Usage: hydranium-cli ast-ground-truth --services <module> [--import <specifier>]... <workspace> [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    "Tally a workspace's live-model AST nodes by `$type` — the ground truth that",
    '`analyze-heap --validate <gt.json>` checks a heap snapshot against. `<module>`',
@@ -44,14 +46,15 @@ export const AST_GROUND_TRUTH_HELP: readonly string[] = [
    '',
    'Options:',
    '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   ...importHelpLines(22),
    '  <workspace>           Workspace root (path or file URI) to build (required).',
    '  --out-file <file>     Write the JSON to this file instead of stdout.',
-   logLevelHelpLine(22)
+   ...logHelpLines(22)
 ];
 
 export function parseAstGroundTruthArgs(args: string[], onError: UsageError = exitWithUsage): AstGroundTruthCommandOptions {
-   const { servicesModule, workspace, options } = parseHarnessArgs(args, 'ast-ground-truth', VALUE_FLAGS, [], { onError });
-   return { servicesModule, workspace, outFile: options[OUT_FILE_FLAG], logLevel: logLevelOption(options[LOG_LEVEL_FLAG]) };
+   const { servicesModule, imports, workspace, options } = parseHarnessArgs(args, 'ast-ground-truth', VALUE_FLAGS, [], { onError });
+   return { servicesModule, imports, workspace, outFile: options[OUT_FILE_FLAG], ...logOptions(options) };
 }
 
 export function runAstGroundTruthCommand(args: string[]): Promise<void> {

package/src/commands/ast-ground-truth-driver.ts

@@ -16,6 +16,7 @@
  */
 
 import * as fs from 'node:fs';
+import { describeError } from '@hydranium/protocol';
 import { loadHeadlessContext, OUT_FILE_FLAG } from './headless-harness.js';
 
 interface DriverArgs {
@@ -76,6 +77,6 @@ async function main(argv: string[]): Promise<void> {
 main(process.argv.slice(2))
    .then(() => process.exit(0))
    .catch((error: unknown) => {
-      console.error(error instanceof Error ? error.message : String(error));
+      console.error(describeError(error));
       process.exit(1);
    });

package/src/commands/ast-ground-truth.ts

@@ -45,5 +45,5 @@ export function buildGroundTruthDriverArgs(options: AstGroundTruthCommandOptions
  * `--out-file`). No `--expose-gc` needed — this walks the AST, it does not weigh it.
  */
 export function runAstGroundTruth(options: AstGroundTruthCommandOptions): Promise<void> {
-   return runDriverChild(['--max-old-space-size=8192', DRIVER, ...buildGroundTruthDriverArgs(options)], options);
+   return runDriverChild([DRIVER, ...buildGroundTruthDriverArgs(options)], options);
 }

package/src/commands/client-session.ts

@@ -0,0 +1,33 @@
+/********************************************************************************
+ * 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 { TransferElement } from '@hydranium/protocol';
+import type { DataServerProtocol } from '@hydranium/protocol/data';
+
+/**
+ * Run `fn` as the client session `clientId`, and end the session whether `fn`
+ * succeeded or not, which closes whatever it left open. An end that fails
+ * after a failed `fn` is swallowed: `fn`'s error is the one the user needs.
+ */
+export async function withClientSession<T>(
+   server: Pick<DataServerProtocol<TransferElement>, 'createSession' | 'closeSession'>,
+   clientId: string,
+   fn: () => Promise<T>
+): Promise<T> {
+   await server.createSession({ clientId, label: 'hydranium-cli' });
+   let result: T;
+   try {
+      result = await fn();
+   } catch (error: unknown) {
+      await server.closeSession({ clientId }).catch(() => undefined);
+      throw error;
+   }
+   await server.closeSession({ clientId });
+   return result;
+}

package/src/commands/create-args.ts

@@ -0,0 +1,68 @@
+/********************************************************************************
+ * Copyright (c) 2026 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,
+   logHelpLines,
+   parseFlagOptions,
+   parseServerSpawnOptions,
+   printHelp,
+   SERVER_SPAWN_VALUE_FLAGS,
+   type UsageError
+} from './harness-args.js';
+import { type CreateCommandOptions, runCreate } from './create.js';
+
+const OWN_FLAGS = ['--uri', '--content', '--client-id'] as const;
+
+/** Every flag `create` accepts, each of which takes a value. */
+export const CREATE_FLAGS: readonly string[] = [...SERVER_SPAWN_VALUE_FLAGS, ...OWN_FLAGS];
+
+/** The `--help` text, as data, held to {@link CREATE_FLAGS} by a test. */
+export const CREATE_HELP: readonly string[] = [
+   'Usage: hydranium-cli create --server "<cmd>..." --uri <uri> --content <text|@file> [--client-id <id>] [--cwd <dir>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
+   '',
+   'Create the document at `<uri>` with `<content>` via createModelDocument, and persist it',
+   'as given. Fails when the file exists or a client has it open.',
+   'Output is the post-save envelope as a single JSON line.',
+   '',
+   'Options:',
+   '  --server "<cmd>"      Command-line for the data-server subprocess (required).',
+   '  --uri <uri>           Document URI (required).',
+   '  --content <text>      Content to write (required). Prefix `@` to read from a file',
+   '                        (escape with `\\@` for literal `@`-leading content).',
+   '  --client-id <id>      clientId for authorship attribution. Default: hydranium-cli.',
+   '  --cwd <dir>           Working directory for the spawned child. Default: cwd.',
+   ...logHelpLines(22, 'the spawned server')
+];
+
+export function parseCreateArgs(args: string[], onError: UsageError = exitWithUsage): CreateCommandOptions {
+   const { serverCommand, serverArgs, cwd, logLevel, logFile, logFileLevel, extra } = parseServerSpawnOptions(args, 'create', onError);
+   const { uri, content, clientId } = parseFlagOptions(extra, 'create', OWN_FLAGS, onError);
+   return {
+      serverCommand,
+      serverArgs,
+      cwd,
+      logLevel,
+      logFile,
+      logFileLevel,
+      uri: assertRequired(uri, '--uri', 'create', onError),
+      content: assertRequired(content, '--content', 'create', onError),
+      clientId
+   };
+}
+
+export function runCreateCommand(args: string[]): Promise<void> {
+   if (helpRequested(args, CREATE_FLAGS)) {
+      printHelp(CREATE_HELP);
+      return Promise.resolve();
+   }
+   return runCreate(parseCreateArgs(args));
+}

package/src/commands/create.ts

@@ -0,0 +1,83 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 { TransferElement } from '@hydranium/protocol';
+import type { DataServerProtocol } from '@hydranium/protocol/data';
+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 runCreate} subcommand. Creates the document at `uri`
+ * with `content` (literal text or `@<path>` for a file reference) via the
+ * data-server's `createModelDocument` RPC, and persists that text as it is.
+ * Fails when the file exists or a client has it open. Writes the post-save
+ * envelope as a single JSON line, as `save` does.
+ *
+ * `clientId` defaults to `'hydranium-cli'`. The command creates as a client
+ * session under it: it registers the session, creates the document, persists
+ * it, since a created document reaches disk only with a save, and ends the
+ * session.
+ */
+export interface CreateCommandOptions extends LogOptions {
+   readonly serverCommand: string;
+   readonly serverArgs?: readonly string[];
+   readonly cwd?: string;
+   readonly uri: string;
+   /** Literal content text, or `@<path>` to read from a file. */
+   readonly content: string;
+   readonly clientId?: string;
+   readonly write?: (line: string) => void;
+   readonly __proxyForTest?: DataServerProtocol<TransferElement>;
+   /** Test-only: override the file-reader so unit tests can stub `@<path>` expansion. */
+   readonly __readFileForTest?: (path: string) => Promise<string>;
+}
+
+export async function runCreate(options: CreateCommandOptions): Promise<void> {
+   const write = options.write ?? ((line: string) => process.stdout.write(line));
+   const clientId = options.clientId ?? 'hydranium-cli';
+   const text = await resolveContent(options.content, options.__readFileForTest);
+
+   if (options.__proxyForTest) {
+      write(`${JSON.stringify(await createPersisted(options.__proxyForTest, options.uri, clientId, text))}\n`);
+      return;
+   }
+
+   await withDataServer(
+      {
+         command: options.serverCommand,
+         args: options.serverArgs,
+         cwd: options.cwd,
+         env: logEnv(options)
+      },
+      async server => {
+         write(`${JSON.stringify(await createPersisted(server, options.uri, clientId, text))}\n`);
+      }
+   );
+}
+
+/**
+ * Create `uri` with `text` as the session `clientId` and persist it, then end
+ * the session. The persist is gated on the version the create made, so a
+ * write that landed before the create's answer or after it, another client's
+ * or an integrity repair, fails the command with a conflict and nothing
+ * persists.
+ */
+function createPersisted(
+   server: Pick<DataServerProtocol<TransferElement>, 'createSession' | 'createModelDocument' | 'persistModelDocument' | 'closeSession'>,
+   uri: string,
+   clientId: string,
+   text: string
+): Promise<unknown> {
+   return withClientSession(server, clientId, async () => {
+      const created = await server.createModelDocument({ uri, clientId, text });
+      return server.persistModelDocument({ uri, clientId, baseVersion: created.created.version });
+   });
+}

package/src/commands/delete-args.ts

@@ -0,0 +1,64 @@
+/********************************************************************************
+ * Copyright (c) 2026 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,
+   logHelpLines,
+   parseFlagOptions,
+   parseServerSpawnOptions,
+   printHelp,
+   SERVER_SPAWN_VALUE_FLAGS,
+   type UsageError
+} from './harness-args.js';
+import { type DeleteCommandOptions, runDelete } from './delete.js';
+
+const OWN_FLAGS = ['--uri', '--client-id'] as const;
+
+/** Every flag `delete` accepts, each of which takes a value. */
+export const DELETE_FLAGS: readonly string[] = [...SERVER_SPAWN_VALUE_FLAGS, ...OWN_FLAGS];
+
+/** The `--help` text, as data, held to {@link DELETE_FLAGS} by a test. */
+export const DELETE_HELP: readonly string[] = [
+   'Usage: hydranium-cli delete --server "<cmd>..." --uri <uri> [--client-id <id>] [--cwd <dir>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
+   '',
+   'Delete the document at `<uri>`, its file and then the document, via deleteModelDocument,',
+   'whatever text it holds. Prints nothing.',
+   '',
+   'Options:',
+   '  --server "<cmd>"      Command-line for the data-server subprocess (required).',
+   '  --uri <uri>           Document URI (required).',
+   '  --client-id <id>      clientId the deletion is attributed to. Default: hydranium-cli.',
+   '  --cwd <dir>           Working directory for the spawned child. Default: cwd.',
+   ...logHelpLines(22, 'the spawned server')
+];
+
+export function parseDeleteArgs(args: string[], onError: UsageError = exitWithUsage): DeleteCommandOptions {
+   const { serverCommand, serverArgs, cwd, logLevel, logFile, logFileLevel, extra } = parseServerSpawnOptions(args, 'delete', onError);
+   const { uri, clientId } = parseFlagOptions(extra, 'delete', OWN_FLAGS, onError);
+   return {
+      serverCommand,
+      serverArgs,
+      cwd,
+      logLevel,
+      logFile,
+      logFileLevel,
+      uri: assertRequired(uri, '--uri', 'delete', onError),
+      clientId
+   };
+}
+
+export function runDeleteCommand(args: string[]): Promise<void> {
+   if (helpRequested(args, DELETE_FLAGS)) {
+      printHelp(DELETE_HELP);
+      return Promise.resolve();
+   }
+   return runDelete(parseDeleteArgs(args));
+}

package/src/commands/delete.ts

@@ -0,0 +1,61 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 { TransferElement } from '@hydranium/protocol';
+import type { DataServerProtocol } from '@hydranium/protocol/data';
+import { logEnv, type LogOptions } from '../log-level.js';
+import { withDataServer } from '../spawn-data-server.js';
+import { withClientSession } from './client-session.js';
+
+/**
+ * Options for the {@link runDelete} subcommand. Deletes the document at `uri`,
+ * its file and then the document, via the data-server's `deleteModelDocument`
+ * RPC, whatever text it holds. Prints nothing; a failed delete rejects.
+ *
+ * `clientId` defaults to `'hydranium-cli'`. The command deletes as a client
+ * session under it: it registers the session, opens the document, deletes it,
+ * and ends the session.
+ */
+export interface DeleteCommandOptions extends LogOptions {
+   readonly serverCommand: string;
+   readonly serverArgs?: readonly string[];
+   readonly cwd?: string;
+   readonly uri: string;
+   readonly clientId?: string;
+   readonly __proxyForTest?: DataServerProtocol<TransferElement>;
+}
+
+export async function runDelete(options: DeleteCommandOptions): Promise<void> {
+   const clientId = options.clientId ?? 'hydranium-cli';
+   if (options.__proxyForTest) {
+      await deleteOpened(options.__proxyForTest, options.uri, clientId);
+      return;
+   }
+   await withDataServer(
+      {
+         command: options.serverCommand,
+         args: options.serverArgs,
+         cwd: options.cwd,
+         env: logEnv(options)
+      },
+      server => deleteOpened(server, options.uri, clientId)
+   );
+}
+
+/** Open `uri` as the session `clientId` and delete it, then end the session. */
+function deleteOpened(
+   server: Pick<DataServerProtocol<TransferElement>, 'createSession' | 'openModelDocument' | 'deleteModelDocument' | 'closeSession'>,
+   uri: string,
+   clientId: string
+): Promise<void> {
+   return withClientSession(server, clientId, async () => {
+      await server.openModelDocument({ uri, clientId });
+      await server.deleteModelDocument({ uri, clientId, baseVersion: 'any' });
+   });
+}