cli-kit 5.2.0 → 5.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c397a745de33f27b897f8fd2048874be2f711a56db37ca17f87c5ad169e4f062
-  data.tar.gz: 80332fe8bd9a5dd5fb459f55d2f655a539cc95b13c4a2df174abafaaa4b7c924
+  metadata.gz: a71589e7905e5dc0152e3f34baada5c16289f98af365aa7f4f795cc2fee3c3d1
+  data.tar.gz: 796526fbab7044920aa42f5d42ca86c6f17a28c9285c344fa210dda10f0e8397
 SHA512:
-  metadata.gz: c689fdcf5ae697be38b21ce60e973874c0d6a7f5c0eeaa085b8b93e635a14cbcd3d6af229d0dcb2c7f00084ca58845c3055c687cd6e7fbd4bc8a1902a5582bd2
-  data.tar.gz: 153bf5c66de83e3d332944dfdc6fa9b1d52d4d5413ff80e4cac4b5aafbf0eddc888e22b2e50cf7914b43d1a90f56c23e2f41aaa7ec3987e7c51276092ad6f132
+  metadata.gz: 645d68f82d0147a7176b8a29d5d75f42848456528c06e3db2798823fc9cd732317f3935ddd5d4572e580d13186d6b17267d168f654ef57a19eaec5510074f64d
+  data.tar.gz: 5c9250e416b97184027b1742bfb88ee05873baf07d5d8bdfdcb6d5b24102eea0498914ee29ee3056a27dcb557879209c85c36f7c80ea53682b3b580cb887b773

data/.github/release.yml

@@ -0,0 +1,20 @@
+changelog:
+  exclude:
+    labels:
+      - dependencies
+    authors:
+      - dependabot
+  categories:
+    - title: 🚧 Breaking Changes
+      labels:
+        - breaking-change
+    - title: ✨ Enhancements
+      labels:
+        - enhancement
+        - feature
+    - title: 🐛 Bug Fixes
+      labels:
+        - bugfix
+    - title: 🛠 Other Changes
+      labels:
+        - "*"

data/.github/workflows/release.yml

@@ -0,0 +1,52 @@
+name: Release gem on RubyGems.org and create GitHub release
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  release_gem:
+    name: Release gem on RubyGems.org
+    if: github.repository == 'Shopify/cli-kit'
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      id-token: write
+
+    environment: release
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+        with:
+          bundler-cache: true
+
+      - name: Release gem on RubyGems.org
+        uses: rubygems/release-gem@7f9650160c1a4e7989fdc9855807bdbd421d8b6b # v1.4.1
+
+  release_github:
+    name: Create GitHub release
+    if: github.repository == 'Shopify/cli-kit'
+    needs: release_gem
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Create GitHub release
+        run: |
+          tag_name="$(git describe --tags --abbrev=0)"
+          gh release create "${tag_name}" --verify-tag --generate-notes
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

data/.github/workflows/ruby.yml

@@ -30,7 +30,7 @@ jobs:
     strategy:
       matrix:
         os: [macos-latest, ubuntu-latest]
-        ruby-version: ['3.1', '3.2', '3.3', '3.4']
+        ruby-version: ['3.2', '3.3', '3.4']
 
     runs-on: ${{ matrix.os }}
     env:

data/.rubocop.yml

@@ -7,6 +7,7 @@ inherit_from:
 plugins: rubocop-sorbet
 
 AllCops:
+  TargetRubyVersion: 3.2
   Exclude:
     - gen/template/**/*
     - vendor/**/*

data/Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: .
   specs:
-    cli-kit (5.2.0)
+    cli-kit (5.3.1)
       cli-ui (~> 2.4)
+      logger (~> 1.7)
 
 GEM
   remote: https://rubygems.org/

data/cli-kit.gemspec

@@ -26,8 +26,9 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_runtime_dependency('cli-ui', '~> 2.4')
+  spec.add_runtime_dependency('logger', '~> 1.7')
 
-  spec.required_ruby_version = '>= 3.0'
+  spec.required_ruby_version = '>= 3.2'
 
   spec.add_development_dependency('bundler', '~> 2.1')
   spec.add_development_dependency('minitest', '~> 5.0')

data/lib/cli/kit/config.rb

@@ -2,12 +2,120 @@
 
 require 'cli/kit'
 require 'fileutils'
+require 'tempfile'
 
 module CLI
   module Kit
     class Config
       XDG_CONFIG_HOME = 'XDG_CONFIG_HOME'
 
+      # 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. Diagnostics contain
+      # only changed section/key names, never their values. Config contents
+      # are not retained on the exception, to keep them out of error 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, Hash[String, Hash[String, String]] old_config, Hash[String, Hash[String, String]] new_config, SystemCallError cause) -> ConfigWriteError
+          def new(config_path, old_config, new_config, cause)
+            instance = allocate
+            instance.__send__(:initialize, config_path, old_config, new_config, cause)
+            instance
+          end
+        end
+
+        #: String
+        attr_reader :config_path
+
+        #: String
+        attr_reader :diff
+
+        # 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, Hash[String, Hash[String, String]] old_config, Hash[String, Hash[String, String]] new_config, SystemCallError cause) -> void
+        def initialize(config_path, old_config, new_config, cause)
+          @config_path = config_path
+          @diff = build_diff(old_config, new_config)
+          @wrapped_errno = cause.errno
+          message = <<~MSG.rstrip
+            Could not write to #{config_path}: #{cause.message}
+
+            Attempted changes (values and 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
+
+        private
+
+        #: (Hash[String, Hash[String, String]] old_config, Hash[String, Hash[String, String]] new_config) -> String
+        def build_diff(old_config, new_config)
+          lines = []
+          (old_config.keys | new_config.keys).each do |section|
+            old_section = old_config[section] || {}
+            new_section = new_config[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}" if old_val
+              changes << "+ #{key}" 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
@@ -129,8 +237,80 @@ module CLI
         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_config = read_config_for_diff(config_path)
+          raise(ConfigWriteError.new(config_path, old_config, all_configs, 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
+          # Configs may contain credentials. Keep them private to the
+          # owner, including when replacing a previously shared file.
+          # Preserve stricter owner permissions on existing files and
+          # respect the umask when creating new ones.
+          mode = if File.exist?(config_path)
+            File.stat(config_path).mode & 0o600
+          else
+            0o600 & ~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) -> Hash[String, Hash[String, String]]
+      def read_config_for_diff(config_path)
+        CLI::Kit::Ini.new(config: File.read(config_path)).tap(&:parse).ini
+      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

@@ -6,11 +6,83 @@ class Exception
   # 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.
 
-  #: -> bool
-  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.).
+    # @sealed
+    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
+
+  #: -> 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
@@ -26,3 +98,44 @@ class Exception
     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

@@ -84,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
@@ -93,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
@@ -114,12 +114,38 @@ module CLI
         e.bug? ? CLI::Kit::EXIT_BUG : CLI::Kit::EXIT_FAILURE_BUT_NOT_BUG
       end
 
+      #: (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)
+
+          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)
-        # happens on normal non-error termination
-        return if error.nil?
-
-        return unless error.bug?
+        return if error.nil? || caused_by_benign_signal?(error) || !caused_by_bug?(error)
 
         case error
         when SignalException

data/lib/cli/kit/version.rb

@@ -2,6 +2,6 @@
 
 module CLI
   module Kit
-    VERSION = '5.2.0'
+    VERSION = '5.3.1'
   end
 end

data/lib/cli/kit.rb

@@ -109,7 +109,7 @@ module CLI
       # `depth` is used to trim leading elements of the backtrace. If you wrap
       # this method in your own wrapper, you'll want to pass `depth: 2`, for
       # example.
-      #: (?(Class | String | Exception) exception, ?untyped string, ?Array[String]? array, ?cause: Exception?, ?bug: bool?, ?silent: bool?, ?depth: Integer) -> bot
+      #: (?(Class | String | Exception) exception, ?untyped string, ?Array[String]? array, ?cause: Exception?, ?bug: bool?, ?silent: bool?, ?fault: Exception::Fault?, ?depth: Integer) -> bot
       def raise(
         # default arguments
         exception = UNTYPED_NIL,
@@ -117,7 +117,7 @@ module CLI
         array = UNTYPED_NIL,
         cause: $ERROR_INFO,
         # new arguments
-        bug: nil, silent: nil, depth: 1
+        bug: nil, silent: nil, fault: nil, depth: 1
       )
         k = Kernel #: as untyped
         if array
@@ -132,6 +132,7 @@ module CLI
       rescue Exception => e # rubocop:disable Lint/RescueException
         e.bug!(bug) unless bug.nil?
         e.silent!(silent) unless silent.nil?
+        e.fault!(fault) if fault
         Kernel.raise(e, cause: cause)
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cli-kit
 version: !ruby/object:Gem::Version
-  version: 5.2.0
+  version: 5.3.1
 platform: ruby
 authors:
 - Burke Libbey
@@ -26,6 +26,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -81,7 +95,9 @@ extra_rdoc_files: []
 files:
 - ".github/CODEOWNERS"
 - ".github/dependabot.yml"
+- ".github/release.yml"
 - ".github/workflows/cla.yml"
+- ".github/workflows/release.yml"
 - ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".rubocop.sorbet.yml"
@@ -164,7 +180,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="