pray-cli 1.9.2 → 1.10.0

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

data/lib/pray/render_patch.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Pray
+  module RenderPatch
+    module_function
+
+    def patch_rendered_content(existing, fresh)
+      existing_segments = split_segments(existing)
+      fresh_segments = split_segments(fresh)
+      fresh_managed = fresh_segments.filter_map do |segment|
+        [segment[:id], segment[:body]] if segment[:kind] == :managed
+      end.to_h
+      overlap = existing_segments.any? do |segment|
+        segment[:kind] == :managed && fresh_managed.key?(segment[:id])
+      end
+      return fresh unless overlap
+
+      used = {}
+      output = existing_segments.map do |segment|
+        next segment[:text] if segment[:kind] == :text
+
+        used[segment[:id]] = true
+        managed_segment(segment[:id], fresh_managed.fetch(segment[:id], segment[:body]))
+      end.join
+      fresh_segments.each do |segment|
+        next unless segment[:kind] == :managed
+        next if used[segment[:id]]
+
+        output << managed_segment(segment[:id], segment[:body])
+      end
+      output.end_with?("\n") ? output : "#{output}\n"
+    end
+
+    def relocate_managed_spans(content, spans)
+      positions = marker_positions(lines_of(content))
+      spans.map do |span|
+        position = positions[span.id]
+        next span unless position
+
+        span.dup.tap do |relocated|
+          relocated.open_line = position[0]
+          relocated.close_line = position[1]
+        end
+      end
+    end
+
+    def split_segments(content)
+      lines = lines_of(content)
+      segments = []
+      text = +""
+      index = 0
+      while index < lines.length
+        identifier = marker_id(lines[index])
+        close = find_closing_marker(lines, index + 1, identifier) if identifier
+        if identifier && close
+          segments << {kind: :text, text: text} unless text.empty?
+          text = +""
+          body_lines = lines[(index + 1)...close]
+          body = body_lines.empty? ? "" : "#{body_lines.join("\n")}\n"
+          segments << {kind: :managed, id: identifier, body: body}
+          index = close + 1
+        else
+          text << "#{lines[index]}\n"
+          index += 1
+        end
+      end
+      segments << {kind: :text, text: text} unless text.empty?
+      segments
+    end
+
+    def lines_of(content)
+      content.lines(chomp: true)
+    end
+
+    def find_closing_marker(lines, start, identifier)
+      (start...lines.length).find { |index| marker_id(lines[index]) == identifier }
+    end
+
+    def marker_positions(lines)
+      positions = {}
+      active = nil
+      lines.each_with_index do |line, index|
+        identifier = marker_id(line)
+        next unless identifier&.match?(/\A[a-z0-9]+\z/)
+
+        if active.nil?
+          active = [identifier, index + 1]
+        elsif active[0] == identifier
+          positions[identifier] = [active[1], index + 1]
+          active = nil
+        end
+      end
+      positions
+    end
+
+    def marker_id(line)
+      match = line.strip.match(/\A<!-- pray:(.+) -->\z/)
+      identifier = match && match[1]
+      identifier unless identifier == "0 ignore-comments"
+    end
+
+    def managed_segment(identifier, body)
+      content = body.empty? ? "" : "#{body.sub(/\n+\z/, "")}\n"
+      "<!-- pray:#{identifier} -->\n#{content}<!-- pray:#{identifier} -->\n"
+    end
+  end
+end

data/lib/pray/resolve.rb

@@ -87,6 +87,7 @@ module Pray
         errors << "#{declaration.name}: #{error.message}"
       end
       raise Error.resolution(errors.join("\n")) unless errors.empty?
+      PackageSpec.warn_resolved_deprecations(packages)
 
       local_files = []
       local_errors = []
@@ -298,40 +299,11 @@ module Pray
     end
 
     def select_exports(declaration, spec)
-      unless declaration.exports.empty?
-        declaration.exports.each do |export|
-          unless spec.exports.key?(export)
-            raise Error.resolution("package #{declaration.name} does not export #{export}")
-          end
-        end
-        return declaration.exports
-      end
-
-      roles = declaration.roles || []
-      return spec.exports.keys.sort if roles.empty? && declaration.file.nil?
-
-      effective_roles = roles.dup
-      effective_roles << "file" if declaration.file && !effective_roles.include?("file")
+      ResolveExports.select_exports(declaration, spec)
+    end
 
-      selected = []
-      effective_roles.each do |role|
-        compatible = spec.exports.filter_map do |name, export|
-          name if Destination.export_kind_matches_role?(export.kind, role)
-        end
-        case compatible.length
-        when 1
-          selected << compatible.first unless selected.include?(compatible.first)
-        when 0
-          raise Error.resolution(
-            "package #{declaration.name} has no export compatible with #{role}"
-          )
-        else
-          raise Error.resolution(
-            "package #{declaration.name} has multiple exports compatible with #{role}; set export: \"name\""
-          )
-        end
-      end
-      selected
+    def load_export_bodies(file_bytes, spec, selected_exports)
+      ResolveExports.load_export_bodies(file_bytes, spec, selected_exports)
     end
 
     def load_package_file_bytes(root, spec)
@@ -346,21 +318,6 @@ module Pray
       file_bytes
     end
 
-    def load_export_bodies(file_bytes, spec, selected_exports)
-      export_bodies = {}
-      selected_exports.each do |export_name|
-        entry = spec.exports[export_name]
-        raise Error.resolution("package #{spec.name} is missing export #{export_name}") unless entry
-        next unless entry.kind == "fragment"
-
-        bytes = file_bytes[entry.path]
-        raise Error.integrity("package file missing for export #{export_name}: #{entry.path}") unless bytes
-
-        export_bodies[export_name] = Hashing.normalize_line_endings(bytes.force_encoding(Encoding::UTF_8))
-      end
-      export_bodies
-    end
-
     def build_skill_file_index(spec)
       index = {}
       spec.exports.each do |export_name, export|