pray-cli 1.9.2 → 1.11.0

data/lib/pray/path_safety.rb

@@ -71,5 +71,34 @@ module Pray
 
       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
+
+    def validate_registry_cache_identity!(package_name, version)
+      namespace, name, extra_segment = package_name.to_s.split("/", -1)
+      unless extra_segment.nil? && registry_cache_segment_safe?(namespace) && registry_cache_segment_safe?(name)
+        raise Error.integrity("invalid registry package name: #{package_name}")
+      end
+      unless registry_cache_segment_safe?(version)
+        raise Error.integrity("invalid registry package version: #{version}")
+      end
+
+      [namespace, name]
+    end
+
+    def registry_cache_segment_safe?(value)
+      value.is_a?(String) &&
+        !value.empty? &&
+        ![".", ".."].include?(value) &&
+        !value.match?(%r{[/\\\0]})
+    end
+    private_class_method :registry_cache_segment_safe?
   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

@@ -47,8 +47,7 @@ module Pray
         project_root,
         source_url,
         declaration.name,
-        selected.version,
-        selected.artifact_hash
+        selected.version
       )
 
       if cache_ready?(cache_directory, selected)
@@ -91,8 +90,7 @@ module Pray
         project_root,
         source_key,
         declaration.name,
-        selected.version,
-        selected.artifact_hash
+        selected.version
       )
 
       if cache_ready?(cache_directory, selected)
@@ -238,15 +236,10 @@ module Pray
       )
     end
 
-    def registry_cache_directory(project_root, source_key, package_name, version, artifact_hash)
-      identifier = [
-        source_key,
-        package_name,
-        version,
-        artifact_hash || "no-artifact-hash"
-      ].join(":")
-      digest = Hashing.sha256_hex(identifier)[0, 16]
-      File.join(project_root, ".pray", "cache", "registry", package_name.tr("/", "-"), version, digest)
+    def registry_cache_directory(project_root, source_key, package_name, version)
+      namespace, name = PathSafety.validate_registry_cache_identity!(package_name, version)
+      source_hash = Hashing.sha256_hex(source_key)[0, 16]
+      File.join(project_root, ".pray", "cache", "registry", namespace, name, version, source_hash)
     end
 
     def offline_package_error(package_name, version)

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
@@ -23,33 +24,29 @@ module Pray
       rendered
     end
 
-    def write_rendered_targets(project, rendered)
+    def write_rendered_targets(project, rendered, previous_lockfile = nil)
       rendered.each do |target|
-        PathSafety.validate_project_relative_path!(target.path)
+        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|
-        PathSafety.validate_project_relative_path!(file.path)
-        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
 
@@ -71,9 +68,10 @@ 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
@@ -82,7 +80,7 @@ module Pray
 
     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

data/lib/pray/render_dest.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module Pray
+  module RenderDest
+    module_function
+
+    def materialize(project, previous_lockfile = nil)
+      planned = Render.planned_provisioned_files(project)
+      previous = previous_map(previous_lockfile)
+      planned_paths = planned.map(&:path).to_h { |path| [path, true] }
+      planned.each { |file| write_leaf(project, file, previous) }
+      prune_dropped(project, previous_lockfile, planned_paths) if previous_lockfile
+    end
+
+    def provisioned_records(project)
+      symbols = project.manifest.symbols || {}
+      Render.planned_provisioned_files(project).map do |file|
+        expected = Render.expected_provisioned_bytes(file.source, symbols)
+        ProvisionedFileRecord.new(
+          path: file.path.to_s.tr("\\", "/"),
+          content_hash: Hashing.sha256_prefixed(expected.b),
+          package: file.package,
+          export: file.export
+        )
+      end
+    end
+
+    def fail_if_symlink!(path, display)
+      return unless File.symlink?(path)
+
+      raise Error.render("refusing to write `#{display}` because it is a symbolic link")
+    end
+
+    def previous_map(lockfile)
+      return {} unless lockfile
+
+      Array(lockfile.provisioned).to_h { |record| [record.path, record] }
+    end
+
+    def destination_status(project, file, previous_lockfile = nil)
+      PathSafety.validate_destination_path!(file.path)
+      ensure_safe_destination_ancestors!(project.project_root, file.path, file.path)
+      destination = File.join(project.project_root, file.path)
+      expected = Render.expected_provisioned_bytes(file.source, project.manifest.symbols || {})
+      record = previous_map(previous_lockfile)[file.path.to_s.tr("\\", "/")]
+      classify_destination(destination, file.path, expected, record)
+    end
+
+    def write_leaf(project, file, previous)
+      PathSafety.validate_destination_path!(file.path)
+      ensure_safe_destination_ancestors!(project.project_root, file.path, file.path)
+      destination = File.join(project.project_root, file.path)
+      expected = Render.expected_provisioned_bytes(file.source, project.manifest.symbols || {})
+      record = previous[file.path.to_s.tr("\\", "/")]
+      status = classify_destination(destination, file.path, expected, record)
+      if status == :write
+        FileUtils.mkdir_p(File.dirname(destination))
+        ensure_safe_destination_ancestors!(project.project_root, file.path, file.path)
+        return create_bytes(destination, file.path, expected)
+      end
+      return if status == :unchanged
+
+      unless record
+        raise Error.render("missing lock ownership for `#{file.path}`")
+      end
+
+      ensure_safe_destination_ancestors!(project.project_root, file.path, file.path)
+      update_bytes(destination, file.path, expected, record.content_hash)
+    end
+
+    def classify_destination(destination, display, expected, record)
+      kind = destination_kind(destination)
+      return :write if kind == :missing
+
+      fail_if_symlink!(destination, display)
+      unless kind == :regular
+        raise Error.render("refusing to write `#{display}`; destination is not a regular file")
+      end
+      on_disk = read_regular_bytes(destination, display)
+      return :unchanged if on_disk.b == expected.b
+      return :update if record && Hashing.sha256_prefixed(on_disk) == record.content_hash
+
+      if record
+        raise Error.render("refusing to overwrite `#{display}`; it was provisioned and then edited")
+      end
+
+      raise Error.render(
+        "refusing to overwrite `#{display}`; it already exists and is not the expected provisioned file"
+      )
+    end
+
+    def prune_dropped(project, previous, planned_paths)
+      Array(previous.provisioned).each do |record|
+        PathSafety.validate_destination_path!(record.path)
+        next if planned_paths[record.path]
+
+        destination = File.join(project.project_root, record.path)
+        ensure_safe_destination_ancestors!(project.project_root, record.path, record.path)
+        next unless destination_kind(destination) == :regular
+
+        on_disk = read_regular_bytes(destination, record.path)
+        if Hashing.sha256_prefixed(on_disk) == record.content_hash
+          ensure_safe_destination_ancestors!(project.project_root, record.path, record.path)
+          File.delete(destination)
+        end
+      end
+    end
+
+    def layout_rendered_content(path, display, fresh)
+      kind = destination_kind(path)
+      return fresh if kind == :missing
+
+      fail_if_symlink!(path, display)
+      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)
+    end
+
+    def write_rendered_content(path, display, fresh)
+      return create_bytes(path, display, fresh) if destination_kind(path) == :missing
+
+      open_regular(path, display, File::RDWR) do |file|
+        existing = decode_utf8(file.read, display)
+        content = RenderPatch.patch_rendered_content(existing, fresh)
+        file.rewind
+        file.truncate(0)
+        file.write(content)
+      end
+    end
+
+    def ensure_safe_destination_ancestors!(project_root, relative_path, display)
+      parent = File.dirname(relative_path.to_s.tr("\\", "/"))
+      return if parent == "."
+
+      current = project_root
+      parent.split("/").each do |component|
+        next if component.empty? || component == "."
+
+        current = File.join(current, component)
+        metadata = File.lstat(current)
+        if metadata.symlink?
+          raise Error.render(
+            "refusing to write `#{display}` because a destination parent is a symbolic link"
+          )
+        end
+        unless metadata.directory?
+          raise Error.render(
+            "refusing to write `#{display}`; a destination parent is not a directory"
+          )
+        end
+      rescue Errno::ENOENT
+        next
+      end
+    end
+
+    def create_bytes(path, display, bytes)
+      open_path(path, display, File::WRONLY | File::CREAT | File::EXCL) do |file|
+        file.write(bytes)
+      end
+    end
+
+    def update_bytes(path, display, bytes, authorized_hash)
+      open_regular(path, display, File::RDWR) do |file|
+        on_disk = file.read
+        return if on_disk.b == bytes.b
+
+        unless Hashing.sha256_prefixed(on_disk) == authorized_hash
+          raise Error.render("refusing to overwrite `#{display}`; it was provisioned and then edited")
+        end
+        file.rewind
+        file.truncate(0)
+        file.write(bytes)
+      end
+    end
+
+    def read_regular_bytes(path, display)
+      open_regular(path, display, File::RDONLY) { |file| file.read }
+    end
+
+    def decode_utf8(bytes, display)
+      text = bytes.dup.force_encoding(Encoding::UTF_8)
+      return text if text.valid_encoding?
+
+      raise Error.render("rendered destination `#{display}` is not valid UTF-8")
+    end
+
+    def open_regular(path, display, flags)
+      open_path(path, display, flags) do |file|
+        unless file.stat.file?
+          raise Error.render("refusing to write `#{display}`; destination is not a regular file")
+        end
+        yield file
+      end
+    end
+
+    def open_path(path, display, flags)
+      no_follow = File.const_defined?(:NOFOLLOW) ? File::NOFOLLOW : 0
+      File.open(path, flags | no_follow) { |file| yield file }
+    rescue Errno::ELOOP
+      raise Error.render("refusing to write `#{display}` because it is a symbolic link")
+    end
+
+    def destination_kind(path)
+      return :symlink if File.symlink?(path)
+      return :missing unless File.exist?(path)
+      return :regular if File.file?(path)
+
+      :other
+    end
+  end
+end

data/lib/pray/render_layout.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Pray
+  module Render
+    module_function
+
+    def layout_rendered_targets(project, rendered)
+      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)
+        RenderedTarget.new(
+          path: target.path,
+          content: content,
+          managed_spans: RenderPatch.relocate_managed_spans(content, target.managed_spans)
+        )
+      end
+    end
+  end
+end