yaic 0.1.0 → 0.2.0

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

@@ -0,0 +1,188 @@
+# WHO and WHOIS
+
+## Description
+
+Implement user information queries. WHO lists users matching criteria, WHOIS provides detailed info about a specific user.
+
+## Behavior
+
+### WHO Command
+
+```ruby
+client.who("#ruby")    # List users in channel
+client.who("nick")     # Get info on specific user
+```
+
+Format: `WHO <mask>`
+
+### WHO Response
+
+- 352 RPL_WHOREPLY - One per matching user
+- 315 RPL_ENDOFWHO - End of list
+
+RPL_WHOREPLY format:
+`:server 352 mynick #chan ~user host server nick H :0 realname`
+
+Fields:
+- channel or `*`
+- username
+- host
+- server
+- nick
+- flags: H (here) or G (gone/away), optionally `*` (ircop)
+- hopcount and realname (after colon)
+
+### WHOIS Command
+
+```ruby
+client.whois("dan")
+```
+
+Format: `WHOIS <nick>`
+
+### WHOIS Response
+
+Common numerics:
+- 311 RPL_WHOISUSER - `nick user host * :realname`
+- 319 RPL_WHOISCHANNELS - Channel list
+- 312 RPL_WHOISSERVER - Server info
+- 317 RPL_WHOISIDLE - Idle time
+- 330 RPL_WHOISACCOUNT - Account name (if identified)
+- 318 RPL_ENDOFWHOIS - End of WHOIS
+
+### WHOIS Errors
+
+- 401 ERR_NOSUCHNICK - Nick not found
+- 318 RPL_ENDOFWHOIS - Still sent on error
+
+### Events
+
+For WHO, can emit individual results or collected batch.
+
+For WHOIS, collect all numerics until ENDOFWHOIS, then emit `:whois` event with aggregated data.
+
+## Models
+
+```ruby
+Yaic::WhoisResult
+  - nick: String
+  - user: String
+  - host: String
+  - realname: String
+  - channels: Array[String]
+  - server: String
+  - idle: Integer (seconds)
+  - signon: Time
+  - account: String or nil
+  - away: String or nil
+```
+
+## Tests
+
+### Integration Tests - WHO
+
+**WHO channel**
+- Given: Client in #test with users
+- When: `client.who("#test")`
+- Then: Receive RPL_WHOREPLY for each user, then RPL_ENDOFWHO
+
+**WHO specific nick**
+- Given: "target" is online
+- When: `client.who("target")`
+- Then: Receive single RPL_WHOREPLY
+
+**WHO non-existent**
+- Given: No such channel/user
+- When: `client.who("nobody")`
+- Then: Receive only RPL_ENDOFWHO (empty results)
+
+### Integration Tests - WHOIS
+
+**WHOIS user**
+- Given: "target" is online
+- When: `client.whois("target")`
+- Then: Receive RPL_WHOISUSER, RPL_WHOISSERVER, RPL_ENDOFWHOIS
+
+**WHOIS with channels**
+- Given: "target" is in channels
+- When: `client.whois("target")`
+- Then: RPL_WHOISCHANNELS shows their channels
+
+**WHOIS non-existent**
+- Given: No such nick
+- When: `client.whois("nobody")`
+- Then: Receive 401 ERR_NOSUCHNICK, then RPL_ENDOFWHOIS
+
+**WHOIS away user**
+- Given: "target" is away
+- When: `client.whois("target")`
+- Then: Receive 301 RPL_AWAY with away message
+
+### Unit Tests - WHO
+
+**Parse RPL_WHOREPLY**
+- Given: `:server 352 me #chan ~user host srv nick H :0 Real Name`
+- When: Parse
+- Then: channel="#chan", user="~user", nick="nick", realname="Real Name", away=false
+
+**Parse RPL_WHOREPLY away**
+- Given: `:server 352 me #chan ~user host srv nick G :0 Name`
+- When: Parse
+- Then: away=true (G flag)
+
+**Format WHO**
+- Given: mask = "#test"
+- When: Build WHO
+- Then: Output = "WHO #test\r\n"
+
+### Unit Tests - WHOIS
+
+**Parse RPL_WHOISUSER**
+- Given: `:server 311 me nick ~user host * :Real Name`
+- When: Parse
+- Then: nick="nick", user="~user", host="host", realname="Real Name"
+
+**Parse RPL_WHOISCHANNELS**
+- Given: `:server 319 me nick :#chan1 @#chan2 +#chan3`
+- When: Parse
+- Then: channels=["#chan1", "#chan2", "#chan3"] with modes noted
+
+**Parse RPL_WHOISIDLE**
+- Given: `:server 317 me nick 300 1234567890 :seconds idle`
+- When: Parse
+- Then: idle=300, signon=Time.at(1234567890)
+
+**Parse RPL_WHOISACCOUNT**
+- Given: `:server 330 me nick account :is logged in as`
+- When: Parse
+- Then: account="account"
+
+**Format WHOIS**
+- Given: nick = "target"
+- When: Build WHOIS
+- Then: Output = "WHOIS target\r\n"
+
+### Collection Tests
+
+**Collect WHOIS parts**
+- Given: WHOIS in progress
+- When: RPL_WHOISUSER, RPL_WHOISCHANNELS, RPL_WHOISSERVER, RPL_ENDOFWHOIS received
+- Then: Single :whois event with all data
+
+**Handle interleaved messages**
+- Given: WHOIS in progress
+- When: Other messages arrive between WHOIS numerics
+- Then: WHOIS data still collected correctly
+
+## Implementation Notes
+
+- WHOIS numerics may be interleaved with other messages
+- Buffer WHOIS results until ENDOFWHOIS
+- Implement timeout for WHOIS (server may not respond)
+- RPL_WHOISCHANNELS may have mode prefixes (@, +)
+- WHO visibility affected by +i mode
+
+## Dependencies
+
+- Requires `01-message-parsing.md`
+- Requires `05-event-system.md`

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

@@ -0,0 +1,180 @@
+# Client API
+
+## Description
+
+Implement the main `Yaic::Client` class that ties everything together and provides the public interface.
+
+## Behavior
+
+### Initialization
+
+```ruby
+client = Yaic::Client.new(
+  server: "irc.libera.chat",
+  port: 6697,
+  ssl: true,
+  nickname: "mynick",
+  username: "myuser",      # optional, defaults to nickname
+  realname: "My Real Name" # optional, defaults to nickname
+)
+```
+
+### Connection
+
+```ruby
+client.connect  # Blocking - connects and starts event loop
+```
+
+### Event Registration
+
+```ruby
+client.on(:message) { |event| puts event.text }
+client.on(:join) { |event| puts "#{event.user} joined #{event.channel}" }
+```
+
+### Commands
+
+```ruby
+client.join("#ruby")
+client.join("#ruby", "key")
+client.part("#ruby")
+client.part("#ruby", "reason")
+client.privmsg("#ruby", "Hello!")
+client.privmsg("nick", "Private message")
+client.notice("#ruby", "Notice")
+client.nick("newnick")
+client.topic("#ruby")
+client.topic("#ruby", "New topic")
+client.quit
+client.quit("Goodbye")
+client.kick("#ruby", "nick")
+client.kick("#ruby", "nick", "reason")
+client.mode("#ruby")
+client.mode("#ruby", "+m")
+client.who("#ruby")
+client.whois("nick")
+client.names("#ruby")
+```
+
+### State Access
+
+```ruby
+client.nick        # Current nickname
+client.connected?  # Boolean
+client.channels    # Hash of joined channels
+client.server      # Server hostname
+```
+
+### Error Handling
+
+- Connection errors raise appropriate exceptions
+- Server errors emit `:error` events
+
+## Models
+
+```ruby
+Yaic::Client
+  - config: Hash
+  - socket: Yaic::Socket
+  - handlers: Hash[Symbol, Array[Block]]
+  - channels: Hash[String, Yaic::Channel]
+  - nick: String
+  - state: Symbol
+```
+
+## Tests
+
+### Integration Tests - Full Flow
+
+**Connect and receive welcome**
+- Given: New client configured for inspircd
+- When: `client.connect`
+- Then: Connected, :connect event fired
+
+**Join channel and send message**
+- Given: Connected client
+- When: Join #test, send PRIVMSG
+- Then: Message received by other client in channel
+
+**Receive and handle message**
+- Given: Connected client in #test with :message handler
+- When: Other client sends message
+- Then: Handler called with correct event
+
+**Full session lifecycle**
+- Given: New client
+- When: Connect, join, chat, part, quit
+- Then: All operations succeed, clean disconnect
+
+### Unit Tests - Initialization
+
+**Default values**
+- Given: Only server, port, ssl, nickname provided
+- When: Create client
+- Then: username = nickname, realname = nickname
+
+**Store configuration**
+- Given: Full config provided
+- When: Create client
+- Then: All values accessible
+
+### Unit Tests - State
+
+**Initially disconnected**
+- Given: New client
+- Then: `client.connected?` = false, `client.state` = :disconnected
+
+**After connect**
+- Given: Client connects successfully
+- Then: `client.connected?` = true, `client.state` = :connected
+
+**After quit**
+- Given: Connected client quits
+- Then: `client.connected?` = false
+
+**Track nickname**
+- Given: Connected as "oldnick"
+- When: Nick changed to "newnick"
+- Then: `client.nick` = "newnick"
+
+**Track channels**
+- Given: Connected client
+- When: Join #test
+- Then: `client.channels["#test"]` exists
+
+### Unit Tests - Command Methods
+
+**join delegates to socket**
+- Given: Connected client
+- When: `client.join("#test")`
+- Then: "JOIN #test" sent
+
+**privmsg delegates to socket**
+- Given: Connected client
+- When: `client.privmsg("#test", "Hello")`
+- Then: "PRIVMSG #test :Hello" sent
+
+### Error Handling Tests
+
+**Connection refused**
+- Given: No server on port
+- When: `client.connect`
+- Then: Raises connection error
+
+**Server error numeric**
+- Given: Connected client with :error handler
+- When: Server sends 433 (nick in use)
+- Then: Handler called with error info
+
+## Implementation Notes
+
+- `connect` should handle the full registration sequence
+- Consider thread-safety for handlers
+- Event loop reads from socket, parses messages, dispatches events
+- All command methods should validate state (connected?) before sending
+- Consider `connect_async` for non-blocking usage
+
+## Dependencies
+
+- Requires all previous features
+- This is the final integration feature

data/docs/agents/ralph/features/16-ssl-test-infrastructure.md.done

@@ -0,0 +1,50 @@
+# SSL Test Infrastructure
+
+## Description
+
+Set up proper SSL/TLS testing infrastructure so that SSL-related tests can run reliably. This includes configuring the inspircd Docker container with SSL certificates and ensuring tests can connect over TLS.
+
+## Behavior
+
+### Container Configuration
+
+1. Create or configure inspircd container with SSL enabled on port 6697
+2. Generate self-signed certificates for testing
+3. Mount certificates into the container
+4. Update `bin/start-irc-server` to set up SSL-enabled container
+
+### Test Updates
+
+1. Remove skip logic from SSL tests in `test/integration/socket_test.rb`
+2. SSL tests should run and pass reliably
+3. Verify both SSL connection and read/write operations work
+
+## Tests
+
+**SSL connection succeeds**
+- Given: inspircd with SSL on localhost:6697
+- When: Connect with ssl: true, verify_mode: VERIFY_NONE
+- Then: Connection established, state is :connecting
+
+**SSL read/write works**
+- Given: SSL connection established
+- When: Send NICK/USER commands
+- Then: Receive server responses
+
+**SSL certificate verification**
+- Given: Self-signed cert on server
+- When: Connect with VERIFY_PEER
+- Then: Fails unless cert is trusted
+- When: Connect with VERIFY_NONE
+- Then: Succeeds
+
+## Implementation Notes
+
+- Use OpenSSL to generate self-signed certs: `openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes`
+- Store certs in `test/fixtures/ssl/` or similar
+- May need custom inspircd.conf to enable SSL module
+- Update `bin/stop-irc-server` if container setup changes
+
+## Dependencies
+
+- Requires `02-connection-socket.md` to be complete (SSL support in Socket class)

data/docs/agents/ralph/features/17-github-actions-ci.md.done

@@ -0,0 +1,70 @@
+# GitHub Actions CI
+
+## Description
+
+Set up GitHub Actions to run tests and linting on pull requests and pushes to the main branch. Tests run on Ruby 3.2 and 3.4 (bottom and top of current EOL lifecycle). Linting runs as a separate job.
+
+## Behavior
+
+### Workflow Triggers
+
+The workflow runs on:
+- Push to `main` branch
+- All pull requests
+
+### Jobs
+
+**1. Lint Job**
+- Runs `bundle exec standardrb` (or `bundle exec rake standard`)
+- Single job, not matrixed
+- Fails fast if code doesn't pass linting
+
+**2. Test Job**
+- Matrix: Ruby 3.2 and Ruby 3.4
+- Runs `bundle exec rake test`
+- Uses `ruby/setup-ruby@v1` with `bundler-cache: true`
+
+### Workflow File
+
+Located at `.github/workflows/main.yml` (update existing file).
+
+## Implementation Notes
+
+- The existing workflow triggers on `master` which doesn't exist - change to `main`
+- Current workflow only tests Ruby 3.4.1 - expand to matrix with 3.2 and 3.4
+- Split lint into its own job so it fails fast and doesn't duplicate across matrix
+- Use `actions/checkout@v4` with `persist-credentials: false`
+
+## Tests
+
+This feature has no unit tests. Verification is done by:
+
+1. Push the workflow changes to a branch
+2. Open a PR or push to main
+3. Verify CI runs successfully using `gh run list` and `gh run view`
+4. All jobs (lint, test on 3.2, test on 3.4) must pass
+
+### Verification Commands
+
+```bash
+# Check recent workflow runs
+gh run list --limit 5
+
+# View specific run details
+gh run view <run-id>
+
+# Check if latest run on current branch passed
+gh run list --branch $(git branch --show-current) --limit 1
+```
+
+## Completion Criteria
+
+- [ ] `.github/workflows/main.yml` updated with correct configuration
+- [ ] Workflow triggers on `main` branch (not `master`)
+- [ ] Lint job runs separately
+- [ ] Test matrix includes Ruby 3.2 and 3.4
+- [ ] CI run passes (verified via `gh run list` showing success)
+
+## Dependencies
+
+None - this is the first feature.

data/docs/agents/ralph/features/18-brakeman-security-scanning.md.done

@@ -0,0 +1,67 @@
+# Brakeman Security Scanning
+
+## Description
+
+Add Brakeman security scanning to CI. Brakeman is a static analysis tool that checks Ruby on Rails applications for security vulnerabilities. This runs as a separate GitHub Actions job.
+
+## Behavior
+
+### Workflow Integration
+
+Add a new job to `.github/workflows/main.yml`:
+
+**Security Job**
+- Runs `bin/brakeman` (or `bundle exec brakeman`)
+- Single job, not matrixed (security scanning doesn't need multiple Ruby versions)
+- Can run in parallel with other jobs
+
+### Brakeman Setup
+
+If `bin/brakeman` doesn't exist, create it as a binstub or run via `bundle exec brakeman`.
+
+Add `brakeman` gem to Gemfile if not present (in development/test group).
+
+## Implementation Notes
+
+- Brakeman may report existing issues in the codebase
+- If Brakeman fails, fix the issues or configure Brakeman to ignore false positives
+- Use `brakeman --no-pager` for CI output
+- Consider `brakeman -o /dev/stdout -o brakeman-output.html` for both console and artifact output
+
+### Handling Existing Issues
+
+If the codebase has existing Brakeman warnings:
+1. Run `brakeman` locally first
+2. Fix any real security issues
+3. For false positives, use `brakeman -I` to create/update `config/brakeman.ignore`
+4. Commit the ignore file if needed
+
+## Tests
+
+This feature has no unit tests. Verification is done by:
+
+1. Ensure Brakeman passes locally: `bundle exec brakeman`
+2. Push changes and verify CI runs
+3. Security job must pass in GitHub Actions
+
+### Verification Commands
+
+```bash
+# Run Brakeman locally
+bundle exec brakeman
+
+# Check CI status
+gh run list --limit 5
+gh run view <run-id>
+```
+
+## Completion Criteria
+
+- [ ] Brakeman gem added to Gemfile (if not present)
+- [ ] Brakeman runs successfully locally with no errors
+- [ ] Security job added to `.github/workflows/main.yml`
+- [ ] CI run passes including the security job (verified via `gh run list`)
+
+## Dependencies
+
+- Requires `17-github-actions-ci.md` (workflow file must exist and work)

data/docs/agents/ralph/features/19-fix-qa.md.done

@@ -0,0 +1,73 @@
+Look at 02-simplified-client-api.md.done
+An agent flag that feature as done without the QA passing on it. Which is TOTALLY UNACCEPTABLE.
+
+Do not rerun QA before you're ready to commit. I'll give you the QA output:
+
+```
+  QA FAILED. Issues found:
+
+       1. Public timeout parameters violate feature spec (/Users/joedupuis/workspace/yaic/lib/yaic/client.rb lines
+       55, 159, 166, 184):
+         - The feature spec at
+       /Users/joedupuis/workspace/yaic/docs/agents/ralph/features/02-simplified-client-api.md.done explicitly
+       states:
+             - Line 32: "All methods block until the operation completes. No bangs, no timeout params, no manual
+       socket handling."
+           - Lines 86-90: "Timeouts are an internal concern. Use sensible defaults... Users don't need to think
+       about this."
+         - However, the implementation exposes timeout: keyword arguments in the public API:
+         def connect(timeout: DEFAULT_CONNECT_TIMEOUT)
+       def join(channel, key = nil, timeout: DEFAULT_OPERATION_TIMEOUT)
+       def part(channel, reason = nil, timeout: DEFAULT_OPERATION_TIMEOUT)
+       def nick(new_nick = nil, timeout: DEFAULT_OPERATION_TIMEOUT)
+         - Fix: Remove the public timeout: parameter from these method signatures. Keep the internal constants and
+       use them directly in wait_until.
+       2. Integration tests still use instance_variable_get(:@socket) (Multiple files):
+         - /Users/joedupuis/workspace/yaic/test/integration/mode_test.rb lines 79, 103, 130
+         - /Users/joedupuis/workspace/yaic/test/integration/kick_test.rb lines 17, 43, 88, 110, 146
+         - /Users/joedupuis/workspace/yaic/test/integration/names_test.rb lines 34, 63, 91
+         - /Users/joedupuis/workspace/yaic/test/integration/nick_test.rb lines 33, 51
+         - /Users/joedupuis/workspace/yaic/test/integration/join_part_test.rb lines 53, 108
+         - /Users/joedupuis/workspace/yaic/test/integration/who_whois_test.rb line 133
+         - The feature spec (lines 136-139) explicitly says to remove:
+             - instance_variable_get
+           - Manual read loops
+           - Custom wait helpers
+           - on_socket_connected
+         - These tests use instance_variable_get(:@socket) to call become_oper and send raw commands like OPER and
+       SAMODE.
+         - Fix: Either add a public raw or send_raw method to the Client class for sending raw IRC commands, or
+       refactor the tests to not require OPER privileges (if possible). The become_oper helper pattern using direct
+        socket access is exactly what the feature was meant to eliminate.
+
+       Required fixes:
+       1. Remove timeout: parameter from the public method signatures of connect, join, part, and nick.
+       2. Either add a public raw(command) method to send arbitrary IRC commands, or refactor integration tests
+       that need OPER privileges to avoid accessing internal socket.
+```
+
+and
+
+```
+  Two issues found:
+
+  1. Public timeout parameters violate feature spec - The methods connect, join, part, and nick expose timeout:
+  keyword arguments, but the feature spec explicitly states "No bangs, no timeout params" and "Timeouts are an
+  internal concern."
+  2. Integration tests still use instance_variable_get(:@socket) - Multiple integration tests access the internal
+  socket directly via instance_variable_get(:@socket) to call become_oper and send raw commands. The feature spec
+  says to remove this pattern.
+
+  Required fixes:
+  1. Remove timeout: parameter from public method signatures
+  2. Add a public raw(command) method for sending arbitrary IRC commands, or refactor the tests
+```
+
+
+Fix the mess. If you cant stop and ask me questions.
+
+
+I think the timeout is fine. Let's ignore the first part. The second part though with the reaching for instance variable is bad.
+The tests should not have to reach out for internals with instance_variable_get.
+
+If you are blocked ask me with the ask question tool.

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

@@ -0,0 +1,70 @@
+# Test Optimization - Planning
+
+## Description
+
+The test suite is slow (173 seconds) and needs optimization. This feature involves profiling the tests to identify slow ones, analyzing why they are slow, and creating an optimization plan for user approval.
+
+## Behavior
+
+### Phase 1: Profiling
+
+Run the full test suite with timing enabled using `rake test TESTOPTS="-v"` and capture:
+- Total time for each test file
+- Individual test method times
+- Identify the slowest tests (top 10 or anything over 1 second)
+
+### Phase 2: Analysis
+
+For each slow test, analyze:
+- Is it an integration test hitting a real IRC server?
+- Does it have unnecessary sleeps or timeouts?
+- Is it doing redundant setup?
+- Could it be parallelized?
+- Is it testing too much in one test?
+
+Document findings with specific line numbers and explanations.
+
+### Phase 3: Plan Creation
+
+Create a plan document at `docs/agents/ralph/plans/test-optimization-plan.md` containing:
+- Summary of profiling results (slowest tests with times)
+- Root causes identified
+- Proposed optimizations with expected impact
+- Risk assessment for each change
+- How test coverage will be preserved
+
+### Phase 4: User Approval
+
+Use `AskUserQuestion` tool to ask the user to review and approve the plan.
+
+If not approved, update the plan based on feedback and ask again.
+
+## Tests
+
+This feature is meta - it's about planning, not adding new functionality. Success criteria:
+
+**Profiling Output**
+- Generate a report showing test execution times
+- Identify tests taking > 500ms
+
+**Plan Document**
+- Plan exists at docs/agents/ralph/plans/test-optimization-plan.md
+- Contains profiling results with specific times
+- Contains proposed changes with rationale
+- Contains risk assessment
+
+## Implementation Notes
+
+- Use `rake test TESTOPTS="-v"` for timing
+- Use `bundle exec standardrb -A` for linting
+
+## Dependencies
+
+None - this is the first feature.
+
+## Next Features
+
+After this planning feature is complete, the following implementation features should be created:
+- 21-test-parallelization.md - Enable parallel test execution
+- 22-wait-until-pattern.md - Replace sleep/read_multiple with wait_until
+- 23-ping-test-optimization.md - Optimize the ping test with faster server config