rosett-ai 1.3.3

data/lib/rosett_ai/mcp/admin/registry.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Mcp
+    module Admin
+      # Registry of configured MCP servers.
+      #
+      # Manages discovery, storage, and querying of MCP server
+      # configurations from XDG-compliant paths.
+      #
+      # @author hugo
+      # @author claude
+      class Registry
+        CONFIG_DIR = '.config/rosett-ai/mcp/servers'
+
+        # @param config_dir [Pathname, nil] override config directory
+        def initialize(config_dir: nil)
+          @config_dir = config_dir || Pathname.new(Dir.home).join(CONFIG_DIR)
+        end
+
+        # Lists all registered MCP servers.
+        #
+        # @return [Array<Hash>] server entries with :name, :transport, :command/:url
+        def list
+          return [] unless @config_dir.directory?
+
+          @config_dir.glob('*.yml').filter_map { |path| load_server(path) }
+        end
+
+        # Finds a server by name.
+        #
+        # @param name [String] server name
+        # @return [Hash, nil] server entry or nil
+        def find(name)
+          list.find { |s| s[:name] == name }
+        end
+
+        # Adds a server configuration.
+        #
+        # @param config [Hash] server configuration
+        # @return [Pathname] path to the written file
+        def add(config)
+          FileUtils.mkdir_p(@config_dir)
+          name = config.fetch('name') { config.fetch(:name) }
+          path = @config_dir.join("#{name}.yml")
+
+          File.write(path, YAML.dump(stringify_keys(config)))
+          path
+        end
+
+        # Removes a server configuration.
+        #
+        # @param name [String] server name
+        # @return [Boolean] true if removed
+        def remove(name) # rubocop:disable Naming/PredicateMethod -- destructive action, not a predicate
+          path = @config_dir.join("#{name}.yml")
+          return false unless path.exist?
+
+          File.delete(path)
+          true
+        end
+
+        # Returns all server config file paths.
+        #
+        # @return [Array<Pathname>]
+        def config_paths
+          return [] unless @config_dir.directory?
+
+          @config_dir.glob('*.yml')
+        end
+
+        private
+
+        def load_server(path)
+          data = YAML.safe_load_file(path, permitted_classes: [Symbol])
+          return nil unless data.is_a?(Hash)
+
+          {
+            name: data['name'],
+            transport: data['transport'] || 'stdio',
+            command: data['command'],
+            url: data['url'],
+            args: data['args'],
+            env: data['env'],
+            source_file: path.to_s
+          }
+        rescue Psych::SyntaxError
+          nil
+        end
+
+        def stringify_keys(hash)
+          hash.transform_keys(&:to_s)
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/mcp/admin/schema_validator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'json_schemer'
+
+module RosettAi
+  module Mcp
+    module Admin
+      # Validates MCP server configurations against JSON Schema.
+      #
+      # Uses conf/schemas/mcp_server_schema.json for validation.
+      #
+      # @author hugo
+      # @author claude
+      class SchemaValidator
+        # @param schema_path [Pathname, nil] override schema file path
+        def initialize(schema_path: nil)
+          @schema_path = schema_path || RosettAi.root.join('conf', 'schemas', 'mcp_server_schema.json')
+        end
+
+        # Validates a server configuration hash.
+        #
+        # @param server [Hash] server configuration
+        # @return [Hash] result with :valid and :errors keys
+        def validate(server)
+          schema = load_schema
+          return { valid: true, errors: [] } unless schema
+
+          data = normalize(server)
+          errors = schema.validate(data).map { |e| e['error'] }
+
+          { valid: errors.empty?, errors: errors }
+        end
+
+        # Validates all servers in a registry.
+        #
+        # @param registry [Registry] server registry
+        # @return [Array<Hash>] validation results
+        def validate_all(registry)
+          registry.list.map do |server|
+            result = validate(server)
+            result.merge(name: server[:name])
+          end
+        end
+
+        private
+
+        def load_schema
+          return nil unless @schema_path.exist?
+
+          data = JSON.parse(File.read(@schema_path))
+          JSONSchemer.schema(data)
+        end
+
+        def normalize(server)
+          server.transform_keys(&:to_s).compact
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/mcp/enforcement/hook_generator.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'time'
+
+module RosettAi
+  module Mcp
+    module Enforcement
+      # Generates self-contained Ruby PreToolUse hook scripts from validated
+      # enforcement rules.
+      #
+      # Generated scripts are standalone — they require only Ruby stdlib (json)
+      # and have zero runtime dependency on rosett-ai. Each script includes:
+      # - YARD documentation
+      # - Human-readable header with generation metadata
+      # - AI client instructions comment block
+      # - Traceability (source behaviour, rule ID, version, generator version)
+      # - Enforcement logic: regex match on tool input, block/warn/log action
+      #
+      # @example Generate a hook script for validated rules
+      #   generator = HookGenerator.new
+      #   script = generator.generate(validated_rules, behaviour_name: 'session_optimization',
+      #                                                behaviour_version: '1.0.0')
+      #
+      # @author hugo
+      # @author claude
+      class HookGenerator
+        # Generates a complete PreToolUse hook script from validated rules.
+        #
+        # @param rules [Array<Hash>] validated rules from {Validator}, each with
+        #   :rule_id, :behaviour, :pattern, :applies_to, :action, :message,
+        #   :priority, :description
+        # @param behaviour_name [String] source behaviour name
+        # @param behaviour_version [String] source behaviour version
+        # @return [String] complete Ruby hook script
+        def generate(rules, behaviour_name:, behaviour_version:)
+          timestamp = Time.now.utc.iso8601
+          parts = []
+          parts << shebang_and_magic
+          parts << yard_documentation(rules)
+          parts << traceability_header(behaviour_name, behaviour_version, rules, timestamp)
+          parts << ai_client_instructions
+          parts << rule_constant(rules)
+          parts << enforcement_body
+          parts.join("\n")
+        end
+
+        private
+
+        # @return [String]
+        def shebang_and_magic
+          <<~RUBY
+            #!/usr/bin/env ruby
+            # frozen_string_literal: true
+          RUBY
+        end
+
+        # Generates YARD documentation block for the hook script.
+        #
+        # @param rules [Array<Hash>]
+        # @return [String]
+        def yard_documentation(rules)
+          rule_list = rules.map { |r| "#   - #{r[:behaviour]}/#{r[:rule_id]} (P#{r[:priority]})" }
+          <<~RUBY
+            # @title Rosett-AI Enforcement Hook
+            # @description Auto-generated PreToolUse hook that enforces behaviour rules
+            #   by matching tool input against regex patterns. Self-contained — no
+            #   external gem dependencies.
+            #
+            # @note This file is auto-generated by rosett-ai. Do not edit manually.
+            #   Re-generate with: raictl mcp tool rai_hook_install
+            #
+            # Enforced rules:
+            #{rule_list.join("\n")}
+          RUBY
+        end
+
+        # Generates traceability header with generation metadata.
+        #
+        # @param behaviour_name [String]
+        # @param behaviour_version [String]
+        # @param rules [Array<Hash>]
+        # @param timestamp [String]
+        # @return [String]
+        def traceability_header(behaviour_name, behaviour_version, rules, timestamp)
+          <<~RUBY
+            # --- Traceability ---
+            # Source behaviour: #{behaviour_name}
+            # Behaviour version: #{behaviour_version}
+            # Generator: rosett-ai v#{RosettAi::VERSION}
+            # Generated at: #{timestamp}
+            # Rule count: #{rules.size}
+            # Rule IDs: #{rules.map { |r| r[:rule_id] }.join(', ')}
+          RUBY
+        end
+
+        # @return [String]
+        def ai_client_instructions
+          <<~RUBY
+            # --- AI Client Instructions ---
+            # This hook is a Claude Code PreToolUse hook. It reads JSON from stdin
+            # describing the tool invocation, checks the input against enforcement
+            # rules, and exits with:
+            #   exit 0  — tool call allowed (or warn/log mode)
+            #   exit 2  — tool call blocked (block mode, non-zero = reject)
+            # Stderr output is shown to the user as hook feedback.
+            # Do NOT modify this file — re-generate via rai_hook_install.
+          RUBY
+        end
+
+        # Generates the RULES constant with validated rule data.
+        #
+        # @param rules [Array<Hash>]
+        # @return [String]
+        def rule_constant(rules)
+          entries = rules.map { |r| format_rule_entry(r) }
+          <<~RUBY
+            RULES = [
+            #{entries.join(",\n")}
+            ].freeze
+          RUBY
+        end
+
+        # Formats a single rule entry for the RULES constant.
+        #
+        # @param rule [Hash]
+        # @return [String]
+        def format_rule_entry(rule)
+          desc = sanitize_string(rule[:description], 80)
+          msg = sanitize_string(rule[:message].to_s, 120)
+          tools = rule[:applies_to].map { |t| "'#{sanitize_string(t, 40)}'" }.join(', ')
+          behaviour = sanitize_string(rule[:behaviour], 100)
+          rule_id = sanitize_string(rule[:rule_id], 40)
+          [
+            "  { behaviour: '#{behaviour}',",
+            "    rule_id: '#{rule_id}',",
+            "    priority: #{rule[:priority]},",
+            "    pattern: #{format_regex(rule[:pattern])},",
+            "    applies_to: [#{tools}],",
+            "    action: :#{rule[:action]},",
+            "    message: '#{msg}',",
+            "    description: '#{desc}' }"
+          ].join("\n  ")
+        end
+
+        # Formats a pattern string as a Regexp literal for the generated script.
+        #
+        # @param pattern [String]
+        # @return [String]
+        def format_regex(pattern)
+          "/#{pattern.gsub('/', '\\/')}/"
+        end
+
+        # Sanitizes a string for safe embedding in single-quoted Ruby strings.
+        # Backslashes must be escaped before quotes to avoid double-escaping.
+        #
+        # @param value [String]
+        # @param max_length [Integer]
+        # @return [String]
+        def sanitize_string(value, max_length)
+          value.to_s.tr("\n", ' ').strip[0, max_length].gsub('\\', '\\\\\\\\').gsub("'", "\\\\'")
+        end
+
+        # Generates the runtime enforcement logic body.
+        # Uses non-interpolating heredoc — this code runs at hook time, not generation time.
+        #
+        # @return [String]
+        def enforcement_body
+          <<~'RUBY'
+            require 'json'
+
+            input = JSON.parse($stdin.read)
+            tool_name = input['tool_name'].to_s
+            tool_input = input['tool_input'].to_s
+
+            violations = RULES.select do |rule|
+              rule[:applies_to].include?(tool_name) && rule[:pattern].match?(tool_input)
+            end
+
+            exit 0 if violations.empty?
+
+            violations.sort_by { |v| -v[:priority] }.each do |v|
+              $stderr.puts "[rai-enforce] #{v[:behaviour]}/#{v[:rule_id]} " \
+                           "(P#{v[:priority]}, #{v[:action]}): #{v[:message].empty? ? v[:description] : v[:message]}"
+            end
+
+            # Block if any violation has action :block
+            blocked = violations.any? { |v| v[:action] == :block }
+            exit(blocked ? 2 : 0)
+          RUBY
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/mcp/enforcement/validator.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Mcp
+    module Enforcement
+      # Validates enforcement blocks in behaviour rules.
+      #
+      # Checks each rule's enforcement block for correctness:
+      # - pattern present and compilable as regex
+      # - pattern not degenerate (would match everything)
+      # - applies_to present and non-empty
+      # - action is a valid enum value
+      #
+      # Invalid enforceable rules are downgraded to advisory with warnings.
+      # Rules without enforcement blocks are skipped (backward compatible).
+      #
+      # @example
+      #   validator = Validator.new
+      #   result = validator.validate(behaviour_data)
+      #   result[:valid]       # => [{ rule_id: "rule_001", ... }]
+      #   result[:downgraded]  # => [{ rule_id: "rule_002", reason: "..." }]
+      #   result[:skipped]     # => [{ rule_id: "rule_003" }]
+      #
+      # @author hugo
+      # @author claude
+      class Validator
+        VALID_TYPES = ['enforceable', 'advisory', 'informational'].freeze
+        VALID_ACTIONS = ['block', 'warn', 'log'].freeze
+
+        # Patterns that match everything or nearly everything — unsafe for hooks.
+        DEGENERATE_PATTERNS = [
+          /\A\.\*\z/,       # .*
+          /\A\.\+\z/,       # .+
+          /\A\\s\*\z/,      # \s*
+          /\A\\S\*\z/,      # \S*
+          /\A\\s\+\z/,      # \s+
+          /\A\\S\+\z/,      # \S+
+          /\A\.\*\?\z/,     # .*?
+          /\A\.\+\?\z/,     # .+?
+          /\A\(\.\*\)\z/,   # (.*)
+          /\A\(\.\+\)\z/    # (.+)
+        ].freeze
+
+        # @!attribute [r] behaviour
+        #   @return [String] behaviour name for error messages
+        # @!attribute [r] rule_id
+        #   @return [String] current rule ID for error messages
+        RuleContext = Struct.new(:behaviour, :rule_id)
+
+        # Validates all enforcement blocks in a behaviour.
+        #
+        # @param behaviour [Hash] parsed behaviour YAML data
+        # @return [Hash] result with :valid, :downgraded, :skipped, :errors keys
+        def validate(behaviour)
+          @result = { valid: [], downgraded: [], skipped: [], errors: [] }
+          rules = behaviour['rules']
+          return @result unless rules.is_a?(Array)
+
+          behaviour_name = behaviour['name'].to_s
+          rules.each { |rule| validate_rule(rule, behaviour_name) }
+
+          @result
+        end
+
+        private
+
+        # Validates a single rule's enforcement block.
+        #
+        # @param rule [Hash] rule data from behaviour YAML
+        # @param behaviour_name [String] parent behaviour name
+        def validate_rule(rule, behaviour_name)
+          return unless rule.is_a?(Hash)
+
+          ctx = RuleContext.new(behaviour: behaviour_name, rule_id: rule['id'].to_s)
+          enforcement = rule['enforcement']
+
+          unless enforcement.is_a?(Hash)
+            @result[:skipped] << { rule_id: ctx.rule_id, behaviour: ctx.behaviour }
+            return
+          end
+
+          classify_enforcement(rule, enforcement, ctx)
+        end
+
+        # Classifies a rule that has an enforcement block.
+        #
+        # @param rule [Hash]
+        # @param enforcement [Hash]
+        # @param ctx [RuleContext]
+        def classify_enforcement(rule, enforcement, ctx)
+          type = enforcement['type'].to_s
+          unless VALID_TYPES.include?(type)
+            @result[:errors] << { rule_id: ctx.rule_id, behaviour: ctx.behaviour,
+                                  reason: "invalid enforcement type '#{type}' " \
+                                          "(must be one of: #{VALID_TYPES.join(', ')})" }
+            return
+          end
+
+          return record_non_enforceable(rule, ctx, type) unless type == 'enforceable'
+
+          validate_enforceable(rule, enforcement, ctx)
+        end
+
+        # Validates and classifies an enforceable rule.
+        #
+        # @param rule [Hash]
+        # @param enforcement [Hash]
+        # @param ctx [RuleContext]
+        def validate_enforceable(rule, enforcement, ctx)
+          warnings = collect_warnings(enforcement, ctx)
+
+          if warnings.empty?
+            @result[:valid] << build_valid_entry(rule, enforcement, ctx)
+          else
+            @result[:downgraded] << { rule_id: ctx.rule_id, behaviour: ctx.behaviour,
+                                      original_type: 'enforceable', downgraded_to: 'advisory',
+                                      warnings: warnings }
+          end
+        end
+
+        # Records advisory/informational rules (no field validation needed).
+        #
+        # @param rule [Hash]
+        # @param ctx [RuleContext]
+        # @param type [String]
+        def record_non_enforceable(rule, ctx, type)
+          @result[:valid] << { rule_id: rule['id'].to_s, behaviour: ctx.behaviour, type: type }
+        end
+
+        # Collects all warnings for an enforceable enforcement block.
+        #
+        # @param enforcement [Hash] the enforcement block
+        # @param ctx [RuleContext]
+        # @return [Array<String>]
+        def collect_warnings(enforcement, ctx)
+          prefix = "#{ctx.behaviour}/#{ctx.rule_id}"
+          [].concat(check_pattern(enforcement['pattern'], prefix))
+            .concat(check_applies_to(enforcement['applies_to'], prefix))
+            .concat(check_action(enforcement['action'], prefix))
+        end
+
+        # Validates the pattern field.
+        #
+        # @param pattern [String, nil]
+        # @param prefix [String] error message prefix
+        # @return [Array<String>]
+        def check_pattern(pattern, prefix)
+          return ["#{prefix}: pattern missing or empty"] if pattern.nil? || blank?(pattern)
+
+          Regexp.new(pattern)
+          return ["#{prefix}: pattern '#{pattern}' is degenerate (matches everything)"] if degenerate?(pattern)
+
+          []
+        rescue RegexpError => e
+          ["#{prefix}: pattern does not compile: #{e.message}"]
+        end
+
+        # Validates the applies_to field.
+        #
+        # @param applies_to [Array, nil]
+        # @param prefix [String] error message prefix
+        # @return [Array<String>]
+        def check_applies_to(applies_to, prefix)
+          return ["#{prefix}: applies_to missing or empty"] unless applies_to.is_a?(Array) && !applies_to.empty?
+
+          []
+        end
+
+        # Validates the action field.
+        #
+        # @param action [String, nil]
+        # @param prefix [String] error message prefix
+        # @return [Array<String>]
+        def check_action(action, prefix)
+          return [] if VALID_ACTIONS.include?(action)
+
+          allowed = VALID_ACTIONS.join(', ')
+          ["#{prefix}: action '#{action}' invalid (must be one of: #{allowed})"]
+        end
+
+        # Tests whether a string is blank (nil, empty, or whitespace-only).
+        #
+        # @param value [String]
+        # @return [Boolean]
+        def blank?(value)
+          value.is_a?(String) && value.strip.empty?
+        end
+
+        # Tests whether a pattern is degenerate (matches everything).
+        #
+        # @param pattern [String] regex pattern string
+        # @return [Boolean]
+        def degenerate?(pattern)
+          DEGENERATE_PATTERNS.any? { |dp| dp.match?(pattern.strip) }
+        end
+
+        # Builds a valid entry hash for an enforceable rule.
+        #
+        # @param rule [Hash]
+        # @param enforcement [Hash]
+        # @param ctx [RuleContext]
+        # @return [Hash]
+        def build_valid_entry(rule, enforcement, ctx)
+          { rule_id: ctx.rule_id, behaviour: ctx.behaviour, type: 'enforceable',
+            pattern: enforcement['pattern'], applies_to: enforcement['applies_to'],
+            action: enforcement['action'], message: enforcement['message'],
+            priority: rule['priority'] || 0, description: rule['description'].to_s.strip }
+        end
+      end
+    end
+  end
+end