yaic 0.1.0 → 0.2.0

data/docs/agents/ralph/features/21-test-parallelization.md.done

@@ -0,0 +1,56 @@
+# Test Parallelization
+
+## Description
+
+Enable minitest's built-in parallel test execution to run tests concurrently, reducing total test time by utilizing multiple CPU cores.
+
+## Behavior
+
+### Enable Parallel Execution
+
+Add `parallelize_me!` to test classes or enable globally in test_helper.rb.
+
+### Fix Unique Identifiers for Thread Safety
+
+Tests currently use `Process.pid` for unique nicks/channels, but with thread-based parallelism all threads share the same PID. Update identifier generation to include thread ID:
+
+```ruby
+# Before
+@test_nick = "t#{Process.pid}#{Time.now.to_i % 10000}"
+
+# After
+@test_nick = "t#{Process.pid}_#{Thread.current.object_id % 10000}_#{rand(10000)}"
+```
+
+### Verify Test Isolation
+
+Ensure tests don't share state:
+- Each test creates its own IRC client connections
+- Each test uses unique channel names
+- No global variables or class variables modified during tests
+
+## Tests
+
+Run the full test suite and verify:
+- All 267 tests pass
+- All 575 assertions pass
+- No new skips introduced
+- Test time is reduced (target: 3-4x speedup)
+
+## Implementation Notes
+
+- Use `bundle exec rake test` to run tests
+- Use `bundle exec standardrb -A` for linting
+- The IRC server can handle multiple concurrent connections
+
+Minitest parallel options:
+1. `parallelize_me!` in individual test classes
+2. Global enable in test_helper.rb via `Minitest::Test.parallelize_me!`
+
+## Dependencies
+
+- 20-test-optimization.md (planning complete)
+
+## Reference
+
+See `docs/agents/ralph/plans/test-optimization-plan.md` for full analysis.

data/docs/agents/ralph/features/22-wait-until-pattern.md.done

@@ -0,0 +1,90 @@
+# Wait Until Pattern
+
+## Description
+
+Replace `sleep 0.5`, `read_multiple`, `read_until_pong`, and similar patterns with a consistent `wait_until` helper that returns as soon as a condition is met.
+
+## Behavior
+
+### Create wait_until Helper
+
+Add a `wait_until` helper to test_helper.rb:
+
+```ruby
+def wait_until(timeout: 2)
+  deadline = Time.now + timeout
+  until Time.now > deadline
+    result = yield
+    return result if result
+    sleep 0.01
+  end
+  nil
+end
+```
+
+### Replace sleep Statements
+
+Replace `sleep 0.5` with `wait_until { condition }`:
+
+```ruby
+# Before
+client1.kick(@test_channel, @test_nick2)
+sleep 0.5
+assert kick_received
+
+# After
+client1.kick(@test_channel, @test_nick2)
+wait_until { kick_received }
+assert kick_received
+```
+
+### Replace read_multiple Pattern
+
+Replace `read_multiple(socket, 5)` with inline `wait_until`:
+
+```ruby
+# Before
+messages = read_multiple(socket, 5)
+erroneous = messages.find { |m| m.command == "432" }
+
+# After
+erroneous = nil
+wait_until(timeout: 2) do
+  raw = socket.read
+  if raw
+    msg = Yaic::Message.parse(raw)
+    erroneous = msg if msg&.command == "432"
+  end
+  erroneous
+end
+```
+
+### Remove Old Helpers
+
+Remove these helpers from test files:
+- `read_multiple`
+- `read_until_pong`
+- `read_until_welcome`
+- `read_with_timeout`
+
+## Tests
+
+Run the full test suite and verify:
+- All tests pass
+- No assertions removed or weakened
+- Test time is reduced
+
+## Implementation Notes
+
+- Use `bundle exec rake test` to run tests
+- Use `bundle exec standardrb -A` for linting
+- Focus on integration tests first (they have the most sleeps)
+
+## Dependencies
+
+- 20-test-optimization.md (planning complete)
+- 21-test-parallelization.md (optional, can be done in parallel)
+
+## Reference
+
+See `docs/agents/ralph/plans/test-optimization-plan.md` for full analysis.

data/docs/agents/ralph/features/23-ping-test-optimization.md.done

@@ -0,0 +1,46 @@
+# Ping Test Optimization
+
+## Description
+
+Optimize the `test_client_automatically_responds_to_server_ping` test which currently takes 7 seconds due to a `sleep 6` waiting for the server's PING.
+
+## Behavior
+
+### Reduce Server Ping Frequency
+
+Update the InspIRCd test config (`test/fixtures/inspircd.conf`) to reduce ping frequency from 5 seconds to 3 seconds.
+
+### Use wait_until Instead of Fixed Sleep
+
+Replace the `sleep 6` with a `wait_until` that detects when a PING/PONG cycle has occurred:
+
+```ruby
+# Before
+sleep 6
+assert client.last_received_at > initial_last_received
+
+# After
+wait_until(timeout: 5) { client.last_received_at > initial_last_received }
+assert client.last_received_at > initial_last_received
+```
+
+## Tests
+
+Run the ping pong integration tests and verify:
+- All tests pass
+- `test_client_automatically_responds_to_server_ping` completes in ~3-4 seconds instead of 7
+
+## Implementation Notes
+
+- Use `bundle exec m test/integration/ping_pong_test.rb` to run just ping tests
+- Use `bundle exec standardrb -A` for linting
+- After changing server config, restart the IRC server: `bin/stop-irc-server && bin/start-irc-server`
+
+## Dependencies
+
+- 20-test-optimization.md (planning complete)
+- 22-wait-until-pattern.md (wait_until helper must exist)
+
+## Reference
+
+See `docs/agents/ralph/plans/test-optimization-plan.md` for full analysis.

data/docs/agents/ralph/features/24-blocking-who-whois.md.done

@@ -0,0 +1,159 @@
+# Blocking WHO/WHOIS
+
+## Description
+
+Convert `who` and `whois` methods from fire-and-forget to blocking calls that return results directly. This follows the same pattern already used by `join`, `part`, and `nick` methods.
+
+## Behavior
+
+### WHO Command
+
+`who(mask, timeout: DEFAULT_OPERATION_TIMEOUT)` sends WHO command and blocks until END OF WHO (315) is received.
+
+- Returns an array of `WhoResult` objects (one per user matching the mask)
+- Returns empty array if no matches
+- Raises `Yaic::TimeoutError` if timeout exceeded
+- Events (`:who`) still fire for each reply (maintains backward compatibility)
+
+### WHOIS Command
+
+`whois(nick, timeout: DEFAULT_OPERATION_TIMEOUT)` sends WHOIS command and blocks until END OF WHOIS (318) is received.
+
+- Returns `WhoisResult` object if user found
+- Returns `nil` if user not found (401 ERR_NOSUCHNICK)
+- Raises `Yaic::TimeoutError` if timeout exceeded
+- Event (`:whois`) still fires (maintains backward compatibility)
+
+### WhoResult Class
+
+Create `lib/yaic/who_result.rb` with attributes matching the `:who` event data:
+
+- `channel` - channel name (or "*" for non-channel queries)
+- `user` - username
+- `host` - hostname
+- `server` - server name
+- `nick` - nickname
+- `away` - boolean, true if user is away
+- `realname` - real name
+
+## Models
+
+New file: `lib/yaic/who_result.rb`
+
+```ruby
+module Yaic
+  class WhoResult
+    attr_reader :channel, :user, :host, :server, :nick, :away, :realname
+
+    def initialize(channel:, user:, host:, server:, nick:, away:, realname:)
+      # ...
+    end
+  end
+end
+```
+
+## Implementation Notes
+
+### Tracking Pending Operations
+
+Use instance variables to track pending blocking operations:
+
+- `@pending_who_results` - Hash of mask => array of WhoResult objects being collected
+- `@pending_who_complete` - Hash of mask => boolean (true when 315 received)
+
+The existing `@pending_whois` already tracks WHOIS, just need to add completion tracking.
+
+### Handle Interleaving
+
+Multiple WHO/WHOIS requests could be in flight. Track by mask/nick to handle interleaving correctly. The existing WHOIS implementation already handles this.
+
+### Modify Handlers
+
+- `handle_rpl_whoreply` (352): Create WhoResult, add to pending array
+- `handle_rpl_endofwho` (315): Mark pending WHO complete
+- `handle_rpl_endofwhois` (318): Already handled, add completion flag
+
+### Waiting Pattern
+
+Follow the existing pattern from `join`:
+
+```ruby
+def who(mask, timeout: DEFAULT_OPERATION_TIMEOUT)
+  @pending_who_results[mask] = []
+  @pending_who_complete[mask] = false
+
+  message = Message.new(command: "WHO", params: [mask])
+  @socket.write(message.to_s)
+
+  wait_until(timeout: timeout) { @pending_who_complete[mask] }
+
+  @pending_who_results.delete(mask)
+ensure
+  @pending_who_complete.delete(mask)
+end
+```
+
+## Tests
+
+### Unit Tests
+
+**who returns array of WhoResult objects**
+- Given: Mock socket returns 352 replies followed by 315
+- When: `client.who("#channel")`
+- Then: Returns array of WhoResult with correct attributes
+
+**who returns empty array when no matches**
+- Given: Mock socket returns only 315 (no 352 replies)
+- When: `client.who("nobody")`
+- Then: Returns empty array
+
+**who raises TimeoutError on timeout**
+- Given: Mock socket never returns 315
+- When: `client.who("#channel", timeout: 0.1)`
+- Then: Raises Yaic::TimeoutError
+
+**who still emits :who events**
+- Given: Mock socket returns 352 replies
+- When: `client.who("#channel")` with event listener attached
+- Then: Events fire AND method returns results
+
+**whois returns WhoisResult**
+- Given: Mock socket returns WHOIS numerics followed by 318
+- When: `client.whois("nick")`
+- Then: Returns WhoisResult with correct attributes
+
+**whois returns nil for unknown nick**
+- Given: Mock socket returns 401 ERR_NOSUCHNICK then 318
+- When: `client.whois("nobody")`
+- Then: Returns nil
+
+**whois raises TimeoutError on timeout**
+- Given: Mock socket never returns 318
+- When: `client.whois("nick", timeout: 0.1)`
+- Then: Raises Yaic::TimeoutError
+
+### Integration Tests
+
+**who channel returns all users**
+- Given: Two clients connected to same channel
+- When: `client1.who("#channel")`
+- Then: Returns array with both users' info
+
+**who nick returns single user**
+- Given: Two clients connected
+- When: `client1.who(client2_nick)`
+- Then: Returns array with one WhoResult for client2
+
+**whois returns user info**
+- Given: Two clients connected
+- When: `client1.whois(client2_nick)`
+- Then: Returns WhoisResult with nick, user, host, realname
+
+**whois unknown returns nil**
+- Given: Client connected
+- When: `client.whois("nobody_exists")`
+- Then: Returns nil (not raises)
+
+## Dependencies
+
+None - builds on existing WHO/WHOIS handling from 14-who-whois.md

data/docs/agents/ralph/features/25-verbose-mode.md.done

@@ -0,0 +1,166 @@
+# Verbose Mode
+
+## Description
+
+Add a `verbose:` option to the Client constructor that outputs debug information about connection state changes and blocking operations. Helps developers understand what the client is doing.
+
+## Behavior
+
+### Enabling Verbose Mode
+
+```ruby
+client = Yaic::Client.new(
+  server: "irc.example.com",
+  nick: "mynick",
+  verbose: true  # defaults to false
+)
+```
+
+### What Gets Logged
+
+**Connection State Changes**
+- When connecting starts
+- When connected successfully
+- When disconnected (including reason if available)
+- When connection state changes (registering, etc.)
+
+**Blocking Operations**
+- When waiting for an operation to complete (join, part, nick, who, whois)
+- When the wait completes
+
+### Output Format
+
+Simple, readable format to STDERR:
+
+```
+[YAIC] Connecting to irc.example.com:6697 (SSL)...
+[YAIC] Connected, registering...
+[YAIC] Registration complete
+[YAIC] Joining #channel...
+[YAIC] Joined #channel
+[YAIC] Sending WHO #channel...
+[YAIC] WHO complete (3 results)
+[YAIC] Sending WHOIS nick...
+[YAIC] WHOIS complete
+[YAIC] Disconnected
+```
+
+### Output Destination
+
+Use `$stderr.puts` for output. This keeps it separate from application output and works well with logging redirection.
+
+## Implementation Notes
+
+### Add verbose attribute
+
+```ruby
+def initialize(server:, port: 6697, nick:, user: nil, realname: nil, ssl: true, verbose: false)
+  @verbose = verbose
+  # ...
+end
+```
+
+### Add logging helper
+
+```ruby
+private
+
+def log(message)
+  return unless @verbose
+  $stderr.puts "[YAIC] #{message}"
+end
+```
+
+### Add logging calls
+
+In `connect`:
+```ruby
+log "Connecting to #{@server}:#{@port}#{@ssl ? ' (SSL)' : ''}..."
+```
+
+After registration complete (in handler for 001):
+```ruby
+log "Connected"
+```
+
+In `set_state`:
+```ruby
+log "State: #{state}" # or more friendly messages per state
+```
+
+In `join`:
+```ruby
+log "Joining #{channel}..."
+# after wait_until
+log "Joined #{channel}"
+```
+
+In `part`:
+```ruby
+log "Parting #{channel}..."
+log "Parted #{channel}"
+```
+
+In `who`:
+```ruby
+log "Sending WHO #{mask}..."
+# after wait_until
+log "WHO complete (#{results.size} results)"
+```
+
+In `whois`:
+```ruby
+log "Sending WHOIS #{nick}..."
+# after wait_until
+log "WHOIS complete"
+```
+
+In disconnect handler:
+```ruby
+log "Disconnected"
+```
+
+## Tests
+
+### Unit Tests
+
+**verbose false produces no output**
+- Given: Client created with `verbose: false` (default)
+- When: Client connects and performs operations
+- Then: No output to stderr
+
+**verbose true logs connection**
+- Given: Client created with `verbose: true`
+- When: Client connects
+- Then: Stderr contains "[YAIC] Connecting to" message
+
+**verbose true logs state changes**
+- Given: Client created with `verbose: true`
+- When: Client connects successfully
+- Then: Stderr contains "[YAIC] Connected" message
+
+**verbose true logs join**
+- Given: Connected client with `verbose: true`
+- When: `client.join("#channel")`
+- Then: Stderr contains "[YAIC] Joining #channel..." and "[YAIC] Joined #channel"
+
+**verbose true logs who**
+- Given: Connected client with `verbose: true`
+- When: `client.who("#channel")`
+- Then: Stderr contains "[YAIC] Sending WHO" and "[YAIC] WHO complete"
+
+**verbose true logs whois**
+- Given: Connected client with `verbose: true`
+- When: `client.whois("nick")`
+- Then: Stderr contains "[YAIC] Sending WHOIS" and "[YAIC] WHOIS complete"
+
+### Integration Tests
+
+**verbose mode produces expected output sequence**
+- Given: Client with `verbose: true`
+- When: Connect, join channel, who channel, disconnect
+- Then: Stderr output matches expected sequence of log messages
+
+## Dependencies
+
+- 24-blocking-who-whois.md (for WHO/WHOIS logging)

data/docs/agents/ralph/plans/test-optimization-plan.md

@@ -0,0 +1,172 @@
+# Test Optimization Plan
+
+## Profiling Results
+
+**Total test time**: 173 seconds
+**Total tests**: 267
+**Tests >= 1 second**: 79 tests (172.51s cumulative)
+**Tests < 1 second**: 188 tests (0.54s cumulative)
+
+### Slowest Tests (> 3 seconds)
+
+| Test | Time | Root Cause |
+|------|------|------------|
+| `PingPongIntegrationTest#test_client_automatically_responds_to_server_ping` | 7.01s | Intentional `sleep 6` to wait for server PING |
+| `NamesIntegrationTest#test_multi_message_names` | 5.73s | Creates 5 clients, each taking ~1s to connect |
+| `SocketIntegrationTest#test_ssl_read_write` | 5.01s | `read_multiple(socket, 5)` - full timeout wait |
+| `RegistrationIntegrationTest#test_invalid_nickname` | 5.01s | `read_multiple(socket, 5)` - full timeout wait |
+| `SocketIntegrationTest#test_write_message` | 5.00s | `read_multiple(socket, 5)` - full timeout wait |
+| `RegistrationIntegrationTest#test_empty_nickname` | 5.00s | `read_multiple(socket, 5)` - full timeout wait |
+| `KickIntegrationTest#test_receive_kick_others` | 4.13s | Creates 3 clients + oper setup + sleep 0.5 |
+| `ModeIntegrationTest#test_give_op_to_user` | 3.12s | 2 clients + oper setup + sleep 0.5 |
+| `KickIntegrationTest#test_receive_kick_self` | 3.12s | 2 clients + oper setup + sleep 0.5 |
+| `KickIntegrationTest#test_kick_user` | 3.12s | 2 clients + oper setup + sleep 0.5 |
+| `TopicIntegrationTest#test_receive_topic_change` | 3.06s | 2 clients + sleep 0.5 |
+| `PingPongIntegrationTest#test_respond_to_server_ping_during_registration` | 3.02s | `read_multiple(socket, 3)` timeout |
+
+### Root Causes Identified
+
+1. **Fixed sleep statements**: Many tests use `sleep 0.5` to wait for IRC responses
+2. **Full timeout waits**: `read_multiple(socket, N)` always waits N seconds even if data arrives immediately
+3. **Multiple client connections**: Each `client.connect` takes ~1 second due to registration
+4. **Sequential test execution**: Tests run one at a time despite being independent
+
+## Proposed Optimizations
+
+### Optimization 1: Enable Parallel Test Execution
+
+**Description**: Use minitest's built-in parallel executor to run tests concurrently.
+
+**Changes**:
+- Add `parallelize_me!` to test classes or enable globally
+- Tests already use unique nicks/channels via `Process.pid` and `Time.now.to_i`
+
+**Expected Impact**: 3-4x speedup (utilize multiple CPU cores)
+
+**Risk**: Low - tests already use unique identifiers, no shared state between tests
+
+**Implementation**:
+```ruby
+# test/test_helper.rb
+require "minitest/autorun"
+class Minitest::Test
+  parallelize_me!
+end
+```
+
+### Optimization 2: Replace `sleep` with `wait_until` Pattern
+
+**Description**: Replace `sleep 0.5` with `wait_until` style helpers that return as soon as condition is met.
+
+**Changes**:
+- Create `wait_until(timeout: 2) { condition }` helper in test_helper.rb
+- Replace `sleep 0.5` with targeted `wait_until` calls
+
+**Expected Impact**: Each test saves 0.3-0.4s (event typically arrives in 0.1s)
+
+**Risk**: Low - uses existing event system, fails fast if event doesn't arrive
+
+**Example**:
+```ruby
+# Before
+client1.kick(@test_channel, @test_nick2)
+sleep 0.5
+assert kick_received
+
+# After
+client1.kick(@test_channel, @test_nick2)
+wait_until { kick_received }
+assert kick_received
+```
+
+### Optimization 3: Replace `read_multiple`/`read_until_*` with `wait_until` Pattern
+
+**Description**: Rename and refactor `read_multiple`, `read_until_pong`, etc. to use consistent `wait_until` naming.
+
+**Changes**:
+- Replace `read_multiple(socket, 5)` with `wait_until(timeout: 2) { messages.any? { |m| m.command == "432" } }`
+- Remove confusingly-named helpers in favor of inline `wait_until` blocks
+
+**Expected Impact**: 4 tests save ~15 seconds total
+
+**Risk**: Low - clearer code, faster execution
+
+**Example**:
+```ruby
+# Before (always waits 5 seconds)
+messages = read_multiple(socket, 5)
+erroneous = messages.find { |m| m.command == "432" }
+
+# After (returns when error found or timeout)
+erroneous = nil
+wait_until(timeout: 2) do
+  raw = socket.read
+  if raw
+    msg = Yaic::Message.parse(raw)
+    erroneous = msg if msg&.command == "432"
+  end
+  erroneous
+end
+```
+
+### Optimization 4: Optimize Ping Test with Faster Server Config
+
+**Description**: The `test_client_automatically_responds_to_server_ping` waits 6 seconds for server PING.
+
+**Changes**:
+- Reduce server's ping frequency in test config from 5s to 3s
+- Use `wait_until` to detect when PING/PONG cycle completes instead of fixed sleep
+
+**Expected Impact**: Save ~4 seconds
+
+**Risk**: Low - just reducing wait time and using event-driven approach
+
+## Implementation Order
+
+1. **Parallel execution** (biggest impact, lowest risk)
+2. **Replace `sleep 0.5` with event waits** (many small wins)
+3. **Fix `read_multiple` pattern** (4 tests)
+4. **Optimize ping test** (1 test)
+
+## Parallelization Safety Analysis
+
+### Already Safe (unique identifiers per test)
+
+All integration tests generate unique identifiers:
+```ruby
+@test_nick = "t#{Process.pid}#{Time.now.to_i % 10000}"
+@test_channel = "#test#{Process.pid}#{Time.now.to_i % 10000}"
+```
+
+When running in parallel, each test process/thread has different:
+- `Process.pid` (if forked)
+- `Time.now.to_i % 10000` (high probability of uniqueness)
+
+### Potential Issue: Thread-based parallelism
+
+If using threads (not forks), `Process.pid` will be the same for all tests. Need to add thread ID:
+```ruby
+@test_nick = "t#{Process.pid}_#{Thread.current.object_id % 10000}_#{Time.now.to_i % 10000}"
+```
+
+### Shared Resources
+
+- IRC server: Can handle multiple concurrent connections
+- `become_oper`: Uses single shared oper account - safe, oper can be used from multiple connections
+- No file system or database shared state
+
+## Verification Plan
+
+1. Run `rake test` and verify all tests pass
+2. Count tests: should be 267
+3. Count assertions: should be 575
+4. Time should be significantly reduced (target: < 60s)
+
+## Risk Assessment
+
+| Change | Risk | Mitigation |
+|--------|------|------------|
+| Parallel execution | Low | Tests already isolated by design |
+| Event-driven waits | Low | Fallback timeout prevents hangs |
+| read_multiple fix | Low | Backwards compatible |
+| Ping test optimization | Medium | May need server config tuning |