crackerjack 0.19.8__tar.gz → 0.20.1__tar.gz

{crackerjack-0.19.8 → crackerjack-0.20.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: crackerjack
-Version: 0.19.8
+Version: 0.20.1
 Summary: Crackerjack: code quality toolkit
 Keywords: bandit,black,creosote,mypy,pyright,pytest,refurb,ruff
 Author-Email: lesleslie <les@wedgwoodwebworks.com>
@@ -37,7 +37,7 @@ Requires-Dist: pytest-xdist>=3.7
 Requires-Dist: rich>=14
 Requires-Dist: tomli-w>=1.2
 Requires-Dist: typer>=0.16
-Requires-Dist: uv>=0.7.10
+Requires-Dist: uv>=0.7.12
 Description-Content-Type: text/markdown
 
 # Crackerjack: Elevate Your Python Development
@@ -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.8 → crackerjack-0.20.1}/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.8 → crackerjack-0.20.1}/crackerjack/.gitignore

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

{crackerjack-0.19.8 → crackerjack-0.20.1}/crackerjack/.pre-commit-config.yaml

@@ -34,7 +34,7 @@ repos:
           - keyring
 
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.7.10
+    rev: 0.7.12
     hooks:
       - id: uv-lock
         files: ^pyproject\.toml$
@@ -55,7 +55,7 @@ repos:
           - tomli
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.12
+    rev: v0.11.13
     hooks:
       - id: ruff-check
       - id: ruff-format

crackerjack-0.20.1/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.8 → crackerjack-0.20.1}/crackerjack/__main__.py

@@ -34,10 +34,13 @@ class Options(BaseModel):
     benchmark: bool = False
     benchmark_regression: bool = False
     benchmark_regression_threshold: float = 5.0
+    test_workers: int = 0
+    test_timeout: int = 0
     all: BumpOption | None = None
     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 +87,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(
@@ -102,6 +105,16 @@ cli_options = {
         "--benchmark-regression-threshold",
         help="Maximum allowed performance regression percentage (default: 5.0%).",
     ),
+    "test_workers": typer.Option(
+        0,
+        "--test-workers",
+        help="Number of parallel workers for running tests (0 = auto-detect, 1 = disable parallelization).",
+    ),
+    "test_timeout": typer.Option(
+        0,
+        "--test-timeout",
+        help="Timeout in seconds for individual tests (0 = use default based on project size).",
+    ),
     "skip_hooks": typer.Option(
         False,
         "-s",
@@ -121,6 +134,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",
@@ -148,8 +166,11 @@ def main(
     benchmark_regression_threshold: float = cli_options[
         "benchmark_regression_threshold"
     ],
+    test_workers: int = cli_options["test_workers"],
+    test_timeout: int = cli_options["test_timeout"],
     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(
@@ -166,10 +187,13 @@ def main(
         benchmark=benchmark,
         benchmark_regression=benchmark_regression,
         benchmark_regression_threshold=benchmark_regression_threshold,
+        test_workers=test_workers,
+        test_timeout=test_timeout,
         skip_hooks=skip_hooks,
         all=all,
         ai_agent=ai_agent,
         create_pr=create_pr,
+        rich_ui=rich_ui,
     )
 
     if ai_agent:
@@ -177,8 +201,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__":