jleechanorg-pr-automation 0.1.1__tar.gz

jleechanorg_pr_automation-0.1.1/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: jleechanorg-pr-automation
+Version: 0.1.1
+Summary: GitHub PR automation system with safety limits and actionable counting
+Author-email: jleechan <jlee@jleechan.org>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jleechanorg/worldarchitect.ai
+Project-URL: Repository, https://github.com/jleechanorg/worldarchitect.ai
+Project-URL: Issues, https://github.com/jleechanorg/worldarchitect.ai/issues
+Keywords: github,automation,pr,pull-request,monitoring
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Provides-Extra: email
+Requires-Dist: keyring>=23.0.0; extra == "email"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# jleechanorg-pr-automation
+
+A comprehensive GitHub PR automation system with safety limits, actionable counting, and intelligent filtering.
+
+## Features
+
+- **Actionable PR Counting**: Only processes PRs that need attention, excluding already-processed ones
+- **Safety Limits**: Built-in rate limiting and attempt tracking to prevent automation abuse
+- **Cross-Process Safety**: Thread-safe operations with file-based persistence
+- **Email Notifications**: Optional SMTP integration for automation alerts
+- **Commit-Based Tracking**: Avoids duplicate processing using commit SHAs
+- **Comprehensive Testing**: 200+ test cases with matrix-driven coverage
+
+## Installation
+
+```bash
+pip install jleechanorg-pr-automation
+```
+
+### Optional Dependencies
+
+For email notifications:
+```bash
+pip install jleechanorg-pr-automation[email]
+```
+
+For development:
+```bash
+pip install jleechanorg-pr-automation[dev]
+```
+
+## Quick Start
+
+### Basic PR Monitoring
+
+```python
+from jleechanorg_pr_automation import JleechanorgPRMonitor
+
+# Initialize monitor
+monitor = JleechanorgPRMonitor()
+
+# Process up to 20 actionable PRs
+result = monitor.run_monitoring_cycle_with_actionable_count(target_actionable_count=20)
+
+print(f"Processed {result['actionable_processed']} actionable PRs")
+print(f"Skipped {result['skipped_count']} non-actionable PRs")
+```
+
+### Safety Management
+
+```python
+from jleechanorg_pr_automation import AutomationSafetyManager
+
+# Initialize safety manager with data directory
+safety = AutomationSafetyManager(data_dir="/tmp/automation_safety")
+
+# Limits are configured via automation_safety_config.json inside the data directory
+# or the AUTOMATION_PR_LIMIT / AUTOMATION_GLOBAL_LIMIT environment variables.
+
+# Check if PR can be processed
+if safety.can_process_pr(pr_number=123, repo="my-repo"):
+    # Process PR...
+    safety.record_pr_attempt(pr_number=123, result="success", repo="my-repo")
+```
+
+## Configuration
+
+### Environment Variables
+
+- `GITHUB_TOKEN`: GitHub personal access token (required)
+- `PR_AUTOMATION_WORKSPACE`: Custom workspace directory (optional)
+- `AUTOMATION_PR_LIMIT`: Maximum attempts per PR (default: 5)
+- `AUTOMATION_GLOBAL_LIMIT`: Maximum global automation runs (default: 50)
+- `AUTOMATION_APPROVAL_HOURS`: Hours before approval expires (default: 24)
+
+### Email Configuration (Optional)
+
+- `SMTP_SERVER`: SMTP server hostname
+- `SMTP_PORT`: SMTP server port (default: 587)
+- `EMAIL_USER`: SMTP username
+- `EMAIL_PASS`: SMTP password
+- `EMAIL_TO`: Notification recipient
+- `EMAIL_FROM`: Sender address (defaults to EMAIL_USER)
+
+## Command Line Interface
+
+### PR Monitor
+
+```bash
+# Monitor all repositories
+jleechanorg-pr-monitor
+
+# Process specific repository
+jleechanorg-pr-monitor --single-repo worldarchitect.ai
+
+# Process specific PR
+jleechanorg-pr-monitor --target-pr 123 --target-repo jleechanorg/worldarchitect.ai
+
+# Dry run (discovery only)
+jleechanorg-pr-monitor --dry-run
+```
+
+### Safety Manager CLI
+
+```bash
+# Check current status
+automation-safety-cli status
+
+# Clear all safety data
+automation-safety-cli clear
+
+# Check specific PR
+automation-safety-cli check-pr 123 --repo my-repo
+```
+
+## Architecture
+
+### Actionable PR Logic
+
+The system implements intelligent PR filtering:
+
+1. **State Check**: Only processes open PRs
+2. **Commit Tracking**: Skips PRs already processed with current commit SHA
+3. **Safety Limits**: Respects per-PR and global automation limits
+4. **Ordering**: Processes most recently updated PRs first
+
+### Safety Features
+
+- **Dual Limiting**: Per-PR consecutive failure limits + global run limits
+- **Cross-Process Safety**: File-based locking for concurrent automation instances
+- **Attempt Tracking**: Full history of success/failure with timestamps
+- **Graceful Degradation**: Continues processing other PRs if one fails
+
+### Testing
+
+The library includes comprehensive test coverage:
+
+- **Matrix Testing**: All PR state combinations (Open/Closed × New/Old Commits × Processed/Fresh)
+- **Actionable Counting**: Batch processing with skip exclusion
+- **Safety Limits**: Concurrent access and edge cases
+- **Integration Tests**: Real GitHub API interactions (optional)
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/jleechanorg/worldarchitect.ai.git
+cd worldarchitect.ai/automation
+
+# Install in development mode
+pip install -e .[dev]
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=jleechanorg_pr_automation
+
+# Format code
+black .
+ruff check .
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Changelog
+
+### 0.1.1 (2025-10-06)
+
+- Fix daily reset of global automation limit so automation never stalls overnight
+- Track latest reset timestamp in safety data for observability
+- Expand safety manager tests to cover daily rollover behaviour
+
+### 0.1.0 (2025-09-28)
+
+- Initial release
+- Actionable PR counting system
+- Safety management with dual limits
+- Cross-process file-based persistence
+- Email notification support
+- Comprehensive test suite (200+ tests)
+- CLI interfaces for monitoring and safety management

jleechanorg_pr_automation-0.1.1/README.md

@@ -0,0 +1,192 @@
+# jleechanorg-pr-automation
+
+A comprehensive GitHub PR automation system with safety limits, actionable counting, and intelligent filtering.
+
+## Features
+
+- **Actionable PR Counting**: Only processes PRs that need attention, excluding already-processed ones
+- **Safety Limits**: Built-in rate limiting and attempt tracking to prevent automation abuse
+- **Cross-Process Safety**: Thread-safe operations with file-based persistence
+- **Email Notifications**: Optional SMTP integration for automation alerts
+- **Commit-Based Tracking**: Avoids duplicate processing using commit SHAs
+- **Comprehensive Testing**: 200+ test cases with matrix-driven coverage
+
+## Installation
+
+```bash
+pip install jleechanorg-pr-automation
+```
+
+### Optional Dependencies
+
+For email notifications:
+```bash
+pip install jleechanorg-pr-automation[email]
+```
+
+For development:
+```bash
+pip install jleechanorg-pr-automation[dev]
+```
+
+## Quick Start
+
+### Basic PR Monitoring
+
+```python
+from jleechanorg_pr_automation import JleechanorgPRMonitor
+
+# Initialize monitor
+monitor = JleechanorgPRMonitor()
+
+# Process up to 20 actionable PRs
+result = monitor.run_monitoring_cycle_with_actionable_count(target_actionable_count=20)
+
+print(f"Processed {result['actionable_processed']} actionable PRs")
+print(f"Skipped {result['skipped_count']} non-actionable PRs")
+```
+
+### Safety Management
+
+```python
+from jleechanorg_pr_automation import AutomationSafetyManager
+
+# Initialize safety manager with data directory
+safety = AutomationSafetyManager(data_dir="/tmp/automation_safety")
+
+# Limits are configured via automation_safety_config.json inside the data directory
+# or the AUTOMATION_PR_LIMIT / AUTOMATION_GLOBAL_LIMIT environment variables.
+
+# Check if PR can be processed
+if safety.can_process_pr(pr_number=123, repo="my-repo"):
+    # Process PR...
+    safety.record_pr_attempt(pr_number=123, result="success", repo="my-repo")
+```
+
+## Configuration
+
+### Environment Variables
+
+- `GITHUB_TOKEN`: GitHub personal access token (required)
+- `PR_AUTOMATION_WORKSPACE`: Custom workspace directory (optional)
+- `AUTOMATION_PR_LIMIT`: Maximum attempts per PR (default: 5)
+- `AUTOMATION_GLOBAL_LIMIT`: Maximum global automation runs (default: 50)
+- `AUTOMATION_APPROVAL_HOURS`: Hours before approval expires (default: 24)
+
+### Email Configuration (Optional)
+
+- `SMTP_SERVER`: SMTP server hostname
+- `SMTP_PORT`: SMTP server port (default: 587)
+- `EMAIL_USER`: SMTP username
+- `EMAIL_PASS`: SMTP password
+- `EMAIL_TO`: Notification recipient
+- `EMAIL_FROM`: Sender address (defaults to EMAIL_USER)
+
+## Command Line Interface
+
+### PR Monitor
+
+```bash
+# Monitor all repositories
+jleechanorg-pr-monitor
+
+# Process specific repository
+jleechanorg-pr-monitor --single-repo worldarchitect.ai
+
+# Process specific PR
+jleechanorg-pr-monitor --target-pr 123 --target-repo jleechanorg/worldarchitect.ai
+
+# Dry run (discovery only)
+jleechanorg-pr-monitor --dry-run
+```
+
+### Safety Manager CLI
+
+```bash
+# Check current status
+automation-safety-cli status
+
+# Clear all safety data
+automation-safety-cli clear
+
+# Check specific PR
+automation-safety-cli check-pr 123 --repo my-repo
+```
+
+## Architecture
+
+### Actionable PR Logic
+
+The system implements intelligent PR filtering:
+
+1. **State Check**: Only processes open PRs
+2. **Commit Tracking**: Skips PRs already processed with current commit SHA
+3. **Safety Limits**: Respects per-PR and global automation limits
+4. **Ordering**: Processes most recently updated PRs first
+
+### Safety Features
+
+- **Dual Limiting**: Per-PR consecutive failure limits + global run limits
+- **Cross-Process Safety**: File-based locking for concurrent automation instances
+- **Attempt Tracking**: Full history of success/failure with timestamps
+- **Graceful Degradation**: Continues processing other PRs if one fails
+
+### Testing
+
+The library includes comprehensive test coverage:
+
+- **Matrix Testing**: All PR state combinations (Open/Closed × New/Old Commits × Processed/Fresh)
+- **Actionable Counting**: Batch processing with skip exclusion
+- **Safety Limits**: Concurrent access and edge cases
+- **Integration Tests**: Real GitHub API interactions (optional)
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/jleechanorg/worldarchitect.ai.git
+cd worldarchitect.ai/automation
+
+# Install in development mode
+pip install -e .[dev]
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=jleechanorg_pr_automation
+
+# Format code
+black .
+ruff check .
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Changelog
+
+### 0.1.1 (2025-10-06)
+
+- Fix daily reset of global automation limit so automation never stalls overnight
+- Track latest reset timestamp in safety data for observability
+- Expand safety manager tests to cover daily rollover behaviour
+
+### 0.1.0 (2025-09-28)
+
+- Initial release
+- Actionable PR counting system
+- Safety management with dual limits
+- Cross-process file-based persistence
+- Email notification support
+- Comprehensive test suite (200+ tests)
+- CLI interfaces for monitoring and safety management

jleechanorg_pr_automation-0.1.1/jleechanorg_pr_automation/__init__.py

@@ -0,0 +1,32 @@
+"""
+jleechanorg-pr-automation: GitHub PR automation system with safety limits and actionable counting.
+
+This package provides comprehensive PR monitoring and automation capabilities with built-in
+safety features, intelligent filtering, and cross-process synchronization.
+"""
+
+from .jleechanorg_pr_monitor import JleechanorgPRMonitor
+from .automation_safety_manager import AutomationSafetyManager
+from .utils import (
+    SafeJSONManager,
+    setup_logging,
+    get_email_config,
+    validate_email_config,
+    get_automation_limits,
+    json_manager,
+)
+
+__version__ = "0.1.1"
+__author__ = "jleechan"
+__email__ = "jlee@jleechan.org"
+
+__all__ = [
+    "JleechanorgPRMonitor",
+    "AutomationSafetyManager",
+    "SafeJSONManager",
+    "setup_logging",
+    "get_email_config",
+    "validate_email_config",
+    "get_automation_limits",
+    "json_manager",
+]