rascal 0.3.9 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffca96c320440170db495b607004508d9f60aac4d6f387e803084aff3480344f
-  data.tar.gz: ca02687246280f362e0035a697a9061eec1edf46de2ebccdc67fc8999f4902d5
+  metadata.gz: 8fa4e3608306dedc697f6da5f37017038e694e2c9182cee77fe79f7a448fdfa3
+  data.tar.gz: 38b938c35bbe6dd09df61fae8f292083cbb1177b954516f79e02d980591100ed
 SHA512:
-  metadata.gz: 88d02bffc72f022deea6798ff1ff34561874367b4d30c796162eae4cbad6610018682ad9b7f1992e319d823a6745e5125c723aa0c97938b64ecf79695ca16652
-  data.tar.gz: cf2c78e81c688d8529828b06f7544bc03887005fbd456a09b23c64ccde685a5eecfa6859427a748c8abfca6e3529a1fc351679cdaa4b9aefa261e5a5e6ffc3dc
+  metadata.gz: c8025fa47c2c66853a8ae0080c2230379f35d123346669864ec2f0d899be13a59f2ff9a8af0677784a49bc1b626dbfcad6e0c4985a4f65626861b2f59f8b8fe6
+  data.tar.gz: 931c0a18f53b506c3f8e3d72803505ec32db08c1c070b06b0c34d8d397068d18e37f1cce34ac9f4c944e9a679962d3b4dd1a1cc142cf23c3c10b74debc3a31d0

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,20 @@ 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.1 (2026-07-30)
+
+- Recreate a service container whose network no longer exists, instead of failing
+  to start it.
+
+
+## 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

@@ -23,23 +23,35 @@ module Rascal
       end
 
       def running?
-        if id
-          container_info = Docker.interface.run(
-            'container',
-            'inspect',
-            id,
-            output: :json,
-          ).first
-          !!container_info.dig('State', 'Running')
-        else
-          false
-        end
+        !!container_info&.dig('State', 'Running')
       end
 
       def exists?
         !!id
       end
 
+      # Docker resolves a container's network by the id it recorded when the
+      # container was created, and refuses to start it once that network is
+      # gone:
+      #
+      #   failed to set up container networking: network 36243f82141a... not found
+      #
+      # `docker network prune` (and `docker system prune`) leaves exactly that
+      # behind, because it removes networks whose containers are all stopped —
+      # the normal state of an environment between runs. Reconnecting does not
+      # help, since docker resolves the recorded id before it looks at the
+      # container's current endpoints, so the container has to go. Nothing in a
+      # service container is worth preserving; #start creates a new one.
+      def remove_if_network_missing(network)
+        return unless exists?
+        attached = attached_network_ids
+        return if attached.empty? || attached.include?(network.id)
+
+        say "Removing container for #{@name}, its network no longer exists"
+        remove_container
+        @id = nil
+      end
+
       def start(network: nil, network_alias: nil, volumes: [], env: {}, command: [])
         say "Starting container for #{@name}"
         create(network: network, network_alias: network_alias, volumes: volumes, env: env, command: command) unless exists?
@@ -65,16 +77,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),
@@ -125,6 +135,24 @@ module Rascal
 
       private
 
+      # A fresh `docker container inspect`, or nil if there is no container.
+      def container_info
+        return unless id
+        Docker.interface.run(
+          'container',
+          'inspect',
+          id,
+          output: :json,
+        ).first
+      end
+
+      # Ids of the networks the container is attached to. Empty for a container
+      # that was created but never started.
+      def attached_network_ids
+        networks = container_info&.dig('NetworkSettings', 'Networks') || {}
+        networks.each_value.filter_map { |n| n['NetworkID'] }.reject(&:empty?).uniq
+      end
+
       def image_exists?
         Docker.interface.run(
           'image',

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/docker/network.rb

@@ -39,11 +39,15 @@ module Rascal
         end
       end
 
+      # The full id, not the short one docker prints by default: a container
+      # records the network it is attached to by full id, and
+      # Container#remove_if_network_missing compares the two.
       def id
         @id ||= Docker.interface.run(
           'network',
           'ls',
           '--quiet',
+          '--no-trunc',
           '--filter', "name=^#{@prefixed_name}$",
           output: :id,
         )

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/service.rb

@@ -17,6 +17,7 @@ module Rascal
 
     def start_if_stopped(network: nil)
       unless @container.running?
+        @container.remove_if_network_missing(network)
         if (container_id = @container.id)
           network.disconnect(container_id)
         end

data/lib/rascal/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rascal
 version: !ruby/object:Gem::Version
-  version: 0.3.9
+  version: 0.4.1
 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