fix(ruby): make platform gems load on Linux and stop building source gem

.github/workflows/publish-rubygems.yml

@@ -46,14 +46,8 @@ jobs:
               exit 1
             fi
           done
-          # Source gem has no platform suffix, e.g. quicknode_sdk-0.1.0.gem
-          if ! ls dist/quicknode_sdk-[0-9]*.gem 2>/dev/null | grep -Ev '(x86_64-linux|aarch64-linux|arm64-darwin)\.gem$' >/dev/null; then
-            echo "Missing source gem (quicknode_sdk-<version>.gem)"
-            ls -la dist/
-            exit 1
-          fi
-          if [ "$gem_count" -ne 4 ]; then
-            echo "Expected 4 gems (3 platform + 1 source), got $gem_count"
+          if [ "$gem_count" -ne 3 ]; then
+            echo "Expected 3 platform gems, got $gem_count"
             ls -la dist/
             exit 1
           fi

.github/workflows/release.yml

@@ -159,7 +159,8 @@ jobs:
             cross: true
             gem_platform: aarch64-linux
           # musl targets are excluded: Rust cdylib is incompatible with musl (no dynamic linker).
-          # Users on musl Linux (e.g. Alpine) will use the source gem which compiles on install.
+          # Users on platforms without a published platform gem (musl Linux, Windows) will get
+          # a normal RubyGems "no compatible platform" error at install time.
           # Placeholder for future macOS support:
           # - target: aarch64-apple-darwin
           #   cross: false
@@ -188,21 +189,23 @@ jobs:
         if: matrix.cross
         run: |
           cargo zigbuild --release -p sdk-ruby --target ${{ matrix.target }}
-          cp target/${{ matrix.target }}/release/libquicknode_sdk.so ruby/lib/quicknode_sdk.so
+          mkdir -p ruby/lib/quicknode_sdk
+          cp target/${{ matrix.target }}/release/libquicknode_sdk.so ruby/lib/quicknode_sdk/quicknode_sdk.so
 
       - name: Build native extension (native)
         if: '!matrix.cross'
         run: |
           cargo build --release -p sdk-ruby
-          cp target/release/libquicknode_sdk.so ruby/lib/quicknode_sdk.so
+          mkdir -p ruby/lib/quicknode_sdk
+          cp target/release/libquicknode_sdk.so ruby/lib/quicknode_sdk/quicknode_sdk.so
 
       - name: Strip debug symbols
         run: |
           if [ "${{ matrix.cross }}" = "true" ]; then
             sudo apt-get install -y llvm
-            llvm-strip ruby/lib/quicknode_sdk.so
+            llvm-strip ruby/lib/quicknode_sdk/quicknode_sdk.so
           else
-            strip ruby/lib/quicknode_sdk.so
+            strip ruby/lib/quicknode_sdk/quicknode_sdk.so
           fi
 
       - name: Build platform gem
@@ -212,17 +215,12 @@ jobs:
             spec = Gem::Specification.load('quicknode_sdk.gemspec')
             spec.platform = Gem::Platform.new('${{ matrix.gem_platform }}')
             spec.extensions = []
-            spec.files += ['lib/quicknode_sdk.so']
+            spec.files += ['lib/quicknode_sdk/quicknode_sdk.so']
             File.write('quicknode_sdk_platform.gemspec', spec.to_ruby)
           "
           gem build quicknode_sdk_platform.gemspec
           rm quicknode_sdk_platform.gemspec
 
-      - name: Build source gem
-        if: matrix.target == 'x86_64-unknown-linux-gnu'
-        working-directory: ruby
-        run: gem build quicknode_sdk.gemspec
-
       - uses: actions/upload-artifact@v4
         with:
           name: ruby-${{ matrix.target }}

.gitignore

@@ -70,5 +70,5 @@ docs/superpowers/
 notes.md
 
 # Ruby native extension (built locally by `just ruby-build`)
-ruby/lib/*.bundle
-ruby/lib/*.so
+ruby/lib/quicknode_sdk/*.bundle
+ruby/lib/quicknode_sdk/*.so

CLAUDE.md

@@ -34,7 +34,7 @@ just node-build                                   # npm install + build + test
 ```bash
 just ruby-build                                   # cargo build + copy .bundle artifact
 ```
-The build compiles `crates/ruby` and copies the resulting `libquicknode_sdk.dylib` to `ruby/lib/quicknode_sdk.bundle` (macOS) or equivalent `.so` on Linux.
+The build compiles `crates/ruby` and copies the resulting `libquicknode_sdk.dylib` to `ruby/lib/quicknode_sdk/quicknode_sdk.bundle` (macOS) or equivalent `.so` on Linux. The native lib lives under `lib/quicknode_sdk/` so `require_relative "quicknode_sdk/quicknode_sdk"` picks the platform extension automatically.
 
 ## Verification
 

Justfile

@@ -15,7 +15,7 @@ node-build:
 
 ruby-build:
   cargo build -p sdk-ruby --release
-  cp target/release/libquicknode_sdk.dylib ruby/lib/quicknode_sdk.bundle
+  cp target/release/libquicknode_sdk.dylib ruby/lib/quicknode_sdk/quicknode_sdk.bundle
 
 # Requires: maturin on PATH (e.g. pipx install maturin or brew install maturin)
 macos-dist-python:
@@ -61,10 +61,11 @@ macos-build-and-publish version:
   just macos-dist-python
   just macos-dist-node
   just macos-dist-ruby
-  # Stage the compiled bundle under ruby/lib so the platform gem picks it up,
+  # Stage the compiled bundle under ruby/lib/quicknode_sdk so the platform gem picks it up,
   # then build the arm64-darwin gem.
-  cp dist/quicknode_sdk.bundle ruby/lib/quicknode_sdk.bundle
-  cd ruby && ruby ../scripts/build-platform-gem.rb arm64-darwin lib/quicknode_sdk.bundle && gem build quicknode_sdk_platform.gemspec && rm quicknode_sdk_platform.gemspec && cd ..
+  mkdir -p ruby/lib/quicknode_sdk
+  cp dist/quicknode_sdk.bundle ruby/lib/quicknode_sdk/quicknode_sdk.bundle
+  cd ruby && ruby ../scripts/build-platform-gem.rb arm64-darwin lib/quicknode_sdk/quicknode_sdk.bundle && gem build quicknode_sdk_platform.gemspec && rm quicknode_sdk_platform.gemspec && cd ..
   mv ruby/*.gem dist/
   gh release upload "v{{version}}" dist/*.whl dist/index.darwin-arm64.node dist/*.gem --clobber
   echo "Uploaded macOS arm64 artifacts to v{{version}}"
@@ -77,7 +78,7 @@ lint:
 
 # Bump version across all manifests, commit, and tag for release.
 # Usage: just release 0.2.0
-release_version:
+release version:
   sed -i.bak 's/^version = ".*"/version = "{{version}}"/' Cargo.toml && rm Cargo.toml.bak
   sed -i.bak 's/^version = ".*"/version = "{{version}}"/' pyproject.toml && rm pyproject.toml.bak
   uv lock

ruby/.solargraph.yml

@@ -1,7 +1,8 @@
 include:
   - "lib/**/*.rb"
 exclude:
-  - "lib/quicknode_sdk.bundle"
+  - "lib/quicknode_sdk/quicknode_sdk.bundle"
+  - "lib/quicknode_sdk/quicknode_sdk.so"
   - "examples/**/*"
 require_paths:
   - lib

ruby/lib/quicknode_sdk.rb

@@ -1,4 +1,4 @@
-require_relative "quicknode_sdk.bundle"
+require_relative "quicknode_sdk/quicknode_sdk"
 require_relative "quicknode_sdk/wrap"
 require_relative "quicknode_sdk/native_delegator"
 require_relative "quicknode_sdk/clients/admin"

ruby/quicknode_sdk.gemspec

@@ -4,7 +4,7 @@ Gem::Specification.new do |s|
   s.summary     = "Quicknode SDK for Ruby"
   s.authors     = ["Quicknode"]
   s.license     = "MIT"
-  s.files       = Dir["lib/**/*.rb"] + Dir["sig/**/*.rbs"] + ["lib/quicknode_sdk.bundle", "README.md"]
+  s.files       = Dir["lib/**/*.rb"] + Dir["sig/**/*.rbs"] + ["README.md"]
   s.required_ruby_version = ">= 3.0"
   s.add_runtime_dependency "hashie", "~> 5.0"
 end

scripts/build-platform-gem.rb

@@ -3,7 +3,7 @@
 # that includes a prebuilt native library. Run from the ruby/ directory.
 #
 # Usage: ruby ../scripts/build-platform-gem.rb <platform> <lib_file>
-# Example: ruby ../scripts/build-platform-gem.rb arm64-darwin lib/quicknode_sdk.bundle
+# Example: ruby ../scripts/build-platform-gem.rb arm64-darwin lib/quicknode_sdk/quicknode_sdk.bundle
 
 platform, lib_file = ARGV
 abort "Usage: build-platform-gem.rb <platform> <lib_file>" unless platform && lib_file