diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..d42bc2e --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,35 @@ +# Code Owners for GeoGuessr MCP Server +# +# This file defines individuals or teams responsible for code in this repository. +# Code owners are automatically requested for review when someone opens a pull request +# that modifies code that they own. +# +# More info: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners + +# Default owner for everything in the repo +* @NyxiumYuuki + +# Core source code +/src/ @NyxiumYuuki + +# API and Authentication +/src/geoguessr_mcp/api/ @NyxiumYuuki +/src/geoguessr_mcp/auth/ @NyxiumYuuki + +# Monitoring system +/src/geoguessr_mcp/monitoring/ @NyxiumYuuki + +# Configuration files +/pyproject.toml @NyxiumYuuki +/docker-compose*.yml @NyxiumYuuki +/Dockerfile @NyxiumYuuki + +# Security and policies +/SECURITY.md @NyxiumYuuki +/LICENSE @NyxiumYuuki + +# CI/CD and GitHub workflows +/.github/ @NyxiumYuuki + +# Tests +/tests/ @NyxiumYuuki diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..5c28fec --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,66 @@ +--- +name: Bug Report +about: Create a report to help us improve +title: '[BUG] ' +labels: bug +assignees: '' +--- + +## Bug Description + + + +## Steps to Reproduce + +1. +2. +3. +4. + +## Expected Behavior + + + +## Actual Behavior + + + +## Environment + +- **OS**: +- **Python Version**: +- **GeoGuessr MCP Version**: +- **Deployment Method**: + +## Configuration + + + +```env +MONITORING_ENABLED=true +LOG_LEVEL=DEBUG +``` + +## Logs + + + +``` +[Paste logs here] +``` + +## Screenshots + + + +## Additional Context + + + +## Possible Solution + + + +## Related Issues + + diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..5e86984 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,78 @@ +--- +name: Feature Request +about: Suggest an idea for this project +title: '[FEATURE] ' +labels: enhancement +assignees: '' +--- + +## Feature Description + + + +## Problem Statement + + + + +## Proposed Solution + + + +## Alternatives Considered + + + +## Use Cases + + + +1. +2. +3. + +## Example Usage + + + +```python +# Example code showing the proposed feature +``` + +## Benefits + + + +- +- +- + +## Potential Drawbacks + + + +## Implementation Suggestions + + + +## Additional Context + + + +## Priority + + + +- [ ] Critical - Blocking my use of the project +- [ ] High - Would significantly improve my workflow +- [ ] Medium - Nice to have +- [ ] Low - Just an idea + +## Willingness to Contribute + + + +- [ ] I can implement this feature +- [ ] I can help with implementation +- [ ] I can test the implementation +- [ ] I can only report the idea diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..bb48554 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,83 @@ +# Pull Request + +## Description + + + +## Type of Change + + + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Documentation update +- [ ] Code refactoring +- [ ] Performance improvement +- [ ] Test improvement + +## Related Issues + + + +Fixes # + +## Changes Made + + + +- +- +- + +## Testing Performed + + + +- [ ] Unit tests added/updated +- [ ] Integration tests added/updated +- [ ] Manual testing performed +- [ ] All existing tests pass + +### Test Details + + + +```bash +# Example test commands +pytest tests/ +``` + +## Screenshots (if applicable) + + + +## Checklist + + + +- [ ] My code follows the project's style guidelines +- [ ] I have performed a self-review of my code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] My changes generate no new warnings +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes +- [ ] Any dependent changes have been merged and published +- [ ] I have checked my code and corrected any misspellings + +## Additional Context + + + +## Breaking Changes + + + +## Performance Impact + + + +--- + +**By submitting this pull request, I confirm that my contribution is made under the terms of the MIT License.** diff --git a/.github/workflows/code-quality.yml b/.github/workflows/code-quality.yml new file mode 100644 index 0000000..223a55c --- /dev/null +++ b/.github/workflows/code-quality.yml @@ -0,0 +1,123 @@ +name: Code Quality + +on: + push: + branches: [ main, develop, claude/** ] + pull_request: + branches: [ main, develop ] + +jobs: + lint-and-format: + name: Lint and Format Check + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.13' + cache: 'pip' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install black ruff mypy + + - name: Check formatting with Black + run: | + black --check src/ tests/ + + - name: Lint with Ruff + run: | + ruff check src/ tests/ + + - name: Type check with MyPy + run: | + mypy src/ + continue-on-error: true + + test: + name: Run Tests + runs-on: ubuntu-latest + + strategy: + matrix: + python-version: ['3.13'] + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + cache: 'pip' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -e ".[dev]" + + - name: Run unit tests + run: | + pytest tests/unit/ -v --cov=src/geoguessr_mcp --cov-report=xml --cov-report=term + + - name: Upload coverage reports + uses: codecov/codecov-action@v4 + with: + file: ./coverage.xml + flags: unittests + name: codecov-umbrella + continue-on-error: true + + security: + name: Security Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.13' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install safety bandit + + - name: Run Safety check + run: | + pip freeze | safety check --stdin + continue-on-error: true + + - name: Run Bandit security scan + run: | + bandit -r src/ -ll + continue-on-error: true + + docker: + name: Docker Build Test + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Build Docker image + uses: docker/build-push-action@v5 + with: + context: . + push: false + tags: geoguessr-mcp:test + cache-from: type=gha + cache-to: type=gha,mode=max diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml new file mode 100644 index 0000000..2867c13 --- /dev/null +++ b/.github/workflows/dependency-review.yml @@ -0,0 +1,25 @@ +name: Dependency Review + +on: + pull_request: + branches: [ main, develop ] + +permissions: + contents: read + pull-requests: write + +jobs: + dependency-review: + name: Review Dependencies + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Dependency Review + uses: actions/dependency-review-action@v4 + with: + fail-on-severity: moderate + deny-licenses: GPL-2.0, GPL-3.0, AGPL-3.0 + comment-summary-in-pr: always diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..7d84d82 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,139 @@ +# Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Project maintainers are responsible for clarifying and enforcing our standards +of acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Project maintainers have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the project maintainers responsible for enforcement at: + +**yuki.vachot@datasingularity.fr** + +All complaints will be reviewed and investigated promptly and fairly. + +All project maintainers are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Project maintainers will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from project maintainers, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations + +--- + +**Contact**: yuki.vachot@datasingularity.fr +**Last Updated**: 2025-11-29 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f195e9f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,351 @@ +# Contributing to GeoGuessr MCP Server + +Thank you for your interest in contributing to the GeoGuessr MCP Server! This document provides guidelines and instructions for contributing. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Setup](#development-setup) +- [How to Contribute](#how-to-contribute) +- [Coding Standards](#coding-standards) +- [Testing](#testing) +- [Pull Request Process](#pull-request-process) +- [License](#license) + +## Code of Conduct + +### Our Standards + +- **Be Respectful**: Treat everyone with respect and professionalism +- **Be Collaborative**: Work together constructively +- **Be Patient**: Help others learn and grow +- **Be Inclusive**: Welcome diverse perspectives and backgrounds + +### Unacceptable Behavior + +- Harassment, discrimination, or offensive comments +- Personal attacks or trolling +- Publishing others' private information +- Any conduct that would be inappropriate in a professional setting + +## Getting Started + +1. **Fork the repository** on GitHub +2. **Clone your fork** locally: + ```bash + git clone https://github.com/YOUR_USERNAME/GeoGuessrMCP.git + cd GeoGuessrMCP + ``` +3. **Add upstream remote**: + ```bash + git remote add upstream https://github.com/NyxiumYuuki/GeoGuessrMCP.git + ``` + +## Development Setup + +### Prerequisites + +- Python 3.13 or higher +- Docker and Docker Compose (for containerized development) +- Git + +### Installation + +```bash +# Create virtual environment +python -m venv .venv +source .venv/bin/activate # On Windows: .venv\Scripts\activate + +# Install dependencies +pip install -e ".[dev]" + +# Set up pre-commit hooks (optional but recommended) +pre-commit install +``` + +### Environment Configuration + +Create a `.env` file with your configuration: + +```env +GEOGUESSR_NCFA_COOKIE=your_cookie_here +MONITORING_ENABLED=true +MONITORING_INTERVAL_HOURS=24 +LOG_LEVEL=DEBUG +``` + +## How to Contribute + +### Reporting Bugs + +Before creating a bug report: +1. **Check existing issues** to avoid duplicates +2. **Use the latest version** to verify the bug still exists +3. **Collect information**: version, OS, steps to reproduce + +Create a detailed bug report including: +- Clear, descriptive title +- Steps to reproduce +- Expected vs. actual behavior +- Screenshots or logs (if applicable) +- Environment details + +### Suggesting Enhancements + +Enhancement suggestions are welcome! Include: +- Clear description of the proposed feature +- Rationale and use cases +- Examples of how it would work +- Any potential drawbacks or alternatives + +### Contributing Code + +1. **Find or create an issue** for the change you want to make +2. **Create a branch** from main: + ```bash + git checkout -b feature/your-feature-name + # or + git checkout -b fix/issue-number-description + ``` +3. **Make your changes** following our coding standards +4. **Write tests** for your changes +5. **Run tests** to ensure nothing breaks +6. **Commit your changes** with clear messages +7. **Push to your fork** and create a pull request + +## Coding Standards + +### Python Style + +We follow PEP 8 with some modifications: + +- **Line length**: 100 characters (Black formatter) +- **Formatting**: Use Black for automatic formatting +- **Linting**: Use Ruff for code quality checks +- **Type hints**: Required for all functions (MyPy strict mode) + +### Code Quality Tools + +Run before committing: + +```bash +# Format code +black src/ tests/ + +# Lint code +ruff check src/ tests/ + +# Type checking +mypy src/ + +# Run all checks +black src/ tests/ && ruff check src/ tests/ && mypy src/ +``` + +### Best Practices + +1. **Keep functions focused**: One responsibility per function +2. **Use type hints**: All parameters and return values +3. **Write docstrings**: For all public functions and classes +4. **Avoid over-engineering**: Simple solutions are preferred +5. **Handle errors gracefully**: Use proper exception handling +6. **Log appropriately**: Use logging module, not print() + +### Docstring Format + +Use Google-style docstrings: + +```python +def function_name(param1: str, param2: int) -> bool: + """Brief description of function. + + Longer description if needed. + + Args: + param1: Description of param1 + param2: Description of param2 + + Returns: + Description of return value + + Raises: + ValueError: When something goes wrong + """ + pass +``` + +## Testing + +### Running Tests + +```bash +# Run all tests +pytest + +# Run with coverage +pytest --cov=src/geoguessr_mcp tests/ + +# Run specific test file +pytest tests/unit/test_specific.py + +# Run tests matching a pattern +pytest -k "test_auth" + +# Run with verbose output +pytest -v +``` + +### Writing Tests + +- **Unit tests**: Test individual components in isolation +- **Integration tests**: Test component interactions +- **Mock external calls**: Use `respx` for HTTP mocking +- **Use fixtures**: Defined in `tests/conftest.py` +- **Test coverage**: Aim for 80%+ coverage on new code + +Example test: + +```python +import pytest +from geoguessr_mcp.services.profile import ProfileService + +async def test_get_profile_success(mock_auth_session): + """Test successful profile retrieval.""" + service = ProfileService(mock_auth_session) + profile = await service.get_profile("user123") + + assert profile is not None + assert profile.id == "user123" +``` + +## Pull Request Process + +### Before Submitting + +- [ ] Code follows style guidelines +- [ ] All tests pass +- [ ] New tests added for new features +- [ ] Documentation updated (if applicable) +- [ ] Commits are clear and atomic +- [ ] No merge conflicts with main branch + +### PR Guidelines + +1. **Title**: Clear, concise description +2. **Description**: Explain what and why, not how +3. **Link issues**: Reference related issues +4. **Screenshots**: Include for UI changes +5. **Breaking changes**: Clearly document + +### PR Template + +```markdown +## Description +Brief description of changes + +## Type of Change +- [ ] Bug fix +- [ ] New feature +- [ ] Breaking change +- [ ] Documentation update + +## Related Issues +Fixes #123 + +## Testing +Describe testing performed + +## Checklist +- [ ] Tests pass +- [ ] Code follows style guide +- [ ] Documentation updated +``` + +### Review Process + +1. **Automated checks**: CI/CD must pass +2. **Code review**: At least one approval required +3. **Owner approval**: Code owners must approve changes to owned files +4. **Feedback**: Address all review comments +5. **Merge**: Squash and merge (typically) + +## Commit Message Guidelines + +Follow conventional commits format: + +``` +(): + + + +