hati-command 0.1.0.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8a7695ebc8436769523738139c4283bd648475092fbd41ee4ffbc6ae3c721a5c
+  data.tar.gz: 075c0911c8855a4a811302fac864fe2fda8c55a1cfc358eb3c1eb3918050e180
+SHA512:
+  metadata.gz: a7c10d976e359912c6a6ef0da1b9b0fc88de2d84ac3d084a2155a6a9437114207254bdc36eefe423938e477f151400e7868dd473ad3fe82c7e677815fdfe6185
+  data.tar.gz: c530a89f9eed5dfa5d2d5b1e25ece68fd422ceb5139a94b98c374af259816f685396a06b8d49974f7170744872f09561efdad4b84589ff65f3bc8f771572cdca

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hackico.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,439 @@
+# ![Ruby](icon.svg) hati-command
+
+The `hati-command` gem is designed to simplify command execution, emphasizing effective handling of success and failure outcomes. It can be employed as a service object or interactor, fostering clean and organized code for managing complex operations.
+
+- **hati-command** provides a simple and flexible way to handle command execution and result handling.
+
+- **hati-command** offers a `Success` and `Failure` result classes to handle command execution results.
+
+- **hati-command** It provides a `Result` object to access the result value, success, and failure, along with options to attach custom messages and metadata for better context.
+
+## Features
+
+- **Command Execution**: Execute commands seamlessly, allowing for optional parameters.
+- **Success Handling**: Provides success responses with transformed messages and additional metadata.
+- **Failure Handling**: Handles failures gracefully, returning informative messages and context.
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Features](#features)
+- [Installation](#installation)
+- [Basic Usage](#basic-usage)
+  - [Handling Success](#handling-success)
+  - [Handling Failure](#handling-failure)
+  - [Transactional Behavior](#transactional-behavior-fail-fast-with-failure)
+- [Advanced Usage](#advanced-usage)
+  - [Result Customization](#result-customization)
+    - [meta](#meta)
+    - [error](#error)
+    - [trace](#trace)
+  - [Command Configurations](#command-configurations)
+    - [failure](#failure)
+    - [fail_fast](#fail_fast)
+    - [unexpected_err](#unexpected_err)
+    - [result_inference](#result_inference)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Code of Conduct](#code-of-conduct)
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add hati-command
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install hati-command
+```
+
+## Basic Usage
+
+To use the `hati-command` gem, you can create a command class that includes the `HatiCommand::Cmd` module. Here’s a simple example:
+
+```ruby
+require 'hati_command'
+
+class GreetingCommand
+  include HatiCommand::Cmd
+
+  def call(greeting = nil)
+    message = build_greeting(greeting)
+    return message if message.failure?
+
+    process_message(message)
+  end
+
+  def build_greeting(greeting)
+    greeting ? Success(greeting) : Failure("No greeting provided")
+  end
+
+  def process_message(message)
+    message.success? ? Success(message.upcase) : Failure("No message provided")
+  end
+end
+```
+
+### Handling `Success`
+
+```ruby
+result = GreetingCommand.call("Hello, World!")
+
+puts result.success? # Outputs: true
+puts result.failure? # Outputs: false
+
+puts result.success  # Outputs: "HELLO, WORLD!"
+puts result.failure  # Outputs: nil
+
+puts result.value    # Outputs: "HELLO, WORLD!"
+puts result.result   # Outputs: HatiCommand::Success
+
+```
+
+### Handling `Failure`
+
+```ruby
+result = GreetingCommand.call
+
+puts result.failure? # Outputs: true
+puts result.success? # Outputs: false
+
+puts result.failure  # Outputs: "No message provided"
+puts result.success  # Outputs: nil
+
+puts result.value    # Outputs: "No message provided"
+puts result.result   # Outputs: HatiCommand::Failure
+```
+
+### Transactional Behavior: Fail Fast with `Failure!`
+
+```ruby
+class GreetingCommand
+  include HatiCommand::Cmd
+
+  # NOTE: Will catch unexpected and wrap to HatiCommand::Failure object
+  #       Requires true || ErrorObject
+  command do
+    unexpected_err true
+  end
+
+  def call(params)
+    message = process_message(params[:message])
+    msg = normalize_message(message, params[:recipients])
+
+    Success(msg)
+  end
+
+  # NOTE: No message passed - auto break an execution
+  def process_message(message)
+    message ? message.upcase : Failure!("No message provided")
+  end
+
+  def normalize_message(message, recipients)
+    Failure!("No recipients provided") if recipients.empty?
+
+    recipients.map { |recipient| "#{recipient}: #{message}" }
+  end
+end
+```
+
+```ruby
+# NOTE: No message passed - command exited
+#       Returns Result (Failure) object
+result = GreetingCommand.call
+
+puts result.failure? # Outputs: true
+puts result.failure  # Outputs: "No message provided"
+puts result.value    # Outputs: "No message provided"
+```
+
+```ruby
+
+result = GreetingCommand.call(params.merge(message: "Hello!"))
+
+puts result.failure? # Outputs: true
+puts result.failure  # Outputs: "No recipients provided"
+puts result.value    # Outputs: "No recipients provided"
+```
+
+```ruby
+result = GreetingCommand.call(params.merge(recipients: ["Alice", "Bob"]))
+
+puts result.failure? # Outputs: false
+puts result.success  # Outputs: true
+puts result.value    # Outputs: ["Alice: Hello!", "Bob: Hello!"]
+```
+
+## Advanced Usage
+
+Configurations and customization allow users to tailor the command to meet their specific needs and preferences
+
+### `Result` Customization
+
+Here are some advanced examples of result customization. Available options are
+
+- `meta` - Hash to attach custom metadata
+- `err` - Message or Error access via `error` method
+- `trace` - By design `Failure!` and `unexpected_err` error's stack top entry
+
+### .meta
+
+```ruby
+class GreetingCommand
+  include HatiCommand::Cmd
+  # ...
+  def process_message(message)
+    Success(message.upcase, meta: { lang: :eng, length: message.length })
+  end
+  # ...
+end
+```
+
+```ruby
+result = GreetingCommand.("Hello, Advanced World!")
+puts result.value         # Outputs: "HELLO, ADVANCED WORLD!"
+
+puts result.meta[:lang]   # Outputs: :eng
+puts result.meta[:length] # Outputs: 22
+puts result.meta          # Outputs: {:lang=>:eng, :length=>22}
+```
+
+### .error
+
+##### set via `err` access via `error` method. Availiable as param for `#Success` as well (ex. partial success)
+
+```ruby
+class GreetingCommand
+  include HatiCommand::Cmd
+  # ...
+  def process_message(message)
+    Failure(message, err: "No message provided")
+  end
+end
+```
+
+```ruby
+result = GreetingCommand.call
+puts result.value   # Outputs: nil
+puts result.error   # Outputs: "No message provided"
+puts result.trace   # Outputs:
+```
+
+### .trace
+
+##### Available as accessor on `Result` object
+
+```ruby
+1| class DoomedCommand
+2|   include HatiCommand::Cmd
+3|
+4|   def call
+5|     Failure!
+6|   end
+7|   # ...
+8| end
+```
+
+```ruby
+result = GreetingCommand.call
+puts result.failure? # Outputs: true
+puts result.trace    # Outputs: path/to/cmds/doomed_command.rb:5:in `call'
+```
+
+### Command `Configurations`
+
+Provides options for default failure message or errors. Available configs are:
+
+- `failure` - Message or Error
+- `fail_fast` - Message or Error
+- `unexpected_err` - Bool(true) or Message or Error
+- `result_inference` - Bool(true) | implicit Result wrapper
+- `call_as` - Symbol | Main call method name
+
+### failure
+
+```ruby
+1 | class DoomedCommand
+2 |   include HatiCommand::Cmd
+3 |
+4 |   command do
+5 |     failure "Default Error"
+6 |   end
+7 |
+8 |   def call(error = nil, fail_fast: false)
+9 |     Failure! if fail_fast
+10|
+11|     return Failure("Foo") unless option
+12|
+13|     Failure(error, err: "Insufficient funds")
+14|   end
+15|   # ...
+16| end
+```
+
+```ruby
+result = DoomedCommand.call(fail_fast: true)
+# NOTE: not configured fail fast uses default error
+puts result.failure # Outputs: nil
+puts result.error   # Outputs: "Default Error"
+puts result.trace   # Outputs: path/to/cmds/doomed_command.rb:5:in `call'
+
+
+result = DoomedCommand.call
+puts result.failure # Outputs: "Foo"
+puts result.error   # Outputs: "Default Error"
+
+result = DoomedCommand.call('Buzz')
+puts result.failure # Outputs: "Buzz"
+puts result.error   # Outputs: "Insufficient funds"
+```
+
+### fail_fast
+
+```ruby
+1 | class DoomedCommand
+2 |   include HatiCommand::Cmd
+3 |
+4 |   command do
+5 |     fail_fast "Default Fail Fast Error"
+6 |   end
+7 |
+8 |   def call
+9 |     Failure!
+10|   end
+11|   # ...
+12| end
+```
+
+```ruby
+result = DoomedCommand.call
+puts result.failure # Outputs: nil
+puts result.error   # Outputs: "Default Fail Fast Error"
+puts result.trace   # Outputs: path/to/cmds/doomed_command.rb:9:in `call'
+```
+
+### unexpected_err
+
+```ruby
+1 | class GreetingCommand
+2 |   include HatiCommand::Cmd
+3 |
+4 |   command do
+5 |     unexpected_err true
+5 |   end
+6 |
+7 |   def call
+8 |     1 + "2"
+9 |   end
+10|   # ...
+11| end
+```
+
+```ruby
+result = GreetingCommand.call
+puts result.failure # Outputs: nil
+puts result.error   # Outputs: TypeError: no implicit conversion of Integer into String
+puts result.trace   # Outputs: path/to/cmds/greeting_command.rb:9:in `call'
+```
+
+### unexpected_err (wrapped)
+
+```ruby
+1 | class GreetingCommand
+2 |   include HatiCommand::Cmd
+3 |
+4 |   class GreetingError < StandardError; end
+5 |
+6 |   command do
+7 |     unexpected_err GreetingError
+8 |   end
+9 |
+10|   def call
+11|     1 + "2"
+12|   end
+13|   # ...
+14| end
+```
+
+```ruby
+result = GreetingCommand.call
+# NOTE: Original error becomes value (failure)
+puts result.failure # Outputs: TypeError: no implicit conversion of Integer into String
+
+puts result.error   # Outputs: GreetingError
+puts result.trace   # Outputs: path/to/cmds/greeting_command.rb:12:in `call'
+```
+
+### result_inference
+
+```ruby
+1 | class GreetingCommand
+2 |   include HatiCommand::Cmd
+3 |
+4 |   command do
+5 |     result_inference true # Implicitly wraps non-Result as Success
+5 |   end
+6 |
+7 |   def call
+8 |     42
+9 |   end
+10|   # ...
+11| end
+```
+
+```ruby
+result = GreetingCommand.call
+puts result.success  # Outputs: 42
+puts result.failure? # Outputs: false
+```
+
+### call_as
+
+```ruby
+1 | class GreetingCommand
+2 |   include HatiCommand::Cmd
+3 |
+4 |   command do
+5 |     call_as :execute # E.q. :perform, :run, etc.
+5 |   end
+6 |
+7 |   def execute
+8 |     Success(42)
+9 |   end
+10|   # ...
+11| end
+```
+
+```ruby
+result = GreetingCommand.execute
+puts result.success  # Outputs: 42
+puts result.failure? # Outputs: false
+```
+
+## Authors
+
+- [Yuri Gi](https://github.com/yurigitsu)
+- [Marie Giy](https://github.com/mariegiy)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/hackico-ai/hati-command. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/hackico-ai/hati-command/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the HatCommand project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/hackico-ai/hati-command/blob/main/CODE_OF_CONDUCT.md).

data/hati-command.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'hati_command/version'
+
+Gem::Specification.new do |spec|
+  spec.name    = 'hati-command'
+  spec.version = HatiCommand::VERSION
+  spec.authors = %w[yurigitsu MarieGiy]
+  spec.email   = %w[yurigi.pro@gmail.com giy.mariya@gmail.com]
+  spec.license = 'MIT'
+
+  spec.summary     = 'A Ruby gem for creating command objects with result handling.'
+  spec.description = 'hati-command is a Ruby gem for implementing the Command pattern with result handling.'
+  spec.homepage    = "https://github.com/hackico-ai/#{spec.name}"
+
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.files  = Dir['CHANGELOG.md', 'LICENSE', 'README.md', 'hati-command.gemspec', 'lib/**/*']
+  spec.bindir = 'bin'
+  spec.executables   = []
+  spec.require_paths = ['lib']
+
+  spec.metadata['repo_homepage']     = spec.homepage
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri']    = spec.homepage
+  spec.metadata['changelog_uri']   = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['bug_tracker_uri'] = "#{spec.homepage}/issues"
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/lib/hati_command/befehl.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+# @module HatiCommand
+# Provides command handling functionalities for creating and managing commands.
+# This module serves as the main namespace for all command-related operations.
+module HatiCommand
+  # @module Befehl
+  # Core module for command handling that provides the base functionality for creating commands.
+  # This module is designed to be extended by classes that need command handling capabilities.
+  module Befehl
+    # Extends the base class with command handling functionality
+    # @param base [Class] the class that is extending this module
+    # @return [void]
+    def self.extended(base)
+      base.extend(BefehlClassMethods)
+      def base.inherited(subclass)
+        super
+        subclass.instance_variable_set(:@__command_config, @__command_config.dup)
+      end
+    end
+
+    # @module BefehlClassMethods
+    # Provides class methods for command configuration and execution.
+    # These methods are automatically added to any class that extends Befehl.
+    module BefehlClassMethods
+      # Configures a command block with specific settings
+      # @yield [void] The configuration block
+      # @return [Hash] The command configuration
+      # @example
+      #   command do
+      #     failure :my_failure_handler
+      #     fail_fast true
+      #   end
+      def command(&block)
+        @__command_config ||= { call_as: :call }
+        instance_eval(&block) if block_given?
+      end
+
+      # Retrieves the current command configuration
+      # @return [Hash] The current command configuration settings
+      def command_config
+        @__command_config
+      end
+
+      # Sets the result inference behavior for the command.
+      # @param value [Boolean] Indicates whether to enable result inference.
+      # @return [void]
+      def result_inference(value)
+        @__command_config[:result_inference] = value
+      end
+
+      # Sets the failure handler for the command
+      # @param value [Symbol, Proc] The failure handler to be used
+      # @return [void]
+      def failure(value)
+        @__command_config[:failure] = value
+      end
+
+      # Sets the fail-fast behavior for the command
+      # @param value [Boolean] Whether to enable fail-fast behavior
+      # @return [void]
+      def fail_fast(value)
+        @__command_config[:fail_fast] = value
+      end
+
+      # Sets the unexpected error handler for the command
+      # @param value [Symbol, Proc, Boolean] The error handler to be used
+      # @return [void]
+      def unexpected_err(value)
+        @__command_config[:unexpected_err] = value
+      end
+
+      # This method checks if a caller method has been set; if not, it defaults to `:call`.
+      # @return [Symbol] The name of the method to call.
+      def call_as(value = :call)
+        @__command_config[:call_as] = value
+
+        singleton_class.send(:alias_method, value, :call)
+      end
+
+      # Executes the command with the given arguments.
+      #
+      # This method creates a new instance of the command class, yields it to an optional block,
+      # and then calls the instance method with the provided arguments. It handles the result
+      # of the command execution, returning a success or failure result based on the outcome.
+      #
+      # @param args [Array] Arguments to be passed to the instance method.
+      # @yield [Object] Optional block that yields the new instance for additional configuration.
+      # @return [HatiCommand::Result, Object] The result of the command execution, wrapped in a Result object if applicable.
+      # @raise [HatiCommand::Errors::FailFastError] If a fail-fast condition is triggered.
+      # @raise [StandardError] If an unexpected error occurs and no handler is configured.
+      def call(...)
+        obj = new
+
+        yield(obj) if block_given?
+
+        result = obj.send(command_config[:call_as], ...)
+        return result unless command_config[:result_inference]
+        return result if result.is_a?(HatiCommand::Result)
+
+        HatiCommand::Success.new(result)
+      rescue HatiCommand::Errors::FailFastError => e
+        handle_fail_fast_error(e)
+      rescue StandardError => e
+        handle_standard_error(e)
+      end
+
+      module_function
+
+      # Handles fail-fast errors during command execution
+      # @param error [HatiCommand::Errors::FailFastError] The fail-fast error to handle
+      # @return [HatiCommand::Failure] A failure object containing error details
+      # @api private
+      def handle_fail_fast_error(error)
+        err_obj = error.err_obj
+        return HatiCommand::Failure.new(error, trace: error.backtrace.first) unless err_obj
+
+        err_obj.tap { |err| err.trace = error.backtrace[1] }
+      end
+
+      # Handles standard errors during command execution
+      # @param error [StandardError] The error to handle
+      # @return [HatiCommand::Failure] A failure object containing error details
+      # @raise [StandardError] If no unexpected error handler is configured
+      # @api private
+      def handle_standard_error(error)
+        internal_err = command_config[:unexpected_err]
+        raise error unless internal_err
+
+        err = internal_err.is_a?(TrueClass) ? error : internal_err
+        HatiCommand::Failure.new(error, err: err, trace: error.backtrace.first)
+      end
+    end
+  end
+end

data/lib/hati_command/callee.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'pry'
+
+# @module HatiCommand
+# Provides command handling functionalities and callable patterns.
+module HatiCommand
+  # @module Callee
+  # Module for adding callable functionality to a class.
+  # This module implements the callable pattern, allowing classes to be called like functions
+  # while maintaining object-oriented principles.
+  #
+  # @example
+  #   class MyCallable
+  #     include HatiCommand::Callee
+  #
+  #     def call(input)
+  #       # Process input
+  #       input.upcase
+  #     end
+  #   end
+  #
+  #   # Can be used as:
+  #   result = MyCallable.call("hello")  # => "HELLO"
+  #
+  #   # Or with a block:
+  #   MyCallable.call("hello") do |instance|
+  #     instance.configure(some: :option)
+  #   end
+  module Callee
+    # Extends the including class with callable functionality
+    # @param base [Class] The class including this module
+    # @return [void]
+    # @api private
+    def self.included(base)
+      base.extend(CalleeClassMethods)
+    end
+
+    # Returns the identity of the module
+    # @note This is a work in progress method
+    # @return [String] The module's identity string
+    # @api public
+    def self.whoami
+      'My Name is Callee'
+    end
+
+    # @module CalleeClassMethods
+    # Class methods that are extended to classes including Callee.
+    # Provides the callable interface at the class level.
+    module CalleeClassMethods
+      # This method checks if a caller method has been set; if not, it defaults to `:call`.
+      #
+      # @return [Symbol] The name of the method to call.
+      def __caller_method
+        @__caller_method || :call
+      end
+
+      # Creates a new instance and calls its `call` method with the given arguments.
+      # This method implements the callable pattern, allowing the class to be used
+      # like a function while maintaining object-oriented principles.
+      #
+      # @param args [Array] Arguments to be passed to the instance's call method
+      # @yield [Object] Optional block that yields the new instance before calling
+      # @yieldparam instance [Object] The newly created instance
+      # @return [Object] The result of the instance method call
+      #
+      # @example Without block
+      #   MyCallable.call(arg1, arg2)
+      # @example With configuration block
+      #   MyCallable.call(input) do |instance|
+      #     instance.configure(option: value)
+      #   end
+      def call(...)
+        obj = new
+
+        yield(obj) if block_given?
+
+        obj.send(__caller_method, ...)
+      end
+
+      # This method allows you to configure command call method name such as: :execute, :perform, etc.
+      # Note: method call_as and command main instance method should much
+      # @param method_name [Symbol] The name of the alias to create for the `call` method.
+      # @return [void]
+      #
+      #  @example
+      #   class MyCallable
+      #     include HatiCommand::Callee
+      #
+      #     call_as :execute # :run, :perform, etc.
+      #
+      #     def execute(input) # :run, :perform, etc.
+      #       input.upcase
+      #     end
+      #
+      #   end
+      #   MyCallable.execute("hello")  # => "HELLO"
+      #   MyCallable.perform("hello")  # => "HELLO"
+      #   MyCallable.run("hello")  # => "HELLO"
+      def call_as(method_name)
+        @__caller_method = method_name
+
+        singleton_class.send(:alias_method, method_name, :call)
+      end
+    end
+  end
+end

data/lib/hati_command/cmd.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# @module HatiCommand
+# Provides command handling functionalities with a focus on Railway-oriented programming.
+# This module implements the Railway pattern for better error handling and command flow control.
+module HatiCommand
+  # @module Cmd
+  # Dev-friendly extension of the Befehl core module with Railway track API.
+  # This module provides a Railway-oriented programming interface for handling success and failure states
+  # in a functional way, making it easier to chain operations and handle errors gracefully.
+  #
+  # @example
+  #   class MyCommand
+  #     include HatiCommand::Cmd
+  #
+  #     def call(input)
+  #       if valid?(input)
+  #         Success(input)
+  #       else
+  #         Failure("Invalid input")
+  #       end
+  #     end
+  #   end
+  module Cmd
+    # Includes the module in the base class and sets up necessary configurations
+    # @param base [Class] The class including this module
+    # @return [void]
+    def self.included(base)
+      base.extend(HatiCommand::Befehl)
+      base.private_class_method :new
+    end
+
+    # Returns the identity of the module
+    # @note This is a work in progress method
+    # @return [String] The module's identity string
+    # @api public
+    def self.whoami
+      'My Name is Cmd'
+    end
+
+    # Creates a Success monad representing a successful operation
+    # @param value [Object, nil] The value to wrap in the Success monad
+    # @param err [Object, nil] Optional error object
+    # @param meta [Hash] Additional metadata for the success state
+    # @return [HatiCommand::Success] A Success monad containing the result
+    # @example
+    #   Success("Operation completed", meta: { time: Time.now })
+    def Success(value = nil, err: nil, meta: {}) # rubocop:disable Naming/MethodName
+      HatiCommand::Success.new(value, err: err, meta: meta)
+    end
+
+    # Creates a Failure monad representing a failed operation
+    # @param value [Object, nil] The value to wrap in the Failure monad
+    # @param err [Object, nil] Optional error object (falls back to configured default)
+    # @param meta [Hash] Additional metadata for the failure state
+    # @return [HatiCommand::Failure] A Failure monad containing the error details
+    # @example
+    #   Failure("Operation failed", err: StandardError.new, meta: { reason: "invalid_input" })
+    def Failure(value = nil, err: nil, meta: {}) # rubocop:disable Naming/MethodName
+      default_err = self.class.command_config[:failure]
+      HatiCommand::Failure.new(value, err: err || default_err, meta: meta)
+    end
+
+    # Creates a Failure monad and immediately raises a FailFastError
+    # @param value [Object, nil] The value to wrap in the Failure monad
+    # @param err [Object, nil] Optional error object (falls back to configured defaults)
+    # @param meta [Hash] Additional metadata for the failure state
+    # @param _opts [Hash] Additional options (currently unused)
+    # @raise [HatiCommand::Errors::FailFastError] Always raises with the created Failure monad
+    # @example
+    #   Failure!("Critical error", err: FatalError.new)
+    def Failure!(value = nil, err: nil, meta: {}, **_opts) # rubocop:disable Naming/MethodName
+      default_error = self.class.command_config[:fail_fast] || self.class.command_config[:failure]
+      error = err || default_error
+
+      err_obj = HatiCommand::Failure.new(value, err: error, meta: meta)
+      raise HatiCommand::Errors::FailFastError.new('Fail Fast Triggered', err_obj: err_obj)
+    end
+  end
+end

data/lib/hati_command/errors/fail_fast_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module HatiCommand
+  module Errors
+    # Custom error class for fail-fast scenarios in HatiCommand
+    #
+    # @example Raising a FailFastError with a message
+    #   raise HatiCommand::FailFastError.new("Operation failed")
+    #
+    # @example Raising a FailFastError with a message and error object
+    #   begin
+    #     # Some operation that might fail
+    #   rescue StandardError => e
+    #     raise HatiCommand::FailFastError.new("Operation failed", err_obj: e)
+    #   end
+    class FailFastError < StandardError
+      # @return [Object] The associated error object
+      attr_reader :err_obj
+
+      # Initialize a new FailFastError
+      #
+      # @param message [String] The error message
+      # @param err_obj [Object] An optional error object associated with this error
+      def initialize(message, err_obj: nil)
+        super(message)
+        @err_obj = err_obj
+      end
+    end
+  end
+end

data/lib/hati_command/failure.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# @module HatiCommand
+# Provides command handling functionalities and result objects.
+module HatiCommand
+  # @class Failure
+  # Represents a failure result in the Result pattern.
+  # This class is used to wrap failure values and provide a consistent interface
+  # for handling both successful and failed operations.
+  #
+  # The Failure class is part of the Result pattern implementation, working alongside
+  # the Success class to provide a type-safe way to handle operation outcomes.
+  #
+  # @example Basic usage
+  #   failure = HatiCommand::Failure.new("Operation failed")
+  #   failure.failure?  # => true
+  #   failure.success?  # => false
+  #
+  # @example With error and metadata
+  #   error = StandardError.new("Database connection failed")
+  #   failure = HatiCommand::Failure.new(
+  #     "Could not save record",
+  #     err: error,
+  #     meta: { attempted_at: Time.now }
+  #   )
+  #
+  # @example Pattern matching
+  #   case result
+  #   when HatiCommand::Failure
+  #     handle_error(result.failure)
+  #   end
+  #
+  # @see HatiCommand::Success
+  # @see HatiCommand::Result
+  class Failure < Result
+    # Returns the failure value wrapped by this Failure instance.
+    # This method provides access to the actual error value or message
+    # that describes why the operation failed.
+    #
+    # @return [Object] The wrapped failure value
+    # @example
+    #   failure = Failure.new("Database error")
+    #   failure.failure  # => "Database error"
+    def failure
+      value
+    end
+
+    # Indicates that this is a failure result.
+    # This method is part of the Result pattern interface and always
+    # returns true for Failure instances.
+    #
+    # @return [Boolean] Always returns true
+    # @example
+    #   failure = Failure.new("Error")
+    #   failure.failure?  # => true
+    def failure?
+      true
+    end
+
+    # Returns nil since a Failure has no success value.
+    # This method is part of the Result pattern interface and always
+    # returns nil for Failure instances.
+    #
+    # @return [nil] Always returns nil
+    # @example
+    #   failure = Failure.new("Error")
+    #   failure.success  # => nil
+    def success
+      nil
+    end
+
+    # Indicates that this is not a success result.
+    # This method is part of the Result pattern interface and always
+    # returns false for Failure instances.
+    #
+    # @return [Boolean] Always returns false
+    # @example
+    #   failure = Failure.new("Error")
+    #   failure.success?  # => false
+    def success?
+      false
+    end
+
+    # Returns the symbolic representation of this result type.
+    # Useful for pattern matching and result type checking.
+    #
+    # @return [Symbol] Always returns :failure
+    # @api public
+    # @example
+    #   failure = Failure.new("Error")
+    #   failure.to_sym  # => :failure
+    def to_sym
+      :failure
+    end
+  end
+end

data/lib/hati_command/result.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+# @module HatiCommand
+# Provides command handling functionalities and result objects.
+module HatiCommand
+  # @class Result
+  # Base class for the Result pattern implementation.
+  # This class serves as the foundation for Success and Failure result types,
+  # providing common functionality and a consistent interface for handling
+  # operation outcomes.
+  #
+  # The Result pattern helps in handling operation outcomes in a type-safe way,
+  # making it explicit whether an operation succeeded or failed, and carrying
+  # additional context like error messages and metadata.
+  #
+  # @abstract Subclass and override {#to_sym} to implement a concrete result type
+  #
+  # @example Basic usage
+  #   result = HatiCommand::Result.new("Operation output")
+  #   result.value  # => "Operation output"
+  #
+  # @example With error and metadata
+  #   result = HatiCommand::Result.new(
+  #     "Operation output",
+  #     err: "Warning: partial completion",
+  #     meta: { duration_ms: 150 }
+  #   )
+  #
+  # @example Using trace information
+  #   result = HatiCommand::Result.new("Output", trace: caller(1..1))
+  #   result.trace  # => ["path/to/file.rb:42:in `method_name'"]
+  #
+  # @see HatiCommand::Success
+  # @see HatiCommand::Failure
+  #
+  # @!attribute [r] value
+  #   @return [Object] The wrapped value representing the operation's output
+  #
+  # @!attribute [r] meta
+  #   @return [Hash] Additional metadata associated with the result
+  #
+  # @!attribute [rw] trace
+  #   @return [Array<String>, nil] Execution trace information for debugging
+  class Result
+    attr_reader :value, :meta
+    attr_accessor :trace
+
+    # Initializes a new Result instance with a value and optional context.
+    #
+    # @param value [Object] The value to be wrapped in the result
+    # @param err [String, nil] Optional error message or error object
+    # @param meta [Hash] Optional metadata for additional context
+    # @param trace [Array<String>, nil] Optional execution trace for debugging
+    #
+    # @example Basic initialization
+    #   result = Result.new("Success")
+    #
+    # @example With full context
+    #   result = Result.new(
+    #     "Partial success",
+    #     err: "Some records failed",
+    #     meta: { processed: 10, failed: 2 },
+    #     trace: caller
+    #   )
+    def initialize(value, err: nil, meta: {}, trace: nil)
+      @value = value
+      @err = err
+      @meta = meta
+      @trace = trace
+    end
+
+    # Returns self to provide a consistent interface across result types.
+    # This method ensures that all result objects can be treated uniformly
+    # when chaining operations.
+    #
+    # @return [HatiCommand::Result] The result instance itself
+    # @api public
+    def result
+      self
+    end
+
+    # Returns the error associated with this result.
+    # This can be used to check for warnings or errors even in successful results.
+    #
+    # @return [String, nil] The error message or object, if any
+    # @raise [StandardError] If accessing the error triggers an error condition
+    # @api public
+    # @example
+    #   result = Result.new("Value", err: "Warning message")
+    #   result.error  # => "Warning message"
+    def error
+      @err
+    end
+
+    # Returns the symbolic representation of this result type.
+    # This is an abstract method that should be overridden by concrete result types.
+    #
+    # @return [Symbol] Returns :undefined for the base class
+    # @abstract Subclasses must override this method
+    # @api public
+    # @example
+    #   Result.new("value").to_sym  # => :undefined
+    def to_sym
+      :undefined
+    end
+  end
+end

data/lib/hati_command/success.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# @module HatiCommand
+# Provides command handling functionalities and result objects.
+module HatiCommand
+  # @class Success
+  # Represents a successful result in the Result pattern.
+  # This class is used to wrap successful operation values and provide a consistent interface
+  # for handling both successful and failed operations.
+  #
+  # The Success class is part of the Result pattern implementation, working alongside
+  # the Failure class to provide a type-safe way to handle operation outcomes.
+  #
+  # @example Basic usage
+  #   success = HatiCommand::Success.new("Operation completed")
+  #   success.success?  # => true
+  #   success.failure?  # => false
+  #
+  # @example With metadata
+  #   success = HatiCommand::Success.new(
+  #     { id: 123, name: "Example" },
+  #     meta: { duration_ms: 50 }
+  #   )
+  #   success.success  # => { id: 123, name: "Example" }
+  #
+  # @example Pattern matching
+  #   case result
+  #   when HatiCommand::Success
+  #     process_data(result.success)
+  #   end
+  #
+  # @see HatiCommand::Failure
+  # @see HatiCommand::Result
+  class Success < Result
+    # Returns the success value wrapped by this Success instance.
+    # This method provides access to the actual value or result
+    # that was produced by the successful operation.
+    #
+    # @return [Object] The wrapped success value
+    # @example
+    #   success = Success.new("Operation output")
+    #   success.success  # => "Operation output"
+    def success
+      value
+    end
+
+    # Indicates that this is a success result.
+    # This method is part of the Result pattern interface and always
+    # returns true for Success instances.
+    #
+    # @return [Boolean] Always returns true
+    # @example
+    #   success = Success.new("Result")
+    #   success.success?  # => true
+    def success?
+      true
+    end
+
+    # Returns nil since a Success has no failure value.
+    # This method is part of the Result pattern interface and always
+    # returns nil for Success instances.
+    #
+    # @return [nil] Always returns nil
+    # @example
+    #   success = Success.new("Result")
+    #   success.failure  # => nil
+    def failure
+      nil
+    end
+
+    # Indicates that this is not a failure result.
+    # This method is part of the Result pattern interface and always
+    # returns false for Success instances.
+    #
+    # @return [Boolean] Always returns false
+    # @example
+    #   success = Success.new("Result")
+    #   success.failure?  # => false
+    def failure?
+      false
+    end
+
+    # Returns the symbolic representation of this result type.
+    # Useful for pattern matching and result type checking.
+    #
+    # @return [Symbol] Always returns :success
+    # @api public
+    # @example
+    #   success = Success.new("Result")
+    #   success.to_sym  # => :success
+    def to_sym
+      :success
+    end
+  end
+end

data/lib/hati_command/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HatiCommand
+  VERSION = '0.1.0.beta1'
+end

data/lib/hati_command.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'hati_command/version'
+# errors
+require 'hati_command/errors/fail_fast_error'
+# result
+require 'hati_command/result'
+require 'hati_command/success'
+require 'hati_command/failure'
+# core
+require 'hati_command/callee'
+require 'hati_command/befehl'
+require 'hati_command/cmd'

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: hati-command
+version: !ruby/object:Gem::Version
+  version: 0.1.0.beta1
+platform: ruby
+authors:
+- yurigitsu
+- MarieGiy
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-06-14 00:00:00.000000000 Z
+dependencies: []
+description: hati-command is a Ruby gem for implementing the Command pattern with
+  result handling.
+email:
+- yurigi.pro@gmail.com
+- giy.mariya@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- hati-command.gemspec
+- lib/hati_command.rb
+- lib/hati_command/befehl.rb
+- lib/hati_command/callee.rb
+- lib/hati_command/cmd.rb
+- lib/hati_command/errors/fail_fast_error.rb
+- lib/hati_command/failure.rb
+- lib/hati_command/result.rb
+- lib/hati_command/success.rb
+- lib/hati_command/version.rb
+homepage: https://github.com/hackico-ai/hati-command
+licenses:
+- MIT
+metadata:
+  repo_homepage: https://github.com/hackico-ai/hati-command
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/hackico-ai/hati-command
+  changelog_uri: https://github.com/hackico-ai/hati-command/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/hackico-ai/hati-command
+  bug_tracker_uri: https://github.com/hackico-ai/hati-command/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A Ruby gem for creating command objects with result handling.
+test_files: []