Implement initial API

Author: rafaelfranca

README.md

@@ -7,12 +7,86 @@ need to activate the Ruby environment in order to launch Ruby executables, such
 
 ## Features
 
-TODO: this extension is getting extracted from the Ruby LSP.
+- **Automatic Ruby detection**: Discovers the Ruby interpreter installed on your machine
+- **Version manager integrations**: Supports popular version managers including:
+  - [chruby](https://github.com/postmodern/chruby)
+  - [rbenv](https://github.com/rbenv/rbenv)
+  - [rvm](https://rvm.io/)
+  - [asdf](https://asdf-vm.com/) (with ruby plugin)
+  - [mise](https://mise.jdx.dev/)
+- **Environment activation**: Composes the correct environment variables (`PATH`, `GEM_HOME`, `GEM_PATH`, etc.) to match your shell configuration
+- **JIT detection**: Identifies available JIT compilers (YJIT, ZJIT) for the activated Ruby version
+- **Shell support**: Works with various shells including bash, zsh, fish, and PowerShell
+- **Extension API**: Provides a programmatic API for other extensions to access the activated Ruby environment
 
 ## Extension Settings
 
 TODO
 
 ## API
 
-TODO
+This extension exposes an API that other extensions can use to access the activated Ruby environment.
+
+### Getting the API
+
+```typescript
+const rubyEnvExtension = vscode.extensions.getExtension("Shopify.ruby-environments");
+
+if (rubyEnvExtension) {
+  const api = rubyEnvExtension.exports;
+  // Use the API...
+}
+```
+
+### Activating the Ruby Environment
+
+Request the extension to activate Ruby for a specific workspace:
+
+```typescript
+api.activate(vscode.workspace.workspaceFolders?.[0]);
+```
+
+### Getting the Current Ruby Definition
+
+Retrieve the currently activated Ruby environment:
+
+```typescript
+const ruby = api.getRuby();
+
+if (ruby === null) {
+  console.log("Ruby environment not yet activated");
+} else if (ruby.error) {
+  console.log("Ruby activation failed");
+} else {
+  console.log(`Ruby version: ${ruby.rubyVersion}`);
+  console.log(`Available JITs: ${ruby.availableJITs.join(", ")}`);
+  console.log(`GEM_PATH: ${ruby.gemPath.join(":")}`);
+}
+```
+
+### Subscribing to Ruby Environment Changes
+
+Listen for changes to the Ruby environment (e.g., when the user switches Ruby versions):
+
+```typescript
+const disposable = api.onDidRubyChange((event) => {
+  console.log(`Ruby changed in workspace: ${event.workspace?.name}`);
+
+  if (!event.ruby.error) {
+    console.log(`New Ruby version: ${event.ruby.rubyVersion}`);
+  }
+});
+
+// Add to your extension's subscriptions for automatic cleanup
+context.subscriptions.push(disposable);
+```
+
+### Extension Dependency
+
+To ensure your extension loads after Ruby Environments, add it as a dependency in your `package.json`:
+
+```json
+{
+  "extensionDependencies": ["Shopify.ruby-environments"]
+}
+```

src/extension.ts

@@ -1,11 +1,68 @@
 import * as vscode from "vscode";
 
-// The public API that gets exposed to other extensions that depend on Ruby environments
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-interface RubyEnvironmentsApi {}
+/**
+ * Represents a Ruby environment that failed to activate
+ */
+export interface RubyError {
+  error: true;
+}
+
+/**
+ * JIT compiler types supported by Ruby
+ */
+export enum JitType {
+  YJIT = "YJIT",
+  ZJIT = "ZJIT",
+}
+
+/**
+ * Represents a successfully activated Ruby environment
+ */
+export interface RubyEnvironment {
+  error: false;
+  rubyVersion: string;
+  availableJITs: JitType[];
+  env: NodeJS.ProcessEnv;
+  gemPath: string[];
+}
+
+/**
+ * Represents a Ruby environment definition - either an error or a successful environment
+ */
+export type RubyDefinition = RubyError | RubyEnvironment;
+
+/**
+ * Event data emitted when the Ruby environment changes
+ */
+export interface RubyChangeEvent {
+  workspace: vscode.WorkspaceFolder | undefined;
+  ruby: RubyDefinition;
+}
+
+/**
+ * The public API that gets exposed to other extensions that depend on Ruby environments
+ */
+export interface RubyEnvironmentsApi {
+  /** Activate the extension for a specific workspace */
+  activate: (workspace: vscode.WorkspaceFolder | undefined) => void;
+  /** Get the current Ruby definition */
+  getRuby: () => RubyDefinition | null;
+  /** Event that fires when the Ruby environment changes */
+  onDidRubyChange: vscode.Event<RubyChangeEvent>;
+}
+
+// Event emitter for Ruby environment changes
+const rubyChangeEmitter = new vscode.EventEmitter<RubyChangeEvent>();
+
+export function activate(context: vscode.ExtensionContext): RubyEnvironmentsApi {
+  // Ensure the event emitter is disposed when the extension is deactivated
+  context.subscriptions.push(rubyChangeEmitter);
 
-export function activate(_context: vscode.ExtensionContext): RubyEnvironmentsApi {
-  return {};
+  return {
+    activate: (_workspace: vscode.WorkspaceFolder | undefined) => {},
+    getRuby: () => null,
+    onDidRubyChange: rubyChangeEmitter.event,
+  };
 }
 
 export function deactivate() {}

src/test/extension.test.ts

@@ -1,7 +1,32 @@
 import * as assert from "assert";
+import * as vscode from "vscode";
+import { activate, deactivate } from "../extension";
 
 suite("Extension Test Suite", () => {
-  test("Sample test", () => {
-    assert.strictEqual(1 + 1, 2);
+  suite("activate", () => {
+    test("returns an API object with activate and getRuby methods", () => {
+      const mockContext = {} as vscode.ExtensionContext;
+      const api = activate(mockContext);
+
+      assert.ok(api, "API should be defined");
+      assert.strictEqual(typeof api.activate, "function", "activate should be a function");
+      assert.strictEqual(typeof api.getRuby, "function", "getRuby should be a function");
+    });
+
+    test("multiple activate calls return independent API instances", () => {
+      const mockContext = {} as vscode.ExtensionContext;
+      const api1 = activate(mockContext);
+      const api2 = activate(mockContext);
+
+      assert.notStrictEqual(api1, api2, "Each activate call should return a new API instance");
+    });
+  });
+
+  suite("deactivate", () => {
+    test("can be called without errors", () => {
+      assert.doesNotThrow(() => {
+        deactivate();
+      }, "deactivate should not throw errors");
+    });
   });
 });