rosett-ai 1.3.3

data/lib/rosett_ai/thor/tasks/doctor.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'terminal-table'
+
+module RosettAi
+  module Thor
+    module Tasks
+      # CLI task for `rai doctor` — runtime diagnostics.
+      #
+      # @author hugo
+      # @author claude
+      class Doctor < ::Thor
+        default_task :status
+
+        desc 'status', 'Run all diagnostic checks'
+        long_desc <<~LONGDESC
+          Runs all registered diagnostic checks and displays a summary.
+
+          Checks include Ruby version, gem dependencies, file permissions,
+          D-Bus availability, engine detection, and cache health.
+
+          Exit codes: 0 = all pass, 1 = any warn, 2 = any fail.
+
+          EXAMPLES
+
+            raictl doctor
+            raictl doctor --check ruby_version
+            raictl doctor --format json
+        LONGDESC
+        method_option :check, type: :string, desc: 'Run only the named check'
+        method_option :format, type: :string, enum: ['table', 'json'], default: 'table',
+                               desc: 'Output format'
+        def status
+          validate_check_name!(options[:check]) if options[:check]
+          results = RosettAi::Doctor.run_all(only: options[:check])
+
+          if options[:format] == 'json'
+            print_json(results)
+          else
+            print_header
+            print_table_output(results)
+            print_summary(results)
+          end
+
+          code = RosettAi::Doctor.exit_code(results)
+          exit code unless code.zero?
+        end
+
+        private
+
+        def validate_check_name!(name)
+          return if RosettAi::Doctor.check_names.include?(name)
+
+          raise ::Thor::Error,
+                "Unknown check '#{name}'. Available: #{RosettAi::Doctor.check_names.join(', ')}"
+        end
+
+        def t(key, **args)
+          ::I18n.t("rosett_ai.doctor.#{key}", **args)
+        end
+
+        def print_header
+          say "raictl #{RosettAi::VERSION} | Ruby #{RUBY_VERSION} | #{RUBY_PLATFORM}"
+          say ''
+        end
+
+        def print_table_output(results)
+          table = ::Terminal::Table.new(
+            headings: [t('header.check'), t('header.status'), t('header.details')],
+            rows: results.map { |r| build_row(r) }
+          )
+          say table
+          say ''
+        end
+
+        def build_row(result)
+          status_text = format_status(result[:status])
+          detail = result[:message]
+          detail = "#{detail}\n  #{result[:remediation]}" if result[:remediation]
+          [result[:name], status_text, detail]
+        end
+
+        def format_status(status)
+          case status
+          when 'pass' then Rainbow('PASS').green
+          when 'warn' then Rainbow('WARN').yellow
+          when 'fail' then Rainbow('FAIL').red
+          else status.upcase
+          end
+        end
+
+        def print_summary(results)
+          counts = results.group_by { |r| r[:status] }.transform_values(&:size)
+          total = results.size
+          warn_count = counts.fetch('warn', 0)
+          fail_count = counts.fetch('fail', 0)
+
+          if fail_count.positive?
+            say Rainbow(t('summary.failures', total: total, fail: fail_count)).red
+          elsif warn_count.positive?
+            say Rainbow(t('summary.warnings', total: total, warn: warn_count)).yellow
+          else
+            say Rainbow(t('summary.all_pass', total: total)).green
+          end
+        end
+
+        def print_json(results)
+          output = {
+            rai_version: RosettAi::VERSION,
+            ruby_version: RUBY_VERSION,
+            platform: RUBY_PLATFORM,
+            checks: results,
+            summary: {
+              pass: results.count { |r| r[:status] == 'pass' },
+              warn: results.count { |r| r[:status] == 'warn' },
+              fail: results.count { |r| r[:status] == 'fail' }
+            }
+          }
+          say JSON.generate(output)
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/thor/tasks/documentation.rb

@@ -0,0 +1,321 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'thor'
+require 'tty-spinner'
+require 'paint'
+require 'pathname'
+
+module RosettAi
+  module Thor
+    module Tasks
+      # Documentation management tasks
+      class Documentation < ::Thor
+        TYPE_COLORS = {
+          lib: :cyan, behaviour: :magenta, dependency: :yellow, reference: :blue
+        }.freeze
+        desc 'update', 'Update documentation based on code/config changes'
+        long_desc <<~LONGDESC
+          Scans the codebase for undocumented changes and updates documentation files accordingly.
+          Checks for new/changed methods, behaviour files, dependencies, and LaTeX reference documents.
+
+          Flags:
+            --locale: Target locale for documentation (default: en)
+            --all-locales: Update documentation for all configured locales
+            --dry-run: Show what would be updated without making changes
+            --skip-reference: Skip LaTeX reference document compilation
+
+          EXAMPLES
+
+            raictl documentation update
+            raictl documentation update --dry-run
+            raictl documentation update --all-locales
+            raictl documentation update --locale fr --skip-reference
+
+          Related commands: status, translate
+        LONGDESC
+        method_option :locale,
+                      type: :string,
+                      default: 'en',
+                      desc: 'Target locale for documentation'
+        method_option :all_locales,
+                      type: :boolean,
+                      default: false,
+                      desc: 'Update documentation for all configured locales'
+        method_option :dry_run,
+                      type: :boolean,
+                      default: false,
+                      desc: 'Show what would be updated without making changes'
+        method_option :skip_reference,
+                      type: :boolean,
+                      default: false,
+                      desc: 'Skip LaTeX reference document compilation'
+
+        def update
+          changes = scan_with_spinner
+          return puts Paint[t('no_updates'), :yellow] if changes.empty?
+
+          display_changes(changes)
+          return if options[:dry_run]
+
+          reference_changes, locale_changes = changes.partition { |change| change[:type] == :reference }
+          reference_changes.each { |_change| compile_reference_document! }
+          apply_changes_with_spinner(locale_changes) unless locale_changes.empty?
+        end
+
+        desc 'status', 'Show documentation status and coverage'
+        long_desc <<~LONGDESC
+          Displays documentation file count, last modified timestamps, and configured locales.
+          Provides an overview of the current documentation state without making changes.
+
+          EXAMPLES
+
+            raictl documentation status
+
+          Related commands: update, translate
+        LONGDESC
+        def status
+          display_status_header
+          display_doc_files
+          display_configured_locales
+        end
+
+        desc 'translate', 'Translate documentation files'
+        long_desc <<~LONGDESC
+          Translates documentation files from one locale to another.
+          If no source file is specified, translates all markdown files in the doc/ directory.
+
+          Flags:
+            --from: Source locale (default: en)
+            --to: Target locale (required)
+
+          EXAMPLES
+
+            raictl documentation translate --to fr
+            raictl documentation translate doc/README.md --from en --to ar
+
+          Related commands: update, status
+        LONGDESC
+        method_option :from,
+                      type: :string,
+                      default: 'en',
+                      desc: 'Source locale'
+        method_option :to,
+                      type: :string,
+                      required: true,
+                      desc: 'Target locale'
+
+        def translate(source_file = nil)
+          files = source_file ? [source_file] : Dir.glob(RosettAi.root.join('doc', '*.md'))
+
+          translator = RosettAi::Documentation::Translator.new
+
+          files.each do |file|
+            unless File.exist?(file)
+              puts Rainbow(t('translate_source_missing', path: file)).red
+              next
+            end
+
+            result = translator.translate(file, from: options[:from], to: options[:to])
+            puts Rainbow(t('translate_done', path: result)).green
+          end
+        end
+
+        private
+
+        def t(key, **)
+          ::I18n.t("rosett_ai.cli.documentation.#{key}", **)
+        end
+
+        def scan_with_spinner
+          spinner = TTY::Spinner.new('[:spinner] Scanning for changes...', format: :dots)
+          spinner.auto_spin
+          changes = scan_for_changes
+          spinner.success(Paint[t('scan_complete'), :green])
+          changes
+        end
+
+        def apply_changes_with_spinner(changes)
+          spinner = TTY::Spinner.new("[:spinner] #{t('updating')}", format: :dots)
+          spinner.auto_spin
+          apply_changes(changes)
+          spinner.success(Paint[t('done'), :green])
+        end
+
+        def display_status_header
+          puts Paint[t('status_title'), :bright]
+          puts '-' * 40
+        end
+
+        def display_doc_files
+          doc_files = Dir.glob(RosettAi.root.join('doc', '*.md'))
+          puts t('doc_files', count: doc_files.count)
+          doc_files.each { |file| display_doc_file_info(file) }
+        end
+
+        def display_doc_file_info(file)
+          basename = File.basename(file)
+          mtime = File.mtime(file).strftime('%Y-%m-%d %H:%M')
+          puts "  #{Paint[basename, :cyan]}: #{mtime}"
+        end
+
+        def display_configured_locales
+          locale_dirs = Dir.glob(RosettAi.root.join('doc', 'locales', '*'))
+          puts "\n#{t('configured_locales', count: locale_dirs.count)}"
+          locale_dirs.each { |dir| puts "  #{Paint[File.basename(dir), :cyan]}" }
+        end
+
+        def scan_for_changes
+          changes = []
+
+          # Scan for new/changed configuration options in lib/
+          changes.concat(scan_lib_changes)
+
+          # Scan for new behaviour files
+          changes.concat(scan_behaviour_changes)
+
+          # Scan for dependency changes
+          changes.concat(scan_dependency_changes)
+
+          # Scan for stale LaTeX reference document
+          changes.concat(scan_reference_changes)
+
+          changes
+        end
+
+        def scan_lib_changes
+          changes = []
+          lib_files = Dir.glob(RosettAi.root.join('lib', '**', '*.rb'))
+
+          lib_files.each do |file|
+            # Check for undocumented public methods
+            content = File.read(file)
+            if content.match?(/^\s*def\s+[^_]/) && !documented?(file)
+              changes << { type: :lib, file: file, reason: t('undocumented') }
+            end
+          end
+
+          changes
+        end
+
+        def scan_behaviour_changes
+          changes = []
+          behaviour_files = Dir.glob(RosettAi.conf_root.join('conf', 'behaviour', '*.yml'))
+          doc_file = RosettAi.root.join('doc', 'BEHAVIOUR.md')
+
+          return changes unless doc_file.exist?
+
+          doc_content = doc_file.read
+          behaviour_files.each do |file|
+            basename = File.basename(file, '.yml')
+            unless doc_content.include?(basename)
+              changes << { type: :behaviour, file: file, reason: t('not_in_behaviour_md') }
+            end
+          end
+
+          changes
+        end
+
+        def scan_dependency_changes
+          changes = []
+          gemfile = RosettAi.root.join('Gemfile')
+          doc_file = RosettAi.root.join('doc', 'SETUP.md')
+
+          return changes unless gemfile.exist? && doc_file.exist?
+
+          if gemfile.mtime > doc_file.mtime
+            changes << { type: :dependency, file: gemfile.to_s, reason: t('gemfile_newer') }
+          end
+
+          changes
+        end
+
+        def scan_reference_changes
+          changes = []
+          return changes if options[:skip_reference]
+
+          compiler = RosettAi::Documentation::ReferenceCompiler.new
+          return changes unless compiler.source_dir.exist?
+
+          if !compiler.output_path.exist?
+            changes << { type: :reference, file: compiler.output_path.to_s,
+                         reason: t('reference.missing') }
+          elsif compiler.stale?
+            changes << { type: :reference, file: compiler.output_path.to_s,
+                         reason: t('reference.stale') }
+          end
+
+          changes
+        end
+
+        def compile_reference_document!
+          compiler = RosettAi::Documentation::ReferenceCompiler.new
+
+          unless compiler.available?
+            puts Paint[t('reference.tools_missing', tools: compiler.missing_tools.join(', ')), :yellow]
+            return
+          end
+
+          spinner = TTY::Spinner.new("[:spinner] #{t('reference.compiling')}", format: :dots)
+          spinner.auto_spin
+          compiler.compile!
+          spinner.success(Paint[t('reference.compiled', path: compiler.output_path), :green])
+        end
+
+        def documented?(file)
+          content = File.read(file)
+          # Simple heuristic: check for YARD-style documentation
+          content.match?(/^\s*#\s*@|^\s*# [A-Z]/)
+        end
+
+        def display_changes(changes)
+          puts Paint["\n#{t('pending_updates')}", :bright]
+          changes.each do |change|
+            type_color = TYPE_COLORS[change[:type]]
+            puts "  [#{Paint[change[:type].to_s.upcase, type_color]}] #{change[:file]}"
+            puts "    Reason: #{change[:reason]}"
+          end
+          puts
+        end
+
+        def apply_changes(changes)
+          target_locales.each do |locale|
+            changes.each { |change| apply_single_change(change, locale) }
+          end
+        end
+
+        def target_locales
+          options[:all_locales] ? available_locales : [options[:locale]]
+        end
+
+        def apply_single_change(change, locale)
+          case change[:type]
+          when :lib then update_api_documentation(change[:file], locale)
+          when :behaviour then update_behaviour_documentation(change[:file], locale)
+          when :dependency then update_setup_documentation(locale)
+          end
+        end
+
+        def available_locales
+          locale_dirs = Dir.glob(RosettAi.root.join('doc', 'locales', '*'))
+          locales = locale_dirs.map { |dir| File.basename(dir) }
+          locales.empty? ? ['en'] : locales
+        end
+
+        def update_api_documentation(file, locale)
+          puts "  [not yet implemented] #{t('updating_api', file: File.basename(file), target_locale: locale)}"
+        end
+
+        def update_behaviour_documentation(file, locale)
+          puts "  [not yet implemented] #{t('updating_behaviour', file: File.basename(file), target_locale: locale)}"
+        end
+
+        def update_setup_documentation(locale)
+          puts "  [not yet implemented] #{t('updating_setup', target_locale: locale)}"
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/thor/tasks/engines.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'thor'
+require 'terminal-table'
+require 'rainbow'
+
+module RosettAi
+  module Thor
+    module Tasks
+      # Thor task for engine detection and management
+      class Engines < ::Thor
+        desc 'list', 'List all known engines'
+        long_desc <<~LONGDESC
+          Lists all engines registered in the Rosett-AI ecosystem.
+          Displays engine name, display name, and version in a formatted table.
+
+          EXAMPLES
+
+            raictl engines list
+
+          Related commands: detect, status, plugins
+        LONGDESC
+        def list
+          rows = RosettAi::Engines::Registry.available.map do |name|
+            manifest = RosettAi::Engines::Registry.manifest(name)
+            [manifest['name'], manifest['display_name'], manifest['version']]
+          rescue StandardError => e
+            [name, Rainbow("error: #{e.message}").red, '?']
+          end
+
+          table = ::Terminal::Table.new(
+            title: Rainbow(t('list_title')).bright,
+            headings: [t('name'), t('display_name'), t('version')],
+            rows: rows,
+            style: { border: :unicode_round }
+          )
+          puts table
+        end
+
+        desc 'detect', 'Detect installed engines on this system'
+        long_desc <<~LONGDESC
+          Runs detection checks for all engines that have a detector component.
+          Shows which engines are installed and available on the current system.
+
+          EXAMPLES
+
+            raictl engines detect
+
+          Related commands: list, status, plugins
+        LONGDESC
+        def detect
+          rows = RosettAi::Engines::Registry.available.filter_map do |name|
+            manifest = RosettAi::Engines::Registry.manifest(name)
+            next unless manifest.dig('components', 'detector')
+
+            result = build_detector(name).detect
+            result[:checks].map do |check|
+              status = check[:passed] ? Rainbow(t('found')).green : Rainbow(t('not_found')).red
+              [result[:display_name], check[:type], check[:name], status]
+            end
+          rescue StandardError => e
+            [[name, 'manifest', '-', Rainbow("error: #{e.message}").red]]
+          end.flatten(1)
+
+          table = ::Terminal::Table.new(
+            title: Rainbow(t('detect_title')).bright,
+            headings: [t('engine'), t('check_type'), t('check_name'), t('status')],
+            rows: rows,
+            style: { border: :unicode_round }
+          )
+          puts table
+        end
+
+        desc 'status', 'Show default engine and detection status'
+        long_desc <<~LONGDESC
+          Displays the currently configured default engine and detection status for all engines.
+          Shows which engines are detected and which one is set as default.
+
+          EXAMPLES
+
+            raictl engines status
+
+          Related commands: list, detect, plugins
+        LONGDESC
+        def status
+          default_engine = RosettAi.rai_config.default_engine
+          puts "#{t('default_engine')}: #{Rainbow(default_engine).bright}"
+          puts
+
+          rows = RosettAi::Engines::Registry.available.map do |name|
+            manifest = RosettAi::Engines::Registry.manifest(name)
+            detected = if manifest.dig('components', 'detector')
+                         result = build_detector(name).detect
+                         result[:detected] ? Rainbow(t('yes')).green : Rainbow(t('no')).red
+                       else
+                         Rainbow(t('no_detector')).yellow
+                       end
+            is_default = name == default_engine ? Rainbow(t('yes')).green : t('no')
+            [manifest['display_name'], detected, is_default]
+          rescue StandardError => e
+            [name, Rainbow("error: #{e.message}").red, '?']
+          end
+
+          table = ::Terminal::Table.new(
+            title: Rainbow(t('status_title')).bright,
+            headings: [t('engine'), t('detected'), t('default')],
+            rows: rows,
+            style: { border: :unicode_round }
+          )
+          puts table
+        end
+
+        desc 'plugins', 'Show registered plugin engines'
+        long_desc <<~LONGDESC
+          Lists all third-party plugin engines registered in the Rosett-AI plugin system.
+          Shows plugin name, display name, and version in a formatted table.
+
+          Related commands: list, detect, status
+        LONGDESC
+        def plugins
+          plugin_engines = RosettAi::Plugins::Registry.available(:engine)
+
+          if plugin_engines.empty?
+            puts Rainbow(t('no_plugins')).yellow
+            return
+          end
+
+          rows = plugin_engines.map do |name|
+            plugin = RosettAi::Plugins::Registry.plugin_module(:engine, name)
+            version = plugin.respond_to?(:version) ? plugin.version : '?'
+            display = plugin.respond_to?(:display_name) ? plugin.display_name : name
+            [name, display, version]
+          end
+
+          table = ::Terminal::Table.new(
+            title: Rainbow(t('plugins_title')).bright,
+            headings: [t('name'), t('display_name'), t('version')],
+            rows: rows,
+            style: { border: :unicode_round }
+          )
+          puts table
+        end
+
+        private
+
+        def t(key, **)
+          ::I18n.t("rosett_ai.cli.engines.#{key}", **)
+        end
+
+        def build_detector(name)
+          manifest = RosettAi::Engines::Registry.manifest(name)
+          engine_mod = RosettAi::Engines::Registry.engine_module(name)
+          detector_klass = engine_mod.detector_class
+
+          if manifest.dig('components', 'detector') && detector_klass
+            detector_klass.new(name)
+          else
+            RosettAi::Engines::Detector.new(name)
+          end
+        end
+      end
+    end
+  end
+end