Rabbot code conventions

Navigation for AI and new contributors: AGENTS.md, LIB_INDEX.md, CONTRACTS.md.

Keep plugins small and DRY — reuse lib/ helpers instead of copying code.

Shared libraries

Do not duplicate

• irc_color / IRC_CTRL — use IrcFormat (already existed in many plugins; consolidate new code there)

• URI.parse(...).open("User-Agent" => ...) — use RabbotHttp.fetch

• Nick/channel normalization — use Normalize or RabbotDb.normalize_* for DB calls

• Add/rem/list parsing — use ListCommand.parse_add_rem when the grammar matches

• Whitespace collapse / truncate / title-case — use TextUtil

• Catalogue search query parsing — use SearchQuery.parse

• Catalogue IRC report cards — use SearchReport + SearchLookup.format

• Cursor-agent plan questions — use CursorAgentQuestions.extract_from_event

• Directchat session wire encoding — use DirectchatSessionCodec

• mIRC .ibis file reads / popup line detection — use DirectchatMircParse

• Database access — use RabbotDb / plugin_data, not new JSON files in data/

IRC presentation

Rabbot targets Undernet with mIRC-class clients. Aim for award-winning ASCII art on the frame around a reply — not on the content itself.

Clean body text (important)

Keep main text plain. Colour and ASCII art belong on:

• Headings — «TAG» bracket label, -=// title \=- menu heading

• Separators — ===, ·, — between header fields

• Footers — muted status strip, model/timing line

• Doodles — opening/closing box art, ASCII bars beside stats (not inside sentences)

The readable payload (forecast text, joke punchline, wiki summary, list items) should be uncoloured plain text unless one word truly needs emphasis (e.g. a nick). Think fserve layout: flashy header, plain file list, small grey footer.

«BOM»                                   ← bracket label (IrcFormat.bracket_label / tag)
-=// Brisbane · issued 14:30 \\=-       ← menu heading (IrcFormat.menu_heading)
Fine. Partly cloudy. Max 28.             ← plain body
(forecast · Bureau of Meteorology)       ← accent_paren footer

Reference implementations: plugins/bom.rb, plugins/news.rb, lib/car_report.rb, lib/irc_reply.rb, plugins/silence.rb, plugins/cocktail.rb, plugins/fart.rb, plugins/cursorusage.rb.

Not: every line wrapped in \003 codes.

Prefer IrcReply.card or IrcFormat.report_header / report_footer for reply frames; use IrcFormat.divider for section breaks. Leave body lines unstyled.

Character set (ASCII-first)

Many IRC clients mishandle UTF-8 in channel text. Prefer widely compatible characters for art and borders:

When in doubt, build banners from +, -, and | (fserve-style) rather than Unicode box glyphs. A +---+ frame beats mojibake on a phone client.

Colour contrast

Always pair foreground and background so text stays readable:

• Good: (1, 8) black on yellow, (0, 4) white on red, (0, 3) white on green, (0, 10) black on aqua, (15, 1) white on black

• Weak: similar fg/bg (e.g. (14, 15), (8, 14)), or light-on-light / dark-on-dark

• Extended colours (16–98): use bright fg (52–63) on dark bg (88–92), or light bg (96–98) with dark fg (88–89)

Reset with IRC_RESET after every coloured segment.

Extended mIRC colours (16–98)

Beyond the 16 theme colours (0–15), mIRC defines 83 fixed RGB colours (16–98) that look the same for all users. IrcFormat.color accepts any index 0–98:

STYLE_ACCENT = IrcFormat.color(52)        # bright red foreground
STYLE_PANEL  = IrcFormat.color(15, 88)    # light grey on near-black
STYLE_LINK   = IrcFormat.color(59, 98)    # blue on white

Highlights: 52–63 vivid primaries, 64–75 pastels, 76–87 light tints, 88–98 greyscale. See IRC formatting docs for the full table. Prefer extended colours for accents and gradients; keep body text on 0–15 for broad client support.

Use IrcFormat (require_relative "../lib/irc_format"):

IRC_CTRL = IrcFormat::CTRL
IRC_RESET = IrcFormat::RESET
STYLE_TITLE = IrcFormat.named_style(:title)   # extended 52,88
STYLE_CLASSIC = IrcFormat.named_style(:classic_title)  # theme-dependent 0,4

def self.decorate(text, style)
  IrcFormat.decorate(text, style)
end

Channel opt-in: !lolcat on pipes themed replies through installed lolcat (ANSI→IRC via AnsiToIrc). Body rainbow is intentional when enabled.

mIRC colour palette (0–15)

Background colours use the same index range (0–15 theme, 16–98 fixed). Format: \003fg,bg via IrcFormat.color(fg, bg) — codes are zero-padded to two digits.

Undernet style sheet

Avoid on Undernet: emoji-heavy output, rainbow per-word colouring, Markdown, colouring entire paragraphs, Unicode art in body lines. Some channels use +c (no colours) — plain body still works.

Classic IRC aesthetics (what to emulate)

Patterns used across plugins

Recommended colour pairs (fg, bg)

Always IRC_RESET after each coloured segment so later text is not tinted. Name styles STYLE_TITLE, STYLE_NICK, STYLE_SEP, etc. at class level — see plugins/bom.rb and plugins/autoop.rb.

Plugin checklist

1. # Help: description at top for !help (see plugins/help.rb). If the plugin is loaded on multiple bots, add — responders: <scope> (see Responder scope below).

2. require_relative "../lib/flood_safe" + include FloodSafe for long output; add flood_safe_theme + FloodSafeTheme and themed_flood_safe_reply for theme-ready plugins

3. Extract testable logic into self. methods; keep execute thin

4. Prefer RabbotDb over in-memory hashes for data that should survive restarts

5. Check lib/ before adding a helper — extend an existing module if it fits

6. Style headings, footers, separators, and doodles only — use IrcReply.card or IrcFormat.report_header; keep body text plain; see IRC presentation

7. Theme-ready plugins — register PaintSamples, wire FloodSafeTheme + themed_flood_safe_reply; see docs/THEME_MIGRATION.md

Theme migration (IRC frames)

Channel admins use !theme use <name> to recolour plugin output via PaintStore overrides. Migrated plugins call ThemeOutput.apply before sending (via FloodSafeTheme).

require_relative "../lib/flood_safe_theme"

include FloodSafeTheme

def execute(m, ...)
  themed_flood_safe_reply(m, format_reply(...))
end

Register sample output in lib/paint_samples/register_*.rb. Sprint backlog: docs/THEME_MIGRATION.md.

Progress gutter (multi-line replies)

FloodSafe defaults to with_progress: :auto — prefixes each queued line/chunk with a 4-character gutter (01% … 100 ) when there are 2+ logical lines or 2+ flood chunks. Gutter text uses uniform aqua on dark blue (IrcFormat.color(11, 2)); channel themes may override via progress_percent paint rules.

themed_flood_safe_reply(m, format_reply(...))              # auto progress
flood_safe_reply(m, "error", with_progress: false)         # one-liner / errors
flood_safe_reply(m, header_and_body, skip_prefix_lines: 1) # e.g. !sing header

Body text after the gutter aligns at column 5 — see ReplyLayout::PROGRESS_GUTTER_WIDTH. Use TextAlign.format_colon_rows / ReplyLayout.align_colon_body for label:value blocks.

Responder scope

Several bots share the same channels. If a plugin is included on more than one bot, declare who should reply and gate in execute with BotIdentity (silent early return — no channel spam).

require_relative "../lib/bot_identity"

def execute(m, prompt)
  return if admin_command?(prompt) && !BotIdentity.owner_bot?(bot)
  # ...
end

Help line examples:

• # Help: chat with GPT — voice (+v) or op required — responders: all_loaded (models: owner)

• # Help: controlled autonomous chat — responders: room_reader

AI access

User-initiated AI commands (!ai, etc.) must check AiAccess.user_allowed? before calling agents:

• IRC channel op or voice (+v), or

• Rabbot-registered user at voice level or higher (for non-moderated channels).

Use lib/ai_access.rb. Internal system paths (room_reader refine, !chat autonomous mode, !rabbot plugin agent) are exempt but must not auto-execute builds from bots — see ChannelTrust.

require_relative "../lib/ai_access"

return flood_safe_reply(m, AiAccess.denial_message) unless AiAccess.user_allowed?(
  channel: m.channel, user: m.user, network: bot.config.server, nick: m.user.nick
)

Tests

• test/ mirrors plugins/ (test/plugins/foo_test.rb for plugins/foo.rb)

• Pass fetch: lambdas into search/lookup methods — no live HTTP in tests

• Use temp DB: RabbotDb.db_path = ...; RabbotDb.reset!(path: ...)

New plugin generation

rabbot_meta build/enhance prompts include IRC presentation, theme migration (FloodSafeTheme, PaintSamples, !theme), and column layout (ReplyLayout, progress gutter, colon alignment). Follow them when writing plugins by hand too — see Theme migration and Progress gutter above.