rosett-ai 1.3.3

data/lib/rosett_ai/structured_logger.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'logger'
+require 'json'
+require 'securerandom'
+
+module RosettAi
+  # Structured logger with per-invocation correlation IDs and JSON/text output.
+  #
+  # Drop-in replacement for Ruby's +Logger+. Every log entry includes a
+  # correlation ID (UUID v4) generated once per CLI invocation so that all
+  # entries from one run can be correlated.
+  #
+  # Log format is controlled by +RAI_LOG_FORMAT+:
+  # - +"text"+ (default): <tt>[LEVEL] [correlation_id] message</tt>
+  # - +"json"+: JSON Lines (one JSON object per line)
+  #
+  # @example
+  #   logger = RosettAi::StructuredLogger.new
+  #   logger.info("Loading behaviour files")
+  #   # Text: [INFO] [a1b2c3d4-...] Loading behaviour files
+  #   # JSON: {"timestamp":"...","level":"info","correlation_id":"a1b2c3d4-...","pid":12345,"message":"Loading behaviour files"}
+  #
+  # @author hugo
+  # @author claude
+  class StructuredLogger < ::Logger
+    VALID_FORMATS = ['text', 'json'].freeze
+
+    # @return [String] correlation ID for the current invocation (UUID v4)
+    attr_reader :correlation_id
+
+    # @return [String, nil] current command name (set via {#command=})
+    attr_reader :command
+
+    # Creates a new structured logger writing to stderr.
+    #
+    # @param output [IO] output stream (default: $stderr)
+    # @param correlation_id [String, nil] explicit correlation ID (default: generates new UUID)
+    def initialize(output = $stderr, correlation_id: nil)
+      super(output)
+      @correlation_id = correlation_id || SecureRandom.uuid
+      @command = nil
+      @mutex = Mutex.new
+
+      self.level = resolve_level
+      self.formatter = build_formatter
+    end
+
+    # Sets the current command name for inclusion in log entries.
+    #
+    # @param name [String] command name
+    # @return [void]
+    def command=(name)
+      @mutex.synchronize { @command = name }
+    end
+
+    # Reset logger state. Generates a new correlation ID.
+    # Intended for test isolation.
+    #
+    # @return [void]
+    def reset!
+      @mutex.synchronize do
+        @correlation_id = SecureRandom.uuid
+        @command = nil
+      end
+    end
+
+    private
+
+    def resolve_level
+      raw = ENV.fetch('RAI_LOG_LEVEL', 'WARN').upcase
+      ::Logger.const_get(raw)
+    rescue NameError
+      ::Logger::WARN
+    end
+
+    def log_format
+      raw = ENV.fetch('RAI_LOG_FORMAT', 'text').downcase
+      VALID_FORMATS.include?(raw) ? raw : 'text'
+    end
+
+    def build_formatter
+      case log_format
+      when 'json' then method(:json_formatter)
+      else method(:text_formatter)
+      end
+    end
+
+    def text_formatter(severity, _timestamp, _progname, message)
+      "[#{severity}] [#{@correlation_id[0, 8]}] #{message}\n"
+    end
+
+    def json_formatter(severity, timestamp, _progname, message)
+      entry = {
+        timestamp: timestamp.utc.iso8601(3),
+        level: severity.downcase,
+        correlation_id: @correlation_id,
+        pid: Process.pid,
+        message: message.to_s
+      }
+      cmd = @mutex.synchronize { @command }
+      entry[:command] = cmd if cmd
+
+      "#{JSON.generate(entry)}\n"
+    end
+  end
+end

data/lib/rosett_ai/telemetry/json_lines_writer.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'json'
+
+module RosettAi
+  module Telemetry
+    # Writes telemetry events as JSON Lines (one JSON object per line).
+    #
+    # @author hugo
+    # @author claude
+    class JsonLinesWriter
+      # @param io [IO] output stream
+      # @param rotator [LogRotator, nil] optional log rotator for file output
+      def initialize(io:, rotator: nil)
+        @io = io
+        @rotator = rotator
+      end
+
+      # Write a single event as a JSON line.
+      #
+      # @param event_hash [Hash] event data (must be JSON-serializable)
+      # @return [void]
+      def write(event_hash)
+        rotate_if_needed
+        @io.puts(JSON.generate(event_hash))
+      end
+
+      # Close the underlying IO.
+      # @return [void]
+      def close
+        @io.close unless @io == $stderr || @io == $stdout
+      end
+
+      private
+
+      def rotate_if_needed
+        return unless @rotator
+
+        return unless @rotator.rotate_if_needed!
+
+        @io.close
+        @io = File.open(@rotator.path, 'a') # rubocop:disable Style/FileOpen -- lifecycle managed by #close
+        @io.sync = true
+      end
+    end
+  end
+end

data/lib/rosett_ai/telemetry/log_rotator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Telemetry
+    # Rotates telemetry log files when they exceed a size threshold.
+    #
+    # Rotated files are numbered .1 through .N, where .1 is the most
+    # recent. The oldest file is deleted when max_files is exceeded.
+    #
+    # @author hugo
+    # @author claude
+    class LogRotator
+      DEFAULT_MAX_SIZE  = 10 * 1024 * 1024 # 10 MB
+      DEFAULT_MAX_FILES = 5
+
+      # @return [String] path to the log file
+      attr_reader :path
+
+      # @param path [String] log file path
+      # @param max_size [Integer] rotation threshold in bytes (default: 10 MB)
+      # @param max_files [Integer] number of rotated files to keep (default: 5)
+      def initialize(path:, max_size: DEFAULT_MAX_SIZE, max_files: DEFAULT_MAX_FILES)
+        @path = path
+        @max_size = max_size
+        @max_files = max_files
+      end
+
+      # Rotate the log file if it exceeds the size threshold.
+      #
+      # @return [Boolean] true if rotation occurred
+      def rotate_if_needed! # rubocop:disable Naming/PredicateMethod -- mutates state, not a pure predicate
+        return false unless File.exist?(@path)
+        return false unless File.size(@path) >= @max_size
+
+        rotate!
+        true
+      end
+
+      private
+
+      def rotate!
+        delete_oldest
+        shift_rotated_files
+        File.rename(@path, rotated_path(1))
+      end
+
+      def delete_oldest
+        oldest = rotated_path(@max_files)
+        FileUtils.rm_f(oldest)
+      end
+
+      def shift_rotated_files
+        (@max_files - 1).downto(1) do |index|
+          current = rotated_path(index)
+          File.rename(current, rotated_path(index + 1)) if File.exist?(current)
+        end
+      end
+
+      def rotated_path(index)
+        "#{@path}.#{index}"
+      end
+    end
+  end
+end

data/lib/rosett_ai/telemetry/provider.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Telemetry
+    # Interface module for telemetry providers.
+    #
+    # Providers receive frozen event hashes via +#report+ and must
+    # not mutate them. Implement this interface to add custom
+    # telemetry consumers (e.g., D-Bus health, metrics aggregation).
+    #
+    # @author hugo
+    # @author claude
+    module Provider
+      # Receive a telemetry event.
+      #
+      # @param event_hash [Hash] frozen event data
+      # @return [void]
+      def report(event_hash)
+        raise NotImplementedError, "#{self.class}#report must be implemented"
+      end
+    end
+  end
+end

data/lib/rosett_ai/telemetry/reporter.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'securerandom'
+
+module RosettAi
+  module Telemetry
+    # Singleton reporter that writes structured telemetry events.
+    #
+    # Events are written as JSON Lines to stderr (default) or a file
+    # specified by +RAI_TELEMETRY_FILE+. Providers can be registered
+    # to receive event notifications.
+    #
+    # @author hugo
+    # @author claude
+    class Reporter
+      @instance = nil
+      @mutex = Mutex.new
+
+      # @return [Reporter] singleton instance
+      def self.instance
+        @mutex.synchronize { @instance ||= new }
+      end
+
+      # Reset singleton. Intended for test isolation.
+      # @return [void]
+      def self.reset!
+        @mutex.synchronize do
+          @instance&.close
+          @instance = nil
+        end
+      end
+
+      # @return [Boolean] telemetry enabled?
+      def self.enabled?
+        RosettAi::Telemetry.enabled?
+      end
+
+      def initialize
+        @providers = []
+        @mutex = Mutex.new
+        @correlation_id = SecureRandom.uuid
+        @writer = resolve_writer
+      end
+
+      # Write a telemetry event.
+      #
+      # @param level [Symbol, String] event severity (:debug, :info, :warn, :error)
+      # @param event [Symbol, String] event name (e.g. :command_start)
+      # @param data [Hash] additional event data
+      # @return [void]
+      def write_event(level:, event:, **data)
+        return unless self.class.enabled?
+        return unless RosettAi::Telemetry.level_enabled?(level)
+
+        event_hash = build_event(level: level, event: event, **data).freeze
+        @mutex.synchronize do
+          safe_write(event_hash)
+          @providers.each { |provider| provider.report(event_hash) }
+        end
+      end
+
+      # Emit a command_start event.
+      #
+      # @param command [String] command name
+      # @param data [Hash] additional data
+      # @return [void]
+      def command_start(command:, **data)
+        write_event(level: :info, event: :command_start, command: command, **data)
+      end
+
+      # Emit a command_end event with timing.
+      #
+      # @param command [String] command name
+      # @param duration_ms [Float] execution time in milliseconds
+      # @param status [String] outcome ('success' or 'error')
+      # @param data [Hash] additional data
+      # @return [void]
+      def command_end(command:, duration_ms:, status:, **data)
+        write_event(level: :info, event: :command_end, command: command,
+                    duration_ms: duration_ms, status: status, **data)
+      end
+
+      # Register a telemetry provider.
+      #
+      # @param provider [#report] object implementing the Provider interface
+      # @return [void]
+      def register_provider(provider)
+        @mutex.synchronize { @providers << provider }
+      end
+
+      # @return [String] correlation ID for this session
+      attr_reader :correlation_id
+
+      # Close any open file handles.
+      # @return [void]
+      def close
+        @mutex.synchronize do
+          @writer&.close
+          @writer = nil
+        end
+      end
+
+      private
+
+      def build_event(level:, event:, **data)
+        {
+          timestamp: Time.now.utc.iso8601(3),
+          level: level.to_s,
+          event: event.to_s,
+          pid: Process.pid,
+          correlation_id: @correlation_id
+        }.merge(data)
+      end
+
+      def safe_write(event_hash)
+        @writer&.write(event_hash)
+      rescue IOError, Errno::ENOSPC => e
+        warn "rai: telemetry write failed — #{e.message}"
+      end
+
+      def resolve_writer
+        return nil unless self.class.enabled?
+
+        file_path = ENV.fetch('RAI_TELEMETRY_FILE', nil)
+        if file_path
+          rotator = LogRotator.new(path: file_path)
+          rotator.rotate_if_needed!
+          io = File.open(file_path, 'a') # rubocop:disable Style/FileOpen -- lifecycle managed by #close
+          io.sync = true
+          JsonLinesWriter.new(io: io, rotator: rotator)
+        else
+          JsonLinesWriter.new(io: $stderr)
+        end
+      rescue Errno::EACCES, Errno::ENOENT => e
+        warn "rai: telemetry file #{file_path} unwritable " \
+             "— telemetry disabled for this invocation (#{e.message})"
+        nil
+      end
+    end
+  end
+end

data/lib/rosett_ai/telemetry.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  # Opt-in structured telemetry for CLI observability.
+  #
+  # Enabled via +RAI_TELEMETRY=1+. Captures JSON Lines events for
+  # command timing, errors, and diagnostics. All data stays local.
+  #
+  # @author hugo
+  # @author claude
+  # @see conf/design/monitoring_observability.yml
+  module Telemetry
+    LEVELS = ['debug', 'info', 'warn', 'error'].freeze
+
+    # @return [Boolean] true if telemetry is enabled via environment variable
+    def self.enabled?
+      ENV['RAI_TELEMETRY'] == '1'
+    end
+
+    # @return [RosettAi::Telemetry::Reporter] singleton reporter instance
+    def self.reporter
+      Reporter.instance
+    end
+
+    # @return [String] configured telemetry level (default: info)
+    def self.level
+      raw = ENV.fetch('RAI_TELEMETRY_LEVEL', 'info').downcase
+      LEVELS.include?(raw) ? raw : 'info'
+    end
+
+    # @param level [String] event level to check
+    # @return [Boolean] true if the level meets the configured threshold
+    def self.level_enabled?(level)
+      LEVELS.index(level.to_s) >= LEVELS.index(self.level)
+    end
+
+    # Reset singleton state. Intended for test isolation.
+    #
+    # @return [void]
+    def self.reset!
+      Reporter.reset!
+    end
+  end
+end

data/lib/rosett_ai/text_sanitizer.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  # Sanitizes text for safe TUI display and normalizes Unicode input.
+  #
+  # strip_ansi  — removes ANSI escape sequences and control characters
+  #               at display boundaries (criterion 10).
+  # normalize_nfc — applies Unicode NFC normalization at input boundaries
+  #                 (criterion 11).
+  module TextSanitizer
+    # Matches ANSI CSI sequences (\e[...X), OSC sequences (\e]...\a),
+    # and non-printable control characters except tab, newline, and CR.
+    ANSI_PATTERN = /\e\[\d*(?:;\d*)*[A-Za-z]|\e\][^\a]*\a|[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/
+
+    # Removes ANSI escape sequences and non-printable control characters.
+    #
+    # @param string [String] the input string to sanitize
+    # @return [String] the string with ANSI sequences removed
+    def self.strip_ansi(string)
+      String(string).gsub(ANSI_PATTERN, '')
+    end
+
+    # Applies Unicode NFC normalization at input boundaries.
+    #
+    # @param string [String] the input string to normalize
+    # @return [String] the NFC-normalized UTF-8 string
+    def self.normalize_nfc(string)
+      String(string).encode('UTF-8').unicode_normalize(:nfc)
+    end
+
+    # Characters that have special meaning in Markdown syntax.
+    MARKDOWN_META = /([\\`*_{}\[\]()#+\-.!|])/
+
+    # Escapes Markdown metacharacters so text renders as literal content.
+    #
+    # @param text [String, nil] the input text
+    # @return [String] the escaped text safe for Markdown embedding
+    def self.escape_markdown(text)
+      text.to_s.gsub(MARKDOWN_META, '\\\\\1')
+    end
+
+    # Recursively strips ANSI escape sequences from strings in nested structures.
+    #
+    # @param data [String, Hash, Array, Object] the data to sanitize
+    # @return [String, Hash, Array, Object] the sanitized data in its original structure
+    def self.sanitize_for_display(data)
+      case data
+      when String
+        strip_ansi(data)
+      when Hash
+        data.transform_values { |v| sanitize_for_display(v) }
+      when Array
+        data.map { |v| sanitize_for_display(v) }
+      else
+        data
+      end
+    end
+  end
+end