legionio 1.4.116 → 1.4.117

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6979926154eb319a990087443af9becaa5831d4eb0ab5525f1b044287e2c279f
-  data.tar.gz: '0129c7452e19e2f9c63f996ea254b44764a6caebfccb84f50ad0c8d058b910bb'
+  metadata.gz: d03cb4a8c6be7dd7d726f3999ebf88826914163aa9c59ac3a7206f7975616892
+  data.tar.gz: 1002f6425389c201d397f07163ccc40101880d0f9dadce0fb4c4159078b531cb
 SHA512:
-  metadata.gz: c1d1b49e93559deda93761855fa70fb72fe76673af87cf7c5fa4819a326d57318a2cc43c7c1f8bf9d0311487e3bbe1ee9d2154f52f14254630f4db8d7302f23f
-  data.tar.gz: fec26b4465b3806815ca5ddc62a476a54c4e88ce94654a18983aadab6940fcca9197ee8545b85038960d9688a9ba64d810499eef09374d0723081e523048766c
+  metadata.gz: 3f1679456170344d1ea966e7b08f5ba518f2f1957030b1cfa18c614516502bab2848861fd2c698f86ef72889cf4f79882ee1cafbf65a4bf8f3b00b23e8fb517c
+  data.tar.gz: 72c3d056636a57c41244a9483824d6eaa448feb3b970bff31dc79741ba884e89045d4cec22b32e716d350bdbbd72b67465d09ca91aade426c8b9596f7fb12e92

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Legion Changelog
 
+## [1.4.117] - 2026-03-22
+
+### Added
+- `Legion::CLI::Error` gains `suggestions`, `code` attributes and `.actionable` factory method
+- `Legion::CLI::ErrorHandler` module: 6-pattern matcher maps common exceptions (RabbitMQ, DB, extensions, permissions, data, Vault) to actionable errors with fix suggestions
+- `ErrorHandler.wrap` wraps any `StandardError` into a `CLI::Error` with suggestions when a pattern matches
+- `ErrorHandler.format_error` prints suggestions below the error line when the error is actionable
+- `Legion::CLI::Main.start` overrides Thor's entry point to wrap unhandled exceptions through `ErrorHandler` before exiting
+
 ## [1.4.116] - 2026-03-22
 
 ### Added

data/lib/legion/cli/error.rb

@@ -2,6 +2,19 @@
 
 module Legion
   module CLI
-    class Error < StandardError; end
+    class Error < StandardError
+      attr_reader :suggestions, :code
+
+      def self.actionable(code:, message:, suggestions: [])
+        err = new(message)
+        err.instance_variable_set(:@code, code)
+        err.instance_variable_set(:@suggestions, suggestions)
+        err
+      end
+
+      def actionable?
+        !suggestions.nil? && !suggestions.empty?
+      end
+    end
   end
 end

data/lib/legion/cli/error_handler.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Legion
+  module CLI
+    module ErrorHandler
+      PATTERNS = [
+        {
+          match:       /connection refused.*5672|ECONNREFUSED.*5672|bunny.*not connected/i,
+          code:        :transport_unavailable,
+          message:     'Cannot connect to RabbitMQ',
+          suggestions: [
+            "Run 'legion doctor' to diagnose connectivity",
+            "Check transport settings: 'legion config show -s transport'",
+            'Verify RabbitMQ is running: brew services list | grep rabbitmq'
+          ]
+        },
+        {
+          match:       /table.*not.*found|no such table|PG::UndefinedTable|Sequel::DatabaseError.*exist/i,
+          code:        :database_missing,
+          message:     'Database table not found',
+          suggestions: [
+            "Run 'legion start' to apply pending migrations",
+            "Check database config: 'legion config show -s data'",
+            "Verify database is running: 'legion doctor'"
+          ]
+        },
+        {
+          match:       /extension.*not.*found|no such extension|uninitialized constant.*Extensions/i,
+          code:        :extension_missing,
+          message:     'Extension not found',
+          suggestions: [
+            "Search available extensions: 'legion marketplace search <name>'",
+            'Install with: gem install lex-<name>',
+            "List installed: 'legion lex list'"
+          ]
+        },
+        {
+          match:       /permission denied|EACCES/i,
+          code:        :permission_denied,
+          message:     'Permission denied',
+          suggestions: [
+            'Try running with sudo for system directories',
+            'Set custom config dir: LEGIONIO_CONFIG_DIR=~/.legionio',
+            'Check file permissions: ls -la ~/.legionio/'
+          ]
+        },
+        {
+          match:       /legion-data.*not.*connected|data.*not.*available/i,
+          code:        :data_unavailable,
+          message:     'Database not connected',
+          suggestions: [
+            "Check database config: 'legion config show -s data'",
+            "Run diagnostics: 'legion doctor'",
+            'Some commands work without a database — try adding --no-data flag'
+          ]
+        },
+        {
+          match:       /vault.*not.*connected|vault.*sealed|VAULT_ADDR/i,
+          code:        :vault_unavailable,
+          message:     'Vault not connected',
+          suggestions: [
+            "Check Vault config: 'legion config show -s crypt'",
+            'Verify VAULT_ADDR and VAULT_TOKEN environment variables',
+            "Run diagnostics: 'legion doctor'"
+          ]
+        }
+      ].freeze
+
+      module_function
+
+      def wrap(error)
+        pattern = PATTERNS.find { |p| error.message.match?(p[:match]) }
+        return error unless pattern
+
+        Error.actionable(
+          code:        pattern[:code],
+          message:     "#{pattern[:message]}: #{error.message}",
+          suggestions: pattern[:suggestions]
+        )
+      end
+
+      def format_error(error, formatter)
+        formatter.error(error.message)
+        return unless error.is_a?(Error) && error.actionable?
+
+        error.suggestions.each do |suggestion|
+          puts "  #{formatter.colorize('>', :label)} #{suggestion}"
+        end
+      end
+    end
+  end
+end

data/lib/legion/cli.rb

@@ -3,6 +3,7 @@
 require 'thor'
 require 'legion/version'
 require 'legion/cli/error'
+require 'legion/cli/error_handler'
 require 'legion/cli/output'
 require 'legion/cli/connection'
 
@@ -61,6 +62,19 @@ module Legion
         true
       end
 
+      def self.start(given_args = ARGV, config = {})
+        super
+      rescue Legion::CLI::Error => e
+        formatter = Output::Formatter.new(json: given_args.include?('--json'), color: !given_args.include?('--no-color'))
+        ErrorHandler.format_error(e, formatter)
+        exit(1)
+      rescue StandardError => e
+        wrapped = ErrorHandler.wrap(e)
+        formatter = Output::Formatter.new(json: given_args.include?('--json'), color: !given_args.include?('--no-color'))
+        ErrorHandler.format_error(wrapped, formatter)
+        exit(1)
+      end
+
       class_option :json, type: :boolean, default: false, desc: 'Output as JSON'
       class_option :no_color, type: :boolean, default: false, desc: 'Disable color output'
       class_option :verbose, type: :boolean, default: false, aliases: ['-V'], desc: 'Verbose logging'

data/lib/legion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Legion
-  VERSION = '1.4.116'
+  VERSION = '1.4.117'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legionio
 version: !ruby/object:Gem::Version
-  version: 1.4.116
+  version: 1.4.117
 platform: ruby
 authors:
 - Esity
@@ -498,6 +498,7 @@ files:
 - lib/legion/cli/doctor/vault_check.rb
 - lib/legion/cli/doctor_command.rb
 - lib/legion/cli/error.rb
+- lib/legion/cli/error_handler.rb
 - lib/legion/cli/eval_command.rb
 - lib/legion/cli/failover_command.rb
 - lib/legion/cli/function.rb