refactor: make error code field required and consolidate error handling

- Made PrintModeError.code field required (was optional)
- Consolidated failure() and failureWithCode() into single failure() function
- Updated ErrorObject to include required code field with optional status/originalError
- Removed redundant failureWithCode() and ExtendedErrorObject type
- Added standard ErrorCodes constants (AUTH_FAILED, NETWORK_ERROR, etc.)
- Updated all error creation sites to include error codes
- Eliminated all 'as any' type casting for error codes

Author: brandonkachen

common/src/util/error.ts

@@ -16,6 +16,9 @@ export type ErrorObject = {
   name: string
   message: string
   stack?: string
+  code: string
+  status?: number
+  originalError?: unknown
 }
 
 export function success<T>(value: T): Success<T> {
@@ -26,85 +29,52 @@ export function success<T>(value: T): Success<T> {
 }
 
 export function failure(error: any): Failure<ErrorObject> {
+  if (error instanceof Error) {
+    const base = getErrorObject(error)
+    
+    // Safely extract code, status, and originalError if present
+    const errorWithMetadata = error as Error & {
+      code?: string
+      status?: number
+      originalError?: unknown
+    }
+
+    return {
+      success: false,
+      error: {
+        ...base,
+        code: typeof errorWithMetadata.code === 'string' ? errorWithMetadata.code : 'UNKNOWN_ERROR',
+        ...(typeof errorWithMetadata.status === 'number' && { status: errorWithMetadata.status }),
+        ...('originalError' in errorWithMetadata && { originalError: errorWithMetadata.originalError }),
+      },
+    }
+  }
+
   return {
     success: false,
-    error: getErrorObject(error),
+    error: {
+      ...getErrorObject(error),
+      code: 'UNKNOWN_ERROR',
+    },
   }
 }
 
 export function getErrorObject(error: any): ErrorObject {
   if (error instanceof Error) {
+    const errorWithCode = error as Error & { code?: string }
     return {
       name: error.name,
       message: error.message,
       stack: error.stack,
+      code: typeof errorWithCode.code === 'string' ? errorWithCode.code : 'UNKNOWN_ERROR',
     }
   }
 
   return {
     name: 'Error',
     message: `${error}`,
+    code: 'UNKNOWN_ERROR',
   }
 }
 
-/**
- * Extended error object that can preserve additional metadata like code, status, and originalError
- * from Error instances (e.g., NetworkError, AuthenticationError).
- */
-export type ExtendedErrorObject = ErrorObject & {
-  code?: string
-  status?: number
-  originalError?: unknown
-}
-
-/**
- * Wrap an unknown error into a Failure<ExtendedErrorObject>, preserving `code`, `status`, and `originalError`
- * when present on Error instances.
- *
- * This is useful for converting thrown errors into ErrorOr results while maintaining error metadata.
- *
- * @example
- * ```typescript
- * try {
- *   await somethingThatMightThrow()
- *   return success(result)
- * } catch (error) {
- *   return failureWithCode(error)
- * }
- * ```
- */
-export function failureWithCode(error: unknown): Failure<ExtendedErrorObject> {
-  if (error instanceof Error) {
-    const base = getErrorObject(error)
-    const enriched: ExtendedErrorObject = {
-      ...base,
-    }
-
-    // Safely extract code, status, and originalError if present
-    const errorWithMetadata = error as Error & {
-      code?: string
-      status?: number
-      originalError?: unknown
-    }
-
-    if (typeof errorWithMetadata.code === 'string') {
-      enriched.code = errorWithMetadata.code
-    }
 
-    if (typeof errorWithMetadata.status === 'number') {
-      enriched.status = errorWithMetadata.status
-    }
-
-    if ('originalError' in errorWithMetadata) {
-      enriched.originalError = errorWithMetadata.originalError
-    }
-
-    return {
-      success: false,
-      error: enriched,
-    }
-  }
-
-  // Fallback to base failure, which will still give us an ErrorObject
-  return failure(error)
-}

npm-app/src/cli.ts

@@ -297,6 +297,7 @@ export class CLI {
         printModeLog({
           type: 'error',
           message: errorMessage,
+          code: 'UNHANDLED_REJECTION',
         })
       }
       console.error(`\n${errorMessage}`)
@@ -319,6 +320,7 @@ export class CLI {
         printModeLog({
           type: 'error',
           message: errorMessage,
+          code: 'UNCAUGHT_EXCEPTION',
         })
       }
       console.error(`\n${errorMessage}`)
@@ -778,6 +780,7 @@ export class CLI {
         printModeLog({
           type: 'error',
           message: `Print mode requires authentication. Please run "codebuff login" or set the ${API_KEY_ENV_VAR} environment variable first.`,
+          code: 'AUTH_FAILED',
         })
         process.exit(1)
       }
@@ -1330,6 +1333,7 @@ export class CLI {
       printModeLog({
         type: 'error',
         message: 'Could not connect to server.',
+        code: 'NETWORK_ERROR',
       })
       process.exit(1)
     }

npm-app/src/index.ts

@@ -279,6 +279,7 @@ For all commands and options, run 'codebuff' and then type 'help'.
       printModeLog({
         type: 'error',
         message: 'Error: Print mode requires a prompt to be set',
+        code: 'VALIDATION_ERROR',
       })
       process.exit(1)
     }

sdk/src/impl/database-safe.ts

@@ -1,7 +1,7 @@
 import { getUserInfoFromApiKey } from './database'
 import {
-  failureWithCode,
-  type ExtendedErrorObject,
+  failure,
+  type ErrorObject,
   type ErrorOr,
 } from '@codebuff/common/util/error'
 import type {
@@ -15,7 +15,7 @@ type User = {
   discord_id: string | null
 }
 
-export type GetUserInfoFromApiKeySafeError = ExtendedErrorObject
+export type GetUserInfoFromApiKeySafeError = ErrorObject
 
 export async function getUserInfoFromApiKeySafe<T extends UserColumn>(
   params: GetUserInfoFromApiKeyInput<T>,
@@ -27,6 +27,6 @@ export async function getUserInfoFromApiKeySafe<T extends UserColumn>(
       value: result,
     }
   } catch (error) {
-    return failureWithCode(error)
+    return failure(error)
   }
 }

sdk/src/index.ts

@@ -45,8 +45,9 @@ export type { ValidationResult, ValidateAgentsOptions } from './validate-agents'
 
 // ErrorOr utilities
 export {
-  failureWithCode,
-  type ExtendedErrorObject,
+  failure,
+  success,
+  type ErrorObject,
   type ErrorOr,
   type Success,
   type Failure,