toys-core 0.23.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a09f479bfecbde001cec1076fdce57080117cbdeecfc2738879445a682b7363f
-  data.tar.gz: 277635722c80c2691759147cf7fc4b928755f0349a54fd970327c46bae443170
+  metadata.gz: c9a692b91f8fcd9e2aee00a360ac14b676ec1876bbf889468440e3827ce8877b
+  data.tar.gz: 6fc4cbd7769db055405a17be755dd0dc0e9612f9e5fd00451c3a1480c2924c6c
 SHA512:
-  metadata.gz: 6cfaa55d28079f651f9eab9d8a693af1386ddc6d08e58553ab457c4c669265902da5bba6e0f336faa8113bf0a92b2fbbe2bde4b49480118fe1d63b00a38ba791
-  data.tar.gz: f8b6b6efcc6c978d1a1ce7cece9040eb5475eb7baa58c6b1527ba2dc5bb780c8401f30917e62fcc43999224ecd755b136d03d05d79c03fdc26622efc306e02d3
+  metadata.gz: 9f3850a2d2d3eaf18f9ace3730a4bc34355400b8ff75308e0e739d77a5e664a7377c0fa9bacbd9726be3b99fc4bb5c5c6e742f5171d3ff4185dab90fe50f61f5
+  data.tar.gz: f0337ba0809e6e56f233fe22f2e4b423f19b36df4f1163498c8bd1ef6e545301bbbb0e51b12a92a2f218d001d5a9092e739ff088ea5caf6547e07568c4692a04

data/.yardopts

@@ -1,7 +1,6 @@
 --no-private
 --title=Toys Core
 --markup=markdown
---markup-provider redcarpet
 --main=README.md
 ./lib/toys/**/*.rb
 ./lib/toys-core.rb

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Release History
 
+### v0.25.0 / 2026-10-10
+
+This is a release candidate release toward version 1.0. It includes a variety of fixes and small features, largely around adherence to clig.dev and other common CLI guidelines.
+
+* ADDED: Added `Toys::Utils::Terminal.infer_styled`, the rule a terminal uses to decide whether to style output
+* ADDED: The `FORCE_COLOR` environment variable forces styled output on, or off when set to 0 or false
+* ADDED: The `show_help` middleware includes `-h` in the default help flags
+* ADDED: `StandardUI` logs with a simple severity prefix unless verbosity is positive
+* ADDED: Issue warnings for deprecated interfaces
+* ADDED: `Utils::Pager` supports an output option
+* FIXED: The `:push` handler creates a new array rather than appending in place, so that a frozen or non-cloneable default doesn't cause problems
+* FIXED: An empty `NO_COLOR` environment variable no longer disables styled output, per the no-color.org spec
+* FIXED: Styled output is disabled when the `TERM` environment variable is set to `dumb`
+* FIXED: The highline mixin decides whether to use color from its own output stream, and honors `NO_COLOR`, `FORCE_COLOR`, and `TERM=dumb`
+* FIXED: Help text displayed through a pager honors the styled output setting, including `NO_COLOR`, `FORCE_COLOR`, and `TERM=dumb`
+* FIXED: Tool-not-found suggestions include namespaces
+* FIXED: Tool initializers run within the logger level implied by the verbosity
+* FIXED: `StandardUI` no longer colors the `DEBUG` log header
+* FIXED: Re-vendor `simple_xdg` 0.1.2 to pick up home directory fix
+* FIXED: Re-vendor `git_cache` 0.2.0 to report an unwritable cache directory clearly and fix repo lock races
+* FIXED: Show_help writes paged help to the configured stream
+* DOCS: Documentation no longer references a few obsolete features such as the `TOYS_PATH` variable
+
+### v0.24.0 / 2026-09-11
+
+Feature updates:
+
+* `SourceSpec::Gem` now includes optional `on_missing:` and `default_confirm:` fields to control how missing gems are handled.
+* The `load_gem` directive now takes optional `on_missing:` and `default_confirm:` arguments to control how missing gems are handled.
+* Passing options when activating a gem using the `:gems` mixin no longer clobbers options passed when instantiating the mixin.
+
+Removed some old deprecated items. (All technically breaking changes)
+
+* Removed deprecated `Toys::CORE_VERSION`. Use `Toys::Core::VERSION` instead.
+* Removed deprecated `alias_tool` directive. Pass `delegate_relative:` to the `tool` directive instead.
+* Removed deprecated `suppress_confirm:` argument to the `Gems` utility. Use `on_missing:` instead.
+
 ### v0.23.0 / 2026-09-09
 
 This is a major release, with several new features, a number of fixes, and a significant refactor of the tool loading and execution layers, including several breaking interface changes. It is a release candidate for the upcoming version 1.0.

data/docs/guide.md

@@ -705,7 +705,8 @@ cli = Toys::CLI.new(logger_factory: my_logger_factory)
 #### StandardUI logging
 
 {Toys::Utils::StandardUI} implements the logger used by the `toys` gem, which
-formats log entries with the severity and timestamp using ANSI coloring.
+formats log entries with a severity prefix using ANSI coloring, and adds a
+timestamp when the tool is run with positive verbosity.
 
 You can use this logger by passing the proc returned by
 {Toys::Utils::StandardUI#logger_factory_proc} to the CLI constructor:
@@ -718,8 +719,10 @@ cli = Toys::CLI.new(logger_factory: standard_ui.logger_factory_proc)
 You can also customize the logger by subclassing StandardUI and overriding its
 methods or adjusting its parameters. In particular, you can alter the
 {Toys::Utils::StandardUI#log_header_severity_styles} mapping to adjust styling,
-or override {Toys::Utils::StandardUI#create_logger} or
-{Toys::Utils::StandardUI#format_log_entry} to adjust content and
+or override {Toys::Utils::StandardUI#create_logger},
+{Toys::Utils::StandardUI#verbose_log_format?},
+{Toys::Utils::StandardUI#format_simple_log_entry}, or
+{Toys::Utils::StandardUI#format_verbose_log_entry} to adjust content and
 formatting.
 
 ### Handling errors

data/lib/toys/arg_parser.rb

@@ -641,7 +641,8 @@ module Toys
           if @tool.runnable? || !@seen_flags.empty?
             ExtraArgumentsError.new(arguments: @unmatched_positional)
           else
-            dictionary = @loader.list_subtools(@tool.full_name).map(&:simple_name)
+            subtools = @loader.list_subtools(@tool.full_name, include_namespaces: true)
+            dictionary = subtools.map(&:simple_name)
             first_arg = @unmatched_positional.first
             ToolUnrecognizedError.new(full_name: @tool.full_name + [first_arg],
                                       suggestions: Compat.suggestions(first_arg, dictionary))

data/lib/toys/cli.rb

@@ -88,6 +88,8 @@ module Toys
     #     as an argument, and returns a `Logger` to use when running that tool.
     #     Optional. If not provided (and no global logger is set),
     #     {Toys::CLI.default_logger_factory} is called to get a basic default.
+    #     See {Toys::Runner} for how a logger can receive the verbosity of
+    #     the run.
     # @param base_level [Integer] The logger level that should correspond
     #     to zero verbosity.
     #     Optional. If not provided, defaults to the level the logger has
@@ -351,8 +353,8 @@ module Toys
     # source list. If the given search directory path does not exist or does
     # not contain either the file or directory, nothing is added.
     #
-    # The main Toys executable uses this method to load tools from directories
-    # in the `TOYS_PATH`.
+    # The main Toys executable uses this method to load tools from the
+    # directories in its upward walk and from the home directory.
     #
     # @param search_path [String,Pathname] A directory path to search for the
     #     well-known source file and directory. Must be a String or a Pathname.
@@ -405,9 +407,6 @@ module Toys
     # given directory and works up through parent directories until it reaches
     # the file system root or it encounters one of the "terminate" directories.
     #
-    # The main Toys executable uses this method to load tools from the current
-    # directory and its ancestors.
-    #
     # @param start [String,Pathname,nil] The first directory path to search.
     #     If not given, defaults to the current working directory. If provided,
     #     must be a String or a Pathname. Paths should generally be absolute.
@@ -581,6 +580,9 @@ module Toys
                         high_priority: false,
                         source_name: nil,
                         context_directory: :parent)
+      Warnings.warn(:add_config_path_deprecated,
+                    "CLI#add_config_path is deprecated. Use add_source instead.",
+                    uplevel: 1)
       path = SourceSpec.check_and_normalize_path(path)
       context_directory = resolve_context_directory(context_directory, path)
       spec = SourceSpec.path(path, source_name: source_name, context_directory: context_directory)
@@ -631,6 +633,9 @@ module Toys
                          source_name: nil,
                          context_directory: nil,
                          &block)
+      Warnings.warn(:add_config_block_deprecated,
+                    "CLI#add_config_block is deprecated. Use add_source instead.",
+                    uplevel: 1)
       spec = SourceSpec.block(source_name: source_name, context_directory: context_directory, &block)
       add_source(spec, high_priority: high_priority)
     end

data/lib/toys/compat.rb

@@ -22,127 +22,133 @@ module Toys
     #
     RUBY_VERSION_CODE = ruby_version
 
-    ##
-    # @private
-    # Whether the current Ruby implementation is JRuby
-    #
-    # @return [boolean]
-    #
-    def self.jruby?
-      ::RUBY_ENGINE == "jruby"
-    end
+    class << self
+      ##
+      # @private
+      # Whether the current Ruby implementation is JRuby
+      #
+      # @return [boolean]
+      #
+      def jruby?
+        ::RUBY_ENGINE == "jruby"
+      end
 
-    ##
-    # @private
-    # Whether the current Ruby implementation is TruffleRuby
-    #
-    # @return [boolean]
-    #
-    def self.truffleruby?
-      ::RUBY_ENGINE == "truffleruby"
-    end
+      ##
+      # @private
+      # Whether the current Ruby implementation is TruffleRuby
+      #
+      # @return [boolean]
+      #
+      def truffleruby?
+        ::RUBY_ENGINE == "truffleruby"
+      end
 
-    ##
-    # @private
-    # Whether we are running on Windows
-    #
-    # @return [boolean]
-    #
-    def self.windows?
-      ::RbConfig::CONFIG["host_os"] =~ /mswin|msys|mingw|cygwin|bccwin|wince|emc/
-    end
+      ##
+      # @private
+      # Whether we are running on Windows
+      #
+      # @return [boolean]
+      #
+      def windows?
+        ::RbConfig::CONFIG["host_os"] =~ /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+      end
 
-    ##
-    # @private
-    # Whether we are running on Mac OS
-    #
-    # @return [boolean]
-    #
-    def self.macos?
-      ::RbConfig::CONFIG["host_os"] =~ /darwin/
-    end
+      ##
+      # @private
+      # Whether we are running on Mac OS
+      #
+      # @return [boolean]
+      #
+      def macos?
+        ::RbConfig::CONFIG["host_os"] =~ /darwin/
+      end
 
-    ##
-    # @private
-    # Whether fork is supported on the current Ruby and OS
-    #
-    # @return [boolean]
-    #
-    def self.allow_fork?
-      !jruby? && !truffleruby? && !windows?
-    end
+      ##
+      # @private
+      # Whether fork is supported on the current Ruby and OS
+      #
+      # @return [boolean]
+      #
+      def allow_fork?
+        !jruby? && !truffleruby? && !windows?
+      end
 
-    ##
-    # @private
-    # Whether it is possible to get suggestions from DidYouMean. If this
-    # returns false, {Compat.suggestions} will always return the empty array.
-    #
-    # @return [boolean]
-    #
-    def self.supports_suggestions?
-      unless defined?(@supports_suggestions)
-        begin
-          require "did_you_mean"
-        rescue ::LoadError
-          require "rubygems"
+      ##
+      # @private
+      # Whether it is possible to get suggestions from DidYouMean. If this
+      # returns false, {Compat.suggestions} will always return the empty array.
+      #
+      # @return [boolean]
+      #
+      def supports_suggestions?
+        unless defined?(@supports_suggestions)
           begin
             require "did_you_mean"
           rescue ::LoadError
-            # Oh well, it's not available
+            require "rubygems"
+            begin
+              require "did_you_mean"
+            rescue ::LoadError
+              # Oh well, it's not available
+            end
           end
+          @supports_suggestions = defined?(::DidYouMean::SpellChecker)
         end
-        @supports_suggestions = defined?(::DidYouMean::SpellChecker)
+        @supports_suggestions
       end
-      @supports_suggestions
-    end
 
-    ##
-    # @private
-    # A list of suggestions from DidYouMean.
-    #
-    # @param word [String] A value that seems wrong
-    # @param list [Array<String>] A list of valid values
-    #
-    # @return [Array<String>] A possibly empty array of suggestions from the
-    #     valid list that could match the given word.
-    #
-    def self.suggestions(word, list)
-      if supports_suggestions?
-        ::DidYouMean::SpellChecker.new(dictionary: list).correct(word)
-      else
-        []
+      ##
+      # @private
+      # A list of suggestions from DidYouMean.
+      #
+      # @param word [String] A value that seems wrong
+      # @param list [Array<String>] A list of valid values
+      #
+      # @return [Array<String>] A possibly empty array of suggestions from the
+      #     valid list that could match the given word.
+      #
+      def suggestions(word, list)
+        if supports_suggestions?
+          ::DidYouMean::SpellChecker.new(dictionary: list).correct(word)
+        else
+          []
+        end
       end
-    end
 
-    ##
-    # @private
-    # A list of gems that should generally not be included in a bundle, usually
-    # because the Ruby implementation handles the library specially and cannot
-    # install the real gem. Currently, this includes the `pathname` gem for
-    # TruffleRuby, since TruffleRuby includes a special version of it.
-    #
-    # @return [Array<String>]
-    #
-    def self.gems_to_omit_from_bundles
-      if truffleruby?
-        ["pathname"]
-      else
-        []
+      ##
+      # @private
+      # A list of gems that should generally not be included in a bundle,
+      # usually because the Ruby implementation handles the library specially
+      # and cannot install the real gem. Currently, this includes the
+      # `pathname` gem for TruffleRuby, since TruffleRuby includes a special
+      # version of it.
+      #
+      # @return [Array<String>]
+      #
+      def gems_to_omit_from_bundles
+        if truffleruby?
+          ["pathname"]
+        else
+          []
+        end
       end
-    end
 
-    ##
-    # @private
-    # Sets the backtrace on an exception. In Ruby < 3.4, Exception#set_backtrace
-    # required a string array, whereas in newer Rubies, it would accept an array
-    # of backtrace locations.
-    #
-    # @param [Exception] exception
-    # @param [nil,Array<String>,Array<Thread::Backtrace::Location>] backtrace
-    #
-    def self.set_backtrace(exception, backtrace)
-      backtrace = backtrace.map(&:to_s) if RUBY_VERSION_CODE < 30400 && !backtrace.nil?
-      exception.set_backtrace(backtrace)
+      ##
+      # @private
+      # Sets the backtrace on an exception. In Ruby `< 3.4`,
+      # `Exception#set_backtrace` required a string array, whereas in newer
+      # Rubies, it would accept an array of backtrace locations.
+      #
+      # @param [Exception] exception
+      # @param [nil,Array<String>,Array<Thread::Backtrace::Location>] backtrace
+      #
+      # @return [Exception] The modified exception
+      #
+      def set_backtrace(exception, backtrace)
+        backtrace = backtrace.map(&:to_s) if RUBY_VERSION_CODE < 30400 && !backtrace.nil?
+        exception.set_backtrace(backtrace)
+        exception
+      end
     end
   end
 end

data/lib/toys/core.rb

@@ -9,13 +9,6 @@ module Toys
     # Current version of Toys core.
     # @return [String]
     #
-    VERSION = "0.23.0"
+    VERSION = "0.25.0"
   end
-
-  ##
-  # Deprecated
-  #
-  # @private
-  #
-  CORE_VERSION = Core::VERSION
 end

data/lib/toys/dsl/tool.rb

@@ -329,39 +329,6 @@ module Toys
         self
       end
 
-      ##
-      # Create an alias, representing an "alternate name" for a tool.
-      #
-      # Note: This is functionally equivalent to creating a tool with the
-      # `:delegate_relative` option. As such, `alias_tool` is considered
-      # deprecated.
-      #
-      # ### Example
-      #
-      # This example defines a tool and an alias pointing to it. Both the tool
-      # name `test` and the alias `t` will then refer to the same tool.
-      #
-      #     tool "test" do
-      #       def run
-      #         puts "Running tests..."
-      #       end
-      #     end
-      #     alias_tool "t", "test"
-      #     # Note: the following is preferred over alias_tool:
-      #     # tool "t", delegate_relative: "test"
-      #
-      # @param word [String] The name of the alias
-      # @param target [String,Array<String>] Relative path to the target of the
-      #     alias. This path may be given as an array of strings, or a single
-      #     string possibly delimited by path separators.
-      # @return [self]
-      # @deprecated Use {#tool} and pass `:delegate_relative` instead
-      #
-      def alias_tool(word, target)
-        tool(word, delegate_relative: target)
-        self
-      end
-
       ##
       # Causes the current tool to delegate to another tool, specified by the
       # full tool name. When run, it simply invokes the target tool with the
@@ -508,6 +475,18 @@ module Toys
       #     Context directory paths should generally be absolute. Relative
       #     paths will be converted to absolute, using the current working
       #     directory at the time of loading.
+      # @param on_missing [:confirm,:error,:install] What to do if the
+      #     requested gem is not installed. Possible values:
+      #
+      #      *  `:confirm` - prompt the user on whether to install
+      #      *  `:error` - raise an exception
+      #      *  `:install` - just install the gem
+      #
+      #     Defaults to the setting in the {Toys::Utils::Gems} utility used to
+      #     activate the gem (usually `:confirm`).
+      # @param default_confirm [boolean] The default confirmation result, if
+      #     `on_missing` is set to `:confirm`. Defaults to the setting in the
+      #     {Toys::Utils::Gems} utility used to activate the gem (usually true).
       # @param as [String] Load into the given tool/namespace, relative to the
       #     current namespace. If omitted, tools will be loaded into the
       #     current namespace.
@@ -519,6 +498,8 @@ module Toys
                    path: nil,
                    toys_dir: nil,
                    context_directory: nil,
+                   on_missing: nil,
+                   default_confirm: nil,
                    as: nil)
         version = versions + Array(version)
         if as
@@ -527,7 +508,9 @@ module Toys
                      version: version,
                      path: path,
                      toys_dir: toys_dir,
-                     context_directory: context_directory)
+                     context_directory: context_directory,
+                     on_missing: on_missing,
+                     default_confirm: default_confirm)
           end
           return self
         end
@@ -535,7 +518,9 @@ module Toys
                               version: version,
                               path: path,
                               toys_dir: toys_dir,
-                              context_directory: context_directory)
+                              context_directory: context_directory,
+                              on_missing: on_missing,
+                              default_confirm: default_confirm)
         DSL::Internal.current_load_state(self).load_source(spec)
         self
       end

data/lib/toys/flag.rb

@@ -377,10 +377,12 @@ module Toys
     SET_HANDLER = proc { |val| val }
 
     ##
-    # The push handler pushes the given value using the `<<` operator.
+    # The push handler appends the given value, returning a new array. The
+    # previous array is not modified, so a shared or frozen default array
+    # can be used safely.
     # @return [Proc]
     #
-    PUSH_HANDLER = proc { |val, prev| prev.nil? ? [val] : prev << val }
+    PUSH_HANDLER = proc { |val, prev| prev.nil? ? [val] : prev + [val] }
 
     ##
     # The default handler is the set handler, which replaces the previous value.

data/lib/toys/runner.rb

@@ -38,6 +38,15 @@ module Toys
   #       end
   #     end
   #
+  # While a tool runs, the Runner sets the level of the tool's logger to reflect
+  # the verbosity, as described under the `base_level` parameter of
+  # {#initialize}. A logger can also receive the verbosity itself, by
+  # implementing a `verbosity` attribute: if the logger responds to both
+  # `verbosity` and `verbosity=`, the Runner sets it to the verbosity (an
+  # Integer) for the duration of the run, and restores the previous value
+  # afterward. This lets a logger vary its behavior, such as its formatting, by
+  # verbosity independently of its level.
+  #
   class Runner
     ##
     # The singleton default logger_factory Proc, which simply returns a new
@@ -74,7 +83,8 @@ module Toys
     # @param logger_factory [Proc,nil] A proc that takes a
     #     {Toys::ToolDefinition} as an argument, and returns a logger to use
     #     when running that tool. If not given,
-    #     {Toys::Runner::DEFAULT_LOGGER_FACTORY} is used.
+    #     {Toys::Runner::DEFAULT_LOGGER_FACTORY} is used. See {Toys::Runner}
+    #     for how a logger can receive the verbosity of the run.
     # @param base_level [Integer,nil] The logger level that corresponds to zero
     #     verbosity. If not provided, the level the logger has before a run
     #     adjusts it is used (typically Logger::WARN). A run nested inside
@@ -404,15 +414,15 @@ module Toys
       end
 
       # Prepares the runtime environment for the tool, applying lib paths and
-      # initializers, and then calls the tool within its middleware stack and
-      # within the logger level implied by the verbosity, returning the
-      # resulting exit code.
+      # initializers, and then calls the tool within its middleware stack,
+      # returning the resulting exit code. The initializers and the tool both
+      # run within the logger level implied by the verbosity.
       def execute_tool(context, &block)
         @tool.source_info&.find_lib_paths&.reverse_each do |path|
           $LOAD_PATH.unshift(path) unless $LOAD_PATH.include?(path)
         end
-        @tool.run_initializers(context)
         with_logger_level(context) do
+          @tool.run_initializers(context)
           executor = build_executor(context, &block)
           catch(:result) do
             executor.call
@@ -426,23 +436,39 @@ module Toys
       # afterward. The restoration must cover the level assignment itself,
       # because a base level that cannot be combined with the verbosity fails
       # there, and a base level left recorded behind a failed run would be
-      # picked up by later runs sharing the logger. Yields directly if the tool
-      # has no logger.
-      def with_logger_level(context)
+      # picked up by later runs sharing the logger. Also sets the verbosity on
+      # a logger that supports it, as described in {Runner}. Yields directly if
+      # the tool has no logger.
+      def with_logger_level(context, &block)
         cur_logger = context[Context::Key::LOGGER]
         return yield unless cur_logger
+        verbosity = context[Context::Key::VERBOSITY].to_i
         original_level = cur_logger.level
         base_level = @base_level || base_levels[cur_logger] || original_level
         saved_base_level = set_base_level(cur_logger, base_level)
         begin
-          cur_logger.level = base_level - context[Context::Key::VERBOSITY].to_i
-          yield
+          cur_logger.level = base_level - verbosity
+          with_logger_verbosity(cur_logger, verbosity, &block)
         ensure
           set_base_level(cur_logger, saved_base_level)
           cur_logger.level = original_level
         end
       end
 
+      # Sets the verbosity on a logger that supports it for the duration of
+      # the block, and restores it afterward. Yields directly if the logger
+      # does not have both a reader and a writer for the verbosity.
+      def with_logger_verbosity(logger, verbosity)
+        return yield unless logger.respond_to?(:verbosity) && logger.respond_to?(:verbosity=)
+        original_verbosity = logger.verbosity
+        begin
+          logger.verbosity = verbosity
+          yield
+        ensure
+          logger.verbosity = original_verbosity
+        end
+      end
+
       # The base levels currently in effect on this thread, keyed by logger
       # identity. A run that adjusts a logger's level records the base
       # level it used, for the extent of that run, because a nested run cannot

data/lib/toys/source_info.rb

@@ -345,6 +345,8 @@ module Toys
       end
 
       def resolve_gem_spec(spec, parent, priority, gems_util)
+        gems_util ||= default_gems_util
+        gems_util = gems_util.with(on_missing: spec.on_missing, default_confirm: spec.default_confirm)
         gem_version, gem_path, source_path =
           resolve_gem_info(gems_util, spec.name, spec.version, spec.path, spec.toys_dir)
         source_path, type = check_path(source_path, false)
@@ -486,7 +488,7 @@ module Toys
       def resolve_gem_info(gems_util, gem_name, gem_versions, gem_path, gem_toys_dir)
         require "toys/utils/gems"
         begin
-          (gems_util || default_gems_util).activate(gem_name, *gem_versions)
+          gems_util.activate(gem_name, *gem_versions)
         rescue ::Toys::Utils::Gems::ActivationFailedError => e
           raise ToolSourceError, e.message
         end