crackerjack 0.18.2__py3-none-any.whl → 0.45.2__py3-none-any.whl

crackerjack/slash_commands/run.md

@@ -0,0 +1,197 @@
+______________________________________________________________________
+
+## description: Run crackerjack with AI-powered auto-fixing using intelligent session integration. Automatically tries enhanced session-mgmt execution first, then gracefully falls back to standard crackerjack execution if unavailable. Perfect for comprehensive code quality enforcement with zero configuration required.
+
+# /run
+
+Intelligent crackerjack runner that tries session-mgmt:crackerjack-run first with fallback to crackerjack:run for optimal integration with session management systems.
+
+## Usage
+
+```
+/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 provides intelligent crackerjack execution with automatic fallback:
+
+1. **Primary**: Attempts `session-mgmt:crackerjack-run` for enhanced session integration
+1. **Fallback**: Uses `crackerjack:run` if session-mgmt is unavailable
+
+Both execution paths use AI agent mode for autonomous code quality enforcement:
+
+- `--ai-fix`: AI auto-fixing 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 `/run`:**
+
+```bash
+# 1. Plan with crackerjack-architect first
+Task tool with subagent_type="crackerjack-architect" for feature planning
+
+# 2. Run crackerjack for quality enforcement
+/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 `/run` to achieve full compliance.
+
+## What It Does
+
+**Smart Execution Strategy:**
+
+### 1. 🧠 **Session-Mgmt Integration (Primary)**
+
+When `session-mgmt:crackerjack-run` is available:
+
+- **Enhanced Context**: Leverages session history for better AI decisions
+- **Progress Continuity**: Builds on previous session learnings
+- **Memory Integration**: Remembers past error patterns and fixes
+- **Quality Trends**: Uses historical quality metrics for optimization
+
+### 2. 🔄 **Standard Execution (Fallback)**
+
+When session-mgmt is unavailable, falls back to `crackerjack:run`:
+
+- **Full Functionality**: Complete AI auto-fixing capabilities
+- **Zero Degradation**: All quality features remain available
+- **Seamless Transition**: User experience unchanged
+
+### 3. ⚡ **Iterative AI-Powered Auto-Fixing Process (up to 10 iterations)**
+
+Both execution paths follow the same comprehensive workflow:
+
+#### 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 /run command to automatically fix all code quality issues with intelligent session integration.
+
+/run
+
+[AI first tries: session-mgmt:crackerjack-run]
+✅ Session-mgmt available - using enhanced execution mode
+
+[Enhanced execution with session context: python -m crackerjack --ai-fix --test --verbose]
+
+The crackerjack AI agent completed successfully after 2 iterations! Here's what was automatically fixed:
+
+**Session Context Benefits**:
+- Leveraged previous session learnings about this codebase
+- Applied remembered fix patterns from similar issues
+- Optimized execution based on historical performance data
+
+**Iteration 1**: Fixed formatting and imports
+- Reformatted 5 files with proper indentation
+- Organized imports in 3 modules (using cached preferences)
+- Removed trailing whitespace
+
+**Iteration 2**: Final quality improvements
+- Added type hints to 4 functions (improved from previous 7 due to session learning)
+- All 42 tests now pass with 47% coverage
+
+🎉 **Result**: Perfect code quality achieved with enhanced session integration!
+```
+
+## Benefits
+
+- **Smart Integration**: Automatically leverages session-mgmt when available
+- **Graceful Fallback**: No functionality loss when session-mgmt unavailable
+- **Enhanced Learning**: Session context improves AI decision quality
+- **Zero Configuration**: AI doesn't need to remember complex integration logic
+- **Optimal Performance**: Uses best available execution method automatically
+- **Consistent Results**: Same high-quality outcome regardless of execution path
+
+## Implementation
+
+**CRITICAL**: When an AI assistant encounters `/run`, it MUST implement the intelligent fallback strategy using MCP server tools.
+
+### Execution Strategy
+
+```python
+# 1. Try session-mgmt integration first
+try:
+    job_result = session_mgmt_crackerjack_run()
+    job_id = job_result["job_id"]
+    print("✅ Using session-mgmt enhanced execution")
+except (ConnectionError, ServiceUnavailable, ToolNotFound):
+    # 2. Fallback to standard crackerjack execution
+    job_result = execute_crackerjack("/crackerjack:run")
+    job_id = job_result["job_id"]
+    print("⚡ Using standard crackerjack execution")
+
+# For debugging, append --debug flag to either execution path:
+# session_mgmt_crackerjack_run("--debug") or execute_crackerjack("/crackerjack:run --debug")
+```
+
+### Key Features
+
+- **Automatic Detection**: No manual configuration needed
+- **Seamless Fallback**: User unaware of which execution path used
+- **Progress Tracking**: Real-time progress updates via MCP tools for both paths
+- **Enhanced Context**: Session-mgmt path leverages conversation history
+- **Background Execution**: Both paths run in background, return job_id immediately
+- **Debug Support**: --debug flag works with both execution methods
+
+**Note**: This command provides the best of both worlds - enhanced session integration when available, with full functionality guaranteed through intelligent fallback.

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

crackerjack/tools/README.md

@@ -0,0 +1,11 @@
+> Crackerjack Docs: [Main](<../../README.md>) | [Crackerjack Package](<../README.md>) | [Tools](<./README.md>)
+
+# Package Tools
+
+Internal helper tools used within the package (distinct from top-level `tools/`).
+
+## Related
+
+- [Crackerjack Package](<../README.md>) - Parent package
+- [MCP](<../mcp/README.md>) - MCP tool implementations
+- [Services](<../services/README.md>) - Service layer using these tools

crackerjack/tools/__init__.py

@@ -0,0 +1,30 @@
+"""Native tool implementations for crackerjack (Phase 8).
+
+This package contains Python implementations of quality checking tools,
+providing direct invocation without pre-commit wrapper overhead.
+
+Native tools replace pre-commit-hooks utilities with equivalent functionality:
+- trailing_whitespace: Remove trailing whitespace
+- end_of_file_fixer: Ensure files end with newline
+- check_yaml: Validate YAML syntax
+- check_toml: Validate TOML syntax
+- check_json: Validate JSON syntax
+- check_ast: Validate Python AST syntax
+- format_json: Format JSON files
+- check_jsonschema: Validate JSON files against schemas
+- check_added_large_files: Warn on large file additions
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "trailing_whitespace",
+    "end_of_file_fixer",
+    "check_yaml",
+    "check_toml",
+    "check_json",
+    "check_ast",
+    "format_json",
+    "check_jsonschema",
+    "check_added_large_files",
+]

crackerjack/tools/_git_utils.py

@@ -0,0 +1,105 @@
+"""Git-aware file discovery utilities for native tools.
+
+This module provides utilities for discovering files while respecting .gitignore
+patterns. It uses `git ls-files` to automatically handle gitignore compliance,
+making crackerjack behave identically to pre-commit.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+def get_git_tracked_files(pattern: str | None = None) -> list[Path]:
+    """Get list of files tracked by git, optionally filtered by pattern.
+
+    This function uses `git ls-files` which automatically respects .gitignore
+    patterns. This is the industry-standard approach used by pre-commit and
+    ensures only git-tracked files are processed.
+
+    Args:
+        pattern: Optional glob pattern to filter files (e.g., "*.py", "*.yaml")
+                If None, returns all tracked files.
+
+    Returns:
+        List of Path objects for git-tracked files matching the pattern.
+        Falls back to empty list if not in a git repository.
+
+    Example:
+        >>> # Get all tracked Python files
+        >>> python_files = get_git_tracked_files("*.py")
+        >>> # Get all tracked YAML files
+        >>> yaml_files = get_git_tracked_files("*.yaml")
+    """
+    try:
+        cmd = ["git", "ls-files"]
+        if pattern:
+            cmd.append(pattern)
+
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            check=True,
+            cwd=Path.cwd(),
+        )
+
+        # Filter to only include files that actually exist on disk
+        # (git ls-files can include deleted files still in the index)
+        return [
+            Path(line.strip())
+            for line in result.stdout.splitlines()
+            if line.strip() and Path(line.strip()).exists()
+        ]
+
+    except subprocess.CalledProcessError:
+        # Git command failed (not in a git repo, etc.)
+        return []
+    except FileNotFoundError:
+        # Git not available
+        return []
+
+
+def get_files_by_extension(extensions: list[str], use_git: bool = True) -> list[Path]:
+    """Get files with specified extensions, respecting git if available.
+
+    Args:
+        extensions: List of file extensions to match (e.g., [".py", ".yaml"])
+        use_git: If True (default), use git ls-files when in a git repo.
+                If False, use Path.rglob() for all files.
+
+    Returns:
+        List of Path objects matching the extensions.
+        Automatically respects .gitignore when use_git=True.
+
+    Example:
+        >>> # Get Python files (git-aware)
+        >>> py_files = get_files_by_extension([".py"])
+        >>> # Get YAML files (all files, ignore git)
+        >>> yaml_files = get_files_by_extension([".yaml", ".yml"], use_git=False)
+    """
+    if not use_git:
+        # Fallback to rglob for all files
+        files = []
+        for ext in extensions:
+            files.extend(Path.cwd().rglob(f"*{ext}"))
+        return [f for f in files if f.is_file()]
+
+    # Try git-aware discovery first
+    files = []
+    for ext in extensions:
+        # git ls-files pattern: *.ext
+        pattern = f"*{ext}"
+        git_files = get_git_tracked_files(pattern)
+        if git_files:
+            files.extend(git_files)
+
+    if files:
+        return files
+
+    # Fallback to rglob if git unavailable
+    result = []
+    for ext in extensions:
+        result.extend(Path.cwd().rglob(f"*{ext}"))
+    return [f for f in result if f.is_file()]

crackerjack/tools/check_added_large_files.py

@@ -0,0 +1,139 @@
+"""Check for large files added to git repository.
+
+This tool is a native Python implementation replacing pre-commit's
+check-added-large-files hook. It warns about files exceeding a size threshold.
+
+Usage:
+    python -m crackerjack.tools.check_added_large_files [files...]
+
+Exit Codes:
+    0: No large files found
+    1: One or more large files detected
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from crackerjack.tools._git_utils import get_git_tracked_files
+
+
+def get_file_size(file_path: Path) -> int:
+    """Get file size in bytes.
+
+    Args:
+        file_path: Path to file
+
+    Returns:
+        File size in bytes, or 0 if file doesn't exist
+    """
+    try:
+        return file_path.stat().st_size
+    except (FileNotFoundError, OSError):
+        return 0
+
+
+def format_size(size_bytes: int | float) -> str:
+    """Format file size in human-readable format.
+
+    Args:
+        size_bytes: Size in bytes
+
+    Returns:
+        Human-readable size string (e.g., "1.5 MB")
+    """
+    size: float = float(size_bytes)
+    for unit in ("B", "KB", "MB", "GB"):
+        if size < 1024.0:
+            return f"{size:.1f} {unit}"
+        size /= 1024.0
+    return f"{size:.1f} TB"
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main entry point for check-added-large-files tool.
+
+    Args:
+        argv: Command-line arguments (defaults to sys.argv[1:])
+
+    Returns:
+        Exit code: 0 if no large files, 1 if large files found
+    """
+    parser = argparse.ArgumentParser(
+        description="Check for large files in git repository"
+    )
+    parser.add_argument(
+        "files",
+        nargs="*",
+        type=Path,
+        help="Files to check (default: all git-tracked files)",
+    )
+    parser.add_argument(
+        "--maxkb",
+        type=int,
+        default=1000,
+        help="Maximum file size in KB (default: 1000)",
+    )
+    parser.add_argument(
+        "--enforce-all",
+        action="store_true",
+        help="Check all files, not just newly added ones",
+    )
+
+    # When called from tests, avoid picking up pytest argv
+    if argv is None:
+        argv = []
+    args = parser.parse_args(argv)
+
+    # Convert KB to bytes
+    max_size_bytes = args.maxkb * 1024
+
+    # Determine which files to check
+    if not args.files:
+        # Get all git-tracked files, respecting gitignore
+        files = get_git_tracked_files()
+        if not files:
+            # Fallback to all files in current directory if not in git repo
+            files = list(Path.cwd().rglob("*"))
+            files = [f for f in files if f.is_file()]
+    else:
+        files = args.files
+
+    # Filter to existing files only
+    files = [f for f in files if f.is_file()]
+
+    if not files:
+        print("No files to check")  # noqa: T201
+        return 0
+
+    # Process files
+    large_files = []
+    for file_path in files:
+        size = get_file_size(file_path)
+        if size > max_size_bytes:
+            large_files.append((file_path, size))
+
+    # Report results
+    if large_files:
+        print("Large files detected:", file=sys.stderr)  # noqa: T201
+        for file_path, size in large_files:
+            print(
+                f"  {file_path}: {format_size(size)} "
+                f"(exceeds {format_size(max_size_bytes)})",
+                file=sys.stderr,
+            )  # noqa: T201
+        print(
+            f"\n{len(large_files)} large file(s) found. "
+            f"Consider using Git LFS for large files.",
+            file=sys.stderr,
+        )  # noqa: T201
+        return 1
+
+    print("All files are under size limit")  # noqa: T201
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())