rosett-ai 1.3.3

data/lib/rosett_ai/workflow/steps/rai_step.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Workflow
+    module Steps
+      # Executes an internal rai CLI subcommand.
+      #
+      # Resolves the rai binary via PATH lookup, falling back to the
+      # development tree's bin/raictl.
+      #
+      # @author hugo
+      # @author claude
+      class RaiStep
+        # @param definition [Hash] step definition from workflow YAML
+        def initialize(definition)
+          @definition = definition
+          @command = definition.fetch('command')
+          validate!
+        end
+
+        # @return [String] step description for dry-run
+        def describe
+          "[raictl] #{@definition['name']} — #{@command}"
+        end
+
+        # Executes the rai subcommand.
+        #
+        # @return [Hash] execution result with :status and :message
+        def execute
+          argv = @command.split
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          success = system(resolve_rai_binary, *argv)
+          elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(1)
+
+          if success
+            { status: 'pass', message: "Completed: raictl #{@command}", duration_ms: elapsed }
+          else
+            { status: 'fail', message: "Failed: raictl #{@command} (exit #{$CHILD_STATUS&.exitstatus})",
+              duration_ms: elapsed }
+          end
+        end
+
+        private
+
+        # Resolves the rai binary path.
+        #
+        # Prefers a system-installed binary found via PATH, falls back
+        # to the development tree's bin/raictl.
+        #
+        # @return [String] absolute path to the rai binary
+        def resolve_rai_binary
+          @resolve_rai_binary ||= begin
+            which_result = `which rai 2>/dev/null`.strip
+            if $CHILD_STATUS&.success? && !which_result.empty?
+              which_result
+            else
+              RosettAi.root.join('bin', 'rai').to_s
+            end
+          end
+        end
+
+        def validate!
+          return if @command.is_a?(String)
+
+          raise RosettAi::WorkflowError,
+                "Rai step '#{@definition['name']}' command must be a string"
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/workflow/steps/shell_step.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Workflow
+    module Steps
+      # Executes a shell command in array-form (no string interpolation).
+      #
+      # @author hugo
+      # @author claude
+      class ShellStep
+        # @param definition [Hash] step definition from workflow YAML
+        def initialize(definition)
+          @definition = definition
+          @command = definition.fetch('command')
+          validate!
+        end
+
+        # @return [String] step description for dry-run
+        def describe
+          "[shell] #{@definition['name']} — #{@command.join(' ')}"
+        end
+
+        # Executes the shell command.
+        #
+        # @return [Hash] execution result with :status and :message
+        def execute
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          success = system(*@command)
+          elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(1)
+
+          if success
+            { status: 'pass', message: "Completed: #{@command.join(' ')}", duration_ms: elapsed }
+          else
+            { status: 'fail', message: "Failed: #{@command.join(' ')} (exit #{$CHILD_STATUS&.exitstatus})",
+              duration_ms: elapsed }
+          end
+        end
+
+        private
+
+        def validate!
+          return if @command.is_a?(Array)
+
+          raise RosettAi::WorkflowError,
+                "Shell step '#{@definition['name']}' command must be an array"
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/yaml_loader.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'yaml'
+
+module RosettAi
+  # Centralized YAML loading with bounds checking.
+  #
+  # Enforces file-size, nesting-depth, and key-count limits to prevent
+  # denial-of-service via maliciously crafted YAML payloads.
+  module YamlLoader
+    MAX_FILE_SIZE = 1_048_576 # 1 MB
+    MAX_DEPTH     = 10
+    MAX_KEY_COUNT = 1000
+
+    # Loads and validates a YAML file with bounds checking.
+    #
+    # Enforces file size, nesting depth, and key count limits before
+    # returning the parsed data.
+    #
+    # @param path [String] absolute path to the YAML file
+    # @param permitted_classes [Array<Class>] classes allowed during safe loading
+    # @return [Hash] parsed YAML data
+    # @raise [RosettAi::ValidationError] if file size, nesting depth, or key count
+    #   exceeds the configured limits
+    def self.load_file(path, permitted_classes: [Date, Time])
+      check_file_size!(path)
+      data = YAML.safe_load_file(path, permitted_classes: permitted_classes)
+      check_depth!(data, path)
+      check_key_count!(data, path)
+      data
+    end
+
+    def self.check_file_size!(path)
+      size = File.size(path)
+      return if size <= MAX_FILE_SIZE
+
+      raise RosettAi::ValidationError,
+            "YAML file exceeds #{MAX_FILE_SIZE} byte limit (#{size} bytes): #{path}"
+    end
+    private_class_method :check_file_size!
+
+    def self.check_depth!(data, path, current = 0)
+      raise RosettAi::ValidationError, "YAML nesting exceeds #{MAX_DEPTH} levels: #{path}" if current > MAX_DEPTH
+
+      case data
+      when Hash
+        data.each_value { |v| check_depth!(v, path, current + 1) }
+      when Array
+        data.each { |v| check_depth!(v, path, current + 1) }
+      end
+    end
+    private_class_method :check_depth!
+
+    def self.check_key_count!(data, path)
+      count = count_keys(data)
+      return if count <= MAX_KEY_COUNT
+
+      raise RosettAi::ValidationError,
+            "YAML key count exceeds #{MAX_KEY_COUNT} (#{count} keys): #{path}"
+    end
+    private_class_method :check_key_count!
+
+    def self.count_keys(data)
+      case data
+      when Hash
+        data.size + data.each_value.sum { |v| count_keys(v) }
+      when Array
+        data.sum { |v| count_keys(v) }
+      else
+        0
+      end
+    end
+    private_class_method :count_keys
+  end
+end

data/lib/rosett_ai.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'zeitwerk'
+require 'json'
+require 'logger'
+require 'pathname'
+require 'i18n'
+
+# NeatNerds Code Companion — engine-agnostic configuration management
+# for AI-assisted development workflows.
+#
+# Author rules once in YAML, compile to any AI tool: Claude, Cursor, AGENTS.md,
+# and any engine with a pluggable backend.
+#
+# @see https://neatnerds.be/rosett-ai
+module RosettAi
+  # @!group Error hierarchy
+
+  # Base error for all rosett-ai operations.
+  class Error < StandardError; end
+  # Raised when configuration files are invalid or unreadable.
+  class ConfigurationError < Error; end
+  # Raised when schema or bounds validation fails.
+  class ValidationError < Error; end
+  # Raised when behaviour file processing fails.
+  class BehaviourError < Error; end
+  # Raised when compilation encounters an unrecoverable error.
+  class CompileError < Error; end
+  # Raised when rule adoption analysis fails.
+  class AdoptError < Error; end
+  # Raised when workspace initialization fails.
+  class InitError < Error; end
+  # Raised when backup creation or restoration fails.
+  class BackupError < Error; end
+  # Raised when package build fails.
+  class BuildError < Error; end
+  # Raised when design document operations fail.
+  class DesignError < Error; end
+  # Raised when documentation generation fails.
+  class DocumentationError < Error; end
+  # Raised when release management operations fail.
+  class ReleaseError < Error; end
+  # Raised when tooling validation fails.
+  class ToolingError < Error; end
+  # Raised when license activation or validation fails.
+  class LicenseError < Error; end
+  # Raised when content pack operations fail.
+  class ContentError < Error; end
+  # Raised when behaviour composition fails.
+  class CompositionError < Error; end
+  # Raised when AI provenance operations fail.
+  class ProvenanceError < Error; end
+  # Raised when AI tool configuration operations fail.
+  class AiConfigError < Error; end
+  # Raised when AI authorship attribution fails.
+  class AuthorshipError < Error; end
+  # Raised when policy management operations fail.
+  class PolicyError < Error; end
+  # Raised when doctor diagnostics encounter an unexpected error.
+  class DoctorError < Error; end
+  # Raised when an experimental feature is invoked without its flag enabled.
+  class FeatureFlagError < Error; end
+  # Raised when compliance checks encounter an unrecoverable error.
+  class ComplianceError < Error; end
+  # Raised when workflow definition or execution fails.
+  class WorkflowError < Error; end
+  # Raised when project management operations fail.
+  class ProjectError < Error; end
+  # Raised when reverse compilation (retrofit) fails.
+  class RetrofitError < Error; end
+  # Raised when git hook operations fail.
+  class GitHooksError < Error; end
+  # Raised when MCP server or admin operations fail.
+  class McpError < Error; end
+
+  # @!endgroup
+
+  class << self
+    # Project root directory (where the gemspec lives).
+    #
+    # @return [Pathname]
+    def root
+      @root ||= Pathname.new(File.expand_path('..', __dir__))
+    end
+
+    # Zeitwerk autoloader instance. Sets up inflections, ignores
+    # deprecated stubs and optional gems, then calls +setup+.
+    #
+    # @return [Zeitwerk::Loader]
+    def loader
+      @loader ||= begin
+        loader = Zeitwerk::Loader.for_gem
+        loader.inflector.inflect('cli' => 'CLI', 'dbus' => 'DBus')
+        loader.ignore("#{__dir__}/rubocop")
+        loader.ignore("#{__dir__}/scripts")
+        unless gem_available?('ruby-dbus')
+          # Ignore D-Bus interface/service files that require ruby-dbus,
+          # but keep pure-Ruby utilities (e.g. RateLimiter) available.
+          ['service', 'compositor_detector', 'focus_monitor_interface', 'manager_interface',
+           'plugin_manager_interface', 'status_notifier_interface'].each do |f|
+            loader.ignore("#{__dir__}/rosett-ai/dbus/#{f}.rb")
+          end
+          loader.ignore("#{__dir__}/rosett-ai/dbus/focus_adapters/gnome_adapter.rb")
+          loader.ignore("#{__dir__}/rosett-ai/dbus/focus_adapters/kwin_adapter.rb")
+          loader.ignore("#{__dir__}/rosett-ai/desktop")
+        end
+        ignore_deprecated_stubs(loader)
+        loader.setup
+        loader
+      end
+    end
+
+    # Active project context (detects +.rosett-ai/+ marker).
+    #
+    # @return [RosettAi::ProjectContext]
+    def context
+      @context ||= ProjectContext.new
+    end
+
+    # Configuration root directory, scoped to the active project if present.
+    #
+    # @return [Pathname]
+    def conf_root
+      context.conf_root
+    end
+
+    # Global {Configuration} instance (settings.json hierarchy).
+    #
+    # @return [RosettAi::Configuration]
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Global {PathResolver} instance for filesystem path lookups.
+    #
+    # @return [RosettAi::PathResolver]
+    def paths
+      @paths ||= PathResolver.new
+    end
+
+    # Loaded +~/.config/rosett-ai/config.yml+ settings.
+    #
+    # @return [RosettAi::RaiConfig]
+    def rai_config
+      @rai_config ||= RaiConfig.load
+    end
+
+    # Initializes I18n with rosett-ai locale files, resolves the active locale,
+    # and configures fallback chains (e.g. nl_BE -> nl -> en).
+    #
+    # @param locale [String, nil] explicit locale override (e.g. +"fr"+)
+    # @return [void]
+    def setup_i18n(locale: nil)
+      require 'i18n/backend/fallbacks'
+      ::I18n::Backend::Simple.include(::I18n::Backend::Fallbacks)
+
+      ::I18n.load_path += Dir[root.join('locales', '*.yml')]
+      ::I18n.default_locale = :en
+      ::I18n.enforce_available_locales = false
+
+      resolved_locale = resolve_locale(locale)
+      ::I18n.locale = resolved_locale.to_sym
+    end
+
+    # Structured logger with correlation IDs and JSON/text output.
+    # Level controlled by +RAI_LOG_LEVEL+, format by +RAI_LOG_FORMAT+.
+    #
+    # @return [RosettAi::StructuredLogger]
+    def logger
+      @logger ||= StructuredLogger.new
+    end
+
+    # Resets all memoized singletons. Intended for test isolation.
+    #
+    # @return [void]
+    def reset_config!
+      @config = nil
+      @paths = nil
+      @rai_config = nil
+      @logger = nil
+      @context = nil
+    end
+
+    private
+
+    def resolve_locale(explicit)
+      resolver = RosettAi::I18n::LocaleResolver.new
+      result = resolver.resolve(explicit: explicit)
+      available = ::I18n.available_locales.map(&:to_s)
+      locale = result[:chain].find { |loc| available.include?(loc) } || 'en'
+      chain = resolver.fallback_chain(locale).map(&:to_sym)
+      ::I18n.fallbacks = ::I18n::Locale::Fallbacks.new(locale.to_sym => chain)
+      locale
+    end
+
+    # Deprecated delegation stubs reference engine gem constants
+    # (RosettAiEngine::Claude::*, RosettAiEngine::Generic::*) that are only available
+    # when engine gems are installed. Ignoring them from Zeitwerk prevents
+    # NameError on autoload. Will be removed in v1.1.0.
+    def ignore_deprecated_stubs(loader)
+      ['compiler/backends/claude_backend', 'compiler/backends/generic_backend',
+       'config/compiler', 'config/key_map', 'config/scope_router'].each do |stub|
+        loader.ignore("#{__dir__}/rosett-ai/#{stub}.rb")
+      end
+    end
+
+    def gem_available?(name)
+      Gem::Specification.find_by_name(name)
+      true
+    rescue Gem::MissingSpecError
+      false
+    end
+  end
+end
+
+RosettAi.loader
+RosettAi.setup_i18n
+RosettAi::Plugins::Registry.discover!

data/lib/rubocop/cop/rosett_ai/shell_interpolation.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RuboCop
+  module Cop
+    module RosettAi
+      # Flags `system`, `exec`, and `spawn` calls where the first argument
+      # is an interpolated string, and backtick commands with interpolation.
+      # Both patterns risk shell injection.
+      #
+      # Use array-form instead: `system('cmd', arg1, arg2)` or
+      # `IO.popen([cmd, arg], &:read)`.
+      #
+      # @example
+      #   # bad
+      #   system("rm #{filename}")
+      #   exec("echo #{user_input}")
+      #   spawn("process #{data}")
+      #   `#{cmd} --flag`
+      #
+      #   # good
+      #   system('rm', filename)
+      #   system(ENV.fetch('EDITOR', 'vim'), file)
+      #   IO.popen([cmd, '--flag'], &:read)
+      #   `ls -la`
+      class ShellInterpolation < Base
+        MSG = 'Use array-form `system(cmd, arg, ...)` instead of interpolated string to avoid shell injection.'
+        BACKTICK_MSG = 'Use `IO.popen([cmd, arg], &:read)` instead of backtick interpolation to avoid shell injection.'
+
+        SHELL_METHODS = [:system, :exec, :spawn].freeze
+
+        # system/exec/spawn with a dstr (interpolated string) as first argument
+        # @!method shell_with_interpolation?(node)
+        def_node_matcher :shell_with_interpolation?, <<~PATTERN
+          (send nil? {#{SHELL_METHODS.map { |method| ":#{method}" }.join(' ')}} dstr ...)
+        PATTERN
+
+        def on_send(node)
+          return unless shell_with_interpolation?(node)
+
+          add_offense(node)
+        end
+
+        def on_xstr(node)
+          return unless node.children.any?(&:begin_type?)
+
+          add_offense(node, message: BACKTICK_MSG)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/rosett_ai/unsafe_const_get.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RuboCop
+  module Cop
+    module RosettAi
+      # Flags `const_get` and `constantize` calls with non-literal arguments.
+      # Dynamic constant lookup with user input can lead to arbitrary class
+      # instantiation and code execution.
+      #
+      # Safe patterns use frozen constant registries that map user input to
+      # allowed class names.
+      #
+      # @example
+      #   # bad
+      #   Object.const_get(user_input)
+      #   Kernel.const_get(params[:class])
+      #   user_input.constantize
+      #
+      #   # good - use a frozen allowlist
+      #   ALLOWED_CLASSES = { 'foo' => Foo, 'bar' => Bar }.freeze
+      #   ALLOWED_CLASSES.fetch(user_input)
+      #
+      #   # good - literal constant names
+      #   Object.const_get(:MyClass)
+      #   Object.const_get('RosettAi::Parser')
+      class UnsafeConstGet < Base
+        MSG = 'Avoid `const_get` with non-literal arguments. ' \
+              'Use a frozen allowlist instead to prevent arbitrary class instantiation.'
+        CONSTANTIZE_MSG = 'Avoid `constantize` on dynamic strings. ' \
+                          'Use a frozen allowlist instead.'
+
+        CONST_GET_METHODS = [:const_get].freeze
+        CONSTANTIZE_METHODS = [:constantize, :safe_constantize].freeze
+
+        # const_get with any argument that is not a literal symbol or string
+        # @!method const_get_with_dynamic?(node)
+        def_node_matcher :const_get_with_dynamic?, <<~PATTERN
+          (send _ {:const_get} $!{sym str})
+        PATTERN
+
+        # .constantize or .safe_constantize on any receiver
+        # @!method constantize_call?(node)
+        def_node_matcher :constantize_call?, <<~PATTERN
+          (send _ {:constantize :safe_constantize})
+        PATTERN
+
+        def on_send(node)
+          if const_get_with_dynamic?(node)
+            add_offense(node)
+          elsif constantize_call?(node)
+            add_offense(node, message: CONSTANTIZE_MSG)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/rosett_ai/unsafe_send.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RuboCop
+  module Cop
+    module RosettAi
+      # Flags `send`, `public_send`, and `__send__` calls with non-literal
+      # method names. Dynamic method dispatch with user input can lead to
+      # arbitrary method execution.
+      #
+      # Safe patterns validate the method name against an allowlist before
+      # calling send.
+      #
+      # @example
+      #   # bad
+      #   object.send(user_input)
+      #   object.public_send(params[:method])
+      #   receiver.__send__(dynamic_method)
+      #
+      #   # good - validate against allowlist first
+      #   ALLOWED_METHODS = %w[foo bar].freeze
+      #   raise ArgumentError unless ALLOWED_METHODS.include?(method_name)
+      #   object.send(method_name)
+      #
+      #   # good - literal method names
+      #   object.send(:known_method)
+      #   object.public_send('safe_method')
+      class UnsafeSend < Base
+        MSG = 'Avoid `%<method>s` with non-literal method names. ' \
+              'Validate against an allowlist first to prevent arbitrary method execution.'
+
+        SEND_METHODS = [:send, :public_send, :__send__].freeze
+
+        # send/public_send/__send__ with any argument that is not a literal symbol or string
+        # @!method send_with_dynamic?(node)
+        def_node_matcher :send_with_dynamic?, <<~PATTERN
+          (send _ ${:send :public_send :__send__} $!{sym str} ...)
+        PATTERN
+
+        def on_send(node)
+          send_with_dynamic?(node) do |method_name, _arg|
+            add_offense(node, message: format(MSG, method: method_name))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/rosett_ai/unsafe_yaml_load.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RuboCop
+  module Cop
+    module RosettAi
+      # Flags calls to `YAML.load` which is unsafe for untrusted input.
+      #
+      # Use `YAML.safe_load`, `YAML.safe_load_file`, or
+      # `RosettAi::YamlLoader.load_file` instead.
+      #
+      # @example
+      #   # bad
+      #   YAML.load(string)
+      #   YAML.load_file(path)
+      #
+      #   # good
+      #   YAML.safe_load(string)
+      #   YAML.safe_load_file(path)
+      #   RosettAi::YamlLoader.load_file(path)
+      class UnsafeYamlLoad < Base
+        MSG = 'Use `YAML.safe_load` or `RosettAi::YamlLoader.load_file` instead of `YAML.load`.'
+
+        # YAML.load(...) or YAML.load_file(...)
+        # @!method unsafe_yaml_load?(node)
+        def_node_matcher :unsafe_yaml_load?, <<~PATTERN
+          (send (const {nil? cbase} :YAML) {:load :load_file} ...)
+        PATTERN
+
+        def on_send(node)
+          return unless unsafe_yaml_load?(node)
+
+          add_offense(node)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/rosett_ai.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require_relative 'cop/rosett_ai/unsafe_yaml_load'
+require_relative 'cop/rosett_ai/shell_interpolation'
+require_relative 'cop/rosett_ai/unsafe_const_get'
+require_relative 'cop/rosett_ai/unsafe_send'