@kb-labs/shared 1.1.0

package/packages/shared-command-kit/src/__tests__/ws-types.test.ts

@@ -0,0 +1,359 @@
+/**
+ * @file Unit tests for WebSocket message builders and routers
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { defineMessage, MessageBuilder, MessageRouter } from '../ws-types.js';
+import type { WSMessage, WSSender } from '@kb-labs/plugin-contracts';
+
+describe('MessageBuilder', () => {
+  describe('create', () => {
+    it('should create message with type and payload', () => {
+      const builder = new MessageBuilder<{ name: string }>('test');
+
+      const message = builder.create({ name: 'Alice' });
+
+      expect(message.type).toBe('test');
+      expect(message.payload).toEqual({ name: 'Alice' });
+      expect(message.timestamp).toBeGreaterThan(0);
+    });
+
+    it('should create message with messageId', () => {
+      const builder = new MessageBuilder<{ data: string }>('test');
+
+      const message = builder.create({ data: 'hello' }, 'msg-123');
+
+      expect(message.type).toBe('test');
+      expect(message.payload).toEqual({ data: 'hello' });
+      expect(message.messageId).toBe('msg-123');
+      expect(message.timestamp).toBeGreaterThan(0);
+    });
+
+    it('should create message without messageId', () => {
+      const builder = new MessageBuilder<object>('ping');
+
+      const message = builder.create({});
+
+      expect(message.type).toBe('ping');
+      expect(message.payload).toEqual({});
+      expect(message.messageId).toBeUndefined();
+      expect(message.timestamp).toBeGreaterThan(0);
+    });
+
+    it('should generate unique timestamps for sequential calls', () => {
+      const builder = new MessageBuilder<object>('test');
+
+      const msg1 = builder.create({});
+      const msg2 = builder.create({});
+
+      // Timestamps should be close but not necessarily different
+      // (depends on system clock resolution)
+      expect(msg1.timestamp).toBeLessThanOrEqual(msg2.timestamp);
+    });
+  });
+
+  describe('is', () => {
+    it('should return true for matching message type', () => {
+      const builder = new MessageBuilder<{ count: number }>('update');
+
+      const message: WSMessage = {
+        type: 'update',
+        payload: { count: 42 },
+        timestamp: Date.now(),
+      };
+
+      expect(builder.is(message)).toBe(true);
+    });
+
+    it('should return false for non-matching message type', () => {
+      const builder = new MessageBuilder<{ count: number }>('update');
+
+      const message: WSMessage = {
+        type: 'ping',
+        payload: {},
+        timestamp: Date.now(),
+      };
+
+      expect(builder.is(message)).toBe(false);
+    });
+
+    it('should narrow type when used in if statement', () => {
+      const UpdateMsg = new MessageBuilder<{ progress: number }>('update');
+
+      const message: WSMessage = {
+        type: 'update',
+        payload: { progress: 50 },
+        timestamp: Date.now(),
+      };
+
+      if (UpdateMsg.is(message)) {
+        // TypeScript should infer message.payload as { progress: number }
+        const progress: number = message.payload.progress;
+        expect(progress).toBe(50);
+      } else {
+        throw new Error('Should match');
+      }
+    });
+  });
+});
+
+describe('defineMessage', () => {
+  it('should create MessageBuilder instance', () => {
+    const PingMsg = defineMessage<object>('ping');
+
+    expect(PingMsg).toBeInstanceOf(MessageBuilder);
+  });
+
+  it('should create type-safe message builder', () => {
+    interface ProgressPayload {
+      phase: string;
+      progress: number;
+    }
+
+    const ProgressMsg = defineMessage<ProgressPayload>('progress');
+
+    const message = ProgressMsg.create({
+      phase: 'analyzing',
+      progress: 50,
+    });
+
+    expect(message.type).toBe('progress');
+    expect((message.payload as any).phase).toBe('analyzing');
+    expect((message.payload as any).progress).toBe(50);
+  });
+
+  it('should support different payload types', () => {
+    const StringMsg = defineMessage<string>('text');
+    const NumberMsg = defineMessage<number>('count');
+    const ObjectMsg = defineMessage<{ items: string[] }>('list');
+
+    const textMsg = StringMsg.create('hello');
+    const countMsg = NumberMsg.create(42);
+    const listMsg = ObjectMsg.create({ items: ['a', 'b'] });
+
+    expect(textMsg.payload).toBe('hello');
+    expect(countMsg.payload).toBe(42);
+    expect(listMsg.payload).toEqual({ items: ['a', 'b'] });
+  });
+});
+
+describe('MessageRouter', () => {
+  let mockContext: any;
+  let mockSender: WSSender;
+
+  beforeEach(() => {
+    mockContext = {
+      logger: {
+        info: vi.fn(),
+        error: vi.fn(),
+      },
+    };
+
+    mockSender = {
+      send: vi.fn(),
+      broadcast: vi.fn(),
+      sendTo: vi.fn(),
+      close: vi.fn(),
+      getConnectionId: vi.fn(() => 'conn-123'),
+    };
+  });
+
+  describe('on', () => {
+    it('should register message handler', () => {
+      const router = new MessageRouter();
+      const PingMsg = defineMessage<object>('ping');
+      const handler = vi.fn();
+
+      router.on(PingMsg, handler);
+
+      // Handler should be registered (tested via handle())
+      expect(router).toBeDefined();
+    });
+
+    it('should support chaining', () => {
+      const router = new MessageRouter();
+      const PingMsg = defineMessage<object>('ping');
+      const PongMsg = defineMessage<object>('pong');
+
+      const result = router.on(PingMsg, vi.fn()).on(PongMsg, vi.fn());
+
+      expect(result).toBe(router);
+    });
+
+    it('should register multiple handlers for different message types', () => {
+      const router = new MessageRouter();
+      const StartMsg = defineMessage<object>('start');
+      const StopMsg = defineMessage<object>('stop');
+
+      const startHandler = vi.fn();
+      const stopHandler = vi.fn();
+
+      router.on(StartMsg, startHandler).on(StopMsg, stopHandler);
+
+      // Handlers registered (tested via handle())
+      expect(router).toBeDefined();
+    });
+  });
+
+  describe('handle', () => {
+    it('should call handler for matching message type', async () => {
+      const router = new MessageRouter();
+      const PingMsg = defineMessage<object>('ping');
+      const handler = vi.fn();
+
+      router.on(PingMsg, handler);
+
+      const message: WSMessage = {
+        type: 'ping',
+        payload: {},
+        timestamp: Date.now(),
+      };
+
+      const handled = await router.handle(mockContext, message, mockSender);
+
+      expect(handled).toBe(true);
+      expect(handler).toHaveBeenCalledWith(mockContext, {}, mockSender);
+    });
+
+    it('should return false for unhandled message type', async () => {
+      const router = new MessageRouter();
+      const PingMsg = defineMessage<object>('ping');
+
+      router.on(PingMsg, vi.fn());
+
+      const message: WSMessage = {
+        type: 'unknown',
+        payload: {},
+        timestamp: Date.now(),
+      };
+
+      const handled = await router.handle(mockContext, message, mockSender);
+
+      expect(handled).toBe(false);
+    });
+
+    it('should pass payload to handler', async () => {
+      const router = new MessageRouter();
+      const UpdateMsg = defineMessage<{ progress: number }>('update');
+      const handler = vi.fn();
+
+      router.on(UpdateMsg, handler);
+
+      const message: WSMessage = {
+        type: 'update',
+        payload: { progress: 75 },
+        timestamp: Date.now(),
+      };
+
+      await router.handle(mockContext, message, mockSender);
+
+      expect(handler).toHaveBeenCalledWith(mockContext, { progress: 75 }, mockSender);
+    });
+
+    it('should handle async handlers', async () => {
+      const router = new MessageRouter();
+      const StartMsg = defineMessage<object>('start');
+
+      let resolved = false;
+      const asyncHandler = vi.fn(async () => {
+        await new Promise<void>((resolve) => { setTimeout(resolve, 10); });
+        resolved = true;
+      });
+
+      router.on(StartMsg, asyncHandler);
+
+      const message: WSMessage = {
+        type: 'start',
+        payload: {},
+        timestamp: Date.now(),
+      };
+
+      await router.handle(mockContext, message, mockSender);
+
+      expect(resolved).toBe(true);
+      expect(asyncHandler).toHaveBeenCalled();
+    });
+
+    it('should route to correct handler among multiple', async () => {
+      const router = new MessageRouter();
+      const PingMsg = defineMessage<object>('ping');
+      const PongMsg = defineMessage<object>('pong');
+      const StartMsg = defineMessage<object>('start');
+
+      const pingHandler = vi.fn();
+      const pongHandler = vi.fn();
+      const startHandler = vi.fn();
+
+      router.on(PingMsg, pingHandler).on(PongMsg, pongHandler).on(StartMsg, startHandler);
+
+      const pongMessage: WSMessage = {
+        type: 'pong',
+        payload: {},
+        timestamp: Date.now(),
+      };
+
+      await router.handle(mockContext, pongMessage, mockSender);
+
+      expect(pingHandler).not.toHaveBeenCalled();
+      expect(pongHandler).toHaveBeenCalled();
+      expect(startHandler).not.toHaveBeenCalled();
+    });
+
+    it('should propagate handler errors', async () => {
+      const router = new MessageRouter();
+      const ErrorMsg = defineMessage<object>('error');
+      const error = new Error('Handler failed');
+
+      router.on(ErrorMsg, async () => {
+        throw error;
+      });
+
+      const message: WSMessage = {
+        type: 'error',
+        payload: {},
+        timestamp: Date.now(),
+      };
+
+      await expect(router.handle(mockContext, message, mockSender)).rejects.toThrow(error);
+    });
+  });
+
+  describe('integration', () => {
+    it('should handle complete message flow', async () => {
+      const router = new MessageRouter();
+
+      // Define message types
+      const StartMsg = defineMessage<{ scope?: string }>('start');
+      const ProgressMsg = defineMessage<{ progress: number }>('progress');
+      const CompleteMsg = defineMessage<{ result: string }>('complete');
+
+      // Handlers
+      const startHandler = vi.fn(async (ctx, payload, sender) => {
+        await sender.send(ProgressMsg.create({ progress: 0 }));
+      });
+
+      const progressHandler = vi.fn();
+      const completeHandler = vi.fn();
+
+      router.on(StartMsg, startHandler).on(ProgressMsg, progressHandler).on(CompleteMsg, completeHandler);
+
+      // Handle start message
+      const startMessage: WSMessage = {
+        type: 'start',
+        payload: { scope: 'packages' },
+        timestamp: Date.now(),
+      };
+
+      const handled = await router.handle(mockContext, startMessage, mockSender);
+
+      expect(handled).toBe(true);
+      expect(startHandler).toHaveBeenCalledWith(mockContext, { scope: 'packages' }, mockSender);
+      expect(mockSender.send).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'progress',
+          payload: { progress: 0 },
+        })
+      );
+    });
+  });
+});

package/packages/shared-command-kit/src/analytics/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @module @kb-labs/shared-command-kit/analytics
+ * Analytics tracking helpers
+ */
+
+export * from './with-analytics';

package/packages/shared-command-kit/src/analytics/with-analytics.ts

@@ -0,0 +1,195 @@
+/**
+ * Analytics Wrapper
+ *
+ * Optional helper for wrapping operations with analytics events.
+ * You can always use ctx.platform.analytics.track() directly - this is just convenience.
+ *
+ * @example
+ * ```typescript
+ * import { withAnalytics } from '@kb-labs/shared-command-kit';
+ *
+ * const result = await withAnalytics(ctx, 'mind.query', {
+ *   started: { queryId, text, mode },
+ *   completed: (result) => ({ tokensIn: result.tokensIn, tokensOut: result.tokensOut }),
+ *   failed: (error) => ({ errorMessage: error.message }),
+ * }, async () => {
+ *   return await executeQuery(...);
+ * });
+ * ```
+ */
+
+import type { IAnalytics } from '@kb-labs/core-platform';
+
+/**
+ * Context with optional analytics
+ */
+export interface AnalyticsContext {
+  platform?: {
+    analytics?: IAnalytics;
+  };
+}
+
+/**
+ * Analytics event configuration
+ */
+export interface AnalyticsEvents<TResult> {
+  /** Event properties when operation starts */
+  started?: Record<string, unknown>;
+  /** Event properties when operation completes (can be function of result) */
+  completed?: Record<string, unknown> | ((result: TResult) => Record<string, unknown>);
+  /** Event properties when operation fails (can be function of error) */
+  failed?: Record<string, unknown> | ((error: Error) => Record<string, unknown>);
+}
+
+/**
+ * Wrap an async operation with analytics tracking
+ *
+ * Automatically tracks:
+ * - `{eventName}.started` when operation begins
+ * - `{eventName}.completed` when operation succeeds
+ * - `{eventName}.failed` when operation fails
+ *
+ * @param ctx - Context with platform.analytics
+ * @param eventName - Base event name (e.g., 'mind.query', 'workflow.run')
+ * @param events - Event properties for started/completed/failed events
+ * @param operation - Async operation to execute
+ * @returns Result of the operation
+ *
+ * @example
+ * ```typescript
+ * const result = await withAnalytics(ctx, 'mind.query', {
+ *   started: { queryId: '123', text: 'search query' },
+ *   completed: (result) => ({
+ *     tokensIn: result.tokensIn,
+ *     tokensOut: result.tokensOut,
+ *     resultsCount: result.results.length,
+ *   }),
+ *   failed: (error) => ({
+ *     errorCode: error.code,
+ *     errorMessage: error.message,
+ *   }),
+ * }, async () => {
+ *   return await executeQuery('search query');
+ * });
+ * ```
+ */
+export async function withAnalytics<TResult>(
+  ctx: AnalyticsContext,
+  eventName: string,
+  events: AnalyticsEvents<TResult>,
+  operation: () => Promise<TResult>
+): Promise<TResult> {
+  const analytics = ctx.platform?.analytics;
+  const startTime = Date.now();
+
+  // Track started event
+  if (analytics && events.started) {
+    await analytics.track(`${eventName}.started`, {
+      ...events.started,
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  try {
+    // Execute operation
+    const result = await operation();
+
+    // Track completed event
+    if (analytics && events.completed) {
+      const completedProps = typeof events.completed === 'function'
+        ? events.completed(result)
+        : events.completed;
+
+      await analytics.track(`${eventName}.completed`, {
+        ...completedProps,
+        durationMs: Date.now() - startTime,
+        timestamp: new Date().toISOString(),
+      });
+    }
+
+    return result;
+  } catch (error: any) {
+    // Track failed event
+    if (analytics && events.failed) {
+      const failedProps = typeof events.failed === 'function'
+        ? events.failed(error)
+        : events.failed;
+
+      await analytics.track(`${eventName}.failed`, {
+        ...failedProps,
+        durationMs: Date.now() - startTime,
+        timestamp: new Date().toISOString(),
+      });
+    }
+
+    // Re-throw error
+    throw error;
+  }
+}
+
+/**
+ * Create a reusable analytics wrapper for a specific event
+ *
+ * @param eventName - Base event name
+ * @param defaultEvents - Default event properties
+ * @returns Function that wraps operations with analytics
+ *
+ * @example
+ * ```typescript
+ * const trackQuery = createAnalyticsWrapper('mind.query', {
+ *   started: { source: 'cli' },
+ *   completed: (result) => ({ resultsCount: result.results.length }),
+ * });
+ *
+ * // Use multiple times
+ * const result1 = await trackQuery(ctx, { text: 'query 1' }, async () => {...});
+ * const result2 = await trackQuery(ctx, { text: 'query 2' }, async () => {...});
+ * ```
+ */
+export function createAnalyticsWrapper<TResult>(
+  eventName: string,
+  defaultEvents: AnalyticsEvents<TResult>
+) {
+  return async (
+    ctx: AnalyticsContext,
+    additionalEvents: Partial<AnalyticsEvents<TResult>>,
+    operation: () => Promise<TResult>
+  ): Promise<TResult> => {
+    const mergedEvents: AnalyticsEvents<TResult> = {
+      started: { ...defaultEvents.started, ...additionalEvents.started },
+      completed: additionalEvents.completed || defaultEvents.completed,
+      failed: additionalEvents.failed || defaultEvents.failed,
+    };
+
+    return withAnalytics(ctx, eventName, mergedEvents, operation);
+  };
+}
+
+/**
+ * Track a simple event (no wrapping)
+ *
+ * Convenience helper for tracking single events without wrapping an operation.
+ *
+ * @param ctx - Context with platform.analytics
+ * @param eventName - Event name
+ * @param properties - Event properties
+ *
+ * @example
+ * ```typescript
+ * await trackEvent(ctx, 'button.clicked', { buttonId: 'submit', page: 'settings' });
+ * ```
+ */
+export async function trackEvent(
+  ctx: AnalyticsContext,
+  eventName: string,
+  properties?: Record<string, unknown>
+): Promise<void> {
+  const analytics = ctx.platform?.analytics;
+
+  if (analytics) {
+    await analytics.track(eventName, {
+      ...properties,
+      timestamp: new Date().toISOString(),
+    });
+  }
+}

package/packages/shared-command-kit/src/define-action.ts

@@ -0,0 +1,100 @@
+/**
+ * Define a workflow action handler
+ */
+
+import type { PluginContextV3, CommandResult, HostContext } from '@kb-labs/plugin-contracts';
+
+export interface ActionHandler<TConfig = unknown, TInput = unknown> {
+  /**
+   * Execute the workflow action
+   */
+  execute(
+    context: PluginContextV3<TConfig>,
+    input: TInput
+  ): Promise<CommandResult | void> | CommandResult | void;
+
+  /**
+   * Optional cleanup - called after execute completes
+   */
+  cleanup?(): Promise<void> | void;
+}
+
+export interface ActionDefinition<TConfig = unknown, TInput = unknown> {
+  /**
+   * Action ID (e.g., "send-email")
+   */
+  id: string;
+
+  /**
+   * Action description
+   */
+  description?: string;
+
+  /**
+   * Handler implementation
+   */
+  handler: ActionHandler<TConfig, TInput>;
+
+  /**
+   * Optional input schema validation (future: use Zod/JSON Schema)
+   */
+  schema?: unknown;
+}
+
+/**
+ * Define a workflow action
+ *
+ * @example
+ * ```typescript
+ * export default defineAction({
+ *   id: 'send-email',
+ *   description: 'Send an email notification',
+ *   handler: {
+ *     async execute(context, input: { to: string; subject: string; body: string }) {
+ *       // Access workflow context
+ *       const { workflowId, runId, stepId } = context.hostContext as WorkflowHost;
+ *
+ *       context.ui.info(`Sending email in workflow ${workflowId}`);
+ *
+ *       // Send email...
+ *
+ *       return {
+ *         data: { sent: true, messageId: '123' },
+ *         exitCode: 0,
+ *       };
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export function defineAction<TConfig = unknown, TInput = unknown>(
+  definition: ActionDefinition<TConfig, TInput>
+): ActionHandler<TConfig, TInput> {
+  // Validate host type at runtime
+  const wrappedHandler: ActionHandler<TConfig, TInput> = {
+    execute: (context, input) => {
+      // Ensure we're running in workflow host
+      if (context.host !== 'workflow') {
+        throw new Error(
+          `Action ${definition.id} can only run in workflow host (current: ${context.host})`
+        );
+      }
+
+      // Call the actual handler
+      return definition.handler.execute(context, input);
+    },
+
+    cleanup: definition.handler.cleanup,
+  };
+
+  return wrappedHandler;
+}
+
+/**
+ * Type guard to check if host context is workflow
+ */
+export function isWorkflowHost(
+  hostContext: HostContext
+): hostContext is Extract<HostContext, { host: 'workflow' }> {
+  return hostContext.host === 'workflow';
+}