Metadata-Version: 2.4
Name: devchat-p2p
Version: 1.0.0
Summary: A professional, globally-connected, E2E encrypted terminal chat for developers.
Author: Soumyadip Ghosh
License-Expression: MIT
Project-URL: Homepage, https://github.com/dev-soumyadip/devchat-p2p
Project-URL: Repository, https://github.com/dev-soumyadip/devchat-p2p
Project-URL: Bug Tracker, https://github.com/dev-soumyadip/devchat-p2p/issues
Keywords: chat,terminal,mqtt,encrypted,developer,p2p,cli,tui
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Terminals
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=0.40.0
Requires-Dist: pyperclip>=1.8.2
Requires-Dist: cryptography>=41.0.0
Requires-Dist: paho-mqtt>=2.0.0
Requires-Dist: rich>=13.0.0
Dynamic: license-file

<div align="center">

# DevChat P2P

### A terminal chat application for developers who work in the command line

[![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-10b981?style=for-the-badge)](LICENSE)
[![PyPI](https://img.shields.io/badge/PyPI-devchat--p2p-3b82f6?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/devchat-p2p/)
[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-f59e0b?style=for-the-badge)]()

**A globally connected, end-to-end encrypted terminal chat application.**

Connect with any developer directly from your terminal. No accounts, no servers to manage, and no data collection. Just encrypted communication between two machines.

Built by [Soumyadip Ghosh](https://github.com/dev-soumyadip)

</div>

---

## Why DevChat

DevChat solves a few recurring problems for developers who prefer the terminal.

| Problem | How DevChat handles it |
|---------|------------------------|
| Sharing a code snippet with a remote colleague | Markdown rendering with syntax highlighting |
| Not wanting to route private conversations through third-party chat apps | End-to-end Fernet encryption, with keys held only on your machines |
| Chat apps cluttering project folders with config files | All data stays in `~/.devchat/`, leaving your workspace untouched |
| Firewalls and NATs blocking direct connections | An MQTT relay that works across most networks |
| Sending files securely | Chunked, encrypted file transfer built in |

---

## Features

- **Global connectivity** through an MQTT relay over TLS (port 8883) that traverses most NAT and firewall setups
- **End-to-end encryption** using Fernet symmetric encryption, with the shared key kept on your terminal
- **Encrypted file transfer** with chunked delivery and progress tracking
- **Rich terminal UI** built with [Textual](https://textual.textualize.io/), including Markdown rendering and syntax highlighting
- **Message delivery receipts** that track `SENDING → DELIVERED → READ` status in real time
- **Live typing indicators** that show when your peer is typing, debounced to avoid noise
- **Persistent local history** stored in `~/.devchat/history.db` using SQLite with WAL mode
- **CSV export** of your full chat history with a single command
- **Latency ping** to measure connection round-trip time in milliseconds
- **Clean workspace** with no files written to your project directories
- **Automatic reconnection** that handles disconnects gracefully
- **Clipboard integration** that copies auth tokens when a room is created

---

## Installation

### From PyPI (recommended)

```bash
pip install devchat-p2p
```

### From source

```bash
# 1. Clone the repository
git clone https://github.com/dev-soumyadip/devchat-p2p.git
cd devchat-p2p

# 2. Install in editable mode
pip install -e .
```

### Verify the installation

```bash
devchat --help
```

Expected output:

```
usage: devchat [-h] {config,history,export,host,join} ...

DevChat Professional Interface

positional arguments:
  {config,history,export,host,join}
    config              Set Global Identity
    history             Print local persistent chat history
    export              Export history to CSV in downloads folder
    host                Initialize a secure global room
    join                Connect to an existing room

options:
  -h, --help            show this help message and exit
```

---

## Quick start

### Step 1: Set your identity (optional but recommended)

```bash
devchat config --username "yourname" --email "your@email.com"
```

If you skip this step, you will appear as `guest_xxxx@devchat`.

### Step 2: Host a secure room

```bash
devchat host
```

This creates a unique encrypted room, generates a secure auth token, and copies that token to your clipboard (or prints it to the terminal). Share the token with the person you want to chat with. If you lose it, run `/copytoken` inside the chat to copy it again.

### Step 3: Join a room from the other machine

```bash
devchat join <AUTH_TOKEN>
```

Paste the token you received and you are connected.

### Step 4: Start chatting

- Type a message and press **Enter** to send it
- Use Markdown syntax, which renders inline:
  - `` `inline code` ``, **bold**, *italic*
  - Code blocks with syntax highlighting (` ```python `)
- Press **Ctrl+Q** to quit

---

## Command reference

### CLI commands

| Command | Description | Example |
|---------|-------------|---------|
| `devchat host` | Create a new encrypted chat room | `devchat host` |
| `devchat join <token>` | Join an existing room using an auth token | `devchat join aBcD3F...` |
| `devchat config` | Set your global identity | `devchat config --username "alice"` |
| `devchat history` | Print all saved messages to the terminal | `devchat history` |
| `devchat export` | Export full chat history as CSV | `devchat export` |

### Config options

| Flag | Description | Example |
|------|-------------|---------|
| `--username` | Set your display name | `devchat config --username "alice"` |
| `--email` | Set your email (stored locally) | `devchat config --email "a@b.com"` |
| `--pubkey` | Store a public key reference | `devchat config --pubkey "ssh-rsa..."` |

### In-chat commands

| Command | Description |
|---------|-------------|
| `/help` | Show all available in-chat commands |
| `/file <path>` | Send a file, with live autocomplete |
| `/send <path>` | Alias for `/file` |
| `/copytoken` | Copy the auth token to the clipboard again |
| `/ping` | Measure round-trip connection latency in ms |
| `/status` | Show your identity and current room ID |
| `/export` | Export chat history to a CSV file |
| `/clear` | Clear the terminal chat display |
| `/quit` | Exit the application |

File autocomplete: when you type `/file ` followed by any letters, DevChat shows real-time file suggestions from your current directory. It supports fuzzy matching, so typing `main` will find `src/main.py`.

### Keyboard shortcuts

| Shortcut | Action |
|----------|--------|
| `Enter` | Send message |
| `Ctrl+Q` | Quit the application |

---

## File transfer

DevChat can send files of any type over the encrypted channel.

### Sending a file

On Windows:

```
/file C:\Users\you\Documents\report.pdf
```

On macOS or Linux:

```
/send ~/Documents/report.pdf
```

### How it works

1. The file is split into 32KB chunks
2. Each chunk is Base64 encoded, then Fernet encrypted, then sent over TLS MQTT
3. The receiver sees a real-time progress bar
4. Chunks are reassembled and verified on arrival
5. The completed file is saved to `~/.devchat/downloads/`

### Security notes

- Filenames are sanitized, which blocks path traversal attempts
- Chunk integrity is verified before assembly
- Data passes through Fernet encryption, then TLS, then MQTT

---

## Data storage and privacy

All persistent data is stored in your home directory. Nothing is written to your project folders.

```
~/.devchat/
├── config.json        # Your identity (username, email)
├── history.db         # SQLite message history (WAL mode)
├── devchat.log        # Rotating application logs (5MB x 3)
└── downloads/         # Received files and CSV exports
    ├── report.pdf
    └── export_20260624_211500.csv
```

| Item | Location | Purpose |
|------|----------|---------|
| Config | `~/.devchat/config.json` | Stores username, email, and public key reference |
| Database | `~/.devchat/history.db` | All messages with timestamps, status, and sender |
| Logs | `~/.devchat/devchat.log` | Rotating debug and error logs |
| Downloads | `~/.devchat/downloads/` | Received files and CSV exports |

Windows path: `C:\Users\<you>\.devchat\`

macOS and Linux path: `/home/<you>/.devchat/` or `/Users/<you>/.devchat/`

---

## Architecture overview

```
┌──────────────┐          TLS (8883)          ┌──────────────┐
│   DevChat A   │◄──── MQTT Broker ────►│   DevChat B   │
│   (Host)      │    broker.hivemq.com        │   (Joiner)   │
└──────┬────────┘                              └──────┬────────┘
       │                                              │
   Fernet E2E                                    Fernet E2E
   Encryption                                    Decryption
       │                                              │
   ┌───▼────┐                                   ┌─────▼─────┐
   │ SQLite  │ ~/.devchat/history.db             │  SQLite   │
   │  (WAL)  │                                   │  (WAL)    │
   └─────────┘                                   └───────────┘
```

### Design decisions

| Layer | Technology | Reasoning |
|-------|-----------|-----------|
| Transport | MQTT over TLS | Traverses NAT and firewalls, and works behind many corporate proxies |
| Broker | HiveMQ (public) | Globally available with a reliable free tier |
| Encryption | Fernet (AES-128-CBC with HMAC) | Symmetric and fast, with the key shared through the token |
| UI framework | Textual (Python) | Rich terminal UI with Markdown and syntax highlighting |
| Storage | SQLite with WAL | Thread-safe and zero-config, with no external database |
| Token | Base64(room_id:fernet_key) | A single string that carries both routing and encryption info |

---

## System requirements

| Requirement | Minimum |
|-------------|---------|
| Python | 3.9 or higher |
| OS | Windows 10+, macOS 10.15+, or any modern Linux distribution |
| Network | Internet access with outbound TCP port 8883 for MQTT over TLS |
| Terminal | Any modern terminal, such as Windows Terminal, iTerm2, or GNOME Terminal |

### Dependencies (installed automatically)

| Package | Purpose |
|---------|---------|
| `textual` | Terminal UI framework |
| `rich` | Markdown rendering and syntax highlighting |
| `paho-mqtt` | MQTT client for global connectivity |
| `cryptography` | Fernet end-to-end encryption |
| `pyperclip` | Clipboard integration (optional) |

---

## Troubleshooting

### Connection rejected or unable to connect

- Check your internet connection
- Confirm that outbound TCP port 8883 is open, since some corporate firewalls block it
- Try a different network, such as a mobile hotspot, to isolate the issue

### Token error when joining

- Make sure you copied the entire token string
- Tokens are single use per room, so a new token is generated if the host restarts
- Avoid adding extra spaces or newlines when pasting

### No clipboard support

- On headless Linux servers, `pyperclip` may not work, so the token is printed to the terminal instead
- On Linux, install `xclip` or `xsel`, for example `sudo apt install xclip`

### Messages not appearing

- Check `~/.devchat/devchat.log` for error details
- Confirm that both peers are using the same token
- Run `/ping`, and if you receive a pong response, the connection is working

---

## Usage examples

### Quick chat between two developers

Developer A (host):

```bash
$ devchat config --username "alice"
[*] Configuration saved to ~/.devchat/config.json

$ devchat host
# UI launches, token is copied to clipboard
# Share the token with Developer B
```

Developer B (joiner):

```bash
$ devchat config --username "bob"
$ devchat join "dGhpcyBpcyBhIHNhbXBsZSB0b2tlbg=="
# UI launches, connected to Alice's room
```

### Send a file

```
# Inside the chat UI, type:
/file ./my_script.py

# Output:
# [*] INITIATING TRANSFER: my_script.py
# [*] UPLOADING my_script.py ... 100%
# [*] UPLOAD COMPLETE: my_script.py
```

### Export chat history

```bash
# From the CLI:
$ devchat export
[*] History successfully exported to ~/.devchat/downloads/export_20260624_211500.csv

# Or from inside the chat UI:
/export
```

### Check connection quality

```
# Inside the chat UI:
/ping

# Output:
# [*] PONG received: 42.37ms latency
```

---

## Roadmap

- Multi-room support with tabs
- Message reactions (emoji)
- Code snippet mode (`/code python`)
- Room persistence and rejoin
- User presence (online, offline, idle)
- WebSocket transport fallback (port 443)
- Full-text message search (`/search`)
- Message editing and deletion
- Desktop notifications
- Self-hosted broker option
- Plugin and hook system

---

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

---

## Author

**Soumyadip Ghosh**

[GitHub](https://github.com/dev-soumyadip)

---

<div align="center">

If DevChat is useful to you, a star on the repository is appreciated.

Built with Python, Fernet, MQTT, and Textual.

</div>
