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

crackerjack/slash_commands/init.md

@@ -0,0 +1,122 @@
+______________________________________________________________________
+
+## description: Initialize or update crackerjack configuration for a Python project with best practices, quality hooks, and AI guidelines.
+
+# /crackerjack:init
+
+Initialize or update crackerjack configuration for a Python project.
+
+## Usage
+
+```
+/crackerjack:init
+/crackerjack:init --force
+```
+
+## Description
+
+This slash command initializes a new Python project with crackerjack's best practices or updates an existing project's configuration to the latest standards.
+
+## What It Does
+
+1. **Checks Project State**: Verifies which configuration files exist
+1. **Smart Merge Configuration**:
+   - `pyproject.toml` - Intelligently merges tool configurations, preserves higher coverage requirements
+   - `.pre-commit-config.yaml` - Adds missing repos, preserves existing hooks
+   - `CLAUDE.md` - Appends crackerjack guidelines without overwriting existing content
+   - `RULES.md` - Copies only if missing, preserves existing coding standards
+1. **Preserves Project Identity**: Never overwrites existing project metadata, dependencies, or configurations
+1. **Installs Pre-commit Hooks**: Sets up git hooks for quality enforcement
+
+## When to Use /crackerjack:init
+
+### Automatic Detection
+
+The MCP server can detect when initialization is needed:
+
+- **Missing Core Files**: No pyproject.toml or .pre-commit-config.yaml
+- **New Project**: Git repository just initialized
+- **Outdated Hooks**: Pre-commit hooks older than 30 days
+- **Manual Request**: User explicitly asks for initialization
+
+### Recommended Frequency
+
+- **New Projects**: Always run on project creation
+- **Weekly**: For active development projects
+- **After Tool Updates**: When crackerjack or dependencies update
+- **Team Onboarding**: When new developers join
+
+## Options
+
+- `--force`: Force reinitialization even if configuration exists
+
+## Example
+
+```
+User: Set up this Python project with best practices
+AI: I'll initialize crackerjack configuration for your project.
+
+/crackerjack:init
+
+[AI executes initialization and reports results]
+
+The project has been initialized with:
+✅ pyproject.toml - Project configuration
+✅ .pre-commit-config.yaml - Quality hooks
+✅ CLAUDE.md - AI guidelines
+✅ RULES.md - Coding standards
+
+Your project now follows Python best practices!
+```
+
+## Auto-Init Behavior
+
+When connected via MCP, crackerjack can automatically suggest initialization when:
+
+1. Running `/crackerjack:run` in an uninitialized project
+1. Detecting missing critical configuration files
+1. Finding outdated pre-commit hooks (>30 days old)
+
+This ensures projects always have up-to-date quality standards without manual intervention.
+
+## Smart Merge Behavior
+
+**Crackerjack uses intelligent smart merging instead of destructive overwrites:**
+
+### pyproject.toml Smart Merge
+
+- **Preserves Project Identity**: Project name, version, description, dependencies remain untouched
+- **Ensures Crackerjack Dependency**: Adds `crackerjack` to `[dependency-groups].dev` if missing
+- **Merges Tool Configurations**: Adds missing tool sections (`[tool.ruff]`, `[tool.pyright]`, etc.)
+- **Preserves Higher Coverage**: If target has higher `--cov-fail-under` than source, keeps the higher value
+- **Adds Missing Pytest Markers**: Appends new test markers while preserving existing ones
+
+### CLAUDE.md Smart Append
+
+- **Non-Destructive**: Appends crackerjack guidelines with clear markers
+- **Prevents Duplicates**: Skips if crackerjack section already exists
+- **Clear Boundaries**: Uses `<!-- CRACKERJACK_START -->` and `<!-- CRACKERJACK_END -->` markers
+
+### .pre-commit-config.yaml Smart Merge
+
+- **Adds Missing Repos**: Only adds pre-commit repos that don't already exist
+- **Preserves Existing Hooks**: Never modifies existing hook configurations
+- **Skips if No New Repos**: Intelligent detection prevents unnecessary changes
+
+### Universal Compatibility
+
+This smart merge approach works with **any Python package**, not just specific projects:
+
+- ✅ **MCP Servers** (session-mgmt-mcp, excalidraw-mcp)
+- ✅ **Django Projects** with existing configurations
+- ✅ **Flask Applications** with established tooling
+- ✅ **Data Science Projects** with Jupyter-specific settings
+- ✅ **CLI Tools** with complex pyproject.toml configurations
+
+### Example Smart Merge Results
+
+**Before**: Project with 85% coverage requirement
+**After**: Keeps 85% coverage, adds all crackerjack tools, preserves project identity
+
+**Before**: CLAUDE.md with project-specific guidelines
+**After**: Original content + crackerjack section appended with clear markers

crackerjack/slash_commands/run.md

@@ -0,0 +1,163 @@
+______________________________________________________________________
+
+## description: Run Crackerjack with advanced orchestrated AI-powered auto-fix mode to automatically resolve all code quality issues with intelligent execution strategies and granular progress tracking.
+
+# /crackerjack:run
+
+Run Crackerjack with advanced orchestrated AI-powered auto-fix mode to automatically resolve all code quality issues with intelligent execution strategies and granular progress tracking.
+
+## Usage
+
+```
+/crackerjack:run [--debug]
+```
+
+### Arguments
+
+- `--debug`: Run in foreground with debug output visible (for troubleshooting)
+  - Shows all crackerjack command output directly to console
+  - Runs synchronously instead of in background
+  - Useful for debugging issues with hooks, tests, or AI fixes
+  - No need for progress monitoring - output is immediate
+
+## Description
+
+This slash command runs Crackerjack with AI agent mode for autonomous code quality enforcement:
+
+- `--ai-agent`: AI agent mode for structured error output and intelligent fixing
+- `--test`: Run tests with comprehensive test coverage
+- `--verbose`: Show detailed AI decision-making and execution details
+
+## 💡 Agent Recommendation
+
+**For optimal results, use the `crackerjack-architect` agent alongside `/crackerjack:run`:**
+
+```bash
+# 1. Plan with crackerjack-architect first
+Task tool with subagent_type="crackerjack-architect" for feature planning
+
+# 2. Run crackerjack for quality enforcement
+/crackerjack:run
+
+# 3. Use crackerjack-architect for any remaining issues
+```
+
+**Why?** The crackerjack-architect agent ensures code follows crackerjack patterns from the start, reducing the number of iterations needed for `/crackerjack:run` to achieve full compliance.
+
+## What It Does
+
+**Iterative AI-Powered Auto-Fixing Process (up to 10 iterations):**
+
+### Pre-Execution Safety Checks:
+
+0. 🔍 **Comprehensive Status Check** (automatic conflict prevention)
+
+   - Check for active crackerjack jobs in the same project to prevent file conflicts
+   - Verify MCP and WebSocket server health status
+   - Identify beneficial cleanup opportunities (stale temp files, old debug logs)
+   - Auto-start missing services if needed
+   - Report resource usage and system health
+
+### Each Iteration Cycle:
+
+1. ⚡ **Fast Hooks** (formatting & basic fixes)
+
+   - Run `trailing-whitespace`, `end-of-file-fixer`, `ruff-format`, `ruff-check`, `gitleaks`
+   - If any fail → **Retry fast hooks once** (formatting fixes often resolve downstream issues)
+   - Only proceed when fast hooks pass or have been retried
+
+1. 🧪 **Full Test Suite**
+
+   - Run ALL tests, collect ALL test failures (don't stop on first failure)
+   - Gather complete list of failing tests with error details
+
+1. 🔍 **Comprehensive Hooks** (type checking, security, complexity)
+
+   - Run `pyright`, `bandit`, `vulture`, `refurb`, `creosote`, `complexipy`
+   - Collect ALL hook failures (don't stop on first failure)
+   - Gather complete list of quality issues
+
+1. 🤖 **AI Analysis & Batch Fixing**
+
+   - Analyze ALL collected failures (tests + comprehensive hooks)
+   - Apply intelligent fixes for ALL issues in one coordinated pass:
+     - **Type Errors**: Adds missing annotations, fixes type mismatches
+     - **Security Issues**: Removes hardcoded paths, fixes vulnerabilities
+     - **Dead Code**: Removes unused imports, variables, functions
+     - **Test Failures**: Fixes missing fixtures, import errors, assertions
+     - **Code Quality**: Applies refactoring, reduces complexity
+     - **Hook Failures**: All formatting, linting, style issues
+
+1. 🔄 **Next Full Iteration**: Repeat entire cycle until ALL checks pass or max iterations (10) reached
+
+### Final Result:
+
+🎉 **Perfect Code Quality**: All hooks pass, all tests pass, zero manual intervention!
+
+## Example
+
+When an AI assistant uses this command:
+
+```
+User: Can you fix all the code quality issues in this project?
+AI: I'll use the /crackerjack:run command to automatically fix all code quality issues.
+
+/crackerjack:run
+
+[AI runs: python -m crackerjack --ai-agent --test --verbose]
+
+The crackerjack AI agent completed successfully after 3 iterations! Here's what was automatically fixed:
+
+**Iteration 1**: Fixed formatting and imports
+- Reformatted 5 files with proper indentation
+- Organized imports in 3 modules
+- Removed trailing whitespace
+
+**Iteration 2**: Resolved type and security issues
+- Added type hints to 7 functions
+- Fixed 2 hardcoded temp path security warnings
+- Removed 1 unused variable
+
+**Iteration 3**: Final test fixes
+- Fixed missing test fixture import
+- Updated assertion in test_workflow.py
+- All 42 tests now pass with 45% coverage
+
+🎉 **Result**: Perfect code quality achieved with zero manual intervention!
+```
+
+## Benefits
+
+- **Zero Configuration**: AI doesn't need to remember complex flag combinations
+- **Optimal Settings**: Always uses the most effective options
+- **Complete Automation**: Handles the entire quality workflow automatically
+- **Consistent Results**: Same high-quality outcome every time
+
+## Implementation
+
+**CRITICAL**: When an AI assistant encounters `/crackerjack:run`, it MUST ONLY use the MCP server tools. Never fall back to bash/shell execution of `python -m crackerjack`.
+
+When an AI assistant encounters `/crackerjack:run`, it calls the MCP server tool directly:
+
+**Note**: The WebSocket server on localhost:8675 is automatically started when the command runs, so no manual setup is required.
+
+```python
+# Call MCP server tool for orchestrated iterative auto-fixing (returns job_id immediately)
+job_result = execute_crackerjack("/crackerjack:run")
+job_id = job_result["job_id"]
+
+# For debugging, use the --debug flag:
+job_result = execute_crackerjack("/crackerjack:run --debug")
+# This runs in foreground and shows all output directly
+```
+
+This runs the AI agent auto-fixing process:
+
+- **Background Execution**: Workflow runs in background, returns job_id immediately
+- **Progress Tracking**: Real-time progress updates via MCP tools
+- **Autonomous Fixing**: Makes actual code changes to resolve all issues
+- **Comprehensive Coverage**: Handles ALL error types (not just formatting)
+- **Iterative Process**: Continues fixing until perfect quality achieved (up to 10 iterations)
+- **Zero Manual Work**: No human intervention required
+
+**Note**: This is NOT the same as basic hook auto-fix modes (like `ruff --fix`) which only handle simple formatting. The AI agent performs sophisticated code analysis and coordinated modification.

crackerjack/slash_commands/status.md

@@ -0,0 +1,127 @@
+______________________________________________________________________
+
+## description: Check comprehensive Crackerjack system status including running jobs, MCP server health, WebSocket connections, and progress monitoring with real-time updates.
+
+# /crackerjack:status - Comprehensive System Status
+
+Check the comprehensive status of the Crackerjack system including running jobs, MCP server health, WebSocket server status, and progress monitoring. This command provides real-time status from all system components.
+
+## Usage
+
+```
+/crackerjack:status
+```
+
+## What This Command Does
+
+1. **MCP Server Status** - Shows running processes, health, and resource usage
+1. **WebSocket Server Status** - Displays connection status, port, and active monitoring
+1. **Job Management** - Lists all active, completed, and failed jobs with detailed progress
+1. **Progress Tracking** - Shows iteration counts, stage completion, and error resolution metrics
+1. **System Health** - Comprehensive monitoring of all Crackerjack services and components
+1. **Resource Usage** - Memory, CPU, and temporary file statistics
+
+## Example Output
+
+The command will show information like:
+
+```json
+{
+  "services": {
+    "mcp_server": {
+      "running": true,
+      "processes": [
+        {
+          "pid": 12345,
+          "cpu": "0.5%",
+          "mem": "0.8%",
+          "command": "python -m crackerjack --start-mcp-server"
+        }
+      ]
+    },
+    "websocket_server": {
+      "running": true,
+      "port": 8675,
+      "processes": [
+        {
+          "pid": 12346,
+          "cpu": "0.2%",
+          "mem": "0.6%"
+        }
+      ]
+    }
+  },
+  "jobs": {
+    "active_count": 2,
+    "completed_count": 1,
+    "failed_count": 0,
+    "details": [
+      {
+        "job_id": "abc123-def456-ghi789",
+        "status": "running",
+        "iteration": 3,
+        "max_iterations": 10,
+        "current_stage": "comprehensive_hooks",
+        "overall_progress": 30,
+        "stage_progress": 75,
+        "message": "Running pyright type checking...",
+        "error_counts": {
+          "hook_errors": 0,
+          "test_failures": 2,
+          "total": 13
+        }
+      }
+    ]
+  },
+  "server_stats": {
+    "resource_usage": {
+      "temp_files_count": 5,
+      "progress_dir": "/tmp/crackerjack-mcp-progress"
+    },
+    "rate_limiting": {
+      "requests_per_minute": 60,
+      "current_requests": 2,
+      "can_execute": true
+    }
+  }
+}
+```
+
+## When to Use
+
+- **Before starting work** - Check if any jobs are already running
+- **During development** - Monitor progress of long-running jobs
+- **Troubleshooting** - Verify services are running correctly
+- **Planning** - See completion status before starting new work
+
+## Technical Implementation
+
+This command uses the `get_comprehensive_status` MCP tool which:
+
+- **Process Discovery**: Uses `ps aux` to find running Crackerjack processes
+- **Progress File Analysis**: Reads job progress from `/tmp/crackerjack-mcp-progress/job-*.json` files
+- **WebSocket Health**: Checks port availability and connection status
+- **Resource Monitoring**: Tracks temporary files, memory usage, and rate limiting
+- **State Management**: Integrates with MCP server state for session tracking
+
+## Integration
+
+This command integrates with:
+
+- **WebSocket Progress Server** (localhost:8675)
+- **MCP Server** progress and state files
+- **Service Watchdog** monitoring
+- **TUI Monitor** data sources
+- **Server Manager** process discovery
+
+The status information comes from the same sources that power the TUI monitor and web interface, ensuring consistent data across all interfaces.
+
+## Usage in Claude Code
+
+When using this command in Claude Code, the AI agent will:
+
+1. Call the `get_comprehensive_status` MCP tool
+1. Parse the JSON response for relevant information
+1. Present a formatted summary of system health
+1. Highlight any issues requiring attention
+1. Suggest next actions based on current status