cmdx 0.5.0 → 1.0.1

data/docs/interruptions/halt.md

@@ -1,80 +1,233 @@
 # Interruptions - Halt
 
-Halting stops execution of a task. Halt methods signal the intent as to why a task
-is stopped executing.
+Halting stops execution of a task with explicit intent signaling. Tasks provide
+two primary halt methods that control execution flow and result in different
+outcomes, each serving specific use cases in business logic.
 
-## Skip
+## Table of Contents
 
-The `skip!` method indicates that a task did not meet the criteria to continue execution.
+- [TLDR](#tldr)
+- [Skip (`skip!`)](#skip-skip)
+- [Fail (`fail!`)](#fail-fail)
+- [Metadata Enrichment](#metadata-enrichment)
+- [State Transitions](#state-transitions)
+- [Exception Behavior](#exception-behavior)
+- [The Reason Key](#the-reason-key)
+
+## TLDR
+
+- **`skip!`** - Controlled interruption when task shouldn't execute (not an error)
+- **`fail!`** - Controlled interruption when task encounters an error condition
+- **Metadata** - Both methods accept metadata hash: `skip!(reason: "...", error_code: "...")`
+- **State changes** - Both transition to `interrupted` state, `skipped` or `failed` status
+- **Exception behavior** - `call` returns results, `call!` raises `CMDx::Skipped/Failed` based on task_halt config
+
+## Skip (`skip!`)
+
+The `skip!` method indicates that a task did not meet the criteria to continue
+execution. This represents a controlled, intentional interruption where the
+task determines that execution is not necessary or appropriate under current
+conditions.
+
+### Basic Usage
 
 ```ruby
-class ProcessOrderTask < CMDx::Task
+class ProcessUserOrderTask < CMDx::Task
 
   def call
-    skip! if cart_abandoned?
+    context.order = Order.find(context.order_id)
+
+    # Skip if order is already processed
+    skip!(reason: "Order already processed") if context.order.processed?
 
-    # Do work...
+    # Skip if prerequisites aren't met
+    skip!(reason: "Payment method not configured") unless context.order.payment_method
+
+    # Continue with business logic
+    context.order.process!
   end
 
 end
 ```
 
-## Fail
+> [!NOTE]
+> Use `skip!` when a task cannot or should not execute under current conditions, but this is not an error. Skipped tasks are considered successful outcomes.
+
+## Fail (`fail!`)
+
+The `fail!` method indicates that a task encountered an error condition that
+prevents successful completion. This represents controlled failure where the
+task explicitly determines that execution cannot continue successfully.
 
-The `fail!` method indicates that a task met with incomplete, broken, or failed logic.
+### Basic Usage
 
 ```ruby
-class ProcessOrderTask < CMDx::Task
+class ProcessOrderPaymentTask < CMDx::Task
 
   def call
-    fail! if cart_items_out_of_stock?
+    context.payment = Payment.find(context.payment_id)
 
-    # Do work...
+    # Fail on validation errors
+    fail!(reason: "Payment amount must be positive") unless context.payment.amount > 0
+
+    # Fail on business rule violations
+    fail!(reason: "Insufficient funds") unless sufficient_funds?
+
+    # Continue with processing
+    process_payment
   end
 
 end
 ```
 
-## Metadata
+> [!IMPORTANT]
+> Use `fail!` when a task encounters an error that prevents successful completion. Failed tasks represent error conditions that need to be handled or corrected.
+
+## Metadata Enrichment
 
-Pass metadata to enrich faults with additional contextual information. Metadata requires
-that it be passed as a hash object. Internal failures will hydrate metadata into its result,
-eg: failed validations and unrescued exceptions.
+Both halt methods accept metadata to provide context about the interruption.
+Metadata is stored as a hash and becomes available through the result object.
+
+### Structured Metadata
 
 ```ruby
-class ProcessOrderTask < CMDx::Task
+class ProcessUserOrderTask < CMDx::Task
 
   def call
-    if cart_abandoned?
-      skip!(reason: "Cart was abandoned due to 30 days of inactivity")
-    elsif cart_items_out_of_stock?
-      fail!(reason: "Items in the cart are out of stock", item: [123, 987])
-    else
-      # Do work...
+    context.order = Order.find(context.order_id)
+
+    if context.order.status == "cancelled"
+      skip!(
+        reason: "Order was cancelled",
+        order_id: context.order.id,
+        cancelled_at: context.order.cancelled_at,
+        reason_code: context.order.cancellation_reason
+      )
+    end
+
+    unless inventory_available?
+      fail!(
+        reason: "Insufficient inventory",
+        required_quantity: context.order.quantity,
+        available_quantity: current_inventory,
+        restock_date: estimated_restock_date,
+        error_code: "INVENTORY_DEPLETED"
+      )
     end
+
+    process_order
   end
 
 end
+```
+
+### Accessing Metadata
+
+```ruby
+result = ProcessUserOrderTask.call(order_id: 123)
+
+# Check result status
+result.skipped?                #=> true
+result.failed?                 #=> false
+
+# Access metadata
+result.metadata[:reason]       #=> "Order was cancelled"
+result.metadata[:order_id]     #=> 123
+result.metadata[:cancelled_at] #=> 2023-01-01 10:00:00 UTC
+result.metadata[:reason_code]  #=> "customer_request"
+```
+
+## State Transitions
+
+Halt methods trigger specific state and status transitions:
+
+### Skip Transitions
+- **State**: `initialized` → `executing` → `interrupted`
+- **Status**: `success` → `skipped`
+- **Result**: `good? = true`, `bad? = true`
+
+### Fail Transitions
+- **State**: `initialized` → `executing` → `interrupted`
+- **Status**: `success` → `failed`
+- **Result**: `good? = false`, `bad? = true`
+
+```ruby
+result = ProcessUserOrderTask.call(order_id: 123)
+
+# State information
+result.state        #=> "interrupted"
+result.status       #=> "skipped" or "failed"
+result.interrupted? #=> true
+result.complete?    #=> false
+
+# Outcome categorization
+result.good?        #=> true for skipped, false for failed
+result.bad?         #=> true for both skipped and failed
+```
+
+## Exception Behavior
+
+Halt methods behave differently depending on the call method used:
+
+### With `call` (Non-bang)
+Returns a result object without raising exceptions:
+
+```ruby
+result = ProcessUserOrderTask.call(order_id: 123)
+
+case result.status
+when "success"
+  puts "Order processed successfully"
+when "skipped"
+  puts "Order skipped: #{result.metadata[:reason]}"
+when "failed"
+  puts "Order failed: #{result.metadata[:reason]}"
+end
+```
+
+### With `call!` (Bang)
+Raises fault exceptions based on `task_halt` configuration:
 
-result = ProcessOrderTask.call
-result.metadata #=> { reason: "Items in the cart are out of stock", item: [123, 987] }
+```ruby
+begin
+  result = ProcessUserOrderTask.call!(order_id: 123)
+  puts "Success: #{result.context.order.id}"
+rescue CMDx::Skipped => e
+  puts "Skipped: #{e.message}"
+  puts "Order ID: #{e.context.order_id}"
+rescue CMDx::Failed => e
+  puts "Failed: #{e.message}"
+  puts "Error code: #{e.result.metadata[:error_code]}"
+end
 ```
 
-> [!Important]
-> The `:reason` key is used to define the fault exception message. While not
-> required, it is strongly recommended that it is used on every halt method.
+> [!WARNING]
+> The `call!` method raises exceptions for halt conditions based on the `task_halt` configuration. The `call` method always returns result objects without raising exceptions.
+
+## The Reason Key
 
-## Results
+The `:reason` key in metadata has special significance:
 
-The following represents a result output example of a halted task.
+- Used as the exception message when faults are raised
+- Provides human-readable explanation of the halt
+- Strongly recommended for all halt calls
 
 ```ruby
-result = ProcessOrderTask.call
-result.status   #=> "failed"
-result.metadata #=> { reason: "Cart was abandoned due to 30 days of inactivity" }
+# Good: Provides clear reason
+skip!(reason: "User already has an active session")
+fail!(reason: "Credit card expired", code: "EXPIRED_CARD")
+
+# Acceptable: Other metadata without reason
+skip!(status: "redundant", timestamp: Time.now)
+
+# Fallback: Default message if no reason provided
+skip! # Exception message: "no reason given"
 ```
 
+> [!TIP]
+> Always try to include a `:reason` key in metadata when using halt methods. This provides clear context for debugging and creates meaningful exception messages when using `call!`.
+
 ---
 
-- **Prev:** [Basics - Run](https://github.com/drexed/cmdx/blob/main/docs/basics/run.md)
-- **Next:** [Interruptions - Faults](https://github.com/drexed/cmdx/blob/main/docs/interruptions/faults.md)
+- **Prev:** [Basics - Chain](../basics/chain.md)
+- **Next:** [Interruptions - Faults](faults.md)

data/docs/logging.md

@@ -1,104 +1,255 @@
 # Logging
 
-Tasks log the result object after execution. Multi-threaded systems will have many
-tasks executing concurrently so `CMDx` uses a custom logger to make debugging easier.
-
-## Output
-
-Built-in log formatters are:
-- Standard: `Line`, `Json`, `KeyValue`, `Logstash`, `Raw`
-- Stylized: `PrettyLine` (default), `PrettyJson`, `PrettyKeyValue`
-
-#### Success:
-```txt
-I, [2022-07-17T18:43:15.000000 #3784] INFO -- SimulationTask: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=complete status=success outcome=success metadata={} runtime=0 origin=CMDx
-```
-
-#### Skipped:
+CMDx provides comprehensive automatic logging for task execution with structured data, customizable formatters, and intelligent severity mapping. All task results are logged after completion with rich metadata for debugging and monitoring.
+
+## Table of Contents
+- [TLDR](#tldr)
+- [Log Formatters](#log-formatters)
+  - [Standard Formatters](#standard-formatters)
+  - [Stylized Formatters (ANSI Colors)](#stylized-formatters-ansi-colors)
+- [Sample Output](#sample-output)
+  - [Success Result](#success-result)
+  - [Skipped Result](#skipped-result)
+  - [Failed Result](#failed-result)
+  - [Failure Chain (Workflow Workflows)](#failure-chain-workflow-workflows)
+- [Configuration](#configuration)
+  - [Global Configuration](#global-configuration)
+  - [Task-Specific Configuration](#task-specific-configuration)
+  - [Environment-Specific Configuration](#environment-specific-configuration)
+- [Severity Mapping](#severity-mapping)
+- [Manual Logging](#manual-logging)
+- [Advanced Formatter Usage](#advanced-formatter-usage)
+  - [Custom Formatter](#custom-formatter)
+  - [Multi-Destination Logging](#multi-destination-logging)
+- [Log Data Structure](#log-data-structure)
+
+## TLDR
+
+- **Automatic logging** - All task results logged after completion with structured data
+- **8 formatters** - Standard (Line, Json, KeyValue, Logstash, Raw) and Stylized (Pretty variants)
+- **Configuration** - Global via `CMDx.configure` or task-specific via `task_settings!`
+- **Severity mapping** - Success=INFO, Skipped=WARN, Failed=ERROR
+- **Rich metadata** - Includes runtime, chain_id, status, context, and failure chains
+- **Manual logging** - Access `logger` within tasks for custom messages
+
+## Log Formatters
+
+CMDx provides 8 built-in log formatters organized into standard and stylized categories:
+
+### Standard Formatters
+- **`Line`** - Traditional single-line format similar to Ruby's Logger
+- **`Json`** - Compact single-line JSON for structured logging systems
+- **`KeyValue`** - Space-separated key=value pairs for easy parsing
+- **`Logstash`** - ELK stack compatible JSON with @version and @timestamp fields
+- **`Raw`** - Minimal output containing only the message content
+
+### Stylized Formatters (ANSI Colors)
+
+> [!NOTE]
+> Stylized formatters include ANSI color codes for terminal readability and are best suited for development environments.
+
+- **`PrettyLine`** - Colorized line format (default)
+- **`PrettyJson`** - Human-readable multi-line JSON with syntax highlighting
+- **`PrettyKeyValue`** - Colorized key=value pairs for terminal readability
+
+## Sample Output
+
+### Success Result
 ```txt
-W, [2022-07-17T18:43:15.000000 #3784] WARN -- SimulationTask: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=interrupted status=skipped outcome=skipped metadata={} runtime=0 origin=CMDx
+I, [2022-07-17T18:43:15.000000 #3784] INFO -- CreateOrderTask: index=0 chain_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=CreateOrderTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=complete status=success outcome=success metadata={order_id: 123, confirmation: "ABC123"} runtime=0.45 origin=CMDx
 ```
 
-#### Failed:
+### Skipped Result
 ```txt
-E, [2022-07-17T18:43:15.000000 #3784] ERROR -- SimulationTask: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=interrupted status=failed outcome=failed metadata={} runtime=0 origin=CMDx
+W, [2022-07-17T18:43:15.000000 #3784] WARN -- ValidatePaymentTask: index=0 chain_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=ValidatePaymentTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=interrupted status=skipped outcome=skipped metadata={reason: "Order already processed"} runtime=0.02 origin=CMDx
 ```
 
-#### Level 1 subtask failure:
+### Failed Result
 ```txt
-E, [2022-07-17T18:43:15.000000 #3784] ERROR -- SimulationTask: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=interrupted status=failed outcome=interrupted metadata={} runtime=0 caused_failure={index: 1, run_id: "018c2b95-b764-7615-a924-cc5b910ed1e5", type: "Task", class: "SimulationTask", id: "018c2b95-b764-7615-a924-cc5b910ed1e5", tags: [], state: "interrupted", status: "failed", outcome: "failed", metadata: {}, runtime: 0} threw_failure={index: 1, run_id: "018c2b95-b764-7615-a924-cc5b910ed1e5", type: "Task", class: "SimulationTask", id: "018c2b95-b764-7615-a924-cc5b910ed1e5", tags: [], state: "interrupted", status: "failed", outcome: "failed", metadata: {}, runtime: 0} origin=CMDx
+E, [2022-07-17T18:43:15.000000 #3784] ERROR -- ProcessPaymentTask: index=0 chain_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=ProcessPaymentTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=interrupted status=failed outcome=failed metadata={reason: "Payment declined", error_code: "INSUFFICIENT_FUNDS"} runtime=0.15 origin=CMDx
 ```
 
-#### Level 2+ subtask failure:
+### Failure Chain (Workflow Workflows)
 ```txt
-E, [2022-07-17T18:43:15.000000 #3784] ERROR -- SimulationTask: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=interrupted status=failed outcome=interrupted metadata={} runtime=0 caused_failure={index: 2, run_id: "018c2b95-b764-7615-a924-cc5b910ed1e5", type: "Task", class: "SimulationTask", id: "018c2b95-b764-7615-a924-cc5b910ed1e5", tags: [], state: "interrupted", status: "failed", outcome: "failed", metadata: {}, runtime: 0} threw_failure={index: 1, run_id: "018c2b95-b764-7615-a924-cc5b910ed1e5", type: "Task", class: "SimulationTask", id: "018c2b95-b764-7615-a924-cc5b910ed1e5", tags: [], state: "interrupted", status: "failed", outcome: "interrupted", metadata: {}, runtime: 0} origin=CMDx
+E, [2022-07-17T18:43:15.000000 #3784] ERROR -- OrderCreationWorkflow: index=0 chain_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Workflow class=OrderCreationWorkflow id=018c2b95-b764-7615-a924-cc5b910ed1e5 tags=[] state=interrupted status=failed outcome=interrupted metadata={} runtime=0.75 caused_failure={index: 2, class: "ValidatePaymentTask", status: "failed"} threw_failure={index: 1, class: "ProcessPaymentTask", status: "failed"} origin=CMDx
 ```
 
-## Logger
+## Configuration
 
-CMDx defaults to using Ruby's standard library Logger. Log levels thus follow the
-[stdlib documentation](http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger.html).
+### Global Configuration
 
-#### Global settings:
+Configure logging globally in your CMDx initializer:
 
 ```ruby
 CMDx.configure do |config|
-  # Single declaration:
-  config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::Line.new, level: Logger::DEBUG)
-
-  # Multiline declarations:
-  config.logger           = Rails.logger
-  config.logger.formatter = CMDx::LogFormatters::Line.new
-  config.logger.level     = Logger::WARN
+  config.logger = Logger.new("log/cmdx.log", formatter: CMDx::LogFormatters::Json.new)
+  config.logger.level = Logger::INFO
 end
 ```
 
-#### Task settings:
+### Task-Specific Configuration
 
-```ruby
-class ProcessOrderTask < CMDx::Task
+Override logging settings for individual tasks:
 
-  task_settings!(logger: Rails.logger, log_format: CMDx::LogFormatters::Logstash.new, log_level: Logger::WARN)
+```ruby
+class SendEmailTask < CMDx::Task
+  task_settings!(
+    logger: Rails.logger,
+    log_formatter: CMDx::LogFormatters::Json.new,
+    log_level: Logger::WARN
+  )
 
   def call
-    # Do work...
+    # Task implementation
   end
+end
 
+# Base class with shared logging configuration
+class ApplicationTask < CMDx::Task
+  task_settings!(
+    logger: Logger.new("log/tasks.log"),
+    log_formatter: CMDx::LogFormatters::Logstash.new,
+    log_level: Logger::INFO
+  )
 end
 ```
 
-> [!TIP]
-> In production environments, a log level of DEBUG may be too verbose for your needs.
-> For quieter logs that use less disk space, you can change the log level to only show INFO and higher.
+## Severity Mapping
+
+> [!IMPORTANT]
+> CMDx automatically maps result statuses to appropriate log severity levels. Manual log level overrides are not recommended.
+
+| Result Status | Log Level | Use Case |
+| ------------- | --------- | -------- |
+| `success`     | `INFO`    | Normal successful completion |
+| `skipped`     | `WARN`    | Intentional skip (business logic) |
+| `failed`      | `ERROR`   | Task failure or exception |
 
-## Write to log
+## Manual Logging
 
-Write to log via the `logger` method.
+Access the configured logger within tasks for custom log messages:
 
 ```ruby
 class ProcessOrderTask < CMDx::Task
-
   def call
-    logger.info "Processing order"
-    logger.debug { context.to_h }
+    logger.info "Starting order processing", order_id: context.order_id
+
+    # Performance-optimized debug logging
+    logger.debug { "Order details: #{context.order.inspect}" }
+
+    # Structured logging
+    logger.info "Payment processed", {
+      order_id: context.order_id,
+      amount: context.order.total,
+      payment_method: context.payment_method
+    }
+
+    # Exception handling with logging
+    begin
+      validate_inventory
+    rescue StandardError => e
+      logger.error "Inventory validation failed: #{e.message}", {
+        exception: e.class.name,
+        order_id: context.order_id
+      }
+      raise
+    end
   end
-
 end
 ```
 
-## Output format
+## Advanced Formatter Usage
 
-Define a custom log formatter to match your expected output, for example one that changes the JSON keys:
+### Custom Formatter
+
+Create custom formatters for specific output requirements:
 
 ```ruby
-class CustomCmdxLogFormat
+class SlackLogFormatter
   def call(severity, time, task, message)
-    # Return string, hash, array, etc to output...
+    emoji = case severity
+            when 'INFO' then '✅'
+            when 'WARN' then '⚠️'
+            when 'ERROR' then '❌'
+            else '📝'
+            end
+
+    "#{emoji} #{task.class.name}: #{message}\n"
+  end
+end
+
+class SendNotificationTask < CMDx::Task
+  task_settings!(
+    logger: Logger.new("log/notifications.log", formatter: SlackLogFormatter.new)
+  )
+end
+```
+
+### Multi-Destination Logging
+
+> [!TIP]
+> Use multi-destination logging to send output to both console and files simultaneously during development.
+
+```ruby
+class MultiLogger
+  def initialize(*loggers)
+    @loggers = loggers
+  end
+
+  %w[debug info warn error fatal].each do |level|
+    define_method(level) do |message = nil, &block|
+      @loggers.each { |logger| logger.send(level, message, &block) }
+    end
+  end
+
+  def formatter=(formatter)
+    @loggers.each { |logger| logger.formatter = formatter }
+  end
+
+  def level=(level)
+    @loggers.each { |logger| logger.level = level }
   end
 end
+
+# Usage
+CMDx.configure do |config|
+  config.logger = MultiLogger.new(
+    Logger.new(STDOUT, formatter: CMDx::LogFormatters::PrettyLine.new),
+    Logger.new("log/cmdx.log", formatter: CMDx::LogFormatters::Json.new)
+  )
+end
 ```
 
+## Log Data Structure
+
+CMDx logs contain comprehensive execution metadata:
+
+#### Standard Fields
+- `severity` - Log level (INFO, WARN, ERROR)
+- `pid` - Process ID for multi-process debugging
+- `timestamp` - ISO 8601 formatted execution time
+- `origin` - Always "CMDx" for filtering
+
+#### Task Identification
+- `index` - Position in execution sequence
+- `chain_id` - Unique identifier for execution chain
+- `type` - Task or Workflow
+- `class` - Task class name
+- `id` - Unique task instance identifier
+- `tags` - Custom tags for categorization
+
+#### Execution Information
+- `state` - Execution lifecycle state (initialized, executing, complete, interrupted)
+- `status` - Business logic outcome (success, skipped, failed)
+- `outcome` - Final result classification
+- `metadata` - Custom data from skip!/fail! calls
+- `runtime` - Execution time in seconds
+
+#### Failure Chain (Complex Workflows)
+- `caused_failure` - Original failing task information
+- `threw_failure` - Task that propagated the failure
+
 ---
 
-- **Prev:** [Batch](https://github.com/drexed/cmdx/blob/main/docs/batch.md)
-- **Next:** [Tips & Tricks](https://github.com/drexed/cmdx/blob/main/docs/tips_and_tricks.md)
+- **Prev:** [Workflows](workflows.md)
+- **Next:** [Internationalization (i18n)](internationalization.md)