pray-cli 1.25.0 → 1.26.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 817f233c7933ea4baf101ff50028641a039e3970951e83a1bfdda61f1ec55412
-  data.tar.gz: 43b0d03df5ee524eefc819d5984b2ac01fa05377ffbdb60621ce195113339c45
+  metadata.gz: 7a2524f61bfecb06bcdcf1656ed618e104d854a2d0386c791c3bf3989b9894d1
+  data.tar.gz: d20780c7dd5cb5a9f14448fcb793e2bb42007ec8c29db9a390fbe3d4c9dd27b5
 SHA512:
-  metadata.gz: 6ae47d928e86b7beb3c3b4009e836fe0a53d2f620a54eb891576acb8854931b51508bda2fbd4fe33565aab97047691561dc2ce49e332068f6235e1be0db34ba2
-  data.tar.gz: 16e3dfa34136071143a0adcb85184c341f655fbcef9a6319c0a8249bd90c86bb0f61ace49ad16da2470660c23240a70c5ec343d3b14fec563fcffac741fbf9a3
+  metadata.gz: 3f721c1a473ce6e07b726c6be47f6b98da4dcd83a6f6da6e3afcf6f80d18d50a7f47ed1b42f3bdde9b4922e16c05784ef5c32f69e1255cb7ae521f7f6ade8dbe
+  data.tar.gz: aeeaaade1743bf0b15511ec45704692fed58ed65b2f2f4ccca6d848481b23bd958bee3e433bb944632828ed029391f638c1ffaf31699bb73251763e8654f0c9b

data/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 1.26.1 (2026-11-02)
+
+- Show optional package referrals separately in `pray explain`, exclude them from dependency cycles and trees, and validate their constraints when another declaration selects the target.
+- Keep drift, render checks, planning, and writes consistent for managed files that contain local content.
+
+## 1.26.0 (2026-10-30)
+
+- Add validated `related` references to prayspec parsing, rendering, and `pray explain`.
+- Make `render --check`, frozen install, and `plan` compare destinations with the bytes the write path would produce. Remove unchanged managed spans retired by the previous lock while preserving edited or unknown spans for explicit review.
+- Add `pray search` parity with the stable distribution-index contract. Search package names by substring through a declared source, local distribution root, or registry URL, and label catalog summaries as unverified claims in help.
+
 ## 1.25.0 (2026-10-26)
 
 - Bump the gem version to 1.25.0 with the coordinated language-registry cut.

data/README.md

@@ -62,6 +62,7 @@ pray remove sample/base
 pray update
 pray unlock sample/base
 pray list
+pray search base --source default
 pray tree
 pray explain sample/base
 pray outdated

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

@@ -84,7 +84,13 @@ module Pray
       end
       lines << "source: #{package_source_summary(package)}"
       lines << "exports: #{format_list(package.selected_exports)}"
-      lines << "dependencies: #{format_list(package.spec.dependencies.map(&:name))}"
+      required_dependencies = package.spec.dependencies.reject(&:optional).map(&:name)
+      optional_referrals = package.spec.dependencies.select(&:optional).map do |dependency|
+        "#{dependency.name} (#{dependency.constraint})"
+      end
+      lines << "dependencies: #{format_list(required_dependencies)}"
+      lines << "optional referrals: #{format_list(optional_referrals)}"
+      lines << "related prayers: #{format_list(package.spec.related)}"
       lines << "tree hash: #{package.tree_hash}"
       lines << "artifact hash: #{package.artifact_hash}"
       if lockfile_package

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Pray
+  module CLI
+    def search_command(query:, source:, root:, url:)
+      hits = if root
+        RegistrySearch.search_local_registry(root, query)
+      elsif url
+        RegistrySearch.search_http_registry(url, query)
+      else
+        search_declared_source(query, source)
+      end
+      if hits.empty?
+        puts "no packages matched"
+      else
+        hits.each { |hit| puts(hit.summary ? "#{hit.name} — #{hit.summary}" : hit.name) }
+      end
+    end
+
+    def search_declared_source(query, source_name)
+      manifest = Pray.parse_manifest(Pray.read_manifest_text(manifest_path))
+      source = source_name ? manifest.sources.find { |entry| entry.name == source_name } : searchable_source(manifest)
+      raise Error.resolution("unknown source: #{source_name}") if source_name && !source
+      unless source
+        raise Error.resolution("Prayfile has no searchable sources; pass --root PATH or --url URL")
+      end
+
+      case source.kind
+      when "path"
+        root = File.expand_path(source.url, File.dirname(manifest_path))
+        RegistrySearch.search_local_registry(root, query)
+      when "registry", "static index"
+        RegistrySearch.search_http_registry(source.url, query)
+      else
+        raise Error.unsupported("search does not support source kind #{source.kind}")
+      end
+    end
+
+    def searchable_source(manifest)
+      manifest.sources.find { |source| %w[registry static\ index].include?(source.kind) } || manifest.sources.first
+    end
+  end
+end

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

@@ -29,7 +29,7 @@ module Pray
       if flags[:check]
         ensure_rendered_outputs_current(project, rendered)
       else
-        Render.write_rendered_targets(project, rendered)
+        Render.write_rendered_targets(project, rendered, project.previous_lockfile)
       end
     end
 

data/lib/pray/cli/help.rb

@@ -36,6 +36,7 @@ module Pray
 
       INSPECT_COMMANDS = [
         "list                                   list declared packages",
+        "search <query> [--source|--root|--url]  find packages in a distribution index",
         "outdated [--remote]                    show constraint vs resolved versions",
         "explain <package>                      show why a package was selected",
         "tree                                   print the dependency tree"
@@ -102,7 +103,7 @@ module Pray
 
           Without --check, render writes dest. It does not write Prayfile.lock.
           Use pray plan to preview a write.
-          --check writes nothing. It fails unless dest already matches a fresh render from current inputs.
+          --check writes nothing. It fails when render would change dest.
         TEXT
         "format" => <<~TEXT.strip,
           rewrite Prayfile to recommended destination DSL
@@ -187,6 +188,7 @@ module Pray
           Subcommands: list, show, add-key, remove-key, set-signed, set-allow, import-repo, import-registry, check
         TEXT
         "list" => "list declared packages\n\nUsage: pray list",
+        "search" => "search a distribution index for package names\n\nUsage: pray search <query> [--source NAME | --root PATH | --url URL]\n\nMatches package names by case-insensitive substring. Summaries are unverified catalog claims.",
         "outdated" => <<~TEXT.strip,
           show constraint vs resolved versions
 

data/lib/pray/cli/helpers.rb

@@ -59,8 +59,8 @@ module Pray
     def ensure_rendered_outputs_current(project, rendered)
       rendered.each do |target|
         path = File.join(project.project_root, target.path)
-        on_disk = File.read(path)
-        if on_disk != target.content
+        retired = RenderReconcile.retired_span_checksums(project.previous_lockfile, target)
+        unless RenderReconcile.current?(path, target.path, target.content, retired)
           raise Error.render("#{path} is stale; rerun pray install to regenerate it or pray plan to inspect the diff")
         end
       end
@@ -152,7 +152,7 @@ module Pray
       lines << "#{indent}#{package.declaration.name} #{package.spec.recorded_version}"
       return unless ancestry.add?(package.declaration.name)
 
-      package.spec.dependencies.each do |dependency|
+      package.spec.dependencies.reject(&:optional).each do |dependency|
         resolved = package_map[dependency.name]
         if resolved
           if ancestry.include?(resolved.declaration.name)

data/lib/pray/cli/parse.rb

@@ -64,6 +64,7 @@ module Pray
       when "serve" then [:serve, parse_serve_arguments(arguments)]
       when "confess" then [:confess, parse_confess_arguments(arguments)]
       when "list" then [:list]
+      when "search" then [:search, parse_search_arguments(arguments)]
       when "outdated" then [:outdated, arguments]
       when "explain" then [:explain, arguments.shift]
       when "vendor" then [:vendor]
@@ -121,6 +122,32 @@ module Pray
       {unused: unused}
     end
 
+    def parse_search_arguments(arguments)
+      options = {query: nil, source: nil, root: nil, url: nil}
+      while (argument = arguments.shift)
+        case argument
+        when "--source" then options[:source] = search_option_value(arguments, argument)
+        when "--root" then options[:root] = search_option_value(arguments, argument)
+        when "--url" then options[:url] = search_option_value(arguments, argument)
+        when /^--/ then raise Error.usage("unknown search flag: #{argument}")
+        else
+          raise Error.usage("unexpected search argument: #{argument}") if options[:query]
+
+          options[:query] = argument
+        end
+      end
+      raise Error.usage("search requires a query") unless options[:query]
+
+      options
+    end
+
+    def search_option_value(arguments, flag)
+      value = arguments.shift
+      raise Error.usage("#{flag} requires a value") unless value && !value.start_with?("--")
+
+      value
+    end
+
     def parse_add_arguments(arguments)
       name = arguments.shift
       raise Error.unsupported("add requires a package name") unless name

data/lib/pray/cli.rb

@@ -14,6 +14,7 @@ require_relative "cli/commands/init_prayer"
 require_relative "cli/commands/workflow"
 require_relative "cli/commands/update_latest"
 require_relative "cli/commands/packages"
+require_relative "cli/commands/search"
 require_relative "cli/commands/distribution"
 require_relative "cli/commands/trust"
 require_relative "cli/commands/auth"
@@ -119,6 +120,7 @@ module Pray
       in [:confess, confess_args] then confess_command(**confess_args)
       in [:sync, sync_args] then sync_command(**sync_args)
       in [:list] then list_command
+      in [:search, search_args] then search_command(**search_args)
       in [:outdated, arguments] then outdated_command(arguments)
       in [:explain, name] then explain_command(name)
       in [:vendor] then raise Error.unsupported("vendor is not implemented yet in pray-cli Ruby")

data/lib/pray/lockfile.rb

@@ -169,7 +169,7 @@ module Pray
     end
 
     def build_lockfile(manifest_hash, environment, project_root, manifest_sources, manifest_targets, rendered, packages, source_revisions, source_host_keys, project = nil)
-      rendered = Render.layout_rendered_targets(project, rendered) if project
+      rendered = Render.layout_rendered_targets(project, rendered, project.previous_lockfile) if project
       lockfile = Lockfile.new(
         manifest_hash: manifest_hash,
         environment: environment,

data/lib/pray/materialize.rb

@@ -90,8 +90,8 @@ module Pray
         if frozen
           rendered.each do |target|
             path = File.join(project.project_root, target.path)
-            on_disk = File.read(path)
-            if on_disk != target.content
+            retired = RenderReconcile.retired_span_checksums(existing, target)
+            unless RenderReconcile.current?(path, target.path, target.content, retired)
               raise Error.render(
                 "#{path} is stale; rerun install to regenerate it or plan to inspect the diff"
               )

data/lib/pray/package_relation.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Pray
+  module PackageRelation
+    module_function
+
+    def canonicalize(references)
+      Array(references).map(&:strip).uniq.sort.tap do |canonical|
+        invalid = canonical.find { |reference| !valid?(reference) }
+        raise Error.parse("prayspec", "invalid related prayer reference") if invalid
+      end
+    end
+
+    def valid?(reference)
+      return false if reference.empty? || reference.match?(/[\\[:cntrl:]]/)
+      if reference.match?(/\A[A-Za-z][A-Za-z0-9+.-]*:.+\z/)
+        return !uri_has_userinfo?(reference)
+      end
+      if reference.start_with?("/")
+        path = locator_path(reference)
+        return path.length > 1 && !path.start_with?("//")
+      end
+      if reference.start_with?("./", "../")
+        return locator_path(reference).split("/").any? do |segment|
+          !segment.empty? && ![".", ".."].include?(segment)
+        end
+      end
+
+      return false if reference.match?(/[?#]/)
+
+      segments = reference.split("/", -1)
+      segments.length == 2 && segments.none? { |segment| segment.empty? || [".", ".."].include?(segment) }
+    end
+
+    def locator_path(reference)
+      reference.split(/[?#]/, 2).first
+    end
+
+    def uri_has_userinfo?(reference)
+      after_scheme = reference.split("://", 2)[1]
+      after_scheme && after_scheme.split(%r{[/?#]}, 2).first.include?("@")
+    end
+  end
+end

data/lib/pray/package_spec.rb

@@ -14,13 +14,13 @@ module Pray
   PackageSpec = Struct.new(
     :name, :version, :summary, :description, :authors, :maintainers, :license, :homepage,
     :source_code_uri, :changelog_uri, :prayfile_version, :files, :exports,
-    :skills, :templates, :adapters, :targets, :dependencies, :metadata, :upstream
+    :skills, :templates, :adapters, :targets, :related, :dependencies, :metadata, :upstream
   ) do
     def initialize(
       name: "", version: "", summary: nil, description: nil, authors: [], maintainers: [], license: nil,
       homepage: nil, source_code_uri: nil, changelog_uri: nil, prayfile_version: nil,
       files: [], exports: {}, skills: {}, templates: {}, adapters: {}, targets: [],
-      dependencies: [], metadata: {}, upstream: nil
+      related: [], dependencies: [], metadata: {}, upstream: nil
     )
       super
     end
@@ -50,6 +50,7 @@ module Pray
         copy.authors = Array(authors).sort
         copy.maintainers = Array(maintainers).sort
         copy.targets = Array(targets).sort
+        copy.related = PackageRelation.canonicalize(related)
         copy.dependencies = dependencies.sort_by { |dependency| [dependency.name, dependency.constraint, dependency.optional] }
       end
     end
@@ -258,6 +259,7 @@ module Pray
         when "maintainers" then spec.maintainers = array_of_strings(value)
         when "files" then spec.files = array_of_strings(value)
         when "targets" then spec.targets = array_of_strings(value)
+        when "related" then spec.related = array_of_strings(value)
         when "exports" then spec.exports = parse_exports(value)
         when "skills" then spec.skills = parse_skills(value)
         when "templates" then spec.templates = parse_templates(value)

data/lib/pray/package_spec_render.rb

@@ -51,6 +51,9 @@ module Pray
       push_named_paths(lines, "templates", spec.templates)
       push_string_map(lines, "adapters", spec.adapters)
       push_array(lines, "targets", spec.targets) unless spec.targets.nil? || spec.targets.empty?
+      unless spec.related.nil? || spec.related.empty?
+        push_array(lines, "related", spec.related)
+      end
     end
 
     def push_relation_fields(lines, spec)

data/lib/pray/path_safety.rb

@@ -21,8 +21,10 @@ module Pray
     end
 
     def reject_unsafe_package_name!(package_name)
-      if package_name.nil? || package_name.empty? || package_name.include?("\0") || package_name.include?("\\") ||
-          package_name.include?("..")
+      segments = package_name&.split("/", -1)
+      if segments&.length != 2 || segments.any? do |segment|
+        segment.empty? || [".", ".."].include?(segment) || segment.include?("\0") || segment.include?("\\")
+      end
         raise Error.resolution("invalid package name: #{package_name.inspect}")
       end
 

data/lib/pray/plan.rb

@@ -16,7 +16,7 @@ module Pray
         package_lines: ApplyReport.local_summary_lines(previous_lockfile, project) +
           package_summary_lines(previous_lockfile, lockfile, project),
         lockfile: lockfile_change_status(previous_lockfile, lockfile),
-        targets: rendered.map { |target| target_change(project, target) },
+        targets: rendered.map { |target| target_change(project, target, previous_lockfile) },
         provisioned: destinations.map { |file, status| [file.path, status.to_s] },
         warnings: []
       )
@@ -57,11 +57,12 @@ module Pray
       Pray.lockfiles_equivalent?(lockfile, existing) ? "unchanged" : "update"
     end
 
-    def target_change(project, target)
+    def target_change(project, target, previous_lockfile)
       path = File.join(project.project_root, target.path)
+      retired = RenderReconcile.retired_span_checksums(previous_lockfile, target)
       change = if !File.exist?(path)
         "write"
-      elsif RenderDest.read_regular_bytes(path, target.path) == target.content.b
+      elsif RenderReconcile.current?(path, target.path, target.content, retired)
         "unchanged"
       else
         "update"

data/lib/pray/registry.rb

@@ -276,7 +276,7 @@ module Pray
 
     def http_get(url)
       uri = URI(url)
-      bounded_http_exchange(uri, Net::HTTP::Get.new(uri), "HTTP request failed for #{url}")
+      bounded_http_exchange(uri, Net::HTTP::Get.new(uri), "HTTP request failed for #{UrlRedaction.redact_userinfo(url)}")
     end
 
     def http_put(url, content_type, body)
@@ -284,7 +284,7 @@ module Pray
       request = Net::HTTP::Put.new(uri)
       request["Content-Type"] = content_type
       request.body = body
-      bounded_http_exchange(uri, request, "HTTP upload failed for #{url}")
+      bounded_http_exchange(uri, request, "HTTP upload failed for #{UrlRedaction.redact_userinfo(url)}")
     end
 
     def http_post(url, content_type, body)
@@ -292,7 +292,7 @@ module Pray
       request = Net::HTTP::Post.new(uri)
       request["Content-Type"] = content_type
       request.body = body
-      bounded_http_exchange(uri, request, "HTTP request failed for #{url}")
+      bounded_http_exchange(uri, request, "HTTP request failed for #{UrlRedaction.redact_userinfo(url)}")
     end
 
     def bounded_http_exchange(uri, request, failure_message)

data/lib/pray/registry_search.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Pray
+  RegistrySearchHit = Struct.new(:name, :summary, keyword_init: true)
+
+  module RegistrySearch
+    module_function
+
+    def search_local_registry(root, query, include_summary: true)
+      index = parse_index(File.read(File.join(root, "v1", "index.json"), encoding: "UTF-8"))
+      search_index_names(index, query).map do |name|
+        metadata_path = Registry.registry_metadata_path(root, name)
+        metadata = Registry.parse_metadata(File.read(metadata_path, encoding: "UTF-8")) if include_summary && File.file?(metadata_path)
+        search_hit(name, metadata)
+      end
+    end
+
+    def search_http_registry(url, query, include_summary: true)
+      index = parse_index(Registry.http_get(Registry.join_url(url, "v1/index.json")))
+      search_index_names(index, query).map do |name|
+        PathSafety.reject_unsafe_package_name!(name)
+        metadata = fetch_http_metadata(url, name) if include_summary
+        search_hit(name, metadata)
+      end
+    end
+
+    def search_index_names(index, query)
+      needle = query.strip.downcase
+      index.fetch("packages").select do |name|
+        raise Error.parse("registry index", "package names must be strings") unless name.is_a?(String)
+
+        PathSafety.reject_unsafe_package_name!(name)
+        name.downcase.include?(needle)
+      end.sort
+    end
+
+    def latest_non_yanked_summary(metadata)
+      return unless metadata
+
+      latest = metadata.versions.reject(&:yanked).max_by { |version| Gem::Version.new(version.version) }
+      summary = latest&.derived_metadata&.fetch("summary", nil).to_s.strip
+      summary unless summary.empty?
+    end
+
+    def parse_index(text)
+      index = JSON.parse(text)
+      unless index["spec"] == "prayfile-distribution-1" && index["packages"].is_a?(Array)
+        raise Error.parse("registry index", "expected prayfile-distribution-1 with a packages array")
+      end
+      index
+    rescue JSON::ParserError => error
+      raise Error.parse("registry index", error.message)
+    end
+
+    def fetch_http_metadata(url, name)
+      path = "v1/packages/#{name}.json"
+      Registry.parse_metadata(Registry.http_get(Registry.join_url(url, path)))
+    rescue Error => error
+      raise unless error.category == :resolution
+
+      nil
+    end
+
+    def search_hit(name, metadata)
+      if metadata && metadata.name != name
+        raise Error.integrity("registry metadata name mismatch for #{name}")
+      end
+      RegistrySearchHit.new(name: name, summary: latest_non_yanked_summary(metadata))
+    end
+  end
+end

data/lib/pray/render_dest.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "fileutils"
-require "pathname"
 
 module Pray
   module RenderDest
@@ -9,13 +8,15 @@ module Pray
 
     def write_rendered_targets(project, rendered, previous_lockfile = nil)
       validate_destinations!(project, previous_lockfile)
+      RenderReconcile.reject_managed_span_conflicts!(project, rendered, previous_lockfile) if previous_lockfile
       rendered.each do |target|
         PathSafety.validate_destination_path!(target.path)
         ensure_safe_destination_ancestors!(project.project_root, target.path, target.path)
         path = File.join(project.project_root, target.path)
         FileUtils.mkdir_p(File.dirname(path))
         ensure_safe_destination_ancestors!(project.project_root, target.path, target.path)
-        write_rendered_content(path, target.path, target.content)
+        retired = RenderReconcile.retired_span_checksums(previous_lockfile, target)
+        write_rendered_content(path, target.path, target.content, retired)
       end
       materialize(project, previous_lockfile)
     end
@@ -147,7 +148,7 @@ module Pray
       end
     end
 
-    def layout_rendered_content(path, display, fresh)
+    def layout_rendered_content(path, display, fresh, retired = {})
       kind = destination_kind(path)
       return fresh if kind == :missing
 
@@ -155,15 +156,15 @@ module Pray
       unless kind == :regular
         raise Error.render("refusing to write `#{display}`; destination is not a regular file")
       end
-      RenderPatch.patch_rendered_content(decode_utf8(read_regular_bytes(path, display), display), fresh)
+      RenderReconcile.reconcile_content(decode_utf8(read_regular_bytes(path, display), display), fresh, retired)
     end
 
-    def write_rendered_content(path, display, fresh)
+    def write_rendered_content(path, display, fresh, retired = {})
       return create_bytes(path, display, fresh) if destination_kind(path) == :missing
 
       open_regular(path, display, File::RDWR) do |file|
         existing = decode_utf8(read_destination_bytes(file, display), display)
-        content = RenderPatch.patch_rendered_content(existing, fresh)
+        content = RenderReconcile.reconcile_content(existing, fresh, retired)
         return if Transaction.replace(path, existing.b, content.b)
 
         file.rewind

data/lib/pray/render_layout.rb

@@ -4,12 +4,13 @@ module Pray
   module Render
     module_function
 
-    def layout_rendered_targets(project, rendered)
+    def layout_rendered_targets(project, rendered, previous_lockfile = project.previous_lockfile)
       rendered.map do |target|
         PathSafety.validate_destination_path!(target.path)
         RenderDest.ensure_safe_destination_ancestors!(project.project_root, target.path, target.path)
         path = File.join(project.project_root, target.path)
-        content = RenderDest.layout_rendered_content(path, target.path, target.content)
+        retired = RenderReconcile.retired_span_checksums(previous_lockfile, target)
+        content = RenderDest.layout_rendered_content(path, target.path, target.content, retired)
         RenderedTarget.new(
           path: target.path,
           content: content,

data/lib/pray/render_patch.rb

@@ -4,11 +4,11 @@ module Pray
   module RenderPatch
     module_function
 
-    def patch_rendered_content(existing, fresh)
-      existing_segments = split_segments(existing)
+    def patch_rendered_content(existing, fresh, retired = {})
       fresh_segments = split_segments(fresh)
       fresh_managed = managed_bodies(fresh_segments)
-      return fresh unless overlapping_managed?(existing_segments, fresh_managed)
+      existing_segments = drop_unchanged_retired(split_segments(existing), fresh_managed, retired)
+      return preserve_unmatched_managed(fresh, existing_segments, fresh_managed) unless overlapping_managed?(existing_segments, fresh_managed)
 
       used = {}
       output = +""
@@ -24,6 +24,28 @@ module Pray
       output.end_with?("\n") ? output : "#{output}\n"
     end
 
+    def drop_unchanged_retired(segments, fresh_managed, retired)
+      segments.reject do |segment|
+        next false unless segment[:kind] == :managed
+        next false if fresh_managed.key?(segment[:id])
+
+        expected = retired[segment[:id]]
+        expected && Hashing.checksum_managed_span_content(segment[:body]) == expected
+      end
+    end
+
+    def preserve_unmatched_managed(fresh, segments, fresh_managed)
+      unmatched = segments.select do |segment|
+        segment[:kind] == :managed && !fresh_managed.key?(segment[:id])
+      end
+      return fresh if unmatched.empty?
+
+      output = fresh.dup
+      output << "\n" unless output.empty? || output.end_with?("\n")
+      unmatched.each { |segment| output << managed_segment(segment[:id], segment[:body]) }
+      output
+    end
+
     def managed_bodies(segments)
       segments.filter_map { |segment| [segment[:id], segment[:body]] if segment[:kind] == :managed }.to_h
     end

data/lib/pray/render_reconcile.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Pray
+  module RenderReconcile
+    module_function
+
+    def reconcile_content(existing, fresh, retired = {})
+      RenderPatch.patch_rendered_content(existing, fresh, retired)
+    end
+
+    def current?(path, display, fresh, retired = {})
+      kind = RenderDest.destination_kind(path)
+      return false if kind == :missing
+
+      RenderDest.fail_if_symlink!(path, display)
+      unless kind == :regular
+        raise Error.render("refusing to read `#{display}`; destination is not a regular file")
+      end
+      existing = RenderDest.decode_utf8(RenderDest.read_regular_bytes(path, display), display)
+      existing == reconcile_content(existing, fresh, retired)
+    end
+
+    def retired_span_checksums(previous_lockfile, target)
+      current_ids = target.managed_spans.to_h { |span| [span.id, true] }
+      Array(previous_lockfile&.managed_span).filter_map do |span|
+        next unless span.target == target.path
+        next if current_ids[span.id]
+
+        [span.id, span.ideal_checksum]
+      end.to_h
+    end
+
+    def reject_managed_span_conflicts!(project, rendered, previous_lockfile)
+      active_by_target = rendered.to_h do |target|
+        [target.path, target.managed_spans.to_h { |span| [span.id, true] }]
+      end
+      Array(previous_lockfile.managed_span).group_by(&:target).each do |target_path, spans|
+        active = active_by_target[target_path]
+        next unless active
+
+        PathSafety.validate_destination_path!(target_path)
+        RenderDest.ensure_safe_destination_ancestors!(project.project_root, target_path, target_path)
+        path = File.join(project.project_root, target_path)
+        next unless File.file?(path)
+
+        content = RenderDest.decode_utf8(RenderDest.read_regular_bytes(path, target_path), target_path)
+        bodies = RenderPatch.managed_bodies(RenderPatch.split_segments(content))
+        spans.each do |span|
+          next unless active[span.id] && bodies.key?(span.id)
+          next if Hashing.checksum_managed_span_content(bodies[span.id]) == span.ideal_checksum
+
+          raise Error.render(
+            "conflict: managed span `#{span.id}` in `#{target_path}` was edited " \
+            "(`#{span.package}::#{span.export}`)"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/pray/resolve.rb

@@ -100,6 +100,7 @@ module Pray
       raise Error.resolution(local_errors.join("\n")) unless local_errors.empty?
 
       ResolveDeps.reject_dependency_cycles(packages)
+      ResolveDeps.validate_optional_referrals(packages)
       source_revisions = git_sources.revisions
 
       ResolvedProject.new(

data/lib/pray/resolve_deps.rb

@@ -7,12 +7,29 @@ module Pray
     def reject_dependency_cycles(packages)
       edges = {}
       packages.each do |package|
-        edges[package.declaration.name] = package.spec.dependencies.map(&:name)
+        edges[package.declaration.name] = package.spec.dependencies.reject(&:optional).map(&:name)
       end
       cycle = DependencyGraph.find_dependency_cycle(edges)
       return unless cycle
 
       raise Error.resolution("dependency cycle detected: #{cycle.join(" -> ")}")
     end
+
+    def validate_optional_referrals(packages)
+      packages_by_name = packages.to_h { |package| [package.declaration.name, package] }
+      packages.each do |package|
+        package.spec.dependencies.select(&:optional).each do |dependency|
+          target = packages_by_name[dependency.name]
+          next unless target
+
+          target.spec.satisfy_constraint!(dependency.constraint)
+        rescue Error
+          raise Error.resolution(
+            "optional referral #{package.declaration.name} -> #{dependency.name} requires " \
+              "#{dependency.constraint}, but selected version is #{target.spec.recorded_version}"
+          )
+        end
+      end
+    end
   end
 end

data/lib/pray/url_redaction.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Pray
+  module UrlRedaction
+    module_function
+
+    def redact_userinfo(url)
+      uri = URI(url)
+      return url unless uri.user || uri.password
+
+      uri.user = "***"
+      uri.password = nil
+      uri.to_s
+    rescue URI::InvalidURIError
+      url
+    end
+  end
+end

data/lib/pray/verify.rb

@@ -36,11 +36,16 @@ module Pray
 
     def drift_project(project, lockfile)
       report, rendered_targets, fresh_targets = collect_verification_report(project, lockfile)
-      fresh_targets.each do |path, fresh_content|
-        normalized_fresh = Hashing.normalize_line_endings(fresh_content)
+      fresh_targets.each do |path, fresh_target|
         on_disk = rendered_targets[path]
-        on_disk = Hashing.normalize_line_endings(on_disk) if on_disk
-        unless on_disk == normalized_fresh
+        retired = RenderReconcile.retired_span_checksums(lockfile, fresh_target)
+        expected = if on_disk
+          RenderReconcile.reconcile_content(on_disk, fresh_target.content, retired)
+        else
+          fresh_target.content
+        end
+        normalized_on_disk = Hashing.normalize_line_endings(on_disk) if on_disk
+        unless normalized_on_disk == Hashing.normalize_line_endings(expected)
           report.findings << VerificationFinding.new(
             kind: "renderer_drift",
             message: "#{path} differs from fresh render"
@@ -64,7 +69,7 @@ module Pray
     def collect_verification_report(project, lockfile)
       report = VerificationReport.new
       rendered_targets = {}
-      fresh_targets = Render.render_project(project).to_h { |target| [target.path, target.content] }
+      fresh_targets = Render.render_project(project).to_h { |target| [target.path, target] }
 
       if project.manifest_hash != lockfile.manifest_hash
         report.findings << VerificationFinding.new(
@@ -104,6 +109,7 @@ module Pray
       end
 
       target_spans = lockfile.managed_span.group_by(&:target)
+      fresh_targets.each_key { |target_path| target_spans[target_path] ||= [] }
       target_spans.each do |target_path, spans|
         absolute_path = File.join(project.project_root, target_path)
         unless File.exist?(absolute_path)
@@ -135,7 +141,7 @@ module Pray
             end
           end
         end
-        fresh_lines = fresh_targets[target_path]&.lines(chomp: true)
+        fresh_lines = fresh_targets[target_path]&.content&.lines(chomp: true)
         summary = VerifyPosition.summarize_position_drift(
           target_path,
           spans,
@@ -177,7 +183,7 @@ module Pray
 
         VerificationFinding.new(
           kind: "orphan_marker",
-          message: "`#{target_path}` contains marker `#{marker_id}` that is not tracked in `Prayfile.lock`. Remove the marker or run `pray install` to reconcile."
+          message: "`#{target_path}` contains marker `#{marker_id}` that is not tracked in `Prayfile.lock`. Inspect and remove the block explicitly."
         )
       end
     end

data/lib/pray/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Pray
-  VERSION = "1.25.0"
-  GENERATED_BY = "pray 1.25.0"
+  VERSION = "1.26.1"
+  GENERATED_BY = "pray 1.26.1"
 end

data/lib/pray.rb

@@ -15,6 +15,7 @@ require_relative "pray/destination"
 require_relative "pray/manifest"
 require_relative "pray/format_serialize"
 require_relative "pray/format_manifest"
+require_relative "pray/package_relation"
 require_relative "pray/package_spec"
 require_relative "pray/package_spec_paths"
 require_relative "pray/package_spec_version"
@@ -52,6 +53,7 @@ require_relative "pray/render_content"
 require_relative "pray/render_managed"
 require_relative "pray/render"
 require_relative "pray/render_dest"
+require_relative "pray/render_reconcile"
 require_relative "pray/transaction"
 require_relative "pray/render_layout"
 require_relative "pray/verify_position"
@@ -60,9 +62,11 @@ require_relative "pray/verify"
 require_relative "pray/verify_locked_dest"
 require_relative "pray/resource_limits"
 require_relative "pray/http_body"
+require_relative "pray/url_redaction"
 require_relative "pray/registry_install"
 require_relative "pray/registry_integrity"
 require_relative "pray/registry"
+require_relative "pray/registry_search"
 require_relative "pray/derived_metadata"
 require_relative "pray/archive_unpack"
 require_relative "pray/archive"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pray-cli
 version: !ruby/object:Gem::Version
-  version: 1.25.0
+  version: 1.26.1
 platform: ruby
 authors:
 - Andrei Makarov
@@ -115,6 +115,7 @@ files:
 - lib/pray/cli/commands/init_prayer_manifest.rb
 - lib/pray/cli/commands/meta.rb
 - lib/pray/cli/commands/packages.rb
+- lib/pray/cli/commands/search.rb
 - lib/pray/cli/commands/trust.rb
 - lib/pray/cli/commands/update_latest.rb
 - lib/pray/cli/commands/workflow.rb
@@ -161,6 +162,7 @@ files:
 - lib/pray/manifest_parser_helpers.rb
 - lib/pray/manifest_parser_publish.rb
 - lib/pray/materialize.rb
+- lib/pray/package_relation.rb
 - lib/pray/package_spec.rb
 - lib/pray/package_spec_paths.rb
 - lib/pray/package_spec_render.rb
@@ -176,6 +178,7 @@ files:
 - lib/pray/registry_install.rb
 - lib/pray/registry_integrity.rb
 - lib/pray/registry_paths.rb
+- lib/pray/registry_search.rb
 - lib/pray/render.rb
 - lib/pray/render_content.rb
 - lib/pray/render_dest.rb
@@ -183,6 +186,7 @@ files:
 - lib/pray/render_managed.rb
 - lib/pray/render_patch.rb
 - lib/pray/render_project.rb
+- lib/pray/render_reconcile.rb
 - lib/pray/resolve.rb
 - lib/pray/resolve_context.rb
 - lib/pray/resolve_deps.rb
@@ -216,6 +220,7 @@ files:
 - lib/pray/upstream_merge.rb
 - lib/pray/upstream_plan.rb
 - lib/pray/upstream_refresh.rb
+- lib/pray/url_redaction.rb
 - lib/pray/verify.rb
 - lib/pray/verify_locked_dest.rb
 - lib/pray/verify_position.rb