pray-cli 1.18.1 → 1.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91a549f989bb5872cf7307c16101a89c479bda9f919dd4f969917a80f4bf5958
-  data.tar.gz: 01a7042cad4e383a95ca2b15d698b9e00a46707d27b2885381ce57f6775cb15b
+  metadata.gz: 4eb951f0ca0abc5ac0aa68ab27e63e4f778c92453fddb9a7cca0115dac1526d9
+  data.tar.gz: 28ba1073042c0c2a77138e35a9ae80688cb1a6075dd16cba5ee1b9aef2c9c3af
 SHA512:
-  metadata.gz: 52f904573df3f97eb3ad240388db1ac7d81d36cd66fe24b43be8cf32f392d59abf6283fc496a92b9844e40cec4d7058bf8db54fb97716164635c395c95a27796
-  data.tar.gz: ccc7110154721dbc019d02c37ecdbeaaac225ccf702e8d1007cfe3af4b3f54f35627876fb78f15eb5617e691c7c7ca7016c9c05853b1719655545a087baf8eef
+  metadata.gz: 260a99edc903d99d235b2d9dd40904490fbcc392d67a07a4323d43b1359fead4428976745e438e17767948a1494262daa97b87650965ffc22366267c8faf5226
+  data.tar.gz: f031ff7ebaeceee86829abac7e2f99f060be902ebc586c00e5ad67135d25958248ac7c4fd5425a12068b67d1a01ebd747cacf53501f2c81cc68f3bdcbcfd838d

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # CHANGELOG
 
+## 1.20.0 (2026-09-18)
+
+- Fetch a locked git catalog revision during `pray install` when the local cache does not have that commit yet. `pray install --offline` still refuses a missing commit.
+- Refuse `pray install --offline` when a git catalog is not already in the local cache, instead of cloning it. A global cache seed still works.
+- Honour a locked git revision for a local file catalog. Install does not read the origin worktree after that checkout fails.
+- Keep git catalog objects in the shared cache. The project catalog is a file tree without a git directory.
+- When a locked git revision is missing from a shallow cache, fetch the missing history instead of only that one commit.
+- Keep an unchanged published version when a later `pray publish` uses a different publisher label.
+- Keep `pray drift` clean after `pray install` when a compose block adds a local file after a package dest already had.
+
+## 1.19.0 (2026-09-18)
+
+- Declare named `publish` remotes in Prayfile (RFC 0118). `pray publish` uses them when dest flags are omitted, and publishes only path-owned packages.
+
 ## 1.18.1 (2026-09-17)
 
 - Fix `pray package` and `pray publish` when the CLI cannot create a staging directory.

data/lib/pray/cli/commands/distribution.rb

@@ -2,16 +2,64 @@
 
 module Pray
   module CLI
-    def publish_command(roots:, servers:)
+    def publish_command(roots:, servers:, to: [], dry_run: false)
       project = resolve_current_project
-      roots.each { |root| Publish.publish_to_root(project, root) }
-      servers.each { |server| Publish.publish_to_server(project, server) }
+      dests = PublishSelect.resolve_publish_destinations(
+        project.manifest.publish_remotes || [],
+        PublishSelect::PublishCliDest.new(to: to, roots: roots, servers: servers),
+        Dir.pwd
+      )
+      if dry_run
+        print_publish_plan(project, dests)
+        return
+      end
+      dests.each do |dest|
+        packages = selected_publish_packages(project, dest.packages)
+        filtered = project.dup
+        filtered.packages = packages
+        Publish.publish_to_root(filtered, dest.root) if dest.root
+        Publish.publish_to_server(filtered, dest.server) if dest.server
+      end
     end
 
-    def serve_command(root:, host:, port:, stdio:)
+    def selected_publish_packages(project, listed)
+      allowed = PublishRemote.allowed_publish_names(project.manifest, listed)
+      selected = project.packages.select { |package| allowed.include?(package.declaration.name) }
+      if selected.empty?
+        raise Error.usage("no path packages to publish; remote dependencies are not published")
+      end
+      selected.each { |package| package.spec.require_release_version! }
+      selected
+    end
+
+    def print_publish_plan(project, dests)
+      dests.each do |dest|
+        packages = selected_publish_packages(project, dest.packages)
+        target = dest.root || dest.server || dest.name
+        packages.each do |package|
+          puts "publish #{package.declaration.name} #{package.spec.version} -> #{dest.name} (#{target})"
+        end
+      end
+    end
+
+    def serve_command(root:, host:, port:, stdio:, to: nil)
       raise Error.unsupported("serve --stdio is not implemented yet in pray-cli Ruby") if stdio
 
-      Serve.run_server(root: root, host: host, port: port)
+      Serve.run_server(root: optional_path_remote_root(to, root), host: host, port: port)
+    end
+
+    def optional_path_remote_root(to, root)
+      remotes = begin
+        Pray.parse_manifest(Pray.read_manifest_text(manifest_path)).publish_remotes || []
+      rescue Error
+        return root if to.nil?
+
+        raise
+      end
+      return root if remotes.empty? && to.nil?
+
+      cli_root = (root == ".") ? nil : root
+      PublishSelect.resolve_path_remote(remotes, to, cli_root, Dir.pwd)
     end
   end
 end

data/lib/pray/cli/commands/init.rb

@@ -34,6 +34,32 @@ module Pray
       FileUtils.mkdir_p(File.join(distribution_root, "v1", "artifacts"))
       Publish.write_registry_index(distribution_root, RegistryIndex.new)
       Distribution.write_settings(distribution_root)
+      maybe_declare_publish_remote(Dir.pwd, distribution_root)
+    end
+
+    def maybe_declare_publish_remote(project_root, distribution_root)
+      manifest_path_value = File.join(project_root, "Prayfile")
+      return unless File.exist?(manifest_path_value)
+
+      text = File.read(manifest_path_value)
+      manifest = Pray.parse_manifest(text)
+      return unless (manifest.publish_remotes || []).empty?
+
+      relative = if distribution_root == project_root
+        "."
+      else
+        prefix = project_root.end_with?("/") ? project_root : "#{project_root}/"
+        distribution_root.start_with?(prefix) ? distribution_root.delete_prefix(prefix).tr("\\", "/") : "prayers"
+      end
+      statement = %(publish "prayers", path: "#{relative}")
+      lines = text.split("\n")
+      insertion = lines.rindex { |line| line.lstrip.start_with?("source ") }
+      insertion ||= lines.index { |line| line.lstrip.start_with?("prayfile ") }
+      insertion = insertion ? insertion + 1 : 1
+      lines.insert(insertion, statement)
+      updated = lines.join("\n")
+      updated += "\n" unless updated.end_with?("\n")
+      File.write(manifest_path_value, updated)
     end
 
     def repo_distribution_root(root)

data/lib/pray/cli/commands/packages.rb

@@ -53,7 +53,12 @@ module Pray
 
     def package_command
       project = resolve_current_project
-      project.packages.each do |package|
+      allowed = PublishRemote.path_owned_package_names(project.manifest)
+      packages = project.packages.select { |package| allowed.include?(package.declaration.name) }
+      if packages.empty?
+        raise Error.usage("no path packages to package; remote dependencies are not packed")
+      end
+      packages.each do |package|
         package.spec.require_release_version!
         output_path = Archive.package_archive_path(package.declaration.name, package.spec.version)
         Archive.write_package_archive(package, output_path)

data/lib/pray/cli/help.rb

@@ -23,9 +23,9 @@ module Pray
       ].freeze
 
       DISTRIBUTION_COMMANDS = [
-        "publish --root PATH [--server URL ...]",
+        "publish [--root PATH|--server URL|--to NAME] [--dry-run]",
         "login --server URL --email EMAIL",
-        "serve [--root PATH] [--host HOST] [--port PORT] [--stdio]",
+        "serve [--root PATH | --to NAME] [--host HOST] [--port PORT] [--stdio]",
         "sync [--root PATH] [--peer URL ...]",
         "confess <package> | --from-lock SPAN_ID [--accepted|--rejected]"
       ].freeze
@@ -146,9 +146,11 @@ module Pray
         "vendor" => "copy resolved packages locally\n\nUsage: pray vendor",
         "clean" => "remove local cache and vendor trees, or only unused registry entries\n\nUsage: pray clean [--unused]",
         "publish" => <<~TEXT.strip,
-          upload packages to a registry or local root
+          upload path packages to a registry or local root
 
-          Usage: pray publish --root PATH [--server URL ...]
+          Usage: pray publish [--root PATH] [--server URL ...] [--to NAME] [--dry-run]
+
+          Prayfile publish remotes supply dests when flags are omitted.
         TEXT
         "login" => <<~TEXT.strip,
           authenticate to a registry server
@@ -158,7 +160,7 @@ module Pray
         "serve" => <<~TEXT.strip,
           run a local registry server
 
-          Usage: pray serve [--root PATH] [--host HOST] [--port PORT] [--stdio]
+          Usage: pray serve [--root PATH | --to NAME] [--host HOST] [--port PORT] [--stdio]
         TEXT
         "sync" => <<~TEXT.strip,
           sync packages with peer registries

data/lib/pray/cli/parse.rb

@@ -141,26 +141,33 @@ module Pray
     def parse_publish_arguments(arguments)
       roots = []
       servers = []
+      to = []
+      dry_run = false
       while (argument = arguments.shift)
         case argument
         when "--root"
           roots << arguments.shift
         when "--server"
           servers << arguments.shift
+        when "--to"
+          to << arguments.shift
+        when "--dry-run"
+          dry_run = true
+        when "--signing-key"
+          arguments.shift
         else
           raise Error.unsupported("unexpected publish argument: #{argument}")
         end
       end
-      raise Error.unsupported("publish requires at least one --root PATH or --server URL") if roots.empty? && servers.empty?
-
-      {roots: roots, servers: servers}
+      {roots: roots, servers: servers, to: to, dry_run: dry_run}
     end
 
     def parse_serve_arguments(arguments)
-      options = {root: ".", host: "127.0.0.1", port: 7429, stdio: false}
+      options = {root: ".", to: nil, host: "127.0.0.1", port: 7429, stdio: false}
       while (argument = arguments.shift)
         case argument
         when "--root" then options[:root] = arguments.shift
+        when "--to" then options[:to] = arguments.shift
         when "--host" then options[:host] = arguments.shift
         when "--port" then options[:port] = Integer(arguments.shift)
         when "--stdio" then options[:stdio] = true

data/lib/pray/format_manifest.rb

@@ -79,6 +79,7 @@ module Pray
         targets: [],
         packages: manifest.packages.map { |package| clone_package(package) },
         local: manifest.local.map { |local| local.dup },
+        publish_remotes: (manifest.publish_remotes || []).map(&:dup),
         symbols: manifest.symbols.dup,
         render: manifest.render.dup
       )

data/lib/pray/format_serialize.rb

@@ -12,6 +12,11 @@ module Pray
         manifest.sources.each { |source| lines << format_source(source) }
       end
 
+      unless (manifest.publish_remotes || []).empty?
+        lines << ""
+        manifest.publish_remotes.each { |remote| lines << format_publish_remote(remote) }
+      end
+
       unless manifest.symbols.empty?
         lines << ""
         lines << "pray do"
@@ -109,6 +114,18 @@ module Pray
       parts.join(", ")
     end
 
+    def format_publish_remote(remote)
+      parts = [%(publish "#{remote.name}")]
+      parts << %(path: "#{remote.path}") if remote.path
+      parts << %("#{remote.url}") if remote.url
+      return parts.join(", ") if remote.packages.empty?
+
+      lines = ["#{parts.join(", ")} do"]
+      remote.packages.each { |name| lines << %(  pray "#{name}") }
+      lines << "end"
+      lines.join("\n")
+    end
+
     def format_destination_entry(entry, manifest)
       if entry.kind == "local"
         return %(pray "#{entry.path}")

data/lib/pray/git_cache.rb

@@ -1,33 +1,26 @@
 # frozen_string_literal: true
 
-require "fileutils"
-require "pathname"
 require_relative "error"
 require_relative "hashing"
 require_relative "git_run"
-require_relative "git_clone"
+require_relative "git_store"
+require_relative "git_materialize"
 
 module Pray
   module GitCache
     module_function
 
-    def ensure_git_repository(project_root, clone_url, refresh:, pinned_revision:, sparse_subdir:)
-      shared = git_source_cache_directory(project_root, clone_url)
-      ensure_shared_git_repository(project_root, clone_url, shared, refresh: refresh, pinned_revision: pinned_revision)
-      checkout = git_source_cache_directory(project_root, clone_url, sparse_subdir)
-      if checkout != shared
-        ensure_linked_worktree(shared, checkout)
-        GitClone.apply_sparse_checkout(checkout, sparse_subdir)
-        if pinned_revision
-          checkout_git_revision(checkout, clone_url, pinned_revision, refresh)
-        elsif refresh
-          GitRun.run_git(checkout, "reset", "--hard", git_head_revision(shared))
-        end
-        return [checkout, git_head_revision(checkout)]
-      end
-
-      GitClone.apply_sparse_checkout(shared)
-      [shared, git_head_revision(shared)]
+    def ensure_git_repository(project_root, clone_url, refresh:, pinned_revision:, sparse_subdir:, offline: false)
+      db, revision = GitStore.ensure_global_git_db(
+        clone_url,
+        pinned_revision: pinned_revision,
+        refresh: refresh,
+        offline: offline,
+        working_directory: project_root
+      )
+      catalog = git_source_cache_directory(project_root, clone_url, sparse_subdir)
+      GitMaterialize.materialize_catalog_tree(db, catalog, revision, sparse_subdir, refresh)
+      [catalog, revision]
     end
 
     def git_source_cache_directory(project_root, clone_url, subdir = nil)
@@ -36,6 +29,9 @@ module Pray
     end
 
     def git_source_cached_repository(project_root, clone_url)
+      global_cache = GitStore.global_git_cache_directory(clone_url)
+      return global_cache if global_cache && GitStore.global_git_cache_ready?(global_cache)
+
       shared = git_source_cache_directory(project_root, clone_url)
       return shared if git_checkout?(shared)
 
@@ -57,60 +53,6 @@ module Pray
       Hashing.sha256_prefixed(text)[7, 16]
     end
 
-    def ensure_shared_git_repository(project_root, clone_url, shared, refresh:, pinned_revision:)
-      if File.directory?(File.join(shared, ".git"))
-        if pinned_revision
-          checkout_git_revision(shared, clone_url, pinned_revision, refresh)
-        elsif refresh
-          refresh_git_worktree(shared, clone_url)
-        end
-        refresh_global_from_project(clone_url, shared) if refresh
-        return
-      end
-
-      FileUtils.rm_rf(shared) if File.exist?(shared)
-      FileUtils.mkdir_p(File.dirname(shared))
-      seeded = seed_git_cache_from_global(clone_url, shared, project_root)
-      if seeded
-        GitRun.run_git(shared, "remote", "set-url", "origin", clone_url)
-      else
-        GitClone.clone_git_cache(project_root, clone_url, shared, quiet: false)
-        mirror_git_cache_to_global(clone_url, shared)
-      end
-      GitClone.apply_sparse_checkout(shared)
-      if pinned_revision
-        checkout_git_revision(shared, clone_url, pinned_revision, true)
-      elsif refresh && seeded
-        refresh_git_worktree(shared, clone_url)
-      end
-      refresh_global_from_project(clone_url, shared) if refresh && seeded
-    end
-
-    def ensure_linked_worktree(shared, checkout)
-      return if same_object_store?(shared, checkout)
-
-      FileUtils.rm_rf(checkout) if File.exist?(checkout)
-      FileUtils.mkdir_p(File.dirname(checkout))
-      return if GitRun.try_run_git(shared, "worktree", "add", "--detach", "--no-checkout", checkout)
-
-      GitRun.run_git(shared, "worktree", "add", "--detach", checkout)
-    end
-
-    def same_object_store?(shared, checkout)
-      return false unless git_checkout?(checkout)
-
-      git_common_dir(shared) == git_common_dir(checkout)
-    end
-
-    def git_common_dir(repository)
-      output, status = GitRun.capture_git(repository, "rev-parse", "--git-common-dir")
-      raise Error.resolution(GitRun.command_error("git rev-parse --git-common-dir", output)) unless status.success?
-
-      reported = output.strip
-      path = Pathname.new(reported).absolute? ? reported : File.expand_path(reported, repository)
-      File.realpath(path)
-    end
-
     def origin_matches?(repository, clone_url)
       output, status = GitRun.capture_git(repository, "remote", "get-url", "origin")
       return false unless status.success?
@@ -118,75 +60,5 @@ module Pray
       origin = output.strip.delete_prefix("git+")
       origin == clone_url
     end
-
-    def global_cache_root
-      return ENV["PRAY_CACHE"] if ENV["PRAY_CACHE"]
-      return File.join(ENV["PRAY_HOME"], "cache") if ENV["PRAY_HOME"]
-
-      home = ENV["HOME"]
-      home ? File.join(home, ".cache", "pray") : nil
-    end
-
-    def global_git_cache_directory(clone_url)
-      root = global_cache_root
-      root ? File.join(root, "git", cache_key(clone_url)) : nil
-    end
-
-    def global_git_cache_ready?(global_cache)
-      File.directory?(File.join(global_cache, ".git")) || File.file?(File.join(global_cache, "HEAD"))
-    end
-
-    def seed_git_cache_from_global(clone_url, destination, working_directory)
-      global_cache = global_git_cache_directory(clone_url)
-      return false unless global_cache && global_git_cache_ready?(global_cache)
-
-      GitClone.clone_git_cache(working_directory, global_cache, destination, quiet: true)
-      true
-    end
-
-    def mirror_git_cache_to_global(clone_url, project_cache)
-      global_cache = global_git_cache_directory(clone_url)
-      return unless global_cache
-      return if global_git_cache_ready?(global_cache)
-
-      FileUtils.mkdir_p(File.dirname(global_cache))
-      FileUtils.rm_rf(global_cache) if File.exist?(global_cache)
-      GitRun.run_git(File.dirname(project_cache), "clone", "--bare", "--quiet", File.basename(project_cache), global_cache)
-    end
-
-    def fetch_origin(repository, revision = nil)
-      extra = revision ? [revision] : []
-      return if GitRun.try_run_git(repository, "fetch", "--depth", "1", "--filter=blob:none", "origin", *extra)
-
-      GitRun.run_git(repository, "fetch", "--depth", "1", "origin", *extra)
-    end
-
-    def checkout_git_revision(repository, _clone_url, revision, refresh)
-      fetch_origin(repository, revision) if refresh
-      GitRun.run_git(repository, "checkout", "--force", revision)
-    end
-
-    def refresh_git_worktree(repository, _clone_url)
-      fetch_origin(repository)
-      GitRun.run_git(repository, "reset", "--hard", "origin/HEAD")
-    end
-
-    def refresh_global_from_project(clone_url, project_cache)
-      global_cache = global_git_cache_directory(clone_url)
-      return unless global_cache
-
-      FileUtils.rm_rf(global_cache) if global_git_cache_ready?(global_cache) || File.exist?(global_cache)
-      mirror_git_cache_to_global(clone_url, project_cache)
-    end
-
-    def git_head_revision(repository)
-      output, status = GitRun.capture_git(repository, "rev-parse", "HEAD")
-      raise Error.resolution(GitRun.command_error("git rev-parse HEAD", output)) unless status.success?
-
-      revision = output.strip
-      raise Error.resolution("git repository has no HEAD revision") if revision.empty?
-
-      revision
-    end
   end
 end

data/lib/pray/git_clone.rb

@@ -6,21 +6,17 @@ module Pray
   module GitClone
     module_function
 
-    def clone_git_cache(working_directory, source, destination, quiet:)
-      filtered = ["clone", "--depth", "1", "--filter=blob:none", "--sparse", source, destination]
+    def clone_bare_git_db(working_directory, source, destination, quiet:)
+      local = source.start_with?("file://", "/") ? ["--no-local"] : []
+      filtered = ["clone", "--bare", "--depth", "1", "--filter=blob:none", *local, source, destination]
       filtered.insert(1, "--quiet") if quiet
       return if GitRun.try_run_git(working_directory, *filtered)
 
-      full = ["clone", "--depth", "1", source, destination]
+      full = ["clone", "--bare", "--depth", "1", *local, source, destination]
       full.insert(1, "--quiet") if quiet
       GitRun.run_git(working_directory, *full)
     end
 
-    def apply_sparse_checkout(repository, subdir = nil)
-      GitRun.run_git(repository, "sparse-checkout", "init", "--cone")
-      GitRun.run_git(repository, "sparse-checkout", "set", *catalog_sparse_cones(subdir))
-    end
-
     def catalog_sparse_cones(subdir)
       if subdir && !subdir.empty?
         ["#{subdir}/v1/packages"]

data/lib/pray/git_materialize.rb

@@ -1,11 +1,17 @@
 # frozen_string_literal: true
 
-require_relative "git_run"
+require "fileutils"
+require "open3"
 require_relative "error"
+require_relative "git_clone"
+require_relative "git_run"
 require_relative "path_safety"
 
 module Pray
   module GitMaterialize
+    REVISION_MARKER = ".pray-revision"
+    GIT_DIR_MARKER = ".pray-git-dir"
+
     module_function
 
     def read_local_artifact_bytes(source_root, artifact)
@@ -28,49 +34,95 @@ module Pray
       File.binread(path)
     end
 
-    def materialize_catalog_file(source_root, relative)
-      return if File.file?(File.join(source_root, relative))
-      return unless sparse_checkout_enabled?(source_root)
-
-      toplevel = git_toplevel(source_root)
-      return unless toplevel
-
-      repo_relative = repo_relative_text(source_root, relative)
-      return unless repo_relative
+    def materialize_catalog_tree(git_dir, dest, revision, subdir, refresh)
+      return if !refresh && catalog_matches?(dest, git_dir, revision)
 
-      cone = artifact_sparse_cone(repo_relative)
-      GitRun.run_git(toplevel, "sparse-checkout", "add", cone) if cone
-      GitRun.run_git(toplevel, "checkout", "HEAD", "--", repo_relative)
-    end
+      FileUtils.rm_rf(dest) if File.exist?(dest)
+      FileUtils.mkdir_p(dest)
+      unpacked = GitClone.catalog_sparse_cones(subdir).any? do |prefix|
+        unpack_archive_prefix(git_dir, dest, revision, prefix)
+      end
+      raise Error.resolution("no pray distribution root in git source at revision #{revision}") unless unpacked
 
-    def sparse_checkout_enabled?(source_root)
-      output, status = GitRun.capture_git(source_root, "config", "--get", "core.sparseCheckout")
-      status.success? && output.strip == "true"
+      File.write(File.join(dest, REVISION_MARKER), revision)
+      File.write(File.join(dest, GIT_DIR_MARKER), git_dir)
     end
 
-    def git_toplevel(source_root)
-      output, status = GitRun.capture_git(source_root, "rev-parse", "--show-toplevel")
-      return unless status.success?
+    def materialize_catalog_file(source_root, relative)
+      return if File.file?(File.join(source_root, relative))
 
-      text = output.strip
-      text.empty? ? nil : text
+      markers = find_catalog_markers(source_root)
+      return unless markers
+
+      full_path = File.join(source_root, relative)
+      repo_relative = full_path.delete_prefix(markers.fetch(:work_tree)).delete_prefix("/")
+      GitRun.run_git(
+        markers.fetch(:git_dir),
+        "--work-tree",
+        markers.fetch(:work_tree),
+        "checkout",
+        markers.fetch(:revision),
+        "--",
+        repo_relative
+      )
     end
 
-    def repo_relative_text(source_root, relative)
-      output, status = GitRun.capture_git(source_root, "rev-parse", "--show-prefix")
-      return unless status.success?
-
-      prefix = output.strip
-      prefix.empty? ? relative : File.join(prefix, relative)
+    def catalog_matches?(dest, git_dir, revision)
+      revision_path = File.join(dest, REVISION_MARKER)
+      git_dir_path = File.join(dest, GIT_DIR_MARKER)
+      return false unless File.file?(revision_path) && File.file?(git_dir_path)
+      return false unless File.read(revision_path).strip == revision
+      return false unless File.read(git_dir_path).strip == git_dir
+
+      File.directory?(File.join(dest, "v1", "packages")) ||
+        File.directory?(File.join(dest, "prayers", "v1", "packages")) ||
+        Dir.children(dest).any? { |name| File.directory?(File.join(dest, name, "v1", "packages")) }
+    rescue Errno::ENOENT
+      false
     end
 
-    def artifact_sparse_cone(repo_relative)
-      parts = repo_relative.split("/").reject(&:empty?)
-      return repo_relative if parts.length < 2
+    def unpack_archive_prefix(git_dir, dest, revision, prefix)
+      env = ENV.to_h.merge("GIT_TERMINAL_PROMPT" => "0")
+      stdout, _stderr, status = Open3.capture3(
+        env,
+        "git",
+        "-c",
+        "protocol.file.allow=always",
+        "-C",
+        git_dir,
+        "archive",
+        "--format=tar",
+        revision,
+        "--",
+        prefix,
+        stdin_data: ""
+      )
+      return false unless status.success? && !stdout.empty?
+
+      _ignored, extract_status = Open3.capture2(env, "tar", "-x", "-C", dest, stdin_data: stdout)
+      raise Error.resolution("failed to unpack git catalog archive") unless extract_status.success?
+
+      true
+    end
 
-      parts.pop
-      parts.pop if parts.last != "artifacts" && parts.length > 3
-      parts.join("/")
+    def find_catalog_markers(start)
+      current = start
+      8.times do
+        revision_path = File.join(current, REVISION_MARKER)
+        git_dir_path = File.join(current, GIT_DIR_MARKER)
+        if File.file?(revision_path) && File.file?(git_dir_path)
+          revision = File.read(revision_path).strip
+          git_dir = File.read(git_dir_path).strip
+          return if revision.empty? || !File.exist?(git_dir)
+
+          return {git_dir: git_dir, revision: revision, work_tree: current}
+        end
+        parent = File.dirname(current)
+        return if parent == current
+
+        current = parent
+      end
+      nil
     end
   end
 end