rosett-ai 1.3.3

data/lib/rosett_ai/error_handler.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  # Centralized error handler for CLI commands.
+  #
+  # Catches +RosettAi::Error+ (and subclasses), formats the error message with
+  # what/why/fix structure, and exits with the mapped exit code. Stack traces
+  # are only shown when +RAI_LOG_LEVEL=DEBUG+.
+  #
+  # TTY-aware: uses colour and formatting when stdout is a TTY, plain text
+  # when piped.
+  #
+  # @author hugo
+  # @author claude
+  # @see ExitCodes
+  # @see conf/design/error_handling.yml
+  class ErrorHandler
+    # Wraps a block, rescuing +RosettAi::Error+ and formatting the output.
+    #
+    # @param stderr [IO] output stream for errors (default: $stderr)
+    # @yield the CLI command block to execute
+    # @return [Integer] exit code (0 on success)
+    def self.handle(stderr: $stderr, &)
+      new(stderr: stderr).handle(&)
+    end
+
+    # @param stderr [IO] output stream for errors
+    def initialize(stderr: $stderr)
+      @stderr = stderr
+    end
+
+    # Executes the block and handles errors.
+    #
+    # @yield the CLI command block
+    # @return [Integer] exit code
+    def handle
+      yield
+      ExitCodes::SUCCESS
+    rescue RosettAi::Error => e
+      report(e)
+      ExitCodes.for(e)
+    end
+
+    private
+
+    # Formats and writes the error to stderr.
+    #
+    # @param error [RosettAi::Error] the caught error
+    # @return [void]
+    def report(error)
+      exit_code = ExitCodes.for(error)
+      parts = parse_message(error.message)
+
+      if tty?
+        report_tty(error, parts, exit_code)
+      else
+        report_plain(error, parts, exit_code)
+      end
+
+      report_backtrace(error) if debug?
+    end
+
+    # Parses a message for what/why/fix structure.
+    #
+    # Messages can use the convention:
+    #   "What failed. Why: reason. Fix: suggestion"
+    # or just be a plain string.
+    #
+    # @param message [String]
+    # @return [Hash{Symbol => String, nil}]
+    def parse_message(message)
+      parts = { what: message, why: nil, fix: nil }
+
+      if message.include?(' Fix: ')
+        before_fix, parts[:fix] = message.split(' Fix: ', 2)
+        if before_fix.include?(' Why: ')
+          parts[:what], parts[:why] = before_fix.split(' Why: ', 2)
+        else
+          parts[:what] = before_fix
+        end
+      elsif message.include?(' Why: ')
+        parts[:what], parts[:why] = message.split(' Why: ', 2)
+      end
+
+      parts
+    end
+
+    # TTY-formatted error output with colour.
+    #
+    # @param error [RosettAi::Error]
+    # @param parts [Hash]
+    # @param exit_code [Integer]
+    # @return [void]
+    def report_tty(error, parts, exit_code)
+      @stderr.puts Rainbow("Error [#{exit_code}]: #{parts[:what]}").red.bright
+      @stderr.puts Rainbow("  Why: #{parts[:why]}").yellow if parts[:why]
+      @stderr.puts Rainbow("  Fix: #{parts[:fix]}").green if parts[:fix]
+      @stderr.puts Rainbow("  Type: #{error.class}").faint
+    end
+
+    # Plain text error output for pipes.
+    #
+    # @param error [RosettAi::Error]
+    # @param parts [Hash]
+    # @param exit_code [Integer]
+    # @return [void]
+    def report_plain(error, parts, exit_code)
+      @stderr.puts "Error [#{exit_code}]: #{parts[:what]}"
+      @stderr.puts "  Why: #{parts[:why]}" if parts[:why]
+      @stderr.puts "  Fix: #{parts[:fix]}" if parts[:fix]
+      @stderr.puts "  Type: #{error.class}"
+    end
+
+    # Outputs backtrace when RAI_LOG_LEVEL=DEBUG.
+    #
+    # @param error [RosettAi::Error]
+    # @return [void]
+    def report_backtrace(error)
+      return unless error.backtrace
+
+      @stderr.puts ''
+      @stderr.puts 'Backtrace (first 10 frames):'
+      error.backtrace.first(10).each { |frame| @stderr.puts "  #{frame}" }
+    end
+
+    # @return [Boolean] true if stderr is a TTY
+    def tty?
+      @stderr.respond_to?(:tty?) && @stderr.tty?
+    end
+
+    # @return [Boolean] true if RAI_LOG_LEVEL is DEBUG
+    def debug?
+      ENV.fetch('RAI_LOG_LEVEL', '').casecmp('debug').zero?
+    end
+  end
+end

data/lib/rosett_ai/exit_codes.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  # Maps error categories to numeric exit codes for CLI process exit.
+  #
+  # Exit codes follow Unix conventions:
+  # - 0: success
+  # - 1: general/runtime error
+  # - 2: validation/input error
+  # - 3: configuration error
+  # - 4: permission/access error
+  # - 5: dependency/environment error
+  #
+  # @author hugo
+  # @author claude
+  module ExitCodes
+    SUCCESS      = 0
+    GENERAL      = 1
+    VALIDATION   = 2
+    CONFIG       = 3
+    PERMISSION   = 4
+    DEPENDENCY   = 5
+
+    # Maps each RosettAi error class to its exit code.
+    #
+    # @return [Hash{Class => Integer}]
+    MAPPING = {
+      RosettAi::Error => GENERAL,
+      RosettAi::ValidationError => VALIDATION,
+      RosettAi::BehaviourError => VALIDATION,
+      RosettAi::DesignError => VALIDATION,
+      RosettAi::CompositionError => VALIDATION,
+      RosettAi::CompileError => VALIDATION,
+      RosettAi::ConfigurationError => CONFIG,
+      RosettAi::AiConfigError => CONFIG,
+      RosettAi::PolicyError => CONFIG,
+      RosettAi::InitError => CONFIG,
+      RosettAi::AdoptError => GENERAL,
+      RosettAi::BackupError => GENERAL,
+      RosettAi::BuildError => GENERAL,
+      RosettAi::DocumentationError => GENERAL,
+      RosettAi::ReleaseError => GENERAL,
+      RosettAi::ToolingError => VALIDATION,
+      RosettAi::LicenseError => CONFIG,
+      RosettAi::ContentError => GENERAL,
+      RosettAi::ProvenanceError => GENERAL,
+      RosettAi::AuthorshipError => GENERAL,
+      RosettAi::DoctorError => GENERAL,
+      RosettAi::FeatureFlagError => GENERAL,
+      RosettAi::ComplianceError => VALIDATION,
+      RosettAi::WorkflowError => GENERAL,
+      RosettAi::ProjectError => GENERAL,
+      RosettAi::RetrofitError => CONFIG,
+      RosettAi::GitHooksError => GENERAL,
+      RosettAi::McpError => GENERAL
+    }.freeze
+
+    # Resolves the exit code for a given error.
+    #
+    # Walks the class hierarchy to find the most specific mapping.
+    # Falls back to GENERAL (1) for unmapped error classes.
+    #
+    # @param error [Exception] the error to map
+    # @return [Integer] the exit code (0-5)
+    def self.for(error)
+      klass = error.is_a?(Class) ? error : error.class
+      MAPPING.fetch(klass) do
+        ancestor = klass.ancestors.find { |ancestor_class| MAPPING.key?(ancestor_class) }
+        ancestor ? MAPPING[ancestor] : GENERAL
+      end
+    end
+  end
+end

data/lib/rosett_ai/feature_flags.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  # Environment-variable-based feature gating for experimental features.
+  #
+  # Setting +RAI_EXPERIMENTAL=workflow,mcp+ enables only the listed features;
+  # all others remain hidden. Flags are parsed once at module load time into
+  # a frozen Set for O(1) membership checks.
+  #
+  # @example Check if a feature is enabled
+  #   RosettAi::FeatureFlags.enabled?(:workflow) # => true if RAI_EXPERIMENTAL includes "workflow"
+  #
+  # @example Gate a command (raises if not enabled)
+  #   RosettAi::FeatureFlags.gate!(:workflow)
+  #
+  # @author hugo
+  # @author claude
+  module FeatureFlags
+    # All recognised experimental feature names. When a feature is promoted
+    # to stable, remove it from this set.
+    KNOWN_FLAGS = Set['workflow', 'mcp', 'comply', 'retrofit'].freeze
+
+    # Raised when a gated command is invoked without its feature flag enabled.
+    class ExperimentalFeatureError < RosettAi::Error
+      # @return [String] the feature name that was not enabled
+      attr_reader :feature
+
+      def initialize(feature)
+        @feature = feature.to_s
+        super(::I18n.t('rosett_ai.feature_flags.not_enabled',
+                       feature: @feature,
+                       env_example: "RAI_EXPERIMENTAL=#{@feature}"))
+      end
+    end
+
+    class << self
+      # Returns true if the given feature is currently enabled.
+      #
+      # @param feature [Symbol, String] the feature flag name
+      # @return [Boolean]
+      def enabled?(feature)
+        active_flags.include?(feature.to_s)
+      end
+
+      # Raises {ExperimentalFeatureError} unless the given feature is enabled.
+      # Used as a guard in CLI commands that are experimental.
+      #
+      # @param feature [Symbol, String] the feature flag name
+      # @raise [ExperimentalFeatureError] if the feature is not enabled
+      # @return [void]
+      def gate!(feature)
+        return if enabled?(feature)
+
+        raise ExperimentalFeatureError, feature
+      end
+
+      # Returns the Set of currently active (enabled) flags.
+      #
+      # @return [Set<String>]
+      def all_enabled
+        active_flags
+      end
+
+      # Re-parses RAI_EXPERIMENTAL from the environment. Intended for
+      # test isolation only.
+      #
+      # @return [void]
+      def reset!
+        @active_flags = nil
+      end
+
+      private
+
+      def active_flags
+        @active_flags ||= parse_flags
+      end
+
+      def parse_flags
+        raw = ENV.fetch('RAI_EXPERIMENTAL', '')
+        return Set.new.freeze if raw.empty?
+
+        requested = raw.split(',').map(&:strip).reject(&:empty?).to_set
+        unknown = requested - KNOWN_FLAGS
+
+        warn_unknown(unknown) unless unknown.empty?
+
+        (requested & KNOWN_FLAGS).freeze
+      end
+
+      def warn_unknown(unknown)
+        unknown.sort.each do |flag|
+          warn ::I18n.t('rosett_ai.feature_flags.unknown_flag',
+                        flag: flag,
+                        known: KNOWN_FLAGS.sort.join(', '))
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/formatting.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  # Human-readable formatting for byte sizes and durations.
+  # Include in any class that needs to display file sizes or elapsed times.
+  module Formatting
+    SIZE_UNITS = ['B', 'KB', 'MB', 'GB'].freeze
+
+    # Formats a byte count as a human-readable string (e.g. "2.0 KB").
+    def format_size(bytes)
+      unit_index = 0
+      size = bytes.to_f
+      while size >= 1024 && unit_index < SIZE_UNITS.length - 1
+        size /= 1024
+        unit_index += 1
+      end
+      format('%<size>.1f %<unit>s', size: size, unit: SIZE_UNITS[unit_index])
+    end
+
+    # Formats a duration in seconds as a human-readable string.
+    # Returns "Xs" for < 60s, "Xm Ys" for >= 60s.
+    def format_duration(seconds)
+      if seconds >= 60
+        format('%<min>dm %<sec>.0fs', min: (seconds / 60).to_i, sec: seconds % 60)
+      else
+        format('%<sec>.1fs', sec: seconds)
+      end
+    end
+  end
+end

data/lib/rosett_ai/gem_consistency_checker.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'pathname'
+
+module RosettAi
+  # Checks that gem version references across the codebase are consistent
+  # with the resolved versions in Gemfile.lock and the constraints in the gemspec.
+  #
+  # Parses Gemfile.lock for resolved runtime dependency versions, compares them
+  # against gemspec constraints, and scans project files for stale gem version
+  # references.
+  class GemConsistencyChecker
+    EXCLUDED_DIRS = ['vendor', 'tmp', 'coverage', '.git', '.bundle'].freeze
+    EXCLUDED_FILES = ['Gemfile.lock', 'Gemfile', 'rosett_ai.gemspec',
+                      'spec/rosett_ai/gem_consistency_checker_spec.rb',
+                      'spec/examples.txt'].freeze
+    EXCLUDED_PREFIXES = ['doc/changes/', 'doc/claude-sessions/', 'conf/design/'].freeze
+    EXCLUDED_EXTENSIONS = ['.aux', '.toc', '.out', '.ptc', '.log', '.idx', '.ind',
+                           '.ilg', '.bbl', '.blg', '.bcf', '.fls', '.json'].freeze
+
+    attr_reader :results
+
+    def initialize(project_dir: Dir.pwd)
+      @project_dir = Pathname.new(project_dir)
+      @results = { gems: [], stale_references: [], consistent: true }
+    end
+
+    def check
+      constraints = parse_gemspec_constraints
+      locked = parse_lockfile_versions
+
+      gems = build_gem_audit(constraints, locked)
+      dependency_versions = locked.select { |name, _| constraints.key?(name) }
+      stale = scan_for_stale_references(dependency_versions)
+
+      @results = {
+        gems: gems,
+        stale_references: stale,
+        consistent: gems.all? { |entry| entry[:status] == :ok } && stale.empty?
+      }
+    end
+
+    def consistent?
+      check if @results[:gems].empty? && @results[:stale_references].empty?
+      @results[:consistent]
+    end
+
+    private
+
+    def parse_gemspec_constraints
+      gemspec_path = find_gemspec
+      return {} unless gemspec_path
+
+      constraints = {}
+      File.readlines(gemspec_path, encoding: 'UTF-8').each do |line|
+        match = line.match(/add_dependency\s+['"]([^'"]+)['"]\s*,\s*['"]([^'"]+)['"]/)
+        next unless match
+
+        constraints[match[1]] = match[2]
+      end
+      constraints
+    end
+
+    def find_gemspec
+      pattern = @project_dir.join('*.gemspec')
+      files = Dir.glob(pattern)
+      files.first
+    end
+
+    def parse_lockfile_versions
+      lockfile = @project_dir.join('Gemfile.lock')
+      return {} unless lockfile.exist?
+
+      gem_specs_section = extract_gem_specs(File.readlines(lockfile, encoding: 'UTF-8'))
+      parse_specs_lines(gem_specs_section)
+    end
+
+    def extract_gem_specs(lines)
+      in_gem = false
+      in_specs = false
+      specs = []
+
+      lines.each do |line|
+        in_gem = true if line.strip == 'GEM'
+        in_specs = true if in_gem && line.strip == 'specs:'
+        break if in_gem && in_specs && !line.start_with?('  ')
+
+        specs << line if in_specs
+      end
+      specs
+    end
+
+    def parse_specs_lines(lines)
+      versions = {}
+      lines.each do |line|
+        match = line.match(/^\s{4}(\S+)\s+\((\d+\.\d+[\d.]*)\)/)
+        versions[match[1]] = match[2] if match
+      end
+      versions
+    end
+
+    def build_gem_audit(constraints, locked)
+      constraints.map do |gem_name, constraint|
+        resolved = locked[gem_name]
+        status = gem_status(constraint, resolved)
+
+        { name: gem_name, constraint: constraint, resolved: resolved, status: status }
+      end
+    end
+
+    def gem_status(constraint, resolved)
+      return :missing unless resolved
+
+      requirement = Gem::Requirement.new(constraint)
+      version = Gem::Version.new(resolved)
+      requirement.satisfied_by?(version) ? :ok : :conflict
+    end
+
+    def scan_for_stale_references(locked)
+      return [] if locked.empty?
+
+      stale = []
+      project_files.each do |file|
+        scan_file_for_gems(file, locked, stale)
+      end
+      stale
+    end
+
+    def scan_file_for_gems(file, locked, stale)
+      relative = Pathname.new(file).relative_path_from(@project_dir).to_s
+
+      File.readlines(file, encoding: 'UTF-8').each_with_index do |line, index|
+        next if constraint_line?(line)
+        next if suppressed_line?(line)
+
+        check_line_for_stale_gems(line, locked, relative, index, stale)
+      end
+    rescue ArgumentError, Encoding::InvalidByteSequenceError
+      # Skip files with encoding issues
+    end
+
+    def check_line_for_stale_gems(line, locked, relative, index, stale)
+      locked.each do |gem_name, locked_version|
+        pattern = /\b#{Regexp.escape(gem_name)}\b\s+v?(\d+\.\d+[\d.]*)\b/
+        line.scan(pattern).each do |match|
+          found_version = match[0]
+          next if found_version == locked_version
+
+          stale << {
+            file: relative,
+            line: index + 1,
+            gem: gem_name,
+            found: found_version,
+            expected: locked_version
+          }
+        end
+      end
+    end
+
+    def project_files
+      Dir.glob(@project_dir.join('**', '*'), File::FNM_DOTMATCH)
+        .select { |f| File.file?(f) }
+        .reject { |f| excluded?(f) }
+        .reject { |f| binary?(f) }
+        .sort
+    end
+
+    def excluded?(file)
+      relative = Pathname.new(file).relative_path_from(@project_dir).to_s
+
+      return true if EXCLUDED_DIRS.any? { |dir| relative.start_with?("#{dir}/") }
+      return true if EXCLUDED_FILES.include?(relative)
+      return true if EXCLUDED_PREFIXES.any? { |prefix| relative.start_with?(prefix) }
+      return true if EXCLUDED_EXTENSIONS.any? { |ext| relative.end_with?(ext) }
+
+      false
+    end
+
+    def binary?(file)
+      sample = File.read(file, 512)
+      return true if sample.nil?
+
+      sample.include?("\x00")
+    rescue ArgumentError
+      true
+    end
+
+    def constraint_line?(line)
+      line.match?(/[><=!~]{1,2}\s*\d+\.\d+/)
+    end
+
+    def suppressed_line?(line)
+      line.include?('rai:no-version-check')
+    end
+  end
+end

data/lib/rosett_ai/git_hooks/chain_detector.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module GitHooks
+    # Detects existing git hook managers and hook scripts in a repository.
+    #
+    # Identifies overcommit, husky, lefthook, and plain shell hooks
+    # to inform the installer about chaining requirements.
+    #
+    # @author hugo
+    # @author claude
+    class ChainDetector
+      KNOWN_MANAGERS = {
+        'overcommit' => { marker: /overcommit/i, config: '.overcommit.yml' },
+        'husky' => { marker: /husky/i, config: '.husky' },
+        'lefthook' => { marker: /lefthook/i, config: 'lefthook.yml' }
+      }.freeze
+
+      # @param project_root [Pathname] path to the project root
+      def initialize(project_root:)
+        @project_root = Pathname.new(project_root)
+        @hooks_dir = @project_root.join('.git', 'hooks')
+      end
+
+      # Detects which hook managers are present in the project.
+      #
+      # @return [Array<Hash>] list of detected managers with :name and :type
+      def detect
+        managers = []
+
+        KNOWN_MANAGERS.each do |name, info|
+          config_path = @project_root.join(info[:config])
+          managers << { name: name, type: :config } if config_path.exist?
+        end
+
+        managers
+      end
+
+      # Checks if a specific hook has an existing non-rosett-ai script.
+      #
+      # @param hook_name [String] the git hook name
+      # @return [Hash, nil] info about the existing hook or nil
+      def existing_hook(hook_name)
+        path = @hooks_dir.join(hook_name)
+        return nil unless path.exist?
+        return nil if rai_managed?(path)
+
+        content = File.read(path)
+        manager = identify_manager(content)
+
+        {
+          path: path.to_s,
+          manager: manager,
+          symlink: path.symlink?,
+          executable: path.executable?
+        }
+      end
+
+      # Checks all supported hooks for existing non-rosett-ai scripts.
+      #
+      # @return [Hash{String => Hash}] map of hook names to existing hook info
+      def all_existing
+        Installer::SUPPORTED_HOOKS.each_with_object({}) do |hook, result|
+          info = existing_hook(hook)
+          result[hook] = info if info
+        end
+      end
+
+      private
+
+      def rai_managed?(path)
+        File.read(path).include?(Installer::RAI_MARKER)
+      end
+
+      def identify_manager(content)
+        KNOWN_MANAGERS.each do |name, info|
+          return name if content.match?(info[:marker])
+        end
+        'unknown'
+      end
+    end
+  end
+end