Skip to content

CLI Utilities

The Fast Craftsmanship CLI utilities provide a foundation for building robust, type-safe, and functional command-line applications. These utilities are designed with functional programming principles and focus on error handling, user experience, and maintainability.

Available Utilities

User Interface

  • UI Utilities: Rich terminal output, interactive prompts, and display components
  • Display functions (messages, panels, tables)
  • Error handling and recovery
  • Progress tracking
  • Input validation
  • Context management

Error Handling

  • Error Handling: Functional approach to error management
  • Railway-oriented programming
  • Tagged union error types
  • Error recovery strategies
  • Command error decorators

Type System

  • Type Utils: Type safety and validation utilities
  • Generic type constraints
  • Runtime type checking
  • Type validation functions
  • Type-safe conversions

File Operations

  • File Utils: File system operations
  • Path validation
  • Safe file operations
  • File type checking
  • Directory management

Validation

  • Validation: Input validation utilities
  • Data validators
  • Schema validation
  • Format checking
  • Custom validation rules

Design Philosophy

The utilities follow these core principles:

  1. Functional Programming
  2. Pure functions
  3. Immutable data structures
  4. Explicit error handling

  5. Composition over inheritance

  6. Type Safety

  7. Static type checking
  8. Runtime type validation
  9. Generic type constraints

  10. Type-safe error handling

  11. User Experience

  12. Consistent UI patterns
  13. Clear error messages
  14. Interactive feedback

  15. Progressive disclosure

  16. Maintainability

  17. Modular design
  18. Clear documentation
  19. Comprehensive testing
  20. Consistent patterns

Getting Started

Basic Usage

from fcship.utils.ui import display_message, success_message
from fcship.utils.error_handling import handle_command_errors
from expression import Result, Ok, Error

@handle_command_errors
def my_command() -> None:
    result = display_message("Starting operation...", "cyan")
    if result.is_ok():
        success_message("Operation completed!")

Error Handling

from fcship.utils.ui import DisplayError, handle_ui_error
from expression import Result

def safe_operation() -> Result[None, DisplayError]:
    # Your operation here
    return Ok(None)

result = safe_operation()
if result.is_error():
    handle_ui_error(result.error)

Integration Examples

Combining Multiple Utilities

from fcship.utils import ui, error_handling, validation
from expression import Result, pipe

def validated_command(input_data: str) -> Result[None, DisplayError]:
    return (
        validation.validate_input(input_data)
        .bind(process_data)
        .bind(ui.display_result)
    )

Best Practices

  1. Error Handling
  2. Always use Result types for operations that can fail
  3. Handle all error cases explicitly
  4. Provide meaningful error messages

  5. Use appropriate error types

  6. Type Safety

  7. Use type hints consistently
  8. Validate input types at runtime
  9. Use generic types for flexible components

  10. Maintain type safety across boundaries

  11. User Interface

  12. Follow consistent display patterns
  13. Provide clear feedback
  14. Handle long operations with progress indicators

  15. Use appropriate UI components

  16. Testing

  17. Write unit tests for all utilities
  18. Test error cases explicitly
  19. Mock external dependencies
  20. Test type constraints

Contributing

When adding new utilities:

  1. Follow functional programming principles
  2. Maintain type safety
  3. Add comprehensive documentation
  4. Include unit tests
  5. Follow existing patterns

See Also