pray-cli 1.9.2 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85c1a7462b69a935d6e9a83d1489c43a445e63190dcebb5481744de051bf562a
-  data.tar.gz: 778142b6ea1ac16ae0762dc9015a30f20ca06cfb3abcb715fa37eea2620a05ff
+  metadata.gz: 1d3cea2d193f4cf496417c5098ad4ff57b0a4b55bc7ee26664f72293c2fcbd06
+  data.tar.gz: 89d8dc8a3c5c65062531e175587d3f86f27ca9630679dac925593be231062e8c
 SHA512:
-  metadata.gz: 7199ad20e75fd83ad98c97d0bbf9f97ae4c6d91bc2e2a8dca0cf4b14339da30a7396d8b076e0f789d8f17f0334b2b10853c8298e429705ef99ccaccc02b88f09
-  data.tar.gz: 19ea0fb475fdfeabc7ab7729e40d2228eba70be9f52becd2923d9b2c770a31fc146215aa2fa65b04c2e14733114c672f67a906e364841df027fedbcd9ca6f61f
+  metadata.gz: aa2d115c1300f177cd4c9dc8c8e4ab2802baf700be3b7124a644f6889ba4138cafe3a6be16d37005f5c2aba95b803740084139171466ebf7ba126e22f82e7d9c
+  data.tar.gz: 1d0c8da737a56bcb21ad6798f6cf59c3fd6ad3384e2d423bb492b37ddf42ccb2c6231b6afebf2b2fc9dc8b7a44e748dd505910a0ceb6835b87006870ae3e68d9

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # CHANGELOG
 
+## 1.10.0 (2026-09-02)
+
+- Refuse to overwrite exclusive `file:` and `tree:` destinations that already exist with other bytes.
+- Fail when a provisioned or compose destination is a symbolic link.
+- Record provisioned leaves in `Prayfile.lock` and delete a dropped leaf only when on-disk bytes still match the locked hash.
+- Keep the previous lock when a provisioned destination write fails, so retry still has its ownership record.
+- Reject destination paths that start with `~`.
+- Print every provisioned path in `pray plan`.
+- BREAKING: Drop unused `render` fields `section_markers` and `line_endings`; reject them at parse.
+- Inline a UTF-8 `file` export into `compose` as a marked span. Exclusive `file:` stays unmarked.
+- Write the Agent context banner on `AGENTS.md` by default. Other compose destinations opt in with `header: true`.
+- Fail compose of JSON, binary, or an unknown file type and name `file:` as the unmarked path.
+- Warn when Prayfile uses deprecated `skills`, export type `skill`, or `spec.skills`; prefer `tree` / `folder`. These forms will be removed in version 2.
+
 ## 1.9.2 (2026-09-01)
 
 - Fix `.praypkg` unpack for git and registry installs when the Ruby process forces UTF-8 internal encoding.

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

@@ -107,8 +107,8 @@ module Pray
       rendered = Render.render_project(project)
       updated_lockfile = build_lockfile(project, rendered)
       merged_lockfile = merge_selected_package_update(previous_lockfile, updated_lockfile, name)
+      Render.write_rendered_targets(project, rendered, previous_lockfile)
       Pray.write_lockfile(lockfile_path, merged_lockfile)
-      Render.write_rendered_targets(project, rendered)
       puts "Unlocked #{name}"
     end
 

data/lib/pray/cli/helpers.rb

@@ -38,7 +38,8 @@ module Pray
         rendered,
         project.packages,
         project.source_revisions,
-        project.source_host_keys
+        project.source_host_keys,
+        project
       )
     end
 

data/lib/pray/compose_dest.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Pray
+  module ComposeDest
+    module_function
+
+    HTML_COMMENT_EXTENSIONS = %w[.md .markdown .html .htm].freeze
+    BINARY_EXTENSIONS = %w[
+      .png .jpg .jpeg .gif .webp .ico .pdf .zip .gz .tgz .tar .wasm .bin
+      .woff .woff2 .exe .dylib .so
+    ].freeze
+
+    def compose_writes_header?(target, output, project_header)
+      return target.header unless target.header.nil?
+
+      project_header && agents_markdown?(output)
+    end
+
+    def header_text(target, output, project_header)
+      return unless compose_writes_header?(target, output, project_header)
+
+      name = File.basename(output)
+      guidance = if agents_markdown?(output)
+        "Do not edit managed blocks in `#{name}` or provisioned files under `.agents/`."
+      else
+        "Do not edit managed blocks in `#{name}`."
+      end
+      <<~HEADER.rstrip
+        <!-- pray:0 ignore-comments -->
+
+        # Agent context
+
+        #{guidance}
+        To change shared guidance, update `Prayfile` and run `pray install`.
+      HEADER
+    end
+
+    def ensure_html_comment_dest!(output)
+      dest = output.tr("\\", "/")
+      extension = File.extname(output).downcase
+      return if HTML_COMMENT_EXTENSIONS.include?(extension)
+      if extension == ".json"
+        raise Error.render("compose cannot write JSON; use file: \"#{dest}\" for unmarked bytes")
+      end
+      if BINARY_EXTENSIONS.include?(extension)
+        raise Error.render(
+          "compose cannot write a binary file; use file: \"#{dest}\" for unmarked bytes"
+        )
+      end
+      raise Error.render(
+        "compose cannot write this file type; use file: \"#{dest}\" for unmarked bytes"
+      )
+    end
+
+    def agents_markdown?(output)
+      File.basename(output) == "AGENTS.md"
+    end
+  end
+end

data/lib/pray/format_serialize.rb

@@ -28,7 +28,12 @@ module Pray
         case target.mode
         when "compose"
           path = target.outputs.first || ""
-          lines << %(compose "#{path}" do)
+          header = case target.header
+          when true then ", header: true"
+          when false then ", header: false"
+          else ""
+          end
+          lines << %(compose "#{path}"#{header} do)
           target.entries.each do |entry|
             lines << "  #{format_destination_entry(entry, manifest)}"
           end

data/lib/pray/lockfile.rb

@@ -20,14 +20,16 @@ module Pray
     :id, :target, :open_line, :close_line, :ideal_checksum, :package, :export,
     :source_checksum, :silenced
   )
+  ProvisionedFileRecord = Struct.new(:path, :content_hash, :package, :export)
 
   Lockfile = Struct.new(
     :prayfile_lock, :spec, :generated_by, :manifest_hash, :environment, :source, :package,
-    :target, :managed_span
+    :target, :managed_span, :provisioned
   ) do
     def initialize(
       prayfile_lock: "1", spec: "0.1", generated_by: Pray::GENERATED_BY,
-      manifest_hash: "", environment: nil, source: [], package: [], target: [], managed_span: []
+      manifest_hash: "", environment: nil, source: [], package: [], target: [], managed_span: [],
+      provisioned: []
     )
       super
     end
@@ -38,6 +40,7 @@ module Pray
         copy.package = package.sort_by { |entry| [entry.name, entry.source.to_s, entry.version] }
         copy.target = target.sort_by(&:name)
         copy.managed_span = managed_span.sort_by { |span| [span.target, span.open_line, span.id] }
+        copy.provisioned = provisioned.sort_by { |entry| [entry.path, entry.package] }
       end
     end
 
@@ -70,7 +73,8 @@ module Pray
         "source" => lockfile.source.map { |entry| source_to_hash(entry) },
         "package" => lockfile.package.map { |entry| package_to_hash(entry) },
         "target" => lockfile.target.map { |entry| {"name" => entry.name, "outputs" => entry.outputs} },
-        "managed_span" => lockfile.managed_span.map { |entry| managed_span_to_hash(entry) }
+        "managed_span" => lockfile.managed_span.map { |entry| managed_span_to_hash(entry) },
+        "provisioned" => lockfile.provisioned.map { |entry| provisioned_to_hash(entry) }
       }
     end
 
@@ -111,6 +115,15 @@ module Pray
       }
     end
 
+    def provisioned_to_hash(entry)
+      {
+        "path" => entry.path,
+        "content_hash" => entry.content_hash,
+        "package" => entry.package,
+        "export" => entry.export
+      }
+    end
+
     def parse_lockfile(text)
       data = TomlRB.parse(text)
       from_hash(data)
@@ -147,8 +160,9 @@ module Pray
       left.equivalent_to?(right)
     end
 
-    def build_lockfile(manifest_hash, environment, project_root, manifest_sources, manifest_targets, rendered, packages, source_revisions, source_host_keys)
-      Lockfile.new(
+    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
+      lockfile = Lockfile.new(
         manifest_hash: manifest_hash,
         environment: environment,
         source: manifest_sources.map do |source|
@@ -176,7 +190,11 @@ module Pray
         end,
         target: manifest_targets.map { |target| LockedTarget.new(name: target.name, outputs: target.outputs) },
         managed_span: rendered.flat_map(&:managed_spans)
-      ).canonicalized
+      )
+      if project
+        lockfile.provisioned = RenderDest.provisioned_records(project)
+      end
+      lockfile.canonicalized
     end
 
     def from_hash(data)
@@ -222,6 +240,14 @@ module Pray
             source_checksum: entry["source_checksum"],
             silenced: entry["silenced"]
           )
+        end,
+        provisioned: Array(data["provisioned"]).map do |entry|
+          ProvisionedFileRecord.new(
+            path: entry["path"],
+            content_hash: entry["content_hash"],
+            package: entry["package"],
+            export: entry["export"]
+          )
         end
       )
     end

data/lib/pray/lockfile_serialize.rb

@@ -22,6 +22,7 @@ module Pray
       lockfile.package.each { |entry| append_section(lines, format_package(entry)) }
       lockfile.target.each { |entry| append_section(lines, format_target(entry)) }
       lockfile.managed_span.each { |entry| append_section(lines, format_managed_span(entry)) }
+      lockfile.provisioned.each { |entry| append_section(lines, format_provisioned(entry)) }
 
       lines.pop while lines.last == ""
       "#{lines.join("\n")}\n"
@@ -94,6 +95,20 @@ module Pray
       lines
     end
 
+    def format_provisioned(entry)
+      lines = ["[[provisioned]]"]
+      append_scalars(
+        lines,
+        [
+          ["path", entry.path],
+          ["content_hash", entry.content_hash],
+          ["package", entry.package],
+          ["export", entry.export]
+        ]
+      )
+      lines
+    end
+
     def append_scalars(lines, entries)
       entries.each do |key, value|
         lines << case value

data/lib/pray/manifest.rb

@@ -9,27 +9,25 @@ require_relative "path_safety"
 
 module Pray
   RenderPolicy = Struct.new(
-    :mode, :conflict, :churn, :header, :section_markers, :line_endings
+    :mode, :conflict, :churn, :header
   ) do
     def self.default
       new(
         mode: "managed",
         conflict: "fail",
         churn: "minimal",
-        header: true,
-        section_markers: true,
-        line_endings: "lf"
+        header: true
       )
     end
   end
 
   ManifestSource = Struct.new(:name, :kind, :url, :subdir, :rev, :tag)
   ManifestTarget = Struct.new(
-    :name, :outputs, :skills, :commands, :rules, :max_bytes, :mode, :scoped, :entries
+    :name, :outputs, :skills, :commands, :rules, :max_bytes, :mode, :scoped, :entries, :header
   ) do
     def initialize(
       name:, outputs: [], skills: [], commands: [], rules: [], max_bytes: nil,
-      mode: "legacy", scoped: false, entries: []
+      mode: "legacy", scoped: false, entries: [], header: nil
     )
       super
     end
@@ -73,7 +71,7 @@ module Pray
     end
 
     def note_deprecated_keyword(keyword)
-      return unless %w[target output agent].include?(keyword)
+      return unless %w[target output agent skills].include?(keyword)
       self.deprecated_keywords ||= []
       deprecated_keywords << keyword unless deprecated_keywords.include?(keyword)
     end
@@ -82,7 +80,10 @@ module Pray
       replacements = {
         "target" => "compose` / `tree",
         "output" => "compose",
-        "agent" => "pray"
+        "agent" => "pray",
+        "skills" => "tree` / `folder",
+        "skill" => "folder",
+        "spec.skills" => "a folder export"
       }
       (deprecated_keywords || []).filter_map do |keyword|
         replacement = replacements[keyword]
@@ -127,12 +128,12 @@ module Pray
     def validate_manifest_paths!(manifest)
       manifest.targets.each do |target|
         (target.outputs + target.skills + target.commands + target.rules).each do |path|
-          PathSafety.validate_project_relative_path!(path)
+          PathSafety.validate_destination_path!(path)
         end
       end
       manifest.packages.each do |package|
         PathSafety.validate_project_relative_path!(package.path) if package.path
-        PathSafety.validate_project_relative_path!(package.file) if package.file
+        PathSafety.validate_destination_path!(package.file) if package.file
       end
       manifest.local.each { |local| PathSafety.validate_project_relative_path!(local.path) }
     end

data/lib/pray/manifest_json.rb

@@ -34,7 +34,7 @@ module Pray
     end
 
     def target_fields(target)
-      {
+      fields = {
         "name" => target.name,
         "outputs" => target.outputs,
         "skills" => target.skills,
@@ -45,6 +45,8 @@ module Pray
         "scoped" => target.scoped || false,
         "entries" => (target.entries || []).map { |entry| entry_fields(entry) }
       }
+      fields["header"] = target.header unless target.header.nil?
+      fields
     end
 
     def entry_fields(entry)
@@ -93,9 +95,7 @@ module Pray
         "mode" => render.mode,
         "conflict" => render.conflict,
         "churn" => render.churn,
-        "header" => render.header,
-        "section_markers" => render.section_markers,
-        "line_endings" => render.line_endings
+        "header" => render.header
       }
     end
 

data/lib/pray/manifest_parser.rb

@@ -104,6 +104,7 @@ module Pray
         if statement.start_with?("folder ", "skills ") && !statement.end_with?(" do")
           raise Error.parse("manifest", "top-level folder/skills must use a tree block")
         end
+        manifest.note_deprecated_keyword("skills") if statement.start_with?("skills ")
         parse_destination_block(manifest, rest, "tree")
       end
 

data/lib/pray/manifest_parser_blocks.rb

@@ -55,11 +55,13 @@ module Pray
         end
 
         header = rest.sub(/\s*do\z/, "").strip
-        values, = parse_call(header)
+        values, keywords = parse_call(header)
         raise Error.parse("manifest", "destination missing path") if values.empty?
 
         path = string_from_value(values.first)
-        manifest.targets << Destination.new_destination_target(mode, path)
+        target = Destination.new_destination_target(mode, path)
+        target.header = destination_header_keyword(mode, keywords)
+        manifest.targets << target
         index = manifest.targets.length - 1
         parse_destination_body(manifest, index, mode)
       end
@@ -207,6 +209,7 @@ module Pray
           raise Error.manifest("target index out of range") unless target
 
           manifest.note_deprecated_keyword("output") if statement.start_with?("output ")
+          manifest.note_deprecated_keyword("skills") if statement.start_with?("skills ")
           apply_target_statement(target, statement)
         end
         raise Error.parse("manifest", "missing 'end' for target block")

data/lib/pray/manifest_parser_helpers.rb

@@ -170,23 +170,52 @@ module Pray
 
       def parse_render_policy(rest)
         _, keywords = parse_call(rest)
+        keywords.each_key do |key|
+          unless %w[mode conflict churn header].include?(key)
+            raise Error.parse("manifest", "render does not accept #{key}")
+          end
+        end
         conflict = keywords["conflict"]&.as_string || "fail"
         unless conflict == "fail"
           raise Error.unsupported(
             "render conflict :#{conflict} is not implemented; only :fail is supported"
           )
         end
+        mode = keywords["mode"]&.as_string || "managed"
+        unless mode == "managed"
+          raise Error.unsupported("render mode :#{mode} is not implemented")
+        end
+        churn = keywords["churn"]&.as_string || "minimal"
+        unless churn == "minimal"
+          raise Error.unsupported("render churn :#{churn} is not implemented")
+        end
 
         RenderPolicy.new(
-          mode: keywords["mode"]&.as_string || "managed",
+          mode: mode,
           conflict: conflict,
-          churn: keywords["churn"]&.as_string || "minimal",
-          header: keyword_bool(keywords, "header", true),
-          section_markers: keyword_bool(keywords, "section_markers", true),
-          line_endings: keywords["line_endings"]&.as_string || "lf"
+          churn: churn,
+          header: keyword_bool(keywords, "header", true)
         )
       end
 
+      def destination_header_keyword(mode, keywords)
+        label = (mode == "compose") ? "compose" : "tree"
+        keywords.each_key do |key|
+          unless key == "header"
+            raise Error.parse("manifest", "#{label} does not accept #{key}")
+          end
+        end
+        return if keywords["header"].nil?
+        unless mode == "compose"
+          raise Error.parse("manifest", "#{label} does not accept header")
+        end
+
+        value = keywords["header"].as_bool
+        raise Error.parse("manifest", "header must be true or false") if value.nil?
+
+        value
+      end
+
       def keyword_bool(keywords, key, default)
         value = keywords[key]
         return default if value.nil?

data/lib/pray/materialize.rb

@@ -40,6 +40,7 @@ module Pray
       end
       rendered = Render.render_project(project)
       lockfile_path = default_lockfile_path(project.project_root)
+      previous_lockfile = File.exist?(lockfile_path) ? Pray.read_lockfile(lockfile_path) : nil
       next_lockfile = LockfileIO.build_lockfile(
         project.manifest_hash,
         project.environment,
@@ -49,7 +50,8 @@ module Pray
         rendered,
         project.packages,
         project.source_revisions,
-        project.source_host_keys
+        project.source_host_keys,
+        project
       )
 
       if locked
@@ -61,7 +63,7 @@ module Pray
           raise Error.verify("lockfile needs update; rerun install to refresh Prayfile.lock")
         end
         unless frozen
-          Render.write_rendered_targets(project, rendered)
+          Render.write_rendered_targets(project, rendered, existing)
         end
         if frozen
           rendered.each do |target|
@@ -89,8 +91,8 @@ module Pray
         end
       end
 
+      Render.write_rendered_targets(project, rendered, previous_lockfile)
       Pray.write_lockfile_if_changed(lockfile_path, next_lockfile)
-      Render.write_rendered_targets(project, rendered)
     end
 
     def default_manifest_path(working_directory = Dir.pwd)

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

@@ -71,5 +71,14 @@ 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
   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