Introduce Bundlebun.system(): runs Bun as a subprocess and returns. The default call() works as it was: replaces the process. exec() added for clarity. (#12)

Author: yaroslav

CHANGELOG.md

@@ -1,5 +1,7 @@
 ## [Unreleased]
 
+- `Bundlebun.system(args)` method: runs Bun as a subprocess and returns to Ruby. Returns `true` if Bun exited successfully. Use this when you need to continue executing Ruby code after Bun finishes.
+- Default behaviour remains: `Bundlebun.()` / `Bundlebun.call` / `Bundlebun.exec` all replace the current Ruby process with Bun (never return). This is what binstubs and wrappers use.
 - Added RBS type signatures for the public API
 
 ## [0.3.0] - 2026-01-29

README.md

@@ -197,13 +197,30 @@ bun outdated v1.1.38 (bf2f153f)
 
 **Check bundlebun API: https://rubydoc.info/gems/bundlebun**.
 
-The easiest way to call Bun from Ruby would be `Bundlebun.call`:
+The easiest way to call Bun from Ruby is via `Bundlebun.()` (shortcut for `Bundlebun.call()`).
+
+**Note:** `Bundlebun.call` replaces the current Ruby process with Bun: it never returns.
+
+```ruby
+Bundlebun.('outdated')             # runs `bun outdated`
+Bundlebun.call(['add', 'postcss']) # runs `bun add postcss`
+```
+
+If you need to run Bun and then continue executing your Ruby code, use `Bundlebun.system`:
 
 ```ruby
-Bundlebun.call("outdated") # => `bun outdated`
-Bundlebun.call(["add", "postcss"]) # => `bun add postcss`
+if Bundlebun.system('install')
+  puts 'Dependencies installed!'
+else
+  puts 'Installation failed'
+end
+
+# Run tests and check result
+success = Bundlebun.system('test')
 ```
 
+Returns `true` if Bun exited successfully, `false` or `nil` otherwise.
+
 Check out the [API documentation](https://rubydoc.info/gems/bundlebun) on `Bundlebun::Runner` for helper methods.
 
 ## Versioning

exe/bundlebun

@@ -24,4 +24,4 @@ rescue LoadError
 end
 require 'bundlebun'
 
-Bundlebun::Runner.call(ARGV)
+Bundlebun.call(ARGV)

lib/bundlebun.rb

@@ -9,28 +9,84 @@
 # bundlebun includes binary distributions of Bun for each of the supported
 # platforms (macOS, Linux, Windows) and architectures.
 #
+# bundlebun provides two ways to run Bun:
+#
+# - {.call} (also available as {.exec}): Replaces the current Ruby process with Bun. The default.
+#
+# - {.system}: Runs Bun as a subprocess and returns control to Ruby.
+#   Use this when you need to continue executing Ruby code after Bun finishes.
+#
 # @see Bundlebun::Runner
 # @see Bundlebun::Integrations
+#
+# @example Running Bun (replaces process, never returns)
+#   Bundlebun.('install')                # .() shorthand syntax
+#   Bundlebun.call('outdated')
+#   Bundlebun.call(['add', 'postcss'])
+#
+# @example Running Bun as subprocess (returns to Ruby)
+#   if Bundlebun.system('install')
+#     puts 'Dependencies installed!'
+#   end
 module Bundlebun
   class << self
-    # Runs the Bun runtime with parameters.
+    # Replaces the current Ruby process with Bun.
     #
-    # A shortcut for {Bundlebun::Runner.call}.
+    # This is the default way to run Bun. The Ruby process is replaced by Bun
+    # and never returns. Also available via the +.()+ shorthand syntax.
     #
     # @param arguments [String, Array<String>] Command arguments to pass to Bun
-    # @return [Integer] Exit status code (`127` if executable not found)
+    # @return [void] This method never returns
     #
-    # @example String as an argument
-    #   Bundlebun.call('--version') # => `bun --version`
+    # @example Basic usage
+    #   Bundlebun.call('outdated')
+    #   Bundlebun.call(['add', 'postcss'])
     #
-    # @example Array of strings as an argument
-    #   Bundlebun.call(['add', 'postcss']) # => `bun add postcss`
+    # @example Using the .() shorthand
+    #   Bundlebun.('install')
+    #   Bundlebun.(ARGV)
     #
+    # @see .exec
+    # @see .system
     # @see Bundlebun::Runner.call
     def call(...)
       Runner.call(...)
     end
 
+    # Replaces the current Ruby process with Bun. Same as {.call}.
+    #
+    # @param arguments [String, Array<String>] Command arguments to pass to Bun
+    # @return [void] This method never returns
+    #
+    # @see .call
+    # @see Bundlebun::Runner.exec
+    def exec(...)
+      Runner.exec(...)
+    end
+
+    # Runs Bun as a subprocess and returns control to Ruby.
+    #
+    # Unlike {.call} and {.exec}, this method does not replace the current process.
+    # Use this when you need to run Bun and then continue executing Ruby code.
+    #
+    # @param arguments [String, Array<String>] Command arguments to pass to Bun
+    # @return [Boolean, nil] +true+ if Bun exited successfully (status 0),
+    #   +false+ if it exited with an error, +nil+ if execution failed
+    #
+    # @example Run install and check result
+    #   if Bundlebun.system('install')
+    #     puts 'Dependencies installed!'
+    #   else
+    #     puts 'Installation failed'
+    #   end
+    #
+    # @see .call
+    # @see .exec
+    # @see Bundlebun::Runner.system
+    def system(...)
+      Runner.system(...)
+    end
+
     def loader # @private
       @loader ||= Zeitwerk::Loader.for_gem.tap do |loader|
         loader.ignore("#{__dir__}/tasks")

lib/bundlebun/runner.rb

@@ -3,29 +3,84 @@
 module Bundlebun
   # {Runner} is the class that bundlebun uses to run the bundled Bun executable.
   #
+  # bundlebun provides two ways to run Bun:
+  #
+  # - {.call} (also available as {.exec}): Replaces the current Ruby process with Bun. This is the default.
+  #
+  # - {.system}: Runs Bun as a subprocess and returns control to Ruby.
+  #   Use this when you need to continue executing Ruby code after Bun finishes.
+  #
   # @see Bundlebun
+  #
+  # @example Running Bun (replaces process, never returns)
+  #   Bundlebun.('install')
+  #   Bundlebun.call('outdated')
+  #   Bundlebun.call(['add', 'postcss'])
+  #
+  # @example Running Bun as subprocess (returns to Ruby)
+  #   if Bundlebun.system('install')
+  #     puts 'Dependencies installed!'
+  #   end
   class Runner
     BINSTUB_PATH = 'bin/bun'
     RELATIVE_DIRECTORY = 'lib/bundlebun/vendor/bun'
 
     class << self
-      # Runs the Bun runtime with parameters.
+      # Replaces the current Ruby process with Bun.
+      #
+      # @param arguments [String, Array<String>] Command arguments to pass to Bun
+      # @return [void] This method never returns
       #
-      # A wrapper for {Bundlebun::Runner.new}, {Bundlebun::Runner.call}.
+      # @example In a binstub (bin/bun)
+      #   #!/usr/bin/env ruby
+      #   require 'bundlebun'
+      #   Bundlebun.exec(ARGV)
+      #
+      # @see .call
+      # @see .system
+      def exec(...)
+        new(...).exec
+      end
+
+      # Replaces the current Ruby process with Bun. Alias for {.exec}.
+      # Also available via the +.()+ shorthand syntax.
       #
       # @param arguments [String, Array<String>] Command arguments to pass to Bun
-      # @return [Integer] Exit status code (`127` if executable not found)
+      # @return [void] This method never returns
       #
-      # @example String as an argument
-      #   Bundlebun.call('--version') # => `bun --version`
+      # @example Basic usage
+      #   Bundlebun.call('outdated')
+      #   Bundlebun.call(['add', 'postcss'])
       #
-      # @example Array of strings as an argument
-      #   Bundlebun.call(['add', 'postcss']) # => `bun add postcss`
+      # @example Using the .() shorthand
+      #   Bundlebun.('install')
       #
-      # @see Bundlebun::Runner.new
-      # @see Bundlebun::Runner#call
+      # @see .exec
+      # @see .system
       def call(...)
-        new(...).call
+        exec(...)
+      end
+
+      # Runs Bun as a subprocess and returns control to Ruby.
+      #
+      # Unlike {.call} and {.exec}, this method does not replace the current process.
+      # Use this when you need to run Bun and then continue executing Ruby code.
+      #
+      # @param arguments [String, Array<String>] Command arguments to pass to Bun
+      # @return [Boolean, nil] +true+ if Bun exited successfully (status 0),
+      #   +false+ if it exited with an error, +nil+ if execution failed
+      #
+      # @example Run install and check result
+      #   if Bundlebun.system('install')
+      #     puts 'Dependencies installed!'
+      #   else
+      #     puts 'Installation failed'
+      #   end
+      #
+      # @see .call
+      # @see .exec
+      def system(...)
+        new(...).system
       end
 
       # A relative path to binstub that bundlebun usually generates with installation Rake tasks.
@@ -98,35 +153,64 @@ def binstub_exist?
       end
     end
 
-    # Intialize the {Runner} with arguments to run the Bun runtime later via #call.
+    # Initialize the {Runner} with arguments to run the Bun runtime later.
     #
     # @param arguments [String, Array<String>] Command arguments to pass to Bun
     #
     # @example String as an argument
-    #   Bundlebun::Runner.new('--version') # => `bun --version`
+    #   Bundlebun::Runner.new('--version')
     #
     # @example Array of strings as an argument
-    #   Bundlebun::Runner.new(['add', 'postcss']) # => `bun add postcss`
+    #   Bundlebun::Runner.new(['add', 'postcss'])
     #
-    # @see Bundlebun::Runner#call
+    # @see #system
+    # @see #exec
     def initialize(arguments = '')
       @arguments = arguments
     end
 
-    # Runs the Bun executable with previously specified arguments.
-    #
-    # Check other methods of {Bundlebun::Runner} to see how we determine what to run exactly.
+    # Replaces the current Ruby process with Bun.
+    # This is the default behavior.
     #
-    # @return [Integer] Exit status code (`127` if executable not found)
+    # @return [void] This method never returns
     #
     # @example
-    #   b = Bundlebun::Runner.new('--version')
-    #   b.call
+    #   runner = Bundlebun::Runner.new(ARGV)
+    #   runner.exec  # Ruby process ends here, Bun takes over
+    #
+    # @see #system
+    def exec
+      check_executable!
+      Kernel.exec(command)
+    end
+
+    # Replaces the current Ruby process with Bun. Alias for {#exec}.
+    #
+    # @return [void] This method never returns
     #
-    # @see Bundlebun::Runner
+    # @see #exec
     def call
+      exec
+    end
+
+    # Runs Bun as a subprocess and returns control to Ruby.
+    #
+    # Unlike {#call} and {#exec}, this method does not replace the current process.
+    # Use this when you need to run Bun and then continue executing Ruby code.
+    #
+    # @return [Boolean, nil] +true+ if Bun exited successfully (status 0),
+    #   +false+ if it exited with an error, +nil+ if execution failed
+    #
+    # @example
+    #   runner = Bundlebun::Runner.new('install')
+    #   if runner.system
+    #     puts 'Dependencies installed!'
+    #   end
+    #
+    # @see #exec
+    def system
       check_executable!
-      exec(command)
+      Kernel.system(command)
     end
 
     private

lib/tasks/bun.rake

@@ -17,5 +17,5 @@ require 'rake'
 desc 'Run bundled Bun with parameters. Example: rake "bun[build]"'
 task :bun, [:command] do |_t, args|
   command = args[:command] || ''
-  Bundlebun::Runner.call(command)
+  Bundlebun.call(command)
 end

sig/bundlebun.rbs

@@ -1,7 +1,17 @@
 module Bundlebun
   VERSION: String
 
-  def self.call: (*String arguments) -> void
+  # Replaces the current Ruby process with Bun.
+  # This is the default way to run Bun. Never returns.
+  def self.call: (String | Array[String] arguments) -> bot
+
+  # Replaces the current Ruby process with Bun. Same as .call.
+  def self.exec: (String | Array[String] arguments) -> bot
+
+  # Runs Bun as a subprocess and returns control to Ruby.
+  # Returns true if Bun exited successfully, false if it failed, nil if execution failed.
+  def self.system: (String | Array[String] arguments) -> bool?
+
   def self.prepend_to_path: () -> String?
   def self.load_tasks: () -> void
   def self.load_integrations: () -> Array[Module]

sig/bundlebun/runner.rbs

@@ -3,7 +3,15 @@ module Bundlebun
     BINSTUB_PATH: String
     RELATIVE_DIRECTORY: String
 
-    def self.call: (*String arguments) -> void
+    # Replaces the current Ruby process with Bun. Never returns.
+    def self.exec: (String | Array[String] arguments) -> bot
+
+    # Replaces the current Ruby process with Bun. Alias for .exec. Never returns.
+    def self.call: (String | Array[String] arguments) -> bot
+
+    # Runs Bun as a subprocess and returns control to Ruby.
+    def self.system: (String | Array[String] arguments) -> bool?
+
     def self.binstub_path: () -> String
     def self.full_binstub_path: () -> String
     def self.relative_directory: () -> String
@@ -14,6 +22,14 @@ module Bundlebun
     def self.binstub_exist?: () -> bool
 
     def initialize: (?String | Array[String] arguments) -> void
-    def call: () -> void
+
+    # Replaces the current Ruby process with Bun. Never returns.
+    def exec: () -> bot
+
+    # Replaces the current Ruby process with Bun. Alias for #exec. Never returns.
+    def call: () -> bot
+
+    # Runs Bun as a subprocess and returns control to Ruby.
+    def system: () -> bool?
   end
 end