pray-cli 1.9.1 → 1.10.0

data/lib/pray/package_spec.rb

@@ -24,6 +24,25 @@ module Pray
       super
     end
 
+    def deprecation_warnings
+      keywords = []
+      keywords << "spec.skills" unless skills.nil? || skills.empty?
+      keywords << "skill" if (exports || {}).values.any? { |export| export.kind == "skill" }
+      Manifest.new(deprecated_keywords: keywords).deprecation_warnings
+    end
+
+    def self.warn_resolved_deprecations(packages)
+      seen = {}
+      packages.each do |package|
+        package.spec.deprecation_warnings.each do |warning|
+          next if seen[warning]
+
+          seen[warning] = true
+          warn(warning)
+        end
+      end
+    end
+
     def canonicalized
       dup.tap do |copy|
         copy.files = files.sort

data/lib/pray/path_safety.rb

@@ -37,5 +37,48 @@ module Pray
 
       cleaned
     end
+
+    def validate_archive_member_path!(path)
+      cleaned = path.to_s.delete_prefix("./")
+      if cleaned.empty? || Pathname.new(cleaned).absolute? || cleaned.start_with?("/")
+        raise Error.integrity("package path must be relative: #{path}")
+      end
+
+      cleaned.split("/").each do |part|
+        next if part.empty? || part == "."
+
+        if part == ".." || part.include?("\0")
+          raise Error.integrity("package path escapes package root: #{path}")
+        end
+      end
+
+      cleaned
+    end
+
+    def validate_project_relative_path!(value)
+      path = value.to_s.strip
+      windows_absolute = path.match?(/\A(?:[A-Za-z]:[\\\/]|[\\\/]{2})/)
+      if path.empty? || Pathname.new(path).absolute? || windows_absolute
+        raise Error.manifest("project path must be repository-relative: #{value}")
+      end
+      parts = path.tr("\\", "/").split("/")
+      if parts.include?("..") || path.include?("\0")
+        raise Error.manifest("project path escapes repository root: #{value}")
+      end
+      if parts.all? { |part| part.empty? || part == "." }
+        raise Error.manifest("project path must be repository-relative: #{value}")
+      end
+
+      path
+    end
+
+    def validate_destination_path!(value)
+      path = value.to_s.strip
+      if path.start_with?("~")
+        raise Error.manifest("project path must be repository-relative: #{value}")
+      end
+
+      validate_project_relative_path!(value)
+    end
   end
 end

data/lib/pray/plan.rb

@@ -15,7 +15,9 @@ module Pray
         package_lines: package_summary_lines(previous_lockfile, lockfile, project),
         lockfile: lockfile_change_status(lockfile_path, lockfile),
         targets: rendered.map { |target| target_change(project, target) },
-        provisioned: Render.planned_provisioned_files(project).map { |file| provisioned_change(project, file) },
+        provisioned: Render.planned_provisioned_files(project).map do |file|
+          provisioned_change(project, file, previous_lockfile)
+        end,
         warnings: []
       )
     end
@@ -68,16 +70,8 @@ module Pray
       [target.path, change]
     end
 
-    def provisioned_change(project, file)
-      destination = File.join(project.project_root, file.path)
-      change = if !File.exist?(destination)
-        "write"
-      elsif FileUtils.compare_file(destination, file.source)
-        "unchanged"
-      else
-        "update"
-      end
-      [file.path, change]
+    def provisioned_change(project, file, previous_lockfile)
+      [file.path, RenderDest.destination_status(project, file, previous_lockfile).to_s]
     end
   end
 end

data/lib/pray/registry.rb

@@ -6,6 +6,7 @@ require "uri"
 require "fileutils"
 require "pathname"
 require_relative "path_safety"
+require_relative "http_body"
 
 module Pray
   RegistryPackageVersion = Struct.new(
@@ -33,12 +34,15 @@ module Pray
   )
 
   module Registry
+    extend RegistryIntegrity
+
     module_function
 
     def resolve_registry_package_root(project_root, source_url, declaration, preferred_version: nil, offline: false)
       metadata = fetch_package_metadata(source_url, declaration.name)
       registry_latest_version = registry_latest_version_label(metadata)
       selected = select_package_version(metadata, declaration.constraint, preferred_version)
+      require_integrity_fields!(declaration.name, selected)
       cache_directory = registry_cache_directory(
         project_root,
         source_url,
@@ -57,11 +61,10 @@ module Pray
 
       raise Error.resolution(offline_package_error(declaration.name, selected.version)) if offline
 
-      FileUtils.rm_rf(cache_directory) if File.exist?(cache_directory)
-      FileUtils.mkdir_p(cache_directory)
-
       artifact_bytes = read_artifact_bytes(source_url, selected.artifact)
-      validate_and_unpack(cache_directory, declaration, selected, artifact_bytes, source_url: source_url)
+      RegistryInstall.install_artifact_to_cache(
+        cache_directory, declaration, selected, artifact_bytes, source_url: source_url
+      )
 
       RegistryPackageResolution.new(
         root: cache_directory,
@@ -83,6 +86,7 @@ module Pray
       metadata = parse_metadata(File.read(metadata_path, encoding: "UTF-8"))
       registry_latest_version = registry_latest_version_label(metadata)
       selected = select_package_version(metadata, declaration.constraint, preferred_version)
+      require_integrity_fields!(declaration.name, selected)
       cache_directory = registry_cache_directory(
         project_root,
         source_key,
@@ -101,11 +105,10 @@ module Pray
 
       raise Error.resolution(offline_package_error(declaration.name, selected.version)) if offline
 
-      FileUtils.rm_rf(cache_directory) if File.exist?(cache_directory)
-      FileUtils.mkdir_p(cache_directory)
-
       artifact_bytes = read_local_artifact_bytes(source_root, selected.artifact)
-      validate_and_unpack(cache_directory, declaration, selected, artifact_bytes, source_url: source_root)
+      RegistryInstall.install_artifact_to_cache(
+        cache_directory, declaration, selected, artifact_bytes, source_url: source_root
+      )
 
       RegistryPackageResolution.new(
         root: cache_directory,
@@ -177,51 +180,13 @@ module Pray
       Gem::Version.new(left) <=> Gem::Version.new(right)
     end
 
-    def validate_and_unpack(cache_directory, declaration, selected, artifact_bytes, source_url: nil)
-      if selected.artifact_hash
-        artifact_hash = Hashing.sha256_prefixed(artifact_bytes)
-        if artifact_hash != selected.artifact_hash
-          raise Error.integrity(
-            "package artifact hash mismatch for #{declaration.name} #{selected.version}"
-          )
-        end
-      end
-
-      verify_registry_signature!(declaration, selected, artifact_bytes)
-      Trust.verify_publisher_fingerprint!(source_url, selected) if source_url
-
-      Archive.unpack_praypkg(artifact_bytes, cache_directory)
-      spec_path = Resolve.find_prayspec_file(cache_directory)
-      spec = Pray.parse_package_spec(File.read(spec_path)).canonicalized
-      if spec.name != declaration.name
-        raise Error.resolution(
-          "package path #{cache_directory.inspect} declares #{spec.name.inspect}, expected #{declaration.name.inspect}"
-        )
-      end
-      if spec.version != selected.version
-        raise Error.resolution(
-          "package #{declaration.name} version #{spec.version} does not match registry version #{selected.version}"
-        )
-      end
-      if selected.tree_hash
-        actual_tree_hash = spec.tree_hash_for_root(cache_directory)
-        if actual_tree_hash != selected.tree_hash
-          raise Error.integrity(
-            "package tree hash mismatch for #{declaration.name} #{selected.version}"
-          )
-        end
-      end
-    end
-
     def read_local_artifact_bytes(source_root, artifact)
-      if artifact.start_with?("http://", "https://")
-        return http_get(artifact)
-      end
       if artifact.start_with?("file://")
         path = PathSafety.join_under_root(source_root, artifact.delete_prefix("file://"))
         raise Error.resolution("package artifact path escapes distribution root") unless path
         return File.binread(path)
       end
+      reject_absolute_artifact!(artifact)
 
       path = PathSafety.join_under_root(source_root, artifact)
       raise Error.resolution("package artifact path escapes distribution root") unless path
@@ -233,17 +198,14 @@ module Pray
     def read_artifact_bytes(source_url, artifact)
       return read_local_artifact_bytes(source_url, artifact) if local_source?(source_url)
 
+      reject_absolute_artifact!(artifact)
       http_get(join_url(source_url, artifact))
     end
 
-    def cache_ready?(cache_directory, selected)
-      return false unless File.directory?(cache_directory)
+    def reject_absolute_artifact!(artifact)
+      return unless artifact.match?(%r{\A[a-z][a-z0-9+.-]*:}i)
 
-      spec_path = Resolve.find_prayspec_file(cache_directory)
-      spec = Pray.parse_package_spec(File.read(spec_path)).canonicalized
-      spec.version == selected.version
-    rescue Errno::ENOENT, Errno::ENOTDIR, SystemCallError
-      false
+      raise Error.integrity("remote artifact path must be relative: #{artifact}")
     end
 
     def registry_metadata_path(source_root, package_name)
@@ -301,12 +263,7 @@ module Pray
 
     def http_get(url)
       uri = URI(url)
-      response = http_request(uri) { |http| http.get(uri.request_uri) }
-      unless response.is_a?(Net::HTTPSuccess)
-        raise Error.resolution("HTTP request failed for #{url}: #{response.code}")
-      end
-
-      response.body
+      bounded_http_exchange(uri, Net::HTTP::Get.new(uri), "HTTP request failed for #{url}")
     end
 
     def http_put(url, content_type, body)
@@ -314,12 +271,7 @@ module Pray
       request = Net::HTTP::Put.new(uri)
       request["Content-Type"] = content_type
       request.body = body
-      response = http_request(uri) { |http| http.request(request) }
-      unless response.is_a?(Net::HTTPSuccess)
-        raise Error.resolution("HTTP upload failed for #{url}: #{response.code}")
-      end
-
-      response.body
+      bounded_http_exchange(uri, request, "HTTP upload failed for #{url}")
     end
 
     def http_post(url, content_type, body)
@@ -327,12 +279,23 @@ module Pray
       request = Net::HTTP::Post.new(uri)
       request["Content-Type"] = content_type
       request.body = body
-      response = http_request(uri) { |http| http.request(request) }
-      unless response.is_a?(Net::HTTPSuccess)
-        raise Error.resolution("HTTP request failed for #{url}: #{response.code}")
+      bounded_http_exchange(uri, request, "HTTP request failed for #{url}")
+    end
+
+    def bounded_http_exchange(uri, request, failure_message)
+      body = nil
+      code = nil
+      success = false
+      http_request(uri) do |http|
+        http.request(request) do |response|
+          success = response.is_a?(Net::HTTPSuccess)
+          code = response.code
+          body = HttpBody.read_response!(response)
+        end
       end
+      raise Error.resolution("#{failure_message}: #{code}") unless success
 
-      response.body
+      body
     end
 
     def http_request(uri)

data/lib/pray/registry_install.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Pray
+  module RegistryInstall
+    module_function
+
+    def install_artifact_to_cache(cache_directory, declaration, selected, artifact_bytes, source_url: nil)
+      staging_directory = "#{cache_directory}.staging"
+      FileUtils.rm_rf(staging_directory)
+      FileUtils.mkdir_p(staging_directory)
+      unpacked_directory = File.join(staging_directory, "unpacked")
+      FileUtils.mkdir_p(unpacked_directory)
+
+      begin
+        Registry.validate_and_unpack(
+          unpacked_directory, declaration, selected, artifact_bytes, source_url: source_url
+        )
+        FileUtils.rm_rf(cache_directory) if File.exist?(cache_directory)
+        FileUtils.mv(unpacked_directory, cache_directory)
+      rescue
+        FileUtils.rm_rf(staging_directory)
+        raise
+      else
+        FileUtils.rm_rf(staging_directory)
+      end
+    end
+  end
+end

data/lib/pray/registry_integrity.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Pray
+  module RegistryIntegrity
+    def validate_and_unpack(cache_directory, declaration, selected, artifact_bytes, source_url: nil)
+      require_integrity_fields!(declaration.name, selected)
+      artifact_hash = Hashing.sha256_prefixed(artifact_bytes)
+      if artifact_hash != selected.artifact_hash
+        raise Error.integrity(
+          "package artifact hash mismatch for #{declaration.name} #{selected.version}"
+        )
+      end
+
+      verify_registry_signature!(declaration, selected, artifact_bytes)
+      Trust.verify_publisher_fingerprint!(source_url, selected) if source_url
+      Archive.unpack_praypkg(artifact_bytes, cache_directory)
+      spec_path = Resolve.find_prayspec_file(cache_directory)
+      spec = Pray.parse_package_spec(File.read(spec_path)).canonicalized
+      validate_package_identity!(cache_directory, declaration, selected, spec)
+      actual_tree_hash = spec.tree_hash_for_root(cache_directory)
+      if actual_tree_hash != selected.tree_hash
+        raise Error.integrity(
+          "package tree hash mismatch for #{declaration.name} #{selected.version}"
+        )
+      end
+    end
+
+    def require_integrity_fields!(package_name, selected)
+      if selected.artifact_hash.to_s.empty?
+        raise Error.integrity("package #{package_name} #{selected.version} is missing artifact_hash")
+      end
+      if selected.tree_hash.to_s.empty?
+        raise Error.integrity("package #{package_name} #{selected.version} is missing tree_hash")
+      end
+    end
+
+    def cache_ready?(cache_directory, selected)
+      return false unless File.directory?(cache_directory)
+
+      spec_path = Resolve.find_prayspec_file(cache_directory)
+      spec = Pray.parse_package_spec(File.read(spec_path)).canonicalized
+      spec.version == selected.version && !selected.tree_hash.to_s.empty? &&
+        spec.tree_hash_for_root(cache_directory) == selected.tree_hash
+    rescue Error, SystemCallError
+      false
+    end
+
+    private
+
+    def validate_package_identity!(cache_directory, declaration, selected, spec)
+      if spec.name != declaration.name
+        raise Error.resolution(
+          "package path #{cache_directory.inspect} declares #{spec.name.inspect}, expected #{declaration.name.inspect}"
+        )
+      end
+      return if spec.version == selected.version
+
+      raise Error.resolution(
+        "package #{declaration.name} version #{spec.version} does not match registry version #{selected.version}"
+      )
+    end
+  end
+end

data/lib/pray/render.rb

@@ -2,6 +2,7 @@
 
 require "fileutils"
 require "pathname"
+require_relative "render_content"
 
 module Pray
   RenderedTarget = Struct.new(:path, :content, :managed_spans) do
@@ -18,37 +19,34 @@ module Pray
       project.manifest.targets.each do |target|
         output = target.outputs.first
         next unless output
-
         rendered << render_target(project, target, output)
       end
       rendered
     end
 
-    def write_rendered_targets(project, rendered)
+    def write_rendered_targets(project, rendered, previous_lockfile = nil)
       rendered.each 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)
         FileUtils.mkdir_p(File.dirname(path))
-        File.write(path, target.content)
+        RenderDest.ensure_safe_destination_ancestors!(project.project_root, target.path, target.path)
+        RenderDest.write_rendered_content(path, target.path, target.content)
       end
-      materialize_provisioned_exports(project)
+      materialize_provisioned_exports(project, previous_lockfile)
     end
 
-    def materialize_provisioned_exports(project)
-      symbols = project.manifest.symbols || {}
-      planned_provisioned_files(project).each do |file|
-        destination = File.join(project.project_root, file.path)
-        FileUtils.mkdir_p(File.dirname(destination))
-        write_provisioned_file(file.source, destination, symbols)
-      end
+    def materialize_provisioned_exports(project, previous_lockfile = nil)
+      RenderDest.materialize(project, previous_lockfile)
     end
 
-    def write_provisioned_file(source, destination, symbols)
+    def expected_provisioned_bytes(source, symbols)
       bytes = File.binread(source)
-      text = bytes.force_encoding(Encoding::UTF_8)
+      text = bytes.dup.force_encoding(Encoding::UTF_8)
       if text.valid_encoding?
-        File.write(destination, Substitute.substitute_pray_symbols(text, symbols))
+        Substitute.substitute_pray_symbols(text, symbols)
       else
-        File.binwrite(destination, bytes)
+        bytes
       end
     end
 
@@ -70,19 +68,19 @@ module Pray
       planned.sort_by(&:path).uniq(&:path)
     end
 
-    PlannedProvisionedFile = Struct.new(:path, :source)
+    PlannedProvisionedFile = Struct.new(:path, :source, :package, :export, keyword_init: true)
 
     def render_target(project, target, output)
+      ComposeDest.ensure_html_comment_dest!(output)
       if target.scoped && target.mode == "compose"
         return render_scoped_compose(project, target, output)
       end
-
       render_legacy_compose(project, target, output)
     end
 
     def render_scoped_compose(project, target, output)
       builder = ContentBuilder.new
-      append_header(builder, project, output)
+      append_header(builder, project, target, output)
       symbols = project.manifest.symbols || {}
       managed_spans = []
 
@@ -99,7 +97,7 @@ module Pray
 
     def render_legacy_compose(project, target, output)
       builder = ContentBuilder.new
-      append_header(builder, project, output)
+      append_header(builder, project, target, output)
 
       unbound_locals = project.local_files.select do |local|
         declaration = project.manifest.local.find { |entry| entry.path == local.manifest_path }
@@ -137,16 +135,11 @@ module Pray
       RenderedTarget.new(path: output, content: builder.finish, managed_spans: managed_spans)
     end
 
-    def append_header(builder, project, output)
-      return unless project.manifest.render.header
+    def append_header(builder, project, target, output)
+      text = ComposeDest.header_text(target, output, project.manifest.render.header)
+      return unless text
 
-      output_name = File.basename(output)
-      builder.append_line("<!-- pray:0 ignore-comments -->")
-      builder.append_empty_line
-      builder.append_line("# Agent context")
-      builder.append_empty_line
-      builder.append_line("Do not edit managed blocks in `#{output_name}` or provisioned files under `.agents/`.")
-      builder.append_line("To change shared guidance, update `Prayfile` and run `pray install`.")
+      builder.append_body(text)
       builder.append_empty_line
     end
 
@@ -173,7 +166,10 @@ module Pray
 
     def append_managed_export(builder, managed_spans, package, export, target, output, symbols)
       body = package.export_bodies[export]
-      raise Error.render("package #{package.declaration.name} is missing cached export #{export}") unless body
+      unless body
+        raise Error.integrity("compose cannot write binary export #{export}; use file: for unmarked bytes") if package.spec.exports[export]&.kind == "file"
+        raise Error.render("package #{package.declaration.name} is missing cached export #{export}")
+      end
 
       body = Substitute.substitute_pray_symbols(body, symbols)
       identifier = Hashing.marker_id("#{package.declaration.name}:#{export}:#{target.name}")
@@ -198,7 +194,7 @@ module Pray
 
     def should_inline_export?(package, export_name)
       export = package.spec.exports[export_name]
-      export.nil? || export.kind == "fragment"
+      export.nil? || %w[fragment file].include?(export.kind)
     end
 
     def collect_exact_file_bindings(project, planned)
@@ -215,7 +211,12 @@ module Pray
           source = File.join(package.root, export.path)
           raise Error.render("file export source missing: #{source}") unless File.file?(source)
 
-          planned << PlannedProvisionedFile.new(path: destination, source: source)
+          planned << PlannedProvisionedFile.new(
+            path: destination,
+            source: source,
+            package: package.declaration.name,
+            export: export_name
+          )
           matched = true
           break
         end
@@ -241,6 +242,8 @@ module Pray
           skill_files,
           [],
           [],
+          package.declaration.name,
+          skill_name,
           planned
         )
       end
@@ -274,6 +277,8 @@ module Pray
             indexed_files,
             export.only || [],
             export.except || [],
+            package.declaration.name,
+            export_name,
             planned
           )
         when "file"
@@ -285,7 +290,9 @@ module Pray
           destination = File.join(destination_root, export_name, File.basename(source))
           planned << PlannedProvisionedFile.new(
             path: relative_project_path(project, destination),
-            source: source
+            source: source,
+            package: package.declaration.name,
+            export: export_name
           )
         end
       end
@@ -295,7 +302,7 @@ module Pray
       File.basename(export_path.delete_suffix("/")).empty? ? export_name : File.basename(export_path.delete_suffix("/"))
     end
 
-    def collect_tree_files(project, source_root, destination_root, relative_files, only, except, planned)
+    def collect_tree_files(project, source_root, destination_root, relative_files, only, except, package_name, export_name, planned)
       raise Error.render("folder source directory missing: #{source_root}") unless File.directory?(source_root)
       raise Error.render("no files listed in package manifest for #{source_root}") if relative_files.empty?
 
@@ -310,7 +317,9 @@ module Pray
         destination = File.join(destination_root, relative)
         planned << PlannedProvisionedFile.new(
           path: relative_project_path(project, destination),
-          source: source
+          source: source,
+          package: package_name,
+          export: export_name
         )
         matched = true
       end
@@ -325,36 +334,5 @@ module Pray
     rescue ArgumentError
       absolute
     end
-
-    class ContentBuilder
-      def initialize
-        @content = +""
-      end
-
-      def next_line_number
-        @content.count("\n") + 1
-      end
-
-      def append_line(line)
-        @content << line << "\n"
-      end
-
-      def append_empty_line
-        @content << "\n"
-      end
-
-      def append_body(body)
-        trimmed = body.sub(/\n+\z/, "")
-        return if trimmed.empty?
-
-        trimmed.each_line(chomp: true) { |line| append_line(line) }
-      end
-
-      def finish
-        @content.sub(/\n\n+\z/, "\n")
-        @content << "\n" unless @content.end_with?("\n")
-        @content
-      end
-    end
   end
 end

data/lib/pray/render_content.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Pray
+  module Render
+    class ContentBuilder
+      def initialize
+        @content = +""
+      end
+
+      def next_line_number
+        @content.count("\n") + 1
+      end
+
+      def append_line(line)
+        @content << line << "\n"
+      end
+
+      def append_empty_line
+        @content << "\n"
+      end
+
+      def append_body(body)
+        trimmed = body.sub(/\n+\z/, "")
+        return if trimmed.empty?
+
+        trimmed.each_line(chomp: true) { |line| append_line(line) }
+      end
+
+      def finish
+        @content.sub(/\n\n+\z/, "\n")
+        @content << "\n" unless @content.end_with?("\n")
+        @content
+      end
+    end
+  end
+end