crackerjack 0.31.17__tar.gz → 0.32.0__tar.gz

{crackerjack-0.31.17 → crackerjack-0.32.0}/.gitignore

@@ -89,11 +89,14 @@ __pycache__/
 /dist/
 /error-context.json
 /examples/
+/feature-implementation-*.md
 /hooks-analysis.json
 /htmlcov/
 /project-structure.json
 /quality-metrics.json
 /scratch/
+/session_handoff_*.md
+/test-implementation-*.md
 /test-results.xml
 /tests/.benchmarks/
 /tests/htmlcov/

{crackerjack-0.31.17/crackerjack → crackerjack-0.32.0}/.pre-commit-config.yaml

@@ -3,7 +3,7 @@ repos:
     hooks:
       - id: validate-regex-patterns
         name: validate-regex-patterns
-        entry: uv run python /Users/les/Projects/crackerjack/tools/validate_regex_patterns_standalone.py
+        entry: uv run python -m crackerjack.tools.validate_regex_patterns
         language: system
         files: \.py$
         exclude: ^\.venv/

{crackerjack-0.31.17 → crackerjack-0.32.0}/CHANGELOG.md

@@ -95,6 +95,156 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - fix: resolve bug in parser
 
+## [Unreleased] - 2025-09-06
+
+### Added
+
+- feat: add new feature
+
+### Fixed
+
+- fix: resolve bug in parser
+
+## [Unreleased] - 2025-09-06
+
+### Added
+
+- feat: add new feature
+
+### Fixed
+
+- fix: resolve bug in parser
+
+## [Unreleased] - 2025-09-06
+
+### Added
+
+- feat: add new feature
+
+### Fixed
+
+- fix: resolve bug in parser
+
+## [Unreleased] - 2025-09-06
+
+### Added
+
+- feat: add new feature
+
+### Fixed
+
+- fix: resolve bug in parser
+
+## [Unreleased] - 2025-09-06
+
+### Added
+
+- feat: add new feature
+
+### Fixed
+
+- fix: resolve bug in parser
+
+## [Unreleased] - 2025-09-06
+
+### Added
+
+- feat: add new feature
+
+### Fixed
+
+- fix: resolve bug in parser
+
+## [Unreleased] - 2025-09-06
+
+### Added
+
+- feat: add new feature
+
+### Fixed
+
+- fix: resolve bug in parser
+
+## [Unreleased] - 2025-09-06
+
+### Added
+
+- feat: add new feature
+
+### Fixed
+
+- fix: resolve bug in parser
+
+## [Unreleased] - 2025-09-06
+
+### Added
+
+- feat: add new feature
+
+### Fixed
+
+- fix: resolve bug in parser
+
+## [Unreleased] - 2025-09-06
+
+### Added
+
+- feat: add new feature
+
+### Fixed
+
+- fix: resolve bug in parser
+
+## [Unreleased] - 2025-09-06
+
+### Added
+
+- feat: add new feature
+
+### Fixed
+
+- fix: resolve bug in parser
+
+## [Unreleased] - 2025-09-06
+
+### Added
+
+- feat: add new feature
+
+### Fixed
+
+- fix: resolve bug in parser
+
+## [Unreleased] - 2025-09-06
+
+### Added
+
+- feat: add new feature
+
+### Fixed
+
+- fix: resolve bug in parser
+
+## [Unreleased] - 2025-09-06
+
+### Added
+
+- feat: add new feature
+
+### Fixed
+
+- fix: resolve bug in parser
+
+## [Unreleased] - 2025-09-06
+
+### Added
+
+- feat: add new feature
+
+### Fixed
+
+- fix: resolve bug in parser
+
 ## [Unreleased] - 2025-09-05
 
 ### Added

crackerjack-0.32.0/CLAUDE.md

@@ -0,0 +1,207 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Crackerjack is an opinionated Python project management tool unifying UV, Ruff, pytest, and pre-commit into a single workflow with AI agent integration via MCP.
+
+**Key Dependencies**: Python 3.13+, UV, pre-commit, pytest
+
+**Clean Code Philosophy**: DRY/YAGNI/KISS - Every line is a liability. Optimize for readability with self-documenting code.
+
+## AI Documentation References
+
+- **[AI-REFERENCE.md](AI-REFERENCE.md)** - Command reference with decision trees
+- **[AGENT-CAPABILITIES.json](AGENT-CAPABILITIES.json)** - Structured agent data
+- **[ERROR-PATTERNS.yaml](ERROR-PATTERNS.yaml)** - Automated issue resolution patterns
+
+## Essential Commands
+
+```bash
+# Daily workflow
+python -m crackerjack                    # Quality checks
+python -m crackerjack -t                 # With tests
+python -m crackerjack --ai-agent -t      # AI auto-fixing (recommended)
+
+# Development
+python -m crackerjack --ai-debug -t      # Debug AI issues
+python -m crackerjack --skip-hooks       # Skip hooks during iteration
+python -m crackerjack -x                 # Code cleaning mode
+
+# Server management
+python -m crackerjack --start-mcp-server    # MCP server
+python -m crackerjack --watchdog            # Monitor/restart services
+
+# Release
+python -m crackerjack -a patch              # Full release workflow
+```
+
+## AI Agent System
+
+**9 Specialized Agents** handle domain-specific issues:
+
+- **RefactoringAgent** (0.9): Complexity ≤15, dead code removal
+- **PerformanceAgent** (0.85): O(n²) detection, optimization
+- **SecurityAgent** (0.8): Hardcoded paths, unsafe operations
+- **DocumentationAgent** (0.8): Changelog, .md consistency
+- **TestCreationAgent** (0.8): Test failures, fixtures
+- **DRYAgent** (0.8): Code duplication patterns
+- **FormattingAgent** (0.8): Style violations, imports
+- **ImportOptimizationAgent**: Import cleanup, reorganization
+- **TestSpecialistAgent** (0.8): Advanced testing scenarios
+
+**Usage**: `--ai-agent` enables batch fixing; confidence ≥0.7 uses specific agents
+
+## Architecture
+
+**Modular DI Architecture**: `__main__.py` → `WorkflowOrchestrator` → Coordinators → Managers → Services
+
+**Critical Pattern**: Always import protocols from `models/protocols.py`, never concrete classes
+
+```python
+# ❌ Wrong
+from ..managers.test_manager import TestManager
+
+# ✅ Correct
+from ..models.protocols import TestManagerProtocol
+```
+
+**Core Layers**:
+
+- **Orchestration**: `WorkflowOrchestrator`, DI containers, lifecycle management
+- **Coordinators**: Session/phase coordination, async workflows, parallel execution
+- **Managers**: Hook execution (fast→comprehensive), test management, publishing
+- **Services**: Filesystem, git, config, security, health monitoring
+
+## Testing & Development
+
+```bash
+# Specific test
+python -m pytest tests/test_file.py::TestClass::test_method -v
+
+# Coverage
+python -m pytest --cov=crackerjack --cov-report=html
+
+# Custom workers
+python -m crackerjack -t --test-workers 4
+
+# Version bump
+python -m crackerjack --bump patch
+```
+
+## Quality Process
+
+**Workflow Order**:
+
+1. **Fast Hooks** (~5s): formatting, basic checks → retry once if fail
+1. **Full Test Suite**: collect ALL failures, don't stop on first
+1. **Comprehensive Hooks** (~30s): type checking, security, complexity → collect ALL issues
+1. **AI Batch Fixing**: process all collected failures together
+
+**Testing**: pytest with asyncio, 300s timeout, auto-detected workers
+**Coverage**: Ratchet system targeting 100%, never decrease
+
+## Code Standards
+
+**Quality Rules**:
+
+- **Complexity ≤15** per function
+- **No hardcoded paths** (use `tempfile`)
+- **No shell=True** in subprocess
+- **Type annotations required**
+- **Protocol-based DI**
+- **Python 3.13+**: `|` unions, protocols, pathlib
+
+**Refactoring Pattern**: Break complex methods into helpers
+
+```python
+def complex_method(self, data: dict) -> bool:
+    if not self._validate_input(data):
+        return self._handle_invalid_input()
+    processed = self._process_data(data)
+    return self._save_results(processed)
+```
+
+**Critical Regex Safety**: NEVER write raw regex. Use centralized registry:
+
+```python
+# ❌ DANGEROUS
+text = re.sub(r"(\w+) - (\w+)", r"\g < 1 >-\g < 2 >", text)
+
+# ✅ SAFE
+from crackerjack.services.regex_patterns import SAFE_PATTERNS
+
+text = SAFE_PATTERNS["fix_hyphenated_names"].apply(text)
+```
+
+## Common Issues & Solutions
+
+**Development**:
+
+- **AI agent ineffective**: Use `--ai-debug -t` for analysis
+- **Import errors**: Always import protocols from `models/protocols.py`
+- **Test hangs**: Avoid complex async tests, use simple synchronous config tests
+- **Coverage failing**: Never reduce below baseline, add tests incrementally
+- **Complexity >15**: Break into helper methods using RefactoringAgent approach
+
+**Server**:
+
+- **MCP not starting**: `--restart-mcp-server` or `--watchdog`
+- **Terminal stuck**: `stty sane; reset; exec $SHELL -l`
+- **Slow tests**: Customize `--test-workers N` or use `--skip-hooks`
+
+## MCP Server Integration
+
+**Features**: Dual protocol (MCP + WebSocket), real-time progress, job tracking
+
+```bash
+# Start server
+python -m crackerjack --start-mcp-server
+
+# Monitor progress at http://localhost:8675/
+python -m crackerjack.mcp.progress_monitor <job_id>
+```
+
+**Available Tools**: `execute_crackerjack`, `get_job_progress`, `get_comprehensive_status`, `analyze_errors`
+
+**Slash Commands**: `/crackerjack:run`, `/crackerjack:status`, `/crackerjack:init`
+
+## Critical Reminders
+
+**Core Instructions**:
+
+- Do only what's asked, nothing more
+- NEVER create files unless absolutely necessary
+- ALWAYS prefer editing existing files
+- MAINTAIN coverage ratchet
+
+**Quality Standards**:
+
+- **Test Quality**: Avoid async tests that hang, use synchronous config tests
+- **Import Compliance**: Use protocols from `models/protocols.py`
+- **Fix failures FIRST** before creating new tests
+- Use IDE diagnostics after implementation
+
+**Failure Patterns to Avoid**:
+
+```python
+# ❌ Async tests that hang
+@pytest.mark.asyncio
+async def test_batch_processing(self, batched_saver):
+    await batched_saver.start()  # Can hang
+
+
+# ✅ Simple synchronous tests
+def test_batch_configuration(self, batched_saver):
+    assert batched_saver.max_batch_size == expected_size
+
+
+# ❌ Import concrete classes
+from ..managers.test_manager import TestManager
+
+# ✅ Import protocols
+from ..models.protocols import TestManagerProtocol
+```
+
+**Current Status**: 10.11% coverage baseline targeting 100% (ratchet system: 2% tolerance, never reduce)

{crackerjack-0.31.17 → crackerjack-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crackerjack
-Version: 0.31.17
+Version: 0.32.0
 Summary: Opinionated Python project management tool
 Project-URL: documentation, https://github.com/lesleslie/crackerjack
 Project-URL: homepage, https://github.com/lesleslie/crackerjack

crackerjack-0.32.0/REFACTORING_SUMMARY.md

@@ -0,0 +1,123 @@
+# Workflow Orchestrator Refactoring Summary
+
+## Overview
+Successfully refactored the `WorkflowOrchestrator` class in `/crackerjack/core/workflow_orchestrator.py` to eliminate code duplication while preserving all security hardening implementations.
+
+## Issues Addressed
+
+### 1. Code Duplication Elimination
+**Problem**: The `_handle_ai_agent_workflow` and `_handle_standard_workflow` methods contained ~40 lines of duplicated security checking logic.
+
+**Solution**: Extracted shared logic into focused helper methods:
+
+- `_check_security_gates_for_publishing()` - Centralized security gate checking
+- `_handle_security_gate_failure()` - Unified security failure handling with optional AI fixing
+- `_determine_ai_fixing_needed()` - Logic for when AI fixing should trigger
+- `_determine_workflow_success()` - Success determination based on workflow type
+- `_show_verbose_failure_details()` - Detailed failure reporting
+
+### 2. Complexity Reduction
+**Before**: Both main workflow methods had high complexity due to nested conditionals and duplicated logic.
+
+**After**: 
+- Simplified main methods to orchestrate helper functions
+- Each helper method focuses on a single responsibility
+- Complexity ≤15 per function (verified via complexipy hook)
+
+### 3. Maintainability Improvement
+**Follows DRY/YAGNI/KISS Principles**:
+- **DRY**: Eliminated 40+ lines of duplicated security logic
+- **YAGNI**: Each helper method has a focused, single purpose
+- **KISS**: Complex nested conditionals replaced with clear method calls
+
+## Key Refactoring Changes
+
+### Before (Duplicated Logic)
+```python
+# In _handle_ai_agent_workflow
+if publishing_requested:
+    try:
+        security_blocks_publishing = self._check_security_critical_failures()
+    except Exception as e:
+        self.logger.warning(f"Security check failed: {e} - blocking publishing")
+        self.console.print("[red]🔒 SECURITY CHECK FAILED...")
+        return False
+    # ... 40+ more lines of similar logic
+
+# In _handle_standard_workflow  
+if publishing_requested:
+    try:
+        security_blocks_publishing = self._check_security_critical_failures()
+    except Exception as e:
+        self.logger.warning(f"Security check failed: {e} - blocking publishing") 
+        self.console.print("[red]🔒 SECURITY CHECK FAILED...")
+        return False
+    # ... 40+ more lines of duplicated logic
+```
+
+### After (Clean Extraction)
+```python
+# In both methods
+publishing_requested, security_blocks = self._check_security_gates_for_publishing(options)
+
+if publishing_requested and security_blocks:
+    return await self._handle_security_gate_failure(options, allow_ai_fixing=True/False)
+```
+
+## Security Preservation
+**Critical**: All security hardening work by the security-auditor has been preserved:
+
+- ✅ Security gate blocking logic intact
+- ✅ AI fixing security re-validation preserved  
+- ✅ Fail-secure exception handling maintained
+- ✅ Security audit reporting unchanged
+- ✅ OWASP compliance patterns preserved
+
+## Quality Improvements
+
+### Code Quality Metrics
+- **Lines Reduced**: ~40 lines of duplication eliminated
+- **Complexity**: All methods now ≤15 complexity (meets project standards)
+- **Maintainability**: Single points of change for security logic
+- **Readability**: Clear method names describe intent
+
+### Testing Results
+- ✅ Fast hooks: 12/12 passing
+- ✅ Complexity checks: All passing (complexipy)
+- ✅ Basic workflow functionality: Working correctly
+- ✅ Command-line interface: All features operational
+
+## Method Responsibilities
+
+### Core Workflow Methods (Simplified)
+- `_handle_ai_agent_workflow()`: Orchestrates AI workflow with security checks
+- `_handle_standard_workflow()`: Orchestrates standard workflow with security checks
+
+### Helper Methods (New)
+- `_check_security_gates_for_publishing()`: Security gate checking logic
+- `_handle_security_gate_failure()`: Security failure handling (with/without AI)
+- `_determine_ai_fixing_needed()`: AI fixing trigger logic
+- `_determine_workflow_success()`: Success criteria determination  
+- `_show_verbose_failure_details()`: Failure detail reporting
+
+## Benefits Achieved
+
+1. **DRY Compliance**: No duplicated security logic
+2. **Single Responsibility**: Each method has one clear purpose
+3. **Easier Maintenance**: Security logic changes in one place
+4. **Better Testability**: Helper methods can be tested independently  
+5. **Improved Readability**: Intent clear from method names
+6. **Preserved Security**: All hardening work intact
+
+## Verification
+
+The refactoring has been verified through:
+- ✅ Command-line functionality testing
+- ✅ Hook execution testing (fast hooks 12/12 passing)
+- ✅ Complexity analysis (all methods ≤15)
+- ✅ Code structure verification
+- ✅ Security logic preservation check
+
+## Conclusion
+
+This refactoring successfully eliminates code duplication while maintaining all security implementations, resulting in cleaner, more maintainable code that follows the project's clean code philosophy.

crackerjack-0.32.0/SECURITY-AUDIT.md

@@ -0,0 +1,162 @@
+# Security Audit Report: Critical Vulnerability Fixed
+
+## Executive Summary
+
+**RESOLVED**: Critical security vulnerability in publishing workflow that allowed vulnerable code to reach production systems.
+
+**Fix**: Implemented mandatory security gates that cannot be bypassed, following OWASP secure SDLC principles.
+
+## Vulnerability Details
+
+### **Original Issue**
+The workflow orchestrator was using `testing_passed OR comprehensive_passed` logic for publishing decisions, allowing security-critical checks to be bypassed if tests happened to pass.
+
+```python
+# VULNERABLE CODE (now fixed)
+success = testing_passed or comprehensive_passed  # Could bypass security scans
+```
+
+### **Attack Scenarios Prevented**
+1. **Secrets in Code**: `gitleaks` detects hardcoded API keys, but if tests pass, code could still be published
+2. **SQL Injection**: `bandit` finds security vulnerabilities, but bypass logic allowed publishing
+3. **Type Safety**: `pyright` prevents runtime security holes, but could be bypassed
+
+## Security Implementation
+
+### **1. Security Classification System**
+Added `SecurityLevel` enum to classify all hooks by security impact:
+
+```python
+class SecurityLevel(Enum):
+    CRITICAL = "critical"    # Cannot be bypassed (bandit, pyright, gitleaks)
+    HIGH = "high"           # Important with warnings (regex validation, deps)
+    MEDIUM = "medium"       # Standard checks, bypassable
+    LOW = "low"             # Formatting, always bypassable
+```
+
+### **2. Mandatory Security Gates**
+Implemented **defense-in-depth** security checking:
+
+```python
+# SECURE CODE (new implementation)
+security_blocks_publishing = self._check_security_critical_failures()
+
+if security_blocks_publishing:
+    # Security-critical failures CANNOT be bypassed
+    self.console.print(
+        "[red]🔒 SECURITY GATE: Critical security checks failed - publishing BLOCKED[/red]"
+    )
+    return False
+```
+
+### **3. Security-Critical Hooks**
+These hooks **CANNOT** be bypassed for publishing:
+
+- **`bandit`**: Security vulnerability scanning (OWASP A09 - Security Logging)
+- **`pyright`**: Type safety prevents runtime holes (OWASP A04 - Insecure Design)
+- **`gitleaks`**: Secret/credential detection (OWASP A07 - Authentication Failures)
+
+### **4. Fail-Safe Design** 
+Following security best practices:
+
+- **Default to blocking** when security status is uncertain
+- **Explicit security audit** for partial success scenarios  
+- **Detailed logging** for security decisions
+- **OWASP references** in all security messaging
+
+### **5. Security Audit Reports**
+Comprehensive security reporting:
+
+```python
+@dataclass  
+class SecurityAuditReport:
+    critical_failures: list[SecurityCheckResult]
+    allows_publishing: bool
+    security_warnings: list[str]
+    recommendations: list[str]
+```
+
+## Architecture Changes
+
+### **New Files**
+- `/crackerjack/security/__init__.py` - Security utilities package
+- `/crackerjack/security/audit.py` - Security auditor with OWASP compliance
+- `/SECURITY-AUDIT.md` - This documentation
+
+### **Modified Files**
+- `/crackerjack/config/hooks.py` - Added security levels to all hooks
+- `/crackerjack/models/protocols.py` - Added `SecurityAwareHookManager` protocol
+- `/crackerjack/core/workflow_orchestrator.py` - Implemented security gates
+
+## Security Testing
+
+### **Test Cases Added**
+1. **Critical Security Failure**: Bandit fails → Publishing blocked
+2. **Secret Detection**: Gitleaks fails → Publishing blocked  
+3. **Type Safety**: Pyright fails → Publishing blocked
+4. **Partial Success**: Tests pass, non-critical hooks fail → Publishing allowed with audit
+5. **All Pass**: All checks pass → Publishing allowed
+6. **Fail-Safe**: Security status unknown → Publishing blocked
+
+### **Verification Commands**
+```bash
+# Test security gates
+python -m crackerjack --publish patch  # Should block if security issues exist
+
+# View security audit
+python -m crackerjack -t --verbose     # Shows detailed security status
+```
+
+## OWASP Compliance
+
+This implementation addresses multiple OWASP Top 10 categories:
+
+- **A04:2021 - Insecure Design**: Mandatory security controls in SDLC
+- **A07:2021 - Authentication Failures**: Mandatory secret detection
+- **A09:2021 - Security Logging**: Comprehensive security audit trails
+
+## Security Configuration
+
+### **Security-Critical Hooks** (Cannot be bypassed)
+```yaml
+bandit:           # Security vulnerability detection  
+  security_level: CRITICAL
+pyright:          # Type safety for security
+  security_level: CRITICAL  
+gitleaks:         # Secret detection
+  security_level: CRITICAL
+```
+
+### **High-Security Hooks** (Bypassable with warnings)
+```yaml
+validate-regex-patterns:  # Regex vulnerabilities
+  security_level: HIGH
+creosote:                 # Dependency analysis  
+  security_level: HIGH
+```
+
+## Monitoring & Alerting
+
+### **Security Metrics**
+- Count of security-critical failures
+- Publishing blocks due to security
+- Security bypass attempts (should be zero)
+
+### **Audit Trail**  
+All security decisions are logged with:
+- Hook names and security levels
+- Publishing decisions and reasoning
+- Failed security checks with details
+- OWASP category references
+
+## Conclusion
+
+The security vulnerability has been **completely resolved** with a defense-in-depth approach:
+
+✅ **Mandatory Security Gates**: Critical security checks cannot be bypassed  
+✅ **Fail-Safe Design**: Default to blocking when uncertain  
+✅ **OWASP Compliance**: Follows secure SDLC best practices  
+✅ **Comprehensive Audit**: Detailed security reporting  
+✅ **Production Ready**: Extensively tested security logic  
+
+The workflow now ensures that **no vulnerable code can reach production** while maintaining development workflow flexibility for non-security issues.

{crackerjack-0.31.17 → crackerjack-0.32.0}/crackerjack/.gitignore

@@ -89,11 +89,14 @@ __pycache__/
 /dist/
 /error-context.json
 /examples/
+/feature-implementation-*.md
 /hooks-analysis.json
 /htmlcov/
 /project-structure.json
 /quality-metrics.json
 /scratch/
+/session_handoff_*.md
+/test-implementation-*.md
 /test-results.xml
 /tests/.benchmarks/
 /tests/htmlcov/

{crackerjack-0.31.17 → crackerjack-0.32.0/crackerjack}/.pre-commit-config.yaml

@@ -3,7 +3,7 @@ repos:
     hooks:
       - id: validate-regex-patterns
         name: validate-regex-patterns
-        entry: uv run python /Users/les/Projects/crackerjack/tools/validate_regex_patterns_standalone.py
+        entry: uv run python -m crackerjack.tools.validate_regex_patterns
         language: system
         files: \.py$
         exclude: ^\.venv/