feat: Enhanced CLI Architecture with Modular Completion System

[un33k]

🚀 Summary

This PR introduces significant enhancements to the ehAye™ Core CLI framework, implementing a robust modular architecture with advanced completion support, comprehensive utility modules, and strict dependency management.

✨ Key Features

1. Modular Completion System

• Implemented auto-discovery completion architecture where each subcommand manages its own completions
• Added completion.py modules for all command groups (dev, build, package, proj, release)
• Enhanced shell completion with context-aware suggestions for bash/zsh
• Separated completion logic for better maintainability

2. Advanced Utility Modules

• config.py: Centralized configuration management with validation
• paths.py: Robust path resolution for project root detection
• logging.py: Structured logging with multiple handlers and formatters
• subprocess.py: Secure subprocess execution with timeout and sanitization
• exceptions.py: Comprehensive exception hierarchy for better error handling

3. Dependency Management

• Pinned all package versions for reproducibility (Black 25.1.0, Ruff 0.12.8, MyPy 1.17.1)
• Created requirements-lock.txt for complete dependency tree
• Aligned versions across CI, local development, and pre-commit hooks
• Fixed version conflicts between different environments

4. Project Structure Improvements

• Reorganized test structure under tests/ directory
• Added configuration files (pip.conf, setup.cfg) to control build artifacts
• Prevented egg-info directory creation in project root
• Enhanced .gitignore patterns for cleaner repository

📊 Changes Overview

• 36 files changed: 3,193 additions, 63 deletions
• New utility modules: 2,285 lines of robust infrastructure code
• Enhanced completion: 571 lines across 6 completion modules
• Test coverage: All 14 tests passing

🔧 Technical Details

Configuration Management

• JSON-based configuration with schema validation
• Environment variable support with precedence
• Type-safe configuration access

Path Resolution

• Multiple strategy support (git, pyproject, file markers)
• Cached results for performance
• Cross-platform compatibility

Logging System

• Structured JSON logging support
• Multiple output formats (console, file, JSON)
• Contextual information capture

Subprocess Security

• Command sanitization to prevent injection
• Configurable timeouts with proper cleanup
• Safe environment variable handling

✅ Testing & Quality

• ✅ All 14 tests passing
• ✅ Black formatting (v25.1.0)
• ✅ Ruff linting (v0.12.8)
• ✅ MyPy type checking (v1.17.1)
• ✅ Pre-commit hooks configured
• ✅ CI/CD pipeline green

🔄 Migration Notes

For existing users:

1. Run ./setup.sh to update dependencies
2. Activate environment: source .venv/bin/activate
3. Completion files are now auto-generated in commands/autogen/

📝 Documentation

• Updated README with new features
• Added comprehensive docstrings to all modules
• Created test documentation in tests/README.md
• Enhanced CLAUDE.md with development guidelines

🎯 Breaking Changes

None - All changes are backward compatible.

🚦 Checklist

• Code follows project style guidelines
• Tests pass locally and in CI
• Documentation updated
• Dependencies pinned and locked
• Pre-commit hooks passing
• CI pipeline green

---

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]