Lib index

Domain catalogue for lib/. See also CONVENTIONS.md (shared helpers) and CONTRACTS.md (return shapes).

Naming conventions

Suffix / pattern Role Examples
*_search.rb Parse query, fetch HTTP, return { query, total, items, error } auslib_search, car_search, whatson_search
*_report.rb Format hits as IRC reply (IrcReply.card or lines) auslib_report, theatres_report
*_config.rb Base URLs, limits, env key names auslib_config, govau_config, kfc_config
*_store.rb RabbotDb plugin JSON persistence whatsnew_store, veto_store, quote_store
*_game.rb Game rules and state machine rpg_game, battleships_game, siege_game
*_lookup.rb Single-purpose lookup (no full search/report split) man_lookup, geo_lookup, urban_lookup
*_format.rb IRC presentation for a domain sunbus_format
Shared (no prefix) Cross-cutting helpers text_util, search_report, normalize, game

Subdirectories: solitaire/ (engine + games), bot_console/ (TUI), car_search/ (query, listings, details, filter — loaded via car_search.rb), clock/ (flip, report, segment, … — shims at clock_*.rb), sunbus/ (gtfs, connect, format, … — shims at sunbus_*.rb), directchat/ (wire, session, mesh, … — shims at directchat_*.rb; directchat_mirc/ and directchat_prd/ stay at repo root), ai/ (agent, access, chat_core, … — shims at ai_*.rb; ai/chat_core/ context + plan), rabbot_db/ (connection, migrations, channels, users, plugin_data — loaded via rabbot_db.rb), animal_news/ (parse, format, fetch, plugin — loaded via animal_news.rb), geo_lookup/ (geocode, place, format — loaded via geo_lookup.rb), vendor/ (generated — do not edit).

1. IRC presentation

Purpose: Undernet/mIRC styling — coloured headers/footers, plain body text.

Module Role
irc_format.rb Colours, tags, menu headings, dividers, nicks; named_style via extended pairs
irc_extended_colors.rb mIRC fixed extended palette 16–98 — RGB table, groups, lookup
irc_ascii.rb Ibis/fserve ASCII frame helpers (plain text)
ansi_to_irc.rb Convert lolcat ANSI output to mIRC extended codes
lolcat_runner.rb, lolcat_store.rb, lolcat_output.rb, lolcat_command.rb, lolcat_report.rb !lolcat channel rainbow pipeline
irc_reply.rb IrcReply.card composer
flood_safe.rb Multi-line reply chunking
flood_safe_theme.rb themed_flood_safe_reply — applies ThemeOutput before send
message_progress.rb Line % gutter (aqua on dark blue; theme progress_percent)
reply_layout.rb Fixed 4-char progress gutter; colon body alignment
reply_delivery.rb Thread-local lag/queue context for progress digits
theme_output.rb Runtime PaintApply for channel overrides
theme_paint_rules.rb Auto-discover paint rules from PaintSamples
paint_samples.rb Registered sample lines per plugin (!paint preview)
theme_catalog.rb, theme_paint.rb, theme_store.rb Built-in themes, !theme use, persistence
paint_apply.rb, paint_store.rb Colour override apply/store
paragraph_format.rb Byte-limited paragraph joining
help_parser.rb, help_reply.rb !help sections

Plugins: all (via FloodSafe); reference: plugins/bom.rb, plugins/news.rb.

Tests: test/irc_format_test.rb, test/lib/irc_reply_test.rb, test/lib/help_*_test.rb.

2. HTTP and text utilities

Module Role
rabbot_http.rb fetch, fetch_json, default User-Agent
text_util.rb squish, truncate, title_words, format_count
search_query.rb SearchQuery.parse for catalogue queries
search_report.rb SearchReport.* cards, SearchLookup.format
normalize.rb Nick/channel/user_key normalization
url_link.rb, url_preview.rb URL detection and previews

Tests: test/lib/text_util_test.rb, test/lib/search_*_test.rb, test/lib/url_preview_test.rb.

3. Database

Module Role
rabbot_db.rb PostgreSQL facade: channels, users, lists, plugin JSON, bots (see rabbot_db/)
bot_mesh.rb Cross-bot shared plugin_data via per-network/channel groups
game_store.rb, game_persistent_store.rb Game credit persistence wrappers
remind_store.rb, quote_store.rb, veto_store.rb, … Domain-specific stores

Doc: RABBOT_DB.md.

Tests: test/rabbot_db_test.rb, test/lib/bot_log_store_test.rb, store *_test.rb.

4. AI stack

Module Role
ai/ access.rb, agent.rb, guard.rb, chat_core.rb, plan_session.rb, … AI stack (shims: ai_*.rb)
ai/chat_core/ context.rb, plan.rb !aip context assembly and plan dispatch
draw_core.rb, draw_session.rb, comic_core.rb, ascii_display_size.rb ASCII art from images/prompts; comic strips; display sizes
dcc_image_hooks.rb Pub/sub after DCC image registration
cursor_agent_output.rb, cursor_agent_questions.rb Stream-json parsing

Plugins: ai.rb, aip.rb, draw.rb, comic.rb, wget.rb, recipe.rb (AI paths).

Secrets: CURSOR_SESSION_TOKEN — see README.md.

Tests: test/lib/ai_*_test.rb, test/plugins/ai_test.rb.

5. Rabbot meta / build pipeline

Module Role
rabbot_meta_agent.rb Cursor agent for plugin builds
rabbot_meta_build.rb Write plugin + test files from agent output
rabbot_meta_build_job.rb Pre-build IRC lines when a queued job starts
rabbot_meta_colors_report.rb !rabbot colors IRC reply formatting
rabbot_meta_build_target.rb Plugin identity for build/enhance queue conflicts
rabbot_meta_queue.rb Serialize build jobs
rabbot_meta_plan_session.rb Pending plan questions for builds
room_reader.rb Steve channel watcher
build_coordinator_store.rb, build_proposal_filter.rb Build proposals and veto
character_transcripts.rb, character_profile.rb Character bot context
lib_reload.rb, plugin_reload_signal.rb Hot reload
whatsnew_tracker.rb, whatsnew_feed.rb Post-build changelog

Plugins: rabbot_meta.rb, build_coordinator.rb, veto.rb, chat_mode.rb.

Tests: test/lib/rabbot_meta_*_test.rb, test/plugins/rabbot_meta_test.rb.

6. Directchat

Module Role
directchat/ session.rb, session_codec.rb, wire.rb, mesh.rb, mesh_io.rb, plan.rb, dcc.rb Session, wire, mesh relay (shims: directchat_*.rb)
directchat/ mirc_parse.rb, mirc_catalog.rb, mirc_inventory.rb, directchat_mirc/ mIRC script analysis
directchat/ prd.rb, directchat_prd/ PRD document generation

Plugin: directchat.rb.

Tests: test/lib/directchat_*_test.rb, test/plugins/directchat_test.rb.

7. Catalogue / library search

Module Role
auslib_search.rb, auslib_report.rb, auslib_config.rb Trove (NLA)
qldlibrary_search.rb, qldlibrary_report.rb, qldlibrary_config.rb SLQ One Search
qldmuseum_search.rb, qldmuseum_report.rb, qldmuseum_config.rb QM CKAN datastore

Plugins: auslib.rb, qldlibrary.rb, qldmuseum.rb.

Fixtures: test/fixtures/auslib/, qldlibrary/, qldmuseum/.

Tests: test/lib/auslib_*_test.rb, qldlibrary_*, qldmuseum_*.

8. Events and places

Module Role
whatson_search.rb, whatson_report.rb, whatson_towns.rb, whatson_free_events.rb Town events
theatres_search.rb, theatres_report.rb, theatres_catalog.rb, theatres_event_cinemas.rb, theatres_jacro_cinema.rb Cinema sessions
town_lookup.rb AU town resolution (catalog + GeoLookup)
geo_lookup.rb Geocoding / IP geo (see geo_lookup/)

Plugins: whatson.rb, theatres.rb, geo.rb, car.rb (location).

Tests: test/lib/whatson_*_test.rb, theatres_*_test.rb, town_lookup_test.rb, geo_lookup_test.rb.

9. Sunbus and QLD transit

Module Role
sunbus/ gtfs.rb, connect.rb, times.rb, stop_search.rb, format.rb, … Townsville/Cairns buses (shims: sunbus_*.rb)
qld_translink_departures.rb, qld_translink_gtfs.rb, qld_translink_rt.rb SEQ Translink
qld_traffic.rb, qld_traffic_watch.rb, qld_config.rb Road events
vendor/translink/gtfs-realtime_pb.rb Generated protobuf

Plugins: sunbus.rb, qld.rb, au_aliases.rb (shortcuts).

Doc: QLD_APIS.md.

Fixtures: test/fixtures/sunbus_gtfs/, sunbus_*_rss.xml, qld_traffic_sample.json, qld_seq_alerts.pb.

Tests: test/lib/sunbus_*_test.rb, test/plugins/qld_test.rb.

10. Government and open data (AU)

Module Role
govau_ckan.rb, govau_ptv.rb, govau_routes.rb, govau_status.rb, govau_derby.rb, govau_tfnsw.rb, … data.gov.au + PTV/TFNSW
abs_api.rb, abs_population.rb, abs_showdown.rb ABS
aec_results.rb, aec_tally.rb AEC
fuel_nsw.rb, fuel_hunt.rb, fuel_config.rb FuelCheck NSW
tm_search.rb, tm_config.rb, tm_game.rb IP Australia trademarks
rba_rates.rb, rba_rumble.rb RBA rates
transit_derby.rb Shared peak-hour logic for derby games

Plugins: govau.rb, abs.rb, aec.rb, fuel.rb, tm.rb, rba.rb.

Doc: AU_APIS.md.

Tests: test/lib/govau_*_test.rb, abs_*, aec_*, fuel_*, tm_*, rba_*.

11. Games

Module Role
game.rb Credits, bets, cards, IRC game styling, PersistentStore
async_duel.rb, async_duel_handler.rb Two-player async games
*_game.rb Per-game rules: rpg_game, battleships_game, siege_game, rumor_game, …
solitaire/registry.rb, solitaire/engine.rb, solitaire/freecell.rb AisleRiot solitaire
aisleriot_catalog.rb Parse AisleRiot XML catalog
fandom_trivia.rb Wiki trivia
fandom_trivia_sources.rb Multi-bot Fandom profile discovery for trivia
bom_poker.rb, quake_roulette.rb, tm_game.rb Themed mini-games

Plugins: blackjack.rb, poker.rb, roulette.rb, solitaire.rb, and async duel plugins.

Tests: test/lib/*_game_test.rb, test/plugins/blackjack_test.rb, etc.

12. Food and retail

Module Role
kfc_api.rb, kfc_menu.rb, kfc_stores.rb, kfc_location.rb, kfc_fetch.rb, kfc_config.rb KFC
red_rooster_api.rb, red_rooster_menu.rb, red_rooster_auth.rb, red_rooster_stores.rb Red Rooster
staticice_search.rb, staticice_report.rb staticICE prices
car_search.rb, car_search/ (query, listings, details, filter), car_report.rb Used car listings

Plugins: kfc.rb, redrooster.rb, staticice.rb, car.rb.

Tests: test/lib/kfc_*_test.rb, red_rooster_*, staticice_*, car_search_test.rb.

13. Media and misc lookup

Module Role
man_lookup.rb Linux man pages
winehq_search.rb WineHQ AppDB
animal_news.rb Google News RSS by animal (see animal_news/)
athf_episode_index.rb ATHF episodes
holiday_calendar.rb, holiday_store.rb Public holidays
recipe_store.rb, recipe_history.rb, ai_recipe_capture.rb Cookbook
image_wget.rb, google_drive_*.rb Image fetch + Drive
ala_species.rb, ala_species_report.rb, ala_myth.rb Atlas of Living Australia

Plugins: man.rb, wine.rb, animal.rb, recipe.rb, wget.rb, ala.rb, holidays.rb.

Tests: matching test/lib/*_test.rb.

14. Clock / flip time

Module Role
clock/flip.rb, clock/flip_store.rb, clock/flip_meaning.rb, clock/flip_rank.rb Upside-down LED clock (shims: clock_flip*.rb)
clock/report.rb, clock/segment.rb, clock/wordnet.rb, clock/lookup_throttle.rb Display and word lookup (shims: clock_report.rb, etc.)

Plugins: clock.rb, flip_time.rb.

Tests: test/lib/clock_*_test.rb, test/plugins/clock_test.rb.

15. Bot runtime

Module Role
rabbot_app.rb Bot factory, YAML config, plugin loading
rabbot_config.rb Config helpers
bot_console.rb, bot_console/ui.rb, bot_console/bot_process.rb, … Multi-bot TUI
async_job.rb Background jobs
bot_identity.rb Owner vs room_reader vs all_loaded
channel_trust.rb Who may trigger builds
graceful_quit.rb, graceful_quit_signal.rb Clean shutdown
plugin_catalog.rb Help topic matching for build suggestions
plugin_timers.rb, message_progress.rb Timers and progress lines
bot_log_store.rb Retained IRC logs
chat_mode_session.rb, chat_mode_registry.rb Autonomous chat mode

Plugins: bot.rb, message.rb, logbook.rb.

Tests: test/lib/bot_*_test.rb, test/plugins/bot_test.rb.