freesail 0.0.1 → 0.1.0

package/packages/core/src/parser.ts

@@ -0,0 +1,270 @@
+/**
+ * JSON Stream Parser
+ * 
+ * Handles parsing of JSON data from SSE streams,
+ * including incremental/chunked JSON parsing.
+ */
+
+import type { A2UXMessage } from './types.js';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ParseResult {
+  success: boolean;
+  message?: A2UXMessage;
+  error?: string;
+  remaining?: string;
+}
+
+export interface ParserOptions {
+  /** Enable lenient parsing mode */
+  lenient?: boolean;
+  /** Maximum buffer size in characters */
+  maxBufferSize?: number;
+}
+
+// =============================================================================
+// JSON Stream Parser
+// =============================================================================
+
+/**
+ * JSONStreamParser handles incremental JSON parsing from SSE streams.
+ * It buffers partial JSON and emits complete messages.
+ */
+export class JSONStreamParser {
+  private buffer: string = '';
+  private maxBufferSize: number;
+  private lenient: boolean;
+
+  constructor(options: ParserOptions = {}) {
+    this.maxBufferSize = options.maxBufferSize ?? 1024 * 1024; // 1MB default
+    this.lenient = options.lenient ?? false;
+  }
+
+  /**
+   * Feed data into the parser and get any complete messages
+   */
+  feed(chunk: string): A2UXMessage[] {
+    this.buffer += chunk;
+    
+    // Check buffer overflow
+    if (this.buffer.length > this.maxBufferSize) {
+      console.warn('[JSONStreamParser] Buffer overflow, clearing buffer');
+      this.buffer = '';
+      return [];
+    }
+
+    return this.extractMessages();
+  }
+
+  /**
+   * Parse a single complete JSON string
+   */
+  parse(jsonString: string): ParseResult {
+    try {
+      const message = JSON.parse(jsonString) as A2UXMessage;
+      return { success: true, message };
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      return { 
+        success: false, 
+        error: err.message,
+        remaining: jsonString 
+      };
+    }
+  }
+
+  /**
+   * Reset the parser state
+   */
+  reset(): void {
+    this.buffer = '';
+  }
+
+  /**
+   * Get current buffer content (for debugging)
+   */
+  getBuffer(): string {
+    return this.buffer;
+  }
+
+  // ===========================================================================
+  // Private Methods
+  // ===========================================================================
+
+  private extractMessages(): A2UXMessage[] {
+    const messages: A2UXMessage[] = [];
+    
+    // Try to extract complete JSON objects
+    let startIndex = 0;
+    let depth = 0;
+    let inString = false;
+    let escapeNext = false;
+
+    for (let i = 0; i < this.buffer.length; i++) {
+      const char = this.buffer[i];
+
+      if (escapeNext) {
+        escapeNext = false;
+        continue;
+      }
+
+      if (char === '\\' && inString) {
+        escapeNext = true;
+        continue;
+      }
+
+      if (char === '"') {
+        inString = !inString;
+        continue;
+      }
+
+      if (inString) continue;
+
+      if (char === '{') {
+        if (depth === 0) {
+          startIndex = i;
+        }
+        depth++;
+      } else if (char === '}') {
+        depth--;
+        if (depth === 0) {
+          // Found complete JSON object
+          const jsonString = this.buffer.slice(startIndex, i + 1);
+          const result = this.parse(jsonString);
+          
+          if (result.success && result.message) {
+            messages.push(result.message);
+          } else if (!this.lenient) {
+            console.warn('[JSONStreamParser] Failed to parse:', result.error);
+          }
+          
+          startIndex = i + 1;
+        }
+      }
+    }
+
+    // Keep remaining incomplete data in buffer
+    this.buffer = this.buffer.slice(startIndex);
+
+    return messages;
+  }
+}
+
+// =============================================================================
+// SSE Parser
+// =============================================================================
+
+/**
+ * SSEParser handles Server-Sent Events format parsing
+ */
+export class SSEParser {
+  private jsonParser: JSONStreamParser;
+  private lineBuffer: string = '';
+
+  constructor(options: ParserOptions = {}) {
+    this.jsonParser = new JSONStreamParser(options);
+  }
+
+  /**
+   * Feed raw SSE data and extract A2UX messages
+   */
+  feed(chunk: string): A2UXMessage[] {
+    const messages: A2UXMessage[] = [];
+    this.lineBuffer += chunk;
+
+    // Split by SSE line endings
+    const lines = this.lineBuffer.split(/\r?\n/);
+    
+    // Keep the last incomplete line in buffer
+    this.lineBuffer = lines.pop() ?? '';
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      
+      // Skip empty lines and comments
+      if (!trimmed || trimmed.startsWith(':')) {
+        continue;
+      }
+
+      // Parse SSE data field
+      if (trimmed.startsWith('data:')) {
+        const data = trimmed.slice(5).trim();
+        
+        // Skip [DONE] marker
+        if (data === '[DONE]') {
+          continue;
+        }
+
+        const parsed = this.jsonParser.feed(data);
+        messages.push(...parsed);
+      }
+    }
+
+    return messages;
+  }
+
+  /**
+   * Reset the parser state
+   */
+  reset(): void {
+    this.jsonParser.reset();
+    this.lineBuffer = '';
+  }
+}
+
+// =============================================================================
+// Template Expression Parser
+// =============================================================================
+
+/**
+ * Parses and evaluates template expressions like ${user.name}
+ */
+export function parseTemplateExpression(
+  template: string, 
+  dataModel: Record<string, unknown>
+): string {
+  return template.replace(/\$\{([^}]+)\}/g, (_, expression) => {
+    try {
+      const value = evaluateExpression(expression.trim(), dataModel);
+      return String(value ?? '');
+    } catch {
+      return '';
+    }
+  });
+}
+
+/**
+ * Evaluates a simple path expression against a data model
+ */
+function evaluateExpression(
+  expression: string, 
+  dataModel: Record<string, unknown>
+): unknown {
+  const parts = expression.split('.');
+  let current: unknown = dataModel;
+
+  for (const part of parts) {
+    if (current === null || current === undefined) {
+      return undefined;
+    }
+    
+    // Handle array index access like items[0]
+    const arrayMatch = part.match(/^(\w+)\[(\d+)\]$/);
+    if (arrayMatch) {
+      const [, key, index] = arrayMatch;
+      current = (current as Record<string, unknown>)[key];
+      if (Array.isArray(current)) {
+        current = current[parseInt(index, 10)];
+      } else {
+        return undefined;
+      }
+    } else {
+      current = (current as Record<string, unknown>)[part];
+    }
+  }
+
+  return current;
+}

package/packages/core/src/protocol.ts

@@ -0,0 +1,254 @@
+/**
+ * A2UX Protocol Handler
+ * 
+ * Core protocol listener that processes incoming A2UX messages
+ * and dispatches them to appropriate handlers.
+ */
+
+import type {
+  A2UXMessage,
+  CreateSurfaceMessage,
+  UpdateComponentsMessage,
+  UpdateDataModelMessage,
+  DeleteSurfaceMessage,
+  WatchSurfaceMessage,
+  UnwatchSurfaceMessage,
+} from './types.js';
+
+import {
+  isCreateSurface,
+  isUpdateComponents,
+  isUpdateDataModel,
+  isDeleteSurface,
+  isWatchSurface,
+  isUnwatchSurface,
+  getMessageType,
+} from './types.js';
+
+import { SurfaceStore } from './store';
+
+// =============================================================================
+// Event Types
+// =============================================================================
+
+export interface ProtocolEventMap {
+  'createSurface': CreateSurfaceMessage['createSurface'];
+  'updateComponents': UpdateComponentsMessage['updateComponents'];
+  'updateDataModel': UpdateDataModelMessage['updateDataModel'];
+  'deleteSurface': DeleteSurfaceMessage['deleteSurface'];
+  'watchSurface': WatchSurfaceMessage['watchSurface'];
+  'unwatchSurface': UnwatchSurfaceMessage['unwatchSurface'];
+  'error': { message: string; originalError?: Error };
+  'connected': { url: string };
+  'disconnected': { reason: string };
+}
+
+export type ProtocolEventHandler<K extends keyof ProtocolEventMap> = 
+  (data: ProtocolEventMap[K]) => void;
+
+// =============================================================================
+// Protocol Handler
+// =============================================================================
+
+export interface ProtocolHandlerOptions {
+  /** Surface store for state management */
+  store?: SurfaceStore;
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+/**
+ * A2UXProtocolHandler processes incoming A2UX messages and manages
+ * protocol state. It acts as the central message dispatcher.
+ */
+export class A2UXProtocolHandler {
+  private store: SurfaceStore;
+  private debug: boolean;
+  private listeners: Map<keyof ProtocolEventMap, Set<ProtocolEventHandler<keyof ProtocolEventMap>>> = new Map();
+  private watchTimers: Map<string, ReturnType<typeof setInterval>> = new Map();
+
+  constructor(options: ProtocolHandlerOptions = {}) {
+    this.store = options.store ?? new SurfaceStore();
+    this.debug = options.debug ?? false;
+  }
+
+  /**
+   * Process an incoming A2UX message
+   */
+  processMessage(message: A2UXMessage): void {
+    try {
+      const messageType = getMessageType(message);
+      this.log(`Processing message: ${messageType}`);
+
+      if (isCreateSurface(message)) {
+        this.handleCreateSurface(message.createSurface);
+      } else if (isUpdateComponents(message)) {
+        this.handleUpdateComponents(message.updateComponents);
+      } else if (isUpdateDataModel(message)) {
+        this.handleUpdateDataModel(message.updateDataModel);
+      } else if (isDeleteSurface(message)) {
+        this.handleDeleteSurface(message.deleteSurface);
+      } else if (isWatchSurface(message)) {
+        this.handleWatchSurface(message.watchSurface);
+      } else if (isUnwatchSurface(message)) {
+        this.handleUnwatchSurface(message.unwatchSurface);
+      } else {
+        this.log(`Unknown message type: ${messageType}`, 'warn');
+      }
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.emit('error', { message: err.message, originalError: err });
+    }
+  }
+
+  /**
+   * Process a raw JSON string message
+   */
+  processRawMessage(jsonString: string): void {
+    try {
+      const message = JSON.parse(jsonString) as A2UXMessage;
+      this.processMessage(message);
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.emit('error', { 
+        message: `Failed to parse message: ${err.message}`, 
+        originalError: err 
+      });
+    }
+  }
+
+  // ===========================================================================
+  // Message Handlers
+  // ===========================================================================
+
+  private handleCreateSurface(payload: CreateSurfaceMessage['createSurface']): void {
+    const { surfaceId, catalogId } = payload;
+    this.store.createSurface(surfaceId, catalogId);
+    this.emit('createSurface', payload);
+  }
+
+  private handleUpdateComponents(payload: UpdateComponentsMessage['updateComponents']): void {
+    const { surfaceId, components } = payload;
+    this.store.updateComponents(surfaceId, components);
+    this.emit('updateComponents', payload);
+  }
+
+  private handleUpdateDataModel(payload: UpdateDataModelMessage['updateDataModel']): void {
+    const { surfaceId, path, op, value } = payload;
+    this.store.updateDataModel(surfaceId, path ?? '/', op ?? 'replace', value);
+    this.emit('updateDataModel', payload);
+  }
+
+  private handleDeleteSurface(payload: DeleteSurfaceMessage['deleteSurface']): void {
+    const { surfaceId } = payload;
+    
+    // Clear any active watchers
+    this.clearWatcher(surfaceId);
+    
+    this.store.deleteSurface(surfaceId);
+    this.emit('deleteSurface', payload);
+  }
+
+  private handleWatchSurface(payload: WatchSurfaceMessage['watchSurface']): void {
+    const { surfaceId, interval = 10, expiresIn = 300 } = payload;
+    
+    // Clear any existing watcher
+    this.clearWatcher(surfaceId);
+    
+    // Set up new watcher
+    const timer = setInterval(() => {
+      this.store.triggerWatchCallback(surfaceId);
+    }, interval * 1000);
+    
+    this.watchTimers.set(surfaceId, timer);
+    
+    // Set expiration
+    setTimeout(() => {
+      this.clearWatcher(surfaceId);
+    }, expiresIn * 1000);
+    
+    this.emit('watchSurface', payload);
+  }
+
+  private handleUnwatchSurface(payload: UnwatchSurfaceMessage['unwatchSurface']): void {
+    const { surfaceId } = payload;
+    this.clearWatcher(surfaceId);
+    this.emit('unwatchSurface', payload);
+  }
+
+  private clearWatcher(surfaceId: string): void {
+    const timer = this.watchTimers.get(surfaceId);
+    if (timer) {
+      clearInterval(timer);
+      this.watchTimers.delete(surfaceId);
+    }
+  }
+
+  // ===========================================================================
+  // Event Emitter
+  // ===========================================================================
+
+  on<K extends keyof ProtocolEventMap>(
+    event: K, 
+    handler: ProtocolEventHandler<K>
+  ): () => void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set());
+    }
+    this.listeners.get(event)!.add(handler as ProtocolEventHandler<keyof ProtocolEventMap>);
+    
+    // Return unsubscribe function
+    return () => this.off(event, handler);
+  }
+
+  off<K extends keyof ProtocolEventMap>(
+    event: K, 
+    handler: ProtocolEventHandler<K>
+  ): void {
+    this.listeners.get(event)?.delete(handler as ProtocolEventHandler<keyof ProtocolEventMap>);
+  }
+
+  private emit<K extends keyof ProtocolEventMap>(event: K, data: ProtocolEventMap[K]): void {
+    this.listeners.get(event)?.forEach(handler => {
+      try {
+        (handler as ProtocolEventHandler<K>)(data);
+      } catch (error) {
+        console.error(`Error in event handler for ${event}:`, error);
+      }
+    });
+  }
+
+  // ===========================================================================
+  // Accessors
+  // ===========================================================================
+
+  getStore(): SurfaceStore {
+    return this.store;
+  }
+
+  // ===========================================================================
+  // Cleanup
+  // ===========================================================================
+
+  destroy(): void {
+    // Clear all watchers
+    this.watchTimers.forEach((timer) => clearInterval(timer));
+    this.watchTimers.clear();
+    
+    // Clear all listeners
+    this.listeners.clear();
+    
+    // Clear store
+    this.store.clear();
+  }
+
+  // ===========================================================================
+  // Debug
+  // ===========================================================================
+
+  private log(message: string, level: 'log' | 'warn' | 'error' = 'log'): void {
+    if (this.debug) {
+      console[level](`[A2UX Protocol] ${message}`);
+    }
+  }
+}