|
| 1 | +# AGENTS.md - Coding Guidelines for modpacktoserver Repository |
| 2 | + |
| 3 | +This document provides guidelines for coding agents (such as yourself) working in this repository. It outlines commands for building, linting, and testing, as well as code style conventions to ensure consistency and quality. |
| 4 | + |
| 5 | +Always use Context7 MCP when I need library/API documentation, code generation, setup or configuration steps without me having to explicitly ask. |
| 6 | + |
| 7 | +## Build/Lint/Test Commands |
| 8 | + |
| 9 | +This project is a Python-based CLI tool. There is no compilation step, but we use tools for linting and testing. |
| 10 | + |
| 11 | +### Prerequisites |
| 12 | +- Python 3.8+ required (3.11+ recommended for built-in `tomllib`). |
| 13 | +- Install dependencies: `pip install -r requirements.txt` (if present; otherwise, core dependencies like `tomli` for Python <3.11). |
| 14 | +- For linting: Install `flake8`, `black`, `isort`, `mypy` (e.g., `pip install flake8 black isort mypy`). |
| 15 | + |
| 16 | +### Build Commands |
| 17 | +- No build required: Run scripts directly with `python`. |
| 18 | +- Example: `python server_pack_builder.py --source mods --destination server_mods` |
| 19 | + |
| 20 | +### Linting Commands |
| 21 | +- **Full Lint**: `flake8 .` (checks style, errors, complexity). |
| 22 | +- **Format Code**: `black .` (auto-format Python files). |
| 23 | +- **Sort Imports**: `isort .` (organize import statements). |
| 24 | +- **Type Check**: `mypy .` (static type analysis; run after formatting). |
| 25 | +- **Combined Lint+Format**: `black . && isort . && flake8 . && mypy .` |
| 26 | + |
| 27 | +### Testing Commands |
| 28 | +- Use `pytest` for unit tests (install via `pip install pytest`). |
| 29 | +- **Run All Tests**: `pytest` |
| 30 | +- **Run Tests in Verbose Mode**: `pytest -v` |
| 31 | +- **Run a Single Test**: `pytest tests/test_file.py::test_function_name` (e.g., `pytest tests/test_mod_filter.py::test_fabric_client_only`) |
| 32 | +- **Run Tests with Coverage**: `pytest --cov=server_pack_builder --cov-report=html` |
| 33 | +- **Run Specific Module Tests**: `pytest tests/ -k "fabric"` (filters tests by keyword). |
| 34 | +- If no tests exist yet, create them in a `tests/` directory using `pytest` conventions (e.g., `test_*.py` files). |
| 35 | + |
| 36 | +### CI/CD Integration |
| 37 | +- For automated checks, run: `black . && isort . && flake8 . && mypy . && pytest` |
| 38 | +- Ensure all commands pass before committing. |
| 39 | + |
| 40 | +## Code Style Guidelines |
| 41 | + |
| 42 | +Follow PEP 8 (Python Enhancement Proposal 8) as the baseline, with additions for this project. Aim for readable, maintainable, and type-safe code. Use tools like `black` and `isort` for enforcement. |
| 43 | + |
| 44 | +### General Principles |
| 45 | +- Write code for humans first: Prioritize clarity over brevity. |
| 46 | +- Use descriptive names; avoid abbreviations unless widely understood (e.g., `jar` for JAR file is acceptable). |
| 47 | +- Keep functions short (under 50 lines); break into smaller helpers if needed. |
| 48 | +- Add docstrings to all public functions/classes using Google-style (brief description + args/returns). |
| 49 | +- Comments: Explain *why* (not what), especially for complex logic. Avoid redundant comments. |
| 50 | +- Logging: Use `logging` module for output; avoid `print` in production code. |
| 51 | +- Security: Never hardcode secrets; validate inputs to prevent path traversal (e.g., use `os.path.join` safely). |
| 52 | + |
| 53 | +### Imports |
| 54 | +- Use absolute imports: `from modpacktoserver.utils import helper` (not `from .utils`). |
| 55 | +- Group imports: Standard library, third-party, local (separated by blank lines). |
| 56 | +- Use `isort` to sort alphabetically within groups. |
| 57 | +- Avoid wildcard imports (`from module import *`). |
| 58 | +- Lazy imports in functions if needed for performance. |
| 59 | + |
| 60 | +### Formatting |
| 61 | +- Line length: 88 characters (Black default). |
| 62 | +- Indentation: 4 spaces (never tabs). |
| 63 | +- Blank lines: 1 between functions/classes, 2 between top-level definitions. |
| 64 | +- Trailing commas: Always in multi-line structures for consistency. |
| 65 | +- String quotes: Double quotes for consistency (e.g., `"hello"`), single for contractions (e.g., `don't`). |
| 66 | +- Use `black` to auto-format; do not manually adjust spacing. |
| 67 | + |
| 68 | +### Types |
| 69 | +- Use type hints everywhere: For functions, variables, and classes. |
| 70 | +- Import from `typing`: `List`, `Dict`, `Optional`, `Tuple`, etc. |
| 71 | +- Enable `mypy` strict mode if possible (in `mypy.ini` or pyproject.toml). |
| 72 | +- Avoid `Any`; use unions or generics instead. |
| 73 | +- Example: `def process_mods(mods: List[str]) -> Dict[str, bool]:` |
| 74 | + |
| 75 | +### Naming Conventions |
| 76 | +- **Variables/Functions**: `snake_case` (e.g., `is_client_only`). |
| 77 | +- **Constants**: `UPPER_SNAKE_CASE` (e.g., `DEFAULT_TIMEOUT = 120`). |
| 78 | +- **Classes**: `PascalCase` (e.g., `ModProcessor`). |
| 79 | +- **Modules**: `snake_case` (e.g., `mod_filter.py`). |
| 80 | +- **Private**: Prefix with `_` (e.g., `_helper_function`). |
| 81 | +- Boolean variables: Start with `is_`, `has_`, `can_` (e.g., `is_fabric_mod`). |
| 82 | +- Avoid single-letter names except in loops (e.g., `for mod in mods:`). |
| 83 | + |
| 84 | +### Error Handling |
| 85 | +- Use exceptions over return codes for errors. |
| 86 | +- Catch specific exceptions (e.g., `FileNotFoundError`, not `Exception`). |
| 87 | +- Provide meaningful error messages; log at appropriate levels (`error` for fatal, `warning` for recoverable). |
| 88 | +- Use `try/except/else/finally` blocks; avoid bare `except`. |
| 89 | +- For CLI tools, exit with codes: 0 (success), 1 (error). |
| 90 | +- Example: Raise `ValueError` for invalid inputs; handle at top level. |
| 91 | + |
| 92 | +### Functions and Classes |
| 93 | +- Functions: Pure where possible; side effects in docstrings. |
| 94 | +- Classes: Use for stateful logic (e.g., a `ModPackBuilder` class if expanded). |
| 95 | +- Avoid global state; pass dependencies explicitly. |
| 96 | +- Use `@staticmethod` or `@classmethod` for utility methods. |
| 97 | + |
| 98 | +### File Structure |
| 99 | +- Main script: `server_pack_builder.py` (entry point). |
| 100 | +- Tests: `tests/` directory with `test_*.py` files mirroring source structure. |
| 101 | +- Config: Use `pyproject.toml` or `setup.cfg` for tool configs (e.g., Black, Flake8). |
| 102 | +- Keep flat structure until >10 files. |
| 103 | + |
| 104 | +### Best Practices |
| 105 | +- DRY (Don't Repeat Yourself): Extract common logic into functions. |
| 106 | +- SOLID Principles: Single responsibility per function/class. |
| 107 | +- Testing: Write tests first (TDD); cover happy path, edge cases, and errors. |
| 108 | +- Performance: Profile with `cProfile` if needed; avoid premature optimization. |
| 109 | +- Dependencies: Minimize; pin versions in `requirements.txt`. |
| 110 | +- Git: Commit often; use conventional commits (e.g., `feat: add forge support`). |
| 111 | + |
| 112 | +### Project-Specific Notes |
| 113 | +- This is a CLI tool for Minecraft mod filtering; keep it simple and CLI-focused for future GUI integration. |
| 114 | +- Handle JAR files safely: Use `zipfile` for reading; validate paths. |
| 115 | +- Extensibility: Design for easy addition of new mod loaders (e.g., via strategy pattern). |
| 116 | + |
| 117 | +### Cursor Rules |
| 118 | +No Cursor rules found (.cursor/rules/ or .cursorrules). |
| 119 | + |
| 120 | +### Copilot Rules |
| 121 | +No Copilot rules found (.github/copilot-instructions.md). |
| 122 | + |
| 123 | +### Additional Resources |
| 124 | +- PEP 8: https://peps.python.org/pep-0008/ |
| 125 | +- Black: https://black.readthedocs.io/ |
| 126 | +- MyPy: https://mypy.readthedocs.io/ |
| 127 | +- Pytest: https://docs.pytest.org/ |
0 commit comments