Fix: Replace stack traces with user-friendly error messages

[hovu96]

Summary

Implements a comprehensive exception handling solution that ensures users never see Python stack traces when running CLI commands. The decorator catches all exceptions during command initialization and dependency injection, providing clear, actionable error messages instead.

Scope of Solution

Two-Tier Exception Handling Strategy

1. Specific Handlers for Well-Known Exceptions

   • Network errors (ClientConnectorError, ClientConnectionError)
   • Timeout errors (TimeoutError)
   • Server disconnect errors (ServerDisconnectedError)
   • SSL/Certificate errors (ClientSSLError, ssl.SSLError)
   • Each handler provides context-specific guidance and troubleshooting steps

2. Generic Catch-All for Everything Else

   • Ensures NO exception becomes a stack trace
   • Shows error type and message without implementation details
   • Trusts that error messages contain relevant context (e.g., "run workato init")
   • Clean output without redundant advice

Key Design Principles

• Conservative approach: Only apply specific handlers when confident about error type
• Generic fallback: Ensures complete coverage - no stack traces slip through
• Clean messages: Original error messages already contain helpful context, no need to add redundant suggestions
• Decorator placement: Applied above @inject to catch dependency injection errors

Changes

• ✅ Add handle_cli_exceptions decorator to exception_handler.py
• ✅ Apply decorator to 11 commands that use dependency injection
• ✅ Add 16 comprehensive unit tests covering sync/async functions and all error types
• ✅ All 919 tests passing
• ✅ Type checking and linting passing

Before & After

Before:

$ workato workspace
Traceback (most recent call last):
  File "/Users/.../workato", line 12, in <module>
    sys.exit(cli())
  [... 30 lines of Python stack trace ...]
  File ".../containers.py", line 40, in create_profile_aware_workato_config
    raise ValueError(
        ...<2 lines>...
    )
ValueError: Could not resolve API credentials. Please check your profile configuration or run 'workato init' to set up authentication.

After:

$ workato workspace
❌ ValueError
   Could not resolve API credentials. Please check your profile configuration or run 'workato init' to set up authentication.

Testing

• All unit tests pass (62 tests for exception handler, 919 total)
• Manually tested with commands before workato init
• Verified both table and JSON output modes

Closes DEVP-424

🤖 Generated with Claude Code

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
__init__.py	68	4	94%	10–11, 69–70
cli
__init__.py	52	3	94%	49, 51, 60
containers.py	27	0	100%
cli/commands
__init__.py	0	0	100%
api_clients.py	291	9	96%	27, 302, 448–449, 483, 493, 584, 615, 623
api_collections.py	257	3	98%	28, 183, 347
assets.py	47	2	95%	55–56
connections.py	526	5	99%	589, 591, 597, 635, 986
data_tables.py	165	5	96%	31, 253, 267, 321–322
guide.py	166	1	99%	106
init.py	90	0	100%
profiles.py	203	0	100%
properties.py	97	1	98%	21
pull.py	172	2	98%	193–194
workspace.py	39	2	94%	61, 71
cli/commands/connectors
__init__.py	0	0	100%
command.py	90	2	97%	110, 159
connector_manager.py	203	4	98%	176, 292, 300–301
cli/commands/projects
__init__.py	0	0	100%
command.py	272	10	96%	359–362, 373, 439–441, 491, 495
project_manager.py	166	7	95%	48, 66, 263–264, 276, 317, 325
cli/commands/push
__init__.py	0	0	100%
command.py	133	4	96%	109, 112, 230, 308
cli/commands/recipes
__init__.py	0	0	100%
command.py	427	9	97%	117, 133–134, 272–275, 403, 709
validator.py	706	20	97%	174, 883, 1136, 1223, 1246, 1279, 1281–1282, 1359–1361, 1457–1458, 1517–1518, 1707–1708, 1736–1738
cli/utils
__init__.py	3	0	100%
exception_handler.py	304	25	91%	134–135, 140–141, 143–144, 170–171, 177, 220, 267, 294, 321, 378, 413, 472, 474–475, 480–481, 483–487
gitignore.py	14	0	100%
ignore_patterns.py	23	0	100%
spinner.py	43	0	100%
version_checker.py	135	6	95%	24, 26, 33–34, 72, 102
cli/utils/config
__init__.py	5	0	100%
manager.py	467	19	95%	125, 136–138, 141, 154, 204–205, 357, 438–439, 478, 692, 835–836, 850–851, 912, 971
models.py	33	0	100%
profiles.py	309	10	96%	93, 189–190, 193, 228–230, 255–257
workspace.py	68	0	100%
TOTAL	5601	153	97%

[Copilot]

Pull Request Overview

This PR adds a new handle_cli_exceptions decorator to handle CLI initialization and network errors with user-friendly messages. The decorator is designed to catch errors that occur during dependency injection and CLI setup, such as network failures, SSL errors, and configuration issues.

• Implements the handle_cli_exceptions decorator with support for both sync and async functions
• Adds dedicated error handlers for network, timeout, SSL, and generic CLI errors with JSON output support
• Applies the decorator to multiple CLI commands throughout the codebase

Reviewed Changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.

File	Description
src/workato_platform_cli/cli/utils/exception_handler.py	Adds handle_cli_exceptions decorator and helper functions for handling CLI-level errors
tests/unit/utils/test_exception_handler.py	Comprehensive test suite for the new decorator covering sync/async functions, various error types, and JSON output
src/workato_platform_cli/cli/commands/*.py	Applies the new decorator to various command functions (workspace, recipes, push, pull, properties, projects, profiles, data_tables, connectors, connections, api_clients)
src/.openapi-generator-ignore	Updates ignored path from workato_platform/__init__.py to workato_platform_cli/__init__.py

---

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

[oalami]

Looks good except for the exiting with a non-zero status code and the copilot raised issue on TimeoutError vs asyncio.TimeoutError looks worth implementing for better type safety.

[hovu96]

Looks good except for the exiting with a non-zero status code and the copilot raised issue on TimeoutError vs asyncio.TimeoutError looks worth implementing for better type safety.

Addressed both:

1. Exiting with a non-zero status
2. Type annotation inconsistency (just cosmetic: asyncio.TimeoutError → TimeoutError since it's an alias)

[oalami]

LGTM