crackerjack 0.30.3__py3-none-any.whl → 0.31.7__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.
- crackerjack/CLAUDE.md +1005 -0
- crackerjack/RULES.md +380 -0
- crackerjack/__init__.py +42 -13
- crackerjack/__main__.py +227 -299
- crackerjack/agents/__init__.py +41 -0
- crackerjack/agents/architect_agent.py +281 -0
- crackerjack/agents/base.py +170 -0
- crackerjack/agents/coordinator.py +512 -0
- crackerjack/agents/documentation_agent.py +498 -0
- crackerjack/agents/dry_agent.py +388 -0
- crackerjack/agents/formatting_agent.py +245 -0
- crackerjack/agents/import_optimization_agent.py +281 -0
- crackerjack/agents/performance_agent.py +669 -0
- crackerjack/agents/proactive_agent.py +104 -0
- crackerjack/agents/refactoring_agent.py +788 -0
- crackerjack/agents/security_agent.py +529 -0
- crackerjack/agents/test_creation_agent.py +657 -0
- crackerjack/agents/test_specialist_agent.py +486 -0
- crackerjack/agents/tracker.py +212 -0
- crackerjack/api.py +560 -0
- crackerjack/cli/__init__.py +24 -0
- crackerjack/cli/facade.py +104 -0
- crackerjack/cli/handlers.py +267 -0
- crackerjack/cli/interactive.py +471 -0
- crackerjack/cli/options.py +409 -0
- crackerjack/cli/utils.py +18 -0
- crackerjack/code_cleaner.py +618 -928
- crackerjack/config/__init__.py +19 -0
- crackerjack/config/hooks.py +218 -0
- crackerjack/core/__init__.py +0 -0
- crackerjack/core/async_workflow_orchestrator.py +406 -0
- crackerjack/core/autofix_coordinator.py +200 -0
- crackerjack/core/container.py +104 -0
- crackerjack/core/enhanced_container.py +542 -0
- crackerjack/core/performance.py +243 -0
- crackerjack/core/phase_coordinator.py +585 -0
- crackerjack/core/proactive_workflow.py +316 -0
- crackerjack/core/session_coordinator.py +289 -0
- crackerjack/core/workflow_orchestrator.py +826 -0
- crackerjack/dynamic_config.py +94 -103
- crackerjack/errors.py +263 -41
- crackerjack/executors/__init__.py +11 -0
- crackerjack/executors/async_hook_executor.py +431 -0
- crackerjack/executors/cached_hook_executor.py +242 -0
- crackerjack/executors/hook_executor.py +345 -0
- crackerjack/executors/individual_hook_executor.py +669 -0
- crackerjack/intelligence/__init__.py +44 -0
- crackerjack/intelligence/adaptive_learning.py +751 -0
- crackerjack/intelligence/agent_orchestrator.py +551 -0
- crackerjack/intelligence/agent_registry.py +414 -0
- crackerjack/intelligence/agent_selector.py +502 -0
- crackerjack/intelligence/integration.py +290 -0
- crackerjack/interactive.py +576 -315
- crackerjack/managers/__init__.py +11 -0
- crackerjack/managers/async_hook_manager.py +135 -0
- crackerjack/managers/hook_manager.py +137 -0
- crackerjack/managers/publish_manager.py +433 -0
- crackerjack/managers/test_command_builder.py +151 -0
- crackerjack/managers/test_executor.py +443 -0
- crackerjack/managers/test_manager.py +258 -0
- crackerjack/managers/test_manager_backup.py +1124 -0
- crackerjack/managers/test_progress.py +114 -0
- crackerjack/mcp/__init__.py +0 -0
- crackerjack/mcp/cache.py +336 -0
- crackerjack/mcp/client_runner.py +104 -0
- crackerjack/mcp/context.py +621 -0
- crackerjack/mcp/dashboard.py +636 -0
- crackerjack/mcp/enhanced_progress_monitor.py +479 -0
- crackerjack/mcp/file_monitor.py +336 -0
- crackerjack/mcp/progress_components.py +569 -0
- crackerjack/mcp/progress_monitor.py +949 -0
- crackerjack/mcp/rate_limiter.py +332 -0
- crackerjack/mcp/server.py +22 -0
- crackerjack/mcp/server_core.py +244 -0
- crackerjack/mcp/service_watchdog.py +501 -0
- crackerjack/mcp/state.py +395 -0
- crackerjack/mcp/task_manager.py +257 -0
- crackerjack/mcp/tools/__init__.py +17 -0
- crackerjack/mcp/tools/core_tools.py +249 -0
- crackerjack/mcp/tools/error_analyzer.py +308 -0
- crackerjack/mcp/tools/execution_tools.py +372 -0
- crackerjack/mcp/tools/execution_tools_backup.py +1097 -0
- crackerjack/mcp/tools/intelligence_tool_registry.py +80 -0
- crackerjack/mcp/tools/intelligence_tools.py +314 -0
- crackerjack/mcp/tools/monitoring_tools.py +502 -0
- crackerjack/mcp/tools/proactive_tools.py +384 -0
- crackerjack/mcp/tools/progress_tools.py +217 -0
- crackerjack/mcp/tools/utility_tools.py +341 -0
- crackerjack/mcp/tools/workflow_executor.py +565 -0
- crackerjack/mcp/websocket/__init__.py +14 -0
- crackerjack/mcp/websocket/app.py +39 -0
- crackerjack/mcp/websocket/endpoints.py +559 -0
- crackerjack/mcp/websocket/jobs.py +253 -0
- crackerjack/mcp/websocket/server.py +116 -0
- crackerjack/mcp/websocket/websocket_handler.py +78 -0
- crackerjack/mcp/websocket_server.py +10 -0
- crackerjack/models/__init__.py +31 -0
- crackerjack/models/config.py +93 -0
- crackerjack/models/config_adapter.py +230 -0
- crackerjack/models/protocols.py +118 -0
- crackerjack/models/task.py +154 -0
- crackerjack/monitoring/ai_agent_watchdog.py +450 -0
- crackerjack/monitoring/regression_prevention.py +638 -0
- crackerjack/orchestration/__init__.py +0 -0
- crackerjack/orchestration/advanced_orchestrator.py +970 -0
- crackerjack/orchestration/coverage_improvement.py +223 -0
- crackerjack/orchestration/execution_strategies.py +341 -0
- crackerjack/orchestration/test_progress_streamer.py +636 -0
- crackerjack/plugins/__init__.py +15 -0
- crackerjack/plugins/base.py +200 -0
- crackerjack/plugins/hooks.py +246 -0
- crackerjack/plugins/loader.py +335 -0
- crackerjack/plugins/managers.py +259 -0
- crackerjack/py313.py +8 -3
- crackerjack/services/__init__.py +22 -0
- crackerjack/services/cache.py +314 -0
- crackerjack/services/config.py +358 -0
- crackerjack/services/config_integrity.py +99 -0
- crackerjack/services/contextual_ai_assistant.py +516 -0
- crackerjack/services/coverage_ratchet.py +356 -0
- crackerjack/services/debug.py +736 -0
- crackerjack/services/dependency_monitor.py +617 -0
- crackerjack/services/enhanced_filesystem.py +439 -0
- crackerjack/services/file_hasher.py +151 -0
- crackerjack/services/filesystem.py +421 -0
- crackerjack/services/git.py +176 -0
- crackerjack/services/health_metrics.py +611 -0
- crackerjack/services/initialization.py +873 -0
- crackerjack/services/log_manager.py +286 -0
- crackerjack/services/logging.py +174 -0
- crackerjack/services/metrics.py +578 -0
- crackerjack/services/pattern_cache.py +362 -0
- crackerjack/services/pattern_detector.py +515 -0
- crackerjack/services/performance_benchmarks.py +653 -0
- crackerjack/services/security.py +163 -0
- crackerjack/services/server_manager.py +234 -0
- crackerjack/services/smart_scheduling.py +144 -0
- crackerjack/services/tool_version_service.py +61 -0
- crackerjack/services/unified_config.py +437 -0
- crackerjack/services/version_checker.py +248 -0
- crackerjack/slash_commands/__init__.py +14 -0
- crackerjack/slash_commands/init.md +122 -0
- crackerjack/slash_commands/run.md +163 -0
- crackerjack/slash_commands/status.md +127 -0
- crackerjack-0.31.7.dist-info/METADATA +742 -0
- crackerjack-0.31.7.dist-info/RECORD +149 -0
- crackerjack-0.31.7.dist-info/entry_points.txt +2 -0
- crackerjack/.gitignore +0 -34
- crackerjack/.libcst.codemod.yaml +0 -18
- crackerjack/.pdm.toml +0 -1
- crackerjack/crackerjack.py +0 -3805
- crackerjack/pyproject.toml +0 -286
- crackerjack-0.30.3.dist-info/METADATA +0 -1290
- crackerjack-0.30.3.dist-info/RECORD +0 -16
- {crackerjack-0.30.3.dist-info → crackerjack-0.31.7.dist-info}/WHEEL +0 -0
- {crackerjack-0.30.3.dist-info → crackerjack-0.31.7.dist-info}/licenses/LICENSE +0 -0
|
@@ -0,0 +1,742 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: crackerjack
|
|
3
|
+
Version: 0.31.7
|
|
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
|
+
[](https://www.python.org/downloads/)
|
|
65
|
+
[](https://pytest.org)
|
|
66
|
+
[](https://github.com/astral-sh/ruff)
|
|
67
|
+
[](https://github.com/astral-sh/uv)
|
|
68
|
+
[](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)
|