carson 3.18.0 → 3.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c18ffa310a6fdb0b0e1581eba83b9ab7dcb8c88a546c391f83200871e17d7f6
-  data.tar.gz: 77c0d6e97438a1f9512e3dbef51a22981caf1b6b0126ffe8ab3bdbf3c7ec3bbb
+  metadata.gz: 36c68c06630159e0dca3560f62993befe8b50dd324fac5a6f8232895b2a667bd
+  data.tar.gz: 1a4462a8b56b6b7fe505705c30ded47e24a279f4fa775baf56b05ae2e48f450a
 SHA512:
-  metadata.gz: 5ac7c43bd96d94c1013c5ade599bd906dbda305b3c0216c184093b62292de30c93d7b8f7bd0e090ffe13fd272e97345d6adb30b321df3188f48b2e5ef50913d6
-  data.tar.gz: 00da3a36874c8dca3ade2736e2e0d5852018cbe13c7a68cb0af746a59cbcbda51b4f992ebe862a88cf855824d7388c2a3b09b04d5950da385f3bdcf6ff09af12
+  metadata.gz: 3f644435f5ca88527edc597a7b19134b701bc970748b5ef075f9b1e3c600b3be60724d80c8567bb919cf378a9a5da2dc54fcc27f29b0da811c0f3880c990f016
+  data.tar.gz: 12e3651de47f5f741115c58308c2fe344d542bcc94c3f1234e08990b506b6ffa2c518e5f782ea9cb0a86a699111926c6df1f6571724b5ef3d318666889f2a13f

data/RELEASE.md

@@ -5,6 +5,17 @@ Release-note scope rule:
 - `RELEASE.md` records only version deltas, breaking changes, and migration actions.
 - Operational usage guides live in `MANUAL.md` and `API.md`.
 
+## 3.19.0
+
+### What changed
+
+- **Persistent pending tracking for batch operations** — repos skipped during `--all` operations (due to active worktrees, uncommitted changes, or path errors) are now recorded in `~/.carson/cache/batch_pending.json`. On the next run, pending repos are reported and automatically retried. `carson status --all` shows pending operations per repo with attempt count and timestamp.
+- **Ruby 3.4+ `it` implicit parameter** — single-parameter blocks where the parameter is the receiver now use `it` instead of named block variables (e.g. `.map { it.fetch( :name ) }` instead of `.map { |e| e.fetch( :name ) }`). Guard clause early returns replace `elsif` chains in `remote_sync_status`.
+
+### UX improvement
+
+- Batch operations are now self-healing: repos that can't be reached on one run aren't silently forgotten. They're logged with reasons and retried on the next invocation. `carson status --all` makes pending operations visible so the user always knows what needs attention.
+
 ## 3.18.0
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.18.0
+3.19.0

data/lib/carson/runtime/audit.rb

@@ -72,7 +72,7 @@ module Carson
 					fail_n = checks.fetch( :failing_count )
 					pend_n = checks.fetch( :pending_count )
 					total = checks.fetch( :required_total )
-					fail_names = checks.fetch( :failing ).map { |e| e.fetch( :name ) }.join( ", " )
+					fail_names = checks.fetch( :failing ).map { it.fetch( :name ) }.join( ", " )
 					if fail_n.positive? && pend_n.positive?
 						audit_concise_problems << "Checks: #{fail_n} failing (#{fail_names}), #{pend_n} pending of #{total} required."
 					elsif fail_n.positive?
@@ -89,11 +89,11 @@ module Carson
 				if baseline_st == "block"
 					parts = []
 					if default_branch_baseline.fetch( :failing_count ).positive?
-						names = default_branch_baseline.fetch( :failing ).map { |e| e.fetch( :name ) }.join( ", " )
+						names = default_branch_baseline.fetch( :failing ).map { it.fetch( :name ) }.join( ", " )
 						parts << "#{default_branch_baseline.fetch( :failing_count )} failing (#{names})"
 					end
 					if default_branch_baseline.fetch( :pending_count ).positive?
-						names = default_branch_baseline.fetch( :pending ).map { |e| e.fetch( :name ) }.join( ", " )
+						names = default_branch_baseline.fetch( :pending ).map { it.fetch( :name ) }.join( ", " )
 						parts << "#{default_branch_baseline.fetch( :pending_count )} pending (#{names})"
 					end
 					parts << "no check-runs for active workflows" if default_branch_baseline.fetch( :no_check_evidence )
@@ -101,11 +101,11 @@ module Carson
 				elsif baseline_st == "attention"
 					parts = []
 					if default_branch_baseline.fetch( :advisory_failing_count ).positive?
-						names = default_branch_baseline.fetch( :advisory_failing ).map { |e| e.fetch( :name ) }.join( ", " )
+						names = default_branch_baseline.fetch( :advisory_failing ).map { it.fetch( :name ) }.join( ", " )
 						parts << "#{default_branch_baseline.fetch( :advisory_failing_count )} advisory failing (#{names})"
 					end
 					if default_branch_baseline.fetch( :advisory_pending_count ).positive?
-						names = default_branch_baseline.fetch( :advisory_pending ).map { |e| e.fetch( :name ) }.join( ", " )
+						names = default_branch_baseline.fetch( :advisory_pending ).map { it.fetch( :name ) }.join( ", " )
 						parts << "#{default_branch_baseline.fetch( :advisory_pending_count )} advisory pending (#{names})"
 					end
 					audit_concise_problems << "Baseline (#{default_branch_baseline.fetch( :default_branch, config.main_branch )}): #{parts.join( ', ' )}."
@@ -176,6 +176,7 @@ module Carson
 					repo_name = File.basename( repo_path )
 					unless Dir.exist?( repo_path )
 						puts_line "#{repo_name}: FAIL (path not found)"
+						record_batch_skip( command: "audit", repo_path: repo_path, reason: "path not found" )
 						failed += 1
 						next
 					end
@@ -186,16 +187,19 @@ module Carson
 						case status
 						when EXIT_OK
 							puts_line "#{repo_name}: ok" unless verbose?
+							clear_batch_success( command: "audit", repo_path: repo_path )
 							passed += 1
 						when EXIT_BLOCK
 							puts_line "#{repo_name}: BLOCK" unless verbose?
 							blocked += 1
 						else
 							puts_line "#{repo_name}: FAIL" unless verbose?
+							record_batch_skip( command: "audit", repo_path: repo_path, reason: "audit failed" )
 							failed += 1
 						end
 					rescue StandardError => e
 						puts_line "#{repo_name}: FAIL (#{e.message})"
+						record_batch_skip( command: "audit", repo_path: repo_path, reason: e.message )
 						failed += 1
 					end
 				end
@@ -258,7 +262,7 @@ module Carson
 					return report
 				end
 				checks_data = JSON.parse( checks_stdout )
-				pending = checks_data.select { |entry| entry[ "bucket" ].to_s == "pending" }
+				pending = checks_data.select { it[ "bucket" ].to_s == "pending" }
 				failing = checks_data.select { |entry| check_entry_failing?( entry: entry ) }
 				report[ :checks ][ :status ] = checks_success ? "ok" : ( checks_exit == 8 ? "pending" : "attention" )
 				report[ :checks ][ :required_total ] = checks_data.count

data/lib/carson/runtime/housekeep.rb

@@ -34,10 +34,18 @@ module Carson
 				end
 
 				results = []
-				repos.each { |repo_path| results << housekeep_one_entry( repo_path: repo_path, silent: json_output ) }
+				repos.each do |repo_path|
+					entry = housekeep_one_entry( repo_path: repo_path, silent: json_output )
+					if entry[ :status ] == "ok"
+						clear_batch_success( command: "housekeep", repo_path: repo_path )
+					else
+						record_batch_skip( command: "housekeep", repo_path: repo_path, reason: entry[ :error ] || "housekeep failed" )
+					end
+					results << entry
+				end
 
-				succeeded = results.count { |r| r[ :status ] == "ok" }
-				failed = results.count { |r| r[ :status ] != "ok" }
+				succeeded = results.count { it[ :status ] == "ok" }
+				failed = results.count { it[ :status ] != "ok" }
 				result = { command: "housekeep", status: failed.zero? ? "ok" : "partial", repos: results, succeeded: succeeded, failed: failed }
 				housekeep_finish( result: result, exit_code: failed.zero? ? EXIT_OK : EXIT_ERROR, json_output: json_output, results: results, succeeded: succeeded, failed: failed )
 			end

data/lib/carson/runtime/local/onboard.rb

@@ -1,3 +1,7 @@
+# Repository onboarding and refresh lifecycle.
+# Onboard: detect remote, install hooks, apply templates, run initial audit.
+# Refresh: re-apply hooks and templates after Carson upgrade.
+# Refresh all: batch refresh across governed portfolio with safety checks.
 module Carson
 	class Runtime
 		module Local
@@ -44,7 +48,7 @@ module Carson
 					hook_status = prepare!
 					return hook_status unless hook_status == EXIT_OK
 
-					drift_count = template_results.count { |entry| entry.fetch( :status ) != "ok" }
+					drift_count = template_results.count { it.fetch( :status ) != "ok" }
 					template_status = template_apply!
 					return template_status unless template_status == EXIT_OK
 
@@ -64,7 +68,7 @@ module Carson
 				return hook_status unless hook_status == EXIT_OK
 				puts_line "Hooks installed (#{config.managed_hooks.count} hooks)."
 
-				template_drift_count = template_results.count { |entry| entry.fetch( :status ) != "ok" }
+				template_drift_count = template_results.count { it.fetch( :status ) != "ok" }
 				template_status = with_captured_output { template_apply! }
 				return template_status unless template_status == EXIT_OK
 				if template_drift_count.positive?
@@ -82,7 +86,7 @@ module Carson
 
 			# Re-applies hooks, templates, and audit across all governed repositories.
 			# Checks each repo for safety (active worktrees, uncommitted changes) and
-			# skips unsafe repos to avoid disrupting active work.
+			# marks unsafe repos as pending to avoid disrupting active work.
 			def refresh_all!
 				repos = config.govern_repos
 				if repos.empty?
@@ -91,24 +95,32 @@ module Carson
 					return EXIT_ERROR
 				end
 
+				pending_before = pending_repos_for( command: "refresh" )
+				if pending_before.any?
+					puts_line "#{pending_before.length} repo#{plural_suffix( count: pending_before.length )} pending from previous run"
+				end
+
 				puts_line ""
 				puts_line "Refresh all (#{repos.length} repo#{plural_suffix( count: repos.length )})"
 				refreshed = 0
-				skipped = 0
+				pending = 0
 				failed = 0
 
 				repos.each do |repo_path|
 					repo_name = File.basename( repo_path )
 					unless Dir.exist?( repo_path )
 						puts_line "#{repo_name}: FAIL (path not found)"
+						record_batch_skip( command: "refresh", repo_path: repo_path, reason: "path not found" )
 						failed += 1
 						next
 					end
 
 					safety = portfolio_repo_safety( repo_path: repo_path )
 					unless safety.fetch( :safe )
-						puts_line "#{repo_name}: SKIP (#{safety.fetch( :reasons ).join( ', ' )})"
-						skipped += 1
+						reason = safety.fetch( :reasons ).join( ", " )
+						puts_line "#{repo_name}: PENDING (#{reason})"
+						record_batch_skip( command: "refresh", repo_path: repo_path, reason: reason )
+						pending += 1
 						next
 					end
 
@@ -116,16 +128,17 @@ module Carson
 					if status == EXIT_ERROR
 						failed += 1
 					else
+						clear_batch_success( command: "refresh", repo_path: repo_path )
 						refreshed += 1
 					end
 				end
 
 				puts_line ""
 				parts = [ "#{refreshed} refreshed" ]
-				parts << "#{skipped} skipped" if skipped.positive?
+				parts << "#{pending} still pending (will retry on next run)" if pending.positive?
 				parts << "#{failed} failed" if failed.positive?
 				puts_line "Refresh all complete: #{parts.join( ', ' )}."
-				failed.zero? && skipped.zero? ? EXIT_OK : EXIT_ERROR
+				failed.zero? && pending.zero? ? EXIT_OK : EXIT_ERROR
 			end
 
 			def prune_all!
@@ -145,6 +158,7 @@ module Carson
 					repo_name = File.basename( repo_path )
 					unless Dir.exist?( repo_path )
 						puts_line "#{repo_name}: FAIL (path not found)"
+						record_batch_skip( command: "prune", repo_path: repo_path, reason: "path not found" )
 						failed += 1
 						next
 					end
@@ -158,9 +172,16 @@ module Carson
 							summary = buf.string.lines.last.to_s.strip
 							puts_line "#{repo_name}: #{summary.empty? ? 'OK' : summary}"
 						end
-						status == EXIT_ERROR ? ( failed += 1 ) : ( succeeded += 1 )
+						if status == EXIT_ERROR
+							record_batch_skip( command: "prune", repo_path: repo_path, reason: "prune failed" )
+							failed += 1
+						else
+							clear_batch_success( command: "prune", repo_path: repo_path )
+							succeeded += 1
+						end
 					rescue StandardError => e
 						puts_line "#{repo_name}: FAIL (#{e.message})"
+						record_batch_skip( command: "prune", repo_path: repo_path, reason: e.message )
 						failed += 1
 					end
 				end
@@ -227,7 +248,7 @@ module Carson
 				return hook_status unless hook_status == EXIT_OK
 				puts_line "Hooks installed (#{config.managed_hooks.count} hooks)."
 
-				template_drift_count = template_results.count { |entry| entry.fetch( :status ) != "ok" }
+				template_drift_count = template_results.count { it.fetch( :status ) != "ok" }
 				template_status = with_captured_output { template_apply! }
 				return template_status unless template_status == EXIT_OK
 				if template_drift_count.positive?

data/lib/carson/runtime/local/sync.rb

@@ -60,6 +60,7 @@ module Carson
 					repo_name = File.basename( repo_path )
 					unless Dir.exist?( repo_path )
 						puts_line "#{repo_name}: FAIL (path not found)"
+						record_batch_skip( command: "sync", repo_path: repo_path, reason: "path not found" )
 						failed += 1
 						next
 					end
@@ -69,13 +70,16 @@ module Carson
 						status = rt.sync!
 						if status == EXIT_OK
 							puts_line "#{repo_name}: ok" unless verbose?
+							clear_batch_success( command: "sync", repo_path: repo_path )
 							synced += 1
 						else
 							puts_line "#{repo_name}: FAIL" unless verbose?
+							record_batch_skip( command: "sync", repo_path: repo_path, reason: "sync failed" )
 							failed += 1
 						end
 					rescue StandardError => e
 						puts_line "#{repo_name}: FAIL (#{e.message})"
+						record_batch_skip( command: "sync", repo_path: repo_path, reason: e.message )
 						failed += 1
 					end
 				end

data/lib/carson/runtime/local/template.rb

@@ -18,8 +18,8 @@ module Carson
 				puts_verbose "[Template Sync Check]"
 				results = template_results
 				stale = template_superseded_present
-				drift_count = results.count { |entry| entry.fetch( :status ) == "drift" }
-				error_count = results.count { |entry| entry.fetch( :status ) == "error" }
+				drift_count = results.count { it.fetch( :status ) == "drift" }
+				error_count = results.count { it.fetch( :status ) == "error" }
 				stale_count = stale.count
 				results.each do |entry|
 					puts_verbose "template_file: #{entry.fetch( :file )} status=#{entry.fetch( :status )} reason=#{entry.fetch( :reason )}"
@@ -32,7 +32,7 @@ module Carson
 						summary_parts << "#{drift_count} of #{results.count} drifted" if drift_count.positive?
 						summary_parts << "#{stale_count} stale" if stale_count.positive?
 						puts_line "Templates: #{summary_parts.join( ", " )}"
-						results.select { |entry| entry.fetch( :status ) == "drift" }.each { |entry| puts_line "  #{entry.fetch( :file )}" }
+						results.select { it.fetch( :status ) == "drift" }.each { |entry| puts_line "  #{entry.fetch( :file )}" }
 						stale.each { |file| puts_line "  #{file} — superseded" }
 					else
 						puts_line "Templates: #{results.count} files in sync"
@@ -62,6 +62,7 @@ module Carson
 					repo_name = File.basename( repo_path )
 					unless Dir.exist?( repo_path )
 						puts_line "#{repo_name}: FAIL (path not found)"
+						record_batch_skip( command: "template_check", repo_path: repo_path, reason: "path not found" )
 						failed += 1
 						next
 					end
@@ -71,6 +72,7 @@ module Carson
 						status = rt.template_check!
 						if status == EXIT_OK
 							puts_line "#{repo_name}: in sync" unless verbose?
+							clear_batch_success( command: "template_check", repo_path: repo_path )
 							in_sync += 1
 						else
 							puts_line "#{repo_name}: DRIFT" unless verbose?
@@ -78,6 +80,7 @@ module Carson
 						end
 					rescue StandardError => e
 						puts_line "#{repo_name}: FAIL (#{e.message})"
+						record_batch_skip( command: "template_check", repo_path: repo_path, reason: e.message )
 						failed += 1
 					end
 				end
@@ -124,7 +127,7 @@ module Carson
 					removed += 1
 				end
 
-				error_count = results.count { |entry| entry.fetch( :status ) == "error" }
+				error_count = results.count { it.fetch( :status ) == "error" }
 				puts_verbose "template_apply_summary: updated=#{applied} removed=#{removed} error=#{error_count}"
 				unless verbose?
 					if applied.positive? || removed.positive?

data/lib/carson/runtime/status.rb

@@ -49,6 +49,7 @@ module Carson
 				puts_line "Carson #{Carson::VERSION} — Portfolio (#{repos.length} repo#{plural_suffix( count: repos.length )})"
 				puts_line ""
 
+				all_pending = load_batch_pending
 				repos.each do |repo_path|
 					repo_name = File.basename( repo_path )
 					unless Dir.exist?( repo_path )
@@ -68,6 +69,10 @@ module Carson
 						parts << "#{worktrees.count} worktree#{plural_suffix( count: worktrees.count )}" if worktrees.any?
 						parts << "templates #{gov.fetch( :templates )}" unless gov.fetch( :templates ) == :in_sync
 						puts_line "#{repo_name}: #{parts.join( '  ' )}"
+
+						# Show pending operations for this repo.
+						repo_pending = status_pending_for_repo( all_pending: all_pending, repo_path: repo_path )
+						repo_pending.each { |desc| puts_line "  pending: #{desc}" }
 					rescue StandardError => e
 						puts_line "#{repo_name}: FAIL (#{e.message})"
 					end
@@ -78,6 +83,21 @@ module Carson
 
 		private
 
+			# Returns an array of human-readable pending descriptions for a repo.
+			def status_pending_for_repo( all_pending:, repo_path: )
+				descriptions = []
+				all_pending.each do |command, repos|
+					next unless repos.is_a?( Hash ) && repos.key?( repo_path )
+
+					info = repos[ repo_path ]
+					attempts = info.fetch( "attempts", 0 )
+					skipped_at = info.fetch( "skipped_at", nil )
+					time_part = skipped_at ? ", since #{skipped_at[ 11..15 ]}" : ""
+					descriptions << "#{command} (#{attempts} attempt#{attempts == 1 ? '' : 's'}#{time_part})"
+				end
+				descriptions
+			end
+
 			# Collects all status facets into a structured hash.
 			def gather_status
 				data = {
@@ -129,15 +149,10 @@ module Carson
 				ahead = parts[ 0 ].to_i
 				behind = parts[ 1 ].to_i
 
-				if ahead.zero? && behind.zero?
-					:in_sync
-				elsif ahead.positive? && behind.zero?
-					:ahead
-				elsif ahead.zero? && behind.positive?
-					:behind
-				else
-					:diverged
-				end
+				return :in_sync if ahead.zero? && behind.zero?
+				return :ahead if behind.zero?
+				return :behind if ahead.zero?
+				:diverged
 			end
 
 			# Lists all worktrees with branch name.
@@ -147,7 +162,7 @@ module Carson
 				# Filter out the main worktree (the repository root itself).
 				# Use realpath for comparison — git returns canonical paths that may differ from repo_root.
 				canonical_root = realpath_safe( repo_root )
-				entries.reject { |wt| wt.fetch( :path ) == canonical_root }.map do |wt|
+				entries.reject { it.fetch( :path ) == canonical_root }.map do |wt|
 					{
 						path: wt.fetch( :path ),
 						name: File.basename( wt.fetch( :path ) ),
@@ -185,9 +200,9 @@ module Carson
 				entries = Array( rollup )
 				return :none if entries.empty?
 
-				states = entries.map { |c| c[ "conclusion" ].to_s.upcase }
-				return :fail if states.any? { |s| s == "FAILURE" || s == "CANCELLED" || s == "TIMED_OUT" }
-				return :pending if states.any? { |s| s == "" || s == "PENDING" || s == "QUEUED" || s == "IN_PROGRESS" }
+				states = entries.map { it[ "conclusion" ].to_s.upcase }
+				return :fail if states.any? { it == "FAILURE" || it == "CANCELLED" || it == "TIMED_OUT" }
+				return :pending if states.any? { it == "" || it == "PENDING" || it == "QUEUED" || it == "IN_PROGRESS" }
 
 				:pass
 			end

data/lib/carson/runtime.rb

@@ -213,6 +213,70 @@ module Carson
 			github_adapter.run( *args )
 		end
 
+		# --- Batch pending tracking (shared by all --all commands) ---
+
+		# Path to the persistent pending log for batch operations.
+		def batch_pending_path
+			File.join( report_dir_path, "batch_pending.json" )
+		end
+
+		# Reads and parses the pending log. Returns empty hash if missing or corrupt.
+		def load_batch_pending
+			path = batch_pending_path
+			return {} unless File.file?( path )
+
+			JSON.parse( File.read( path ) )
+		rescue StandardError
+			{}
+		end
+
+		# Writes the pending log atomically.
+		def save_batch_pending( data )
+			path = batch_pending_path
+			FileUtils.mkdir_p( File.dirname( path ) )
+			tmp = "#{path}.tmp"
+			File.write( tmp, JSON.pretty_generate( data ) )
+			File.rename( tmp, path )
+		end
+
+		# Adds or updates an entry in the pending log, incrementing attempts.
+		def record_batch_skip( command:, repo_path:, reason: )
+			data = load_batch_pending
+			data[ command ] ||= {}
+			existing = data[ command ][ repo_path ]
+			attempts = existing ? existing.fetch( "attempts", 0 ) + 1 : 1
+			data[ command ][ repo_path ] = {
+				"skipped_at" => Time.now.utc.iso8601,
+				"reason" => reason,
+				"attempts" => attempts
+			}
+			save_batch_pending( data )
+		end
+
+		# Removes an entry from the pending log after successful completion.
+		def clear_batch_success( command:, repo_path: )
+			data = load_batch_pending
+			return unless data.key?( command )
+
+			data[ command ].delete( repo_path )
+			data.delete( command ) if data[ command ].empty?
+			save_batch_pending( data )
+		end
+
+		# Returns array of pending repo info hashes for a command.
+		def pending_repos_for( command: )
+			data = load_batch_pending
+			entries = data.fetch( command, {} )
+			entries.map do |path, info|
+				{
+					path: path,
+					reason: info.fetch( "reason", "unknown" ),
+					skipped_at: info.fetch( "skipped_at", nil ),
+					attempts: info.fetch( "attempts", 0 )
+				}
+			end
+		end
+
 		# --- Portfolio helpers (shared by all --all commands) ---
 
 		# Checks whether a governed repo is safe for batch operations.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 3.18.0
+  version: 3.19.0
 platform: ruby
 authors:
 - Hailei Wang