@kb-labs/shared 1.1.0

package/packages/shared-command-kit/src/__tests__/define-websocket.test.ts

@@ -0,0 +1,316 @@
+/**
+ * @file Unit tests for defineWebSocket and message validation
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { defineWebSocket, isWSHost } from '../define-websocket.js';
+import type { PluginContextV3, WebSocketHostContext, WSInput, WSSender } from '@kb-labs/plugin-contracts';
+
+describe('defineWebSocket', () => {
+  let mockContext: PluginContextV3<unknown>;
+  let mockSender: WSSender;
+  let mockLogger: any;
+
+  beforeEach(() => {
+    mockLogger = {
+      info: vi.fn(),
+      error: vi.fn(),
+      warn: vi.fn(),
+      debug: vi.fn(),
+    };
+
+    const wsHostContext: WebSocketHostContext = {
+      host: 'ws',
+      channelPath: '/test',
+      connectionId: 'conn-123',
+      clientIp: '127.0.0.1',
+      headers: {},
+      requestId: 'req-123',
+      traceId: 'trace-123',
+    };
+
+    mockContext = {
+      host: 'ws',
+      hostContext: wsHostContext,
+      ui: {} as any,
+      platform: {
+        logger: mockLogger,
+      } as any,
+      config: {},
+    } as any;
+
+    mockSender = {
+      send: vi.fn(),
+      broadcast: vi.fn(),
+      sendTo: vi.fn(),
+      close: vi.fn(),
+      getConnectionId: vi.fn(() => 'conn-123'),
+    };
+  });
+
+  describe('host validation', () => {
+    it('should throw error if host is not ws', async () => {
+      const handler = defineWebSocket({
+        path: '/test',
+        handler: {
+          async onConnect() {},
+        },
+      });
+
+      const invalidContext = {
+        ...mockContext,
+        host: 'cli' as const,
+        hostContext: { host: 'cli' as const } as any,
+      };
+
+      const input: WSInput = { event: 'connect', sender: mockSender };
+
+      await expect(
+        handler.execute(invalidContext, input)
+      ).rejects.toThrow('can only run in ws host');
+    });
+
+    it('should throw error if channel path mismatch', async () => {
+      const handler = defineWebSocket({
+        path: '/expected',
+        handler: {
+          async onConnect() {},
+        },
+      });
+
+      const wrongPathContext = {
+        ...mockContext,
+        hostContext: {
+          ...mockContext.hostContext,
+          channelPath: '/wrong',
+        } as WebSocketHostContext,
+      };
+
+      const input: WSInput = { event: 'connect', sender: mockSender };
+
+      await expect(
+        handler.execute(wrongPathContext, input)
+      ).rejects.toThrow('expects channel /expected but got /wrong');
+    });
+
+    it('should throw error if sender not provided for connect event', async () => {
+      const handler = defineWebSocket({
+        path: '/test',
+        handler: {
+          async onConnect() {},
+        },
+      });
+
+      const input: WSInput = { event: 'connect' }; // no sender
+
+      await expect(
+        handler.execute(mockContext, input)
+      ).rejects.toThrow('WebSocket sender not provided in input');
+    });
+
+    it('should accept valid ws host context with sender', async () => {
+      const onConnect = vi.fn();
+
+      const handler = defineWebSocket({
+        path: '/test',
+        handler: { onConnect },
+      });
+
+      const input: WSInput = { event: 'connect', sender: mockSender };
+
+      await handler.execute(mockContext, input);
+
+      expect(onConnect).toHaveBeenCalled();
+    });
+  });
+
+  describe('message validation', () => {
+    it('should validate message structure', async () => {
+      const onMessage = vi.fn();
+
+      const handler = defineWebSocket({
+        path: '/test',
+        handler: { onMessage },
+      });
+
+      const validMessage = {
+        type: 'test',
+        payload: { data: 'hello' },
+        timestamp: Date.now(),
+      };
+
+      const input: WSInput = {
+        event: 'message',
+        message: validMessage,
+        sender: mockSender,
+      };
+
+      await handler.execute(mockContext, input);
+
+      expect(onMessage).toHaveBeenCalled();
+      expect(mockLogger.error).not.toHaveBeenCalled();
+    });
+
+    it('should reject message without type field', async () => {
+      const onMessage = vi.fn();
+
+      const handler = defineWebSocket({
+        path: '/test',
+        handler: { onMessage },
+      });
+
+      const invalidMessage = {
+        payload: { data: 'hello' },
+        timestamp: Date.now(),
+      } as any;
+
+      const input: WSInput = {
+        event: 'message',
+        message: invalidMessage,
+        sender: mockSender,
+      };
+
+      await handler.execute(mockContext, input);
+
+      expect(onMessage).not.toHaveBeenCalled();
+      expect(mockContext.platform.logger.error).toHaveBeenCalled();
+      expect(mockSender.send).toHaveBeenCalledWith({
+        type: 'error',
+        payload: { error: 'Invalid message format' },
+        timestamp: expect.any(Number),
+      });
+    });
+
+    it('should reject message with empty type', async () => {
+      const onMessage = vi.fn();
+
+      const handler = defineWebSocket({
+        path: '/test',
+        handler: { onMessage },
+      });
+
+      const invalidMessage = {
+        type: '',
+        payload: {},
+        timestamp: Date.now(),
+      };
+
+      const input: WSInput = {
+        event: 'message',
+        message: invalidMessage,
+        sender: mockSender,
+      };
+
+      await handler.execute(mockContext, input);
+
+      expect(onMessage).not.toHaveBeenCalled();
+      expect(mockLogger.error).toHaveBeenCalled();
+    });
+  });
+
+  describe('lifecycle events', () => {
+    it('should call onConnect handler', async () => {
+      const onConnect = vi.fn();
+
+      const handler = defineWebSocket({
+        path: '/test',
+        handler: { onConnect },
+      });
+
+      const input: WSInput = { event: 'connect', sender: mockSender };
+
+      await handler.execute(mockContext, input);
+
+      expect(onConnect).toHaveBeenCalled();
+    });
+
+    it('should call onDisconnect handler without sender', async () => {
+      const onDisconnect = vi.fn();
+
+      const handler = defineWebSocket({
+        path: '/test',
+        handler: { onDisconnect },
+      });
+
+      // disconnect event doesn't need sender
+      const input: WSInput = {
+        event: 'disconnect',
+        disconnectCode: 1000,
+        disconnectReason: 'Normal closure',
+      };
+
+      await handler.execute(mockContext, input);
+
+      expect(onDisconnect).toHaveBeenCalledWith(mockContext, 1000, 'Normal closure');
+    });
+  });
+
+  describe('cleanup', () => {
+    it('should call cleanup after successful execution', async () => {
+      const cleanup = vi.fn();
+
+      const handler = defineWebSocket({
+        path: '/test',
+        handler: {
+          async onConnect() {},
+          cleanup,
+        },
+      });
+
+      const input: WSInput = { event: 'connect', sender: mockSender };
+
+      await handler.execute(mockContext, input);
+
+      expect(cleanup).toHaveBeenCalled();
+    });
+
+    it('should call cleanup even if handler throws', async () => {
+      const cleanup = vi.fn();
+
+      const handler = defineWebSocket({
+        path: '/test',
+        handler: {
+          async onMessage() {
+            throw new Error('Handler error');
+          },
+          cleanup,
+        },
+      });
+
+      const message = { type: 'test', payload: {}, timestamp: Date.now() };
+      const input: WSInput = { event: 'message', message, sender: mockSender };
+
+      await expect(handler.execute(mockContext, input)).rejects.toThrow(
+        'Handler error'
+      );
+
+      expect(cleanup).toHaveBeenCalled();
+    });
+  });
+});
+
+describe('isWSHost', () => {
+  it('should return true for ws host context', () => {
+    const wsContext: WebSocketHostContext = {
+      host: 'ws',
+      channelPath: '/test',
+      connectionId: 'conn-123',
+      clientIp: '127.0.0.1',
+      headers: {},
+      requestId: 'req-123',
+      traceId: 'trace-123',
+    };
+
+    expect(isWSHost(wsContext)).toBe(true);
+  });
+
+  it('should return false for non-ws host context', () => {
+    const cliContext = {
+      host: 'cli' as const,
+      argv: [],
+      flags: {},
+    };
+
+    expect(isWSHost(cliContext)).toBe(false);
+  });
+});

package/packages/shared-command-kit/src/__tests__/errors.spec.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import { formatError } from '../errors/index';
+
+describe('formatError', () => {
+  it('should format Error object', () => {
+    const error = new Error('Something went wrong');
+    const formatted = formatError(error);
+
+    expect(formatted.message).toBe('Something went wrong');
+    expect(formatted.json.ok).toBe(false);
+    expect(formatted.json.error).toBe('Something went wrong');
+  });
+
+  it('should format string error', () => {
+    const formatted = formatError('String error');
+
+    expect(formatted.message).toBe('String error');
+    expect(formatted.json.error).toBe('String error');
+  });
+
+  it('should include stack trace when showStack is true', () => {
+    const error = new Error('Test error');
+    const formatted = formatError(error, { showStack: true });
+
+    expect(formatted.message).toContain('Test error');
+    expect(formatted.message).toContain('Error: Test error');
+    expect(formatted.json.stack).toBeDefined();
+  });
+
+  it('should include timing when provided', () => {
+    const error = new Error('Test error');
+    const formatted = formatError(error, { timingMs: 1234 });
+
+    expect(formatted.json.timingMs).toBe(1234);
+  });
+
+  it('should not include stack when showStack is false', () => {
+    const error = new Error('Test error');
+    const formatted = formatError(error, { showStack: false });
+
+    expect(formatted.message).toBe('Test error');
+    expect(formatted.json.stack).toBeUndefined();
+  });
+});
+

package/packages/shared-command-kit/src/__tests__/flags.spec.ts

@@ -0,0 +1,353 @@
+import { describe, it, expect } from 'vitest';
+import { defineFlags, validateFlags, validateFlagsSafe, FlagValidationError } from '../flags/index';
+
+describe('defineFlags', () => {
+  it('should create flag schema with type inference', () => {
+    const schema = defineFlags({
+      scope: {
+        type: 'string',
+        required: true,
+      },
+      'dry-run': {
+        type: 'boolean',
+        default: false,
+      },
+    });
+
+    expect(schema.schema).toBeDefined();
+    expect(schema.schema.scope).toBeDefined();
+    expect(schema.schema['dry-run']).toBeDefined();
+  });
+});
+
+describe('validateFlags', () => {
+  it('should validate boolean flags', async () => {
+    const schema = defineFlags({
+      verbose: { type: 'boolean', default: false },
+      quiet: { type: 'boolean' },
+    });
+
+    const flags = await validateFlags({ verbose: true, quiet: false }, schema);
+    expect(flags.verbose).toBe(true);
+    expect(flags.quiet).toBe(false);
+  });
+
+  it('should validate string flags', async () => {
+    const schema = defineFlags({
+      name: { type: 'string', required: true },
+      format: { type: 'string', default: 'json' },
+    });
+
+    const flags = await validateFlags({ name: 'test', format: 'yaml' }, schema);
+    expect(flags.name).toBe('test');
+    expect(flags.format).toBe('yaml');
+  });
+
+  it('should validate number flags', async () => {
+    const schema = defineFlags({
+      limit: { type: 'number', min: 1, max: 100, default: 10 },
+      port: { type: 'number' },
+    });
+
+    const flags = await validateFlags({ limit: 50, port: 8080 }, schema);
+    expect(flags.limit).toBe(50);
+    expect(flags.port).toBe(8080);
+  });
+
+  it('should validate array flags', async () => {
+    const schema = defineFlags({
+      tags: { type: 'array', items: 'string' },
+      numbers: { type: 'array', items: 'number' },
+    });
+
+    const flags = await validateFlags(
+      { tags: ['a', 'b'], numbers: [1, 2, 3] },
+      schema
+    );
+    expect(flags.tags).toEqual(['a', 'b']);
+    expect(flags.numbers).toEqual([1, 2, 3]);
+  });
+
+  it('should apply default values', async () => {
+    const schema = defineFlags({
+      verbose: { type: 'boolean', default: false },
+      limit: { type: 'number', default: 10 },
+      format: { type: 'string', default: 'json' },
+    });
+
+    const flags = await validateFlags({}, schema);
+    expect(flags.verbose).toBe(false);
+    expect(flags.limit).toBe(10);
+    expect(flags.format).toBe('json');
+  });
+
+  it('should throw error for required flags', async () => {
+    const schema = defineFlags({
+      name: { type: 'string', required: true },
+    });
+
+    await expect(validateFlags({}, schema)).rejects.toThrow(FlagValidationError);
+  });
+
+  it('should validate choices', async () => {
+    const schema = defineFlags({
+      format: {
+        type: 'string',
+        choices: ['json', 'yaml', 'toml'] as const,
+      },
+    });
+
+    const flags = await validateFlags({ format: 'json' }, schema);
+    expect(flags.format).toBe('json');
+
+    await expect(validateFlags({ format: 'xml' }, schema)).rejects.toThrow();
+  });
+
+  it('should validate pattern', async () => {
+    const schema = defineFlags({
+      scope: {
+        type: 'string',
+        pattern: /^[@a-z0-9-/]+$/i,
+      },
+    });
+
+    const flags = await validateFlags({ scope: '@my-org/package' }, schema);
+    expect(flags.scope).toBe('@my-org/package');
+
+    await expect(validateFlags({ scope: 'invalid scope!' }, schema)).rejects.toThrow();
+  });
+
+  it('should validate min/max for numbers', async () => {
+    const schema = defineFlags({
+      limit: { type: 'number', min: 1, max: 100 },
+    });
+
+    await expect(validateFlags({ limit: 0 }, schema)).rejects.toThrow();
+    await expect(validateFlags({ limit: 101 }, schema)).rejects.toThrow();
+    
+    const flags = await validateFlags({ limit: 50 }, schema);
+    expect(flags.limit).toBe(50);
+  });
+
+  it('should coerce string to boolean', async () => {
+    const schema = defineFlags({
+      verbose: { type: 'boolean' },
+    });
+
+    const flags1 = await validateFlags({ verbose: 'true' }, schema);
+    expect(flags1.verbose).toBe(true);
+
+    const flags2 = await validateFlags({ verbose: 'false' }, schema);
+    expect(flags2.verbose).toBe(false);
+  });
+
+  it('should coerce string to number', async () => {
+    const schema = defineFlags({
+      limit: { type: 'number' },
+    });
+
+    const flags = await validateFlags({ limit: '42' }, schema);
+    expect(flags.limit).toBe(42);
+  });
+
+  it('should coerce comma-separated string to array', async () => {
+    const schema = defineFlags({
+      tags: { type: 'array', items: 'string' },
+    });
+
+    const flags = await validateFlags({ tags: 'a,b,c' }, schema);
+    expect(flags.tags).toEqual(['a', 'b', 'c']);
+  });
+});
+
+describe('validateFlagsSafe', () => {
+  it('should return success result for valid flags', async () => {
+    const schema = defineFlags({
+      name: { type: 'string', required: true },
+    });
+
+    const result = await validateFlagsSafe({ name: 'test' }, schema);
+    expect(result.success).toBe(true);
+    expect(result.data).toBeDefined();
+    expect(result.data?.name).toBe('test');
+    expect(result.errors).toEqual([]);
+  });
+
+  it('should return error result for invalid flags', async () => {
+    const schema = defineFlags({
+      name: { type: 'string', required: true },
+    });
+
+    const result = await validateFlagsSafe({}, schema);
+    expect(result.success).toBe(false);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0]?.flag).toBe('name');
+  });
+});
+
+describe('validateFlags - advanced features', () => {
+  it('should validate conflicts', async () => {
+    const schema = defineFlags({
+      verbose: { type: 'boolean', conflicts: ['quiet'] },
+      quiet: { type: 'boolean', conflicts: ['verbose'] },
+    });
+
+    await expect(
+      validateFlags({ verbose: true, quiet: true }, schema)
+    ).rejects.toThrow();
+  });
+
+  it('should validate dependsOn', async () => {
+    const schema = defineFlags({
+      output: { type: 'string', dependsOn: ['format'] },
+      format: { type: 'string' },
+    });
+
+    await expect(
+      validateFlags({ output: 'file.txt' }, schema)
+    ).rejects.toThrow();
+
+    const flags = await validateFlags(
+      { output: 'file.txt', format: 'json' },
+      schema
+    );
+    expect(flags.output).toBe('file.txt');
+  });
+
+  it('should validate implies', async () => {
+    const schema = defineFlags({
+      verbose: { type: 'boolean', implies: ['debug'] },
+      debug: { type: 'boolean' },
+    });
+
+    const flags = await validateFlags({ verbose: true }, schema);
+    expect(flags.debug).toBe(true);
+  });
+
+  it('should apply custom validator', async () => {
+    const schema = defineFlags({
+      port: {
+        type: 'number',
+        validate: (value: number) => {
+          if (value < 1024 || value > 65535) {
+            return 'Port must be between 1024 and 65535';
+          }
+          return true;
+        },
+      },
+    });
+
+    await expect(validateFlags({ port: 80 }, schema)).rejects.toThrow();
+    await expect(validateFlags({ port: 70000 }, schema)).rejects.toThrow();
+
+    const flags = await validateFlags({ port: 8080 }, schema);
+    expect(flags.port).toBe(8080);
+  });
+
+  it('should apply async custom validator', async () => {
+    const schema = defineFlags({
+      name: {
+        type: 'string',
+        validate: async (value: string) => {
+          // Simulate async check
+          await new Promise<void>((resolve) => { setTimeout(resolve, 10); });
+          if (value.length < 3) {
+            return 'Name must be at least 3 characters';
+          }
+          return true;
+        },
+      },
+    });
+
+    await expect(validateFlags({ name: 'ab' }, schema)).rejects.toThrow();
+
+    const flags = await validateFlags({ name: 'test' }, schema);
+    expect(flags.name).toBe('test');
+  });
+
+  it('should apply transform', async () => {
+    const schema = defineFlags({
+      name: {
+        type: 'string',
+        transform: (value: string) => value.toUpperCase(),
+      },
+    });
+
+    const flags = await validateFlags({ name: 'test' }, schema);
+    expect(flags.name).toBe('TEST');
+  });
+
+  it('should apply async transform', async () => {
+    const schema = defineFlags({
+      name: {
+        type: 'string',
+        transform: async (value: string) => {
+          await new Promise<void>((resolve) => { setTimeout(resolve, 10); });
+          return value.trim().toLowerCase();
+        },
+      },
+    });
+
+    const flags = await validateFlags({ name: '  TEST  ' }, schema);
+    expect(flags.name).toBe('test');
+  });
+
+  it('should validate array minLength', async () => {
+    const schema = defineFlags({
+      tags: {
+        type: 'array',
+        items: 'string',
+        minLength: 2,
+      },
+    });
+
+    await expect(validateFlags({ tags: ['a'] }, schema)).rejects.toThrow();
+
+    const flags = await validateFlags({ tags: ['a', 'b'] }, schema);
+    expect(flags.tags).toEqual(['a', 'b']);
+  });
+
+  it('should validate array maxLength', async () => {
+    const schema = defineFlags({
+      tags: {
+        type: 'array',
+        items: 'string',
+        maxLength: 2,
+      },
+    });
+
+    await expect(validateFlags({ tags: ['a', 'b', 'c'] }, schema)).rejects.toThrow();
+
+    const flags = await validateFlags({ tags: ['a', 'b'] }, schema);
+    expect(flags.tags).toEqual(['a', 'b']);
+  });
+
+  it('should validate string minLength', async () => {
+    const schema = defineFlags({
+      name: {
+        type: 'string',
+        minLength: 3,
+      },
+    });
+
+    await expect(validateFlags({ name: 'ab' }, schema)).rejects.toThrow();
+
+    const flags = await validateFlags({ name: 'abc' }, schema);
+    expect(flags.name).toBe('abc');
+  });
+
+  it('should validate string maxLength', async () => {
+    const schema = defineFlags({
+      name: {
+        type: 'string',
+        maxLength: 5,
+      },
+    });
+
+    await expect(validateFlags({ name: 'abcdef' }, schema)).rejects.toThrow();
+
+    const flags = await validateFlags({ name: 'abc' }, schema);
+    expect(flags.name).toBe('abc');
+  });
+});
+