refactor(core): replace fragile string-based errors with a type-safe …

[YasmeenOgo]

…system

Pull Request

Description

This commit introduces a significant refactoring of the core error handling system to enhance stability and user experience. The previous implementation, which relied on fragile string-matching of error messages, has been replaced with a robust, type-safe architecture. A new hierarchy of custom error classes, including AuthenticationError, NetworkError, and RateLimitError, has been established . AI providers have been updated to throw these specific error types, allowing the CLI's central error handler to reliably identify the root cause of a failure using instanceof checks. This new approach makes the application resilient to changes in external API error messages and enables the delivery of clearer, more actionable feedback to the user, ultimately making the tool easier to debug and use.

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
• 🧹 Code refactoring (no functional changes)
• ⚡ Performance improvement
• 🧪 Test coverage improvement
• 🔧 Build/CI configuration change

Related Issues

• Fixes #
• Related to #

Changes Made

• Created Custom Error Types: Introduced specific error classes like AuthenticationError and NetworkError to replace unreliable error text checking.

• Updated AI Providers: Providers now identify issues and throw these new, specific error types.

• Improved CLI Feedback: The command-line interface now catches these specific errors to give users clearer, more helpful advice.

AI Provider Impact

• OpenAI
• Anthropic
• Google AI/Vertex
• AWS Bedrock
• Azure OpenAI
• Hugging Face
• Ollama
• Mistral
• All providers
• No provider-specific changes

Component Impact

• CLI
• SDK
• MCP Integration
• Streaming
• Tool Calling
• Configuration
• Documentation
• Tests

Testing

• Unit tests added/updated
• Integration tests added/updated
• E2E tests added/updated
• Manual testing performed
• All existing tests pass

Test Environment

• OS: macOS
• Node.js version: Node version v20.19.4
• Package manager:

Performance Impact

• No performance impact
• Performance improvement
• Minor performance impact (acceptable)
• Significant performance impact (needs discussion)

Breaking Changes

Screenshots/Demo

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Additional Notes

Summary by CodeRabbit

• New Features
  • Clear, provider-aware error messages in the CLI with actionable guidance for authentication setup, permissions, rate limits, and network issues (covers Google AI, OpenAI, AWS Bedrock, Vertex AI, Anthropic, Azure OpenAI).
• Bug Fixes
  • Reduced misleading generic errors; more accurate surfacing of issues like model not found, rate limits, and connectivity problems.
• Refactor
  • Standardized, consistent error handling across providers with a unified error taxonomy. No changes to CLI commands or overall success/failure behavior.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

Introduces a typed error hierarchy and refactors providers (Anthropic, Google AI Studio, OpenAI) and CLI to throw and handle specific error classes (authentication, authorization, network, rate limit, invalid model, provider). Removes string-based parsing, adds provider-context messages, and preserves CLI exit behavior.

Changes

Cohort / File(s)	Summary
Typed error hierarchy src/lib/types/errors.ts	Adds BaseError and provider-aware errors: ProviderError, AuthenticationError, AuthorizationError, NetworkError, RateLimitError, InvalidModelError.
CLI error handling src/cli/index.ts	Switches to instanceof-based handling of new error types; prints provider- and scenario-specific guidance; removes string-matching logic; retains process.exit(1).
Provider error refactor — Anthropic src/lib/providers/anthropic.ts	Replaces generic returns with throwing typed errors (Network, Auth, RateLimit, Provider); standardizes messages; maps categories via extracted message; delegates generation to BaseProvider.
Provider error refactor — Google AI Studio src/lib/providers/googleAiStudio.ts	Throws typed errors for timeout, invalid API key, rate limit, and generic provider failures; adds provider context; AuthenticationError on missing API key; integrates buildMessagesArray in streaming.
Provider error refactor — OpenAI src/lib/providers/openAI.ts	Throws typed errors for timeout, invalid API key, rate limit, model_not_found (InvalidModelError), and generic provider errors; adds error type discrimination; introduces private model field and accessor.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant User
  participant CLI as CLI (index.ts)
  participant Provider as Provider (Anthropic/Google/OpenAI)
  participant API as Upstream API

  User->>CLI: run command
  CLI->>Provider: generate/stream request
  Provider->>API: call
  API-->>Provider: response or error
  alt success
    Provider-->>CLI: result
    CLI-->>User: output
  else error (typed)
    Provider--x CLI: throw AuthenticationError / RateLimitError / NetworkError / InvalidModelError / ProviderError
    CLI->>CLI: instanceof dispatch
    CLI-->>User: print targeted guidance
    CLI->>CLI: process.exit(1)
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• chore(refactor): add comprehensive TypeScript compliance refactor plans #81 — Introduces the typed error hierarchy and updates provider/CLI error handling; overlaps directly with the files and refactors in this PR.

Poem

I thump my paws at tidy throws,
No more guessing what error arose.
From clouds to keys, the paths are clear,
Providers speak, the CLI can hear.
With typed trails and gentle light,
Bugs hop off into the night.
🐇✨

✨ Finishing Touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

• Visit our Status Page to check the current availability of CodeRabbit.
• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.