@hydranium/cli 1.0.0-next.42 → 1.0.0-next.421

package/src/commands/query.ts

@@ -7,9 +7,9 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { LogThreshold, TransferElement } from '@hydranium/protocol';
+import { TransferDocument, type TransferElement } from '@hydranium/protocol';
 import type { DataServerProtocol } from '@hydranium/protocol/data';
-import { logLevelEnv } from '../log-level.js';
+import { logEnv, type LogOptions } from '../log-level.js';
 import { withDataServer } from '../spawn-data-server.js';
 
 /**
@@ -17,17 +17,17 @@ import { withDataServer } from '../spawn-data-server.js';
  * current view of a document — invokes `getModelDocument({ uri })` on
  * the spawned subprocess and writes the response envelope as a single
  * JSON line. Adopters piping the output into `jq` get a complete record
- * per invocation.
+ * per invocation. A URI the server holds no document at fails the command,
+ * since the server answers it with an envelope of the URI alone, which a
+ * script would read as a document.
  *
  * Test-only `__proxyForTest` bypasses the spawn for unit tests; the
  * production CLI never passes it.
  */
-export interface QueryCommandOptions {
+export interface QueryCommandOptions extends LogOptions {
    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 write?: (line: string) => void;
    readonly __proxyForTest?: DataServerProtocol<TransferElement>;
@@ -39,7 +39,7 @@ export async function runQuery(options: QueryCommandOptions): Promise<void> {
    if (options.__proxyForTest) {
       // One-shot, unsubscribed read — request validation so the dumped envelope carries diagnostics.
       const doc = await options.__proxyForTest.getModelDocument({ uri: options.uri, includeDiagnostics: true });
-      write(`${JSON.stringify(doc)}\n`);
+      write(`${JSON.stringify(TransferDocument.assertLoaded(doc))}\n`);
       return;
    }
 
@@ -48,11 +48,11 @@ export async function runQuery(options: QueryCommandOptions): Promise<void> {
          command: options.serverCommand,
          args: options.serverArgs,
          cwd: options.cwd,
-         env: options.logLevel ? logLevelEnv(options.logLevel) : undefined
+         env: logEnv(options)
       },
       async server => {
          const doc = await server.getModelDocument({ uri: options.uri, includeDiagnostics: true });
-         write(`${JSON.stringify(doc)}\n`);
+         write(`${JSON.stringify(TransferDocument.assertLoaded(doc))}\n`);
       }
    );
 }

package/src/commands/reflect-args.ts

@@ -9,34 +9,36 @@
 
 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';
 import { runReflect, type ReflectCommandOptions } from './reflect.js';
 
-const VALUE_FLAGS = [OUT_FILE_FLAG, LOG_LEVEL_FLAG] as const;
+const VALUE_FLAGS = [OUT_FILE_FLAG, ...LOG_VALUE_FLAGS] as const;
 const BOOL_FLAGS = ['--json'] as const;
 
 /**
  * Every flag `reflect` 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.
+ * 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 REFLECT_FLAGS: readonly string[] = [SERVICES_FLAG, ...VALUE_FLAGS, ...BOOL_FLAGS];
+export const REFLECT_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS, ...VALUE_FLAGS, ...BOOL_FLAGS];
 
 /** The subset that takes a value, so `--help` in a value position reads as data. */
-export const REFLECT_VALUE_FLAGS: readonly string[] = [SERVICES_FLAG, ...VALUE_FLAGS];
+export const REFLECT_VALUE_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS, ...VALUE_FLAGS];
 
 /** The `--help` text, as data, held to {@link REFLECT_FLAGS} by a test. */
 export const REFLECT_HELP: readonly string[] = [
-   'Usage: hydranium-cli reflect --services <module> [--json] [--out-file <file>] [--log-level <lvl>]',
+   'Usage: hydranium-cli reflect [--services <module>] [--import <specifier>]... [--json] [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    "Dump a head's grammar/AST reflection — the type hierarchy, each language's",
    'terminals and entry rule, and every cross-reference target. Read-only: no',
@@ -45,24 +47,26 @@ export const REFLECT_HELP: readonly string[] = [
    'exporting a zero-arg `createServices(): { shared }` thunk. Needs @hydranium/core.',
    '',
    'Options:',
-   '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   '  --services <module>   ESM module exporting `createServices(): { shared }` (required) unless package.json sets hydranium.services.',
+   ...importHelpLines(22),
    '  --json                Emit the raw JSON reflection instead of the Markdown report.',
    '  --out-file <file>     Write the report to this file instead of stdout. Written',
    '                        only once the report exists, unlike a shell redirection,',
    '                        which truncates the file before the head is even booted.',
-   logLevelHelpLine(22)
+   ...logHelpLines(22)
 ];
 
 export function parseReflectArgs(args: string[], onError: UsageError = exitWithUsage): ReflectCommandOptions {
-   const { servicesModule, options } = parseHarnessArgs(args, 'reflect', VALUE_FLAGS, BOOL_FLAGS, {
+   const { servicesModule, imports, options } = parseHarnessArgs(args, 'reflect', VALUE_FLAGS, BOOL_FLAGS, {
       requireWorkspace: false,
       onError
    });
    return {
       servicesModule,
+      imports,
       json: options['--json'] === 'true',
       outFile: options[OUT_FILE_FLAG],
-      logLevel: logLevelOption(options[LOG_LEVEL_FLAG])
+      ...logOptions(options)
    };
 }
 

package/src/commands/reflect-driver.ts

@@ -16,6 +16,7 @@
  * imported — only spawned.
  */
 
+import { describeError } from '@hydranium/protocol';
 import { emitReport, loadHeadlessContext, OUT_FILE_FLAG } from './headless-harness.js';
 import { formatReflectionReport } from './reflect-report.js';
 
@@ -71,6 +72,6 @@ async function main(argv: string[]): Promise<number> {
 main(process.argv.slice(2))
    .then(code => process.exit(code))
    .catch((error: unknown) => {
-      console.error(error instanceof Error ? error.message : String(error));
+      console.error(describeError(error));
       process.exit(1);
    });

package/src/commands/reflect.ts

@@ -47,5 +47,5 @@ export function buildReflectDriverArgs(options: ReflectCommandOptions): string[]
  * the binary language-agnostic.
  */
 export function runReflect(options: ReflectCommandOptions): Promise<void> {
-   return runDriverChild(['--max-old-space-size=8192', DRIVER, ...buildReflectDriverArgs(options)], options);
+   return runDriverChild([DRIVER, ...buildReflectDriverArgs(options)], options);
 }

package/src/commands/save-args.ts

@@ -11,6 +11,7 @@ import {
    assertRequired,
    exitWithUsage,
    helpRequested,
+   logHelpLines,
    parseFlagOptions,
    parseServerSpawnOptions,
    printHelp,
@@ -36,9 +37,10 @@ export const SAVE_VALUE_FLAGS: readonly string[] = SAVE_FLAGS;
 
 /** The `--help` text, as data, held to {@link SAVE_FLAGS} by a test. */
 export const SAVE_HELP: readonly string[] = [
-   'Usage: hydranium-cli save --server "<cmd>..." --uri <uri> --content <text|@file> [--client-id <id>] [--cwd <dir>] [--log-level <level>]',
+   '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:',
@@ -48,17 +50,19 @@ export const SAVE_HELP: readonly string[] = [
    '                        (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.',
-   '  --log-level <lvl>     Log threshold for the spawned server (off|error|warn|info|debug|trace).'
+   ...logHelpLines(22, 'the spawned server')
 ];
 
 export function parseSaveArgs(args: string[], onError: UsageError = exitWithUsage): SaveCommandOptions {
-   const { serverCommand, serverArgs, cwd, logLevel, extra } = parseServerSpawnOptions(args, 'save', onError);
+   const { serverCommand, serverArgs, cwd, logLevel, logFile, logFileLevel, extra } = parseServerSpawnOptions(args, 'save', onError);
    const { uri, content, clientId } = parseFlagOptions(extra, 'save', OWN_FLAGS, onError);
    return {
       serverCommand,
       serverArgs,
       cwd,
       logLevel,
+      logFile,
+      logFileLevel,
       uri: assertRequired(uri, '--uri', 'save', onError),
       content: assertRequired(content, '--content', 'save', onError),
       clientId

package/src/commands/save.ts

@@ -7,11 +7,12 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { LogThreshold, 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 { logLevelEnv } from '../log-level.js';
+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
@@ -23,13 +24,16 @@ import { withDataServer } from '../spawn-data-server.js';
  *
  * `clientId` defaults to `'hydranium-cli'` — adopters wanting a richer
  * identity (per-user, per-script) override.
+ *
+ * The command saves as a client session under `clientId`: it registers the
+ * session, 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 {
+export interface SaveCommandOptions extends LogOptions {
    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;
    /** Literal content text, or `@<path>` to read from a file. */
    readonly content: string;
@@ -46,8 +50,7 @@ export async function runSave(options: SaveCommandOptions): Promise<void> {
    const model = await resolveContent(options.content, options.__readFileForTest);
 
    if (options.__proxyForTest) {
-      const doc = await options.__proxyForTest.saveModelDocument({ uri: options.uri, clientId, model });
-      write(`${JSON.stringify(doc)}\n`);
+      write(`${JSON.stringify(await saveOpened(options.__proxyForTest, options.uri, clientId, model))}\n`);
       return;
    }
 
@@ -56,29 +59,23 @@ export async function runSave(options: SaveCommandOptions): Promise<void> {
          command: options.serverCommand,
          args: options.serverArgs,
          cwd: options.cwd,
-         env: options.logLevel ? logLevelEnv(options.logLevel) : undefined
+         env: logEnv(options)
       },
       async server => {
-         const doc = await server.saveModelDocument({ uri: options.uri, clientId, model });
-         write(`${JSON.stringify(doc)}\n`);
+         write(`${JSON.stringify(await saveOpened(server, options.uri, clientId, model))}\n`);
       }
    );
 }
 
-/**
- * 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;
+/** 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> {
+   return withClientSession(server, clientId, async () => {
+      await server.openModelDocument({ uri, clientId });
+      return server.saveModelDocument({ uri, clientId, model, baseVersion: 'any' });
+   });
 }

package/src/commands/skills.ts

@@ -0,0 +1,146 @@
+/********************************************************************************
+ * 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 * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { resolve } from 'import-meta-resolve';
+import { parse } from 'yaml';
+
+/** A compatibility result applies to one installed copy, not just its skill name. */
+export interface SkillCompatibility {
+   readonly file: string;
+   readonly status: 'compatible' | 'incompatible' | 'unverified';
+   readonly detail: string;
+}
+
+export const SKILL_DIRECTORIES = ['.agents/skills', '.claude/skills'] as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+   return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Resolve from the adopter, never from a globally installed CLI's dependencies. */
+export function installedPackageManifest(name: string, from: string): Record<string, unknown> | undefined {
+   const parent = path.join(path.resolve(from), 'package.json');
+   let manifest: string;
+   try {
+      manifest = createRequire(parent).resolve(`${name}/package.json`);
+   } catch {
+      try {
+         let directory = path.dirname(fileURLToPath(resolve(name, pathToFileURL(parent).href)));
+         while (true) {
+            const candidate = path.join(directory, 'package.json');
+            if (fs.existsSync(candidate)) {
+               const value: unknown = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+               if (isRecord(value) && value.name === name) {
+                  return value;
+               }
+            }
+            const next = path.dirname(directory);
+            if (next === directory) {
+               return undefined;
+            }
+            directory = next;
+         }
+      } catch {
+         return undefined;
+      }
+   }
+   const value: unknown = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+   return isRecord(value) && value.name === name ? value : undefined;
+}
+
+/** Missing or malformed requirements never constitute evidence of compatibility. */
+export function checkSkill(file: string, from: string): SkillCompatibility {
+   const result = (status: SkillCompatibility['status'], detail: string): SkillCompatibility => ({ file, status, detail });
+   try {
+      const text = fs.readFileSync(file, 'utf8');
+      const frontmatter = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
+      const skill: unknown = frontmatter === undefined ? undefined : parse(frontmatter);
+      const metadata = isRecord(skill) ? skill.metadata : undefined;
+      if (!isRecord(metadata) || metadata['hydranium-compatibility-schema'] !== '1') {
+         return result('unverified', 'No supported Hydranium compatibility metadata.');
+      }
+      const encoded = metadata['hydranium-contracts'];
+      const contracts: unknown = typeof encoded === 'string' ? JSON.parse(encoded) : undefined;
+      if (
+         !isRecord(contracts) ||
+         Object.keys(contracts).length === 0 ||
+         Object.entries(contracts).some(
+            ([name, declarations]) =>
+               !/^(@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/.test(name) ||
+               !isRecord(declarations) ||
+               Object.keys(declarations).length === 0 ||
+               Object.entries(declarations).some(
+                  ([contract, revision]) => !contract.trim() || typeof revision !== 'string' || !revision.trim()
+               )
+         )
+      ) {
+         return result('unverified', 'Invalid package contract requirements.');
+      }
+      const problems: string[] = [];
+      const versions: string[] = [];
+      let mismatch = false;
+      for (const [name, requiredContracts] of Object.entries(contracts)) {
+         const manifest = installedPackageManifest(name, from);
+         const version = manifest?.version;
+         const configuration = manifest?.hydranium;
+         const suppliedContracts = isRecord(configuration) ? configuration.skillContracts : undefined;
+         const contractMatches =
+            isRecord(requiredContracts) &&
+            isRecord(suppliedContracts) &&
+            Object.entries(requiredContracts).every(
+               ([contract, revision]) => Object.hasOwn(suppliedContracts, contract) && suppliedContracts[contract] === revision
+            );
+         if (manifest === undefined) {
+            problems.push(`${name} is not installed; install dependencies and retry.`);
+         } else if (!contractMatches) {
+            mismatch = true;
+            problems.push(`${name} does not declare the required skill contracts.`);
+         } else {
+            versions.push(`${name}${typeof version === 'string' ? `@${version}` : ''} (declared skill contract)`);
+         }
+      }
+      return problems.length > 0
+         ? result(mismatch ? 'incompatible' : 'unverified', problems.join(' '))
+         : result('compatible', `Declared requirements satisfied by ${versions.join(', ')}.`);
+   } catch (error) {
+      return result('unverified', error instanceof Error ? error.message : String(error));
+   }
+}
+
+/** Check every selected copy so an outdated agent-specific copy cannot hide behind a shared one. */
+export function checkSkills(project: string, from = project, names?: readonly string[]): SkillCompatibility[] {
+   const results: SkillCompatibility[] = [];
+   const found = new Set<string>();
+   for (const directory of SKILL_DIRECTORIES) {
+      const root = path.join(project, directory);
+      if (!fs.existsSync(root)) {
+         continue;
+      }
+      for (const name of fs.readdirSync(root)) {
+         if (!(names ? names.includes(name) : name.startsWith('hydranium-'))) {
+            continue;
+         }
+         found.add(name);
+         results.push(checkSkill(path.join(root, name, 'SKILL.md'), from));
+      }
+   }
+   for (const name of names ?? []) {
+      if (!found.has(name)) {
+         results.push({ file: name, status: 'unverified', detail: 'Skill is not installed in a checked project directory.' });
+      }
+   }
+   if (results.length === 0) {
+      results.push({ file: project, status: 'unverified', detail: 'No Hydranium project skills found.' });
+   }
+   return results;
+}

package/src/commands/validate-args.ts

@@ -9,34 +9,36 @@
 
 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';
 import { runValidate, type ValidateCommandOptions } from './validate.js';
 
-const VALUE_FLAGS = [OUT_FILE_FLAG, LOG_LEVEL_FLAG] as const;
+const VALUE_FLAGS = [OUT_FILE_FLAG, ...LOG_VALUE_FLAGS] as const;
 const BOOL_FLAGS = ['--strict', '--json'] as const;
 
 /**
  * Every flag `validate` 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.
+ * 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 VALIDATE_FLAGS: readonly string[] = [SERVICES_FLAG, ...VALUE_FLAGS, ...BOOL_FLAGS];
+export const VALIDATE_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS, ...VALUE_FLAGS, ...BOOL_FLAGS];
 
 /** The subset that takes a value, so `--help` in a value position reads as data. */
-export const VALIDATE_VALUE_FLAGS: readonly string[] = [SERVICES_FLAG, ...VALUE_FLAGS];
+export const VALIDATE_VALUE_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS, ...VALUE_FLAGS];
 
 /** The `--help` text, as data, held to {@link VALIDATE_FLAGS} by a test. */
 export const VALIDATE_HELP: readonly string[] = [
-   'Usage: hydranium-cli validate --services <module> <workspace> [--strict] [--json] [--out-file <file>] [--log-level <lvl>]',
+   'Usage: hydranium-cli validate [--services <module>] [--import <specifier>]... <workspace> [--strict] [--json] [--out-file <file>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    'Build a workspace headlessly and report its validation diagnostics — a CI gate:',
    'the process exits non-zero when any error is found. `<module>` is an ESM module',
@@ -44,7 +46,8 @@ export const VALIDATE_HELP: readonly string[] = [
    'filesystem inside). Needs @hydranium/core.',
    '',
    'Options:',
-   '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   '  --services <module>   ESM module exporting `createServices(): { shared }` (required) unless package.json sets hydranium.services.',
+   ...importHelpLines(22),
    '  <workspace>           Workspace root (path or file URI) to validate (required).',
    '  --strict              Also fail (non-zero exit) on warnings, not only errors.',
    '  --json                Emit the raw JSON result instead of the human report.',
@@ -52,18 +55,19 @@ export const VALIDATE_HELP: readonly string[] = [
    '                        still decides the exit code, and the file is written only',
    '                        once the report exists, unlike a shell redirection, which',
    '                        truncates the file before the workspace is even built.',
-   logLevelHelpLine(22)
+   ...logHelpLines(22)
 ];
 
 export function parseValidateArgs(args: string[], onError: UsageError = exitWithUsage): ValidateCommandOptions {
-   const { servicesModule, workspace, options } = parseHarnessArgs(args, 'validate', VALUE_FLAGS, BOOL_FLAGS, { onError });
+   const { servicesModule, imports, workspace, options } = parseHarnessArgs(args, 'validate', VALUE_FLAGS, BOOL_FLAGS, { onError });
    return {
       servicesModule,
+      imports,
       workspace,
       strict: options['--strict'] === 'true',
       json: options['--json'] === 'true',
       outFile: options[OUT_FILE_FLAG],
-      logLevel: logLevelOption(options[LOG_LEVEL_FLAG])
+      ...logOptions(options)
    };
 }
 

package/src/commands/validate-driver.ts

@@ -16,6 +16,7 @@
  * `--strict` also fails on warnings). Never imported — only spawned.
  */
 
+import { describeError } from '@hydranium/protocol';
 import { emitReport, loadHeadlessContext, OUT_FILE_FLAG } from './headless-harness.js';
 import { formatValidationReport, validationExitCode } from './validate-report.js';
 
@@ -79,6 +80,6 @@ async function main(argv: string[]): Promise<number> {
 main(process.argv.slice(2))
    .then(code => process.exit(code))
    .catch((error: unknown) => {
-      console.error(error instanceof Error ? error.message : String(error));
+      console.error(describeError(error));
       process.exit(1);
    });

package/src/commands/validate.ts

@@ -54,5 +54,5 @@ export function buildValidateDriverArgs(options: ValidateCommandOptions): string
  * The child's exit code propagates to this process so shells and CI see the gate.
  */
 export function runValidate(options: ValidateCommandOptions): Promise<void> {
-   return runDriverChild(['--max-old-space-size=8192', DRIVER, ...buildValidateDriverArgs(options)], options);
+   return runDriverChild([DRIVER, ...buildValidateDriverArgs(options)], options);
 }

package/src/commands/watch-args.ts

@@ -11,6 +11,7 @@ import {
    assertRequired,
    exitWithUsage,
    helpRequested,
+   logHelpLines,
    parseFlagOptions,
    parseServerSpawnOptions,
    printHelp,
@@ -35,7 +36,7 @@ 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>]',
+   'Usage: hydranium-cli watch --server "<cmd>..." --uri <uri> [--client-id <id>] [--cwd <dir>] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    'Subscribe to document updates at `<uri>` and print events as newline-delimited',
    'JSON. Long-running — exits cleanly on SIGINT (Ctrl-C).',
@@ -45,18 +46,20 @@ export const WATCH_HELP: readonly string[] = [
    '  --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).'
+   ...logHelpLines(22, 'the spawned server')
 ];
 
 /** 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 { serverCommand, serverArgs, cwd, logLevel, logFile, logFileLevel, extra } = parseServerSpawnOptions(args, 'watch', onError);
    const { uri, clientId } = parseFlagOptions(extra, 'watch', OWN_FLAGS, onError);
    return {
       serverCommand,
       serverArgs,
       cwd,
       logLevel,
+      logFile,
+      logFileLevel,
       uri: assertRequired(uri, '--uri', 'watch', onError),
       clientId
    };

package/src/commands/watch.ts

@@ -7,14 +7,14 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { LogThreshold, TransferElement } from '@hydranium/protocol';
+import type { TransferElement } from '@hydranium/protocol';
 import type {
    DataClientProtocol,
    DataServerProtocol,
    TransferDocumentDeletedEvent,
    TransferDocumentUpdatedEvent
 } from '@hydranium/protocol/data';
-import { logLevelEnv } from '../log-level.js';
+import { logEnv, type LogOptions } from '../log-level.js';
 import { spawnDataServer } from '../spawn-data-server.js';
 
 /**
@@ -27,12 +27,10 @@ import { spawnDataServer } from '../spawn-data-server.js';
  * — production CLI wires SIGINT directly. `__handleForTest` bypasses
  * the spawn step for unit tests.
  */
-export interface WatchCommandOptions {
+export interface WatchCommandOptions extends LogOptions {
    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;
@@ -137,6 +135,9 @@ export async function runWatch(options: WatchCommandOptions): Promise<void> {
       onDocumentSaved(): void {
          // Persistence is out of band for the per-URI update view.
       },
+      onDocumentDirtyChanged(): void {
+         // Out of band for the per-URI update view, as persistence is.
+      },
       onDocumentDeleted(event: TransferDocumentDeletedEvent): void {
          // In band, unlike the two neighbours: this is the end of the stream
          // the view exists to show, and a consumer that never hears it waits
@@ -166,7 +167,7 @@ export async function runWatch(options: WatchCommandOptions): Promise<void> {
             command: options.serverCommand,
             args: options.serverArgs,
             cwd: options.cwd,
-            env: options.logLevel ? logLevelEnv(options.logLevel) : undefined
+            env: logEnv(options)
          },
          localClient
       );