yaic 0.1.0 → 0.2.0

data/docs/agents/ralph/features/05-event-system.md.done

@@ -0,0 +1,167 @@
+# Event System
+
+## Description
+
+Implement the event callback system that allows user code to react to IRC events. This is the primary interface for users of the library.
+
+## Behavior
+
+### Registering Handlers
+
+```ruby
+client.on(:message) { |event| ... }
+client.on(:join) { |event| ... }
+client.on(:raw) { |message| ... }
+```
+
+Multiple handlers can be registered for the same event. They are called in order of registration.
+
+### Event Dispatch
+
+When an IRC message is received:
+1. Parse the message
+2. Determine event type(s) to emit
+3. Build event payload
+4. Call each registered handler with payload
+5. Optionally emit `:raw` for every message
+
+### Event Types
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `:connect` | 001 RPL_WELCOME | `{server:}` |
+| `:disconnect` | Connection closed | `{reason:}` |
+| `:message` | PRIVMSG | `{source:, target:, text:}` |
+| `:notice` | NOTICE | `{source:, target:, text:}` |
+| `:join` | JOIN | `{channel:, user:}` |
+| `:part` | PART | `{channel:, user:, reason:}` |
+| `:quit` | QUIT | `{user:, reason:}` |
+| `:kick` | KICK | `{channel:, user:, by:, reason:}` |
+| `:nick` | NICK | `{old_nick:, new_nick:}` |
+| `:topic` | TOPIC / 332 | `{channel:, topic:, setter:}` |
+| `:mode` | MODE | `{target:, modes:, params:}` |
+| `:error` | 4xx/5xx | `{numeric:, message:}` |
+| `:raw` | Any message | `{message:}` |
+
+### Handler Signature
+
+```ruby
+client.on(:message) do |event|
+  event.source   # Yaic::Source - who sent it
+  event.target   # String - channel or nick
+  event.text     # String - message content
+end
+```
+
+### Error Handling in Handlers
+
+If a handler raises an exception:
+- Log the error
+- Continue calling remaining handlers
+- Do not crash the event loop
+
+## Models
+
+```ruby
+Yaic::Event
+  - type: Symbol
+  - attributes: Hash
+  - message: Yaic::Message (original parsed message)
+  - method_missing for attribute access
+```
+
+## Tests
+
+### Unit Tests - Handler Registration
+
+**Register single handler**
+- Given: New client
+- When: Register handler for :message
+- Then: Handler is stored
+
+**Register multiple handlers for same event**
+- Given: New client
+- When: Register 3 handlers for :message
+- Then: All 3 handlers stored in order
+
+**Register handlers for different events**
+- Given: New client
+- When: Register handlers for :message, :join, :part
+- Then: Each event has its handlers
+
+### Unit Tests - Event Dispatch
+
+**Dispatch calls all handlers**
+- Given: 3 handlers registered for :message
+- When: Dispatch :message event
+- Then: All 3 handlers called in order
+
+**Dispatch with correct payload**
+- Given: Handler registered for :message
+- When: PRIVMSG received from "nick!user@host" to "#chan" with text "hello"
+- Then: Handler receives event with source.nick="nick", target="#chan", text="hello"
+
+**Handler exception doesn't stop others**
+- Given: 3 handlers, second one raises
+- When: Dispatch event
+- Then: First and third handlers still called
+
+**Unknown event type**
+- Given: No handlers registered for :foo
+- When: Dispatch :foo event
+- Then: No error, silently ignored
+
+### Unit Tests - Event Type Detection
+
+**PRIVMSG triggers :message**
+- Given: PRIVMSG message received
+- When: Determine event type
+- Then: Returns :message
+
+**NOTICE triggers :notice**
+- Given: NOTICE message received
+- When: Determine event type
+- Then: Returns :notice
+
+**JOIN triggers :join**
+- Given: JOIN message received
+- When: Determine event type
+- Then: Returns :join
+
+**001 triggers :connect**
+- Given: 001 numeric received
+- When: Determine event type
+- Then: Returns :connect
+
+**4xx/5xx triggers :error**
+- Given: 433 numeric received
+- When: Determine event type
+- Then: Returns :error with numeric in payload
+
+### Integration Tests
+
+**End-to-end message event**
+- Given: Connected client with :message handler
+- When: Another client sends PRIVMSG
+- Then: Handler called with correct source, target, text
+
+**End-to-end join event**
+- Given: Connected client with :join handler
+- When: Client joins #test
+- Then: Handler called with channel="#test", user=self
+
+**Multiple events from one message**
+- Given: Connected client with :raw and :message handlers
+- When: PRIVMSG received
+- Then: Both :raw and :message handlers called
+
+## Implementation Notes
+
+- Use simple array of [event_type, block] pairs
+- Consider using a Queue for thread-safe dispatch
+- Events should be fired synchronously (blocking until all handlers complete)
+- Provide `client.off(:event)` to remove handlers if needed
+
+## Dependencies
+
+- Requires `01-message-parsing.md` (to parse incoming messages)

data/docs/agents/ralph/features/06-privmsg-notice.md.done

@@ -0,0 +1,163 @@
+# PRIVMSG and NOTICE
+
+## Description
+
+Implement sending and receiving private messages and notices. This is the core messaging functionality of IRC.
+
+## Behavior
+
+### Sending PRIVMSG
+
+```ruby
+client.privmsg("#channel", "Hello everyone!")
+client.privmsg("nickname", "Hello you!")
+```
+
+Format: `PRIVMSG <target> :<text>`
+
+Target can be:
+- Channel name (e.g., `#ruby`)
+- Nickname (e.g., `dan`)
+
+### Sending NOTICE
+
+```ruby
+client.notice("#channel", "Announcement!")
+client.notice("nickname", "FYI...")
+```
+
+Format: `NOTICE <target> :<text>`
+
+Same targets as PRIVMSG. Key difference: bots should use NOTICE to avoid loops.
+
+### Receiving PRIVMSG
+
+Incoming format: `:nick!user@host PRIVMSG <target> :<text>`
+
+Parse and emit `:message` event with:
+- `source` - Yaic::Source of sender
+- `target` - Channel or own nick
+- `text` - Message content
+
+### Receiving NOTICE
+
+Incoming format: `:nick!user@host NOTICE <target> :<text>`
+
+Parse and emit `:notice` event with same fields as :message.
+
+### Error Responses
+
+- 401 ERR_NOSUCHNICK - Target user doesn't exist
+- 404 ERR_CANNOTSENDTOCHAN - Cannot send to channel (banned, moderated, not joined)
+- 407 ERR_TOOMANYTARGETS - Too many targets
+
+### Message Length
+
+- Messages over 512 bytes (total) will be truncated by server
+- Client should warn or split long messages
+- Usable text length ≈ 400-450 chars depending on nick/channel length
+
+## Models
+
+No new models. Uses existing Message and Event.
+
+## Tests
+
+### Integration Tests - Sending
+
+**Send PRIVMSG to channel**
+- Given: Client joined to #test
+- When: `client.privmsg("#test", "Hello")`
+- Then: Server receives "PRIVMSG #test :Hello"
+
+**Send PRIVMSG to user**
+- Given: Connected client
+- When: `client.privmsg("othernick", "Hello")`
+- Then: Server receives "PRIVMSG othernick :Hello"
+
+**Send NOTICE to channel**
+- Given: Client joined to #test
+- When: `client.notice("#test", "Announcement")`
+- Then: Server receives "NOTICE #test :Announcement"
+
+**Send message with special characters**
+- Given: Connected client
+- When: `client.privmsg("#test", "Hello :) world")`
+- Then: Server receives "PRIVMSG #test :Hello :) world" (colon preserved)
+
+### Integration Tests - Receiving
+
+**Receive PRIVMSG from user**
+- Given: Client with :message handler
+- When: Other user sends PRIVMSG to client's nick
+- Then: Handler receives event with source, target=own_nick, text
+
+**Receive PRIVMSG in channel**
+- Given: Client joined #test with :message handler
+- When: Other user sends PRIVMSG to #test
+- Then: Handler receives event with source, target="#test", text
+
+**Receive NOTICE**
+- Given: Client with :notice handler
+- When: Server sends NOTICE
+- Then: Handler receives event with source, target, text
+
+**Distinguish channel from private message**
+- Given: :message handler that tracks target
+- When: Receive PRIVMSG to "#chan" vs PRIVMSG to "mynick"
+- Then: target reflects correct destination
+
+### Unit Tests - Message Formatting
+
+**Format PRIVMSG**
+- Given: target = "#test", text = "Hello"
+- When: Build PRIVMSG
+- Then: Output = "PRIVMSG #test :Hello\r\n"
+
+**Format PRIVMSG with colon in text**
+- Given: target = "#test", text = ":smile:"
+- When: Build PRIVMSG
+- Then: Output = "PRIVMSG #test ::smile:\r\n"
+
+**Format NOTICE**
+- Given: target = "nick", text = "Info"
+- When: Build NOTICE
+- Then: Output = "NOTICE nick :Info\r\n"
+
+### Unit Tests - Event Parsing
+
+**Parse PRIVMSG event**
+- Given: `:dan!d@host PRIVMSG #ruby :Hello everyone`
+- When: Parse and create event
+- Then: event.type = :message, source.nick = "dan", target = "#ruby", text = "Hello everyone"
+
+**Parse NOTICE event**
+- Given: `:server NOTICE * :Looking up hostname`
+- When: Parse and create event
+- Then: event.type = :notice, source = server, target = "*", text = "Looking up hostname"
+
+### Error Handling Tests
+
+**Send to non-existent nick**
+- Given: Connected client
+- When: `client.privmsg("nonexistent", "Hello")`
+- Then: Receive 401 ERR_NOSUCHNICK, :error event emitted
+
+**Send to channel not joined**
+- Given: Connected client, not in #secret
+- When: `client.privmsg("#secret", "Hello")`
+- Then: Receive 404 ERR_CANNOTSENDTOCHAN
+
+## Implementation Notes
+
+- PRIVMSG text always needs trailing colon prefix (may contain spaces)
+- Consider convenience method: `client.msg(target, text)` as alias for privmsg
+- Bot authors should use notice() for automatic responses
+- Track own nick to detect private vs channel messages
+
+## Dependencies
+
+- Requires `01-message-parsing.md`
+- Requires `02-connection-socket.md`
+- Requires `03-registration.md` (must be registered to send)
+- Requires `05-event-system.md`

data/docs/agents/ralph/features/07-join-part.md.done

@@ -0,0 +1,190 @@
+# JOIN and PART
+
+## Description
+
+Implement joining and leaving IRC channels. This is essential for participating in channel conversations.
+
+## Behavior
+
+### JOIN Command
+
+```ruby
+client.join("#ruby")
+client.join("#ruby", "channelkey")  # For key-protected channels
+client.join("#a,#b,#c")             # Multiple channels
+```
+
+Format: `JOIN <channel>[,<channel>...] [<key>[,<key>...]]`
+
+Special case: `JOIN 0` leaves all channels.
+
+### Server Response to JOIN
+
+On successful join, server sends:
+1. `:yournick!user@host JOIN #channel` - Confirmation
+2. `332 RPL_TOPIC` - Channel topic (if set)
+3. `333 RPL_TOPICWHOTIME` - Who set topic and when (optional)
+4. `353 RPL_NAMREPLY` - List of users in channel (may be multiple)
+5. `366 RPL_ENDOFNAMES` - End of names list
+
+### JOIN Errors
+
+- 403 ERR_NOSUCHCHANNEL - Invalid channel name
+- 405 ERR_TOOMANYCHANNELS - Client limit reached
+- 471 ERR_CHANNELISFULL - Channel is full (+l mode)
+- 473 ERR_INVITEONLYCHAN - Channel is invite-only (+i mode)
+- 474 ERR_BANNEDFROMCHAN - Banned from channel
+- 475 ERR_BADCHANNELKEY - Wrong or missing key (+k mode)
+
+### PART Command
+
+```ruby
+client.part("#ruby")
+client.part("#ruby", "Goodbye!")  # With reason
+client.part("#a,#b")              # Multiple channels
+```
+
+Format: `PART <channel>[,<channel>...] [:<reason>]`
+
+### Server Response to PART
+
+Server sends: `:yournick!user@host PART #channel :reason`
+
+### PART Errors
+
+- 403 ERR_NOSUCHCHANNEL - Channel doesn't exist
+- 442 ERR_NOTONCHANNEL - Not in that channel
+
+### Tracking Other Users
+
+When other users JOIN/PART:
+- `:othernick!user@host JOIN #channel`
+- `:othernick!user@host PART #channel :reason`
+
+Emit appropriate events for these.
+
+## Models
+
+Track joined channels:
+```ruby
+client.channels  # => {"#ruby" => Yaic::Channel, ...}
+```
+
+## Tests
+
+### Integration Tests - JOIN
+
+**Join single channel**
+- Given: Connected client
+- When: `client.join("#test")`
+- Then: Receive JOIN confirmation, RPL_NAMREPLY, RPL_ENDOFNAMES
+
+**Join channel with topic**
+- Given: Connected client, #test has topic
+- When: `client.join("#test")`
+- Then: Receive RPL_TOPIC with topic text
+
+**Join key-protected channel**
+- Given: Connected client, #secret requires key "pass123"
+- When: `client.join("#secret", "pass123")`
+- Then: Successfully joins
+
+**Join key-protected with wrong key**
+- Given: Connected client, #secret requires key
+- When: `client.join("#secret", "wrongkey")`
+- Then: Receive 475 ERR_BADCHANNELKEY
+
+**Join multiple channels**
+- Given: Connected client
+- When: `client.join("#a,#b,#c")`
+- Then: Joined to all three channels
+
+**Join non-existent channel creates it**
+- Given: Connected client
+- When: `client.join("#newchannel")`
+- Then: Channel created, client is operator
+
+### Integration Tests - PART
+
+**Part single channel**
+- Given: Client in #test
+- When: `client.part("#test")`
+- Then: Receive PART confirmation, channel removed from tracking
+
+**Part with reason**
+- Given: Client in #test
+- When: `client.part("#test", "Going home")`
+- Then: Reason included in PART message
+
+**Part channel not in**
+- Given: Client not in #other
+- When: `client.part("#other")`
+- Then: Receive 442 ERR_NOTONCHANNEL
+
+### Integration Tests - Events
+
+**Emit :join event on self join**
+- Given: Client with :join handler
+- When: Join #test
+- Then: Handler called with channel="#test", user=self
+
+**Emit :join event on other join**
+- Given: Client in #test with :join handler
+- When: Other user joins #test
+- Then: Handler called with channel="#test", user=other
+
+**Emit :part event on self part**
+- Given: Client in #test with :part handler
+- When: Part #test
+- Then: Handler called with channel="#test", user=self
+
+**Emit :part event on other part**
+- Given: Client in #test with :part handler
+- When: Other user parts #test
+- Then: Handler called with channel="#test", user=other, reason
+
+### Unit Tests
+
+**Format JOIN**
+- Given: channel = "#test"
+- When: Build JOIN
+- Then: Output = "JOIN #test\r\n"
+
+**Format JOIN with key**
+- Given: channel = "#test", key = "secret"
+- When: Build JOIN
+- Then: Output = "JOIN #test secret\r\n"
+
+**Format PART**
+- Given: channel = "#test"
+- When: Build PART
+- Then: Output = "PART #test\r\n"
+
+**Format PART with reason**
+- Given: channel = "#test", reason = "Bye all"
+- When: Build PART
+- Then: Output = "PART #test :Bye all\r\n"
+
+**Parse JOIN event**
+- Given: `:nick!u@h JOIN #test`
+- When: Parse
+- Then: event.channel = "#test", event.user.nick = "nick"
+
+**Parse PART event**
+- Given: `:nick!u@h PART #test :Later`
+- When: Parse
+- Then: event.channel = "#test", event.user.nick = "nick", event.reason = "Later"
+
+## Implementation Notes
+
+- Track which channels client is in via `client.channels` hash
+- Update channel user list on JOIN/PART from others
+- RPL_NAMREPLY may come in multiple messages - collect until RPL_ENDOFNAMES
+- Channel names start with # or & (check CHANTYPES from ISUPPORT)
+
+## Dependencies
+
+- Requires `01-message-parsing.md`
+- Requires `02-connection-socket.md`
+- Requires `03-registration.md`
+- Requires `05-event-system.md`

data/docs/agents/ralph/features/08-quit.md.done

@@ -0,0 +1,118 @@
+# QUIT Command
+
+## Description
+
+Implement the QUIT command for gracefully disconnecting from the server, and handle QUIT messages from other users.
+
+## Behavior
+
+### Sending QUIT
+
+```ruby
+client.quit
+client.quit("Gone for lunch")
+```
+
+Format: `QUIT [:<reason>]`
+
+After sending QUIT:
+1. Server sends ERROR message
+2. Server closes connection
+3. Client should close socket and clean up
+
+### Server Response to QUIT
+
+Server sends: `ERROR :Closing Link: nick[host] (Quit: reason)`
+
+Then closes the connection.
+
+### Other Users Quitting
+
+When another user quits: `:nick!user@host QUIT :reason`
+
+Server prepends "Quit: " to reason when distributing.
+
+Netsplits appear as: `:nick!user@host QUIT :server1 server2`
+
+### Events
+
+Emit `:quit` event with:
+- `user` - Source of the quit
+- `reason` - Quit message
+
+Emit `:disconnect` event when own connection closes.
+
+## Models
+
+No new models.
+
+## Tests
+
+### Integration Tests
+
+**Quit without reason**
+- Given: Connected client
+- When: `client.quit`
+- Then: Server receives "QUIT", connection closes
+
+**Quit with reason**
+- Given: Connected client
+- When: `client.quit("Bye!")`
+- Then: Server receives "QUIT :Bye!", connection closes
+
+**Receive other user quit**
+- Given: Client in #test with :quit handler, other user in #test
+- When: Other user quits
+- Then: Handler called with user=other, reason
+
+**Detect netsplit quit**
+- Given: Client with :quit handler
+- When: Receive QUIT with reason "*.net *.split"
+- Then: Handler receives netsplit-style reason
+
+### Unit Tests
+
+**Format QUIT**
+- Given: No reason
+- When: Build QUIT
+- Then: Output = "QUIT\r\n"
+
+**Format QUIT with reason**
+- Given: reason = "Going away"
+- When: Build QUIT
+- Then: Output = "QUIT :Going away\r\n"
+
+**Parse QUIT event**
+- Given: `:nick!u@h QUIT :Quit: Leaving`
+- When: Parse
+- Then: event.user.nick = "nick", event.reason = "Quit: Leaving"
+
+**Parse netsplit QUIT**
+- Given: `:nick!u@h QUIT :hub.net leaf.net`
+- When: Parse
+- Then: event.reason = "hub.net leaf.net"
+
+### State Tests
+
+**State after quit**
+- Given: Connected client
+- When: Quit
+- Then: State = :disconnected, channels cleared
+
+**Cleanup after quit**
+- Given: Client in multiple channels
+- When: Quit
+- Then: All channel tracking cleared
+
+## Implementation Notes
+
+- QUIT is the graceful way to disconnect
+- Wait briefly for ERROR response before closing socket
+- Remove quitting users from all tracked channels
+- Consider implementing `client.disconnect` as alias
+
+## Dependencies
+
+- Requires `01-message-parsing.md`
+- Requires `02-connection-socket.md`
+- Requires `05-event-system.md`