pray-cli 1.6.0

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Pray
+  module CLI
+    def add_command(name:, constraint: nil, path: nil)
+      manifest_path_value = manifest_path
+      manifest_text = Pray.read_manifest_text(manifest_path_value)
+      manifest = Pray.parse_manifest(manifest_text)
+      if manifest.packages.any? { |package| package.name == name }
+        raise Error.manifest("package #{name} already exists")
+      end
+
+      declaration = Pray.format_package_declaration(
+        ManifestPackage.new(name: name, constraint: constraint || "*", path: path)
+      )
+      File.write(manifest_path_value, insert_manifest_statement(manifest_text, declaration))
+    end
+
+    def remove_command(name)
+      raise Error.manifest("remove requires a package name") unless name
+
+      manifest_path_value = manifest_path
+      manifest_text = Pray.read_manifest_text(manifest_path_value)
+      manifest = Pray.parse_manifest(manifest_text)
+      unless manifest.packages.any? { |package| package.name == name }
+        raise Error.manifest("package #{name} not found")
+      end
+
+      File.write(manifest_path_value, remove_manifest_statement(manifest_text, name))
+      install_command({locked: false, frozen: false, offline: false})
+    end
+
+    def list_command
+      project = resolve_current_project
+      lines = ["Package list"]
+      project.packages.each do |package|
+        lines << "#{package.declaration.name} #{package.spec.version} source=#{package_source_summary(package)} exports=#{format_list(package.selected_exports)}"
+      end
+      puts lines.join("\n")
+    end
+
+    def tree_command
+      project = resolve_current_project
+      package_map = project.packages.to_h { |package| [package.declaration.name, package] }
+      lines = ["Dependency tree"]
+      project.packages.each do |package|
+        render_tree_node(package, package_map, 0, Set.new, lines)
+      end
+      puts lines.join("\n")
+    end
+
+    def package_command
+      project = resolve_current_project
+      project.packages.each do |package|
+        output_path = Archive.package_archive_path(package.declaration.name, package.spec.version)
+        Archive.write_package_archive(package, output_path)
+      end
+    end
+
+    def explain_command(name)
+      raise Error.resolution("explain requires a package name") unless name
+
+      project = resolve_current_project
+      package = project.packages.find { |entry| entry.declaration.name == name }
+      raise Error.resolution("package #{name} not found") unless package
+
+      lockfile = File.exist?(lockfile_path) ? Pray.read_lockfile(lockfile_path) : nil
+      lockfile_package = lockfile&.package&.find { |entry| entry.name == name }
+
+      lines = ["Package explanation"]
+      lines << "name: #{package.declaration.name}"
+      lines << "constraint: #{package.declaration.constraint}"
+      lines << "resolved version: #{package.spec.version}"
+      if package.registry_latest_version
+        lines << "registry latest: #{package.registry_latest_version}"
+      end
+      lines << "source: #{package_source_summary(package)}"
+      lines << "exports: #{format_list(package.selected_exports)}"
+      lines << "dependencies: #{format_list(package.spec.dependencies.map(&:name))}"
+      lines << "tree hash: #{package.tree_hash}"
+      lines << "artifact hash: #{package.artifact_hash}"
+      if lockfile_package
+        lines << "lockfile version: #{lockfile_package.version}"
+        lines << "lockfile path: #{lockfile_package.path}"
+        lines << "lockfile exports: #{format_list(lockfile_package.exports)}"
+      else
+        lines << "lockfile record: missing"
+      end
+      puts lines.join("\n")
+    end
+
+    def outdated_command(_arguments)
+      previous_lockfile = File.exist?(lockfile_path) ? Pray.read_lockfile(lockfile_path) : nil
+      project = resolve_current_project
+      rendered = Render.render_project(project)
+      latest_lockfile = build_lockfile(project, rendered)
+      puts "Outdated packages"
+      if previous_lockfile && Pray.lockfiles_equivalent?(latest_lockfile, previous_lockfile)
+        puts "All packages up to date"
+      else
+        Plan.package_summary_lines(previous_lockfile, latest_lockfile, project).each { |line| puts line }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Pray
+  module CLI
+    def trust_list_command(scope: :all, source_url: nil)
+      puts Trust.list_policy(scope: scope, source_url: source_url)
+    end
+
+    def trust_show_command
+      puts Trust.show_policy_toml
+    end
+
+    def trust_add_key_command(key, match_prefix: nil)
+      Trust.add_allowed_signing_key(key, match_prefix: match_prefix)
+    end
+
+    def trust_remove_key_command(key, match_prefix: nil)
+      Trust.remove_allowed_signing_key(key, match_prefix: match_prefix)
+    end
+
+    def trust_set_signed_command(match_prefix:, enabled:)
+      Trust.set_require_signed_commit(match_prefix, enabled)
+    end
+
+    def trust_set_allow_command(match_prefix:, allow:)
+      Trust.set_allow(match_prefix, allow)
+    end
+
+    def trust_import_repo_command(source_url, match_prefix: nil)
+      clone_url = source_url.delete_prefix("git+")
+      repository = GitSources.git_source_cache_directory(Dir.pwd, clone_url)
+      unless File.directory?(File.join(repository, ".git"))
+        raise Error.resolution(
+          "no cached git repository for #{clone_url} at #{repository}"
+        )
+      end
+
+      added = Trust.import_repo(
+        clone_url, repository, match_prefix: match_prefix || clone_url
+      )
+      puts "imported #{added} key(s) from #{repository}"
+    end
+
+    def trust_import_registry_command(source_url, match_prefix: nil, include_host_key: false)
+      result = Trust.import_registry(
+        source_url, match_prefix: match_prefix, include_host_key: include_host_key
+      )
+      puts "imported #{result[:publishers_added]} publisher fingerprint(s) and " \
+           "#{result[:host_keys_added]} host key(s) for #{match_prefix || source_url}"
+    end
+
+    def trust_check_command(source = nil)
+      source_description, hits = Trust.check_compromised(source)
+      if hits.empty?
+        puts "no compromised trusted signing keys detected (checked against #{source_description})"
+        return
+      end
+
+      hits.each do |key, scopes, matches|
+        puts "[compromised] #{key}"
+        puts "  scopes: #{scopes.join(", ")}"
+        matches.each do |entry|
+          puts "  reason: #{entry.reason}" if entry.reason
+          puts "  reference: #{entry.reference}" if entry.reference
+          puts "  reported_at: #{entry.reported_at}" if entry.reported_at
+        end
+      end
+      raise Error.integrity(
+        "found #{hits.length} compromised trusted key(s) in #{source_description}"
+      )
+    end
+  end
+end

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Pray
+  module CLI
+    def install_command(flags)
+      Pray.materialize_project(
+        manifest_path: manifest_path,
+        frozen: flags[:frozen],
+        locked: flags[:locked],
+        offline: flags[:offline],
+        refresh: flags[:refresh]
+      )
+    end
+
+    def render_command(flags)
+      project = resolve_current_project
+      rendered = Render.render_project(project)
+      if flags[:check]
+        ensure_rendered_outputs_current(project, rendered)
+      else
+        Render.write_rendered_targets(project, rendered)
+      end
+    end
+
+    def verify_command(flags)
+      project = resolve_current_project
+      lockfile = ensure_existing_lockfile(lockfile_path)
+      report = Verify.verify_project(project, lockfile, strict: flags[:strict])
+      puts format_verification_report(report) unless report.clean?
+    end
+
+    def drift_command(flags)
+      project = resolve_current_project
+      lockfile = ensure_existing_lockfile(lockfile_path)
+      report = if flags[:semantic]
+        Verify.inspect_project(project, lockfile)
+      else
+        Verify.drift_project(project, lockfile)
+      end
+      puts format_drift_report(report) unless report.clean?
+    end
+
+    def format_command
+      path = manifest_path
+      original = Pray.read_manifest_text(path)
+      manifest = Pray.parse_manifest(original)
+      project = begin
+        resolve_current_project(ResolveOptions.new(offline: true))
+      rescue Error
+        resolve_current_project
+      end
+      hints = FormatManifest.classify_format_hints(project)
+      formatted = FormatManifest.format_recommended(manifest, hints)
+      File.write(path, formatted) if formatted != original
+
+      return unless File.exist?(lockfile_path)
+
+      lockfile = Pray.read_lockfile(lockfile_path)
+      lockfile.target.each do |target|
+        target.outputs.each do |output|
+          next unless File.exist?(output)
+
+          original_output = File.read(output)
+          formatted_output = format_marker_comments(Hashing.normalize_line_endings(original_output))
+          File.write(output, formatted_output) if formatted_output != original_output
+        end
+      end
+    end
+
+    def plan_command(_arguments)
+      project = Invocation.resolve_current_project_with_git_refresh_fallback(
+        ResolveOptions.new,
+        allow_git_refresh_fallback: true
+      )
+      rendered = Render.render_project(project)
+      lockfile = build_lockfile(project, rendered)
+      previous_lockfile = File.exist?(lockfile_path) ? Pray.read_lockfile(lockfile_path) : nil
+      preview = Plan.build_materialization_preview(
+        project, rendered, lockfile, lockfile_path, previous_lockfile
+      )
+      Plan.print_materialization_report(preview, :plan)
+    end
+
+    def update_command(arguments)
+      package = arguments.reject { |argument| argument.start_with?("--") }.first
+      offline = arguments.include?("--offline")
+      if package
+        manifest = Pray.parse_manifest(Pray.read_manifest_text(manifest_path))
+        unless manifest.packages.any? { |entry| entry.name == package }
+          raise Error.manifest("package #{package} not found")
+        end
+      end
+      install_command({locked: false, frozen: false, offline: offline, refresh: true})
+    end
+
+    def unlock_command(name)
+      raise Error.manifest("unlock requires a package name") unless name
+
+      project = resolve_current_project
+      unless project.manifest.packages.any? { |entry| entry.name == name }
+        raise Error.manifest("package #{name} not found")
+      end
+
+      previous_lockfile = Pray.read_lockfile(lockfile_path)
+      rendered = Render.render_project(project)
+      updated_lockfile = build_lockfile(project, rendered)
+      merged_lockfile = merge_selected_package_update(previous_lockfile, updated_lockfile, name)
+      Pray.write_lockfile(lockfile_path, merged_lockfile)
+      Render.write_rendered_targets(project, rendered)
+      puts "Unlocked #{name}"
+    end
+
+    def merge_selected_package_update(previous, updated, selected_package)
+      merged = updated.dup
+      merged.package = updated.package.map do |package|
+        next package if package.name == selected_package
+
+        previous_package = previous.package.find { |entry| entry.name == package.name }
+        previous_package ? package.dup.tap { |copy| copy.version = previous_package.version } : package
+      end
+      merged
+    end
+  end
+end

data/lib/pray/cli/help.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Pray
+  module CLI
+    module Help
+      DOCS_URL = "https://github.com/kiskolabs/pray"
+
+      WORKFLOW_COMMANDS = [
+        "install [--locked|--frozen|--offline]  resolve, render, and write Prayfile.lock",
+        "plan [--remote]                        preview materialization changes",
+        "apply                                  apply the current plan",
+        "verify [--strict]                      check rendered output against the lockfile",
+        "drift [--semantic]                     compare lockfile to current resolution",
+        "render [--check]                       render targets without updating the lockfile",
+        "format, fmt                            rewrite Prayfile to recommended destination DSL"
+      ].freeze
+
+      PACKAGE_COMMANDS = [
+        "add <name> [constraint] [--path PATH]",
+        "remove <name>",
+        "update [package] [--major] [--latest] [--dry-run] [--json]",
+        "unlock <package>",
+        "vendor                                 copy resolved packages locally",
+        "clean                                  remove local cache and vendor trees"
+      ].freeze
+
+      DISTRIBUTION_COMMANDS = [
+        "publish --root PATH [--server URL ...]",
+        "login --server URL --email EMAIL",
+        "serve [--root PATH] [--host HOST] [--port PORT] [--stdio]",
+        "sync [--root PATH] [--peer URL ...]",
+        "confess <package> | --from-lock SPAN_ID [--accepted|--rejected]"
+      ].freeze
+
+      TRUST_COMMANDS = [
+        "trust list|show|add-key|remove-key|set-signed|set-allow|import-repo|import-registry|check"
+      ].freeze
+
+      INSPECT_COMMANDS = [
+        "list                                   list declared packages",
+        "outdated [--remote]                      show constraint vs resolved versions",
+        "explain <package>                        show why a package was selected",
+        "tree                                     print the dependency tree"
+      ].freeze
+
+      META_COMMANDS = [
+        "init [--targets tool_a,tool_b]",
+        "prayer init                            scaffold a prayer package",
+        "repo init                              scaffold a distribution root",
+        "manifest                               print canonical Prayfile JSON",
+        "package                                build a distributable prayer archive",
+        "version | -V | --version"
+      ].freeze
+
+      COMMAND_HELP = {
+        "install" => <<~TEXT.strip,
+          install — resolve packages, render targets, and update Prayfile.lock
+
+          Usage: pray install [--locked|--frozen|--offline]
+
+          --locked   require an existing lockfile
+          --frozen   require lockfile to match Prayfile exactly
+          --offline  use cache only
+        TEXT
+        "verify" => <<~TEXT.strip,
+          verify — check rendered files against Prayfile.lock
+
+          Usage: pray verify [--strict]
+
+          Without --strict, orphan-marker warnings print to stderr but exit 0.
+          With --strict, any finding fails with exit code 6.
+        TEXT
+        "drift" => <<~TEXT.strip,
+          drift — report differences between lockfile and current resolution
+
+          Usage: pray drift [--semantic]
+
+          Exits with code 6 when drift is found.
+        TEXT
+        "update" => <<~TEXT.strip,
+          update — refresh package versions within constraints
+
+          Usage: pray update [package] [--major] [--latest] [--dry-run] [--json]
+        TEXT
+        "plan" => <<~TEXT.strip,
+          plan — preview install/apply changes
+
+          Usage: pray plan [--remote]
+        TEXT
+        "apply" => "apply — materialize the current resolution plan\n\nUsage: pray apply",
+        "trust" => <<~TEXT.strip,
+          trust — manage client trust policy for remote sources
+
+          Usage: pray trust <subcommand>
+
+          Subcommands: list, show, add-key, remove-key, set-signed, set-allow, import-repo, import-registry, check
+        TEXT
+        "init" => <<~TEXT.strip,
+          init — create a starter Prayfile
+
+          Usage: pray init [--targets tool_a,tool_b]
+        TEXT
+        "add" => <<~TEXT.strip,
+          add — declare a package in Prayfile
+
+          Usage: pray add <name> [constraint] [--path PATH]
+        TEXT
+        "publish" => <<~TEXT.strip,
+          publish — upload packages to a registry or local root
+
+          Usage: pray publish --root PATH [--server URL ...]
+        TEXT
+        "serve" => <<~TEXT.strip
+          serve — run a local registry server
+
+          Usage: pray serve [--root PATH] [--host HOST] [--port PORT] [--stdio]
+        TEXT
+      }.freeze
+
+      module_function
+
+      def print_concise_help
+        puts "pray — reproducible inference input for projects"
+        puts
+        puts "Declare shared instructions in Prayfile, lock versions, and render tool-specific output."
+        puts
+        puts "Getting started:"
+        puts "  pray init"
+        puts "  pray install"
+        puts "  pray plan"
+        puts "  pray apply"
+        puts "  pray verify"
+        puts
+        print_command_groups
+        puts
+        puts "Run `pray help <command>` or `pray <command> --help` for one command."
+        puts "Documentation: #{DOCS_URL}"
+        puts "Exit codes: 0 success; 2 usage/parse; 3 resolution; 4 integrity; 5 render; 6 verify; 8 unsupported."
+      end
+
+      def print_command_help(command)
+        text = COMMAND_HELP[command]
+        return false unless text
+
+        puts text
+        puts
+        puts "Documentation: #{DOCS_URL}"
+        true
+      end
+
+      def print_command_groups
+        puts "Workflow:"
+        WORKFLOW_COMMANDS.each { |line| puts "  #{line}" }
+        puts "Packages:"
+        PACKAGE_COMMANDS.each { |line| puts "  #{line}" }
+        puts "Distribution:"
+        DISTRIBUTION_COMMANDS.each { |line| puts "  #{line}" }
+        puts "Trust:"
+        TRUST_COMMANDS.each { |line| puts "  #{line}" }
+        puts "Inspect:"
+        INSPECT_COMMANDS.each { |line| puts "  #{line}" }
+        puts "Meta:"
+        META_COMMANDS.each { |line| puts "  #{line}" }
+        puts "Global flags: --no-input (disable prompts), --rm (ephemeral home), --trust [--global]"
+      end
+    end
+  end
+end

data/lib/pray/cli/helpers.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Pray
+  module CLI
+    def manifest_path
+      Invocation.manifest_path
+    end
+
+    def lockfile_path
+      Invocation.lockfile_path
+    end
+
+    def project_root
+      Invocation.project_root
+    end
+
+    def resolve_current_project(options = ResolveOptions.new)
+      Invocation.resolve_current_project(options)
+    end
+
+    def default_output_for_target(target)
+      case target
+      when "tool_a" then "INSTRUCTIONS"
+      when "tool_b" then "TOOL_B"
+      else target.upcase
+      end
+    end
+
+    def build_lockfile(project, rendered)
+      LockfileIO.build_lockfile(
+        project.manifest_hash,
+        project.environment,
+        project.project_root,
+        project.manifest.sources,
+        project.manifest.targets,
+        rendered,
+        project.packages,
+        project.source_revisions,
+        project.source_host_keys
+      )
+    end
+
+    def ensure_existing_lockfile(path)
+      raise Error.verify("missing Prayfile.lock; run pray install first") unless File.exist?(path)
+
+      Pray.read_lockfile(path)
+    end
+
+    def ensure_lockfile_current(project, rendered, existing)
+      current = build_lockfile(project, rendered)
+      return if Pray.lockfiles_equivalent?(current, existing)
+
+      raise Error.verify("lockfile needs update; rerun pray install to refresh Prayfile.lock")
+    end
+
+    def ensure_rendered_outputs_current(project, rendered)
+      rendered.each do |target|
+        path = File.join(project.project_root, target.path)
+        on_disk = File.read(path)
+        if on_disk != target.content
+          raise Error.render("#{path} is stale; rerun pray install to regenerate it or pray plan to inspect the diff")
+        end
+      end
+    end
+
+    def insert_manifest_statement(text, statement)
+      lines = text.lines.map(&:chomp)
+      insertion_index = lines.index do |line|
+        trimmed = line.lstrip
+        trimmed.start_with?("local ", "render ")
+      end || lines.length
+      lines.insert(insertion_index, statement)
+      output = lines.join("\n")
+      output += "\n" unless output.end_with?("\n")
+      output
+    end
+
+    def remove_manifest_statement(text, name)
+      lines = text.lines.map(&:chomp)
+      package_prefix = "agent \"#{name}\""
+      alternate_prefix = "agent '#{name}'"
+      index = lines.index do |line|
+        trimmed = line.lstrip
+        trimmed.start_with?(package_prefix, alternate_prefix)
+      end
+      if index
+        lines.delete_at(index)
+        lines.delete_at(index) if index < lines.length && lines[index].strip.empty?
+        lines.delete_at(index - 1) if index.positive? && lines[index - 1].strip.empty?
+      end
+      output = lines.join("\n")
+      output += "\n" unless output.end_with?("\n")
+      output
+    end
+
+    def format_marker_comments(text)
+      lines = text.split("\n", -1).map do |line|
+        canonical_marker_line(line) || line
+      end
+      output = lines.join("\n")
+      output += "\n" unless output.end_with?("\n")
+      output
+    end
+
+    def canonical_marker_line(line)
+      trimmed = line.strip
+      remainder = trimmed.delete_prefix("<!--").strip
+      return nil unless remainder.start_with?("pray:")
+
+      content = remainder.delete_prefix("pray:").strip.delete_suffix("-->").strip
+      return "<!-- pray:0 ignore-comments -->" if content == "0 ignore-comments"
+      return "<!-- pray:#{content} -->" if content.match?(/\A[a-z0-9]+\z/)
+
+      nil
+    end
+
+    def package_source_summary(package)
+      if package.declaration.path
+        "path:#{package.declaration.path}"
+      elsif package.declaration.source
+        "source:#{package.declaration.source}"
+      else
+        "root:#{package.root}"
+      end
+    end
+
+    def format_list(values)
+      values.empty? ? "none" : values.join(", ")
+    end
+
+    def format_verification_report(report)
+      Verify.format_verification_report(report)
+    end
+
+    def format_drift_report(report)
+      Verify.format_drift_report(report)
+    end
+
+    def render_tree_node(package, package_map, depth, ancestry, lines)
+      indent = "  " * depth
+      lines << "#{indent}#{package.declaration.name} #{package.spec.version}"
+      return unless ancestry.add?(package.declaration.name)
+
+      package.spec.dependencies.each do |dependency|
+        resolved = package_map[dependency.name]
+        if resolved
+          if ancestry.include?(resolved.declaration.name)
+            lines << "#{indent}  #{resolved.declaration.name} #{resolved.spec.version} (cycle)"
+          else
+            render_tree_node(resolved, package_map, depth + 1, ancestry, lines)
+          end
+        else
+          lines << "#{indent}  #{dependency.name} (missing)"
+        end
+      end
+    end
+
+    def remove_path_if_exists(path)
+      return unless File.exist?(path)
+
+      File.directory?(path) ? FileUtils.rm_rf(path) : File.delete(path)
+    end
+  end
+end