cli-kit 5.1.0 → 5.3.0

data/lib/cli/kit/config.rb

@@ -2,15 +2,132 @@
 
 require 'cli/kit'
 require 'fileutils'
+require 'tempfile'
 
 module CLI
   module Kit
     class Config
-      extend T::Sig
-
       XDG_CONFIG_HOME = 'XDG_CONFIG_HOME'
 
-      sig { params(tool_name: String).void }
+      # Raised when the config file cannot be written (e.g. read-only
+      # directory, read-only filesystem, nix/home-manager-managed symlink
+      # pointing into +/nix/store+).
+      #
+      # Inherits from SystemCallError so existing `rescue SystemCallError`
+      # handlers around +Config#set+ continue to match. The message contains
+      # only the keys that actually changed; unchanged keys (which may
+      # include sensitive values such as API tokens) are intentionally
+      # excluded so the failure message can never leak secrets through
+      # stderr or exception reports.
+      class ConfigWriteError < SystemCallError
+        class << self
+          # Ruby's +SystemCallError.===+ uses errno-based matching,
+          # which means +rescue ConfigWriteError+ would otherwise fail
+          # to catch a ConfigWriteError instance (it would match
+          # +Errno::EACCES+ or +Errno::EPERM+ instead, based on the
+          # wrapped errno). Override with plain class-hierarchy
+          # matching so +rescue ConfigWriteError+ works as callers
+          # expect. +rescue SystemCallError+ still matches via normal
+          # inheritance.
+          #: (untyped other) -> bool
+          def ===(other)
+            other.is_a?(self)
+          end
+
+          # +SystemCallError.new+ has a factory-style signature defined
+          # in Sorbet's stdlib RBI (+(String | Integer?) ->
+          # SystemCallError+) which doesn't match this subclass's
+          # four-argument constructor. Override +.new+ here so type
+          # checkers and callers see the real signature, and allocate
+          # the instance manually to bypass +SystemCallError+'s
+          # factory behaviour.
+          #: (String config_path, String old_content, String new_content, SystemCallError cause) -> ConfigWriteError
+          def new(config_path, old_content, new_content, cause)
+            instance = allocate
+            instance.__send__(:initialize, config_path, old_content, new_content, cause)
+            instance
+          end
+        end
+
+        #: String
+        attr_reader :config_path
+
+        #: String
+        attr_reader :old_content
+
+        #: String
+        attr_reader :new_content
+
+        # rubocop:disable Lint/MissingSuper
+        # +SystemCallError#initialize+ has a factory-style signature that
+        # cannot be invoked from a plain subclass (it expects a matching
+        # Errno constant on the class). We bypass it deliberately and
+        # initialize via Exception so we just get a message-only
+        # exception that +rescue SystemCallError+ still catches via
+        # inheritance. +super+ would not work here.
+        #: (String config_path, String old_content, String new_content, SystemCallError cause) -> void
+        def initialize(config_path, old_content, new_content, cause)
+          @config_path = config_path
+          @old_content = old_content
+          @new_content = new_content
+          @wrapped_errno = cause.errno
+          message = <<~MSG.rstrip
+            Could not write to #{config_path}: #{cause.message}
+
+            Attempted changes (unchanged keys omitted):
+            #{diff}
+          MSG
+          Exception.instance_method(:initialize).bind(self).call(message)
+        end
+        # rubocop:enable Lint/MissingSuper
+
+        # Preserve the original errno from the wrapped Errno so callers
+        # that inspect +errno+ continue to see the real underlying code.
+        #: -> Integer?
+        def errno
+          @wrapped_errno
+        end
+
+        # A line-by-line diff of only the sections/keys that changed
+        # between +old_content+ and +new_content+. Unchanged keys are
+        # omitted so that sensitive values stored elsewhere in the config
+        # are never included in the failure message.
+        #: -> String
+        def diff
+          old_ini = CLI::Kit::Ini.new(config: @old_content).tap(&:parse).ini
+          new_ini = CLI::Kit::Ini.new(config: @new_content).tap(&:parse).ini
+
+          lines = []
+          (old_ini.keys | new_ini.keys).each do |section|
+            old_section = old_ini[section] || {}
+            new_section = new_ini[section] || {}
+
+            changes = []
+            (old_section.keys | new_section.keys).each do |key|
+              old_val = old_section[key]
+              new_val = new_section[key]
+              next if old_val == new_val
+
+              changes << "- #{key} = #{old_val}" if old_val
+              changes << "+ #{key} = #{new_val}" if new_val
+            end
+            next if changes.empty?
+
+            prefix = if old_section.empty?
+              '+ '
+            elsif new_section.empty?
+              '- '
+            else
+              '  '
+            end
+            lines << "#{prefix}#{section}"
+            lines.concat(changes)
+          end
+          lines.join("\n")
+        end
+      end
+
+      #: (tool_name: String) -> void
       def initialize(tool_name:)
         @tool_name = tool_name
       end
@@ -28,13 +145,13 @@ module CLI
       # #### Example Usage
       # `config.get('name.of.config')`
       #
-      sig { params(section: String, name: String, default: T.nilable(String)).returns(T.nilable(String)) }
+      #: (String section, String name, ?default: String?) -> String?
       def get(section, name, default: nil)
         all_configs.dig("[#{section}]", name) || default
       end
 
       # Coalesce and enforce the value of a config to a boolean
-      sig { params(section: String, name: String, default: T.nilable(T::Boolean)).returns(T.nilable(T::Boolean)) }
+      #: (String section, String name, ?default: bool?) -> bool?
       def get_bool(section, name, default: false)
         case get(section, name)
         when 'true'
@@ -58,14 +175,15 @@ module CLI
       # #### Example Usage
       # `config.set('section', 'name.of.config', 'value')`
       #
-      sig { params(section: String, name: String, value: T.nilable(T.any(String, T::Boolean))).void }
+      #: (String section, String name, (String | bool)? value) -> void
       def set(section, name, value)
         all_configs["[#{section}]"] ||= {}
+        section = all_configs["[#{section}]"] #: as !nil
         case value
         when nil
-          T.must(all_configs["[#{section}]"]).delete(name)
+          section.delete(name)
         else
-          T.must(all_configs["[#{section}]"])[name] = value.to_s
+          section[name] = value.to_s
         end
         write_config
       end
@@ -79,7 +197,7 @@ module CLI
       # #### Example Usage
       # `config.unset('section', 'name.of.config')`
       #
-      sig { params(section: String, name: String).void }
+      #: (String section, String name) -> void
       def unset(section, name)
         set(section, name, nil)
       end
@@ -92,12 +210,12 @@ module CLI
       # #### Example Usage
       # `config.get_section('section')`
       #
-      sig { params(section: String).returns(T::Hash[String, String]) }
+      #: (String section) -> Hash[String, String]
       def get_section(section)
         (all_configs["[#{section}]"] || {}).dup
       end
 
-      sig { returns(String) }
+      #: -> String
       def to_s
         ini.to_s
       end
@@ -107,7 +225,7 @@ module CLI
       # if ENV['XDG_CONFIG_HOME'] is not set, we default to ~/.config, e.g.:
       #   ~/.config/tool/config
       #
-      sig { returns(String) }
+      #: -> String
       def file
         config_home = ENV.fetch(XDG_CONFIG_HOME, '~/.config')
         File.expand_path(File.join(@tool_name, 'config'), config_home)
@@ -115,23 +233,98 @@ module CLI
 
       private
 
-      sig { returns(T::Hash[String, T::Hash[String, String]]) }
+      #: -> Hash[String, Hash[String, String]]
       def all_configs
         ini.ini
       end
 
-      sig { returns(CLI::Kit::Ini) }
+      #: -> CLI::Kit::Ini
       def ini
         @ini ||= CLI::Kit::Ini.new(file).tap(&:parse)
       end
 
-      sig { void }
+      #: -> void
       def write_config
         all_configs.each do |section, sub_config|
           all_configs.delete(section) if sub_config.empty?
         end
-        FileUtils.mkdir_p(File.dirname(file))
-        File.write(file, to_s)
+
+        # Capture +file+ and +to_s+ up front so they are visible (and
+        # known to be non-nil) inside the rescue block below.
+        config_path = file
+        new_content = to_s
+
+        begin
+          # Always write atomically (tmpfile + rename) so readers never
+          # observe a partial write. If +config_path+ is a symlink (e.g.
+          # a nix/home-manager-managed config), resolve it so the rename
+          # replaces the real file at the end of the chain and leaves
+          # the managed symlink itself intact.
+          target_path = resolved_write_path(config_path)
+          target_dir = File.dirname(target_path)
+          FileUtils.mkdir_p(target_dir)
+          write_config_atomic(target_path, target_dir, new_content)
+        rescue Errno::EACCES, Errno::EPERM, Errno::EROFS => e
+          # +EROFS+ (read-only filesystem) is the canonical error raised
+          # when the underlying filesystem is mounted read-only — common
+          # for nix/home-manager configs that live in +/nix/store+. Wrap
+          # it the same way as +EACCES+/+EPERM+ so callers always see
+          # the diff and any +rescue ConfigWriteError+ handler matches.
+          old_content = read_config_for_diff(config_path)
+          raise(ConfigWriteError.new(config_path, old_content, new_content, e))
+        end
+      end
+
+      # Write +new_content+ into +config_path+ atomically, via a tmpfile
+      # in the same directory followed by rename. Readers never observe
+      # a partial write.
+      #: (String config_path, String config_dir, String new_content) -> void
+      def write_config_atomic(config_path, config_dir, new_content)
+        tmpfile = Tempfile.new([File.basename(config_path), '.tmp'], config_dir)
+        tmpfile_path = tmpfile.path #: as !nil
+        begin
+          tmpfile.write(new_content)
+          tmpfile.close
+          # Tempfile defaults to 0o600. Match the permissions a plain
+          # +File.write+ would have produced: preserve the existing
+          # mode when the config is being updated, and use the
+          # umask-adjusted default (matching +open(2)+ for new files)
+          # otherwise. This avoids silently tightening permissions on
+          # an existing config and avoids creating new configs with
+          # the more restrictive Tempfile default.
+          mode = if File.exist?(config_path)
+            File.stat(config_path).mode
+          else
+            0o666 & ~File.umask
+          end
+          File.chmod(mode, tmpfile_path)
+          File.rename(tmpfile_path, config_path)
+        rescue Exception # rubocop:disable Lint/RescueException
+          tmpfile.close unless tmpfile.closed?
+          File.unlink(tmpfile_path) if File.exist?(tmpfile_path)
+          raise
+        end
+      end
+
+      #: (String config_path) -> String
+      def read_config_for_diff(config_path)
+        File.read(config_path)
+      rescue SystemCallError
+        ''
+      end
+
+      # Resolve +config_path+ through any symlinks so the atomic rename
+      # in +write_config_atomic+ replaces the real file at the end of
+      # the chain instead of clobbering the symlink with a regular file.
+      # For broken symlinks, fall back to +config_path+ itself so we
+      # still create a config there.
+      #: (String config_path) -> String
+      def resolved_write_path(config_path)
+        return config_path unless File.symlink?(config_path)
+
+        File.realpath(config_path)
+      rescue Errno::ENOENT
+        config_path
       end
     end
   end

data/lib/cli/kit/core_ext.rb

@@ -2,29 +2,139 @@
 # frozen_string_literal: true
 
 class Exception
-  extend(T::Sig)
-
   # You'd think instance variables @bug and @silent would work here. They
   # don't. I'm not sure why. If you, the reader, want to take some time to
   # figure it out, go ahead and refactor to that.
 
-  sig { returns(T::Boolean) }
-  def bug?
-    true
+  # Fault represents who is responsible for an error. It is used to attribute
+  # exceptions to the right owner for observability and triage.
+  #
+  # @abstract
+  # @sealed
+  class Fault
+    # @abstract
+    #: -> String
+    def to_s = raise NotImplementedError, 'abstract method called'
+
+    # A bug in the tool itself (dev, tec, cli-kit, etc.).
+    class System < Fault
+      # @override
+      #: -> String
+      def to_s = 'system'
+    end
+    SYSTEM = System.new.freeze #: System
+
+    # The default fault for exceptions that have not been explicitly attributed.
+    # Nothing should reference this constant directly — it exists only as the
+    # default return value of Exception#fault. Use rubocop to enforce this.
+    #
+    # Inherits from System so that `fault.is_a?(System)` and checks like
+    # `bug?` (which uses `Fault::System ===`) treat unattributed errors as
+    # system errors by default.
+    class ImplicitlySystem < System
+      # @override
+      #: -> String
+      def to_s = 'implicitly_system'
+    end
+    IMPLICITLY_SYSTEM = ImplicitlySystem.new.freeze #: ImplicitlySystem
+
+    # A problem with the project's configuration (dev.yml, zone.nix, etc.).
+    class Project < Fault
+      # @override
+      #: -> String
+      def to_s = 'project'
+    end
+    PROJECT = Project.new.freeze #: Project
+
+    # User error: incorrect CLI usage, expired tokens, bad arguments, etc.
+    class User < Fault
+      # @override
+      #: -> String
+      def to_s = 'user'
+    end
+    USER = User.new.freeze #: User
+
+    # Not a real failure — e.g. user cancellation, interrupt, or conditions
+    # wildly out of anyone's control (no disk space). Doesn't require fixing
+    # or tracking.
+    class Terroir < Fault
+      # @override
+      #: -> String
+      def to_s = 'terroir'
+    end
+    TERROIR = Terroir.new.freeze #: Terroir
   end
 
-  sig { returns(T::Boolean) }
+  #: -> Fault
+  def fault = Fault::IMPLICITLY_SYSTEM
+
+  #: (Fault fault) -> void
+  def fault!(fault)
+    singleton_class.define_method(:fault) { fault }
+  end
+
+  #: (Fault fault) -> self
+  def with_fault(fault)
+    fault!(fault)
+    self
+  end
+
+  #: -> bool
+  def bug? = (Fault::System === fault)
+
+  #: -> bool
   def silent?
     false
   end
 
-  sig { params(bug: T::Boolean).void }
+  #: (?bool bug) -> void
   def bug!(bug = true)
     singleton_class.define_method(:bug?) { bug }
   end
 
-  sig { params(silent: T::Boolean).void }
+  #: (?bool silent) -> void
   def silent!(silent = true)
     singleton_class.define_method(:silent?) { silent }
   end
 end
+
+# -- Custom fault defaults for Ruby stdlib exceptions --------------------------
+#
+# Normally, fault attribution belongs at the raise site (via `fault:` kwarg).
+# These classes are different: Ruby itself raises them (e.g. the kernel sends
+# SIGINT, the OS returns ENOSPC), so there is no raise site we control. We
+# override the default fault at the class level instead.
+#
+# All of these are environmental conditions ("terroir") — nobody's fault,
+# nothing to fix, shouldn't be reported as bugs.
+
+class Interrupt # Ctrl-C / SIGINT
+  #: -> Exception::Fault
+  def fault = Exception::Fault::TERROIR
+end
+
+class SignalException # SIGTERM, SIGHUP, etc.
+  #: -> Exception::Fault
+  def fault = Exception::Fault::TERROIR
+end
+
+module Errno
+  class ENOSPC # disk full
+    #: -> Exception::Fault
+    def fault = Exception::Fault::TERROIR
+  end
+end
+
+module Errno
+  class EPIPE # broken pipe
+    #: -> Exception::Fault
+    def fault = Exception::Fault::TERROIR
+  end
+end
+
+module Errno
+  class EIO # I/O error (e.g. terminal disconnected)
+    #: -> Exception::Fault
+    def fault = Exception::Fault::TERROIR
+  end
+end

data/lib/cli/kit/error_handler.rb

@@ -6,23 +6,12 @@ require 'English'
 module CLI
   module Kit
     class ErrorHandler
-      extend T::Sig
+      #: type exception_reporter_or_proc = singleton(ExceptionReporter) | ^() -> singleton(ExceptionReporter)
 
-      ExceptionReporterOrProc = T.type_alias do
-        T.any(T.class_of(ExceptionReporter), T.proc.returns(T.class_of(ExceptionReporter)))
-      end
-
-      sig { params(override_exception_handler: T.proc.params(arg0: Exception).returns(Integer)).void }
+      #: ^(Exception arg0) -> Integer
       attr_writer :override_exception_handler
 
-      sig do
-        params(
-          log_file: T.nilable(String),
-          exception_reporter: ExceptionReporterOrProc,
-          tool_name: T.nilable(String),
-          dev_mode: T::Boolean,
-        ).void
-      end
+      #: (?log_file: String?, ?exception_reporter: exception_reporter_or_proc, ?tool_name: String?, ?dev_mode: bool) -> void
       def initialize(log_file: nil, exception_reporter: NullExceptionReporter, tool_name: nil, dev_mode: false)
         @log_file = log_file
         @exception_reporter_or_proc = exception_reporter
@@ -30,33 +19,28 @@ module CLI
         @dev_mode = dev_mode
       end
 
+      # @abstract
       class ExceptionReporter
-        extend T::Sig
-        extend T::Helpers
-        abstract!
-
         class << self
-          extend T::Sig
-
-          sig { abstract.params(exception: T.nilable(Exception), logs: T.nilable(String)).void }
-          def report(exception, logs = nil); end
+          # @abstract
+          #: (Exception?, ?String?) -> void
+          def report(exception, logs = nil)
+            raise(NotImplementedError)
+          end
         end
       end
 
       class NullExceptionReporter < ExceptionReporter
-        extend T::Sig
-
         class << self
-          extend T::Sig
-
-          sig { override.params(_exception: T.nilable(Exception), _logs: T.nilable(String)).void }
+          # @override
+          #: (Exception? _exception, ?String? _logs) -> void
           def report(_exception, _logs = nil)
             nil
           end
         end
       end
 
-      sig { params(block: T.proc.void).returns(Integer) }
+      #: { -> void } -> Integer
       def call(&block)
         # @at_exit_exception is set if handle_abort decides to submit an error.
         # $ERROR_INFO is set if we terminate because of a signal.
@@ -64,7 +48,7 @@ module CLI
         triage_all_exceptions(&block)
       end
 
-      sig { params(error: T.nilable(Exception)).void }
+      #: (Exception? error) -> void
       def report_exception(error)
         if (notify_with = exception_for_submission(error))
           logs = nil
@@ -92,7 +76,7 @@ module CLI
       # they're #bug?
       #
       # Returns an exit status for the program.
-      sig { params(block: T.proc.void).returns(Integer) }
+      #: { -> void } -> Integer
       def triage_all_exceptions(&block)
         begin
           block.call
@@ -100,7 +84,7 @@ module CLI
         rescue Interrupt => e # Ctrl-C
           # transform message, prevent bugsnag
           exc = e.exception('Interrupt')
-          CLI::Kit.raise(exc, bug: false)
+          CLI::Kit.raise(exc, fault: Exception::Fault::TERROIR)
         rescue Errno::ENOSPC => e
           # transform message, prevent bugsnag
           message = if @tool_name
@@ -109,7 +93,7 @@ module CLI
             'Your disk is full - free space is required to operate'
           end
           exc = e.exception(message)
-          CLI::Kit.raise(exc, bug: false)
+          CLI::Kit.raise(exc, fault: Exception::Fault::TERROIR)
         end
       # If SystemExit was raised, e.g. `exit()`, then
       # return whatever status is attached to the exception
@@ -130,12 +114,38 @@ module CLI
         e.bug? ? CLI::Kit::EXIT_BUG : CLI::Kit::EXIT_FAILURE_BUT_NOT_BUG
       end
 
-      sig { params(error: T.nilable(Exception)).returns(T.nilable(Exception)) }
-      def exception_for_submission(error)
-        # happens on normal non-error termination
-        return if error.nil?
+      #: (Exception? error) -> bool
+      def caused_by_benign_signal?(error)
+        current = error #: Exception?
+        while current
+          return true if current.is_a?(SignalException) && SIGNALS_THAT_ARENT_BUGS.include?(current.message)
 
-        return unless error.bug?
+          current = current.cause
+        end
+        false
+      end
+
+      # Walks the cause chain looking for anything that should be reported as a
+      # bug. A terroir wrapper (e.g. Errno::EPIPE raised by a finalizer) can
+      # mask a real bug as its cause, so we can't only inspect the outermost
+      # exception. A non-benign signal (e.g. SIGSEGV) also counts as a bug.
+      #: (Exception? error) -> bool
+      def caused_by_bug?(error)
+        current = error #: Exception?
+        while current
+          return true if current.bug?
+          if current.is_a?(SignalException) && !SIGNALS_THAT_ARENT_BUGS.include?(current.message)
+            return true
+          end
+
+          current = current.cause
+        end
+        false
+      end
+
+      #: (Exception? error) -> Exception?
+      def exception_for_submission(error)
+        return if error.nil? || caused_by_benign_signal?(error) || !caused_by_bug?(error)
 
         case error
         when SignalException
@@ -161,14 +171,14 @@ module CLI
         end
       end
 
-      sig { params(message: String).void }
+      #: (String message) -> void
       def stderr_puts(message)
         $stderr.puts(CLI::UI.fmt("{{red:#{message}}}"))
       rescue Errno::EPIPE, Errno::EIO
         nil
       end
 
-      sig { returns(T.class_of(ExceptionReporter)) }
+      #: -> singleton(ExceptionReporter)
       def exception_reporter
         case @exception_reporter_or_proc
         when Proc

data/lib/cli/kit/executor.rb

@@ -7,15 +7,13 @@ require 'fileutils'
 module CLI
   module Kit
     class Executor
-      extend T::Sig
-
-      sig { params(log_file: String).void }
+      #: (log_file: String) -> void
       def initialize(log_file:)
         FileUtils.mkpath(File.dirname(log_file))
         @log_file = log_file
       end
 
-      sig { params(command: T.class_of(CLI::Kit::BaseCommand), command_name: String, args: T::Array[String]).void }
+      #: (singleton(CLI::Kit::BaseCommand) command, String command_name, Array[String] args) -> void
       def call(command, command_name, args)
         with_traps do
           with_logging do |id|
@@ -36,10 +34,7 @@ module CLI
 
       private
 
-      sig do
-        type_parameters(:T).params(block: T.proc.params(id: String).returns(T.type_parameter(:T)))
-          .returns(T.type_parameter(:T))
-      end
+      #: [T] { (String id) -> T } -> T
       def with_logging(&block)
         CLI::UI.log_output_to(@log_file) do
           CLI::UI::StdoutRouter.with_id(on_streams: [CLI::UI::StdoutRouter.duplicate_output_to].compact) do |id|
@@ -48,18 +43,14 @@ module CLI
         end
       end
 
-      sig { type_parameters(:T).params(block: T.proc.returns(T.type_parameter(:T))).returns(T.type_parameter(:T)) }
+      #: [T] { -> T } -> T
       def with_traps(&block)
         twrap('QUIT', method(:quit_handler)) do
           twrap('INFO', method(:info_handler), &block)
         end
       end
 
-      sig do
-        type_parameters(:T)
-          .params(signal: String, handler: Method, block: T.proc.returns(T.type_parameter(:T)))
-          .returns(T.type_parameter(:T))
-      end
+      #: [T] (String signal, Method handler) { -> T } -> T
       def twrap(signal, handler, &block)
         return yield unless Signal.list.key?(signal)
 
@@ -78,7 +69,7 @@ module CLI
         end
       end
 
-      sig { params(_sig: T.untyped).void }
+      #: (untyped _sig) -> void
       def quit_handler(_sig)
         z = caller
         CLI::UI.raw do
@@ -88,7 +79,7 @@ module CLI
         exit(CLI::Kit::EXIT_FAILURE_BUT_NOT_BUG)
       end
 
-      sig { params(_sig: T.untyped).void }
+      #: (untyped _sig) -> void
       def info_handler(_sig)
         z = caller
         CLI::UI.raw do