[Refactor]: Better error messages and experience

[kfirstri]

Description

This PR introduces a comprehensive error handling system that replaces generic error throws with a structured error hierarchy. The new system distinguishes between user-fixable errors (UserError) and system errors (SystemError), provides actionable hints with optional commands for AI agents, and improves telemetry tracking with error codes and classification. This refactor enhances developer experience by making errors clearer and more actionable across the entire codebase.

Related Issue

None

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Other (please describe):

Changes Made

• New Error Hierarchy: Created CLIError base class with two main branches: UserError (user-fixable issues like auth/config problems) and SystemError (system issues like API/file failures)
• 11 Specific Error Classes: Implemented AuthRequiredError, AuthExpiredError, ConfigNotFoundError, ConfigInvalidError, ConfigExistsError, SchemaValidationError, InvalidInputError, ApiError, FileNotFoundError, FileReadError, InternalError
• Actionable Hints System: Each error includes structured hints with optional commands (e.g., { message: "Run 'base44 login'", command: "base44 login" }) to guide users and AI agents
• Automatic Zod Error Formatting: SchemaValidationError automatically formats validation errors using z.prettifyError() for better readability
• Enhanced Telemetry: Error reporting now includes error_code and is_user_error properties in PostHog for better analytics and debugging (src/cli/telemetry/error-reporter.ts:366-377)
• Comprehensive Test Coverage: Added 161 lines of tests covering all error classes, hints, type guards, and Zod integration (tests/core/errors.spec.ts)
• Documentation: Added 160+ lines to AGENTS.md documenting the error hierarchy, usage patterns, best practices, and error code reference table
• Codebase Migration: Updated ~30 files across auth, project, resources, and utilities to use structured errors instead of throw new Error()
• Type Guards: Added isCLIError(), isUserError(), and isSystemError() type guards for error handling
• Removed Old Error Classes: Replaced AuthApiError and AuthValidationError with new structured errors

Testing

• I have tested these changes locally
• I have added/updated tests as needed
• All tests pass (npm test)

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (if applicable)
• My changes generate no new warnings
• I have updated AGENTS.md if I made architectural changes

Additional Notes

This refactor significantly improves the developer experience by providing clear, actionable feedback when errors occur. The distinction between UserError and SystemError helps with debugging, prioritizing fixes, and providing better user guidance. The structured hints system is particularly valuable for AI agents that can now automatically suggest and execute recovery commands. All error messages now follow consistent patterns and include helpful context for resolution.

Key architectural improvements:

• Error codes enable better telemetry filtering and analytics
• Hints with commands enable automated recovery workflows
• Zod validation errors are now consistently formatted across the codebase
• Cause tracking preserves the full error chain for debugging

---

_{🤖 Generated by Claude | 2026-01-31 09:54 UTC}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.0.25-pr.159.7480a31

Prefer not to change any import paths? Install using npm alias so your code still imports base44:

npm i "base44@npm:@base44-preview/cli@0.0.25-pr.159.7480a31"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.0.25-pr.159.7480a31"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.0.25-pr.159.7480a31
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

[kfirstri]

This PR Still doesn't add better errors for API client, we will add it after #135 is merged, then we can throw the nicer errors