yaic 0.1.0 → 0.2.0

data/docs/agents/ralph/features/02-simplified-client-api.md.done

@@ -0,0 +1,306 @@
+# Simplified Client API
+
+## Description
+
+The current Client API is broken. Users must:
+- Call `client.on_socket_connected` manually (insane)
+- Access internal socket via `instance_variable_get(:@socket)`
+- Manually loop calling `socket.read`, `Message.parse`, `client.handle_message`
+- Build custom `wait_for_*` helpers for every operation
+
+The spec at `15-client-api.md.done` described the correct interface but the implementation didn't deliver. Fix it.
+
+## Target API
+
+```ruby
+client = Yaic::Client.new(
+  server: "irc.libera.chat",
+  port: 6697,
+  ssl: true,
+  nickname: "mynick"
+)
+
+client.on(:message) { |event| puts event.text }
+client.connect
+
+client.join("#ruby")
+client.privmsg("#ruby", "Hello!")
+client.part("#ruby")
+client.quit
+```
+
+That's it. All methods block until the operation completes. No bangs, no timeout params, no manual socket handling.
+
+## Behavior
+
+### All Operations Block
+
+| Method | Blocks until |
+|--------|--------------|
+| `connect` | 001 RPL_WELCOME received |
+| `join(channel)` | Channel appears in `@channels` |
+| `part(channel)` | Channel removed from `@channels` |
+| `nick(new)` | Nick change confirmed |
+| `quit` | Disconnect complete |
+
+### `connect` Method
+
+Current (broken):
+```ruby
+client.connect
+client.on_socket_connected  # User must call this!
+socket = client.instance_variable_get(:@socket)  # Insane
+# Manual loop...
+```
+
+After:
+```ruby
+client.connect  # Does everything, blocks until registered
+```
+
+Internally `connect` must:
+1. Create socket and connect (blocking with TCPSocket after feature 01)
+2. Send NICK/USER registration
+3. Start read loop (background thread)
+4. Wait for 001 RPL_WELCOME
+5. Set state to `:connected`
+6. Return
+
+### Read Loop
+
+Background thread that runs continuously:
+```ruby
+loop do
+  raw = @socket.read
+  if raw
+    message = Message.parse(raw)
+    handle_message(message) if message
+  end
+  break if @state == :disconnected
+  sleep 0.001  # Prevent busy-wait when no data
+end
+```
+
+### Internal Timeouts
+
+Timeouts are an internal concern. Use sensible defaults:
+- `connect`: 30 seconds
+- `join`/`part`/`nick`: 10 seconds
+
+Raise an error if exceeded. Users don't need to think about this.
+
+### Thread Safety
+
+- `@handlers` hash needs mutex protection for `on`/`off` during loop
+- `@state` writes should be protected
+- `@channels` needs mutex if accessed from handlers
+
+### Remove Exposed Internals
+
+- Remove `on_socket_connected` - internal use only
+- `handle_message` can stay public for testing but document as internal
+- Socket should never need to be accessed by users
+
+## Tests
+
+### Integration Tests - The Dream
+
+After this feature, integration tests should look like:
+
+```ruby
+def test_two_clients_chat
+  client1 = Yaic::Client.new(server: "localhost", port: 6667, nickname: "alice")
+  client2 = Yaic::Client.new(server: "localhost", port: 6667, nickname: "bob")
+
+  received = []
+  client2.on(:message) { |e| received << e }
+
+  client1.connect
+  client2.connect
+
+  client1.join("#test")
+  client2.join("#test")
+
+  client1.privmsg("#test", "Hello Bob!")
+  sleep 0.5  # Let message arrive
+
+  assert_equal 1, received.size
+  assert_equal "Hello Bob!", received.first.text
+ensure
+  client1&.quit
+  client2&.quit
+end
+```
+
+No more:
+- `instance_variable_get`
+- Manual read loops
+- Custom wait helpers
+- `on_socket_connected`
+
+### Unit Tests
+
+**connect blocks until registered**
+- Given: Mock socket that returns 001 after NICK/USER
+- When: `client.connect`
+- Then: Returns only after state is `:connected`
+
+**connect handles nick collision**
+- Given: Mock socket returns 433 then 001
+- When: `client.connect`
+- Then: Retries with underscore, eventually connects
+
+**events fire from background thread**
+- Given: Connected client with :message handler
+- When: Server sends PRIVMSG
+- Then: Handler called without user intervention
+
+**quit stops the read loop**
+- Given: Connected client
+- When: `client.quit`
+- Then: Background thread terminates cleanly
+
+**on/off are thread-safe**
+- Given: Read loop running
+- When: Add handler from different thread
+- Then: No race condition, handler works
+
+**join blocks until confirmed**
+- Given: Connected client
+- When: `client.join("#test")`
+- Then: Returns only after channel appears in `@channels`
+
+**part blocks until confirmed**
+- Given: Client in #test
+- When: `client.part("#test")`
+- Then: Returns only after channel removed from `@channels`
+
+**nick blocks until confirmed**
+- Given: Connected client
+- When: `client.nick("newnick")`
+- Then: Returns only after `@nick` updated
+
+### Simplify Existing Integration Tests
+
+All existing integration tests get dramatically simpler. Delete all the helper methods:
+- `wait_for_connection`
+- `wait_for_join`
+- `wait_for_part`
+
+Before:
+```ruby
+client.connect
+client.on_socket_connected
+socket = client.instance_variable_get(:@socket)
+wait_for_connection(client, socket)
+client.join(@test_channel)
+wait_for_join(client, socket, @test_channel)
+```
+
+After:
+```ruby
+client.connect
+client.join(@test_channel)
+```
+
+## Implementation Notes
+
+### Structure
+
+```ruby
+def connect
+  @socket = Socket.new(@server, @port, ssl: @ssl)
+  @socket.connect
+  send_registration
+  @state = :registering
+  start_read_loop
+  wait_until { @state == :connected }
+end
+
+def join(channel, key = nil)
+  params = key ? [channel, key] : [channel]
+  message = Message.new(command: "JOIN", params: params)
+  @socket.write(message.to_s)
+  wait_until { @channels.key?(channel) }
+end
+
+def part(channel, reason = nil)
+  params = reason ? [channel, reason] : [channel]
+  message = Message.new(command: "PART", params: params)
+  @socket.write(message.to_s)
+  wait_until { !@channels.key?(channel) }
+end
+
+def nick(new_nick)
+  message = Message.new(command: "NICK", params: [new_nick])
+  @socket.write(message.to_s)
+  wait_until { @nick == new_nick }
+end
+
+private
+
+def wait_until(timeout: 10)
+  deadline = Time.now + timeout
+  until yield
+    raise "Operation timeout" if Time.now > deadline
+    sleep 0.01
+  end
+end
+
+def start_read_loop
+  @read_thread = Thread.new do
+    loop do
+      break if @state == :disconnected
+      process_incoming
+    end
+  end
+end
+
+def process_incoming
+  raw = @socket.read
+  return sleep(0.001) unless raw
+
+  message = Message.parse(raw)
+  handle_message(message) if message
+rescue => e
+  emit(:error, nil, exception: e)
+end
+```
+
+### Cleanup on Quit
+
+```ruby
+def quit(reason = nil)
+  params = reason ? [reason] : []
+  message = Message.new(command: "QUIT", params: params)
+  @socket.write(message.to_s)
+  @channels.clear
+  @state = :disconnected
+  @read_thread&.join(5)
+  @socket&.disconnect
+  emit(:disconnect, nil)
+end
+```
+
+### Graceful Error Handling
+
+If socket dies unexpectedly:
+- Set state to `:disconnected`
+- Emit `:disconnect` event with error info
+- Stop read loop
+
+## Documentation
+
+Create `README.md` with:
+
+1. **Installation** - gem install / Gemfile
+2. **Quick Start** - 10-line example that works
+3. **Events** - List all events with their attributes
+4. **Commands** - All IRC commands with examples
+5. **Threading** - Brief note that a background thread handles reads
+
+Keep it concise. The API should be obvious from the examples.
+
+## Dependencies
+
+- Requires `01-tcpsocket-refactor.md` (blocking connect simplifies this)

data/docs/agents/ralph/features/03-registration.md.done

@@ -0,0 +1,147 @@
+# Connection Registration
+
+## Description
+
+Implement the IRC connection registration sequence. After connecting, the client must send NICK and USER commands (optionally PASS) and wait for the server to acknowledge registration.
+
+## Behavior
+
+### Registration Sequence
+
+1. If password provided, send: `PASS <password>`
+2. Send: `NICK <nickname>`
+3. Send: `USER <username> 0 * :<realname>`
+4. Wait for numeric 001 (RPL_WELCOME) to confirm registration
+5. Transition state to `:connected`
+
+### PASS Command
+
+- Format: `PASS <password>`
+- Must be sent before NICK/USER
+- Only last PASS is used if sent multiple times
+
+### NICK Command
+
+- Format: `NICK <nickname>`
+- Can be sent during or after registration
+- Server may reject with:
+  - 431 ERR_NONICKNAMEGIVEN
+  - 432 ERR_ERRONEUSNICKNAME
+  - 433 ERR_NICKNAMEINUSE
+
+### USER Command
+
+- Format: `USER <username> 0 * :<realname>`
+- The `0` and `*` are required (historical reasons)
+- realname can contain spaces
+
+### Handling Nick Collisions
+
+If ERR_NICKNAMEINUSE (433) received during registration:
+- Try alternative nick (append underscore or number)
+- Emit event so user code can provide alternative
+
+### Welcome Numerics
+
+After successful registration, server sends:
+- 001 RPL_WELCOME - Registration complete
+- 002 RPL_YOURHOST - Server info
+- 003 RPL_CREATED - Server creation time
+- 004 RPL_MYINFO - Server name and supported modes
+- 005 RPL_ISUPPORT - Server capabilities (multiple lines)
+
+## Models
+
+```ruby
+Yaic::Registration
+  - nickname: String
+  - username: String
+  - realname: String
+  - password: String or nil
+  - state: :pending, :nick_sent, :user_sent, :complete
+```
+
+## Tests
+
+### Integration Tests - Successful Registration
+
+**Register with nickname and user**
+- Given: Connected to inspircd
+- When: Send NICK and USER
+- Then: Receive 001 RPL_WELCOME, state becomes :connected
+
+**Register with password**
+- Given: Connected to inspircd (configured with password)
+- When: Send PASS, NICK, USER
+- Then: Receive 001 RPL_WELCOME
+
+### Integration Tests - Nick Handling
+
+**Nick already in use**
+- Given: Connected to inspircd, nick "taken" already connected
+- When: Send NICK taken
+- Then: Receive 433 ERR_NICKNAMEINUSE
+
+**Invalid nickname**
+- Given: Connected to inspircd
+- When: Send NICK "#invalid"
+- Then: Receive 432 ERR_ERRONEUSNICKNAME
+
+**Empty nickname**
+- Given: Connected to inspircd
+- When: Send NICK with no parameter
+- Then: Receive 431 ERR_NONICKNAMEGIVEN
+
+### Unit Tests - Message Formatting
+
+**Format PASS command**
+- Given: password = "secret"
+- When: Build PASS message
+- Then: Output = "PASS secret\r\n"
+
+**Format NICK command**
+- Given: nickname = "mynick"
+- When: Build NICK message
+- Then: Output = "NICK mynick\r\n"
+
+**Format USER command**
+- Given: username = "myuser", realname = "My Real Name"
+- When: Build USER message
+- Then: Output = "USER myuser 0 * :My Real Name\r\n"
+
+**Format USER with empty realname**
+- Given: username = "myuser", realname = ""
+- When: Build USER message
+- Then: Output = "USER myuser 0 * :\r\n"
+
+### State Machine Tests
+
+**State transitions**
+- Given: State = :disconnected
+- When: Connect initiated
+- Then: State = :connecting
+
+- Given: State = :connecting
+- When: Socket connected
+- Then: State = :registering, NICK/USER sent
+
+- Given: State = :registering
+- When: 001 received
+- Then: State = :connected
+
+**State on nick collision**
+- Given: State = :registering
+- When: 433 received
+- Then: State remains :registering, retry with alternate nick
+
+## Implementation Notes
+
+- Parse RPL_ISUPPORT (005) to learn server capabilities
+- Store ISUPPORT values for later use (CHANTYPES, CHANMODES, etc.)
+- Username may be prefixed with ~ if no ident server
+- Some servers require PING response during registration
+
+## Dependencies
+
+- Requires `01-message-parsing.md`
+- Requires `02-connection-socket.md`

data/docs/agents/ralph/features/04-ping-pong.md.done

@@ -0,0 +1,109 @@
+# PING/PONG Keepalive
+
+## Description
+
+Implement PING/PONG handling to maintain connection with the server. This is critical - servers will disconnect clients that don't respond to PING.
+
+## Behavior
+
+### Responding to PING
+
+When server sends `PING <token>`:
+1. Immediately respond with `PONG <token>`
+2. Token must be identical to what server sent
+3. Can occur at any time, including during registration
+
+### Server PING Format
+
+```
+PING <token>
+PING :<token>
+```
+
+The token may be with or without the trailing `:` prefix.
+
+### Client PONG Response
+
+```
+PONG <token>
+PONG :<token>
+```
+
+Mirror the token exactly. Do NOT include a server parameter.
+
+### Connection Timeout Detection
+
+If no data received from server for extended period (e.g., 180+ seconds):
+- Connection may be dead
+- Client should consider reconnecting
+
+### Latency Measurement (Optional)
+
+- Client may send `PING <token>` to server
+- Server responds with `PONG <token>`
+- Measure round-trip time
+
+## Models
+
+No new models required. Handled in message dispatch.
+
+## Tests
+
+### Integration Tests
+
+**Respond to PING during registration**
+- Given: Connected, registration in progress
+- When: Server sends PING
+- Then: Client responds with PONG, registration continues
+
+**Respond to PING when connected**
+- Given: Fully connected
+- When: Server sends "PING :irc.example.com"
+- Then: Client sends "PONG :irc.example.com"
+
+**Handle PING without colon**
+- Given: Fully connected
+- When: Server sends "PING token123"
+- Then: Client sends "PONG token123"
+
+**Maintain connection over time**
+- Given: Connected to inspircd
+- When: Wait for server to send PING (typically 2-5 minutes)
+- Then: Client responds, connection stays alive
+
+### Unit Tests
+
+**Parse PING message**
+- Given: "PING :test.server.com\r\n"
+- When: Parse message
+- Then: command = "PING", params = ["test.server.com"]
+
+**Build PONG response**
+- Given: PING with token "abc123"
+- When: Build PONG
+- Then: Output = "PONG abc123\r\n"
+
+**Build PONG with spaces in token**
+- Given: PING with token "some server"
+- When: Build PONG
+- Then: Output = "PONG :some server\r\n"
+
+### Timeout Tests
+
+**Detect no data timeout**
+- Given: Connected, no data received for 180 seconds
+- When: Check connection health
+- Then: Report connection as potentially dead
+
+## Implementation Notes
+
+- PING handling should be automatic, not requiring user code
+- Process PING before other message handling to ensure quick response
+- Log PING/PONG for debugging but don't emit as regular events
+- Consider emitting a `:ping` event for latency tracking
+
+## Dependencies
+
+- Requires `01-message-parsing.md`
+- Requires `02-connection-socket.md`
+- Requires `03-registration.md` (PING can occur during registration)