samagotchi 0.2.0

data/lib/samagotchi/memory_bundle/source.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "fileutils"
+require "shellwords"
+
+module Samagotchi
+  module MemoryBundle
+    # Normalizes a source (directory, zip, tar.gz, etc.) into a plain directory of .md files.
+    #
+    # Returns [normalized_path, owned] where:
+    #   - dir sources:  [dir_path, false]  — caller owns the directory, do NOT delete.
+    #   - archive sources: [temp_dir_path, true] — caller must call cleanup(dir).
+    class SourceNormalizer
+      class UnknownSourceError < StandardError; end
+
+      def self.normalize(source_path)
+        return normalize_git(source_path) if git_url?(source_path)
+
+        path = File.expand_path(source_path)
+        raise UnknownSourceError, "source does not exist: #{path}" unless File.exist?(path)
+
+        if File.directory?(path)
+          return [path, false]
+        end
+
+        # Use full lowercase path for compound extensions like .tar.gz
+        lower = path.downcase
+        if lower.end_with?(".zip")
+          normalize_zip(path)
+        elsif lower.end_with?(".tar.gz") || lower.end_with?(".tgz") || lower.end_with?(".tar")
+          normalize_tar(path)
+        else
+          ext = File.extname(path).downcase
+          raise UnknownSourceError, "unsupported source format: #{path} (extension: #{ext})"
+        end
+      end
+
+      # The bundles shipped with chi (lib/samagotchi/bundles/<name>).
+      SHIPPED_DIR = File.expand_path("../bundles", __dir__)
+
+      # A bare name (no path separator) that isn't a path here names a
+      # shipped bundle: `chi bundle install guardrails`. A directory or file
+      # of that name in the cwd wins.
+      # @return [String, nil] the shipped bundle's dir
+      def self.shipped_bundle_dir(source, cwd: Dir.pwd)
+        name = source.to_s.strip
+        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 = File.join(SHIPPED_DIR, name)
+        File.file?(File.join(dir, "manifest.yml")) ? dir : nil
+      end
+
+      def self.git_url?(str)
+        s = str.to_s.strip
+        return false if s.empty?
+        s.match?(%r{\A(?:https?://|git@|ssh://|git://|file://).+})
+      end
+
+      def self.strip_git_ref(url)
+        if url.include?("#")
+          parts = url.split("#", 2)
+          [parts[0], parts[1]]
+        else
+          [url, nil]
+        end
+      end
+
+      def self.normalize_git(git_url)
+        url, ref = strip_git_ref(git_url.strip)
+        Dir.mktmpdir("samagotchi-git-") do |clone_parent|
+          clone_dir = File.join(clone_parent, "repo")
+          args = ["git", "clone", "--depth", "1"]
+          args += ["--branch", ref] if ref && !ref.empty?
+          args += [url, clone_dir]
+          result = system(*args)
+          raise UnknownSourceError, "git clone failed for #{git_url}" unless result && File.directory?(clone_dir)
+          # Capture HEAD commit before stripping .git (audit trail)
+          commit = nil
+          begin
+            commit = `git -C #{clone_dir.shellescape} rev-parse HEAD 2>/dev/null`.strip
+            commit = nil if commit.empty?
+          rescue StandardError
+            commit = nil
+          end
+          # Remove .git to avoid leaking
+          FileUtils.rm_rf(File.join(clone_dir, ".git"))
+          path, owned = clean_copy_of(clone_dir)
+          # Thread commit through via extra return value and class accessor for backward compat
+          @last_git_commit = commit
+          return [path, owned, commit]
+        end
+      end
+
+      class << self
+        attr_accessor :last_git_commit
+
+        def cleanup(dir)
+          FileUtils.rm_rf(dir) if dir && File.directory?(dir)
+        end
+      end
+
+      private
+
+      def self.normalize_zip(zip_path)
+        Dir.mktmpdir("samagotchi-zip-") do |extract_dir|
+          result = system("unzip", "-o", zip_path, "-d", extract_dir)
+          raise UnknownSourceError, "unzip failed for #{zip_path}" unless result
+          clean_copy_of(extract_dir)
+        end
+      end
+
+      def self.normalize_tar(tar_path)
+        Dir.mktmpdir("samagotchi-tar-") do |extract_dir|
+          is_gz = tar_path.end_with?(".tar.gz", ".tgz")
+          cmd = is_gz ? ["tar", "-xzf"] : ["tar", "-xf"]
+          result = system(*cmd, tar_path, "-C", extract_dir)
+          raise UnknownSourceError, "tar extraction failed for #{tar_path}" unless result
+          clean_copy_of(extract_dir)
+        end
+      end
+
+      # 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.
+      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.
+        contents.each do |entry|
+          if entry.include?("..")
+            raise UnknownSourceError, "archive contains unsafe path component: #{entry}"
+          end
+        end
+
+        if contents.size == 1
+          entry_path = File.join(src_dir, contents.first)
+          if File.directory?(entry_path) && !Dir.empty?(entry_path)
+            dst = Dir.mktmpdir("samagotchi-bundle-")
+            FileUtils.cp_r("#{entry_path}/.", dst)
+            return [dst, true]
+          end
+        end
+
+        dst = Dir.mktmpdir("samagotchi-bundle-")
+        contents.each do |entry|
+          FileUtils.cp_r(File.join(src_dir, entry), dst)
+        end
+        [dst, true]
+      end
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/status.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+require "digest"
+require_relative "provenance"
+require_relative "manifest"
+require_relative "../version"
+require_relative "index_updater"
+require_relative "../memory_paths"
+require_relative "../bundle_needs"
+
+module Samagotchi
+  module MemoryBundle
+    module Status
+      def self.bundle_status(name, scope_override: nil)
+        provenance = Provenance.new(name: name)
+        data = provenance.read
+        return nil unless data
+
+        raw_scope = scope_override || data[:scope]&.to_s
+        scope = (raw_scope.nil? || raw_scope.strip.empty?) ? "system" : raw_scope
+        target_dir = resolve_target_dir(scope)
+        files = data[:files] || {}
+        details = {}
+        files.each do |file_key, meta|
+          file_key_str = file_key.to_s
+          target_path = File.join(target_dir, file_key_str)
+          base_path = provenance.base_path(file_key_str)
+          stored_checksum = meta[:checksum] || meta["checksum"]
+          current_checksum = File.exist?(target_path) ? Digest::SHA256.hexdigest(File.read(target_path)) : nil
+          base_checksum = File.exist?(base_path) ? Digest::SHA256.hexdigest(File.read(base_path)) : nil
+          modified = base_checksum && current_checksum && base_checksum != current_checksum
+          missing = !File.exist?(target_path)
+          index_present = index_has_entry?(scope, file_key_str)
+          details[file_key_str] = {
+            stored_checksum: stored_checksum,
+            current_checksum: current_checksum,
+            base_checksum: base_checksum,
+            modified: modified,
+            missing: missing,
+            index_present: index_present,
+            target_path: target_path,
+            base_path: base_path
+          }
+        end
+        { provenance: data, scope: scope, target_dir: target_dir, files: details, plugin: plugin_status(provenance, data),
+          needs: needs_status(data) }
+      end
+
+      # The stored needs, each with found: from this process's PATH (the
+      # shell's; a worker's PATH can differ, see docs/memory.md).
+      def self.needs_status(data, path: ENV["PATH"])
+        Manifest.parse_needs(data[:needs]).map do |need|
+          need.merge(found: BundleNeeds.found?(need[:command], path: path))
+        end
+      rescue Manifest::ValidationError
+        []
+      end
+
+      # "needs gh (reads PRs) [ok]" / "needs gh [not found]: brew install gh"
+      def self.need_line(need)
+        why = need[:why] ? " (#{need[:why]})" : ""
+        state = need[:found] ? "[ok]" : "[not found]"
+        hint = !need[:found] && need[:hint] ? ": #{need[:hint]}" : ""
+        "needs #{need[:command]}#{why} #{state}#{hint}"
+      end
+
+      # The installed plugin: {file:, path:, state:, requires_chi:,
+      # requires_failure:}; state is "ok", "modified" (its sha256 differs
+      # from the installed one: it won't load) or "missing". nil without one.
+      def self.plugin_status(provenance, data)
+        path = provenance.plugin_path(data)
+        return nil unless path
+
+        recorded = data[:plugin][:sha256].to_s.delete_prefix("sha256:")
+        state = if !File.file?(path) then "missing"
+                elsif Digest::SHA256.hexdigest(File.binread(path)) == recorded then "ok"
+                else "modified"
+                end
+        { file: File.basename(path), path: path, state: state, requires_chi: data[:requires_chi],
+          requires_failure: Manifest.requires_chi_failure(data[:requires_chi], Samagotchi::VERSION) }
+      end
+
+      def self.resolve_target_dir(scope)
+        case scope
+        when "system"
+          Samagotchi::MemoryBundle::Installer.system_dir
+        when "project"
+          base = Samagotchi::MemoryBundle::Installer.project_dir_base
+          # If override set via Installer, use it; else compute hash
+          if Samagotchi::MemoryBundle::Installer.project_dir_base_override
+            base
+          else
+            File.join(base, MemoryPaths.project_key)
+          end
+        else
+          Samagotchi::MemoryBundle::Installer.system_dir
+        end
+      end
+
+      def self.index_has_entry?(scope, file_key)
+        path = IndexUpdater.index_path_for(scope)
+        return false unless path && File.exist?(path)
+        content = File.read(path)
+        content.match?(IndexUpdater.managed_pattern(file_key))
+      end
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/system_bundle.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "installer"
+require_relative "provenance"
+require_relative "manifest"
+require_relative "../log"
+
+module Samagotchi
+  module MemoryBundle
+    # Manages the built-in "samagotchi-system" bundle shipped inside the gem.
+    #
+    # The bundle lives at lib/samagotchi/bundles/system/ (manifest.yml + *.md)
+    # and is lazily installed into the user's system memories directory
+    # (~/.config/samagotchi/memories) on first Engine creation.
+    #
+    # A newer shipped version (manifest.yml) triggers a 3-way upgrade:
+    # fast-forward when not edited, keep when bundle unchanged, conflict keeps
+    # local edit with a warning. An older shipped version is left alone, so an
+    # old checkout never downgrades the installed bundle; it says so once.
+    module SystemBundle
+      BUNDLE_NAME = "samagotchi-system"
+      SCOPE = "system"
+      SKIP_ENV = "SAMAGOTCHI_SKIP_SYSTEM_BUNDLE"
+      GEM_BUNDLE_DIR = File.expand_path("../bundles/system", __dir__)
+      NOTED_FILE = "older_shipped_noted"
+
+      module_function
+
+      # Ensure the system bundle is installed and up-to-date.
+      # Idempotent and warn-only: never raises to callers.
+      # Safe for TUI and non-TUI (web/worker) paths — Engine calls this.
+      def ensure!
+        return false if skip?
+        return false unless File.directory?(GEM_BUNDLE_DIR)
+
+        begin
+          gem_manifest = Manifest.read(dir: GEM_BUNDLE_DIR)
+        rescue Manifest::ValidationError => e
+          Log.error(:memory, "system_manifest_invalid", echo: "[samagotchi-system] invalid gem manifest: #{e.message}")
+          return false
+        end
+
+        with_lock do
+          data = Provenance.new(name: BUNDLE_NAME).read
+
+          if data.nil?
+            install_fresh(gem_manifest)
+          elsif installed_newer?(data[:version], gem_manifest.version)
+            # Running an older checkout/gem: never downgrade the user's system memories
+            # (not even to restore a missing file). `chi self` shows installed vs shipped.
+            note_newer_installed(data[:version], gem_manifest.version)
+            false
+          elsif data[:version].to_s != gem_manifest.version.to_s
+            upgrade_existing(gem_manifest, data)
+          else
+            # Already at desired version — still verify files present (e.g. user deleted one)
+            verify_files_present(gem_manifest, data)
+          end
+        end
+      rescue StandardError => e
+        Log.error(:memory, "system_bundle_failed", echo: "[samagotchi-system] ensure failed: #{e.class}: #{e.message}", error: e.class.name)
+        false
+      end
+
+      # Parallel chi starts on one config dir take turns: the second one reads
+      # the provenance the first one wrote, instead of installing over it and
+      # warning "Skipped … already exists" for every file.
+      def with_lock
+        dir = Provenance.bundles_dir
+        FileUtils.mkdir_p(dir)
+        File.open(File.join(dir, "#{BUNDLE_NAME}.lock"), File::RDWR | File::CREAT, 0o644) do |f|
+          f.flock(File::LOCK_EX)
+          yield
+        end
+      end
+
+      def skip?
+        val = ENV[SKIP_ENV].to_s.strip.downcase
+        val == "1" || val == "true"
+      end
+
+      # Unparseable versions fall back to the old "any difference upgrades" behaviour.
+      def installed_newer?(installed, shipped)
+        installed, shipped = installed.to_s, shipped.to_s
+        return false unless Gem::Version.correct?(installed) && Gem::Version.correct?(shipped)
+
+        Gem::Version.new(installed) > Gem::Version.new(shipped)
+      end
+
+      # One line per installed/shipped pair, so an old worktree (and each of its
+      # workers) says it once instead of on every start. The pairs already noted
+      # sit in the bundle's provenance dir; ensure! holds the lock here.
+      def note_newer_installed(installed, shipped)
+        pair = "#{installed} #{shipped}"
+        path = File.join(Provenance.new(name: BUNDLE_NAME).bundle_dir, NOTED_FILE)
+        noted = File.exist?(path) ? File.readlines(path, chomp: true) : []
+        return if noted.include?(pair)
+
+        Log.warn(:memory, "system_bundle_newer", echo: "[samagotchi-system] installed system bundle #{installed} is newer than this chi's #{shipped}; left as is", installed: installed.to_s, shipped: shipped.to_s)
+        File.write(path, "#{pair}\n", mode: "a")
+      end
+
+      def install_fresh(gem_manifest)
+        installer = Installer.new(
+          source: GEM_BUNDLE_DIR,
+          name: BUNDLE_NAME,
+          scope: SCOPE,
+          force: false,
+          strict: true
+        )
+        _nd, _manifest = installer.run
+        unless installer.warnings.empty?
+          installer.warnings.each { |w| Log.warn(:memory, "system_bundle_warning", echo: "[samagotchi-system] #{w}") }
+        end
+        true
+      end
+
+      def upgrade_existing(gem_manifest, _existing_data)
+        installer = Installer.new(
+          source: GEM_BUNDLE_DIR,
+          name: BUNDLE_NAME,
+          scope: SCOPE,
+          force: false,
+          strict: true,
+          upgrade: true
+        )
+        _nd, _manifest = installer.run
+        # Installer already handled fast_forward/keep/noop. Conflicts are kept with warning.
+        if installer.conflicts.any?
+          installer.conflicts.each do |file_key, _info|
+            Log.info(:memory, "system_local_edit_kept", echo: "[samagotchi-system] kept local edit in #{file_key} (bundle v#{gem_manifest.version} has update — run: chi bundle status #{BUNDLE_NAME} / chi bundle diff #{BUNDLE_NAME} #{file_key})", file: file_key.to_s)
+          end
+        end
+        installer.warnings.each { |w| Log.warn(:memory, "system_bundle_warning", echo: "[samagotchi-system] #{w}") } unless installer.warnings.empty?
+        true
+      end
+
+      def verify_files_present(gem_manifest, data)
+        # If any file from the bundle is missing on disk but provenance says it should exist,
+        # reinstall that file via Installer (which will classify as :install). This handles
+        # accidental user deletion without forcing a full reinstall.
+        target_dir = Installer.system_dir
+        missing = gem_manifest.files.keys.any? { |k| !File.exist?(File.join(target_dir, k)) }
+        return false unless missing
+
+        installer = Installer.new(
+          source: GEM_BUNDLE_DIR,
+          name: BUNDLE_NAME,
+          scope: SCOPE,
+          force: false,
+          strict: true,
+          upgrade: true
+        )
+        _nd, _manifest = installer.run
+        true
+      end
+      private_class_method :with_lock, :note_newer_installed, :install_fresh, :upgrade_existing, :verify_files_present
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/uninstaller.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+require "fileutils"
+require "digest"
+require_relative "../memory_paths"
+require_relative "provenance"
+require_relative "index_updater"
+require_relative "merger"
+
+module Samagotchi
+  module MemoryBundle
+    class Uninstaller
+      class UninstallError < StandardError; end
+
+      attr_reader :warnings, :removed_files
+
+      class << self
+        attr_accessor :system_dir_override, :project_dir_base_override
+        def system_dir
+          system_dir_override || MemoryPaths.system_dir
+        end
+        def project_dir_base
+          project_dir_base_override || MemoryPaths.projects_dir
+        end
+      end
+
+      def initialize(name:, scope: nil, force: false)
+        @name = name
+        @scope = scope&.to_s&.strip&.downcase
+        @force = force
+        @warnings = []
+        @removed_files = []
+        IndexUpdater.system_dir_override = self.class.system_dir_override
+        IndexUpdater.project_dir_base_override = self.class.project_dir_base_override
+      end
+
+      def run
+        provenance = Provenance.new(name: @name)
+        data = provenance.read
+        raise UninstallError, "Bundle '#{@name}' is not installed" unless data
+
+        # Determine scope from flag or provenance
+        cli_scope = @scope.to_s.strip.empty? ? nil : @scope
+        raw = cli_scope || data[:scope]&.to_s
+        target_scope = (raw.nil? || raw.strip.empty?) ? "system" : raw
+        target_dir = resolve_target_dir(target_scope)
+
+        files = data[:files] || {}
+        hooks = data[:hooks] || {}
+        if files.empty? && hooks.empty?
+          # No file list, just remove provenance
+          FileUtils.rm_rf(provenance.bundle_dir)
+          return true
+        end
+
+        blocked = []
+        files.each do |file_key, meta|
+          file_key_str = file_key.to_s
+          target_path = File.join(target_dir, file_key_str)
+          base_path = provenance.base_path(file_key_str)
+          next unless File.exist?(target_path)
+          if !@force && File.exist?(base_path) && Merger.current_modified?(base_path, target_path)
+            blocked << file_key_str
+            @warnings << "Skipped #{file_key_str}: local edits detected (use --force to remove)"
+          end
+        end
+
+        raise UninstallError, "Uninstall blocked: #{blocked.join(', ')} has local edits (use --force)" if blocked.any?
+
+        files.each do |file_key, _meta|
+          file_key_str = file_key.to_s
+          target_path = File.join(target_dir, file_key_str)
+          if File.exist?(target_path)
+            FileUtils.rm_f(target_path)
+            @removed_files << file_key_str
+          end
+          # Remove index line
+          begin
+            IndexUpdater.remove_index(target_scope, file_key_str.delete_suffix(".md"))
+            IndexUpdater.remove_index(target_scope, file_key_str) # legacy "name.md" line
+          rescue => _e
+          end
+        end
+
+        # ── Hooks removal (bundle-owned) ──────────────────────────
+        # Hooks are stored under <bundle_dir>/hooks/ and are not part of the index.
+        # Explicit removal for intent; the final rm_rf sweeps it anyway.
+        if hooks.is_a?(Hash) && !hooks.empty?
+          hooks_dir = provenance.hooks_dir
+          hooks.each do |hook_key, _meta|
+            hook_key_str = hook_key.to_s
+            hook_path = File.join(hooks_dir, hook_key_str)
+            if File.exist?(hook_path)
+              FileUtils.rm_f(hook_path)
+              @removed_files << "hooks/#{hook_key_str}"
+            end
+          end
+          # Remove hooks dir if empty, else rm_rf will clean
+          FileUtils.rm_rf(hooks_dir) if Dir.exist?(hooks_dir)
+        else
+          # Ensure stale hooks dir removed even if provenance has no hooks map but dir exists
+          FileUtils.rm_rf(provenance.hooks_dir) if Dir.exist?(provenance.hooks_dir)
+        end
+
+        plugin_path = provenance.plugin_path(data)
+        @removed_files << "plugin/#{File.basename(plugin_path)}" if plugin_path && File.exist?(plugin_path)
+        FileUtils.rm_rf(provenance.bundle_dir)
+        true
+      end
+
+      private
+
+      def resolve_target_dir(scope)
+        case scope
+        when "system", ""
+          self.class.system_dir
+        when "project"
+          if self.class.project_dir_base_override
+            self.class.project_dir_base
+          else
+            File.join(self.class.project_dir_base, MemoryPaths.project_key)
+          end
+        else
+          raise UninstallError, "invalid scope: #{scope}"
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/memory_bundle.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+require_relative "memory_bundle/manifest"
+require_relative "memory_bundle/source"
+require_relative "memory_bundle/provenance"
+require_relative "memory_bundle/placeholder"
+require_relative "memory_bundle/index_updater"
+require_relative "memory_bundle/merger"
+require_relative "memory_bundle/installer"
+require_relative "memory_bundle/uninstaller"
+require_relative "memory_bundle/status"
+require_relative "memory_bundle/system_bundle"
+require_relative "memory_bundle/builder"
+require_relative "memory_bundle/listing"
+module Samagotchi
+  # Namespace for shareable memory bundle functionality.
+  module MemoryBundle; end
+end

data/lib/samagotchi/memory_paths.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "config"
+
+module Samagotchi
+  # Where memories live: <config dir>/memories, i.e. $XDG_CONFIG_HOME/samagotchi/memories
+  # or ~/.config/samagotchi/memories. Resolved on every call, like
+  # ConfigFile.global_path, so an XDG_CONFIG_HOME set after load (specs, smoke runs,
+  # a fixture chi) moves memories together with config.yml.
+  #
+  # Project memories are keyed by the project root (see project_root), so every
+  # worktree and subdirectory of one git repository shares one folder.
+  module MemoryPaths
+    module_function
+
+    def system_dir(env: ENV)
+      File.join(ConfigFile.config_dir(env: env), "memories")
+    end
+
+    def projects_dir(env: ENV)
+      File.join(system_dir(env: env), "projects")
+    end
+
+    # One folder per project root: basename + 8 hex chars of MD5(full root path).
+    def project_key(cwd = Dir.pwd)
+      root = project_root(cwd)
+      "#{File.basename(root)}_#{Digest::MD5.hexdigest(root)[0..7]}"
+    end
+
+    # The repository's common git directory identifies the project; every linked
+    # worktree shares it. Returns the checkout holding it when it is named .git,
+    # otherwise the git dir itself (a bare repo, a proj/.bare layout,
+    # --separate-git-dir, a submodule's .git/modules/<name>), so for those layouts
+    # the "project root" is a git dir, not a checkout. Outside any repository the
+    # root is cwd. No git subprocess: at most two small files are read.
+    def project_root(cwd = Dir.pwd)
+      dot_git = find_dot_git(cwd)
+      return cwd unless dot_git
+
+      holder = File.dirname(dot_git)
+      gitdir = File.directory?(dot_git) ? dot_git : gitdir_from_file(dot_git)
+      return holder unless gitdir
+
+      common = common_dir(gitdir)
+      common = begin
+        File.realpath(common)
+      rescue SystemCallError
+        common
+      end
+      File.basename(common) == ".git" ? File.dirname(common) : common
+    end
+
+    # Is +cwd+ inside a git repository (a .git somewhere above it)?
+    def in_repo?(cwd = Dir.pwd)
+      !find_dot_git(cwd).nil?
+    end
+
+    def find_dot_git(start)
+      dir = File.expand_path(start)
+      loop do
+        candidate = File.join(dir, ".git")
+        return candidate if File.exist?(candidate)
+
+        parent = File.dirname(dir)
+        return nil if parent == dir
+
+        dir = parent
+      end
+    end
+
+    # A ".git" file holds "gitdir: <path>", relative to the file's directory.
+    def gitdir_from_file(path)
+      line = File.read(path, 4096).to_s[/\Agitdir:\s*(.+)$/, 1]&.strip
+      return nil if line.nil? || line.empty?
+
+      File.expand_path(line, File.dirname(path))
+    rescue SystemCallError, ArgumentError
+      nil
+    end
+
+    def common_dir(gitdir)
+      file = File.join(gitdir, "commondir")
+      return gitdir unless File.file?(file)
+
+      rel = File.read(file).strip
+      rel.empty? ? gitdir : File.expand_path(rel, gitdir)
+    rescue SystemCallError
+      gitdir
+    end
+    private_class_method :find_dot_git, :gitdir_from_file, :common_dir
+
+    def project_dir(env: ENV, cwd: Dir.pwd)
+      File.join(projects_dir(env: env), project_key(cwd))
+    end
+
+    def bundles_dir(env: ENV)
+      File.join(system_dir(env: env), ".bundles")
+    end
+  end
+end