samagotchi 0.150.0 → 0.152.0

data/lib/samagotchi/memory_bundle/installer.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
-require "digest"
+require_relative "file_digest"
 require_relative "../memory_paths"
 require_relative "provenance"
 require_relative "manifest"
@@ -21,14 +21,16 @@ module Samagotchi
     #
     # Flow (#run):
     #   1. Normalize source → directory, read manifest.yml (load_source)
-    #   2. Copy .md files to the target scope dir and update index.md
+    #   2. Refuse a bundle whose requires_chi this chi doesn't meet,
+    #      unless force (refuse_too_new)
+    #   3. Copy .md files to the target scope dir and update index.md
     #      (install_memories: plain, dry run, or an upgrade's 3-way merge)
-    #   3. Hooks, guardrail rules, plugin, scripts into .bundles/<name>/
+    #   4. Hooks, guardrail rules, plugin, scripts into .bundles/<name>/
     #      (AssetInstaller)
-    #   4. An upgrade prunes the files the bundle dropped
-    #   5. Verify checksums (strict mode), warn about missing needs
-    #   6. Write provenance (.bundles/<name>/manifest.json, write_provenance)
-    #   7. Detect and report {{placeholders}}
+    #   5. An upgrade prunes the files the bundle dropped
+    #   6. Verify checksums (strict mode), warn about missing needs
+    #   7. Write provenance (.bundles/<name>/manifest.json, write_provenance)
+    #   8. Detect and report {{placeholders}}
     class Installer
       class InstallError < StandardError; end
 
@@ -42,8 +44,10 @@ module Samagotchi
       # shipped_dir: the bundles this chi ships (a bundle of their names
       # installs from a dir in it only, unless force); ShippedUpdate,
       # Profile and SystemBundle pass the one they install from.
+      # chi_version: the chi this install is for (Profile and ShippedUpdate
+      # check their bundles against a version they are given); default this chi.
       def initialize(source:, name:, scope: nil, force: false, strict: true, upgrade: false, dry_run: false, prepared: nil,
-                     shipped_dir: SourceNormalizer::SHIPPED_DIR, dev: false)
+                     shipped_dir: SourceNormalizer::SHIPPED_DIR, dev: false, chi_version: Samagotchi::VERSION)
         @source = source
         @shipped_dir = shipped_dir
         @prepared = prepared
@@ -54,6 +58,7 @@ module Samagotchi
         @upgrade = upgrade
         @dry_run = dry_run
         @dev = dev
+        @chi_version = chi_version
         @results = {}
         @warnings = []
         @placeholder_warnings = []
@@ -99,12 +104,14 @@ module Samagotchi
 
       def run
         load_source
+        refuse_too_new
+        warn_unknown_keys(@manifest) if @manifest
         @target_scope, @target_dir = resolve_target
         @file_descriptions = @manifest&.file_descriptions || {}
         @provenance = Provenance.new(name: @name)
         @existing = @provenance.record
         check_source
-        # A plain install over an installed bundle: summary points at upgrade.
+        # A plain install over an installed bundle: its summary says so.
         @reinstall = @existing && !@upgrade && !@force && !@dry_run
         installed = replace_files
         verify_memory_checksums if @manifest && @strict
@@ -138,7 +145,15 @@ module Samagotchi
         merged = merged_files
         would_merge = @results.select { |_, r| r[:status].to_s == "would_merge" }.keys
         kept = @results.select { |_, r| %w[kept keep kept_pruned].include?(r[:status].to_s) }.keys
-        skipped = @results.select { |_, r| %w[skipped noop would_skip].include?(r[:status].to_s) }.keys
+        # A file whose bytes are already the bundle's was not left out: it is
+        # up to date. Skipped keeps the files really left out -- the user's own
+        # memory, and a dry run's would_skip (a dry run's `noop` carries no
+        # reason, so it stays here).
+        up_to_date = @results.select { |_, r| r[:reason] == "already up to date" }.keys
+        skipped = @results.select do |_, r|
+          status = r[:status].to_s
+          status == "would_skip" || status == "noop" || (status == "skipped" && r[:reason] != "already up to date")
+        end.keys
         would_install = @results.select { |_, r| r[:status].to_s == "would_install" }.keys
         fast_forward = @results.select { |_, r| r[:status].to_s == "fast_forward" }.keys
         removed = @results.select { |_, r| r[:status].to_s == "removed" }.keys
@@ -153,17 +168,52 @@ module Samagotchi
         lines << "Removed (no longer in the bundle): #{removed.join(", ")}#{" (moved to #{trash_dir})" if trash_dir}" unless removed.empty?
         lines << "Would remove (no longer in the bundle): #{would_remove.join(", ")}" unless would_remove.empty?
         lines << "Kept (local edits preserved): #{kept.join(", ")}" unless kept.empty?
+        lines << "Up to date: #{up_to_date.join(", ")}" unless up_to_date.empty?
         lines << "Skipped: #{skipped.join(", ")}" unless skipped.empty?
         lines << trash_copy_line if trash_copy_line
         lines.concat(@warnings) unless @warnings.empty?
         lines.concat(@placeholder_warnings) unless @placeholder_warnings.empty?
-        lines << "#{@name} is already installed; `chi bundle upgrade #{@name}` updates it and keeps local edits" if @reinstall
+        lines << reinstall_line if @reinstall
 
         lines.any? ? lines.join("\n") : "No files to install."
       end
 
+      # The one words for a record whose source can't be read again (relative,
+      # empty or gone): what `chi bundle upgrade NAME` refuses with and
+      # ManifestStanding names. An upgrade from a copy switches the source.
+      def self.source_gone_line(name, source)
+        recorded = source.to_s.strip
+        owner = recorded.empty? ? "#{name} has no recorded source" : "#{name}'s recorded source #{recorded} is gone"
+        "#{owner}: chi bundle upgrade <path or URL of a copy>"
+      end
+
+      # The one words for a dev install an upgrade or a plain install meets:
+      # it follows its source already. `Installer#refuse_dev_mismatch` raises
+      # with them, and `chi bundle upgrade NAME` (which never reaches the
+      # Installer for a dev record) prints the same line.
+      def self.dev_install_line(name, source)
+        "#{name} is a dev install of #{source}: it follows its source already " \
+          "(to leave dev mode: chi bundle uninstall #{name}, then chi bundle install without --dev)"
+      end
+
       private
 
+      # A plain install over a bundle that is already installed from the same
+      # source: it rewrote the bundle's hooks, rules, plugin, scripts and its
+      # record, and left a memory the user wrote as it was. So the line says
+      # what changed, and points at the upgrade for the memories it kept.
+      def reinstall_line
+        line = "#{@name} was already installed from #{@source}: its hooks, rules, plugin and scripts " \
+               "now match it and its record was rewritten"
+        # `already exists` is the only reason a memory is left out of a plain
+        # install (skip_existing): its bytes differ from the bundle's.
+        if @results.any? { |_, r| r[:reason] == "already exists" }
+          line << "; your own copies of its memories were kept (chi bundle upgrade #{@name} " \
+                 "merges the bundle's changes into them)"
+        end
+        line
+      end
+
       # The steps that replace files: memories, the bundle's own folder, then
       # the files it dropped. The record isn't written yet, so a failed run is
       # retried as the same upgrade.
@@ -176,7 +226,7 @@ module Samagotchi
         installed = AssetInstaller.new(
           name: @name, source_dir: @bundle_dir, manifest: @manifest, provenance: @provenance, existing: @existing,
           results: @results, warnings: @warnings, conflicts: @conflicts, trash: @trash,
-          force: @force, strict: @strict, upgrade: @upgrade, dry_run: @dry_run, dev: @dev
+          force: @force, strict: @strict, upgrade: @upgrade, dry_run: @dry_run, dev: @dev, chi_version: @chi_version
         ).run
 
         # Files the previous version shipped and this one doesn't.
@@ -232,9 +282,9 @@ module Samagotchi
         return if @existing.nil? || @existing.dev == @dev
 
         if @existing.dev
-          raise InstallError, "#{@name} is a dev install of #{@existing.source}: it follows its source already " \
-                              "(to leave dev mode: chi bundle uninstall #{@name}, then chi bundle install without --dev)"
+          raise InstallError, self.class.dev_install_line(@name, @existing.source)
         end
+
         raise InstallError, "#{@name} is installed normally; `chi bundle uninstall #{@name}` first, then chi bundle install --dev"
       end
 
@@ -298,6 +348,19 @@ module Samagotchi
         @warnings << "No manifest found — proceeding without strict manifest validation"
       end
 
+      # A bundle whose requires_chi this chi doesn't meet is not installed at
+      # all: --force is what installs it, and its plugin, hooks and rules then
+      # warn that they won't load (AssetInstaller). The words come from
+      # Manifest.requires_chi_failure, so the requirement is said one way.
+      # A dry run is refused the same way: nothing there would load either.
+      # @raise [InstallError]
+      def refuse_too_new
+        failure = Manifest.requires_chi_failure(@manifest&.requires_chi, @chi_version)
+        return if failure.nil? || @force
+
+        raise InstallError, "#{@name} can't be installed: #{failure} (chi update, or --force to install it anyway)"
+      end
+
       # The scope the files go to (the CLI's wins over the manifest's) and
       # its dir, created.
       # @return [Array(String, String)] scope, dir
@@ -473,7 +536,7 @@ module Samagotchi
           expected = @manifest.checksum_for(file_key)
           next unless expected
 
-          actual = Digest::SHA256.hexdigest(File.read(target_path))
+          actual = FileDigest.hex(target_path)
           if actual != expected
             @warnings << "Checksum mismatch for #{file_key}: expected #{expected[0..7]}..., got #{actual[0..7]}..."
           end
@@ -516,12 +579,14 @@ module Samagotchi
           incoming_dir: @bundle_dir,
           scripts_files: installed.script_files,
           context_providers: @manifest.context_providers,
+          block_renderers: @manifest.block_renderers,
           file_descriptions: @manifest.file_descriptions,
           session_settings: @manifest.session_settings,
           session_setting_types: @manifest.session_setting_types,
           settings: @manifest.settings,
           setting_types: @manifest.setting_types,
-          dev: @dev
+          dev: @dev,
+          manifest_from: @bundle_dir
         )
         # Replaced by --force: an earlier merge into it no longer says anything true.
         @provenance.clear_merge_notes([], files: @replaced)
@@ -671,6 +736,16 @@ module Samagotchi
         File.exist?(base_path) && Provenance.file_sha(target) == Provenance.file_sha(base_path)
       end
 
+      # One warning per manifest key this chi's parser never reads (docs/cli.md's
+      # unknown-key): it is ignored, so the advice is chi's own. A dry run warns
+      # too: the key is in the manifest either way.
+      def warn_unknown_keys(manifest)
+        manifest.unknown_keys.each do |key|
+          @warnings << "#{Manifest.unknown_key_line(key)}; a newer chi reads it from the installed manifest " \
+                       "(chi update, then chi bundle status #{manifest.name} says whether it needs chi bundle upgrade #{manifest.name})"
+        end
+      end
+
       # Not fatal, like update_target_index: a warning says so.
       def remove_target_index(scope, file_key)
         IndexUpdater.remove_index(scope, file_key.delete_suffix(".md"))

data/lib/samagotchi/memory_bundle/manifest.rb

@@ -4,9 +4,12 @@ require "yaml"
 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__)
+
   module MemoryBundle
     # Parses and validates a bundle manifest.yml.
     #
@@ -41,6 +44,9 @@ module Samagotchi
     #       cmd: '{ruby} {bundle_dir}/scripts/pr_context.rb {url}'
     #       why: GitHub PR      #   optional
     #       every_seconds: 300  #   optional
+    #   block_renderers:       # optional — a fence's language → the scripts/
+    #     - lang: mermaid      #   files chi web's page loads to draw it
+    #       load: [lib.js, draw.js]   # (BlockRenderers); each one a scripts: key
     #   session_settings: [cap] # optional — the settings a session may set
     #                          #   (chi --set cost-cap.cap=3), read by the
     #                          #   plugin from ctx.settings at call time;
@@ -67,15 +73,51 @@ module Samagotchi
       # A bundle name, as `chi bundle install <name>` takes a shipped one.
       BUNDLE_NAME = /\A[A-Za-z0-9][A-Za-z0-9_-]*\z/
 
+      # Every top-level manifest key this chi reads (requires_chi_next is known
+      # but read only by the release tooling: docs/releasing.md). A key not
+      # here is one this chi ignores: #unknown_keys, which `chi bundle check`
+      # and the Installer say.
+      KEYS = %w[name version scope description files hooks trust_level plugin requires_chi requires_chi_next needs
+                scripts context_providers block_renderers includes session_settings settings].freeze
+
+      # The first chi release that reads each manifest key or shape (from git:
+      # the first tag whose manifest.rb reads it), for `chi bundle check`'s
+      # requires-chi-floor on the manifest itself: a bundle whose requires_chi
+      # 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
+      # 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).
+      SINCE = {
+        "includes" => "0.8.0",
+        "scripts" => "0.32.0",
+        "context_providers" => "0.32.0",
+        "files.description" => "0.34.0",
+        "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"
+      }.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,
-                  :scripts, :context_providers, :session_settings, :session_setting_types, :settings, :setting_types
+                  :scripts, :context_providers, :block_renderers, :session_settings, :session_setting_types, :settings, :setting_types, :unknown_keys
 
       def initialize(path:)
         @path = path
         raw = load_mapping(path)
+        # Every key of the manifest, for #floor_keys to look at the shapes a
+        # newer chi reads.
+        @raw = raw
+        # A key this chi's parser never reads is one it ignores, in the order
+        # the manifest lists it.
+        @unknown_keys = raw.keys - KEYS
         @name     = require_str(raw, "name")
         # The name is a directory under .bundles/: never a path.
         if @name.match?(%r{[/\\\0]}) || %w[. ..].include?(@name)
@@ -94,6 +136,7 @@ module Samagotchi
         @needs = self.class.parse_needs(raw["needs"])
         @scripts = parse_scripts(raw["scripts"])
         @context_providers = parse_context_providers(raw["context_providers"])
+        @block_renderers = parse_block_renderers(raw["block_renderers"])
         @includes = parse_includes(raw["includes"])
         @session_settings = self.class.parse_session_settings(raw["session_settings"])
         @session_setting_types = self.class.parse_session_setting_types(raw["session_settings"])
@@ -118,6 +161,28 @@ module Samagotchi
         !@includes.empty?
       end
 
+      # An installed bundle's kept manifest.yml read key by key
+      # (InstalledManifest): each key parsed as #initialize parses it, in its
+      # own rescue and in this order, so a key that doesn't parse under this
+      # 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
+      #   (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,
+      #   trust_level, description. Then unknown_keys.
+      # @param fallback_scripts [Array<String>] the script names block_renderers
+      #   is checked against when scripts: doesn't parse (the record's)
+      # @return [Array(Manifest, Hash{String => String})] the manifest and
+      #   key => message for each key that didn't parse
+      # @raise [ValidationError] the file isn't YAML or isn't a mapping
+      def self.tolerant(path:, fallback_scripts: [])
+        manifest = allocate
+        [manifest, manifest.send(:read_tolerantly, path, fallback_scripts)]
+      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)
@@ -126,12 +191,14 @@ module Samagotchi
       end
 
       # Returns the expected sha256 hex digest for a given file key
-      # (e.g. "identity.md"), with the "sha256:" prefix stripped.
+      # (e.g. "identity.md"), with the "sha256:" prefix stripped, nil when
+      # the entry declares none (an empty value is nothing to verify).
       def checksum_for(file_key)
         raw = @files[file_key]
         return nil unless raw
 
-        raw.start_with?("sha256:") ? raw[7..] : raw
+        hex = raw.start_with?("sha256:") ? raw[7..] : raw
+        hex unless hex.nil? || hex.empty?
       end
 
       # Returns sha256 hex for a hook basename (e.g. "guardrails.rb"), nil
@@ -156,14 +223,47 @@ module Samagotchi
         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 => e # Gem::Requirement::BadRequirementError is one
+      rescue ArgumentError, EncodingError => e
+        # Gem::Requirement::BadRequirementError is an ArgumentError; bytes that
+        # aren't UTF-8 (a record another chi wrote) raise an EncodingError out
+        # of Gem::Requirement. Either way this chi can't read the requirement,
+        # which is a failure: the bundle is refused, not loaded.
         "its requires_chi #{requirement.inspect} is not a version requirement (#{e.message})"
       end
 
+      # What an unknown manifest key means, said once (docs/cli.md): the
+      # Installer and `chi bundle check` add their own fix to it.
+      def self.unknown_key_line(key, version = Samagotchi::VERSION)
+        "this chi (#{version}) doesn't know the manifest key #{key}:, so it ignores it"
+      end
+
+      # 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.
+      # @return [Hash{String => String}]
+      def floor_keys
+        raw = @raw
+        found = {}
+        found["includes"] = SINCE["includes"] unless @includes.empty?
+        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["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,
-                     plugin: nil, requires_chi: nil, needs: nil, scripts: {}, context_providers: [], file_descriptions: {},
+                     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)
         manifest = {
@@ -187,6 +287,7 @@ module Samagotchi
         manifest["needs"] = needs.map { |n| n.transform_keys(&:to_s).compact } unless needs.empty?
         manifest["scripts"] = scripts.transform_keys(&:to_s) unless scripts.empty?
         manifest["context_providers"] = context_providers.map(&:to_h) unless context_providers.empty?
+        manifest["block_renderers"] = block_renderers.map(&:to_h) unless block_renderers.empty?
         manifest["session_settings"] = session_settings_entry(session_settings, session_setting_types) unless Array(session_settings).empty?
         manifest["settings"] = session_settings_entry(settings, setting_types) unless settings.nil?
         File.write(File.join(dir, "manifest.yml"), YAML.dump(manifest))
@@ -270,6 +371,51 @@ module Samagotchi
 
       private
 
+      # Manifest.tolerant's read: the order and the keys are its comment's.
+      def read_tolerantly(path, fallback_scripts)
+        @path = path
+        raw = @raw = load_mapping(path)
+        problems = {}
+        @name = raw["name"].to_s
+        @version = raw["version"].to_s
+        @scope = normalize_scope(raw["scope"])
+        @files, @file_descriptions = tolerate(problems, "files", [{}, {}]) do
+          [parse_files(raw["files"] || {}), parse_file_descriptions(raw["files"])]
+        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"] || {}) }
+        @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
+        @block_renderers = tolerate(problems, "block_renderers", []) { parse_block_renderers(raw["block_renderers"], script_names) }
+        @includes = tolerate(problems, "includes", []) { parse_includes(raw["includes"]) }
+        @session_settings, @session_setting_types = tolerate(problems, "session_settings", [[], {}]) do
+          [self.class.parse_session_settings(raw["session_settings"]), self.class.parse_session_setting_types(raw["session_settings"])]
+        end
+        @settings, @setting_types = tolerate(problems, "settings", [nil, {}]) do
+          next [nil, {}] if raw["settings"].nil?
+
+          [self.class.parse_session_settings(raw["settings"], key: "settings"),
+           self.class.parse_session_setting_types(raw["settings"], key: "settings")]
+        end
+        @requires_chi = tolerate(problems, "requires_chi", nil) { parse_requires_chi(raw["requires_chi"]) }
+        @trust_level = tolerate(problems, "trust_level", "experimental") { (raw["trust_level"] || "experimental").to_s }
+        @description = tolerate(problems, "description", "") { (raw["description"] || "").to_s }
+        @unknown_keys = raw.keys - KEYS
+        problems
+      end
+
+      # The block's value, else +empty+ with the key's problem noted. Anything
+      # a parser raises counts: the file is a load-time input, and one key
+      # must never cost the bundle.
+      def tolerate(problems, key, empty)
+        yield
+      rescue StandardError => e
+        problems[key] = e.message
+        empty
+      end
+
       # The manifest.yml's top-level mapping ({} for an empty file); YAML that
       # doesn't parse, or isn't a mapping, raises ValidationError, as every
       # other manifest problem does.
@@ -362,6 +508,21 @@ module Samagotchi
         raise ValidationError, e.message
       end
 
+      # @param script_names [Array<String>] the scripts: keys each load must be
+      # @return [Array<BlockRenderers::Renderer>] each load is a scripts: key
+      def parse_block_renderers(raw, script_names = @scripts.keys)
+        return [] if raw.nil?
+
+        renderers = BlockRenderers.parse_list(raw)
+        renderers.each do |renderer|
+          missing = renderer.load - script_names
+          raise ValidationError, "block_renderers: #{renderer.lang} loads #{missing.join(", ")}, not under scripts:" unless missing.empty?
+        end
+        renderers
+      rescue BlockRenderers::Invalid => e
+        raise ValidationError, e.message
+      end
+
       # includes: → the names in order, duplicates dropped; [] when absent.
       # A meta ships nothing of its own, so files, hooks or a plugin next
       # to it is a ValidationError.

data/lib/samagotchi/memory_bundle/manifest_standing.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require_relative "installed_bundle"
+require_relative "installer"
+require_relative "manifest"
+require_relative "provenance"
+require_relative "source"
+
+module Samagotchi
+  module MemoryBundle
+    # The one owner of the words for an installed bundle's manifest.yml, as
+    # InstalledManifest read it (chi bundle status's Manifest: line, chi
+    # update's row), and of keeping it for a record an older chi wrote
+    # (.keep: Provenance#adopt_manifest from where it came from). The cases:
+    #   :kept     read from the kept file; a line only when chi +installed_by+
+    #             predates a key it uses (Manifest::SINCE): newer than its installer
+    #   :legacy   no kept file, no manifest_sha: a chi before the kept manifest installed it
+    #   :stale    a kept file, no manifest_sha: such a chi rewrote the record since
+    #   :missing  a manifest_sha, no kept file
+    #   :edited   the kept file isn't the recorded one (or isn't a YAML mapping)
+    # The first three and :missing are "unkept": chi update keeps the manifest
+    # where it has the bundle's own at the recorded version, else the line
+    # names the command that does.
+    module ManifestStanding
+      UNKEPT = %i[legacy stale missing].freeze
+
+      # What .keep did: bundle is the record after it (re-read when kept),
+      # line what to say (nil: nothing), kept whether it kept (or, in a dry
+      # run, would keep) the manifest.
+      Outcome = Data.define(:bundle, :line, :kept)
+
+      module_function
+
+      # @param bundle [InstalledBundle]
+      # @return [Symbol, nil] the case, nil for a record with no dir or that doesn't read
+      def state(bundle)
+        return nil if bundle.error? || bundle.dir.nil?
+
+        manifest = bundle.manifest
+        return :kept if manifest.origin == :kept
+
+        manifest.standing || :legacy
+      end
+
+      # "[kept]" when chi reads the kept manifest.yml, else "[from the install record]".
+      def label(bundle) = state(bundle) == :kept ? "[kept]" : "[from the install record]"
+
+      # The case in words with what to run, nil for a clean kept one.
+      # @param refused [String, Symbol, nil] why .keep didn't keep it: :git (not
+      #   cloned), :gone (no source left), or Provenance#adopt_manifest's why.
+      #   nil: not tried, so a source chi update can read says that it will.
+      # @return [String, nil]
+      def line(bundle, refused: nil)
+        case (state = state(bundle))
+        when :kept then newer_line(bundle)
+        when :edited then "manifest.yml changed since it was installed, so chi reads the install record (#{reinstall(bundle)})"
+        when *UNKEPT then "#{unkept_words(state)}: #{unkept_fix(bundle, refused)}"
+        end
+      end
+
+      # #line as chi bundle status says it: for a record chi update would keep
+      # from its folder, a dry Provenance#adopt_manifest first, so the line says
+      # whether it will or why not (an archive isn't extracted here: chi update
+      # tries it).
+      # @return [String, nil]
+      # A bundle chi ships is checked against this chi's shipped copy, which chi
+      # update reads (at another version, chi update upgrades it instead).
+      def status_line(bundle)
+        return line(bundle) unless bundle.manifest_unkept? && !bundle.dev && !bundle.profile?
+
+        dir = try_dir(bundle)
+        dir ? line(bundle, refused: Provenance.new(name: bundle.name).adopt_manifest(dir, dry_run: true)) : line(bundle)
+      end
+
+      # The folder chi update keeps it from, nil when it wouldn't try one here.
+      def try_dir(bundle)
+        source = bundle.source.to_s.strip
+        unless SourceIdentity.of(source)&.shipped?
+          return source.start_with?("/") && File.directory?(source) ? source : nil
+        end
+
+        dir = File.join(SourceNormalizer::SHIPPED_DIR, File.basename(source.chomp("/")))
+        File.file?(File.join(dir, "manifest.yml")) && Manifest.read(dir: dir).version == bundle.version.to_s ? dir : nil
+      rescue Manifest::ValidationError, Psych::Exception
+        nil
+      end
+
+      # Keeps the manifest of a record without a usable kept one (UNKEPT, not
+      # dev) from +source_dir+, else from the record's source: a dir as it is,
+      # a zip or tar extracted and removed after; a git URL is never cloned.
+      # A bundle with nothing to keep gets its #line.
+      # @return [Outcome]
+      def keep(bundle, source_dir: nil, dry_run: false)
+        return Outcome.new(bundle: bundle, line: line(bundle), kept: false) unless bundle.manifest_unkept? && !bundle.dev
+
+        refused = adopt(bundle, source_dir, dry_run)
+        return Outcome.new(bundle: bundle, line: line(bundle, refused: refused), kept: false) if refused
+
+        kept = dry_run ? bundle : Provenance.new(name: bundle.name).record
+        Outcome.new(bundle: kept, line: dry_run ? "would keep its manifest" : "kept its manifest", kept: true)
+      end
+
+      # @return [String, Symbol, nil] why not (as #line's refused:), nil when kept
+      def adopt(bundle, source_dir, dry_run)
+        provenance = Provenance.new(name: bundle.name)
+        return provenance.adopt_manifest(source_dir, dry_run: dry_run) if source_dir
+
+        source = bundle.source.to_s.strip
+        return :git if SourceNormalizer.git_url?(source)
+        return :gone unless local?(source)
+        return provenance.adopt_manifest(source, dry_run: dry_run) if File.directory?(source)
+
+        prepared = PreparedSource.prepare(source)
+        begin
+          provenance.adopt_manifest(prepared.dir, dry_run: dry_run)
+        ensure
+          prepared.cleanup
+        end
+      rescue SourceNormalizer::UnknownSourceError => e
+        e.message
+      end
+
+      def unkept_words(state)
+        case state
+        when :legacy then "installed by an older chi, which didn't keep its manifest"
+        when :stale then "an older chi rewrote its record after the install, so its manifest.yml may be an earlier version's"
+        else "its kept manifest.yml is gone, so chi reads the install record"
+        end
+      end
+
+      def unkept_fix(bundle, refused)
+        source = bundle.source.to_s.strip
+        return reinstall(bundle) if bundle.dev
+        return "chi bundle upgrade #{bundle.name} reads it again from #{source}" if refused == :git || SourceNormalizer.git_url?(source)
+        return Installer.source_gone_line(bundle.name, source) if gone?(source, refused)
+
+        shipped = SourceIdentity.of(source)&.shipped?
+        # chi update keeps a profile's only when chi ships it (ShippedUpdate).
+        return "chi bundle upgrade #{bundle.name} reads it again from #{source}" if bundle.profile? && !shipped
+
+        if refused
+          upgrade = shipped ? "chi bundle upgrade #{bundle.name}" : "chi bundle upgrade #{bundle.name} reads it again from #{source}"
+          return "#{upgrade} (#{refused})"
+        end
+        return "chi update keeps it" if shipped
+
+        File.file?(source) ? "chi update tries to keep it from #{source}" : "chi update keeps it from #{source}"
+      end
+
+      def gone?(source, refused) = refused == :gone || (refused.nil? && !SourceIdentity.of(source)&.shipped? && !local?(source))
+
+      # A source chi can read again here: an absolute path that is there.
+      def local?(source) = source.start_with?("/") && File.exist?(source)
+
+      def reinstall(bundle) = bundle.dev ? "chi bundle install --dev #{bundle.source}" : "chi bundle upgrade #{bundle.name}"
+
+      # The kept keys whose floor is above the chi that installed it.
+      def newer_line(bundle)
+        by = bundle.installed_by.to_s
+        return nil if by.empty? || !Gem::Version.correct?(by)
+
+        newer = bundle.manifest.floor_keys.select { |_, floor| Gem::Version.new(floor) > Gem::Version.new(by) }
+        return nil if newer.empty?
+
+        keys = newer.map { |key, floor| "#{key}: (#{floor})" }.join(", ")
+        "installed by chi #{by}, which didn't act on #{keys}: #{reinstall(bundle)}"
+      end
+      private_class_method :try_dir, :adopt, :unkept_words, :unkept_fix, :gone?, :local?, :reinstall, :newer_line
+    end
+  end
+end