samagotchi 0.156.0 → 0.158.0

data/lib/samagotchi/memory_bundle/manifest.rb

@@ -5,7 +5,6 @@ require "digest"
 require "fileutils"
 require_relative "../context_providers"
 require_relative "../version"
-require_relative "bundle_hook"
 
 module Samagotchi
   autoload :BlockRenderers, File.expand_path("../block_renderers", __dir__)
@@ -26,6 +25,8 @@ module Samagotchi
     #   plugin:                # optional — the bundle's plugin.rb (docs/plugins.md)
     #     file: plugin.rb
     #     sha256: sha256:0a1b...
+    #     required: true       # optional: a guardrail; when it fails to load
+    #                          #   chi denies every tool call (docs/hooks.md)
     #   requires_chi: ">= 0.1.28"   # optional — a Gem::Requirement for chi's VERSION
     #   requires_chi_next: true     # optional, shipped bundles — ignored here:
     #                          #   `rake release:bump` raises requires_chi to
@@ -64,6 +65,26 @@ module Samagotchi
     class Manifest
       class ValidationError < StandardError; end
 
+      # Class-file bundle hooks (hooks/*.rb, the manifest's hooks:) are
+      # retired: chi installs and loads none. WORDS is the one wording of
+      # it, wherever chi meets one (the Engine's first-turn line, install,
+      # chi bundle check and status, chi update's row). A strict read of a
+      # manifest with a hooks: entry raises it (.for_key's message); a
+      # tolerant read (a kept manifest.yml) ignores the key.
+      class HooksRetired < ValidationError
+        WORDS = "class-file bundle hooks are retired: chi loads no hooks/*.rb; a bundle hooks events from its " \
+                "plugin.rb with chi.on, see docs/plugins.md"
+
+        # The manifest's hooks: key.
+        def self.for_key = new("hooks: #{WORDS}")
+
+        # A source's hooks/*.rb (+files+, relative), with or without the key.
+        def self.for_files(files) = new("#{files.join(", ")}: #{WORDS}")
+
+        # The source's hooks/*.rb, relative and sorted ([] for none).
+        def self.files_in(dir) = Dir.glob(File.join(dir, "hooks", "*.rb")).map { |f| "hooks/#{File.basename(f)}" }.sort
+      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 script is a plain file name in the bundle's scripts/.
@@ -86,7 +107,7 @@ module Samagotchi
       # admits a chi that never saw the key. A key the first tag (v0.2.0)
       # already reads has no entry. `files.description` is a files: entry given
       # as a mapping, `*.types` a session_settings:/settings: given as a mapping
-      # of keys to types, `hooks.events` a hook entry with an events: list. A key
+      # of keys to types. A key
       # whose release is not out yet waits here as a comment naming it, the way
       # Plugin::Api::SINCE does, until `release:bump` gives it its version
       # (docs/releasing.md).
@@ -98,15 +119,14 @@ module Samagotchi
         "session_settings" => "0.84.0",
         "session_settings.types" => "0.92.0",
         "settings.types" => "0.92.0",
-        "hooks.events" => "0.98.0",
         "settings" => "0.143.0",
-        "block_renderers" => "0.151.0"
+        "block_renderers" => "0.151.0",
+        "plugin.required" => "0.157.0"
       }.freeze
 
       # files: name → "sha256:<hex>" (both forms); file_descriptions: name →
-      # the description a mapping gave, for the files that have one; hooks:
-      # name → BundleHook.
-      attr_reader :name, :version, :scope, :description, :files, :file_descriptions, :hooks, :trust_level, :plugin, :requires_chi, :needs, :includes,
+      # the description a mapping gave, for the files that have one.
+      attr_reader :name, :version, :scope, :description, :files, :file_descriptions, :trust_level, :plugin, :requires_chi, :needs, :includes,
                   :scripts, :context_providers, :block_renderers, :session_settings, :session_setting_types, :settings, :setting_types, :unknown_keys
 
       def initialize(path:)
@@ -128,7 +148,8 @@ module Samagotchi
         @scope    = normalize_scope(raw["scope"])
         @description = (raw["description"] || "").to_s
         @files    = parse_files(raw["files"] || {})
-        @hooks    = parse_hooks(raw["hooks"] || {})
+        raise HooksRetired.for_key if self.class.lists_hooks?(raw["hooks"])
+
         @file_descriptions = parse_file_descriptions(raw["files"])
         @trust_level = (raw["trust_level"] || "experimental").to_s
         @plugin = parse_plugin(raw["plugin"])
@@ -167,8 +188,8 @@ module Samagotchi
       # chi (a newer chi tightened it, or an older one wrote it) costs only
       # that key, which reads as empty with its message in the problems:
       #   name, version (never checked: identity is the record's), scope;
-      #   files and their descriptions, scripts, plugin; hooks (one bad entry
-      #   fails the whole key); needs, context_providers; block_renderers
+      #   files and their descriptions, scripts, plugin (hooks: is ignored,
+      #   HooksRetired); needs, context_providers; block_renderers
       #   (against +fallback_scripts+ when scripts: failed); includes (after
       #   what its check reads); session_settings with its types, settings
       #   with theirs (one raw value each, so one problem); requires_chi,
@@ -183,6 +204,10 @@ module Samagotchi
         [manifest, manifest.send(:read_tolerantly, path, fallback_scripts)]
       end
 
+      # Whether a manifest's hooks: value lists anything (none, {} and []
+      # don't: a manifest may keep an empty key).
+      def self.lists_hooks?(raw) = !(raw.nil? || ((raw.is_a?(Hash) || raw.is_a?(Array)) && raw.empty?))
+
       def self.read(dir:)
         manifest_path = File.join(dir, "manifest.yml")
         raise ValidationError, "manifest.yml not found in #{dir}" unless File.exist?(manifest_path)
@@ -201,13 +226,6 @@ module Samagotchi
         hex unless hex.nil? || hex.empty?
       end
 
-      # Returns sha256 hex for a hook basename (e.g. "guardrails.rb"), nil
-      # when it declares none (nothing to verify).
-      def checksum_for_hook(basename)
-        hex = @hooks[basename]&.hex
-        hex unless hex.nil? || hex.empty?
-      end
-
       # @return [String, nil] the plugin's sha256 hex, "sha256:" stripped
       def checksum_for_plugin
         sha = @plugin && @plugin[:sha256].to_s
@@ -239,8 +257,8 @@ module Samagotchi
 
       # The SINCE keys this manifest actually uses, each with the chi release
       # that first read it: the plain keys, and the shapes only a newer chi
-      # reads — a files: entry given as a mapping, a hook entry with an events:
-      # list, a session_settings:/settings: given as a mapping of keys to types.
+      # reads — a files: entry given as a mapping, a session_settings:/settings:
+      # given as a mapping of keys to types.
       # @return [Hash{String => String}]
       def floor_keys
         raw = @raw
@@ -249,20 +267,18 @@ module Samagotchi
         found["scripts"] = SINCE["scripts"] unless @scripts.empty?
         found["context_providers"] = SINCE["context_providers"] unless @context_providers.empty?
         found["block_renderers"] = SINCE["block_renderers"] unless @block_renderers.empty?
+        found["plugin.required"] = SINCE["plugin.required"] if @plugin&.dig(:required) && SINCE.key?("plugin.required")
         found["session_settings"] = SINCE["session_settings"] unless @session_settings.empty?
         found["settings"] = SINCE["settings"] unless @settings.nil?
         found["files.description"] = SINCE["files.description"] if raw["files"].is_a?(Hash) && raw["files"].values.any?(Hash)
         found["session_settings.types"] = SINCE["session_settings.types"] if raw["session_settings"].is_a?(Hash)
         found["settings.types"] = SINCE["settings.types"] if raw["settings"].is_a?(Hash)
-        if raw["hooks"].is_a?(Hash) && raw["hooks"].values.any? { |entry| entry.is_a?(Hash) && entry.key?("events") }
-          found["hooks.events"] = SINCE["hooks.events"]
-        end
         found
       end
 
       # Writes a fresh manifest.yml from computed checksums at `dir`.
       # +file_descriptions+ (name → text) writes those files as mappings.
-      def self.write(dir:, name:, version:, files:, scope: nil, description: "", hooks: nil, trust_level: nil,
+      def self.write(dir:, name:, version:, files:, scope: nil, description: "", trust_level: nil,
                      plugin: nil, requires_chi: nil, needs: nil, scripts: {}, context_providers: [], block_renderers: [], file_descriptions: {},
                      session_settings: [], session_setting_types: {}, settings: nil, setting_types: {})
         FileUtils.mkdir_p(dir)
@@ -276,11 +292,11 @@ module Samagotchi
           text = file_descriptions[key].to_s.strip
           [key, text.empty? ? sha : { "sha256" => sha, "description" => text }]
         end
-        manifest["hooks"] = hooks.to_h { |k, v| [k.to_s, BundleHook.parse(v).to_record] } if hooks && !hooks.empty?
         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}" }
+          manifest["plugin"]["required"] = true if plugin[:required]
         end
         manifest["requires_chi"] = requires_chi.to_s if requires_chi && !requires_chi.to_s.empty?
         needs = parse_needs(needs)
@@ -384,7 +400,7 @@ module Samagotchi
         end
         @scripts = tolerate(problems, "scripts", {}) { parse_scripts(raw["scripts"]) }
         @plugin = tolerate(problems, "plugin", nil) { parse_plugin(raw["plugin"]) }
-        @hooks = tolerate(problems, "hooks", {}) { parse_hooks(raw["hooks"] || {}) }
+        # An old kept manifest's hooks: is no problem: it isn't read (HooksRetired).
         @needs = tolerate(problems, "needs", []) { self.class.parse_needs(raw["needs"]) }
         @context_providers = tolerate(problems, "context_providers", []) { parse_context_providers(raw["context_providers"]) }
         script_names = problems.key?("scripts") ? fallback_scripts.map(&:to_s) : @scripts.keys
@@ -471,8 +487,10 @@ module Samagotchi
         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.
+      # plugin: {file:, sha256:, required:} → {file:, sha256:} (sha "" when
+      # not given) with required: true when it says so, or nil; a file that
+      # isn't a plain .rb name, or a required: that isn't true or false, 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)
@@ -484,7 +502,10 @@ module Samagotchi
 
         sha = (raw["sha256"] || raw[:sha256]).to_s.strip
         sha = "sha256:#{sha}" unless sha.empty? || sha.start_with?("sha256:")
-        { file: file, sha256: sha }
+        required = raw.key?("required") ? raw["required"] : raw[:required]
+        raise ValidationError, "plugin required: must be true or false, not #{required.inspect}" unless [nil, true, false].include?(required)
+
+        required ? { file: file, sha256: sha, required: true } : { file: file, sha256: sha }
       end
 
       # scripts: {file => sha256} → the same, "sha256:" prefixed; {} when absent.
@@ -536,8 +557,8 @@ module Samagotchi
 
           name
         end.uniq
-        if !names.empty? && (!@files.empty? || !@hooks.empty? || @plugin || !@scripts.empty?)
-          raise ValidationError, "a bundle with includes: holds only its includes (no files, hooks, plugin or scripts)"
+        if !names.empty? && (!@files.empty? || @plugin || !@scripts.empty?)
+          raise ValidationError, "a bundle with includes: holds only its includes (no files, plugin or scripts)"
         end
 
         names
@@ -549,34 +570,6 @@ module Samagotchi
         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)
-
-          check_hook_events(k, v)
-          acc[k] = BundleHook.parse(v)
-        end
-      end
-
-      HOOK_EVENT_NAME = /\A[a-z][a-z0-9_]*\z/
-
-      # A hook's events: list holds event names (one instance registered
-      # for each); it and event: are one or the other.
-      def check_hook_events(file, entry)
-        return unless entry.key?("events")
-
-        raw = entry["events"]
-        raise ValidationError, "hooks: #{file}: give event: or events:, not both" if entry.key?("event")
-        raise ValidationError, "hooks: #{file}: events: must be a list of event names" unless raw.is_a?(Array) && !raw.empty?
-
-        raw.each do |item|
-          raise ValidationError, "hooks: #{file}: events: #{item.inspect} is not an event name" unless item.is_a?(String) && item.strip.match?(HOOK_EVENT_NAME)
-        end
-      end
     end
   end
 end

data/lib/samagotchi/memory_bundle/merger.rb

@@ -4,6 +4,7 @@ require "digest"
 require_relative "../atomic_file"
 require_relative "file_digest"
 require_relative "installed_bundle"
+require_relative "file_actions"
 
 module Samagotchi
   module MemoryBundle
@@ -13,8 +14,8 @@ module Samagotchi
 
     # 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.
+    # An upgrade's merge: what FileState and FileActions' UPGRADE table say of
+    # a file, as an Outcome, and the text merge where both sides changed it.
     module Merger
       # What an upgrade does to one file. status names the case; base is where
       # the file's next base comes from:
@@ -26,15 +27,13 @@ module Samagotchi
       #              edits, so it must never become the base (the edit is what
       #              differs from the base, and the next upgrade would
       #              fast-forward over it).
-      # Installer#next_base reads it. A new outcome and its base go here; it
-      # also needs a branch in Installer#merge_memory (which raises without
-      # one), #next_base if its base is a new kind, and its status word in
-      # Installer#preview_memory, #verify_memory_checksums' list and #summary.
+      # The same words as FileActions::Action#next_base: an Outcome is what an
+      # UPGRADE cell stands for to a plan, and a :decide cell's answer.
       #
       # merge is Upgrade#outcome's TextMerge::Result, so a merge runs git once
       # and its answer travels with the outcome: a :merged outcome's text, a
       # :conflict's why (nil for a real one). current_sha is the digest of the
-      # file that merge read: write_merged checks it. .classify leaves both nil.
+      # file that merge read: write_merged checks it. The constants leave both nil.
       Outcome = Data.define(:status, :base, :merge, :current_sha) do
         def initialize(status:, base:, merge: nil, current_sha: nil) = super
 
@@ -65,39 +64,38 @@ module Samagotchi
         def conflicts = behind.map(&:file)
       end
 
+      # One file's upgrade, read once (Upgrade#decision): its FileState, the
+      # action the upgrade takes (a :decide cell already answered) and the
+      # Outcome that action stands for.
+      Decision = Data.define(:state, :action, :outcome)
+
       # One bundle's upgrade as seen before it runs: what it does to a file,
       # nothing written. The one way to ask: Installer's merge and dry run,
       # ShippedUpdate's plan and SystemBundle's dry run. Which files to ask
       # about is the caller's, and they differ (see #forecast).
       Upgrade = Data.define(:provenance, :target_dir, :source_dir) do
-        # What the upgrade does to the file: .classify, then, where both sides
-        # changed it, the text merge (git runs here, once per call). A mark from
-        # an older chi fast-forwards only if no line of the file goes or its base
-        # is proved: see .merge_outcome.
-        # @return [Outcome]
-        def outcome(file_key)
-          classified = classified(file_key)
-          return classified unless classified.conflict? || classified == FAST_FORWARD
-
-          legacy = InstalledBundle.legacy_mark?(provenance.record&.files&.fetch(file_key, nil))
-          # Asked only when the guard would otherwise fire.
-          unproved = -> { legacy && !ShippedHistory.shipped?(provenance.name, file_key, paths(file_key)[:base]) }
-          return Merger.merge_outcome(paths(file_key), unproved: unproved) if classified.conflict?
-
-          # The guard's own case at its plainest: the file is the base, which
-          # may be the user's text. One that only gains lines loses nothing, and
-          # save_marked_file keeps a copy.
-          sides = paths(file_key)
-          return classified unless legacy && Merger.removes_lines?(File.binread(sides[:current]), File.binread(sides[:incoming]))
-
-          unproved.call ? CONFLICT.with(merge: TextMerge.failed(FileStanding::LEGACY_BASE)) : classified
+        # What the upgrade does to the file, with what it was read from: its
+        # FileState, the UPGRADE action (a :decide cell answered by #outcome's
+        # merge or legacy guard, through FileActions.decided) and the Outcome.
+        # @param state [FileState] the file's, when the caller has read it
+        # @return [Decision]
+        def decision(file_key, state = state(file_key))
+          action = FileActions.for(:upgrade, state)
+          outcome = outcome_of(file_key, state, action)
+          Decision.new(state: state, action: action.do == :decide ? FileActions.decided(outcome) : action, outcome: outcome)
         end
 
-        # .classify alone: no merge is tried.
+        # What the upgrade does to the file: its FileState's UPGRADE cell, and
+        # where both sides changed it, the text merge (git runs here, once per
+        # call). A mark from an older chi fast-forwards only if no line of the
+        # file goes or its base is proved: see .merge_outcome.
         # @return [Outcome]
-        def classified(file_key)
-          sides = paths(file_key)
-          Merger.classify(base_path: sides[:base], current_path: sides[:current], incoming_path: sides[:incoming])
+        def outcome(file_key) = decision(file_key).outcome
+
+        # The file as the upgrade meets it (FileState, with the source).
+        # @return [FileState]
+        def state(file_key)
+          FileState.of(file_key, record: provenance.record, provenance: provenance, target_dir: target_dir, source_dir: source_dir)
         end
 
         # The ones among +file_keys+ that would merge or end in a conflict. The
@@ -138,38 +136,50 @@ module Samagotchi
           { base: provenance.base_path(file_key), current: File.join(target_dir, file_key),
             incoming: File.join(source_dir, file_key) }
         end
-      end
 
-      # Classify a single file for upgrade.
-      # @return [Outcome]
-      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 NO_INCOMING unless incoming_exists
-
-        unless current_exists
-          return INSTALL
+        private
+
+        # The Outcome a cell stands for; a :decide cell's is the text merge
+        # (:diverged) or the legacy guard ([:pristine, :legacy]).
+        def outcome_of(file_key, state, action)
+          return NO_INCOMING if state.digests.incoming.nil?
+
+          case action.do
+          when :decide then decide(file_key, state)
+          when :write_incoming then action.word == :installed ? INSTALL : FAST_FORWARD
+          when :keep
+            return no_base(state) if action.behind?
+
+            action.word == :kept ? KEEP : NOOP
+          # A file the bundle doesn't own, the user's: there is no base to merge from.
+          when :skip then no_base(state)
+          # It can't be read: the read raises, as the merge would.
+          when :refuse then FileDigest.hex(paths(file_key)[:current])
+          else raise ArgumentError, "no outcome for #{action.do.inspect} (#{file_key})"
+          end
         end
 
-        # No base (legacy bundle without provenance or first file) -> treat as modified
-        unless base_exists
-          return FileDigest.hex(current_path) == FileDigest.hex(incoming_path) ? NOOP : CONFLICT
+        # No base to merge from: the file stays behind. With none on disk
+        # TextMerge::NO_BASE says why; one the checksum contradicts (the file
+        # equals it, yet is edited) may be the user's own text, as an older
+        # chi's can (FileStanding::LEGACY_BASE).
+        def no_base(state)
+          why = state.digests.base.nil? ? TextMerge::NO_BASE : FileStanding::LEGACY_BASE
+          CONFLICT.with(merge: TextMerge.failed(why))
         end
 
-        base_digest = FileDigest.hex(base_path)
-        current_digest = FileDigest.hex(current_path)
-        incoming_digest = FileDigest.hex(incoming_path)
-
-        if current_digest == incoming_digest
-          NOOP
-        elsif current_digest == base_digest
-          FAST_FORWARD
-        elsif incoming_digest == base_digest
-          KEEP
-        else
-          CONFLICT
+        def decide(file_key, state)
+          # Asked only when the guard would otherwise fire.
+          unproved = -> { state.mark == :legacy && !ShippedHistory.shipped?(provenance.name, file_key, paths(file_key)[:base]) }
+          return Merger.merge_outcome(paths(file_key), unproved: unproved) unless state.kind == :pristine
+
+          # The guard's own case at its plainest: the file is the base, which
+          # may be the user's text. One that only gains lines loses nothing, and
+          # its save_first keeps a copy (Installer#save_first).
+          sides = paths(file_key)
+          return FAST_FORWARD unless Merger.removes_lines?(File.binread(sides[:current]), File.binread(sides[:incoming]))
+
+          unproved.call ? CONFLICT.with(merge: TextMerge.failed(FileStanding::LEGACY_BASE)) : FAST_FORWARD
         end
       end
 
@@ -243,12 +253,6 @@ module Samagotchi
       def self.digest(path)
         FileDigest.hex(path)
       end
-
-      def self.current_modified?(base_path, current_path)
-        return true unless base_path && File.exist?(base_path) && File.exist?(current_path)
-
-        FileDigest.hex(base_path) != FileDigest.hex(current_path)
-      end
     end
   end
 end

data/lib/samagotchi/memory_bundle/plugin_ref.rb

@@ -3,11 +3,12 @@
 module Samagotchi
   module MemoryBundle
     # The plugin an installed bundle's record (manifest.json) names: its
-    # file under plugin/ and the sha256 recorded at install ("" when none
+    # file under plugin/, the sha256 recorded at install ("" when none
     # is; either "sha256:<hex>" or a bare hex, Provenance.recorded_sha
-    # reads both).
-    PluginRef = Data.define(:file, :sha256) do
-      def initialize(file:, sha256: "")
+    # reads both), and whether its manifest called it required (a guardrail
+    # plugin: plugin: required: true; an older chi ignores the key).
+    PluginRef = Data.define(:file, :sha256, :required) do
+      def initialize(file:, sha256: "", required: false)
         super
       end
 
@@ -20,7 +21,7 @@ module Samagotchi
 
         h = raw.transform_keys(&:to_s)
         file = h["file"].to_s
-        file.empty? ? nil : new(file: file, sha256: h["sha256"].to_s)
+        file.empty? ? nil : new(file: file, sha256: h["sha256"].to_s, required: h["required"] == true)
       end
     end
   end

data/lib/samagotchi/memory_bundle/profile.rb

@@ -27,7 +27,7 @@ module Samagotchi
       # installed: members installed now; already: members found installed
       # (recorded, not reinstalled); skipped and failed: name => why;
       # kept_own: member installed now => its memory files the user already
-      # had, left as they are and not owned (Installer#skip_existing);
+      # had, left as they are and not owned (the INSTALL rows of a file not owned);
       # trash_copies: "member: line" for what --force copied to the trash
       # (Installer#trash_copy_line).
       InstallResult = Struct.new(:name, :version, :installed, :already, :skipped, :failed, :kept_own, :trash_copies, keyword_init: true) do
@@ -140,11 +140,11 @@ module Samagotchi
       private_class_method :install_member
 
       # An Installer result for a file the user already had, with other
-      # bytes: skipped ("already exists"), or a dry run's would_skip. One
-      # with the bundle's bytes ("already up to date") isn't named: nothing
-      # of the bundle's is missing (it stays the user's all the same).
+      # bytes: kept as the user's own (:kept_own), or a dry run's
+      # :would_skip. One with the bundle's bytes (:up_to_date) isn't named:
+      # nothing of the bundle's is missing (it stays the user's all the same).
       def kept_own?(entry)
-        entry[:status] == "would_skip" || (entry[:status] == "skipped" && entry[:reason] == "already exists")
+        %i[would_skip kept_own].include?(entry.word)
       end
       private_class_method :kept_own?