Feature/major release v2.0.0

.github/workflows/mermaid.yml

@@ -0,0 +1,38 @@
+name: Mermaid
+
+on:
+  push:
+    paths:
+      - '**.md'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install Mermaid CLI
+        run: npm install -g @mermaid-js/mermaid-cli
+
+      - name: Build Mermaid Diagrams
+        run: |
+          find . -name "*.md" -type f -exec sh -c '
+            for file do
+              mmdc -i "$file" -o "${file%.md}.png"
+            done
+          ' sh {} +
+          
+      - name: Commit and Push
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git add .
+          git commit -m "Generate Mermaid diagrams" || echo "No changes to commit"
+          git push 

.github/workflows/sonarcloud.yml

@@ -33,7 +33,7 @@ jobs:
           pytest tests/ --cov=githubauthlib --cov-report=xml --cov-report=term-missing
 
       - name: SonarCloud Scan
-        uses: SonarSource/sonarcloud-github-action@master
+        uses: SonarSource/sonarqube-scan-action@v5.0.0
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

.github/workflows/workflow.yml

@@ -13,19 +13,21 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
+        python-version: ['3.9', '3.10', '3.12', '3.13']
 
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
+        cache: 'pip'
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         pip install -r requirements.txt
-        pip install black isort flake8 pytest pytest-cov
+        python -m black --version
+        python -m isort --version
     - name: Run tests and linting
       run: |
         black --check githubauthlib tests

VERSION-2.0.0-PLAN.md

@@ -0,0 +1,240 @@
+# Version 2.0.0 Release Plan
+
+## Overview
+
+This document outlines the comprehensive plan for githubauthlib version 2.0.0, a major release that addresses critical production-quality issues identified in the current codebase.
+
+## Current Status
+
+- **Current Version**: 1.0.1 (released Jan 29, 2025)
+- **PyPI Package**: [githubauthlib](https://pypi.org/project/githubauthlib/)
+- **Status**: Production library with thousands of downloads
+- **Quality Assessment**: Requires major improvements for production readiness
+
+## Why Version 2.0.0?
+
+This is a **major version bump** due to breaking changes and significant improvements:
+
+### Breaking Changes
+
+1. **Exception Handling**: Replace generic exceptions with custom `GitHubAuthError` hierarchy
+2. **Logging**: Replace `print()` statements with structured logging
+3. **Return Types**: Standardize return values and error handling
+4. **Token Validation**: Add strict token format validation
+5. **Configuration**: Introduce configurable parameters
+
+### New Features
+
+1. **Structured Logging**: Proper logging levels and context
+2. **Token Validation**: Secure token format validation
+3. **Configuration Support**: Customizable behavior
+4. **Performance Optimizations**: Caching and timeout mechanisms
+5. **Enhanced Error Context**: Detailed error information
+
+## Critical Issues Identified
+
+### 🚨 Security Vulnerabilities
+
+- **Fragile Token Extraction**: Line 33 uses unsafe string parsing
+- **No Input Validation**: Missing token format validation
+- **Potential Information Leakage**: Error messages may expose sensitive data
+
+### ⚠️ Production Quality Issues
+
+- **Inconsistent Error Handling**: Mixed exception handling patterns
+- **Poor Logging**: Using `print()` instead of proper logging
+- **Missing Type Hints**: No type annotations for better IDE support
+- **Insufficient Documentation**: Missing comprehensive docstrings
+
+### 🔧 Code Quality Problems
+
+- **Code Duplication**: Repeated credential parsing logic
+- **Magic Strings**: Hardcoded values throughout
+- **Platform Detection**: Inefficient platform-specific logic
+- **No Caching**: Repeated system calls for same information
+
+## Implementation Plan
+
+### Phase 1: Core Infrastructure (Breaking Changes)
+
+- [ ] Add `GitHubAuthError` exception hierarchy
+- [ ] Replace `print()` with structured logging
+- [ ] Add comprehensive type hints
+- [ ] Implement token validation
+- [ ] Add input sanitization
+
+### Phase 2: Enhanced Features
+
+- [ ] Add configuration support
+- [ ] Implement caching mechanisms
+- [ ] Add performance optimizations
+- [ ] Enhance documentation
+- [ ] Add monitoring capabilities
+
+### Phase 3: Testing & Validation
+
+- [ ] Increase test coverage to 95%+
+- [ ] Add integration tests
+- [ ] Validate across all supported platforms
+- [ ] Performance benchmarking
+- [ ] Security audit
+
+## Migration Guide
+
+### Current Usage (v1.x.x)
+
+```python
+from githubauthlib import get_github_token
+
+token = get_github_token()
+if token:
+    print("Success")
+```
+
+### New Usage (v2.0.0)
+
+```python
+from githubauthlib import get_github_token, GitHubAuthError
+import logging
+
+try:
+    token = get_github_token()
+    if token:
+        logging.info("Token retrieved successfully")
+except GitHubAuthError as e:
+    logging.error(f"Authentication failed: {e}")
+```
+
+## Version Strategy
+
+```text
+Current: 1.0.1
+Next: 2.0.0 (Major - Breaking Changes)
+Future: 2.1.0, 2.2.0 (Minor - New Features)
+Future: 2.0.1, 2.0.2 (Patch - Bug Fixes)
+```
+
+## Release Timeline
+
+### v2.0.0-beta.1 (Week 1)
+
+- Core infrastructure changes
+- Exception hierarchy implementation
+- Logging system implementation
+
+### v2.0.0-rc.1 (Week 2)
+
+- Feature complete
+- Comprehensive testing
+- Documentation updates
+
+### v2.0.0 (Week 3)
+
+- Stable release
+- Migration guide publication
+- Community announcement
+
+## Quality Gates
+
+### Code Quality
+
+- [ ] 95%+ test coverage
+- [ ] All linting checks pass
+- [ ] Type hints coverage 100%
+- [ ] Security audit passed
+
+### Performance
+
+- [ ] No performance regression
+- [ ] Caching implemented
+- [ ] Timeout mechanisms added
+- [ ] Memory usage optimized
+
+### Documentation
+
+- [ ] API documentation complete
+- [ ] Migration guide published
+- [ ] Examples updated
+- [ ] Troubleshooting guide enhanced
+
+## Risk Assessment
+
+### High Risk
+
+- **Breaking Changes**: May affect existing users
+- **Security Changes**: Token handling modifications
+- **Platform Compatibility**: Cross-platform testing required
+
+### Mitigation Strategies
+
+- **Comprehensive Testing**: Extensive test coverage
+- **Beta Release**: Community feedback before stable release
+- **Migration Guide**: Clear upgrade instructions
+- **Rollback Plan**: Ability to revert if issues arise
+
+## Success Metrics
+
+### Technical Metrics
+
+- Test coverage: 95%+
+- Performance: No regression
+- Security: Zero known vulnerabilities
+- Documentation: 100% API coverage
+
+### User Experience
+
+- Migration success rate: 95%+
+- User satisfaction: Positive feedback
+- Adoption rate: Smooth transition
+- Support tickets: Minimal increase
+
+## Communication Plan
+
+### Pre-Release
+
+- [ ] Announce beta release
+- [ ] Gather community feedback
+- [ ] Address reported issues
+- [ ] Finalize migration guide
+
+### Release
+
+- [ ] Publish stable release
+- [ ] Update documentation
+- [ ] Notify community
+- [ ] Monitor adoption
+
+### Post-Release
+
+- [ ] Monitor for issues
+- [ ] Provide support
+- [ ] Collect feedback
+- [ ] Plan next version
+
+## Dependencies
+
+### Development Dependencies
+
+- `pytest>=7.0.0` - Testing framework
+- `pytest-cov>=4.0.0` - Coverage reporting
+- `mypy>=1.0.0` - Type checking
+- `black>=23.0.0` - Code formatting
+- `isort>=5.0.0` - Import sorting
+
+### Runtime Dependencies
+
+- `Python>=3.6` - Minimum Python version
+- `Git` - Required for credential access
+- `libsecret-tools` - Linux-specific (optional)
+
+## Conclusion
+
+Version 2.0.0 represents a significant milestone in githubauthlib's evolution, transforming it from a functional library to a production-ready, enterprise-grade solution. The breaking changes are necessary to address fundamental issues that could impact users in production environments.
+
+The comprehensive plan outlined above ensures a smooth transition while maintaining backward compatibility where possible and providing clear migration paths for breaking changes.
+
+---
+
+**Document Version**: 1.0  
+**Last Updated**: January 2025  
+**Next Review**: Post v2.0.0 release

githubauthlib/__init__.py

@@ -5,10 +5,24 @@
 from various system-specific secure storage solutions.
 """
 
-from .github_auth import get_github_token
+from .github_auth import (
+    CredentialHelperError,
+    GitHubAuthError,
+    InvalidTokenError,
+    PlatformNotSupportedError,
+    TokenNotFoundError,
+    get_github_token,
+)
 
-__version__ = "1.0.0"
+__version__ = "2.0.0"
 __author__ = "garotm"
 __license__ = "MIT"
 
-__all__ = ["get_github_token"]
+__all__ = [
+    "get_github_token",
+    "GitHubAuthError",
+    "TokenNotFoundError",
+    "InvalidTokenError",
+    "PlatformNotSupportedError",
+    "CredentialHelperError",
+]