ohzi-core 13.2.2 → 14.0.0

package/src/dev_bridge/CommandDispatcher.ts

@@ -0,0 +1,114 @@
+import type { Command, Reply } from './protocol';
+
+// `unknown` already absorbs Promise<unknown>; run() normalises both via Promise.resolve.
+export type CommandHandler = (args: Record<string, unknown>) => unknown;
+export type HandlerTiming = 'immediate' | 'frame_end';
+
+interface Registration
+{
+  timing: HandlerTiming;
+  handler: CommandHandler;
+}
+
+interface QueuedCommand
+{
+  id: string;
+  args: Record<string, unknown>;
+  handler: CommandHandler;
+}
+
+class CommandDispatcher
+{
+  handlers: Record<string, Registration>;
+  queue: QueuedCommand[];
+
+  private reply: (reply: Reply) => void;
+
+  constructor(reply: (reply: Reply) => void)
+  {
+    this.reply = reply;
+    this.handlers = {};
+    this.queue = [];
+  }
+
+  register(cmd: string, timing: HandlerTiming, handler: CommandHandler)
+  {
+    this.handlers[cmd] = { timing, handler };
+  }
+
+  handle(command: Command)
+  {
+    const registration = this.handlers[command.cmd];
+    const args = command.args === undefined ? {} : command.args;
+
+    if (registration === undefined)
+    {
+      this.reply({
+        id: command.id,
+        ok: false,
+        error: { code: 'unknown_command', message: `Unknown command '${command.cmd}'` }
+      });
+
+      return;
+    }
+
+    if (registration.timing === 'frame_end')
+    {
+      this.queue.push({ id: command.id, args, handler: registration.handler });
+      return;
+    }
+
+    this.run(command.id, args, registration.handler);
+  }
+
+  // Called from MainApplication.on_frame_end() so rendering and mutation
+  // never happen part-way through a frame.
+  drain()
+  {
+    const queued = this.queue;
+    this.queue = [];
+
+    for (const command of queued)
+    {
+      this.run(command.id, command.args, command.handler);
+    }
+  }
+
+  private run(id: string, args: Record<string, unknown>, handler: CommandHandler)
+  {
+    try
+    {
+      Promise.resolve(handler(args))
+        .then((result) => this.reply({ id, ok: true, result }))
+        .catch((error) => this.reply({ id, ok: false, error: this.to_error(error) }));
+    }
+    catch (error)
+    {
+      this.reply({ id, ok: false, error: this.to_error(error) });
+    }
+  }
+
+  private to_error(error: unknown): { code: string; message: string }
+  {
+    const code = (error as { code?: string })?.code;
+    const message = (error as { message?: string })?.message;
+
+    return {
+      code: code === undefined ? 'handler_failed' : code,
+      message: typeof message === 'string' ? message : this.describe(error)
+    };
+  }
+
+  // Avoids '[object Object]' reaching the developer for a thrown non-Error.
+  private describe(error: unknown): string
+  {
+    if (typeof error === 'string')
+    {
+      return error;
+    }
+
+    return `Handler failed with a non-Error value of type ${typeof error}`;
+  }
+}
+
+export { CommandDispatcher };

package/src/dev_bridge/ConsoleBuffer.ts

@@ -0,0 +1,286 @@
+const DEFAULT_CAPACITY = 200;
+const MAX_MESSAGE_LENGTH = 2000;
+
+export type ConsoleLevel = 'log' | 'info' | 'warn' | 'error';
+
+const LEVELS: ConsoleLevel[] = ['log', 'info', 'warn', 'error'];
+
+export interface ConsoleEntry
+{
+  seq: number;
+  level: ConsoleLevel;
+  message: string;
+  at: number;
+}
+
+export interface ConsoleLike
+{
+  log: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+}
+
+export interface ErrorSource
+{
+  addEventListener(type: string, listener: (event: unknown) => void): void;
+  removeEventListener(type: string, listener: (event: unknown) => void): void;
+}
+
+// Read options arrive off the dev-bridge wire and are therefore untrusted.
+export interface ConsoleReadOptions
+{
+  level?: unknown;
+  limit?: unknown;
+  since?: unknown;
+}
+
+export interface ConsoleReadResult
+{
+  entries: ConsoleEntry[];
+  dropped: number;
+  total: number;
+  capacity: number;
+}
+
+// A bounded log of console output and uncaught failures, so the bridge can
+// report what a screenshot cannot show. Injected console and error source keep
+// this testable outside a browser.
+class ConsoleBuffer
+{
+  private capacity: number;
+  private entries: ConsoleEntry[];
+  private seq: number;
+  private dropped: number;
+  private clock: () => number;
+
+  private target: ConsoleLike | null;
+  private source: ErrorSource | null;
+  private originals: Partial<Record<ConsoleLevel, (...args: unknown[]) => void>>;
+  private on_error: ((event: unknown) => void) | null;
+  private on_rejection: ((event: unknown) => void) | null;
+
+  constructor(capacity: number = DEFAULT_CAPACITY, clock: () => number = () => Date.now())
+  {
+    this.capacity = capacity > 0 ? Math.floor(capacity) : DEFAULT_CAPACITY;
+    this.entries = [];
+    this.seq = 0;
+    this.dropped = 0;
+    this.clock = clock;
+    this.target = null;
+    this.source = null;
+    this.originals = {};
+    this.on_error = null;
+    this.on_rejection = null;
+  }
+
+  install(target: ConsoleLike, source?: ErrorSource)
+  {
+    this.dispose();
+    this.target = target;
+
+    for (const level of LEVELS)
+    {
+      // Explicitly typed: indexing with a union then calling .bind() widens to
+      // any, which the lint rules reject.
+      const original: (...args: unknown[]) => void = target[level];
+      this.originals[level] = original;
+
+      target[level] = (...args: unknown[]) =>
+      {
+        this.push(level, this.format(args));
+        original.apply(target, args);
+      };
+    }
+
+    if (source !== undefined)
+    {
+      this.source = source;
+
+      this.on_error = (event) => this.push('error', this.event_message(event));
+      this.on_rejection = (event) => this.push('error', `Unhandled rejection: ${this.event_reason(event)}`);
+
+      source.addEventListener('error', this.on_error);
+      source.addEventListener('unhandledrejection', this.on_rejection);
+    }
+  }
+
+  dispose()
+  {
+    const target = this.target;
+
+    if (target !== null)
+    {
+      for (const level of LEVELS)
+      {
+        const original = this.originals[level];
+
+        if (original !== undefined)
+        {
+          target[level] = original;
+        }
+      }
+    }
+
+    const source = this.source;
+
+    if (source !== null)
+    {
+      if (this.on_error !== null)
+      {
+        source.removeEventListener('error', this.on_error);
+      }
+
+      if (this.on_rejection !== null)
+      {
+        source.removeEventListener('unhandledrejection', this.on_rejection);
+      }
+    }
+
+    this.originals = {};
+    this.target = null;
+    this.source = null;
+    this.on_error = null;
+    this.on_rejection = null;
+  }
+
+  read(options: ConsoleReadOptions): ConsoleReadResult
+  {
+    const level = typeof options.level === 'string' ? options.level : null;
+    const since = typeof options.since === 'number' ? options.since : 0;
+    const limit = typeof options.limit === 'number' && options.limit > 0 ? Math.floor(options.limit) : 0;
+
+    let entries = this.entries.filter((entry) => entry.seq > since);
+
+    if (level !== null)
+    {
+      entries = entries.filter((entry) => entry.level === level);
+    }
+
+    if (limit > 0 && entries.length > limit)
+    {
+      entries = entries.slice(entries.length - limit);
+    }
+
+    return { entries, dropped: this.dropped, total: this.seq, capacity: this.capacity };
+  }
+
+  private push(level: ConsoleLevel, message: string)
+  {
+    this.seq++;
+    this.entries.push({ seq: this.seq, level, message, at: this.clock() });
+
+    while (this.entries.length > this.capacity)
+    {
+      this.entries.shift();
+      this.dropped++;
+    }
+  }
+
+  private format(args: unknown[]): string
+  {
+    const message = args.map((arg) => this.describe(arg)).join(' ');
+
+    if (message.length <= MAX_MESSAGE_LENGTH)
+    {
+      return message;
+    }
+
+    const overflow = message.length - MAX_MESSAGE_LENGTH;
+
+    return `${message.slice(0, MAX_MESSAGE_LENGTH)} ... [truncated ${overflow} chars]`;
+  }
+
+  // Deliberately exhaustive: a log line rendered as '[object Object]' is worse
+  // than no log line at all.
+  private describe(value: unknown): string
+  {
+    if (typeof value === 'string')
+    {
+      return value;
+    }
+
+    if (value === null)
+    {
+      return 'null';
+    }
+
+    if (value === undefined)
+    {
+      return 'undefined';
+    }
+
+    if (typeof value === 'number' || typeof value === 'boolean')
+    {
+      return String(value);
+    }
+
+    if (typeof value === 'function')
+    {
+      return '[function]';
+    }
+
+    if (typeof value === 'symbol')
+    {
+      return '[symbol]';
+    }
+
+    if (typeof value === 'bigint')
+    {
+      return `${value.toString()}n`;
+    }
+
+    if (value instanceof Error)
+    {
+      return `${value.name}: ${value.message}`;
+    }
+
+    try
+    {
+      const json = JSON.stringify(value);
+
+      return json === undefined ? '[unserialisable]' : json;
+    }
+    catch
+    {
+      return '[unserialisable]';
+    }
+  }
+
+  private event_message(event: unknown): string
+  {
+    if (typeof event === 'object' && event !== null)
+    {
+      const record = event as Record<string, unknown>;
+
+      if (typeof record.message === 'string')
+      {
+        return record.message;
+      }
+
+      if (record.error !== undefined)
+      {
+        return this.describe(record.error);
+      }
+    }
+
+    return this.describe(event);
+  }
+
+  private event_reason(event: unknown): string
+  {
+    if (typeof event === 'object' && event !== null)
+    {
+      const record = event as Record<string, unknown>;
+
+      if (record.reason !== undefined)
+      {
+        return this.describe(record.reason);
+      }
+    }
+
+    return this.describe(event);
+  }
+}
+
+export { ConsoleBuffer };

package/src/dev_bridge/DevBridge.ts

@@ -0,0 +1,195 @@
+import type { CommandHandler, HandlerTiming } from './CommandDispatcher';
+import { CommandDispatcher } from './CommandDispatcher';
+import type { AppInfo, Command, Reply } from './protocol';
+import { PROTOCOL_VERSION } from './protocol';
+
+const RETRY_DELAY_MS = 2000;
+
+interface DevBridgeOptions
+{
+  port: number;
+  app_info: () => AppInfo;
+}
+
+class DevBridge
+{
+  dispatcher: CommandDispatcher;
+
+  private socket: WebSocket;
+  private options: DevBridgeOptions;
+  private retry_timer: number;
+  private disposed: boolean;
+
+  constructor()
+  {
+    this.socket = null;
+    this.options = null;
+    this.retry_timer = 0;
+    this.disposed = false;
+    this.dispatcher = new CommandDispatcher((reply) => this.send_reply(reply));
+  }
+
+  init(options: DevBridgeOptions)
+  {
+    this.options = options;
+    this.disposed = false;
+    this.connect();
+  }
+
+  register(cmd: string, timing: HandlerTiming, handler: CommandHandler)
+  {
+    this.dispatcher.register(cmd, timing, handler);
+  }
+
+  // Called from the application's on_frame_end so queued commands run at a
+  // safe frame boundary instead of part-way through a frame.
+  on_frame_end()
+  {
+    this.dispatcher.drain();
+  }
+
+  dispose()
+  {
+    this.disposed = true;
+    window.clearTimeout(this.retry_timer);
+
+    if (this.socket !== null)
+    {
+      this.socket.onclose = null;
+      this.socket.close();
+      this.socket = null;
+    }
+  }
+
+  private connect()
+  {
+    const options = this.options;
+
+    if (this.disposed || options === null)
+    {
+      return;
+    }
+
+    const socket = new WebSocket(`ws://127.0.0.1:${options.port}`);
+    this.socket = socket;
+
+    socket.onopen = () =>
+    {
+      socket.send(JSON.stringify({
+        event: 'hello',
+        protocol: PROTOCOL_VERSION,
+        app: options.app_info()
+      }));
+    };
+
+    socket.onmessage = (message) => this.on_message(message);
+
+    socket.onclose = () =>
+    {
+      if (this.socket === socket)
+      {
+        this.socket = null;
+      }
+
+      this.schedule_retry();
+    };
+
+    // A closed host raises both error and close. Retry is driven by close only.
+    socket.onerror = () => {};
+  }
+
+  private on_message(message: { data: unknown })
+  {
+    const raw = message.data;
+
+    if (typeof raw !== 'string')
+    {
+      return;
+    }
+
+    const frame = this.parse_frame(raw);
+
+    if (frame === null)
+    {
+      return;
+    }
+
+    if (frame.event === 'welcome')
+    {
+      console.info('[ohzi-mcp] bridge connected');
+      return;
+    }
+
+    if (frame.event === 'refused')
+    {
+      const reason = this.as_text(frame.reason);
+      const server_protocol = this.as_text(frame.server_protocol);
+
+      console.warn(`[ohzi-mcp] bridge refused: ${reason} (server protocol ${server_protocol}, this app speaks ${PROTOCOL_VERSION})`);
+      return;
+    }
+
+    if (typeof frame.id === 'string' && typeof frame.cmd === 'string')
+    {
+      this.dispatcher.handle(frame as unknown as Command);
+    }
+  }
+
+  private parse_frame(raw: string): Record<string, unknown> | null
+  {
+    try
+    {
+      const value: unknown = JSON.parse(raw);
+
+      if (typeof value !== 'object' || value === null)
+      {
+        return null;
+      }
+
+      return value as Record<string, unknown>;
+    }
+    catch
+    {
+      return null;
+    }
+  }
+
+  // Never let an object reach a template literal as '[object Object]'.
+  private as_text(value: unknown): string
+  {
+    if (typeof value === 'string')
+    {
+      return value;
+    }
+
+    if (typeof value === 'number' || typeof value === 'boolean')
+    {
+      return String(value);
+    }
+
+    return '(unknown)';
+  }
+
+  private send_reply(reply: Reply)
+  {
+    if (this.socket === null || this.socket.readyState !== WebSocket.OPEN)
+    {
+      return;
+    }
+
+    this.socket.send(JSON.stringify(reply));
+  }
+
+  private schedule_retry()
+  {
+    if (this.disposed)
+    {
+      return;
+    }
+
+    window.clearTimeout(this.retry_timer);
+    this.retry_timer = window.setTimeout(() => this.connect(), RETRY_DELAY_MS);
+  }
+}
+
+export { DevBridge };