aim-helm-bashkit 0.1.0-x86_64-darwin

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 929065005f97d6c20a507c95c11707d452a2fd6fabbdf100f03fafacdab380d1
+  data.tar.gz: 017b7078516f5984ad3ec78ca5965305ebaa76ccfdfd420becdaeeb9109d7003
+SHA512:
+  metadata.gz: a190fee490c545ba0fec52fa593f495b63acd60f5a180505c63121d511591f6fa5236389064159482cb6f276defa35571cf4e61ebd8288968900e535ec142cd7
+  data.tar.gz: c6432323bbe2cf692f0c2008864241534c890571d587fae46556f63348aa1b16dc57d9205239d60d34670d5f523a39700152e6a90fc9d7f2edbfd140f6d28e85

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "irb"
+gem "rake"
+gem "rdoc"
+gem "rspec"
+gem "rubocop"

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Accountaim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,128 @@
+# aim-helm-bashkit
+
+Ruby bindings for [Bashkit](https://github.com/everruns/bashkit), a sandboxed bash interpreter
+written in Rust. Scripts run in-process against a virtual filesystem: no external shell, no host
+filesystem, no network. `grep`, `rg`, `sed`, `awk`, `jq`, pipes, and redirects are Bashkit's own
+implementations.
+
+The gem calls Bashkit's C ABI through `ffi` and mirrors the core of the Python binding's `Bash` API.
+`AimHelmBashkit::Workspace` adds a sync layer for running scripts over documents kept in a database.
+
+## Installation
+
+```ruby
+gem "aim-helm-bashkit"
+```
+
+Platform gems bundle `libbashkit` for `x86_64-linux-gnu`, `aarch64-linux-gnu`, `x86_64-darwin`, and
+`arm64-darwin` (Linux needs glibc 2.34+). The source gem downloads the same checksum-verified
+library from the Bashkit release on install. Set `AIM_HELM_BASHKIT_LIB_PATH` to use your own build. The
+pinned version is `AimHelmBashkit::BASHKIT_VERSION`.
+
+## Bash
+
+```ruby
+bash = AimHelmBashkit::Bash.new(cwd: "/work", env: { "CI" => "1" }, timeout_seconds: 30)
+
+bash.execute("echo hello > greeting.txt")
+result = bash.execute("cat greeting.txt | tr a-z A-Z")
+result.stdout     # => "HELLO\n"
+result.exit_code  # => 0
+result.success?   # => true
+
+bash.execute!("exit 3")  # raises AimHelmBashkit::BashError
+bash.close
+```
+
+Shell state and files persist across `execute` calls on one instance. `reset` discards both.
+
+A script that cannot finish still returns a result, with `exit_code` 1 and a message in `error`.
+This covers parse errors, exceeded limits, timeouts, and cancellation. ABI failures such as bad
+configuration raise `AimHelmBashkit::Error`.
+
+Constructor options: `profile` (`:hardened`, `:standard`, `:interactive`), `cwd`, `env`, `files`
+(text, `{ "/path" => "content" }`), `username`, `hostname`, `timeout_seconds`,
+`parser_timeout_seconds`, `max_commands`, `max_input_bytes`, `max_output_bytes`,
+`readonly_filesystem`, `capture_final_env`.
+
+### Cancellation
+
+`execute` releases the GVL, so other threads keep running. `cancel` is safe from any thread and
+stops the script at its next command boundary. It is sticky until `clear_cancel`.
+
+```ruby
+Thread.new { sleep 1; bash.cancel }
+bash.execute("sleep 10").error  # => "execution cancelled"
+bash.clear_cancel
+```
+
+### Files
+
+```ruby
+bash.mkdir("/data", recursive: true)
+bash.write_file("/data/config.json", '{"debug": true}')
+bash.read_file("/data/config.json")
+bash.remove("/data", recursive: true)
+```
+
+`write_file` requires the parent directory to exist. Bashkit processes text: shell commands that
+emit invalid UTF-8 replace those bytes with U+FFFD.
+
+## Workspace
+
+`Workspace` runs a script over chosen documents from a store and saves what changed. The store is
+any object with `read(path)` (returning `nil` when missing), `write(path, content)`, and
+`delete(path)`.
+
+```ruby
+workspace = AimHelmBashkit::Workspace.new(store, root: "/workspace")
+
+run = workspace.execute(
+  "rg -ni 'amount|premium' inputs/schema.sql > outputs/money.txt",
+  files: ["inputs/schema.sql", "outputs/money.txt"],
+  timeout_seconds: 30,
+)
+
+run.result   # => AimHelmBashkit::ExecResult
+run.written  # => ["outputs/money.txt"]
+run.deleted  # => []
+```
+
+`files` names every document the script may read or write. Each call:
+
+1. Creates a fresh interpreter and copies in the listed documents that exist, at `root/<path>`.
+   Parent directories are created for every listed path.
+2. Runs the script. Unlisted documents do not exist in the shell.
+3. Saves listed files the script created or changed and deletes listed files it removed. Anything
+   else the script wrote is discarded.
+
+Store paths are relative (`inputs/schema.sql`); paths containing `.`, `..`, or empty segments are
+rejected. Files written before a failure or timeout are still saved. Writes are last-writer-wins
+against the store.
+
+## Examples
+
+- [Console walkthrough](docs/console.md): a directory-backed store, reading, writing, editing, and
+  deleting files, plus known `awk` differences.
+- [Stores](docs/stores.md): the aim-helm-rails Workspace adapter and a store over any Active Record
+  model.
+- [Read-only execution](docs/read-only.md): let a script read documents without writing anything.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake native:fetch
+bundle exec rspec
+bundle exec rubocop
+bin/console   # IRB with `bash`, `store`, and `workspace` ready
+```
+
+## Releasing
+
+Tag `vX.Y.Z` and push. The release workflow packages platform gems plus the source gem and publishes
+to RubyGems via trusted publishing.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+namespace :native do
+  desc "Fetch the prebuilt libbashkit for this platform"
+  task :fetch do
+    ruby "scripts/fetch_native.rb"
+  end
+end
+
+task default: :spec

data/aim-helm-bashkit.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "lib/aim_helm_bashkit/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "aim-helm-bashkit"
+  spec.version = AimHelmBashkit::VERSION
+  spec.authors = ["Accountaim"]
+  spec.summary = "Ruby bindings for Bashkit, a sandboxed bash interpreter"
+  spec.description = <<~DESC
+    Wraps the Bashkit C ABI: run bash scripts in-process against a virtual
+    filesystem, with limits and cancellation, and sync named files with a
+    host-supplied document store.
+  DESC
+  spec.homepage = "https://github.com/AccountAim/aim-helm-bashkit"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.4.0"
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir["{lib,ext}/**/*", "scripts/native_release.rb", "Gemfile", "Rakefile",
+        "aim-helm-bashkit.gemspec", "README.md", "LICENSE"]
+      .grep_v(%r{\Alib/aim_helm_bashkit/libbashkit\.(so|dylib)\z})
+  end
+
+  spec.require_paths = ["lib"]
+  spec.extensions = ["ext/aim_helm_bashkit/extconf.rb"]
+
+  spec.add_dependency "ffi", "~> 1.15"
+
+  spec.metadata = {
+    "source_code_uri" => "https://github.com/AccountAim/aim-helm-bashkit",
+    "rubygems_mfa_required" => "true",
+  }
+end

data/ext/aim_helm_bashkit/extconf.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Source installs download the official libbashkit for this platform. Platform
+# gems bundle the library and drop this extension.
+
+require_relative "../../scripts/native_release"
+
+lib_dir = File.expand_path("../../lib/aim_helm_bashkit", __dir__)
+
+if Dir[File.join(lib_dir, "libbashkit.{so,dylib}")].any?
+  puts "libbashkit already present in #{lib_dir}, skipping."
+else
+  platform = NativeRelease.host_platform or abort <<~MSG
+    ERROR: no prebuilt libbashkit for #{RbConfig::CONFIG["host_os"]} / #{RbConfig::CONFIG["host_cpu"]}.
+    Build it from #{NativeRelease::REPO} with ./scripts/build-c-api.sh --release
+    and set AIM_HELM_BASHKIT_LIB_PATH.
+  MSG
+  NativeRelease.install(platform, lib_dir)
+end
+
+# Required by the rubygems extension protocol.
+File.write(File.join(__dir__, "Makefile"), "all:\ninstall:\nclean:\n")

data/lib/aim-helm-bashkit.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "aim_helm_bashkit"

data/lib/aim_helm_bashkit/bash.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "json"
+
+module AimHelmBashkit
+  # A sandboxed bash interpreter with an in-memory filesystem. Shell state and
+  # files persist across `execute` calls on the same instance.
+  #
+  # Calls on one instance serialize; `cancel` is safe from any thread.
+  class Bash
+    # `files` seeds text files: { "/workspace/input.txt" => "hello\n" }.
+    def initialize(
+      profile: nil, cwd: nil, env: nil, files: nil, username: nil, hostname: nil,
+      timeout_seconds: nil, parser_timeout_seconds: nil, readonly_filesystem: nil,
+      capture_final_env: nil, max_commands: nil, max_input_bytes: nil, max_output_bytes: nil
+    )
+      limits = {
+        max_commands:, max_input_bytes:, max_output_bytes:,
+        timeout_ms: timeout_seconds && (timeout_seconds * 1000).round,
+        parser_timeout_ms: parser_timeout_seconds && (parser_timeout_seconds * 1000).round
+      }.compact
+
+      @config = JSON.generate({
+        schema_version: 1, profile: profile&.to_s, cwd:, env:, files:, username:, hostname:,
+        readonly_filesystem:, capture_final_env:, limits: limits.empty? ? nil : limits
+      }.compact)
+      @handle = create
+    end
+
+    def execute(script)
+      result_out = FFI::MemoryPointer.new(:pointer)
+      Native.call(:bashkit_execute, handle, Native.bytes(script), result_out) do |status, message|
+        return ExecResult.failure(message) if Native::FAILED_RUN.include?(status)
+
+        raise Error.new(message, code: status)
+      end
+      take_result(result_out.read_pointer)
+    end
+
+    def execute!(script)
+      execute(script).tap { raise BashError, it unless it.success? }
+    end
+
+    # Aborts the running execution at its next command boundary. Sticky until
+    # `clear_cancel`: later executions fail immediately.
+    def cancel
+      Native.bashkit_cancel(handle)
+      nil
+    end
+
+    def clear_cancel
+      Native.bashkit_clear_cancel(handle)
+      nil
+    end
+
+    # Discards shell state and files, keeping the constructor configuration.
+    def reset
+      close
+      @handle = create
+      nil
+    end
+
+    def close
+      @handle&.free
+      @handle = nil
+    end
+
+    def read_file(path)
+      buffer_out = FFI::MemoryPointer.new(:pointer)
+      Native.call(:bashkit_read_file, handle, Native.bytes(path), buffer_out)
+      Native.take_buffer(buffer_out.read_pointer)
+    end
+
+    # Parent directories must exist.
+    def write_file(path, content)
+      Native.call(:bashkit_write_file, handle, Native.bytes(path), Native.bytes(content))
+      nil
+    end
+
+    def mkdir(path, recursive: false)
+      Native.call(:bashkit_mkdir, handle, Native.bytes(path), recursive ? 1 : 0)
+      nil
+    end
+
+    def remove(path, recursive: false)
+      Native.call(:bashkit_remove, handle, Native.bytes(path), recursive ? 1 : 0)
+      nil
+    end
+
+    private
+
+    def handle
+      @handle or raise Error, "bash is closed"
+    end
+
+    def create
+      bash_out = FFI::MemoryPointer.new(:pointer)
+      Native.call(:bashkit_create_json, Native.bytes(@config), bash_out)
+      FFI::AutoPointer.new(bash_out.read_pointer, Native.method(:bashkit_free))
+    end
+
+    def take_result(pointer)
+      flags = Native.bashkit_result_flags(pointer)
+      final_env = Native.read(Native.bashkit_result_final_env_json(pointer))
+
+      ExecResult.new(
+        stdout: Native.read(Native.bashkit_result_stdout(pointer)),
+        stderr: Native.read(Native.bashkit_result_stderr(pointer)),
+        exit_code: Native.bashkit_result_exit_code(pointer),
+        error: nil,
+        stdout_truncated: flags.anybits?(Native::STDOUT_TRUNCATED),
+        stderr_truncated: flags.anybits?(Native::STDERR_TRUNCATED),
+        final_env: final_env.empty? ? nil : JSON.parse(final_env),
+      )
+    ensure
+      Native.bashkit_result_free(pointer)
+    end
+  end
+end

data/lib/aim_helm_bashkit/error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module AimHelmBashkit
+  # `code` is the bashkit ABI status when the failure came from the native call.
+  class Error < StandardError
+    attr_reader :code
+
+    def initialize(message = nil, code: nil)
+      @code = code
+      super(message)
+    end
+  end
+
+  class LibraryNotFoundError < Error; end
+
+  # Raised by `execute!` when the script exits nonzero or fails to run.
+  class BashError < Error
+    attr_reader :result
+
+    def initialize(result)
+      @result = result
+      super(result.error || "exit #{result.exit_code}: #{result.stderr}")
+    end
+
+    def exit_code = result.exit_code
+    def stderr = result.stderr
+  end
+end

data/lib/aim_helm_bashkit/exec_result.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module AimHelmBashkit
+  # `error` is set when the script could not run to completion: parse errors,
+  # exceeded limits, timeouts, and cancellation.
+  ExecResult = Data.define(
+    :stdout, :stderr, :exit_code, :error, :stdout_truncated, :stderr_truncated, :final_env
+  ) do
+    def self.failure(message)
+      new(
+        stdout: +"", stderr: message, exit_code: 1, error: message,
+        stdout_truncated: false, stderr_truncated: false, final_env: nil
+      )
+    end
+
+    def success? = exit_code.zero?
+  end
+end

data/lib/aim_helm_bashkit/native.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module AimHelmBashkit
+  # FFI bindings to libbashkit's C ABI (crates/bashkit-capi/include/bashkit.h).
+  #
+  # @api private
+  module Native
+    extend FFI::Library
+
+    LIB_FILE = "libbashkit.#{FFI::Platform::LIBSUFFIX}".freeze
+    ABI_VERSION = 1
+
+    OK = 0
+    EXECUTION_ERROR = 4
+    IO_ERROR = 5
+    CANCELLED = 7
+    # Statuses meaning the script ran but could not finish, reported as a result.
+    FAILED_RUN = [EXECUTION_ERROR, CANCELLED].freeze
+    STDOUT_TRUNCATED = 1 << 0
+    STDERR_TRUNCATED = 1 << 1
+
+    def self.library_path
+      ENV.fetch("AIM_HELM_BASHKIT_LIB_PATH") { File.expand_path(LIB_FILE, __dir__) }
+    end
+
+    begin
+      ffi_lib library_path
+    rescue LoadError => e
+      raise LibraryNotFoundError, <<~MSG
+        Could not load #{LIB_FILE}: #{e.message}
+        Run `rake native:fetch`, or set AIM_HELM_BASHKIT_LIB_PATH to the library.
+      MSG
+    end
+
+    class Bytes < FFI::Struct
+      layout :ptr, :pointer, :len, :size_t
+
+      def self.from(string) = new.tap { it.string = string.to_s }
+
+      # The struct holds the buffer so it lives as long as the struct.
+      def string=(string)
+        @memory = FFI::MemoryPointer.new(:uint8, string.bytesize)
+        @memory.put_bytes(0, string)
+        self[:ptr] = @memory
+        self[:len] = string.bytesize
+      end
+    end
+
+    attach_function :bashkit_abi_version, [], :uint32
+    attach_function :bashkit_version, [], Bytes.by_value
+    attach_function :bashkit_capabilities_json, [], Bytes.by_value
+
+    attach_function :bashkit_create_json, [Bytes.by_value, :pointer, :pointer], :uint32
+    attach_function :bashkit_free, [:pointer], :void
+    attach_function :bashkit_execute, [:pointer, Bytes.by_value, :pointer, :pointer], :uint32,
+                    blocking: true
+    attach_function :bashkit_cancel, [:pointer], :uint32
+    attach_function :bashkit_clear_cancel, [:pointer], :uint32
+
+    attach_function :bashkit_result_exit_code, [:pointer], :int32
+    attach_function :bashkit_result_stdout, [:pointer], Bytes.by_value
+    attach_function :bashkit_result_stderr, [:pointer], Bytes.by_value
+    attach_function :bashkit_result_flags, [:pointer], :uint32
+    attach_function :bashkit_result_final_env_json, [:pointer], Bytes.by_value
+    attach_function :bashkit_result_free, [:pointer], :void
+
+    attach_function :bashkit_write_file, [:pointer, Bytes.by_value, Bytes.by_value, :pointer],
+                    :uint32, blocking: true
+    attach_function :bashkit_read_file, [:pointer, Bytes.by_value, :pointer, :pointer], :uint32,
+                    blocking: true
+    attach_function :bashkit_mkdir, [:pointer, Bytes.by_value, :uint32, :pointer], :uint32
+    attach_function :bashkit_remove, [:pointer, Bytes.by_value, :uint32, :pointer], :uint32
+
+    attach_function :bashkit_buffer_bytes, [:pointer], Bytes.by_value
+    attach_function :bashkit_buffer_free, [:pointer], :void
+
+    attach_function :bashkit_error_code, [:pointer], :uint32
+    attach_function :bashkit_error_message, [:pointer], Bytes.by_value
+    attach_function :bashkit_error_free, [:pointer], :void
+
+    unless (abi = bashkit_abi_version) == ABI_VERSION
+      raise Error, "#{library_path} speaks bashkit ABI #{abi}, expected #{ABI_VERSION}"
+    end
+
+    class << self
+      # Calls a status-returning function whose trailing argument is `BashkitError **`.
+      # Yields the status and message for a non-OK status; raises when there is no block.
+      def call(function, *)
+        error_out = FFI::MemoryPointer.new(:pointer)
+        status = public_send(function, *, error_out)
+        return status if status == OK
+
+        message = take_error(error_out.read_pointer)
+        return yield(status, message) if block_given?
+
+        raise Error.new(message, code: status)
+      end
+
+      def bytes(string) = Bytes.from(string)
+
+      def read(bytes)
+        return +"" if bytes[:len].zero?
+
+        bytes[:ptr].read_bytes(bytes[:len]).force_encoding(Encoding::UTF_8)
+      end
+
+      def take_buffer(pointer)
+        read(bashkit_buffer_bytes(pointer))
+      ensure
+        bashkit_buffer_free(pointer)
+      end
+
+      private
+
+      def take_error(pointer)
+        return "bashkit call failed" if pointer.null?
+
+        read(bashkit_error_message(pointer))
+      ensure
+        bashkit_error_free(pointer) unless pointer.null?
+      end
+    end
+  end
+end

data/lib/aim_helm_bashkit/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module AimHelmBashkit
+  VERSION = "0.1.0"
+  BASHKIT_VERSION = "0.18.2"
+end

data/lib/aim_helm_bashkit/workspace.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module AimHelmBashkit
+  # Runs a script against chosen documents from a store, then saves what changed.
+  #
+  # The store is any object with `read(path) -> String | nil`, `write(path, content)`,
+  # and `delete(path)`. Store paths are relative ("inputs/schema.sql") and appear
+  # under `root` in the shell ("/workspace/inputs/schema.sql").
+  #
+  # Each `execute` uses a fresh interpreter. `files` is the only way in or out:
+  # listed documents are copied in, and afterwards each listed path is saved,
+  # deleted, or left alone to match the shell. Anything else the script writes
+  # is discarded.
+  class Workspace
+    Run = Data.define(:result, :written, :deleted)
+
+    attr_reader :store, :root
+
+    def initialize(store, root: "/workspace")
+      raise ArgumentError, "root must be absolute: #{root.inspect}" unless root.start_with?("/")
+
+      @store = store
+      @root = root.chomp("/")
+    end
+
+    def execute(script, files: [], **)
+      files = files.map { relative(it) }.uniq
+      bash = Bash.new(cwd: root, **)
+      loaded = copy_in(bash, files)
+      result = bash.execute(script)
+      written, deleted = copy_out(bash, loaded)
+
+      Run.new(result:, written:, deleted:)
+    ensure
+      bash&.close
+    end
+
+    private
+
+    # Parent directories exist for every listed path, so a script can write a
+    # new document without `mkdir -p`.
+    def copy_in(bash, files)
+      files.to_h do |path|
+        content = store.read(path)
+        bash.mkdir(File.dirname(absolute(path)), recursive: true)
+        bash.write_file(absolute(path), content) if content
+        [path, content]
+      end
+    end
+
+    def copy_out(bash, loaded)
+      written = []
+      deleted = []
+
+      loaded.each do |path, before|
+        after = read_shell_file(bash, path)
+
+        if after.nil?
+          next unless before
+
+          store.delete(path)
+          deleted << path
+        elsif after != before
+          store.write(path, after)
+          written << path
+        end
+      end
+
+      [written, deleted]
+    end
+
+    # A listed path the script removed, or turned into a directory, counts as absent.
+    def read_shell_file(bash, path)
+      bash.read_file(absolute(path))
+    rescue Error => e
+      raise unless e.code == Native::IO_ERROR
+
+      nil
+    end
+
+    def absolute(path) = "#{root}/#{path}"
+
+    def relative(path)
+      path = path.to_s.delete_prefix("#{root}/")
+      raise ArgumentError, "invalid workspace path: #{path.inspect}" unless valid?(path)
+
+      path
+    end
+
+    def valid?(path)
+      segments = path.split("/", -1)
+      segments.any? && segments.none? { it.empty? || %w[. ..].include?(it) }
+    end
+  end
+end

data/lib/aim_helm_bashkit.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "aim_helm_bashkit/version"
+require_relative "aim_helm_bashkit/error"
+require_relative "aim_helm_bashkit/native"
+require_relative "aim_helm_bashkit/exec_result"
+require_relative "aim_helm_bashkit/bash"
+require_relative "aim_helm_bashkit/workspace"
+
+# Ruby bindings for Bashkit, a sandboxed bash interpreter with a virtual filesystem.
+module AimHelmBashkit
+  class << self
+    def version = Native.read(Native.bashkit_version)
+    def capabilities = JSON.parse(Native.read(Native.bashkit_capabilities_json))
+  end
+end

data/scripts/native_release.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "open-uri"
+require "rbconfig"
+require "tmpdir"
+require_relative "../lib/aim_helm_bashkit/version"
+
+# Upstream bashkit-capi release archives, keyed by gem platform.
+module NativeRelease
+  REPO = "https://github.com/everruns/bashkit"
+
+  TARGETS = {
+    "x86_64-linux-gnu" => "x86_64-unknown-linux-gnu",
+    "aarch64-linux-gnu" => "aarch64-unknown-linux-gnu",
+    "x86_64-darwin" => "x86_64-apple-darwin",
+    "arm64-darwin" => "aarch64-apple-darwin",
+  }.freeze
+
+  module_function
+
+  def host_platform
+    cpu = RbConfig::CONFIG["host_cpu"]
+    case RbConfig::CONFIG["host_os"]
+    when /linux/ then "#{cpu == "arm64" ? "aarch64" : cpu}-linux-gnu"
+    when /darwin/ then "#{cpu == "x86_64" ? "x86_64" : "arm64"}-darwin"
+    end
+  end
+
+  def install(platform, lib_dir)
+    target = TARGETS.fetch(platform) do
+      abort "ERROR: no prebuilt libbashkit for #{platform.inspect}. " \
+            "Known: #{TARGETS.keys.join(", ")}"
+    end
+
+    archive = "bashkit-capi-#{target}.tar.gz"
+    base = "#{REPO}/releases/download/v#{AimHelmBashkit::BASHKIT_VERSION}"
+    puts "Downloading #{base}/#{archive}..."
+    tarball = URI.parse("#{base}/#{archive}").open.read
+    expected = URI.parse("#{base}/#{archive}.sha256").open.read[/\A\h{64}/]
+    unless Digest::SHA256.hexdigest(tarball) == expected
+      abort "ERROR: checksum mismatch for #{archive}"
+    end
+
+    Dir.mktmpdir do |dir|
+      File.binwrite(File.join(dir, archive), tarball)
+      system("tar", "xzf", archive, chdir: dir) or abort "ERROR: tar extraction failed"
+
+      library = Dir[File.join(dir, "*", "lib", "libbashkit.{so,dylib}")].first
+      abort "ERROR: libbashkit not found in #{archive}" unless library
+
+      FileUtils.mkdir_p(lib_dir)
+      FileUtils.cp(library, lib_dir, verbose: true)
+    end
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: aim-helm-bashkit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: x86_64-darwin
+authors:
+- Accountaim
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+description: |
+  Wraps the Bashkit C ABI: run bash scripts in-process against a virtual
+  filesystem, with limits and cancellation, and sync named files with a
+  host-supplied document store.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- aim-helm-bashkit.gemspec
+- ext/aim_helm_bashkit/extconf.rb
+- lib/aim-helm-bashkit.rb
+- lib/aim_helm_bashkit.rb
+- lib/aim_helm_bashkit/bash.rb
+- lib/aim_helm_bashkit/error.rb
+- lib/aim_helm_bashkit/exec_result.rb
+- lib/aim_helm_bashkit/libbashkit.dylib
+- lib/aim_helm_bashkit/native.rb
+- lib/aim_helm_bashkit/version.rb
+- lib/aim_helm_bashkit/workspace.rb
+- scripts/native_release.rb
+homepage: https://github.com/AccountAim/aim-helm-bashkit
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/AccountAim/aim-helm-bashkit
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby bindings for Bashkit, a sandboxed bash interpreter
+test_files: []