Fix telegram-archiver: graceful startup without .env + dev tools

telegram-archiver/DEVELOPMENT.md

@@ -0,0 +1,119 @@
+# Telegram Archiver - Development Configuration
+
+## Virtual Environment Setup
+
+This project uses `uv` for virtual environment and package management.
+
+### Setup (First Time)
+
+```bash
+# Create virtual environment
+uv venv
+
+# Activate virtual environment
+# Windows (PowerShell):
+.venv\Scripts\Activate.ps1
+
+# Windows (cmd):
+.venv\Scripts\activate
+
+# macOS / Linux:
+source .venv/bin/activate
+
+# Install dependencies
+uv pip install -r requirements.txt
+
+# Or install from pyproject.toml (recommended for development):
+uv pip install -e ".[dev]"
+```
+
+### Running the Application
+
+#### CLI Mode
+
+```bash
+# Activate venv first
+python -m telegram-archiver --channel dedinit
+
+# Or with options:
+python -m telegram-archiver -c dedinit -l 10 -o ./test-archive
+```
+
+#### API Mode
+
+```bash
+# Start the server
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+
+# Open browser to http://localhost:8000/docs for Swagger UI
+```
+
+### Development Tools
+
+#### Linting
+
+```bash
+ruff check .
+ruff format .
+```
+
+#### Type Checking
+
+```bash
+mypy app/
+```
+
+#### Testing
+
+```bash
+# Create tests directory first
+mkdir tests
+touch tests/__init__.py
+
+# Run tests
+pytest
+pytest --cov=app
+```
+
+#### Pre-commit Hooks
+
+```bash
+# Install pre-commit hooks
+pre-commit install
+
+# Run all hooks manually
+pre-commit run --all-files
+```
+
+### Code Quality Checklist
+
+Before committing:
+
+- [ ] `ruff check .` passes
+- [ ] `mypy app/` passes (or has explicit ignores)
+- [ ] Tests pass: `pytest`
+- [ ] Manual test: CLI or API works
+- [ ] `.env` file NOT committed (check .gitignore)
+- [ ] `.session` files NOT committed (check .gitignore)
+
+### Troubleshooting
+
+**Import errors:**
+```bash
+# Make sure venv is activated
+# Reinstall dependencies
+uv pip install -r requirements.txt
+```
+
+**Telethon auth issues:**
+```bash
+# Delete session file and re-authenticate
+rm telegram-archiver.session
+# Run again, will prompt for code
+```
+
+**Port already in use:**
+```bash
+# Use different port
+uvicorn app.main:app --port 8001
+```