kettle-gha-pins 0.3.8 → 0.3.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a1c43269ba88dfec876d3107fb7883511cbcec7456353a8e239d74071d0d94e
-  data.tar.gz: 7499e3b722b86736e91a8a1dfde9ea53ab4f261428e5ec6816a83db73f428ece
+  metadata.gz: e39d2df910b12d4b40d0978f63481a73d87a5efcdf6ea58c4966b397d3319470
+  data.tar.gz: 584ac1b59952635a279806c03aba51460a757e9edd2dbcafc5b7f158b8a302dd
 SHA512:
-  metadata.gz: d05a9abcb27812e5db10f60e44e3eb9b2e40cd9747476078a22008dab208a578ed816a93255093255ee86f24ccb5856f2ae1fda212659cd97f005d12a5b6bbfb
-  data.tar.gz: 06bf550cb1113a1acb1363307d6dc4faa902c8d283aae15ecdfffaba658b9391d09606cb8005bb6071a30031bcd72b3046aae3674f2b359789793b78c2e82f59
+  metadata.gz: 43c208e30cd0c6501479f4cf52a48a3e4df4b9192ada22b05017681a4761ffe01ca4abdb0398cf8c523828a32814ef9fcd51cf57f2be46f7ff55b81c89e05237
+  data.tar.gz: a47e19be556a73215a786b4e9fe23b50ac1890e5087ed0b5eea1a14e8e7f9dd1ce8da62d8e95a329949a6e339aacda9c1b8e12cabd0debe167e301ed12ca96f9

data/CHANGELOG.md

@@ -30,6 +30,32 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [0.3.10] - 2026-08-09
+
+- TAG: [v0.3.10][0.3.10t]
+- COVERAGE: 98.08% -- 1022/1042 lines in 8 files
+- BRANCH COVERAGE: 88.03% -- 412/468 branches in 8 files
+- 26.17% documented
+
+### Added
+
+- Add JSON action inventory and cache review modes, strict offline pin resolution, and configurable action metadata TTL handling.
+
+### Fixed
+
+- Keep JSON action inventory and review parsing compatible with Ruby 2.5.
+
+## [0.3.9] - 2026-08-05
+
+- TAG: [v0.3.9][0.3.9t]
+- COVERAGE: 98.36% -- 961/977 lines in 8 files
+- BRANCH COVERAGE: 89.95% -- 394/438 branches in 8 files
+- 25.71% documented
+
+### Fixed
+
+- Emit NDJSON progress events for family orchestration without replaying the full human report.
+
 ## [0.3.8] - 2026-08-05
 
 - TAG: [v0.3.8][0.3.8t]
@@ -271,7 +297,11 @@ Please file a bug if you notice a violation of semantic versioning.
 - kettle-jem-template-20260720-005 - Generated README Support & Community rows
   now include a RubyForum help badge.
 
-[Unreleased]: https://github.com/kettle-dev/kettle-gha-pins/compare/v0.3.8...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-gha-pins/compare/v0.3.10...HEAD
+[0.3.10]: https://github.com/kettle-dev/kettle-gha-pins/compare/v0.3.9...v0.3.10
+[0.3.10t]: https://github.com/kettle-dev/kettle-gha-pins/releases/tag/v0.3.10
+[0.3.9]: https://github.com/kettle-dev/kettle-gha-pins/compare/v0.3.8...v0.3.9
+[0.3.9t]: https://github.com/kettle-dev/kettle-gha-pins/releases/tag/v0.3.9
 [0.3.8]: https://github.com/kettle-dev/kettle-gha-pins/compare/v0.3.7...v0.3.8
 [0.3.8t]: https://github.com/kettle-dev/kettle-gha-pins/releases/tag/v0.3.8
 [0.3.7]: https://github.com/kettle-dev/kettle-gha-pins/compare/v0.3.6...v0.3.7

data/README.md

@@ -155,6 +155,17 @@ cooldown window. The same default can be supplied with
 `KETTLE_GHA_PINS_COOLDOWN_DAYS`. The default is `0`, so checks remain strict
 unless a project opts into a warning window.
 
+The action metadata cache uses a one-day TTL by default. Set `--ttl DAYS` to
+change it; `--ttl 0` forces a refresh. `--offline` trusts the cache without
+checking TTL or contacting GitHub and fails if required repository metadata is
+missing.
+
+For family orchestration, `kettle-gha-pins --list --json` emits the action
+repositories used by a project without network access. A separate
+`kettle-gha-pins --review --input PATH` refreshes the repositories listed in
+that JSON and updates the shared cache. Review refreshes metadata independently
+of the selected major/minor/patch upgrade policy.
+
 `Kettle::Gha::Pins::PersistentActionCache.default_path` intentionally preserves
 the historical `kettle-gha-sha-pins` cache location so command-line tools can
 share action metadata without coupling to each other.
@@ -188,6 +199,14 @@ plan[:updates]
 # => {sha: "...", version: "7.0.0", reason: "upgrade_to_allowed_release"}
 ```
 
+The family-oriented cache workflow is:
+
+```console
+kettle-gha-pins --list --json
+kettle-gha-pins --review --input pins.json
+kettle-gha-pins --offline --write --upgrade major
+```
+
 When two version-equivalent tags point at the same SHA, the rubric keeps the
 more explicit release spelling. For example, `v7` and `v7.0.0` pointing at the
 same commit canonicalize to `v7.0.0`; if they point at different SHAs, both
@@ -563,7 +582,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.961-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-1.042-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/kettle-dev/kettle-gha-pins/blob/main/SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/lib/kettle/gha/pins/cli.rb

@@ -59,6 +59,7 @@ module Kettle
             dry_run: true,
             token: ENV["GITHUB_TOKEN"] || ENV["GH_TOKEN"],
             json: false,
+            events: false,
             validate: true,
             write: false,
             check: false,
@@ -66,9 +67,13 @@ module Kettle
             user_agent: "kettle-gha-pins",
             upgrade: DEFAULT_UPGRADE_LEVEL,
             cache_path: ENV["KETTLE_GHA_SHA_PINS_CACHE"] || PersistentActionCache.default_path,
+            ttl_days: DEFAULT_CACHE_TTL_SECONDS / 86_400.0,
             cooldown_days: cooldown_days,
             clock: clock,
             refresh_cache: false,
+            offline: false,
+            mode: :project,
+            input: nil,
             reject_patterns: Set.new,
             progress: nil
           }
@@ -77,20 +82,43 @@ module Kettle
         def run!
           parse!
 
-          @options[:token] ||= gh_auth_token if @options[:api_base] == API_BASE
+          return list_workflows! if @options[:mode] == :list
+
+          client, persistent_cache = build_client
+          return review_cache!(client: client, persistent_cache: persistent_cache) if @options[:mode] == :review
+
+          run_project!(client: client)
+        rescue Error, GitHubClient::CacheMissError, GitHubClient::RefreshError => error
+          @err.puts("kettle-gha-pins: #{error.message}")
+          2
+        end
+
+        private
+
+        def build_client
+          @options[:token] ||= gh_auth_token if @options[:api_base] == API_BASE && !@options[:offline]
           persistent_cache = if @options[:cache_path].to_s.empty?
             nil
           else
-            PersistentActionCache.new(path: @options[:cache_path])
+            PersistentActionCache.new(
+              path: @options[:cache_path],
+              ttl_seconds: (@options[:ttl_days] * 86_400).to_i,
+              clock: @options[:clock]
+            )
           end
           client = GitHubClient.new(
             token: @options[:token],
             api_base: @options[:api_base],
             user_agent: @options[:user_agent],
             persistent_cache: persistent_cache,
-            refresh_cache: @options[:refresh_cache]
+            refresh_cache: @options[:refresh_cache],
+            offline: @options[:offline],
+            fail_on_refresh_error: @options[:mode] == :review
           )
+          [client, persistent_cache]
+        end
 
+        def run_project!(client:)
           state = {
             files_scanned: 0,
             files_with_changes: 0,
@@ -104,8 +132,10 @@ module Kettle
           }
 
           progress_message("Discovering workflow files under #{display_path(@options[:root])}...")
+          emit_event("start", root: @options[:root])
           workflow_files = discover_workflow_files(@options[:root], @options[:reject_patterns])
           progress_message("Discovered #{workflow_files.length} workflow file(s).")
+          emit_event("workflows", total: workflow_files.length)
 
           workflows = load_workflows(workflow_files, state)
           action_count = workflows.sum { |workflow| workflow[:uses_nodes].count { |node| classify_action_ref(node[:value].to_s) } }
@@ -119,6 +149,7 @@ module Kettle
           )
           action_plan_cache = {}
 
+          completed_actions = 0
           workflows.each do |workflow|
             path = workflow.fetch(:path)
             text = workflow.fetch(:text)
@@ -134,6 +165,7 @@ module Kettle
                 action = parsed_ref[:action]
                 repo_ref = "#{action[:owner]}/#{action[:repo]}"
                 old_ref = action[:ref]
+                cached_before = action_plan_cache.key?(repo_ref)
                 upgrade_plan = resolve_action_plan(
                   cache: action_plan_cache,
                   client: client,
@@ -141,6 +173,16 @@ module Kettle
                   repo_ref: repo_ref,
                   old_ref: old_ref
                 )
+                completed_actions += 1
+                emit_event(
+                  "action",
+                  action_ref: repo_ref,
+                  path: path,
+                  line: node[:line] + 1,
+                  completed: completed_actions,
+                  total: action_count,
+                  cache: (cached_before || (client.respond_to?(:last_versions_cache_hit) && client.last_versions_cache_hit)) ? "hit" : "miss"
+                )
 
                 updates = nil
                 if upgrade_plan[:updates]
@@ -261,6 +303,15 @@ module Kettle
           end
           action_progress.stop
           progress_message("Action resolution checks: #{action_progress.cached_count} cached, #{action_progress.live_count} live.") if action_count.positive?
+          emit_event(
+            "summary",
+            files_scanned: state[:files_scanned],
+            changed_files: state[:changed_files].length,
+            updates: state[:updates],
+            failures: state[:failures],
+            cached: action_progress.cached_count,
+            live: action_progress.live_count
+          )
 
           print_report(state)
           return 2 unless state[:failures].zero?
@@ -269,7 +320,79 @@ module Kettle
           0
         end
 
-        private
+        def list_workflows!
+          state = {files_scanned: 0, failures: 0, errors: []}
+          workflow_files = discover_workflow_files(@options[:root], @options[:reject_patterns])
+          workflows = load_workflows(workflow_files, state)
+          pins = workflows.flat_map do |workflow|
+            workflow.fetch(:uses_nodes).each_with_object([]) do |node, entries|
+              parsed = classify_action_ref(node[:value].to_s)
+              next unless parsed
+
+              action = parsed.fetch(:action)
+              entries << {
+                "repository" => "#{action[:owner]}/#{action[:repo]}",
+                "ref" => action[:ref],
+                "value" => parsed[:value],
+                "path" => workflow[:path],
+                "line" => node[:line].to_i + 1
+              }
+            end
+          end
+          repositories = pins.map { |pin| pin.fetch("repository") }.uniq.sort
+          puts JSON.pretty_generate(
+            "schema_version" => 1,
+            "root" => @options[:root],
+            "repositories" => repositories,
+            "pins" => pins
+          )
+          state[:failures].zero? ? 0 : 2
+        end
+
+        def review_cache!(client:, persistent_cache:)
+          raise Error, "--review requires a writable cache; do not use --cache-path \"\"" unless persistent_cache
+
+          repositories = review_repositories
+          refreshed = repositories.map do |repository|
+            versions = client.versions_for_repo(repository)
+            {
+              "repository" => repository,
+              "versions" => versions.length,
+              "cache" => client.last_versions_cache_hit ? "hit" : "refreshed"
+            }
+          end
+          puts JSON.pretty_generate(
+            "schema_version" => 1,
+            "mode" => "review",
+            "ttl_days" => @options[:ttl_days],
+            "repositories" => refreshed
+          )
+          0
+        end
+
+        def review_repositories
+          source = @options[:input].to_s
+          source = if source.empty? || source == "-"
+            $stdin.read
+          else
+            File.read(source)
+          end
+          payload = JSON.parse(source)
+          entries = if payload.is_a?(Array)
+            payload
+          elsif payload.is_a?(Hash)
+            payload["repositories"] || payload["actions"] || payload["pins"] || []
+          else
+            []
+          end
+          entries.each_with_object([]) do |entry, repositories|
+            value = entry.is_a?(Hash) ? (entry["repository"] || entry["action"] || entry["value"]) : entry
+            repository = value.to_s.split("@", 2).first
+            repositories << repository if repository.match?(%r{\A[^/\s]+/[^/\s]+\z})
+          end.uniq.sort
+        rescue JSON::ParserError => error
+          raise Error, "invalid review JSON: #{error.message}"
+        end
 
         def parse!
           parser = OptionParser.new do |opt|
@@ -304,12 +427,36 @@ module Kettle
             opt.on("--refresh-cache", "Bypass cached action release data and refresh discovered actions") do
               @options[:refresh_cache] = true
             end
+            opt.on("--ttl DAYS", Float, "Cache TTL in days (default: #{@options[:ttl_days]})") do |days|
+              Kernel.abort("Invalid --ttl value #{days.inspect}; use a non-negative number") if days.negative?
+
+              @options[:ttl_days] = days
+            end
+            opt.on("--offline", "Use only the persistent cache; fail on a cache miss") do
+              @options[:offline] = true
+            end
+            opt.on("--list", "List project action pins as JSON without network access") do
+              raise OptionParser::InvalidOption, "--list cannot be combined with --review" if @options[:mode] == :review
+
+              @options[:mode] = :list
+            end
+            opt.on("--review", "Refresh action metadata from JSON input and update the cache") do
+              raise OptionParser::InvalidOption, "--review cannot be combined with --list" if @options[:mode] == :list
+
+              @options[:mode] = :review
+            end
+            opt.on("--input PATH", "Review JSON input path, or - for stdin") do |path|
+              @options[:input] = path
+            end
             opt.on("--cache-path PATH", "Action release cache path (default: #{@options[:cache_path]})") do |path|
               @options[:cache_path] = path
             end
             opt.on("--json", "Emit JSON report") do
               @options[:json] = true
             end
+            opt.on("--events", "Emit line-delimited JSON events") do
+              @options[:events] = true
+            end
             opt.on("--[no-]progress", "Show progress feedback on STDERR (default: on unless --json)") do |bool|
               @options[:progress] = bool
             end
@@ -329,6 +476,9 @@ module Kettle
             end
           end
           parser.parse!(@argv)
+          if @options[:mode] == :review && @options[:offline]
+            raise OptionParser::InvalidOption, "--review cannot be combined with --offline"
+          end
         end
 
         def display_path(path)
@@ -384,7 +534,13 @@ module Kettle
         def progress_enabled?
           return @options[:progress] unless @options[:progress].nil?
 
-          !@options[:json]
+          !@options[:json] && !@options[:events]
+        end
+
+        def emit_event(action, payload = {})
+          return unless @options[:events]
+
+          puts JSON.generate({"event_version" => 1, "type" => "gha_sha_pins_#{action}", "action" => action}.merge(payload))
         end
 
         def progress_message(message)
@@ -858,8 +1014,12 @@ module Kettle
             lines << "Recommended fix: kettle-gha-pins --write --upgrade #{@options[:upgrade]}"
           end
 
-          puts lines.join("
-")
+          output = lines.join("\n")
+          if @options[:events]
+            @err.puts output
+          else
+            puts output
+          end
         end
       end
     end

data/lib/kettle/gha/pins/github_client.rb

@@ -10,12 +10,17 @@ module Kettle
     module Pins
       # Lightweight GitHub API client for commit and release SHA resolution.
       class GitHubClient
-        def initialize(token:, api_base:, user_agent:, persistent_cache: nil, refresh_cache: false, open_timeout: DEFAULT_HTTP_OPEN_TIMEOUT_SECONDS, read_timeout: DEFAULT_HTTP_READ_TIMEOUT_SECONDS, refresh_timeout: DEFAULT_HTTP_REFRESH_TIMEOUT_SECONDS)
+        class CacheMissError < Error; end
+        class RefreshError < Error; end
+
+        def initialize(token:, api_base:, user_agent:, persistent_cache: nil, refresh_cache: false, offline: false, fail_on_refresh_error: false, open_timeout: DEFAULT_HTTP_OPEN_TIMEOUT_SECONDS, read_timeout: DEFAULT_HTTP_READ_TIMEOUT_SECONDS, refresh_timeout: DEFAULT_HTTP_REFRESH_TIMEOUT_SECONDS)
           @token = token
           @api_base = api_base
           @user_agent = user_agent
           @persistent_cache = persistent_cache
           @refresh_cache = refresh_cache
+          @offline = offline
+          @fail_on_refresh_error = fail_on_refresh_error
           @open_timeout = open_timeout
           @read_timeout = read_timeout
           @refresh_timeout = refresh_timeout
@@ -34,15 +39,22 @@ module Kettle
             return @release_cache[repo_ref]
           end
 
+          if @offline
+            cached = @persistent_cache&.versions_for_repo(repo_ref, fresh: false)
+            raise CacheMissError, "offline cache miss for #{repo_ref}" if cached.nil?
+
+            @last_versions_cache_hit = true
+            @release_cache[repo_ref] = cached
+            return cached
+          end
+
           stale = nil
           unless @refresh_cache
             cached = @persistent_cache&.versions_for_repo(repo_ref, fresh: true)
             if cached
-              unless cache_requires_refresh?(repo_ref, cached)
-                @last_versions_cache_hit = true
-                @release_cache[repo_ref] = cached
-                return cached
-              end
+              @last_versions_cache_hit = true
+              @release_cache[repo_ref] = cached
+              return cached
             end
             stale = @persistent_cache&.versions_for_repo(repo_ref, fresh: false)
           end
@@ -50,10 +62,10 @@ module Kettle
           releases = nil
           Timeout.timeout(@refresh_timeout) do
             data = request_json("/repos/#{repo_ref}/releases?per_page=100")
-            return cached_versions(repo_ref, stale) unless data.is_a?(Array)
+            return refresh_failed!(repo_ref, stale, "invalid releases response") unless data.is_a?(Array)
 
             tag_shas = tag_ref_shas(repo_ref)
-            return cached_versions(repo_ref, stale) unless tag_shas
+            return refresh_failed!(repo_ref, stale, "invalid tag response") unless tag_shas
 
             releases = build_release_versions(data, tag_shas)
           end
@@ -61,7 +73,7 @@ module Kettle
           @release_cache[repo_ref] = releases
           releases
         rescue Timeout::Error
-          cached_versions(repo_ref, stale)
+          refresh_failed!(repo_ref, stale, "GitHub refresh timed out")
         end
 
         def commit_sha(repo_ref, ref, refresh: false)
@@ -71,13 +83,15 @@ module Kettle
           return @commit_cache[cache_key] if @commit_cache.key?(cache_key) && !refresh
 
           unless @refresh_cache || refresh
-            cached = @persistent_cache&.ref_sha(repo_ref, ref, fresh: true)
+            cached = @persistent_cache&.ref_sha(repo_ref, ref, fresh: !@offline)
             if cached
               @commit_cache[cache_key] = cached
               return cached
             end
           end
 
+          raise CacheMissError, "offline cache miss for #{repo_ref}@#{ref}" if @offline
+
           data = request_json("/repos/#{repo_ref}/commits/#{uri_encode(ref)}")
           sha = if data.is_a?(Hash)
             data.fetch("sha", "")[0, 40]
@@ -106,24 +120,10 @@ module Kettle
           versions
         end
 
-        # Release tags can be added or retargeted inside the cache TTL. Probe
-        # the latest release before trusting a cached inventory, and refresh
-        # only when that probe identifies a tag or target the cache lacks.
-        def cache_requires_refresh?(repo_ref, cached)
-          latest = request_json("/repos/#{repo_ref}/releases/latest")
-          return false unless latest.is_a?(Hash)
-
-          tag = latest["tag_name"].to_s
-          return false unless VersionRubric.parse(tag)
-
-          cached_entry = cached.find { |entry| entry[:tag].to_s == tag }
-          return true unless cached_entry
-
-          latest_sha = commit_sha(repo_ref, tag, refresh: true)
-          cached_sha = cached_entry[:sha].to_s
-          return !latest_sha.to_s.empty? if cached_sha.empty?
+        def refresh_failed!(repo_ref, stale, message)
+          return cached_versions(repo_ref, stale) unless @fail_on_refresh_error
 
-          !latest_sha.to_s.empty? && latest_sha != cached_sha
+          raise RefreshError, "#{message} for #{repo_ref}"
         end
 
         def build_release_versions(data, tag_shas)

data/lib/kettle/gha/pins/version.rb

@@ -6,7 +6,7 @@ module Kettle
       # Version namespace for this gem.
       module Version
         # Current gem version.
-        VERSION = "0.3.8"
+        VERSION = "0.3.10"
       end
       # Current gem version exposed at the traditional constant location.
       VERSION = Version::VERSION # Traditional Constant Location

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-gha-pins
 version: !ruby/object:Gem::Version
-  version: 0.3.8
+  version: 0.3.10
 platform: ruby
 authors:
 - Peter H. Boling
@@ -301,10 +301,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/kettle-dev/kettle-gha-pins
-  source_code_uri: https://github.com/kettle-dev/kettle-gha-pins/tree/v0.3.8
-  changelog_uri: https://github.com/kettle-dev/kettle-gha-pins/blob/v0.3.8/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-dev/kettle-gha-pins/tree/v0.3.10
+  changelog_uri: https://github.com/kettle-dev/kettle-gha-pins/blob/v0.3.10/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-dev/kettle-gha-pins/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-gha-pins/0.3.8
+  documentation_uri: https://www.rubydoc.info/gems/kettle-gha-pins/0.3.10
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-dev/kettle-gha-pins/wiki
   news_uri: https://www.railsbling.com/tags/kettle-gha-pins