smbcloud-ruby-native-gem

name	smbcloud-ruby-native-gem
description	Use when building, packaging, or publishing smbCloud Ruby gems backed by Rust native extensions through Magnus and rb_sys, especially under sdk/gems/model and sdk/gems/auth. Covers gem layout, path wiring to workspace crates, rake build/compile flows, pkg output, .gitignore conventions, and RubyGems release preflight.

smbCloud Ruby Native Gem

Use this skill when work touches smbCloud Ruby gems that wrap Rust crates through Magnus.

Applies to:

• sdk/gems/model
• sdk/gems/auth
• new gems following the same pattern
• ext/*/Cargo.toml path wiring
• auth.gemspec or model.gemspec
• Rakefile, extconf.rb, lib/*.rb, sig/*.rbs
• local build and RubyGems publish steps

Source of truth

For each gem, inspect these files first:

• sdk/gems/<name>/<name>.gemspec
• sdk/gems/<name>/Rakefile
• sdk/gems/<name>/ext/<name>/Cargo.toml
• sdk/gems/<name>/ext/<name>/extconf.rb
• sdk/gems/<name>/lib/<name>.rb
• sdk/gems/<name>/lib/<name>/version.rb
• sdk/gems/<name>/.gitignore

The Rust crate under crates/ remains the API source of truth. The gem should stay a thin Ruby-facing adapter.

Expected layout

Use the same structure as sdk/gems/model and sdk/gems/auth:

• workspace Cargo.toml at gem root
• native extension crate at ext/<name>
• Ruby entrypoint at lib/<name>.rb
• version file at lib/<name>/version.rb
• type signature file under sig/
• Rakefile using RbSys::ExtensionTask
• extconf.rb using create_rust_makefile

Do not invent a different packaging layout unless there is a strong reason.

Cargo path wiring

Be careful with relative paths from sdk/gems/<name>/ext/<name>/Cargo.toml to workspace crates.

From that directory, crates/... is typically five levels up:

• ./../../../../../crates/<crate-name>

Do not assume four levels. Verify the actual path before building.

Ruby API design

Keep the gem framework-agnostic.

Preferred layering:

1. Rust crate owns transport and domain logic
2. native Magnus extension bridges into Ruby
3. plain Ruby wrapper exposes the public API

For reusable SDKs, prefer a client object such as:

• SmbCloud::Auth::Client.new(...)

Keep Rails-specific helpers, sessions, and controller concerns out of the core gem. If needed later, create a separate Rails adapter gem.

Build workflow

Use the standard rake tasks.

From sdk/gems/<name>:

• bundle install
• bundle exec rake compile
• bundle exec rake build

Expected behavior:

• native build output goes under target/
• packaged gem goes under pkg/

For Rust-only verification, also use:

• cargo check
• cargo fmt --manifest-path ext/<name>/Cargo.toml

Prefer formatting the extension crate directly if the parent workspace has unrelated manifest issues.

.gitignore conventions

Match the sdk/gems/model pattern.

Ignore:

• /.bundle/
• /pkg/
• /tmp/
• target/
• *.bundle
• native object outputs such as *.so, *.o, *.a
• mkmf.log

Do not track built .gem artifacts in git. They belong in pkg/ and should be ignored.

Release preflight

Before publishing:

1. confirm the version in lib/<name>/version.rb
2. build the gem with bundle exec rake build
3. verify the artifact exists in pkg/
4. inspect warnings from gem build or rake build
5. confirm RubyGems credentials exist

Credentials can come from either:

• ~/.gem/credentials
• GEM_HOST_API_KEY

Without one of those, gem push will fail.

Publish

From sdk/gems/<name>:

• bundle exec gem push pkg/<name>-<version>.gem

Do not claim a publish succeeded unless the push completed successfully.

Common mistakes

• wrong relative path from ext/<name>/Cargo.toml to crates/...
• exposing Ruby methods that the native extension does not actually export
• putting release artifacts in git
• making the gem Rails-specific when the crate should stay generic
• using gem build ad hoc while ignoring the repo's rake build and pkg/ convention
• attempting gem push without RubyGems credentials configured