anzen 0.1.0

data/lib/anzen/cli.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module Anzen
+  # Command-line interface for Anzen safety monitoring
+  #
+  # Provides operator-facing commands to query protection status,
+  # configuration, and monitor state without code changes.
+  #
+  # @api public
+  class CLI
+    # Display current protection configuration and monitor state
+    #
+    # @param format [Symbol] Output format (:json or :text)
+    # @return [String] Formatted output
+    # @api public
+    def status(format: :text)
+      status_data = Anzen.status
+
+      case format
+      when :json
+        JSON.pretty_generate(status_data)
+      when :text
+        format_status_text(status_data)
+      else
+        raise ArgumentError, "Invalid format: #{format}. Use :json or :text"
+      end
+    end
+
+    # Display detailed configuration for all monitors or specific monitor
+    #
+    # @param monitor_name [String, nil] Specific monitor name, or nil for all
+    # @param format [Symbol] Output format (:json or :text)
+    # @return [String] Formatted output
+    # @api public
+    def config(monitor_name: nil, format: :text)
+      if monitor_name
+        monitor_config = get_monitor_config(monitor_name)
+        case format
+        when :json
+          JSON.pretty_generate(monitor_config)
+        when :text
+          format_monitor_config_text(monitor_name, monitor_config)
+        else
+          raise ArgumentError, "Invalid format: #{format}. Use :json or :text"
+        end
+      else
+        all_configs = get_all_configs
+        case format
+        when :json
+          JSON.pretty_generate(all_configs)
+        when :text
+          format_all_configs_text(all_configs)
+        else
+          raise ArgumentError, "Invalid format: #{format}. Use :json or :text"
+        end
+      end
+    end
+
+    # Display general information about the Anzen gem installation
+    #
+    # @param format [Symbol] Output format (:json or :text)
+    # @return [String] Formatted output
+    # @api public
+    def info(format: :text)
+      info_data = {
+        name: 'anzen',
+        version: Anzen::VERSION,
+        ruby_version: RUBY_VERSION,
+        platform: RUBY_PLATFORM,
+        monitors_available: %w[recursion memory],
+        license: 'MIT',
+        documentation_url: 'https://github.com/[org]/anzen'
+      }
+
+      case format
+      when :json
+        JSON.pretty_generate(info_data)
+      when :text
+        format_info_text(info_data)
+      else
+        raise ArgumentError, "Invalid format: #{format}. Use :json or :text"
+      end
+    end
+
+    # Display help documentation and command reference
+    #
+    # @param command [String, nil] Specific command name, or nil for general help
+    # @return [String] Help text
+    # @api public
+    def help(command: nil)
+      if command
+        format_command_help(command)
+      else
+        format_general_help
+      end
+    end
+
+    private
+
+    def get_monitor_config(monitor_name)
+      status_data = Anzen.status
+      monitor = status_data[:monitors].find { |m| m[:name] == monitor_name }
+
+      unless monitor
+        available = status_data[:monitors].map { |m| m[:name] }
+        raise Anzen::MonitorNotFoundError.new(monitor_name)
+      end
+
+      {
+        monitor: monitor_name,
+        enabled: monitor[:enabled],
+        config: monitor[:thresholds]
+      }
+    end
+
+    def get_all_configs
+      status_data = Anzen.status
+      {
+        monitors: status_data[:monitors].each_with_object({}) do |monitor, hash|
+          hash[monitor[:name]] = {
+            enabled: monitor[:enabled],
+            config: monitor[:thresholds]
+          }
+        end
+      }
+    end
+
+    def format_status_text(status_data)
+      output = []
+      output << 'Anzen Safety Protection Status'
+      output << ('=' * 40)
+      output << ''
+      output << "Enabled Monitors: #{status_data[:enabled].join(", ")}"
+      output << ''
+
+      status_data[:monitors].each do |monitor|
+        output << "Monitor: #{monitor[:name]}"
+        output << "  Status: #{monitor[:enabled] ? "enabled" : "disabled"}"
+        output << '  Thresholds:'
+
+        monitor[:thresholds].each do |key, value|
+          output << "    #{key}: #{value}"
+        end
+
+        last_check = monitor[:last_check]
+        output << if last_check
+                    "  Last Check: #{last_check.strftime("%Y-%m-%d %H:%M:%S %Z")}"
+                  else
+                    '  Last Check: never'
+                  end
+
+        output << "  Violations Detected: #{monitor[:violations]}"
+        output << ''
+      end
+
+      output << "Total Violations: #{status_data[:violations_total]}"
+      output << "Setup Time: #{status_data[:setup_at].strftime("%Y-%m-%d %H:%M:%S %Z")}"
+
+      output.join("\n")
+    end
+
+    def format_monitor_config_text(monitor_name, config)
+      output = []
+      output << "Monitor: #{monitor_name}"
+      output << "  Enabled: #{config[:enabled] ? "yes" : "no"}"
+      output << '  Configuration:'
+
+      config[:config].each do |key, value|
+        output << "    #{key}: #{value}"
+      end
+
+      output.join("\n")
+    end
+
+    def format_all_configs_text(configs)
+      output = []
+      output << 'Anzen Configuration'
+      output << ('=' * 20)
+      output << ''
+
+      configs[:monitors].each do |name, config|
+        output << "Monitor: #{name}"
+        output << "  Enabled: #{config[:enabled] ? "yes" : "no"}"
+        output << '  Configuration:'
+
+        config[:config].each do |key, value|
+          output << "    #{key}: #{value}"
+        end
+
+        output << ''
+      end
+
+      output.join("\n")
+    end
+
+    def format_info_text(info_data)
+      output = []
+      output << 'Anzen Gem Information'
+      output << ('=' * 25)
+      output << ''
+      output << "Version: #{info_data[:version]}"
+      output << "Installed Location: #{Gem.loaded_specs["anzen"]&.full_gem_path || "Not installed as gem"}"
+      output << "Ruby Version: #{info_data[:ruby_version]}"
+      output << "Platform: #{info_data[:platform]}"
+      output << "Available Monitors: #{info_data[:monitors_available].join(", ")}"
+      output << "License: #{info_data[:license]}"
+      output << "Documentation: #{info_data[:documentation_url]}"
+
+      output.join("\n")
+    end
+
+    def format_general_help
+      <<~HELP
+        Anzen Safety Protection - Command Line Interface
+
+        Usage: anzen [command] [options]
+
+        Commands:
+          status        Display protection status and monitor state
+          config        Display monitor configuration details
+          info          Display gem installation information
+          help          Show this help message
+
+        Options:
+          --format      Output format: json, text (default: text)
+          --help        Show command help
+          -v, --version Show gem version
+
+        Examples:
+          anzen status                    # Show status
+          anzen config memory --format json  # Show memory config as JSON
+          anzen info                      # Show gem info
+
+        For more information, see: https://github.com/[org]/anzen
+      HELP
+    end
+
+    def format_command_help(command)
+      case command
+      when 'status'
+        <<~HELP
+          anzen status - Display protection status and monitor state
+
+          Usage: anzen status [options]
+
+          Options:
+            --format FORMAT   Output format: json, text (default: text)
+
+          Examples:
+            anzen status
+            anzen status --format json
+
+          Output includes:
+            - Monitor names and enabled/disabled state
+            - Configured thresholds for each monitor
+            - Last check timestamp
+            - Total violations detected
+        HELP
+      when 'config'
+        <<~HELP
+          anzen config - Display monitor configuration details
+
+          Usage: anzen config [monitor_name] [options]
+
+          Arguments:
+            monitor_name      Optional: Show config for specific monitor
+
+          Options:
+            --format FORMAT   Output format: json, text (default: text)
+
+          Examples:
+            anzen config
+            anzen config memory
+            anzen config --format json
+
+          Shows configuration for all monitors or specific monitor.
+        HELP
+      when 'info'
+        <<~HELP
+          anzen info - Display gem installation information
+
+          Usage: anzen info [options]
+
+          Options:
+            --format FORMAT   Output format: json, text (default: text)
+
+          Examples:
+            anzen info
+            anzen info --format json
+
+          Shows gem version, Ruby version, platform, and other metadata.
+        HELP
+      else
+        "Unknown command '#{command}'. Use 'anzen help' for available commands."
+      end
+    end
+  end
+end

data/lib/anzen/configuration.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+
+module Anzen
+  # Configuration manager for Anzen
+  #
+  # Loads and validates configuration from various sources.
+  # Supports dot-notation for accessing nested config values.
+  #
+  # @api public
+  class Configuration
+    # Known monitor names
+    KNOWN_MONITORS = %w[call_stack_depth recursion memory].freeze
+    private_constant :KNOWN_MONITORS
+    # Load configuration from environment variable
+    #
+    # Expects ANZEN_CONFIG to contain JSON or YAML config.
+    #
+    # @return [Configuration] configuration instance
+    # @raise [ConfigurationError] if config is invalid
+    def self.from_env
+      config_str = ENV.fetch('ANZEN_CONFIG', nil)
+      raise Anzen::ConfigurationError, 'ANZEN_CONFIG not set' unless config_str
+
+      config = nil
+      begin
+        # Try JSON first
+        config = JSON.parse(config_str)
+      rescue JSON::ParserError
+        # Fall back to YAML
+        config = YAML.safe_load(config_str)
+      end
+
+      # Ensure we got a hash back
+      raise Anzen::ConfigurationError, 'ANZEN_CONFIG must contain a valid JSON or YAML hash' unless config.is_a?(Hash)
+
+      new(config)
+    end
+
+    # Load configuration from file
+    #
+    # @param path [String] path to config file (JSON or YAML)
+    # @return [Configuration] configuration instance
+    # @raise [ConfigurationError] if file doesn't exist or is invalid
+    def self.from_file(path)
+      raise Anzen::ConfigurationError, "Config file not found: #{path}" unless File.exist?(path)
+
+      content = File.read(path)
+      config = if path.end_with?('.json')
+                 JSON.parse(content)
+               else
+                 YAML.safe_load(content)
+               end
+
+      new(config)
+    end
+
+    # Create configuration from hash (programmatic)
+    #
+    # @param config [Hash] configuration hash
+    # @return [Configuration] configuration instance
+    def self.programmatic(config = {})
+      new(config)
+    end
+
+    # Initialize Configuration
+    #
+    # @param config [Hash] configuration hash
+    def initialize(config = {})
+      @config = normalize_keys(config)
+      validate!
+    end
+
+    # Get configuration value by dot-notation path
+    #
+    # @param path [String] dot-notation path (e.g., "monitors.recursion.depth_limit")
+    # @return [Object] configuration value
+    # @raise [ConfigurationError] if path doesn't exist
+    def get(path)
+      keys = path.split('.')
+      value = @config
+
+      keys.each do |key|
+        case value
+        when Hash
+          value = value[key] || value[key.to_sym]
+        else
+          raise Anzen::ConfigurationError, "Cannot access '#{key}' in non-hash value"
+        end
+
+        raise Anzen::ConfigurationError, "Config path not found: #{path}" if value.nil?
+      end
+
+      value
+    end
+
+    # Check if monitor is enabled
+    #
+    # @param name [String] monitor name
+    # @return [Boolean] true if monitor is in enabled_monitors list
+    def monitor_enabled?(name)
+      enabled = begin
+        get('enabled_monitors')
+      rescue StandardError
+        []
+      end
+      enabled.include?(name)
+    end
+
+    # Get configuration for specific monitor
+    #
+    # @param name [String] monitor name
+    # @return [Hash] monitor configuration
+    # @raise [ConfigurationError] if monitor config not found
+    def monitor_config(name)
+      get("monitors.#{name}")
+    end
+
+    # Validate configuration schema
+    #
+    # @return [Boolean] true if valid
+    # @raise [ConfigurationError] if invalid
+    def validate!
+      # Normalize keys to strings for consistent access
+      normalized = normalize_keys(@config)
+
+      # enabled_monitors should be array if present and non-nil
+      if normalized.key?('enabled_monitors') && !normalized['enabled_monitors'].nil? && !normalized['enabled_monitors'].is_a?(Array)
+        raise Anzen::ConfigurationError, 'enabled_monitors must be an array'
+      end
+
+      # monitors should be hash if present and non-nil
+      if normalized.key?('monitors') && !normalized['monitors'].nil? && !normalized['monitors'].is_a?(Hash)
+        raise Anzen::ConfigurationError, 'monitors must be a hash'
+      end
+
+      # Check that all enabled monitors are known
+      enabled_monitors = normalized['enabled_monitors'] || []
+      unknown_monitors = enabled_monitors - KNOWN_MONITORS
+      unless unknown_monitors.empty?
+        raise Anzen::ConfigurationError, "Unknown monitor(s): #{unknown_monitors.join(", ")}"
+      end
+
+      # Validate monitor configs
+      monitors = normalized['monitors'] || {}
+      monitors.each do |name, config|
+        validate_monitor_config(name, config)
+      end
+
+      true
+    end
+
+    # Return raw configuration hash
+    #
+    # @return [Hash]
+    def to_h
+      deep_dup(@config)
+    end
+
+    private
+
+    # Deep copy of a hash
+    #
+    # @param obj [Object] object to deep copy
+    # @return [Object] deep copy
+    def deep_dup(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(k, v), hash|
+          hash[k] = deep_dup(v)
+        end
+      when Array
+        obj.map { |item| deep_dup(item) }
+      else
+        begin
+          obj.dup
+        rescue StandardError
+          obj
+        end
+      end
+    end
+
+    # Normalize hash keys from symbols to strings (recursively)
+    #
+    # @param hash [Hash] hash to normalize
+    # @return [Hash] hash with string keys
+    def normalize_keys(hash)
+      return hash unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) do |(key, value), new_hash|
+        string_key = key.is_a?(Symbol) ? key.to_s : key
+        new_hash[string_key] = value.is_a?(Hash) ? normalize_keys(value) : value
+      end
+    end
+
+    # Validate individual monitor configuration
+    #
+    # @param name [String] monitor name
+    # @param config [Hash] monitor configuration
+    # @raise [ConfigurationError] if invalid
+    def validate_monitor_config(name, config)
+      return unless config.is_a?(Hash)
+
+      case name
+      when 'recursion'
+        validate_recursion_config(config)
+      when 'memory'
+        validate_memory_config(config)
+      end
+    end
+
+    # Validate recursion monitor config
+    #
+    # @param config [Hash] recursion config
+    # @raise [ConfigurationError] if invalid
+    def validate_recursion_config(config)
+      normalized = normalize_keys(config)
+
+      if normalized['depth_limit'] && !normalized['depth_limit'].is_a?(Numeric)
+        raise Anzen::ConfigurationError, 'recursion.depth_limit must be numeric'
+      end
+
+      return unless normalized['depth_limit'] && normalized['depth_limit'] <= 0
+
+      raise Anzen::ConfigurationError, 'recursion.depth_limit must be positive'
+    end
+
+    # Validate memory monitor config
+    #
+    # @param config [Hash] memory config
+    # @raise [ConfigurationError] if invalid
+    def validate_memory_config(config)
+      normalized = normalize_keys(config)
+
+      if normalized['limit_mb'] && !normalized['limit_mb'].is_a?(Numeric)
+        raise Anzen::ConfigurationError, 'memory.limit_mb must be numeric'
+      end
+
+      if normalized['limit_mb'] && normalized['limit_mb'] <= 0
+        raise Anzen::ConfigurationError, 'memory.limit_mb must be positive'
+      end
+
+      if normalized['limit_percent'] && !normalized['limit_percent'].is_a?(Numeric)
+        raise Anzen::ConfigurationError, 'memory.limit_percent must be numeric'
+      end
+
+      if normalized['limit_percent'] && (normalized['limit_percent'] <= 0 || normalized['limit_percent'] > 100)
+        raise Anzen::ConfigurationError, 'memory.limit_percent must be between 0 and 100'
+      end
+    end
+  end
+end

data/lib/anzen/exceptions.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Anzen
+  # Base exception for all Anzen errors
+  class Error < StandardError; end
+
+  # Base exception for safety violations detected by monitors
+  #
+  # @api public
+  class ViolationError < Error; end
+
+  # Raised when recursion depth exceeds configured threshold
+  #
+  # @api public
+  class RecursionLimitExceeded < ViolationError
+    # @return [Integer] current recursion depth when violation detected
+    attr_reader :current_depth
+
+    # @return [Integer] configured depth threshold
+    attr_reader :threshold
+
+    # Initialize RecursionLimitExceeded exception
+    #
+    # @param current_depth [Integer] current call stack depth
+    # @param threshold [Integer] configured limit
+    def initialize(current_depth, threshold)
+      @current_depth = current_depth
+      @threshold = threshold
+      super("Recursion depth (#{current_depth}) exceeded threshold (#{threshold})")
+    end
+  end
+
+  # Raised when process memory usage exceeds configured threshold
+  #
+  # @api public
+  class MemoryLimitExceeded < ViolationError
+    # @return [Integer] current memory usage in MB
+    attr_reader :current_memory_mb
+
+    # @return [Integer] configured memory threshold in MB
+    attr_reader :threshold_mb
+
+    # Initialize MemoryLimitExceeded exception
+    #
+    # @param current_memory_mb [Integer] current process memory in MB
+    # @param threshold_mb [Integer] configured threshold in MB
+    def initialize(current_memory_mb, threshold_mb)
+      @current_memory_mb = current_memory_mb
+      @threshold_mb = threshold_mb
+      super("Memory usage (#{current_memory_mb}MB) exceeded threshold (#{threshold_mb}MB)")
+    end
+  end
+
+  # Raised when a monitor's check infrastructure fails (not a violation)
+  #
+  # Used to distinguish infrastructure errors from actual safety violations.
+  # For example: cannot read /proc/self/status when checking memory.
+  #
+  # @api public
+  class CheckFailedError < Error
+    # @return [String] name of the monitor that failed
+    attr_reader :monitor_name
+
+    # @return [String] reason for the check failure
+    attr_reader :reason
+
+    # @return [Exception, nil] original exception if available
+    attr_reader :original_error
+
+    # Initialize CheckFailedError
+    #
+    # @param monitor_name [String] name of the monitor that failed
+    # @param reason [String] description of what failed
+    # @param original_error [Exception, nil] exception from the failed check
+    def initialize(monitor_name, reason, original_error = nil)
+      @monitor_name = monitor_name
+      @reason = reason
+      @original_error = original_error
+
+      message = "Monitor '#{monitor_name}' check failed: #{reason}"
+      message += " (#{original_error.class}: #{original_error.message})" if original_error
+      super(message)
+    end
+  end
+
+  # Raised when Anzen configuration is invalid
+  #
+  # @api public
+  class ConfigurationError < Error; end
+
+  # Raised when attempting to access a non-existent monitor
+  #
+  # @api public
+  class MonitorNotFoundError < Error
+    # @param monitor_name [String] name of monitor that was not found
+    def initialize(monitor_name)
+      super("Monitor '#{monitor_name}' not found in registry")
+    end
+  end
+
+  # Raised when attempting to register an invalid monitor
+  #
+  # @api public
+  class InvalidMonitorError < Error
+    # @param reason [String] description of what makes monitor invalid
+    def initialize(reason)
+      super("Invalid monitor: #{reason}")
+    end
+  end
+
+  # Raised when attempting to register a monitor with a name that already exists
+  #
+  # @api public
+  class MonitorNameConflictError < Error
+    # @param monitor_name [String] name that caused conflict
+    def initialize(monitor_name)
+      super("Monitor name '#{monitor_name}' is already registered")
+    end
+  end
+
+  # Raised when Anzen.setup is called more than once
+  #
+  # @api public
+  class InitializationError < Error
+    # @param reason [String] description of initialization problem
+    def initialize(reason = 'Anzen already initialized')
+      super(reason)
+    end
+  end
+end