rosett-ai 1.3.3 → 1.5.10

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

@@ -33,6 +33,8 @@ module RosettAi
         method_option :check, type: :string, desc: 'Run only the named check'
         method_option :format, type: :string, enum: ['table', 'json'], default: 'table',
                                desc: 'Output format'
+        # Return the current status.
+        # @return [String]
         def status
           validate_check_name!(options[:check]) if options[:check]
           results = RosettAi::Doctor.run_all(only: options[:check])

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

@@ -13,6 +13,7 @@ module RosettAi
     module Tasks
       # Documentation management tasks
       class Documentation < ::Thor
+        # @return [Hash] Terminal color codes for documentation types.
         TYPE_COLORS = {
           lib: :cyan, behaviour: :magenta, dependency: :yellow, reference: :blue
         }.freeze
@@ -53,6 +54,8 @@ module RosettAi
                       default: false,
                       desc: 'Skip LaTeX reference document compilation'
 
+        # Update to the latest version.
+        # @return [void]
         def update
           changes = scan_with_spinner
           return puts Paint[t('no_updates'), :yellow] if changes.empty?
@@ -76,6 +79,8 @@ module RosettAi
 
           Related commands: update, translate
         LONGDESC
+        # Return the current status.
+        # @return [String]
         def status
           display_status_header
           display_doc_files
@@ -107,6 +112,8 @@ module RosettAi
                       required: true,
                       desc: 'Target locale'
 
+        # Translate documentation to the target locale.
+        # @return [void]
         def translate(source_file = nil)
           files = source_file ? [source_file] : Dir.glob(RosettAi.root.join('doc', '*.md'))
 

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

@@ -23,6 +23,8 @@ module RosettAi
 
           Related commands: detect, status, plugins
         LONGDESC
+        # List available items.
+        # @return [void]
         def list
           rows = RosettAi::Engines::Registry.available.map do |name|
             manifest = RosettAi::Engines::Registry.manifest(name)
@@ -51,6 +53,8 @@ module RosettAi
 
           Related commands: list, status, plugins
         LONGDESC
+        # Detect available engines on the system.
+        # @return [Array<Hash>]
         def detect
           rows = RosettAi::Engines::Registry.available.filter_map do |name|
             manifest = RosettAi::Engines::Registry.manifest(name)
@@ -85,6 +89,8 @@ module RosettAi
 
           Related commands: list, detect, plugins
         LONGDESC
+        # Return the current status.
+        # @return [String]
         def status
           default_engine = RosettAi.rai_config.default_engine
           puts "#{t('default_engine')}: #{Rainbow(default_engine).bright}"
@@ -120,6 +126,8 @@ module RosettAi
 
           Related commands: list, detect, status
         LONGDESC
+        # List installed engine plugins.
+        # @return [void]
         def plugins
           plugin_engines = RosettAi::Plugins::Registry.available(:engine)
 

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

@@ -35,6 +35,8 @@ module RosettAi
           Related: hooks uninstall, hooks status
         LONGDESC
         method_option :verbose, type: :boolean, default: false, desc: 'Show detailed output'
+        # Install the component.
+        # @return [void]
         def install
           config = load_hooks_config
           return exit_with_error(t('no_config')) if config.empty?
@@ -61,6 +63,8 @@ module RosettAi
 
           Related: hooks install, hooks status
         LONGDESC
+        # Remove the installed hooks.
+        # @return [void]
         def uninstall
           installer = build_installer({})
           results = installer.uninstall
@@ -81,6 +85,8 @@ module RosettAi
           Related: hooks status, hooks install
         LONGDESC
         method_option :format, type: :string, default: 'table', enum: ['table', 'json'], desc: 'Output format'
+        # List available items.
+        # @return [void]
         def list
           installer = build_installer({})
           hooks = installer.list
@@ -111,6 +117,8 @@ module RosettAi
           Related: hooks install, hooks list
         LONGDESC
         method_option :format, type: :string, default: 'table', enum: ['table', 'json'], desc: 'Output format'
+        # Return the current status.
+        # @return [String]
         def status
           config = load_hooks_config
           installer = RosettAi::GitHooks::Installer.new(

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

@@ -15,6 +15,7 @@ module RosettAi
       class Init < ::Thor
         default_task :setup
 
+        # @return [Array] Default project subdirectory names.
         PROJECT_DIRS = ['conf', 'conf/behaviour', 'conf/design'].freeze
 
         desc 'setup', 'Initialize rai project structure'

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

@@ -31,6 +31,10 @@ module RosettAi
 
           Related commands: status, deactivate
         LONGDESC
+        # Activate a license key.
+        #
+        # @param raw_key [Object] the raw key
+        # @return [void]
         def activate(raw_key)
           key = RosettAi::Licensing::LicenseKey.new(raw_key)
           key.decode
@@ -54,6 +58,8 @@ module RosettAi
 
           Related commands: activate, deactivate
         LONGDESC
+        # Return the current status.
+        # @return [String]
         def status
           result = RosettAi::Licensing::LicenseValidator.new.validate
 
@@ -77,6 +83,8 @@ module RosettAi
 
           Related commands: activate, status
         LONGDESC
+        # Deactivate the current license.
+        # @return [void]
         def deactivate
           store = RosettAi::Licensing::LicenseStore.new
 

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

@@ -7,6 +7,7 @@ require 'terminal-table'
 
 module RosettAi
   module Thor
+    # CLI subcommand task implementations.
     module Tasks
       # Thor CLI for MCP server and administration.
       #
@@ -44,6 +45,8 @@ module RosettAi
         method_option :allow_remote, type: :boolean, default: false, desc: 'Allow non-localhost binding'
         method_option :config, type: :string, desc: 'Path to server config YAML'
         method_option :plugin, type: :array, default: [], desc: 'Plugin names to load'
+        # Start the MCP JSON-RPC server.
+        # @return [void]
         def serve
           server = RosettAi::Mcp::Server.new(
             config_path: options[:config],
@@ -85,6 +88,8 @@ module RosettAi
           Related: mcp status, mcp validate
         LONGDESC
         method_option :format, type: :string, default: 'table', enum: ['table', 'json'], desc: 'Output format'
+        # List available items.
+        # @return [void]
         def list
           registry = build_registry
           servers = registry.list
@@ -112,6 +117,8 @@ module RosettAi
           Related: mcp list, mcp status
         LONGDESC
         method_option :format, type: :string, default: 'table', enum: ['table', 'json'], desc: 'Output format'
+        # Validate the input and return any errors.
+        # @return [Array<Hash>]
         def validate
           registry = build_registry
           validator = RosettAi::Mcp::Admin::SchemaValidator.new
@@ -137,6 +144,8 @@ module RosettAi
           Related: mcp list, mcp validate
         LONGDESC
         method_option :format, type: :string, default: 'table', enum: ['table', 'json'], desc: 'Output format'
+        # Return the current status.
+        # @return [String]
         def status
           registry = build_registry
           checker = RosettAi::Mcp::Admin::HealthChecker.new
@@ -166,6 +175,8 @@ module RosettAi
           Related: mcp validate, mcp status
         LONGDESC
         method_option :format, type: :string, default: 'json', enum: ['table', 'json'], desc: 'Output format'
+        # Run a security audit on MCP configuration.
+        # @return [void]
         def audit
           registry = build_registry
           checker = RosettAi::Mcp::Admin::HealthChecker.new
@@ -192,6 +203,11 @@ module RosettAi
         method_option :transport, type: :string, default: 'stdio',
                                   enum: ['stdio', 'http', 'streamable-http'],
                                   desc: 'Transport type'
+        # Add a new entry.
+        #
+        # @param name [Object] the name
+        # @param uri [Object] the uri
+        # @return [void]
         def add(name, uri)
           installer = build_installer
           result = installer.install(name: name, uri: uri, transport: options[:transport])
@@ -219,6 +235,10 @@ module RosettAi
           Related: mcp add, mcp list
         LONGDESC
         method_option :force, type: :boolean, default: false, desc: 'Force removal of managed servers'
+        # Remove the component.
+        #
+        # @param name [Object] the name
+        # @return [void]
         def remove(name)
           installer = build_installer
           result = installer.remove(name: name, force: options[:force])
@@ -247,6 +267,8 @@ module RosettAi
         LONGDESC
         method_option :format, type: :string, default: 'table', enum: ['table', 'json'], desc: 'Output format'
         map 'trust-sources' => :trust_sources
+        # List trusted MCP sources.
+        # @return [void]
         def trust_sources
           manager = build_trust_manager
           sources = manager.list
@@ -267,6 +289,10 @@ module RosettAi
         LONGDESC
         method_option :description, type: :string, default: 'User-trusted domain', desc: 'Trust source description'
         map 'trust-add' => :trust_add
+        # Add a trusted MCP source.
+        #
+        # @param domain [Object] the domain
+        # @return [void]
         def trust_add(domain)
           manager = build_trust_manager
           manager.add_trust(domain, description: options[:description])
@@ -287,6 +313,10 @@ module RosettAi
           Related: mcp trust-add, mcp trust-sources
         LONGDESC
         map 'trust-remove' => :trust_remove
+        # Remove a trusted MCP source.
+        #
+        # @param domain [Object] the domain
+        # @return [void]
         def trust_remove(domain)
           manager = build_trust_manager
           if manager.remove_trust(domain)
@@ -308,6 +338,8 @@ module RosettAi
 
             raictl mcp tools
         LONGDESC
+        # List registered MCP tools.
+        # @return [void]
         def tools
           server = RosettAi::Mcp::Server.new
           tool_list = server.tools
@@ -334,6 +366,8 @@ module RosettAi
         method_option :name, type: :string, required: true, desc: 'Key name'
         method_option :keyfile, type: :string, default: RosettAi::Mcp::Keyfile::DEFAULT_FILENAME, desc: 'Keyfile path'
         map 'generate-key' => :generate_key
+        # Generate a new MCP API key.
+        # @return [void]
         def generate_key
           path = RosettAi::Mcp::Keyfile.create_if_missing(options[:keyfile])
           plaintext = RosettAi::Mcp::KeyHasher.generate_key
@@ -362,6 +396,8 @@ module RosettAi
         LONGDESC
         method_option :keyfile, type: :string, default: RosettAi::Mcp::Keyfile::DEFAULT_FILENAME, desc: 'Keyfile path'
         map 'list-keys' => :list_keys
+        # List all MCP API keys.
+        # @return [void]
         def list_keys
           path = File.expand_path(options[:keyfile])
           unless File.exist?(path)
@@ -399,6 +435,8 @@ module RosettAi
         method_option :name, type: :string, required: true, desc: 'Key name to revoke'
         method_option :keyfile, type: :string, default: RosettAi::Mcp::Keyfile::DEFAULT_FILENAME, desc: 'Keyfile path'
         map 'revoke-key' => :revoke_key
+        # Revoke an MCP API key.
+        # @return [void]
         def revoke_key
           keyfile = RosettAi::Mcp::Keyfile.new(File.expand_path(options[:keyfile]))
           keyfile.load!
@@ -425,6 +463,8 @@ module RosettAi
         method_option :name, type: :string, required: true, desc: 'Key name to rotate'
         method_option :keyfile, type: :string, default: RosettAi::Mcp::Keyfile::DEFAULT_FILENAME, desc: 'Keyfile path'
         map 'rotate-key' => :rotate_key
+        # Rotate an MCP API key.
+        # @return [void]
         def rotate_key
           keyfile = RosettAi::Mcp::Keyfile.new(File.expand_path(options[:keyfile]))
           keyfile.load!

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

@@ -36,6 +36,8 @@ module RosettAi
         LONGDESC
         option :workspace, type: :string, desc: 'Scan and migrate all .nncc/ dirs under PATH'
         option :dry_run, type: :boolean, default: false, desc: 'Show what would be migrated'
+        # Execute the legacy configuration migration.
+        # @return [void]
         def run_migrate
           migrate_xdg_config
           migrate_projects

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

@@ -16,6 +16,7 @@ module RosettAi
       # @author hugo
       # @author claude
       class Plugins < ::Thor
+        # @return [Array] Set of permitted type values.
         VALID_TYPES = ['engine', 'gui', 'mcp'].freeze
 
         desc 'list TYPE', 'List installed plugins of a given type (engine, gui, mcp)'
@@ -28,6 +29,10 @@ module RosettAi
 
           Related: plugins install, plugins remove, engines list
         LONGDESC
+        # List available items.
+        #
+        # @param type [Object] the type
+        # @return [void]
         def list(type)
           validate_type!(type)
           type_sym = type.to_sym
@@ -58,6 +63,11 @@ module RosettAi
 
           Related: plugins remove, plugins list
         LONGDESC
+        # Install the component.
+        #
+        # @param type [Object] the type
+        # @param name [Object] the name
+        # @return [void]
         def install(type, name)
           validate_type!(type)
           package = plugin_package_name(type, name)
@@ -85,6 +95,11 @@ module RosettAi
 
           Related: plugins install, plugins list
         LONGDESC
+        # Remove the component.
+        #
+        # @param type [Object] the type
+        # @param name [Object] the name
+        # @return [void]
         def remove(type, name)
           validate_type!(type)
           package = plugin_package_name(type, name)

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

@@ -30,6 +30,8 @@ module RosettAi
         LONGDESC
         method_option :format, type: :string, enum: ['table', 'json'], default: 'table',
                                desc: 'Output format'
+        # Return the current status.
+        # @return [String]
         def status
           manager = RosettAi::Project::Manager.new(project_root: resolve_project_root)
           result = manager.status
@@ -50,6 +52,8 @@ module RosettAi
 
             raictl project info
         LONGDESC
+        # Display project information.
+        # @return [void]
         def info
           manager = RosettAi::Project::Manager.new(project_root: resolve_project_root)
           result = manager.info
@@ -114,6 +118,8 @@ module RosettAi
                              desc: 'Drift type to detect (default: both)'
         method_option :format, type: :string, enum: ['table', 'json'], default: 'table',
                                desc: 'Output format'
+        # Check for project configuration drift.
+        # @return [void]
         def drift
           root = resolve_project_root
           validate_project!(root)
@@ -149,6 +155,8 @@ module RosettAi
                               desc: 'Apply breaking changes without prompting'
         method_option :simulate, type: :boolean, default: false,
                                  desc: 'Preview changes without applying'
+        # Synchronize project configuration.
+        # @return [void]
         def sync
           sync_mgr = RosettAi::Project::SyncManager.new(
             project_root: resolve_project_root,

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

@@ -30,6 +30,8 @@ module RosettAi
 
           Related commands: validate, show, log
         LONGDESC
+        # Initialize the provenance file in the current project.
+        # @return [void]
         def init
           store = build_store
           store.init
@@ -55,6 +57,8 @@ module RosettAi
 
           Related commands: init, show, log
         LONGDESC
+        # Validate the input and return any errors.
+        # @return [Array<Hash>]
         def validate
           store = build_store
           data = store.read
@@ -92,6 +96,8 @@ module RosettAi
           Related commands: init, validate, log
         LONGDESC
         method_option :file, type: :string, desc: 'Show provenance for a specific file'
+        # Display detailed information for the named item.
+        # @return [void]
         def show(commit = nil)
           store = build_store
           entries = if options[:file]
@@ -133,6 +139,8 @@ module RosettAi
           Related commands: init, validate, show
         LONGDESC
         method_option :role, type: :string, desc: 'Filter by AI role'
+        # Display the provenance log.
+        # @return [void]
         def log
           store = build_store
           entries = store.read['entries'].reverse

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

@@ -19,8 +19,10 @@ module RosettAi
       #
       # Design reference: conf/design/release_management.yml
       class Release < ::Thor
+        # @return [Array] Allowed release version bump levels.
         VALID_LEVELS = ['major', 'minor', 'patch'].freeze
 
+        # @return [Array] Release verification gate definitions.
         VERIFICATION_GATES = [
           ['rspec',         ['bundle', 'exec', 'rspec', '--format', 'progress']],
           ['rubocop',       ['bundle', 'exec', 'rubocop', '--format', 'simple']],
@@ -51,6 +53,10 @@ module RosettAi
         LONGDESC
         method_option :skip_verify, type: :boolean, default: false,
                                     desc: 'Skip verification suite (NOT recommended)'
+        # Prepare the release artifacts.
+        #
+        # @param level [Object] the level
+        # @return [void]
         def prepare(level)
           validate_level!(level)
           ensure_clean_working_tree!
@@ -108,6 +114,8 @@ module RosettAi
 
           Related commands: prepare, tag
         LONGDESC
+        # Return the current status.
+        # @return [String]
         def status
           version = current_version
           last_tag = latest_tag

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

@@ -38,6 +38,8 @@ module RosettAi
                               desc: 'Overwrite existing Rosett-AI YAML files'
         method_option :simulate, type: :boolean, default: false,
                                  desc: 'Show what would be generated without writing'
+        # Convert native configs to rosett-ai YAML format.
+        # @return [void]
         def convert
           output_dir = resolve_output_dir
           engine = RosettAi::Retrofit::Engine.new(
@@ -54,6 +56,8 @@ module RosettAi
         end
 
         desc 'engines', 'List available retrofit engines'
+        # List available retrofit engine parsers.
+        # @return [void]
         def engines
           available = RosettAi::Retrofit::Engine.available_engines
           if available.empty?

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

@@ -15,6 +15,7 @@ module RosettAi
       class Validate < ::Thor
         default_task :all
 
+        # @return [Array] Validation category names.
         CATEGORIES = [
           { name: 'behaviour', dir: 'conf/behaviour', validator: 'BehaviourValidator' },
           { name: 'design', dir: 'conf/design', validator: 'DesignValidator' },

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

@@ -27,6 +27,8 @@ module RosettAi
 
             raictl workflow list
         LONGDESC
+        # List available items.
+        # @return [void]
         def list
           files = discover_workflows
           if files.empty?
@@ -60,6 +62,10 @@ module RosettAi
 
             raictl workflow validate release
         LONGDESC
+        # Validate the input and return any errors.
+        #
+        # @param name [Object] the name
+        # @return [Array<Hash>]
         def validate(name)
           path = resolve_workflow(name)
           engine = RosettAi::Workflow::Engine.new(workflow_path: path)
@@ -83,6 +89,10 @@ module RosettAi
 
             raictl workflow simulate release
         LONGDESC
+        # Simulate workflow execution without applying changes.
+        #
+        # @param name [Object] the name
+        # @return [void]
         def simulate(name)
           path = resolve_workflow(name)
           engine = RosettAi::Workflow::Engine.new(workflow_path: path)
@@ -113,6 +123,10 @@ module RosettAi
                                desc: 'Resume from last completed step'
         method_option :format, type: :string, enum: ['table', 'json'], default: 'table',
                                desc: 'Output format'
+        # Execute the named workflow.
+        #
+        # @param name [Object] the name
+        # @return [void]
         def execute(name)
           path = resolve_workflow(name)
           audit_path = resolve_audit_log_path(name)

data/lib/rosett_ai/tooling/version_checker.rb

@@ -4,6 +4,7 @@
 # Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
 
 module RosettAi
+  # External tool integration and version checking.
   module Tooling
     # MCP-facing facade for tool version checking.
     #

data/lib/rosett_ai/ui/accessible_tui.rb

@@ -12,10 +12,19 @@ module RosettAi
     # ANSI escape sequences. Auto-selected when assistive technology is
     # detected (ORCA_RUNNING, BRLTTY_TTY).
     class AccessibleTui < Tui
+      # Render content in the UI backend.
+      #
+      # @param content [Object] the content
+      # @return [void]
       def render(content)
         $stdout.puts(RosettAi::TextSanitizer.strip_ansi(String(content)))
       end
 
+      # Render a table in the UI backend.
+      #
+      # @param headers [Object] the headers
+      # @param rows [Object] the rows
+      # @return [void]
       def display_table(headers, rows)
         widths = compute_column_widths(headers, rows)
 
@@ -27,6 +36,10 @@ module RosettAi
         rows.each { |row| $stdout.puts(format_row(row, widths)) }
       end
 
+      # Display a spinner during a long-running operation.
+      #
+      # @param message [Object] the message
+      # @return [void]
       def show_spinner(message)
         $stdout.puts("Processing: #{message}...")
         result = yield
@@ -37,6 +50,11 @@ module RosettAi
         raise e
       end
 
+      # Announce a message to the user via the UI backend.
+      #
+      # @param message [Object] the message
+      # @param priority [Object] the priority
+      # @return [void]
       def announce(message, priority: :polite)
         prefix = priority == :assertive ? '[ASSERTIVE]' : '[POLITE]'
         warn("#{prefix} #{message}")

data/lib/rosett_ai/ui/base.rb

@@ -11,6 +11,7 @@ module RosettAi
     # implement the required methods. The shared example
     # 'a UI implementation' verifies conformance.
     class Base
+      # @return [Array] Rtl locales constant.
       RTL_LOCALES = ['ar', 'he', 'fa', 'ur'].freeze
 
       def render(content)
@@ -37,6 +38,8 @@ module RosettAi
         ENV.key?('ORCA_RUNNING') || ENV.key?('BRLTTY_TTY')
       end
 
+      # Return the text direction for the current locale.
+      # @return [Symbol]
       def text_direction(locale = nil)
         lang = locale || ENV.fetch('LANG', 'en')[0, 2]
         RTL_LOCALES.include?(lang) ? :rtl : :ltr

data/lib/rosett_ai/ui/gtk4.rb

@@ -15,6 +15,7 @@ module RosettAi
     # Methods raise RosettAi::Error with install instructions if the gem
     # is not available at runtime.
     class Gtk4 < Base
+      # @return [String] Error message when the UI backend is not available.
       UNAVAILABLE_MESSAGE = 'GTK4 adapter requires the gtk4 gem. Install: gem install gtk4'
 
       def self.available?
@@ -24,6 +25,10 @@ module RosettAi
         false
       end
 
+      # Render content in the UI backend.
+      #
+      # @param content [Object] the content
+      # @return [void]
       def render(content)
         require_gtk4!
         text_view = ::Gtk::TextView.new
@@ -32,6 +37,11 @@ module RosettAi
         text_view
       end
 
+      # Render a table in the UI backend.
+      #
+      # @param headers [Object] the headers
+      # @param rows [Object] the rows
+      # @return [void]
       def display_table(headers, rows)
         require_gtk4!
         store = build_list_store(headers.length)
@@ -49,6 +59,10 @@ module RosettAi
         dialog
       end
 
+      # Display a spinner during a long-running operation.
+      #
+      # @param _message [Object] the  message
+      # @return [void]
       def show_spinner(_message)
         require_gtk4!
         spinner = ::Gtk::Spinner.new
@@ -58,6 +72,11 @@ module RosettAi
         result
       end
 
+      # Announce a message to the user via the UI backend.
+      #
+      # @param message [Object] the message
+      # @param priority [Object] the priority
+      # @return [void]
       def announce(message, priority: :polite)
         warn("[GTK4:#{priority}] #{message}")
       end

data/lib/rosett_ai/ui/kde.rb

@@ -12,6 +12,7 @@ module RosettAi
     # KDE integration requires Qt6 bindings which do not exist for Ruby.
     # This adapter serves as a placeholder for the rosett-ai-kde package concept.
     class Kde < Base
+      # @return [String] Error message when the UI backend is not available.
       UNAVAILABLE_MESSAGE = 'KDE adapter not available — Ruby Qt6/KDE bindings do not exist. Use GTK4 or TUI.'
 
       def render(_content)

data/lib/rosett_ai/ui/qt6.rb

@@ -12,6 +12,7 @@ module RosettAi
     # Ruby Qt6 bindings do not exist (qtbindings is unmaintained, Qt4-only).
     # This adapter serves as a placeholder for the rosett-ai-qt6 package concept.
     class Qt6 < Base
+      # @return [String] Error message when the UI backend is not available.
       UNAVAILABLE_MESSAGE = 'Qt6 adapter not available — Ruby Qt6 bindings do not exist. Use GTK4 or TUI.'
 
       def render(_content)