fix(backend): consolidate error handling with custom error classes

[Netty-kun]

Overview

This PR consolidates error handling across the backend by introducing a hierarchy of custom error classes. Instead of ad-hoc res.status().json() calls and raw throw new Error(), all routes now throw typed errors that are caught by the updated error handler middleware. This ensures consistent error response shapes everywhere.

Related Issue

Closes #109

Changes

🏗️ Custom Error Classes

• [ADD] backend/src/errors/AppError.ts — Base class with statusCode, code, isOperational, details
• [ADD] backend/src/errors/ValidationError.ts — 400, VALIDATION_ERROR code, supports field details
• [ADD] backend/src/errors/NotFoundError.ts — 404, NOT_FOUND code, supports resource name + optional ID
• [ADD] backend/src/errors/UnauthorizedError.ts — 401, UNAUTHORIZED code, accepts custom message
• [ADD] backend/src/errors/RateLimitError.ts — 429, RATE_LIMITED code
• [ADD] backend/src/errors/index.ts — Barrel exports

⚙️ Error Handler Middleware

• [MODIFY] backend/src/api/middleware/errorHandler.ts
  • Now recognizes all AppError subclasses and returns correct HTTP status codes
  • Logs operational errors at warn level (no stack trace) vs non-operational at error level
  • Hides stack traces in production (NODE_ENV=production)
  • Falls back to 500 for raw Error objects

🔐 Auth & Routes

• [MODIFY] backend/src/api/middleware/auth.ts — Calls next(new UnauthorizedError()) instead of res.status(401).json()
• [MODIFY] backend/src/api/app.ts — All inline route handlers use next(new ValidationError | NotFoundError | UnauthorizedError | AppError(...)); defaultDispatch throws AppError instead of Error
• [MODIFY] backend/src/api/routes/agents.ts — All error paths use next() with custom error classes
• [MODIFY] backend/src/api/routes/tasks.ts — Same pattern applied
• [MODIFY] backend/src/api/routes/stats.ts — Same pattern applied

🧪 Tests

• [MODIFY] backend/tests/middleware.test.ts — Auth tests now verify next is called with error (statusCode 401)
• [MODIFY] backend/tests/agents.test.ts — Updated expectations for { error: { code, message } } shape; added test error handler
• All existing passing tests continue to pass

Verification Results

Acceptance Criteria	Status
Custom error classes in backend/src/errors/	✅
Error handler handles all custom types	✅
No raw Error objects thrown in routes	✅
Error responses have consistent shape: { error: { code, message, details? } }	✅
Stack traces hidden in production	✅
All existing error tests pass	✅

[vercel]

@Netty-kun is attempting to deploy a commit to the Jaja's projects Team on Vercel.

A member of the Team first needs to authorize it.

[devJaja]

Nice Implementation @Netty-kun
I can see all CI checks are passing. Quick one please, resolve the conflicts for the PR to be merge

[devJaja]

@Netty-kun
Resolve the conflict please