yaic 0.1.0 → 0.2.0

data/docs/agents/ralph/features/09-nick-change.md.done

@@ -0,0 +1,109 @@
+# NICK Change
+
+## Description
+
+Implement changing nickname after registration and tracking nickname changes from other users.
+
+## Behavior
+
+### Changing Own Nick
+
+```ruby
+client.nick("newnick")
+```
+
+Format: `NICK <nickname>`
+
+### Server Response
+
+On success: `:oldnick!user@host NICK newnick`
+
+Update internal state to track new nickname.
+
+### Nick Change Errors
+
+- 431 ERR_NONICKNAMEGIVEN - No nick provided
+- 432 ERR_ERRONEUSNICKNAME - Invalid characters
+- 433 ERR_NICKNAMEINUSE - Nick taken
+- 436 ERR_NICKCOLLISION - Collision (rare)
+
+### Other Users Changing Nick
+
+When another user changes nick: `:oldnick!user@host NICK newnick`
+
+Update user tracking in all shared channels.
+
+### Events
+
+Emit `:nick` event with:
+- `old_nick` - Previous nickname
+- `new_nick` - New nickname
+- `user` - Source (optional, has old nick info)
+
+## Models
+
+```ruby
+client.nick  # => current nickname (String)
+```
+
+## Tests
+
+### Integration Tests
+
+**Change own nick**
+- Given: Connected as "oldnick"
+- When: `client.nick("newnick")`
+- Then: Receive NICK confirmation, client.nick = "newnick"
+
+**Nick in use**
+- Given: Connected, "taken" nick exists
+- When: `client.nick("taken")`
+- Then: Receive 433 ERR_NICKNAMEINUSE
+
+**Invalid nick**
+- Given: Connected
+- When: `client.nick("#invalid")`
+- Then: Receive 432 ERR_ERRONEUSNICKNAME
+
+**Other user changes nick**
+- Given: Client in #test with "bob", :nick handler
+- When: Bob changes nick to "robert"
+- Then: Handler called with old_nick="bob", new_nick="robert"
+
+### Unit Tests
+
+**Format NICK**
+- Given: nickname = "newnick"
+- When: Build NICK
+- Then: Output = "NICK newnick\r\n"
+
+**Parse NICK event**
+- Given: `:old!u@h NICK new`
+- When: Parse
+- Then: event.old_nick = "old", event.new_nick = "new"
+
+**Track own nick change**
+- Given: client.nick = "old"
+- When: Receive `:old!u@h NICK new` from self
+- Then: client.nick = "new"
+
+### Channel User Tracking
+
+**Update user in channels**
+- Given: Client tracks "bob" in #test
+- When: Bob changes nick to "robert"
+- Then: #test user list shows "robert" not "bob"
+
+## Implementation Notes
+
+- Store current nick in client.nick
+- On NICK event, check if source matches own nick to update self
+- Update all channel user lists when any nick changes
+- Nick comparison should be case-insensitive per server CASEMAPPING
+
+## 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/10-topic.md.done

@@ -0,0 +1,145 @@
+# Channel TOPIC
+
+## Description
+
+Implement getting and setting channel topics.
+
+## Behavior
+
+### Getting Topic
+
+```ruby
+client.topic("#ruby")  # Request current topic
+```
+
+Format: `TOPIC <channel>`
+
+Server responds with:
+- 332 RPL_TOPIC - The topic text
+- 333 RPL_TOPICWHOTIME - Who set it and when
+- 331 RPL_NOTOPIC - No topic set
+
+### Setting Topic
+
+```ruby
+client.topic("#ruby", "Welcome to #ruby!")
+client.topic("#ruby", "")  # Clear topic
+```
+
+Format: `TOPIC <channel> :<topic>`
+
+### Topic Change Notification
+
+When topic changes: `:nick!user@host TOPIC #channel :New topic`
+
+### Topic Errors
+
+- 442 ERR_NOTONCHANNEL - Not in channel (when getting)
+- 482 ERR_CHANOPRIVSNEEDED - Not op (when setting protected topic)
+
+### Events
+
+Emit `:topic` event with:
+- `channel` - Channel name
+- `topic` - Topic text (may be nil if cleared)
+- `setter` - Who set it (nick)
+- `time` - When it was set (Time, optional)
+
+## Models
+
+```ruby
+channel.topic        # => String or nil
+channel.topic_setter # => String
+channel.topic_time   # => Time
+```
+
+## Tests
+
+### Integration Tests
+
+**Get topic**
+- Given: Client in #test which has topic
+- When: `client.topic("#test")`
+- Then: Receive RPL_TOPIC with topic text
+
+**Get topic when none set**
+- Given: Client in #test with no topic
+- When: `client.topic("#test")`
+- Then: Receive RPL_NOTOPIC
+
+**Set topic**
+- Given: Client is op in #test
+- When: `client.topic("#test", "New topic")`
+- Then: Receive TOPIC confirmation, topic changed
+
+**Clear topic**
+- Given: Client is op in #test with topic
+- When: `client.topic("#test", "")`
+- Then: Topic cleared
+
+**Set topic without permission**
+- Given: Client in #test (not op), channel has +t mode
+- When: `client.topic("#test", "New topic")`
+- Then: Receive 482 ERR_CHANOPRIVSNEEDED
+
+**Receive topic change**
+- Given: Client in #test with :topic handler
+- When: Op changes topic
+- Then: Handler called with channel, new topic, setter
+
+### Unit Tests
+
+**Format TOPIC get**
+- Given: channel = "#test"
+- When: Build TOPIC (no text)
+- Then: Output = "TOPIC #test\r\n"
+
+**Format TOPIC set**
+- Given: channel = "#test", topic = "Hello"
+- When: Build TOPIC
+- Then: Output = "TOPIC #test :Hello\r\n"
+
+**Format TOPIC clear**
+- Given: channel = "#test", topic = ""
+- When: Build TOPIC
+- Then: Output = "TOPIC #test :\r\n"
+
+**Parse TOPIC event**
+- Given: `:nick!u@h TOPIC #test :New topic`
+- When: Parse
+- Then: event.channel = "#test", event.topic = "New topic", event.setter = "nick"
+
+**Parse RPL_TOPIC**
+- Given: `:server 332 mynick #test :The topic`
+- When: Parse
+- Then: channel = "#test", topic = "The topic"
+
+**Parse RPL_TOPICWHOTIME**
+- Given: `:server 333 mynick #test setter 1234567890`
+- When: Parse
+- Then: setter = "setter", time = Time.at(1234567890)
+
+### State Tracking
+
+**Update channel topic on change**
+- Given: Client tracking #test
+- When: TOPIC message received
+- Then: channel.topic updated
+
+**Topic from JOIN**
+- Given: Client joins #test with topic
+- When: JOIN completes
+- Then: channel.topic populated from RPL_TOPIC
+
+## Implementation Notes
+
+- Topic can be received at JOIN time (RPL_TOPIC) or via TOPIC command/event
+- RPL_TOPICWHOTIME time is Unix timestamp
+- Some channels have +t (topic protected) - only ops can change
+- Empty string topic clears it
+
+## Dependencies
+
+- Requires `01-message-parsing.md`
+- Requires `05-event-system.md`
+- Requires `07-join-part.md` (topic received at join)

data/docs/agents/ralph/features/11-kick.md.done

@@ -0,0 +1,122 @@
+# Channel KICK
+
+## Description
+
+Implement kicking users from channels and handling being kicked.
+
+## Behavior
+
+### Sending KICK
+
+```ruby
+client.kick("#ruby", "baduser")
+client.kick("#ruby", "baduser", "No spamming")
+```
+
+Format: `KICK <channel> <nick> [:<reason>]`
+
+Requires channel operator privileges.
+
+### Server Response
+
+Server confirms: `:kicker!user@host KICK #channel kicked :reason`
+
+### Being Kicked
+
+When client is kicked:
+1. Receive KICK message
+2. Remove channel from tracking
+3. Emit :kick event
+
+### Kick Errors
+
+- 441 ERR_USERNOTINCHANNEL - Target not in channel
+- 442 ERR_NOTONCHANNEL - Kicker not in channel
+- 482 ERR_CHANOPRIVSNEEDED - Kicker not op
+
+### Events
+
+Emit `:kick` event with:
+- `channel` - Channel name
+- `user` - Who was kicked (nick)
+- `by` - Who kicked (Source)
+- `reason` - Kick reason
+
+## Models
+
+No new models.
+
+## Tests
+
+### Integration Tests
+
+**Kick user**
+- Given: Client is op in #test, "target" is in #test
+- When: `client.kick("#test", "target")`
+- Then: Target removed from channel
+
+**Kick with reason**
+- Given: Client is op in #test
+- When: `client.kick("#test", "target", "Breaking rules")`
+- Then: Reason included in KICK
+
+**Kick without permission**
+- Given: Client in #test (not op)
+- When: `client.kick("#test", "target")`
+- Then: Receive 482 ERR_CHANOPRIVSNEEDED
+
+**Kick non-existent user**
+- Given: Client is op in #test
+- When: `client.kick("#test", "nobody")`
+- Then: Receive 441 ERR_USERNOTINCHANNEL
+
+**Receive kick (others)**
+- Given: Client in #test with :kick handler
+- When: Op kicks "baduser"
+- Then: Handler called with channel, user="baduser", by=op
+
+**Receive kick (self)**
+- Given: Client in #test
+- When: Op kicks client
+- Then: :kick event emitted, #test removed from channels
+
+### Unit Tests
+
+**Format KICK**
+- Given: channel = "#test", nick = "target"
+- When: Build KICK
+- Then: Output = "KICK #test target\r\n"
+
+**Format KICK with reason**
+- Given: channel = "#test", nick = "target", reason = "Bye"
+- When: Build KICK
+- Then: Output = "KICK #test target :Bye\r\n"
+
+**Parse KICK event**
+- Given: `:op!u@h KICK #test target :reason`
+- When: Parse
+- Then: event.channel = "#test", event.user = "target", event.by.nick = "op", event.reason = "reason"
+
+### State Updates
+
+**Remove kicked user from channel**
+- Given: Client tracking "target" in #test
+- When: KICK for "target"
+- Then: "target" removed from #test user list
+
+**Remove channel when self kicked**
+- Given: Client in #test
+- When: Kicked from #test
+- Then: #test removed from client.channels
+
+## Implementation Notes
+
+- Kick requires op status (@) in channel
+- Server may have kick reason length limits
+- After being kicked, must rejoin if allowed
+
+## Dependencies
+
+- Requires `01-message-parsing.md`
+- Requires `05-event-system.md`
+- Requires `07-join-part.md` (channel tracking)

data/docs/agents/ralph/features/12-names.md.done

@@ -0,0 +1,124 @@
+# Channel NAMES
+
+## Description
+
+Implement querying channel user lists. NAMES returns all users in a channel with their mode prefixes.
+
+## Behavior
+
+### Requesting NAMES
+
+```ruby
+client.names("#ruby")
+```
+
+Format: `NAMES <channel>`
+
+### Server Response
+
+- 353 RPL_NAMREPLY - User list (may be multiple)
+- 366 RPL_ENDOFNAMES - End of list
+
+RPL_NAMREPLY format: `:server 353 mynick = #channel :@op +voice regular`
+
+User prefixes:
+- `@` - Operator
+- `+` - Voice
+- `%` - Half-op (some servers)
+- `~` - Owner (some servers)
+- `&` - Admin (some servers)
+
+### Events
+
+Emit `:names` event with:
+- `channel` - Channel name
+- `users` - Array of {nick:, modes:} or similar
+
+Or update channel.users and emit general update event.
+
+## Models
+
+```ruby
+channel.users  # => Hash[String, Set[Symbol]]
+               # e.g., {"dan" => Set[:op], "bob" => Set[:voice]}
+```
+
+## Tests
+
+### Integration Tests
+
+**Get names**
+- Given: Client in #test with users
+- When: `client.names("#test")`
+- Then: Receive RPL_NAMREPLY with user list
+
+**Names with prefixes**
+- Given: #test has @op and +voice users
+- When: `client.names("#test")`
+- Then: Response shows prefixes
+
+**Names at join**
+- Given: Client joins #test
+- When: JOIN completes
+- Then: channel.users populated from NAMREPLY
+
+**Multi-message names**
+- Given: Channel with many users
+- When: Request NAMES
+- Then: Multiple RPL_NAMREPLY collected until RPL_ENDOFNAMES
+
+### Unit Tests
+
+**Parse RPL_NAMREPLY**
+- Given: `:server 353 me = #test :@op +voice regular`
+- When: Parse
+- Then: Extract users with modes: op=>[:op], voice=>[:voice], regular=>[]
+
+**Parse prefix @ (op)**
+- Given: User string "@dan"
+- When: Parse user
+- Then: nick = "dan", modes = [:op]
+
+**Parse prefix + (voice)**
+- Given: User string "+bob"
+- When: Parse user
+- Then: nick = "bob", modes = [:voice]
+
+**Parse multiple prefixes**
+- Given: User string "@+admin"
+- When: Parse user
+- Then: nick = "admin", modes = [:op, :voice]
+
+**Parse no prefix**
+- Given: User string "regular"
+- When: Parse user
+- Then: nick = "regular", modes = []
+
+**Collect until ENDOFNAMES**
+- Given: Multiple RPL_NAMREPLY then RPL_ENDOFNAMES
+- When: Process all
+- Then: All users aggregated before emitting event
+
+### State Updates
+
+**Populate users on join**
+- Given: Client joins #test
+- When: NAMREPLY received
+- Then: channel.users contains all listed users
+
+**Update user modes**
+- Given: Client tracking #test
+- When: New NAMES requested and received
+- Then: channel.users updated
+
+## Implementation Notes
+
+- NAMREPLY at JOIN is same as explicit NAMES command
+- May receive multiple NAMREPLY messages - collect all before processing
+- PREFIX in ISUPPORT defines which prefixes map to which modes
+- Default: @ = op, + = voice
+
+## Dependencies
+
+- Requires `01-message-parsing.md`
+- Requires `07-join-part.md` (NAMES comes with JOIN)

data/docs/agents/ralph/features/13-mode.md.done

@@ -0,0 +1,174 @@
+# MODE Command
+
+## Description
+
+Implement user and channel mode queries and changes. This covers both viewing and setting modes.
+
+## Behavior
+
+### User Modes
+
+Query own modes:
+```ruby
+client.mode(client.nick)  # Get current modes
+```
+
+Set own modes:
+```ruby
+client.mode(client.nick, "+i")  # Set invisible
+client.mode(client.nick, "-i")  # Unset invisible
+```
+
+Common user modes:
+- `+i` - Invisible (hide from WHO unless sharing channel)
+- `+w` - Receive wallops
+- `+o` - Operator (set via OPER, not MODE)
+
+### Channel Modes
+
+Query channel modes:
+```ruby
+client.mode("#ruby")  # Get channel modes
+```
+
+Set channel modes (requires op):
+```ruby
+client.mode("#ruby", "+m")           # Set moderated
+client.mode("#ruby", "+o", "nick")   # Give op to nick
+client.mode("#ruby", "+k", "secret") # Set channel key
+client.mode("#ruby", "-k")           # Remove key
+```
+
+Common channel modes:
+- `+o nick` - Channel operator
+- `+v nick` - Voice
+- `+m` - Moderated (only +v/+o can speak)
+- `+i` - Invite only
+- `+k key` - Require key to join
+- `+l limit` - User limit
+- `+b mask` - Ban mask
+- `+t` - Only ops can change topic
+
+### Server Response
+
+Mode query: `324 RPL_CHANNELMODEIS :server 324 mynick #chan +nt`
+
+Mode change: `:nick!u@h MODE #chan +o target`
+
+### Mode Errors
+
+- 472 ERR_UNKNOWNMODE - Unknown mode character
+- 482 ERR_CHANOPRIVSNEEDED - Need op to change channel mode
+- 501 ERR_UMODEUNKNOWNFLAG - Unknown user mode
+
+### Events
+
+Emit `:mode` event with:
+- `target` - Channel or nick
+- `modes` - Mode string (e.g., "+o-v")
+- `params` - Mode parameters array
+
+## Models
+
+```ruby
+channel.modes  # => Hash[Symbol, Object]
+               # e.g., {moderated: true, key: "secret", limit: 50}
+```
+
+## Tests
+
+### Integration Tests - User Modes
+
+**Get own modes**
+- Given: Connected client
+- When: `client.mode(client.nick)`
+- Then: Receive 221 RPL_UMODEIS
+
+**Set invisible**
+- Given: Connected client
+- When: `client.mode(client.nick, "+i")`
+- Then: Mode confirmed, hidden from WHO
+
+**Cannot set other user's modes**
+- Given: Connected client
+- When: `client.mode("other", "+i")`
+- Then: Receive 502 ERR_USERSDONTMATCH
+
+### Integration Tests - Channel Modes
+
+**Get channel modes**
+- Given: Client in #test
+- When: `client.mode("#test")`
+- Then: Receive 324 RPL_CHANNELMODEIS
+
+**Set channel mode as op**
+- Given: Client is op in #test
+- When: `client.mode("#test", "+m")`
+- Then: Mode confirmed
+
+**Give op to user**
+- Given: Client is op in #test, "target" in channel
+- When: `client.mode("#test", "+o", "target")`
+- Then: Target becomes op
+
+**Set key**
+- Given: Client is op in #test
+- When: `client.mode("#test", "+k", "secret")`
+- Then: Channel now requires key
+
+**Mode without permission**
+- Given: Client in #test (not op)
+- When: `client.mode("#test", "+m")`
+- Then: Receive 482 ERR_CHANOPRIVSNEEDED
+
+### Unit Tests
+
+**Format MODE query**
+- Given: target = "#test"
+- When: Build MODE (no modes)
+- Then: Output = "MODE #test\r\n"
+
+**Format MODE set**
+- Given: target = "#test", modes = "+m"
+- When: Build MODE
+- Then: Output = "MODE #test +m\r\n"
+
+**Format MODE with params**
+- Given: target = "#test", modes = "+o", params = ["nick"]
+- When: Build MODE
+- Then: Output = "MODE #test +o nick\r\n"
+
+**Parse MODE event**
+- Given: `:op!u@h MODE #test +o target`
+- When: Parse
+- Then: target = "#test", modes = "+o", params = ["target"]
+
+**Parse multi-mode**
+- Given: `:op!u@h MODE #test +ov target1 target2`
+- When: Parse
+- Then: modes = "+ov", params = ["target1", "target2"]
+
+### State Updates
+
+**Track channel modes**
+- Given: Client in #test
+- When: MODE +m received
+- Then: channel.modes[:moderated] = true
+
+**Track user op status**
+- Given: Client tracking "nick" in #test
+- When: MODE +o nick received
+- Then: "nick" has :op in user modes
+
+## Implementation Notes
+
+- Parse CHANMODES from ISUPPORT for parameter requirements
+- Mode types: A (list), B (always param), C (param on set), D (no param)
+- Multiple modes can be set at once: +ov nick1 nick2
+- Track modes received both at join and via MODE messages
+
+## Dependencies
+
+- Requires `01-message-parsing.md`
+- Requires `05-event-system.md`
+- Requires `07-join-part.md` (channel tracking)