@forgeax/engine-remote 0.1.27 → 0.1.29

package/src/cli.ts

@@ -1,333 +0,0 @@
-#!/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

@@ -1,169 +0,0 @@
-// @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`;
-}