crackerjack 0.19.7__tar.gz → 0.20.0__tar.gz

{crackerjack-0.19.7 → crackerjack-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: crackerjack
-Version: 0.19.7
+Version: 0.20.0
 Summary: Crackerjack: code quality toolkit
 Keywords: bandit,black,creosote,mypy,pyright,pytest,refurb,ruff
 Author-Email: lesleslie <les@wedgwoodwebworks.com>
@@ -82,7 +82,7 @@ Crackerjack integrates powerful tools like Ruff, PDM, pre-commit, pytest, and mo
 ### Quick Start
 
 If you're new to Crackerjack, follow these steps:
-1. **Install Python 3.13:** Ensure you have Python 3.13 installed.
+1. **Install Python 3.13:** Ensure you have Python 3.13 or higher installed.
 2. **Install PDM:**
     ```
     pipx install pdm
@@ -98,6 +98,11 @@ If you're new to Crackerjack, follow these steps:
     python -m crackerjack
     ```
 
+    Or use the interactive Rich UI:
+    ```
+    python -m crackerjack --rich-ui
+    ```
+
 ---
 
 ## The Crackerjack Philosophy
@@ -137,9 +142,12 @@ Crackerjack is built on the following core principles:
 
 ### Developer Experience
 - **Command-Line Interface:** Simple, intuitive CLI with comprehensive options
+- **Interactive Rich UI:** Visual workflow with real-time task tracking, progress visualization, and interactive prompts
+- **Structured Error Handling:** Clear error messages with error codes, detailed explanations, and recovery suggestions
 - **Programmatic API:** Can be integrated into your own Python scripts and workflows
 - **AI Agent Integration:** Structured output format for integration with AI assistants, with complete style rules available in [RULES.md](RULES.md) for AI tool customization
 - **Verbose Mode:** Detailed output for debugging and understanding what's happening
+- **Python 3.13+ Features:** Leverages the latest Python language features including PEP 695 type parameter syntax, Self type annotations, and structural pattern matching
 
 ## Pre-commit Hooks
 
@@ -217,7 +225,7 @@ python -m crackerjack -t --benchmark-regression --benchmark-regression-threshold
 
 ## Installation
 
-1.  **Python:** Ensure you have Python 3.13 installed.
+1.  **Python:** Ensure you have Python 3.13 or higher installed.
 2.  **PDM:** Install [PDM](https://pdm.fming.dev/) using `pipx`:
 
     ```
@@ -231,6 +239,11 @@ python -m crackerjack -t --benchmark-regression --benchmark-regression-threshold
     python -m crackerjack
     ```
 
+    Or with the interactive Rich UI:
+    ```
+    python -m crackerjack --rich-ui
+    ```
+
 ## Usage
 
 ### Command Line
@@ -312,6 +325,7 @@ runner.process(MyOptions())
 -   `--benchmark-regression`: Fail tests if benchmarks regress beyond threshold.
 -   `--benchmark-regression-threshold`: Set threshold percentage for benchmark regression (default 5.0%).
 -   `-a`, `--all`: Run with `-x -t -p <micro|minor|major> -c` development options.
+-   `--rich-ui`: Enable the interactive Rich UI for a more user-friendly experience with visual progress tracking and interactive prompts.
 -   `--ai-agent`: Enable AI agent mode with structured output (see [AI Agent Integration](#ai-agent-integration)).
 -   `--help`: Display help.
 
@@ -387,6 +401,11 @@ runner.process(MyOptions())
   python -m crackerjack -i
   ```
 
+- **Rich Interactive Mode** - Run with the interactive Rich UI:
+  ```bash
+  python -m crackerjack --rich-ui
+  ```
+
 - **AI Integration** - Run with structured output for AI tools:
   ```bash
   python -m crackerjack --ai-agent --test
@@ -413,6 +432,79 @@ python -m crackerjack --ai-agent --test
 
 For detailed information about using Crackerjack with AI agents, including the structured output format and programmatic usage, see [README-AI-AGENT.md](README-AI-AGENT.md).
 
+## Interactive Rich UI
+
+Crackerjack now offers an enhanced interactive experience through its Rich UI:
+
+- **Visual Workflow:** See a visual representation of the entire task workflow with dependencies
+- **Real-time Progress:** Track task progress with interactive progress bars and status indicators
+- **Task Management:** Confirm tasks before execution and view detailed status information
+- **Error Visualization:** Errors are presented in a structured, easy-to-understand format with recovery suggestions
+- **File Selection:** Interactive file browser for operations that require selecting files
+
+To use the Rich UI, run Crackerjack with the `--rich-ui` flag:
+
+```bash
+python -m crackerjack --rich-ui
+```
+
+This launches an interactive terminal interface where you can:
+1. View all available tasks and their dependencies
+2. Confirm each task before execution
+3. Get detailed status information for running tasks
+4. See a summary of completed, failed, and skipped tasks
+5. Visualize error details with recovery suggestions
+
+## Structured Error Handling
+
+Crackerjack implements a comprehensive error handling system that provides:
+
+- **Error Categories:** Errors are categorized by type (configuration, execution, testing, etc.)
+- **Error Codes:** Each error has a unique numeric code for easy reference
+- **Detailed Messages:** Clear, descriptive messages explain what went wrong
+- **Recovery Suggestions:** Where possible, errors include recovery suggestions to help resolve issues
+- **Rich Formatting:** Errors are presented with clear visual formatting (when using Rich UI or verbose mode)
+
+Error types include:
+- Configuration errors (1000-1999)
+- Execution errors (2000-2999)
+- Test errors (3000-3999)
+- Publishing errors (4000-4999)
+- Git errors (5000-5999)
+- File operation errors (6000-6999)
+- Code cleaning errors (7000-7999)
+- Generic errors (9000-9999)
+
+Use the `-v` or `--verbose` flag to see more detailed error information:
+
+```bash
+python -m crackerjack -v
+```
+
+For the most comprehensive error details with visual formatting, combine verbose mode with the Rich UI:
+
+```bash
+python -m crackerjack --rich-ui -v
+```
+
+## Python 3.13+ Features
+
+Crackerjack is designed to leverage the latest Python 3.13+ language features:
+
+- **Type Parameter Syntax (PEP 695):** Uses the new, more concise syntax for generic type parameters
+- **Self Type:** Leverages the `Self` type for better method chaining and builder patterns
+- **Structural Pattern Matching:** Uses pattern matching for cleaner code, especially in configuration and command processing
+- **Enhanced Type Hints:** More precise type hints with union types using the pipe operator
+- **Modern Dictionary Patterns:** Leverages structural pattern matching with dictionaries for cleaner data handling
+
+These modern Python features contribute to:
+- More readable and maintainable code
+- Better static type checking with tools like pyright
+- Cleaner, more concise implementations
+- Enhanced error handling and pattern recognition
+
+Crackerjack provides examples of these features in action, serving as a reference for modern Python development practices.
+
 ## Contributing
 
 Crackerjack is an evolving project. Contributions are welcome! Please open a pull request or issue.

{crackerjack-0.19.7 → crackerjack-0.20.0}/README.md

@@ -40,7 +40,7 @@ Crackerjack integrates powerful tools like Ruff, PDM, pre-commit, pytest, and mo
 ### Quick Start
 
 If you're new to Crackerjack, follow these steps:
-1. **Install Python 3.13:** Ensure you have Python 3.13 installed.
+1. **Install Python 3.13:** Ensure you have Python 3.13 or higher installed.
 2. **Install PDM:**
     ```
     pipx install pdm
@@ -56,6 +56,11 @@ If you're new to Crackerjack, follow these steps:
     python -m crackerjack
     ```
 
+    Or use the interactive Rich UI:
+    ```
+    python -m crackerjack --rich-ui
+    ```
+
 ---
 
 ## The Crackerjack Philosophy
@@ -95,9 +100,12 @@ Crackerjack is built on the following core principles:
 
 ### Developer Experience
 - **Command-Line Interface:** Simple, intuitive CLI with comprehensive options
+- **Interactive Rich UI:** Visual workflow with real-time task tracking, progress visualization, and interactive prompts
+- **Structured Error Handling:** Clear error messages with error codes, detailed explanations, and recovery suggestions
 - **Programmatic API:** Can be integrated into your own Python scripts and workflows
 - **AI Agent Integration:** Structured output format for integration with AI assistants, with complete style rules available in [RULES.md](RULES.md) for AI tool customization
 - **Verbose Mode:** Detailed output for debugging and understanding what's happening
+- **Python 3.13+ Features:** Leverages the latest Python language features including PEP 695 type parameter syntax, Self type annotations, and structural pattern matching
 
 ## Pre-commit Hooks
 
@@ -175,7 +183,7 @@ python -m crackerjack -t --benchmark-regression --benchmark-regression-threshold
 
 ## Installation
 
-1.  **Python:** Ensure you have Python 3.13 installed.
+1.  **Python:** Ensure you have Python 3.13 or higher installed.
 2.  **PDM:** Install [PDM](https://pdm.fming.dev/) using `pipx`:
 
     ```
@@ -189,6 +197,11 @@ python -m crackerjack -t --benchmark-regression --benchmark-regression-threshold
     python -m crackerjack
     ```
 
+    Or with the interactive Rich UI:
+    ```
+    python -m crackerjack --rich-ui
+    ```
+
 ## Usage
 
 ### Command Line
@@ -270,6 +283,7 @@ runner.process(MyOptions())
 -   `--benchmark-regression`: Fail tests if benchmarks regress beyond threshold.
 -   `--benchmark-regression-threshold`: Set threshold percentage for benchmark regression (default 5.0%).
 -   `-a`, `--all`: Run with `-x -t -p <micro|minor|major> -c` development options.
+-   `--rich-ui`: Enable the interactive Rich UI for a more user-friendly experience with visual progress tracking and interactive prompts.
 -   `--ai-agent`: Enable AI agent mode with structured output (see [AI Agent Integration](#ai-agent-integration)).
 -   `--help`: Display help.
 
@@ -345,6 +359,11 @@ runner.process(MyOptions())
   python -m crackerjack -i
   ```
 
+- **Rich Interactive Mode** - Run with the interactive Rich UI:
+  ```bash
+  python -m crackerjack --rich-ui
+  ```
+
 - **AI Integration** - Run with structured output for AI tools:
   ```bash
   python -m crackerjack --ai-agent --test
@@ -371,6 +390,79 @@ python -m crackerjack --ai-agent --test
 
 For detailed information about using Crackerjack with AI agents, including the structured output format and programmatic usage, see [README-AI-AGENT.md](README-AI-AGENT.md).
 
+## Interactive Rich UI
+
+Crackerjack now offers an enhanced interactive experience through its Rich UI:
+
+- **Visual Workflow:** See a visual representation of the entire task workflow with dependencies
+- **Real-time Progress:** Track task progress with interactive progress bars and status indicators
+- **Task Management:** Confirm tasks before execution and view detailed status information
+- **Error Visualization:** Errors are presented in a structured, easy-to-understand format with recovery suggestions
+- **File Selection:** Interactive file browser for operations that require selecting files
+
+To use the Rich UI, run Crackerjack with the `--rich-ui` flag:
+
+```bash
+python -m crackerjack --rich-ui
+```
+
+This launches an interactive terminal interface where you can:
+1. View all available tasks and their dependencies
+2. Confirm each task before execution
+3. Get detailed status information for running tasks
+4. See a summary of completed, failed, and skipped tasks
+5. Visualize error details with recovery suggestions
+
+## Structured Error Handling
+
+Crackerjack implements a comprehensive error handling system that provides:
+
+- **Error Categories:** Errors are categorized by type (configuration, execution, testing, etc.)
+- **Error Codes:** Each error has a unique numeric code for easy reference
+- **Detailed Messages:** Clear, descriptive messages explain what went wrong
+- **Recovery Suggestions:** Where possible, errors include recovery suggestions to help resolve issues
+- **Rich Formatting:** Errors are presented with clear visual formatting (when using Rich UI or verbose mode)
+
+Error types include:
+- Configuration errors (1000-1999)
+- Execution errors (2000-2999)
+- Test errors (3000-3999)
+- Publishing errors (4000-4999)
+- Git errors (5000-5999)
+- File operation errors (6000-6999)
+- Code cleaning errors (7000-7999)
+- Generic errors (9000-9999)
+
+Use the `-v` or `--verbose` flag to see more detailed error information:
+
+```bash
+python -m crackerjack -v
+```
+
+For the most comprehensive error details with visual formatting, combine verbose mode with the Rich UI:
+
+```bash
+python -m crackerjack --rich-ui -v
+```
+
+## Python 3.13+ Features
+
+Crackerjack is designed to leverage the latest Python 3.13+ language features:
+
+- **Type Parameter Syntax (PEP 695):** Uses the new, more concise syntax for generic type parameters
+- **Self Type:** Leverages the `Self` type for better method chaining and builder patterns
+- **Structural Pattern Matching:** Uses pattern matching for cleaner code, especially in configuration and command processing
+- **Enhanced Type Hints:** More precise type hints with union types using the pipe operator
+- **Modern Dictionary Patterns:** Leverages structural pattern matching with dictionaries for cleaner data handling
+
+These modern Python features contribute to:
+- More readable and maintainable code
+- Better static type checking with tools like pyright
+- Cleaner, more concise implementations
+- Enhanced error handling and pattern recognition
+
+Crackerjack provides examples of these features in action, serving as a reference for modern Python development practices.
+
 ## Contributing
 
 Crackerjack is an evolving project. Contributions are welcome! Please open a pull request or issue.

{crackerjack-0.19.7 → crackerjack-0.20.0}/crackerjack/.gitignore

@@ -12,3 +12,5 @@
 /*.pyc
 /scratch/
 /.zencoder/
+
+**/.claude/settings.local.json

{crackerjack-0.19.7 → crackerjack-0.20.0}/crackerjack/.pre-commit-config.yaml

@@ -75,7 +75,6 @@ repos:
     rev: v2.1.0
     hooks:
       - id: refurb
-        exclude: ^tests/
 
   # Code quality tier 3 - thorough checks
   - repo: local

crackerjack-0.20.0/crackerjack/__init__.py

@@ -0,0 +1,42 @@
+import typing as t
+
+from .crackerjack import Crackerjack, create_crackerjack_runner
+from .errors import (
+    CleaningError,
+    ConfigError,
+    CrackerjackError,
+    ErrorCode,
+    ExecutionError,
+    FileError,
+    GitError,
+    PublishError,
+    TestError,
+    check_command_result,
+    check_file_exists,
+    handle_error,
+)
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("crackerjack")
+except (ImportError, ModuleNotFoundError):
+    __version__ = "0.19.8"
+
+__all__: t.Sequence[str] = [
+    "create_crackerjack_runner",
+    "Crackerjack",
+    "__version__",
+    "CrackerjackError",
+    "ConfigError",
+    "ExecutionError",
+    "TestError",
+    "PublishError",
+    "GitError",
+    "FileError",
+    "CleaningError",
+    "ErrorCode",
+    "handle_error",
+    "check_file_exists",
+    "check_command_result",
+]

{crackerjack-0.19.7 → crackerjack-0.20.0}/crackerjack/__main__.py

@@ -38,6 +38,7 @@ class Options(BaseModel):
     ai_agent: bool = False
     create_pr: bool = False
     skip_hooks: bool = False
+    rich_ui: bool = False
 
     @classmethod
     @field_validator("publish", "bump", mode="before")
@@ -84,7 +85,7 @@ cli_options = {
         False,
         "-x",
         "--clean",
-        help="Remove docstrings, line comments, and unnecessary whitespace.",
+        help="Remove docstrings, line comments, and unnecessary whitespace from source code (doesn't affect test files).",
     ),
     "test": typer.Option(False, "-t", "--test", help="Run tests."),
     "benchmark": typer.Option(
@@ -121,6 +122,11 @@ cli_options = {
         "--pr",
         help="Create a pull request to the upstream repository.",
     ),
+    "rich_ui": typer.Option(
+        False,
+        "--rich-ui",
+        help="Use the interactive Rich UI for a better experience.",
+    ),
     "ai_agent": typer.Option(
         False,
         "--ai-agent",
@@ -150,6 +156,7 @@ def main(
     ],
     skip_hooks: bool = cli_options["skip_hooks"],
     create_pr: bool = cli_options["create_pr"],
+    rich_ui: bool = cli_options["rich_ui"],
     ai_agent: bool = cli_options["ai_agent"],
 ) -> None:
     options = Options(
@@ -170,6 +177,7 @@ def main(
         all=all,
         ai_agent=ai_agent,
         create_pr=create_pr,
+        rich_ui=rich_ui,
     )
 
     if ai_agent:
@@ -177,8 +185,20 @@ def main(
 
         os.environ["AI_AGENT"] = "1"
 
-    runner = create_crackerjack_runner(console=console)
-    runner.process(options)
+    if rich_ui:
+        from crackerjack.interactive import launch_interactive_cli
+
+        try:
+            from importlib.metadata import version
+
+            pkg_version = version("crackerjack")
+        except (ImportError, ModuleNotFoundError):
+            pkg_version = "0.19.8"
+
+        launch_interactive_cli(pkg_version)
+    else:
+        runner = create_crackerjack_runner(console=console)
+        runner.process(options)
 
 
 if __name__ == "__main__":