cli_class_tool 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 641f72caf2c39cac1c5a222756c481f0de86b5fd7db14893001a64773400d894
-  data.tar.gz: 612b9cca3cbd1b157780c490093657e77ba021bb973ca38e76e63f19de1e730e
+  metadata.gz: b709fe8b17a110ea17968fb9d7d4ff45e2ceac57bed76c3dcda67438880dcdc4
+  data.tar.gz: 1ff6831f0c5bfbc9d54d8dac31e18fdad3003ec0d527bfb3999e11a472b1591b
 SHA512:
-  metadata.gz: f2ceb59e563ebe911176786f1e4ffdd3762c2ef0b9a62acad6323896c68741228468f3b21e53331f4b22774b4bd0ac8746048330408d84366b6fa4426a546ff6
-  data.tar.gz: 3d848b3725fd1e80e061d04e358bbb71821708fc2ed490612ad4fe66b2ffc038396605cda7dfa28f89d7bdaaf703f6b038a0b66a68f18d18c12a2a12742667ab
+  metadata.gz: f408128eb985f8ad45949c452be46aa55edc028f1dc060c2870afdbea358016258071e0cc8aadf155e867c0f8e7be4295e8045c699eb0f82c501feaeb9b7502b
+  data.tar.gz: 75d8bbfd502b9a331be9c57e25b7f824b2bf1d24c94f6fe477f64f2078dde1a76911b4964b0bdcf531098f895a753556778571f0a4354e1d2b733b1fedc56212

data/CHANGELOG

@@ -1,7 +1,17 @@
+------------------
+0.3.0  (2026-06-02)
+------------------
+
+
+* Enforce module/class namespaces for all action classes (potentially breaking change)
+* Support automatic project-specific `RunError` generation with customized base error inheritance
+
 ------------------
 0.2.1  (2026-06-01)
 ------------------
 
+* Fix issue with conflicting addon files
+
 ------------------
 0.2.0  (2026-06-01)
 ------------------

data/README.md

@@ -112,6 +112,61 @@ exit MyProject.execAction(opts, opts[:action])
 
 ---
 
+## Namespace Requirement & Error Handling
+
+### 1. Module Namespace Requirement
+
+To ensure clean encapsulation and safe error resolution, all action classes and standard subclasses inheriting from `CLIClassTool::Common` **must** be defined within a named module/class namespace (such as `MyProject`):
+
+```ruby
+# Correct: Action class is scoped under MyProject namespace
+module MyProject
+  class Suse < CLIClassTool::Common
+    # ...
+  end
+end
+
+# Incorrect: Defining action classes directly in the global namespace is forbidden
+# and will raise an error at load-time:
+class Suse < CLIClassTool::Common; end
+# => "CLIClassTool action classes must be defined within a named module/class namespace"
+```
+
+### 2. Automated `RunError` Generation & Customized Inheritance
+
+When your project's parent module extends `CLIClassTool::Utils`, `CLIClassTool` automatically generates a nested `RunError` class (i.e. `MyProject::RunError`) specifically for your project on load.
+
+By default, this generated error inherits from `CLIClassTool::RunError`. However, if you have a binary-specific or project-wide base error class defined, `CLIClassTool` will **automatically detect it** and make `RunError` inherit from it instead!
+
+It looks for existing error classes in this order:
+1. `#{base_name}Error` (e.g., `MyProjectError` in the global scope)
+2. `#{base_name}::Error` (e.g., `MyProject::Error` within your namespace)
+3. Falls back to `CLIClassTool::RunError`
+
+#### Why is this useful?
+This allows you to catch all potential CLI errors (including system command failures from `run`, `runGit`, etc.) in a single rescue block at the entry point of your binary:
+
+```ruby
+# Define your binary-specific error class
+class MyProjectError < StandardError; end
+
+module MyProject
+  extend CLIClassTool::Utils
+  # CLIClassTool automatically defines MyProject::RunError inheriting from MyProjectError!
+end
+
+# In your executable (bin/mytool)
+begin
+  MyProject.run_cli
+rescue MyProjectError => e
+  # This cleanly catches MyProject::RunError, as well as any other custom MyProjectError!
+  STDERR.puts "# ERROR: #{e.message}"
+  exit e.respond_to?(:err_code) ? e.err_code : 1
+end
+```
+
+---
+
 ## Logging Levels
 By inheriting from `CLIClassTool::Common`, your action classes have access to a rich `log` helper supporting several standard output and color levels:
 

data/lib/cli_class_tool/common.rb

@@ -3,6 +3,16 @@ module CLIClassTool
 
     # Common utility class providing logging, configuration, and shell execution methods
     class Common
+        # Hook to enforce namespace loading at load time
+        def self.inherited(subclass)
+            if subclass.name
+                parts = subclass.name.to_s.split('::')
+                if parts.size <= 1
+                    raise "CLIClassTool action classes must be defined within a named module/class namespace"
+                end
+            end
+        end
+
         # List of available actions for this class
         ACTION_LIST = [ :list_actions ]
         # Help text for actions
@@ -12,8 +22,15 @@ module CLIClassTool
         # Get the parent module of this class (e.g. KernelWork or XXX)
         def parent_module
             @parent_module ||= begin
-                parts = self.class.name.split('::')
-                parts.size > 1 ? Object.const_get(parts[0...-1].join('::')) : Object
+                if self.class.name.nil?
+                    Object
+                else
+                    parts = self.class.name.split('::')
+                    if parts.size <= 1
+                        raise "CLIClassTool action classes must be defined within a named module/class namespace"
+                    end
+                    Object.const_get(parts[0...-1].join('::'))
+                end
             end
         end
 
@@ -40,8 +57,10 @@ module CLIClassTool
         # @raise [StandardError] If command failed
         def abort_if_err(check_err, sysret, ret = nil)
             if sysret.exitstatus != 0 && check_err == true
-                run_error_class = parent_module.const_defined?(:RunError) ? parent_module::RunError : RuntimeError
-                raise(run_error_class.new(sysret.exitstatus, ret))
+                unless parent_module.const_defined?(:RunError)
+                    raise "CLIClassTool parent module #{parent_module} must extend CLIClassTool::Utils to define RunError"
+                end
+                raise(parent_module::RunError.new(sysret.exitstatus, ret))
             end
         end
 

data/lib/cli_class_tool/utils.rb

@@ -2,6 +2,21 @@ module CLIClassTool
     # Generic utilities for CLI class-based actions
     module Utils
 
+        # Hook called when a module extends CLIClassTool::Utils
+        def self.extended(base)
+            possible_name = base.name ? "#{base.name}Error" : nil
+
+            superclass = if possible_name && Object.const_defined?(possible_name)
+                Object.const_get(possible_name)
+            elsif base.const_defined?(:Error)
+                base.const_get(:Error)
+            else
+                CLIClassTool::RunError
+            end
+
+            CLIClassTool.define_run_error(base, superclass)
+        end
+
         # Convert a string to an action symbol, validating it against available actions
         #
         # @param str [String] Action name
@@ -186,7 +201,6 @@ module CLIClassTool
         def run_cli(opts = {}, argv = ARGV)
             # Fetch actions and action helps
             action_helps = self.getActionAttr("ACTION_HELP")
-            action_list = self.getActionAttr("ACTION_LIST")
 
             # 1. Action Parser Setup
             action_parser = OptionParser.new(nil, 60)

data/lib/cli_class_tool.rb

@@ -1,3 +1,33 @@
+module CLIClassTool
+  class RunError < StandardError
+    attr_reader :err_code, :output
+
+    def initialize(err_code, output = nil)
+      @err_code = err_code
+      @output = output
+      super("Command failed with exit status #{err_code}#{output ? "\n#{output}" : ''}")
+    end
+  end
+
+  def self.define_run_error(parent_module, superclass = CLIClassTool::RunError)
+    klass = Class.new(superclass)
+
+    if !(superclass <= CLIClassTool::RunError)
+      klass.class_eval do
+        attr_reader :err_code, :output
+
+        def initialize(err_code, output = nil)
+          @err_code = err_code
+          @output = output
+          super("Command failed with exit status #{err_code}#{output ? "\n#{output}" : ''}")
+        end
+      end
+    end
+
+    parent_module.const_set(:RunError, klass)
+  end
+end
+
 require_relative 'cli_class_tool/string'
 require_relative 'cli_class_tool/common'
 require_relative 'cli_class_tool/utils'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: cli_class_tool
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Nicolas Morey
 bindir: bin
 cert_chain: []
-date: 2026-06-01 00:00:00.000000000 Z
+date: 2026-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake