beni 0.0.0 → 0.1.0

data/lib/beni/target.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Beni
+  # A +target <name>+ declaration (SPEC.md Terminology: target
+  # declaration) — names one build target to verify and holds the
+  # toolchain references its block declared.
+  class Target < Data.define(:name, :references)
+  end
+end

data/lib/beni/tasks.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rake/tasklib"
+
+require_relative "../beni"
+
+module Beni
+  # Rake task library exposing the +beni:*+ namespace. Add to a Rakefile:
+  #
+  #   require "beni/tasks"
+  #
+  #   Beni::Tasks.new
+  #
+  # or with declarations (a custom config cross-building to wasm32-wasip1):
+  #
+  #   Beni::Tasks.new do
+  #     build_config "build_config/mruby.rb"
+  #
+  #     target :host
+  #     target :wasi do
+  #       toolchain "wasi-sdk"
+  #     end
+  #   end
+  #
+  # The block is the declarative DSL from SPEC.md, run on +DSL::Context+:
+  # scalar settings (+version+ / +build_config+ / +vendor_dir+), target
+  # declarations carrying toolchain references, and top-level toolchain
+  # definitions overriding a built-in pair. Every malformed declaration
+  # raises here — no task defined, nothing downloaded.
+  #
+  # Defined tasks:
+  #
+  #   rake beni:build           — fetch toolchains + build libmruby.a per target
+  #   rake beni:clean           — remove mruby build trees (keeps source)
+  #   rake beni:config          — generate the upstream default build config
+  #   rake beni:vendor:setup    — download & unpack the selected toolchains
+  #   rake beni:vendor:clean    — remove unpacked toolchains (keeps tarball cache)
+  #   rake beni:vendor:clobber  — remove the vendor tree entirely
+  class Tasks < Rake::TaskLib
+    # The resolved declarations — exposed so consumers and tests can
+    # inspect what the task definitions were wired from.
+    attr_reader :configuration
+
+    def initialize(&block)
+      super()
+      context = DSL::Context.new
+      context.instance_exec(&block) if block
+      @configuration = context.configuration
+      define
+    end
+
+    private
+
+    def builder
+      @builder ||= Builder.new(
+        vendor_dir: configuration.vendor_dir,
+        build_config: configuration.build_config,
+        targets: configuration.targets
+      )
+    end
+
+    # The selected toolchains as Vendor pipeline values, each carrying
+    # its resolved version and checksum.
+    def vendor_toolchains
+      @vendor_toolchains ||= configuration.toolchains.map do |selected|
+        Vendor.public_send(
+          Vendor::TOOLCHAIN_FACTORIES.fetch(selected.name),
+          vendor_dir: configuration.vendor_dir, version: selected.version, sha256: selected.sha256
+        )
+      end
+    end
+
+    def define
+      namespace :beni do
+        define_vendor_namespace
+        define_build_task
+        define_clean_task
+        define_config_task
+      end
+    end
+
+    def define_vendor_namespace
+      namespace :vendor do
+        vendor_toolchains.each { |toolchain| define_toolchain_tasks(toolchain) }
+        define_vendor_setup_task
+        define_vendor_clean_tasks
+      end
+    end
+
+    def define_vendor_setup_task
+      desc "Fetch and unpack the selected vendor toolchains (#{vendor_toolchains.map(&:name).join(" + ")})"
+      task setup: vendor_toolchains.map { |toolchain| "setup:#{toolchain.task_name}" } do
+        Vendor.stage_wasi_toolchain_file(vendor_dir: configuration.vendor_dir) if wasi_sdk_selected?
+      end
+    end
+
+    def wasi_sdk_selected?
+      configuration.toolchains.any? { |toolchain| toolchain.name == "wasi-sdk" }
+    end
+
+    def define_vendor_clean_tasks
+      desc "Remove unpacked vendor toolchains (keeps cached tarballs)"
+      task :clean do
+        vendor_toolchains.each { |toolchain| FileUtils.rm_rf(toolchain.final_dir) }
+      end
+
+      desc "Remove #{configuration.vendor_dir} entirely (unpacked trees and cached tarballs)"
+      task :clobber do
+        FileUtils.rm_rf(configuration.vendor_dir)
+      end
+    end
+
+    def define_toolchain_tasks(toolchain)
+      file toolchain.tarball_path do
+        toolchain.fetch
+      end
+
+      namespace :setup do
+        desc "Download and unpack #{toolchain.name} #{toolchain.version_label} into #{toolchain.final_dir}"
+        task toolchain.task_name => toolchain.tarball_path do
+          toolchain.install
+        end
+      end
+    end
+
+    def define_build_task
+      desc "Build vendored mruby for #{configuration.targets.join(" + ")} " \
+           "(produces #{builder.libmruby_paths.join(", ")})"
+      task build: "vendor:setup" do
+        builder.ensure_built
+      end
+    end
+
+    def define_clean_task
+      desc "Remove mruby's build trees (keeps vendored mruby source)"
+      task :clean do
+        builder.clean
+      end
+    end
+
+    def define_config_task
+      desc "Generate mruby's upstream default build config at the `build_config` declaration's path"
+      task :config do
+        dest = configuration.build_config
+        raise Error, "[beni] beni:config requires a `build_config` declaration naming the file to generate" unless dest
+
+        BuildConfig.generate(dest, mruby_dir: builder.mruby_dir, version: mruby_version)
+        puts "[beni] generated #{dest} — edit it to define further targets"
+      end
+    end
+
+    # mruby's selected version — always present, `mruby` is selected in
+    # every resolution.
+    def mruby_version
+      configuration.toolchains.to_h { |toolchain| [toolchain.name, toolchain.version] }.fetch("mruby")
+    end
+  end
+end

data/lib/beni/toolchain_definition.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Beni
+  # A top-level +toolchain <name>+ block (SPEC.md Terminology: toolchain
+  # definition) — carries the +version+ and +sha256+ pair that replaces
+  # the named toolchain's built-in pair.
+  class ToolchainDefinition < Data.define(:name, :version, :sha256)
+  end
+end

data/lib/beni/vendor/checksum.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Beni
+  module Vendor
+    # SHA256 verification for vendored tarballs. One instance per +(path,
+    # expected_sha)+ pair; reuse is not supported and not needed by
+    # +Beni::Tasks+. Operates in two modes:
+    #
+    #   * Explicit expected hash (a built-in pair entry or a consumer
+    #     override) — must match exactly; mismatch raises.
+    #   * Trust-on-first-use (TOFU) — when +expected_sha+ is +nil+ or empty,
+    #     the actual hash is pinned to a +.sha256+ sidecar next to the
+    #     tarball. Subsequent runs compare against the pinned value and
+    #     raise on drift.
+    #
+    # Public contract is the single +#verify_or_pin+ entry point; the two
+    # branches and the digest helper are internal.
+    class Checksum
+      def initialize(path, expected_sha)
+        @path = path
+        @expected_sha = expected_sha
+      end
+
+      # Verify the tarball against +expected_sha+ (if non-empty) or TOFU-pin
+      # against the +.sha256+ sidecar. Returns the computed SHA256 hex digest
+      # on success. Raises +Beni::Error+ on mismatch (explicit mode) or drift
+      # (TOFU mode); both error messages carry a +[beni]+ prefix for CI log
+      # grepping.
+      def verify_or_pin
+        actual = sha256
+        sidecar = "#{@path}.sha256"
+        expected? ? verify_against_expected(actual, sidecar) : verify_or_pin_sidecar(actual, sidecar)
+        actual
+      end
+
+      private
+
+      def expected?
+        !@expected_sha.to_s.empty?
+      end
+
+      def sha256
+        Digest::SHA256.file(@path).hexdigest
+      end
+
+      def verify_against_expected(actual, sidecar)
+        unless actual == @expected_sha
+          raise Error, "[beni] checksum mismatch for #{File.basename(@path)}: " \
+                       "expected #{@expected_sha}, got #{actual}"
+        end
+        File.write(sidecar, "#{actual}\n")
+      end
+
+      def verify_or_pin_sidecar(actual, sidecar)
+        if File.exist?(sidecar)
+          pinned = File.read(sidecar).strip
+          return if actual == pinned
+
+          raise Error, "[beni] checksum drift for #{File.basename(@path)}: " \
+                       "pinned #{pinned}, got #{actual}"
+        end
+        File.write(sidecar, "#{actual}\n")
+      end
+    end
+  end
+end

data/lib/beni/vendor/downloader.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open-uri"
+require "net/http" # eager — TRANSIENT_ERRORS names Net::* at class-eval
+
+module Beni
+  module Vendor
+    # Tarball download with exponential-backoff retry on transient network
+    # failures. One instance per +(url, dest)+ pair; reuse is not supported
+    # and not needed by +Beni::Tasks+.
+    #
+    # Public contract is the single +#download+ entry point; +TRANSIENT_ERRORS+
+    # and +MAX_RETRIES+ are exposed as tunable knobs but the retry mechanics
+    # themselves are internal.
+    class Downloader
+      # Retry attempts wait +1 << attempt+ seconds (2 + 4 + 8 = 14s total)
+      # — enough to ride out a GitHub archive 502 / TCP read timeout.
+      MAX_RETRIES = 3
+
+      # Transient network errors retried by the internal +with_retry+ wrapper.
+      # +OpenURI::HTTPError+ is narrowed to 5xx; 4xx (URL typo, deleted repo)
+      # bypasses the retry path.
+      TRANSIENT_ERRORS = [
+        OpenURI::HTTPError, Net::ReadTimeout, Net::OpenTimeout,
+        Errno::ECONNRESET, SocketError
+      ].freeze
+
+      def initialize(url, dest)
+        @url = url
+        @dest = dest
+      end
+
+      # Fetch +url+ into +dest+ atomically via a +.part+ sidecar, retrying
+      # transient failures with exponential backoff. Permanent failures
+      # (4xx, DNS resolution failure on non-network condition) surface
+      # immediately. Raises whatever the underlying +URI#open+ raises after
+      # the retry budget is exhausted.
+      def download
+        FileUtils.mkdir_p(File.dirname(@dest))
+        tmp = "#{@dest}.part"
+        with_retry { fetch(tmp) }
+        File.rename(tmp, @dest)
+      end
+
+      private
+
+      # Stream the URL body into +tmp+ — the seam between the retry
+      # policy and the network; tests override this to script outcomes
+      # per attempt.
+      def fetch(tmp)
+        URI.parse(@url).open("rb") { |io| File.open(tmp, "wb") { |f| IO.copy_stream(io, f) } }
+      end
+
+      def with_retry
+        attempts = 0
+        begin
+          yield
+        rescue *TRANSIENT_ERRORS => e
+          raise if permanent?(e) || (attempts += 1) > MAX_RETRIES
+
+          warn_and_sleep(e, attempts)
+          retry
+        end
+      end
+
+      def permanent?(error)
+        error.is_a?(OpenURI::HTTPError) && !error.message.match?(/\A5\d\d\b/)
+      end
+
+      def warn_and_sleep(error, attempt)
+        warn "[beni] retry #{attempt}/#{MAX_RETRIES} after #{error.class}: " \
+             "#{error.message.lines.first&.strip}"
+        sleep(1 << attempt)
+      end
+    end
+  end
+end

data/lib/beni/vendor/tarball.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Beni
+  module Vendor
+    # Unpacks a vendored tarball into +final_dir+, idempotent on a
+    # +.beni-version+ marker stamped inside the tree. One instance per
+    # +(tarball, top_level_dir, final_dir, version)+ configuration; reuse is
+    # not supported and not needed by +Beni::Tasks+.
+    #
+    # A version mismatch (toolchain bump) forces a clean re-extract, so the
+    # unpacked tree never lags the pinned version. Public contract is the
+    # single +#prepare+ entry point; the staging-directory step is internal.
+    class Tarball
+      # Marker stamped inside +final_dir+ after a successful unpack; a matching
+      # value short-circuits +#prepare+, a mismatch forces re-extract.
+      VERSION_MARKER = ".beni-version"
+
+      def initialize(tarball:, top_level_dir:, final_dir:, version:)
+        @tarball = tarball
+        @top_level_dir = top_level_dir
+        @final_dir = final_dir
+        @version = version
+      end
+
+      # Extract the tarball into a staging sibling of +final_dir+, then
+      # atomically move the +top_level_dir+ subtree into place and stamp the
+      # version marker. A no-op when the stamped version already matches.
+      # Raises if the tarball does not contain the expected +top_level_dir+
+      # root. The staging tree is removed whether or not extraction succeeds.
+      def prepare
+        return if installed_version == @version
+
+        staging = "#{@final_dir}.staging"
+        begin
+          extract_to_staging(staging)
+          promote(staging)
+        ensure
+          FileUtils.rm_rf(staging)
+        end
+      end
+
+      private
+
+      # Version recorded by the last successful unpack, or +nil+ when the tree
+      # is absent or predates version stamping (forcing a re-extract).
+      def installed_version
+        marker = File.join(@final_dir, VERSION_MARKER)
+        File.read(marker).strip if File.exist?(marker)
+      end
+
+      def extract_to_staging(staging)
+        FileUtils.rm_rf(staging)
+        FileUtils.mkdir_p(staging)
+        system("tar", "-xzf", @tarball, "-C", staging, exception: true)
+      end
+
+      # Move the expected +top_level_dir+ subtree out of +staging+ into
+      # +final_dir+ and stamp the version marker.
+      def promote(staging)
+        src = File.join(staging, @top_level_dir)
+        raise Error, "[beni] expected #{src} after extracting #{@tarball}, missing" unless File.directory?(src)
+
+        FileUtils.rm_rf(@final_dir)
+        FileUtils.mkdir_p(File.dirname(@final_dir))
+        FileUtils.mv(src, @final_dir)
+        File.write(File.join(@final_dir, VERSION_MARKER), "#{@version}\n")
+      end
+    end
+  end
+end

data/lib/beni/vendor/toolchain.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Beni
+  module Vendor
+    # Declarative value object describing a tarball-style vendored
+    # toolchain. Captures the +(remote, cache, unpacked)+ triple anchored
+    # on +vendor_dir+, and exposes the three pipeline stages (+#fetch+,
+    # +#verify+, +#install+) that +Beni::Tasks+ wires into +file+ /
+    # +task+ declarations.
+    #
+    # Adding a new tarball-based vendor artifact is a single factory
+    # method in +Beni::Vendor+; the rake DSL loop in +Beni::Tasks+
+    # picks it up automatically.
+    #
+    # Fields:
+    #
+    #   * +name+          — display name; also the basename of the unpacked
+    #                       tree under +vendor_dir+ and the base for the
+    #                       +setup:<name>+ task identifier.
+    #   * +version_label+ — version string; printed in the download log and
+    #                       stamped into +final_dir+ as the idempotency key
+    #                       that detects a bump and forces a re-extract.
+    #   * +base_url+      — remote URL prefix; resolved through
+    #                       +Beni::Vendor.base_url_for+ so test fixtures
+    #                       can override via +BENI_VENDOR_BASE_URL+.
+    #   * +tarball_name+  — filename joined to both +base_url+ (download)
+    #                       and the +.cache+ directory (cache location).
+    #   * +top_level_dir+ — the single top-level directory produced when
+    #                       the tarball is extracted; passed through to
+    #                       +Tarball#prepare+ under the same name.
+    #   * +vendor_dir+    — root of the vendor tree; anchors +final_dir+
+    #                       and +tarball_path+.
+    #   * +expected_sha256+ — the toolchain's selected checksum (resolved
+    #                       by +Beni::Vendor+ from the built-in pair or a
+    #                       consumer override); +nil+ falls to TOFU
+    #                       sidecar pinning in +Checksum#verify_or_pin+.
+    class Toolchain <
+      Data.define(:name, :version_label, :base_url, :tarball_name, :top_level_dir, :vendor_dir, :expected_sha256)
+      # Symbol used to identify the +setup:<task_name>+ rake task. Dashes
+      # in +name+ are not valid in rake task identifiers, so we map them
+      # to underscores at this single seam.
+      def task_name
+        name.tr("-", "_").to_sym
+      end
+
+      # Resolved download URL. Honours the +BENI_VENDOR_BASE_URL+ test
+      # fixture override at call time (not at construction time), so a
+      # test can flip the env var after the Toolchain is built.
+      def url
+        "#{Vendor.base_url_for(base_url)}/#{tarball_name}"
+      end
+
+      # Destination under +vendor_dir+ where the unpacked tree is moved.
+      def final_dir
+        File.join(vendor_dir, name)
+      end
+
+      # Local cache path for the downloaded tarball. Lives under
+      # +vendor_dir/.cache+ (the cache moves with the vendor tree).
+      def tarball_path
+        File.join(vendor_dir, ".cache", tarball_name)
+      end
+
+      # Download the tarball into +tarball_path+ and verify its SHA256.
+      # Intended as the body of the +file tarball_path+ rake task; the
+      # task's mtime-based caching avoids re-downloading on a cache hit.
+      # A tarball failing verification deliberately stays cached: a
+      # checksum mismatch is an abort condition, never a re-download
+      # trigger, and the cache-hit path re-fails it the same way.
+      def fetch
+        puts "[beni] downloading #{name} #{version_label} from #{url}"
+        downloader.download
+        verify
+      end
+
+      # Recompute the cached tarball's SHA256 and check it against
+      # +expected_sha256+ (or pin via TOFU sidecar). Idempotent — safe
+      # to call from both +file+ and +setup+ task bodies when the latter
+      # depends on the former.
+      def verify
+        Checksum.new(tarball_path, expected_sha256).verify_or_pin
+      end
+
+      # Verify the cached tarball, then unpack it into +final_dir+ via
+      # +Tarball#prepare+. A no-op when the version stamped under +final_dir+
+      # already matches +version_label+.
+      def install
+        verify
+        Tarball.new(
+          tarball: tarball_path,
+          top_level_dir: top_level_dir,
+          final_dir: final_dir,
+          version: version_label
+        ).prepare
+        puts "[beni] #{name} ready at #{final_dir}"
+      end
+
+      private
+
+      # The network boundary — tests override this to script the
+      # download without opening a connection.
+      def downloader
+        Downloader.new(url, tarball_path)
+      end
+    end
+  end
+end

data/lib/beni/vendor/toolchains/wasi.rake

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# beni's wasm32-wasip1 cross-compile toolchain — the wasi toolchain
+# file, staged into the mruby tree's +tasks/toolchains/+ by
+# +beni:vendor:setup+ whenever wasi-sdk is selected. A build config
+# activates it with +conf.toolchain :wasi+.
+MRuby::Toolchain.new(:wasi) do |conf, _params|
+  # WASI_SDK_PATH overrides the wasi-sdk root; the default is the
+  # vendor tree this mruby source is staged in (MRUBY_ROOT's parent).
+  wasi_sdk = ENV["WASI_SDK_PATH"] || File.join(File.expand_path("..", MRUBY_ROOT), "wasi-sdk")
+  bin = File.join(wasi_sdk, "bin")
+  target_flags = ["--target=wasm32-wasi", "--sysroot=#{File.join(wasi_sdk, "share", "wasi-sysroot")}"]
+  # setjmp/longjmp via the wasm exception-handling mechanism: all
+  # three flags must be present at both compile and link stages.
+  sjlj_flags = ["-mllvm", "-wasm-enable-sjlj", "-mllvm", "-wasm-use-legacy-eh=false"]
+
+  conf.toolchain :clang
+  conf.cc.command       = File.join(bin, "clang")
+  conf.cxx.command      = File.join(bin, "clang++")
+  conf.linker.command   = File.join(bin, "clang")
+  conf.archiver.command = File.join(bin, "llvm-ar")
+  # GNU archive format: llvm-ar defaults to the Darwin format on
+  # macOS hosts, which can overflow on many long wasm member paths.
+  conf.archiver.archive_options = "--format=gnu rs %<outfile>s %<objs>s"
+
+  [conf.cc, conf.cxx, conf.linker].each do |tool|
+    tool.flags << target_flags << sjlj_flags
+  end
+  conf.linker.libraries << "setjmp"
+end

data/lib/beni/vendor.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative "vendor/downloader"
+require_relative "vendor/checksum"
+require_relative "vendor/tarball"
+require_relative "vendor/toolchain"
+
+module Beni
+  # Vendor toolchain façade. Owns the release-vendored toolchain pins and
+  # the factory methods that build declarative +Toolchain+ values anchored
+  # on a caller-supplied +vendor_dir+; +Beni::Tasks+ calls the factories
+  # with each selected toolchain's resolved +(version, sha256)+ to wire
+  # +file+ / +task+ declarations. Network download lives in
+  # +Vendor::Downloader+, SHA256 verification in +Vendor::Checksum+,
+  # tarball extraction in +Vendor::Tarball+, and the per-toolchain
+  # pipeline composition in +Vendor::Toolchain+.
+  #
+  # Honors +BENI_VENDOR_BASE_URL+ to point downloads at a local fixture
+  # during tests.
+  module Vendor
+    # ---- Built-in pairs ----------------------------------------------------
+    # The version and checksum pair this release vendors per toolchain.
+    # wasi-sdk ships one tarball per build platform, so its checksum is
+    # keyed by +WASI_SDK_PLATFORM+ (values from the GitHub release asset
+    # digests); mruby's source archive is host-agnostic with a single
+    # checksum.
+    #
+    # wasi-sdk: must be >= 26 for native wasm32-wasip1 setjmp/longjmp
+    # support. 33's +libc.a+ supplies +__wasi_init_tp+, which Rust's
+    # wasm32-wasip1 +crt1-command.o+ references from 1.96 onward. Keep in
+    # lockstep with the channel in +rust-toolchain.toml+ — in both this
+    # repo and kobako.
+    BUILT_IN_PAIRS = {
+      "mruby" => {
+        version: "4.0.0",
+        sha256: "e2ea271dbed14e9f2b33df773ae447b747dbc242ce2675022c0a57efea85a7b4"
+      },
+      "wasi-sdk" => {
+        version: "33.0",
+        sha256: {
+          "arm64-linux" => "4f98ee738c7abb45c81a94d1461fc53cc569d1cd01498951c8184d841a027844",
+          "arm64-macos" => "85c997a2665ead91673b5bb88b7d0df3fc8900df3bfa244f720d478187bbdc78",
+          "x86_64-linux" => "0ba8b5bfaeb2adf3f29bab5841d76cf5318ab8e1642ea195f88baba1abd47bce",
+          "x86_64-macos" => "18f3f201ba9734e6a4455b0b6410690395a55e9ffa9f6f5066f66083a94b93b3"
+        }
+      }
+    }.freeze
+
+    # Transitive toolchain dependencies, folded into the selected set at
+    # task-definition time: referencing wasi-sdk implies mruby.
+    DEPENDENCIES = { "wasi-sdk" => %w[mruby] }.freeze
+
+    # ---- Platform detection (wasi-sdk only; mruby tarball is host-agnostic).
+    # +x86_64-linux+ is both the most common host triple and the safest
+    # fallback for unrecognised ones, so we collapse both cases into the
+    # +else+ branch rather than carrying an explicit +when+ that would
+    # duplicate the default.
+    WASI_SDK_PLATFORM =
+      case RUBY_PLATFORM
+      when /arm64-darwin|aarch64-darwin/ then "arm64-macos"
+      when /x86_64-darwin/               then "x86_64-macos"
+      when /aarch64-linux|arm64-linux/   then "arm64-linux"
+      else "x86_64-linux"
+      end
+
+    # Known toolchain names mapped to their factory methods — the name
+    # domain the DSL validates against and +Beni::Tasks+ dispatches on.
+    TOOLCHAIN_FACTORIES = {
+      "mruby" => :mruby,
+      "wasi-sdk" => :wasi_sdk
+    }.freeze
+
+    module_function
+
+    def wasi_sdk(vendor_dir:, version: nil, sha256: nil)
+      version ||= BUILT_IN_PAIRS.fetch("wasi-sdk").fetch(:version)
+      # The release tag carries the major version only; tarballs carry the
+      # full version plus the platform.
+      Toolchain.new(
+        name: "wasi-sdk",
+        version_label: "#{version} (#{WASI_SDK_PLATFORM})",
+        base_url: "https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-#{version.split(".").first}",
+        tarball_name: "wasi-sdk-#{version}-#{WASI_SDK_PLATFORM}.tar.gz",
+        top_level_dir: "wasi-sdk-#{version}-#{WASI_SDK_PLATFORM}",
+        vendor_dir: vendor_dir,
+        expected_sha256: sha256 || built_in_sha256("wasi-sdk", version)
+      )
+    end
+
+    def mruby(vendor_dir:, version: nil, sha256: nil)
+      version ||= BUILT_IN_PAIRS.fetch("mruby").fetch(:version)
+      Toolchain.new(
+        name: "mruby",
+        version_label: version,
+        base_url: "https://github.com/mruby/mruby/archive/refs/tags",
+        tarball_name: "#{version}.tar.gz",
+        top_level_dir: "mruby-#{version}",
+        vendor_dir: vendor_dir,
+        expected_sha256: sha256 || built_in_sha256("mruby", version)
+      )
+    end
+
+    # When BENI_VENDOR_BASE_URL is set, all tarballs are fetched from that
+    # base URL (test fixture). The base URL must serve files named exactly
+    # +tarball_name+ for each toolchain.
+    def base_url_for(default)
+      override = ENV.fetch("BENI_VENDOR_BASE_URL", nil)
+      return default if override.nil? || override.empty?
+
+      override.chomp("/")
+    end
+
+    # The built-in checksum for +name+ at +version+: the build platform's
+    # entry when the toolchain's checksums are platform-keyed, +nil+ for
+    # any version other than the vendored one — mruby's TOFU pinning path.
+    def built_in_sha256(name, version)
+      pair = BUILT_IN_PAIRS.fetch(name)
+      return nil unless version == pair.fetch(:version)
+
+      checksum = pair.fetch(:sha256)
+      checksum.is_a?(Hash) ? checksum.fetch(WASI_SDK_PLATFORM) : checksum
+    end
+
+    # Write the gem-shipped wasi toolchain file into the staged mruby
+    # source, where mruby's +conf.toolchain :wasi+ resolves it from.
+    # Idempotent and always overwriting, so a re-extracted tree or an
+    # older beni's copy converges on this release's definition. Returns
+    # the staged path.
+    def stage_wasi_toolchain_file(vendor_dir:)
+      # `__dir__ || "."`: __dir__ is only nil under eval, which never
+      # loads this file; the fallback satisfies steep's String? typing.
+      source = File.expand_path("vendor/toolchains/wasi.rake", __dir__ || ".")
+      target = File.join(vendor_dir, "mruby", "tasks", "toolchains", "wasi.rake")
+      FileUtils.mkdir_p(File.dirname(target))
+      FileUtils.cp(source, target)
+      target
+    end
+  end
+end

data/lib/beni/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Beni
-  VERSION = "0.0.0"
+  VERSION = "0.1.0"
 end