@littlebearapps/platform-admin-sdk 2.0.0 → 2.1.0

package/templates/shared/tests/helpers/mock-storage.ts

@@ -0,0 +1,166 @@
+type StatementRecord = { sql: string; params: unknown[] };
+
+type QueuedResult = {
+  type: 'first';
+  value: Record<string, unknown> | null;
+};
+
+type QueuedRunResult = {
+  type: 'run';
+  value: { success: boolean; results?: unknown[] };
+};
+
+type QueuedAllResult = {
+  type: 'all';
+  value: { results: unknown[] };
+};
+
+class MockPreparedStatement {
+  private boundParams: unknown[] = [];
+
+  constructor(
+    private readonly db: MockD1Database,
+    private readonly sql: string
+  ) {}
+
+  bind(...params: unknown[]): MockPreparedStatement {
+    this.boundParams = params;
+    return this;
+  }
+
+  async run(): Promise<{ success: boolean; results?: unknown[] }> {
+    this.db.statements.push({ sql: this.sql, params: this.boundParams });
+    const queued = this.db.dequeueResult('run');
+    return queued?.value ?? { success: true, results: [] };
+  }
+
+  async first<T = Record<string, unknown>>(): Promise<T | null> {
+    this.db.statements.push({ sql: this.sql, params: this.boundParams });
+    const queued = this.db.dequeueResult('first');
+    return (queued?.value as T | null) ?? null;
+  }
+
+  async all<T = Record<string, unknown>>(): Promise<{ results: T[] }> {
+    this.db.statements.push({ sql: this.sql, params: this.boundParams });
+    const queued = this.db.dequeueResult('all');
+    return (queued?.value as { results: T[] }) ?? { results: [] as T[] };
+  }
+}
+
+export class MockD1Database {
+  statements: StatementRecord[] = [];
+  private queuedResults: Array<QueuedResult | QueuedRunResult | QueuedAllResult> = [];
+
+  prepare(query: string): MockPreparedStatement {
+    return new MockPreparedStatement(this, query);
+  }
+
+  // These methods are required for the SDK's isD1Database type guard.
+  // Without them, the SDK wraps all methods in async circuit-breaker wrappers,
+  // which breaks the mock's synchronous dequeueResult/queueFirstResult methods.
+  async batch(_statements: unknown[]): Promise<unknown[]> {
+    return [];
+  }
+
+  // D1Database.exec method stub
+  async execBatch(_query: string): Promise<unknown> {
+    return { count: 0 };
+  }
+
+  // Alias for the SDK type guard check (expects 'exec' property)
+  get exec(): (_query: string) => Promise<unknown> {
+    return this.execBatch.bind(this);
+  }
+
+  queueFirstResult(value: Record<string, unknown> | null): void {
+    this.queuedResults.push({ type: 'first', value });
+  }
+
+  queueRunResult(value: { success: boolean; results?: unknown[] }): void {
+    this.queuedResults.push({ type: 'run', value });
+  }
+
+  queueAllResult(value: { results: unknown[] }): void {
+    this.queuedResults.push({ type: 'all', value });
+  }
+
+  dequeueResult(type: 'first'): QueuedResult | undefined;
+  dequeueResult(type: 'run'): QueuedRunResult | undefined;
+  dequeueResult(type: 'all'): QueuedAllResult | undefined;
+  dequeueResult(
+    type: 'first' | 'run' | 'all'
+  ): QueuedResult | QueuedRunResult | QueuedAllResult | undefined {
+    const index = this.queuedResults.findIndex((item) => item.type === type);
+    if (index === -1) {
+      return undefined;
+    }
+
+    return this.queuedResults.splice(index, 1)[0];
+  }
+}
+
+export class MockKVNamespace {
+  store = new Map<string, string>();
+
+  async get(_key: string): Promise<string | null> {
+    return null;
+  }
+
+  async put(key: string, value: string, _options?: unknown): Promise<void> {
+    this.store.set(key, value);
+  }
+
+  async delete(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+
+  async list(): Promise<{ keys: string[]; list_complete: boolean }> {
+    return { keys: [], list_complete: true };
+  }
+}
+
+export class MockR2Bucket {
+  objects = new Map<string, string>();
+
+  async put(key: string, value: string): Promise<void> {
+    this.objects.set(key, value);
+  }
+
+  async delete(key: string | string[]): Promise<void> {
+    if (Array.isArray(key)) {
+      key.forEach((k) => this.objects.delete(k));
+    } else {
+      this.objects.delete(key);
+    }
+  }
+}
+
+export class MockQueue {
+  messages: unknown[] = [];
+
+  async send(message: unknown): Promise<void> {
+    this.messages.push(message);
+  }
+
+  async sendBatch(messages: unknown[]): Promise<void> {
+    this.messages.push(...messages);
+  }
+}
+
+export type GitHubMonitorEnv = {
+  PLATFORM_DB: MockD1Database;
+  PLATFORM_CACHE: MockKVNamespace;
+  PLATFORM_ARCHIVES: MockR2Bucket;
+  PLATFORM_TELEMETRY: MockQueue;
+  GITHUB_WEBHOOK_SECRET: string;
+};
+
+export function createGitHubMonitorEnv(secret = 'test-secret'): GitHubMonitorEnv {
+  return {
+    PLATFORM_DB: new MockD1Database(),
+    PLATFORM_CACHE: new MockKVNamespace(),
+    PLATFORM_ARCHIVES: new MockR2Bucket(),
+    PLATFORM_TELEMETRY: new MockQueue(),
+    GITHUB_WEBHOOK_SECRET: secret,
+  };
+}

package/templates/shared/tests/integration/kv-cache.test.ts

@@ -0,0 +1,252 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  cacheData,
+  getCachedData,
+  getOrCompute,
+  getStoredData,
+  invalidateCache,
+  putWithMetadata,
+  shouldSendAlert,
+  type KVNamespaceLike,
+} from '../../storage/kv/cache';
+import {
+  getCircuitBreakerState,
+  incrementHopCount,
+  isServiceAllowed,
+  recordFailure,
+  recordSuccess,
+  resetCircuitBreaker,
+  updateCircuitBreakerState,
+} from '../../storage/kv/circuit-breaker';
+
+function createMockKV(): KVNamespaceLike & {
+  get: ReturnType<typeof vi.fn>;
+  put: ReturnType<typeof vi.fn>;
+  delete: ReturnType<typeof vi.fn>;
+} {
+  return {
+    get: vi.fn(),
+    put: vi.fn(),
+    delete: vi.fn(),
+  } as unknown as KVNamespaceLike & {
+    get: ReturnType<typeof vi.fn>;
+    put: ReturnType<typeof vi.fn>;
+    delete: ReturnType<typeof vi.fn>;
+  };
+}
+
+describe('KV Cache helpers', () => {
+  let mockKV: ReturnType<typeof createMockKV>;
+
+  beforeEach(() => {
+    mockKV = createMockKV();
+  });
+
+  describe('Alert deduplication', () => {
+    it('allows first alert and stores marker', async () => {
+      mockKV.get.mockResolvedValue(null);
+
+      const result = await shouldSendAlert('test-alert', mockKV);
+
+      expect(result).toBe(true);
+      expect(mockKV.put).toHaveBeenCalledWith(
+        'alert:test-alert',
+        expect.any(String),
+        expect.objectContaining({ expirationTtl: 3600 })
+      );
+    });
+
+    it('suppresses duplicate alerts within TTL window', async () => {
+      mockKV.get.mockResolvedValue('already-sent');
+
+      const result = await shouldSendAlert('duplicate-alert', mockKV);
+
+      expect(result).toBe(false);
+      expect(mockKV.put).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Cache primitives', () => {
+    it('stores hot data with default TTL', async () => {
+      await cacheData('mrr', { value: 100 }, mockKV);
+      expect(mockKV.put).toHaveBeenCalledWith(
+        'cache:mrr',
+        JSON.stringify({ value: 100 }),
+        expect.objectContaining({ expirationTtl: 900 })
+      );
+    });
+
+    it('retrieves cached data and parses JSON', async () => {
+      mockKV.get.mockResolvedValue(JSON.stringify({ foo: 'bar' }));
+
+      const cached = await getCachedData<{ foo: string }>('demo', mockKV);
+
+      expect(cached).toEqual({ foo: 'bar' });
+      expect(mockKV.get).toHaveBeenCalledWith('cache:demo');
+    });
+
+    it('supports getOrCompute pattern with cache miss', async () => {
+      mockKV.get.mockResolvedValueOnce(null);
+      const compute = vi.fn().mockResolvedValue({ total: 42 });
+
+      const result = await getOrCompute('report', compute, mockKV, 120);
+
+      expect(compute).toHaveBeenCalledTimes(1);
+      expect(mockKV.put).toHaveBeenCalledWith(
+        'cache:report',
+        JSON.stringify({ total: 42 }),
+        expect.objectContaining({ expirationTtl: 120 })
+      );
+      expect(result).toEqual({ total: 42 });
+    });
+
+    it('returns cached value when available without recomputing', async () => {
+      mockKV.get.mockResolvedValue(JSON.stringify({ total: 99 }));
+      const compute = vi.fn();
+
+      const result = await getOrCompute('report', compute, mockKV);
+
+      expect(compute).not.toHaveBeenCalled();
+      expect(result).toEqual({ total: 99 });
+    });
+
+    it('invalidates cached entries', async () => {
+      await invalidateCache('stale', mockKV);
+      expect(mockKV.delete).toHaveBeenCalledWith('cache:stale');
+    });
+
+    it('stores and retrieves arbitrary data payloads', async () => {
+      mockKV.get.mockResolvedValue(JSON.stringify({ state: 'ok' }));
+
+      await putWithMetadata('status', { state: 'ok' }, mockKV, {
+        ttl: 30,
+        metadata: { scope: 'demo' },
+      });
+      expect(mockKV.put).toHaveBeenCalledWith(
+        'data:status',
+        JSON.stringify({ state: 'ok' }),
+        expect.objectContaining({ expirationTtl: 30, metadata: { scope: 'demo' } })
+      );
+
+      const retrieved = await getStoredData<{ state: string }>('status', mockKV);
+      expect(retrieved).toEqual({ state: 'ok' });
+    });
+  });
+
+  describe('Circuit breaker integration', () => {
+    it('returns default state when none persisted', async () => {
+      mockKV.get.mockResolvedValue(null);
+
+      const state = await getCircuitBreakerState('cloakpipe', mockKV);
+
+      expect(state).toMatchObject({
+        hop_count: 0,
+        cooldown: false,
+        kill_switch: false,
+        consecutive_failures: 0,
+      });
+    });
+
+    it('updates stored state when incrementing hop count', async () => {
+      mockKV.get.mockResolvedValue(
+        JSON.stringify({
+          hop_count: 1,
+          cooldown: false,
+          kill_switch: false,
+          last_updated: '2025-10-25T10:00:00Z',
+          consecutive_failures: 0,
+        })
+      );
+
+      const state = await incrementHopCount('cloakpipe', mockKV, 3);
+
+      expect(state.hop_count).toBe(2);
+      expect(mockKV.put).toHaveBeenCalled();
+    });
+
+    it('trips circuit breaker when hop count exceeds limit', async () => {
+      mockKV.get.mockResolvedValue(
+        JSON.stringify({
+          hop_count: 2,
+          cooldown: false,
+          kill_switch: false,
+          last_updated: '2025-10-25T10:00:00Z',
+          consecutive_failures: 0,
+        })
+      );
+
+      const state = await incrementHopCount('homeostat', mockKV, 3);
+
+      expect(state.cooldown).toBe(true);
+    });
+
+    it('blocks service when kill switch active', async () => {
+      mockKV.get.mockResolvedValue(
+        JSON.stringify({
+          hop_count: 0,
+          cooldown: false,
+          kill_switch: true,
+          consecutive_failures: 0,
+        })
+      );
+
+      const allowed = await isServiceAllowed('gatekeeper', mockKV);
+      expect(allowed).toBe(false);
+    });
+
+    it('records failures and trips when threshold reached', async () => {
+      mockKV.get.mockResolvedValue(
+        JSON.stringify({
+          hop_count: 0,
+          cooldown: false,
+          kill_switch: false,
+          consecutive_failures: 4,
+        })
+      );
+
+      const state = await recordFailure('cloakpipe', mockKV, 5);
+      expect(state.consecutive_failures).toBe(5);
+      expect(state.cooldown).toBe(true);
+    });
+
+    it('resets failure counter on success and clears cooldown', async () => {
+      mockKV.get.mockResolvedValue(
+        JSON.stringify({
+          hop_count: 0,
+          cooldown: true,
+          kill_switch: false,
+          consecutive_failures: 2,
+        })
+      );
+
+      const state = await recordSuccess('homeostat', mockKV);
+      expect(state.consecutive_failures).toBe(0);
+      expect(state.cooldown).toBe(false);
+    });
+
+    it('allows manual state updates and resets', async () => {
+      const updatedState = {
+        hop_count: 1,
+        cooldown: true,
+        kill_switch: false,
+        last_updated: '2025-10-25T10:00:00Z',
+        consecutive_failures: 3,
+      };
+
+      await updateCircuitBreakerState('gatekeeper', updatedState, mockKV);
+      expect(mockKV.put).toHaveBeenCalledWith(
+        'circuit:gatekeeper',
+        expect.any(String),
+        expect.objectContaining({ expirationTtl: 86400 })
+      );
+
+      mockKV.put.mockClear();
+      await resetCircuitBreaker('gatekeeper', mockKV);
+      expect(mockKV.put).toHaveBeenCalledWith(
+        'circuit:gatekeeper',
+        expect.any(String),
+        expect.objectContaining({ expirationTtl: 86400 })
+      );
+    });
+  });
+});