rosett-ai 1.3.3

data/lib/rosett_ai/doctor/checks/stale_home_nncc_check.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Doctor
+    module Checks
+      # Warns when a stale .rosett-ai/ directory exists at $HOME level.
+      #
+      # Having .rosett-ai/ at $HOME is almost never intentional — it is typically
+      # left over from a previous `rai init --project` run at the home
+      # directory. It causes scope resolution confusion because behaviour
+      # files in ~/.rosett-ai/conf/behaviour/ shadow XDG-path files.
+      #
+      # @author hugo
+      # @author claude
+      class StaleHomeNnccCheck
+        include Check
+
+        check_name 'stale_home_nncc'
+
+        private
+
+        def perform
+          home_rai = Pathname.new(Dir.home).join('.rosett-ai')
+
+          unless home_rai.directory?
+            pass!(::I18n.t('rosett_ai.doctor.stale_home_nncc.clean'))
+            return
+          end
+
+          warn_stale(home_rai)
+        end
+
+        def warn_stale(home_rai)
+          path_str = home_rai.to_s
+          removal = ::I18n.t('rosett_ai.doctor.stale_home_nncc.remove', path: path_str)
+          behaviour_dir = home_rai.join('conf', 'behaviour')
+          children = behaviour_dir.directory? ? behaviour_dir.children : []
+
+          if children.any?
+            warn!(
+              ::I18n.t('rosett_ai.doctor.stale_home_nncc.found', path: path_str, count: children.count),
+              remediation: removal
+            )
+          else
+            warn!(
+              ::I18n.t('rosett_ai.doctor.stale_home_nncc.empty', path: path_str),
+              remediation: removal
+            )
+          end
+        end
+      end
+    end
+  end
+end
+
+RosettAi::Doctor.register(RosettAi::Doctor::Checks::StaleHomeNnccCheck)

data/lib/rosett_ai/doctor.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  # Self-diagnostic runner for Rosett-AI runtime prerequisites.
+  #
+  # Orchestrates registered checks and collects results.
+  # Each check implements the Check interface (#name, #run, #status,
+  # #message, #remediation).
+  #
+  # @author hugo
+  # @author claude
+  # @see conf/design/doctor.yml
+  module Doctor
+    STATUSES = ['pass', 'warn', 'fail'].freeze
+
+    @checks = []
+    @mutex = Mutex.new
+
+    class << self
+      # Register a check class.
+      #
+      # @param check_class [Class] a class that includes Doctor::Check
+      # @return [void]
+      def register(check_class)
+        @mutex.synchronize { @checks << check_class }
+      end
+
+      # Return all registered check classes.
+      #
+      # @return [Array<Class>]
+      def checks
+        @mutex.synchronize { @checks.dup }
+      end
+
+      # Return the names of all registered checks.
+      #
+      # @return [Array<String>]
+      def check_names
+        checks.map(&:check_name)
+      end
+
+      # Run all registered checks (or a filtered subset).
+      #
+      # @param only [String, nil] run only the named check
+      # @return [Array<Hash>] results with :name, :status, :message, :remediation
+      def run_all(only: nil)
+        targets = only ? checks.select { |klass| klass.check_name == only } : checks
+        targets.map do |check_class|
+          instance = check_class.new
+          instance.run
+          {
+            name: instance.name,
+            status: instance.status.to_s,
+            message: instance.message,
+            remediation: instance.remediation
+          }
+        end
+      end
+
+      # Determine the overall exit code from results.
+      #
+      # @param results [Array<Hash>] check results
+      # @return [Integer] 0=all pass, 1=any warn, 2=any fail
+      def exit_code(results)
+        return 2 if results.any? { |r| r[:status] == 'fail' }
+        return 1 if results.any? { |r| r[:status] == 'warn' }
+
+        0
+      end
+
+      # Reset registered checks. Intended for test isolation.
+      # @return [void]
+      def reset!
+        @mutex.synchronize { @checks = [] }
+      end
+    end
+  end
+end

data/lib/rosett_ai/documentation/reference_compiler.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'fileutils'
+require 'pathname'
+
+module RosettAi
+  module Documentation
+    # Compiles the LaTeX technical reference document.
+    #
+    # Runs the full pdflatex → biber → makeindex → pdflatex toolchain
+    # to produce doc/reference/rosett-ai-technical-reference.pdf from the
+    # LaTeX sources in doc/reference/src/.
+    #
+    # Design reference: conf/design/documentation.yml
+    class ReferenceCompiler
+      REQUIRED_TOOLS = ['pdflatex', 'biber', 'makeindex'].freeze
+      OUTPUT_NAME = 'rosett-ai-technical-reference.pdf'
+      BUILD_ARTIFACTS = ['aux', 'bbl', 'bcf', 'blg', 'idx', 'ilg', 'ind',
+                         'lof', 'log', 'lot', 'out', 'ptc', 'run.xml', 'toc'].freeze
+
+      def initialize(root: nil)
+        @root = root || RosettAi.root
+      end
+
+      def available?
+        REQUIRED_TOOLS.all? { |tool| tool_on_path?(tool) }
+      end
+
+      def missing_tools
+        REQUIRED_TOOLS.reject { |tool| tool_on_path?(tool) }
+      end
+
+      def stale?
+        pdf = output_path
+        return true unless pdf.exist?
+
+        pdf_mtime = pdf.mtime
+        source_files.any? { |f| f.mtime > pdf_mtime }
+      end
+
+      def compile!
+        raise RosettAi::DocumentationError, "Missing LaTeX tools: #{missing_tools.join(', ')}" unless available?
+        raise RosettAi::DocumentationError, "Source directory not found: #{source_dir}" unless source_dir.exist?
+
+        Dir.chdir(source_dir) do
+          run_pdflatex!
+          run_biber!
+          run_makeindex
+          3.times { run_pdflatex! }
+        end
+
+        install_pdf!
+        clean_artifacts!
+      end
+
+      def output_path
+        @root.join('doc', 'reference', OUTPUT_NAME)
+      end
+
+      def source_dir
+        @root.join('doc', 'reference', 'src')
+      end
+
+      private
+
+      def source_files
+        patterns = [
+          @root.join('conf', 'design', '*.yml'),
+          @root.join('conf', 'schemas', '*.json'),
+          source_dir.join('*.tex'),
+          source_dir.join('*.bib'),
+          source_dir.join('*.ist')
+        ]
+        patterns.flat_map { |pat| Dir.glob(pat).map { |f| Pathname.new(f) } }
+      end
+
+      def run_pdflatex!
+        success = system('pdflatex', '-interaction=nonstopmode', 'main.tex',
+                         [:out, :err] => File::NULL)
+        raise RosettAi::DocumentationError, 'pdflatex compilation failed' unless success
+      end
+
+      def run_biber!
+        success = system('biber', 'main', [:out, :err] => File::NULL)
+        raise RosettAi::DocumentationError, 'biber bibliography processing failed' unless success
+      end
+
+      # makeindex failure is non-fatal — the document compiles without an index
+      def run_makeindex
+        idx_file = source_dir.join('main.idx')
+        return unless idx_file.exist?
+
+        system('makeindex', 'main.idx', '-s', 'StyleInd.ist',
+               [:out, :err] => File::NULL)
+      end
+
+      def install_pdf!
+        built_pdf = source_dir.join('main.pdf')
+        raise RosettAi::DocumentationError, 'LaTeX compilation produced no PDF' unless built_pdf.exist?
+
+        FileUtils.mkdir_p(output_path.dirname)
+        FileUtils.cp(built_pdf.to_s, output_path.to_s)
+      end
+
+      def clean_artifacts!
+        BUILD_ARTIFACTS.each do |ext|
+          FileUtils.rm_f(source_dir.join("main.#{ext}").to_s)
+        end
+        FileUtils.rm_f(source_dir.join('main.pdf').to_s)
+      end
+
+      def tool_on_path?(name)
+        ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).any? do |dir|
+          File.executable?(File.join(dir, name))
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/documentation/translator.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'fileutils'
+
+module RosettAi
+  module Documentation
+    # Produces draft translations of documentation files using the Claude API.
+    #
+    # Reads source documentation, sends to API with a translation prompt,
+    # and writes the result to doc/locales/{locale}/.
+    class Translator
+      MODEL = 'claude-sonnet-4-20250514'
+
+      def initialize(doc_dir: nil)
+        @doc_dir = doc_dir || RosettAi.root.join('doc')
+      end
+
+      def translate(source_file, from:, to:)
+        content = File.read(source_file)
+        basename = File.basename(source_file)
+
+        translated = call_api(content, from: from, to: to)
+
+        output_dir = @doc_dir.join('locales', to)
+        FileUtils.mkdir_p(output_dir)
+        output_path = output_dir.join(basename)
+        File.open(output_path, 'w', 0o644) { |f| f.write(translated) }
+
+        output_path.to_s
+      end
+
+      private
+
+      def call_api(content, from:, to:)
+        require 'anthropic' # lazy require — gem not in core deps
+        client = Anthropic::Client.new
+        response = client.messages.create(
+          model: MODEL,
+          max_tokens: 4096,
+          messages: [{ role: 'user', content: build_prompt(content, from: from, to: to) }]
+        )
+
+        response.content.first.text
+      end
+
+      def build_prompt(content, from:, to:)
+        <<~PROMPT
+          Translate the following documentation from #{from} to #{to}.
+          Preserve all markdown formatting, code blocks, and technical terms.
+          Do not translate code examples, file paths, or command names.
+          Return only the translated document, no explanations.
+
+          ---
+          #{content}
+        PROMPT
+      end
+    end
+  end
+end

data/lib/rosett_ai/engines/base_config_compiler.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'json'
+require 'json_schemer'
+require 'digest'
+
+module RosettAi
+  module Engines
+    # Abstract base class for engine config compilers.
+    #
+    # Extracts shared compilation infrastructure from Claude::ConfigCompiler:
+    # file discovery, YAML loading, schema validation, checksum diffing,
+    # action determination, and result writing.
+    #
+    # Subclasses must implement:
+    #   - #config_dir       → Pathname to scope YAML directory
+    #   - #schema_path      → Pathname to JSON Schema file
+    #   - #scope_router     → object responding to #target_path(scope)
+    #   - #transform(data, scope) → [json_data, warnings]
+    #   - #output_format    → Symbol (:json, :yaml)
+    class BaseConfigCompiler
+      HEADER_KEYS = ['name', 'scope', 'version', 'status', 'compatibility',
+                     'author', 'created_at', 'modified_at', 'modified_by'].freeze
+
+      def initialize(simulate: false, secret_resolver: nil)
+        @simulate = simulate
+        @secret_resolver = secret_resolver || RosettAi::Config::SecretResolver.new
+        @schema = load_schema
+      end
+
+      # Compile all scope files. Returns [RosettAi::Config::CompileResult].
+      def compile
+        discover_scope_files.map { |path| compile_scope(path) }
+      end
+
+      # Compile a single scope file. Returns RosettAi::Config::CompileResult.
+      def compile_scope(path)
+        warnings = []
+        data = load_and_validate(path)
+        header = extract_header(data)
+        scope = header['scope']
+        warnings.concat(check_compatibility(header, path))
+
+        json_data, transform_warnings = transform(data, scope)
+        warnings.concat(transform_warnings)
+
+        json_data = @secret_resolver.resolve_all(json_data)
+
+        target = scope_router.target_path(scope)
+        action, diff = determine_action(target, json_data)
+
+        RosettAi::Config::CompileResult.new(
+          scope: scope, source_path: Pathname.new(path), target_path: target,
+          json_data: json_data, warnings: warnings, action: action, diff: diff
+        )
+      rescue RosettAi::Error, ArgumentError, JSON::Schema::ValidationError => e
+        RosettAi::Config::CompileResult.new(
+          scope: extract_scope_from_path(path), source_path: Pathname.new(path),
+          target_path: nil, json_data: nil,
+          warnings: [e.message], action: :skipped, diff: nil
+        )
+      end
+
+      # Discover scope files in the engine's config directory.
+      def discover_scope_files
+        dir = config_dir
+        return [] unless dir.exist?
+
+        Dir.glob(dir.join('*.yml'))
+      end
+
+      # Write compiled results to their target paths.
+      def write_results(results)
+        return results if @simulate
+
+        results.each do |result|
+          next unless result.changed? && result.target_path
+
+          write_output(result.target_path, result.json_data)
+        end
+        results
+      end
+
+      protected
+
+      # Subclass must override: path to scope YAML directory.
+      def config_dir
+        raise NotImplementedError, "#{self.class}#config_dir must be implemented"
+      end
+
+      # Subclass must override: path to JSON Schema file.
+      def schema_path
+        raise NotImplementedError, "#{self.class}#schema_path must be implemented"
+      end
+
+      # Subclass must override: scope router instance.
+      def scope_router
+        raise NotImplementedError, "#{self.class}#scope_router must be implemented"
+      end
+
+      # Subclass must override: transform data into output format.
+      # @return [Array(Hash, Array<String>)] [output_data, warnings]
+      def transform(_data, _scope)
+        raise NotImplementedError, "#{self.class}#transform must be implemented"
+      end
+
+      # Subclass may override: output format (:json or :yaml).
+      def output_format = :json
+
+      # Subclass may override: compatibility checks.
+      def check_compatibility(_header, _path)
+        []
+      end
+
+      private
+
+      def load_schema
+        schema_data = JSON.parse(schema_path.read)
+        JSONSchemer.schema(schema_data)
+      end
+
+      def load_and_validate(path)
+        data = RosettAi::YamlLoader.load_file(path)
+        errors = @schema.validate(data).to_a
+        return data if errors.empty?
+
+        messages = errors.map do |err|
+          pointer = err['data_pointer'].empty? ? 'root' : err['data_pointer']
+          "#{pointer}: #{err['type']}"
+        end
+        raise RosettAi::ValidationError, "Schema validation failed for #{path}: #{messages.join(', ')}"
+      end
+
+      def extract_header(data)
+        HEADER_KEYS.each_with_object({}) do |key, header|
+          header[key] = data[key] if data.key?(key)
+        end
+      end
+
+      def determine_action(target_path, output_data)
+        return [:created, nil] unless target_path.exist?
+
+        existing = File.read(target_path)
+        new_content = serialize(output_data)
+
+        if checksum(existing) == checksum(new_content)
+          [:unchanged, nil]
+        else
+          diff = @simulate ? generate_diff(existing, new_content) : nil
+          [:updated, diff]
+        end
+      rescue Errno::ENOENT
+        [:created, nil]
+      end
+
+      def serialize(data)
+        case output_format
+        when :yaml then YAML.dump(data)
+        else JSON.pretty_generate(data)
+        end
+      end
+
+      def generate_diff(old_content, new_content)
+        old_lines = old_content.lines
+        new_lines = new_content.lines
+
+        lines = []
+        lines << '--- a/settings'
+        lines << '+++ b/settings'
+
+        max = [old_lines.size, new_lines.size].max
+        (0...max).each do |i|
+          old_line = old_lines[i]
+          new_line = new_lines[i]
+          next if old_line == new_line
+
+          lines << "@@ -#{i + 1} +#{i + 1} @@"
+          lines << "-#{old_line&.chomp}" if old_line
+          lines << "+#{new_line&.chomp}" if new_line
+        end
+
+        lines.join("\n")
+      end
+
+      def checksum(content)
+        Digest::SHA256.hexdigest(content)
+      end
+
+      def write_output(path, data)
+        FileUtils.mkdir_p(path.dirname)
+        content = serialize(data)
+        File.open(path, 'w', 0o644) { |f| f.write(content) }
+      end
+
+      def extract_scope_from_path(path)
+        File.basename(path, '.yml')
+      end
+    end
+  end
+end

data/lib/rosett_ai/engines/detector.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Engines
+    # Base engine detector that reads manifest detection rules and probes the system.
+    #
+    # Subclasses may override `custom_checks` to add engine-specific detection logic
+    # beyond the manifest-driven cli_binary and config_dir checks.
+    class Detector
+      attr_reader :engine_name
+
+      def initialize(engine_name)
+        @engine_name = engine_name.to_s
+        @manifest = Registry.manifest(@engine_name)
+      end
+
+      def detect
+        checks = []
+        detection = @manifest['detection'] || {}
+
+        checks << check_cli_binary(detection['cli_binary']) if detection['cli_binary']
+        checks << check_config_dir(detection['config_dir']) if detection['config_dir']
+        checks.concat(custom_checks)
+
+        {
+          engine: @engine_name,
+          display_name: @manifest['display_name'],
+          checks: checks,
+          detected: checks.all? { |check| check[:passed] }
+        }
+      end
+
+      protected
+
+      def custom_checks
+        []
+      end
+
+      private
+
+      def check_cli_binary(binary_name)
+        found = system('which', binary_name, out: File::NULL, err: File::NULL)
+        {
+          type: :cli_binary,
+          name: binary_name,
+          passed: found == true
+        }
+      end
+
+      def check_config_dir(dir_path)
+        expanded = File.expand_path(dir_path)
+        {
+          type: :config_dir,
+          name: dir_path,
+          passed: Dir.exist?(expanded)
+        }
+      end
+    end
+  end
+end

data/lib/rosett_ai/engines/registry.rb

@@ -0,0 +1,50 @@
+# 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 Engines
+    # Engine registry — delegates to RosettAi::Plugins::Registry for dynamic
+    # plugin discovery. External engine gems self-register via their
+    # register.rb files, discovered by Gem.find_files.
+    class Registry
+      class << self
+        def available
+          RosettAi::Plugins::Registry.available(:engine)
+        end
+
+        def engine_module(name)
+          RosettAi::Plugins::Registry.plugin_module(:engine, name.to_s)
+        end
+
+        def manifest(name)
+          mod = engine_module(name)
+          path = mod.manifest_path
+          raise RosettAi::Error, "No manifest for engine: #{name}" unless path.exist?
+
+          data = RosettAi::YamlLoader.load_file(path)
+          validate_manifest!(data, path)
+          data
+        end
+
+        private
+
+        def validate_manifest!(data, path)
+          schema_path = RosettAi.root.join('conf', 'schemas', 'engine_manifest_schema.json')
+          schema = JSON.parse(schema_path.read)
+          schemer = JSONSchemer.schema(schema)
+          errors = schemer.validate(data).to_a
+
+          return if errors.empty?
+
+          messages = errors.map { |e| "#{e['data_pointer']}: #{e['type']}" }
+          raise RosettAi::Error,
+                "Invalid engine manifest at #{path}: #{messages.join(', ')}"
+        end
+      end
+    end
+  end
+end