rosett-ai 1.3.3

data/lib/rosett_ai/desktop/gui_logger.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'json'
+require 'time'
+
+module RosettAi
+  module Desktop
+    # Structured GUI action logger for debugging and crash analysis.
+    #
+    # Provides comprehensive logging of all GUI interactions including:
+    # - Action invocation with parameters
+    # - Success/failure outcomes with duration
+    # - Widget events and state changes
+    # - D-Bus operations
+    #
+    # Log output is controlled by environment variables:
+    #   RAI_GUI_LOG=1           Enable logging to stderr
+    #   RAI_GUI_LOG_FILE=path   Also log to file
+    #   RAI_GUI_LOG_LEVEL=debug Set log level (debug, info, warn, error)
+    #
+    # Log format is JSON Lines for easy parsing and analysis.
+    #
+    # @example Enable logging
+    #   RAI_GUI_LOG=1 bin/raictl desktop gtk4
+    #
+    # @example Log to file
+    #   RAI_GUI_LOG=1 RAI_GUI_LOG_FILE=/tmp/rosett-ai-gui.log bin/raictl desktop gtk4
+    #
+    class GuiLogger
+      LEVELS = { debug: 0, info: 1, warn: 2, error: 3 }.freeze
+      DEFAULT_LEVEL = :info
+
+      class << self
+        # Get the singleton instance.
+        #
+        # @return [GuiLogger]
+        def instance
+          @instance ||= new
+        end
+
+        # Delegate class methods to instance for convenience.
+        [:action, :action_start, :action_end, :callback, :widget_event, :dbus_call, :debug, :info, :warn, :error,
+         :enabled?].each do |method|
+          define_method(method) { |*args, **kwargs, &block| instance.send(method, *args, **kwargs, &block) }
+        end
+      end
+
+      def initialize
+        @enabled = ENV['RAI_GUI_LOG'] == '1'
+        @log_file = ENV.fetch('RAI_GUI_LOG_FILE', nil)
+        @level = parse_level(ENV.fetch('RAI_GUI_LOG_LEVEL', 'info'))
+        @file_handle = nil
+        @action_stack = []
+        @mutex = Mutex.new
+
+        setup_file_logging if @log_file
+        at_exit { cleanup }
+      end
+
+      # Check if logging is enabled.
+      #
+      # @return [Boolean]
+      def enabled?
+        @enabled
+      end
+
+      # Log a complete action with automatic timing.
+      #
+      # @param name [String, Symbol] action name
+      # @param context [Hash] additional context
+      # @yield the action block
+      # @return [Object] result of the block
+      def action(name, context = {})
+        return yield unless @enabled
+
+        action_start(name, context)
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        begin
+          result = yield
+          duration = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
+          action_end(name, status: :success, duration_ms: duration)
+          result
+        rescue StandardError => e
+          duration = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
+          action_end(name, status: :error, duration_ms: duration, error: e.class.name, message: e.message)
+          raise
+        end
+      end
+
+      # Log action start.
+      #
+      # @param name [String, Symbol] action name
+      # @param context [Hash] additional context
+      def action_start(name, context = {})
+        return unless @enabled
+
+        @mutex.synchronize { @action_stack.push(name.to_s) }
+        write_log(:info, 'action_start', { action: name.to_s }.merge(context))
+      end
+
+      # Log action end.
+      #
+      # @param name [String, Symbol] action name
+      # @param context [Hash] additional context (status, duration_ms, error)
+      def action_end(name, context = {})
+        return unless @enabled
+
+        @mutex.synchronize { @action_stack.pop }
+        level = context[:status] == :error ? :error : :info
+        write_log(level, 'action_end', { action: name.to_s }.merge(context))
+      end
+
+      # Log a callback invocation.
+      #
+      # @param name [String, Symbol] callback name
+      # @param context [Hash] additional context
+      def callback(name, context = {})
+        return unless @enabled
+
+        write_log(:debug, 'callback', { callback: name.to_s }.merge(context))
+      end
+
+      # Log a widget event.
+      #
+      # @param widget_type [String, Symbol] widget type (e.g., :switch_row, :combo_row)
+      # @param event [String, Symbol] event name (e.g., :toggled, :selected)
+      # @param context [Hash] additional context (value, widget_id, etc.)
+      def widget_event(widget_type, event, context = {})
+        return unless @enabled
+
+        write_log(:debug, 'widget_event', {
+          widget: widget_type.to_s,
+          event: event.to_s
+        }.merge(context))
+      end
+
+      # Log a D-Bus operation.
+      #
+      # @param operation [String, Symbol] operation name
+      # @param context [Hash] additional context
+      def dbus_call(operation, context = {})
+        return unless @enabled
+
+        write_log(:debug, 'dbus_call', { operation: operation.to_s }.merge(context))
+      end
+
+      # Log debug message.
+      #
+      # @param message [String] log message
+      # @param context [Hash] additional context
+      def debug(message, context = {})
+        write_log(:debug, 'debug', { message: message }.merge(context))
+      end
+
+      # Log info message.
+      #
+      # @param message [String] log message
+      # @param context [Hash] additional context
+      def info(message, context = {})
+        write_log(:info, 'info', { message: message }.merge(context))
+      end
+
+      # Log warning message.
+      #
+      # @param message [String] log message
+      # @param context [Hash] additional context
+      def warn(message, context = {})
+        write_log(:warn, 'warn', { message: message }.merge(context))
+      end
+
+      # Log error message.
+      #
+      # @param message [String] log message
+      # @param error [Exception, nil] optional exception
+      # @param context [Hash] additional context
+      def error(message, error = nil, context = {})
+        data = { message: message }.merge(context)
+        if error
+          data[:error_class] = error.class.name
+          data[:error_message] = error.message
+          data[:backtrace] = error.backtrace&.first(5)
+        end
+        write_log(:error, 'error', data)
+      end
+
+      private
+
+      def parse_level(level_str)
+        LEVELS.fetch(level_str.to_sym, LEVELS[DEFAULT_LEVEL])
+      end
+
+      def setup_file_logging
+        @file_handle = File.open(@log_file, 'a') # rubocop:disable Style/FileOpen -- persistent handle, closed in #cleanup
+        @file_handle.sync = true
+      rescue StandardError => e
+        warn "[GuiLogger] Failed to open log file: #{e.message}"
+        @file_handle = nil
+      end
+
+      def cleanup
+        @file_handle&.close
+      rescue StandardError
+        nil
+      end
+
+      def write_log(level, event_type, data)
+        return unless @enabled
+        return if LEVELS.fetch(level, 0) < @level
+
+        entry = {
+          timestamp: Time.now.utc.iso8601(3),
+          level: level.to_s,
+          event: event_type,
+          pid: Process.pid
+        }.merge(data)
+
+        # Add action context if within an action
+        entry[:action_stack] = @action_stack.dup unless @action_stack.empty?
+
+        json_line = JSON.generate(entry)
+
+        @mutex.synchronize do
+          warn json_line
+          @file_handle&.puts(json_line)
+        end
+      rescue StandardError
+        # Never let logging cause issues
+        nil
+      end
+    end
+  end
+end

data/lib/rosett_ai/doctor/check.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Doctor
+    # Base interface for diagnostic checks.
+    #
+    # Include this module and implement #perform to create a check.
+    # The #run method calls #perform and sets status/message/remediation.
+    #
+    # @author hugo
+    # @author claude
+    module Check
+      # @return [String] human-readable check name
+      def name
+        self.class.check_name
+      end
+
+      # @return [Symbol] :pass, :warn, or :fail
+      attr_reader :status
+
+      # @return [String] result description
+      attr_reader :message
+
+      # @return [String, nil] remediation steps (nil when passing)
+      attr_reader :remediation
+
+      # Execute the check. Sets status, message, and remediation.
+      # @return [void]
+      def run
+        perform
+      rescue StandardError => e
+        fail!(e.message, remediation: ::I18n.t('rosett_ai.doctor.unexpected_error'))
+      end
+
+      # Register this check class with the Doctor module.
+      # @param check_name [String] unique check identifier
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Class-level methods for check classes.
+      module ClassMethods
+        # Set or get the check name.
+        # @param name [String, nil] check name to set
+        # @return [String]
+        def check_name(name = nil)
+          @check_name = name if name
+          @check_name || (self.name || 'anonymous').split('::').last.gsub(/Check$/, '').gsub(/([A-Z])/, '_\1').sub(
+            /^_/, ''
+          ).downcase
+        end
+      end
+
+      private
+
+      # Mark the check as passing.
+      # @param message [String]
+      def pass!(message)
+        @status = :pass
+        @message = message
+        @remediation = nil
+      end
+
+      # Mark the check as warning.
+      # @param message [String]
+      # @param remediation [String]
+      def warn!(message, remediation:)
+        @status = :warn
+        @message = message
+        @remediation = remediation
+      end
+
+      # Mark the check as failed.
+      # @param message [String]
+      # @param remediation [String]
+      def fail!(message, remediation:)
+        @status = :fail
+        @message = message
+        @remediation = remediation
+      end
+
+      # Subclasses must implement this method.
+      # @abstract
+      def perform
+        raise NotImplementedError, "#{self.class}#perform must be implemented"
+      end
+    end
+  end
+end

data/lib/rosett_ai/doctor/checks/cache_health_check.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Doctor
+    module Checks
+      # Verifies the cache directory exists and is writable.
+      #
+      # @author hugo
+      # @author claude
+      class CacheHealthCheck
+        include Check
+
+        check_name 'cache_health'
+
+        private
+
+        def perform
+          cache_dir = resolve_cache_dir
+
+          unless cache_dir.exist?
+            warn!(
+              ::I18n.t('rosett_ai.doctor.cache_health.not_found', path: cache_dir),
+              remediation: ::I18n.t('rosett_ai.doctor.cache_health.create_dir', path: cache_dir)
+            )
+            return
+          end
+
+          if cache_dir.writable?
+            pass!(::I18n.t('rosett_ai.doctor.cache_health.writable', path: cache_dir))
+          else
+            fail!(
+              ::I18n.t('rosett_ai.doctor.cache_health.not_writable', path: cache_dir),
+              remediation: ::I18n.t('rosett_ai.doctor.cache_health.fix_permissions', path: cache_dir)
+            )
+          end
+        end
+
+        def resolve_cache_dir
+          xdg = ENV.fetch('XDG_CACHE_HOME', File.join(Dir.home, '.cache'))
+          Pathname.new(xdg).join('rosett-ai')
+        end
+      end
+    end
+  end
+end
+
+RosettAi::Doctor.register(RosettAi::Doctor::Checks::CacheHealthCheck)

data/lib/rosett_ai/doctor/checks/dbus_availability_check.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Doctor
+    module Checks
+      # Checks whether the D-Bus session bus is available.
+      #
+      # D-Bus is optional — missing D-Bus is a warning, not a failure.
+      #
+      # @author hugo
+      # @author claude
+      class DbusAvailabilityCheck
+        include Check
+
+        check_name 'dbus_availability'
+
+        private
+
+        def perform
+          bus_address = ENV.fetch('DBUS_SESSION_BUS_ADDRESS', nil)
+
+          if bus_address && !bus_address.empty?
+            pass!(::I18n.t('rosett_ai.doctor.dbus_availability.available'))
+          else
+            warn!(
+              ::I18n.t('rosett_ai.doctor.dbus_availability.unavailable'),
+              remediation: ::I18n.t('rosett_ai.doctor.dbus_availability.install_dbus')
+            )
+          end
+        end
+      end
+    end
+  end
+end
+
+RosettAi::Doctor.register(RosettAi::Doctor::Checks::DbusAvailabilityCheck)

data/lib/rosett_ai/doctor/checks/engine_detection_check.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Doctor
+    module Checks
+      # Detects installed rai engines.
+      #
+      # No engines is a warning (rosett-ai still works for validation/compilation
+      # with the generic target).
+      #
+      # @author hugo
+      # @author claude
+      class EngineDetectionCheck
+        include Check
+
+        check_name 'engine_detection'
+
+        private
+
+        def perform
+          engines = discover_engines
+
+          if engines.empty?
+            warn!(
+              ::I18n.t('rosett_ai.doctor.engine_detection.none_found'),
+              remediation: ::I18n.t('rosett_ai.doctor.engine_detection.install_engine')
+            )
+          else
+            pass!(::I18n.t('rosett_ai.doctor.engine_detection.found', engines: engines.join(', ')))
+          end
+        end
+
+        def discover_engines
+          RosettAi::Plugins::Registry.available(:engine)
+        rescue StandardError
+          []
+        end
+      end
+    end
+  end
+end
+
+RosettAi::Doctor.register(RosettAi::Doctor::Checks::EngineDetectionCheck)

data/lib/rosett_ai/doctor/checks/file_permission_check.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Doctor
+    module Checks
+      # Verifies key directories are writable.
+      #
+      # @author hugo
+      # @author claude
+      class FilePermissionCheck
+        include Check
+
+        check_name 'file_permissions'
+
+        private
+
+        def perform
+          resolver = RosettAi::PathResolver.new
+          dirs = [resolver.global_dir, resolver.rai_config_dir]
+          problems = dirs.each_with_object([]) do |dir, acc|
+            next unless dir.exist?
+            next if dir.writable?
+
+            acc << dir.to_s
+          end
+
+          if problems.empty?
+            pass!(::I18n.t('rosett_ai.doctor.file_permissions.writable'))
+          else
+            fail!(
+              ::I18n.t('rosett_ai.doctor.file_permissions.not_writable', dirs: problems.join(', ')),
+              remediation: ::I18n.t('rosett_ai.doctor.file_permissions.fix_permissions')
+            )
+          end
+        end
+      end
+    end
+  end
+end
+
+RosettAi::Doctor.register(RosettAi::Doctor::Checks::FilePermissionCheck)

data/lib/rosett_ai/doctor/checks/gem_dependency_check.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Doctor
+    module Checks
+      # Verifies all Gemfile.lock dependencies are installed.
+      #
+      # @author hugo
+      # @author claude
+      class GemDependencyCheck
+        include Check
+
+        check_name 'gem_dependencies'
+
+        private
+
+        def perform
+          lockfile = RosettAi.root.join('Gemfile.lock')
+
+          unless lockfile.exist?
+            warn!(
+              ::I18n.t('rosett_ai.doctor.gem_dependencies.no_lockfile'),
+              remediation: ::I18n.t('rosett_ai.doctor.gem_dependencies.run_bundle')
+            )
+            return
+          end
+
+          missing = find_missing_gems
+          if missing.empty?
+            pass!(::I18n.t('rosett_ai.doctor.gem_dependencies.all_installed',
+                           count: Gem.loaded_specs.size))
+          else
+            fail!(
+              ::I18n.t('rosett_ai.doctor.gem_dependencies.missing', gems: missing.join(', ')),
+              remediation: ::I18n.t('rosett_ai.doctor.gem_dependencies.run_bundle')
+            )
+          end
+        end
+
+        def find_missing_gems
+          Bundler.locked_gems.specs.each_with_object([]) do |spec, missing|
+            missing << spec.name unless Gem.loaded_specs.key?(spec.name)
+          end
+        rescue StandardError
+          []
+        end
+      end
+    end
+  end
+end
+
+RosettAi::Doctor.register(RosettAi::Doctor::Checks::GemDependencyCheck)

data/lib/rosett_ai/doctor/checks/ruby_version_check.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Doctor
+    module Checks
+      # Verifies the running Ruby version matches .ruby-version.
+      #
+      # @author hugo
+      # @author claude
+      class RubyVersionCheck
+        include Check
+
+        check_name 'ruby_version'
+
+        private
+
+        def perform
+          expected = read_ruby_version
+          actual = RUBY_VERSION
+
+          if expected.nil?
+            warn!(
+              ::I18n.t('rosett_ai.doctor.ruby_version.no_file'),
+              remediation: ::I18n.t('rosett_ai.doctor.ruby_version.create_file')
+            )
+          elsif actual == expected
+            pass!(::I18n.t('rosett_ai.doctor.ruby_version.match', version: actual))
+          else
+            fail!(
+              ::I18n.t('rosett_ai.doctor.ruby_version.mismatch', actual: actual, expected: expected),
+              remediation: ::I18n.t('rosett_ai.doctor.ruby_version.install', version: expected)
+            )
+          end
+        end
+
+        def read_ruby_version
+          path = RosettAi.root.join('.ruby-version')
+          return nil unless path.exist?
+
+          path.read.strip
+        end
+      end
+    end
+  end
+end
+
+RosettAi::Doctor.register(RosettAi::Doctor::Checks::RubyVersionCheck)

data/lib/rosett_ai/doctor/checks/stale_config_nncc_check.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Doctor
+    module Checks
+      # Warns when a stale ~/.config/nncc/ directory exists.
+      #
+      # The legacy XDG config path was ~/.config/nncc/ before the rename to
+      # rosett-ai. This check detects the stale directory and recommends
+      # running `raictl migrate` to move the config.
+      #
+      # @author hugo
+      # @author claude
+      class StaleConfigNnccCheck
+        include Check
+
+        check_name 'stale_config_nncc'
+
+        private
+
+        def perform
+          config_nncc = Pathname.new(Dir.home).join('.config', 'nncc')
+
+          unless config_nncc.directory?
+            pass!(::I18n.t('rosett_ai.doctor.stale_config_nncc.clean'))
+            return
+          end
+
+          warn_stale(config_nncc)
+        end
+
+        def warn_stale(config_nncc)
+          path_str = config_nncc.to_s
+          remediation = ::I18n.t('rosett_ai.doctor.stale_config_nncc.migrate')
+          children = config_nncc.children
+
+          if children.any?
+            warn!(
+              ::I18n.t('rosett_ai.doctor.stale_config_nncc.found', path: path_str, count: children.count),
+              remediation: remediation
+            )
+          else
+            warn!(
+              ::I18n.t('rosett_ai.doctor.stale_config_nncc.empty', path: path_str),
+              remediation: remediation
+            )
+          end
+        end
+      end
+    end
+  end
+end
+
+RosettAi::Doctor.register(RosettAi::Doctor::Checks::StaleConfigNnccCheck)