all_images 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbf39eaf44bd3eef5cba7b22e942621717fd838cde984764c684ba2a7f8842f7
-  data.tar.gz: f8c257c224e80f2ae251ec8e05b8869d3348ae0408d4a0dadd789ef74ce182c3
+  metadata.gz: 42b558d4ade42f9b21753fda5785174363fa80a5ffd8ff1989e7976250d249f1
+  data.tar.gz: 9291ccd0e8c4395825cd2bd4dd0123f5c84f62e5af15405affbec47eaf43d692
 SHA512:
-  metadata.gz: 39b423c850d91d8a7261c2b4677ba9935486797e0dd08ab2cca2ed6e9af78c162296cd89daa7e7ce71dd23999fed098f4158edc57d34222d99ef38db495bca10
-  data.tar.gz: 4a2d1611e0452b452963c099aed19163af335290015b25b72757db37803827a304d77282c3cc0919cfc0b24855703d8fb727cd74dd4c11664edcee7b3bbbac08
+  metadata.gz: b98d326311eb1fb12ced669ab1134a473a12d985118c8ff66911bee5282f17c1f09a92ace674c7d14f78a571212b78113fc11592b8612fc5c19f21a503329c37
+  data.tar.gz: a3e3fd149747181efd18dd8283f7591a0cf8a39b32ae1b5dffea51fd19c0b14864eb3306e0478723a22555845c89d46c2c2015b7fd85a9c708ed37b7b495bb24

data/.utilsrc

@@ -1,18 +1,17 @@
 # vim: set ft=ruby:
 
 search do
-  prune_dirs /\A(\.svn|\.git|CVS|tmp|tags|coverage|pkg)\z/
+  prune_dirs /\A(\.svn|\.git|CVS|tmp|tags|coverage|pkg|\.yardoc)\z/
   skip_files /(\A\.|\.sw[pon]\z|\.(log|fnm|jpg|jpeg|png|pdf|svg)\z|tags|~\z)/i
 end
 
 discover do
-  prune_dirs /\A(\.svn|\.git|CVS|tmp|tags|coverage|pkg)\z/
+  prune_dirs /\A(\.svn|\.git|CVS|tmp|tags|coverage|pkg|\.yardoc)\z/
   skip_files /(\A\.|\.sw[pon]\z|\.log\z|~\z)/
-  binary false
 end
 
 strip_spaces do
-  prune_dirs /\A(\..*|CVS|pkg)\z/
+  prune_dirs /\A(\..*|CVS|pkg|\.yardoc)\z/
   skip_files /(\A\.|\.sw[pon]\z|\.log\z|~\z)/
 end
 

data/CHANGES.md

@@ -1,5 +1,18 @@
 # Changes
 
+## 2025-09-03 v0.7.0
+
+- **Interactive Image Selection**: Integrated `SearchUI` for enhanced user
+  experience when selecting Docker images
+- **Improved Configuration Handling**: Better error handling and fallback
+  mechanisms for configuration loading
+- Removed support for Ruby **3.0** and **3.1**
+- Added support for Ruby **3.4** with `ruby:3.4-alpine` image configuration
+- Simplified SimpleCov setup using `GemHadar::SimpleCov.start`
+- Removed obsolete `binary` option from utils config
+- Added comprehensive documentation across the library
+- Improved logging with `info_puts` method for colored console output
+
 ## 2024-10-14 v0.6.0
 
 ### Significant Changes

data/Rakefile

@@ -10,18 +10,19 @@ GemHadar do
   summary     'Runs a script in all of the docker images'
   description 'A script that runs a script in all of the configured docker images'
   test_dir    'spec'
-  ignore      '.*.sw[pon]', 'pkg', 'Gemfile.lock', 'coverage',
-    '.AppleDouble', 'tags', '.DS_Store'
   readme      'README.md'
   title       "#{name.camelize} -- #{summary}"
+  licenses << 'MIT'
+  executables << 'all_images'
+  ignore      '.*.sw[pon]', 'pkg', 'Gemfile.lock', 'coverage',
+    '.AppleDouble', 'tags', '.DS_Store', '.yardoc'
   package_ignore '.all_images.yml', '.gitignore', 'VERSION'
 
-  dependency  'tins', '~>1.0'
-  dependency  'term-ansicolor'
+  dependency  'tins',           '~> 1.42'
+  dependency  'search_ui',      '~> 0.0'
+  dependency  'term-ansicolor', '~> 1.11'
   development_dependency 'rake'
   development_dependency 'simplecov'
   development_dependency 'rspec'
   development_dependency 'debug'
-  licenses << 'MIT'
-  executables << 'all_images'
 end

data/all_images.gemspec

@@ -1,14 +1,14 @@
 # -*- encoding: utf-8 -*-
-# stub: all_images 0.6.0 ruby lib
+# stub: all_images 0.7.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "all_images".freeze
-  s.version = "0.6.0".freeze
+  s.version = "0.7.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
   s.authors = ["Florian Frank".freeze]
-  s.date = "2024-10-14"
+  s.date = "1980-01-02"
   s.description = "A script that runs a script in all of the configured docker images".freeze
   s.email = "flori@ping.de".freeze
   s.executables = ["all_images".freeze]
@@ -17,17 +17,18 @@ Gem::Specification.new do |s|
   s.homepage = "https://github.com/flori/all_images".freeze
   s.licenses = ["MIT".freeze]
   s.rdoc_options = ["--title".freeze, "AllImages -- Runs a script in all of the docker images".freeze, "--main".freeze, "README.md".freeze]
-  s.rubygems_version = "3.5.18".freeze
+  s.rubygems_version = "3.6.9".freeze
   s.summary = "Runs a script in all of the docker images".freeze
   s.test_files = ["spec/app_spec.rb".freeze, "spec/spec_helper.rb".freeze]
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 1.19".freeze])
+  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 2.2".freeze])
   s.add_development_dependency(%q<rake>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<simplecov>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<rspec>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<debug>.freeze, [">= 0".freeze])
-  s.add_runtime_dependency(%q<tins>.freeze, ["~> 1.0".freeze])
-  s.add_runtime_dependency(%q<term-ansicolor>.freeze, [">= 0".freeze])
+  s.add_runtime_dependency(%q<tins>.freeze, ["~> 1.42".freeze])
+  s.add_runtime_dependency(%q<search_ui>.freeze, ["~> 0.0".freeze])
+  s.add_runtime_dependency(%q<term-ansicolor>.freeze, ["~> 1.11".freeze])
 end

data/lib/all_images/app.rb

@@ -4,28 +4,60 @@ require 'fileutils'
 require 'tins'
 require 'tins/xt/full'
 require 'shellwords'
+require 'search_ui'
 
+# AllImages::App is the core application class that orchestrates Docker image
+# execution workflows
+#
+# This class provides the main interface for running scripts across multiple
+# Docker images, handling configuration loading, command processing, and Docker
+# container operations.
+#
+# It supports various commands including listing available images, running all
+# images, running specific images, and debugging interactive sessions.
+#
+# The application manages Docker image building, tagging, and cleanup while
+# providing environment variable handling and error reporting capabilities.
 class AllImages::App
   include Term::ANSIColor
   include FileUtils
+  include SearchUI
 
+  # Initializes a new instance of the AllImages application
+  #
+  # Sets up the application with the provided command-line arguments,
+  # determines the initial command to execute, and prepares internal state
+  # for processing configuration and Docker image operations.
+  #
+  # @param args [ Array<String> ] the command-line arguments passed to the
+  # application
   def initialize(args)
     @args     = args.dup
+    @config   = load_config or return 23
     @command  = pick_command
     @commands = %w[ ls help run debug run_all ].sort
     @suffix   = Tins::Token.new(alphabet: Tins::Token::BASE32_ALPHABET, bits: 32)
   end
 
+  # Executes the configured command across Docker images
+  #
+  # Processes the specified command and runs it against the configured Docker
+  # images. Depending on the command, this method may list available images,
+  # display help information, or execute scripts in containers. It handles both
+  # individual image execution and batch processing of all configured images.
+  #
+  # @return [ Integer ] the cumulative result code from executing commands
+  # across images, where 0 indicates success and non-zero values indicate
+  # failures
   def run
-    @config   = load_config or return 23
-    result = 0
+    result  = 0
     case @command
     when 'ls'
-      puts Array(@config['images']).map(&:first)
+      puts images.map(&:first)
     when 'help'
       puts "Usage: #{File.basename($0)} #{@commands * ?|} [IMAGE]"
     else
-      Array(@config['images']).each do |image, script|
+      images.each do |image, script|
         case @command
         when 'run_all'
           result |= run_image(image, script)
@@ -44,6 +76,33 @@ class AllImages::App
 
   private
 
+  # Returns an array of configured Docker images for execution
+  #
+  # This method retrieves the list of Docker images from the application's
+  # configuration and ensures it is returned as an Array instance, even if the
+  # configuration contains a single image value rather than an array.
+  #
+  # @return [ Array<String> ] an array containing the names of Docker images
+  #                           to be processed by the application
+  def images
+     Array(@config['images'])
+  end
+
+  # Prints the given text using green colored output
+  #
+  # @param text [ String ] the text to be printed with color formatting
+  def info_puts(text)
+    puts white { on_color(28) { text } }
+  end
+
+  # Returns a hash of environment variables for Docker container execution
+  #
+  # This method constructs a set of environment variables by combining those
+  # specified in the configuration file with any terminal-related variables
+  # from the current environment, ensuring proper variable expansion and
+  # assignment for use in Docker container runs.
+  #
+  # @return [ Hash ] a hash mapping environment variable names to their values
   def env
     vars = @config.fetch('env', [])
     vars << 'TERM' if ENV.key?('TERM')
@@ -57,6 +116,18 @@ class AllImages::App
     }
   end
 
+  # Executes a system command and handles its result
+  #
+  # This method runs a given system command with the provided arguments,
+  # optionally logging the execution when debug mode is enabled. It checks the
+  # command's exit status and raises an exception if the command fails,
+  # otherwise returning true to indicate success.
+  #
+  # @param a [ Array<String> ] the command and its arguments to be executed
+  #
+  # @return [ TrueClass ] when the command executes successfully
+  #
+  # @raise [ RuntimeError ] if the executed command exits with a non-zero status
   def sh(*a)
     if $DEBUG
       STDERR.puts "Executing #{a.inspect}."
@@ -69,23 +140,46 @@ class AllImages::App
     end
   end
 
+  # Generates a unique name for Docker container operations
+  #
+  # Creates a name by combining the fixed prefix "all_images" with a randomly
+  # generated suffix, separated by a hyphen, for use in Docker container
+  # identification and cleanup.
+  #
+  # @return [ String ] a unique identifier suitable for Docker container naming
   def name
     [ 'all_images', @suffix ] * ?-
   end
 
+  # Executes a Docker image with the specified script in a container
+  #
+  # This method builds a Docker image based on the provided configuration,
+  # runs the script inside the container, and handles both interactive and
+  # non-interactive execution modes. It ensures cleanup of the container
+  # afterward regardless of success or failure.
+  #
+  # @param image [ String ] the Docker image name to use for execution
+  # @param script [ String ] the script content to be executed within the container
+  # @param interactive [ TrueClass, FalseClass ] flag indicating whether to run
+  #   the container interactively or in non-interactive mode
+  #
+  # @return [ Integer ] exit code indicating success (0) or failure (1) of the script execution
   def run_image(image, script, interactive: false)
     dockerfile = @config.fetch('dockerfile').to_s
-    tag  = provide_image image, dockerfile, script
-    envs = env.full? { |e| +' ' << e.map { |n, v| '-e %s=%s' % [ n, v.inspect ] } * ' ' }
+    tag        = provide_image image, dockerfile, script
+    envs       = env.full? { |e| +' ' << e.map { |n, v| '-e %s=%s' % [ n, v.inspect ] } * ' ' }
     if interactive
       puts "You can run /script interactively now."
       sh "docker run --name #{name} -it#{envs} -v `pwd`:/work '#{tag}' sh"
       return 0
     else
+      info_puts "Running container #{name.inspect} for image tagged #{tag.inspect}."
       if sh "docker run --name #{name} -it#{envs} -v `pwd`:/work '#{tag}' sh -c /script"
+        info_puts "Image tagged #{tag.inspect} was run with result:"
         puts green('SUCCESS')
         return 0
       else
+        info_puts "Image tagged #{tag.inspect} was run with result:"
         puts red('FAILURE')
         return 1
       end
@@ -94,6 +188,41 @@ class AllImages::App
     sh "docker rm -f #{name} >/dev/null"
   end
 
+  # Presents a searchable interface for selecting a configured Docker image
+  #
+  # This method initializes and starts a search UI that allows users to
+  # interactively pick a Docker image from the list of configured images. It
+  # provides filtering capabilities based on user input and displays the
+  # options with visual highlighting for the selected item.
+  #
+  # @return [ String ] the name of the selected Docker image
+  def pick_configured_image
+    Search.new(
+      prompt: 'Pick a configured container image: ',
+      match: -> answer {
+        matches = images.map(&:first).grep(/#{Regexp.quote(answer)}/)
+        matches.empty? and matches = images
+        matches.first(Tins::Terminal.lines - 1)
+      },
+      query: -> _answer, matches, selector {
+        matches.each_with_index.map { |m, i|
+          i == selector ? "#{blue{?⮕}} #{on_blue{bold{m}}}" : "  #{m.to_s}"
+        } * ?\n
+      },
+      found: -> _answer, matches, selector {
+        matches[selector]
+      },
+      output: STDOUT
+    ).start
+  end
+
+  # Determines the command to execute based on the provided arguments
+  #
+  # Processes the command-line arguments to identify the intended operation,
+  # handling cases for running all images, listing images, running a specific
+  # image, debugging a specific image, or displaying help information.
+  #
+  # @return [ String ] the determined command to be executed
   def pick_command
     case command = @args.shift
     when 'run_all', nil
@@ -101,32 +230,51 @@ class AllImages::App
     when 'ls'
       'ls'
     when 'run'
-      @selected = @args.shift or fail "Usage: #{File.basename($0)} #{command} IMAGE"
+      @selected = @args.shift || pick_configured_image
+      @selected or fail "Usage: #{File.basename($0)} #{command} IMAGE"
       'run_selected'
     when 'debug'
-      @selected = @args.shift or fail "Usage: #{File.basename($0)} #{command} IMAGE"
+      @selected = @args.shift || pick_configured_image
+      @selected or fail "Usage: #{File.basename($0)} #{command} IMAGE"
       'debug_selected'
     else
       'help'
     end
   end
 
+  # Loads and processes the configuration file for the AllImages application
+  #
+  # This method determines the appropriate configuration file to load based on
+  # command-line arguments or defaults to .all_images.yml. If the file doesn't exist
+  # and no alternative is provided, it initializes a default configuration file
+  # and displays an example for customization before exiting.
+  #
+  # @return [ Object, nil ] the parsed configuration hash if successful, or nil if
+  #   initialization occurred and the method should terminate early
   def load_config
     config_filename = '.all_images.yml'
-    if @args.empty?
-      unless File.exist?(config_filename)
-        AllImages::Config.init(config_filename)
-        puts bold("Config file #{config_filename} not found!\n\n")  +
-          "The following example was created, adapt to your own needs:\n\n",
-          AllImages::Config.example, ""
-        return
-      end
-    else
-      config_filename = @args.shift
+    unless File.exist?(config_filename)
+      AllImages::Config.init(config_filename)
+      puts bold("Config file #{config_filename} not found!\n\n")  +
+        "The following example was created, adapt to your own needs:\n\n",
+        AllImages::Config.example, ""
+      return
     end
     AllImages::Config.load(config_filename)
   end
 
+  # Prepares a Docker image for execution by pulling, building, and tagging it
+  #
+  # This method ensures that the specified Docker image is available locally,
+  # creates a temporary build environment, generates a Dockerfile with the
+  # provided configuration and script, builds the image with a unique tag, and
+  # cleans up the temporary files afterward.
+  #
+  # @param image [ String ] the base Docker image name to pull and use for building
+  # @param dockerfile [ String ] additional Dockerfile instructions to include in the build
+  # @param script [ String ] the script content that will be copied into the built image
+  #
+  # @return [ String ] the unique tag assigned to the newly built Docker image
   def provide_image(image, dockerfile, script)
     prefix = @config.fetch('prefix', File.basename(Dir.pwd))
     tag    = "#{prefix}/all_images/#{image}"
@@ -148,6 +296,7 @@ class AllImages::App
         COPY --chmod=755 script /script
       end
       end
+      info_puts "Now building image #{tag.inspect}…"
       sh "docker build --pull -t '#{tag}' ."
     end
     tag

data/lib/all_images/config.rb

@@ -1,15 +1,25 @@
 require 'yaml'
 
+# Configuration handling for AllImages
+#
+# Provides functionality for loading, initializing, and accessing example
+# configuration files used by the AllImages application to define Docker image
+# build and execution parameters.
 module AllImages::Config
+  # Loads and parses a YAML configuration file
+  #
+  # @param filename [ String ] the path to the YAML file to load
+  #
+  # @return [ Object ] the parsed YAML content as a Ruby object
   def load(filename)
     YAML.unsafe_load_file(filename)
   end
 
-  EXAMPLE = <<~end
+  # Example configuration for `all_images`.
+  EXAMPLE = <<~EOT
     dockerfile: |-
-      RUN apk add --no-cache build-base git
-      RUN gem update --system
-      RUN gem install gem_hadar bundler
+      RUN apk add --no-cache build-base yaml-dev git
+      RUN gem install gem_hadar
 
     script: &script |-
       echo -e "\\e[1m"
@@ -19,18 +29,33 @@ module AllImages::Config
       rake test
 
     images:
+      ruby:3.4-alpine: *script
       ruby:3.3-alpine: *script
       ruby:3.2-alpine: *script
-      ruby:3.1-alpine: *script
-      ruby:3.0-alpine: *script
-  end
+  EOT
 
+  # Initializes a configuration file with example content
+  #
+  # Creates a new configuration file at the specified path and writes example
+  # configuration content to it. This method is typically used when no existing
+  # configuration file is found, providing a starting point for users to
+  # customize.
+  #
+  # @param filename [ String ] the path where the example configuration file
+  # will be created
   def init(filename)
-    File.open(filename, 'w') do |output|
+    File.open(filename, ?w) do |output|
       output.print EXAMPLE
     end
   end
 
+  # Returns the example configuration content
+  #
+  # This method provides access to the predefined example configuration
+  # that can be used to initialize a new configuration file.
+  #
+  # @return [ String ] the multi-line string containing the example configuration
+  #                     structure and default settings
   def example
     EXAMPLE
   end

data/lib/all_images/version.rb

@@ -1,6 +1,6 @@
 module AllImages
   # AllImages version
-  VERSION         = '0.6.0'
+  VERSION         = '0.7.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/lib/all_images.rb

@@ -1,3 +1,14 @@
+# AllImages is a Ruby library that provides functionality for managing and
+# executing scripts across multiple Docker images.
+#
+# It offers a command-line interface for running automated tasks in
+# containerized environments, supporting configuration-driven execution, image
+# building, and interactive debugging.
+#
+# The library includes modules for handling configuration files, managing
+# Docker image operations, and providing a user-friendly interface for
+# developers to test their code across different environments without manual
+# setup.
 module AllImages
 end
 

data/spec/spec_helper.rb

@@ -1,9 +1,5 @@
-if ENV['START_SIMPLECOV'].to_i == 1
-  require 'simplecov'
-  SimpleCov.start do
-    add_filter "#{File.basename(File.dirname(__FILE__))}/"
-  end
-end
+require 'gem_hadar/simplecov'
+GemHadar::SimpleCov.start
 require 'rspec'
 begin
   require 'debug'

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: all_images
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Florian Frank
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-14 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: gem_hadar
@@ -16,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.19'
+        version: '2.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.19'
+        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -86,28 +85,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.42'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.42'
+- !ruby/object:Gem::Dependency
+  name: search_ui
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
 - !ruby/object:Gem::Dependency
   name: term-ansicolor
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.11'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.11'
 description: A script that runs a script in all of the configured docker images
 email: flori@ping.de
 executables:
@@ -138,7 +151,6 @@ homepage: https://github.com/flori/all_images
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options:
 - "--title"
 - AllImages -- Runs a script in all of the docker images
@@ -157,8 +169,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.18
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Runs a script in all of the docker images
 test_files: