Initial API proposal for Ruby Environments extension

[rafaelfranca]

Summary

This PR proposes the initial API design for the Ruby Environments VS Code extension. The goal is to establish the public interface that other extensions (like Ruby LSP) will use to obtain activated Ruby environments.

This is an API proposal focused on design and discussion—not a full feature implementation. The actual version manager integrations and environment detection logic will be added in subsequent PRs.

Proposed Public API

• activate(workspace): Request Ruby environment activation for a specific workspace
• getRuby(): Retrieve the current Ruby definition (success or error state)
• onDidRubyChange: Event to subscribe to Ruby environment changes

Type Definitions

• RubyEnvironment: Represents a successfully activated Ruby (version, JIT compilers, env vars, gem paths)
• RubyError: Represents a failed activation
• RubyDefinition: Union type for success/error states
• RubyChangeEvent: Event payload for environment changes
• JitType: Enum for supported JIT compilers (YJIT, ZJIT)

Next Steps

Once the API design is agreed upon:

• Implement version manager integrations (chruby, rbenv, asdf, mise, rvm)
• Add status bar integration
• Implement configuration watchers

[vinistock]

What do you think about breaking this down into smaller chunks? If we have bandwidth to design the API, let's do it step by step and make sure we avoid shortcomings of the current implementation.

For example:

• Better callbacks for when re-activation will happen
• Better ways to handle error scenarios gracefully (one of the biggest pain points of the LSP)
• Clearer status communication about degraded status or what caused failures to help users debug their setup

I think it will be easier if we discuss each step one by one

[rafaelfranca]

• Allow users to configure a Ruby path #11 : 2 dependent PRs (#10 , #12 )
• Initial API proposal for Ruby Environments extension #9 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[rafaelfranca]

Done. I broke the PR in multiple stacks. This is the API proposal now

[vinistock]

Do we need a package just for the types? From what I can tell, it's more common for VS Code extensions that export an API to just tell users to copy a d.ts file with the license written on top.

It's easier than maintaining an extra dependency.

[rafaelfranca]

I debated that but copying code can cause a lot of problems. The dependency only has types, and releasing is as easy as the publish.yml workflow.

It also make easier for consumers to know which version of the extension will work with the API they are trying to console since the type definition library version will match the version of the extension.

[vinistock]

Instead of having a getRuby function, how about we return the Ruby object from the activate call?

We can cache the Ruby objects internally in the extension by workspace URI, so that multiple extensions requesting it don't produce different objects.

[rafaelfranca]

I think we can do that. Take a look at https://app.graphite.com/github/pr/Shopify/ruby-environments/12/Support-multiple-workspace-folders-with-independent-Ruby-environments. It supports multiple workspace folders, and a new method to activate the workspace fodler was added. We can change it to return the Ruby object and remove the getRuby(). What do you think?