samagotchi 0.2.0

data/lib/samagotchi/memory_bundle/manifest.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "digest"
+require "fileutils"
+
+module Samagotchi
+  module MemoryBundle
+    # Parses and validates a bundle manifest.yml.
+    #
+    # Expected structure:
+    #   name: my-bundle
+    #   version: 1.0.0
+    #   scope: system          # optional — CLI --scope wins over this
+    #   description: "…"       # optional
+    #   files:
+    #     identity.md: sha256:abc123...
+    #     commit_preferences.md: sha256:def456...
+    #   plugin:                # optional — the bundle's plugin.rb (docs/plugins.md)
+    #     file: plugin.rb
+    #     sha256: sha256:0a1b...
+    #   requires_chi: ">= 0.1.28"   # optional — a Gem::Requirement for chi's VERSION
+    #   needs:                 # optional — outside commands the memories rely on
+    #     - command: gh        #   (checked on PATH, never installed; docs/memory.md)
+    #       why: reads PRs     #   optional
+    #       hint: brew install gh   # optional
+    #     - jq                 #   short form: just the command
+    class Manifest
+      class ValidationError < StandardError; end
+
+      # A plugin file is a plain .rb name in the bundle's top directory.
+      PLUGIN_FILE = /\A[A-Za-z0-9_][A-Za-z0-9_.-]*\.rb\z/
+      # A need is a plain executable name: no path, no spaces.
+      NEED_COMMAND = /\A[A-Za-z0-9][A-Za-z0-9._+-]*\z/
+
+      attr_reader :name, :version, :scope, :description, :files, :hooks, :trust_level, :plugin, :requires_chi, :needs
+
+      def initialize(path:)
+        @path = path
+        raw = YAML.load_file(path) || {}
+        @name     = require_str(raw, "name")
+        @version  = require_str(raw, "version")
+        @scope    = normalize_scope(raw["scope"])
+        @description = (raw["description"] || "").to_s
+        @files    = parse_files(raw["files"] || {})
+        @hooks    = parse_hooks(raw["hooks"] || {})
+        @trust_level = (raw["trust_level"] || "experimental").to_s
+        @plugin = parse_plugin(raw["plugin"])
+        @requires_chi = parse_requires_chi(raw["requires_chi"])
+        @needs = self.class.parse_needs(raw["needs"])
+      end
+
+      def self.read(dir:)
+        manifest_path = File.join(dir, "manifest.yml")
+        raise ValidationError, "manifest.yml not found in #{dir}" unless File.exist?(manifest_path)
+        new(path: manifest_path)
+      end
+
+      # Returns the expected sha256 hex digest for a given file key
+      # (e.g. "identity.md"), with the "sha256:" prefix stripped.
+      def checksum_for(file_key)
+        raw = @files[file_key]
+        return nil unless raw
+        raw.start_with?("sha256:") ? raw[7..] : raw
+      end
+
+      # Returns sha256 hex for a hook basename (e.g. "guardrails.rb").
+      def checksum_for_hook(basename)
+        raw = @hooks[basename]
+        return nil unless raw
+        sha = raw[:sha256] || raw["sha256"]
+        return nil unless sha
+        sha.to_s.start_with?("sha256:") ? sha.to_s[7..] : sha.to_s
+      end
+
+      # @return [String, nil] the plugin's sha256 hex, "sha256:" stripped
+      def checksum_for_plugin
+        sha = @plugin && @plugin[:sha256].to_s
+        return nil if sha.nil? || sha.empty?
+
+        sha.delete_prefix("sha256:")
+      end
+
+      # Why chi +version+ can't load this bundle's plugin, or nil when it can
+      # (or the bundle names no requirement).
+      def self.requires_chi_failure(requirement, version)
+        return nil if requirement.nil? || requirement.to_s.strip.empty?
+        return nil if Gem::Requirement.new(*requirement.to_s.split(",").map(&:strip)).satisfied_by?(Gem::Version.new(version.to_s))
+
+        "it requires chi #{requirement} (this is chi #{version})"
+      rescue ArgumentError, Gem::Requirement::BadRequirementError => e
+        "its requires_chi #{requirement.inspect} is not a version requirement (#{e.message})"
+      end
+
+      # Writes a fresh manifest.yml from computed checksums at `dir`.
+      def self.write(dir:, name:, version:, scope: nil, description: "", files:, hooks: nil, trust_level: nil,
+                     plugin: nil, requires_chi: nil, needs: nil)
+        FileUtils.mkdir_p(dir)
+        manifest = {
+          "name" => name,
+          "version" => version,
+          "description" => description,
+        }
+        manifest["scope"] = scope if scope
+        manifest["files"] = files # { "file.md" => "sha256:abc..." }
+        if hooks && !hooks.empty?
+          # Normalize hooks to string-keyed with sha256 prefix preserved
+          manifest["hooks"] = hooks.transform_keys(&:to_s).transform_values do |v|
+            h = v.transform_keys(&:to_s)
+            h["sha256"] = h["sha256"].to_s.start_with?("sha256:") ? h["sha256"].to_s : "sha256:#{h["sha256"]}" if h["sha256"]
+            h
+          end
+        end
+        manifest["trust_level"] = trust_level.to_s if trust_level && !trust_level.to_s.empty?
+        if plugin
+          sha = plugin[:sha256].to_s
+          manifest["plugin"] = { "file" => plugin[:file].to_s, "sha256" => sha.start_with?("sha256:") ? sha : "sha256:#{sha}" }
+        end
+        manifest["requires_chi"] = requires_chi.to_s if requires_chi && !requires_chi.to_s.empty?
+        needs = parse_needs(needs)
+        manifest["needs"] = needs.map { |n| n.transform_keys(&:to_s).compact } unless needs.empty?
+        File.write(File.join(dir, "manifest.yml"), YAML.dump(manifest))
+      end
+
+      # needs: → [{command:, why:, hint:}] (why/hint a String or nil), [] when
+      # absent. Takes the manifest's string-keyed YAML or the symbol-keyed
+      # form provenance stores. Duplicates merge (the first one's why/hint
+      # win); a list that isn't one, or a command that isn't a plain name,
+      # is a ValidationError.
+      def self.parse_needs(raw)
+        return [] if raw.nil?
+        raise ValidationError, "needs: must be a list of commands" unless raw.is_a?(Array)
+
+        raw.each_with_object([]) do |item, acc|
+          unless item.is_a?(Hash) || item.is_a?(String) || item.is_a?(Symbol)
+            raise ValidationError, "needs: each item must be a command name or a mapping with command:, not #{item.inspect}"
+          end
+
+          need = item.is_a?(Hash) ? item.transform_keys(&:to_s) : { "command" => item }
+          command = need["command"].to_s.strip
+          raise ValidationError, "needs: #{command.inspect} is not a plain command name" unless command.match?(NEED_COMMAND)
+          next if acc.any? { |n| n[:command] == command }
+
+          acc << { command: command, why: optional_text(need["why"]), hint: optional_text(need["hint"]) }
+        end
+      end
+
+      def self.optional_text(value)
+        text = value.to_s.strip
+        text.empty? ? nil : text
+      end
+      private_class_method :optional_text
+
+      private
+
+      def require_str(hash, key)
+        val = hash[key]
+        return val if val.is_a?(String) && !val.empty?
+        raise ValidationError, "manifest missing required field: #{key}"
+      end
+
+      def normalize_scope(val)
+        return nil if val.nil?
+        v = val.to_s.strip.downcase
+        %w[project system].include?(v) ? v : nil
+      end
+
+      def parse_files(raw)
+        return {} unless raw.is_a?(Hash)
+        raw.each_with_object({}) do |(k, v), acc|
+          next unless k.is_a?(String) && !k.empty?
+          str = v.to_s
+          acc[k] = if str.start_with?("sha256:")
+                     str
+                   else
+                     "sha256:#{str}"
+                   end
+        end
+      end
+
+      # plugin: {file:, sha256:} → {file:, sha256:} (sha "" when not given),
+      # or nil; a file that isn't a plain .rb name is a validation error.
+      def parse_plugin(raw)
+        return nil if raw.nil?
+        raise ValidationError, "plugin: must be a mapping with file: and sha256:" unless raw.is_a?(Hash)
+
+        file = (raw["file"] || raw[:file]).to_s.strip
+        unless file.match?(PLUGIN_FILE)
+          raise ValidationError, "plugin file must be a .rb file name in the bundle's top directory, not #{file.inspect}"
+        end
+
+        sha = (raw["sha256"] || raw[:sha256]).to_s.strip
+        sha = "sha256:#{sha}" unless sha.empty? || sha.start_with?("sha256:")
+        { file: file, sha256: sha }
+      end
+
+      def parse_requires_chi(raw)
+        return nil if raw.nil?
+
+        text = raw.to_s.strip
+        text.empty? ? nil : text
+      end
+
+      def parse_hooks(raw)
+        return {} unless raw.is_a?(Hash)
+        raw.each_with_object({}) do |(k, v), acc|
+          next unless k.is_a?(String) && !k.empty?
+          next unless v.is_a?(Hash)
+          sha = (v["sha256"] || v[:sha256] || "").to_s
+          sha = sha.start_with?("sha256:") ? sha : "sha256:#{sha}" unless sha.empty?
+          event = (v["event"] || v[:event] || "").to_s.strip
+          on_error = (v["on_error"] || v[:on_error] || "skip").to_s.strip
+          on_error = "skip" if on_error.empty?
+          priority = (v["priority"] || v[:priority] || 100).to_i
+          acc[k] = {
+            sha256: sha,
+            event: event,
+            on_error: on_error,
+            priority: priority
+          }
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/merger.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+require "digest"
+
+module Samagotchi
+  module MemoryBundle
+    # 3-way merge helper for bundle upgrades.
+    #
+    # Compare base (provenance snapshot), current (on-disk), incoming (new bundle)
+    # and classify per file. Used by Installer#run when provenance exists.
+    module Merger
+      # Classify a single file for upgrade.
+      # Returns :install, :keep, :fast_forward, :conflict, :noop
+      def self.classify(base_path:, current_path:, incoming_path:)
+        base_exists = base_path && File.exist?(base_path)
+        current_exists = File.exist?(current_path)
+        incoming_exists = File.exist?(incoming_path)
+
+        return :noop unless incoming_exists
+
+        unless current_exists
+          return :install
+        end
+
+        # No base (legacy bundle without provenance or first file) -> treat as modified
+        unless base_exists
+          incoming_digest = Digest::SHA256.hexdigest(File.read(incoming_path))
+          current_digest = Digest::SHA256.hexdigest(File.read(current_path))
+          return current_digest == incoming_digest ? :noop : :conflict
+        end
+
+        base_digest = Digest::SHA256.hexdigest(File.read(base_path))
+        current_digest = Digest::SHA256.hexdigest(File.read(current_path))
+        incoming_digest = Digest::SHA256.hexdigest(File.read(incoming_path))
+
+        if current_digest == incoming_digest
+          return :noop
+        elsif current_digest == base_digest
+          return :fast_forward
+        elsif incoming_digest == base_digest
+          return :keep
+        else
+          return :conflict
+        end
+      end
+
+      def self.current_modified?(base_path, current_path)
+        return true unless base_path && File.exist?(base_path) && File.exist?(current_path)
+        Digest::SHA256.hexdigest(File.read(base_path)) != Digest::SHA256.hexdigest(File.read(current_path))
+      end
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/placeholder.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module MemoryBundle
+    # Detects {{placeholder}} patterns in file content.
+    # Placeholders are hints, not gates — install succeeds with unfilled ones.
+    class Placeholder
+      PLACEHOLDER_RE = /\{\{([^}]+)\}\}/
+
+      attr_reader :placeholders
+
+      def initialize(content:)
+        @placeholders = extract_placeholders(content)
+      end
+
+      def self.detect_in_file(path)
+        content = File.read(path)
+        new(content: content).placeholders
+      end
+
+      # Returns a sorted list of unique placeholder names found.
+      def unique_names
+        @placeholders.map(&:strip).uniq.sort
+      end
+
+      def any?
+        !@placeholders.empty?
+      end
+
+      private
+
+      def extract_placeholders(content)
+        content.scan(PLACEHOLDER_RE).flatten
+      end
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/provenance.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require "date"
+require "fileutils"
+require_relative "../memory_paths"
+
+module Samagotchi
+  module MemoryBundle
+    # Manages provenance storage at <memories>/.bundles/<name>/ (see MemoryPaths)
+    # Each installed bundle gets a directory with:
+    #   manifest.json — metadata about the install (merged on reinstall)
+    #   bases/        — snapshots of every file as installed (for 3-way merge later)
+    class Provenance
+      class << self
+        attr_accessor :bundles_dir_override
+
+        def bundles_dir
+          bundles_dir_override || MemoryPaths.bundles_dir
+        end
+      end
+
+      attr_reader :name, :bundle_dir
+
+      def initialize(name:)
+        @name = name
+        @bundle_dir = File.join(self.class.bundles_dir, name)
+      end
+
+      def hooks_dir
+        File.join(@bundle_dir, "hooks")
+      end
+
+      # Installed guardrail rule files (guardrails/*.yml).
+      def guardrails_dir
+        File.join(@bundle_dir, "guardrails")
+      end
+
+      # The installed plugin file's dir (plugin/<file>).
+      def plugin_dir
+        File.join(@bundle_dir, "plugin")
+      end
+
+      # The plugin file as installed, or nil when the bundle has none.
+      def plugin_path(data = read)
+        file = data && data[:plugin].is_a?(Hash) ? data[:plugin][:file].to_s : ""
+        file.empty? ? nil : File.join(plugin_dir, file)
+      end
+
+      # The plugin's base snapshot (bases/plugin/<file>), for bundle diff.
+      def plugin_base_path(file)
+        File.join(@bundle_dir, "bases", "plugin", file.to_s)
+      end
+
+      # Yields [name, data] for each installed bundle with a plugin, by
+      # name. A manifest that doesn't parse is yielded as {error:} when its
+      # bundle has a plugin/ dir.
+      def self.each_installed_with_plugin
+        return enum_for(:each_installed_with_plugin) unless block_given?
+        dir = bundles_dir
+        return unless Dir.exist?(dir)
+        Dir[File.join(dir, "*", "manifest.json")].sort.each do |mjson|
+          name = File.basename(File.dirname(mjson))
+          begin
+            data = JSON.parse(File.read(mjson), symbolize_names: true)
+          rescue JSON::ParserError, SystemCallError => e
+            yield name, { error: "manifest.json is unreadable: #{e.message}" } if Dir.exist?(File.join(File.dirname(mjson), "plugin"))
+            next
+          end
+          next unless data.is_a?(Hash) && data[:plugin].is_a?(Hash)
+          yield name, data
+        end
+      end
+
+      # Yields [name, data] for each installed bundle with guardrail rule
+      # files, by name. A manifest that doesn't parse is yielded as
+      # {error:} when its bundle has a guardrails/ dir (its rules can't be
+      # checked), and skipped otherwise.
+      def self.each_installed_with_guardrails
+        return enum_for(:each_installed_with_guardrails) unless block_given?
+        dir = bundles_dir
+        return unless Dir.exist?(dir)
+        Dir[File.join(dir, "*", "manifest.json")].sort.each do |mjson|
+          name = File.basename(File.dirname(mjson))
+          begin
+            data = JSON.parse(File.read(mjson), symbolize_names: true)
+          rescue JSON::ParserError, SystemCallError => e
+            yield name, { error: "manifest.json is unreadable: #{e.message}" } if Dir.exist?(File.join(File.dirname(mjson), "guardrails"))
+            next
+          end
+          next unless data.is_a?(Hash) && data[:guardrails].is_a?(Hash) && !data[:guardrails].empty?
+          yield name, data
+        end
+      end
+
+      def self.each_installed_holding_hooks
+        return enum_for(:each_installed_holding_hooks) unless block_given?
+        dir = self.bundles_dir
+        return unless Dir.exist?(dir)
+        Dir[File.join(dir, "*", "manifest.json")].sort.each do |mjson|
+          data = JSON.parse(File.read(mjson), symbolize_names: true)
+          next unless data && data[:hooks].is_a?(Hash) && !data[:hooks].empty?
+          yield File.basename(File.dirname(mjson)), data
+        end
+      end
+
+      # Writes provenance for an installation: merges into existing manifest.json
+      # and saves base snapshots. Stale base snapshots (files removed from bundle)
+      # are pruned.
+      # @param hooks_files [Hash] basename => path for hook file snapshots (optional)
+      # @param guardrails_files [Hash] basename => installed rule file; the
+      #   sha256 of each is recorded (the Engine checks it at load)
+      # @param plugin_file [String, nil] the installed plugin file; its name
+      #   and sha256 are recorded (the Engine checks it at load) with a base
+      #   snapshot
+      # @param requires_chi [String, nil] the manifest's requirement
+      # @param needs [Array<Hash>] the manifest's needs ({command:, why:, hint:})
+      def write(files:, scope:, version:, source_path:, hooks: {}, trust_level: nil, source_commit: nil, hooks_files: {},
+                guardrails_files: {}, plugin_file: nil, requires_chi: nil, needs: nil)
+        FileUtils.mkdir_p(@bundle_dir)
+        bases_dir = File.join(@bundle_dir, "bases")
+        FileUtils.mkdir_p(bases_dir)
+
+        # Read existing manifest to merge file entries and find stale files.
+        # read symbolizes keys; stringify them so incoming string keys replace
+        # them instead of sitting next to them as duplicates.
+        existing = read
+        merged_entries = existing && existing[:files] ? existing[:files].transform_keys(&:to_s) : {}
+
+        files.each do |file_key, file_path|
+          content = File.read(file_path)
+          checksum = Digest::SHA256.hexdigest(content)
+          # Save base snapshot — use file_key as-is (it already includes .md).
+          File.write(File.join(bases_dir, file_key), content)
+          merged_entries[file_key] = { checksum: checksum }
+        end
+
+        # Prune stale base snapshots for files no longer in the bundle.
+        if existing && existing[:files]
+          existing[:files].keys.each do |old_key|
+            old_key_str = old_key.to_s
+            unless files.key?(old_key_str) || files.key?(old_key)
+              old_base = File.join(bases_dir, old_key_str)
+              FileUtils.rm_f(old_base) if File.exist?(old_base)
+              merged_entries.delete(old_key_str)
+            end
+          end
+        end
+
+        # Hooks provenance: persist metadata and base snapshots for hooks
+        hooks_map = {}
+        # existing hooks for pruning
+        existing_hooks = existing && existing[:hooks] ? existing[:hooks] : {}
+        # Normalize incoming hooks (basename => metadata hash)
+        normalized_hooks = {}
+        if hooks.is_a?(Hash)
+          hooks.each do |k, v|
+            next unless k.is_a?(String) && !k.empty?
+            next unless v.is_a?(Hash)
+            hv = v.transform_keys(&:to_sym)
+            sha = (hv[:sha256] || "").to_s
+            sha = sha.start_with?("sha256:") ? sha : "sha256:#{sha}" unless sha.empty?
+            normalized_hooks[k] = {
+              sha256: sha,
+              event: (hv[:event] || "").to_s,
+              on_error: (hv[:on_error] || "skip").to_s,
+              priority: (hv[:priority] || 100).to_i
+            }
+          end
+        end
+        # Prune stale hook bases
+        if existing_hooks.is_a?(Hash)
+          existing_hooks.keys.each do |old_key|
+            old_key_str = old_key.to_s
+            unless normalized_hooks.key?(old_key_str) || normalized_hooks.key?(old_key_str.to_sym)
+              old_base = File.join(bases_dir, old_key_str)
+              FileUtils.rm_f(old_base) if File.exist?(old_base)
+            end
+          end
+        end
+        # Save base snapshots for hooks where a file path was provided, and
+        # record the sha256 of the installed file itself: the load-time check
+        # compares against it, and a declared sha can be wrong (installing
+        # only warns about that).
+        hooks_files = {} unless hooks_files.is_a?(Hash)
+        normalized_hooks.each do |k, meta|
+          src = hooks_files[k] || hooks_files[k.to_sym]
+          if src && File.exist?(src.to_s)
+            meta = meta.merge(sha256: "sha256:#{Digest::SHA256.hexdigest(File.read(src.to_s))}")
+          end
+          hooks_map[k] = meta.transform_keys(&:to_s)
+          if src && File.exist?(src.to_s)
+            begin
+              File.write(File.join(bases_dir, k), File.read(src.to_s))
+            rescue StandardError
+              nil
+            end
+          end
+        end
+
+        manifest_data = {
+          "name" => @name,
+          "version" => version.to_s,
+          "scope" => scope.to_s,
+          "source" => source_path.to_s,
+          "installed_at" => DateTime.now.iso8601,
+          "files" => merged_entries,
+          "hooks" => hooks_map
+        }
+        manifest_data["trust_level"] = trust_level.to_s if trust_level && !trust_level.to_s.empty?
+        if guardrails_files.is_a?(Hash) && !guardrails_files.empty?
+          manifest_data["guardrails"] = guardrails_files.sort.to_h do |basename, path|
+            [basename.to_s, { "sha256" => "sha256:#{Digest::SHA256.hexdigest(File.read(path.to_s))}" }]
+          end
+        end
+        manifest_data["source_commit"] = source_commit.to_s if source_commit && !source_commit.to_s.empty?
+        FileUtils.rm_rf(File.join(bases_dir, "plugin"))
+        if plugin_file
+          content = File.binread(plugin_file.to_s)
+          manifest_data["plugin"] = { "file" => File.basename(plugin_file.to_s),
+                                      "sha256" => "sha256:#{Digest::SHA256.hexdigest(content)}" }
+          FileUtils.mkdir_p(File.join(bases_dir, "plugin"))
+          File.binwrite(plugin_base_path(File.basename(plugin_file.to_s)), content)
+        end
+        manifest_data["requires_chi"] = requires_chi.to_s if requires_chi && !requires_chi.to_s.empty?
+        manifest_data["needs"] = needs.map { |n| n.transform_keys(&:to_s).compact } if needs.is_a?(Array) && !needs.empty?
+
+        # Write aside and rename, so a reader in another process (a parallel
+        # chi start) never parses a truncated manifest.json.
+        manifest_path = File.join(@bundle_dir, "manifest.json")
+        tmp_path = "#{manifest_path}.#{Process.pid}.tmp"
+        File.write(tmp_path, JSON.pretty_generate(manifest_data))
+        File.rename(tmp_path, manifest_path)
+      ensure
+        FileUtils.rm_f(tmp_path) if tmp_path
+      end
+
+      # Reads provenance data (returns nil if not installed).
+      def read
+        manifest_path = File.join(@bundle_dir, "manifest.json")
+        return nil unless File.exist?(manifest_path)
+        JSON.parse(File.read(manifest_path), symbolize_names: true)
+      end
+
+      # Returns the path to a base snapshot for a given file key.
+      def base_path(file_key)
+        File.join(@bundle_dir, "bases", file_key)
+      end
+
+      # Checks whether the bundle is installed.
+      def installed?
+        read.nil? ? false : true
+      end
+    end
+  end
+end