rosett-ai 1.3.3

data/lib/rosett_ai/project/sync_manager.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'yaml'
+
+module RosettAi
+  module Project
+    # Handles upstream synchronization for rosett-ai-managed projects.
+    #
+    # Detects breaking changes when upstream templates are updated and
+    # applies updates with user confirmation or --force flag.
+    #
+    # @author hugo
+    # @author claude
+    class SyncManager
+      # @param project_root [Pathname] root directory of the project
+      # @param force [Boolean] apply breaking changes without prompting
+      def initialize(project_root:, force: false)
+        @project_root = project_root
+        @project_dir = project_root.join('.rosett-ai')
+        @force = force
+      end
+
+      # Synchronizes the project with upstream template updates.
+      #
+      # @return [Hash] result with :updated, :conflicts, :skipped arrays
+      def sync
+        validate!
+        origin = load_origin
+        template_name = origin['template']
+        template_dir = RosettAi.root.join(TemplateApplier::TEMPLATES_DIR, template_name)
+
+        unless template_dir.directory?
+          return { updated: [], conflicts: [], skipped: [],
+                   error: 'Template no longer available' }
+        end
+
+        results = { updated: [], conflicts: [], skipped: [] }
+
+        Dir.glob(template_dir.join('**', '*').to_s).each do |tmpl_path|
+          tmpl = Pathname.new(tmpl_path)
+          next if tmpl.directory?
+
+          relative = tmpl.relative_path_from(template_dir)
+          dest = @project_dir.join(relative)
+
+          sync_file(tmpl, dest, relative, results)
+        end
+
+        update_origin_timestamp(origin) unless results[:updated].empty?
+        results
+      end
+
+      # Preview what sync would change without applying.
+      #
+      # @return [Hash] same structure as sync but without writing files
+      def simulate
+        validate!
+        origin = load_origin
+        template_name = origin['template']
+        template_dir = RosettAi.root.join(TemplateApplier::TEMPLATES_DIR, template_name)
+
+        return { updated: [], conflicts: [], skipped: [] } unless template_dir.directory?
+
+        results = { updated: [], conflicts: [], skipped: [] }
+
+        Dir.glob(template_dir.join('**', '*').to_s).each do |tmpl_path|
+          tmpl = Pathname.new(tmpl_path)
+          next if tmpl.directory?
+
+          relative = tmpl.relative_path_from(template_dir)
+          dest = @project_dir.join(relative)
+
+          classify_change(tmpl, dest, relative, results)
+        end
+
+        results
+      end
+
+      private
+
+      def validate!
+        raise RosettAi::ProjectError, 'Project .rosett-ai/ directory not found' unless @project_dir.directory?
+
+        origin_file = @project_dir.join('.template_origin.yml')
+        return if origin_file.exist?
+
+        raise RosettAi::ProjectError,
+              'No template origin found. Run rai project apply-template first.'
+      end
+
+      def load_origin
+        YAML.safe_load(@project_dir.join('.template_origin.yml').read)
+      end
+
+      def sync_file(tmpl, dest, relative, results)
+        unless dest.exist?
+          dest.dirname.mkpath
+          FileUtils.cp(tmpl.to_s, dest.to_s)
+          results[:updated] << relative.to_s
+          return
+        end
+
+        return if files_identical?(tmpl, dest)
+
+        if @force
+          FileUtils.cp(tmpl.to_s, dest.to_s)
+          results[:updated] << relative.to_s
+        else
+          results[:conflicts] << relative.to_s
+        end
+      end
+
+      def classify_change(tmpl, dest, relative, results)
+        unless dest.exist?
+          results[:updated] << relative.to_s
+          return
+        end
+
+        return if files_identical?(tmpl, dest)
+
+        results[:conflicts] << relative.to_s
+      end
+
+      def files_identical?(file_a, file_b)
+        Digest::SHA256.file(file_a.to_s).hexdigest == Digest::SHA256.file(file_b.to_s).hexdigest
+      end
+
+      def update_origin_timestamp(origin)
+        origin['synced_at'] = Time.now.utc.iso8601
+        origin['rai_version'] = RosettAi::VERSION
+        File.write(@project_dir.join('.template_origin.yml'), YAML.dump(origin))
+      end
+    end
+  end
+end

data/lib/rosett_ai/project/template_applier.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'yaml'
+require 'fileutils'
+
+module RosettAi
+  module Project
+    # Applies project templates to populate .rosett-ai/ with starter configs.
+    #
+    # Templates are directories under conf/templates/ containing behaviour
+    # and design YAML files. Application never overwrites user-modified
+    # files without explicit --force flag.
+    #
+    # @author hugo
+    # @author claude
+    class TemplateApplier
+      TEMPLATES_DIR = 'conf/templates'
+
+      # @param project_root [Pathname] root directory of the project
+      # @param template_name [String] name of the template to apply
+      # @param force [Boolean] overwrite existing files
+      def initialize(project_root:, template_name:, force: false)
+        @project_root = project_root
+        @template_name = template_name
+        @force = force
+        @project_dir = project_root.join('.rosett-ai')
+      end
+
+      # Applies the template to the project.
+      #
+      # @return [Hash] result with :applied, :skipped, :errors arrays
+      def apply
+        validate!
+        results = { applied: [], skipped: [], errors: [] }
+
+        template_files.each do |src_path|
+          relative = src_path.relative_path_from(template_dir)
+          dest = @project_dir.join(relative)
+          apply_file(src_path, dest, results)
+        end
+
+        record_template_origin
+        results
+      end
+
+      # @return [Boolean] true if the template exists
+      def template_exists?
+        template_dir.directory?
+      end
+
+      # @return [Array<String>] list of available template names
+      def self.available_templates
+        dir = RosettAi.root.join(TEMPLATES_DIR)
+        return [] unless dir.directory?
+
+        Dir.children(dir.to_s)
+          .select { |name| dir.join(name).directory? }
+          .sort
+      end
+
+      private
+
+      def validate!
+        raise RosettAi::ProjectError, "Template '#{@template_name}' not found" unless template_exists?
+        raise RosettAi::ProjectError, 'Project .rosett-ai/ directory not found' unless @project_dir.directory?
+      end
+
+      def template_dir
+        RosettAi.root.join(TEMPLATES_DIR, @template_name)
+      end
+
+      def template_files
+        Dir.glob(template_dir.join('**', '*').to_s)
+          .map { |path| Pathname.new(path) }
+          .reject(&:directory?)
+      end
+
+      def apply_file(src, dest, results)
+        dest.dirname.mkpath
+
+        if dest.exist? && !@force
+          results[:skipped] << dest.relative_path_from(@project_root).to_s
+        else
+          FileUtils.cp(src.to_s, dest.to_s)
+          results[:applied] << dest.relative_path_from(@project_root).to_s
+        end
+      rescue StandardError => e
+        results[:errors] << "#{dest}: #{e.message}"
+      end
+
+      def record_template_origin
+        origin_file = @project_dir.join('.template_origin.yml')
+        data = {
+          'template' => @template_name,
+          'applied_at' => Time.now.utc.iso8601,
+          'rai_version' => RosettAi::VERSION
+        }
+        File.write(origin_file, YAML.dump(data))
+      end
+    end
+  end
+end

data/lib/rosett_ai/project_context.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
+  # Detects whether Dir.pwd is inside an rosett-ai-managed project by walking
+  # up from the start directory looking for a `.rosett-ai/` marker directory.
+  #
+  # When found, content commands (design, behaviour, compile) resolve
+  # their source paths relative to the project's `.rosett-ai/` directory
+  # instead of the Rosett-AI installation root.
+  class ProjectContext
+    # Directory name that marks the root of an rai project.
+    PROJECT_MARKER = '.rosett-ai'
+
+    # @return [Pathname, nil] absolute path to the project root, or nil if no project detected
+    attr_reader :project_root
+
+    # @param start_dir [String] directory to begin searching from.
+    #   Defaults to `RAI_ORIGINAL_PWD` env var (set by the `.deb` wrapper
+    #   to preserve the user's directory), falling back to `Dir.pwd`.
+    def initialize(start_dir: ENV.fetch('RAI_ORIGINAL_PWD', Dir.pwd))
+      @project_root = detect_project_root(start_dir)
+    end
+
+    # @return [Boolean] true if a `.rosett-ai/` marker was found
+    def project?
+      !@project_root.nil?
+    end
+
+    # @return [Boolean] true if the detected project is the Rosett-AI installation itself
+    #   or the Rosett-AI source tree (when running the installed .deb from source)
+    def rai_internal?
+      @project_root == RosettAi.root || nncc_source_tree?
+    end
+
+    # @return [Pathname] the `.rosett-ai/` directory if inside a project, otherwise `RosettAi.root`
+    #
+    # When inside the rosett-ai source tree, returns the source tree root (not `.rosett-ai/`)
+    # so that `conf/` resolves to the real configuration directory containing
+    # behaviour and design YAML files, rather than the empty `.rosett-ai/conf/`
+    # placeholder created by `rai init --project`.
+    def conf_root
+      return @project_root if rai_internal?
+
+      project? ? @project_root.join(PROJECT_MARKER) : RosettAi.root
+    end
+
+    # @return [Pathname] path to the `conf/` subdirectory for behaviour/design files
+    def project_conf_dir
+      conf_root.join('conf')
+    end
+
+    private
+
+    # Detects the Rosett-AI source tree by checking for the gem's main entry
+    # point and gemspec. This combination is unique to rosett-ai — no other
+    # rosett-ai-managed project will have both files at the project root.
+    #
+    # Handles the case where the installed .deb package (RosettAi.root = /opt/rosett-ai/app)
+    # is run from the Rosett-AI source tree (project_root = ~/git/.../rosett-ai).
+    # Without this check, rai_internal? returns false and conf_root resolves
+    # to the empty .rosett-ai/conf/ placeholder instead of the real conf/ directory.
+    #
+    # @return [Boolean]
+    def nncc_source_tree?
+      return false unless @project_root
+
+      @project_root.join('lib', 'rosett_ai.rb').exist? &&
+        @project_root.join('rosett_ai.gemspec').exist?
+    end
+
+    def detect_project_root(dir)
+      path = Pathname.new(dir).expand_path
+      path.ascend do |ancestor|
+        marker = ancestor.join(PROJECT_MARKER)
+        return ancestor if marker.directory?
+      end
+    end
+  end
+end

data/lib/rosett_ai/provenance/entry.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 Provenance
+    # A single provenance entry recording AI involvement in a commit.
+    #
+    # Each entry captures the commit SHA, contributor identity, AI tool used,
+    # the AI's role, and which files were involved.
+    class Entry
+      ALLOWED_ROLES = [
+        'AI-Generated-By',
+        'AI-Co-Author',
+        'AI-Assisted-By',
+        'AI-Reviewed-By'
+      ].freeze
+
+      attr_reader :commit, :contributor, :ai_tool, :ai_role, :files, :timestamp
+
+      # @param commit [String] git commit SHA
+      # @param contributor [String] contributor name and email
+      # @param ai_tool [String] AI tool identifier (e.g. "Claude Opus 4.6 (Anthropic)")
+      # @param ai_role [String] one of {ALLOWED_ROLES}
+      # @param files [Array<Hash>] file-level source references
+      # @param timestamp [String, nil] ISO 8601 timestamp (defaults to now)
+      # rubocop:disable Metrics/ParameterLists -- provenance entry requires all fields
+      def initialize(commit:, contributor:, ai_tool:, ai_role:, files: [], timestamp: nil)
+        validate_role!(ai_role)
+
+        @commit = commit.freeze
+        @contributor = contributor.freeze
+        @ai_tool = ai_tool.freeze
+        @ai_role = ai_role.freeze
+        @files = files.freeze
+        @timestamp = (timestamp || Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')).freeze
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # @return [Hash] serializable representation for YAML output
+      def to_h
+        {
+          'commit' => @commit,
+          'timestamp' => @timestamp,
+          'contributor' => @contributor,
+          'ai_tool' => @ai_tool,
+          'ai_role' => @ai_role,
+          'files' => @files.map { |file| file.is_a?(Hash) ? file : file.to_h }
+        }
+      end
+
+      private
+
+      def validate_role!(role)
+        return if ALLOWED_ROLES.include?(role)
+
+        raise ArgumentError,
+              "Invalid AI role '#{role}'. Allowed: #{ALLOWED_ROLES.join(', ')}"
+      end
+    end
+  end
+end

data/lib/rosett_ai/provenance/file_source.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Provenance
+    # Represents a file-level source reference within a provenance entry.
+    #
+    # Tracks which files were involved in an AI contribution and
+    # what lines or sections were affected.
+    class FileSource
+      attr_reader :path, :lines, :source_type
+
+      # @param path [String] relative path from project root
+      # @param lines [String, nil] line range (e.g. "1-50") or nil for whole file
+      # @param source_type [String] one of Source::ALLOWED_TYPES
+      def initialize(path:, source_type:, lines: nil)
+        @path = path.freeze
+        @lines = lines&.freeze
+        @source_type = source_type.freeze
+      end
+
+      # @return [Hash] serializable representation
+      def to_h
+        hash = { 'path' => @path, 'source_type' => @source_type }
+        hash['lines'] = @lines if @lines
+        hash
+      end
+    end
+  end
+end

data/lib/rosett_ai/provenance/source.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 Provenance
+    # Classifies the source type of an AI contribution.
+    #
+    # Source types track where AI-generated code drew its knowledge from,
+    # enabling license traceability and compliance auditing.
+    class Source
+      ALLOWED_TYPES = [
+        'library_api',
+        'project_code',
+        'documentation',
+        'pattern',
+        'external_source'
+      ].freeze
+
+      attr_reader :type, :reference, :url
+
+      # @param type [String] one of {ALLOWED_TYPES}
+      # @param reference [String] human-readable description of the source
+      # @param url [String, nil] URL for external_source type
+      # @raise [ArgumentError] if type is not in {ALLOWED_TYPES}
+      # @raise [ArgumentError] if external_source has bare domain URL
+      def initialize(type:, reference:, url: nil)
+        validate_type!(type)
+        validate_url!(type, url)
+
+        @type = type.freeze
+        @reference = reference.freeze
+        @url = url&.freeze
+      end
+
+      # @return [Hash] serializable representation
+      def to_h
+        hash = { 'type' => @type, 'reference' => @reference }
+        hash['url'] = @url if @url
+        hash
+      end
+
+      private
+
+      def validate_type!(type)
+        return if ALLOWED_TYPES.include?(type)
+
+        raise ArgumentError,
+              "Invalid source type '#{type}'. Allowed: #{ALLOWED_TYPES.join(', ')}"
+      end
+
+      def validate_url!(type, url)
+        return unless type == 'external_source'
+        return if url&.include?('/') && url.count('/') > 2
+
+        raise ArgumentError,
+              'external_source requires a specific URL, not a bare domain'
+      end
+    end
+  end
+end

data/lib/rosett_ai/provenance/store.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'digest'
+require 'yaml'
+
+module RosettAi
+  module Provenance
+    # Append-only YAML store for `.ai-provenance.yml`.
+    #
+    # Manages the provenance file lifecycle: creation, appending entries,
+    # reading, querying, and hash chain integrity. Entries are never
+    # modified or deleted. Each entry includes a SHA-256 hash of the
+    # previous entry to create a tamper-evident chain.
+    #
+    # @author hugo
+    # @author claude
+    class Store
+      FILENAME = '.ai-provenance.yml'
+      MAX_FILE_SIZE = 1_048_576 # 1 MB
+      SCHEMA_VERSION = 1
+      ZERO_HASH = ('0' * 64).freeze
+
+      attr_reader :root
+
+      # @param root [Pathname, String] project root directory
+      def initialize(root:)
+        @root = Pathname.new(root)
+      end
+
+      # @return [Pathname] full path to the provenance file
+      def path
+        @root.join(FILENAME)
+      end
+
+      # @return [Boolean] true if the provenance file exists
+      def exist?
+        path.exist?
+      end
+
+      # Creates a new provenance file with version header.
+      #
+      # @return [Pathname] path to the created file
+      # @raise [RosettAi::ProvenanceError] if file already exists
+      def init
+        raise RosettAi::ProvenanceError, "Provenance file already exists: #{path}" if exist?
+
+        data = { 'provenance_version' => SCHEMA_VERSION, 'entries' => [] }
+        path.write(YAML.dump(data))
+        path
+      end
+
+      # Appends an entry to the provenance file with hash chain linkage.
+      #
+      # @param entry [Entry] provenance entry to append
+      # @return [Pathname] path to the updated file
+      # @raise [RosettAi::ProvenanceError] if provenance file does not exist
+      def append(entry)
+        raise RosettAi::ProvenanceError, "Provenance file not found: #{path}" unless exist?
+
+        warn_file_size if file_over_limit?
+        data = read_data
+        entry_hash = chain_hash(data['entries'])
+        serialized = entry.to_h.merge('chain_hash' => entry_hash)
+        data['entries'] << serialized
+        path.write(YAML.dump(data))
+        path
+      end
+
+      # Reads and parses the provenance file.
+      #
+      # @return [Hash] parsed provenance data
+      # @raise [RosettAi::ProvenanceError] if provenance file is missing
+      def read
+        raise RosettAi::ProvenanceError, "Provenance file not found: #{path}" unless exist?
+
+        read_data
+      end
+
+      # Returns all entries for a specific commit.
+      #
+      # @param commit_sha [String] full or partial commit SHA
+      # @return [Array<Hash>] matching entries
+      def entries_for_commit(commit_sha)
+        return [] unless exist?
+
+        read['entries'].select { |entry| entry['commit']&.start_with?(commit_sha) }
+      end
+
+      # Returns all entries that reference a specific file.
+      #
+      # @param file_path [String] relative file path
+      # @return [Array<Hash>] matching entries
+      def entries_for_file(file_path)
+        return [] unless exist?
+
+        read['entries'].select do |entry|
+          Array(entry['files']).any? { |file| file['path'] == file_path }
+        end
+      end
+
+      # @return [Integer] number of entries in the provenance file
+      def entry_count
+        return 0 unless exist?
+
+        read['entries'].size
+      end
+
+      # Verifies the integrity of the hash chain.
+      #
+      # @return [Array<String>] list of integrity violations (empty if valid)
+      def verify_chain
+        return [] unless exist?
+
+        entries = read['entries']
+        violations = []
+        entries.each_with_index do |entry, index|
+          expected = chain_hash(entries[0...index])
+          actual = entry['chain_hash']
+          next if actual == expected
+
+          violations << "Entry ##{index + 1} (#{entry['commit']}): " \
+                        "expected #{expected[0, 16]}..., got #{(actual || 'nil')[0, 16]}..."
+        end
+        violations
+      end
+
+      private
+
+      def read_data
+        YAML.safe_load(path.read, permitted_classes: [Date, Time])
+      end
+
+      def chain_hash(entries)
+        return ZERO_HASH if entries.empty?
+
+        previous = entries.last.reject { |k| k == 'chain_hash' }
+        Digest::SHA256.hexdigest(YAML.dump(previous))
+      end
+
+      def file_over_limit?
+        exist? && path.size > MAX_FILE_SIZE
+      end
+
+      def warn_file_size
+        warn 'Provenance file exceeds 1 MB — run `rai provenance archive` ' \
+             'to move older entries to a dated archive'
+      end
+    end
+  end
+end

data/lib/rosett_ai/provenance/tracker.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 Provenance
+    # MCP-facing facade for provenance operations.
+    #
+    # Delegates to {Store} for the actual provenance logic, providing
+    # the simplified interface expected by {Mcp::Tools::ProvenanceTool}.
+    #
+    # @author hugo
+    # @author claude
+    class Tracker
+      # @param root [Pathname, String] project root (defaults to pwd)
+      def initialize(root: Dir.pwd)
+        @store = Store.new(root: root)
+      end
+
+      # Validates all provenance entries and hash chain integrity.
+      #
+      # @return [Hash] with :errors key
+      def validate
+        errors = []
+        errors << 'Provenance file not found' unless @store.exist?
+        errors.concat(@store.verify_chain) if @store.exist?
+        { errors: errors }
+      end
+
+      # Finds provenance entries for a specific commit.
+      #
+      # @param commit [String] commit SHA
+      # @return [Hash, nil] matching entry
+      def find_by_commit(commit)
+        entries = @store.entries_for_commit(commit)
+        entries.first
+      end
+
+      # Finds provenance entries referencing a file.
+      #
+      # @param file [String] file path
+      # @return [Array<Hash>] matching entries
+      def find_by_file(file)
+        @store.entries_for_file(file)
+      end
+
+      # Returns provenance log, optionally filtered by role.
+      #
+      # @param role [String, nil] AI role filter
+      # @return [Array<Hash>] provenance entries
+      def log(role: nil)
+        return [] unless @store.exist?
+
+        entries = @store.read['entries'] || []
+        return entries unless role
+
+        entries.select { |e| e['role'] == role }
+      end
+    end
+  end
+end