pray-cli 1.10.0 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d3cea2d193f4cf496417c5098ad4ff57b0a4b55bc7ee26664f72293c2fcbd06
-  data.tar.gz: 89d8dc8a3c5c65062531e175587d3f86f27ca9630679dac925593be231062e8c
+  metadata.gz: 68bb4b372a260d62b3cfce3bdc74811b85c2cff0446adf0bd551065b0214fbb1
+  data.tar.gz: 3bfc7db4cd0b6227a554199f6c8cbf8fd2e4c1e2715be48f7d102903e7a26bb2
 SHA512:
-  metadata.gz: aa2d115c1300f177cd4c9dc8c8e4ab2802baf700be3b7124a644f6889ba4138cafe3a6be16d37005f5c2aba95b803740084139171466ebf7ba126e22f82e7d9c
-  data.tar.gz: 1d0c8da737a56bcb21ad6798f6cf59c3fd6ad3384e2d423bb492b37ddf42ccb2c6231b6afebf2b2fc9dc8b7a44e748dd505910a0ceb6835b87006870ae3e68d9
+  metadata.gz: '095670c5e563280d0610d1eefa2ef2a825e2676aaff537c54eda62ad97ee11a631dc5328648614bfdd69b6dca744c7377fea9fef3b5cc0c4d3341ad511adb4be'
+  data.tar.gz: a820d50b02742e1b8a7c79fe9075f48e6ae7c90f3551dba8e8fbb37c7ed28d2e7089ac9fe81b82c2db7e8bf7d20f926840084d841e30bb3d2a733efa68e2892f

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # CHANGELOG
 
+## Unreleased
+
+## 1.12.0 (2026-09-07)
+
+- Speed up planning for large package trees and reuse the resolved lock during installation.
+- Report duplicate lockfile fields as parsing errors with lockfile context.
+- Restore compose files, provisioned destinations, Prayfile, and lock after failed writes, and recover interrupted writes on the next install, plan, or verification on Unix.
+- Preserve later local edits when recovery encounters changed files, and prevent cooperating Pray commands from writing the same project together.
+- Limit destination reads to 32 MiB, saved transaction payload to 64 MiB across 10,000 writes, and grouped conflict details to 100 entries.
+- Report conflicting file and tree destinations together before changing compose output, with steps that preserve local edits.
+- Reject unsupported update options (`--latest`, `--major`, `--dry-run`, and `--json`) instead of silently ignoring them.
+
+## 1.11.0 (2026-09-04)
+
+- Read the whole eight byte tar checksum field so `.praypkg` archives whose checksum is written as seven octal digits unpack instead of failing integrity.
+- Share the source-keyed registry cache path with the Rust and TypeScript CLIs.
+- Add `pray clean --unused` for lockfile-driven registry cache cleanup.
+- Reject unsafe registry package and version path segments.
+
 ## 1.10.0 (2026-09-02)
 
 - Refuse to overwrite exclusive `file:` and `tree:` destinations that already exist with other bytes.

data/lib/pray/cache_clean.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Pray
+  module CacheClean
+    module_function
+
+    def clean_unused_registry_cache(project_root)
+      lockfile = Pray.read_lockfile(File.join(project_root, "Prayfile.lock"))
+      validate_lockfile_for_cleanup!(lockfile)
+      registry_root = File.expand_path(".pray/cache/registry", project_root)
+      retained = lockfile.package.filter_map do |package|
+        package_path = File.expand_path(package.path, project_root)
+        package_path if PathSafety.path_under_root?(registry_root, package_path)
+      end
+
+      begin
+        metadata = File.lstat(registry_root)
+      rescue Errno::ENOENT
+        return
+      end
+      if metadata.symlink? || !metadata.directory?
+        remove_path(registry_root)
+        return
+      end
+      prune_directory(registry_root, retained, remove_when_empty: false)
+    end
+
+    def validate_lockfile_for_cleanup!(lockfile)
+      validate_sha256_digest!("manifest_hash", lockfile.manifest_hash)
+      lockfile.package.each do |package|
+        if !package.path.is_a?(String) || package.path.empty?
+          raise Error.parse("lockfile", "package path must not be empty")
+        end
+        validate_sha256_digest!("package tree_hash", package.tree_hash)
+        validate_sha256_digest!("package artifact_hash", package.artifact_hash)
+      end
+    end
+
+    def validate_sha256_digest!(field, value)
+      digest = value.to_s.delete_prefix("sha256:")
+      return if value.is_a?(String) && value.start_with?("sha256:") && digest.match?(/\A[0-9a-f]{64}\z/)
+
+      raise Error.parse("lockfile", "#{field} must be a sha256 digest")
+    end
+
+    def prune_directory(path, retained, remove_when_empty:)
+      Dir.each_child(path) do |name|
+        entry = File.join(path, name)
+        protects_entry = retained.include?(entry)
+        leads_to_retained = retained.any? { |kept| PathSafety.path_under_root?(entry, kept) }
+        next if protects_entry
+
+        metadata = File.lstat(entry)
+        if leads_to_retained && metadata.directory? && !metadata.symlink?
+          prune_directory(entry, retained, remove_when_empty: true)
+        else
+          remove_path(entry)
+        end
+      end
+      Dir.rmdir(path) if remove_when_empty && Dir.empty?(path)
+    end
+
+    def remove_path(path)
+      metadata = File.lstat(path)
+      if metadata.directory? && !metadata.symlink?
+        FileUtils.rm_rf(path)
+      else
+        File.unlink(path)
+      end
+    rescue Errno::ENOENT
+      nil
+    end
+  end
+end

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

@@ -6,10 +6,15 @@ module Pray
       puts "pray #{Pray::VERSION}"
     end
 
-    def clean_command
-      remove_path_if_exists(".pray/cache")
-      remove_path_if_exists(".pray/vendor")
-      remove_path_if_exists(".pray/state.json")
+    def clean_command(unused: false)
+      project_root = Invocation.project_root
+      if unused
+        CacheClean.clean_unused_registry_cache(project_root)
+        return
+      end
+      remove_path_if_exists(File.join(project_root, ".pray/cache"))
+      remove_path_if_exists(File.join(project_root, ".pray/vendor"))
+      remove_path_if_exists(File.join(project_root, ".pray/state.json"))
     end
   end
 end

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

@@ -15,7 +15,7 @@ module Pray
       declaration = Pray.format_package_declaration(
         ManifestPackage.new(name: name, constraint: constraint || "*", path: path)
       )
-      File.write(manifest_path_value, insert_manifest_statement(manifest_text, declaration))
+      Transaction.write_file(manifest_path_value, insert_manifest_statement(manifest_text, declaration))
     end
 
     def remove_command(name)
@@ -28,7 +28,7 @@ module Pray
         raise Error.manifest("package #{name} not found")
       end
 
-      File.write(manifest_path_value, remove_manifest_statement(manifest_text, name))
+      Transaction.write_file(manifest_path_value, remove_manifest_statement(manifest_text, name))
       install_command({locked: false, frozen: false, offline: false})
     end
 

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

@@ -76,7 +76,7 @@ module Pray
       )
       rendered = Render.render_project(project)
       lockfile = build_lockfile(project, rendered)
-      previous_lockfile = File.exist?(lockfile_path) ? Pray.read_lockfile(lockfile_path) : nil
+      previous_lockfile = project.previous_lockfile
       preview = Plan.build_materialization_preview(
         project, rendered, lockfile, lockfile_path, previous_lockfile
       )
@@ -84,6 +84,14 @@ module Pray
     end
 
     def update_command(arguments)
+      if arguments.any? { |argument| %w[--dry-run --json].include?(argument) }
+        raise Error.unsupported("this Ruby CLI does not support --dry-run or --json for update; use `pray plan` to preview the current Prayfile")
+      end
+      if arguments.any? { |argument| %w[--latest --major].include?(argument) }
+        raise Error.unsupported(
+          "to update beyond the current constraint, edit the package version in Prayfile, then run `pray update`"
+        )
+      end
       package = arguments.reject { |argument| argument.start_with?("--") }.first
       offline = arguments.include?("--offline")
       if package

data/lib/pray/cli/help.rb

@@ -16,7 +16,7 @@ module Pray
       PACKAGE_COMMANDS = [
         "add <name> [constraint] [--path PATH]  declare a package in Prayfile",
         "remove <name>                          remove a package from Prayfile",
-        "update [package] [--major] [--latest] [--dry-run] [--json]",
+        "update [package]",
         "unlock <package>                       clear a locked package pin",
         "vendor                                 copy resolved packages locally",
         "clean                                  remove local cache and vendor trees"
@@ -101,7 +101,7 @@ module Pray
         "update" => <<~TEXT.strip,
           refresh package versions within constraints
 
-          Usage: pray update [package] [--major] [--latest] [--dry-run] [--json]
+          Usage: pray update [package]
         TEXT
         "plan" => <<~TEXT.strip,
           preview install/apply changes
@@ -117,7 +117,7 @@ module Pray
         "remove" => "remove a package from Prayfile\n\nUsage: pray remove <name>",
         "unlock" => "clear a locked package pin\n\nUsage: pray unlock <package>",
         "vendor" => "copy resolved packages locally\n\nUsage: pray vendor",
-        "clean" => "remove local cache and vendor trees\n\nUsage: pray clean",
+        "clean" => "remove local cache and vendor trees, or only unused registry entries\n\nUsage: pray clean [--unused]",
         "publish" => <<~TEXT.strip,
           upload packages to a registry or local root
 

data/lib/pray/cli/parse.rb

@@ -67,7 +67,7 @@ module Pray
       when "outdated" then [:outdated, arguments]
       when "explain" then [:explain, arguments.shift]
       when "vendor" then [:vendor]
-      when "clean" then [:clean]
+      when "clean" then [:clean, parse_clean_arguments(arguments, flags)]
       when "tree" then [:tree]
       when "sync" then [:sync, parse_sync_arguments(arguments)]
       when "trust" then parse_trust_command(arguments)
@@ -83,6 +83,24 @@ module Pray
       found
     end
 
+    def parse_clean_arguments(arguments, flags)
+      if flags.values_at(:check, :strict, :semantic, :locked, :frozen, :offline).any?
+        raise Error.unsupported("unknown clean flag")
+      end
+
+      unused = false
+      arguments.each do |argument|
+        if argument == "--unused" && !unused
+          unused = true
+        elsif argument.start_with?("--")
+          raise Error.unsupported("unknown clean flag: #{argument}")
+        else
+          raise Error.unsupported("unexpected clean argument: #{argument}")
+        end
+      end
+      {unused: unused}
+    end
+
     def parse_add_arguments(arguments)
       name = arguments.shift
       raise Error.unsupported("add requires a package name") unless name

data/lib/pray/cli.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 
 require_relative "invocation"
+require_relative "cache_clean"
 require_relative "cli/parse"
 require_relative "cli/help"
 require_relative "cli/suggest"
@@ -29,7 +30,11 @@ module Pray
       return if maybe_print_help(arguments)
 
       command = parse_command(arguments)
-      dispatch(command)
+      if %i[install apply update unlock add remove render plan verify drift].include?(command.first)
+        Transaction.run(Invocation.invocation_context.project_root) { dispatch(command) }
+      else
+        dispatch(command)
+      end
     end
 
     def maybe_print_help(arguments)
@@ -97,7 +102,7 @@ module Pray
       in [:outdated, arguments] then outdated_command(arguments)
       in [:explain, name] then explain_command(name)
       in [:vendor] then raise Error.unsupported("vendor is not implemented yet in pray-cli Ruby")
-      in [:clean] then clean_command
+      in [:clean, options] then clean_command(**options)
       in [:tree] then tree_command
       in [:trust_list, options] then trust_list_command(**options)
       in [:trust_show] then trust_show_command

data/lib/pray/config.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "toml-rb"
+require "perfect_toml"
 
 module Pray
   module Config
@@ -22,14 +22,14 @@ module Pray
       path = user_config_path
       return PrayConfig.new unless path && File.file?(path)
 
-      data = TomlRB.load_file(path)
+      data = PerfectTOML.parse(File.read(path, encoding: "UTF-8"))
       PrayConfig.new(
         local: PrayLocalConfig.new(
           package: data.dig("local", "package") || {},
           source: data.dig("local", "source") || {}
         )
       )
-    rescue TomlRB::ParseError => error
+    rescue PerfectTOML::ParseError => error
       raise Error.parse("config", "#{path}: #{error.message}")
     end
 

data/lib/pray/lockfile.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "toml-rb"
+require "perfect_toml"
 
 require_relative "lockfile_serialize"
 
@@ -125,9 +125,9 @@ module Pray
     end
 
     def parse_lockfile(text)
-      data = TomlRB.parse(text)
+      data = PerfectTOML.parse(text)
       from_hash(data)
-    rescue TomlRB::ParseError => error
+    rescue PerfectTOML::ParseError => error
       raise Error.parse("lockfile", error.message)
     end
 
@@ -144,7 +144,7 @@ module Pray
     end
 
     def write_lockfile(path, lockfile)
-      File.write(path, serialize_lockfile(lockfile))
+      Transaction.write_file(path, serialize_lockfile(lockfile))
     end
 
     def write_lockfile_if_changed(path, lockfile)
@@ -153,7 +153,7 @@ module Pray
         return
       end
 
-      File.write(path, serialized)
+      Transaction.write_file(path, serialized)
     end
 
     def lockfiles_equivalent?(left, right)

data/lib/pray/materialize.rb

@@ -4,7 +4,11 @@ module Pray
   module Materialize
     module_function
 
-    def materialize_project(
+    def materialize_project(**options)
+      Transaction.run(Invocation.invocation_context.project_root) { materialize_in_transaction(**options) }
+    end
+
+    def materialize_in_transaction(
       manifest_path: nil,
       frozen: false,
       locked: false,
@@ -40,7 +44,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
+      previous_lockfile = project.previous_lockfile
       next_lockfile = LockfileIO.build_lockfile(
         project.manifest_hash,
         project.environment,
@@ -58,7 +62,7 @@ module Pray
         unless File.exist?(lockfile_path)
           raise Error.verify("missing Prayfile.lock; run install first")
         end
-        existing = Pray.read_lockfile(lockfile_path)
+        existing = previous_lockfile
         unless Pray.lockfiles_equivalent?(existing, next_lockfile)
           raise Error.verify("lockfile needs update; rerun install to refresh Prayfile.lock")
         end
@@ -80,7 +84,7 @@ module Pray
       end
 
       if frozen
-        existing = File.exist?(lockfile_path) ? Pray.read_lockfile(lockfile_path) : nil
+        existing = previous_lockfile
         if existing
           rendered.each do |target|
             output_path = File.join(project.project_root, target.path)

data/lib/pray/path_safety.rb

@@ -80,5 +80,25 @@ module Pray
 
       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

@@ -10,14 +10,13 @@ module Pray
 
     module_function
 
-    def build_materialization_preview(project, rendered, lockfile, lockfile_path, previous_lockfile)
+    def build_materialization_preview(project, rendered, lockfile, _lockfile_path, previous_lockfile)
+      destinations = RenderDest.validate_destinations!(project, previous_lockfile)
       MaterializationPreview.new(
         package_lines: package_summary_lines(previous_lockfile, lockfile, project),
-        lockfile: lockfile_change_status(lockfile_path, lockfile),
+        lockfile: lockfile_change_status(previous_lockfile, lockfile),
         targets: rendered.map { |target| target_change(project, target) },
-        provisioned: Render.planned_provisioned_files(project).map do |file|
-          provisioned_change(project, file, previous_lockfile)
-        end,
+        provisioned: destinations.map { |file, status| [file.path, status.to_s] },
         warnings: []
       )
     end
@@ -51,10 +50,9 @@ module Pray
       end
     end
 
-    def lockfile_change_status(lockfile_path, lockfile)
-      return "create" unless File.exist?(lockfile_path)
+    def lockfile_change_status(existing, lockfile)
+      return "create" unless existing
 
-      existing = Pray.read_lockfile(lockfile_path)
       Pray.lockfiles_equivalent?(lockfile, existing) ? "unchanged" : "update"
     end
 
@@ -62,7 +60,7 @@ module Pray
       path = File.join(project.project_root, target.path)
       change = if !File.exist?(path)
         "write"
-      elsif File.read(path) == target.content
+      elsif RenderDest.read_regular_bytes(path, target.path) == target.content.b
         "unchanged"
       else
         "update"

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

@@ -25,20 +25,10 @@ module Pray
     end
 
     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))
-        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, previous_lockfile)
+      Transaction.run(project.project_root) { RenderDest.write_rendered_targets(project, rendered, previous_lockfile) }
     end
 
-    def materialize_provisioned_exports(project, previous_lockfile = nil)
-      RenderDest.materialize(project, previous_lockfile)
-    end
+    def materialize_provisioned_exports(project, previous_lockfile = nil) = RenderDest.materialize(project, previous_lockfile)
 
     def expected_provisioned_bytes(source, symbols)
       bytes = File.binread(source)
@@ -306,6 +296,7 @@ module Pray
       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?
 
+      relative_root = relative_project_path(project, destination_root)
       matched = false
       relative_files.each do |relative|
         next if !only.empty? && !only.include?(relative)
@@ -314,9 +305,9 @@ module Pray
         source = File.join(source_root, relative)
         raise Error.render("provisioned file missing: #{source}") unless File.file?(source)
 
-        destination = File.join(destination_root, relative)
+        destination = Pathname(File.join(relative_root, relative)).cleanpath.to_s
         planned << PlannedProvisionedFile.new(
-          path: relative_project_path(project, destination),
+          path: destination,
           source: source,
           package: package_name,
           export: export_name

data/lib/pray/render_dest.rb

@@ -7,6 +7,19 @@ module Pray
   module RenderDest
     module_function
 
+    def write_rendered_targets(project, rendered, previous_lockfile = nil)
+      validate_destinations!(project, previous_lockfile)
+      rendered.each do |target|
+        PathSafety.validate_destination_path!(target.path)
+        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))
+        ensure_safe_destination_ancestors!(project.project_root, target.path, target.path)
+        write_rendered_content(path, target.path, target.content)
+      end
+      materialize(project, previous_lockfile)
+    end
+
     def materialize(project, previous_lockfile = nil)
       planned = Render.planned_provisioned_files(project)
       previous = previous_map(previous_lockfile)
@@ -40,15 +53,40 @@ module Pray
       Array(lockfile.provisioned).to_h { |record| [record.path, record] }
     end
 
-    def destination_status(project, file, previous_lockfile = nil)
+    def destination_status(project, file, previous_lockfile = nil, previous = previous_map(previous_lockfile))
       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("\\", "/")]
+      record = previous[file.path.to_s.tr("\\", "/")]
       classify_destination(destination, file.path, expected, record)
     end
 
+    def validate_destinations!(project, previous_lockfile = nil)
+      errors = []
+      statuses = []
+      omitted = 0
+      diagnostic_bytes = 0
+      previous = previous_map(previous_lockfile)
+      Render.planned_provisioned_files(project).each do |file|
+        statuses << [file, destination_status(project, file, previous_lockfile, previous)]
+      rescue Error => error
+        raise unless error.category == :render
+
+        message = "#{error.message} (package `#{file.package}`, export `#{file.export}`)"
+        if errors.length < 100 && diagnostic_bytes + message.bytesize < 60 * 1024
+          diagnostic_bytes += message.bytesize
+          errors << message
+        else
+          omitted += 1
+        end
+      end
+      errors << "#{omitted} additional destination conflicts omitted; resolve the listed paths and run `pray plan` again" if omitted > 0
+      raise Error.render(errors.join("\n")) unless errors.empty?
+
+      statuses
+    end
+
     def write_leaf(project, file, previous)
       PathSafety.validate_destination_path!(file.path)
       ensure_safe_destination_ancestors!(project.project_root, file.path, file.path)
@@ -84,11 +122,11 @@ module Pray
       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")
+        raise Error.render("refusing to overwrite `#{display}`; it was written by pray and then edited. Inspect your changes and move the file aside, then run `pray install`")
       end
 
       raise Error.render(
-        "refusing to overwrite `#{display}`; it already exists and is not the expected provisioned file"
+        "refusing to overwrite `#{display}`; its existing contents differ from this package. Inspect the file and move it aside, then run `pray install`. If an older pray wrote it, restore the original Prayfile and package version, run `pray install`, then retry the update"
       )
     end
 
@@ -104,7 +142,7 @@ module Pray
         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)
+          File.delete(destination) unless Transaction.replace(destination, on_disk, nil)
         end
       end
     end
@@ -124,8 +162,10 @@ module Pray
       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)
+        existing = decode_utf8(read_destination_bytes(file, display), display)
         content = RenderPatch.patch_rendered_content(existing, fresh)
+        return if Transaction.replace(path, existing.b, content.b)
+
         file.rewind
         file.truncate(0)
         file.write(content)
@@ -158,6 +198,8 @@ module Pray
     end
 
     def create_bytes(path, display, bytes)
+      return if Transaction.replace(path, nil, bytes.b)
+
       open_path(path, display, File::WRONLY | File::CREAT | File::EXCL) do |file|
         file.write(bytes)
       end
@@ -165,12 +207,14 @@ module Pray
 
     def update_bytes(path, display, bytes, authorized_hash)
       open_regular(path, display, File::RDWR) do |file|
-        on_disk = file.read
+        on_disk = read_destination_bytes(file, display)
         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")
+          raise Error.render("refusing to overwrite `#{display}`; it was written by pray and then edited. Inspect your changes and move the file aside, then run `pray install`")
         end
+        return if Transaction.replace(path, on_disk, bytes.b)
+
         file.rewind
         file.truncate(0)
         file.write(bytes)
@@ -178,7 +222,30 @@ module Pray
     end
 
     def read_regular_bytes(path, display)
-      open_regular(path, display, File::RDONLY) { |file| file.read }
+      open_regular(path, display, File::RDONLY) { |file| read_destination_bytes(file, display) }
+    end
+
+    MAX_DESTINATION_BYTES = 32 * 1024 * 1024
+
+    def read_destination_bytes(file, display)
+      if file.stat.size > MAX_DESTINATION_BYTES
+        raise Error.render("refusing to read `#{display}`; destination exceeds the 32 MiB limit")
+      end
+      bytes = +"".b
+      capacity = [file.stat.size + 1, 64 * 1024].min
+      loop do
+        chunk = file.read([capacity, MAX_DESTINATION_BYTES + 1 - bytes.bytesize].min)
+        break unless chunk
+
+        bytes << chunk
+        if bytes.bytesize > MAX_DESTINATION_BYTES
+          raise Error.render("refusing to read `#{display}`; destination exceeds the 32 MiB limit")
+        end
+        break if chunk.bytesize < capacity
+
+        capacity = 64 * 1024
+      end
+      bytes
     end
 
     def decode_utf8(bytes, display)

data/lib/pray/resolve.rb

@@ -3,7 +3,7 @@
 module Pray
   ResolvedProject = Struct.new(
     :manifest_path, :project_root, :manifest, :manifest_hash, :packages,
-    :local_files, :source_revisions, :source_host_keys, :environment
+    :local_files, :source_revisions, :source_host_keys, :environment, :previous_lockfile
   ) do
     def lockfile_hash
       manifest_hash
@@ -107,7 +107,8 @@ module Pray
         local_files: local_files,
         source_revisions: source_revisions,
         source_host_keys: source_host_keys,
-        environment: options.environment
+        environment: options.environment,
+        previous_lockfile: lockfile_hints
       )
     end
 

data/lib/pray/tar_validation.rb

@@ -102,7 +102,10 @@ module Pray
     end
 
     def verify_checksum!(header)
-      stored = parse_octal(header.byteslice(148, 6), "checksum")
+      # The checksum field is eight bytes. Writers fill it differently: six octal
+      # digits then NUL and space, seven digits then NUL, or space padding. Read the
+      # whole field and let parse_octal strip the terminator.
+      stored = parse_octal(header.byteslice(148, 8), "checksum")
       sum = 0
       header.bytes.each_with_index do |byte, index|
         sum += (index >= 148 && index < 156) ? 32 : byte

data/lib/pray/transaction/journal.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "base64"
+require "pathname"
+
+module Pray
+  class TransactionJournal
+    MAX_LOG = 96 * 1024 * 1024
+    MAX_SAVED = 64 * 1024 * 1024
+    MAX_FILE = 32 * 1024 * 1024
+    attr_reader :root
+
+    def initialize(root, directory)
+      @root = root
+      @directory = directory
+      @path = File.join(directory, "journal")
+      @saved = 0
+      @entries = 0
+    end
+
+    def append(record)
+      bytes = JSON.generate(record) + "\n"
+      RenderDest.open_regular(@path, "project recovery journal", File::WRONLY | File::APPEND) do |file|
+        raise Error.render("project recovery journal exceeds its 96 MiB limit") if file.size + bytes.bytesize > MAX_LOG
+
+        file.write(bytes)
+        file.fsync
+      end
+    end
+
+    def replace(path, before, after)
+      return if before == after
+
+      display = Pathname.new(File.expand_path(path)).relative_path_from(Pathname.new(root)).to_s.tr("\\", "/")
+      destination(display)
+      validate_budget(before, after)
+      raise changed(display) if self.class.snapshot(path) != before
+
+      mode = before.nil? ? 0o644 : File.lstat(path).mode & 0o777
+      unless File.exist?(@path)
+        TransactionOwner.private_file(@path, &:fsync)
+        append({"type" => "start", "version" => 1})
+        TransactionOwner.sync_directory(@directory)
+      end
+      append({"type" => "write", "entry" => {"path" => display,
+                                             "before" => before.nil? ? nil : Base64.strict_encode64(before),
+                                             "after_hash" => after.nil? ? nil : Hashing.sha256_prefixed(after), "mode" => mode}})
+      @saved += (before&.bytesize || 0) + (after&.bytesize || 0)
+      @entries += 1
+      install(display, before, after, mode)
+    end
+
+    def validate_budget(before, after)
+      if [before, after].compact.any? { |bytes| bytes.bytesize > MAX_FILE }
+        raise Error.render("destination exceeds the 32 MiB limit")
+      end
+      if @saved + (before&.bytesize || 0) + (after&.bytesize || 0) > MAX_SAVED || @entries == 10_000
+        raise Error.render("project write exceeds the 64 MiB or 10000-file recovery limit")
+      end
+    end
+
+    def destination(display)
+      PathSafety.validate_destination_path!(display)
+      if display == ".pray/write-state" || display.start_with?(".pray/write-state/")
+        raise Error.render("destination overlaps project recovery state")
+      end
+      RenderDest.ensure_safe_destination_ancestors!(root, display, display)
+      File.join(root, display)
+    end
+
+    def install(display, expected, bytes, mode)
+      path = destination(display)
+      FileUtils.mkdir_p(File.dirname(path))
+      destination(display)
+      temporary = File.join(@directory, "#{SecureRandom.hex(16)}.stage")
+      unless bytes.nil?
+        TransactionOwner.private_file(temporary) do |file|
+          file.write(bytes)
+          file.chmod(mode & 0o777)
+          file.fsync
+        end
+      end
+      raise changed(display) if self.class.snapshot(path) != expected
+
+      destination(display)
+      if !bytes.nil? && expected.nil?
+        File.link(temporary, path)
+        File.unlink(temporary)
+      elsif !bytes.nil?
+        File.rename(temporary, path)
+      elsif !expected.nil?
+        File.unlink(path)
+      end
+      sync_parents(path)
+    end
+
+    def sync_parents(path)
+      parent = File.dirname(path)
+      loop do
+        begin
+          TransactionOwner.sync_directory(parent)
+        rescue Errno::ENOENT
+          nil
+        end
+        break if parent == root
+
+        parent = File.dirname(parent)
+      end
+    end
+
+    def recover
+      clean_stages
+      return unless File.exist?(@path)
+
+      entries, undone, committed = TransactionRecords.read(@path)
+      unless committed
+        (entries.length - 1).downto(0) do |index|
+          next if undone.include?(index)
+
+          restore(entries[index])
+          append({"type" => "undone", "index" => index})
+        end
+      end
+      File.unlink(@path)
+      TransactionOwner.sync_directory(@directory)
+      @saved = @entries = 0
+      clean_stages
+    rescue ArgumentError
+      raise Error.render("invalid recovery bytes")
+    end
+
+    def restore(entry)
+      before = entry["before"].nil? ? nil : Base64.strict_decode64(entry["before"])
+      raise Error.render("recovery file exceeds 32 MiB") if before && before.bytesize > MAX_FILE
+
+      current = self.class.snapshot(destination(entry["path"]))
+      if current != before
+        current_hash = current.nil? ? nil : Hashing.sha256_prefixed(current)
+        raise changed(entry["path"]) if !current.nil? && current_hash != entry["after_hash"]
+
+        install(entry["path"], current, before, entry["mode"])
+      end
+      # A prior recovery may have stopped before its directory sync completed.
+      sync_parents(destination(entry["path"]))
+    end
+
+    def commit
+      if File.exist?(@path)
+        append({"type" => "commit"})
+        File.unlink(@path)
+        TransactionOwner.sync_directory(@directory)
+      end
+      clean_stages
+    end
+
+    def clean_stages
+      Dir.children(@directory).each do |name|
+        File.unlink(File.join(@directory, name)) if name.match?(/\A[a-f0-9]{32}\.stage\z/)
+      end
+    end
+
+    def self.snapshot(path)
+      (RenderDest.destination_kind(path) == :missing) ? nil : RenderDest.read_regular_bytes(path, path)
+    end
+
+    def changed(display)
+      Error.render("`#{display}` changed during the interrupted write. Inspect your changes and move the file aside, then retry; recovery data remains in .pray/write-state")
+    end
+  end
+end

data/lib/pray/transaction/owner.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require "securerandom"
+
+module Pray
+  module TransactionOwner
+    module_function
+
+    def acquire(directory, path = File.join(directory, "owner"), depth = 0)
+      raise Error.render("too many interrupted lock recoveries; inspect .pray/write-state") if depth > 16
+
+      owner = {"version" => 1, "pid" => Process.pid, "host" => Socket.gethostname, "token" => SecureRandom.hex(16)}
+      linked = publish_owner(directory, path, owner)
+      if linked
+        sync_directory(directory)
+        return -> { File.unlink(path) if read_owner(path)["token"] == owner["token"] }
+      end
+      previous = read_owner(path)
+      if previous["host"] != Socket.gethostname || alive?(previous["pid"])
+        raise Error.render("another pray command owns this project; retry after it finishes")
+      end
+      # The dead owner's unique token serializes stale-lock removal.
+      release = acquire(directory, File.join(directory, "reclaim-#{previous["token"]}"), depth + 1)
+      begin
+        if read_owner(path)["token"] != previous["token"]
+          raise Error.render("project ownership changed; retry the command")
+        end
+        File.unlink(path)
+        acquire(directory, path, depth + 1)
+      ensure
+        release.call
+      end
+    end
+
+    def publish_owner(directory, path, owner)
+      temporary = File.join(directory, "#{owner["token"]}.owner")
+      private_file(temporary) { |file|
+        file.write(JSON.generate(owner))
+        file.fsync
+      }
+      begin
+        File.link(temporary, path)
+        true
+      rescue Errno::EEXIST
+        false
+      ensure
+        File.unlink(temporary)
+      end
+    end
+
+    def read_owner(path)
+      bytes = RenderDest.read_regular_bytes(path, "project write owner")
+      raise Error.render("invalid project write owner") if bytes.bytesize > 4096
+
+      owner = JSON.parse(bytes)
+      unless owner.is_a?(Hash) && owner["version"] == 1 && owner["pid"].is_a?(Integer) && owner["pid"] > 0 &&
+          owner["host"].is_a?(String) && owner["token"].is_a?(String) && owner["token"].match?(/\A[a-f0-9]{32}\z/)
+        raise Error.render("invalid project write owner")
+      end
+      owner
+    rescue JSON::ParserError
+      raise Error.render("invalid project write owner")
+    end
+
+    def alive?(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    rescue Errno::EPERM, RangeError
+      true
+    end
+
+    def private_file(path, &block)
+      no_follow = File.const_defined?(:NOFOLLOW) ? File::NOFOLLOW : 0
+      File.open(path, File::WRONLY | File::CREAT | File::EXCL | no_follow, 0o600, &block)
+    end
+
+    def sync_directory(path)
+      return if Gem.win_platform?
+
+      File.open(path, File::RDONLY, &:fsync)
+    end
+  end
+end

data/lib/pray/transaction/records.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Pray
+  module TransactionRecords
+    module_function
+
+    def read(path)
+      bytes = RenderDest.open_regular(path, "project recovery journal", File::RDWR) do |file|
+        raise Error.render("project recovery journal exceeds its 96 MiB limit") if file.size > TransactionJournal::MAX_LOG
+
+        contents = file.read(TransactionJournal::MAX_LOG + 1) || ""
+        raise Error.render("project recovery journal exceeds its 96 MiB limit") if contents.bytesize > TransactionJournal::MAX_LOG
+
+        complete = (contents.rindex("\n") || -1) + 1
+        file.truncate(complete)
+        file.fsync
+        contents.byteslice(0, complete)
+      end
+      parse(bytes)
+    end
+
+    def parse(bytes)
+      entries = []
+      undone = {}
+      committed = false
+      bytes.lines.each_with_index do |line, index|
+        record = JSON.parse(line)
+        case record["type"]
+        when "start"
+          invalid! unless record["version"] == 1 && index == 0
+        when "write"
+          invalid! unless index > 0 && !committed && undone.empty?
+          validate_entry(record["entry"], entries.length)
+          entries << record["entry"]
+        when "undone"
+          invalid! unless !committed && record["index"].is_a?(Integer) && (0...entries.length).cover?(record["index"])
+          undone[record["index"]] = true
+        when "commit"
+          invalid! unless index > 0 && undone.empty? && !committed
+          committed = true
+        else
+          invalid!
+        end
+      end
+      [entries, undone, committed]
+    rescue JSON::ParserError
+      invalid!
+    end
+
+    def validate_entry(entry, count)
+      invalid! if count >= 10_000
+      invalid! unless entry.is_a?(Hash) && entry["path"].is_a?(String)
+      invalid! unless entry["mode"].is_a?(Integer) && (0..0o777).cover?(entry["mode"])
+      invalid! unless entry["before"].nil? || entry["before"].is_a?(String)
+      if entry["after_hash"]
+        invalid! unless entry["after_hash"].is_a?(String) && entry["after_hash"].match?(/\Asha256:[a-f0-9]{64}\z/)
+      end
+      PathSafety.validate_destination_path!(entry["path"])
+    end
+
+    def invalid!
+      raise Error.render("invalid project recovery journal state")
+    end
+  end
+end

data/lib/pray/transaction.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "transaction/owner"
+require_relative "transaction/journal"
+require_relative "transaction/records"
+
+module Pray
+  module Transaction
+    module_function
+
+    def run(root)
+      root = File.expand_path(root)
+      current = Thread.current[:pray_write_transaction]
+      return yield if current && current.root == root
+      raise Error.render("a command cannot write two projects in one transaction") if current
+
+      RenderDest.ensure_safe_destination_ancestors!(root, ".pray/write-state/owner", "project write state")
+      directory = File.join(root, ".pray/write-state")
+      FileUtils.mkdir_p(directory, mode: 0o700)
+      RenderDest.ensure_safe_destination_ancestors!(root, ".pray/write-state/owner", "project write state")
+      File.open(directory, File::RDONLY | File::NOFOLLOW) { |file| file.chmod(0o700) }
+      [directory, File.join(root, ".pray"), root].each { |path| TransactionOwner.sync_directory(path) }
+      release = TransactionOwner.acquire(directory)
+      begin
+        journal = TransactionJournal.new(root, directory)
+        journal.recover
+        Thread.current[:pray_write_transaction] = journal
+        begin
+          result = yield
+        rescue => error
+          begin
+            journal.recover
+          rescue => recovery
+            raise Error.render("#{error}\nRecovery stopped: #{recovery}")
+          end
+          raise
+        end
+        journal.commit
+        result
+      ensure
+        Thread.current[:pray_write_transaction] = nil
+        release.call
+      end
+    end
+
+    def replace(path, before, after)
+      journal = Thread.current[:pray_write_transaction]
+      return false unless journal
+
+      journal.replace(path, before, after)
+      true
+    end
+
+    def write_file(path, bytes)
+      journal = Thread.current[:pray_write_transaction]
+      return File.binwrite(path, bytes) unless journal
+
+      journal.replace(path, TransactionJournal.snapshot(path), bytes.b)
+    end
+  end
+end

data/lib/pray/trust.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "toml-rb"
+require "perfect_toml"
 require "fileutils"
 
 module Pray
@@ -44,8 +44,8 @@ module Pray
       path = trust_policy_path(home)
       return nil unless File.file?(path)
 
-      parse_policy(TomlRB.load_file(path))
-    rescue TomlRB::ParseError => error
+      parse_policy(PerfectTOML.parse(File.read(path, encoding: "UTF-8")))
+    rescue PerfectTOML::ParseError => error
       raise Error.parse("trust policy", "#{path}: #{error.message}")
     end
 

data/lib/pray/trust_feed.rb

@@ -44,7 +44,7 @@ module Pray
     end
 
     def parse_compromised_toml(body)
-      data = TomlRB.parse(body)
+      data = PerfectTOML.parse(body)
       Array(data["keys"]).filter_map do |entry|
         key = normalize_key(entry["value"].to_s)
         next if key.empty?
@@ -54,7 +54,7 @@ module Pray
           reference: entry["reference"], reported_at: entry["reported_at"]
         )
       end
-    rescue TomlRB::ParseError
+    rescue PerfectTOML::ParseError
       []
     end
 

data/lib/pray/verify.rb

@@ -114,7 +114,7 @@ module Pray
           next
         end
 
-        text = File.read(absolute_path)
+        text = RenderDest.decode_utf8(RenderDest.read_regular_bytes(absolute_path, target_path), target_path)
         rendered_targets[target_path] = text
         lines = text.lines(chomp: true)
         markers = marker_positions(lines)
@@ -165,7 +165,7 @@ module Pray
         )
       end
 
-      VerifyProvisioned.push_findings(project, report)
+      VerifyProvisioned.push_findings(project, report, lockfile)
 
       [report, rendered_targets, fresh_targets]
     end

data/lib/pray/verify_provisioned.rb

@@ -4,8 +4,9 @@ module Pray
   module VerifyProvisioned
     module_function
 
-    def push_findings(project, report)
+    def push_findings(project, report, lockfile)
       push_exclusive_file_export_findings(project, report)
+      previous = RenderDest.previous_map(lockfile)
       Render.planned_provisioned_files(project).each do |file|
         path_text = file.path.to_s.tr("\\", "/")
         absolute = File.join(project.project_root, file.path)
@@ -23,13 +24,20 @@ module Pray
           )
           next
         end
-        destination_bytes = File.binread(absolute)
+        destination_bytes = RenderDest.read_regular_bytes(absolute, path_text)
         expected_bytes = Render.expected_provisioned_bytes(file.source, project.manifest.symbols || {})
-        next if Hashing.sha256_prefixed(destination_bytes) == Hashing.sha256_prefixed(expected_bytes.b)
+        destination_hash = Hashing.sha256_prefixed(destination_bytes)
+        next if destination_hash == Hashing.sha256_prefixed(expected_bytes.b)
 
+        owned = previous[path_text]&.content_hash == destination_hash
+        recovery = if owned
+          "Run `pray install` to restore it."
+        else
+          "Inspect your changes and move the file aside, then run `pray install` to restore it."
+        end
         report.findings << VerificationFinding.new(
           kind: "package_integrity",
-          message: "Provisioned file `#{path_text}` no longer matches package `#{file.package}`. Run `pray install` to restore it."
+          message: "Provisioned file `#{path_text}` no longer matches package `#{file.package}`. #{recovery}"
         )
       end
     end

data/lib/pray/version.rb

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

data/lib/pray.rb

@@ -27,6 +27,7 @@ require_relative "pray/compose_dest"
 require_relative "pray/render_patch"
 require_relative "pray/render"
 require_relative "pray/render_dest"
+require_relative "pray/transaction"
 require_relative "pray/render_layout"
 require_relative "pray/verify_position"
 require_relative "pray/verify_provisioned"

data/pray-cli.gemspec

@@ -39,7 +39,7 @@ Gem::Specification.new do |spec|
     "rubygems_mfa_required" => "true"
   }
 
-  spec.add_dependency "toml-rb", "~> 4.0"
+  spec.add_dependency "perfect_toml", "~> 0.9", ">= 0.9.1"
   spec.add_dependency "base64", "~> 0.2"
 
   spec.add_development_dependency "rspec", "~> 3.13"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pray-cli
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.12.0
 platform: ruby
 authors:
 - Andrei Makarov
@@ -10,19 +10,25 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: toml-rb
+  name: perfect_toml
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.1
 - !ruby/object:Gem::Dependency
   name: base64
   requirement: !ruby/object:Gem::Requirement
@@ -99,6 +105,7 @@ files:
 - lib/pray/archive.rb
 - lib/pray/archive_unpack.rb
 - lib/pray/auth_client.rb
+- lib/pray/cache_clean.rb
 - lib/pray/cli.rb
 - lib/pray/cli/commands/auth.rb
 - lib/pray/cli/commands/distribution.rb
@@ -165,6 +172,10 @@ files:
 - lib/pray/sync.rb
 - lib/pray/tar_validation.rb
 - lib/pray/terminal.rb
+- lib/pray/transaction.rb
+- lib/pray/transaction/journal.rb
+- lib/pray/transaction/owner.rb
+- lib/pray/transaction/records.rb
 - lib/pray/trust.rb
 - lib/pray/trust_feed.rb
 - lib/pray/trust_ops.rb