@forgeax/engine-remote 0.1.3 → 0.1.6

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/execute.ts

@@ -9,7 +9,7 @@
 // function with `world` / `renderer` / `assets` / `rhiCapture` / `simulation` / `_import`
 // in scope. So all of these Just Work, un-wrapped:
 //   - a bare expression:            `renderer.backend`            -> auto-returned
-//   - top-level await:              `await _import('@forgeax/engine-ecs')`
+//   - top-level await:              `await _import('engine-module')`
 //   - top-level return:             `return world.inspect().entityCount`
 //   - multi-statement + return:     `const m = await _import(...); return m.x`
 // (the historical `(async () => { ... })()` IIFE form still works too — its
@@ -45,6 +45,7 @@ export type ExecuteContext = {
   readonly renderer: unknown;
   readonly assets: unknown;
   readonly rhiCapture?: unknown;
+  readonly simulation?: unknown;
   readonly profiler?: unknown;
   readonly execution?: unknown;
   readonly importModule?: (specifier: string) => Promise<unknown>;
@@ -70,6 +71,7 @@ function compile(script: string): FunctionConstructor['prototype'] {
     'renderer',
     'assets',
     'rhiCapture',
+    'simulation',
     'profiler',
     'execution',
     '_import',
@@ -113,6 +115,7 @@ export async function executeScript(script: string, ctx: ExecuteContext): Promis
       ctx.renderer,
       ctx.assets,
       ctx.rhiCapture,
+      ctx.simulation,
       ctx.profiler,
       ctx.execution,
       ctx.importModule ?? _import,

package/src/index.ts

@@ -1,12 +1,13 @@
-// @forgeax/engine-remote - inspector P0 server + eval core.
+// @forgeax/engine-remote - inspector P0 server + CLI dual-exit package.
 //
 // Single entry facade (charter proposition 1 progressive disclosure). The
-// runtime server lives under the ./server sub-path. AI users import the shared
-// error model from this top entry:
+// runtime server lives under the ./server sub-path; the standalone CLI binary
+// ships via `bin.forgeax` -> dist/cli.mjs. AI users import the shared error
+// model from this top entry:
 //
 //   import { RemoteError, type RemoteErrorCode } from '@forgeax/engine-remote';
 //
-// The error model SSOT (5-member closed RemoteErrorCode union) lives in
+// The error model SSOT (4-member closed RemoteErrorCode union) lives in
 // src/errors.ts and is also exposed via the ./errors sub-path for callers that
 // want type-only imports without pulling the runtime surface (D-P4 bundle
 // isolation + AGENTS.md "Inspector / Console" evolution contract minor

package/src/introspect.ts

@@ -15,6 +15,8 @@ export interface RemoteRootValues {
   readonly rhiCapture?: unknown;
   readonly profiler?: unknown;
   readonly execution?: unknown;
+  /** Read-only World-owned simulation summary; no restore/replay operation. */
+  readonly simulation?: unknown;
   readonly introspection?: readonly ComponentIntrospectionDescriptor[];
 }
 
@@ -25,11 +27,8 @@ type RootProjection = {
   readonly capability?: string;
   readonly phaseCatalog?: unknown;
   readonly operations?: {
-    readonly startCapture?: string;
-    readonly latestCapture?: string;
-    readonly load?: string;
-    readonly snapshot?: string;
-    readonly subscribe?: string;
+    readonly startCapture: string;
+    readonly latestCapture: string;
   };
 };
 
@@ -80,20 +79,16 @@ function projectRoot(name: string, value: unknown): RootProjection {
       type: 'ExecutionReportProvider',
       description: 'The host execution report provider for tier, health, performance, and fault.',
     },
+    simulation: {
+      type: 'SimulationInspection',
+      description:
+        'A read-only World-owned simulation record, participant, trace, and report summary.',
+    },
   };
   const descriptor = descriptions[name] ?? { type: 'unknown', description: 'A live eval root.' };
   return {
     available: true,
     ...descriptor,
-    ...(name === 'assets'
-      ? {
-          operations: {
-            load: 'assets.load(guid, expectedKind)',
-            snapshot: 'assets.snapshot()',
-            subscribe: 'assets.subscribe(listener)',
-          },
-        }
-      : {}),
     ...(name === 'profiler'
       ? {
           capability: 'cpu-profile-v1',
@@ -190,7 +185,7 @@ export function buildIntrospectDoc(host: string, port: number, roots: RemoteRoot
       title: '@forgeax/engine-remote remote eval',
       version: '0.0.0',
       description:
-        'Remote eval server. Methods: eval / introspect. Errors map to JSON-RPC -32001..-32005.',
+        'Remote eval server. Methods: eval / introspect. Errors map to JSON-RPC -32001..-32006.',
     },
     servers: [{ name: 'in-process', url: `ws://${host}:${port}/inspector` }],
     methods: [