carson 3.22.0 → 3.23.0

data/lib/carson/runtime/status.rb

@@ -1,10 +1,8 @@
-# Agent briefing — one command to know the full state of the estate.
-# Gathers branch, worktrees, open PRs, stale branches,
-# governance health, and version. Supports human-readable and JSON output.
+# Agent-readable repository status centred on branch deliveries.
 module Carson
 	class Runtime
 		module Status
-			# Entry point for `carson status`. Collects estate state and reports.
+			# Entry point for `carson status`.
 			def status!( json_output: false )
 				data = gather_status
 
@@ -19,63 +17,33 @@ module Carson
 
 			# Portfolio-wide status overview across all governed repositories.
 			def status_all!( json_output: false )
-				repos = config.govern_repos
-				if repos.empty?
+				repositories = config.govern_repos
+				if repositories.empty?
 					puts_line "No governed repositories configured."
 					puts_line "  Run carson onboard in each repo to register."
 					return EXIT_ERROR
 				end
 
-				if json_output
-					results = []
-					repos.each do |repo_path|
-						repo_name = File.basename( repo_path )
-						unless Dir.exist?( repo_path )
-							results << { name: repo_name, status: "error", error: "path not found" }
-							next
-						end
+				results = repositories.map do |repo_path|
+					repo_name = File.basename( repo_path )
+					unless Dir.exist?( repo_path )
+						{ name: repo_name, status: "error", error: "not found" }
+					else
 						begin
 							scoped_runtime = build_scoped_runtime( repo_path: repo_path )
-							data = scoped_runtime.send( :gather_status )
-							results << { name: repo_name, status: "ok" }.merge( data )
+							{ name: repo_name, status: "ok" }.merge( scoped_runtime.send( :gather_status ) )
 						rescue StandardError => exception
-							results << { name: repo_name, status: "error", error: exception.message }
+							{ name: repo_name, status: "error", error: exception.message }
 						end
 					end
-					output.puts JSON.pretty_generate( { command: "status", repos: results } )
-					return EXIT_OK
 				end
 
-				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 )
-						puts_line "#{repo_name}: MISSING"
-						next
-					end
-
-					begin
-						scoped_runtime = build_scoped_runtime( repo_path: repo_path )
-						data = scoped_runtime.send( :gather_status )
-						branch = data.fetch( :branch )
-						dirty = branch.fetch( :dirty ) ? " (dirty)" : ""
-						worktrees = data.fetch( :worktrees )
-						gov = data.fetch( :governance )
-						parts = []
-						parts << branch.fetch( :name ) + dirty
-						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 { |description| puts_line "  pending: #{description}" }
-					rescue StandardError => exception
-						puts_line "#{repo_name}: FAIL (#{exception.message})"
-					end
+				if json_output
+					output.puts JSON.pretty_generate( { command: "status", repos: results, repositories: results } )
+				else
+					puts_line "Carson #{Carson::VERSION} — Portfolio (#{repositories.length} repo#{plural_suffix( count: repositories.length )})"
+					puts_line ""
+					results.each { |result| print_portfolio_status( result: result ) }
 				end
 
 				EXIT_OK
@@ -83,141 +51,77 @@ 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 = {
+				repository = repository_record
+				branch = branch_record
+				deliveries = ledger.active_deliveries( repo_path: repo_root )
+
+				{
 					version: Carson::VERSION,
-					branch: gather_branch_info,
-					worktrees: gather_worktree_info,
-					governance: gather_governance_info
+					repository: {
+						name: repository.name,
+						path: repository.path,
+						authority: repository.authority
+					},
+					branch: {
+						name: branch.name,
+						head: branch.head,
+						worktree: branch.worktree,
+						dirty: working_tree_dirty?,
+						dirty_reason: dirty_worktree_reason,
+						sync: remote_sync_status( branch: branch.name )
+					},
+					branches: deliveries.map { |delivery| status_branch_entry( delivery: delivery ) },
+					stale_branches: gather_stale_branch_info
 				}
-
-				# PR and stale branch data require gh — gather with graceful fallback.
-				if gh_available?
-					data[ :pull_requests ] = gather_pr_info
-					data[ :stale_branches ] = gather_stale_branch_info
-				end
-
-				data
 			end
 
-			# Branch name, clean/dirty state, sync status with remote.
-			def gather_branch_info
-				branch = current_branch
-				dirty = working_tree_dirty?
-				sync = remote_sync_status( branch: branch )
-
-				{ name: branch, dirty: dirty, sync: sync }
+			def status_branch_entry( delivery: )
+				{
+					branch: delivery.branch,
+					worktree_path: delivery.worktree_path,
+					head: delivery.head,
+					pr_number: delivery.pull_request_number,
+					delivery_state: delivery.status,
+					revision_count: delivery.revision_count,
+					summary: delivery.summary,
+					updated_at: delivery.updated_at
+				}
 			end
 
-			# Returns true when the working tree has uncommitted changes.
 			def working_tree_dirty?
 				stdout, _, success, = git_run( "status", "--porcelain" )
 				return true unless success
 				!stdout.strip.empty?
 			end
 
-			# Compares local branch against its remote tracking ref.
-			# Returns :in_sync, :ahead, :behind, :diverged, or :no_remote.
+			def dirty_worktree_reason
+				return nil unless working_tree_dirty?
+				return "main_worktree" if main_worktree_context?
+
+				"working_tree"
+			end
+
+			def main_worktree_context?
+				realpath_safe( repo_root ) == realpath_safe( main_worktree_root )
+			end
+
 			def remote_sync_status( branch: )
 				remote = config.git_remote
 				remote_ref = "#{remote}/#{branch}"
-
-				# Check if the remote ref exists.
 				_, _, exists, = git_run( "rev-parse", "--verify", remote_ref )
 				return :no_remote unless exists
 
 				ahead_behind, _, success, = git_run( "rev-list", "--left-right", "--count", "#{branch}...#{remote_ref}" )
 				return :unknown unless success
 
-				parts = ahead_behind.strip.split( /\s+/ )
-				ahead = parts[ 0 ].to_i
-				behind = parts[ 1 ].to_i
-
+				ahead, behind = ahead_behind.strip.split.map( &:to_i )
 				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.
-			def gather_worktree_info
-				entries = worktree_list
-
-				# Filter output 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 { it.fetch( :path ) == canonical_root }.map do |worktree|
-					{
-						path: worktree.fetch( :path ),
-						name: File.basename( worktree.fetch( :path ) ),
-						branch: worktree.fetch( :branch, nil )
-					}
-				end
-			end
-
-			# Queries open PRs via gh.
-			def gather_pr_info
-				stdout, _, success, = gh_run(
-					"pr", "list", "--state", "open",
-					"--json", "number,title,headRefName,statusCheckRollup,reviewDecision"
-				)
-				return [] unless success
-
-				prs = JSON.parse( stdout ) rescue []
-				prs.map do |pr|
-					ci = summarise_checks( rollup: pr[ "statusCheckRollup" ] )
-					review = pr[ "reviewDecision" ].to_s
-					review_label = review_decision_label( decision: review )
-
-					{
-						number: pr[ "number" ],
-						title: pr[ "title" ],
-						branch: pr[ "headRefName" ],
-						ci: ci,
-						review: review_label
-					}
-				end
-			end
-
-			# Summarises check rollup into a single status word.
-			def summarise_checks( rollup: )
-				entries = Array( rollup )
-				return :none if entries.empty?
-
-				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
-
-			# Translates GitHub review decision to a concise label.
-			def review_decision_label( decision: )
-				case decision.upcase
-				when "APPROVED" then :approved
-				when "CHANGES_REQUESTED" then :changes_requested
-				when "REVIEW_REQUIRED" then :review_required
-				else :none
-				end
-			end
-
-			# Counts local branches that are stale (tracking a deleted upstream).
 			def gather_stale_branch_info
 				stdout, _, success, = git_run( "branch", "-vv" )
 				return { count: 0 } unless success
@@ -226,77 +130,57 @@ module Carson
 				{ count: gone_branches.size }
 			end
 
-			# Quick governance health check: are templates in sync?
-			def gather_governance_info
-				result = with_captured_output { template_check! }
-				{
-					templates: result == EXIT_OK ? :in_sync : :drifted
-				}
-			rescue StandardError
-				{ templates: :unknown }
-			end
-
-			# Prints the human-readable status report.
 			def print_status( data: )
 				puts_line "Carson #{data.fetch( :version )}"
-				puts_line ""
+				puts_line "Repository: #{data.dig( :repository, :name )}"
+				puts_line "Authority: #{data.dig( :repository, :authority )}"
 
-				# Branch
 				branch = data.fetch( :branch )
-				dirty_marker = branch.fetch( :dirty ) ? " (dirty)" : ""
-				sync_marker = format_sync( sync: branch.fetch( :sync ) )
-				puts_line "Branch: #{branch.fetch( :name )}#{dirty_marker}#{sync_marker}"
-
-				# Worktrees
-				worktrees = data.fetch( :worktrees )
-				if worktrees.any?
-					puts_line ""
-					puts_line "Worktrees:"
-					worktrees.each do |worktree|
-						branch_label = worktree.fetch( :branch ) || "(detached)"
-						puts_line "  #{worktree.fetch( :name )}  #{branch_label}"
-					end
+				branch_line = "Branch: #{branch.fetch( :name )}"
+				branch_line += " (dirty #{branch.fetch( :dirty_reason )})" if branch.fetch( :dirty )
+				branch_line += " [#{format_sync( sync: branch.fetch( :sync ) )}]"
+				puts_line branch_line
+
+				deliveries = data.fetch( :branches )
+				if deliveries.empty?
+					puts_line "Deliveries: none"
+					return
 				end
 
-				# Pull requests
-				prs = data.fetch( :pull_requests, nil )
-				if prs && prs.any?
-					puts_line ""
-					puts_line "Pull requests:"
-					prs.each do |pr|
-						ci_label = pr.fetch( :ci ).to_s
-						review_label = pr.fetch( :review ).to_s.tr( "_", " " )
-						puts_line "  ##{pr.fetch( :number )}  #{pr.fetch( :title )}"
-						puts_line "        CI: #{ci_label}  Review: #{review_label}"
-					end
+				puts_line "Deliveries:"
+				deliveries.each do |delivery|
+					line = "- #{delivery.fetch( :delivery_state )}: #{delivery.fetch( :branch )}"
+					pr_number = delivery.fetch( :pr_number )
+					line += " (#{"PR ##{pr_number}"} )" if pr_number
+					puts_line line.gsub( " )", ")" )
+					puts_line "  #{delivery.fetch( :summary )}" unless delivery.fetch( :summary ).to_s.empty?
 				end
+			end
 
-				# Stale branches
-				stale = data.fetch( :stale_branches, nil )
-				if stale && stale.fetch( :count ) > 0
-					count = stale.fetch( :count )
-					puts_line ""
-					puts_line "#{count} stale #{ count == 1 ? 'branch' : 'branches' } ready for pruning."
+			def print_portfolio_status( result: )
+				if result.fetch( :status ) == "error"
+					puts_line "#{result.fetch( :name )}: #{result.fetch( :error )}"
+					return
 				end
 
-				# Governance
-				gov = data.fetch( :governance )
-				templates = gov.fetch( :templates )
-				unless templates == :in_sync
-					puts_line ""
-					puts_line "Templates: #{templates} — run `carson sync` to fix."
+				deliveries = Array( result.fetch( :branches, [] ) )
+				counts = deliveries.each_with_object( Hash.new( 0 ) ) { |delivery, memo| memo[ delivery.fetch( :delivery_state ) ] += 1 }
+				summary = if counts.empty?
+					"no active deliveries"
+				else
+					counts.map { |state, count| "#{count} #{state}" }.join( ", " )
 				end
+				puts_line "#{result.fetch( :name )}: #{result.dig( :repository, :authority )} — #{summary}"
 			end
 
-			# Formats sync status for display.
 			def format_sync( sync: )
 				case sync
-				when :in_sync then ""
-				when :ahead then " (ahead of remote)"
-				when :behind then " (behind remote)"
-				when :diverged then " (diverged from remote)"
-				when :no_remote then " (no remote tracking)"
-				else ""
+				when :in_sync then "in sync"
+				when :ahead then "ahead"
+				when :behind then "behind"
+				when :diverged then "diverged"
+				when :no_remote then "no remote"
+				else "unknown"
 				end
 			end
 		end

data/lib/carson/runtime.rb

@@ -33,15 +33,22 @@ module Carson
 			@config = Config.load( repo_root: repo_root )
 			@git_adapter = Adapters::Git.new( repo_root: repo_root )
 			@github_adapter = Adapters::GitHub.new( repo_root: repo_root )
+			@ledger = Ledger.new( path: @config.govern_state_path )
 			@template_sync_result = nil
 		end
 
-		attr_reader :template_sync_result
+		attr_reader :template_sync_result, :ledger
 
 	private
 
 		attr_reader :repo_root, :tool_root, :output, :error, :in, :config, :git_adapter, :github_adapter
 
+		# Ruby 2.6 treats bare `in` awkwardly because of pattern-matching parsing.
+		# Keep the original ivar/reader for compatibility, but expose a safe helper name.
+		def input_stream
+			instance_variable_get( :@in )
+		end
+
 		# Returns true when full diagnostic output is enabled via --verbose.
 		def verbose?
 			@verbose
@@ -74,6 +81,21 @@ module Carson
 			git_capture!( "rev-parse", "--abbrev-ref", "HEAD" ).strip
 		end
 
+		# Current branch head SHA for delivery identity.
+		def current_head
+			git_capture!( "rev-parse", "HEAD" ).strip
+		end
+
+		# Passive repository record for the current runtime context.
+		def repository_record
+			Repository.new( path: repo_root, authority: config.govern_authority, runtime: self )
+		end
+
+		# Passive branch record for the current checkout.
+		def branch_record( name: current_branch )
+			repository_record.branch( name ).reload
+		end
+
 		# Checks local branch existence before restore attempts in ensure blocks.
 		def branch_exists?( branch_name: )
 			_, _, success, = git_run( "show-ref", "--verify", "--quiet", "refs/heads/#{branch_name}" )
@@ -310,9 +332,9 @@ module Carson
 			# so only genuinely active worktrees block the operation.
 			scoped_runtime = build_scoped_runtime( repo_path: repo_path )
 			scoped_runtime.sweep_stale_worktrees!
-			worktrees = scoped_runtime.send( :worktree_list )
-			main_root = scoped_runtime.send( :realpath_safe, repo_path )
-			active = worktrees.reject { |worktree| worktree.fetch( :path ) == main_root }
+			worktrees = scoped_runtime.worktree_list
+			main_root = scoped_runtime.realpath_safe( repo_path )
+			active = worktrees.reject { |worktree| worktree.path == main_root }
 			if active.any?
 				reasons << "#{active.count} active worktree#{active.count == 1 ? '' : 's'}"
 			end
@@ -346,3 +368,16 @@ require_relative "runtime/govern"
 require_relative "runtime/setup"
 require_relative "runtime/status"
 require_relative "runtime/deliver"
+
+# Infrastructure interface for domain objects.
+# Carson::Worktree and future domain objects call these methods
+# on a runtime reference — the way ActiveRecord models use a connection.
+# Defined private for internal use, exposed here for domain object access.
+module Carson
+	class Runtime
+		public :config, :output, :verbose?, :puts_verbose, :puts_line,
+			:git_run, :git_capture!, :main_worktree_root, :realpath_safe,
+			:block_if_outsider_fingerprints!, :branch_absorbed_into_main?,
+			:ledger, :current_head, :repository_record, :branch_record
+	end
+end