rosett-ai 1.3.3 → 1.5.9

data/lib/rosett_ai/retrofit/parsers/agents_md_parser.rb

@@ -14,10 +14,14 @@ module RosettAi
       # @author hugo
       # @author claude
       class AgentsMdParser < BaseParser
+        # Return the engine identifier string.
+        # @return [String]
         def engine_name
           'agents_md'
         end
 
+        # Discover native config files for this engine.
+        # @return [Array<String>]
         def discover
           project_root = Pathname.new(ENV.fetch('RAI_ORIGINAL_PWD', Dir.pwd))
           agents_md = project_root.join('AGENTS.md')
@@ -27,6 +31,10 @@ module RosettAi
           []
         end
 
+        # Parse a native config file into rosett-ai format.
+        #
+        # @param path [Object] the path
+        # @return [Hash]
         def parse(path)
           validate_path!(path)
           content = File.read(path)

data/lib/rosett_ai/retrofit/parsers/claude_parser.rb

@@ -7,6 +7,7 @@ require 'json'
 
 module RosettAi
   module Retrofit
+    # Engine-specific native config parsers.
     module Parsers
       # Retrofit parser for Claude Code configuration files.
       #
@@ -16,14 +17,19 @@ module RosettAi
       # @author hugo
       # @author claude
       class ClaudeParser < BaseParser
+        # @return [Array] Configuration keys recognized by this parser.
         KNOWN_KEYS = [
           'permissions', 'allowedTools', 'deniedTools', 'trustedTools', 'env', 'hooks', 'mcpServers', 'customApiKeyResponses', 'contextProviders', 'preferences'
         ].freeze
 
+        # Return the engine identifier string.
+        # @return [String]
         def engine_name
           'claude'
         end
 
+        # Discover native config files for this engine.
+        # @return [Array<String>]
         def discover
           paths = []
           global = Pathname.new(Dir.home).join('.claude', 'settings.json')
@@ -35,6 +41,10 @@ module RosettAi
           paths
         end
 
+        # Parse a native config file into rosett-ai format.
+        #
+        # @param path [Object] the path
+        # @return [Hash]
         def parse(path)
           validate_path!(path)
           content = File.read(path)

data/lib/rosett_ai/retrofit/parsers/cursor_parser.rb

@@ -16,14 +16,19 @@ module RosettAi
       # @author hugo
       # @author claude
       class CursorParser < BaseParser
+        # @return [Array] Configuration keys recognized by this parser.
         KNOWN_KEYS = [
           'rules', 'model', 'temperature', 'maxTokens', 'contextFiles', 'ignoreFiles'
         ].freeze
 
+        # Return the engine identifier string.
+        # @return [String]
         def engine_name
           'cursor'
         end
 
+        # Discover native config files for this engine.
+        # @return [Array<String>]
         def discover
           paths = []
           project_root = Pathname.new(ENV.fetch('RAI_ORIGINAL_PWD', Dir.pwd))
@@ -37,6 +42,10 @@ module RosettAi
           paths
         end
 
+        # Parse a native config file into rosett-ai format.
+        #
+        # @param path [Object] the path
+        # @return [Hash]
         def parse(path)
           validate_path!(path)
 

data/lib/rosett_ai/retrofit/secret_detector.rb

@@ -14,6 +14,7 @@ module RosettAi
     # @author hugo
     # @author claude
     class SecretDetector
+      # @return [Array] Regex patterns matching sensitive configuration keys.
       SENSITIVE_KEY_PATTERNS = [
         /api[_-]?key/i,
         /secret/i,
@@ -24,8 +25,10 @@ module RosettAi
         /private[_-]?key/i
       ].freeze
 
+      # @return [Array] String prefixes indicating a secret value.
       SECRET_VALUE_PREFIXES = ['sk-', 'pk-', 'ghp_', 'gho_', 'ghs_', 'github_pat_', 'xoxb-', 'xoxp-'].freeze
 
+      # @return [Integer] Minimum string length to consider as a potential secret.
       MIN_SECRET_LENGTH = 20
 
       # @param warnings [Array<String>] mutable array for warning messages

data/lib/rosett_ai/secrets_resolver.rb

@@ -8,6 +8,7 @@ module RosettAi
   # Resolution order: ENV variable > secrets file (0600).
   # System keyring support planned for GUI phase (P3).
   module SecretsResolver
+    # @return [Object] File permission mode for secrets files.
     SAFE_PERMISSIONS = 0o600
 
     module_function

data/lib/rosett_ai/session_hooks/installer.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'json'
+require 'fileutils'
+
+module RosettAi
+  module SessionHooks
+    # Idempotently wires a Ruby script into the Claude Code settings.json
+    # SessionStart and PostToolUse hook sections.
+    #
+    # The installer reads the settings file, appends a new hook block if the
+    # target command is not already present, and atomically writes the result.
+    # A second install call is a no-op.
+    #
+    # @example
+    #   installer = RosettAi::SessionHooks::Installer.new(
+    #     script_path: '/path/to/write_heartbeat.rb'
+    #   )
+    #   result = installer.install
+    #   result[:modified_types] #=> ["SessionStart", "PostToolUse"]
+    #
+    # @author hugo
+    # @author claude
+    class Installer
+      # Default path to the global Claude Code settings file.
+      SETTINGS_PATH = File.expand_path('~/.claude/settings.json').freeze
+
+      # Hook event types that receive the heartbeat hook.
+      HOOK_TYPES = ['SessionStart', 'PostToolUse'].freeze
+
+      # @param script_path [String] absolute path to the Ruby hook script
+      # @param timeout [Integer] hook timeout in seconds
+      # @param settings_path [String] path to settings.json (injectable for tests)
+      def initialize(script_path:, timeout: 5, settings_path: SETTINGS_PATH)
+        @script_path  = script_path.to_s
+        @timeout      = Integer(timeout)
+        @settings_path = settings_path.to_s
+      end
+
+      # Install the hook into SessionStart and PostToolUse if not already present.
+      #
+      # @return [Hash] result with keys :modified_types and :already_present_types
+      # @raise [RosettAi::SessionHooksError] if settings file cannot be read or written
+      def install
+        settings = load_settings
+        modified, already_present = classify_hooks(settings)
+        write_settings(settings) unless modified.empty?
+        { modified_types: modified, already_present_types: already_present }
+      end
+
+      # Check whether the hook is present in all required event types.
+      #
+      # @return [Boolean]
+      def installed?
+        settings = load_settings
+        HOOK_TYPES.all? { |ht| hook_present?(settings, ht) }
+      end
+
+      private
+
+      # @return [Array<Array>] [modified_types, already_present_types]
+      def classify_hooks(settings)
+        modified = []
+        already_present = []
+        HOOK_TYPES.each do |hook_type|
+          if hook_present?(settings, hook_type)
+            already_present << hook_type
+          else
+            inject_hook(settings, hook_type)
+            modified << hook_type
+          end
+        end
+        [modified, already_present]
+      end
+
+      # @return [Hash] parsed settings.json; empty hash if file absent
+      def load_settings
+        return {} unless File.exist?(@settings_path)
+
+        JSON.parse(File.read(@settings_path))
+      rescue JSON::ParserError => e
+        raise RosettAi::SessionHooksError, "Failed to parse #{@settings_path}: #{e.message}"
+      rescue SystemCallError => e
+        raise RosettAi::SessionHooksError, "Failed to read #{@settings_path}: #{e.message}"
+      end
+
+      # Atomically persist modified settings via tmp → rename.
+      def write_settings(settings)
+        content = JSON.pretty_generate(settings)
+        tmp = "#{@settings_path}.tmp"
+        FileUtils.mkdir_p(File.dirname(@settings_path))
+        File.write(tmp, content)
+        File.rename(tmp, @settings_path)
+      rescue SystemCallError => e
+        raise RosettAi::SessionHooksError, "Failed to write #{@settings_path}: #{e.message}"
+      end
+
+      # The hook entry object for the command.
+      def hook_entry
+        { 'type' => 'command', 'command' => command_string, 'timeout' => @timeout }
+      end
+
+      # The shell command string identifying this hook in settings.
+      def command_string
+        "ruby #{@script_path}"
+      end
+
+      # Returns true if any existing hook block in hook_type already has this command.
+      def hook_present?(settings, hook_type)
+        blocks = settings.dig('hooks', hook_type) || []
+        blocks.any? { |block| block_has_command?(block) }
+      end
+
+      # Returns true if the given hook block contains the target command.
+      def block_has_command?(block)
+        (block['hooks'] || []).any? { |h| h['command'] == command_string }
+      end
+
+      # Appends a new hook block containing the hook entry to the given event type.
+      def inject_hook(settings, hook_type)
+        hooks = settings['hooks'] ||= {}
+        hooks[hook_type] ||= []
+        hooks[hook_type] << { 'hooks' => [hook_entry] }
+      end
+    end
+  end
+end

data/lib/rosett_ai/smart_feedback/suggester.rb

@@ -4,6 +4,7 @@
 # Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
 
 module RosettAi
+  # Intelligent CLI command and flag suggestions.
   module SmartFeedback
     # Provides "Did you mean?" suggestions using Levenshtein distance.
     #
@@ -14,8 +15,11 @@ module RosettAi
     # @author hugo
     # @author claude
     class Suggester
+      # @return [Integer] Maximum number of feedback suggestions to show.
       MAX_SUGGESTIONS = 3
+      # @return [Integer] Minimum similarity score for command suggestions.
       COMMAND_THRESHOLD = 2
+      # @return [Integer] Minimum similarity score for flag suggestions.
       FLAG_THRESHOLD = 3
 
       # Find suggestion matches for a given input.

data/lib/rosett_ai/smart_feedback/thor_middleware.rb

@@ -23,6 +23,13 @@ module RosettAi
 
       # Prepended module that wraps Thor command dispatch with smart feedback.
       module CommandDispatch
+        # Dispatch a Thor command with smart feedback middleware.
+        #
+        # @param meth [Object] the meth
+        # @param given_args [Object] the given args
+        # @param given_opts [Object] the given opts
+        # @param config [Object] the config
+        # @return [Object]
         def dispatch(meth, given_args, given_opts, config)
           super
         rescue ::Thor::UndefinedCommandError => e

data/lib/rosett_ai/structured_logger.rb

@@ -27,6 +27,7 @@ module RosettAi
   # @author hugo
   # @author claude
   class StructuredLogger < ::Logger
+    # @return [Array] Supported structured log output formats.
     VALID_FORMATS = ['text', 'json'].freeze
 
     # @return [String] correlation ID for the current invocation (UUID v4)

data/lib/rosett_ai/telemetry/log_rotator.rb

@@ -14,6 +14,7 @@ module RosettAi
     # @author claude
     class LogRotator
       DEFAULT_MAX_SIZE  = 10 * 1024 * 1024 # 10 MB
+      # @return [Integer] Default maximum number of log files to retain.
       DEFAULT_MAX_FILES = 5
 
       # @return [String] path to the log file

data/lib/rosett_ai/telemetry.rb

@@ -13,6 +13,7 @@ module RosettAi
   # @author claude
   # @see conf/design/monitoring_observability.yml
   module Telemetry
+    # @return [Array] Supported level values.
     LEVELS = ['debug', 'info', 'warn', 'error'].freeze
 
     # @return [Boolean] true if telemetry is enabled via environment variable

data/lib/rosett_ai/thor/cli.rb

@@ -7,9 +7,11 @@ require 'thor'
 require 'rainbow'
 
 module RosettAi
+  # Thor CLI command framework and task definitions.
   module Thor
     # Main CLI entry point for Rosett-AI commands
     class CLI < ::Thor
+      # @return [Array] Thor commands excluded from user-facing help.
       INTERNAL_COMMANDS = ['build', 'release', 'documentation', 'dbus', 'desktop'].freeze
 
       def self.exit_on_failure?
@@ -89,6 +91,8 @@ module RosettAi
       end
 
       desc 'version', 'Display rosett-ai version'
+      # Return the version string.
+      # @return [String]
       def version
         puts ::I18n.t('rosett_ai.cli.version', version: RosettAi::VERSION)
         build_info = RosettAi.root.join('..', 'etc', 'BUILD_INFO')
@@ -146,6 +150,9 @@ module RosettAi
       desc 'config SUBCOMMAND', 'Compile and inspect AI tool configurations'
       subcommand 'config', RosettAi::Thor::Tasks::Config
 
+      desc 'backfill-user-yml', 'Backfill user.yml from ~/.claude/settings.json'
+      subcommand 'backfill-user-yml', RosettAi::Thor::Tasks::BackfillUserYml
+
       desc 'tooling SUBCOMMAND', 'Validate CI/CD files and check version consistency'
       subcommand 'tooling', RosettAi::Thor::Tasks::Tooling
 
@@ -195,6 +202,8 @@ module RosettAi
       subcommand 'plugins', RosettAi::Thor::Tasks::Plugins
 
       desc 'tree', 'Print a tree of all available commands'
+      # Display the CLI command tree.
+      # @return [void]
       def tree
         say 'rai', :blue
         leaves, groups = tree_partition_entries(self.class)

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

@@ -56,6 +56,8 @@ module RosettAi
                       default: false,
                       desc: 'Run analysis across all available engines (requires --api)'
 
+        # Perform analysis on the given files.
+        # @return [Hash]
         def analyze
           adopter = build_adopter
           files = adopter.discover_managed_files

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

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'thor'
+require 'json'
+require 'rainbow'
+
+module RosettAi
+  module Thor
+    module Tasks
+      # Backfill user.yml from the live Claude Code settings.json.
+      #
+      # Reads ~/.claude/settings.json and merges any permission entries or env vars
+      # not yet covered by the engine's user.yml source file. Shows a summary and
+      # prompts for confirmation before writing — never auto-applies unless --yes is
+      # given. Idempotent: re-running when nothing is uncovered is a no-op.
+      class BackfillUserYml < ::Thor
+        default_task :backfill
+
+        SETTINGS_PATH = File.expand_path('~/.claude/settings.json')
+
+        desc 'backfill', 'Backfill user.yml from ~/.claude/settings.json'
+        long_desc <<~LONGDESC
+          Reads ~/.claude/settings.json and merges any entries not yet captured
+          in the engine's user.yml YAML source. Shows what would be added, then
+          prompts for confirmation before writing.
+
+          Flags:
+            --target PATH  YAML file to update (auto-detected if omitted)
+            --yes          Apply without confirmation prompt
+
+          EXAMPLES
+
+            raictl backfill-user-yml
+            raictl backfill-user-yml --target conf/config/user.yml
+            raictl backfill-user-yml --yes
+
+          Related commands: raictl config compile, raictl config show user
+        LONGDESC
+        method_option :target, type: :string, default: nil,
+                               desc: 'YAML file to update (default: auto-detected engine user.yml)'
+        method_option :yes, type: :boolean, default: false,
+                            desc: 'Apply without confirmation'
+
+        # Run the backfill.
+        # @return [void]
+        def backfill
+          target_path = resolve_target
+          raise ::Thor::Error, "settings.json not found at #{SETTINGS_PATH}" unless File.exist?(SETTINGS_PATH)
+
+          unless File.exist?(target_path)
+            raise ::Thor::Error,
+                  "user.yml not found at #{target_path}. Specify --target or install the engine."
+          end
+
+          settings  = JSON.parse(File.read(SETTINGS_PATH))
+          user_yml  = YAML.safe_load_file(target_path)
+          compiled  = extract_compiled_stub(user_yml)
+          uncovered = find_uncovered(compiled, settings)
+
+          if uncovered.empty?
+            puts Rainbow('Nothing to backfill — user.yml already covers all entries.').green
+            return
+          end
+
+          total = count_leaves(uncovered)
+          say "Target : #{target_path}"
+          say "Found #{total} entr#{total == 1 ? 'y' : 'ies'} not in user.yml:\n"
+          print_uncovered(uncovered)
+          say
+
+          unless options[:yes]
+            answer = ask("Apply #{total} entr#{total == 1 ? 'y' : 'ies'} to user.yml? [y/N]")
+            unless answer.strip.downcase == 'y'
+              say 'Aborted — no changes written.'
+              return
+            end
+          end
+
+          apply_uncovered!(user_yml, uncovered)
+          warn_unmapped(uncovered)
+          File.write(target_path, user_yml.to_yaml)
+          say Rainbow("Wrote #{target_path} (#{total} entr#{total == 1 ? 'y' : 'ies'} added).").green
+          say 'Run `raictl config compile --simulate --verbose` to preview compiled output.'
+        end
+
+        private
+
+        def resolve_target
+          return File.expand_path(options[:target]) if options[:target]
+
+          candidates = [
+            File.expand_path('../../rosett-ai-engine-claude/conf/config/user.yml',
+                             RosettAi.root),
+            find_installed_engine_user_yml
+          ].compact
+          found = candidates.find { |p| File.exist?(p) }
+          return found if found
+
+          raise ::Thor::Error,
+                "Cannot auto-detect user.yml. Use --target PATH.\nTried:\n" \
+                "#{candidates.map { |p| "  #{p}" }.join("\n")}"
+        end
+
+        def find_installed_engine_user_yml
+          require 'rubygems'
+          spec = Gem::Specification.find_by_name('rosett-ai-engine-claude')
+          File.join(spec.gem_dir, 'conf', 'config', 'user.yml')
+        rescue Gem::MissingSpecError
+          nil
+        end
+
+        # Build a minimal compiled-form stub from user.yml so we can diff at the
+        # same key-naming level as settings.json (camelCase for JSON keys).
+        def extract_compiled_stub(user_yml_data)
+          stub = {}
+          perms = user_yml_data['permissions']
+          if perms.is_a?(Hash)
+            stub['permissions'] = {}
+            ['allow', 'deny', 'ask'].each do |k|
+              stub['permissions'][k] = Array(perms[k]) if perms.key?(k)
+            end
+            if perms.key?('additional_directories')
+              stub['permissions']['additionalDirectories'] = Array(perms['additional_directories'])
+            end
+          end
+          env = user_yml_data['env']
+          stub['env'] = env.transform_values(&:to_s) if env.is_a?(Hash)
+          stub
+        end
+
+        def find_uncovered(source_data, existing_data)
+          existing_data.each_with_object({}) do |(key, existing_val), result|
+            if source_data.key?(key)
+              uncovered = uncovered_value(source_data[key], existing_val)
+              result[key] = uncovered if uncovered
+            else
+              result[key] = existing_val
+            end
+          end
+        end
+
+        def uncovered_value(source_val, existing_val)
+          if source_val.is_a?(Array) && existing_val.is_a?(Array)
+            extra = existing_val - source_val
+            extra unless extra.empty?
+          elsif source_val.is_a?(Hash) && existing_val.is_a?(Hash)
+            sub = find_uncovered(source_val, existing_val)
+            sub unless sub.empty?
+          end
+        end
+
+        def apply_uncovered!(user_yml_data, uncovered)
+          user_yml_data['permissions'] ||= {}
+          perms_uncovered = uncovered['permissions'] || {}
+          ['allow', 'deny', 'ask'].each do |k|
+            next unless perms_uncovered.key?(k)
+
+            user_yml_data['permissions'][k] =
+              Array(user_yml_data['permissions'][k]) + perms_uncovered[k]
+          end
+          if perms_uncovered.key?('additionalDirectories')
+            user_yml_data['permissions']['additional_directories'] =
+              Array(user_yml_data['permissions']['additional_directories']) +
+              perms_uncovered['additionalDirectories']
+          end
+          return unless uncovered.key?('env')
+
+          user_yml_data['env'] ||= {}
+          uncovered['env'].each { |k, v| user_yml_data['env'][k] = v }
+        end
+
+        def warn_unmapped(uncovered)
+          other = uncovered.except('permissions', 'env')
+          return if other.empty?
+
+          say Rainbow("\nWarning: the following keys have no direct YAML mapping and were skipped:").yellow
+          other.each { |k, v| say "  #{k}: #{v.inspect}" }
+          say 'Add them manually if needed.'
+        end
+
+        def count_leaves(hash)
+          hash.sum do |_k, v|
+            case v
+            when Hash  then count_leaves(v)
+            when Array then v.size
+            else 1
+            end
+          end
+        end
+
+        def print_uncovered(uncovered, prefix = '')
+          uncovered.each do |key, val|
+            path = prefix.empty? ? key.to_s : "#{prefix}.#{key}"
+            case val
+            when Hash  then print_uncovered(val, path)
+            when Array then val.each { |e| say "  + #{path}[]: #{e}" }
+            else            say "  + #{path}: #{val.inspect}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -67,6 +67,8 @@ module RosettAi
                       default: nil,
                       desc: 'Output file path (shorthand for --destination)'
 
+        # Create the resource.
+        # @return [void]
         def create
           validate_options!
           compressor = resolve_compressor
@@ -105,6 +107,10 @@ module RosettAi
                       default: true,
                       desc: 'Restore local scope entries'
 
+        # Restore configuration from a backup archive.
+        #
+        # @param archive_path [Object] the archive path
+        # @return [void]
         def restore(archive_path)
           validate_archive!(archive_path)
           entries = extract_entries(archive_path)

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

@@ -37,6 +37,10 @@ module RosettAi
                       default: ENV.fetch('USER', 'unknown'),
                       desc: 'Author of the behaviour file'
 
+        # Add a new entry.
+        #
+        # @param name [Object] the name
+        # @return [void]
         def add(name)
           name = RosettAi::TextSanitizer.normalize_nfc(name)
           return if behaviour_exists?(name)
@@ -278,6 +282,8 @@ module RosettAi
                       enum: ['table', 'json', 'yaml'],
                       desc: 'Output format'
 
+        # Display a summary overview of behaviours.
+        # @return [void]
         def display
           behaviours = load_all_behaviours
 
@@ -306,6 +312,8 @@ module RosettAi
 
             raictl behaviour list
         LONGDESC
+        # List available items.
+        # @return [void]
         def list
           files = behaviour_files
           if files.empty?
@@ -329,6 +337,10 @@ module RosettAi
             raictl behaviour show code_generation
             raictl behaviour show security_rules
         LONGDESC
+        # Display detailed information for the named item.
+        #
+        # @param name [Object] the name
+        # @return [void]
         def show(name)
           name = RosettAi::TextSanitizer.normalize_nfc(name)
           file_path = find_behaviour_file(name)