@principal-ai/subsystems-core 0.29.0

package/src/registry/CompositeRegistry.ts

@@ -0,0 +1,140 @@
+/**
+ * CompositeRegistry - Routes between local and remote registries
+ *
+ * Decision logic:
+ * 1. Check if scope is in local development mode
+ * 2. If yes → use LocalRegistry
+ * 3. If no → use RemoteRegistry
+ *
+ * This is the main registry implementation that should be used in production.
+ */
+
+import type { FileTree } from '@principal-ai/repository-abstraction';
+import type { StoryboardRegistryInterface, ScopeLookupResult } from '../types/registered-trace';
+import type { LocalRegistry } from './LocalRegistry';
+import type { RemoteRegistry } from './RemoteRegistry';
+
+/**
+ * Composite registry that routes to local or remote
+ */
+export class CompositeRegistry implements StoryboardRegistryInterface {
+  constructor(
+    private localRegistry: LocalRegistry,
+    private remoteRegistry: RemoteRegistry
+  ) {}
+
+  async lookupByScope(
+    scope: { name: string; version: string },
+    resource: { attributes?: Record<string, unknown> }
+  ): Promise<ScopeLookupResult> {
+    // Check if this is local development
+    if (this.isLocalDevelopment(resource, scope)) {
+      console.log('[CompositeRegistry] Using LocalRegistry for:', scope.name);
+      return this.localRegistry.lookupByScope(scope, resource);
+    }
+
+    // Use remote registry for published libraries/services
+    console.log('[CompositeRegistry] Using RemoteRegistry for:', scope.name);
+    return this.remoteRegistry.lookupByScope(scope, resource);
+  }
+
+  /**
+   * Determine if this scope is in local development mode
+   */
+  private isLocalDevelopment(
+    resource: { attributes?: Record<string, unknown> },
+    scope: { name: string; version: string }
+  ): boolean {
+    // Check for dev.mode flag
+    if (resource.attributes?.['dev.mode'] === true) {
+      console.log('[CompositeRegistry] Dev mode detected (dev.mode=true)');
+      return true;
+    }
+
+    // Check for dev version patterns
+    if (
+      scope.version?.includes('-dev') ||
+      scope.version?.includes('-local') ||
+      scope.version === '0.0.0-dev'
+    ) {
+      console.log('[CompositeRegistry] Dev mode detected (dev version pattern):', scope.version);
+      return true;
+    }
+
+    return false;
+  }
+
+  async listScopes(): Promise<Array<{ name: string; versions: string[] }>> {
+    // Combine scopes from both registries
+    const localScopes = await this.localRegistry.listScopes();
+    const remoteScopes = await this.remoteRegistry.listScopes();
+
+    // Merge, preferring local for conflicts
+    const scopeMap = new Map<string, { name: string; versions: string[] }>();
+
+    for (const scope of remoteScopes) {
+      scopeMap.set(scope.name, scope);
+    }
+
+    for (const scope of localScopes) {
+      scopeMap.set(scope.name, scope); // Local overrides remote
+    }
+
+    return Array.from(scopeMap.values());
+  }
+
+  supportsHotReload(): boolean {
+    return this.localRegistry.supportsHotReload();
+  }
+
+  /**
+   * Get the local registry (for workspace management)
+   */
+  getLocalRegistry(): LocalRegistry {
+    return this.localRegistry;
+  }
+
+  /**
+   * Get the remote registry (for cache management, etc.)
+   */
+  getRemoteRegistry(): RemoteRegistry {
+    return this.remoteRegistry;
+  }
+
+  /**
+   * Register a local workspace (convenience method)
+   */
+  async registerWorkspace(fileTree: FileTree): Promise<string[]> {
+    return this.localRegistry.registerWorkspace(fileTree);
+  }
+
+  /**
+   * Unregister a local workspace (convenience method)
+   */
+  unregisterWorkspace(scopeName: string): void {
+    this.localRegistry.unregisterWorkspace(scopeName);
+  }
+
+  /**
+   * Get list of registered local workspaces
+   */
+  getRegisteredWorkspaces(): Array<{ scopeName: string; fileTreeSha: string }> {
+    return this.localRegistry.getRegisteredWorkspaces();
+  }
+
+  /**
+   * Invalidate cache for a workspace (convenience method)
+   *
+   * Call this when .principal-views files change to trigger rebuild.
+   */
+  invalidateCache(scopeName: string): void {
+    this.localRegistry.invalidateCache(scopeName);
+  }
+
+  /**
+   * Cleanup: destroy local registry watchers
+   */
+  destroy(): void {
+    this.localRegistry.destroy();
+  }
+}

package/src/registry/EventRegistry.test.ts

@@ -0,0 +1,387 @@
+/**
+ * Tests for EventRegistry
+ */
+
+import { EventRegistry } from './EventRegistry';
+import type { ExtendedCanvas } from '../types/canvas';
+import type { ComponentLibrary } from '../types/library';
+
+describe('EventRegistry', () => {
+  // ============================================================================
+  // Helper Functions
+  // ============================================================================
+
+  function createLibrary(eventSchemas: Record<string, { description: string; attributes: Record<string, unknown> }>): ComponentLibrary {
+    return {
+      version: '1.0.0',
+      name: 'Test Library',
+      nodeComponents: {},
+      edgeComponents: {},
+      eventSchemas,
+    };
+  }
+
+  function createCanvas(events: Array<{ nodeId: string; event?: { name: string }; eventRef?: string }>): ExtendedCanvas {
+    return {
+      nodes: events.map(({ nodeId, event, eventRef }) => ({
+        id: nodeId,
+        type: 'text' as const,
+        x: 0,
+        y: 0,
+        width: 100,
+        height: 50,
+        text: nodeId,
+        pv: {
+          nodeType: 'test',
+          ...(event ? { event: { ...event, description: 'Test event', attributes: {} } } : {}),
+          ...(eventRef ? { eventRef } : {}),
+        },
+      })),
+      edges: [],
+      pv: {
+        version: '1.0.0',
+        name: 'Test Canvas',
+      },
+    };
+  }
+
+  // ============================================================================
+  // Basic Building Tests
+  // ============================================================================
+
+  describe('build', () => {
+    it('should build an empty registry when no library or canvases provided', () => {
+      const registry = EventRegistry.build(undefined, new Map());
+
+      expect(registry.size).toBe(0);
+      expect(registry.getAllEventNames()).toEqual([]);
+    });
+
+    it('should index events from library eventSchemas', () => {
+      const library = createLibrary({
+        'auth.started': { description: 'Auth started', attributes: {} },
+        'auth.completed': { description: 'Auth completed', attributes: {} },
+      });
+
+      const registry = EventRegistry.build(library, new Map(), 'library.yaml');
+
+      expect(registry.size).toBe(2);
+      expect(registry.hasEvent('auth.started')).toBe(true);
+      expect(registry.hasEvent('auth.completed')).toBe(true);
+    });
+
+    it('should index inline events from canvases', () => {
+      const canvas = createCanvas([
+        { nodeId: 'node1', event: { name: 'task.created' } },
+        { nodeId: 'node2', event: { name: 'task.updated' } },
+      ]);
+
+      const canvases = new Map<string, ExtendedCanvas>();
+      canvases.set('tasks.otel.canvas', canvas);
+
+      const registry = EventRegistry.build(undefined, canvases);
+
+      expect(registry.size).toBe(2);
+      expect(registry.hasEvent('task.created')).toBe(true);
+      expect(registry.hasEvent('task.updated')).toBe(true);
+    });
+
+    it('should index eventRef from canvases', () => {
+      const canvas = createCanvas([
+        { nodeId: 'node1', eventRef: 'auth.started' },
+        { nodeId: 'node2', eventRef: 'auth.completed' },
+      ]);
+
+      const canvases = new Map<string, ExtendedCanvas>();
+      canvases.set('auth.otel.canvas', canvas);
+
+      const registry = EventRegistry.build(undefined, canvases);
+
+      expect(registry.size).toBe(2);
+      expect(registry.hasEvent('auth.started')).toBe(true);
+      expect(registry.hasEvent('auth.completed')).toBe(true);
+    });
+
+    it('should prioritize library events over canvas eventRefs', () => {
+      const library = createLibrary({
+        'shared.event': { description: 'From library', attributes: {} },
+      });
+
+      const canvas = createCanvas([
+        { nodeId: 'node1', eventRef: 'shared.event' },
+      ]);
+
+      const canvases = new Map<string, ExtendedCanvas>();
+      canvases.set('test.otel.canvas', canvas);
+
+      const registry = EventRegistry.build(library, canvases, 'library.yaml');
+
+      // Should only have one entry (library takes precedence)
+      const sources = registry.findEvent('shared.event');
+      expect(sources).toHaveLength(1);
+      expect(sources[0].type).toBe('library');
+    });
+
+    it('should track events from multiple canvases', () => {
+      const canvas1 = createCanvas([
+        { nodeId: 'node1', event: { name: 'canvas1.event' } },
+      ]);
+      const canvas2 = createCanvas([
+        { nodeId: 'node2', event: { name: 'canvas2.event' } },
+      ]);
+
+      const canvases = new Map<string, ExtendedCanvas>();
+      canvases.set('canvas1.otel.canvas', canvas1);
+      canvases.set('canvas2.otel.canvas', canvas2);
+
+      const registry = EventRegistry.build(undefined, canvases);
+
+      expect(registry.size).toBe(2);
+      expect(registry.hasEvent('canvas1.event')).toBe(true);
+      expect(registry.hasEvent('canvas2.event')).toBe(true);
+    });
+  });
+
+  // ============================================================================
+  // findEvent Tests
+  // ============================================================================
+
+  describe('findEvent', () => {
+    it('should return empty array for non-existent event', () => {
+      const registry = EventRegistry.build(undefined, new Map());
+
+      expect(registry.findEvent('nonexistent.event')).toEqual([]);
+    });
+
+    it('should return library source for library events', () => {
+      const library = createLibrary({
+        'auth.started': { description: 'Auth started', attributes: {} },
+      });
+
+      const registry = EventRegistry.build(library, new Map(), 'path/to/library.yaml');
+
+      const sources = registry.findEvent('auth.started');
+      expect(sources).toHaveLength(1);
+      expect(sources[0]).toEqual({
+        type: 'library',
+        path: 'path/to/library.yaml',
+        eventSchema: {
+          name: 'auth.started',
+          description: 'Auth started',
+          attributes: {},
+        },
+      });
+    });
+
+    it('should return canvas source for canvas events', () => {
+      const canvas = createCanvas([
+        { nodeId: 'node1', event: { name: 'task.created' } },
+      ]);
+
+      const canvases = new Map<string, ExtendedCanvas>();
+      canvases.set('tasks.otel.canvas', canvas);
+
+      const registry = EventRegistry.build(undefined, canvases);
+
+      const sources = registry.findEvent('task.created');
+      expect(sources).toHaveLength(1);
+      expect(sources[0].type).toBe('canvas');
+      expect(sources[0].path).toBe('tasks.otel.canvas');
+    });
+
+    it('should return library sources first when event exists in both', () => {
+      const library = createLibrary({
+        'shared.event': { description: 'From library', attributes: {} },
+      });
+
+      // Canvas with inline event (same name as library)
+      const canvas = createCanvas([
+        { nodeId: 'node1', event: { name: 'shared.event' } },
+      ]);
+
+      const canvases = new Map<string, ExtendedCanvas>();
+      canvases.set('test.otel.canvas', canvas);
+
+      const registry = EventRegistry.build(library, canvases, 'library.yaml');
+
+      const sources = registry.findEvent('shared.event');
+      expect(sources.length).toBeGreaterThan(0);
+      expect(sources[0].type).toBe('library'); // Library comes first
+    });
+
+    it('should sort canvas sources alphabetically', () => {
+      const canvasZ = createCanvas([{ nodeId: 'n1', event: { name: 'shared.event' } }]);
+      const canvasA = createCanvas([{ nodeId: 'n2', event: { name: 'shared.event' } }]);
+
+      const canvases = new Map<string, ExtendedCanvas>();
+      canvases.set('z-canvas.otel.canvas', canvasZ);
+      canvases.set('a-canvas.otel.canvas', canvasA);
+
+      const registry = EventRegistry.build(undefined, canvases);
+
+      const sources = registry.findEvent('shared.event');
+      expect(sources).toHaveLength(2);
+      expect(sources[0].path).toBe('a-canvas.otel.canvas');
+      expect(sources[1].path).toBe('z-canvas.otel.canvas');
+    });
+  });
+
+  // ============================================================================
+  // hasEvent Tests
+  // ============================================================================
+
+  describe('hasEvent', () => {
+    it('should return false for non-existent event', () => {
+      const registry = EventRegistry.build(undefined, new Map());
+
+      expect(registry.hasEvent('nonexistent')).toBe(false);
+    });
+
+    it('should return true for existing library event', () => {
+      const library = createLibrary({
+        'auth.started': { description: 'Auth started', attributes: {} },
+      });
+
+      const registry = EventRegistry.build(library, new Map());
+
+      expect(registry.hasEvent('auth.started')).toBe(true);
+    });
+
+    it('should return true for existing canvas event', () => {
+      const canvas = createCanvas([
+        { nodeId: 'node1', event: { name: 'task.created' } },
+      ]);
+
+      const canvases = new Map<string, ExtendedCanvas>();
+      canvases.set('tasks.otel.canvas', canvas);
+
+      const registry = EventRegistry.build(undefined, canvases);
+
+      expect(registry.hasEvent('task.created')).toBe(true);
+    });
+  });
+
+  // ============================================================================
+  // getAllEventNames Tests
+  // ============================================================================
+
+  describe('getAllEventNames', () => {
+    it('should return empty array for empty registry', () => {
+      const registry = EventRegistry.build(undefined, new Map());
+
+      expect(registry.getAllEventNames()).toEqual([]);
+    });
+
+    it('should return sorted event names', () => {
+      const library = createLibrary({
+        'zebra.event': { description: 'Z event', attributes: {} },
+        'alpha.event': { description: 'A event', attributes: {} },
+        'beta.event': { description: 'B event', attributes: {} },
+      });
+
+      const registry = EventRegistry.build(library, new Map());
+
+      expect(registry.getAllEventNames()).toEqual([
+        'alpha.event',
+        'beta.event',
+        'zebra.event',
+      ]);
+    });
+
+    it('should include events from both library and canvases', () => {
+      const library = createLibrary({
+        'library.event': { description: 'From library', attributes: {} },
+      });
+
+      const canvas = createCanvas([
+        { nodeId: 'node1', event: { name: 'canvas.event' } },
+      ]);
+
+      const canvases = new Map<string, ExtendedCanvas>();
+      canvases.set('test.otel.canvas', canvas);
+
+      const registry = EventRegistry.build(library, canvases);
+
+      const names = registry.getAllEventNames();
+      expect(names).toContain('library.event');
+      expect(names).toContain('canvas.event');
+    });
+  });
+
+  // ============================================================================
+  // Edge Cases
+  // ============================================================================
+
+  describe('edge cases', () => {
+    it('should handle canvas with no nodes', () => {
+      const canvas: ExtendedCanvas = {
+        nodes: [],
+        edges: [],
+        pv: { version: '1.0.0', name: 'Empty Canvas' },
+      };
+
+      const canvases = new Map<string, ExtendedCanvas>();
+      canvases.set('empty.otel.canvas', canvas);
+
+      const registry = EventRegistry.build(undefined, canvases);
+
+      expect(registry.size).toBe(0);
+    });
+
+    it('should handle canvas with nodes without pv extension', () => {
+      const canvas: ExtendedCanvas = {
+        nodes: [
+          {
+            id: 'node1',
+            type: 'text',
+            x: 0,
+            y: 0,
+            width: 100,
+            height: 50,
+            text: 'No PV',
+            // No pv field
+          },
+        ],
+        edges: [],
+        pv: { version: '1.0.0', name: 'Canvas' },
+      };
+
+      const canvases = new Map<string, ExtendedCanvas>();
+      canvases.set('test.otel.canvas', canvas);
+
+      const registry = EventRegistry.build(undefined, canvases);
+
+      expect(registry.size).toBe(0);
+    });
+
+    it('should handle library without eventSchemas', () => {
+      const library: ComponentLibrary = {
+        version: '1.0.0',
+        name: 'No Events Library',
+        nodeComponents: {},
+        edgeComponents: {},
+        // No eventSchemas
+      };
+
+      const registry = EventRegistry.build(library, new Map());
+
+      expect(registry.size).toBe(0);
+    });
+
+    it('should not duplicate events from same canvas', () => {
+      const canvas = createCanvas([
+        { nodeId: 'node1', event: { name: 'duplicate.event' } },
+        { nodeId: 'node2', event: { name: 'duplicate.event' } },
+      ]);
+
+      const canvases = new Map<string, ExtendedCanvas>();
+      canvases.set('test.otel.canvas', canvas);
+
+      const registry = EventRegistry.build(undefined, canvases);
+
+      const sources = registry.findEvent('duplicate.event');
+      // Should only have one entry for this canvas
+      expect(sources).toHaveLength(1);
+    });
+  });
+});