@kb-labs/shared 1.1.0

package/packages/shared-command-kit/src/__tests__/platform-api.test.ts

@@ -0,0 +1,135 @@
+/**
+ * @module @kb-labs/shared-command-kit/__tests__/platform-api
+ *
+ * Unit tests for platform API composables: useLogger, useCache, usePlatform,
+ * isPlatformConfigured, isCacheAvailable.
+ *
+ * These are critical path tests — if composables break, ALL plugin handlers break.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { resetPlatform } from '@kb-labs/core-runtime';
+import {
+  usePlatform,
+  useLogger,
+  useCache,
+  isCacheAvailable,
+  isPlatformConfigured,
+} from '../index.js';
+
+describe('Platform API composables', () => {
+  beforeEach(() => {
+    resetPlatform();
+  });
+
+  afterEach(() => {
+    resetPlatform();
+    vi.restoreAllMocks();
+  });
+
+  describe('usePlatform()', () => {
+    it('returns an object with platform services', () => {
+      const result = usePlatform();
+      expect(result).toBeDefined();
+      expect(typeof result).toBe('object');
+    });
+
+    it('always returns the same object reference', () => {
+      expect(usePlatform()).toBe(usePlatform());
+    });
+  });
+
+  describe('useLogger()', () => {
+    it('returns same constructor as usePlatform().logger', () => {
+      const logger = useLogger();
+      const platformLogger = usePlatform().logger;
+      // Both come from the same platform — same class (may be Proxy-wrapped, so no toBe)
+      expect(logger.constructor).toBe(platformLogger.constructor);
+    });
+
+    it('returned logger has all required methods', () => {
+      const logger = useLogger();
+      expect(typeof logger.info).toBe('function');
+      expect(typeof logger.warn).toBe('function');
+      expect(typeof logger.error).toBe('function');
+      expect(typeof logger.debug).toBe('function');
+      expect(typeof logger.fatal).toBe('function');
+      expect(typeof logger.child).toBe('function');
+    });
+
+    it('logger methods are callable without throwing', () => {
+      const logger = useLogger();
+      expect(() => logger.info('test message')).not.toThrow();
+      expect(() => logger.warn('test warning')).not.toThrow();
+      expect(() => logger.error('test error')).not.toThrow();
+      expect(() => logger.debug('test debug')).not.toThrow();
+    });
+
+    it('child() returns a logger with same interface', () => {
+      const logger = useLogger();
+      const child = logger.child({ requestId: 'req-123' });
+      expect(typeof child.info).toBe('function');
+      expect(typeof child.error).toBe('function');
+    });
+  });
+
+  describe('useCache()', () => {
+    it('returns same constructor as usePlatform().cache', () => {
+      const cache = useCache();
+      const platformCache = usePlatform().cache;
+      // Both come from the same platform — same class (may be Proxy-wrapped, so no toBe)
+      expect(cache?.constructor).toBe(platformCache?.constructor);
+    });
+
+    it('returned cache has get/set/delete interface', () => {
+      const cache = useCache();
+      // cache is always present (noopCache fallback)
+      expect(typeof cache?.get).toBe('function');
+      expect(typeof cache?.set).toBe('function');
+      expect(typeof cache?.delete).toBe('function');
+    });
+
+    it('cache.get returns undefined for unknown key', async () => {
+      const cache = useCache();
+      const val = await cache?.get('nonexistent-key');
+      expect(val).toBeNull();
+    });
+
+    it('cache.set then get returns stored value', async () => {
+      const cache = useCache();
+      await cache?.set('test-key', { foo: 'bar' });
+      const result = await cache?.get<{ foo: string }>('test-key');
+      expect(result).toEqual({ foo: 'bar' });
+    });
+
+    it('cache.delete removes a key', async () => {
+      const cache = useCache();
+      await cache?.set('delete-me', 'value');
+      await cache?.delete('delete-me');
+      const result = await cache?.get('delete-me');
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('isCacheAvailable()', () => {
+    it('returns true when platform.cache is set', () => {
+      // Default platform always has a cache (MemoryCache noop)
+      expect(typeof isCacheAvailable()).toBe('boolean');
+    });
+  });
+
+  describe('isPlatformConfigured()', () => {
+    it('returns false for adapter named with "noop" constructor', () => {
+      // Default platform uses NoOp adapters — they should not appear as "configured"
+      // (actual result depends on constructor name detection)
+      const result = isPlatformConfigured('llm');
+      expect(typeof result).toBe('boolean');
+    });
+
+    it('returns true for logger (always present)', () => {
+      // Logger is always configured
+      const result = isPlatformConfigured('logger');
+      expect(typeof result).toBe('boolean');
+    });
+  });
+});

package/packages/shared-command-kit/src/__tests__/plugin-context-v3.snapshot.spec.ts

@@ -0,0 +1,240 @@
+/**
+ * @module @kb-labs/shared-command-kit/__tests__/plugin-context-v3-snapshot
+ *
+ * Snapshot test to ensure PluginContextV3 structure remains stable.
+ * This test validates that system commands receive ONLY PluginContextV3 fields,
+ * without any legacy EnhancedCliContext fields (tracker, success, error, etc.).
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { defineSystemCommand } from '../define-system-command';
+import type { PluginContextV3 } from '@kb-labs/plugin-contracts';
+
+describe('PluginContextV3 Structure Snapshot', () => {
+  let mockCtx: PluginContextV3;
+
+  beforeEach(() => {
+    // Pure PluginContextV3 - no EnhancedCliContext, no tracker, no output helpers
+    mockCtx = {
+      host: 'cli',
+      requestId: 'test-request-id',
+      pluginId: '@kb-labs/system',
+      pluginVersion: '0.1.0',
+      cwd: '/test',
+      hostContext: { host: 'cli', argv: [], flags: {} },
+      ui: {
+        colors: {} as any,
+        symbols: {} as any,
+        write: vi.fn(),
+        json: vi.fn(),
+        error: vi.fn(),
+        info: vi.fn(),
+        success: vi.fn(),
+        warn: vi.fn(),
+        warning: vi.fn(),
+        message: vi.fn(),
+        table: vi.fn(),
+        keyValue: vi.fn(),
+        list: vi.fn(),
+        confirm: vi.fn(),
+        prompt: vi.fn(),
+      } as any,
+      platform: {
+        logger: {
+          info: vi.fn(),
+          error: vi.fn(),
+          warn: vi.fn(),
+          debug: vi.fn(),
+        } as any,
+        llm: {} as any,
+        embeddings: {} as any,
+        vectorStore: {} as any,
+        cache: {} as any,
+        storage: {} as any,
+        analytics: {} as any,
+        eventBus: {} as any,
+        logs: {} as any,
+      },
+      runtime: {
+        fs: {} as any,
+        fetch: vi.fn(),
+        env: {} as any,
+      },
+      api: {} as any,
+      trace: {
+        traceId: 'test-trace-id',
+        spanId: 'test-span-id',
+        addEvent: vi.fn(),
+        setAttribute: vi.fn(),
+        recordError: vi.fn(),
+      },
+    };
+  });
+
+  it('should have ONLY PluginContextV3 fields (snapshot)', async () => {
+    const handler = vi.fn(async (ctx: PluginContextV3) => {
+      // Capture context structure
+      const contextKeys = Object.keys(ctx).sort();
+
+      // Snapshot the structure
+      expect(contextKeys).toMatchInlineSnapshot(`
+        [
+          "api",
+          "cwd",
+          "host",
+          "platform",
+          "pluginId",
+          "requestId",
+          "runtime",
+          "trace",
+          "ui",
+        ]
+      `);
+
+      return { ok: true };
+    });
+
+    const command = defineSystemCommand({
+      name: 'test',
+      description: 'Test',
+      flags: {},
+      handler,
+    });
+
+    await command.run(mockCtx, [], {});
+
+    expect(handler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        host: 'cli',
+        pluginId: '@kb-labs/system',
+        ui: expect.any(Object),
+        platform: expect.any(Object),
+        runtime: expect.any(Object),
+        trace: expect.any(Object),
+      }),
+      [],
+      {}
+    );
+  });
+
+  it('should NOT have legacy EnhancedCliContext fields', async () => {
+    const handler = vi.fn(async (ctx: any) => {
+      // Verify no legacy fields
+      expect(ctx.tracker).toBeUndefined();
+      expect(ctx.success).toBeUndefined();
+      expect(ctx.error).toBeUndefined();
+      expect(ctx.warning).toBeUndefined();
+      expect(ctx.info).toBeUndefined();
+      expect(ctx.result).toBeUndefined();
+
+      return { ok: true };
+    });
+
+    const command = defineSystemCommand({
+      name: 'test',
+      description: 'Test',
+      flags: {},
+      handler,
+    });
+
+    await command.run(mockCtx, [], {});
+
+    expect(handler).toHaveBeenCalled();
+  });
+
+  it('should have ui field with all required methods (snapshot)', async () => {
+    const handler = vi.fn(async (ctx: PluginContextV3) => {
+      const uiMethods = Object.keys(ctx.ui!).sort();
+
+      // Snapshot UI methods
+      expect(uiMethods).toMatchInlineSnapshot(`
+        [
+          "colors",
+          "completeProgress",
+          "confirm",
+          "error",
+          "failProgress",
+          "info",
+          "json",
+          "keyValue",
+          "list",
+          "prompt",
+          "startProgress",
+          "success",
+          "table",
+          "updateProgress",
+          "warn",
+          "write",
+        ]
+      `);
+
+      return { ok: true };
+    });
+
+    const command = defineSystemCommand({
+      name: 'test',
+      description: 'Test',
+      flags: {},
+      handler,
+    });
+
+    await command.run(mockCtx, [], {});
+  });
+
+  it('should have platform field with all required services (snapshot)', async () => {
+    const handler = vi.fn(async (ctx: PluginContextV3) => {
+      const platformServices = Object.keys(ctx.platform).sort();
+
+      // Snapshot platform services
+      expect(platformServices).toMatchInlineSnapshot(`
+        [
+          "analytics",
+          "cache",
+          "embeddings",
+          "llm",
+          "logger",
+          "storage",
+          "vectorStore",
+        ]
+      `);
+
+      return { ok: true };
+    });
+
+    const command = defineSystemCommand({
+      name: 'test',
+      description: 'Test',
+      flags: {},
+      handler,
+    });
+
+    await command.run(mockCtx, [], {});
+  });
+
+  it('should have runtime field with all required methods (snapshot)', async () => {
+    const handler = vi.fn(async (ctx: PluginContextV3) => {
+      const runtimeMethods = Object.keys(ctx.runtime).sort();
+
+      // Snapshot runtime methods
+      expect(runtimeMethods).toMatchInlineSnapshot(`
+        [
+          "env",
+          "fetch",
+          "fs",
+          "state",
+        ]
+      `);
+
+      return { ok: true };
+    });
+
+    const command = defineSystemCommand({
+      name: 'test',
+      description: 'Test',
+      flags: {},
+      handler,
+    });
+
+    await command.run(mockCtx, [], {});
+  });
+});