rosett-ai 1.3.3

data/lib/rosett_ai/version_consistency_checker.rb

@@ -0,0 +1,129 @@
+# 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 all Ruby version references across the codebase are consistent
+  # with the canonical version declared in .ruby-version.
+  #
+  # Scans non-binary project files for version strings matching the MAJOR.MINOR
+  # series (e.g. 3.3.x) and reports any that don't match the expected PATCH level.
+  class VersionConsistencyChecker
+    EXCLUDED_DIRS = ['vendor', 'tmp', 'coverage', '.git', '.bundle'].freeze
+    EXCLUDED_FILES = ['.ruby-version', 'CHANGELOG.md', 'Gemfile.lock',
+                      'Gemfile.integration.lock',
+                      'spec/rosett_ai/version_consistency_checker_spec.rb'].freeze
+    EXCLUDED_PREFIXES = ['doc/changes/', 'doc/claude-sessions/', 'doc/INCIDENT_REPORT',
+                         'doc/PACKAGING', 'doc/issues/', 'doc/context/', 'conf/design/'].freeze
+    EXCLUDED_EXTENSIONS = ['.aux', '.toc', '.out', '.ptc', '.log', '.idx', '.ind',
+                           '.ilg', '.bbl', '.blg', '.bcf', '.fls', '.fdb_latexmk',
+                           '.run.xml', '.synctex.gz'].freeze
+
+    attr_reader :results
+
+    def initialize(project_dir: Dir.pwd)
+      @project_dir = Pathname.new(project_dir)
+      @results = { expected_version: nil, references: [], mismatches: [], consistent: true }
+    end
+
+    def check
+      version = read_ruby_version
+      @results = { expected_version: version, references: [], mismatches: [], consistent: true }
+
+      pattern = build_version_pattern(version)
+      scan_files(version, pattern)
+
+      @results[:consistent] = @results[:mismatches].empty?
+      @results
+    end
+
+    def consistent?
+      check if @results[:expected_version].nil?
+      @results[:consistent]
+    end
+
+    private
+
+    def read_ruby_version
+      ruby_version_file = @project_dir.join('.ruby-version')
+      raise RosettAi::ToolingError, "Missing .ruby-version in #{@project_dir}" unless ruby_version_file.exist?
+
+      ruby_version_file.read.strip
+    end
+
+    def build_version_pattern(version)
+      major, minor = version.split('.')[0..1]
+      /\b#{Regexp.escape(major)}\.#{Regexp.escape(minor)}\.\d+\b/
+    end
+
+    def scan_files(expected, pattern)
+      project_files.each do |file|
+        scan_file(file, expected, pattern)
+      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, Errno::ENOENT
+      # ArgumentError: invalid encoding
+      # ENOENT: file deleted between glob and read (e.g., temp files)
+      true
+    end
+
+    def scan_file(file, expected, pattern)
+      relative = Pathname.new(file).relative_path_from(@project_dir).to_s
+
+      File.readlines(file, encoding: 'UTF-8').each_with_index do |line, index|
+        line.scan(pattern).each do |found|
+          next if constraint_line?(line)
+          next if suppressed_line?(line)
+
+          reference = {
+            file: relative,
+            line: index + 1,
+            found: found,
+            expected: expected
+          }
+
+          @results[:references] << reference
+          @results[:mismatches] << reference unless found == expected
+        end
+      end
+    rescue ArgumentError, Encoding::InvalidByteSequenceError
+      # Skip files with encoding issues
+    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/workflow/audit_log.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'json'
+
+module RosettAi
+  module Workflow
+    # Structured audit log for workflow execution.
+    #
+    # Records each step execution with timestamp, status, and duration.
+    # Supports resume by identifying completed steps from the log.
+    #
+    # @author hugo
+    # @author claude
+    class AuditLog
+      attr_reader :entries
+
+      # @param log_path [Pathname, nil] path to audit log file
+      def initialize(log_path: nil)
+        @log_path = log_path
+        @entries = load_entries
+      end
+
+      # Records a step execution result.
+      #
+      # @param workflow_name [String]
+      # @param step_name [String]
+      # @param status [String] 'pass', 'fail', or 'skip'
+      # @param duration_ms [Float]
+      # @param details [String, nil]
+      def record(workflow_name:, step_name:, status:, duration_ms: 0.0, details: nil)
+        entry = {
+          'workflow' => workflow_name,
+          'step' => step_name,
+          'status' => status,
+          'timestamp' => Time.now.utc.iso8601,
+          'duration_ms' => duration_ms.round(1)
+        }
+        entry['details'] = details if details
+        @entries << entry
+        persist_entry(entry)
+      end
+
+      # Returns step names that completed successfully for a workflow.
+      #
+      # @param workflow_name [String]
+      # @return [Array<String>] completed step names
+      def completed_steps(workflow_name)
+        @entries
+          .select { |e| e['workflow'] == workflow_name && e['status'] == 'pass' }
+          .map { |e| e['step'] }
+      end
+
+      # @return [Hash] serializable summary
+      def to_h
+        {
+          'entries' => @entries,
+          'total' => @entries.size,
+          'pass' => @entries.count { |e| e['status'] == 'pass' },
+          'fail' => @entries.count { |e| e['status'] == 'fail' }
+        }
+      end
+
+      private
+
+      def load_entries
+        return [] unless @log_path&.exist?
+
+        @log_path.each_line.filter_map do |line|
+          JSON.parse(line.strip)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+
+      def persist_entry(entry)
+        return unless @log_path
+
+        @log_path.dirname.mkpath
+        File.open(@log_path, 'a') { |f| f.puts(JSON.generate(entry)) }
+      end
+    end
+  end
+end

data/lib/rosett_ai/workflow/engine.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'yaml'
+require_relative 'schema_validator'
+require_relative 'step_runner'
+require_relative 'audit_log'
+
+module RosettAi
+  module Workflow
+    # Orchestrates declarative workflow execution.
+    #
+    # Loads workflow YAML, validates against schema, and executes
+    # steps sequentially. Supports dry-run (simulate), resume from
+    # audit log, and per-step on_failure handling.
+    #
+    # @author hugo
+    # @author claude
+    class Engine
+      attr_reader :workflow_data, :audit_log
+
+      # @param workflow_path [Pathname] path to workflow YAML file
+      # @param audit_log_path [Pathname, nil] path to audit log file
+      def initialize(workflow_path:, audit_log_path: nil)
+        @workflow_path = workflow_path
+        @workflow_data = load_workflow
+        @audit_log = AuditLog.new(log_path: audit_log_path)
+        @step_runner = StepRunner.new
+        @validator = SchemaValidator.new
+      end
+
+      # Validates the workflow definition.
+      #
+      # @return [Array<String>] validation errors (empty if valid)
+      def validate
+        @validator.validate(@workflow_data)
+      end
+
+      # Returns step descriptions for dry-run mode.
+      #
+      # @return [Array<String>] descriptions of each step
+      def simulate
+        errors = validate
+        raise RosettAi::WorkflowError, "Workflow validation failed: #{errors.join(', ')}" unless errors.empty?
+
+        @workflow_data.fetch('steps').map do |step_def|
+          @step_runner.describe(step_def)
+        end
+      end
+
+      # Executes the workflow.
+      #
+      # Runs each step in order. Skips steps already completed (via audit log).
+      # Stops on first failure unless the step has `on_failure: continue`.
+      #
+      # @param resume [Boolean] skip already-completed steps
+      # @return [Hash] execution summary with :status, :results, :workflow
+      def execute(resume: false)
+        errors = validate
+        raise RosettAi::WorkflowError, "Workflow validation failed: #{errors.join(', ')}" unless errors.empty?
+
+        workflow_name = @workflow_data.fetch('name')
+        completed = resume ? @audit_log.completed_steps(workflow_name) : []
+        results = []
+        failed = false
+
+        @workflow_data.fetch('steps').each do |step_def|
+          step_name = step_def.fetch('name')
+
+          if completed.include?(step_name)
+            results << { step: step_name, status: 'skip', message: 'Already completed (resume)' }
+            next
+          end
+
+          if failed
+            results << skip_result(step_name)
+            record_audit(workflow_name, step_name, 'skip')
+            next
+          end
+
+          result = run_step(workflow_name, step_def)
+          results << result
+
+          failed = true if result[:status] == 'fail' && step_def.fetch('on_failure', 'stop') == 'stop'
+        end
+
+        build_summary(workflow_name, results)
+      end
+
+      private
+
+      def load_workflow
+        raise RosettAi::WorkflowError, "Workflow file not found: #{@workflow_path}" unless @workflow_path.exist?
+
+        data = YAML.safe_load(@workflow_path.read, permitted_classes: [Date])
+        raise RosettAi::WorkflowError, 'Workflow file is empty or invalid YAML' unless data.is_a?(Hash)
+
+        data
+      end
+
+      def run_step(workflow_name, step_def)
+        step_name = step_def.fetch('name')
+        result = @step_runner.run(step_def)
+        record_audit(workflow_name, step_name, result[:status], result[:duration_ms])
+        { step: step_name, **result }
+      end
+
+      def record_audit(workflow_name, step_name, status, duration_ms = 0.0)
+        @audit_log.record(
+          workflow_name: workflow_name,
+          step_name: step_name,
+          status: status,
+          duration_ms: duration_ms
+        )
+      end
+
+      def skip_result(step_name)
+        { step: step_name, status: 'skip', message: 'Skipped (previous step failed)' }
+      end
+
+      def build_summary(workflow_name, results)
+        overall = if results.any? { |r| r[:status] == 'fail' }
+                    'fail'
+                  else
+                    'pass'
+                  end
+
+        {
+          workflow: workflow_name,
+          status: overall,
+          total: results.size,
+          pass: results.count { |r| r[:status] == 'pass' },
+          fail: results.count { |r| r[:status] == 'fail' },
+          skip: results.count { |r| r[:status] == 'skip' },
+          results: results
+        }
+      end
+    end
+  end
+end

data/lib/rosett_ai/workflow/manager.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Workflow
+    # MCP-facing facade for workflow operations.
+    #
+    # Delegates to {Engine} for the actual workflow logic, providing
+    # the simplified interface expected by {Mcp::Tools::WorkflowTool}.
+    #
+    # @author hugo
+    # @author claude
+    class Manager
+      WORKFLOW_DIR = File.join(Dir.home, '.claude', 'conf', 'workflows')
+
+      def initialize
+        @workflow_dir = Pathname.new(WORKFLOW_DIR)
+      end
+
+      # Lists all available workflows.
+      #
+      # @return [Array<Hash>] workflow summaries
+      def list
+        workflow_files.map { |path| build_workflow_summary(path) }
+      end
+
+      # Validates a specific workflow by name.
+      #
+      # @param name [String] workflow name
+      # @return [Hash] with :errors key
+      def validate(name)
+        engine = build_engine(name)
+        { errors: engine.validate }
+      end
+
+      # Validates all workflows.
+      #
+      # @return [Hash] with :errors key
+      def validate_all
+        errors = workflow_files.flat_map { |path| validate_workflow_file(path) }
+        { errors: errors }
+      end
+
+      # Simulates a workflow without executing.
+      #
+      # @param name [String] workflow name
+      # @return [Hash] with :steps and :duration keys
+      def simulate(name)
+        engine = build_engine(name)
+        steps = engine.simulate
+        { steps: steps, duration: steps.size }
+      end
+
+      private
+
+      def workflow_files
+        return [] unless @workflow_dir.exist?
+
+        @workflow_dir.glob('*.yml').sort
+      end
+
+      def build_workflow_summary(path)
+        data = YAML.safe_load_file(path, permitted_classes: [Date])
+        { name: data['name'], description: data['description'], path: path.to_s }
+      end
+
+      def validate_workflow_file(path)
+        engine = Engine.new(workflow_path: path)
+        engine.validate.map { |e| "#{File.basename(path)}: #{e}" }
+      end
+
+      def build_engine(name)
+        path = @workflow_dir.join("#{name}.yml")
+        raise RosettAi::WorkflowError, "Workflow '#{name}' not found" unless path.exist?
+
+        Engine.new(workflow_path: path)
+      end
+    end
+  end
+end

data/lib/rosett_ai/workflow/schema_validator.rb

@@ -0,0 +1,71 @@
+# 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 Workflow
+    # Validates workflow YAML files against the workflow JSON Schema.
+    #
+    # Additionally enforces security constraints: shell steps must use
+    # array-form commands, prompt steps must not contain secret literals.
+    #
+    # @author hugo
+    # @author claude
+    class SchemaValidator
+      MAX_STEPS = 50
+      SCHEMA_PATH = File.expand_path('../../../conf/schemas/workflow_schema.json', __dir__)
+
+      # @param data [Hash] parsed workflow YAML
+      # @return [Array<String>] validation errors (empty if valid)
+      def validate(data)
+        errors = schema_errors(data)
+        errors += security_errors(data) if errors.empty?
+        errors
+      end
+
+      # @param data [Hash] parsed workflow YAML
+      # @return [Boolean]
+      def valid?(data)
+        validate(data).empty?
+      end
+
+      private
+
+      def schema_errors(data)
+        schema = JSONSchemer.schema(Pathname.new(SCHEMA_PATH))
+        schema.validate(data).map do |error|
+          "#{error['data_pointer']}: #{error['type']}"
+        end
+      end
+
+      def security_errors(data)
+        errors = []
+        steps = data.fetch('steps', [])
+
+        errors << "Workflow exceeds maximum step count (#{MAX_STEPS})" if steps.size > MAX_STEPS
+
+        steps.each_with_index do |step, idx|
+          errors += validate_step(step, idx)
+        end
+
+        errors
+      end
+
+      def validate_step(step, idx)
+        errors = []
+        case step['type']
+        when 'shell'
+          unless step['command'].is_a?(Array)
+            errors << "Step #{idx + 1} (#{step['name']}): shell command must be an array"
+          end
+        when 'prompt'
+          errors << "Step #{idx + 1} (#{step['name']}): prompt is required" unless step['prompt']
+        end
+        errors
+      end
+    end
+  end
+end

data/lib/rosett_ai/workflow/step_runner.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require_relative 'steps/shell_step'
+require_relative 'steps/rai_step'
+require_relative 'steps/prompt_step'
+
+module RosettAi
+  module Workflow
+    # Dispatches workflow step definitions to the appropriate step class.
+    #
+    # Maps step type strings to step implementations and handles
+    # step-level error recovery (on_failure: continue vs stop).
+    #
+    # @author hugo
+    # @author claude
+    class StepRunner
+      STEP_TYPES = {
+        'shell' => Steps::ShellStep,
+        'rai' => Steps::RaiStep,
+        'prompt' => Steps::PromptStep
+      }.freeze
+
+      # Executes a single step definition.
+      #
+      # @param step_def [Hash] step definition from workflow YAML
+      # @return [Hash] execution result with :status, :message, :duration_ms
+      # @raise [RosettAi::WorkflowError] if step type is unknown
+      def run(step_def)
+        step_class = resolve_step_class(step_def)
+        step = step_class.new(step_def)
+        step.execute
+      rescue RosettAi::WorkflowError
+        raise
+      rescue StandardError => e
+        { status: 'fail', message: "Step '#{step_def['name']}' raised: #{e.message}", duration_ms: 0.0 }
+      end
+
+      # Returns a description string for dry-run mode.
+      #
+      # @param step_def [Hash] step definition from workflow YAML
+      # @return [String] human-readable step description
+      def describe(step_def)
+        step_class = resolve_step_class(step_def)
+        step = step_class.new(step_def)
+        step.describe
+      end
+
+      private
+
+      def resolve_step_class(step_def)
+        type = step_def.fetch('type')
+        STEP_TYPES.fetch(type) do
+          raise RosettAi::WorkflowError, "Unknown step type '#{type}' in step '#{step_def['name']}'"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# 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
+      # Sends a prompt to an AI engine and captures the response.
+      #
+      # Requires network connectivity unless stubbed. Currently a stub
+      # implementation that records the prompt text — engine integration
+      # will be wired when MCP/engine APIs are available.
+      #
+      # @author hugo
+      # @author claude
+      class PromptStep
+        # @param definition [Hash] step definition from workflow YAML
+        def initialize(definition)
+          @definition = definition
+          @prompt = definition.fetch('prompt')
+          @engine = definition['engine']
+          validate!
+        end
+
+        # @return [String] step description for dry-run
+        def describe
+          engine_label = @engine ? " (engine: #{@engine})" : ''
+          "[prompt] #{@definition['name']}#{engine_label} — #{truncate(@prompt, 60)}"
+        end
+
+        # Executes the prompt step.
+        #
+        # Currently a stub: records the prompt and returns a pass result.
+        # Engine integration will dispatch to the configured engine's API.
+        #
+        # @return [Hash] execution result with :status and :message
+        def execute
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(1)
+
+          { status: 'pass', message: "Prompt recorded: #{truncate(@prompt, 80)}", duration_ms: elapsed }
+        end
+
+        private
+
+        def validate!
+          return if @prompt.is_a?(String)
+
+          raise RosettAi::WorkflowError,
+                "Prompt step '#{@definition['name']}' requires a prompt string"
+        end
+
+        def truncate(text, max_length)
+          return text if text.length <= max_length
+
+          "#{text[0, max_length - 3]}..."
+        end
+      end
+    end
+  end
+end