rascal 0.3.9 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffca96c320440170db495b607004508d9f60aac4d6f387e803084aff3480344f
-  data.tar.gz: ca02687246280f362e0035a697a9061eec1edf46de2ebccdc67fc8999f4902d5
+  metadata.gz: d916ce222f77cd89927ad3ac8ceb56da9d34d87f2f808938b6c796ce92ab3d8b
+  data.tar.gz: 070e9c46b5f33074260638ba1b2e5bb19844c515461788ae904d4b1e72690a7e
 SHA512:
-  metadata.gz: 88d02bffc72f022deea6798ff1ff34561874367b4d30c796162eae4cbad6610018682ad9b7f1992e319d823a6745e5125c723aa0c97938b64ecf79695ca16652
-  data.tar.gz: cf2c78e81c688d8529828b06f7544bc03887005fbd456a09b23c64ccde685a5eecfa6859427a748c8abfca6e3529a1fc351679cdaa4b9aefa261e5a5e6ffc3dc
+  metadata.gz: 7cd38cd621c764d5d8548e4093abc1be639713efc2294b7e80b7fec5d7cdb37648569258c6b8725b604ddcbc756b5916d26b2e6577f8e33a03b100d522b5d957
+  data.tar.gz: '00299e9e4c118a754e0b5227c04d2400d7424a551cddaebc24a1fb85c5649e6c7913835e26754f73d663a4ab50b345ed322198f6f4552c3e3f21d318196cf511'

data/.github/workflows/test.yml

@@ -17,6 +17,8 @@ jobs:
           gemfile: Gemfile
         - ruby: 3.4.1
           gemfile: Gemfile
+        - ruby: 4.0.6
+          gemfile: Gemfile
     env:
       BUNDLE_GEMFILE: "${{ matrix.gemfile }}"
     steps:

data/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project will be documented here.
 
 Rascal follows semantic versioning. This has little consequence pre 1.0, so expect breaking changes.
 
+## 0.4.0 (2026-07-30)
+
+- Add `rascal run ENVIRONMENT -- COMMAND`, which runs a single command in an
+  environment without a TTY and exits with the command's status. Useful for
+  scripts, git hooks and AI agents, which cannot drive `rascal shell`.
+- Add `rascal environments`, which lists available environment names on stdout.
+
+
 ## 0.3.9 (2026-06-19)
 
 - Support variables within service definitions.

data/Gemfile.common

@@ -9,6 +9,7 @@ gem 'rake', '~> 13.0'
 gem 'rspec'
 gem 'cucumber'
 gem 'aruba'
+gem 'logger'
 
 gem 'guard-rspec'
 gem 'guard-cucumber'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rascal (0.3.9)
+    rascal (0.4.0)
       thor (>= 1.0.0)
 
 GEM
@@ -18,7 +18,7 @@ GEM
     builder (3.3.0)
     childprocess (3.0.0)
     coderay (1.1.3)
-    contracts (0.17)
+    contracts (0.17.3)
     cucumber (9.2.1)
       builder (~> 3.2)
       cucumber-ci-environment (> 9, < 11)
@@ -67,6 +67,7 @@ GEM
     listen (3.8.0)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
     lumberjack (1.2.8)
     method_source (1.0.0)
     mini_mime (1.1.5)
@@ -108,6 +109,7 @@ DEPENDENCIES
   cucumber
   guard-cucumber
   guard-rspec
+  logger
   rake (~> 13.0)
   rascal!
   rspec

data/README.md

@@ -101,6 +101,37 @@ Start a docker container (plus required services) and open an interactive shell.
 Currently requires a "bash" to exist.
 
 
+#### rascal run <job> -- <command>
+
+Run a single command in a docker container (plus required services), then exit
+with the command's exit status.
+
+```sh
+rascal run rspec -- bundle exec rspec spec/models/user_spec.rb
+```
+
+Unlike `rascal shell`, this allocates no TTY and needs no interaction, so it can
+be used from scripts, git hooks, editors and AI agents. Everything after `--` is
+passed through as a list of arguments, so arguments may contain spaces (`-n 'a
+test name'`). To use shell syntax such as `&&` or `cd`, wrap it explicitly:
+
+```sh
+rascal run rspec -- bash -c 'cd subproject && bundle exec rspec'
+```
+
+`before_shell` and `after_shell` still run around the command, but do not affect
+the exit status. Note that a failing `before_shell` command (e.g. `bundle check`
+in an environment that was never bundled) does not abort the run.
+
+Currently requires a "bash" to exist.
+
+
+#### rascal environments
+
+Print the names of all available (non-hidden) environments, one per line, so that
+scripts can discover them without parsing an error message.
+
+
 #### rascal clean <job> | --all [--volumes]
 
 Stop and remove all created containers, services, networks for either the given or all jobs.

data/lib/rascal/cli/environments.rb

@@ -0,0 +1,15 @@
+require 'rascal'
+
+module Rascal
+  module CLI
+    class Environments < Base
+      include IOHelper
+
+      def run
+        environment_definition.available_environment_names.each do |name|
+          say name
+        end
+      end
+    end
+  end
+end

data/lib/rascal/cli/main.rb

@@ -36,6 +36,24 @@ module Rascal
         end
       end
 
+      desc 'environments', 'List the names of all available environments'
+      def environments
+        handle_error do
+          Environments.new(self, options).run
+        end
+      end
+
+      # Thor::Actions already defines #run, hence the mapping.
+      map 'run' => '_run'
+      stop_on_unknown_option! :_run
+      desc 'run ENVIRONMENT COMMAND', 'Run a command in the given environment and exit with its status'
+      def _run(environment_name = nil, *command)
+        handle_error do
+          command = command.drop(1) if command.first == '--'
+          Run.new(self, options, environment_name, command).run
+        end
+      end
+
       desc 'clean ENVIRONMENT', 'Stop and remove docker containers for the given environment'
       method_option :volumes, type: :boolean, default: false, desc: 'Remove (cache) volumes'
       method_option :all, type: :boolean, default: false, desc: 'Clean all environments'

data/lib/rascal/cli/run.rb

@@ -0,0 +1,29 @@
+require 'rascal'
+
+module Rascal
+  module CLI
+    class Run < Base
+      def initialize(thor, options, environment_name, command)
+        @environment_name = environment_name
+        @command = command
+        super(thor, options)
+      end
+
+      def run
+        if (environment = find_environment(@environment_name))
+          fail_with_error('Missing command. Example: rascal run job -- bundle exec rake') if @command.empty?
+          status = environment.run_command(*@command)
+          exit(exit_code_for(status))
+        end
+      end
+
+      private
+
+      # A command killed by a signal has no exit status. Report it the way a
+      # shell would, so callers still see a non-zero status.
+      def exit_code_for(status)
+        status.exitstatus || (status.termsig ? 128 + status.termsig : 1)
+      end
+    end
+  end
+end

data/lib/rascal/cli.rb

@@ -2,10 +2,12 @@ require 'thor'
 
 module Rascal
   module CLI
-    autoload :Base,   'rascal/cli/base'
-    autoload :Clean,  'rascal/cli/clean'
-    autoload :Main,   'rascal/cli/main'
-    autoload :Shell,  'rascal/cli/shell'
-    autoload :Update, 'rascal/cli/update'
+    autoload :Base,         'rascal/cli/base'
+    autoload :Clean,        'rascal/cli/clean'
+    autoload :Environments, 'rascal/cli/environments'
+    autoload :Main,         'rascal/cli/main'
+    autoload :Run,          'rascal/cli/run'
+    autoload :Shell,        'rascal/cli/shell'
+    autoload :Update,       'rascal/cli/update'
   end
 end

data/lib/rascal/docker/container.rb

@@ -65,16 +65,14 @@ module Rascal
         )
       end
 
-      def run_and_attach(*command, env: {}, network: nil, volumes: [], working_dir: nil, allow_failure: false)
+      def run_and_attach(*command, env: {}, network: nil, volumes: [], working_dir: nil, allow_failure: false, tty: true)
         Docker.interface.run_and_attach(
           'container',
           'run',
           '--rm',
           '-a', 'STDOUT',
           '-a', 'STDERR',
-          '-a', 'STDIN',
-          '--interactive',
-          '--tty',
+          *(['-a', 'STDIN', '--interactive', '--tty'] if tty),
           *(['-w', working_dir] if working_dir),
           *(volumes.flat_map { |v| ['-v', v.to_param] }),
           *env_args(env),

data/lib/rascal/docker/interface.rb

@@ -30,6 +30,7 @@ module Rascal
         unless allow_failure || exit_status.success?
           raise Error, "docker container run failed"
         end
+        exit_status
       end
 
       private

data/lib/rascal/environment.rb

@@ -1,3 +1,5 @@
+require 'shellwords'
+
 module Rascal
   class Environment
     attr_reader :name, :network, :container, :env_variables, :services, :volumes, :working_dir, :before_shell
@@ -27,6 +29,27 @@ module Rascal
       )
     end
 
+    # Runs a single command in the environment, without a TTY, and returns its
+    # Process::Status. Unlike #run_shell this is suitable for non-interactive
+    # use (scripts, CI-like runs, AI agents), which need the command's real
+    # exit status.
+    #
+    # The command is a list of arguments, which is escaped before being handed
+    # to bash, so arguments may contain spaces and shell metacharacters. Use
+    # e.g. `bash -c "foo && bar"` to run something the shell must interpret.
+    def run_command(*command)
+      download_missing
+      start_services
+      @container.run_and_attach('bash', '-c', command_script(Shellwords.join(command)),
+        env: @env_variables,
+        network: @network,
+        volumes: @volumes,
+        working_dir: @working_dir,
+        allow_failure: true,
+        tty: false
+      )
+    end
+
     def clean(clean_volumes: false)
       @services.each(&:clean)
       @network.clean
@@ -42,6 +65,19 @@ module Rascal
 
     private
 
+    # Runs before_shell/after_shell around the given command, but exits with the
+    # command's status. Without saving it, an `after_shell` entry would determine
+    # the exit status, and failures would go unnoticed.
+    def command_script(command)
+      [
+        *@before_shell,
+        command,
+        '__rascal_status=$?',
+        *@after_shell,
+        'exit $__rascal_status',
+      ].join(';')
+    end
+
     def download_missing
       @container.download_missing
       @services.each(&:download_missing)

data/lib/rascal/version.rb

@@ -1,3 +1,3 @@
 module Rascal
-  VERSION = "0.3.9"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rascal
 version: !ruby/object:Gem::Version
-  version: 0.3.9
+  version: 0.4.0
 platform: ruby
 authors:
 - Tobias Kraze
@@ -54,7 +54,9 @@ files:
 - lib/rascal/cli.rb
 - lib/rascal/cli/base.rb
 - lib/rascal/cli/clean.rb
+- lib/rascal/cli/environments.rb
 - lib/rascal/cli/main.rb
+- lib/rascal/cli/run.rb
 - lib/rascal/cli/shell.rb
 - lib/rascal/cli/update.rb
 - lib/rascal/docker.rb
@@ -97,7 +99,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Spin up CI environments locally.
 test_files: []