samagotchi 0.149.0 → 0.151.0

data/lib/samagotchi/memory_bundle/installer.rb

@@ -34,6 +34,9 @@ module Samagotchi
 
       attr_reader :results, :warnings, :placeholder_warnings, :conflicts
 
+      # Each file this run left behind (FileStanding::Behind).
+      attr_reader :behind
+
       # prepared: the source already normalized (a PreparedSource, which the
       # Installer then owns and cleans up as its own); nil normalizes source.
       # shipped_dir: the bundles this chi ships (a bundle of their names
@@ -55,6 +58,9 @@ module Samagotchi
         @warnings = []
         @placeholder_warnings = []
         @conflicts = {}
+        @behind = []
+        @replaced = []
+        @outcomes = {}
         @overlays = []
         @trash = Trash.new(name)
       end
@@ -63,10 +69,16 @@ module Samagotchi
       # source (Installer#check_source), else nil.
       attr_reader :source_change
 
-      # Where an upgrade moved the files the bundle no longer ships (nil:
-      # none moved).
+      # Where this install moved the files the bundle no longer ships and
+      # copied the ones it overwrote (nil: none).
       def trash_dir = @trash.dir
 
+      # What it copied to the trash before overwriting, said once (nil: nothing).
+      def trash_copy_line = @trash.copy_line
+
+      # The files this run merged, the bundle's changes joined to the user's.
+      def merged_files = @results.select { |_, r| r[:status] == "merged" }.keys
+
       # The normalized source dir. An owned one (a git/zip/tar extract) is
       # removed after #run, or kept until #cleanup_source! when an upgrade
       # has conflicts (the agent step reads the incoming files); nil once
@@ -94,16 +106,7 @@ module Samagotchi
         check_source
         # A plain install over an installed bundle: summary points at upgrade.
         @reinstall = @existing && !@upgrade && !@force && !@dry_run
-        install_memories
-
-        installed = AssetInstaller.new(
-          name: @name, source_dir: @bundle_dir, manifest: @manifest, provenance: @provenance, existing: @existing,
-          results: @results, warnings: @warnings, conflicts: @conflicts,
-          force: @force, strict: @strict, upgrade: @upgrade, dry_run: @dry_run, dev: @dev
-        ).run
-
-        # Files the previous version shipped and this one doesn't.
-        prune_dropped_files(@existing.files, @bundle_md, @target_dir, @target_scope, @provenance) if @upgrade && @existing
+        installed = replace_files
         verify_memory_checksums if @manifest && @strict
         warn_missing_needs(@manifest) if @manifest
         if @manifest && !@dry_run
@@ -113,6 +116,7 @@ module Samagotchi
 
         [@bundle_dir, @manifest]
       ensure
+        note_merges
         # An owned source (git/zip/tar) is cleaned up here, unless an upgrade
         # kept conflicts: the agent step still needs the incoming files, so
         # the caller runs #cleanup_source! when it is done.
@@ -131,9 +135,10 @@ module Samagotchi
         lines << "Source changes: #{@source_change.join(" → ")}" if @source_change
         installed = @results.select { |_, r| r[:status].to_s == "installed" }.keys
         updated = @results.select { |_, r| r[:status].to_s == "updated" }.keys
-        kept = @results.select { |_, r| %w[kept kept_pruned].include?(r[:status].to_s) }.keys
+        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
-        conflicts = @results.select { |_, r| r[:status].to_s == "conflict" }.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
@@ -143,11 +148,13 @@ module Samagotchi
         lines << "Updated: #{updated.join(", ")}" unless updated.empty?
         lines << "Would install: #{would_install.join(", ")}" unless would_install.empty?
         lines << "Fast-forward: #{fast_forward.join(", ")}" unless fast_forward.empty?
+        lines << FileStanding.merged_line(merged, @manifest&.version) unless merged.empty?
+        lines << FileStanding.merged_line(would_merge, @manifest&.version, dry_run: true) unless would_merge.empty?
         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 << "Skipped: #{skipped.join(", ")}" unless skipped.empty?
-        lines << "Conflicts: #{conflicts.join(", ")}" unless conflicts.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
@@ -157,6 +164,28 @@ module Samagotchi
 
       private
 
+      # 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.
+      # @return [AssetInstaller::Installed]
+      # @raise [InstallError] a file system error (a file it can't read, a
+      #   .trash it can't write)
+      def replace_files
+        install_memories
+
+        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
+        ).run
+
+        # Files the previous version shipped and this one doesn't.
+        prune_dropped_files(@existing.files, @bundle_md, @target_dir, @target_scope, @provenance) if @upgrade && @existing
+        installed
+      rescue SystemCallError => e
+        raise InstallError, Trash.failure_message(e)
+      end
+
       # Who may install under this name (a manifest can take any name: a
       # repo calling itself guardrails). Sources compare by SourceIdentity
       # (a shipped dir by name, in any gem or checkout; a git URL without
@@ -314,8 +343,12 @@ module Samagotchi
             @owned << file_key if owned_before.include?(file_key)
             skip_existing(file_key, file_path, target_path, @target_scope, owned: owned_before.include?(file_key))
           else
+            # Only --force gets here with a file in place: a copy keeps it.
+            @replaced << file_key if File.exist?(target_path)
+            @trash.copy(target_path) if File.exist?(target_path) && !FileUtils.identical?(file_path, target_path)
             FileUtils.cp(file_path, target_path)
             @owned << file_key
+            @outcomes[file_key] = Merger::INSTALL
             @results[file_key] = { status: "installed" }
             update_target_index(@target_scope, target_path, file_key)
           end
@@ -338,30 +371,71 @@ module Samagotchi
         MemoryFiles.symlinks(@bundle_dir, @manifest).each { |name| @warnings << "#{name} is a symlink (not installed)" }
       end
 
-      # An upgrade's 3-way merge of one file (Merger.classify against the
-      # base the last install recorded); a conflict leaves the local file
-      # and is recorded in @conflicts for the agent step.
+      # An upgrade's 3-way merge of one file (Merger::Upgrade against the
+      # base the last install recorded); a clean text merge replaces the file;
+      # a conflict leaves it and is recorded in @conflicts for the agent step.
       def merge_memory(file_key, file_path, target_path)
-        base_path = @provenance.base_path(file_key)
-        case Merger.classify(base_path: base_path, current_path: target_path, incoming_path: file_path)
+        outcome = @outcomes[file_key] = upgrade_view.outcome(file_key)
+        case outcome.status
         when :install
           FileUtils.cp(file_path, target_path)
           @results[file_key] = { status: "installed" }
         when :fast_forward
+          save_marked_file(file_key, target_path)
           FileUtils.cp(file_path, target_path)
           @results[file_key] = { status: "updated", reason: "auto-merged (not edited)" }
         when :keep
-          @results[file_key] = { status: "kept", reason: "bundle unchanged, local edits preserved" }
+          @results[file_key] = { status: "kept", reason: outcome == Merger::KEEP ? "bundle unchanged, local edits preserved" : "local edits already hold the bundle's changes" }
         when :noop
           @results[file_key] = { status: "skipped", reason: "already up to date" }
+        when :merged
+          if Merger.write_merged(target_path, outcome, @trash)
+            @results[file_key] = { status: "merged", reason: "the bundle's changes joined to local edits" }
+          else
+            note_conflict(file_key, @outcomes[file_key] = Merger::CONFLICT.with(merge: TextMerge.failed(TextMerge::RACED)))
+          end
         when :conflict
-          @results[file_key] = { status: "conflict", reason: "local edits conflict with bundle update" }
-          @conflicts[file_key] = { base: base_path, current: target_path, incoming: file_path }
-          @warnings << "Conflict in #{file_key}: local edits conflict with bundle update (use --force to overwrite or resolve interactively)"
+          note_conflict(file_key, outcome)
+        else raise ArgumentError, "unknown outcome status #{outcome.status.inspect} for #{file_key}" # the base would move with nothing written
         end
         update_target_index(@target_scope, target_path, file_key)
       end
 
+      # The file stays as it is, with the old base and the mark, in FileStanding's
+      # words.
+      def note_conflict(file_key, outcome)
+        behind = upgrade_view.behind(file_key, outcome, @manifest&.version)
+        @behind << behind
+        @results[file_key] = { status: "conflict", reason: behind.state(dry_run: @dry_run) }
+        @conflicts[file_key] = upgrade_view.paths(file_key)
+        @warnings << "#{behind.line(dry_run: @dry_run)} (#{FileStanding::FORCE_TAKES})"
+      end
+
+      # What merged, on the record, a run that failed later too: the file holds the
+      # merge whichever way the run ended. Never fails the run.
+      def note_merges
+        return if merged_files.empty?
+
+        @provenance.note_merged(merged_files, version: @manifest&.version, trash: trash_dir)
+      rescue StandardError => e
+        @warnings << "merge not noted on the record (#{e.message})"
+      end
+
+      def upgrade_view
+        @upgrade_view ||= Merger::Upgrade.new(provenance: @provenance, target_dir: @target_dir, source_dir: @bundle_dir)
+      end
+
+      # A marked file that equals its base, and the update goes ahead: the base
+      # is known to be real (this chi's mark, or ShippedHistory), or no line of the
+      # file goes. A copy is kept, and it says so. (Merger::Upgrade#outcome stops
+      # an older chi's mark otherwise.)
+      def save_marked_file(file_key, target_path)
+        return unless @existing.files.dig(file_key, :conflict)
+
+        @trash.copy(target_path)
+        @warnings << "#{file_key} was marked as kept but matched its recorded base, so it took the update; your copy is in the trash"
+      end
+
       # A dry run's verdict for one file, nothing written: an upgrade
       # classifies as merge_memory would (its status is the classification).
       def preview_memory(file_key, file_path, target_path)
@@ -371,10 +445,10 @@ module Samagotchi
         end
 
         if @upgrade && @existing
-          base_path = @provenance.base_path(file_key)
-          classification = Merger.classify(base_path: base_path, current_path: target_path, incoming_path: file_path)
-          @results[file_key] = { status: classification.to_s }
-          @conflicts[file_key] = { base: base_path, current: target_path, incoming: file_path } if classification == :conflict
+          outcome = upgrade_view.outcome(file_key)
+          return note_conflict(file_key, outcome) if outcome.conflict?
+
+          @results[file_key] = { status: outcome.merged? ? "would_merge" : outcome.status.to_s }
         elsif FileUtils.identical?(file_path, target_path)
           @results[file_key] = { status: "skipped", reason: "already up to date" }
         else
@@ -383,14 +457,15 @@ module Samagotchi
       end
 
       # Strict mode: a memory written from the bundle whose sha256 differs
-      # from its manifest's warns. One that wasn't copied (kept, skipped:
-      # a local edit isn't a bad download) or was merged isn't checked.
+      # from its manifest's warns. One that wasn't copied (kept, skipped, a
+      # dry run's keep and would_skip: a local edit isn't a bad download) or
+      # was merged (merged, a dry run's would_merge) isn't checked.
       def verify_memory_checksums
         @bundle_md.each do |file_key|
           next if @conflicts.key?(file_key)
 
           status = @results[file_key] ? @results[file_key][:status].to_s : nil
-          next if %w[kept kept_pruned fast_forward updated skipped].include?(status)
+          next if %w[kept keep kept_pruned fast_forward updated skipped would_skip merged would_merge].include?(status)
 
           target_path = File.join(@target_dir, file_key)
           next unless File.exist?(target_path)
@@ -437,9 +512,11 @@ module Samagotchi
           plugin_file: installed.plugin_file,
           requires_chi: @manifest.requires_chi,
           needs: @manifest.needs,
-          conflicts: @conflicts.keys,
+          marks: @behind + held_conflict_marks,
+          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,
@@ -447,34 +524,69 @@ module Samagotchi
           setting_types: @manifest.setting_types,
           dev: @dev
         )
+        # Replaced by --force: an earlier merge into it no longer says anything true.
+        @provenance.clear_merge_notes([], files: @replaced)
+      end
+
+      # The files a plain install skipped that are still marked conflict:
+      # Provenance#write rebuilds their entries, and a file it left alone has
+      # missed the bundle's change as much as before (its version may move on
+      # all the same). One with the incoming bytes has nothing left to miss.
+      # @return [Array<FileStanding::Behind>]
+      def held_conflict_marks
+        return [] if @upgrade || @existing.nil?
+
+        kept = @owned.select { |key| @results.dig(key, :reason) == "already exists" && @existing.files.dig(key, :conflict) }
+        kept.map { |key| held_mark(key) }
       end
 
-      # file key => the file whose content becomes its base. A file the
-      # upgrade left as the user has it (kept, noop, conflict, kept_pruned)
-      # keeps its old base, so the next upgrade still sees the local edit;
-      # the rest (installed, updated, skipped) take what is on disk now. A
-      # file the bundle dropped but the user kept stays recorded too.
+      # The mark now speaks of this source's text, so what it says comes from that
+      # text too: what was missed recomputed, an old reason dropped. No merge ran,
+      # so one from an older chi, which can't name sections, keeps its own words.
+      def held_mark(key)
+        entry = @existing.files.fetch(key)
+        return @existing.behind_entry(key, entry).with(version: @manifest.version) if InstalledBundle.legacy_mark?(entry)
+
+        upgrade_view.behind(key, Merger::CONFLICT, @manifest.version)
+      rescue SystemCallError
+        FileStanding::Behind.new(file: key, version: @manifest.version)
+      end
+
+      # file key => the file whose content becomes its base: the one its
+      # Merger::Outcome names (next_base). A file the bundle dropped but the
+      # user kept stays recorded too, with the base it has.
       def upgrade_provenance_files
         files = {}
         @owned.each do |file_key|
-          target_path = File.join(@target_dir, file_key)
-          next unless File.exist?(target_path)
+          next unless File.exist?(File.join(@target_dir, file_key))
 
-          status = @results[file_key] ? @results[file_key][:status].to_s : nil
-          base_path = @provenance.base_path(file_key)
-          files[file_key] = %w[kept noop conflict kept_pruned].include?(status) && File.exist?(base_path) ? base_path : target_path
+          files[file_key] = next_base(file_key, @outcomes.fetch(file_key))
         end
         @existing.files.each_key do |old_key_str|
           next if @bundle_md.include?(old_key_str)
           next unless @results[old_key_str] && @results[old_key_str][:status].to_s == "kept_pruned"
 
-          base_path = @provenance.base_path(old_key_str)
-          src = File.exist?(base_path) ? base_path : File.join(@target_dir, old_key_str)
-          files[old_key_str] = src if File.exist?(src)
+          files[old_key_str] = recorded_base(@provenance.base_path(old_key_str))
         end
         files
       end
 
+      # The file an Outcome's base names. nil for a kept file with no base:
+      # the user's file must not become one, or the next upgrade fast-forwards
+      # over it.
+      def next_base(file_key, outcome)
+        case outcome.base
+        when :recorded then recorded_base(@provenance.base_path(file_key))
+        when :on_disk then File.join(@target_dir, file_key)
+        when :incoming then File.join(@bundle_dir, file_key)
+        else raise ArgumentError, "unknown base #{outcome.base.inspect} for #{file_key}" # nil would drop the base silently
+        end
+      end
+
+      # +base_path+, nil when there is no base (Provenance#write's "keep the
+      # entry, without one").
+      def recorded_base(base_path) = File.exist?(base_path) ? base_path : nil
+
       # file key => its base's content source for a plain install. Skipped
       # for a local edit: keep the installed base, so the next upgrade still
       # sees the edit (not a fast-forward over it).
@@ -483,9 +595,8 @@ module Samagotchi
           target_path = File.join(@target_dir, file_key)
           next unless File.exist?(target_path)
 
-          base_path = @provenance.base_path(file_key)
-          kept = @existing && @results.dig(file_key, :reason) == "already exists" && File.exist?(base_path)
-          map[file_key] = kept ? base_path : target_path
+          kept = @existing && @results.dig(file_key, :reason) == "already exists"
+          map[file_key] = kept ? recorded_base(@provenance.base_path(file_key)) : target_path
         end
         files.merge(dropped_owned_files)
       end
@@ -503,8 +614,7 @@ module Samagotchi
           next if @bundle_md.include?(file_key)
           next unless File.exist?(File.join(@target_dir, file_key))
 
-          base_path = @provenance.base_path(file_key)
-          files[file_key] = base_path if File.exist?(base_path)
+          files[file_key] = recorded_base(@provenance.base_path(file_key))
         end
       end
 
@@ -520,7 +630,7 @@ module Samagotchi
           return
         else
           @results[file_key] = { status: "skipped", reason: "already exists" }
-          @warnings << "Skipped #{file_key} (already exists; use --force to overwrite)"
+          @warnings << "Skipped #{file_key} (already exists; #{FileStanding::FORCE_TAKES})"
         end
         update_target_index(scope, target_path, file_key, owned: owned) unless @dry_run
       end
@@ -548,7 +658,7 @@ module Samagotchi
             remove_target_index(scope, key)
           else
             @results[key] = { status: "kept_pruned", reason: "local edits preserved" }
-            @warnings << "Kept #{key}: no longer in the bundle but edited locally (use --force to remove)"
+            @warnings << "Kept #{key}: no longer in the bundle but edited locally (#{FileStanding::FORCE_MOVES})"
           end
         end
       end

data/lib/samagotchi/memory_bundle/listing.rb

@@ -15,8 +15,9 @@ module Samagotchi
     # its own line, and they aren't listed again.
     module Listing
       # error is set (and the rest nil) when the provenance manifest.json
-      # can't be read; includes is a profile's recorded members, else nil.
-      Installed = Struct.new(:name, :version, :scope, :files, :installed_at, :upgrade, :error, :includes, keyword_init: true)
+      # can't be read; includes is a profile's recorded members, else nil;
+      # behind is its files that stay behind (InstalledBundle#behind_files).
+      Installed = Struct.new(:name, :version, :scope, :files, :installed_at, :upgrade, :error, :includes, :behind, keyword_init: true)
       # source is the name `chi bundle install` takes (the shipped dir's
       # name); includes is a profile's members ([] for a plain bundle).
       Shipped = Struct.new(:name, :source, :version, :description, :includes, keyword_init: true)
@@ -50,7 +51,7 @@ module Samagotchi
           Installed.new(name: name, version: bundle.version, scope: bundle.scope,
                         files: bundle.files.size, installed_at: bundle.installed_at,
                         upgrade: ship && newer?(ship.version, bundle.version) ? ship : nil,
-                        includes: bundle.includes)
+                        includes: bundle.includes, behind: bundle.behind_files)
         end
       end
 

data/lib/samagotchi/memory_bundle/manifest.rb

@@ -7,6 +7,8 @@ require_relative "../context_providers"
 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 +43,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;
@@ -71,7 +76,7 @@ module Samagotchi
       # 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
 
       def initialize(path:)
         @path = path
@@ -94,6 +99,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"])
@@ -163,7 +169,7 @@ module Samagotchi
       # 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 +193,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))
@@ -362,6 +369,20 @@ module Samagotchi
         raise ValidationError, e.message
       end
 
+      # @return [Array<BlockRenderers::Renderer>] each load is a scripts: key
+      def parse_block_renderers(raw)
+        return [] if raw.nil?
+
+        renderers = BlockRenderers.parse_list(raw)
+        renderers.each do |renderer|
+          missing = renderer.load - @scripts.keys
+          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.