Skip to content
This repository was archived by the owner on Apr 12, 2026. It is now read-only.

AGENTS.md

Latest commit

 

History

History
127 lines (103 loc) · 6.53 KB

AGENTS.md

File metadata and controls

127 lines (103 loc) · 6.53 KB

AGENTS.md - Coding Guidelines for modpacktoserver Repository

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.

Always use Context7 MCP when I need library/API documentation, code generation, setup or configuration steps without me having to explicitly ask.

Build/Lint/Test Commands

This project is a Python-based CLI tool. There is no compilation step, but we use tools for linting and testing.

Prerequisites

  • Python 3.8+ required (3.11+ recommended for built-in tomllib).
  • Install dependencies: pip install -r requirements.txt (if present; otherwise, core dependencies like tomli for Python <3.11).
  • For linting: Install flake8, black, isort, mypy (e.g., pip install flake8 black isort mypy).

Build Commands

  • No build required: Run scripts directly with python.
  • Example: python server_pack_builder.py --source mods --destination server_mods

Linting Commands

  • Full Lint: flake8 . (checks style, errors, complexity).
  • Format Code: black . (auto-format Python files).
  • Sort Imports: isort . (organize import statements).
  • Type Check: mypy . (static type analysis; run after formatting).
  • Combined Lint+Format: black . && isort . && flake8 . && mypy .

Testing Commands

  • Use pytest for unit tests (install via pip install pytest).
  • Run All Tests: pytest
  • Run Tests in Verbose Mode: pytest -v
  • Run a Single Test: pytest tests/test_file.py::test_function_name (e.g., pytest tests/test_mod_filter.py::test_fabric_client_only)
  • Run Tests with Coverage: pytest --cov=server_pack_builder --cov-report=html
  • Run Specific Module Tests: pytest tests/ -k "fabric" (filters tests by keyword).
  • If no tests exist yet, create them in a tests/ directory using pytest conventions (e.g., test_*.py files).

CI/CD Integration

  • For automated checks, run: black . && isort . && flake8 . && mypy . && pytest
  • Ensure all commands pass before committing.

Code Style Guidelines

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.

General Principles

  • Write code for humans first: Prioritize clarity over brevity.
  • Use descriptive names; avoid abbreviations unless widely understood (e.g., jar for JAR file is acceptable).
  • Keep functions short (under 50 lines); break into smaller helpers if needed.
  • Add docstrings to all public functions/classes using Google-style (brief description + args/returns).
  • Comments: Explain why (not what), especially for complex logic. Avoid redundant comments.
  • Logging: Use logging module for output; avoid print in production code.
  • Security: Never hardcode secrets; validate inputs to prevent path traversal (e.g., use os.path.join safely).

Imports

  • Use absolute imports: from modpacktoserver.utils import helper (not from .utils).
  • Group imports: Standard library, third-party, local (separated by blank lines).
  • Use isort to sort alphabetically within groups.
  • Avoid wildcard imports (from module import *).
  • Lazy imports in functions if needed for performance.

Formatting

  • Line length: 88 characters (Black default).
  • Indentation: 4 spaces (never tabs).
  • Blank lines: 1 between functions/classes, 2 between top-level definitions.
  • Trailing commas: Always in multi-line structures for consistency.
  • String quotes: Double quotes for consistency (e.g., "hello"), single for contractions (e.g., don't).
  • Use black to auto-format; do not manually adjust spacing.

Types

  • Use type hints everywhere: For functions, variables, and classes.
  • Import from typing: List, Dict, Optional, Tuple, etc.
  • Enable mypy strict mode if possible (in mypy.ini or pyproject.toml).
  • Avoid Any; use unions or generics instead.
  • Example: def process_mods(mods: List[str]) -> Dict[str, bool]:

Naming Conventions

  • Variables/Functions: snake_case (e.g., is_client_only).
  • Constants: UPPER_SNAKE_CASE (e.g., DEFAULT_TIMEOUT = 120).
  • Classes: PascalCase (e.g., ModProcessor).
  • Modules: snake_case (e.g., mod_filter.py).
  • Private: Prefix with _ (e.g., _helper_function).
  • Boolean variables: Start with is_, has_, can_ (e.g., is_fabric_mod).
  • Avoid single-letter names except in loops (e.g., for mod in mods:).

Error Handling

  • Use exceptions over return codes for errors.
  • Catch specific exceptions (e.g., FileNotFoundError, not Exception).
  • Provide meaningful error messages; log at appropriate levels (error for fatal, warning for recoverable).
  • Use try/except/else/finally blocks; avoid bare except.
  • For CLI tools, exit with codes: 0 (success), 1 (error).
  • Example: Raise ValueError for invalid inputs; handle at top level.

Functions and Classes

  • Functions: Pure where possible; side effects in docstrings.
  • Classes: Use for stateful logic (e.g., a ModPackBuilder class if expanded).
  • Avoid global state; pass dependencies explicitly.
  • Use @staticmethod or @classmethod for utility methods.

File Structure

  • Main script: server_pack_builder.py (entry point).
  • Tests: tests/ directory with test_*.py files mirroring source structure.
  • Config: Use pyproject.toml or setup.cfg for tool configs (e.g., Black, Flake8).
  • Keep flat structure until >10 files.

Best Practices

  • DRY (Don't Repeat Yourself): Extract common logic into functions.
  • SOLID Principles: Single responsibility per function/class.
  • Testing: Write tests first (TDD); cover happy path, edge cases, and errors.
  • Performance: Profile with cProfile if needed; avoid premature optimization.
  • Dependencies: Minimize; pin versions in requirements.txt.
  • Git: Commit often; use conventional commits (e.g., feat: add forge support).

Project-Specific Notes

  • This is a CLI tool for Minecraft mod filtering; keep it simple and CLI-focused for future GUI integration.
  • Handle JAR files safely: Use zipfile for reading; validate paths.
  • Extensibility: Design for easy addition of new mod loaders (e.g., via strategy pattern).

Cursor Rules

No Cursor rules found (.cursor/rules/ or .cursorrules).

Copilot Rules

No Copilot rules found (.github/copilot-instructions.md).

Additional Resources