samagotchi 0.157.0 → 0.159.0

data/lib/samagotchi/guardrails/pair_boundary.rb

@@ -52,7 +52,7 @@ module Samagotchi
       RULE = "pair-boundary"
       SOURCE = "core"
       OWNER_VOICED = %w[delegate register_reminder cancel_reminder send_note forget_outputs task_create task_stop
-                        find_tools objectives].freeze
+                        find_tools objectives schedule_task list_schedules cancel_schedule].freeze
       OWNER_VOICED_PREFIX = "delegate_"
       # The background task tools that read the owner's tasks (a pair turn
       # starts none: task_create is owner-voiced, and its execute is never

data/lib/samagotchi/guardrails/path_resolve.rb

@@ -153,6 +153,17 @@ module Samagotchi
         (low == low_dir || low.start_with?(File.join(low_dir, ""))) && folds_case?(dir)
       end
 
+      # Whether +root+ is the home folder or a folder above it (symlinks
+      # resolved on both; false for a blank one). ReviewPaths (a participant
+      # turn's project) and MemoryPaths (where a chi project marker is
+      # ignored) ask this.
+      # @param root [String, nil] @param home [String, nil]
+      def home_root?(root, home)
+        return false if home.to_s.empty? || root.to_s.empty?
+
+        under?(real(home.to_s), real(root.to_s))
+      end
+
       # Whether +path+ is in +dir+, not +dir+ itself (.under?'s terms).
       def strictly_under?(path, dir, fold: true)
         return true if path.start_with?(File.join(dir, ""))

data/lib/samagotchi/guardrails/review_paths.rb

@@ -59,11 +59,7 @@ module Samagotchi
       # review turn reads nothing there (#refusal: HOME_ROOT); a pair turn
       # asks the owner before every write (PairBoundary).
       # @param root [String] @param home [String, nil]
-      def self.home_root?(root, home)
-        return false if home.to_s.empty? || root.to_s.empty?
-
-        PathResolve.under?(PathResolve.real(home.to_s), PathResolve.real(root.to_s))
-      end
+      def self.home_root?(root, home) = PathResolve.home_root?(root, home)
 
       # @param root [String, nil] the session's project root (the work tree
       #   top of its folder); nil or blank refuses every path

data/lib/samagotchi/hook_routes.rb

@@ -21,7 +21,7 @@ module Samagotchi
     # How much of a failed hook's error #plugin_hook_failed shows.
     HOOK_FAILURE_CHARS = 300
     # What the notice says the hook now does, by the policy Hooks.wrap gave it
-    # (a chi.on handler is always :log; a bundle's hook file any of the three).
+    # (a chi.on handler :log, or :deny for an on_error: :fail_closed one).
     HOOK_FAILURE_EFFECTS = {
       log: "it's skipped, and only the log has its next failures",
       skip: "it's skipped, and its next failures are silent",
@@ -98,7 +98,7 @@ module Samagotchi
       nil
     end
 
-    # A bundle hook file or a chi.on handler raised (Hooks.wrap; the log has
+    # A chi.on handler raised (Hooks.wrap; the log has
     # every firing of a :log one). Its first failure on this Engine, so in
     # this worker, tells the user, as a plugin that failed to load does; then
     # only the log. One line per label — file, bundle and event — so a

data/lib/samagotchi/hooks.rb

@@ -2,12 +2,11 @@
 
 require_relative "hooks/registry"
 require_relative "hooks/loader"
-require_relative "hooks/bundle_loader"
 require_relative "hooks/stream_watch"
 
 module Samagotchi
-  # Thin wrapper that exposes the Hooks::Registry, Hooks::Loader and
-  # Hooks::BundleLoader (bundle-owned hook plugins).
+  # Thin wrapper that exposes the Hooks::Registry and Hooks::Loader
+  # (config.yml's hooks; a bundle's hook through its plugin, Plugin::Api#on).
   #
   # The Engine holds an instance of Hooks::Registry and provides:
   # - #register_hook(name, &block) — register a turn-scoped hook

data/lib/samagotchi/memory_bundle/asset_installer.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require_relative "asset_state"
+require_relative "file_actions"
 require_relative "file_digest"
-require_relative "bundle_hook"
 require_relative "manifest"
 require_relative "provenance"
 require_relative "../version"
@@ -13,22 +14,32 @@ module Samagotchi
 
     # The install of a bundle's parts that live in its own dir
     # (<bundles>/<name>/, Provenance#bundle_dir) rather than in the
-    # memories dir: hooks/*.rb, guardrails/*.yml, the plugin file and
-    # scripts/*. Each replaces what an earlier version installed. Installer
+    # memories dir: guardrails/*.yml, the plugin file and scripts/*. Each
+    # replaces what an earlier version installed. An older chi's record
+    # with class-file hooks has them removed (#retire_hooks): chi no longer
+    # loads them, and the Installer refuses a source that has any. Installer
     # runs it after the memories; it adds to the installer's results and
     # warnings, and #run returns what the record (Provenance#write) keeps.
     # A dev install (+dev+, `chi bundle install --dev`) links each file to
     # the source instead of copying it, and warns of no checksum mismatch.
-    # An edited file it replaces or removes is copied to the trash first,
-    # under its subfolder (Trash#copy_edit); a link never is.
+    # Each folder is one loop over its files' AssetStates (#install_set):
+    # FileActions' asset tables say what each gets, the dry run reading the
+    # same row. An edited file it replaces or removes is copied to the trash
+    # first, under its subfolder (AssetState#edited?, Trash.edit?'s rule); a
+    # link never is.
     class AssetInstaller
       # What was installed: the paths Provenance#write records (each
       # empty / nil on a dry run).
-      #   hooks       every hook basename the bundle ships
-      #   hook_files, guardrail_files, script_files
-      #               basename => installed path
+      #   guardrail_files, script_files  basename => installed path
       #   plugin_file the installed plugin file, nil without one
-      Installed = Data.define(:hooks, :hook_files, :guardrail_files, :plugin_file, :script_files)
+      Installed = Data.define(:guardrail_files, :plugin_file, :script_files)
+
+      # The retire's summary words (Installer#summary): why the hooks went.
+      RETIRED = "chi no longer loads class-file bundle hooks"
+
+      # A dry run's word for a real run's (Installer#summary): nothing would
+      # be written to a file already up to date.
+      DRY_WORDS = { installed: :would_install, updated: :would_update, up_to_date: :up_to_date }.freeze
 
       # @param source_dir [String] the normalized bundle source
       # @param manifest [Manifest, nil] nil for a non-strict install without one
@@ -61,18 +72,16 @@ module Samagotchi
       # @raise [Installer::InstallError] the manifest names a plugin or
       #   script the bundle doesn't have
       def run
-        install_hooks
-        prune_dropped_hooks if (@upgrade || (@dev && @existing&.dev)) && @existing && !@dry_run
-        verify_hook_checksums if @manifest && @strict && !@dev
         incoming_rules = Dir.glob(File.join(@bundle_dir, "guardrails", "*.yml")).sort
                             .reject { |src| linked_out?(src, "guardrails/#{File.basename(src)}") }
-        guardrail_files = install_guardrails(incoming_rules)
-        plugin_file = install_plugin
-        script_files = install_scripts
-        warn_hooks_requires_chi
+        guardrail_files = install_set(:rule, rules_incoming(incoming_rules))
+        plugin_file = install_set(:plugin, plugin_incoming).values.first
+        script_files = install_set(:script, scripts_incoming)
+        # After the plugin and scripts, which raise for a file the manifest
+        # names and the bundle lacks: a refused install leaves hooks/ as it was.
+        retire_hooks
         warn_rules_requires_chi(incoming_rules)
-        Installed.new(hooks: @bundle_hooks, hook_files: @hook_files, guardrail_files: guardrail_files,
-                      plugin_file: plugin_file, script_files: script_files)
+        Installed.new(guardrail_files: guardrail_files, plugin_file: plugin_file, script_files: script_files)
       end
 
       # Whether the bundle file +src+ reads through a symlink: it is one, or
@@ -91,138 +100,38 @@ module Samagotchi
 
       private
 
-      # Copies the bundle's hooks/*.rb into <bundle_dir>/hooks/: the ones
-      # its manifest lists, else (no hooks: in it) every hooks/*.rb, which is
-      # then added to manifest.hooks with no event (the loader skips it, the
-      # record keeps it). Without a manifest every hooks/*.rb is copied.
-      # Sets @bundle_hooks (every hook the bundle ships) and @hook_files
-      # (basename => installed path, for the record).
-      def install_hooks
-        @bundle_hooks = []
-        @hook_files = {}
-        return install_unlisted_hooks unless @manifest
-
-        hook_entries = @manifest.hooks
-        if hook_entries.empty?
-          Dir.glob(File.join(@bundle_dir, "hooks", "*.rb")).each { |p| hook_entries[File.basename(p)] = BundleHook.new }
-        end
-        hook_entries.keys.each do |basename|
-          next unless basename.is_a?(String) && !basename.empty?
-
-          src = File.join(@bundle_dir, "hooks", basename)
-          # A linked hook isn't the bundle's: not installed, counted or recorded.
-          next hook_entries.delete(basename) if (File.symlink?(src) || File.exist?(src)) && linked_out?(src, "hooks/#{basename}")
-
-          @bundle_hooks << basename
-          install_hook(basename, src) if File.exist?(src)
-        end
-      end
-
-      # One listed hook; an upgrade overwrites a local edit with a warning.
-      def install_hook(basename, src)
-        dest = File.join(@provenance.hooks_dir, basename)
-        result = result_for(src, dest, updated: @upgrade && @existing)
-        return @results[basename] = planned(result) if @dry_run
-
-        prev_sha = @existing&.hooks&.dig(basename)&.sha256
-        if @upgrade && File.exist?(dest) && !@force && !Provenance.recorded_sha(prev_sha).empty? && !Provenance.sha_matches?(dest, prev_sha)
-          @warnings << "Hook #{basename} was locally modified; overwriting"
+      # The hooks/ an older chi installed (class-file hooks, which no longer
+      # load): every file in it goes, an edited one (or one the record
+      # doesn't know) copied to the trash first, a dev link never (it points
+      # at the source, which stays). Each is a :removed result (a dry run's
+      # :would_remove) with the RETIRED note; an empty hooks/ dir goes
+      # without a word. The record keeps no hooks
+      # (Provenance#write).
+      def retire_hooks
+        dir = @provenance.hooks_dir
+        return unless File.directory?(dir) || File.symlink?(dir)
+
+        files = File.symlink?(dir) ? [] : Dir.glob("**/*", File::FNM_DOTMATCH, base: dir).sort.reject { |f| File.directory?(File.join(dir, f)) }
+        files.each do |file|
+          @results["hooks/#{file}"] = @dry_run ? retired.with(word: :would_remove) : retired
         end
+        return if @dry_run
 
-        FileUtils.mkdir_p(@provenance.hooks_dir)
-        @trash.copy_edit(dest, as: "hooks/#{basename}", recorded: prev_sha, incoming: src)
-        place(src, dest)
-        @results[basename] = result
-        @hook_files[basename] = dest
+        @trash.copy_edits(dir, "hooks", @existing&.hooks&.transform_values(&:sha256))
+        FileUtils.rm_rf(dir)
       end
 
-      # No manifest (a non-strict install): every hooks/*.rb is copied.
-      def install_unlisted_hooks
-        Dir.glob(File.join(@bundle_dir, "hooks", "*.rb")).each do |src|
-          basename = File.basename(src)
-          next if linked_out?(src, "hooks/#{basename}")
-
-          @bundle_hooks << basename
-          if @dry_run
-            @results[basename] = Installer::FileResult.new(word: :would_install)
-          else
-            FileUtils.mkdir_p(@provenance.hooks_dir)
-            dest = File.join(@provenance.hooks_dir, basename)
-            @trash.copy_edit(dest, as: "hooks/#{basename}", recorded: @existing&.hooks&.dig(basename)&.sha256, incoming: src)
-            place(src, dest)
-            @results[basename] = Installer::FileResult.new(word: :installed)
-            @hook_files[basename] = dest
-          end
-        end
-      end
+      def retired = Installer::FileResult.new(word: :removed, note: RETIRED)
 
-      # An upgrade removes the hooks the previous version shipped and this
-      # one doesn't (a local file too, with a warning; a dev link silently).
-      def prune_dropped_hooks
-        @existing.hooks.each_key do |old_key_str|
-          next if @bundle_hooks.include?(old_key_str)
-
-          old_dest = File.join(@provenance.hooks_dir, old_key_str)
-          if File.exist?(old_dest) && !@force && !File.symlink?(old_dest)
-            @warnings << "Bundle no longer includes hook #{old_key_str} but local file exists — removing"
-          end
-          @trash.copy_edit(old_dest, as: "hooks/#{old_key_str}", recorded: @existing.hooks[old_key_str]&.sha256)
-          FileUtils.rm_f(old_dest)
-        end
-      end
-
-      # Strict mode: a hook whose sha256 differs from the one its manifest
-      # declares warns (as verify_memory_checksums does). The bundle's file is
-      # checked, the one the install copies, so a dry run checks what it
-      # would install, not the old hook in place.
-      def verify_hook_checksums
-        @bundle_hooks.each do |basename|
-          next if @conflicts.key?(basename)
-
-          warning = FileDigest.mismatch("hook #{basename}", File.join(@bundle_dir, "hooks", basename),
-                                        @manifest.checksum_for_hook(basename))
-          @warnings << warning if warning
-        end
-      end
-
-      # The bundle's guardrails/*.yml into <bundle_dir>/guardrails/: the
-      # set replaces what an earlier version installed. Same bytes as
-      # installed are reported up to date, not "Installed".
-      # @return [Hash{String => String}] basename => installed path ({} on a dry run)
-      def install_guardrails(incoming_rules)
-        target = @provenance.guardrails_dir
-        results = incoming_rules.to_h { |src| [src, result_for(src, File.join(target, File.basename(src)), updated: false)] }
-        if @dry_run
-          results.each { |src, result| @results["guardrails/#{File.basename(src)}"] = planned(result) }
-          return {}
-        end
+      # The bundle's guardrails/*.yml, by basename.
+      def rules_incoming(incoming_rules) = incoming_rules.to_h { |src| [File.basename(src), src] }
 
-        @trash.copy_edits(target, "guardrails", @existing&.guardrails, incoming_rules.to_h { |src| [File.basename(src), src] })
-        FileUtils.rm_rf(target)
-        return {} if incoming_rules.empty?
-
-        FileUtils.mkdir_p(target)
-        incoming_rules.to_h do |src|
-          dest = File.join(target, File.basename(src))
-          place(src, dest)
-          @results["guardrails/#{File.basename(src)}"] = results[src]
-          [File.basename(src), dest]
-        end
-      end
-
-      # Copy the manifest's plugin file into the bundle's plugin/ dir,
-      # warning when its sha256 differs from the declared one or this chi
-      # doesn't meet requires_chi (the Engine then won't load it).
-      # @return [String, nil] the installed file (nil: none, or a dry run)
-      def install_plugin
+      # The manifest's plugin file, warning when this chi doesn't meet
+      # requires_chi (the Engine then won't load it). {} without one.
+      # @return [Hash{String => String}] its file => the source file
+      def plugin_incoming
         plugin = @manifest&.plugin
-        unless plugin
-          unless @dry_run
-            @trash.copy_edits(@provenance.plugin_dir, "plugin", @existing&.plugin_shas)
-            FileUtils.rm_rf(@provenance.plugin_dir)
-          end
-          return nil
-        end
+        return {} unless plugin
 
         src = File.join(@bundle_dir, plugin[:file])
         raise Installer::InstallError, "the manifest names plugin #{plugin[:file]}, which the bundle doesn't have" unless File.file?(src)
@@ -231,81 +140,84 @@ module Samagotchi
         if (failure = Manifest.requires_chi_failure(@manifest.requires_chi, @chi_version))
           @warnings << "Plugin #{plugin[:file]} won't load: #{failure}"
         end
-        dest = File.join(@provenance.plugin_dir, plugin[:file])
-        result = result_for(src, dest, updated: @upgrade && @provenance.installed?)
-        if @dry_run
-          @results[plugin[:file]] = planned(result)
-          return nil
-        end
-
-        @trash.copy_edits(@provenance.plugin_dir, "plugin", @existing&.plugin_shas, { plugin[:file] => src })
-        FileUtils.rm_rf(@provenance.plugin_dir)
-        FileUtils.mkdir_p(@provenance.plugin_dir)
-        place(src, dest)
-        @results[plugin[:file]] = result
-        warning = FileDigest.mismatch("plugin #{plugin[:file]}", dest, @manifest.checksum_for_plugin) if @strict && !@dev
-        @warnings << warning if warning
-        dest
+        { plugin[:file] => src }
       end
 
-      # The manifest's scripts, copied into <bundle_dir>/scripts/ (the
-      # folder replaced: a script the new version dropped goes). A declared
-      # sha256 that differs warns, as a plugin's does.
-      # @return [Hash{String => String}] file name => installed path
-      def install_scripts
+      # The manifest's scripts (a dev install warns of one it can't run).
+      # @return [Hash{String => String}] file name => the source file
+      def scripts_incoming
         scripts = @manifest&.scripts || {}
-        scripts.each_key do |file|
+        scripts.keys.to_h do |file|
           src = File.join(@bundle_dir, "scripts", file)
           raise Installer::InstallError, "the manifest names scripts/#{file}, which the bundle doesn't have" unless File.file?(src)
           raise Installer::InstallError, "scripts/#{file} is a symlink (not installed)" if linked?(src)
 
           @warnings << "scripts/#{file} is not executable; chmod +x #{src}" if @dev && !File.executable?(src) && !page_only?(file)
+          [file, src]
         end
-        results = scripts.keys.to_h do |file|
-          [file, result_for(File.join(@bundle_dir, "scripts", file), File.join(@provenance.scripts_dir, file),
-                            updated: @upgrade && @provenance.installed?)]
+      end
+
+      # One folder of the bundle's own dir (guardrails/, plugin/, scripts/),
+      # replaced whole by +incoming+: each file's AssetState and its action
+      # (FileActions' ASSET_INSTALL, or ASSET_UPGRADE over an installed
+      # bundle), one result per incoming file (a dry run's DRY_WORDS of it,
+      # and nothing written), an edit copied to the trash first (save_first),
+      # then the folder replaced. A file the source dropped goes without a
+      # word. A plugin or script whose sha256 differs from the declared one
+      # warns (not a dev link: it is the source).
+      # @param incoming [Hash{String => String}] name => the source file, in
+      #   the order the results list them
+      # @return [Hash{String => String}] name => installed path ({} on a dry run)
+      def install_set(kind_of_file, incoming)
+        dir, recorded = folder(kind_of_file)
+        command = @upgrade && @provenance.installed? ? :upgrade : :install
+        states = AssetState.in(dir, kind_of_file: kind_of_file, recorded: recorded, incoming: incoming)
+                           .to_h { |asset| [asset.name, [asset, FileActions.for_asset(command, asset)]] }
+        results = incoming.keys.to_h do |name|
+          asset, action = states.fetch(name)
+          [name, Installer::FileResult.new(word: @dry_run ? DRY_WORDS.fetch(action.word) : action.word, state: asset, action: action)]
         end
         if @dry_run
-          results.each { |file, result| @results["scripts/#{file}"] = planned(result) }
+          results.each { |name, result| @results[result_key(kind_of_file, name)] = result }
           return {}
         end
 
-        @trash.copy_edits(@provenance.scripts_dir, "scripts", @existing&.scripts,
-                          scripts.keys.to_h { |file| [file, File.join(@bundle_dir, "scripts", file)] })
-        FileUtils.rm_rf(@provenance.scripts_dir)
-        return {} if scripts.empty?
-
-        FileUtils.mkdir_p(@provenance.scripts_dir)
-        scripts.to_h do |file, declared|
-          dest = File.join(@provenance.scripts_dir, file)
-          place(File.join(@bundle_dir, "scripts", file), dest)
-          @results["scripts/#{file}"] = results[file]
-          FileUtils.chmod(0o755, dest) unless @dev
-          warning = FileDigest.mismatch("script #{file}", dest, declared.to_s.delete_prefix("sha256:")) if @strict && !@dev
-          @warnings << warning if warning
-          [file, dest]
+        states.each_value { |asset, action| @trash.copy(asset.path, as: asset.label) if action.save_first }
+        FileUtils.rm_rf(dir)
+        return {} if incoming.empty?
+
+        FileUtils.mkdir_p(dir)
+        incoming.to_h do |name, src|
+          dest = File.join(dir, name)
+          place(src, dest)
+          @results[result_key(kind_of_file, name)] = results[name]
+          FileUtils.chmod(0o755, dest) if kind_of_file == :script && !@dev
+          if (declared = declared_sha(kind_of_file, name)) && results[name].action.do == :write_incoming && @strict && !@dev
+            warning = FileDigest.mismatch("#{kind_of_file} #{name}", dest, declared)
+            @warnings << warning if warning
+          end
+          [name, dest]
         end
       end
 
-      # What the real run reports for +src+ over +dest+: up to date when the
-      # bytes are the same, else updated (+updated+: an upgrade over an
-      # install) or installed. A dry run records #planned of it, so the two
-      # can't drift.
-      def result_for(src, dest, updated:)
-        word = if File.file?(dest) && FileUtils.identical?(src, dest) then :up_to_date
-               elsif updated then :updated
-               else :installed
-               end
-        Installer::FileResult.new(word: word)
+      # The kind's folder and the record's shas for it.
+      def folder(kind_of_file)
+        case kind_of_file
+        when :rule then [@provenance.guardrails_dir, @existing&.guardrails]
+        when :plugin then [@provenance.plugin_dir, @existing&.plugin_shas]
+        else [@provenance.scripts_dir, @existing&.scripts]
+        end
       end
 
-      # A dry run's word for a result: would_install, would_update, or the
-      # up to date result as it is (nothing would be written).
-      def planned(result)
-        case result.word
-        when :installed then result.with(word: :would_install)
-        when :updated then result.with(word: :would_update)
-        else result
+      # Its key in the Installer's results (the summary's name): a rule's
+      # guardrails/r.yml, the plugin's own file name, a script's scripts/s.sh.
+      def result_key(kind_of_file, name) = kind_of_file == :plugin ? name : "#{AssetState::FOLDERS.fetch(kind_of_file)}/#{name}"
+
+      # The manifest's sha256 for a plugin or script (hex), nil for a rule.
+      def declared_sha(kind_of_file, name)
+        case kind_of_file
+        when :plugin then @manifest.checksum_for_plugin
+        when :script then @manifest.scripts[name].to_s.delete_prefix("sha256:")
         end
       end
 
@@ -333,21 +245,10 @@ module Samagotchi
         true
       end
 
-      # The hook loader skips every hook of a bundle whose requires_chi this
-      # chi doesn't meet (Hooks::BundleLoader); say so at install, as
-      # install_plugin does for the plugin.
-      def warn_hooks_requires_chi
-        return if @manifest.nil? || @bundle_hooks.empty?
-
-        if (failure = Manifest.requires_chi_failure(@manifest.requires_chi, @chi_version))
-          @warnings << "Bundle #{@name}: its hooks won't load: #{failure}"
-        end
-      end
-
       # GuardrailWiring#bundle_rules doesn't read the rules of a bundle whose
       # requires_chi this chi doesn't meet, and a session that never loaded
       # them records a required load failure (the gate refuses guarded calls
-      # until chi is updated): say so at install, as the hooks warning does.
+      # until chi is updated): say so at install, as #plugin_incoming does.
       def warn_rules_requires_chi(rule_files)
         return if @manifest.nil? || rule_files.empty?
 

data/lib/samagotchi/memory_bundle/asset_state.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "trash"
+
+module Samagotchi
+  module MemoryBundle
+    # One file of a bundle's own folder (a guardrail rule, the plugin, a
+    # script) as a command finds it: derived from the file on disk, the sha
+    # the record holds and the source file that would take its place, never
+    # stored. FileActions' ASSET_* tables say what each command does in each
+    # state; AssetInstaller, ShippedUpdate's plan, Uninstaller and Status read
+    # it. Whether it is edited is Trash.edit?'s answer (what the trash keeps a
+    # copy of), asked once in .of.
+    #
+    #   name          its path in its folder (r.yml, plugin.rb, s.sh)
+    #   path          where it is installed
+    #   kind_of_file  :rule, :plugin or :script
+    #   state         :new        not there (or a broken link), the source has it
+    #                 :unchanged  the source's bytes already (a dev link to them too)
+    #                 :pristine   the recorded sha, the source has other bytes
+    #                 :edited     neither the recorded sha (none recorded: unknown,
+    #                             so edited) nor the source's bytes
+    #                 :linked     a link (a dev install's) to other bytes than the
+    #                             source's: it points at a source nothing here touches
+    #                 :dropped_pristine, :dropped_edited  there, the source hasn't
+    #                             it (with no source read, as uninstall and status
+    #                             do, every file there is one of these)
+    #                 :missing    recorded, not there, the source hasn't it
+    #   recorded      the record's sha256 for it (nil: not in the record)
+    #   incoming      the source file that replaces it (nil: none)
+    AssetState = Data.define(:name, :path, :kind_of_file, :state, :recorded, :incoming) do
+      # @param path [String] the installed file
+      # @param recorded [String, nil] its recorded sha256
+      # @param incoming [String, nil] the source file put in its place
+      def self.of(path, kind_of_file:, recorded: nil, incoming: nil, name: File.basename(path))
+        new(name: name, path: path, kind_of_file: kind_of_file, state: state_of(path, recorded, incoming),
+            recorded: recorded, incoming: incoming)
+      end
+
+      # Every file of the folder +dir+ a command meets: each file in it (at
+      # any depth, as Trash#copy_edits reads it; a linked dir isn't followed),
+      # each incoming one and each recorded one, by name.
+      # @param recorded [Hash, nil] name => recorded sha256
+      # @param incoming [Hash] name => the source file
+      # @return [Array<AssetState>]
+      def self.in(dir, kind_of_file:, recorded: nil, incoming: {})
+        recorded ||= {}
+        on_disk = if File.symlink?(dir) || !File.directory?(dir) then []
+                  else Dir.glob("**/*", File::FNM_DOTMATCH, base: dir).reject { |file| File.directory?(File.join(dir, file)) }
+                  end
+        (on_disk | incoming.keys | recorded.keys).sort.map do |name|
+          of(File.join(dir, name), kind_of_file: kind_of_file, recorded: recorded[name], incoming: incoming[name], name: name)
+        end
+      end
+
+      def self.state_of(path, recorded, incoming)
+        if incoming && File.file?(path) && FileUtils.identical?(incoming, path) then :unchanged
+        elsif File.symlink?(path) && File.exist?(path) then :linked
+        elsif !File.file?(path) then incoming ? :new : :missing
+        elsif Trash.edit?(path, recorded: recorded, incoming: incoming) then incoming ? :edited : :dropped_edited
+        else incoming ? :pristine : :dropped_pristine
+        end
+      end
+      private_class_method :state_of
+
+      # Trash.edit?'s rule (asked in .of): an edit a replace or a removal
+      # would lose, so the trash keeps a copy first.
+      def edited? = %i[edited dropped_edited].include?(state)
+
+      # Where the trash keeps its copy, and the plan names it: guardrails/r.yml,
+      # plugin/plugin.rb, scripts/s.sh.
+      def label = "#{self.class::FOLDERS.fetch(kind_of_file)}/#{name}"
+    end
+
+    class AssetState
+      # Each kind's folder in the bundle's own dir (and in the trash).
+      FOLDERS = { rule: "guardrails", plugin: "plugin", script: "scripts" }.freeze
+    end
+  end
+end