PRD: Hotwire IRC Client (from Ibis / mIRC reference scripts)

Version: 1.2 Status: Ready for implementation Source analysis: reference/stuff · 39 script files Output path: docs/pdf.md Stack: Ruby on Rails 8, Hotwire (Turbo + Stimulus), ActionCable, SQLite/PostgreSQL

1. Executive summary

Build a fully featured web IRC client that recreates the ergonomics of the legacy Ibis mIRC script suite (reference/stuff, formerly reference/newmirc) using modern Rails tooling.

Real-time chat flows through ActionCable WebSockets; UI updates use Turbo Streams and Stimulus controllers for nick lists, topic bars, and context menus. The goal is desktop-class IRC in the browser without requiring mIRC.

Analysis scanned 104 event handlers, 241 popup menu items, and 20 dialog definitions from the reference scripts.

The bundled mirc.pdf scripting reference is available under reference/mirc.pdf for alias/syntax parity during implementation.

Phased delivery

2. Problem statement

The Ibis script collection (style.ibis, popups_*.ibis, dialogs.ibis, events.ibis, etc.) implements a rich IRC workflow:

• Coloured, indented channel logs with custom join/part/kick/topic formatting

• Deep right-click menus on nicks, channels, and the status window

• DCC chat/send, CTCP tooling, and XDCC leech helpers

• Settings dialogs for flood protection, auto-join, auto-connect, and away behaviour

No browser client in the Rabbot ecosystem reproduces this surface area. A Rails Hotwire app provides a maintainable path to parity while keeping server-side IRC connection logic testable.

3. Goals and non-goals

Goals

• ActionCable bridge between IRC server and browser sessions (one server-side IRC connection per user or shared bouncer model)

• Hotwire UI: Turbo Frames for channel tabs, Turbo Streams for incremental log lines

• Stimulus controllers for context menus, mode toggles, and dialog panels

• Feature parity with detected reference capabilities (see section 5)

• mIRC colour code rendering (0–98) matching Rabbot IrcFormat conventions

• Responsive layout: channel list, chat pane, nick list, status bar

• Companion bot: Opt-in per-user Rabbot with fandom.com persona; persists IRC events while browser tab is closed; replays on reconnect

Non-goals (v1)

• Binary-compatible mIRC script execution in the browser

• Full Windows-only integrations (Notepad, Explorer paths from popups)

• IRCnet/EFnet-specific exploits or channel flooding tools from legacy scripts

4. Architecture overview

app/
  channels/irc_channel.rb          # ActionCable — stream log lines to browser
  controllers/irc/
    sessions_controller.rb         # Connect/disconnect IRC
    channels_controller.rb         # Join/part, topic, modes
    messages_controller.rb         # Send channel/PM text
    context_menus_controller.rb    # Popup menu actions (Turbo responses)
  javascript/controllers/
    irc_log_controller.js            # Append Turbo Stream fragments
    context_menu_controller.js       # popups_* parity
    dialog_controller.js             # settings/flood/lock dialogs
  models/
    irc_connection.rb                # Server-side IRC client (Cinch / ircinch)
    irc_message.rb                   # Parsed PRIVMSG/NOTICE/JOIN/PART
    irc_companion_profile.rb         # user ↔ fandom URL ↔ character YAML path
    irc_event.rb                     # persisted IRC events for replay
  services/irc/
    event_formatter.rb               # style.ibis coloured output
    ctcp_handler.rb                  # ping/time/version
    dcc_coordinator.rb               # Phase 3 — WebRTC or relay fallback
    network_profile.rb               # per-network services + startup config
    capability_probe.rb            # parse 004/005/MOTD into supported features
    connection_notes.rb              # @stuff parity — structured connect log
    companion_bot_provisioner.rb     # spawn/stop Rabbot from profile
    event_store.rb                   # append + cursor query
    sync_catchup.rb                  # build Turbo Stream replay payload
  jobs/
    companion_bot_lifecycle_job.rb   # enable/disable, channel mirror
lib/irc_format.rb                    # Shared with Rabbot — mIRC colours
lib/character_profile.rb             # existing — persona source
lib/character_profile_generator.rb   # existing — URL → YAML

Real-time flow

1. Browser subscribes to IrcChannel with session token

2. Rails IRC worker receives PRIVMSG → parses → IrcMessage record (optional) → broadcasts Turbo Stream

3. Stimulus updates scroll position, nick highlights, and unread badges

5. Feature mapping (reference → web)

Detected from mirc.pdf, style.ibis, popups_chat.ibis, popups_channel.ibis, popups_nicklist.ibis, popups_status.ibis, popups_menubar.ibis:

Detailed script inventory, alias notes, and popup mapping: docs/ibis-script-reference.md.

Context menus (popups_*.ibis)

Implement Stimulus-driven menus mirroring:

• popups_channel.ibis — channel window

• popups_chat.ibis — query/private chat window

• popups_menubar.ibis — main menu bar

• popups_nicklist.ibis — nick list selection

• popups_status.ibis — status window

Dialogs

Priority matrix: see docs/irc-client-foundations.md §20.

• asdf — drop v1 — not in scope

• chan — drop v1 — not in scope

• diuqil — drop v1 — not in scope

• draw — drop v1 — not in scope

• first — drop v1 — not in scope

• ircspy — drop v1 — not in scope

• lock — Turbo Frame modal — Phase 3 — screen lock / away

• mp3 — drop v1 — not in scope

• pc — drop v1 — not in scope

• settings — Turbo Frame modal — Phase 2 — auto-join, colours, companion bot

• setup_autojoin — Turbo Frame modal — Phase 2 — merged into settings

• setup_ban — Turbo Frame modal — Phase 3 — ban list viewer

• setup_flood — Turbo Frame modal — Phase 3 — flood limits

• startup — Turbo Frame modal — Phase 2 — connection notes panel

• tdccchangesettings — drop v1 — not in scope

• topic — Turbo Frame modal — Phase 2 — channel topic editor

• who — Turbo Frame modal — Phase 2 — context menu driven

• whois — Turbo Frame modal — Phase 2 — context menu driven

• whoischan — drop v1 — not in scope

• xdccleech — drop v1 — not in scope

6. UI / UX requirements

• Message log: Plain body text; colour only on nicks, joins/parts, topics, and timestamps (match lib/CONVENTIONS.md § IRC presentation)

• Nick list: Group by op/voice; colour from style.ibis nick colouring rules

• Status bar: Network, lag, uptime, unread PM count (from popups_status.ibis / titlebar toggles)

• Channel tab bar: Auto-join list persistence (localStorage + server profile)

• Mobile: Collapsible nick list; long-press for context menu

7. Technical requirements

• Rails 8, import maps, Turbo 8, Stimulus 3

• solid_cable or Redis for ActionCable adapter in production

• Background job for IRC read loop (IrcReadJob) with graceful reconnect

• Encrypted credentials per IrcNetworkProfile; never log raw PASS/IDENTIFY

• Never emit services auth commands unless the network profile and connection notes (MOTD + startup numerics) confirm support

• Rate limiting mirroring flood protection dialog (allow N CTCP events every M seconds)

• System tests with Capybara + ActionCable test helper

8. Phase 1 deliverables (MVP)

• [ ] IRC connect form (server, port, nick, SSL toggle)

• [ ] Join/part channel; live message stream via ActionCable

• [ ] Styled JOIN/PART/QUIT/TOPIC lines from style.ibis rules

• [ ] Private message pane

• [ ] Basic nick list with op/voice prefixes

9. Phase 2 deliverables

• [ ] Context menus (popups_chat, popups_channel, popups_nicklist)

• [ ] CTCP ping/time/version

• [ ] Channel mode toggles from popups_channel.ibis

• [ ] Notify and ignore lists

• [ ] Settings dialog (auto-join, colours, echo indent)

• [ ] Channel/query logging (downloadable)

• [ ] Settings: companion bot toggle, fandom URL field, visibility option

• [ ] Fandom URL validation + profile preview/generation

• [ ] IrcEventStore with cursor-based replay API

• [ ] ActionCable / Turbo catch-up on reconnect

10. Phase 3 deliverables

• [ ] DCC chat relay (WebSocket tunnel or external helper)

• [ ] File upload/send with progress bar

• [ ] XDCC pack browser (read-only; no leech automation)

• [ ] Per-network services auth (profile + MOTD/numeric discovery)

• [ ] Auto-voice/op rules engine

• [ ] Flood protection enforcement

• [ ] Visible-mode channel mirroring (bot JOIN/PART sync with user)

• [ ] Retention policy + storage compaction

• [ ] Companion status in status bar (e.g. “Dr. Weird is watching trout”)

11. Success metrics

• Connect and chat on Undernet test channel within 30 seconds of signup

• Sub-200ms Turbo Stream delivery for 95th percentile local messages

• Context menu covers ≥80% of popups_chat.ibis actions (excluding OS-specific ones)

• mIRC colour rendering matches Rabbot golden fixtures

• Services commands (identify, ghost, ChanServ recovery) only fire when network profile and connection notes confirm capability

• Reopen tab after 5+ minutes away → 100% of missed messages appear within 2s without manual refresh

• Fandom URL → usable companion nick + profile in <30s (cached profile <2s)

• Disabling companion bot quits IRC within 10s; no ghost nicks after 60s

12. Legacy reference caveats

The Ibis mIRC scripts in reference/stuff were written for 2000s-era DALnet/Undernet networks. NickServ, ChanServ, and MemoServ menu items, startup aliases, and raw numeric handlers are historical defaults — not a portable spec for a modern web client.

12.1 Outdated services assumptions

Do not port these patterns literally:

• nickserv IDENTIFY %IbisWord — global identify on connect/away-return (aliases1.ibis, input.ibis, popups_menubar.ibis)

• nickserv ghost / RECOVER — auto-ghost on nick-in-use (raw 433 in raw.ibis)

• chanserv set $chan mlock -i / chanserv unban — join-failure recovery (raw 473/474 in raw.ibis)

• Register prompts baked into raw 477

Modern networks differ: SASL PLAIN, CertFP, different service nicks (e.g. nickserv@services.dal.net on DALnet via pns in aliases1.ibis), or no services at all (EFnet). Auth and recovery commands must be configured per network, never assumed globally.

12.2 Per-network connection profiles

Mirror mIRC’s servers.ini groups with a saved IrcNetworkProfile per network:

Encrypted credentials stay per profile, not one global %ibisword.

12.3 Connection notes — capability discovery

The legacy @stuff status window (events.ibis opens it on start; raw.ibis feeds it) is the model for the web client’s connection log. On each connect, parse and surface startup IRC numerics, then gate services commands on what the server actually supports.

Startup IRC numerics (from reference/stuff/raw.ibis):

MOTD text often documents the network’s real registration flow — treat it as authoritative over hardcoded menu commands. Read connection notes (MOTD + startup numerics) to determine what is supported before enabling NickServ/ChanServ actions.

12.4 Implementation mapping

See §4 architecture: network_profile.rb, capability_probe.rb, and connection_notes.rb under app/services/irc/.

13. Fandom companion bot (offline sync)

Closing the browser tab drops the ActionCable subscription. Without a persistent agent, missed messages, nick-list changes, and topics are lost when the user returns.

Each web IRC user may enable a companion bot in settings. While enabled, a Rabbot instance (persona from a fandom.com wiki page) maintains channel presence and writes structured events to server storage. On reconnect, the client fetches and renders everything since its last cursor — no manual scroll-back or /names refresh.

13.1 Problem and solution

Problem: The web client is ephemeral; IRC traffic continues whether or not a tab is open.

Solution: An opt-in companion bot acts as a per-user bouncer (see §3 shared bouncer model). It logs IRC events server-side and replays them when the browser reconnects.

13.2 Settings (options dialog)

Add to the settings dialog (§5 dialogs / Phase 2 deliverables):

Activation flow:

1. User pastes fandom URL → server validates via CharacterTranscripts.fandom_url?

2. Server generates or loads CharacterProfile (reuse CharacterProfileGenerator for first-time URLs; cache YAML per user)

3. Preview shows character name + summary before save

4. On enable, provision companion bot config (nick derived from profile name, IRC-sanitized)

5. On disable, graceful quit; optional event retention policy (keep N days for re-enable)

13.3 Fandom persona source

Any fandom wiki page is valid — not limited to characters:

• Character pages (primary example; matches existing Dr. Weird flow)

• Episode / transcript pages

• Locations, items, factions — generator extracts title + summary + traits from MediaWiki API (CharacterProfileGenerator.fetch_api_source)

Reuse existing Rabbot libs (lib/character_profile.rb, lib/character_profile_generator.rb, lib/character_transcripts.rb); no new fandom parser required for v1.

Bot behaviour (non-sync): Companion is a lightweight Rabbot instance — CharacterResponder + minimal plugins only (no AI spam). Persona is flavour; sync is the primary job.

13.4 Sync and catch-up

Event store (new service; do not reuse AiChannelLog, which caps at 10 entries):

• IrcEventStore — append-only, keyed by (user_id, network, channel, monotonic_id)

• Event types: PRIVMSG, NOTICE, JOIN, PART, QUIT, TOPIC, NICK, MODE, KICK

• Store plain + formatted text (formatted via event_formatter.rb / IrcFormat)

Cursor model:

• Browser persists last_event_id per (network, channel) in session + localStorage

• On ActionCable subscribe / Turbo reconnect: GET /irc/sync?since=<cursor> → Turbo Stream batch append

• Nick list and topic bar updated from latest snapshot events in the batch

13.5 Visibility modes

• Visible mode: Bot joins when user joins; mirrors channel set; separate nick visible to others

• Invisible mode: Bot does not JOIN channels; piggybacks on the user’s server-side IRC connection (bouncer worker) and logs from that read loop — preferred when channel etiquette matters

User selects mode via companion_visibility in settings (see §13.2).

13.6 Architecture

See §4 architecture for irc_companion_profile.rb, irc_event.rb, companion_bot_provisioner.rb, event_store.rb, sync_catchup.rb, and companion_bot_lifecycle_job.rb.

Real-time catch-up flow:

1. Companion bot (or bouncer worker) appends IRC events to IrcEventStore

2. Browser tracks last_event_id per channel

3. On reconnect, sync_catchup.rb builds Turbo Stream payload for events since cursor

4. Stimulus appends missed lines and refreshes nick list / topic from snapshot events

13.7 Phased deliverables

Phase 2 (core companion bot):

• [ ] Settings: companion bot toggle, fandom URL field, visibility option

• [ ] Fandom URL validation + profile preview/generation

• [ ] IrcEventStore with cursor-based replay API

• [ ] ActionCable / Turbo catch-up on reconnect

Phase 3 (hardening):

• [ ] Visible-mode channel mirroring (bot JOIN/PART sync with user)

• [ ] Retention policy + storage compaction

• [ ] Companion status in status bar

13.8 Success metrics

See §11 success metrics for companion-bot-specific targets.

13.9 Non-goals

• Companion bot is not a full AI chat agent in channels (persona flavour only)

• No automatic fandom page picking — user supplies URL

• No cross-user shared companions

14. Foundations supplement

Build-from-scratch decisions (gem packaging, optional auth, schema, workers, embed API, style.ibis mapping, dialog triage, deployment, tests) are documented in docs/irc-client-foundations.md.

Key decisions:

• rabbot-irc gem — Rails engine embeddable in any host app; mount full-page or attach to any DOM element via Stimulus irc-chat

• Optional accounts — anonymous IRC connect; accounts unlock persistence, saved networks, and companion bot (§13)

• Cinch workers — long-lived bin/irc_worker holds sockets; Solid Queue for short jobs only

• Scale path — Postgres + Redis + Vinyl HTTP edge; see foundations §23

• Federated donate — optional volunteer worker mesh; see foundations §24

End of PRD. Generated by !directchat prd from Rabbot directchat plugin. Foundations supplement: docs/irc-client-foundations.md (§14–§24). Script reference: docs/ibis-script-reference.md.