ripgrep_wasm 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48e7d7bd34377c527f6b51b649ac6e997f058d0a2d8135c590650fb16c986489
-  data.tar.gz: dd19a052210eba94d85fbe5e46d703a6ce6d8a339e59256410fc5cce389bb656
+  metadata.gz: 4b2cecf649bbb67e17109c6a368898b8aa036800961105dbd558191dd4ec5572
+  data.tar.gz: 3565f9f98ac34d4c5fa79a0442166a09a6b3384b83f1e78410bd68abf94667c1
 SHA512:
-  metadata.gz: 3c5dcb66c0aa34f49d0eb379e92984ef20e99f3c00220eb493cd40aed75cd58c4eeebdd0e0555c18ea65aa2c5a3699b2568076375f7c626245eb0a913de0cf7a
-  data.tar.gz: 81934964911d5905b6cf5ca727de8902a440e7af00e0d447d18d8121771b28d7523e55bb2f56e267b609e5a0a3964d0164b41ad605e105292d47fa3fd8fcecb6
+  metadata.gz: 51dc1c74814dc460ebecc8e00b539dc41a374b88eb576dc439a15fd7f33ceb92412c8237e0c5caf6d286eb4dfbc5443b4b17111011fb2f5c732656a060cce31e
+  data.tar.gz: d4b4f371a071cc039449270ac1b481422b4d3aeea0bcb2b61c87b3ad7af3412c2fbca9f9d2e6619d22a582af29147ec8bbc3d45196c6fd8e0a34354ab6c71b5e

data/AGENTS.md

@@ -0,0 +1,395 @@
+# AGENTS.md — Guidelines for WASM Binary Wrapper Ruby Gems
+
+This document describes the architecture and conventions for Ruby gems that wrap a
+WebAssembly binary (executed via a WASI runtime like wasmtime). It is meant to be
+copied and adapted for each new gem of this kind.
+
+---
+
+## 1. Naming Conventions
+
+| Concept | Convention | Example |
+|---------|-----------|---------|
+| Gem name | `<tool>_wasm` (snake_case) | `pandoc_wasm` |
+| Module name | `<Tool>Wasm` (PascalCase) | `PandocWasm` |
+| Binary asset | `<tool>.wasm` | `pandoc.wasm` |
+| GitHub repo | `<owner>/<tool>-wasm` | `NathanHimpens/pandoc-wasm` |
+
+---
+
+## 2. File Layout
+
+```
+lib/
+  <tool>_wasm.rb              # Main entry point — module configuration + public API
+  <tool>_wasm/
+    version.rb                # VERSION constant
+    downloader.rb             # Downloads the .wasm binary from GitHub Releases
+    runner.rb                 # Wraps the WASI runtime system call
+test/
+  test_helper.rb              # Minitest bootstrap + module state reset helper
+  <tool>_wasm_test.rb         # Tests for main module (config, delegation, introspection)
+  runner_test.rb              # Tests for Runner (command building, errors, result)
+  downloader_test.rb          # Tests for Downloader (signature, errors, path expansion)
+  integration_test.rb         # Full user workflow scenario (configure, download, run)
+<tool>_wasm.gemspec           # Gem specification
+Rakefile                      # rake test runs test/**/*_test.rb via Minitest
+AGENTS.md                     # This file — reusable guidelines
+```
+
+---
+
+## 3. Public API Contract
+
+Every gem MUST expose exactly these public methods on the top-level module:
+
+### Configuration
+
+```ruby
+# Get / set the absolute path where the .wasm binary lives.
+# Defaults to lib/<tool>_wasm/<tool>.wasm inside the installed gem.
+<Tool>Wasm.binary_path            # => String
+<Tool>Wasm.binary_path = "/path"  # setter
+
+# Get / set the WASI runtime executable name.
+# Defaults to "wasmtime".
+<Tool>Wasm.runtime                # => String
+<Tool>Wasm.runtime = "wasmer"     # setter
+```
+
+### Download
+
+```ruby
+# Download the .wasm binary from the latest GitHub Release to `binary_path`.
+# Creates intermediate directories if needed.
+# Returns true on success, raises on failure.
+<Tool>Wasm.download_to_binary_path!
+```
+
+### Execution
+
+```ruby
+# Run the wasm binary. All positional arguments are passed through to the binary.
+# Translates to:
+#   <runtime> run --dir <wasm_dir> <binary_path> <args...>
+#
+# Returns a Hash: { stdout: String, stderr: String, success: Boolean }
+# Raises BinaryNotFound if the binary is missing at binary_path.
+# Raises ExecutionError (with stderr) on non-zero exit code.
+<Tool>Wasm.run(*args, wasm_dir: ".")
+```
+
+### Introspection
+
+```ruby
+# Returns true if the binary exists at binary_path.
+<Tool>Wasm.available?
+```
+
+---
+
+## 4. Error Classes
+
+Define these inside the module:
+
+```ruby
+module <Tool>Wasm
+  class Error < StandardError; end
+  class BinaryNotFound < Error; end
+  class ExecutionError < Error; end
+end
+```
+
+- `BinaryNotFound` — raised when `run` is called but the binary does not exist.
+- `ExecutionError` — raised when the WASI runtime exits with a non-zero status.
+  The error message MUST include the stderr output.
+
+---
+
+## 5. Module Implementation Pattern
+
+The main module file (`lib/<tool>_wasm.rb`) must follow this structure:
+
+```ruby
+# frozen_string_literal: true
+
+require_relative '<tool>_wasm/version'
+require_relative '<tool>_wasm/downloader'
+require_relative '<tool>_wasm/runner'
+
+module <Tool>Wasm
+  class Error < StandardError; end
+  class BinaryNotFound < Error; end
+  class ExecutionError < Error; end
+
+  DEFAULT_BINARY_PATH = File.join(File.dirname(__FILE__), '<tool>_wasm', '<tool>.wasm').freeze
+
+  class << self
+    attr_writer :binary_path, :runtime
+
+    def binary_path
+      @binary_path || DEFAULT_BINARY_PATH
+    end
+
+    def runtime
+      @runtime || 'wasmtime'
+    end
+
+    def download_to_binary_path!
+      Downloader.download(to: binary_path)
+    end
+
+    def run(*args, wasm_dir: '.')
+      Runner.run(*args, wasm_dir: wasm_dir)
+    end
+
+    def available?
+      File.exist?(binary_path)
+    end
+  end
+end
+```
+
+---
+
+## 6. Downloader Implementation Pattern
+
+The downloader (`lib/<tool>_wasm/downloader.rb`) must:
+
+1. Accept a `to:` keyword argument — the absolute path where the binary will be written.
+2. Fetch the latest release tag from the GitHub API (`/repos/:owner/:repo/releases/latest`).
+3. Find the asset named `<tool>.wasm` in the release.
+4. Stream-download the asset to the target path.
+5. `chmod 0755` the downloaded file.
+6. Create intermediate directories with `FileUtils.mkdir_p`.
+7. Clean up partial files on failure (`FileUtils.rm_f`).
+8. Use only Ruby stdlib (`net/http`, `json`, `fileutils`, `uri`) — no external dependencies.
+
+Constants to adapt per gem:
+
+```ruby
+REPO_OWNER = '<github_owner>'
+REPO_NAME  = '<tool>-wasm'
+ASSET_NAME = '<tool>.wasm'
+```
+
+---
+
+## 7. Runner Implementation Pattern
+
+The runner (`lib/<tool>_wasm/runner.rb`) must:
+
+1. Use `Open3.capture3` for proper stdout/stderr/status capture.
+2. Build the command array (NOT a shell string) for safety:
+   ```ruby
+   cmd = [
+     <Tool>Wasm.runtime,
+     'run',
+     '--dir', wasm_dir,
+     <Tool>Wasm.binary_path,
+     *args
+   ]
+   ```
+3. Raise `BinaryNotFound` before executing if `binary_path` does not exist.
+4. Raise `ExecutionError` with stderr content if exit status is non-zero.
+5. Return `{ stdout:, stderr:, success: }` on success.
+
+---
+
+## 8. Gemspec Conventions
+
+- `required_ruby_version >= 2.7.0`
+- No external runtime dependencies — only Ruby stdlib.
+- Use `git ls-files` to determine included files; exclude build artifacts, tests,
+  CI configs, patches, and agent working directories.
+- Include a `post_install_message` explaining that the .wasm binary will be
+  downloaded on first use or via `download_to_binary_path!`.
+
+---
+
+## 9. Adapting for a New Binary
+
+To create a new gem for a different WASM binary:
+
+1. Copy the `lib/` directory structure.
+2. Rename all files: replace `pandoc_wasm` with `<tool>_wasm`.
+3. Rename the module: replace `PandocWasm` with `<Tool>Wasm`.
+4. Update these constants in `downloader.rb`:
+   - `REPO_OWNER`
+   - `REPO_NAME`
+   - `ASSET_NAME`
+5. Update `version.rb` with the new gem version.
+6. Update the gemspec metadata (name, description, homepage, etc.).
+7. If the WASI runtime needs additional flags (e.g. `--mapdir`, `--env`),
+   add them as configurable options on the module and pass them through in the runner.
+
+---
+
+## 10. Testing Strategy
+
+Tests use **Minitest** (stdlib, no extra dependency) and run with `rake test`.
+The Rakefile expects `test/**/*_test.rb`.
+
+### 10.1 Test Helper — Module State Reset
+
+Because the module stores configuration in instance variables (`@binary_path`,
+`@runtime`), every test file MUST include a helper that saves and restores state:
+
+```ruby
+# test/test_helper.rb
+require 'minitest/autorun'
+require 'tmpdir'
+require 'fileutils'
+require_relative '../lib/<tool>_wasm'
+
+module <Tool>WasmTestHelper
+  def setup
+    @original_binary_path = <Tool>Wasm.instance_variable_get(:@binary_path)
+    @original_runtime     = <Tool>Wasm.instance_variable_get(:@runtime)
+  end
+
+  def teardown
+    <Tool>Wasm.instance_variable_set(:@binary_path, @original_binary_path)
+    <Tool>Wasm.instance_variable_set(:@runtime,     @original_runtime)
+  end
+end
+```
+
+Every test class includes it: `include <Tool>WasmTestHelper`.
+
+### 10.2 Stubbing Conventions
+
+- **Runner tests**: Stub `Open3.capture3` with a lambda to capture the command
+  array without actually executing anything. Return `[stdout, stderr, status]`
+  where `status` is a `Minitest::Mock` responding to `success?` (and
+  `exitstatus` on the failure path).
+- **Downloader tests**: Stub the private class methods `get_latest_release_tag`
+  and `download_asset` to avoid real HTTP calls.
+- **Main module tests**: Stub `Downloader.download` and `Runner.run` to verify
+  delegation without side effects.
+
+### 10.3 Fake Binary Pattern
+
+When a test needs the binary to exist (Runner tests), create a temp file:
+
+```ruby
+Dir.mktmpdir do |dir|
+  binary = File.join(dir, '<tool>.wasm')
+  File.write(binary, 'fake')
+  <Tool>Wasm.binary_path = binary
+  # ... test logic ...
+end
+```
+
+### 10.4 Test Checklist
+
+When modifying or creating a gem of this type, the test suite MUST cover:
+
+**Main module (`test/<tool>_wasm_test.rb`)**:
+- [ ] `binary_path` returns the default path when not configured
+- [ ] `binary_path =` overrides the path
+- [ ] `runtime` returns `"wasmtime"` by default
+- [ ] `runtime =` overrides the runtime
+- [ ] `available?` returns `false` when binary is missing
+- [ ] `available?` returns `true` when binary exists
+- [ ] Error class hierarchy: `BinaryNotFound < Error < StandardError`
+- [ ] `VERSION` matches semver format
+- [ ] `download_to_binary_path!` delegates to `Downloader.download(to: binary_path)`
+- [ ] `run` delegates to `Runner.run` with all arguments forwarded
+
+**Runner (`test/runner_test.rb`)**:
+- [ ] Raises `BinaryNotFound` when binary does not exist
+- [ ] Builds the correct command array: `[runtime, "run", "--dir", wasm_dir, binary, *args]`
+- [ ] Uses the configured `runtime` in the command
+- [ ] Returns `{ stdout:, stderr:, success: true }` on success
+- [ ] Raises `ExecutionError` with exit status and stderr on failure
+- [ ] Defaults `wasm_dir` to `"."`
+
+**Downloader (`test/downloader_test.rb`)**:
+- [ ] Constants `REPO_OWNER`, `REPO_NAME`, `ASSET_NAME` are defined
+- [ ] `download` method accepts the `to:` keyword argument
+- [ ] `download` raises on network error (re-raises after warning)
+- [ ] `download` expands the target path via `File.expand_path`
+- [ ] `download` returns `true` on success
+
+**Integration (`test/integration_test.rb`)**:
+- [ ] Full workflow: configure -> download -> available? -> run succeeds
+- [ ] Run before download raises `BinaryNotFound`
+
+### 10.5 Integration Test Pattern
+
+Every gem MUST include an integration test (`test/integration_test.rb`) that
+simulates the complete user journey in a single scenario. This ensures the
+public API methods compose correctly end-to-end.
+
+The test walks through these steps in order:
+
+1. **Configure** -- set `binary_path` to a temp directory and `runtime` to a
+   non-default value (e.g. `"wazero"`) to prove configuration is respected.
+2. **Assert not available** -- `available?` returns `false` before download.
+3. **Download** -- call `download_to_binary_path!` (stub `Downloader.download`
+   to write a fake file to the `to:` path).
+4. **Assert available** -- `available?` returns `true` after download.
+5. **Run** -- call `run(*args, wasm_dir:)` (stub `Open3.capture3`), then
+   inspect the captured command array to verify:
+   - `cmd[0]` is the configured runtime
+   - `cmd[4]` is the configured `binary_path`
+   - `cmd[5..]` matches the args passed in.
+
+A second scenario verifies that calling `run` before downloading raises
+`BinaryNotFound`.
+
+```ruby
+class IntegrationTest < Minitest::Test
+  include <Tool>WasmTestHelper
+
+  def test_full_user_workflow
+    Dir.mktmpdir do |dir|
+      target = File.join(dir, '<tool>.wasm')
+
+      # 1. Configure
+      <Tool>Wasm.binary_path = target
+      <Tool>Wasm.runtime = 'wazero'
+
+      # 2. Not available yet
+      refute <Tool>Wasm.available?
+
+      # 3. Download (stub writes fake file)
+      <Tool>Wasm::Downloader.stub(:download, ->(to:) { File.write(to, 'fake'); true }) do
+        <Tool>Wasm.download_to_binary_path!
+      end
+
+      # 4. Now available
+      assert <Tool>Wasm.available?
+
+      # 5. Run (stub Open3, capture command)
+      captured_cmd = nil
+      fake_capture3 = lambda do |*cmd|
+        captured_cmd = cmd
+        status = Minitest::Mock.new
+        status.expect(:success?, true)
+        ['', '', status]
+      end
+
+      Open3.stub(:capture3, fake_capture3) do
+        result = <Tool>Wasm.run('-o', 'output.pptx', 'input.md', wasm_dir: dir)
+        assert result[:success]
+      end
+
+      # 6. Verify command shape
+      assert_equal 'wazero', captured_cmd[0]
+      assert_equal target, captured_cmd[4]
+      assert_equal ['-o', 'output.pptx', 'input.md'], captured_cmd[5..]
+    end
+  end
+
+  def test_run_before_download_raises_binary_not_found
+    Dir.mktmpdir do |dir|
+      <Tool>Wasm.binary_path = File.join(dir, '<tool>.wasm')
+      assert_raises(<Tool>Wasm::BinaryNotFound) do
+        <Tool>Wasm.run('-o', 'output.pptx', 'input.md', wasm_dir: dir)
+      end
+    end
+  end
+end
+```

data/README.md

@@ -25,10 +25,76 @@ console.log(rgWasmPath); // Path to rg.wasm
 gem install ripgrep_wasm
 ```
 
+Or add it to your `Gemfile`:
+
+```ruby
+gem 'ripgrep_wasm'
+```
+
+#### Quick Start
+
 ```ruby
 require 'ripgrep_wasm'
-puts RipgrepWasm.path      # Path to rg.wasm
-puts RipgrepWasm.available? # true if binary exists
+
+# Download the WASM binary (first time only)
+RipgrepWasm.download_to_binary_path!
+
+# Search for a pattern in the current directory
+result = RipgrepWasm.run('-i', 'TODO', '.')
+puts result[:stdout]
+```
+
+#### Configuration
+
+```ruby
+# Get / set the path where rg.wasm is stored
+RipgrepWasm.binary_path              # => ".../lib/ripgrep_wasm/rg.wasm" (default)
+RipgrepWasm.binary_path = "/opt/wasm/rg.wasm"
+
+# Get / set the WASI runtime executable
+RipgrepWasm.runtime                  # => "wasmtime" (default)
+RipgrepWasm.runtime = "wasmer"
+```
+
+#### Download
+
+```ruby
+# Downloads rg.wasm from the latest GitHub Release to binary_path.
+# Creates intermediate directories if needed.
+# Returns true on success, raises on failure.
+RipgrepWasm.download_to_binary_path!
+```
+
+#### Execution
+
+```ruby
+# Run ripgrep. All arguments are forwarded to the binary.
+# wasm_dir controls which directory the WASI sandbox can access (default ".").
+result = RipgrepWasm.run('-n', 'pattern', 'src/', wasm_dir: '.')
+# => { stdout: "src/main.rb:12:  pattern found\n", stderr: "", success: true }
+
+puts result[:stdout]
+```
+
+#### Introspection
+
+```ruby
+RipgrepWasm.available?  # => true if rg.wasm exists at binary_path
+```
+
+#### Error Handling
+
+```ruby
+begin
+  RipgrepWasm.run('pattern', 'file.txt')
+rescue RipgrepWasm::BinaryNotFound => e
+  # rg.wasm is missing -- download it first
+  RipgrepWasm.download_to_binary_path!
+  retry
+rescue RipgrepWasm::ExecutionError => e
+  # Non-zero exit from the runtime (e.g. no matches, bad args)
+  warn e.message  # includes stderr output
+end
 ```
 
 ### Manual

data/lib/ripgrep_wasm/downloader.rb

@@ -10,32 +10,23 @@ module RipgrepWasm
     REPO_OWNER = 'NathanHimpens'
     REPO_NAME = 'ripgrep-wasm'
     ASSET_NAME = 'rg.wasm'
-    
-    def self.wasm_path
-      File.join(File.dirname(__FILE__), ASSET_NAME)
-    end
 
-    # Download rg.wasm from GitHub Releases if it doesn't exist
-    def self.download_if_needed
-      return if File.exist?(wasm_path)
-      
-      puts "rg.wasm not found. Attempting to download from GitHub Releases..."
-      download
-    end
+    # Download rg.wasm from the latest GitHub release.
+    #
+    # @param to [String] absolute path where the binary will be written
+    # @return [true] on success
+    # @raise [StandardError] on network or API errors
+    def self.download(to:)
+      target = File.expand_path(to)
+      FileUtils.mkdir_p(File.dirname(target))
 
-    # Download rg.wasm from the latest GitHub release
-    def self.download
       begin
         tag = get_latest_release_tag
-        download_asset(tag)
+        download_asset(tag, target)
       rescue StandardError => e
+        FileUtils.rm_f(target)
         warn "Error downloading rg.wasm: #{e.message}"
-        warn "\nYou can:"
-        warn "1. Build it yourself following the instructions in README.md"
-        warn "2. Manually download it from a GitHub release"
-        warn "3. Copy it from the build directory after compilation"
-        warn "\n⚠️  Installation will continue, but rg.wasm must be added manually."
-        false
+        raise
       end
     end
 
@@ -44,25 +35,23 @@ module RipgrepWasm
     # Get the latest release tag from GitHub API
     def self.get_latest_release_tag
       uri = URI("https://api.github.com/repos/#{REPO_OWNER}/#{REPO_NAME}/releases/latest")
-      
+
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = true
       http.read_timeout = 30
-      
+
       request = Net::HTTP::Get.new(uri)
       request['User-Agent'] = 'ripgrep-wasm-ruby-downloader'
       request['Accept'] = 'application/vnd.github.v3+json'
-      
+
       response = http.request(request)
-      
+
       case response.code
       when '200'
         release = JSON.parse(response.body)
         release['tag_name']
       when '404'
-        # No releases yet, try to use version from gem
         version = RipgrepWasm::VERSION
-        puts "No GitHub release found. Using version #{version} from gem."
         "v#{version}"
       else
         raise "GitHub API returned status #{response.code}: #{response.body}"
@@ -70,72 +59,58 @@ module RipgrepWasm
     end
 
     # Download the asset from GitHub Releases
-    def self.download_asset(tag)
-      # Get release info to find asset URL
+    def self.download_asset(tag, target)
       uri = URI("https://api.github.com/repos/#{REPO_OWNER}/#{REPO_NAME}/releases/tags/#{tag}")
-      
+
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = true
       http.read_timeout = 30
-      
+
       request = Net::HTTP::Get.new(uri)
       request['User-Agent'] = 'ripgrep-wasm-ruby-downloader'
       request['Accept'] = 'application/vnd.github.v3+json'
-      
+
       response = http.request(request)
-      
+
       case response.code
-      when '404'
-        puts "Release #{tag} not found on GitHub. Skipping download."
-        puts 'You can manually download rg.wasm from the repository or build it yourself.'
-        return false
       when '200'
-        # Continue
+        # continue
+      when '404'
+        raise "Release #{tag} not found on GitHub"
       else
         raise "GitHub API returned status #{response.code}: #{response.body}"
       end
-      
+
       release = JSON.parse(response.body)
       asset = release['assets'].find { |a| a['name'] == ASSET_NAME }
-      
+
       unless asset
-        puts "Asset #{ASSET_NAME} not found in release #{tag}."
-        puts 'You can manually download rg.wasm from the repository or build it yourself.'
-        return false
+        raise "Asset #{ASSET_NAME} not found in release #{tag}"
       end
-      
-      # Download the asset
-      puts "Downloading #{ASSET_NAME} from release #{tag}..."
-      puts "Size: #{(asset['size'] / 1024.0 / 1024.0).round(2)} MB"
-      
+
       download_uri = URI(asset['browser_download_url'])
       download_http = Net::HTTP.new(download_uri.host, download_uri.port)
       download_http.use_ssl = true
-      download_http.read_timeout = 300 # 5 minutes for large file
-      
+      download_http.read_timeout = 300
+
       download_request = Net::HTTP::Get.new(download_uri)
       download_request['User-Agent'] = 'ripgrep-wasm-ruby-downloader'
       download_request['Accept'] = 'application/octet-stream'
-      
-      FileUtils.mkdir_p(File.dirname(wasm_path))
-      
-      File.open(wasm_path, 'wb') do |file|
-        download_http.request(download_request) do |response|
-          case response.code
+
+      File.open(target, 'wb') do |file|
+        download_http.request(download_request) do |dl_response|
+          case dl_response.code
           when '200'
-            response.read_body do |chunk|
+            dl_response.read_body do |chunk|
               file.write(chunk)
             end
           else
-            FileUtils.rm_f(wasm_path)
-            raise "Failed to download asset: #{response.code}"
+            raise "Failed to download asset: #{dl_response.code}"
           end
         end
       end
-      
-      # Make executable
-      File.chmod(0o755, wasm_path)
-      puts "✓ Successfully downloaded #{ASSET_NAME}"
+
+      File.chmod(0o755, target)
       true
     end
   end

data/lib/ripgrep_wasm/runner.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module RipgrepWasm
+  class Runner
+    # Run the WASM binary via the configured WASI runtime.
+    #
+    # @param args [Array<String>] arguments passed through to the binary
+    # @param wasm_dir [String] directory to expose to the WASI sandbox (default ".")
+    # @return [Hash] { stdout: String, stderr: String, success: Boolean }
+    # @raise [BinaryNotFound] if the binary does not exist at binary_path
+    # @raise [ExecutionError] if the runtime exits with non-zero status
+    def self.run(*args, wasm_dir: '.')
+      binary = RipgrepWasm.binary_path
+
+      unless File.exist?(binary)
+        raise BinaryNotFound, "WASM binary not found at #{binary}"
+      end
+
+      cmd = [
+        RipgrepWasm.runtime,
+        'run',
+        '--dir', wasm_dir,
+        binary,
+        *args
+      ]
+
+      stdout, stderr, status = Open3.capture3(*cmd)
+
+      unless status.success?
+        raise ExecutionError, "Command exited with status #{status.exitstatus}: #{stderr}"
+      end
+
+      { stdout: stdout, stderr: stderr, success: true }
+    end
+  end
+end

data/lib/ripgrep_wasm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RipgrepWasm
-  VERSION = '1.0.0'
+  VERSION = '1.0.1'
 end

data/lib/ripgrep_wasm.rb

@@ -2,35 +2,36 @@
 
 require_relative 'ripgrep_wasm/version'
 require_relative 'ripgrep_wasm/downloader'
+require_relative 'ripgrep_wasm/runner'
 
 module RipgrepWasm
   class Error < StandardError; end
+  class BinaryNotFound < Error; end
+  class ExecutionError < Error; end
 
-  # Get the path to the rg.wasm binary
-  #
-  # @return [String] The absolute path to rg.wasm
-  def self.path
-    wasm_path = File.join(File.dirname(__FILE__), 'ripgrep_wasm', 'rg.wasm')
-    
-    # If the file doesn't exist, try to download it
-    unless File.exist?(wasm_path)
-      Downloader.download_if_needed
+  DEFAULT_BINARY_PATH = File.join(File.dirname(__FILE__), 'ripgrep_wasm', 'rg.wasm').freeze
+
+  class << self
+    attr_writer :binary_path, :runtime
+
+    def binary_path
+      @binary_path || DEFAULT_BINARY_PATH
     end
-    
-    wasm_path
-  end
 
-  # Check if rg.wasm is available
-  #
-  # @return [Boolean] true if rg.wasm exists
-  def self.available?
-    File.exist?(path)
-  end
+    def runtime
+      @runtime || 'wasmtime'
+    end
 
-  # Get the absolute path to rg.wasm
-  #
-  # @return [String] The absolute path to rg.wasm
-  def self.absolute_path
-    File.expand_path(path)
+    def download_to_binary_path!
+      Downloader.download(to: binary_path)
+    end
+
+    def run(*args, wasm_dir: '.')
+      Runner.run(*args, wasm_dir: wasm_dir)
+    end
+
+    def available?
+      File.exist?(binary_path)
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ripgrep_wasm
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Nathan Himpens
@@ -17,6 +17,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".npmignore"
+- AGENTS.md
 - IMPLEMENTATION.md
 - RALPH_TASK.md
 - README.md
@@ -27,6 +28,7 @@ files:
 - lib/ripgrep_wasm.rb
 - lib/ripgrep_wasm/downloader.rb
 - lib/ripgrep_wasm/rg.wasm
+- lib/ripgrep_wasm/runner.rb
 - lib/ripgrep_wasm/version.rb
 - package.json
 - rg.wasm