galaaz 0.5.0 → 2.0.0

data/Rakefile

@@ -23,8 +23,10 @@
 
 require 'rake/tasklib'
 require 'rake/testtask'
+require 'shellwords'
 
 require_relative 'version'
+require_relative 'lib/galaaz_jruby'
 
 #----------------------------------------------------------------------------------------
 #
@@ -32,12 +34,10 @@ require_relative 'version'
 
 class MakeTask < Rake::TaskLib
 
-  # Create class variables for the polyglot options and libs
-  # not yet possible to run native with R it seems...
-  # @@polyglot_options = "--polyglot --experimental-options --single_threaded"
-  # @@polyglot_options = "--polyglot --jvm --experimental-options --single-threaded"
-  @@polyglot_options = "--polyglot --jvm"
-  @@libs = "-Ilib/" # -Ir_requires/"
+  # JRuby prefix: required JVM flags from GalaazJRuby + -I lib (see lib/galaaz_jruby.rb).
+  def self.galaaz_jruby_invocation
+    "jruby #{GalaazJRuby.shell_j_arg_string} -I lib"
+  end
 
   #----------------------------------------------------------------------------------------
   #
@@ -56,13 +56,15 @@ class MakeTask < Rake::TaskLib
   end
 
   #----------------------------------------------------------------------------------------
-  # Actual TruffleRuby command (with options) to run the example
+  # Run example or spec with JRuby (Galaaz 2.0 Shadow Bridge)
   #----------------------------------------------------------------------------------------
 
   def make_task
-    @rspec ?
-      (sh %{ ruby #{@@polyglot_options} #{@@libs} -S rspec #{@filepath}.rb -f documentation }) :
-      (sh %{ ruby #{@@polyglot_options} #{@@libs} -S #{@filepath}.rb })
+    if @rspec
+      sh %{ #{MakeTask.galaaz_jruby_invocation} -S rspec #{@filepath}.rb -f documentation }
+    else
+      sh %{ #{MakeTask.galaaz_jruby_invocation} #{@filepath}.rb }
+    end
   end
 
   #----------------------------------------------------------------------------------------
@@ -77,8 +79,11 @@ class MakeTask < Rake::TaskLib
   
 end
 
-
-task :default => "sthda:all"
+# Run each .rb file in a directory (for groups that don't have an all.rb)
+def run_each_file(file_list)
+  inv = MakeTask.galaaz_jruby_invocation
+  file_list.each { |f| sh "#{inv} #{f}" }
+end
 
 geoms = FileList['examples/sthda_ggplot/**/*.rb']
 specs = FileList['specs/**/*.rb']
@@ -165,6 +170,35 @@ bugs.each do |f|
   Desc
 end
 
+#===========================================================================================
+# Aggregate "all" tasks for groups that have multiple files (no single all.rb)
+# sthda:all and islr:all already exist from MakeTask (they run all.rb in that dir)
+#===========================================================================================
+
+desc "Run all misc examples"
+task "misc:all" do
+  run_each_file(misc.to_a)
+end
+
+desc "Run all 50Plots_MasterList examples"
+task "master_list:all" do
+  run_each_file(master_list.to_a)
+end
+
+desc "Run all bug examples"
+task "bugs:all" do
+  run_each_file(bugs.to_a)
+end
+
+#===========================================================================================
+# Run all example groups (sthda_ggplot, misc, 50Plots_MasterList, islr, bugs)
+#===========================================================================================
+
+desc "Run all examples (sthda_ggplot, misc, 50Plots_MasterList, islr, bugs)"
+task "examples:all" => ["sthda:all", "misc:all", "master_list:all", "islr:all", "bugs:all"]
+
+task :default => "examples:all"
+
 #===========================================================================================
 # Creates task for running gknit
 #===========================================================================================
@@ -179,15 +213,6 @@ blogs.each do |dir|
 
 end
 
-#===========================================================================================
-# Loads R and require libraries to run Galaaz
-#===========================================================================================
-
-desc 'Prepare R for running'
-task :make_r do
-  (sh %{ gu install r })
-end
-
 #===========================================================================================
 # Makes a gem for publishing in RubyGems
 #===========================================================================================
@@ -206,27 +231,22 @@ task :publish_gem do
   (sh %{ gem push #{$gem_name}-#{$version}.gem })
 end
 
-=begin
-desc 'default task'
-task :default => [:install_gem]
-
-desc 'Install the gem in the standard location'
-task :install_gem => [:make_gem] do
-  sh "gem install #{$gem_name}-#{$version}-java.gem"
-end
+#===========================================================================================
+# NewBridge gatekeeper + combined spec run (JRuby; see also bin/run_all_rspec)
+#===========================================================================================
 
-desc 'Make documentation'
-task :make_doc do
-  sh "yard doc lib/*.rb lib/**/*.rb"
+desc 'Compile the NewBridge gatekeeper shared library (ext/new_bridge; incremental make)'
+task :compile_gatekeeper do
+  Dir.chdir('ext/new_bridge') { sh 'make all' }
 end
 
-Rake::TestTask.new do |t|
-  t.libs << "test"
-  t.test_files = FileList['test/complete.rb']
-  t.ruby_opts = ["--server", "-Xinvokedynamic.constants=true", "-J-Xmn512m", 
-                 "-J-Xms1024m", "-J-Xmx1024m"]
-  t.verbose = true
-  t.warning = true
+desc 'Run specs/ and new_bridge_specs/ under JRuby with SimpleCov (same idea as bin/run_all_rspec)'
+task :specs_all_with_new_bridge => [:compile_gatekeeper] do
+  root = File.expand_path(__dir__)
+  inv = MakeTask.galaaz_jruby_invocation
+  top = Dir[File.join(root, 'specs', '*_spec.rb')] + Dir[File.join(root, 'specs', '*.spec.rb')]
+  files = top.sort.map { |p| Shellwords.escape(p) }.join(' ')
+  nb = Shellwords.escape(File.join(root, 'new_bridge_specs'))
+  helper = Shellwords.escape(File.join(root, 'specs', 'spec_helper.rb'))
+  sh %{ #{inv} -r #{helper} -S bundle exec rspec #{files} #{nb} }
 end
-
-=end

data/bin/galaaz-bootstrap

@@ -0,0 +1,137 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optparse'
+require 'open3'
+
+ROOT = File.expand_path('..', __dir__)
+$LOAD_PATH.unshift(File.join(ROOT, 'lib'))
+
+require 'new_bridge/bootstrap/windows_bootstrap'
+
+mode = :check
+runtime_mode = :auto
+prompt_doc_tools = true
+
+OptionParser.new do |opts|
+  opts.banner = 'Usage: bin/galaaz-bootstrap [--check|--apply] [--runtime docker|local|auto]'
+
+  opts.on('--check', 'Run diagnostics only (default)') do
+    mode = :check
+  end
+
+  opts.on('--apply', 'Apply WSL-side fixes where possible') do
+    mode = :apply
+  end
+
+  opts.on('--runtime MODE', 'Runtime mode: auto (default), docker, or local') do |v|
+    runtime_mode = v.to_sym
+  end
+
+  opts.on('--[no-]prompt-doc-tools',
+          'In apply mode, ask to install TinyTeX/poppler for gknit PDF support (default: enabled)') do |v|
+    prompt_doc_tools = v
+  end
+end.parse!(ARGV)
+
+bootstrap = NewBridge::Bootstrap::WindowsBootstrap.new
+result = bootstrap.run(mode: mode, runtime_mode: runtime_mode)
+
+def command_exists?(cmd)
+  system("command -v #{cmd} >/dev/null 2>&1")
+end
+
+def yes_no_prompt(question, default_yes: true)
+  return default_yes unless $stdin.tty? && $stdout.tty?
+
+  suffix = default_yes ? '[Y/n]' : '[y/N]'
+  print "#{question} #{suffix} "
+  answer = $stdin.gets
+  return default_yes if answer.nil?
+
+  value = answer.strip.downcase
+  return default_yes if value.empty?
+  return true if %w[y yes].include?(value)
+  return false if %w[n no].include?(value)
+
+  default_yes
+end
+
+def install_tinytex
+  return puts('TinyTeX/LaTeX already available (pdflatex found).') if command_exists?('pdflatex')
+
+  installer = File.join(ROOT, 'bin', 'install-tinytex')
+  cmd =
+    if File.exist?(installer)
+      "bash #{installer.inspect}"
+    else
+      "curl -fsSL https://raw.githubusercontent.com/rstudio/tinytex/master/tools/install-bin-unix.sh | sh"
+    end
+
+  puts 'Installing TinyTeX (LaTeX) for gknit/pdf_document...'
+  ok = system(cmd)
+  puts('TinyTeX install finished.') if ok
+  puts('TinyTeX install failed. Re-run manually: bin/install-tinytex') unless ok
+  puts 'PATH note: ensure ~/bin is available in your shell, or use the Phase 2 spec env helper.'
+end
+
+def install_poppler
+  return puts('Poppler already available (pdftotext found).') if command_exists?('pdftotext')
+
+  puts 'Installing poppler-utils (pdftotext) for full PDF text assertions...'
+  ok = system('sudo apt-get update && sudo apt-get install -y poppler-utils')
+  puts('poppler-utils installed.') if ok
+  puts('poppler-utils install failed or was cancelled.') unless ok
+end
+
+def arrow_available_in_r?
+  return false unless command_exists?('Rscript')
+
+  system(%q{Rscript -e "quit(status = ifelse(requireNamespace('arrow', quietly=TRUE), 0, 1))"})
+end
+
+def install_arrow
+  unless command_exists?('Rscript')
+    puts 'Rscript not found; cannot install arrow package.'
+    return
+  end
+
+  if arrow_available_in_r?
+    puts 'R arrow package already available.'
+    return
+  end
+
+  puts 'Installing R arrow package for Galaaz Arrow helpers...'
+  ok = system(%q{Rscript -e "install.packages('arrow', repos='https://cloud.r-project.org/')"})
+  unless ok && arrow_available_in_r?
+    puts 'arrow install failed or package still unavailable.'
+    puts "Try manually: Rscript -e \"install.packages('arrow', repos='https://cloud.r-project.org/')\""
+    return
+  end
+
+  puts 'R arrow package installed.'
+end
+
+def verify_arrow_from_ruby
+  cmd = "bin/galaaz-jruby -I lib -e \"require 'galaaz'; df=R.data__frame(x:(1..2), y:(2..1)); t=R::Arrow.table_from(df); puts t.rclass\""
+  ok = system("cd #{ROOT.inspect} && #{cmd}")
+  puts(ok ? 'Ruby Arrow bridge check passed.' : 'Ruby Arrow bridge check failed.')
+end
+
+if mode == :apply && prompt_doc_tools
+  if yes_no_prompt('Will you render PDF documents with gknit (LaTeX required)?', default_yes: true)
+    install_tinytex
+
+    if yes_no_prompt('Also install poppler (pdftotext) for strict PDF text checks?', default_yes: true)
+      install_poppler
+    end
+  end
+
+  if yes_no_prompt('Will you use Arrow (Feather/Parquet) from Ruby/R?', default_yes: true)
+    install_arrow
+    verify_arrow_from_ruby if yes_no_prompt('Run a quick Ruby Arrow bridge verification now?', default_yes: true)
+  end
+end
+
+exit(result[:exit_code])
+

data/bin/galaaz-jruby

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Run jruby with Galaaz-required JVM flags and lib/ on the load path.
+# Optional: GALAAZ_JRUBY_OPTS (space-separated extra -J... or jruby args).
+#
+# Usage: bin/galaaz-jruby path/to/script.rb [args...]
+#        bin/galaaz-jruby -S rspec specs/foo_spec.rb
+set -e
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=galaaz_jruby_env.inc.sh
+source "$ROOT/bin/galaaz_jruby_env.inc.sh"
+exec jruby -I "$ROOT/lib" \
+  $GALAAZ_REQUIRED_JRUBY_J_ARGS \
+  ${GALAAZ_JRUBY_OPTS:-} \
+  "$@"

data/bin/galaaz_jruby_env.inc.sh

@@ -0,0 +1,6 @@
+# Galaaz required JVM flags for JRuby (Apache Arrow on Java 9+).
+# Source from bin/*.sh:  source "$ROOT/bin/galaaz_jruby_env.inc.sh"
+#
+# Source of truth in Ruby/Rake: lib/galaaz_jruby.rb (GalaazJRuby::REQUIRED_JRUBY_J_ARGS).
+# Optional extra -J flags: export GALAAZ_JRUBY_OPTS="-J-Xmx4g" (space-separated).
+GALAAZ_REQUIRED_JRUBY_J_ARGS='-J--add-opens=java.base/java.nio=ALL-UNNAMED'

data/bin/gbookdown

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+# coding: utf-8
+
+require 'optparse'
+require 'shellwords'
+
+options = {}
+parser = OptionParser.new do |opts|
+  opts.banner = 'Usage: gbookdown [options]'
+
+  opts.on('-f', '--filename FILE', 'Bookdown input file (typically index.Rmd).') do |opt|
+    options[:input_file] = opt
+  end
+
+  opts.on('--output_format FORMAT',
+          "Bookdown output format (e.g. 'bookdown::gitbook', 'bookdown::pdf_book').") do |opt|
+    options[:output_format] = opt
+  end
+
+  opts.on('--bridge_timeout_sec TIMEOUT_SEC', Integer,
+          'Bridge request timeout in seconds for Ruby->R eval calls.') do |opt|
+    options[:bridge_timeout_sec] = opt
+  end
+
+  opts.on('--callback_timeout_ms TIMEOUT_MS', Integer,
+          'Callback timeout in milliseconds for R<->Ruby calls.') do |opt|
+    options[:callback_timeout_ms] = opt
+  end
+end
+
+remaining_args = parser.permute(ARGV.dup)
+ARGV.replace(remaining_args)
+
+options[:input_file] ||= ARGV[0]
+raise 'Input file name is required. Add -f FILE. For help, type gbookdown -h' if options[:input_file].nil?
+
+input_file = File.expand_path(options[:input_file], Dir.pwd)
+raise "File #{input_file} does not exist!" unless File.exist?(input_file)
+
+input_dir = File.dirname(input_file)
+output_format = options[:output_format].nil? ? 'nil' : %("#{options[:output_format]}")
+r_call = "bookdown::render_book(#{File.basename(input_file).inspect}, #{output_format})"
+
+puts '================================'
+puts "gBookdown #{input_file} with options:"
+puts "   * Output format: \t #{output_format}"
+
+code = <<EOF
+ENV['GALAAZ_CALLBACK_TIMEOUT_MS'] = #{options[:callback_timeout_ms].to_s.inspect} if #{!options[:callback_timeout_ms].nil?}
+ENV['GALAAZ_BRIDGE_TIMEOUT_SEC'] = #{options[:bridge_timeout_sec].to_s.inspect} if #{!options[:bridge_timeout_sec].nil?}
+require %q(galaaz)
+require %q(gknit)
+
+Dir.chdir(#{input_dir.inspect}) do
+  R.install_and_loads('bookdown')
+  R::Support.eval(#{r_call.inspect})
+end
+EOF
+
+libx = File.expand_path('../lib', File.dirname(__FILE__))
+require File.join(libx, 'galaaz_jruby')
+jvm_args = GalaazJRuby.shell_j_arg_string
+exec "jruby #{jvm_args} -I#{libx} -e #{Shellwords.escape(code)}"
+

data/bin/gknit

@@ -2,10 +2,10 @@
 # coding: utf-8
 
 require 'optionparser'
+require 'shellwords'
 
 options = {}
-
-OptionParser.new do |opts|
+parser = OptionParser.new do |opts|
   opts.banner = "Usage: gknit [options]"
   opts.on("-f", "--filename FILE", "The input file to be rendered.  
 This value can also be provided without the '-f' or '--filename' 
@@ -59,7 +59,19 @@ file.") do |opt|
 that are created during rendering.") do |opt|
     options[:clean] = opt
   end
-end.parse!
+  opts.on("--debugR", "Log R/Ruby bridge traffic to logs; print only [RUBY] (commands sent) to stderr. Full R output is in logs/galaaz_r_stdout.log.") do
+    ENV["GALAAZ_DEBUG_R"] = "1"
+  end
+  opts.on("--callback_timeout_ms TIMEOUT_MS", Integer, "Callback timeout in milliseconds for R<->Ruby calls inside chunk execution. Use for long installs/computation (e.g., 7200000 for 2h).") do |opt|
+    options[:callback_timeout_ms] = opt
+  end
+  opts.on("--bridge_timeout_sec TIMEOUT_SEC", Integer, "Bridge request timeout in seconds for Ruby->R eval calls (default 60). Increase for long install.packages/compilation work.") do |opt|
+    options[:bridge_timeout_sec] = opt
+  end
+end
+
+remaining_args = parser.permute(ARGV.dup)
+ARGV.replace(remaining_args)
 
 # Sets the directory
 dir = Dir.pwd
@@ -133,22 +145,81 @@ puts "   * Output directory: \t #{options[:output_dir]}"
 puts "   * Clean: \t\t #{options[:clean]}"
 
 
-# Code to be evaluated by the polyglot Ruby script
+# Code to be evaluated by the polyglot Ruby script.
+# Run render with the input file's directory as current so figure paths (e.g. oh_my_files/figure-html/)
+# are created and found inside the document directory (e.g. blogs/oh_my/).
+input_file = options[:input_file]
+input_dir = File.dirname(input_file)
 code = <<EOF
+ENV['GALAAZ_CALLBACK_TIMEOUT_MS'] = #{options[:callback_timeout_ms].to_s.inspect} if #{!options[:callback_timeout_ms].nil?}
+ENV['GALAAZ_BRIDGE_TIMEOUT_SEC'] = #{options[:bridge_timeout_sec].to_s.inspect} if #{!options[:bridge_timeout_sec].nil?}
 require %q(galaaz)
 require %q(gknit)
 
-R::Rmarkdown.render(
-     %q(#{options[:input_file]}),
-     output_format: #{options[:output_format]},
-     output_file: #{options[:output_file]},
-     output_dir: #{options[:output_dir]},
-     clean: #{options[:clean]}
-) 
+Dir.chdir(#{input_dir.inspect}) do
+  GknitDiagnostics.reset! if defined?(GknitDiagnostics)
+  begin
+    R::Rmarkdown.render(
+         %q(#{input_file}),
+         output_format: #{options[:output_format]},
+         output_file: #{options[:output_file]},
+         output_dir: #{options[:output_dir]},
+         clean: #{options[:clean]}
+    )
+  rescue StandardError => e
+    # Friendly handling for LaTeX/render errors (including bridge timeout wrappers):
+    # prefer actionable message over a Ruby stack trace.
+    log_file = begin
+      base = File.basename(%q(#{input_file}), File.extname(%q(#{input_file})))
+      candidate = File.join(Dir.pwd, "\#{base}.log")
+      File.file?(candidate) ? candidate : nil
+    rescue StandardError
+      nil
+    end
+
+    missing_pkg = nil
+    latex_fatal = nil
+    if log_file
+      begin
+        log_text = File.read(log_file)
+        m = log_text.match(/LaTeX Error: File [`']([^`']+\.sty)[`'] not found\./)
+        missing_pkg = m[1] if m
+        fatal_match = log_text.match(/!pdfTeX error:[^\n]+/)
+        latex_fatal = fatal_match[0] if fatal_match
+      rescue StandardError
+        missing_pkg = nil
+        latex_fatal = nil
+      end
+    end
+
+    STDERR.puts "gknit render failed: \#{e.message}"
+    if e.message.to_s.include?('no RET for')
+      callback_ms = ENV['GALAAZ_CALLBACK_TIMEOUT_MS'] || '120000'
+      bridge_sec = ENV['GALAAZ_BRIDGE_TIMEOUT_SEC'] || '60'
+      STDERR.puts "Likely bridge timeout during long-running Ruby->R evaluation."
+      STDERR.puts "Current bridge timeout: \#{bridge_sec} sec; callback timeout: \#{callback_ms} ms."
+      STDERR.puts "Use gknit --bridge_timeout_sec <sec> and/or --callback_timeout_ms <ms> for longer operations."
+    end
+    if missing_pkg
+      STDERR.puts "Likely missing LaTeX package: \#{missing_pkg} (install with tlmgr)."
+    elsif latex_fatal
+      STDERR.puts "LaTeX fatal error: \#{latex_fatal}"
+    elsif log_file
+      STDERR.puts "See LaTeX log for details: \#{log_file}"
+    end
+    exit 1
+  ensure
+    GknitDiagnostics.print_report(STDERR) if defined?(GknitDiagnostics)
+  end
+end
 EOF
 
-libx = File.expand_path('../../lib', __FILE__)
-exec "ruby --polyglot --jvm --experimental-options --single-threaded -I#{libx} -e '#{code}'"
+libx = File.expand_path('../lib', File.dirname(__FILE__))
+require File.join(libx, 'galaaz_jruby')
+jvm_args = GalaazJRuby.shell_j_arg_string
+ENV['GALAAZ_CALLBACK_TIMEOUT_MS'] = options[:callback_timeout_ms].to_s if !options[:callback_timeout_ms].nil?
+ENV['GALAAZ_BRIDGE_TIMEOUT_SEC'] = options[:bridge_timeout_sec].to_s if !options[:bridge_timeout_sec].nil?
+exec "jruby #{jvm_args} -I#{libx} -e #{Shellwords.escape(code)}"
 
 =begin
 # how to call rmarkdown::render with a parameter list

data/bin/gstudio

@@ -23,6 +23,7 @@
 ##########################################################################################
 
 require 'optionparser'
+require 'shellwords'
 
 options = {}
 
@@ -40,12 +41,13 @@ end.parse!
 
 bin_dir = File.expand_path('..', __FILE__)
 libx = File.expand_path('../../lib', __FILE__)
+require File.join(libx, 'galaaz_jruby')
+jvm_args = GalaazJRuby.shell_j_arg_string
 
 if options[:pry]
   puts "Loading PRY and Galaaz... Please wait!"
-  #exec "ruby --polyglot --jvm -I#{libx} -S pry -r #{bin_dir}/gstudio_pry.rb"
-  exec "ruby --polyglot --jvm --experimental-options --single-threaded -I#{libx} -S pry -r #{bin_dir}/gstudio_pry.rb"  
+  exec "jruby #{jvm_args} -I#{Shellwords.escape(libx)} -S pry -r #{Shellwords.escape(File.join(bin_dir, 'gstudio_pry.rb'))}"
 else
   puts "Loading IRB and Galaaz... Please wait!"
-  exec "ruby --polyglot --jvm -I#{libx} -S irb -r #{bin_dir}/gstudio_irb.rb"
+  exec "jruby #{jvm_args} -I#{Shellwords.escape(libx)} -S irb -r #{Shellwords.escape(File.join(bin_dir, 'gstudio_irb.rb'))}"
 end

data/bin/install-tinytex

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Install TinyTeX to ~/.TinyTeX with symlinks in ~/bin (no sudo).
+# Needed for rmarkdown pdf_document and specs/phase2_gknit_chunk_output_spec.rb.
+set -euo pipefail
+curl -fsSL https://raw.githubusercontent.com/rstudio/tinytex/master/tools/install-bin-unix.sh | sh
+echo "TinyTeX installed. Ensure ~/bin is on PATH for interactive shells, or rely on the Phase 2 spec prepending it for gknit."

data/bin/run_all_rspec

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Run default galaaz specs (specs/) and NewBridge gatekeeper specs (new_bridge_specs/)
+# in a single RSpec process so SimpleCov produces one merged report under coverage/.
+#
+# Compiles ext/new_bridge (incremental make) first — required for integration specs.
+#
+# Usage:
+#   bin/run_all_rspec
+#   bin/run_all_rspec --format documentation
+#   bin/run_all_rspec new_bridge_specs/phase0_protocol_spec.rb
+#
+# If the first argument is an option (starts with -), default dirs are prepended
+# so `bin/run_all_rspec --format doc` still runs specs/ + new_bridge_specs/.
+#
+# For specs/ only (faster day-to-day): bin/run_rspec
+set -e
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=galaaz_jruby_env.inc.sh
+source "$ROOT/bin/galaaz_jruby_env.inc.sh"
+
+echo "[run_all_rspec] compiling gatekeeper: ext/new_bridge"
+make -C "$ROOT/ext/new_bridge" -s all
+
+# Same top-level file set as bin/run_rspec (maxdepth 1), plus whole new_bridge_specs/ tree.
+DEFAULT_SPECS=()
+while IFS= read -r f; do
+  DEFAULT_SPECS+=("$f")
+done < <(find "$ROOT/specs" -maxdepth 1 -type f \( -name '*_spec.rb' -o -name '*.spec.rb' \) | sort)
+DEFAULT_SPECS+=( "$ROOT/new_bridge_specs" )
+
+# With no args, run those paths. If args are only RSpec options (e.g. --format progress),
+# prepend defaults so flags alone do not mean "run zero files".
+if [ $# -eq 0 ]; then
+  set -- "${DEFAULT_SPECS[@]}"
+elif [[ "${1:-}" == -* ]]; then
+  set -- "${DEFAULT_SPECS[@]}" "$@"
+fi
+exec jruby -I "$ROOT/lib" \
+  $GALAAZ_REQUIRED_JRUBY_J_ARGS \
+  ${GALAAZ_JRUBY_OPTS:-} \
+  -S bundle exec rspec \
+  -r "$ROOT/specs/spec_helper.rb" \
+  "$@"

data/bin/run_example

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Run a Galaaz example with required JRuby JVM flags (lib/galaaz_jruby.rb).
+# Optional: GALAAZ_JRUBY_OPTS.
+#
+# Usage: bin/run_example examples/sthda_ggplot/all.rb
+#        bin/run_example examples/sthda_ggplot/one_variable_continuous/geom_density.rb
+set -e
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=galaaz_jruby_env.inc.sh
+source "$ROOT/bin/galaaz_jruby_env.inc.sh"
+exec jruby -I "$ROOT/lib" \
+  $GALAAZ_REQUIRED_JRUBY_J_ARGS \
+  ${GALAAZ_JRUBY_OPTS:-} \
+  "$@"

data/bin/run_old_rspec

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Run legacy specs moved to old_specs/.
+# Usage:
+#   bin/run_old_rspec
+#   bin/run_old_rspec old_specs/r_environment.spec.rb
+set -e
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=galaaz_jruby_env.inc.sh
+source "$ROOT/bin/galaaz_jruby_env.inc.sh"
+if [ $# -eq 0 ]; then
+  shopt -s nullglob
+  SPECS=( "$ROOT"/old_specs/*.spec.rb "$ROOT"/old_specs/*_spec.rb )
+  IFS=$'\n' SPECS=( $(printf '%s\n' "${SPECS[@]}" | sort) )
+  set -- "${SPECS[@]}"
+fi
+exec jruby -I "$ROOT/lib" \
+  $GALAAZ_REQUIRED_JRUBY_J_ARGS \
+  ${GALAAZ_JRUBY_OPTS:-} \
+  -S bundle exec rspec "$@"

data/bin/run_rspec

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Run rspec with JVM options required for Apache Arrow (see lib/galaaz_jruby.rb).
+# Optional JVM/jruby extras: GALAAZ_JRUBY_OPTS (space-separated).
+#
+# Usage:
+#   bin/run_rspec              # run fast specs in specs/ only
+#   bin/run_all_rspec          # top-level specs/ + new_bridge_specs/ + gatekeeper compile (see docs/testing.md)
+#   bin/run_slow_rspec         # run slow specs in slow-specs/
+#   bin/run_rspec specs/protocol_result_spec.rb
+#   GALAAZ_DEBUG=1 bin/run_rspec specs/r_vector_subsetting.spec.rb:61 ...
+set -e
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=galaaz_jruby_env.inc.sh
+source "$ROOT/bin/galaaz_jruby_env.inc.sh"
+if [ $# -eq 0 ]; then
+  set -- $(find "$ROOT/specs" -maxdepth 1 -type f \( -name '*_spec.rb' -o -name '*.spec.rb' \) | sort)
+fi
+exec jruby -I "$ROOT/lib" \
+  $GALAAZ_REQUIRED_JRUBY_J_ARGS \
+  ${GALAAZ_JRUBY_OPTS:-} \
+  -S bundle exec rspec \
+  -r "$ROOT/specs/spec_helper.rb" \
+  "$@"