samagotchi 0.156.0 → 0.157.0

data/lib/samagotchi/memory_bundle/file_actions.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require_relative "file_state"
+
+module Samagotchi
+  module MemoryBundle
+    # What each command that acts on a bundle memory does in each FileState:
+    # one table per command, so a reader sees one command on one screen. A cell
+    # is keyed [kind, mark] or [kind, :any]; a dropped file another bundle
+    # lists too is [kind, :shared] (FileState#shared_with, asked only there).
+    # A dry run reads its command's row and doesn't execute it.
+    #
+    # A new kind or a new command adds a row in each table it reaches
+    # (docs/internals/bundles.md).
+    module FileActions
+      # do:         what happens to the file's bytes
+      #   :write_incoming  the bundle's text replaces it (or is put there)
+      #   :merge           the text merge's result replaces it (Merger::Outcome)
+      #   :decide          not a function of kind and mark: the caller asks
+      #                    Merger::Upgrade#decision, and FileActions.decided
+      #                    turns its Outcome into the action
+      #   :keep            left as it is (already the bundle's, or kept)
+      #   :skip            left as it is, the bundle doesn't take it
+      #   :move_to_trash   moved to the trash (a removal)
+      #   :refuse          the command stops
+      #   :restore         the bundle's text put back (SystemBundle at its version)
+      # save_first: a copy of the old bytes goes to the trash before a write
+      #   (when they differ from what is written)
+      # next_base:  :on_disk (the file as the command leaves it), :incoming,
+      #   :recorded (the base it has; none stays none), :none (no entry left)
+      #   -- Merger::Outcome#base's vocabulary
+      # word:       the report bucket the file is on (Installer#summary)
+      # record:     the entry afterwards: :own (rebuilt, no mark), :keep_entry
+      #   (kept with its base, no mark), :mark (marked behind), :hold_mark (as
+      #   it was, mark and all), :clear_mark, :drop, :not_owned (never recorded)
+      Action = Data.define(:do, :save_first, :next_base, :word, :record) do
+        def initialize(do:, word:, next_base: :recorded, record: :own, save_first: false) = super
+
+        # The file stays behind the bundle, marked (a conflict to the report).
+        def behind? = record == :mark
+
+        # The bundle's text goes into the file: written (installed, forced or
+        # fast-forwarded) or merged into a local edit. The source file is the
+        # download, so the manifest's sha checks it (Installer's integrity
+        # check). :restore is SystemBundle's; it checks its own copy.
+        def takes_source? = %i[write_incoming merge].include?(self.do)
+      end
+
+      WRITE = Action.new(do: :write_incoming, word: :installed, next_base: :on_disk)
+      UP_TO_DATE = Action.new(do: :keep, word: :up_to_date, next_base: :on_disk)
+      USER_SAME = Action.new(do: :keep, word: :up_to_date, next_base: :none, record: :not_owned)
+      USERS_OWN = Action.new(do: :skip, word: :kept_own, next_base: :none, record: :not_owned)
+      KEPT_OWN = Action.new(do: :skip, word: :kept_own, record: :keep_entry)
+      HELD = Action.new(do: :skip, word: :kept_own, record: :hold_mark)
+      FAST_FORWARD = Action.new(do: :write_incoming, word: :updated, next_base: :on_disk)
+      KEEP = Action.new(do: :keep, word: :kept)
+      # No base: no merge is possible, so the file stays behind, marked.
+      BEHIND = Action.new(do: :keep, word: :behind, record: :mark)
+      DECIDE = Action.new(do: :decide, word: nil)
+      REFUSE = Action.new(do: :refuse, word: nil, record: :hold_mark)
+      FORCED = Action.new(do: :write_incoming, word: :installed, next_base: :on_disk, save_first: true)
+      # The bundle dropped it: a plain install keeps it and its entry (the
+      # upgrade it points at moves it), an upgrade moves it unless edited.
+      DROPPED_KEPT = Action.new(do: :keep, word: nil, record: :keep_entry)
+      DROPPED_GONE = Action.new(do: :skip, word: nil, next_base: :none, record: :drop)
+      REMOVE = Action.new(do: :move_to_trash, word: :removed, next_base: :none, record: :drop)
+      KEPT_PRUNED = Action.new(do: :keep, word: :kept_pruned, record: :keep_entry)
+      KEPT_SHARED = Action.new(do: :keep, word: :kept_shared, next_base: :none, record: :drop)
+
+      # Rows every installing command shares: files the bundle doesn't own.
+      NOT_OWNED = {
+        %i[new any] => WRITE, %i[user_same any] => USER_SAME, %i[user_file any] => USERS_OWN,
+        %i[missing any] => WRITE, %i[level any] => UP_TO_DATE, %i[unreadable any] => REFUSE
+      }.freeze
+
+      # A plain install (a re-install over the record, or a fresh one).
+      INSTALL = NOT_OWNED.merge(
+        # A file never edited takes the source's text, as an upgrade's
+        # fast-forward does (D4); an edited one stays (an upgrade merges it).
+        %i[pristine none] => FAST_FORWARD, %i[pristine_no_base none] => FAST_FORWARD,
+        %i[edited none] => KEPT_OWN, %i[diverged none] => KEPT_OWN, %i[edited_no_base none] => KEPT_OWN,
+        # A marked file it skips has missed the bundle's change as much as before.
+        %i[pristine any] => HELD, %i[edited any] => HELD, %i[diverged any] => HELD,
+        %i[pristine_no_base any] => HELD, %i[edited_no_base any] => HELD,
+        %i[dropped_pristine any] => DROPPED_KEPT, %i[dropped_edited any] => DROPPED_KEPT,
+        %i[dropped_missing any] => DROPPED_GONE
+      ).freeze
+
+      # install --force and upgrade --force: the bundle's text everywhere, an
+      # edit copied to the trash first. Its dropped rows are upgrade --force's
+      # (a plain install --force never prunes: its dropped files are INSTALL's).
+      FORCE = NOT_OWNED.merge(
+        # A file that already has the bundle's text is written all the same
+        # (nothing to save): it is installed, and checked, as any other.
+        %i[new any] => FORCED, %i[user_same any] => FORCED, %i[user_file any] => FORCED, %i[level any] => FORCED,
+        %i[pristine any] => FORCED, %i[edited any] => FORCED, %i[diverged any] => FORCED,
+        %i[pristine_no_base any] => FORCED, %i[edited_no_base any] => FORCED,
+        %i[dropped_pristine any] => REMOVE, %i[dropped_edited any] => REMOVE, %i[dropped_missing any] => DROPPED_GONE,
+        %i[dropped_pristine shared] => KEPT_SHARED, %i[dropped_edited shared] => KEPT_SHARED
+      ).freeze
+
+      # An upgrade's 3-way view (Merger::Upgrade#outcome).
+      UPGRADE = NOT_OWNED.merge(
+        %i[pristine none] => FAST_FORWARD,
+        # A marked file that equals its base takes the update; a copy is kept.
+        %i[pristine current] => FAST_FORWARD.with(save_first: true),
+        # An older chi's mark: fast-forward unless it takes a line out and
+        # ShippedHistory can't prove the base (the legacy guard).
+        %i[pristine legacy] => DECIDE,
+        %i[edited any] => KEEP,
+        # The text merge: merged, a conflict, or already merged.
+        %i[diverged any] => DECIDE,
+        # No base: no merge. One never edited (the checksum vouches for it)
+        # takes the update as a file equal to its base would (U4); a marked
+        # one, or an edit, stays behind.
+        %i[pristine_no_base none] => FAST_FORWARD,
+        %i[pristine_no_base any] => BEHIND, %i[edited_no_base any] => BEHIND,
+        %i[dropped_pristine any] => REMOVE, %i[dropped_edited any] => KEPT_PRUNED, %i[dropped_missing any] => DROPPED_GONE,
+        %i[dropped_pristine shared] => KEPT_SHARED, %i[dropped_edited shared] => KEPT_SHARED
+      ).freeze
+
+      # Remerge: the retry of a marked file at the same version. Unmarked
+      # files are never asked. Before the table, a mark whose source moved
+      # stays behind as it is (FileState#source_moved?).
+      REMERGE = {
+        %i[level any] => Action.new(do: :keep, word: :settled, next_base: :on_disk, record: :clear_mark),
+        %i[edited any] => Action.new(do: :keep, word: :settled, record: :clear_mark),
+        %i[diverged any] => DECIDE,
+        # It matches its old base: the next upgrade takes the update.
+        %i[pristine current] => BEHIND,
+        %i[pristine legacy] => DECIDE,
+        %i[pristine_no_base any] => BEHIND, %i[edited_no_base any] => BEHIND,
+        # Not shipped now: behind, nothing to merge.
+        %i[dropped_pristine any] => BEHIND, %i[dropped_edited any] => BEHIND,
+        %i[dropped_missing any] => Action.new(do: :skip, word: nil, record: :hold_mark),
+        # The next upgrade or a restore puts it back.
+        %i[missing any] => Action.new(do: :skip, word: nil, record: :hold_mark),
+        %i[unreadable any] => Action.new(do: :keep, word: :behind, record: :hold_mark)
+      }.freeze
+
+      # SystemBundle at its version: a memory not on disk is put back, one the
+      # record doesn't own too (research Q2, today's behaviour).
+      RESTORE = {
+        %i[missing any] => Action.new(do: :restore, word: :restored, next_base: :on_disk),
+        %i[new any] => Action.new(do: :restore, word: :restored, next_base: :on_disk)
+      }.freeze
+
+      # Uninstall, on the source-less kinds: an edit refuses (Uninstaller's
+      # --force moves it instead); a file another bundle lists stays.
+      UNINSTALL = {
+        %i[pristine any] => REMOVE, %i[pristine_no_base any] => REMOVE,
+        %i[edited any] => REFUSE, %i[edited_no_base any] => REFUSE, %i[unreadable any] => REFUSE,
+        %i[missing any] => DROPPED_GONE,
+        %i[pristine shared] => KEPT_SHARED, %i[pristine_no_base shared] => KEPT_SHARED,
+        %i[edited shared] => KEPT_SHARED, %i[edited_no_base shared] => KEPT_SHARED
+      }.freeze
+
+      TABLES = { install: INSTALL, force: FORCE, upgrade: UPGRADE, remerge: REMERGE, restore: RESTORE,
+                 uninstall: UNINSTALL }.freeze
+      # The kinds whose row depends on another bundle listing the file.
+      SHARED_ASKED = %i[dropped_pristine dropped_edited pristine pristine_no_base edited edited_no_base].freeze
+
+      # The command's action for +state+: [kind, :shared] when another bundle
+      # lists a file that has such a row, else [kind, mark], then [kind, :any].
+      # @param command [Symbol] a TABLES key
+      # @return [Action, nil] nil: the command never meets the state
+      def self.for(command, state)
+        table = TABLES.fetch(command)
+        if SHARED_ASKED.include?(state.kind) && table.key?([state.kind, :shared]) && state.shared_with.any?
+          return table.fetch([state.kind, :shared])
+        end
+
+        table[[state.kind, state.mark]] || table[[state.kind, :any]]
+      end
+
+      # A :decide cell's answer: the action Merger::Upgrade#decision's Outcome
+      # stands for. Remerge never fast-forwards (the next upgrade does) and
+      # settles a file with nothing left to miss.
+      # @param outcome [Merger::Outcome]
+      # @param command [Symbol] :upgrade or :remerge
+      def self.decided(outcome, command = :upgrade)
+        case outcome.status
+        when :merged then Action.new(do: :merge, word: :merged, next_base: :incoming, save_first: true)
+        when :conflict then BEHIND
+        when :fast_forward then command == :remerge ? BEHIND : FAST_FORWARD.with(save_first: true)
+        when :keep, :noop
+          command == :remerge ? Action.new(do: :keep, word: :settled, next_base: outcome.base, record: :clear_mark) : KEEP.with(next_base: outcome.base)
+        else raise ArgumentError, "no action for outcome #{outcome.status.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/file_digest.rb

@@ -26,6 +26,19 @@ module Samagotchi
         hex = hex(path)
         hex && "sha256:#{hex}"
       end
+
+      # The integrity check's one warning: +path+'s bytes against the sha
+      # hex a manifest declares for it. nil when they match, or when there is
+      # nothing to check (no sha declared, no file).
+      # @param label [String] what the file is ("a.md", "hook guard.rb")
+      def self.mismatch(label, path, expected)
+        return nil if expected.nil? || expected.empty?
+
+        actual = hex(path)
+        return nil if actual.nil? || actual == expected
+
+        "Checksum mismatch for #{label}: expected #{expected[0..7]}..., got #{actual[0..7]}..."
+      end
     end
   end
 end

data/lib/samagotchi/memory_bundle/file_state.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require_relative "file_digest"
+require_relative "installed_bundle"
+require_relative "provenance"
+
+module Samagotchi
+  module MemoryBundle
+    # One bundle memory as a command meets it: which of a few states it is in,
+    # computed once from the file (D), its base (B), the bundle's text (I) and
+    # the record's entry (R). Derived, never stored. FileActions says what each
+    # acting command does in each state.
+    #
+    # kind, with a source (install, upgrade, remerge, restore, plan):
+    #   :new               not the bundle's, not on disk
+    #   :user_same         not the bundle's, on disk with I's bytes
+    #   :user_file         not the bundle's, other bytes (the user's own file)
+    #   :missing           the bundle's, not on disk
+    #   :level             the bundle's, D == I
+    #   :pristine          never edited (#edited?: D == R's checksum, or with
+    #                      none D == B): the bundle's text as installed
+    #   :edited            edited, D != B, I == B: the user changed it, the
+    #                      bundle didn't
+    #   :diverged          edited, D != B, I != B: both changed it
+    #   :pristine_no_base  no B, never edited (D == R's checksum)
+    #   :edited_no_base    no B, edited (or no checksum to tell); or a B equal
+    #                      to D that the checksum calls edited: no base to
+    #                      merge from
+    #   :dropped_pristine / :dropped_edited / :dropped_missing  the bundle no
+    #                      longer ships it (no I): unedited, edited, gone
+    #   :unreadable        on disk, but it can't be read
+    # Edited or not is always the one rule (#edited?, the checksum first);
+    # the base then says what the user changed.
+    #
+    # kind, with no source (status, uninstall, diff): I is unknown, so only
+    # :pristine :edited :pristine_no_base :edited_no_base :missing :unreadable,
+    # from #edited? alone.
+    #
+    # mark: :none, :current (a mark this chi wrote) or :legacy (an older
+    # chi's, InstalledBundle.legacy_mark?).
+    FileState = Data.define(:key, :kind, :mark, :digests, :entry, :paths, :claimants) do
+      # Provenance.unchanged?'s answer negated: the one edited rule (checksum
+      # first, then the base). A file it can't read counts as edited.
+      def edited?
+        return false if entry.nil?
+
+        !Provenance.unchanged?(paths[:current], entry, paths[:base])
+      rescue SystemCallError
+        true
+      end
+
+      def marked? = mark != :none
+
+      # A marked file whose source moved since the mark: the mark speaks of
+      # other text than the bundle ships now (Remerge's first question). A mark
+      # that names no text (an older chi's) never moved.
+      def source_moved?
+        marked? && !digests.marked_incoming.nil? && !digests.incoming.nil? && digests.marked_incoming != digests.incoming
+      end
+
+      # The other installed bundles that list the file too. Asked lazily: only
+      # a dropped file and an uninstall need it (Provenance.claimants reads
+      # every record).
+      def shared_with = claimants.call
+    end
+
+    # The digests of the file's texts, each read once: disk (:unreadable when
+    # it can't be read), base, incoming (nil with no source), the record's
+    # checksum, and the text a mark speaks of (nil without a mark or for an
+    # older chi's mark).
+    FileState::Digests = Data.define(:disk, :base, :incoming, :recorded, :marked_incoming)
+
+    class << FileState
+      # @param record [InstalledBundle, nil] the bundle's record
+      # @param provenance [Provenance] the record's (for the base path)
+      # @param source_dir [String, nil] the bundle's incoming dir; nil: the
+      #   source-less kinds
+      # @param claimants [#call, nil] key => other bundles listing it
+      #   (Provenance.claimants), called at most once
+      # @param shipped [Boolean] false: the bundle no longer ships the key
+      #   (a dropped kind), whatever its source dir holds by that name
+      # @return [FileState]
+      def of(key, record:, provenance:, target_dir:, source_dir:, claimants: nil, shipped: true)
+        entry = record&.files&.fetch(key, nil)
+        paths = { base: provenance.base_path(key), current: File.join(target_dir, key),
+                  incoming: source_dir && File.join(source_dir, key) }
+        mark = mark_of(entry)
+        digests = FileState::Digests.new(
+          disk: digest(paths[:current]), base: entry ? digest(paths[:base]) : nil,
+          incoming: source_dir && shipped ? digest(paths[:incoming]) : nil, recorded: entry && Provenance.recorded_sha(entry[:checksum]),
+          marked_incoming: mark == :none ? nil : entry[:incoming_sha]
+        )
+        shared = nil
+        lookup = -> { shared ||= claimants ? claimants.call(key) : [] }
+        state = FileState.new(key: key, kind: nil, mark: mark, digests: digests, entry: entry, paths: paths, claimants: lookup)
+        state.with(kind: source_dir ? kind_with_source(state) : kind_without_source(state))
+      end
+
+      private
+
+      def mark_of(entry)
+        return :none unless entry && entry[:conflict]
+
+        InstalledBundle.legacy_mark?(entry) ? :legacy : :current
+      end
+
+      def digest(path)
+        FileDigest.hex(path)
+      rescue SystemCallError
+        :unreadable
+      end
+
+      def kind_with_source(state)
+        d = state.digests
+        return not_owned(d) unless state.entry
+        return :unreadable if d.disk == :unreadable
+        return dropped(state) if d.incoming.nil?
+        return :missing if d.disk.nil?
+        return :level if d.disk == d.incoming
+        return state.edited? ? :edited_no_base : :pristine_no_base if d.base.nil?
+        return :pristine unless state.edited?
+        # Edited by the one rule, yet equal to its base: the base can't say
+        # what the user changed (it isn't the text the record vouches for),
+        # so there is none to merge from.
+        return :edited_no_base if d.disk == d.base
+
+        d.incoming == d.base ? :edited : :diverged
+      end
+
+      def kind_without_source(state)
+        d = state.digests
+        return :unreadable if d.disk == :unreadable
+        return :missing if d.disk.nil?
+        return state.edited? ? :edited_no_base : :pristine_no_base if d.base.nil?
+
+        state.edited? ? :edited : :pristine
+      end
+
+      def not_owned(digests)
+        return :new if digests.disk.nil?
+
+        digests.disk == digests.incoming ? :user_same : :user_file
+      end
+
+      def dropped(state)
+        return :dropped_missing if state.digests.disk.nil?
+
+        state.edited? ? :dropped_edited : :dropped_pristine
+      end
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/installed_copy.rb

@@ -93,7 +93,8 @@ module Samagotchi
         return nil unless bundle.plugin
 
         file = bundle.plugin.file
-        { file: file, sha256: copy(provenance.plugin_path(bundle), File.join(dir, file), bundle.plugin.sha256) }
+        { file: file, sha256: copy(provenance.plugin_path(bundle), File.join(dir, file), bundle.plugin.sha256),
+          required: bundle.manifest.plugin_required }
       end
       private_class_method :plugin
 

data/lib/samagotchi/memory_bundle/installed_manifest.rb

@@ -50,6 +50,11 @@ module Samagotchi
     #                               as Manifest reads them (settings nil when
     #                               the manifest said nothing of them)
     #   file_descriptions           file key => the memory's description
+    #   plugin_required             plugin: required: true (a guardrail plugin:
+    #                               one that fails to load denies every tool
+    #                               call): the record's (PluginRef#required,
+    #                               recorded at install) or the kept manifest's,
+    #                               so a lost or edited kept file keeps it
     #   includes                    a profile's recorded members (the record's
     #                               identity, never the kept file's), nil for a plain bundle
     #   unknown_keys                the kept manifest's keys this chi doesn't know
@@ -59,7 +64,7 @@ module Samagotchi
     class InstalledManifest < Data.define(:name, :version, :requires_chi, :trust_level, :description, :hooks, :needs,
                                           :script_names, :context_providers, :block_renderers, :session_settings,
                                           :session_setting_types, :settings, :setting_types, :file_descriptions,
-                                          :includes, :unknown_keys, :floor_keys, :problems, :origin)
+                                          :plugin_required, :includes, :unknown_keys, :floor_keys, :problems, :origin)
       # The key problems names the kept file's standing under.
       KEPT_FILE = "manifest.yml"
       # How many manifests the cache holds before it starts again.
@@ -133,6 +138,7 @@ module Samagotchi
             session_settings: session.session_settings, session_setting_types: session.session_setting_types,
             settings: settings.settings, setting_types: settings.setting_types,
             file_descriptions: pick.call("files", kept.file_descriptions, mirrored.file_descriptions),
+            plugin_required: kept.plugin&.dig(:required) == true || mirrored.plugin_required,
             includes: bundle.includes,
             unknown_keys: kept.unknown_keys.map(&:to_s), floor_keys: floors(kept), problems: problems.freeze, origin: :kept)
       end
@@ -168,6 +174,7 @@ module Samagotchi
             settings: list(raw["settings"]),
             setting_types: types(raw["setting_types"]),
             file_descriptions: file_descriptions(bundle.files),
+            plugin_required: bundle.plugin&.required == true,
             includes: bundle.includes, unknown_keys: [], floor_keys: {}, problems: problems.freeze, origin: :record)
       end