@kb-labs/shared 1.1.0

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

@@ -0,0 +1,294 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { defineCommand } from '../index';
+
+describe('defineCommand', () => {
+  let mockCtx: any; // PluginContextV3
+  let mockUI: {
+    write: ReturnType<typeof vi.fn>;
+    json: ReturnType<typeof vi.fn>;
+    error: ReturnType<typeof vi.fn>;
+    info: ReturnType<typeof vi.fn>;
+    success: ReturnType<typeof vi.fn>;
+    warn: ReturnType<typeof vi.fn>;
+  };
+  let mockLogger: {
+    info: ReturnType<typeof vi.fn>;
+    error: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    mockUI = {
+      write: vi.fn(),
+      json: vi.fn(),
+      error: vi.fn(),
+      info: vi.fn(),
+      success: vi.fn(),
+      warn: vi.fn(),
+    };
+
+    mockLogger = {
+      info: vi.fn(),
+      error: vi.fn(),
+    };
+
+    // PluginContextV3 structure
+    mockCtx = {
+      host: 'cli',
+      requestId: 'test-request-id',
+      pluginId: '@kb-labs/test',
+      cwd: '/test',
+      ui: mockUI,
+      platform: {
+        logger: mockLogger as unknown as any,
+        llm: {} as any,
+        embeddings: {} as any,
+        vectorStore: {} as any,
+        cache: {} as any,
+        storage: {} as any,
+        analytics: {} as any,
+      },
+      runtime: {
+        fs: {} as any,
+        fetch: vi.fn(),
+        env: vi.fn(),
+      } as any,
+      api: {} as any,
+      trace: {
+        traceId: 'test-trace-id',
+        spanId: 'test-span-id',
+      },
+    };
+  });
+
+  it('should call handler with correct input (V3 API)', async () => {
+    const handler = vi.fn().mockResolvedValue({ exitCode: 0, ok: true, result: 'success' });
+
+    const command = defineCommand({
+      id: 'test:command',
+      description: 'Test command',
+      handler: {
+        execute: handler,
+      },
+    });
+
+    const result = await command.execute(mockCtx, { flags: { name: 'test' }, argv: [] });
+
+    expect(result.exitCode).toBe(0);
+    expect(result.exitCode).toBe(0);
+    expect(handler).toHaveBeenCalledOnce();
+    expect(handler.mock.calls[0]?.[0]).toBe(mockCtx);
+    expect(handler.mock.calls[0]?.[1]).toEqual({ flags: { name: 'test' }, argv: [] });
+  });
+
+  it('should enforce CLI host restriction', async () => {
+    const handler = vi.fn();
+
+    const command = defineCommand({
+      id: 'test:command',
+      description: 'Test command',
+      handler: {
+        execute: handler,
+      },
+    });
+
+    // Change host to REST
+    mockCtx.host = 'rest';
+
+    try {
+      await command.execute(mockCtx, { flags: {}, argv: [] });
+      expect.fail('Should have thrown an error');
+    } catch (error: any) {
+      expect(error.message).toContain('can only run in CLI or workflow host');
+    }
+
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('should allow workflow host', async () => {
+    const handler = vi.fn().mockResolvedValue({ exitCode: 0, ok: true });
+
+    const command = defineCommand({
+      id: 'test:command',
+      description: 'Test command',
+      handler: {
+        execute: handler,
+      },
+    });
+
+    // Change host to workflow
+    mockCtx.host = 'workflow';
+
+    const result = await command.execute(mockCtx, { flags: {}, argv: [] });
+
+    expect(result.exitCode).toBe(0);
+    expect(handler).toHaveBeenCalledOnce();
+  });
+
+  it('should handle handler returning number', async () => {
+    const handler = vi.fn().mockResolvedValue({ exitCode: 0, ok: true });
+
+    const command = defineCommand({
+      id: 'test:command',
+      description: 'Test command',
+      handler: {
+        execute: handler,
+      },
+    });
+
+    const result = await command.execute(mockCtx, { flags: {}, argv: [] });
+
+    expect(result.exitCode).toBe(0);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it('should handle handler returning object with ok', async () => {
+    const handler = vi.fn().mockResolvedValue({ exitCode: 0, ok: true, data: 'test' });
+
+    const command = defineCommand({
+      id: 'test:command',
+      description: 'Test command',
+      handler: {
+        execute: handler,
+      },
+    });
+
+    const result = await command.execute(mockCtx, { flags: {}, argv: [] });
+
+    expect(result.exitCode).toBe(0);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it('should handle errors in handler', async () => {
+    const handler = vi.fn().mockRejectedValue(new Error('Handler error'));
+
+    const command = defineCommand({
+      id: 'test:command',
+      description: 'Test command',
+      handler: {
+        execute: handler,
+      },
+    });
+
+    await expect(
+      command.execute(mockCtx, { flags: {}, argv: [] })
+    ).rejects.toThrow('Handler error');
+  });
+
+  it('should call cleanup if provided', async () => {
+    const handler = vi.fn().mockResolvedValue({ exitCode: 0, ok: true });
+    const cleanup = vi.fn().mockResolvedValue(undefined);
+
+    const command = defineCommand({
+      id: 'test:command',
+      description: 'Test command',
+      handler: {
+        execute: handler,
+        cleanup,
+      },
+    });
+
+    await command.execute(mockCtx, { flags: {}, argv: [] });
+
+    // Cleanup should be available
+    expect(command.cleanup).toBe(cleanup);
+
+    // Call cleanup manually
+    await command.cleanup!();
+    expect(cleanup).toHaveBeenCalledOnce();
+  });
+
+  it('should handle handler returning exit code 2', async () => {
+    const handler = vi.fn().mockResolvedValue({ exitCode: 2, ok: false });
+
+    const command = defineCommand({
+      id: 'test:command',
+      description: 'Test command',
+      handler: {
+        execute: handler,
+      },
+    });
+
+    const result = await command.execute(mockCtx, { flags: {}, argv: [] });
+
+    expect(result.exitCode).toBe(2);
+    expect(result.exitCode).not.toBe(0);
+  });
+
+  it('should handle handler returning object with ok: false', async () => {
+    const handler = vi.fn().mockResolvedValue({ exitCode: 1, ok: false });
+
+    const command = defineCommand({
+      id: 'test:command',
+      description: 'Test command',
+      handler: {
+        execute: handler,
+      },
+    });
+
+    const result = await command.execute(mockCtx, { flags: {}, argv: [] });
+
+    expect(result.exitCode).toBe(1);
+    expect(result.exitCode).not.toBe(0);
+  });
+
+  it('should pass through custom result fields', async () => {
+    const handler = vi.fn().mockResolvedValue({
+      exitCode: 0,
+      ok: true,
+      customField: 'custom-value',
+      data: { nested: 'data' },
+    });
+
+    const command = defineCommand({
+      id: 'test:command',
+      description: 'Test command',
+      handler: {
+        execute: handler,
+      },
+    });
+
+    const result = await command.execute(mockCtx, { flags: {}, argv: [] }) as any;
+
+    expect(result.exitCode).toBe(0);
+    expect(result.exitCode).toBe(0);
+    expect(result.customField).toBe('custom-value');
+    expect(result.data).toEqual({ nested: 'data' });
+  });
+
+  it('should work with async handlers', async () => {
+    const handler = vi.fn(async () => {
+      await new Promise<void>(resolve => { setTimeout(resolve, 10); });
+      return { exitCode: 0, ok: true };
+    });
+
+    const command = defineCommand({
+      id: 'test:command',
+      description: 'Test command',
+      handler: {
+        execute: handler,
+      },
+    });
+
+    const result = await command.execute(mockCtx, { flags: {}, argv: [] });
+
+    expect(result.exitCode).toBe(0);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it('should work with sync handlers', async () => {
+    const handler = vi.fn(() => ({ exitCode: 0, ok: true }));
+
+    const command = defineCommand({
+      id: 'test:command',
+      description: 'Test command',
+      handler: {
+        execute: handler,
+      },
+    });
+
+    const result = await command.execute(mockCtx, { flags: {}, argv: [] });
+
+    expect(result.exitCode).toBe(0);
+    expect(result.exitCode).toBe(0);
+  });
+});

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

@@ -0,0 +1,285 @@
+/**
+ * @file Unit tests for defineRoute
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { defineRoute, isRESTHost } from '../define-route.js';
+import type { PluginContextV3, RestHostContext } from '@kb-labs/plugin-contracts';
+
+describe('defineRoute', () => {
+  let mockContext: PluginContextV3<unknown>;
+  let mockLogger: any;
+
+  beforeEach(() => {
+    mockLogger = {
+      info: vi.fn(),
+      error: vi.fn(),
+      warn: vi.fn(),
+      debug: vi.fn(),
+    };
+
+    const restHostContext: RestHostContext = {
+      host: 'rest',
+      path: '/api/test',
+      method: 'POST',
+      headers: {},
+      requestId: 'req-123',
+      traceId: 'trace-123',
+    };
+
+    mockContext = {
+      host: 'rest',
+      hostContext: restHostContext,
+      ui: {} as any,
+      platform: {} as any,
+      config: {},
+    } as any;
+  });
+
+  describe('host validation', () => {
+    it('should throw error if host is not rest', async () => {
+      const handler = defineRoute({
+        path: '/api/test',
+        method: 'POST',
+        handler: {
+          async execute() {
+            return { data: {}, exitCode: 0 };
+          },
+        },
+      });
+
+      const invalidContext = {
+        ...mockContext,
+        host: 'cli' as const,
+        hostContext: { host: 'cli' as const } as any,
+      };
+
+      await expect(
+        handler.execute(invalidContext, {})
+      ).rejects.toThrow('can only run in REST host');
+    });
+
+    it('should throw error if HTTP method mismatch', async () => {
+      const handler = defineRoute({
+        path: '/api/test',
+        method: 'POST',
+        handler: {
+          async execute() {
+            return { data: {}, exitCode: 0 };
+          },
+        },
+      });
+
+      const wrongMethodContext = {
+        ...mockContext,
+        hostContext: {
+          ...mockContext.hostContext,
+          method: 'GET',
+        } as RestHostContext,
+      };
+
+      await expect(
+        handler.execute(wrongMethodContext, {})
+      ).rejects.toThrow('expects POST but got GET');
+    });
+
+    it('should be case-insensitive for HTTP methods', async () => {
+      const handler = defineRoute({
+        path: '/api/test',
+        method: 'post',
+        handler: {
+          async execute() {
+            return { data: {}, exitCode: 0 };
+          },
+        },
+      });
+
+      const upperCaseContext = {
+        ...mockContext,
+        hostContext: {
+          ...mockContext.hostContext,
+          method: 'POST',
+        } as RestHostContext,
+      };
+
+      await expect(
+        handler.execute(upperCaseContext, {})
+      ).resolves.toBeDefined();
+    });
+
+    it('should accept valid REST host context', async () => {
+      const execute = vi.fn(async () => ({ data: {}, exitCode: 0 }));
+
+      const handler = defineRoute({
+        path: '/api/test',
+        method: 'POST',
+        handler: { execute },
+      });
+
+      await handler.execute(mockContext, {});
+
+      expect(execute).toHaveBeenCalled();
+    });
+  });
+
+  describe('handler execution', () => {
+    it('should call execute with context and input', async () => {
+      const execute = vi.fn(async (ctx, input) => ({ data: { received: input }, exitCode: 0 }));
+
+      const handler = defineRoute({
+        path: '/api/test',
+        method: 'POST',
+        handler: { execute },
+      });
+
+      const input = { name: 'test' };
+      await handler.execute(mockContext, input);
+
+      expect(execute).toHaveBeenCalledWith(mockContext, input);
+    });
+
+    it('should return handler result', async () => {
+      const expectedResult = { data: { message: 'success' }, exitCode: 0 };
+
+      const handler = defineRoute({
+        path: '/api/test',
+        method: 'POST',
+        handler: {
+          async execute() {
+            return expectedResult;
+          },
+        },
+      });
+
+      const result = await handler.execute(mockContext, {});
+
+      expect(result).toEqual(expectedResult);
+    });
+
+    it('should handle void return from handler', async () => {
+      const handler = defineRoute({
+        path: '/api/test',
+        method: 'POST',
+        handler: {
+          async execute() {
+            // void return
+          },
+        },
+      });
+
+      const result = await handler.execute(mockContext, {});
+
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('cleanup', () => {
+    it('should call cleanup after successful execution', async () => {
+      const cleanup = vi.fn();
+
+      const handler = defineRoute({
+        path: '/api/test',
+        method: 'POST',
+        handler: {
+          async execute() {
+            return { data: {}, exitCode: 0 };
+          },
+          cleanup,
+        },
+      });
+
+      await handler.execute(mockContext, {});
+
+      expect(cleanup).toHaveBeenCalled();
+    });
+
+    it('should call cleanup even if handler throws', async () => {
+      const cleanup = vi.fn();
+
+      const handler = defineRoute({
+        path: '/api/test',
+        method: 'POST',
+        handler: {
+          async execute() {
+            throw new Error('Handler error');
+          },
+          cleanup,
+        },
+      });
+
+      await expect(handler.execute(mockContext, {})).rejects.toThrow('Handler error');
+
+      expect(cleanup).toHaveBeenCalled();
+    });
+
+    it('should not call cleanup if validation fails', async () => {
+      const cleanup = vi.fn();
+      const execute = vi.fn();
+
+      const handler = defineRoute({
+        path: '/api/test',
+        method: 'POST',
+        handler: {
+          execute,
+          cleanup,
+        },
+      });
+
+      const invalidContext = {
+        ...mockContext,
+        host: 'cli' as const,
+        hostContext: { host: 'cli' as const } as any,
+      };
+
+      await expect(handler.execute(invalidContext, {})).rejects.toThrow();
+
+      expect(cleanup).not.toHaveBeenCalled();
+      expect(execute).not.toHaveBeenCalled();
+    });
+
+    it('should propagate handler error after cleanup', async () => {
+      const cleanup = vi.fn();
+      const error = new Error('Handler error');
+
+      const handler = defineRoute({
+        path: '/api/test',
+        method: 'POST',
+        handler: {
+          async execute() {
+            throw error;
+          },
+          cleanup,
+        },
+      });
+
+      await expect(handler.execute(mockContext, {})).rejects.toThrow(error);
+
+      expect(cleanup).toHaveBeenCalled();
+    });
+  });
+});
+
+describe('isRESTHost', () => {
+  it('should return true for REST host context', () => {
+    const restContext: RestHostContext = {
+      host: 'rest',
+      path: '/api/test',
+      method: 'POST',
+      headers: {},
+      requestId: 'req-123',
+      traceId: 'trace-123',
+    };
+
+    expect(isRESTHost(restContext)).toBe(true);
+  });
+
+  it('should return false for non-REST host context', () => {
+    const cliContext = {
+      host: 'cli' as const,
+      argv: [],
+      flags: {},
+    };
+
+    expect(isRESTHost(cliContext)).toBe(false);
+  });
+});