# derp - Project

## Purpose

A lightweight, zero-dependency asyncio IRC bot with a clean plugin system for Python 3.11+. Designed as an operational toolkit for red team engagements, OSINT reconnaissance, and OPSEC workflows -- accessible from any IRC client.

## Architecture

```
CLI (argparse) -> Config (TOML) -> Bot (orchestrator)
                                     |-> IRCConnection (async TCP/TLS)
                                     |-> PluginRegistry (decorators, loader)
                                           |-> plugins/*.py (hot-reloadable)
```

### Modules

| Module | Role |
|--------|------|
| `cli.py` | Argument parsing, logging setup, entry point |
| `config.py` | TOML loader with defaults merging |
| `irc.py` | IRC protocol: message parsing, formatting, async connection |
| `plugin.py` | Decorator-based plugin system with hot-reload |
| `bot.py` | Orchestrator: connect, dispatch, reconnect, plugin management |

### Plugin Categories

| Category | Plugins | Purpose |
|----------|---------|---------|
| Core | core | Bot management, help, plugin lifecycle |
| OSINT | dns, crtsh, internetdb | Reconnaissance and enumeration |
| Red Team | revshell, encode, hash | Offensive tooling |
| OPSEC | defang | Safe IOC handling |
| Utility | cidr, rand, timer, remind | Network tools, scheduling |
| Music | music, lastfm | Mumble playback, discovery (Last.fm/MB) |
| Voice | voice, mumble_admin | STT/TTS, server admin |
| Subscriptions | rss, yt, twitch, alert | Feed monitoring, keyword alerts |

### Key Design Decisions

- **Zero dependencies**: stdlib only (`asyncio`, `ssl`, `tomllib`, `struct`, `ipaddress`, `hashlib`)
- **Decorator-based plugins**: `@command` and `@event` for clean registration
- **Hot-reload**: load, unload, reload plugins without restart
- **Command shorthand**: unambiguous prefix matching (`!h` -> `!help`)
- **Raw DNS resolver**: pure stdlib UDP, no external DNS library
- **Container-first**: Podman with bind-mounted plugins for live editing
- **Async throughout**: all handlers are `async def`

### Deployment

| Method | Command | Notes |
|--------|---------|-------|
| Bare metal | `make run` | Direct Python, editable install |
| Container | `make up` | podman-compose, plugins mounted |
| Symlink | `make link` | Installs `derp` to `~/.local/bin/` |

## Dependencies

- Python 3.11+ (for `tomllib`)
- No external packages required at runtime
- Dev: `pytest`, `ruff`
- Container: `podman`, `podman-compose`