roomz 0.1.0__tar.gz

roomz-0.1.0/.claude/settings.local.json

@@ -0,0 +1,22 @@
+{
+  "permissions": {
+    "allow": [
+      "Skill(c3:commit)",
+      "Skill(c3:python)",
+      "Bash(uv run *)",
+      "Bash(uv sync *)",
+      "Bash(uv pip *)",
+      "Skill(c3:readme)",
+      "Bash(uv add *)",
+      "WebSearch",
+      "WebFetch(domain:python-socketio.readthedocs.io)",
+      "Skill(c3:textual)",
+      "Bash(cat)",
+      "Bash(python3 /tmp/fix_websocket.py)",
+      "Bash(git restore *)",
+      "Bash(make html *)",
+      "Bash(make typecheck *)",
+      "Bash(make build *)"
+    ]
+  }
+}

roomz-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,112 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run ruff linting
+        run: uv run ruff check app/ tests/
+
+  test:
+    name: Test (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests with coverage
+        run: uv run pytest -v --cov=app --cov=src/roomz --cov-report=xml --cov-report=term
+
+      - name: Upload coverage to Coveralls
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        uses: coverallsapp/github-action@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run mypy
+        run: uv run mypy app/
+
+  build:
+    name: Build Package
+    runs-on: ubuntu-latest
+    needs: [lint, test, typecheck]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

roomz-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: 'Target repository'
+        required: true
+        default: 'testpypi'
+        type: choice
+        options:
+          - testpypi
+          - pypi
+
+jobs:
+  publish:
+    name: Build and Publish
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Required for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: uv run pytest -v
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to TestPyPI
+        if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+      - name: Publish to PyPI
+        if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+        uses: pypa/gh-action-pypi-publish@release/v1

roomz-0.1.0/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+.venv/
+venv/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+.mypy_cache/
+.ruff_cache/
+.tox/
+
+# Documentation
+docs/_build/
+
+# Project specific
+*.log
+
+# Distribution
+uv.lock
+.env.local
+resend_email_test.py

roomz-0.1.0/.readthedocs.yaml

@@ -0,0 +1,20 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

roomz-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christophe VG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

roomz-0.1.0/Makefile

@@ -0,0 +1,68 @@
+# Makefile for Roomz
+# Utility targets for common development actions
+
+-include ~/.claude/Makefile
+
+.PHONY: run-env dev-env test test-all lint format typecheck build publish clean all help run
+
+## run-env: Install production dependencies
+run-env:
+	uv sync
+
+## dev-env: Install with all dependencies (dev, extras)
+dev-env:
+	uv sync --extra dev
+
+## test: Run tests with pytest
+test: dev-env
+	uv run pytest -v
+
+## test-all: Run tests with tox (all Python versions)
+test-all: dev-env
+	uv run tox
+
+## test-cov: Run tests with coverage report
+test-cov: dev-env
+	uv run pytest --cov=app --cov-report=term-missing
+
+## lint: Run ruff linting
+lint: dev-env
+	uv run ruff check app/ tests/ src/
+
+## format: Format code with ruff
+format: dev-env
+	uv run ruff check --fix app/ tests/
+
+## typecheck: Run mypy type checking
+typecheck: dev-env
+	uv run mypy app/ src/
+
+## build: Build distribution packages
+build: dev-env
+	uv build
+
+## publish: Publish to PyPI (requires credentials)
+publish: build
+	uv run twine upload dist/*
+
+## publish-test: Publish to TestPyPI (requires credentials)
+publish-test: build
+	uv run twine upload --repository testpypi dist/*
+
+## clean: Clean build artifacts
+clean:
+	rm -rf dist/ build/ *.egg-info .pytest_cache .coverage .mypy_cache .ruff_cache .tox
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+
+## check: Run format, lint, test, and typecheck
+check: dev-env format lint test typecheck
+
+## run: Run the development server
+run: run-env
+	uv run gunicorn -k uvicorn.workers.UvicornWorker app:asgi_app --reload
+
+## help: Show this help message
+help:
+	@echo "Available targets:"
+	@echo ""
+	@sed -n 's/^## //p' $(MAKEFILE_LIST) | column -t -s ':'

roomz-0.1.0/PKG-INFO

@@ -0,0 +1,353 @@
+Metadata-Version: 2.4
+Name: roomz
+Version: 0.1.0
+Summary: Real-time chatroom web service with magic link authentication
+Project-URL: Homepage, https://github.com/christophevg/roomz
+Project-URL: Documentation, https://github.com/christophevg/roomz#readme
+Project-URL: Repository, https://github.com/christophevg/roomz
+Project-URL: Issues, https://github.com/christophevg/roomz/issues
+Author-email: Christophe VG <contact@christophe.vg>
+License: MIT
+License-File: LICENSE
+Keywords: authentication,chat,quart,real-time,socketio,websocket
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: baseweb>=0.5.2
+Requires-Dist: gunicorn>=21.0.0
+Requires-Dist: pyjwt>=2.8.0
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: python-socketio[asyncio]>=5.10.0
+Requires-Dist: resend>=2.30.1
+Requires-Dist: rich>=13.0.0
+Requires-Dist: textual>=0.47.0
+Requires-Dist: uvicorn[standard]>=0.24.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Requires-Dist: tomli>=2.0.0; extra == 'dev'
+Requires-Dist: tox>=4.0.0; extra == 'dev'
+Requires-Dist: twine>=6.0.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: myst-parser>=2.0.0; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == 'docs'
+Requires-Dist: sphinx>=7.0.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# Roomz
+
+[![PyPI version](https://img.shields.io/pypi/v/roomz.svg)](https://pypi.org/project/roomz/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/roomz.svg)](https://pypistats.org/packages/roomz)
+[![Python versions](https://img.shields.io/pypi/pyversions/roomz.svg)](https://pypi.org/project/roomz/)
+[![License](https://img.shields.io/github/license/christophevg/roomz.svg)](https://github.com/christophevg/roomz/blob/main/LICENSE)
+[![CI](https://github.com/christophevg/roomz/actions/workflows/ci.yml/badge.svg)](https://github.com/christophevg/roomz/actions/workflows/ci.yml)
+[![Coverage](https://coveralls.io/repos/github/christophevg/roomz/badge.svg)](https://coveralls.io/github/christophevg/roomz)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-blue.svg)](https://github.com/astral-sh/ruff)
+[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](https://mypy.readthedocs.io/)
+[![Agentic](https://img.shields.io/badge/workflow-agentic-blueviolet?style=flat-square)](https://christophe.vg/about/Coding-Agent)
+
+A real-time chatroom web service with magic link authentication.
+
+## What is Roomz?
+
+Roomz is a real-time chat application with secure magic link authentication. Built with modern async technology (Quart + SocketIO), it provides seamless real-time messaging with passwordless login.
+
+## Screenshots
+
+| Login | Magic Link | Chat | CLI |
+|-------|-------------|------|-----|
+| ![Login](media/login.png) | ![Magic Link](media/magic-link.png) | ![Chat](media/chat.png) | ![CLI](media/cli.png) |
+
+## Features
+
+- **Magic Link Authentication**: Passwordless login via email
+- **Instant Messaging**: Messages appear instantly across all connected users
+- **Real-time Updates**: See when users join or leave
+- **Responsive Design**: Works on desktop, tablet, and mobile
+- **Connection Status**: Visual indicator shows when disconnected
+- **Accessibility**: Keyboard navigation and screen reader support
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.10 or higher
+- [uv](https://docs.astral.sh/uv/) package manager
+
+### Installation
+
+```bash
+# Clone or navigate to the project
+cd /path/to/roomz
+
+# Install dependencies
+uv sync
+
+# Install dev dependencies (for testing)
+uv sync --extra dev
+```
+
+### Running the Application
+
+```bash
+# Start the chat server
+uv run gunicorn -k uvicorn.workers.UvicornWorker app:asgi_app
+
+# Or for development with auto-reload:
+uv run uvicorn app:asgi_app --reload --host 0.0.0.0 --port 8000
+```
+
+Open [http://localhost:8000](http://localhost:8000) in your browser.
+
+### Configuration
+
+Roomz uses environment variables for configuration. Create a `.env` file in the project root:
+
+```bash
+# Required: JWT secret key (minimum 32 characters)
+# Generate with: python -c "import secrets; print(secrets.token_urlsafe(32))"
+JWT_SECRET_KEY=your-256-bit-secret-key-here
+
+# Required: Comma-separated list of allowed email addresses
+ALLOWED_EMAILS=user@example.com,other@example.com
+
+# Email Configuration (choose one)
+# Development: Log magic links to console (default)
+EMAIL_SENDER=console
+
+# Production: Send emails via Resend
+# EMAIL_SENDER=resend
+# RESEND_API_KEY=re_your_api_key_here
+# EMAIL_FROM=noreply@yourdomain.com  # Optional, defaults to no-reply@example.com
+
+# Optional: JWT token expiration in days (default: 30)
+JWT_EXPIRY_DAYS=30
+
+# Optional: Magic link expiration in minutes (default: 15)
+MAGIC_LINK_EXPIRY_MINUTES=15
+
+# Optional: Rate limit for magic link requests per email per hour (default: 5)
+MAGIC_LINK_RATE_LIMIT=5
+```
+
+**Security Notes:**
+- `JWT_SECRET_KEY` must be at least 32 characters (256 bits)
+- `ALLOWED_EMAILS` controls who can authenticate
+- Removing an email from `ALLOWED_EMAILS` immediately revokes their access
+- Session cookies are httpOnly and SameSite=Strict
+
+**Email Setup:**
+- **Development**: Set `EMAIL_SENDER=console` (or leave unset). Magic links are logged to the server console.
+- **Production**: Set `EMAIL_SENDER=resend` and provide `RESEND_API_KEY`. Get your API key from [resend.com](https://resend.com).
+
+### Testing
+
+```bash
+# Run all tests
+uv run pytest tests/ -v
+
+# Run tests with coverage
+uv run pytest --cov=app --cov-report=term-missing
+
+# Run tests across Python versions
+uv run tox
+```
+
+## How to Use
+
+### Authentication
+
+1. Open the application in your browser
+2. Enter your email address
+3. Click "Send Magic Link"
+4. Check the server console for the magic link (development mode)
+5. Click the magic link to authenticate
+6. You're now in the chat!
+
+### Chatting
+
+1. After authentication, you see the chat interface
+2. Type a message in the input field at the bottom
+3. Press **Enter** or click the **Send** button
+4. Your message appears instantly to all connected users
+
+### Multiple Users
+
+1. Open the application in multiple browser tabs or windows
+2. Authenticate in each tab (can use same or different email)
+3. Type messages in any tab
+4. All tabs see the messages instantly
+5. System messages show when users join or leave
+
+## Python Client Library
+
+Roomz includes a Python client library for programmatic access to the chat service.
+
+### Using the CLI
+
+The easiest way to use Roomz from the command line:
+
+```bash
+# Start the CLI
+uv run roomz-cli
+
+# Or with a custom server
+uv run roomz-cli --server http://your-server:8000
+```
+
+**Commands:**
+- `/login <email>` - Request a magic link
+- `/token <token>` - Connect with magic link token
+- `/logout` - Disconnect and clear session
+- `/quit` - Exit the CLI
+
+**Features:**
+- Session caching (auto-reconnect on restart)
+- Split-screen TUI with message history
+- Color-coded messages (your messages in green)
+- Multiline support (Enter to send, Ctrl+Enter for new line)
+
+### Using the AsyncClient
+
+For programmatic access in your Python applications:
+
+```python
+from roomz.client import AsyncClient
+
+# Create client with session caching
+client = AsyncClient(
+  server_url="http://localhost:8000",
+  session_cache_file="~/.roomz/session.json"
+)
+
+# Register event handlers
+client.on("message", lambda data: print(f"{data['user']['email']}: {data['content']}"))
+client.on("user_joined", lambda data: print(f"{data['user']['email']} joined"))
+
+# Request magic link
+await client.login("user@example.com")
+
+# Connect with magic link token
+await client.connect(token="magic-link-token")
+
+# Or reconnect with cached session
+await client.connect()
+
+# Send message
+result = await client.send("Hello, world!")
+if "error" in result:
+  print(f"Failed: {result['error']}")
+
+# Disconnect
+await client.disconnect()
+client.clear_cached_session()
+```
+
+### Using the SyncClient
+
+For synchronous applications:
+
+```python
+from roomz.client import SyncClient
+
+with SyncClient(server_url="http://localhost:8000", session_token="token") as client:
+  client.on("message", lambda data: print(data['content']))
+  result = client.send("Hello!")
+```
+
+### Session Caching
+
+The client can cache session cookies for automatic reconnection:
+
+```python
+# Enable caching (recommended for CLI apps)
+client = AsyncClient(
+  server_url="http://localhost:8000",
+  session_cache_file=Path.home() / ".roomz" / "session.json"
+)
+
+# Disable caching (default)
+client = AsyncClient(server_url="http://localhost:8000")
+```
+
+## Technology Stack
+
+| Layer | Technology |
+|-------|------------|
+| Backend | Quart (async Flask), SocketIO |
+| Frontend | Vue 3, Vuetify 4 |
+| Framework | Baseweb |
+| Runtime | Python 3.10+ |
+| Server | Gunicorn + Uvicorn |
+| Auth | Magic links with httpOnly cookies |
+
+## Architecture
+
+```
+Browser (Vue 3 + Vuetify 4)
+    ↓ HTTP POST /auth/request-magic-link
+    Magic Link Email (or console in dev)
+    ↓ HTTP GET /auth/verify?token=...
+    JWT Cookie Set (httpOnly, SameSite=Strict)
+    ↓ WebSocket with JWT cookie auth
+Quart Server + SocketIO
+    ↓ JWT Validation + ALLOWED_EMAILS check
+Connected Users
+```
+
+**Stateless Authentication**: Sessions use JWT tokens, enabling server restarts without losing sessions. Access is controlled by the `ALLOWED_EMAILS` environment variable.
+
+## Project Structure
+
+```
+roomz/
+├── app/
+│   ├── __init__.py          # Quart app + SocketIO + Auth endpoints
+│   ├── auth.py             # Magic link and session management
+│   ├── models.py           # Session and magic link models
+│   ├── components/auth/    # AuthDialog Vue component
+│   └── pages/chat/         # Chat page Vue component
+├── src/roomz/
+│   ├── client/             # Python client library
+│   │   ├── async_client.py # AsyncClient implementation
+│   │   ├── sync_client.py  # SyncClient wrapper
+│   │   ├── events.py       # Event emitter
+│   │   └── exceptions.py   # Client exceptions
+│   └── cli/                # Command-line interface
+│       ├── app_tui.py      # Textual TUI application
+│       └── styles/         # TUI stylesheets
+├── tests/                  # Test suite
+├── analysis/               # Design documents
+├── reporting/              # Task reports
+├── pyproject.toml          # Project configuration
+└── README.md               # This file
+```
+
+## Development
+
+See [TODO.md](TODO.md) for planned features and [REQUIREMENTS.md](REQUIREMENTS.md) for full requirements list.
+
+## License
+
+MIT License - See [LICENSE](LICENSE) for details.
+
+## Credits
+
+Built with:
+- [Baseweb](https://github.com/christophevg/baseweb) — Web framework
+- [Quart](https://pgjones.gitlab.io/quart/) — Async Flask
+- [Socket.IO](https://python-socketio.readthedocs.io/) — Real-time communication
+- [Vue 3](https://vuejs.org/) — Frontend framework
+- [Vuetify 4](https://vuetifyjs.com/) — Material Design components