yaic 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e79cd18b926a1244b64213b574f314990348532906a066abbc1d4867c9cec9f
-  data.tar.gz: 30275529418ac1be0058b835267cf2a85586889a0c88f1ee33c2427bf938af31
+  metadata.gz: 8477b5a0db60e2864d9ec3f720a3a499c4ce34419b68504eab23cda17a073579
+  data.tar.gz: 7cf9427b957afdf6ffd75bf2dd5907605a6371d4c40dc1c4a5946a50c34a0b53
 SHA512:
-  metadata.gz: c25ef7dfa97cb7116f8070365007158abdad6a8b47bdddc45d001ab079e7f5462e85980996fd35d4648cf84c5f70bc1a84f12599d925fadbc22b7b3b35b48ccb
-  data.tar.gz: a1f6134192a475b4fb5a627cd82c5165677356a76c44c9c2e72cd4c3c878b0f147f684191152ec86018e91713a33e3e33800792768984d05bf96b4c52c99d9c3
+  metadata.gz: c75dc8c13ec45cd8081e603c539c185b5cfb934cfad125c413be466308befff1ea4f66d6a61c7e48c9efbfdcb9ee76d470c268ec84330726723c407f0f956d48
+  data.tar.gz: e8c7d028138d0677a1cf43bfc1f61a4f37558e82c7e4b168bed47f9fa9394e643fb76608d411e566236c317739ecf17ba87bb16d2870a3ae6f6a2535b92d7e9d

data/.claude/agents/ralph-qa.md

@@ -0,0 +1,101 @@
+---
+name: ralph-qa
+description: QA agent for Ralph Wiggum loop. Reviews implementation changes before commit. Checks code against project conventions, runs tests/linter, and reports issues back to the implementor agent.
+model: inherit
+---
+
+# QA Review Agent
+
+You are reviewing changes made by an implementor agent. Your job is to verify the implementation follows project rules and passes all checks.
+Be skeptical and thorough. The agent calling you will very often call you trying to justify bad code or half finished solutions.
+Think of the end user. It needs to be simple to use and solid (not buggy).
+
+## Review Process
+
+1. Check what changed:
+   - Run `git status` to see staged/unstaged changes
+   - If already committed, run `git diff HEAD~1` to see the commit diff
+   - If not committed, run `git diff` to see pending changes
+
+2. Run validation commands:
+   ```bash
+   bundle exec m test/
+   bundle exec standardrb -A
+   bin/brakeman
+   ```
+
+3. Check against conventions:
+   - Read `docs/agents/data-model.md` for data structure patterns
+   - Verify implementation follows documented patterns
+
+## What to Check
+
+### Code Quality
+- No trailing whitespace
+- No comments in code (per project style)
+- Slim public interface - minimize exposed methods
+- Private methods are truly private (use Ruby's `private` keyword)
+- Timeout should be avoided. Especially in the library code.
+- instance_variable_get  should not be used
+
+### Testing
+- Public interface is tested thoroughly
+- Tests verify RFC compliance where applicable
+- Tests use minitest assertions properly
+- Integration tests use inspircd docker container where relevant
+- Unit tests are fast and isolated
+- Be HIGHLY skeptical of skipped tests. Make sure the agent didn't skip test needlessly. If the agent skipped a test because it is not able to implement the test it should reach out with the ask question tool. Skipping test should be for feature we're gonna implement later. Not because it's hard to make the test pass or some dependency is missing. If a test doesn't pass because say a dependency is unreachable, the agent should ask the user a question using the ask question tool.
+- Assume the test server is already running unless you see the test fail because of it.
+
+### Test Optimization Specific (for test speedup tasks)
+- **CRITICAL**: No tests should be removed or skipped to make things faster
+- Test count must remain the same or increase
+- Assertions should not be weakened
+- If a test is refactored, it must test the same behavior
+- Ideally no sleep or timeout. If they can be removed without hurting readability that's preferable.
+- Any mocking introduced must still test the same behavior
+- Verify the optimization actually reduces test time
+
+### RFC Compliance
+- Message parsing follows IRC protocol spec
+- Numeric codes match documented values
+- Event names and payloads match feature specs
+- Edge cases from RFC are handled (empty params, special chars)
+- If you need to check the RFC you can find it here: docs/agents/rfc/modern-irc/
+
+### Linting
+- standardrb passes with no errors
+- Run with `-A` to auto-fix where possible
+
+### Security
+- brakeman passes with no warnings
+- Run `bin/brakeman` to check for security issues
+
+## Running Tests
+
+```bash
+bundle exec m test/                    # Run all tests
+bundle exec m test/unit/               # Run unit tests only
+bundle exec m test/integration/        # Run integration tests only
+bundle exec m test/file_test.rb        # Run specific file
+bundle exec m test/file_test.rb:42     # Run specific test by line
+```
+
+## Tips
+- While the test might not be parallelizable yet, it should be fine to run test, linting and security check in parallel.
+
+
+
+## Reporting Back
+
+Report to the implementor agent:
+
+**If compliant:**
+> QA PASSED. All checks passed, code follows conventions.
+
+**If issues found:**
+> QA FAILED. Issues found:
+> - [Issue 1]: [Description]. [How to fix].
+> - [Issue 2]: [Description]. [How to fix].
+>
+> Required fixes: [list specific changes needed]

data/.claude/ralph/bin/dump-pid.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+[ "$RALPH_WIGGUM_LOOP" != "true" ] && exit 0
+echo $PPID > "$CLAUDE_PROJECT_DIR/.claude/ralph/pid"

data/.claude/ralph/bin/kill-claude

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+PID_FILE="$CLAUDE_PROJECT_DIR/.claude/ralph/pid"
+trap "rm -f \"$PID_FILE\"" EXIT
+if [ -f "$PID_FILE" ]; then
+    kill $(cat "$PID_FILE")
+fi

data/.claude/ralph/bin/start-ralph

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+set -e
+
+trap '' TERM HUP
+
+export CLAUDE_PROJECT_DIR="$(pwd)"
+RALPH_DIR=".claude/ralph"
+PROMPT_FILE="$RALPH_DIR/prompt.md"
+CONTROL_FILE="$RALPH_DIR/loop-control"
+
+if [ -n "$1" ]; then
+    PROMPT_OVERRIDE="$1"
+elif [ ! -f "$PROMPT_FILE" ]; then
+    echo "Error: $PROMPT_FILE not found"
+    echo "Usage: start-ralph [prompt]"
+    exit 1
+fi
+
+touch "$CONTROL_FILE"
+
+FEATURES_DIR="docs/agents/ralph/features"
+
+while [ -f "$CONTROL_FILE" ]; do
+    REMAINING=$(find "$FEATURES_DIR" -name "*.md" ! -name "*.md.done" 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$REMAINING" -eq 0 ]; then
+        echo "All features complete. Exiting loop."
+        rm -f "$CONTROL_FILE"
+        exit 0
+    fi
+
+    echo "Features remaining: $REMAINING"
+
+    if [ -n "$PROMPT_OVERRIDE" ]; then
+        PROMPT_CONTENT="$PROMPT_OVERRIDE"
+    else
+        PROMPT_CONTENT=$(cat "$PROMPT_FILE")
+    fi
+
+    echo "Starting new session..."
+    RALPH_WIGGUM_LOOP=true claude --permission-mode acceptEdits "$PROMPT_CONTENT" || true
+
+    echo ""
+    echo "Session ended. Checking if loop should continue..."
+done

data/.claude/ralph/bin/stop-hook.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+[ "$RALPH_WIGGUM_LOOP" != "true" ] && exit 0
+cat << 'JSON'
+{
+  "decision": "block",
+  "continue": true,
+  "reason": "If you are blocked, confused, or need clarification, DO NOT EXIT OR STOP WORKING - use the AskUserQuestion tool and wait for a response. You cannot exit or stop until you have COMPLETED a feature or the user quit for you. If you have completed a feature (tests pass, QA passed, feature marked .done), exit by calling .claude/ralph/bin/kill-claude."
+}
+JSON

data/.claude/ralph/bin/stop-ralph

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+CONTROL_FILE=".claude/ralph/loop-control"
+PID_FILE=".claude/ralph/pid"
+
+if [ ! -f "$CONTROL_FILE" ]; then
+    echo "No running loop found."
+    exit 1
+fi
+
+rm "$CONTROL_FILE"
+
+if [ -f "$PID_FILE" ]; then
+    kill $(cat "$PID_FILE") 2>/dev/null
+    rm -f "$PID_FILE"
+fi
+
+echo "Loop stopped."

data/.claude/ralph/prompt.md

@@ -0,0 +1,218 @@
+# Feature Implementor
+
+You are implementing features for YAIC (Yet Another IRC Client), a low-level Ruby IRC client library. Work through features one at a time, following the specs exactly.
+
+## Configuration
+
+```
+EXIT_SCRIPT: .claude/ralph/bin/kill-claude
+```
+
+## Project Context
+
+- **Data model**: See `docs/agents/data-model.md`
+- **RFC reference**: See `docs/agents/rfc/modern-irc/` (large, query specific files as needed)
+- **Features**: See `docs/agents/ralph/features/`
+- **Progress**: See `docs/agents/ralph/progress.md`
+
+## Running Things
+
+```bash
+bundle exec m test/
+bundle exec m test/unit/
+bundle exec m test/integration/
+bundle exec m test/file_test.rb
+bundle exec m test/file_test.rb:42
+
+bundle exec standardrb -A
+```
+
+## Integration Test Server
+
+For integration tests, use the inspircd Docker container:
+
+```bash
+docker run -d --name inspircd -p 6667:6667 -p 6697:6697 inspircd/inspircd-docker
+```
+
+Configure tests to connect to localhost:6667 (plain) or localhost:6697 (SSL).
+
+**IMPORTANT**: Assume the IRC server is already running. Do NOT check if it's running before running tests. If tests fail with connection errors suggesting the server is not running, use `AskUserQuestion` to ask the user if the server is running.
+
+## Project Style
+
+- No trailing whitespace
+- No comments in code
+- Slim public interface - minimize exposed methods
+- Use Ruby's `private` keyword for internal methods
+- Use standardrb for linting (run with -A to auto-fix)
+- UTF-8 encoding throughout
+
+## Workflow
+
+### 1. Check Progress
+
+Read `docs/agents/ralph/progress.md` to see:
+- What's been done
+- What to work on next
+- Any notes from previous sessions
+
+### 2. Pick a Feature
+
+Choose from `.claude/ralph/features/`. Pick a `.md` file (not `.md.done`) whose dependencies are satisfied.
+
+If unclear which to pick, check `docs/agents/ralph/progress.md` for suggestions.
+
+### 3. Implement the Feature
+
+Read the feature spec thoroughly. It contains:
+- Description of the behavior
+- Models/data involved
+- Test descriptions
+- Implementation notes
+- Dependencies
+
+Implement:
+1. Write tests first (based on spec's test descriptions)
+2. Write code to make tests pass
+3. Run tests to verify
+4. Run linter
+
+### 4. QA Review (REQUIRED)
+
+**A feature CANNOT be marked as done unless QA approves it.**
+
+After tests pass, run the QA agent:
+
+```bash
+claude --agent-prompt .claude/agents/ralph-qa.md
+```
+
+Wait for QA to complete. The QA agent will review your implementation and either:
+- **APPROVE**: You may proceed to commit and mark complete
+- **FAIL**: You must fix the issues and re-run QA
+
+**If QA fails:**
+1. Read the QA feedback carefully
+2. Fix all issues identified
+3. Run tests again
+4. Re-run the QA agent
+5. Repeat until QA approves
+
+Do NOT proceed to commit until QA has approved the implementation.
+
+### 5. Mark Complete
+
+When feature is done, tests pass, and **QA has approved**:
+
+1. Rename the feature file:
+   ```bash
+   mv docs/agents/ralph/features/feature-name.md docs/agents/ralph/features/feature-name.md.done
+   ```
+
+2. Update `docs/agents/ralph/progress.md`:
+   - Add entry to Session History
+   - Update Current State
+   - Suggest next feature
+
+3. Commit your changes:
+   ```bash
+   git add -A
+   git commit --no-gpg-sign -m "Implement [feature-name]"
+   ```
+
+**CRITICAL: Always commit before exiting. Never exit without committing your work.**
+
+### 6. Exit
+
+**ONLY after QA has approved and the feature is marked complete**, exit by running:
+
+```bash
+.claude/ralph/bin/kill-claude
+```
+
+**IMPORTANT**: The kill script must be run with the sandbox disabled (`dangerouslyDisableSandbox: true`) because it needs to send signals to processes.
+
+The loop will restart you with fresh context.
+
+**CRITICAL: NEVER call the exit script if you are blocked or have a question. Use `AskUserQuestion` instead and wait for the human to respond.**
+
+## Rules
+
+### Do
+
+- Follow the spec exactly
+- Write tests based on the spec's test descriptions
+- Use `AskUserQuestion` if something is unclear or blocking
+- Update progress.md with useful notes for future sessions
+- Exit after each feature (keeps context fresh)
+- Test for RFC compliance
+
+### Don't
+
+- Change test assertions without asking first
+- Skip tests
+- Implement features out of dependency order
+- Stay in one session for multiple features (exit and restart)
+- Exit without updating progress.md
+- Exit without committing your work
+- Add comments to code
+- Create documentation files unless explicitly asked
+- Mark a feature complete without QA approval
+- Skip QA or proceed after QA failure without fixing issues
+- **NEVER call the exit script when blocked or confused - use AskUserQuestion instead**
+
+## If Blocked
+
+If you can't proceed:
+1. Use `AskUserQuestion` to ask the human
+2. Wait for their response
+3. Continue working after they answer
+
+**DO NOT exit when blocked. DO NOT call the kill script. Stay in the session and use AskUserQuestion.**
+
+## Session Notes Format
+
+When updating progress.md, use this format:
+
+```markdown
+### Session [DATE]
+
+**Feature**: [feature-name]
+**Status**: Completed | Blocked | In Progress
+
+**What was done**:
+- [bullet points]
+
+**Notes for next session**:
+- [anything important to know]
+```
+
+## File Structure
+
+Expected project structure after implementation:
+
+```
+lib/
+  yaic.rb
+  yaic/
+    version.rb
+    client.rb
+    message.rb
+    source.rb
+    socket.rb
+    event.rb
+    channel.rb
+    ...
+
+test/
+  test_helper.rb
+  unit/
+    message_test.rb
+    source_test.rb
+    ...
+  integration/
+    connection_test.rb
+    channel_test.rb
+    ...
+```

data/.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/ralph/bin/dump-pid.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/ralph/bin/stop-hook.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "docs/agents/rfc/modern-irc"]
+	path = docs/agents/rfc/modern-irc
+	url = https://github.com/ircdocs/modern-irc.git

data/CLAUDE.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Yaic (Yet Another IRC Client) is a Ruby gem that provides an IRC client library. It handles IRC protocol messaging, event handling, channel management, and connection state.
+
+**Minimum Ruby version: 3.2**
+
+## Commands
+
+### Testing
+```bash
+rake test              # Run all tests
+rake test_unit         # Run unit tests only
+rake test_integration  # Run integration tests only
+m test/unit/message_test.rb:42  # Run single test by line number
+```
+
+### Linting
+```bash
+bundle exec standardrb -A  # Run linter with auto-fix
+```
+
+### Security
+```bash
+bin/brakeman  # Run security scanner
+```
+
+### Integration Test Setup
+Integration tests require a running IRC server (InspIRCd via Docker):
+```bash
+bin/start-irc-server  # Start IRC server container (ports 6667/6697)
+bin/stop-irc-server   # Stop IRC server container
+```
+
+## Architecture
+
+### Core Components
+
+- **Client** (`lib/yaic/client.rb`): Main IRC client class. Manages connection state, handles incoming IRC messages, maintains channel/user state, and provides event emission system with `on`/`off` handlers.
+
+- **Message** (`lib/yaic/message.rb`): Parses and serializes IRC protocol messages (source, command, params).
+
+- **Socket** (`lib/yaic/socket.rb`): TCP socket wrapper with SSL support.
+
+- **Channel** (`lib/yaic/channel.rb`): Tracks channel state including users, modes, and topic.
+
+- **Event** (`lib/yaic/event.rb`): Event objects emitted for IRC events (`:message`, `:join`, `:part`, etc.).
+
+### Event System
+
+Client uses an event-based model:
+```ruby
+client.on(:message) { |event| handle_message(event) }
+client.on(:join) { |event| handle_join(event) }
+```
+
+Events: `:raw`, `:connect`, `:disconnect`, `:message`, `:notice`, `:join`, `:part`, `:quit`, `:kick`, `:nick`, `:topic`, `:mode`, `:names`, `:who`, `:whois`, `:error`
+
+### Test Structure
+
+- `test/unit/` - Unit tests mocking the socket layer
+- `test/integration/` - Integration tests against real IRC server (InspIRCd)

data/README.md

@@ -1,39 +1,128 @@
 # Yaic
 
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/yaic`. To experiment with that code, run `bin/console` for an interactive prompt.
+Yet Another IRC Client - A Ruby IRC client library.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add to your Gemfile:
+
+```ruby
+gem "yaic"
+```
 
-Install the gem and add to the application's Gemfile by executing:
+Or install directly:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install yaic
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+## Quick Start
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+require "yaic"
+
+client = Yaic::Client.new(
+  server: "irc.libera.chat",
+  port: 6697,
+  ssl: true,
+  nickname: "mynick",
+  username: "myuser",
+  realname: "My Real Name"
+)
+
+client.on(:message) { |event| puts "#{event.source.nick}: #{event.text}" }
+
+client.connect
+client.join("#ruby")
+client.privmsg("#ruby", "Hello!")
+client.quit
 ```
 
-## Usage
+## Events
 
-TODO: Write usage instructions here
+Subscribe to events with `on`:
 
-## Development
+```ruby
+client.on(:message) { |event| ... }
+client.on(:join) { |event| ... }
+```
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Unsubscribe with `off`:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```ruby
+client.off(:message)
+```
 
-## Contributing
+| Event | Attributes |
+|-------|------------|
+| `:raw` | `message` - Raw IRC message |
+| `:connect` | `server` - Server name |
+| `:disconnect` | - |
+| `:message` | `source`, `target`, `text` |
+| `:notice` | `source`, `target`, `text` |
+| `:join` | `channel`, `user` |
+| `:part` | `channel`, `user`, `reason` |
+| `:quit` | `user`, `reason` |
+| `:kick` | `channel`, `user`, `by`, `reason` |
+| `:nick` | `old_nick`, `new_nick` |
+| `:topic` | `channel`, `topic`, `setter` |
+| `:mode` | `target`, `modes`, `args` |
+| `:names` | `channel`, `users` |
+| `:who` | `channel`, `user`, `host`, `server`, `nick`, `away`, `realname` |
+| `:whois` | `result` (WhoisResult object) |
+| `:error` | `numeric`, `message` |
+
+## Commands
+
+```ruby
+client.connect                    # Connect and register
+client.quit("Goodbye")            # Disconnect with optional message
+
+client.join("#channel")           # Join a channel
+client.join("#channel", "key")    # Join with key
+client.part("#channel")           # Leave a channel
+client.part("#channel", "reason") # Leave with reason
+
+client.privmsg("#channel", "Hi")  # Send message to channel
+client.privmsg("nick", "Hello")   # Send private message
+client.msg("#channel", "Hi")      # Alias for privmsg
+client.notice("#channel", "Info") # Send notice
+
+client.nick("newnick")            # Change nickname
+client.topic("#channel")          # Request topic
+client.topic("#channel", "New")   # Set topic
+client.kick("#channel", "nick")   # Kick user
+client.mode("#channel", "+o", "nick") # Set mode
+
+client.who("#channel")            # WHO query
+client.whois("nick")              # WHOIS query
+client.names("#channel")          # NAMES query
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/yaic.
+## Threading
+
+The client spawns a background thread to read incoming messages. Event handlers are called from this thread. All public methods are thread-safe.
+
+## Channel State
+
+Access joined channels:
+
+```ruby
+client.channels["#ruby"]           # => Channel object
+client.channels["#ruby"].users     # => {"nick" => Set[:op, :voice], ...}
+client.channels["#ruby"].topic     # => "Ruby programming"
+client.channels["#ruby"].modes     # => {:moderated => true, ...}
+```
+
+## Development
+
+```bash
+rake test              # Run all tests
+rake test_unit         # Run unit tests only
+rake test_integration  # Run integration tests (requires IRC server)
+bundle exec standardrb -A  # Run linter
+```
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+MIT License

data/Rakefile

@@ -5,6 +5,14 @@ require "minitest/test_task"
 
 Minitest::TestTask.create
 
+Minitest::TestTask.create(:test_unit) do |t|
+  t.test_globs = ["test/unit/**/*_test.rb", "test/test_yaic.rb"]
+end
+
+Minitest::TestTask.create(:test_integration) do |t|
+  t.test_globs = ["test/integration/**/*_test.rb"]
+end
+
 require "standard/rake"
 
 task default: %i[test standard]

data/devenv.nix

@@ -4,6 +4,7 @@
 
   env = {
     LD_LIBRARY_PATH = "${config.devenv.profile}/lib";
+    RUBOCOP_CACHE_ROOT = "${config.devenv.state}/rubocop_cache";
   };
 
   packages = with pkgs; [