feat: add user-friendly error messages

[SiddharthaSree]

What this does

Transforms cryptic error messages into helpful guidance. Instead of showing users raw exceptions like WebSocket connection failed: [Errno 61] Connection refused, they now see what went wrong, why it might have happened, and what to try.

Example
Before:
Error: WebSocket connection failed: [Errno 61] Connection refused

After:

❌ Cannot connect to Pieces OS

Possible reasons:
  • Pieces OS may not be running
  • The service port may be blocked

Try these solutions:
  1. Ensure Pieces OS is running: pieces open
  2. Restart Pieces OS: pieces restart

📖 More help: https://docs.pieces.app/products/cli/troubleshooting

Changes:

• Added errors module with pattern-based error matching
• Updated exception handler in app.py to use friendly formatting
• Added 19 tests

Fixes #379

[Copilot]

Pull request overview

This pull request adds a user-friendly error handling system to transform cryptic error messages into helpful, actionable guidance for CLI users. The changes include a new errors module with pattern-based error matching and user-friendly formatting, integration into the existing error handling paths, and comprehensive test coverage.

• Introduces UserFriendlyError dataclass and ErrorCategory enum for structured error representation
• Implements pattern-based error matching for 13+ error scenarios including connection, authentication, permissions, timeouts, and more
• Updates app.py and settings.py to use the new error formatting system

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/pieces/errors/init.py	Exports the public API of the new errors module
src/pieces/errors/user_friendly.py	Core implementation with error patterns, matching logic, and formatting
src/pieces/app.py	Updates main exception handler to use user-friendly error formatting
src/pieces/settings.py	Updates show_error method to handle both Exception objects and string errors with user-friendly formatting
tests/test_user_friendly_errors.py	Comprehensive test suite with 19 tests covering error categorization and formatting

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bishoy-at-pieces]

Super solid thank you so much
Just small change needed