From 5a8d568931d9b23ce0df1265d05259a7012081c9 Mon Sep 17 00:00:00 2001 From: Ahmed Date: Sun, 14 Jun 2026 01:46:29 +0300 Subject: init: mostly vibed --- docs/osterman.md | 134 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 docs/osterman.md (limited to 'docs/osterman.md') diff --git a/docs/osterman.md b/docs/osterman.md new file mode 100644 index 0000000..2e81629 --- /dev/null +++ b/docs/osterman.md @@ -0,0 +1,134 @@ +# osterman + +Channel moderation bot. Manages bans, kicks, mutes, auto-modes, content filters, +and idle tracking. + +## Dependencies + +No external libraries required. + +## Plugins + +| File | Role | +|------|------| +| `protect.py` | Setup, passive protection: flood, caps, repeat, badword, clone, join flood | +| `commands.py` | All user-facing moderation and config commands | +| `tracking.py` | SQLite event log, greeting, `!seen`, `!info`, `!log` | +| `idle.py` | Idle detection tick, `!afk`, `!idle` | +| `help.py` | Three-level help system | + +## Message routing + +| Output type | Delivery | +|-------------|----------| +| `!seen`, `!idle ` results | Channel message | +| `!info`, `!log` results | PM to nick | +| `!ban list`, `!config`, `!filter list`, `!badword list` | PM to nick | +| All other command feedback (errors, confirmations) | IRC NOTICE to nick | +| Greetings, idle warns, bad word warn | IRC NOTICE to nick | + +## Help system + +``` +!help list topics +!help list commands for a topic +!help description and usage for a command +!help description and usage (topic not required) +``` + +Topics: `mod`, `config`, `track`, `idle`, `admin` + +## Commands + +### Moderation (owner / ACL / op) + +| Command | Short | Description | +|---------|-------|-------------| +| `!kick [reason]` | `!k` | Kick | +| `!ban [reason]` | `!b` | Ban + kick | +| `!ban list` | `!b list` | View channel ban list (PM) | +| `!bankick [reason]` | `!bk` | Ban + kick (explicit) | +| `!unban ` | `!ub` | Remove ban | +| `!tempban [reason]` | `!tb` | Timed ban (auto-lifts) | +| `!mute ` | `!mu` | Quiet (+q) | +| `!unmute ` | `!umu` | Unquiet (-q) | +| `!voice ` | `!v` | Give voice (+v) | +| `!devoice ` | `!dv` | Remove voice | +| `!op ` | `!o` | Give op (+o) | +| `!deop ` | `!do` | Remove op | +| `!halfop ` | `!hop` | Give halfop (+h) | +| `!dehalfop ` | `!dhop` | Remove halfop | +| `!lock [m\|i]` | `!lk` | Lock channel (+mi, +m, or +i) | +| `!unlock [m\|i]` | `!ulk` | Unlock channel | + +### Auto-modes (owner / ACL / op, per channel) + +| Command | Short | Description | +|---------|-------|-------------| +| `!autoop [nick\|mask]` | `!ao` | Auto +o on join | +| `!autovoice [nick\|mask]` | `!av` | Auto +v on join | +| `!autohalfop [nick\|mask]` | `!ahop` | Auto +h on join | + +### Config / lists (owner / ACL) + +| Command | Short | Description | +|---------|-------|-------------| +| `!blacklist [mask]` | `!bl` | Global ban list (all channels) | +| `!whitelist [mask]` | `!wl` | Global bypass list | +| `!except [mask]` | `!ex` | Per-channel bypass list | +| `!acl [nick]` | (none) | Trusted nicks (can use mod commands) | +| `!filter [pattern]` | `!f` | Per-channel regex content filter | +| `!badword [word]` | `!bw` | Per-channel word block list | +| `!set ` | `!s` | Set a config value (in channel: per-channel; in PM: global) | +| `!config [#channel]` | `!cfg` | Show channel config (PM) | +| `!idle ` | `!id` | Toggle idle detection | + +### Tracking + +| Command | Auth | Description | +|---------|------|-------------| +| `!seen ` | anyone | Last time nick was seen in this channel. Responds in channel. Owner/ACL may call from PM for cross-channel lookup. | +| `!info ` | anyone | Nick summary scoped to this channel (PM). Owner/ACL may call from PM for global lookup. | +| `!idle ` | anyone | How long nick has been idle in this channel. Responds in channel. | +| `!log [n]` | owner / ACL | Full event log for nick (PM) | +| `!afk` | anyone | Reset your idle timer | + +### Admin (owner) + +| Command | Short | Description | +|---------|-------|-------------| +| `!join <#channel>` | `!j` | Join a channel | +| `!part [#channel]` | `!p` | Leave a channel | +| `!chans` | `!c` | List channels | + +## Configurable settings (`!set `) + +| Key | Default | Description | +|-----|---------|-------------| +| `flood_threshold` | 5 | Messages before flood action | +| `flood_window_sec` | 10 | Flood detection window (seconds) | +| `caps_filter` | 1 | Enable caps filter (0/1) | +| `caps_percent` | 70 | Caps percentage threshold | +| `caps_min_len` | 10 | Minimum message length to check | +| `repeat_filter` | 1 | Enable repeat filter (0/1) | +| `repeat_threshold` | 3 | Repeated messages before action | +| `repeat_window_sec` | 30 | Repeat detection window (seconds) | +| `clone_limit` | 2 | Max connections from same host | +| `join_flood_filter` | 1 | Enable join flood filter (0/1) | +| `join_flood_count` | 5 | Joins before action | +| `join_flood_window` | 10 | Join flood window (seconds) | +| `nick_flood_filter` | 1 | Enable nick flood filter (0/1) | +| `nick_flood_count` | 3 | Nick changes before action | +| `nick_flood_window` | 60 | Nick flood window (seconds) | +| `badword_action` | kick | Action on badword: `kick` or `warn` | +| `tempban_max_min` | 60 | Max duration for `!tempban` (minutes) | +| `idle_warn_min` | 45 | Minutes idle before warning | +| `idle_kick_min` | 60 | Minutes idle before kick | +| `log_limit` | 6 | Default number of events shown by `!log` | +| `greet` | 1 | Send join greeting (0/1) | + +## Config keys + +| Key | Description | +|-----|-------------| +| `[osterman] db_path` | Path to JSON database file | -- cgit v1.2.3