refactor: simplify error handling patterns for v0.17.0

[marcuscastelo]

Summary

Simplify error handling patterns by replacing custom error classes with standard Error() + descriptive messages, while maintaining the essential handleApiError function for application-layer error management.

Current State

The codebase contains:

• Custom error classes that mainly add type complexity without runtime benefits
• Error hierarchies that could be simplified to standard errors
• Good application-layer error handling with handleApiError (keep this!)

Proposed Changes

1. Simplify Error Classes

• Replace custom error classes with standard Error() + descriptive messages
• Use error context objects instead of error inheritance
• Maintain clear error messages that include relevant context

2. Keep Essential Error Infrastructure

• ✅ Maintain handleApiError function - provides real value for user feedback
• ✅ Keep validation error handling patterns
• ✅ Preserve error boundary functionality

3. Standard Error Patterns

// ✅ New pattern: Standard Error with context
throw new Error('Group mismatch: cannot mix different groups', { 
  cause: { groupId, recipeId, operation: 'validateGroupConsistency' } 
})

// ❌ Old pattern: Custom error class
throw new GroupConflictError(groupId, recipeId)

Rationale

Frontend Reality Check:

• Most errors come from network/API calls, not business logic violations
• Standard Error() + good error handling functions are sufficient
• TypeScript provides compile-time safety - runtime errors should be simple
• Users care about clear messages, not error taxonomies

Zod Integration:

• Zod provides excellent validation without custom error classes
• safeParse() patterns eliminate need for validation error hierarchies
• Standard errors work well with Zod's error reporting

Implementation Strategy

Phase 1: Audit Current Error Classes

• Identify all custom error classes in the codebase
• Categorize by actual usage and benefit
• Plan replacement with standard errors

Phase 2: Replace Custom Classes

• Convert custom error classes to standard Error() calls
• Update error handling to work with standard errors
• Maintain error context through cause property

Phase 3: Preserve Application Layer

• Keep handleApiError function intact
• Maintain error boundary patterns
• Ensure user feedback continues working

Testing

• All error handling tests continue to pass
• Error messages remain clear and helpful
• Application-layer error management unchanged
• pnpm check validates changes

Labels

• refactor
• complexity-medium
• improvement

Acceptance Criteria

• Custom error classes replaced with standard Error()
• Error messages remain descriptive and contextual
• handleApiError function preserved and working
• All tests passing
• No regression in user error experience
• pnpm check passes