@quenty/studio-bridge 0.7.0 → 0.8.0

package/src/bridge/internal/host-protocol.test.ts

@@ -0,0 +1,415 @@
+/**
+ * Unit tests for host-protocol -- validates encode/decode round-trip
+ * for all envelope message types.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  encodeHostMessage,
+  decodeHostMessage,
+  type HostEnvelope,
+  type ListSessionsRequest,
+  type ListInstancesRequest,
+  type HostResponse,
+  type ListSessionsResponse,
+  type ListInstancesResponse,
+  type SessionEvent,
+  type HostProtocolMessage,
+} from './host-protocol.js';
+import type { SessionInfo, InstanceInfo } from '../types.js';
+
+function roundTrip(msg: HostProtocolMessage): HostProtocolMessage | null {
+  return decodeHostMessage(encodeHostMessage(msg));
+}
+
+function createSessionInfo(overrides: Partial<SessionInfo> = {}): SessionInfo {
+  return {
+    sessionId: 'session-1',
+    placeName: 'TestPlace',
+    state: 'Edit',
+    pluginVersion: '1.0.0',
+    capabilities: ['execute'],
+    connectedAt: new Date('2024-01-01'),
+    origin: 'user',
+    context: 'edit',
+    instanceId: 'inst-1',
+    placeId: 100,
+    gameId: 200,
+    ...overrides,
+  };
+}
+
+describe('host-protocol', () => {
+  describe('HostEnvelope', () => {
+    it('round-trips correctly', () => {
+      const msg: HostEnvelope = {
+        type: 'host-envelope',
+        requestId: 'req-1',
+        targetSessionId: 'session-1',
+        action: {
+          type: 'execute',
+          sessionId: 'session-1',
+          payload: { script: 'print("hi")' },
+        },
+      };
+
+      const decoded = roundTrip(msg);
+
+      expect(decoded).not.toBeNull();
+      expect(decoded!.type).toBe('host-envelope');
+      const envelope = decoded as HostEnvelope;
+      expect(envelope.requestId).toBe('req-1');
+      expect(envelope.targetSessionId).toBe('session-1');
+      expect(envelope.action.type).toBe('execute');
+    });
+  });
+
+  describe('ListSessionsRequest', () => {
+    it('round-trips correctly', () => {
+      const msg: ListSessionsRequest = {
+        type: 'list-sessions',
+        requestId: 'req-2',
+      };
+
+      const decoded = roundTrip(msg);
+
+      expect(decoded).not.toBeNull();
+      expect(decoded!.type).toBe('list-sessions');
+      expect((decoded as ListSessionsRequest).requestId).toBe('req-2');
+    });
+  });
+
+  describe('ListInstancesRequest', () => {
+    it('round-trips correctly', () => {
+      const msg: ListInstancesRequest = {
+        type: 'list-instances',
+        requestId: 'req-3',
+      };
+
+      const decoded = roundTrip(msg);
+
+      expect(decoded).not.toBeNull();
+      expect(decoded!.type).toBe('list-instances');
+      expect((decoded as ListInstancesRequest).requestId).toBe('req-3');
+    });
+  });
+
+  describe('HostResponse', () => {
+    it('round-trips correctly', () => {
+      const msg: HostResponse = {
+        type: 'host-response',
+        requestId: 'req-4',
+        result: {
+          type: 'stateResult',
+          sessionId: 'session-1',
+          requestId: 'req-4',
+          payload: {
+            state: 'Edit',
+            placeId: 100,
+            placeName: 'Test',
+            gameId: 200,
+          },
+        },
+      };
+
+      const decoded = roundTrip(msg);
+
+      expect(decoded).not.toBeNull();
+      expect(decoded!.type).toBe('host-response');
+      const response = decoded as HostResponse;
+      expect(response.requestId).toBe('req-4');
+      expect(response.result.type).toBe('stateResult');
+    });
+  });
+
+  describe('ListSessionsResponse', () => {
+    it('round-trips correctly', () => {
+      const msg: ListSessionsResponse = {
+        type: 'list-sessions-response',
+        requestId: 'req-5',
+        sessions: [createSessionInfo()],
+      };
+
+      const decoded = roundTrip(msg);
+
+      expect(decoded).not.toBeNull();
+      expect(decoded!.type).toBe('list-sessions-response');
+      const response = decoded as ListSessionsResponse;
+      expect(response.requestId).toBe('req-5');
+      expect(response.sessions).toHaveLength(1);
+      expect(response.sessions[0].sessionId).toBe('session-1');
+    });
+
+    it('handles empty session list', () => {
+      const msg: ListSessionsResponse = {
+        type: 'list-sessions-response',
+        requestId: 'req-6',
+        sessions: [],
+      };
+
+      const decoded = roundTrip(msg);
+
+      expect(decoded).not.toBeNull();
+      expect((decoded as ListSessionsResponse).sessions).toHaveLength(0);
+    });
+  });
+
+  describe('ListInstancesResponse', () => {
+    it('round-trips correctly', () => {
+      const instance: InstanceInfo = {
+        instanceId: 'inst-1',
+        placeName: 'TestPlace',
+        placeId: 100,
+        gameId: 200,
+        contexts: ['edit', 'server'],
+        origin: 'user',
+      };
+
+      const msg: ListInstancesResponse = {
+        type: 'list-instances-response',
+        requestId: 'req-7',
+        instances: [instance],
+      };
+
+      const decoded = roundTrip(msg);
+
+      expect(decoded).not.toBeNull();
+      expect(decoded!.type).toBe('list-instances-response');
+      const response = decoded as ListInstancesResponse;
+      expect(response.instances).toHaveLength(1);
+      expect(response.instances[0].instanceId).toBe('inst-1');
+    });
+  });
+
+  describe('SessionEvent', () => {
+    it('round-trips connected event', () => {
+      const msg: SessionEvent = {
+        type: 'session-event',
+        event: 'connected',
+        session: createSessionInfo(),
+        sessionId: 'session-1',
+        context: 'edit',
+        instanceId: 'inst-1',
+      };
+
+      const decoded = roundTrip(msg);
+
+      expect(decoded).not.toBeNull();
+      expect(decoded!.type).toBe('session-event');
+      const event = decoded as SessionEvent;
+      expect(event.event).toBe('connected');
+      expect(event.session).toBeDefined();
+      expect(event.sessionId).toBe('session-1');
+      expect(event.context).toBe('edit');
+      expect(event.instanceId).toBe('inst-1');
+    });
+
+    it('round-trips disconnected event (no session)', () => {
+      const msg: SessionEvent = {
+        type: 'session-event',
+        event: 'disconnected',
+        sessionId: 'session-1',
+        context: 'edit',
+        instanceId: 'inst-1',
+      };
+
+      const decoded = roundTrip(msg);
+
+      expect(decoded).not.toBeNull();
+      const event = decoded as SessionEvent;
+      expect(event.event).toBe('disconnected');
+      expect(event.session).toBeUndefined();
+    });
+
+    it('round-trips state-changed event', () => {
+      const msg: SessionEvent = {
+        type: 'session-event',
+        event: 'state-changed',
+        session: createSessionInfo({ state: 'Play' }),
+        sessionId: 'session-1',
+        context: 'edit',
+        instanceId: 'inst-1',
+      };
+
+      const decoded = roundTrip(msg);
+
+      expect(decoded).not.toBeNull();
+      expect((decoded as SessionEvent).event).toBe('state-changed');
+    });
+  });
+
+  describe('error handling', () => {
+    it('returns null for invalid JSON', () => {
+      expect(decodeHostMessage('not json')).toBeNull();
+    });
+
+    it('returns null for non-object values', () => {
+      expect(decodeHostMessage('"hello"')).toBeNull();
+      expect(decodeHostMessage('42')).toBeNull();
+      expect(decodeHostMessage('null')).toBeNull();
+    });
+
+    it('returns null for missing type', () => {
+      expect(
+        decodeHostMessage(JSON.stringify({ requestId: 'r-1' }))
+      ).toBeNull();
+    });
+
+    it('returns null for unknown type', () => {
+      expect(decodeHostMessage(JSON.stringify({ type: 'unknown' }))).toBeNull();
+    });
+
+    it('returns null for host-envelope with missing fields', () => {
+      expect(
+        decodeHostMessage(
+          JSON.stringify({
+            type: 'host-envelope',
+            requestId: 'r-1',
+            // missing targetSessionId and action
+          })
+        )
+      ).toBeNull();
+    });
+
+    it('returns null for list-sessions with missing requestId', () => {
+      expect(
+        decodeHostMessage(
+          JSON.stringify({
+            type: 'list-sessions',
+          })
+        )
+      ).toBeNull();
+    });
+
+    it('returns null for session-event with invalid event value', () => {
+      expect(
+        decodeHostMessage(
+          JSON.stringify({
+            type: 'session-event',
+            event: 'invalid',
+            sessionId: 's-1',
+            context: 'edit',
+            instanceId: 'i-1',
+          })
+        )
+      ).toBeNull();
+    });
+  });
+
+  describe('HostEnvelope action validation', () => {
+    function envelope(action: unknown): string {
+      return JSON.stringify({
+        type: 'host-envelope',
+        requestId: 'r-1',
+        targetSessionId: 's-1',
+        action,
+      });
+    }
+
+    it('returns null when action.type is missing', () => {
+      expect(
+        decodeHostMessage(
+          envelope({ sessionId: 's-1', payload: { script: 'x' } })
+        )
+      ).toBeNull();
+    });
+
+    it('returns null when action.type is unknown', () => {
+      expect(
+        decodeHostMessage(
+          envelope({
+            type: 'totally-fake',
+            sessionId: 's-1',
+            payload: {},
+          })
+        )
+      ).toBeNull();
+    });
+
+    it('returns null when execute action is missing payload.script', () => {
+      expect(
+        decodeHostMessage(
+          envelope({ type: 'execute', sessionId: 's-1', payload: {} })
+        )
+      ).toBeNull();
+    });
+
+    it('returns null when execute action has wrong script type', () => {
+      expect(
+        decodeHostMessage(
+          envelope({
+            type: 'execute',
+            sessionId: 's-1',
+            payload: { script: 42 },
+          })
+        )
+      ).toBeNull();
+    });
+
+    it('returns null when queryDataModel action is missing payload.path', () => {
+      expect(
+        decodeHostMessage(
+          envelope({
+            type: 'queryDataModel',
+            sessionId: 's-1',
+            requestId: 'a',
+            payload: {},
+          })
+        )
+      ).toBeNull();
+    });
+
+    it('returns null when error action has unknown error code', () => {
+      expect(
+        decodeHostMessage(
+          envelope({
+            type: 'error',
+            sessionId: 's-1',
+            payload: { code: 'NOT_A_REAL_CODE', message: 'oops' },
+          })
+        )
+      ).toBeNull();
+    });
+
+    it('returns null when sessionId is missing on action', () => {
+      expect(
+        decodeHostMessage(
+          envelope({ type: 'execute', payload: { script: 'x' } })
+        )
+      ).toBeNull();
+    });
+
+    it('accepts a well-formed execute action', () => {
+      const decoded = decodeHostMessage(
+        envelope({
+          type: 'execute',
+          sessionId: 's-1',
+          payload: { script: 'print("ok")' },
+        })
+      );
+      expect(decoded).not.toBeNull();
+      expect(decoded!.type).toBe('host-envelope');
+      expect((decoded as HostEnvelope).action.type).toBe('execute');
+    });
+
+    it('accepts a well-formed queryDataModel action with all fields', () => {
+      const decoded = decodeHostMessage(
+        envelope({
+          type: 'queryDataModel',
+          sessionId: 's-1',
+          requestId: 'q-1',
+          payload: {
+            path: 'workspace',
+            depth: 2,
+            properties: ['Name', 'ClassName'],
+            includeAttributes: true,
+            find: { name: 'Camera', recursive: false },
+            listServices: false,
+          },
+        })
+      );
+      expect(decoded).not.toBeNull();
+      expect(decoded!.type).toBe('host-envelope');
+    });
+  });
+});

package/src/bridge/internal/host-protocol.ts

@@ -0,0 +1,255 @@
+/**
+ * Envelope protocol for client-to-host communication. When a bridge client
+ * needs to send an action to a plugin session, it wraps the action in a
+ * HostEnvelope and sends it to the host. The host unwraps the envelope,
+ * forwards the action to the plugin, wraps the response in a HostResponse,
+ * and sends it back to the client.
+ */
+
+import { z } from 'zod';
+import type {
+  ServerMessage,
+  PluginMessage,
+} from '../../server/web-socket-protocol.js';
+import type { SessionInfo, SessionContext, InstanceInfo } from '../types.js';
+
+export interface HostEnvelope {
+  type: 'host-envelope';
+  requestId: string;
+  targetSessionId: string;
+  action: ServerMessage;
+}
+
+export interface ListSessionsRequest {
+  type: 'list-sessions';
+  requestId: string;
+}
+
+export interface ListInstancesRequest {
+  type: 'list-instances';
+  requestId: string;
+}
+
+export interface HostResponse {
+  type: 'host-response';
+  requestId: string;
+  result: PluginMessage;
+}
+
+export interface ListSessionsResponse {
+  type: 'list-sessions-response';
+  requestId: string;
+  sessions: SessionInfo[];
+}
+
+export interface ListInstancesResponse {
+  type: 'list-instances-response';
+  requestId: string;
+  instances: InstanceInfo[];
+}
+
+export interface SessionEvent {
+  type: 'session-event';
+  event: 'connected' | 'disconnected' | 'state-changed';
+  session?: SessionInfo;
+  sessionId: string;
+  context: SessionContext;
+  instanceId: string;
+}
+
+export interface HostTransferNotice {
+  type: 'host-transfer';
+}
+
+export type HostProtocolMessage =
+  | HostEnvelope
+  | ListSessionsRequest
+  | ListInstancesRequest
+  | HostResponse
+  | ListSessionsResponse
+  | ListInstancesResponse
+  | SessionEvent
+  | HostTransferNotice;
+
+// --- Runtime validation schemas ---
+//
+// `ServerMessageSchema` is the load-bearing one: it validates the `action`
+// payload that /client connections forward to plugins. Without it, a buggy
+// or hostile CLI client could ship malformed actions and crash the plugin.
+// Container fields like `result`, `sessions`, `instances`, and `session` are
+// validated only as objects/arrays — their interior shapes flow through to
+// callers that already know how to handle the typed contracts.
+
+const ErrorCodeSchema = z.enum([
+  'UNKNOWN_REQUEST',
+  'INVALID_PAYLOAD',
+  'TIMEOUT',
+  'CAPABILITY_NOT_SUPPORTED',
+  'INSTANCE_NOT_FOUND',
+  'PROPERTY_NOT_FOUND',
+  'SCREENSHOT_FAILED',
+  'SCRIPT_LOAD_ERROR',
+  'SCRIPT_RUNTIME_ERROR',
+  'BUSY',
+  'SESSION_MISMATCH',
+  'INTERNAL_ERROR',
+]);
+
+const OutputLevelSchema = z.enum(['Print', 'Info', 'Warning', 'Error']);
+
+const ServerMessageSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('execute'),
+    sessionId: z.string(),
+    requestId: z.string().optional(),
+    payload: z.object({ script: z.string() }),
+  }),
+  z.object({
+    type: z.literal('shutdown'),
+    sessionId: z.string(),
+    payload: z.object({}).loose(),
+  }),
+  z.object({
+    type: z.literal('queryState'),
+    sessionId: z.string(),
+    requestId: z.string(),
+    payload: z.object({}).loose(),
+  }),
+  z.object({
+    type: z.literal('captureScreenshot'),
+    sessionId: z.string(),
+    requestId: z.string(),
+    payload: z.object({
+      format: z.literal('png').optional(),
+    }),
+  }),
+  z.object({
+    type: z.literal('queryDataModel'),
+    sessionId: z.string(),
+    requestId: z.string(),
+    payload: z.object({
+      path: z.string(),
+      depth: z.number().optional(),
+      properties: z.array(z.string()).optional(),
+      includeAttributes: z.boolean().optional(),
+      find: z
+        .object({
+          name: z.string(),
+          recursive: z.boolean().optional(),
+        })
+        .optional(),
+      listServices: z.boolean().optional(),
+    }),
+  }),
+  z.object({
+    type: z.literal('queryLogs'),
+    sessionId: z.string(),
+    requestId: z.string(),
+    payload: z.object({
+      count: z.number().optional(),
+      direction: z.enum(['head', 'tail']).optional(),
+      levels: z.array(OutputLevelSchema).optional(),
+      includeInternal: z.boolean().optional(),
+    }),
+  }),
+  z.object({
+    type: z.literal('registerAction'),
+    sessionId: z.string(),
+    requestId: z.string(),
+    payload: z.object({
+      name: z.string(),
+      source: z.string(),
+      hash: z.string().optional(),
+      responseType: z.string().optional(),
+    }),
+  }),
+  z.object({
+    type: z.literal('syncActions'),
+    sessionId: z.string(),
+    requestId: z.string(),
+    payload: z.object({
+      actions: z.record(z.string(), z.string()),
+    }),
+  }),
+  z.object({
+    type: z.literal('error'),
+    sessionId: z.string(),
+    requestId: z.string().optional(),
+    payload: z.object({
+      code: ErrorCodeSchema,
+      message: z.string(),
+      details: z.unknown().optional(),
+    }),
+  }),
+]);
+
+const LooseObjectSchema = z.record(z.string(), z.unknown());
+
+const HostProtocolMessageSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('host-envelope'),
+    requestId: z.string(),
+    targetSessionId: z.string(),
+    action: ServerMessageSchema,
+  }),
+  z.object({
+    type: z.literal('list-sessions'),
+    requestId: z.string(),
+  }),
+  z.object({
+    type: z.literal('list-instances'),
+    requestId: z.string(),
+  }),
+  z.object({
+    type: z.literal('host-response'),
+    requestId: z.string(),
+    result: LooseObjectSchema,
+  }),
+  z.object({
+    type: z.literal('list-sessions-response'),
+    requestId: z.string(),
+    sessions: z.array(LooseObjectSchema),
+  }),
+  z.object({
+    type: z.literal('list-instances-response'),
+    requestId: z.string(),
+    instances: z.array(LooseObjectSchema),
+  }),
+  z.object({
+    type: z.literal('session-event'),
+    event: z.enum(['connected', 'disconnected', 'state-changed']),
+    session: LooseObjectSchema.optional(),
+    sessionId: z.string(),
+    context: z.enum(['edit', 'client', 'server']),
+    instanceId: z.string(),
+  }),
+  z.object({
+    type: z.literal('host-transfer'),
+  }),
+]);
+
+/**
+ * Encode a host protocol message to a JSON string.
+ */
+export function encodeHostMessage(msg: HostProtocolMessage): string {
+  return JSON.stringify(msg);
+}
+
+/**
+ * Decode a host protocol message from a JSON string.
+ * Returns null if the message is malformed or has an unknown type.
+ */
+export function decodeHostMessage(raw: string): HostProtocolMessage | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  const result = HostProtocolMessageSchema.safeParse(parsed);
+  if (!result.success) {
+    return null;
+  }
+  return result.data as HostProtocolMessage;
+}