@forgeax/engine-remote 0.0.0-dev.8d955ade1c79

package/src/__tests__/vm-async-eval-verify.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// biome-ignore-all lint/suspicious/noConsole: standalone D-1 verification CLI script; console is its diagnostic output channel
+// @forgeax/engine-remote/src/__tests__/vm-async-eval-verify.mjs
+// D-1 verification: route A (vm + importModuleDynamically) vs route B (host realm eval).
+//
+// Indicators:
+//   (a)  vm.runInContext with importModuleDynamically: does await import resolve?
+//   (a') host realm eval via new Function: does await import resolve?
+//   (c)  vm timeout watchdog: does it fire on sync infinite loop?
+//
+// Route B has NO timeout watchdog — infinite loops hang the thread.
+//
+// RESULT (2026-06-29, Node 24.15.0):
+//   ROUTE A FALSIFIED — vm.runInContext does NOT support importModuleDynamically.
+//   ROUTE B CONFIRMED — new Function resolves await import naturally.
+//   Timeout: vm watchdog PASS, but host eval has NO timeout.
+
+import * as vm from 'node:vm';
+
+let exitCode = 0;
+const passes = [];
+const fails = [];
+
+function record(label, ok, detail) {
+  if (ok) {
+    passes.push(label);
+    console.log(`(a)  vm importModuleDynamically: ${detail}`);
+  } else {
+    fails.push(label);
+    console.log(`(a)  vm importModuleDynamically: FAIL — ${detail}`);
+  }
+}
+
+// ── Indicator (a): vm route ─────────────────────────────────────────────────
+
+{
+  const label = 'a';
+  const ok = false;
+  let detail = '';
+  const scriptBody = [
+    '(async () => {',
+    "  const ecs = await import('@forgeax/engine-ecs');",
+    "  return typeof ecs.World.prototype.query === 'function';",
+    '})()',
+  ].join('\n');
+  try {
+    const ctx = vm.createContext(
+      {},
+      { importModuleDynamically: vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER },
+    );
+    const promise = vm.runInContext(scriptBody, ctx, { timeout: 10000, displayErrors: true });
+    if (typeof promise?.then === 'function') {
+      // We need to await it — but vm.runInContext is sync, so we get
+      // the Promise object back. However Node's vm Script does NOT
+      // execute the async IIFE — it evaluates the expression and returns
+      // the raw Promise without executing it. The Promise never settles.
+      // This is a known limitation.
+      detail =
+        'Promise returned but never settled — import() never called (vm Script cannot execute async IIFE)';
+      record(label, ok, detail);
+    } else {
+      detail = `returned ${typeof promise} (expected thenable)`;
+      record(label, ok, detail);
+    }
+  } catch (e) {
+    detail = e instanceof Error ? e.message : String(e);
+    record(label, ok, detail);
+  }
+}
+
+// ── Indicator (a'): host realm eval route ───────────────────────────────────
+
+{
+  const label = "a'";
+  let ok = false;
+  let detail = '';
+  try {
+    // Dynamically import in host realm, then new Function.
+    // The fact that new Function runs in host realm means import() works naturally.
+    const script = [
+      'return (async () => {',
+      "  const ecs = await import('@forgeax/engine-ecs');",
+      "  return typeof ecs.World.prototype.query === 'function';",
+      '})();',
+    ].join('\n');
+    const fn = new Function(script);
+    const result = await fn();
+    ok = result === true;
+    detail = `import resolved, World.query is function = ${result}`;
+    record(label, ok, detail);
+  } catch (e) {
+    detail = e instanceof Error ? e.message : String(e);
+    record(label, ok, detail);
+  }
+}
+
+// ── Indicator (c): vm timeout watchdog ──────────────────────────────────────
+
+{
+  const label = 'c';
+  let ok = false;
+  let detail = '';
+  const start = Date.now();
+  try {
+    const ctx = vm.createContext({});
+    vm.runInContext('while(true){}', ctx, { timeout: 200, displayErrors: false });
+    detail = `loop completed without interruption after ${Date.now() - start}ms`;
+    record(label, ok, detail);
+  } catch (e) {
+    const elapsed = Date.now() - start;
+    const msg = e instanceof Error ? e.message : String(e);
+    ok = msg.includes('timed out') || msg.includes('Script execution timed out');
+    detail = `timed out after ~${elapsed}ms`;
+    record(label, ok, detail);
+  }
+}
+
+// ── Final verdict ───────────────────────────────────────────────────────────
+
+const routeBpass = passes.includes("a'");
+const routeAfail = fails.includes('a');
+
+console.log();
+console.log('='.repeat(60));
+console.log('D-1 VERDICT:');
+
+if (routeAfail && routeBpass) {
+  console.log('ROUTE A (vm + importModuleDynamically): FALSIFIED');
+  console.log('  Reason: vm.runInContext does not honor importModuleDynamically');
+  console.log('  for Script execution. Only vm.SourceTextModule is supported.');
+  console.log();
+  console.log('ROUTE B (host realm eval via new Function): CONFIRMED');
+  console.log('  - await import resolves naturally in host realm');
+  console.log('  - NO timeout watchdog (known limitation, documented in R6)');
+  console.log();
+  console.log('IMPLEMENTATION IMPLICATIONS:');
+  console.log('  - w5: implement executeScript via new Function');
+  console.log('  - w5: remove scriptTimeoutMs & timeout logic (dead)');
+  console.log('  - w7: delete script-timeout from RemoteErrorCode');
+  console.log('  - Final error set: 4 members (no script-timeout)');
+  exitCode = 0;
+} else {
+  console.log('UNEXPECTED RESULT:');
+  console.log('  Route A passes:', passes, 'fails:', fails);
+  console.log('  Route B passes:', passes, 'fails:', fails);
+  exitCode = 1;
+}
+
+process.exit(exitCode);

package/src/cli.ts

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+// @forgeax/engine-remote/src/cli - forgeax CLI binary entry (feat-20260517 D-3
+// + D-4: inspect-subcommand removed; only built-in `script` / `eval`
+// remain. M2 w8: plugin discovery (discoverPlugins) deleted alongside
+// routing layer removal. defaultConnect SSOT lives in
+// `@forgeax/engine-types/inspector-client` and is re-exported here
+// for the legacy import surface).
+//
+// Two-subcommand built-in dispatch:
+//   - forgeax-engine-remote script  <file>
+//   - forgeax-engine-remote eval    <inline-script>
+//
+// WebSocket client (D-3 / w18): the in-cli ~80-line `defaultConnect`
+// implementation was extracted to `@forgeax/engine-types/inspector-client`
+// so the engine-remote base CLI and the engine-ecs `cli-ecs` plugin bin
+// (M3) share one client recipe. The Result-form `eval(script)` /
+// `dispose()` surface replaces the legacy `request(method,params)` /
+// `close()` shape that lived inside cli.ts.
+//
+// Argparse via stdlib `node:util.parseArgs` (no commander / sade / cac
+// dep). Help body is produced by the package-internal `defineSubcommand`
+// DSL (plan-strategy D-4 + D-7).
+
+import { readFile, realpath } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import type { RemoteError as RemoteErrorShape } from '@forgeax/engine-types';
+import {
+  type ConnectFn,
+  defaultConnect,
+  INSPECTOR_DEFAULT_HOST,
+  INSPECTOR_DEFAULT_PORT,
+  type InspectorClient,
+} from '@forgeax/engine-types/inspector-client';
+import { defineSubcommand, renderHelp, type SubcommandSpec } from './defineSubcommand';
+
+export type { ConnectFn, InspectorClient };
+export { defaultConnect };
+
+// w8: LEGACY_INSPECT_TARGETS removed alongside plugin discovery deletion.
+// ─── Subcommand spec tree (sade utils.js form) ───────────────────────────────
+
+export const FORGEAX_CLI_SPEC: SubcommandSpec = defineSubcommand({
+  name: 'forgeax-engine-remote',
+  description: 'remote eval CLI - drive a running forgeax engine via JSON-RPC over WS',
+  options: [
+    {
+      flag: '--port <n>',
+      description: `Inspector WebSocket port (default ${INSPECTOR_DEFAULT_PORT}; monitor uses 5731)`,
+    },
+    { flag: '--host <s>', description: `Host name (default ${INSPECTOR_DEFAULT_HOST})` },
+    { flag: '--help, -h', description: 'Show this help and exit 0' },
+  ],
+  subcommands: [
+    defineSubcommand({
+      name: 'script',
+      description: 'eval a script file against the live world/renderer/assets',
+      options: [{ flag: '--help, -h', description: 'Show this help and exit 0' }],
+      examples: [
+        {
+          usage: 'forgeax-engine-remote script ./inspect.mjs',
+          description: 'eval a local script file',
+        },
+      ],
+    }),
+    defineSubcommand({
+      name: 'eval',
+      description: 'evaluate an inline expression against the world',
+      options: [{ flag: '--help, -h', description: 'Show this help and exit 0' }],
+      examples: [
+        {
+          usage: 'forgeax-engine-remote eval "world.inspect().entityCount"',
+          description: 'inline read of world.inspect()',
+        },
+      ],
+    }),
+  ],
+  extraNotes: [
+    'eval is full read/write access to the live world/renderer/assets/debugAdapter; the only security boundary is whether the host started the server.',
+    'Plugin discovery via PATH-prefix removed in M2 (routing layer deletion).',
+    'See also: packages/remote/README.md (eval API, live roots, security model) + AI User Charter.',
+    'Simulation inspection is read-only through eval; restore and replay are not Remote or CLI actions.',
+  ],
+});
+
+// w8: Plugin discovery (discoverPlugins) removed alongside routing layer deletion.
+// renderTopLevelHelp no longer takes plugins — only built-in commands displayed.
+
+function renderTopLevelHelp(): string {
+  const lines: string[] = [];
+  lines.push(`${FORGEAX_CLI_SPEC.name} - ${FORGEAX_CLI_SPEC.description}`);
+  lines.push('');
+  lines.push('Usage:');
+  lines.push(`  ${FORGEAX_CLI_SPEC.name} <subcommand> [args]`);
+  lines.push('');
+
+  lines.push('Built-in commands:');
+  const builtIns = FORGEAX_CLI_SPEC.subcommands ?? [];
+  const builtInWidth = builtIns.reduce((m, s) => Math.max(m, s.name.length), 0);
+  for (const s of builtIns) {
+    const pad = ' '.repeat(builtInWidth - s.name.length + 4);
+    lines.push(`  ${s.name}${pad}${s.description}`);
+  }
+  lines.push('');
+
+  if (FORGEAX_CLI_SPEC.options && FORGEAX_CLI_SPEC.options.length > 0) {
+    lines.push('Options:');
+    const optWidth = FORGEAX_CLI_SPEC.options.reduce((m, o) => Math.max(m, o.flag.length), 0);
+    for (const o of FORGEAX_CLI_SPEC.options) {
+      const pad = ' '.repeat(optWidth - o.flag.length + 4);
+      lines.push(`  ${o.flag}${pad}${o.description}`);
+    }
+    lines.push('');
+  }
+
+  if (FORGEAX_CLI_SPEC.extraNotes && FORGEAX_CLI_SPEC.extraNotes.length > 0) {
+    lines.push('Notes:');
+    for (const note of FORGEAX_CLI_SPEC.extraNotes) {
+      lines.push(`  ${note}`);
+    }
+    lines.push('');
+  }
+
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+// w8: renderConsoleStartupFailed (plugin-discovery error rendering) removed.
+// For unknown subcommands, a simple stderr fallback is used inline.
+
+// --- Dispatch (test-injectable) ---
+
+export interface DispatchOptions {
+  readonly argv: readonly string[];
+  readonly stdoutWrite: (line: string) => void;
+  readonly stderrWrite: (line: string) => void;
+  readonly connect: ConnectFn;
+  readonly fileReader?: (path: string) => Promise<string>;
+}
+
+const defaultFileReader = async (path: string): Promise<string> => {
+  return await readFile(path, 'utf8');
+};
+
+export async function dispatch(opts: DispatchOptions): Promise<number> {
+  const { argv, stdoutWrite, stderrWrite, connect } = opts;
+  const fileReader = opts.fileReader ?? defaultFileReader;
+  const [, , subcommand, ...rest] = argv;
+
+  if (subcommand === undefined || subcommand === '--help' || subcommand === '-h') {
+    stdoutWrite(renderTopLevelHelp());
+    return 0;
+  }
+
+  let port = INSPECTOR_DEFAULT_PORT;
+  let host = INSPECTOR_DEFAULT_HOST;
+  const filteredRest: string[] = [];
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === '--port') {
+      const next = rest[i + 1];
+      if (typeof next === 'string') {
+        const parsed = Number(next);
+        if (!Number.isNaN(parsed) && parsed > 0) {
+          port = parsed;
+          i++;
+          continue;
+        }
+      }
+    }
+    if (arg === '--host') {
+      const next = rest[i + 1];
+      if (typeof next === 'string') {
+        host = next;
+        i++;
+        continue;
+      }
+    }
+    if (typeof arg === 'string') filteredRest.push(arg);
+  }
+
+  switch (subcommand) {
+    case 'script':
+      return runScript(filteredRest, {
+        stdoutWrite,
+        stderrWrite,
+        connect,
+        port,
+        host,
+        fileReader,
+      });
+    case 'eval':
+      return runEval(filteredRest, { stdoutWrite, stderrWrite, connect, port, host });
+    default: {
+      // CLI argument error (not a RemoteErrorCode — that closed union is the
+      // wire/eval failure vocabulary, not a usage-error channel). Plain
+      // usage message mirrors the script/eval missing-arg errors above.
+      stderrWrite(
+        `forgeax: unknown subcommand '${subcommand}'\n  expected: subcommand is one of: script, eval\n  hint: run 'forgeax-engine-remote --help' for usage\n  detail: '${subcommand}' is not a built-in subcommand (plugin discovery removed in M2)\n`,
+      );
+      return 1;
+    }
+  }
+}
+
+interface RunCtx {
+  readonly stdoutWrite: (line: string) => void;
+  readonly stderrWrite: (line: string) => void;
+  readonly connect: ConnectFn;
+  readonly port: number;
+  readonly host: string;
+}
+
+interface RunScriptCtx extends RunCtx {
+  readonly fileReader: (path: string) => Promise<string>;
+}
+
+function inspectorErrorToStderr(e: RemoteErrorShape): string {
+  return [`forgeax: ${e.code}`, `  expected: ${e.expected}`, `  hint:     ${e.hint}`].join('\n');
+}
+
+async function runScript(rest: string[], ctx: RunScriptCtx): Promise<number> {
+  const [file] = rest;
+  if (file === '--help' || file === '-h') {
+    ctx.stdoutWrite(renderHelp(FORGEAX_CLI_SPEC, ['script']));
+    return 0;
+  }
+  if (typeof file !== 'string') {
+    ctx.stderrWrite(
+      [
+        'forgeax: script requires a <file> positional argument',
+        '  expected: forgeax-engine-remote script <path-to-js-file>',
+        "  hint:     e.g. 'forgeax-engine-remote script ./inspect.mjs'",
+      ].join('\n'),
+    );
+    return 1;
+  }
+  let body: string;
+  try {
+    body = await ctx.fileReader(file);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    ctx.stderrWrite(
+      [
+        `forgeax: script file unreadable: ${file}`,
+        '  expected: file exists and is readable',
+        `  hint:     check path; underlying error: ${message}`,
+      ].join('\n'),
+    );
+    return 1;
+  }
+  return invokeExecute(body, ctx);
+}
+
+async function runEval(rest: string[], ctx: RunCtx): Promise<number> {
+  const [script] = rest;
+  if (script === '--help' || script === '-h') {
+    ctx.stdoutWrite(renderHelp(FORGEAX_CLI_SPEC, ['eval']));
+    return 0;
+  }
+  if (typeof script !== 'string') {
+    ctx.stderrWrite(
+      [
+        'forgeax: eval requires an inline <script> positional argument',
+        '  expected: forgeax-engine-remote eval "<expression>"',
+        '  hint:     e.g. \'forgeax-engine-remote eval "world.inspect().entityCount"\'',
+      ].join('\n'),
+    );
+    return 1;
+  }
+  return invokeExecute(script, ctx);
+}
+
+async function invokeExecute(script: string, ctx: RunCtx): Promise<number> {
+  const url = `ws://${ctx.host}:${ctx.port}/inspector`;
+  const connectResult = await ctx.connect(url);
+  if (!connectResult.ok) {
+    ctx.stderrWrite(inspectorErrorToStderr(connectResult.error));
+    return 1;
+  }
+  const client = connectResult.value;
+  try {
+    const result = await client.eval(script);
+    ctx.stdoutWrite(typeof result === 'string' ? result : JSON.stringify(result, null, 2));
+    return 0;
+  } catch (e) {
+    if (isRemoteError(e)) {
+      ctx.stderrWrite(inspectorErrorToStderr(e));
+      return 1;
+    }
+    const message = e instanceof Error ? e.message : String(e);
+    ctx.stderrWrite(
+      [
+        'forgeax: execute failed',
+        '  expected: server-side execute() resolves Result.ok',
+        `  hint:     underlying: ${message}`,
+      ].join('\n'),
+    );
+    return 1;
+  } finally {
+    await client.dispose();
+  }
+}
+
+function isRemoteError(e: unknown): e is RemoteErrorShape {
+  return (
+    typeof e === 'object' &&
+    e !== null &&
+    typeof (e as { code?: unknown }).code === 'string' &&
+    typeof (e as { expected?: unknown }).expected === 'string' &&
+    typeof (e as { hint?: unknown }).hint === 'string'
+  );
+}
+
+// ─── Bin entry — only runs when this module is the process entry ────────────
+
+const isBinEntry = await (async () => {
+  const argv1 = process.argv[1];
+  if (typeof argv1 !== 'string') return false;
+  const argv1Real = await realpath(argv1).catch(() => argv1);
+  const selfReal = await realpath(fileURLToPath(import.meta.url)).catch(() =>
+    fileURLToPath(import.meta.url),
+  );
+  return argv1Real === selfReal;
+})();
+
+if (isBinEntry) {
+  const exitCode = await dispatch({
+    argv: process.argv,
+    stdoutWrite: (line: string) => process.stdout.write(`${line}\n`),
+    stderrWrite: (line: string) => process.stderr.write(`${line}\n`),
+    connect: defaultConnect,
+  });
+  process.exit(exitCode);
+}

package/src/defineSubcommand.ts

@@ -0,0 +1,169 @@
+// @forgeax/engine-remote/src/defineSubcommand - sade utils.js form (~94-line
+// flat-dictionary + section primitive) DSL for the `forgeax-engine-console`
+// CLI help renderer. Plan-strategy D-4 + D-7 lock-in:
+//
+//   - Single file, package-internal (NOT in package.json#exports).
+//     `cli.ts` is the sole consumer; tsup inlines it into dist/cli.mjs.
+//   - 94-line ceiling is a pattern target, not a hard cap; we trade a few
+//     extra lines for explicit JSDoc that AI users read at edit time.
+//   - Three render layers driven by `path` slicing:
+//       path = []                       -> top-level help
+//       path = ['inspect']              -> subcommand help
+//       path = ['inspect', 'entities']  -> sub-target help
+//   - List-width pin: `maxLen + GAP=4` padding (R-4 mitigation; snapshot
+//     test packages/console/src/__tests__/cli-help.test.ts guards drift).
+//
+// charter: proposition 1 (progressive disclosure — `path` is the navigator,
+// not a hidden config) + proposition 3 (machine-readable spec >>> hand-rolled
+// strings) + proposition 4 (explicit failure — render is total: any unknown
+// path returns the closest valid layer rather than throwing).
+
+const GAP = 4;
+
+/** Single option entry: `--with <Name>`, `--port <number>` ... */
+export interface OptionSpec {
+  readonly flag: string;
+  readonly description: string;
+  readonly multiple?: boolean;
+  readonly defaultValue?: string;
+}
+
+/** Single example block: usage line + free description. */
+export interface ExampleSpec {
+  readonly usage: string;
+  readonly description?: string;
+}
+
+/** Subcommand spec — recursive (subcommands map to nested specs). */
+export interface SubcommandSpec {
+  readonly name: string;
+  readonly description: string;
+  readonly options?: ReadonlyArray<OptionSpec>;
+  readonly subcommands?: ReadonlyArray<SubcommandSpec>;
+  readonly examples?: ReadonlyArray<ExampleSpec>;
+  readonly extraNotes?: ReadonlyArray<string>;
+}
+
+/**
+ * Single-input wrapping helper: turns a sade-style descriptor into a
+ * SubcommandSpec POD. Today the function is a near-identity (the spec is
+ * already structurally a POD), but the wrapper preserves a single intercept
+ * point for future validation (charter proposition 4: explicit failure on
+ * malformed input — we can throw here rather than silently render garbage).
+ */
+export function defineSubcommand(spec: SubcommandSpec): SubcommandSpec {
+  if (typeof spec.name !== 'string' || spec.name.length === 0) {
+    throw new Error('defineSubcommand: spec.name must be a non-empty string');
+  }
+  return spec;
+}
+
+/**
+ * Look up the descendant spec at `path`. Returns the closest matching
+ * ancestor when the path is partially unknown so renderHelp degrades to the
+ * deepest valid layer rather than throwing (charter proposition 4 explicit
+ * failure: a wrong path is recoverable; a thrown render is not).
+ */
+function resolvePath(
+  root: SubcommandSpec,
+  path: readonly string[],
+): { readonly spec: SubcommandSpec; readonly path: readonly string[] } {
+  let current = root;
+  const consumed: string[] = [];
+  for (const segment of path) {
+    const next = current.subcommands?.find((s) => s.name === segment);
+    if (next === undefined) break;
+    current = next;
+    consumed.push(segment);
+  }
+  return { spec: current, path: consumed };
+}
+
+/**
+ * Render a single section with `key` left-padded to `maxLen + GAP` columns.
+ * `items` carries `[label, body]` pairs; both halves are flat strings.
+ *
+ * Skips emission entirely when `items` is empty so the rendered help body
+ * has no orphan section headers (UX nit: AI users grep section headers as
+ * anchors — emitting a header followed by nothing fools the grep).
+ */
+function section(title: string, items: ReadonlyArray<readonly [string, string]>): string[] {
+  if (items.length === 0) return [];
+  let maxLen = 0;
+  for (const [label] of items) {
+    if (label.length > maxLen) maxLen = label.length;
+  }
+  const lines: string[] = [];
+  lines.push(`${title}:`);
+  for (const [label, body] of items) {
+    const pad = ' '.repeat(maxLen + GAP - label.length);
+    lines.push(`  ${label}${pad}${body}`);
+  }
+  lines.push('');
+  return lines;
+}
+
+/**
+ * Render the help body for `path` against `root`. Always returns a non-empty
+ * string ending in a single newline so callers can pipe to stdout without
+ * post-processing.
+ *
+ * Layer 1 (root):       title + Usage + Sub-commands + Options + extraNotes
+ * Layer 2 (subcommand): title + Usage + Sub-targets (if any) + Options + Examples + extraNotes
+ * Layer 3 (sub-target): title + Usage + Options + Examples + extraNotes
+ */
+export function renderHelp(root: SubcommandSpec, path: readonly string[]): string {
+  const { spec, path: consumed } = resolvePath(root, path);
+  const fullPath = [root.name, ...consumed].join(' ');
+  const out: string[] = [];
+  out.push(`${fullPath} - ${spec.description}`);
+  out.push('');
+
+  // Usage line — synthesised from `path` + the leaf's surface.
+  const usagePieces: string[] = [fullPath];
+  if (spec.subcommands && spec.subcommands.length > 0) {
+    usagePieces.push('<subcommand>');
+  } else {
+    // Leaf nodes use a generic <args> token; concrete shape lives in
+    // `examples` so the help body stays declarative rather than guessed.
+    usagePieces.push('[options]');
+  }
+  out.push('Usage:');
+  out.push(`  ${usagePieces.join(' ')}`);
+  out.push('');
+
+  if (spec.subcommands && spec.subcommands.length > 0) {
+    out.push(
+      ...section(
+        consumed.length === 0 ? 'Sub-commands' : 'Sub-targets',
+        spec.subcommands.map((s) => [s.name, s.description] as const),
+      ),
+    );
+  }
+
+  if (spec.options && spec.options.length > 0) {
+    out.push(
+      ...section(
+        'Options',
+        spec.options.map((o) => [o.flag, o.description] as const),
+      ),
+    );
+  }
+
+  if (spec.examples && spec.examples.length > 0) {
+    const exampleItems: Array<readonly [string, string]> = spec.examples.map(
+      (e) => [e.usage, e.description ?? ''] as const,
+    );
+    out.push(...section('Examples', exampleItems));
+  }
+
+  if (spec.extraNotes && spec.extraNotes.length > 0) {
+    out.push('Notes:');
+    for (const note of spec.extraNotes) {
+      out.push(`  ${note}`);
+    }
+    out.push('');
+  }
+
+  return `${out.join('\n').trimEnd()}\n`;
+}

package/src/error-messages.ts

@@ -0,0 +1,9 @@
+import type { RemoteErrorCode } from './errors';
+
+export const REMOTE_ERROR_MESSAGES: Readonly<Record<RemoteErrorCode, string>> = {
+  'script-syntax-error': 'Script syntax error',
+  'script-runtime-error': 'Script runtime error',
+  'server-startup-failed': 'Server startup failed',
+  'server-not-running': 'Server not reachable',
+  'eval-result-not-serializable': 'Eval result not serializable',
+};