samagotchi 0.74.0 → 0.76.0

data/lib/samagotchi/memory_bundle/asset_installer.rb

@@ -55,6 +55,7 @@ module Samagotchi
         prune_dropped_hooks if @upgrade && @existing && !@dry_run
         verify_hook_checksums if @manifest && @strict
         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
@@ -81,11 +82,14 @@ module Samagotchi
         if hook_entries.empty?
           Dir.glob(File.join(@bundle_dir, "hooks", "*.rb")).each { |p| hook_entries[File.basename(p)] = BundleHook.new }
         end
-        hook_entries.each_key do |basename|
+        hook_entries.keys.each do |basename|
           next unless basename.is_a?(String) && !basename.empty?
 
-          @bundle_hooks << basename
           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
@@ -120,6 +124,8 @@ module Samagotchi
       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] = { status: "would_install" }
@@ -207,6 +213,7 @@ module Samagotchi
 
         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)
+        raise Installer::InstallError, "plugin #{plugin[:file]} is a symlink (not installed)" if linked?(src)
 
         if (failure = Manifest.requires_chi_failure(@manifest.requires_chi, Samagotchi::VERSION))
           @warnings << "Plugin #{plugin[:file]} won't load: #{failure}"
@@ -243,9 +250,9 @@ module Samagotchi
       def install_scripts
         scripts = @manifest&.scripts || {}
         scripts.each_key do |file|
-          next if File.file?(File.join(@bundle_dir, "scripts", file))
-
-          raise Installer::InstallError, "the manifest names scripts/#{file}, which the bundle doesn't have"
+          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)
         end
         return {} if @dry_run
 
@@ -274,6 +281,28 @@ module Samagotchi
         end
       end
 
+      # Whether the bundle file +src+ reads through a symlink: it is one, or
+      # it (or its dir, hooks/ say) resolves outside the bundle dir. A tar,
+      # zip or git repo keeps links; copying through one would install any
+      # file the user can read. MemoryFiles skips linked memories the same
+      # way.
+      def linked?(src)
+        return true if File.symlink?(src)
+
+        root = File.realpath(@bundle_dir)
+        !File.realpath(src).start_with?("#{root}/")
+      rescue SystemCallError
+        true
+      end
+
+      # linked? with a "<label> is a symlink (not installed)" warning.
+      def linked_out?(src, label)
+        return false unless linked?(src)
+
+        @warnings << "#{label} is a symlink (not installed)"
+        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.

data/lib/samagotchi/memory_bundle/builder.rb

@@ -398,11 +398,10 @@ module Samagotchi
           raise BuildError, "Output file already exists: #{out_path} — remove it or choose different --out"
         end
 
-        # Use zip CLI like source.rb does with unzip
-        Dir.chdir(staging) do
-          result = system("zip", "-r", out_path, ".")
-          raise BuildError, "zip failed for #{out_path} (is zip installed?)" unless result && File.exist?(out_path)
-        end
+        # Use zip CLI like source.rb does with unzip. It runs in the staging
+        # dir (chdir:): Dir.chdir would move the whole process.
+        result = system("zip", "-r", out_path, ".", chdir: staging)
+        raise BuildError, "zip failed for #{out_path} (is zip installed?)" unless result && File.exist?(out_path)
       end
 
       def tar_staging(staging, out_path, format)
@@ -411,15 +410,13 @@ module Samagotchi
           raise BuildError, "Output file already exists: #{out_path} — remove it or choose different --out"
         end
 
-        # Use tar CLI
-        Dir.chdir(staging) do
-          cmd = case format
-                when :tar_gz, :tgz then ["tar", "-czf", out_path, "."]
-                when :tar then ["tar", "-cf", out_path, "."]
-                end
-          result = system(*cmd)
-          raise BuildError, "tar failed for #{out_path}" unless result && File.exist?(out_path)
-        end
+        # Use tar CLI, in the staging dir (chdir:, as zip_staging).
+        cmd = case format
+              when :tar_gz, :tgz then ["tar", "-czf", out_path, "."]
+              when :tar then ["tar", "-cf", out_path, "."]
+              end
+        result = system(*cmd, chdir: staging)
+        raise BuildError, "tar failed for #{out_path}" unless result && File.exist?(out_path)
       end
     end
   end

data/lib/samagotchi/memory_bundle/installer.rb

@@ -11,6 +11,7 @@ require_relative "index_updater"
 require_relative "merger"
 require_relative "trash"
 require_relative "asset_installer"
+require_relative "memory_files"
 require_relative "../bundle_needs"
 require_relative "../model_overlay"
 
@@ -33,8 +34,16 @@ module Samagotchi
 
       attr_reader :results, :warnings, :placeholder_warnings, :conflicts
 
-      def initialize(source:, name:, scope: nil, force: false, strict: true, upgrade: false, dry_run: false)
+      # 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
+      # installs from a dir in it only, unless force); ShippedUpdate,
+      # Profile and SystemBundle pass the one they install from.
+      def initialize(source:, name:, scope: nil, force: false, strict: true, upgrade: false, dry_run: false, prepared: nil,
+                     shipped_dir: SourceNormalizer::SHIPPED_DIR)
         @source = source
+        @shipped_dir = shipped_dir
+        @prepared = prepared
         @name = name
         @scope = scope&.to_s&.strip&.downcase || ""
         @force = force
@@ -49,6 +58,10 @@ module Samagotchi
         @trash = Trash.new(name)
       end
 
+      # [recorded source, this source] when an upgrade switches the bundle's
+      # source (Installer#check_source), else nil.
+      attr_reader :source_change
+
       # Where an upgrade moved the files the bundle no longer ships (nil:
       # none moved).
       def trash_dir = @trash.dir
@@ -77,6 +90,7 @@ module Samagotchi
         @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.
         @reinstall = @existing && !@upgrade && !@force && !@dry_run
         install_memories
@@ -113,6 +127,7 @@ module Samagotchi
 
       def summary
         lines = []
+        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
@@ -141,12 +156,90 @@ module Samagotchi
 
       private
 
+      # 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
+      # #ref; a path resolved); one it can't place (an older record's
+      # relative path) never refuses.
+      #   - a name chi ships comes from a shipped dir only, unless --force
+      #     (install and upgrade): the plugin and hooks it replaces are chi's;
+      #   - a plain install over a bundle from another source is refused,
+      #     --force too (that overwrites files, it doesn't switch sources):
+      #     it would delete the plugin and hooks and rewrite the record;
+      #   - an upgrade may switch sources (a URL and a local copy of it are
+      #     one bundle, an archive's file name has its version), and
+      #     #source_change says so (the summary's first line).
+      def check_source
+        refuse_case_twin
+        refuse_shipped_name
+        now = incoming_identity
+        return if now.nil?
+
+        was = @existing && SourceIdentity.of(@existing.source)
+        return if was.nil? || was == now
+        return @source_change = [@existing.source, @source.to_s] if @upgrade
+
+        raise InstallError, "#{@name} is installed from #{@existing.source}; `chi bundle upgrade #{@source}` " \
+                            "switches its source, or `chi bundle uninstall #{@name}` first"
+      end
+
+      # A name that differs from an installed bundle's only in case is that
+      # bundle's dir on a case-insensitive file system (macOS): BTW would
+      # replace btw. Refused, --force too.
+      def refuse_case_twin
+        twin, = Provenance.each_installed.find { |name, _| name != @name && name.casecmp?(@name) }
+        raise InstallError, "#{@name} differs only in case from the installed #{twin}" if twin
+      end
+
+      # A shipped name (in any case) from anything but this chi's own
+      # shipped dir. A recorded source may be an older gem's (SourceIdentity
+      # matches the path); an incoming one must be a dir in SHIPPED_DIR, so
+      # a fork's lib/samagotchi/bundles/btw isn't chi's.
+      def refuse_shipped_name
+        return if @force || chi_copy?(@source)
+
+        shipped = shipped_names.find { |name| name.casecmp?(@name) }
+        return unless shipped
+
+        what = shipped == @name ? "#{@name} is a bundle shipped with chi" : "#{@name} is #{shipped}, a bundle shipped with chi"
+        raise InstallError, "#{what}; #{@source} isn't chi's copy of it (--force to install it anyway)"
+      end
+
+      # This source's SourceIdentity; one that looks shipped by its path (a
+      # fork's lib/samagotchi/bundles/btw) but isn't a dir in the shipped
+      # dir is its path, so it isn't taken for chi's btw. A recorded source
+      # keeps the path match (older gems).
+      def incoming_identity
+        identity = SourceIdentity.of(@source)
+        identity&.shipped? && !chi_copy?(@source) ? SourceIdentity.path(@source) : identity
+      end
+
+      # Whether +source+ is a dir in the shipped dir.
+      def chi_copy?(source)
+        path = File.realpath(source.to_s)
+        File.directory?(path) && File.dirname(path) == File.realpath(@shipped_dir)
+      rescue SystemCallError
+        false
+      end
+
+      # The names of the bundles shipped with chi (their manifests'),
+      # samagotchi-system and profiles included.
+      def shipped_names
+        Dir.glob(File.join(@shipped_dir, "*", "manifest.yml")).filter_map do |path|
+          Manifest.read(dir: File.dirname(path)).name
+        rescue Manifest::ValidationError
+          nil
+        end
+      end
+
       # The source normalized to a dir (@bundle_dir; an owned one, extracted
       # from git/zip/tar, is cleaned up after #run) and its manifest.yml
       # (@manifest, nil when it has none and the install isn't strict).
       def load_source
-        @bundle_dir, @source_owned, @source_commit = SourceNormalizer.normalize(@source)
-        @source_dir = @bundle_dir
+        prepared = @prepared || PreparedSource.prepare(@source)
+        @bundle_dir = @source_dir = prepared.dir
+        @source_owned = prepared.owned
+        @source_commit = prepared.commit
         @manifest = Manifest.read(dir: @bundle_dir)
       rescue SourceNormalizer::UnknownSourceError => e
         raise InstallError, "Source normalization failed: #{e.message}"
@@ -167,7 +260,8 @@ module Samagotchi
         [scope, dir]
       end
 
-      # Copies the bundle's *.md files into the target dir and refreshes
+      # Copies the bundle's memories (MemoryFiles: the files: list, else
+      # every *.md but README and the like) into the target dir and refreshes
       # their index lines: an upgrade merges (merge_memory), a dry run only
       # classifies (preview_memory), a plain install writes the new ones.
       # Sets @bundle_md (every file the bundle ships) and @owned: the bundle
@@ -178,8 +272,10 @@ module Samagotchi
         owned_before = @existing ? @existing.files.keys : []
         @bundle_md = []
         @owned = []
-        Dir.glob(File.join(@bundle_dir, "*.md")).each do |file_path|
-          file_key = File.basename(file_path)
+        warn_unshipped_files
+        warn_symlinked_files
+        memory_files.each do |file_key|
+          file_path = File.join(@bundle_dir, file_key)
           @bundle_md << file_key
           note_overlay(file_key, @target_dir)
           target_path = File.join(@target_dir, file_key)
@@ -206,6 +302,22 @@ module Samagotchi
         end
       end
 
+      # The bundle's memories' basenames (MemoryFiles.select), once.
+      def memory_files
+        @memory_files ||= MemoryFiles.select(@bundle_dir, @manifest)
+      end
+
+      # A files: entry with no such *.md in the bundle installs nothing.
+      def warn_unshipped_files
+        missing = MemoryFiles.unshipped(@bundle_dir, @manifest)
+        @warnings << "files: names #{missing.join(", ")}, which the bundle doesn't ship (not installed)" unless missing.empty?
+      end
+
+      # A memory that is a symlink isn't installed (MemoryFiles.symlinks).
+      def warn_symlinked_files
+        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.
@@ -342,13 +454,32 @@ module Samagotchi
       # for a local edit: keep the installed base, so the next upgrade still
       # sees the edit (not a fast-forward over it).
       def install_provenance_files
-        @owned.each_with_object({}) do |file_key, files|
+        files = @owned.each_with_object({}) do |file_key, map|
           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)
-          files[file_key] = kept ? base_path : target_path
+          map[file_key] = kept ? base_path : target_path
+        end
+        files.merge(dropped_owned_files)
+      end
+
+      # file key => its base, for each file an earlier install owned that
+      # this version doesn't ship and that is still on disk. A plain
+      # install leaves such a file where it is, and keeps its record, so the
+      # upgrade the summary points at still moves it to the trash
+      # (prune_dropped_files); dropping the record orphaned it as a memory.
+      def dropped_owned_files
+        return {} unless @existing
+
+        @existing.files.each_key.with_object({}) do |key, files|
+          file_key = key.to_s
+          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)
         end
       end
 
@@ -431,7 +562,7 @@ module Samagotchi
       # An overlay-looking name with no base anywhere is an overlay too,
       # with a warning (a dry run warns as well).
       def note_overlay(file_key, target_dir)
-        @bundle_files ||= Dir.glob(File.join(@bundle_dir, "*.md")).map { |f| File.basename(f) }
+        @bundle_files ||= memory_files
         return unless ModelOverlay.bundle_overlay?(file_key, bundle_files: @bundle_files, target_dir: target_dir)
 
         @overlays << file_key

data/lib/samagotchi/memory_bundle/manifest.rb

@@ -64,8 +64,13 @@ module Samagotchi
 
       def initialize(path:)
         @path = path
-        raw = YAML.load_file(path) || {}
+        raw = load_mapping(path)
         @name     = require_str(raw, "name")
+        # The name is a directory under .bundles/: never a path.
+        if @name.match?(%r{[/\\\0]}) || %w[. ..].include?(@name)
+          raise ValidationError, "name: #{@name.inspect} is not a bundle name (no path separators, not . or ..)"
+        end
+
         @version  = require_str(raw, "version")
         @scope    = normalize_scope(raw["scope"])
         @description = (raw["description"] || "").to_s
@@ -188,6 +193,20 @@ module Samagotchi
 
       private
 
+      # 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.
+      def load_mapping(path)
+        raw = YAML.load_file(path) || {}
+        raise ValidationError, "manifest.yml is not a YAML mapping in #{File.dirname(path)}" unless raw.is_a?(Hash)
+
+        raw
+      rescue Psych::SyntaxError => e
+        raise ValidationError, "manifest.yml is not valid YAML in #{File.dirname(path)}: line #{e.line}, column #{e.column}: #{e.problem}"
+      rescue Psych::Exception => e
+        raise ValidationError, "manifest.yml is not valid YAML in #{File.dirname(path)}: #{e.message}"
+      end
+
       def require_str(hash, key)
         val = hash[key]
         return val if val.is_a?(String) && !val.empty?

data/lib/samagotchi/memory_bundle/memory_files.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module MemoryBundle
+    # Which of a bundle dir's top-level *.md files are its memories (the
+    # ones an install copies into the scope dir, docs/memory.md):
+    #   - a manifest whose files: lists any: exactly those (that exist);
+    #   - else (no manifest, no files: key, or files: {}): every *.md but a
+    #     repo's meta files (README, CHANGELOG, LICENSE, ...), so a bundle
+    #     kept in its own git repo doesn't install its README as a memory.
+    # A listed file is installed whatever its name: `chi bundle build` of
+    # a user's own security.md lists it, and it is a memory.
+    # files: {} means "no list" rather than "no memories": shipped bundles
+    # with nothing to install write it (mcp), and an external bundle that
+    # left the map empty installed its *.md before this rule.
+    # A symlink is never a memory (.symlinks names the ones skipped): a
+    # tar, zip or git repo keeps links, and copying through one would put
+    # any file the user can read (~/.ssh/..., an API key) into a memory.
+    module MemoryFiles
+      # A repo's meta files, by name without extension (case-insensitive).
+      REPO_META = %w[readme changelog license licence contributing code_of_conduct security].freeze
+      META_EXTENSIONS = %w[.md .markdown .txt].freeze
+
+      module_function
+
+      # @return [Array<String>] the memories' basenames, sorted
+      def select(bundle_dir, manifest)
+        candidates(bundle_dir, manifest).reject { |name| File.symlink?(File.join(bundle_dir, name)) }
+      end
+
+      # The memories .select leaves out because they are symlinks, sorted.
+      def symlinks(bundle_dir, manifest)
+        candidates(bundle_dir, manifest).select { |name| File.symlink?(File.join(bundle_dir, name)) }
+      end
+
+      # The files: entries that name no top-level *.md of the bundle (a
+      # symlink is in .symlinks, not here).
+      def unshipped(bundle_dir, manifest)
+        listed = manifest&.files&.keys || []
+        listed.reject do |name|
+          path = File.join(bundle_dir, name)
+          name.end_with?(".md") && !name.include?("/") && (File.symlink?(path) || File.file?(path))
+        end
+      end
+
+      # The top-level *.md files the rules above pick, symlinks included.
+      def candidates(bundle_dir, manifest)
+        present = Dir.glob(File.join(bundle_dir, "*.md")).map { |f| File.basename(f) }.sort
+        listed = manifest&.files&.keys
+        return present & listed if listed && !listed.empty?
+
+        present.reject { |name| repo_meta?(name) }
+      end
+      private_class_method :candidates
+
+      # Whether +name+ is a repo's meta file: README, README.md,
+      # readme.markdown, LICENSE.txt, ...
+      def repo_meta?(name)
+        base = name.downcase
+        ext = META_EXTENSIONS.find { |e| base.end_with?(e) }
+        REPO_META.include?(ext ? base.delete_suffix(ext) : base)
+      end
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/profile.rb

@@ -109,7 +109,7 @@ module Samagotchi
         return result.skipped[member] = failure if failure
         return result.installed << member if dry_run
 
-        Installer.new(source: member_dir, name: member, scope: "system", force: force, strict: true).run
+        Installer.new(source: member_dir, name: member, scope: "system", force: force, strict: true, shipped_dir: shipped_dir).run
         result.installed << member
       rescue StandardError => e
         result.failed[member] = e.message.lines.first.to_s.strip

data/lib/samagotchi/memory_bundle/shipped_update.rb

@@ -65,7 +65,8 @@ module Samagotchi
           next row unless row.status == :would_update
           next apply_profile(row) if row.adds
 
-          installer = Installer.new(source: row.source_dir, name: row.name, scope: row.scope, strict: true, upgrade: true)
+          installer = Installer.new(source: row.source_dir, name: row.name, scope: row.scope, strict: true, upgrade: true,
+                                    shipped_dir: File.dirname(row.source_dir))
           installer.run
           row.dup.tap do |r|
             r.status = :updated

data/lib/samagotchi/memory_bundle/source.rb

@@ -50,6 +50,10 @@ module Samagotchi
         return nil unless name.match?(/\A[A-Za-z0-9][A-Za-z0-9_-]*\z/)
         return nil if File.exist?(File.join(cwd, name))
 
+        # Dir.children, not File.file? alone: the name in its exact case
+        # (a case-insensitive file system finds btw's dir for BTW).
+        return nil unless File.directory?(SHIPPED_DIR) && Dir.children(SHIPPED_DIR).include?(name)
+
         dir = File.join(SHIPPED_DIR, name)
         File.file?(File.join(dir, "manifest.yml")) ? dir : nil
       end
@@ -128,6 +132,9 @@ module Samagotchi
       # Copies the contents of `src_dir` into a new permanent directory, stripping
       # one level of nesting if there's a single top-level entry.
       # The returned path survives after `src_dir` is cleaned up.
+      # A symlink stays a symlink, at the top level too (cp_r dereferences
+      # its root by default): the Installer then skips it (MemoryFiles,
+      # AssetInstaller#linked?) instead of installing what it points at.
       def self.clean_copy_of(src_dir)
         contents = Dir.entries(src_dir).reject { |e| e.start_with?(".") }
         # Zip-slip check: reject entries with ".." path components.
@@ -139,21 +146,77 @@ module Samagotchi
 
         if contents.size == 1
           entry_path = File.join(src_dir, contents.first)
-          if File.directory?(entry_path) && !Dir.empty?(entry_path)
+          if File.directory?(entry_path) && !File.symlink?(entry_path) && !Dir.empty?(entry_path)
             dst = Dir.mktmpdir("samagotchi-bundle-")
-            FileUtils.cp_r("#{entry_path}/.", dst)
+            FileUtils.cp_r("#{entry_path}/.", dst, dereference_root: false)
             return [dst, true]
           end
         end
 
         dst = Dir.mktmpdir("samagotchi-bundle-")
         contents.each do |entry|
-          FileUtils.cp_r(File.join(src_dir, entry), dst)
+          FileUtils.cp_r(File.join(src_dir, entry), dst, dereference_root: false)
         end
         [dst, true]
       end
 
       private_class_method :normalize_zip, :normalize_tar, :clean_copy_of
     end
+
+    # What a bundle's source is, for telling whether two installs of one
+    # name come from the same place (Installer: a bundle from elsewhere
+    # doesn't silently replace an installed one). key is
+    #   shipped:<dir>  a shipped dir (SHIPPED_SOURCE), in any gem or checkout,
+    #                  so `chi update` and a newer chi upgrade it
+    #   git:<url>      a git URL without its #ref, a trailing / or .git
+    #   path:<path>    an absolute path, symlinks resolved when it exists
+    # .of is nil for a source it can't place (empty, or a relative path an
+    # older record may hold): unknown never refuses.
+    SourceIdentity = Data.define(:key) do
+      def self.of(source)
+        s = source.to_s.strip
+        return nil if s.empty?
+
+        if SourceNormalizer.git_url?(s)
+          url = SourceNormalizer.strip_git_ref(s).first.sub(%r{/+\z}, "").delete_suffix(".git")
+          new(key: "git:#{url}")
+        elsif s.match?(SourceNormalizer::SHIPPED_SOURCE)
+          new(key: "shipped:#{File.basename(s.chomp("/"))}")
+        elsif s.start_with?("/")
+          new(key: "path:#{real(s)}")
+        end
+      end
+
+      # +source+ as a path:<realpath>, whatever it looks like.
+      def self.path(source) = new(key: "path:#{real(source.to_s)}")
+
+      def self.real(path)
+        File.realpath(path)
+      rescue SystemCallError
+        File.expand_path(path)
+      end
+      private_class_method :real
+
+      def shipped? = key.start_with?("shipped:")
+
+      def to_s = key
+    end
+
+    # A source normalized once to a local dir (SourceNormalizer.normalize):
+    # owned when it is a git clone or a zip/tar extract, which #cleanup
+    # removes; commit is a git clone's HEAD (nil otherwise). BundleCommand
+    # reads the bundle's name from it and the Installer installs from it, so
+    # a source is cloned or extracted once per command.
+    PreparedSource = Data.define(:dir, :owned, :commit) do
+      # @raise [SourceNormalizer::UnknownSourceError]
+      def self.prepare(source)
+        dir, owned, commit = SourceNormalizer.normalize(source)
+        new(dir: dir, owned: owned, commit: commit)
+      end
+
+      def cleanup
+        SourceNormalizer.cleanup(dir) if owned
+      end
+    end
   end
 end

data/lib/samagotchi/memory_bundle/system_bundle.rb

@@ -141,7 +141,8 @@ module Samagotchi
           name: BUNDLE_NAME,
           scope: SCOPE,
           force: false,
-          strict: true
+          strict: true,
+          shipped_dir: File.dirname(GEM_BUNDLE_DIR)
         )
         installer.run
         result(:installed, to: to, warnings: installer.warnings)
@@ -182,7 +183,8 @@ module Samagotchi
       end
 
       def upgrade_installer
-        Installer.new(source: GEM_BUNDLE_DIR, name: BUNDLE_NAME, scope: SCOPE, force: false, strict: true, upgrade: true)
+        Installer.new(source: GEM_BUNDLE_DIR, name: BUNDLE_NAME, scope: SCOPE, force: false, strict: true, upgrade: true,
+                      shipped_dir: File.dirname(GEM_BUNDLE_DIR))
       end
       private_class_method :with_lock, :note_newer_installed, :install_fresh, :upgrade_existing, :verify_files_present,
                            :upgrade_installer, :result, :conflicting

data/lib/samagotchi/model_price.rb

@@ -37,9 +37,10 @@ module Samagotchi
     # USD for one generation, OpenAI usage semantics: +prompt_tokens+ holds
     # the cached reads and the cache writes (OpenRouter keeps that for
     # Anthropic models), and reasoning is inside +completion_tokens+.
-    # llama.cpp's native timings.prompt_n leaves its cache_n out, so the
-    # uncached part is clamped at 0: an undercount, harmless because priced
-    # models are remote.
+    # llama.cpp's native stream ends with tokens_evaluated, the whole prompt
+    # (SessionMetrics keeps the largest count, so not timings.prompt_n,
+    # which leaves cache_n out); the uncached part is clamped at 0 for a
+    # report that has prompt_n alone.
     def cost(prompt_tokens:, cached_tokens:, cache_write_tokens:, completion_tokens:)
       uncached = (prompt_tokens - cached_tokens - cache_write_tokens).clamp(0..)
       ((uncached * input) + (cached_tokens * cache_read) + (cache_write_tokens * cache_write) +

data/lib/samagotchi/paths.rb

@@ -28,7 +28,21 @@ module Samagotchi
     # @return [String] $XDG_CONFIG_HOME (absolute), else ~/.config
     def config_home(env: ENV)
       xdg = env.fetch("XDG_CONFIG_HOME", "").to_s.strip
-      xdg.empty? ? File.expand_path("~/.config") : File.absolute_path(xdg)
+      xdg.empty? ? File.join(Dir.home, ".config") : File.absolute_path(xdg)
+    end
+
+    # The set XDG dirs, made absolute. +set+ is :nonblank (unset or blank
+    # values omitted) or :key (present keys included, even when blank).
+    # @return [Hash{String => String}]
+    def absolute_xdg(env: ENV, set: :nonblank)
+      included = case set
+                 when :nonblank then ->(key) { !env.fetch(key, "").to_s.strip.empty? }
+                 when :key then ->(key) { env.key?(key) }
+                 else raise ArgumentError, "set must be :nonblank or :key"
+                 end
+      { "XDG_STATE_HOME" => :state_home, "XDG_CONFIG_HOME" => :config_home }.each_with_object({}) do |(key, home), dirs|
+        dirs[key] = public_send(home, env: env) if included.call(key)
+      end
     end
 
     # +path+ as chi shows it: ~ for the home folder (~/a for one in it),

data/lib/samagotchi/session.rb

@@ -91,7 +91,7 @@ module Samagotchi
     # one): see #delegate?.
     attr_writer :delegate
     # The session this one continues (SessionManager.continue_session): the
-    # previous link of a chain, "the next day of the same routine", else
+    # previous link of a chain, "the next run of the same routine", else
     # nil. Not a parent: archiving one link leaves the next alone. The chain
     # itself is derived (SessionChain), never stored.
     attr_accessor :continues