crackerjack 0.30.3__py3-none-any.whl → 0.31.4__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of crackerjack might be problematic. Click here for more details.

Files changed (155) hide show
  1. crackerjack/CLAUDE.md +1005 -0
  2. crackerjack/RULES.md +380 -0
  3. crackerjack/__init__.py +42 -13
  4. crackerjack/__main__.py +225 -299
  5. crackerjack/agents/__init__.py +41 -0
  6. crackerjack/agents/architect_agent.py +281 -0
  7. crackerjack/agents/base.py +169 -0
  8. crackerjack/agents/coordinator.py +512 -0
  9. crackerjack/agents/documentation_agent.py +498 -0
  10. crackerjack/agents/dry_agent.py +388 -0
  11. crackerjack/agents/formatting_agent.py +245 -0
  12. crackerjack/agents/import_optimization_agent.py +281 -0
  13. crackerjack/agents/performance_agent.py +669 -0
  14. crackerjack/agents/proactive_agent.py +104 -0
  15. crackerjack/agents/refactoring_agent.py +788 -0
  16. crackerjack/agents/security_agent.py +529 -0
  17. crackerjack/agents/test_creation_agent.py +652 -0
  18. crackerjack/agents/test_specialist_agent.py +486 -0
  19. crackerjack/agents/tracker.py +212 -0
  20. crackerjack/api.py +560 -0
  21. crackerjack/cli/__init__.py +24 -0
  22. crackerjack/cli/facade.py +104 -0
  23. crackerjack/cli/handlers.py +267 -0
  24. crackerjack/cli/interactive.py +471 -0
  25. crackerjack/cli/options.py +401 -0
  26. crackerjack/cli/utils.py +18 -0
  27. crackerjack/code_cleaner.py +618 -928
  28. crackerjack/config/__init__.py +19 -0
  29. crackerjack/config/hooks.py +218 -0
  30. crackerjack/core/__init__.py +0 -0
  31. crackerjack/core/async_workflow_orchestrator.py +406 -0
  32. crackerjack/core/autofix_coordinator.py +200 -0
  33. crackerjack/core/container.py +104 -0
  34. crackerjack/core/enhanced_container.py +542 -0
  35. crackerjack/core/performance.py +243 -0
  36. crackerjack/core/phase_coordinator.py +561 -0
  37. crackerjack/core/proactive_workflow.py +316 -0
  38. crackerjack/core/session_coordinator.py +289 -0
  39. crackerjack/core/workflow_orchestrator.py +640 -0
  40. crackerjack/dynamic_config.py +94 -103
  41. crackerjack/errors.py +263 -41
  42. crackerjack/executors/__init__.py +11 -0
  43. crackerjack/executors/async_hook_executor.py +431 -0
  44. crackerjack/executors/cached_hook_executor.py +242 -0
  45. crackerjack/executors/hook_executor.py +345 -0
  46. crackerjack/executors/individual_hook_executor.py +669 -0
  47. crackerjack/intelligence/__init__.py +44 -0
  48. crackerjack/intelligence/adaptive_learning.py +751 -0
  49. crackerjack/intelligence/agent_orchestrator.py +551 -0
  50. crackerjack/intelligence/agent_registry.py +414 -0
  51. crackerjack/intelligence/agent_selector.py +502 -0
  52. crackerjack/intelligence/integration.py +290 -0
  53. crackerjack/interactive.py +576 -315
  54. crackerjack/managers/__init__.py +11 -0
  55. crackerjack/managers/async_hook_manager.py +135 -0
  56. crackerjack/managers/hook_manager.py +137 -0
  57. crackerjack/managers/publish_manager.py +411 -0
  58. crackerjack/managers/test_command_builder.py +151 -0
  59. crackerjack/managers/test_executor.py +435 -0
  60. crackerjack/managers/test_manager.py +258 -0
  61. crackerjack/managers/test_manager_backup.py +1124 -0
  62. crackerjack/managers/test_progress.py +144 -0
  63. crackerjack/mcp/__init__.py +0 -0
  64. crackerjack/mcp/cache.py +336 -0
  65. crackerjack/mcp/client_runner.py +104 -0
  66. crackerjack/mcp/context.py +615 -0
  67. crackerjack/mcp/dashboard.py +636 -0
  68. crackerjack/mcp/enhanced_progress_monitor.py +479 -0
  69. crackerjack/mcp/file_monitor.py +336 -0
  70. crackerjack/mcp/progress_components.py +569 -0
  71. crackerjack/mcp/progress_monitor.py +949 -0
  72. crackerjack/mcp/rate_limiter.py +332 -0
  73. crackerjack/mcp/server.py +22 -0
  74. crackerjack/mcp/server_core.py +244 -0
  75. crackerjack/mcp/service_watchdog.py +501 -0
  76. crackerjack/mcp/state.py +395 -0
  77. crackerjack/mcp/task_manager.py +257 -0
  78. crackerjack/mcp/tools/__init__.py +17 -0
  79. crackerjack/mcp/tools/core_tools.py +249 -0
  80. crackerjack/mcp/tools/error_analyzer.py +308 -0
  81. crackerjack/mcp/tools/execution_tools.py +370 -0
  82. crackerjack/mcp/tools/execution_tools_backup.py +1097 -0
  83. crackerjack/mcp/tools/intelligence_tool_registry.py +80 -0
  84. crackerjack/mcp/tools/intelligence_tools.py +314 -0
  85. crackerjack/mcp/tools/monitoring_tools.py +502 -0
  86. crackerjack/mcp/tools/proactive_tools.py +384 -0
  87. crackerjack/mcp/tools/progress_tools.py +141 -0
  88. crackerjack/mcp/tools/utility_tools.py +341 -0
  89. crackerjack/mcp/tools/workflow_executor.py +360 -0
  90. crackerjack/mcp/websocket/__init__.py +14 -0
  91. crackerjack/mcp/websocket/app.py +39 -0
  92. crackerjack/mcp/websocket/endpoints.py +559 -0
  93. crackerjack/mcp/websocket/jobs.py +253 -0
  94. crackerjack/mcp/websocket/server.py +116 -0
  95. crackerjack/mcp/websocket/websocket_handler.py +78 -0
  96. crackerjack/mcp/websocket_server.py +10 -0
  97. crackerjack/models/__init__.py +31 -0
  98. crackerjack/models/config.py +93 -0
  99. crackerjack/models/config_adapter.py +230 -0
  100. crackerjack/models/protocols.py +118 -0
  101. crackerjack/models/task.py +154 -0
  102. crackerjack/monitoring/ai_agent_watchdog.py +450 -0
  103. crackerjack/monitoring/regression_prevention.py +638 -0
  104. crackerjack/orchestration/__init__.py +0 -0
  105. crackerjack/orchestration/advanced_orchestrator.py +970 -0
  106. crackerjack/orchestration/execution_strategies.py +341 -0
  107. crackerjack/orchestration/test_progress_streamer.py +636 -0
  108. crackerjack/plugins/__init__.py +15 -0
  109. crackerjack/plugins/base.py +200 -0
  110. crackerjack/plugins/hooks.py +246 -0
  111. crackerjack/plugins/loader.py +335 -0
  112. crackerjack/plugins/managers.py +259 -0
  113. crackerjack/py313.py +8 -3
  114. crackerjack/services/__init__.py +22 -0
  115. crackerjack/services/cache.py +314 -0
  116. crackerjack/services/config.py +347 -0
  117. crackerjack/services/config_integrity.py +99 -0
  118. crackerjack/services/contextual_ai_assistant.py +516 -0
  119. crackerjack/services/coverage_ratchet.py +347 -0
  120. crackerjack/services/debug.py +736 -0
  121. crackerjack/services/dependency_monitor.py +617 -0
  122. crackerjack/services/enhanced_filesystem.py +439 -0
  123. crackerjack/services/file_hasher.py +151 -0
  124. crackerjack/services/filesystem.py +395 -0
  125. crackerjack/services/git.py +165 -0
  126. crackerjack/services/health_metrics.py +611 -0
  127. crackerjack/services/initialization.py +847 -0
  128. crackerjack/services/log_manager.py +286 -0
  129. crackerjack/services/logging.py +174 -0
  130. crackerjack/services/metrics.py +578 -0
  131. crackerjack/services/pattern_cache.py +362 -0
  132. crackerjack/services/pattern_detector.py +515 -0
  133. crackerjack/services/performance_benchmarks.py +653 -0
  134. crackerjack/services/security.py +163 -0
  135. crackerjack/services/server_manager.py +234 -0
  136. crackerjack/services/smart_scheduling.py +144 -0
  137. crackerjack/services/tool_version_service.py +61 -0
  138. crackerjack/services/unified_config.py +437 -0
  139. crackerjack/services/version_checker.py +248 -0
  140. crackerjack/slash_commands/__init__.py +14 -0
  141. crackerjack/slash_commands/init.md +122 -0
  142. crackerjack/slash_commands/run.md +163 -0
  143. crackerjack/slash_commands/status.md +127 -0
  144. crackerjack-0.31.4.dist-info/METADATA +742 -0
  145. crackerjack-0.31.4.dist-info/RECORD +148 -0
  146. crackerjack-0.31.4.dist-info/entry_points.txt +2 -0
  147. crackerjack/.gitignore +0 -34
  148. crackerjack/.libcst.codemod.yaml +0 -18
  149. crackerjack/.pdm.toml +0 -1
  150. crackerjack/crackerjack.py +0 -3805
  151. crackerjack/pyproject.toml +0 -286
  152. crackerjack-0.30.3.dist-info/METADATA +0 -1290
  153. crackerjack-0.30.3.dist-info/RECORD +0 -16
  154. {crackerjack-0.30.3.dist-info → crackerjack-0.31.4.dist-info}/WHEEL +0 -0
  155. {crackerjack-0.30.3.dist-info → crackerjack-0.31.4.dist-info}/licenses/LICENSE +0 -0
@@ -0,0 +1,742 @@
1
+ Metadata-Version: 2.4
2
+ Name: crackerjack
3
+ Version: 0.31.4
4
+ Summary: Opinionated Python project management tool
5
+ Project-URL: documentation, https://github.com/lesleslie/crackerjack
6
+ Project-URL: homepage, https://github.com/lesleslie/crackerjack
7
+ Project-URL: repository, https://github.com/lesleslie/crackerjack
8
+ Author-email: Les Leslie <les@lesleslie.com>
9
+ License: BSD-3-CLAUSE
10
+ License-File: LICENSE
11
+ Classifier: Operating System :: POSIX
12
+ Classifier: Programming Language :: Python
13
+ Classifier: Programming Language :: Python :: 3 :: Only
14
+ Classifier: Programming Language :: Python :: 3.13
15
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
16
+ Classifier: Topic :: Software Development :: Quality Assurance
17
+ Classifier: Topic :: Software Development :: Testing
18
+ Classifier: Topic :: Utilities
19
+ Classifier: Typing :: Typed
20
+ Requires-Python: >=3.13
21
+ Requires-Dist: aiofiles>=24.1
22
+ Requires-Dist: aiohttp>=3.12.14
23
+ Requires-Dist: bandit>=1.8.6
24
+ Requires-Dist: codespell>=2.4.1
25
+ Requires-Dist: complexipy>=3.3
26
+ Requires-Dist: creosote>=4.0.3
27
+ Requires-Dist: fastapi>=0.116.1
28
+ Requires-Dist: fastmcp>=2.10.6
29
+ Requires-Dist: hatchling>=1.25
30
+ Requires-Dist: hypothesis>=6.100
31
+ Requires-Dist: jinja2>=3.1
32
+ Requires-Dist: keyring>=25.6
33
+ Requires-Dist: mcp>=1.12.2
34
+ Requires-Dist: pre-commit>=4.2
35
+ Requires-Dist: psutil>=6.1.0
36
+ Requires-Dist: pydantic>=2.11.7
37
+ Requires-Dist: pyleak>=0.1.14
38
+ Requires-Dist: pyright>=1.1.403
39
+ Requires-Dist: pytest-asyncio>=1
40
+ Requires-Dist: pytest-benchmark>=5.1
41
+ Requires-Dist: pytest-cov>=6.2.1
42
+ Requires-Dist: pytest-mock>=3.14.1
43
+ Requires-Dist: pytest-timeout>=2.4
44
+ Requires-Dist: pytest-xdist>=3.8
45
+ Requires-Dist: pytest>=8.4.1
46
+ Requires-Dist: pyyaml>=6.0.2
47
+ Requires-Dist: refurb>=2.1
48
+ Requires-Dist: rich>=14.1
49
+ Requires-Dist: ruff>=0.12.9
50
+ Requires-Dist: structlog>=24.4
51
+ Requires-Dist: textual>=0.89
52
+ Requires-Dist: tomli-w>=1.2
53
+ Requires-Dist: tomli>=2.2.1
54
+ Requires-Dist: typer>=0.16
55
+ Requires-Dist: uv>=0.7.20
56
+ Requires-Dist: uvicorn>=0.32.1
57
+ Requires-Dist: vulture>=2.14
58
+ Requires-Dist: watchdog>=6
59
+ Requires-Dist: websockets>=15.0.1
60
+ Description-Content-Type: text/markdown
61
+
62
+ # Crackerjack: Proactive AI-Powered Python Project Management
63
+
64
+ [![Python: 3.13+](https://img.shields.io/badge/python-3.13%2B-green)](https://www.python.org/downloads/)
65
+ [![pytest](https://img.shields.io/badge/pytest-coverage%20ratchet-blue)](https://pytest.org)
66
+ [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
67
+ [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
68
+ [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
69
+
70
+ ## 🎯 Mission Statement
71
+
72
+ **Crackerjack** transforms Python development from reactive firefighting to proactive excellence. We believe every line of code should be deliberate, every bug should be prevented rather than fixed, and every developer should write flawless code from the start.
73
+
74
+ ### What is "Crackerjack"?
75
+
76
+ **crackerjack** (noun): *A person or thing of marked excellence or ability; first-rate; exceptional.*
77
+
78
+ Just as the name suggests, Crackerjack makes your Python projects first-rate through:
79
+
80
+ - **🧠 Proactive AI Architecture**: 10+ specialized AI agents prevent issues before they occur
81
+ - **⚡ Autonomous Quality**: Intelligent auto-fixing with architectural planning
82
+ - **🛡️ Zero-Compromise Standards**: 100% test coverage, complexity ≤15, security-first patterns
83
+ - **🔄 Learning System**: Gets smarter with every project, caching successful patterns
84
+ - **🌟 One Command Excellence**: From setup to PyPI publishing with a single command
85
+
86
+ **The Crackerjack Philosophy**: If your code needs fixing after it's written, you're doing it wrong. We prevent problems through intelligent architecture and proactive patterns, making exceptional code the natural outcome, not a lucky accident.
87
+
88
+ ## What Problem Does Crackerjack Solve?
89
+
90
+ **Instead of configuring multiple tools separately:**
91
+
92
+ ```bash
93
+ # Traditional workflow
94
+ pip install black isort flake8 mypy pytest pre-commit
95
+ # Configure each tool individually
96
+ # Set up pre-commit hooks manually
97
+ # Remember different commands for each tool
98
+ ```
99
+
100
+ **Crackerjack provides unified commands:**
101
+
102
+ ```bash
103
+ pip install crackerjack
104
+ python -m crackerjack # Setup + quality checks
105
+ python -m crackerjack -t # Add testing
106
+ python -m crackerjack -a patch # Full release workflow
107
+ ```
108
+
109
+ **Key differentiators:**
110
+
111
+ - **Single command** replaces 6+ separate tools
112
+ - **Pre-configured** with Python best practices
113
+ - **UV integration** for fast dependency management
114
+ - **Automated publishing** with PyPI authentication
115
+ - **MCP server** for AI agent integration
116
+
117
+ ## The Crackerjack Philosophy
118
+
119
+ Crackerjack is built on the following core principles:
120
+
121
+ - **Code Clarity:** Code should be easy to read, understand, and maintain
122
+ - **Automation:** Tedious tasks should be automated, allowing developers to focus on solving problems
123
+ - **Consistency:** Code style, formatting, and project structure should be consistent across projects
124
+ - **Reliability:** Tests are essential, and code should be checked rigorously
125
+ - **Tool Integration:** Leverage powerful existing tools instead of reinventing the wheel
126
+ - **Static Typing:** Static typing is essential for all development
127
+
128
+ ## Table of Contents
129
+
130
+ - [Installation](#installation)
131
+ - [Quick Start](#quick-start)
132
+ - [AI Auto-Fix Features](#ai-auto-fix-features)
133
+ - [Core Features](#core-features)
134
+ - [MCP Server Configuration](#mcp-server-configuration)
135
+ - [Pre-commit Hook Modes](#pre-commit-hook-modes)
136
+ - [Testing Features](#testing-features)
137
+ - [Command Reference](#command-reference)
138
+ - [Style Guide](#style-guide)
139
+ - [Publishing & Version Management](#publishing--version-management)
140
+ - [Developer Experience](#developer-experience)
141
+
142
+ ## Installation
143
+
144
+ ### Prerequisites
145
+
146
+ - Python 3.13+
147
+ - [UV](https://github.com/astral-sh/uv) package manager
148
+
149
+ ### Install UV
150
+
151
+ ```bash
152
+ pipx install uv
153
+ ```
154
+
155
+ ### Install Crackerjack
156
+
157
+ ```bash
158
+ pip install crackerjack
159
+ # or
160
+ uv add crackerjack
161
+ ```
162
+
163
+ ## Quick Start
164
+
165
+ ### Initialize a Project
166
+
167
+ ```bash
168
+ # Navigate to your project directory
169
+ cd your-project
170
+
171
+ # Initialize with Crackerjack
172
+ python -m crackerjack
173
+
174
+ # Or use interactive mode
175
+ python -m crackerjack -i
176
+ ```
177
+
178
+ ## AI Auto-Fix Features
179
+
180
+ Crackerjack provides two distinct approaches to automatic error fixing:
181
+
182
+ ### 1. Hook Auto-Fix Modes (Basic Formatting)
183
+
184
+ Limited tool-specific auto-fixes for simple formatting issues:
185
+
186
+ - `ruff --fix`: Import sorting, basic formatting
187
+ - `trailing-whitespace --fix`: Removes trailing whitespace
188
+ - `end-of-file-fixer --fix`: Ensures files end with newline
189
+
190
+ **Limitations:** Only handles simple style issues, cannot fix type errors, security issues, test failures, or complex code quality problems.
191
+
192
+ ### 2. AI Agent Auto-Fixing (Comprehensive Intelligence)
193
+
194
+ **Revolutionary AI-powered code quality enforcement** that automatically fixes ALL types of issues:
195
+
196
+ #### How AI Agent Auto-Fixing Works
197
+
198
+ 1. **🚀 Run All Checks**: Fast hooks, comprehensive hooks, full test suite
199
+ 1. **🔍 Analyze Failures**: AI parses error messages, identifies root causes
200
+ 1. **🤖 Intelligent Fixes**: AI reads source code and makes targeted modifications
201
+ 1. **🔄 Repeat**: Continue until ALL checks pass (up to 10 iterations)
202
+ 1. **🎉 Perfect Quality**: Zero manual intervention required
203
+
204
+ #### Comprehensive Coverage
205
+
206
+ The AI agent intelligently fixes:
207
+
208
+ - **Type Errors (pyright)**: Adds missing annotations, fixes type mismatches
209
+ - **Security Issues (bandit)**: Removes hardcoded paths, fixes vulnerabilities
210
+ - **Dead Code (vulture)**: Removes unused imports, variables, functions
211
+ - **Performance Issues**: Transforms inefficient patterns (list concatenation, string building, nested loops)
212
+ - **Documentation Issues**: Auto-generates changelogs, maintains consistency across .md files
213
+ - **Test Failures**: Fixes missing fixtures, import errors, assertions
214
+ - **Code Quality (refurb)**: Applies refactoring, reduces complexity
215
+ - **All Hook Failures**: Formatting, linting, style issues
216
+
217
+ #### AI Agent Commands
218
+
219
+ ```bash
220
+ # Standard AI agent mode (recommended)
221
+ python -m crackerjack --ai-agent -t -v
222
+
223
+ # MCP server with WebSocket support (localhost:8675)
224
+ python -m crackerjack --start-mcp-server
225
+
226
+ # Progress monitoring via WebSocket
227
+ python -m crackerjack.mcp.progress_monitor <job_id> ws://localhost:8675
228
+ ```
229
+
230
+ #### Key Benefits
231
+
232
+ - **Zero Configuration**: No complex flag combinations needed
233
+ - **Complete Automation**: Handles entire quality workflow automatically
234
+ - **Intelligent Analysis**: Understands code context and business logic
235
+ - **Comprehensive Coverage**: Fixes ALL error types, not just formatting
236
+ - **Perfect Results**: Achieves 100% code quality compliance
237
+
238
+ #### Security & Safety Features
239
+
240
+ - **Command Validation**: All AI modifications are validated for safety
241
+ - **No Shell Injection**: Uses secure subprocess execution
242
+ - **Rollback Support**: All changes can be reverted via git
243
+ - **Human Review**: Review AI-generated changes before commit
244
+
245
+ ## Core Workflow
246
+
247
+ **Two-stage quality enforcement:**
248
+
249
+ 1. **Fast Hooks** (~5 seconds): Essential formatting and security checks
250
+ 1. **Comprehensive Hooks** (~30 seconds): Complete static analysis
251
+
252
+ **With AI integration:**
253
+
254
+ - `--ai-agent` flag enables automatic error resolution
255
+ - MCP server allows AI agents to run crackerjack commands
256
+ - Structured error output for programmatic fixes
257
+
258
+ ## Core Features
259
+
260
+ ### Project Management
261
+
262
+ - **Effortless Project Setup:** Initializes new Python projects with a standard directory structure, `pyproject.toml`, and essential configuration files
263
+ - **UV Integration:** Manages dependencies and virtual environments using [UV](https://github.com/astral-sh/uv) for lightning-fast package operations
264
+ - **Dependency Management:** Automatically detects and manages project dependencies
265
+
266
+ ### Code Quality
267
+
268
+ - **Automated Code Cleaning:** Removes unnecessary docstrings, line comments, and trailing whitespace
269
+ - **Consistent Code Formatting:** Enforces a unified style using [Ruff](https://github.com/astral-sh/ruff), the lightning-fast Python linter and formatter
270
+ - **Comprehensive Pre-commit Hooks:** Installs and manages a robust suite of pre-commit hooks
271
+ - **Interactive Checks:** Supports interactive pre-commit hooks (like `refurb`, `bandit`, and `pyright`) to fix issues in real-time
272
+ - **Static Type Checking:** Enforces type safety with Pyright integration
273
+
274
+ ### Testing & Coverage Ratchet System
275
+
276
+ - **Built-in Testing:** Automatically runs tests using `pytest` with intelligent parallelization
277
+ - **Coverage Ratchet:** Revolutionary coverage system that targets 100% - coverage can only increase, never decrease
278
+ - **Milestone Celebrations:** Progress tracking with milestone achievements (15%, 20%, 25%... → 100%)
279
+ - **No Arbitrary Limits:** Replaced traditional hard limits with continuous improvement toward perfection
280
+ - **Visual Progress:** Rich terminal displays showing journey to 100% coverage
281
+ - **Benchmark Testing:** Performance regression detection and monitoring
282
+ - **Easy Version Bumping:** Provides commands to bump the project version (patch, minor, or major)
283
+ - **Simplified Publishing:** Automates publishing to PyPI via UV with enhanced authentication
284
+
285
+ #### Coverage Ratchet Philosophy
286
+
287
+ 🎯 **Target: 100% Coverage** - Not an arbitrary number, but true comprehensive testing
288
+ 📈 **Continuous Improvement** - Each test run can only maintain or improve coverage
289
+ 🏆 **Milestone System** - Celebrate achievements at 15%, 25%, 50%, 75%, 90%, and 100%
290
+ 🚫 **No Regression** - Once you achieve a coverage level, you can't go backward
291
+
292
+ ```bash
293
+ # Show coverage progress
294
+ python -m crackerjack --coverage-status
295
+
296
+ # Run tests with ratchet system
297
+ python -m crackerjack -t
298
+
299
+ # Example output:
300
+ # 🎉 Coverage improved from 10.11% to 15.50%!
301
+ # 🏆 Milestone achieved: 15% coverage!
302
+ # 📈 Progress: [███░░░░░░░░░░░░░░░░░] 15.50% → 100%
303
+ # 🎯 Next milestone: 20% (+4.50% needed)
304
+ ```
305
+
306
+ ### Git Integration
307
+
308
+ - **Intelligent Commit Messages:** Analyzes git changes and suggests descriptive commit messages based on file types and modifications
309
+ - **Commit and Push:** Commits and pushes your changes with standardized commit messages
310
+ - **Pull Request Creation:** Creates pull requests to upstream repositories on GitHub or GitLab
311
+ - **Pre-commit Integration:** Ensures code quality before commits
312
+
313
+ ## MCP Server Configuration
314
+
315
+ ### What is MCP?
316
+
317
+ Model Context Protocol (MCP) enables AI agents to interact directly with Crackerjack's CLI tools for autonomous code quality fixes.
318
+
319
+ ### Setup MCP Server
320
+
321
+ 1. **Install MCP dependencies:**
322
+
323
+ ```bash
324
+ uv sync --group mcp
325
+ ```
326
+
327
+ 1. **Start the MCP server:**
328
+
329
+ ```bash
330
+ # Starts WebSocket server on localhost:8675 with MCP protocol support
331
+ python -m crackerjack --start-mcp-server
332
+ ```
333
+
334
+ 1. **Configure your MCP client (e.g., Claude Desktop):**
335
+
336
+ Add to your MCP configuration file (`mcp.json`):
337
+
338
+ **For installed crackerjack (from PyPI):**
339
+
340
+ ```json
341
+ {
342
+ "mcpServers": {
343
+ "crackerjack": {
344
+ "command": "uvx",
345
+ "args": [
346
+ "crackerjack",
347
+ "--start-mcp-server"
348
+ ],
349
+ "env": {
350
+ "UV_KEYRING_PROVIDER": "subprocess",
351
+ "EDITOR": "code --wait"
352
+ }
353
+ }
354
+ }
355
+ }
356
+ ```
357
+
358
+ **For local development version:**
359
+
360
+ ```json
361
+ {
362
+ "mcpServers": {
363
+ "crackerjack": {
364
+ "command": "uvx",
365
+ "args": [
366
+ "--from",
367
+ "/path/to/crackerjack",
368
+ "crackerjack",
369
+ "--start-mcp-server"
370
+ ],
371
+ "env": {
372
+ "UV_KEYRING_PROVIDER": "subprocess",
373
+ "EDITOR": "code --wait"
374
+ }
375
+ }
376
+ }
377
+ }
378
+ ```
379
+
380
+ ### Environment Variables & Security
381
+
382
+ Crackerjack supports several environment variables for configuration:
383
+
384
+ - **`UV_PUBLISH_TOKEN`**: PyPI authentication token for publishing ⚠️ **Keep secure!**
385
+ - **`UV_KEYRING_PROVIDER`**: Keyring provider for secure credential storage (e.g., "subprocess")
386
+ - **`EDITOR`**: Default text editor for interactive commit message editing (e.g., "code --wait")
387
+ - **`AI_AGENT`**: Set to "1" to enable AI agent mode with structured JSON output
388
+
389
+ #### 🔒 Security Best Practices
390
+
391
+ **Token Security:**
392
+
393
+ - **Never commit tokens to version control**
394
+ - Use `.env` files (add to `.gitignore`)
395
+ - Prefer keyring over environment variables
396
+ - Rotate tokens regularly
397
+
398
+ **Recommended setup:**
399
+
400
+ ```bash
401
+ # Create .env file (add to .gitignore)
402
+ echo "UV_PUBLISH_TOKEN=pypi-your-token-here" > .env
403
+ echo ".env" >> .gitignore
404
+
405
+ # Or use secure keyring storage
406
+ keyring set https://upload.pypi.org/legacy/ __token__
407
+ ```
408
+
409
+ **Example MCP configuration with environment variables:**
410
+
411
+ ```json
412
+ {
413
+ "mcpServers": {
414
+ "crackerjack": {
415
+ "command": "uvx",
416
+ "args": [
417
+ "--from",
418
+ "/path/to/crackerjack",
419
+ "crackerjack",
420
+ "--start-mcp-server"
421
+ ],
422
+ "env": {
423
+ "UV_KEYRING_PROVIDER": "subprocess",
424
+ "EDITOR": "code --wait",
425
+ "UV_PUBLISH_TOKEN": "pypi-your-token-here"
426
+ }
427
+ }
428
+ }
429
+ }
430
+ ```
431
+
432
+ ### Available MCP Tools
433
+
434
+ **Job Execution & Monitoring:**
435
+
436
+ - **`execute_crackerjack`**: Start iterative auto-fixing with job tracking
437
+ - **`get_job_progress`**: Real-time progress for running jobs
438
+ - **`run_crackerjack_stage`**: Execute specific quality stages (fast, comprehensive, tests)
439
+
440
+ **Error Analysis:**
441
+
442
+ - **`analyze_errors`**: Analyze and categorize code quality errors
443
+ - **`smart_error_analysis`**: AI-powered error analysis with cached patterns
444
+
445
+ **Session Management:**
446
+
447
+ - **`get_stage_status`**: Check current status of quality stages
448
+ - **`get_next_action`**: Get optimal next action based on session state
449
+ - **`session_management`**: Manage sessions with checkpoints and resume capability
450
+
451
+ **WebSocket Endpoints:**
452
+
453
+ - **Server URL**: `ws://localhost:8675`
454
+ - **Progress Streaming**: `/ws/progress/{job_id}` for real-time updates
455
+
456
+ ### Slash Commands
457
+
458
+ **`/crackerjack:run`**: Autonomous code quality enforcement with AI agent
459
+
460
+ ```bash
461
+ # Through MCP
462
+ {
463
+ "command": "/crackerjack:run",
464
+ "args": []
465
+ }
466
+ ```
467
+
468
+ **`/crackerjack:init`**: Initialize or update project configuration
469
+
470
+ ```bash
471
+ # Through MCP
472
+ {
473
+ "command": "/crackerjack:init",
474
+ "args": ["--force"] # Optional: force reinitialize
475
+ }
476
+ ```
477
+
478
+ ## Pre-commit Hook Modes
479
+
480
+ Crackerjack runs hooks in a two-stage process for optimal development workflow:
481
+
482
+ ### Hook Details
483
+
484
+ **Fast Hooks (~5 seconds):**
485
+
486
+ - Ruff formatting and linting
487
+ - Trailing whitespace cleanup
488
+ - UV lock file updates
489
+ - Security credential detection
490
+ - Spell checking
491
+
492
+ **Comprehensive Hooks (~30 seconds):**
493
+
494
+ - Pyright type checking
495
+ - Bandit security analysis
496
+ - Dead code detection (vulture)
497
+ - Dependency analysis (creosote)
498
+ - Complexity limits (complexipy)
499
+ - Modern Python patterns (refurb)
500
+
501
+ ```bash
502
+ # Default behavior runs comprehensive hooks
503
+ python -m crackerjack
504
+
505
+ # Skip hooks if you only want setup/cleaning
506
+ python -m crackerjack -s
507
+ ```
508
+
509
+ ### Common Commands
510
+
511
+ ```bash
512
+ # Quality checks only
513
+ python -m crackerjack
514
+
515
+ # With testing
516
+ python -m crackerjack -t
517
+
518
+ # Full release workflow
519
+ python -m crackerjack -a patch
520
+
521
+ # AI agent mode
522
+ python -m crackerjack --ai-agent
523
+ ```
524
+
525
+ ## Command Reference
526
+
527
+ **Core Commands:**
528
+
529
+ ```bash
530
+ python -m crackerjack # Quality checks
531
+ python -m crackerjack -t # With testing
532
+ python -m crackerjack -a patch # Release workflow
533
+ ```
534
+
535
+ **Options:**
536
+
537
+ - `-i, --interactive`: Rich UI interface
538
+ - `-v, --verbose`: Detailed output
539
+ - `-s, --skip-hooks`: Skip quality checks
540
+ - `-c, --commit`: Auto-commit changes
541
+ - `-x, --clean`: Remove docstrings/comments
542
+
543
+ ## Style Guide
544
+
545
+ **Code Standards:**
546
+
547
+ - Python 3.13+ with modern type hints (`|` unions, PEP 695)
548
+ - No docstrings (self-documenting code)
549
+ - Pathlib over os.path
550
+ - Protocol-based interfaces
551
+ - Cognitive complexity ≤15 per function
552
+ - UV for dependency management
553
+
554
+ ## Publishing & Version Management
555
+
556
+ ### 🔐 Secure PyPI Authentication
557
+
558
+ **Keyring Storage (Most Secure):**
559
+
560
+ ```bash
561
+ # Install keyring support
562
+ uv add keyring
563
+
564
+ # Store token securely
565
+ keyring set https://upload.pypi.org/legacy/ __token__
566
+ # Enter your PyPI token when prompted
567
+ ```
568
+
569
+ **Environment Variable (Alternative):**
570
+
571
+ ```bash
572
+ # For CI/CD or temporary use
573
+ export UV_PUBLISH_TOKEN=pypi-your-token-here
574
+
575
+ # ⚠️ Security Warning: Never commit this to git
576
+ ```
577
+
578
+ **Environment File (Local Development):**
579
+
580
+ ```bash
581
+ # Create .env file (must be in .gitignore)
582
+ echo "UV_PUBLISH_TOKEN=pypi-your-token-here" > .env
583
+ echo ".env" >> .gitignore
584
+ ```
585
+
586
+ ### Version Management
587
+
588
+ ```bash
589
+ python -m crackerjack -p patch # 1.0.0 -> 1.0.1
590
+ python -m crackerjack -p minor # 1.0.0 -> 1.1.0
591
+ python -m crackerjack -p major # 1.0.0 -> 2.0.0
592
+ ```
593
+
594
+ ### 🛡️ Security Considerations
595
+
596
+ - **Token Rotation**: Rotate PyPI tokens every 90 days
597
+ - **Scope Limitation**: Use project-scoped tokens when possible
598
+ - **Access Review**: Regularly audit who has publish access
599
+ - **Backup Tokens**: Keep backup tokens in secure location
600
+
601
+ ## MCP Integration
602
+
603
+ **AI Agent Support:**
604
+ Crackerjack provides a WebSocket-enabled MCP server for AI agent integration:
605
+
606
+ ```bash
607
+ # Start WebSocket MCP server on localhost:8675
608
+ python -m crackerjack --start-mcp-server
609
+
610
+ # Monitor job progress via WebSocket
611
+ python -m crackerjack.mcp.progress_monitor <job_id> ws://localhost:8675
612
+ ```
613
+
614
+ **MCP client configuration (stdio-based):**
615
+
616
+ ```json
617
+ {
618
+ "mcpServers": {
619
+ "crackerjack": {
620
+ "command": "uvx",
621
+ "args": [
622
+ "--from",
623
+ "/path/to/crackerjack",
624
+ "crackerjack",
625
+ "--start-mcp-server"
626
+ ]
627
+ }
628
+ }
629
+ }
630
+ ```
631
+
632
+ **WebSocket MCP client configuration:**
633
+
634
+ - **Server URL**: `ws://localhost:8675`
635
+ - **Protocol**: WebSocket-based MCP with real-time progress streaming
636
+ - **Endpoints**: `/ws/progress/{job_id}` for live job monitoring
637
+
638
+ **Available tools:** `execute_crackerjack`, `get_job_progress`, `run_crackerjack_stage`, `analyze_errors`, `smart_error_analysis`, `get_next_action`, `session_management`
639
+
640
+ ## 🔧 Troubleshooting
641
+
642
+ ### Common Issues
643
+
644
+ #### Installation Problems
645
+
646
+ ```bash
647
+ # UV not found
648
+ curl -LsSf https://astral.sh/uv/install.sh | sh
649
+ source ~/.bashrc
650
+
651
+ # Python 3.13+ required
652
+ uv python install 3.13
653
+ uv python pin 3.13
654
+ ```
655
+
656
+ #### Authentication Errors
657
+
658
+ ```bash
659
+ # PyPI token issues
660
+ keyring get https://upload.pypi.org/legacy/ __token__ # Verify stored token
661
+ keyring set https://upload.pypi.org/legacy/ __token__ # Reset if needed
662
+
663
+ # Permission denied
664
+ chmod +x ~/.local/bin/uv
665
+ ```
666
+
667
+ #### Hook Failures
668
+
669
+ ```bash
670
+ # Pre-commit hooks failing
671
+ python -m crackerjack --skip-hooks # Skip hooks temporarily
672
+ pre-commit clean # Clear hook cache
673
+ pre-commit install --force # Reinstall hooks
674
+
675
+ # Update hooks
676
+ python -m crackerjack --update-precommit
677
+
678
+ # Type checking errors
679
+ python -m crackerjack # Run quality checks
680
+ ```
681
+
682
+ #### MCP Server Issues
683
+
684
+ ```bash
685
+ # Server won't start
686
+ python -m crackerjack --start-mcp-server --verbose
687
+
688
+ # WebSocket connection issues
689
+ # Check if server is running on localhost:8675
690
+ netstat -an | grep :8675
691
+
692
+ # Test WebSocket connectivity
693
+ curl -s "http://localhost:8675/" || echo "Server not responding"
694
+ ```
695
+
696
+ #### Performance Issues
697
+
698
+ ```bash
699
+ # Slow execution
700
+ python -m crackerjack --test-workers 1 # Reduce parallelism
701
+ python -m crackerjack --skip-hooks # Skip time-consuming checks
702
+
703
+ # Memory issues
704
+ export UV_CACHE_DIR=/tmp/uv-cache # Use different cache location
705
+ ```
706
+
707
+ ### Debug Mode
708
+
709
+ ```bash
710
+ # Enable verbose output
711
+ python -m crackerjack --verbose
712
+
713
+ # Check debug logs (in XDG cache directory)
714
+ ls ~/.cache/crackerjack/logs/debug/
715
+
716
+ # MCP debugging
717
+ python -m crackerjack --start-mcp-server --verbose
718
+ ```
719
+
720
+ ### Getting Help
721
+
722
+ - **GitHub Issues**: [Report bugs](https://github.com/lesleslie/crackerjack/issues)
723
+ - **Command Help**: `python -m crackerjack --help`
724
+ - **MCP Tools**: Use `get_next_action` tool for guidance
725
+
726
+ ## Contributing
727
+
728
+ 1. Fork and clone the repository
729
+ 1. Run `uv sync --all-groups` to install dependencies
730
+ 1. Ensure `python -m crackerjack` passes all checks
731
+ 1. Submit pull request
732
+
733
+ **Requirements:** Python 3.13+, UV package manager, all quality checks must pass
734
+
735
+ ## License
736
+
737
+ BSD 3-Clause License - see [LICENSE](LICENSE) file.
738
+
739
+ ______________________________________________________________________
740
+
741
+ **Issues:** [GitHub Issues](https://github.com/lesleslie/crackerjack/issues)
742
+ **Repository:** [GitHub](https://github.com/lesleslie/crackerjack)