refactor(testing): move DbOperations interface to canonical contracts location

- Move DbOperations and DbWhereResult from testing/mock-db.ts to types/contracts/database.ts
- Update production imports in version-utils.ts, agent-runs/_post.ts, steps/_post.ts
- Re-export from mock-db.ts for backwards compatibility with test imports
- Fix type error in dependencies/_get.ts by handling version: string | null
- Update knowledge.md with proper import guidance

Author: brandonkachen

common/src/testing/knowledge.md

@@ -4,7 +4,17 @@ Mock database objects for testing. No real database needed.
 
 ## DbOperations
 
-`DbOperations` is a minimal interface in `@codebuff/common/testing/mock-db`. Both the real `CodebuffPgDatabase` and these mocks satisfy it, so you can pass mocks directly to functions without `as any`.
+`DbOperations` is a minimal interface defined in `@codebuff/common/types/contracts/database`. Both the real `CodebuffPgDatabase` and test mocks satisfy it, enabling dependency injection without `as any` casts.
+
+**Production code** should import from the contracts location:
+```ts
+import type { DbOperations } from '@codebuff/common/types/contracts/database'
+```
+
+**Test code** can import from either location (mock-db re-exports the interface for convenience):
+```ts
+import { createMockDb, type DbOperations } from '@codebuff/common/testing/mock-db'
+```
 
 ## Utilities
 

common/src/testing/mock-db.ts

@@ -1,49 +1,11 @@
 import type { Logger } from '@codebuff/common/types/contracts/logger'
+import type {
+  DbOperations,
+  DbWhereResult,
+} from '@codebuff/common/types/contracts/database'
 
-// ============================================================================
-// Database Operations Interface
-// ============================================================================
-
-/* eslint-disable @typescript-eslint/no-explicit-any */
-/**
- * Minimal database interface for dependency injection in API routes.
- * Both the real CodebuffPgDatabase and test mocks can satisfy this interface.
- *
- * Uses `any` for table/column parameters to be compatible with Drizzle ORM's
- * specific table types while remaining flexible for mocks.
- */
-export interface DbOperations {
-  insert: (table: any) => {
-    values: (data: any) => PromiseLike<any>
-  }
-  update: (table: any) => {
-    set: (data: any) => {
-      where: (condition: any) => PromiseLike<any>
-    }
-  }
-  select: (columns?: any) => {
-    from: (table: any) => {
-      where: (condition: any) => DbWhereResult
-    }
-  }
-}
-
-/**
- * Result type for where() that supports multiple query patterns:
- * - .limit(n) for simple queries
- * - .orderBy(...).limit(n) for sorted queries
- * - .then() for promise-like resolution
- */
-export interface DbWhereResult {
-  then: <TResult = any[]>(
-    onfulfilled?: ((value: any[]) => TResult | PromiseLike<TResult>) | null | undefined,
-  ) => PromiseLike<TResult>
-  limit: (n: number) => PromiseLike<any[]>
-  orderBy: (...columns: any[]) => {
-    limit: (n: number) => PromiseLike<any[]>
-  }
-}
-/* eslint-enable @typescript-eslint/no-explicit-any */
+// Re-export database interfaces for backwards compatibility with test imports
+export type { DbOperations, DbWhereResult }
 
 // Compatibility layer: use bun:test mock when available, otherwise identity function
 // This allows the utilities to work in both Bun and Jest environments

common/src/types/contracts/database.ts

@@ -1,6 +1,51 @@
 import type { AgentTemplate } from '@codebuff/common/types/agent-template'
 import type { Logger } from '@codebuff/common/types/contracts/logger'
 
+// ============================================================================
+// Database Operations Interface
+// ============================================================================
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Minimal database interface for dependency injection in API routes.
+ * Both the real CodebuffPgDatabase and test mocks can satisfy this interface.
+ *
+ * Uses `any` for table/column parameters to be compatible with Drizzle ORM's
+ * specific table types while remaining flexible for mocks.
+ */
+export interface DbOperations {
+  insert: (table: any) => {
+    values: (data: any) => PromiseLike<any>
+  }
+  update: (table: any) => {
+    set: (data: any) => {
+      where: (condition: any) => PromiseLike<any>
+    }
+  }
+  select: (columns?: any) => {
+    from: (table: any) => {
+      where: (condition: any) => DbWhereResult
+    }
+  }
+}
+
+/**
+ * Result type for where() that supports multiple query patterns:
+ * - .limit(n) for simple queries
+ * - .orderBy(...).limit(n) for sorted queries
+ * - .then() for promise-like resolution
+ */
+export interface DbWhereResult {
+  then: <TResult = any[]>(
+    onfulfilled?: ((value: any[]) => TResult | PromiseLike<TResult>) | null | undefined,
+  ) => PromiseLike<TResult>
+  limit: (n: number) => PromiseLike<any[]>
+  orderBy: (...columns: any[]) => {
+    limit: (n: number) => PromiseLike<any[]>
+  }
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
 type User = {
   id: string
   email: string

packages/internal/src/utils/version-utils.ts

@@ -2,7 +2,7 @@ import { and, desc, eq } from 'drizzle-orm'
 
 import * as schema from '@codebuff/internal/db/schema'
 
-import type { DbOperations } from '@codebuff/common/testing/mock-db'
+import type { DbOperations } from '@codebuff/common/types/contracts/database'
 
 export type Version = { major: number; minor: number; patch: number }
 

web/src/app/api/agents/[publisherId]/[agentId]/[version]/dependencies/_get.ts

@@ -152,8 +152,13 @@ function createBatchingAgentLookup(
   return async function lookupAgent(
     publisher: string,
     agentId: string,
-    version: string,
+    version: string | null,
   ): Promise<AgentLookupResult | null> {
+    // Can't look up an agent without a version
+    if (version === null) {
+      return null
+    }
+
     const cacheKey = `${publisher}/${agentId}@${version}`
 
     // Return from cache if available

web/src/app/api/v1/agent-runs/[runId]/steps/_post.ts

@@ -7,8 +7,10 @@ import { NextResponse } from 'next/server'
 import { z } from 'zod'
 
 import type { TrackEventFn } from '@codebuff/common/types/contracts/analytics'
-import type { GetUserInfoFromApiKeyFn } from '@codebuff/common/types/contracts/database'
-import type { DbOperations } from '@codebuff/common/testing/mock-db'
+import type {
+  DbOperations,
+  GetUserInfoFromApiKeyFn,
+} from '@codebuff/common/types/contracts/database'
 import type {
   Logger,
   LoggerWithContextFn,

web/src/app/api/v1/agent-runs/_post.ts

@@ -7,8 +7,10 @@ import { NextResponse } from 'next/server'
 import { z } from 'zod'
 
 import type { TrackEventFn } from '@codebuff/common/types/contracts/analytics'
-import type { GetUserInfoFromApiKeyFn } from '@codebuff/common/types/contracts/database'
-import type { DbOperations } from '@codebuff/common/testing/mock-db'
+import type {
+  DbOperations,
+  GetUserInfoFromApiKeyFn,
+} from '@codebuff/common/types/contracts/database'
 import type {
   Logger,
   LoggerWithContextFn,