✨ Add Ruby Client SDK

[Robdel12]

Summary

Adds a fully-featured Ruby client SDK for Vizzly with auto-discovery, comprehensive testing, and AI-powered release workflow.

What's Included

Ruby Client SDK (clients/ruby/)

• Zero dependencies - Uses only Ruby stdlib (Net::HTTP, JSON, Base64)
• Auto-discovery - Automatically finds running TDD server via .vizzly/server.json
• Full HTTP API support - Matches JavaScript client behavior exactly
• Comprehensive tests - Unit tests + integration tests against CLI
• RuboCop linting - Follows Ruby best practices

CI/CD Integration

• Tests against Ruby 3.0, 3.1, 3.2, 3.3
• Runs RuboCop linting
• Integration tests with CLI server

AI-Powered Release Workflow

• Manual workflow_dispatch trigger with version bump (patch/minor/major)
• Claude AI generates intelligent changelogs by analyzing commits
• Auto-bumps version in gemspec
• Updates CHANGELOG.md
• Creates namespaced git tags (ruby/vX.X.X)
• Publishes to RubyGems
• Creates GitHub releases

Documentation

• Updated build-your-own-sdk.md with accurate API contract
• Added auto-discovery documentation
• Practical RSpec examples

JS Client Cleanup

• Removed unused variant parameter from API

Usage

require 'vizzly'

# Basic usage
image_data = File.binread('screenshot.png')
Vizzly.screenshot('homepage', image_data)

# With properties
Vizzly.screenshot('checkout', image_data,
  properties: { browser: 'chrome', viewport: { width: 1920, height: 1080 } },
  threshold: 5
)

Release Process

Trigger via GitHub Actions:

1. Actions → Release Ruby Client → Run workflow
2. Select version bump type (patch/minor/major)
3. Workflow handles everything automatically

Testing

cd clients/ruby
bundle install
bundle exec rubocop    # Lint
ruby -I lib test/vizzly_test.rb  # Unit tests
VIZZLY_INTEGRATION=1 ruby -I lib test/integration_test.rb  # Integration tests

Files Changed

• clients/ruby/ - New Ruby client implementation
• .github/workflows/ci.yml - Added Ruby client CI
• .github/workflows/release-ruby-client.yml - New release workflow
• src/client/index.js - Removed unused variant parameter
• Documentation updates in vizzly-docs repo

🚀 Ready for first release!

[claude]

Pull Request Review: Ruby Client SDK

Overview

This is an excellent addition to the Vizzly ecosystem! The Ruby client is well-architected, thoroughly tested, and follows Ruby best practices. The AI-powered release workflow is innovative and well-designed.

✅ Strengths

Code Quality

• Clean architecture: The client implementation mirrors the JavaScript client effectively, maintaining API consistency
• Zero dependencies: Using only Ruby stdlib (Net::HTTP, JSON, Base64) keeps the gem lightweight
• Excellent error handling: Graceful degradation with auto-disable on failure prevents test spam
• Well-documented: Comprehensive YARD documentation with clear examples
• Ruby conventions: Follows Ruby naming conventions (snake_case methods, proper module structure)

Testing

• Comprehensive test coverage: Unit tests cover all major functionality (auto-discovery, environment config, client states)
• Integration tests: Real-world testing against the CLI server validates end-to-end functionality
• Test isolation: Proper setup/teardown with temp directories ensures clean test runs
• Multi-Ruby testing: CI tests against Ruby 3.0-3.3 ensure broad compatibility

Release Workflow

• Innovative approach: AI-generated changelogs are a creative solution for monorepo releases
• Secure credentials: Proper handling of RubyGems API key and git credentials
• Proper permissions: Minimal contents:write and id-token:write permissions
• Namespace tags: Using ruby/vX.X.X pattern prevents conflicts in monorepo

---

🔍 Issues & Recommendations

Critical

1. Workflow Security: Hardcoded Commit Push (.github/workflows/release-ruby-client.yml:131)

The workflow pushes directly to main without protection. This bypasses any branch protection rules.

Recommendation: Add a check to verify the release was triggered from main branch, or use a pull request workflow instead.

2. Version Parsing Edge Case (.github/workflows/release-ruby-client.yml:51)

Bash array splitting may fail with non-standard versions. Doesn't validate version format or handle pre-release versions.

Recommendation: Add version format validation before processing.

High Priority

3. Missing Error Handling in Changelog Step (.github/workflows/release-ruby-client.yml:68-104)

The Claude Code action might fail, but the workflow continues without checking if CHANGELOG-RELEASE.md was created.

Recommendation: Add validation step with fallback content if changelog generation fails.

4. HTTP Connection Not Closed (clients/ruby/lib/vizzly.rb:62-70)

The Net::HTTP connection is created but never explicitly closed, which could lead to resource leaks.

Recommendation: Use Net::HTTP.start with a block form to ensure connection cleanup.

5. Potential Race Condition in Integration Tests (clients/ruby/test/integration_test.rb:82-87)

Polling for server readiness uses fixed retry count (3 seconds total). On slower CI systems, this might not be enough.

Recommendation: Increase timeout to 10 seconds or add actual server health check.

Medium Priority

6. Inconsistent Error Re-raising Logic (clients/ruby/lib/vizzly.rb:107-109)

The error re-raising check uses string matching which is brittle.

Recommendation: Use a custom VisualDiffError exception class for cleaner error handling.

7. Missing HTTPS Support (clients/ruby/lib/vizzly.rb:61-62)

The client doesn't handle HTTPS URLs properly.

Recommendation: Add http.use_ssl support based on uri.scheme.

8. Module-Level State Not Thread-Safe (clients/ruby/lib/vizzly.rb:220-252)

The shared client instance is not thread-safe in multi-threaded test environments.

Recommendation: Use thread-local storage or document the limitation.

Low Priority

9. Magic Numbers (clients/ruby/lib/vizzly.rb:88, 207)

Port 47392 is hardcoded. Extract to DEFAULT_TDD_PORT constant.

10. Gemspec Metadata

Consider adding bug_tracker_uri and documentation_uri for better RubyGems integration.

---

🎯 Summary

This is high-quality, production-ready code. The implementation shows strong understanding of Ruby idioms, excellent test coverage, and thoughtful error handling.

Recommended Actions Before Merge

1. Fix HTTP connection cleanup (issue 🔥 Remove deprecated utilities and types #4) - prevents resource leaks
2. Add version validation in release workflow (issue ♻️ Run lint before tests #2) - prevents invalid releases
3. Document branch protection requirements (issue ✨ Add npmignore file, reduce release size #1)
4. Add fallback for changelog generation (issue ♻️ Refactor server architecture with new handlers #3)

The other issues are minor improvements that can be addressed in follow-up PRs.

Recommendation: Approve with minor changes 🚀