refactor(core): Full hexagonal architecture modularization, secure session handler & mock testing suite

.agents/skills/telegram_mcp_update/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: Update Telegram MCP Tools
+description: Safely update MCP tool configuration and handle lifecycle, git workflow, and validation aligned with current architecture.
+---
+
+# Telegram MCP Update Skill
+
+## When to use
+- Updating `ALLOWED_TOOLS`
+- Modifying MCP configuration
+- Preparing changes for commit/PR
+
+---
+
+## Core Principles
+
+1. **Lifecycle is internal**
+   - The server manages Telethon via `telegram_client_lifespan`
+   - Never kill processes manually
+
+2. **Separation of concerns**
+   - Config changes ≠ runtime fixes
+   - Do not patch runtime behavior externally
+
+3. **Environment awareness**
+   - Do not assume git remotes, branches, or repo structure
+   - Always inspect before acting
+
+---
+
+## Procedure
+
+### 1. Update Configuration
+Modify `ALLOWED_TOOLS` in `mcp_config.json` or `claude_desktop_config.json`.
+
+### 2. Apply Changes
+- Ask user to refresh MCP server via their MCP client UI.
+- Do not restart processes manually.
+- Do not use `pkill`.
+
+### 3. Validate Behavior
+- Confirm tools are available.
+- If failure occurs:
+  - Check logs (`mcp_errors.log` or server output).
+  - Do not apply external fixes (no process killing).
+
+### 4. Git Workflow (Adaptive)
+
+1. **Inspect repo:**
+   ```bash
+   git remote -v
+   ```
+
+2. **Branch:**
+   ```bash
+   git checkout -b feat/<change-name>
+   ```
+
+3. **Commit:**
+   ```bash
+   git commit -m "feat: <clear description>"
+   ```
+
+4. **Push:**
+   Use existing remote:
+   ```bash
+   git push origin feat/<change-name>
+   ```
+
+5. **Pull Request (PR):**
+   - If `upstream` exists → target upstream.
+   - Else → target `origin`.
+
+---
+
+## Anti-Patterns (Forbidden)
+- Using `pkill` or killing processes manually.
+- Direct Telethon manipulation outside the infrastructure layer.
+- Assuming git remotes (`fork`, `upstream`) without confirming via `git remote -v`.
+- Mixing languages in system instructions (English ONLY).
+
+---
+
+## Expected Outcome
+- Clean config update.
+- No orphan processes.
+- Deterministic agent behavior.
+- Repo-agnostic workflow.

.github/workflows/pytest.yml

@@ -0,0 +1,41 @@
+name: Python Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Run Pytest
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+
+    steps:
+      - name: Check out repository 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 Pytest & Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest pytest-asyncio
+          # Install current package to test domain correctly
+          pip install -e .
+
+      - name: Run Tests
+        env:
+          PYTHONPATH: src
+          TELEGRAM_API_ID: "123456"
+          TELEGRAM_API_HASH: "dummy_hash"
+        run: |
+          pytest tests/

.gitignore

@@ -189,7 +189,6 @@ claude_desktop_config.json
 
 # Test files
 .cursor/
-tests/
 test.py
 extract_test_issues.py
 *.tmp
@@ -201,4 +200,7 @@ test_issues_report.md
 test_upload.txt
 test_voice.ogg
 sticker.webp
-two.png
+two.png
+
+# Local scratch directories
+.local/

Dockerfile

@@ -23,8 +23,10 @@ RUN pip install --no-cache-dir --upgrade pip
 RUN pip install --no-cache-dir -r requirements.txt
 
 # Copy the rest of the application code
-COPY main.py .
-# COPY session_string_generator.py . # Optional: if needed within the container, otherwise can be run outside
+COPY pyproject.toml README.md ./
+COPY src/ src/
+
+RUN pip install --no-cache-dir .
 
 # Create a non-root user and switch to it
 RUN adduser --disabled-password --gecos "" appuser && chown -R appuser:appuser /app
@@ -44,4 +46,4 @@ ENV TELEGRAM_SESSION_STRING=""
 # EXPOSE 8000
 
 # Define the command to run the application
-CMD ["python", "main.py"] 
+CMD ["telegram-mcp"]