Merge pull request #110 from JTJag/chore/add-precommit-config

chore: add pre-commit hooks and document contribution workflow

Author: chigwell

.github/workflows/docker-build.yml

@@ -43,4 +43,4 @@ jobs:
         run: docker compose config
 
       - name: Build Compose services
-        run: docker compose build 
+        run: docker compose build

.github/workflows/python-lint-format.yml

@@ -34,4 +34,4 @@ jobs:
 
       - name: Check formatting with Black
         run: |
-          black --check .
+          black --check .

.gitignore

@@ -198,4 +198,4 @@ test_issues_report.md
 test_upload.txt
 test_voice.ogg
 sticker.webp
-two.png
+two.png

.pre-commit-config.yaml

@@ -0,0 +1,40 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 25.9.0
+    hooks:
+      - id: black
+        language_version: python3
+
+  - repo: https://github.com/pycqa/flake8
+    rev: 7.3.0
+    hooks:
+      - id: flake8
+        args: ["--count", "--select=E9,F63,F7,F82", "--show-source", "--statistics"]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-merge-conflict
+
+  - repo: https://github.com/hadolint/hadolint
+    rev: v2.12.0
+    hooks:
+      - id: hadolint-docker
+        args: ["--failure-threshold", "error", "Dockerfile"]
+
+  - repo: local
+    hooks:
+      - id: docker-compose-config
+        name: docker compose config
+        entry: docker compose --env-file .env.example config
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]
+      - id: docker-build-ci
+        name: docker build (ci parity)
+        entry: docker build --file Dockerfile --tag telegram-mcp:ci .
+        language: system
+        pass_filenames: false
+        stages: [pre-push]

Dockerfile

@@ -44,4 +44,4 @@ ENV TELEGRAM_SESSION_STRING=""
 # EXPOSE 8000
 
 # Define the command to run the application
-CMD ["python", "main.py"] 
+CMD ["python", "main.py"]

README.md

@@ -289,10 +289,15 @@ Telegram messages, display names, chat titles, and button labels are untrusted c
 ## Contributing
 
 1. Fork and clone the repository.
-2. Create a focused branch.
-3. Add or update tests when behavior changes.
-4. Run formatting, tests, and coverage locally.
-5. Open a pull request with a concise description.
+2. Install dependencies and git hooks:
+   - `uv sync`
+   - `uv run pre-commit install --hook-type pre-commit --hook-type pre-push`
+3. Create a focused branch.
+4. Add or update tests when behavior changes.
+5. Run checks locally:
+   - `uv run pre-commit run --all-files`
+   - `uv run pre-commit run --hook-stage pre-push --all-files`
+6. Open a pull request with a concise description.
 
 ## License
 

claude_desktop_config.json

@@ -10,4 +10,4 @@
             ]
         }
     }
-}
+}

docker-compose.yml

@@ -17,4 +17,4 @@ services:
     # Replace './telegram_sessions' with your desired host path.
     # volumes:
     #   - ./telegram_sessions:/app
-    restart: unless-stopped 
+    restart: unless-stopped

pyproject.toml

@@ -66,6 +66,7 @@ exclude = [
 dev = [
     "black>=25.9.0",
     "flake8>=7.3.0",
+    "pre-commit>=4.6.0",
     "pytest>=9.0.2",
     "pytest-asyncio>=1.3.0",
     "pytest-cov>=6.0.0",

requirements.txt

@@ -5,4 +5,4 @@ nest-asyncio>=1.6.0
 python-dotenv>=1.1.0
 python-json-logger>=3.3.0
 qrcode>=8.2
-telethon>=1.42.0
+telethon>=1.42.0