pray-cli 1.20.0 → 1.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4eb951f0ca0abc5ac0aa68ab27e63e4f778c92453fddb9a7cca0115dac1526d9
-  data.tar.gz: 28ba1073042c0c2a77138e35a9ae80688cb1a6075dd16cba5ee1b9aef2c9c3af
+  metadata.gz: 98ff5ea4c8847034ac02621b75593119ad7b5810fdde65e25998f0702b326a4a
+  data.tar.gz: a6f9245375fad4ae3b49eeb71e97cb51ccd4554dcd0e98e7acf64cc8b1d1864c
 SHA512:
-  metadata.gz: 260a99edc903d99d235b2d9dd40904490fbcc392d67a07a4323d43b1359fead4428976745e438e17767948a1494262daa97b87650965ffc22366267c8faf5226
-  data.tar.gz: f031ff7ebaeceee86829abac7e2f99f060be902ebc586c00e5ad67135d25958248ac7c4fd5425a12068b67d1a01ebd747cacf53501f2c81cc68f3bdcbcfd838d
+  metadata.gz: a7cf4893383addd2ad24b02f36be80543e4fac33ef93b0f606de2ee4370b4be8998b361ed9739d43424aa872e9c1748009fd04f176aa28a64e2cddda15249b3b
+  data.tar.gz: f4c71dccd6a7f7faf2e4a266893ff693ffdd10827061c85213c87dacd167fc0482d7fac32e67db6ed868809d6a02dff1c9f4fc8b4275d8f74c511be394bb782e

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # CHANGELOG
 
+## Unreleased
+
+## 1.22.0 (2026-10-22)
+
+- Keep and create catalog `derived_metadata` on publish. Unchanged republishes and version appends no longer strip historical summaries, topics, or embeddings.
+- Ignore leftover project git full clones when resolving a shared bare or stub catalog. Install renames those leftovers so they cannot shadow the locked revision.
+- Print a pray-level recovery hint when a locked git revision is missing from the shared bare or when catalog checkout fails.
+- On path-fork upstream merge conflict, name the reset-then-rebrand workflow and tag the error as `upstream_merge_conflict`. `pray update --help` documents the same steps.
+- Print `published` / `unchanged` lines and a count footer after `pray publish` (same shape as `--dry-run`). Add global `-q`/`--quiet` and `-v`/`--verbose` for non-error status stdout across publish, apply, install, plan, doctor, unlock, update, outdated, and would-conflict. Redact URL userinfo in publish and doctor lines.
+- Conflict when a path fork deleted an upstream file and upstream later changes that file, instead of restoring it silently.
+- Publish shared bare git clones through a temporary directory, `*.lock.d`, and `.pray-ready` marker. Prefer `git show` for lazy catalog fill; set `GIT_NO_LAZY_FETCH` when offline.
+- Bound git catalog archive and `git show` blob fills to the same size ceilings as `.praypkg` unpack; probe sizes before buffering; unpack through the shared tar validators instead of system tar.
+- Publish project git catalogs through staging, an advisory lock, and atomic rename; refuse stub `.pray-git-dir` paths that are not the expected shared bare.
+- Recover stale git cache lock directories after ten minutes; wait up to about one minute for a live lock; name the lock path on timeout.
+- Lock catalog file fill and publish blobs through a partial rename; re-check catalog match under the materialize lock.
+- Refuse absolute federation and torrent artifact URLs; refuse URL-shaped registry and catalog artifact paths; validate prayspec member paths on parse and tree hash.
+- Make `pray update --latest --dry-run` list would-conflict path-fork paths before write.
+
+## 1.21.0 (2026-10-21)
+
+- Read package catalogs whose `published_at` is an RFC 3339 string or JSON null.
+- Keep prayer sources under `prayers/<name>/`, beside `prayers/v1/` when this project publishes. `prayers/v1/packages/` is catalog metadata. A root `packages/` folder is not a pray source convention.
+- Prevent commands from changing the calling repository when a Git hook passes repository variables such as `GIT_DIR` or `GIT_WORK_TREE`. Explicit Git configuration, including CI credentials and URL rewrites, still applies.
+- Refuse a damaged Git cache that resolves to a parent repository before changing its remote.
+
 ## 1.20.0 (2026-09-18)
 
 - Fetch a locked git catalog revision during `pray install` when the local cache does not have that commit yet. `pray install --offline` still refuses a missing commit.

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

@@ -13,13 +13,34 @@ module Pray
         print_publish_plan(project, dests)
         return
       end
+      stats = {published: 0, unchanged: 0}
       dests.each do |dest|
         packages = selected_publish_packages(project, dest.packages)
         filtered = project.dup
         filtered.packages = packages
-        Publish.publish_to_root(filtered, dest.root) if dest.root
-        Publish.publish_to_server(filtered, dest.server) if dest.server
+        target = dest.root || dest.server || dest.name
+        if dest.root
+          result = Publish.publish_to_root(
+            filtered,
+            dest.root,
+            dest_name: dest.name,
+            target: target
+          )
+          stats[:published] += result[:published]
+          stats[:unchanged] += result[:unchanged]
+        end
+        if dest.server
+          result = Publish.publish_to_server(
+            filtered,
+            dest.server,
+            dest_name: dest.name,
+            target: target
+          )
+          stats[:published] += result[:published]
+          stats[:unchanged] += result[:unchanged]
+        end
       end
+      print_publish_footer(stats)
     end
 
     def selected_publish_packages(project, listed)
@@ -37,11 +58,21 @@ module Pray
         packages = selected_publish_packages(project, dest.packages)
         target = dest.root || dest.server || dest.name
         packages.each do |package|
-          puts "publish #{package.declaration.name} #{package.spec.version} -> #{dest.name} (#{target})"
+          Terminal.println_stdout(
+            "publish #{package.declaration.name} #{package.spec.version} -> #{Publish.redact_publish_target(dest.name)} (#{Publish.redact_publish_target(target)})"
+          )
         end
       end
     end
 
+    def print_publish_footer(stats)
+      if stats[:published].zero? && stats[:unchanged].zero?
+        Terminal.println_stdout("nothing to publish")
+        return
+      end
+      Terminal.println_stdout("#{stats[:published]} published, #{stats[:unchanged]} unchanged")
+    end
+
     def serve_command(root:, host:, port:, stdio:, to: nil)
       raise Error.unsupported("serve --stdio is not implemented yet in pray-cli Ruby") if stdio
 

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

@@ -102,21 +102,23 @@ module Pray
       project = resolve_current_project
       rendered = Render.render_project(project)
       latest_lockfile = build_lockfile(project, rendered)
-      puts "Outdated packages"
+      Terminal.println_stdout("Outdated packages")
       if previous_lockfile && Pray.lockfiles_equivalent?(latest_lockfile, previous_lockfile)
-        puts "All packages up to date"
+        Terminal.println_stdout("All packages up to date")
       else
-        Plan.package_summary_lines(previous_lockfile, latest_lockfile, project).each { |line| puts line }
+        Plan.package_summary_lines(previous_lockfile, latest_lockfile, project).each do |line|
+          Terminal.println_stdout(line)
+        end
       end
       local_lines = ApplyReport.outdated_local_lines(previous_lockfile, project)
       unless local_lines.empty?
-        puts "Outdated local files"
-        local_lines.each { |line| puts line }
+        Terminal.println_stdout("Outdated local files")
+        local_lines.each { |line| Terminal.println_stdout(line) }
       end
       fork_lines = Upstream.path_fork_drift_lines(project, previous_lockfile, ResolveOptions.new)
       unless fork_lines.empty?
-        puts "Outdated path forks"
-        fork_lines.each { |line| puts line }
+        Terminal.println_stdout("Outdated path forks")
+        fork_lines.each { |line| Terminal.println_stdout(line) }
       end
     end
   end

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

@@ -52,7 +52,10 @@ module Pray
       )
       print_latest_constraint_plans(manifest_updates, upstream_plans)
 
-      return if dry_run
+      if dry_run
+        Upstream.report_path_upstream_would_conflicts(project, previous, package, options)
+        return
+      end
 
       if !manifest_updates.empty? || !upstream_plans.empty?
         Upstream.apply_path_upstream_latest_constraints(upstream_plans)
@@ -76,16 +79,20 @@ module Pray
 
     def print_latest_constraint_plans(manifest_updates, upstream_plans)
       if manifest_updates.empty? && upstream_plans.empty?
-        puts "All package constraints already allow latest versions"
+        Terminal.println_stdout("All package constraints already allow latest versions")
         return
       end
 
       manifest_updates.each do |update|
-        puts "Prayfile: #{update[:name]} constraint #{update[:from_constraint]} -> #{update[:to_constraint]} " \
+        Terminal.println_stdout(
+          "Prayfile: #{update[:name]} constraint #{update[:from_constraint]} -> #{update[:to_constraint]} " \
           "(registry latest #{update[:registry_latest_version]})"
+        )
       end
       upstream_plans.each do |plan|
-        puts "#{plan.package_name} upstream #{plan.current_constraint} -> #{plan.new_constraint} (latest #{plan.latest_version})"
+        Terminal.println_stdout(
+          "#{plan.package_name} upstream #{plan.current_constraint} -> #{plan.new_constraint} (latest #{plan.latest_version})"
+        )
       end
     end
   end

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

@@ -18,7 +18,9 @@ module Pray
       return if flags[:frozen] || flags[:locked]
 
       project = resolve_current_project
-      ApplyReport.local_summary_lines(previous_lockfile, project).each { |line| puts line }
+      ApplyReport.local_summary_lines(previous_lockfile, project).each do |line|
+        Terminal.println_stdout(line)
+      end
     end
 
     def render_command(flags)
@@ -146,7 +148,7 @@ module Pray
       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)
-      puts "Unlocked #{name}"
+      Terminal.println_stdout("Unlocked #{name}")
     end
 
     def merge_selected_package_update(previous, updated, selected_package)

data/lib/pray/cli/help.rb

@@ -52,6 +52,8 @@ module Pray
 
       GLOBAL_OPTIONS = [
         "--no-input            disable prompts",
+        "-q, --quiet           suppress non-error status stdout",
+        "-v, --verbose         extra status detail on stdout",
         "--rm                  use an ephemeral home directory",
         "--trust [--global]    import trust on first use"
       ].freeze
@@ -122,6 +124,8 @@ module Pray
           With no package name, update re-resolves the whole graph within constraints
           and refreshes git source revisions. A package name unlocks that package only.
           Path-fork packages can refresh from upstream.
+          When a branded path fork conflicts, reset conflicting content to the locked upstream,
+          run update --latest, re-apply overlays, then bump the fork version.
           Listed local compose files are re-embedded by pray install, not by update.
 
           --latest adjusts constraints to allow the latest package versions.
@@ -151,6 +155,9 @@ module Pray
           Usage: pray publish [--root PATH] [--server URL ...] [--to NAME] [--dry-run]
 
           Prayfile publish remotes supply dests when flags are omitted.
+          Live publish prints published or unchanged lines and a short count footer.
+          --dry-run prints the planned lines without writing.
+          Global -q/--quiet suppresses this stdout; -v/--verbose adds artifact paths.
         TEXT
         "login" => <<~TEXT.strip,
           authenticate to a registry server
@@ -207,11 +214,19 @@ module Pray
           The default directory is prayers/. Use --path to choose another.
           Declares pray "<source>/<name>" once, such as pray "local/project", inside compose when a compose block exists.
           The default name is project. The name v1 is reserved for the distribution layout.
+          Named prayers may sit beside prayers/v1/. Keep sources under prayers/<name>/.
           Without a Prayfile, writes a versioned package spec in the current directory.
           Add spec.version before pray package or pray publish.
           A compose file such as .agents/project.md remains a shortcut for one local file.
         TEXT
-        "repo" => "scaffold a distribution root\n\nUsage: pray repo init",
+        "repo" => <<~TEXT.strip,
+          scaffold a distribution root
+
+          Usage: pray repo init
+
+          Writes prayers/v1/. Git install discovers that catalog. Named prayers may sit beside v1/.
+          Keep sources under prayers/<name>/.
+        TEXT
         "manifest" => "print canonical Prayfile JSON\n\nUsage: pray manifest",
         "package" => "build a distributable prayer archive\n\nUsage: pray package",
         "version" => <<~TEXT.strip,

data/lib/pray/cli.rb

@@ -30,6 +30,20 @@ module Pray
       if arguments.delete("--no-input")
         ENV["PRAY_NO_INPUT"] = "1"
       end
+      quiet = false
+      verbose = 0
+      arguments.reject! do |argument|
+        if argument == "--quiet" || argument == "-q"
+          quiet = true
+          true
+        elsif argument == "--verbose" || argument == "-v"
+          verbose += 1
+          true
+        else
+          false
+        end
+      end
+      Terminal.configure_output!(quiet: quiet, verbose: verbose)
       arguments = Invocation.initialize(arguments)
       return if maybe_print_help(arguments)
 

data/lib/pray/derived_metadata.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "digest"
+require "tmpdir"
+require_relative "hashing"
+
+module Pray
+  module DerivedMetadata
+    module_function
+
+    EMBEDDING_MODEL = "pray-hash-bucket-v1"
+    EMBEDDING_DIMENSIONS = 16
+    MAX_SUMMARY_PARTS = 2
+    MAX_TOKEN_COUNT = 512
+    MAX_SNIPPET_LENGTH = 120
+    STOPWORDS = %w[
+      a an and are as at be by for from has have in is it its of on or package the this to was we
+      with you your
+    ].freeze
+
+    def from_package_root(root, spec)
+      analysis = analyze_package_files(root, spec)
+      summary_candidates = collect_spec_summary_candidates(spec)
+      analysis.fetch(:sample_lines).each { |line| push_candidate(summary_candidates, line) }
+      analyzed_text = analysis.fetch(:analyzed_text)
+      if summary_candidates.empty?
+        top_topics(analyzed_text).each { |token| push_candidate(summary_candidates, token) }
+      end
+
+      tokens = tokenize(analyzed_text)
+      topics = top_topics(analyzed_text)
+      categories = infer_categories("#{summary_candidates.join(" \n")} #{topics.join(" ")}")
+      {
+        "summary" => build_summary(summary_candidates),
+        "topics" => topics,
+        "categories" => categories,
+        "possible_effects" => infer_possible_effects(categories),
+        "possible_side_effects" => infer_possible_side_effects(analyzed_text, topics),
+        "embeddings" => [{"model" => EMBEDDING_MODEL, "vector" => hashed_embedding(tokens)}],
+        "file_count" => analysis.fetch(:file_count),
+        "character_count" => analysis.fetch(:character_count),
+        "token_count" => tokens.length
+      }
+    end
+
+    def collect_spec_summary_candidates(spec)
+      summary_candidates = []
+      push_candidate(summary_candidates, spec.summary)
+      push_candidate(summary_candidates, spec.description)
+      spec.exports.each_value { |export| push_candidate(summary_candidates, export.summary) }
+      summary_candidates
+    end
+    private_class_method :collect_spec_summary_candidates
+
+    def analyze_package_files(root, spec)
+      analyzed_text = +""
+      sample_lines = []
+      file_count = 0
+      character_count = 0
+      Array(spec.files).each do |relative|
+        path = File.join(root, relative)
+        next unless File.file?(path)
+
+        normalized = Hashing.normalize_line_endings(File.read(path, encoding: "UTF-8"))
+        line = first_meaningful_line(normalized)
+        push_candidate(sample_lines, line) if line
+        file_count += 1
+        character_count += normalized.chars.count
+        analyzed_text << normalized << "\n"
+      end
+      {analyzed_text: analyzed_text, sample_lines: sample_lines, file_count: file_count,
+       character_count: character_count}
+    end
+    private_class_method :analyze_package_files
+
+    def from_archive_bytes(archive_bytes)
+      Dir.mktmpdir("pray-derived-metadata-") do |directory|
+        Archive.unpack_praypkg(archive_bytes, directory)
+        spec_path = Resolve.find_prayspec_file(directory)
+        spec = Pray.parse_package_spec(File.read(spec_path, encoding: "UTF-8")).canonicalized
+        from_package_root(directory, spec)
+      end
+    end
+
+    def build_summary(candidates)
+      summary = []
+      seen = {}
+      candidates.each do |candidate|
+        normalized = candidate.to_s.strip
+        next if normalized.empty?
+
+        key = normalized.downcase
+        next if seen[key]
+
+        seen[key] = true
+        summary << truncate(normalized, MAX_SNIPPET_LENGTH)
+        break if summary.length == MAX_SUMMARY_PARTS
+      end
+      return "Package metadata" if summary.empty?
+
+      summary.join(" — ")
+    end
+    private_class_method :build_summary
+
+    def top_topics(text)
+      counts = Hash.new(0)
+      tokenize(text).each { |token| counts[token] += 1 }
+      counts.sort_by { |token, count| [-count, token] }.first(5).map(&:first)
+    end
+    private_class_method :top_topics
+
+    def infer_categories(text)
+      lowered = text.downcase
+      categories = []
+      categories << "documentation" if contains_any?(lowered, %w[guide guidance readme documentation doc])
+      categories << "testing" if contains_any?(lowered, %w[test testing fixture spec])
+      categories << "security" if contains_any?(lowered, %w[auth security ssh key sign trust])
+      categories << "automation" if contains_any?(lowered, %w[automation workflow render pipeline agent])
+      categories << "general" if categories.empty?
+      categories.sort.uniq
+    end
+    private_class_method :infer_categories
+
+    def infer_possible_effects(categories)
+      effects = []
+      effects << "clarifies usage" if categories.include?("documentation")
+      effects << "improves validation" if categories.include?("testing")
+      effects << "surfaces trust-sensitive behavior" if categories.include?("security")
+      effects << "reduces manual steps" if categories.include?("automation")
+      effects << "improves package discovery" if effects.empty?
+      effects
+    end
+    private_class_method :infer_possible_effects
+
+    def infer_possible_side_effects(text, topics)
+      side_effects = []
+      if contains_any?(text, %w[write overwrite replace render inject delete])
+        side_effects << "may change generated output or managed files"
+      end
+      if contains_any?(topics.join(" "), %w[publish release deploy])
+        side_effects << "may affect downstream package distribution"
+      end
+      side_effects.sort.uniq
+    end
+    private_class_method :infer_possible_side_effects
+
+    def hashed_embedding(tokens)
+      vector = Array.new(EMBEDDING_DIMENSIONS, 0)
+      tokens.first(MAX_TOKEN_COUNT).each do |token|
+        digest = Digest::SHA256.digest(token)
+        bucket = digest.getbyte(0) % EMBEDDING_DIMENSIONS
+        vector[bucket] += 1
+      end
+      vector
+    end
+    private_class_method :hashed_embedding
+
+    def tokenize(text)
+      tokens = []
+      text.to_s.split(/[^[:alnum:]]+/).each do |raw|
+        token = raw.strip.downcase
+        next if token.length < 4 || STOPWORDS.include?(token)
+
+        tokens << token
+        break if tokens.length == MAX_TOKEN_COUNT
+      end
+      tokens
+    end
+    private_class_method :tokenize
+
+    def contains_any?(text, needles)
+      needles.any? { |needle| text.include?(needle) }
+    end
+    private_class_method :contains_any?
+
+    def push_candidate(candidates, candidate)
+      trimmed = candidate.to_s.strip
+      return if trimmed.empty?
+
+      candidates << truncate(trimmed, MAX_SNIPPET_LENGTH)
+    end
+    private_class_method :push_candidate
+
+    def first_meaningful_line(text)
+      text.each_line.map(&:strip).find { |line| !line.empty? }&.then { |line| truncate(line, MAX_SNIPPET_LENGTH) }
+    end
+    private_class_method :first_meaningful_line
+
+    def truncate(text, limit)
+      text[0...limit].chars.join
+    end
+    private_class_method :truncate
+  end
+end

data/lib/pray/git_cache.rb

@@ -5,6 +5,7 @@ require_relative "hashing"
 require_relative "git_run"
 require_relative "git_store"
 require_relative "git_materialize"
+require_relative "git_legacy"
 
 module Pray
   module GitCache
@@ -18,8 +19,16 @@ module Pray
         offline: offline,
         working_directory: project_root
       )
+      GitLegacy.quarantine_legacy_project_git_checkouts(project_root, clone_url)
       catalog = git_source_cache_directory(project_root, clone_url, sparse_subdir)
-      GitMaterialize.materialize_catalog_tree(db, catalog, revision, sparse_subdir, refresh)
+      GitMaterialize.materialize_catalog_tree(
+        db,
+        catalog,
+        revision,
+        sparse_subdir,
+        refresh,
+        offline: offline
+      )
       [catalog, revision]
     end
 
@@ -29,20 +38,12 @@ module Pray
     end
 
     def git_source_cached_repository(project_root, clone_url)
-      global_cache = GitStore.global_git_cache_directory(clone_url)
-      return global_cache if global_cache && GitStore.global_git_cache_ready?(global_cache)
-
-      shared = git_source_cache_directory(project_root, clone_url)
-      return shared if git_checkout?(shared)
-
-      cache_root = File.join(project_root, ".pray", "cache", "git")
-      return nil unless File.directory?(cache_root)
+      expected = GitStore.global_git_cache_directory(clone_url)
+      return nil unless expected
+      return expected if GitStore.global_git_cache_ready?(expected)
 
-      Dir.children(cache_root).each do |name|
-        path = File.join(cache_root, name)
-        return path if git_checkout?(path) && origin_matches?(path, clone_url)
-      end
-      nil
+      stub_git_dir(git_source_cache_directory(project_root, clone_url), expected) ||
+        find_stub_git_dir(project_root, expected)
     end
 
     def git_checkout?(path)
@@ -53,12 +54,38 @@ module Pray
       Hashing.sha256_prefixed(text)[7, 16]
     end
 
-    def origin_matches?(repository, clone_url)
-      output, status = GitRun.capture_git(repository, "remote", "get-url", "origin")
-      return false unless status.success?
+    def stub_git_dir(catalog, expected)
+      marker = File.join(catalog, GitMaterialize::GIT_DIR_MARKER)
+      return nil unless File.file?(marker)
+
+      git_dir = File.read(marker).strip
+      return nil if git_dir.empty? || !File.exist?(git_dir)
+      return nil unless paths_equal?(git_dir, expected)
+
+      git_dir
+    end
+
+    def find_stub_git_dir(project_root, expected)
+      cache_root = File.join(project_root, ".pray", "cache", "git")
+      return nil unless File.directory?(cache_root)
+
+      Dir.children(cache_root).each do |name|
+        path = File.join(cache_root, name)
+        next if git_checkout?(path)
+
+        git_dir = stub_git_dir(path, expected)
+        return git_dir if git_dir
+      end
+      nil
+    end
+
+    def paths_equal?(left, right)
+      return true if left == right
 
-      origin = output.strip.delete_prefix("git+")
-      origin == clone_url
+      File.realpath(left) == File.realpath(right)
+    rescue Errno::ENOENT
+      false
     end
+    private_class_method :stub_git_dir, :find_stub_git_dir, :paths_equal?
   end
 end

data/lib/pray/git_legacy.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "git_run"
+
+module Pray
+  module GitLegacy
+    module_function
+
+    def quarantine_legacy_project_git_checkouts(project_root, clone_url)
+      cache_root = File.join(project_root, ".pray", "cache", "git")
+      return unless File.directory?(cache_root)
+
+      Dir.children(cache_root).each do |name|
+        next if name.end_with?(".legacy-git")
+
+        path = File.join(cache_root, name)
+        next unless File.exist?(File.join(path, ".git"))
+        next unless origin_matches?(path, clone_url)
+
+        legacy = File.join(cache_root, "#{name}.legacy-git")
+        FileUtils.rm_rf(legacy) if File.exist?(legacy)
+        FileUtils.mv(path, legacy)
+      end
+    end
+
+    def origin_matches?(repository, clone_url)
+      output, status = GitRun.capture_git(repository, "remote", "get-url", "origin")
+      return false unless status.success?
+
+      origin = output.strip.delete_prefix("git+")
+      origin == clone_url
+    end
+    private_class_method :origin_matches?
+  end
+end