pray-cli 1.12.0 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68bb4b372a260d62b3cfce3bdc74811b85c2cff0446adf0bd551065b0214fbb1
-  data.tar.gz: 3bfc7db4cd0b6227a554199f6c8cbf8fd2e4c1e2715be48f7d102903e7a26bb2
+  metadata.gz: 55a5d9fd2741f9ecd2d6d41c18acf6c7358b8bedb15e874d3686ce4ac88c7898
+  data.tar.gz: 489b7b073d8194c8f90fbbbab0b757804cc05a9ee309d7e596ce8a894ead1666
 SHA512:
-  metadata.gz: '095670c5e563280d0610d1eefa2ef2a825e2676aaff537c54eda62ad97ee11a631dc5328648614bfdd69b6dca744c7377fea9fef3b5cc0c4d3341ad511adb4be'
-  data.tar.gz: a820d50b02742e1b8a7c79fe9075f48e6ae7c90f3551dba8e8fbb37c7ed28d2e7089ac9fe81b82c2db7e8bf7d20f926840084d841e30bb3d2a733efa68e2892f
+  metadata.gz: 005a627e411946e40ae7b782feb62737b8d49a3eef411fda42ecd90c705c252414e504f231f94f24f5e687b035562233ba68f424abe49d2d541700b281493406
+  data.tar.gz: 80f998bf51a0fa32bf40d36b38f9a1101affdd988a0cb938e34b637a8225d3903d5c98bb217a88dab2ceb99849cd11957748d22d612e4f593f082f0d40122132

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 1.13.0 (2026-09-08)
+
+- Record and verify package upstream pins in `.prayspec` and `Prayfile.lock`. Refuse path-fork updates until this CLI can refresh the path tree safely (RFC 0114).
+
+## 1.12.1 (2026-09-08)
+
+- Refresh a locked git catalog during `pray install` when a newly declared package is missing from the pinned revision, and name that revision with `pray update` if it is still missing.
+
 ## 1.12.0 (2026-09-07)
 
 - Speed up planning for large package trees and reuse the resolved lock during installation.

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

@@ -100,6 +100,8 @@ module Pray
           raise Error.manifest("package #{package} not found")
         end
       end
+      current = resolve_current_project(ResolveOptions.new(offline: offline))
+      Upstream.ensure_update_supported!(current.packages, package)
       install_command({locked: false, frozen: false, offline: offline, refresh: true})
     end
 

data/lib/pray/git_refresh.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Pray
+  module GitRefresh
+    module_function
+
+    def resolution_may_benefit_from_git_source_refresh?(error)
+      error.category == :resolution && catalog_miss_message?(error.message)
+    end
+
+    def catalog_miss_message?(message)
+      message.include?("no registry version") ||
+        message.include?("not found in distribution") ||
+        message.include?("not found in git source") ||
+        message.include?("v1/packages/")
+    end
+
+    def annotate_missing_git_catalog(error, package_name:, source_name:, revision:)
+      return error unless error.category == :resolution
+      return error if revision.to_s.empty?
+      return error unless catalog_miss_message?(error.message)
+      return error if error.message.include?("not found in git source")
+
+      Error.resolution(
+        "package #{package_name} was not found in git source #{source_name} at revision #{revision}. " \
+        "Run `pray update` to advance the source pin."
+      )
+    end
+
+    def annotate_failed_refresh(lockfile_path, error)
+      return error unless error.category == :resolution
+      return error unless catalog_miss_message?(error.message)
+
+      pins = locked_git_revision_guidance(lockfile_path)
+      return error if pins.nil?
+
+      package = package_name_from_catalog_miss(error.message) || "the declared package"
+      Error.resolution(
+        "package #{package} was not found in locked git source (#{pins}). " \
+        "Run `pray update` to advance the source pin."
+      )
+    end
+
+    def locked_git_revision_guidance(lockfile_path)
+      return unless File.exist?(lockfile_path)
+
+      lockfile = LockfileIO.read_lockfile(lockfile_path)
+      pins = lockfile.source.filter_map do |source|
+        next unless source.kind == "git" && source.revision
+
+        "#{source.name} at #{source.revision}"
+      end
+      pins.empty? ? nil : pins.join(", ")
+    rescue Error
+      nil
+    end
+
+    def package_name_from_catalog_miss(message)
+      rest = message.delete_prefix("package ")
+      return if rest == message
+
+      ending = rest.index(" was not found") || rest.index(" not found")
+      return unless ending
+
+      name = rest[0, ending].strip
+      name.empty? ? nil : name
+    end
+  end
+end

data/lib/pray/invocation.rb

@@ -49,10 +49,14 @@ module Pray
       if allow_git_refresh_fallback &&
           !options.offline &&
           !options.refresh &&
-          Resolve.resolution_may_benefit_from_git_source_refresh?(error)
+          GitRefresh.resolution_may_benefit_from_git_source_refresh?(error)
         refreshed = options.dup
         refreshed.refresh = true
-        resolve_current_project(refreshed)
+        begin
+          resolve_current_project(refreshed)
+        rescue Error => retry_error
+          raise GitRefresh.annotate_failed_refresh(lockfile_path, retry_error)
+        end
       else
         raise
       end

data/lib/pray/lockfile.rb

@@ -8,14 +8,15 @@ module Pray
   LockSource = Struct.new(:name, :kind, :url, :revision, :host_key_fingerprint)
   LockedPackage = Struct.new(
     :name, :version, :source, :path, :tree_hash, :artifact_hash, :artifact,
-    :exports, :dependencies, :signer_fingerprint
+    :exports, :dependencies, :signer_fingerprint, :upstream
   ) do
-    def initialize(exports: [], dependencies: [], signer_fingerprint: nil, source: nil, **kwargs)
-      super(**kwargs, exports: exports, dependencies: dependencies, signer_fingerprint: signer_fingerprint, source: source)
+    def initialize(exports: [], dependencies: [], signer_fingerprint: nil, source: nil, upstream: nil, **kwargs)
+      super(**kwargs, exports: exports, dependencies: dependencies, signer_fingerprint: signer_fingerprint, source: source, upstream: upstream)
     end
   end
 
   LockedTarget = Struct.new(:name, :outputs)
+  LockedUpstream = Struct.new(:name, :version, :source, :tree_hash, :artifact_hash, keyword_init: true)
   ManagedSpanRecord = Struct.new(
     :id, :target, :open_line, :close_line, :ideal_checksum, :package, :export,
     :source_checksum, :silenced
@@ -98,6 +99,7 @@ module Pray
       }
       hash["source"] = entry.source unless entry.source.nil?
       hash["signer_fingerprint"] = entry.signer_fingerprint if entry.signer_fingerprint
+      hash["upstream"] = Upstream.to_lock_hash(entry.upstream) if entry.upstream
       hash
     end
 
@@ -185,7 +187,8 @@ module Pray
             artifact: normalize_lockfile_artifact(project_root, package.artifact, package.root),
             exports: package.selected_exports,
             dependencies: package.spec.dependencies.map(&:name),
-            signer_fingerprint: package.signer_fingerprint
+            signer_fingerprint: package.signer_fingerprint,
+            upstream: package.upstream
           )
         end,
         target: manifest_targets.map { |target| LockedTarget.new(name: target.name, outputs: target.outputs) },
@@ -224,7 +227,8 @@ module Pray
             artifact: entry["artifact"],
             exports: entry["exports"] || [],
             dependencies: entry["dependencies"] || [],
-            signer_fingerprint: entry["signer_fingerprint"]
+            signer_fingerprint: entry["signer_fingerprint"],
+            upstream: Upstream.from_lock_hash(entry["upstream"])
           )
         end,
         target: Array(data["target"]).map { |entry| LockedTarget.new(name: entry["name"], outputs: entry["outputs"] || []) },

data/lib/pray/lockfile_serialize.rb

@@ -66,6 +66,25 @@ module Pray
       lines << "exports = #{format_string_array(entry.exports)}"
       lines << "dependencies = #{format_string_array(entry.dependencies)}"
       lines << "signer_fingerprint = #{format_string(entry.signer_fingerprint)}" if entry.signer_fingerprint
+      if entry.upstream
+        lines << ""
+        lines << "[package.upstream]"
+        append_scalars(
+          lines,
+          [
+            ["name", entry.upstream.name],
+            ["version", entry.upstream.version]
+          ].tap do |scalars|
+            scalars << ["source", entry.upstream.source] unless entry.upstream.source.nil?
+            scalars.concat(
+              [
+                ["tree_hash", entry.upstream.tree_hash],
+                ["artifact_hash", entry.upstream.artifact_hash]
+              ]
+            )
+          end
+        )
+      end
       lines
     end
 

data/lib/pray/materialize.rb

@@ -34,10 +34,17 @@ module Pray
         if allow_git_refresh_fallback &&
             !offline &&
             !refresh &&
-            Resolve.resolution_may_benefit_from_git_source_refresh?(error)
+            GitRefresh.resolution_may_benefit_from_git_source_refresh?(error)
           refreshed = options.dup
           refreshed.refresh = true
-          Resolve.resolve_project_in_context(manifest_path, project_root, refreshed)
+          begin
+            Resolve.resolve_project_in_context(manifest_path, project_root, refreshed)
+          rescue Error => retry_error
+            raise GitRefresh.annotate_failed_refresh(
+              default_lockfile_path(project_root),
+              retry_error
+            )
+          end
         else
           raise
         end

data/lib/pray/package_spec.rb

@@ -9,17 +9,18 @@ module Pray
   PackageSkill = Struct.new(:path, :summary)
   PackageTemplate = Struct.new(:path, :summary)
   PackageDependency = Struct.new(:name, :constraint, :optional)
+  PackageUpstream = Struct.new(:name, :constraint, keyword_init: true)
 
   PackageSpec = Struct.new(
     :name, :version, :summary, :description, :authors, :license, :homepage,
     :source_code_uri, :changelog_uri, :prayfile_version, :files, :exports,
-    :skills, :templates, :adapters, :targets, :dependencies, :metadata
+    :skills, :templates, :adapters, :targets, :dependencies, :metadata, :upstream
   ) do
     def initialize(
       name: "", version: "", summary: nil, description: nil, authors: [], license: nil,
       homepage: nil, source_code_uri: nil, changelog_uri: nil, prayfile_version: nil,
       files: [], exports: {}, skills: {}, templates: {}, adapters: {}, targets: [],
-      dependencies: [], metadata: {}
+      dependencies: [], metadata: {}, upstream: nil
     )
       super
     end
@@ -90,6 +91,13 @@ module Pray
         )
       end
 
+      def parse_upstream(rest)
+        values, _keywords = parse_call(rest)
+        name = string_from_value(values.first)
+        constraint = values[1] ? string_from_value(values[1]) : "*"
+        PackageUpstream.new(name: name, constraint: constraint)
+      end
+
       def parse_exports(value)
         map = Literal.parse_literal_map(value)
         exports = {}
@@ -208,6 +216,10 @@ module Pray
           spec.dependencies << parse_dependency(Regexp.last_match(1), false)
         when /\Aspec\.add_optional_dependency (.+)\z/
           spec.dependencies << parse_dependency(Regexp.last_match(1), true)
+        when /\Aspec\.upstream (.+)\z/
+          raise Error.parse("prayspec", "upstream may only be declared once") if spec.upstream
+
+          spec.upstream = parse_upstream(Regexp.last_match(1))
         when /\Aspec\.(.+) = (.+)\z/
           apply_assignment(spec, Regexp.last_match(1).strip, Regexp.last_match(2).strip)
         else

data/lib/pray/resolve.rb

@@ -13,7 +13,7 @@ module Pray
   ResolvedPackage = Struct.new(
     :declaration, :root, :spec, :tree_hash, :artifact_hash, :artifact,
     :selected_exports, :source_checksum, :export_bodies, :skill_files,
-    :signer_fingerprint, :registry_latest_version
+    :signer_fingerprint, :registry_latest_version, :upstream
   )
 
   ResolvedLocalFile = Struct.new(
@@ -75,7 +75,7 @@ module Pray
           user_config,
           declaration,
           lockfile_hints,
-          offline: options.offline
+          options: options
         )
         if seen[package.declaration.name]
           raise Error.resolution("duplicate package declaration: #{package.declaration.name}")
@@ -127,14 +127,21 @@ module Pray
           !refresh &&
           resolution_may_benefit_from_git_source_refresh?(error)
         refreshed = ResolveOptions.new(offline: offline, refresh: true, environment: environment)
-        resolve_project_with_options(manifest_path, refreshed)
+        begin
+          resolve_project_with_options(manifest_path, refreshed)
+        rescue Error => retry_error
+          raise GitRefresh.annotate_failed_refresh(
+            File.join(File.dirname(File.expand_path(manifest_path)), "Prayfile.lock"),
+            retry_error
+          )
+        end
       else
         raise
       end
     end
 
     def resolution_may_benefit_from_git_source_refresh?(error)
-      error.category == :resolution && error.message.include?("no registry version")
+      GitRefresh.resolution_may_benefit_from_git_source_refresh?(error)
     end
 
     def missing_local_embed_guidance(path)
@@ -142,9 +149,10 @@ module Pray
         "Create the file or remove the entry from Prayfile, then run `pray install`."
     end
 
-    def resolve_package(project_root, sources, git_sources, user_config, declaration, lockfile, offline: false)
+    def resolve_package(project_root, sources, git_sources, user_config, declaration, lockfile, offline: false, options: nil)
+      options ||= ResolveOptions.new(offline: offline)
       root, registry_latest_version = resolve_package_root_with_metadata(
-        project_root, sources, git_sources, user_config, declaration, lockfile, offline: offline
+        project_root, sources, git_sources, user_config, declaration, lockfile, offline: options.offline
       )
       spec_path = find_prayspec_file(root)
       spec_text = File.read(spec_path)
@@ -178,7 +186,10 @@ module Pray
         export_bodies: export_bodies,
         skill_files: skill_files,
         signer_fingerprint: nil,
-        registry_latest_version: registry_latest_version
+        registry_latest_version: registry_latest_version,
+        upstream: Upstream.lock_path(
+          project_root, sources, git_sources, user_config, declaration, spec, lockfile, options
+        )
       )
     end
 
@@ -228,14 +239,23 @@ module Pray
           clone_url = source.url.delete_prefix("git+")
           distribution_root = GitSources.resolve_distribution_root(checkout.cache_directory, checkout.subdir)
           source_key = checkout.revision.to_s.empty? ? clone_url : "#{clone_url}@#{checkout.revision}"
-          resolved = Registry.resolve_local_registry_package_root(
-            project_root,
-            source_key,
-            distribution_root,
-            declaration,
-            preferred_version: lockfile_preferred_version(lockfile, declaration.name),
-            offline: offline
-          )
+          resolved = begin
+            Registry.resolve_local_registry_package_root(
+              project_root,
+              source_key,
+              distribution_root,
+              declaration,
+              preferred_version: lockfile_preferred_version(lockfile, declaration.name),
+              offline: offline
+            )
+          rescue Error => error
+            raise GitRefresh.annotate_missing_git_catalog(
+              error,
+              package_name: declaration.name,
+              source_name: source.name,
+              revision: checkout.revision
+            )
+          end
           return [resolved.root, resolved.registry_latest_version]
         else
           raise Error.unsupported("source kind #{source.kind} not implemented yet")

data/lib/pray/upstream.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Pray
+  module Upstream
+    module_function
+
+    def ensure_update_supported!(packages, selected = nil)
+      unsupported = packages.find do |package|
+        package.declaration.path && package.spec.upstream &&
+          (selected.nil? || package.declaration.name == selected)
+      end
+      return unless unsupported
+
+      raise Error.unsupported(
+        "this installation cannot refresh upstream package #{unsupported.declaration.name}; " \
+        "install pray with Cargo and retry"
+      )
+    end
+
+    def to_lock_hash(entry)
+      hash = {
+        "name" => entry.name,
+        "version" => entry.version,
+        "tree_hash" => entry.tree_hash,
+        "artifact_hash" => entry.artifact_hash
+      }
+      hash["source"] = entry.source unless entry.source.nil?
+      hash
+    end
+
+    def from_lock_hash(entry)
+      return nil if entry.nil?
+
+      LockedUpstream.new(
+        name: entry["name"],
+        version: entry["version"],
+        source: entry["source"],
+        tree_hash: entry["tree_hash"],
+        artifact_hash: entry["artifact_hash"]
+      )
+    end
+
+    def lock_path(project_root, sources, git_sources, user_config, declaration, spec, lockfile, options)
+      return nil unless spec.upstream
+      if spec.name == spec.upstream.name
+        raise Error.resolution("package #{spec.name} cannot use itself as upstream")
+      end
+      return nil unless declaration.path
+
+      refresh = options.ignore_locked_versions || options.unlocked_packages.include?(declaration.name)
+      locked = lockfile&.package&.find { |entry| entry.name == declaration.name }&.upstream
+      name, constraint, source = resolution_input(declaration, spec, sources, locked, refresh)
+      resolved = Resolve.resolve_package(
+        project_root,
+        sources,
+        git_sources,
+        user_config,
+        ManifestPackage.new(
+          name: name,
+          constraint: constraint,
+          source: source
+        ),
+        lockfile,
+        options: options
+      )
+      resolved_upstream = LockedUpstream.new(
+        name: name,
+        version: resolved.spec.version,
+        source: source,
+        tree_hash: resolved.tree_hash,
+        artifact_hash: resolved.artifact_hash
+      )
+      ensure_locked_match!(locked, resolved_upstream) if !refresh && locked
+      resolved_upstream
+    end
+
+    def resolution_input(declaration, spec, sources, locked, refresh)
+      if locked && !refresh
+        if locked.name != spec.upstream.name
+          raise Error.integrity(
+            "locked upstream name mismatch for #{declaration.name}: " \
+            "expected #{locked.name}, found #{spec.upstream.name}"
+          )
+        end
+        return [locked.name, "= #{locked.version}", locked.source]
+      end
+
+      name = spec.upstream.name
+      source = ResolveSource.implied_source_name(ManifestPackage.new(name: name), sources)
+      [name, spec.upstream.constraint, source]
+    end
+
+    def ensure_locked_match!(locked, resolved)
+      if locked.name != resolved.name || locked.version != resolved.version
+        raise Error.integrity("locked upstream identity mismatch")
+      end
+      raise Error.integrity("locked upstream source mismatch") if locked.source != resolved.source
+      raise Error.integrity("locked upstream tree hash mismatch") if locked.tree_hash != resolved.tree_hash
+      if locked.artifact_hash != resolved.artifact_hash
+        raise Error.integrity("locked upstream artifact hash mismatch")
+      end
+    end
+  end
+end

data/lib/pray/version.rb

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

data/lib/pray.rb

@@ -22,7 +22,9 @@ require_relative "pray/resolve_context"
 require_relative "pray/resolve_source"
 require_relative "pray/resolve_exports"
 require_relative "pray/invocation"
+require_relative "pray/git_refresh"
 require_relative "pray/resolve"
+require_relative "pray/upstream"
 require_relative "pray/compose_dest"
 require_relative "pray/render_patch"
 require_relative "pray/render"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pray-cli
 version: !ruby/object:Gem::Version
-  version: 1.12.0
+  version: 1.13.0
 platform: ruby
 authors:
 - Andrei Makarov
@@ -130,6 +130,7 @@ files:
 - lib/pray/error.rb
 - lib/pray/format_manifest.rb
 - lib/pray/format_serialize.rb
+- lib/pray/git_refresh.rb
 - lib/pray/git_sources.rb
 - lib/pray/hashing.rb
 - lib/pray/http_body.rb
@@ -179,6 +180,7 @@ files:
 - lib/pray/trust.rb
 - lib/pray/trust_feed.rb
 - lib/pray/trust_ops.rb
+- lib/pray/upstream.rb
 - lib/pray/verify.rb
 - lib/pray/verify_position.rb
 - lib/pray/verify_provisioned.rb