refactor: Wormhole v4.0.0 — Modular Architecture + Hierarchical Staff #5

Merged

everestmcarthur merged 1 commit from refactor/modular-hierarchy into main

2026-05-14 15:09:52 -04:00

everestmcarthur commented

2026-05-14 15:08:41 -04:00

(Migrated from github.com)

🌀 Wormhole v4.0.0 — Full Refactor

Architecture

Complete restructure from monolithic wormhole.py (4,782 lines) into modular architecture (30 files, 5,274 lines):

wormhole/
├── __init__.py          # Cog loader
├── core.py              # Main class, helpers, background loops, context menus
├── utils.py             # Unchanged utility functions
├── models/
│   ├── permissions.py   # Role IntEnum, requires_role() decorator
│   ├── config.py        # DEFAULT_NETWORK/DEFAULT_GLOBAL
│   └── message_map.py   # MessageMap class
├── services/
│   └── emoji.py         # Foreign emoji resolution
├── ui/
│   ├── views.py         # Reply jump button
│   └── modals.py        # Report modal
├── commands/            # 13 command modules (mixin classes)
│   ├── network.py       # create/delete/open/close/list/discover/info
│   ├── settings.py      # relay mode, sync toggles, identity, limits
│   ├── staff.py         # add/rm/promote/demote/list/transfer
│   ├── moderation.py    # ban/mute (user+server), allowlist, purge, nuke
│   ├── filters.py       # word/regex filters, automod, attachment filters
│   ├── social.py        # profiles, karma, starboard, highlights, bookmarks
│   ├── dm.py            # DM relay management
│   ├── mentions.py      # mention policy (per-network/server/user)
│   ├── tos.py           # rules/ToS acceptance gate
│   ├── reports.py       # user report system
│   ├── bridge.py        # cross-network bridging, mirrors
│   ├── advanced.py      # polls, AFK, auto-responses, schedules, analytics, invites
│   └── debug.py         # health, trace, test, backup/restore, version
└── listeners/
    ├── relay.py         # on_message → gate checks → _do_relay
    ├── sync.py          # edit/delete/reaction sync, karma, starboard
    └── misc.py          # typing, pin sync

New Staff System

Per-network hierarchical roles (replaces flat owner/staff):

Bot Owner (Red built-in) — global override
└─ Per Network:
   ├─ Owner    — full control + transfer/delete
   ├─ Admin    — settings, moderation, filters, assign mods
   ├─ Moderator — ban/mute/purge, reports, audit
   ├─ Helper   — view reports, limited mod
   └─ Member   — normal user

Enhanced Moderation

Server-level ban/mute (not just user-level)
Allowlist mode (only whitelisted servers)
Mod edit & nuke (delete N messages by user)
Anti-raid with auto-freeze
Expanded automod: anti-zalgo, anti-emote-spam, anti-newline-spam

Preserved

All existing relay functionality (webhook/embed/compact)
Reply jump buttons, emoji relay, sticker sync
Original wormhole.py kept for reference
utils.py completely unchanged

## 🌀 Wormhole v4.0.0 — Full Refactor ### Architecture Complete restructure from monolithic `wormhole.py` (4,782 lines) into modular architecture (30 files, 5,274 lines): ``` wormhole/ ├── __init__.py # Cog loader ├── core.py # Main class, helpers, background loops, context menus ├── utils.py # Unchanged utility functions ├── models/ │ ├── permissions.py # Role IntEnum, requires_role() decorator │ ├── config.py # DEFAULT_NETWORK/DEFAULT_GLOBAL │ └── message_map.py # MessageMap class ├── services/ │ └── emoji.py # Foreign emoji resolution ├── ui/ │ ├── views.py # Reply jump button │ └── modals.py # Report modal ├── commands/ # 13 command modules (mixin classes) │ ├── network.py # create/delete/open/close/list/discover/info │ ├── settings.py # relay mode, sync toggles, identity, limits │ ├── staff.py # add/rm/promote/demote/list/transfer │ ├── moderation.py # ban/mute (user+server), allowlist, purge, nuke │ ├── filters.py # word/regex filters, automod, attachment filters │ ├── social.py # profiles, karma, starboard, highlights, bookmarks │ ├── dm.py # DM relay management │ ├── mentions.py # mention policy (per-network/server/user) │ ├── tos.py # rules/ToS acceptance gate │ ├── reports.py # user report system │ ├── bridge.py # cross-network bridging, mirrors │ ├── advanced.py # polls, AFK, auto-responses, schedules, analytics, invites │ └── debug.py # health, trace, test, backup/restore, version └── listeners/ ├── relay.py # on_message → gate checks → _do_relay ├── sync.py # edit/delete/reaction sync, karma, starboard └── misc.py # typing, pin sync ``` ### New Staff System Per-network hierarchical roles (replaces flat owner/staff): ``` Bot Owner (Red built-in) — global override └─ Per Network: ├─ Owner — full control + transfer/delete ├─ Admin — settings, moderation, filters, assign mods ├─ Moderator — ban/mute/purge, reports, audit ├─ Helper — view reports, limited mod └─ Member — normal user ``` ### Enhanced Moderation - Server-level ban/mute (not just user-level) - Allowlist mode (only whitelisted servers) - Mod edit & nuke (delete N messages by user) - Anti-raid with auto-freeze - Expanded automod: anti-zalgo, anti-emote-spam, anti-newline-spam ### Preserved - All existing relay functionality (webhook/embed/compact) - Reply jump buttons, emoji relay, sticker sync - Original `wormhole.py` kept for reference - `utils.py` completely unchanged