coreutils-wasm 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a271d6f528a786685d21a08bd7f54d8004a98ddc879a1aa238e0a3cec7abe470
-  data.tar.gz: e4e9b233ee13a2d2ab4bb771a638fb08d633a017ec9aab87f9b329d7025c9da2
+  metadata.gz: d65dbb6cb28564275a6808bc394d13e2d5003bc0845f08759da2ced0f7f057c0
+  data.tar.gz: d46ae0ebf88487d167b5e19269b342787c2264860393f603b1160de5a92ffbbf
 SHA512:
-  metadata.gz: b4f1c045e53050c8a445fd30320e77ed0ebfb058d10a633e42ed2a2d67f8ed9dd887a0f3f29e2a9194e1f71a7f532dace6c37e21b4c9ac3937b7e7c6b301115a
-  data.tar.gz: b46ed7493b0e048c46482fdea77d413fd35e2b9af7cba6719982cafcf1af60146ebc84274aa8b184c7afaa1e7f62ec72f486f8fd861011dbe46cb7c884fc440f
+  metadata.gz: 2c5554269a3c5d9dca5425705077fb0e763398afc516cc00b38d31a2b07816c774e07ca42e8d3e3270247b5524abf8d887c7fc28adf41beba482603261fc0b89
+  data.tar.gz: e69fb35837ebd9c810517698156784e2b2980a4346bf500f3598b0d6199f5cfa389a85be75b61f246f120f334fdfc738f917bb90ad9e8e636d24d934e04e9acc

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development do
+  gem "rake", "~> 13.0"
+  gem "minitest", "~> 5.0"
+end

data/README.md

@@ -1,10 +1,20 @@
 # CoreutilsWasm
 
-GNU Coreutils compiled to WebAssembly.
+GNU Coreutils compiled to WebAssembly, wrapped as a Ruby gem.
 
-This gem provides the WASM binary for GNU coreutils. It includes 100+ commands like `ls`, `cat`, `head`, `tail`, `wc`, `cp`, `mv`, `rm`, etc.
+This gem downloads and runs a WASM binary containing 100+ GNU coreutils commands (`ls`, `cat`, `head`, `tail`, `wc`, `cp`, `mv`, `rm`, etc.) via a WASI runtime like [wasmtime](https://wasmtime.dev/) or [wasmer](https://wasmer.io/).
 
-**This gem only provides the WASM binary.** You choose how to run it with your preferred WebAssembly runtime.
+## Prerequisites
+
+You need a WASI-compatible runtime installed on your system. The gem defaults to `wasmtime`.
+
+```bash
+# Option 1: Install wasmtime (default)
+curl https://wasmtime.dev/install.sh -sSf | bash
+
+# Option 2: Install wasmer
+curl https://get.wasmer.io -sSfL | sh
+```
 
 ## Installation
 
@@ -14,7 +24,7 @@ Add this line to your application's Gemfile:
 gem 'coreutils-wasm'
 ```
 
-And then execute:
+Then execute:
 
 ```bash
 bundle install
@@ -28,94 +38,118 @@ gem install coreutils-wasm
 
 ## Usage
 
-### Get the WASM binary path or bytes
+### Quick start
 
 ```ruby
 require 'coreutils_wasm'
 
-# Get the file path (useful for CLI runtimes)
-wasm_path = CoreutilsWasm.wasm_path
-# => "/path/to/gems/coreutils-wasm-1.0.0/wasm/coreutils.wasm"
+# 1. Download the WASM binary (only needed once)
+CoreutilsWasm.download_to_binary_path!
+
+# 2. Run a command
+result = CoreutilsWasm.run('ls', '-la', wasm_dir: '.')
+puts result[:stdout]
+```
 
-# Get as binary string
-wasm_bytes = CoreutilsWasm.wasm_bytes
+### Download the binary
 
-# Get file size
-wasm_size = CoreutilsWasm.wasm_size
-# => 4705003
+The `.wasm` binary is not bundled with the gem. It is downloaded from GitHub Releases on first use.
+
+```ruby
+# Download to the default location (inside the gem directory)
+CoreutilsWasm.download_to_binary_path!
 
-# Check if file exists
-CoreutilsWasm.wasm_exists?
+# Check if the binary is available
+CoreutilsWasm.available?
 # => true
 ```
 
-### List available commands
+### Run commands
+
+Once the binary is downloaded, use `run` to execute any coreutils command. Arguments are passed through to the WASM binary.
 
 ```ruby
-CoreutilsWasm.commands
-# => ["arch", "base32", "base64", "basename", "cat", "chmod", "cp", "ls", ...]
-```
+# List files
+result = CoreutilsWasm.run('ls', '-la', wasm_dir: '.')
+puts result[:stdout]
 
-## Running with different runtimes
+# Read a file
+result = CoreutilsWasm.run('cat', 'Gemfile', wasm_dir: '.')
+puts result[:stdout]
 
-### With Wasmer CLI
+# Word count
+result = CoreutilsWasm.run('wc', '-l', 'README.md', wasm_dir: '.')
+puts result[:stdout]
 
-```bash
-# Install wasmer
-curl https://get.wasmer.io -sSfL | sh
-
-# Run a command
-wasmer run $(ruby -r coreutils_wasm -e "puts CoreutilsWasm.wasm_path") -- ls -la
+# Sort input (via file)
+result = CoreutilsWasm.run('sort', 'names.txt', wasm_dir: '/path/to/data')
+puts result[:stdout]
 ```
 
-### With Wasmtime CLI
-
-```bash
-# Install wasmtime
-curl https://wasmtime.dev/install.sh -sSf | bash
+The `run` method returns a hash:
 
-# Run a command
-wasmtime $(ruby -r coreutils_wasm -e "puts CoreutilsWasm.wasm_path") -- ls -la
+```ruby
+{
+  stdout:  "...",   # Standard output
+  stderr:  "...",   # Standard error
+  success: true     # Whether the command succeeded
+}
 ```
 
-### With wasmer gem (Ruby runtime)
+The `wasm_dir` parameter controls which host directory is mounted into the WASI sandbox (passed as `--dir` to the runtime). It defaults to `"."`.
+
+### Configuration
 
 ```ruby
-require 'wasmer'
-require 'coreutils_wasm'
+# Change the path where the .wasm binary is stored
+CoreutilsWasm.binary_path = '/opt/wasm/coreutils.wasm'
 
-# Load the WASM binary
-wasm_bytes = CoreutilsWasm.wasm_bytes
-store = Wasmer::Store.new
-module_ = Wasmer::Module.new store, wasm_bytes
+# Change the WASI runtime (default: "wasmtime")
+CoreutilsWasm.runtime = 'wasmer'
 
-# Create WASI environment
-wasi_env = Wasmer::Wasi::StateBuilder.new("ls")
-  .argument("-la")
-  .preopen_directory(".")
-  .finalize
+# Check the current binary path
+CoreutilsWasm.binary_path
+# => "/opt/wasm/coreutils.wasm"
 
-# Instantiate with WASI imports
-import_object = wasi_env.generate_import_object(store, module_)
-instance = Wasmer::Instance.new(module_, import_object)
+# Check the current runtime
+CoreutilsWasm.runtime
+# => "wasmer"
+```
+
+### List available commands
 
-# Run
-wasi_env.start(instance)
+```ruby
+CoreutilsWasm.commands
+# => ["arch", "base32", "base64", "basename", "cat", "chmod", "cp", "ls", ...]
 ```
 
-### With shell execution
+### Error handling
 
 ```ruby
-require 'coreutils_wasm'
+# BinaryNotFound -- raised when running before downloading
+begin
+  CoreutilsWasm.run('ls')
+rescue CoreutilsWasm::BinaryNotFound => e
+  puts "Binary missing: #{e.message}"
+  CoreutilsWasm.download_to_binary_path!
+  retry
+end
 
-# Simple shell execution with wasmer
-def run_coreutils(command, *args)
-  wasm = CoreutilsWasm.wasm_path
-  `wasmer run #{wasm} -- #{command} #{args.join(' ')}`
+# ExecutionError -- raised on non-zero exit code
+begin
+  CoreutilsWasm.run('cat', 'nonexistent_file', wasm_dir: '.')
+rescue CoreutilsWasm::ExecutionError => e
+  puts "Command failed: #{e.message}"
 end
+```
+
+All errors inherit from `CoreutilsWasm::Error`:
 
-puts run_coreutils('ls', '-la')
-puts run_coreutils('cat', 'Gemfile')
+```
+StandardError
+  └── CoreutilsWasm::Error
+        ├── CoreutilsWasm::BinaryNotFound
+        └── CoreutilsWasm::ExecutionError
 ```
 
 ## Available Commands
@@ -128,7 +162,18 @@ This binary includes all GNU coreutils commands:
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+After checking out the repo, install dependencies:
+
+```bash
+cd ruby-gem
+bundle install
+```
+
+Run the test suite:
+
+```bash
+bundle exec rake test
+```
 
 ## Contributing
 

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task default: :test

data/coreutils-wasm.gemspec

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "lib/coreutils_wasm/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "coreutils-wasm"
+  spec.version       = CoreutilsWasm::VERSION
+  spec.authors       = ["Nathan Himpens"]
+  spec.email         = ["nathan@example.com"]
+
+  spec.summary       = "GNU Coreutils compiled to WebAssembly for Ruby"
+  spec.description   = "Provides GNU coreutils commands (ls, cat, head, tail, wc, etc.) " \
+                       "running in a WebAssembly sandbox via a WASI runtime (wasmtime, wasmer, etc.)."
+  spec.homepage      = "https://github.com/NathanHimpens/coreutils-wasm"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match?(%r{\A(test|spec|features|\.github|patches|agents)/}) ||
+      f.match?(%r{\A(\.gitignore|\.rubocop|AGENTS\.md)})
+  end
+  spec.require_paths = ["lib"]
+
+  # No external runtime dependencies — only Ruby stdlib.
+
+  spec.post_install_message = <<~MSG
+    ============================================================
+    coreutils-wasm installed!
+
+    The .wasm binary is NOT bundled with this gem.
+    Download it on first use:
+
+      require 'coreutils_wasm'
+      CoreutilsWasm.download_to_binary_path!
+
+    Or it will be downloaded automatically when needed.
+    A WASI runtime (wasmtime, wasmer, etc.) must be installed.
+    ============================================================
+  MSG
+
+  # Development dependencies
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+end

data/lib/coreutils_wasm/downloader.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'fileutils'
+require 'uri'
+
+module CoreutilsWasm
+  class Downloader
+    REPO_OWNER = 'NathanHimpens'
+    REPO_NAME  = 'coreutils-wasm'
+    ASSET_NAME = 'coreutils.wasm'
+
+    class << self
+      def download(to:)
+        target = File.expand_path(to)
+        FileUtils.mkdir_p(File.dirname(target))
+
+        begin
+          tag = get_latest_release_tag
+          download_asset(tag, target)
+          FileUtils.chmod(0o755, target)
+          true
+        rescue StandardError => e
+          FileUtils.rm_f(target)
+          warn "Download failed: #{e.message}"
+          raise
+        end
+      end
+
+      private
+
+      def get_latest_release_tag
+        uri = URI("https://api.github.com/repos/#{REPO_OWNER}/#{REPO_NAME}/releases/latest")
+        response = Net::HTTP.get(uri)
+        data = JSON.parse(response)
+        data['tag_name']
+      end
+
+      def download_asset(tag, target)
+        uri = URI("https://github.com/#{REPO_OWNER}/#{REPO_NAME}/releases/download/#{tag}/#{ASSET_NAME}")
+
+        Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
+          request = Net::HTTP::Get.new(uri)
+          http.request(request) do |response|
+            if response.is_a?(Net::HTTPRedirection)
+              return download_from_uri(URI(response['location']), target)
+            end
+
+            File.open(target, 'wb') do |file|
+              response.read_body do |chunk|
+                file.write(chunk)
+              end
+            end
+          end
+        end
+      end
+
+      def download_from_uri(uri, target)
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
+          request = Net::HTTP::Get.new(uri)
+          http.request(request) do |response|
+            File.open(target, 'wb') do |file|
+              response.read_body do |chunk|
+                file.write(chunk)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coreutils_wasm/runner.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module CoreutilsWasm
+  class Runner
+    class << self
+      def run(*args, wasm_dir: '.')
+        binary = CoreutilsWasm.binary_path
+
+        raise CoreutilsWasm::BinaryNotFound, "WASM binary not found at #{binary}" unless File.exist?(binary)
+
+        cmd = [
+          CoreutilsWasm.runtime,
+          'run',
+          '--dir', wasm_dir,
+          binary,
+          *args
+        ]
+
+        stdout, stderr, status = Open3.capture3(*cmd)
+
+        unless status.success?
+          raise CoreutilsWasm::ExecutionError,
+                "Command exited with status #{status.exitstatus}: #{stderr}"
+        end
+
+        { stdout: stdout, stderr: stderr, success: true }
+      end
+    end
+  end
+end

data/lib/coreutils_wasm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CoreutilsWasm
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/coreutils_wasm.rb

@@ -1,41 +1,41 @@
 # frozen_string_literal: true
 
-require_relative "coreutils_wasm/version"
-require_relative "coreutils_wasm/commands"
+require_relative 'coreutils_wasm/version'
+require_relative 'coreutils_wasm/downloader'
+require_relative 'coreutils_wasm/runner'
+require_relative 'coreutils_wasm/commands'
 
-# CoreutilsWasm provides GNU coreutils WASM binaries
-#
-# This gem only provides the WASM binary. You choose how to run it
-# with your preferred WebAssembly runtime (wasmer, wasmtime, etc.)
 module CoreutilsWasm
   class Error < StandardError; end
+  class BinaryNotFound < Error; end
+  class ExecutionError < Error; end
+
+  DEFAULT_BINARY_PATH = File.join(File.dirname(__FILE__), 'coreutils_wasm', 'coreutils.wasm').freeze
 
   class << self
-    # Get the absolute path to the coreutils WASM binary
-    # @return [String] Absolute path to coreutils.wasm
-    def wasm_path
-      @wasm_path ||= File.expand_path("../wasm/coreutils.wasm", __dir__)
+    attr_writer :binary_path, :runtime
+
+    def binary_path
+      @binary_path || DEFAULT_BINARY_PATH
+    end
+
+    def runtime
+      @runtime || 'wasmtime'
     end
 
-    # Get the raw WASM binary as a string of bytes
-    # @return [String] Binary string containing the WASM binary
-    def wasm_bytes
-      File.binread(wasm_path)
+    def download_to_binary_path!
+      Downloader.download(to: binary_path)
     end
 
-    # Get the WASM file size in bytes
-    # @return [Integer] Size in bytes
-    def wasm_size
-      File.size(wasm_path)
+    def run(*args, wasm_dir: '.')
+      Runner.run(*args, wasm_dir: wasm_dir)
     end
 
-    # Check if the WASM binary exists
-    # @return [Boolean]
-    def wasm_exists?
-      File.exist?(wasm_path)
+    def available?
+      File.exist?(binary_path)
     end
 
-    # List of all available commands in this binary
+    # List of all available commands in this binary (coreutils-specific convenience)
     # @return [Array<String>]
     def commands
       Commands::ALL

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coreutils-wasm
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Nathan Himpens
@@ -24,59 +24,50 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '5.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '5.0'
 - !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: rubocop
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '13.0'
 description: Provides GNU coreutils commands (ls, cat, head, tail, wc, etc.) running
-  in a WebAssembly sandbox via Wasmer CLI.
+  in a WebAssembly sandbox via a WASI runtime (wasmtime, wasmer, etc.).
 email:
 - nathan@example.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- Gemfile
 - LICENSE
 - README.md
+- Rakefile
+- coreutils-wasm.gemspec
 - lib/coreutils_wasm.rb
 - lib/coreutils_wasm/commands.rb
+- lib/coreutils_wasm/downloader.rb
+- lib/coreutils_wasm/runner.rb
 - lib/coreutils_wasm/version.rb
 - wasm/coreutils.wasm
 homepage: https://github.com/NathanHimpens/coreutils-wasm
@@ -86,6 +77,19 @@ metadata:
   homepage_uri: https://github.com/NathanHimpens/coreutils-wasm
   source_code_uri: https://github.com/NathanHimpens/coreutils-wasm
   changelog_uri: https://github.com/NathanHimpens/coreutils-wasm/blob/main/CHANGELOG.md
+post_install_message: |
+  ============================================================
+  coreutils-wasm installed!
+
+  The .wasm binary is NOT bundled with this gem.
+  Download it on first use:
+
+    require 'coreutils_wasm'
+    CoreutilsWasm.download_to_binary_path!
+
+  Or it will be downloaded automatically when needed.
+  A WASI runtime (wasmtime, wasmer, etc.) must be installed.
+  ============================================================
 rdoc_options: []
 require_paths:
 - lib