carson 3.14.0 → 3.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6187204d01b1fc7f62657f451451a0124e039b265d83379ce8c23e9ba62a346
-  data.tar.gz: d5b11033558afc8847386858bc62d9ba19816636dece60dfe4a5f1708528a50f
+  metadata.gz: b350c2bb611f2357a7ea9a422b8c1c836f551dc22a33c6ed70c9f0409425d208
+  data.tar.gz: 1333080091cb8e945df2c22e3349b4445124dc4ee856dd10de7b557a284c94df
 SHA512:
-  metadata.gz: 005575df223f30f900794447f012d29bfa3c6a939433870da80dd54cdbcb43dd9099413357a049232ffdcd7d7c502996e3d4279a40f310fde576fe991c8659a0
-  data.tar.gz: 9c4c5023488bce12162fbcb0c4746db515c72e2b28618ca35682a3076ec2b3c1c67513af7712cb4238dc76a2fd389f9abf75385baf6d63ea10970be960d949e9
+  metadata.gz: ba0030df2fde050f0fdd971970b4fe0c4053cad7d293076e6f11c6262feb012a7d7466a547a8812f4befbd6364bfed64e06af4308ab84a802611a3c15e16ee57
+  data.tar.gz: ca7d8bab1f94b3981d224d00aeedc388beba5c33f04f54494f5b9ef91e3f693b41440462a298e8c06146773b628a003d9b203ec2d0b3c06918502bfd961056f6

data/RELEASE.md

@@ -5,15 +5,40 @@ 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.15.1
+
+### What changed
+
+- **Dead worktree reaping** — `housekeep` now reaps dead worktrees before pruning. Unblocks prune for branches held by stale worktrees.
+- Two-layer dead check: fast content-absorbed test, then definitive merged-PR evidence via GitHub API. Covers simple merges and rebase/squash cases where main has evolved.
+- Safe removal only — refuses dirty working trees (`git worktree remove` without `--force`).
+- Deletes the local branch after removal (unless protected).
+
+## 3.15.0
+
+### What changed
+
+- **`carson housekeep` command** — sync + prune for repositories. Carson knocks each gate humbly:
+  - `carson housekeep` — serve the repo you are standing in.
+  - `carson housekeep <repo>` — serve a named governed repo (resolved by basename, case-insensitive).
+  - `carson housekeep --all` — knock each governed repo's gate in turn.
+- Supports `--json` for machine-readable output in all three modes.
+
+### UX improvement
+
+- Fixed double-badge display when housekeep summarises prune results.
+- JSON mode suppresses human-readable lines cleanly.
+
 ## 3.14.0
 
 ### What changed
 
 - **`carson repos` command** — lists all governed repositories from Carson's global config. Shows which repos Carson is serving at a glance. Supports `--json` for machine-readable output. Portfolio-level command — works from any directory.
+- **Auto-register on onboard** — `carson onboard` now automatically registers the repository for portfolio governance. No more TTY-only Y/n prompt — onboard means govern.
 
 ### UX improvement
 
-- Bots and humans can now verify which repos Carson oversees with a single command instead of reading raw config JSON.
+- Onboarding is now one step: `carson onboard` sets up hooks, templates, and portfolio registration in a single pass. Works identically in TTY and non-TTY (agent) sessions.
 
 ## 3.13.2
 

data/VERSION

@@ -1 +1 @@
-3.14.0
+3.15.1

data/lib/carson/cli.rb

@@ -12,7 +12,7 @@ module Carson
 				return Runtime::EXIT_OK
 			end
 
-			if %w[repos refresh:all prune:all].include?( command )
+			if %w[repos refresh:all prune:all housekeep:all housekeep:target].include?( command )
 				verbose = parsed.fetch( :verbose, false )
 				runtime = Runtime.new( repo_root: repo_root, tool_root: tool_root, out: out, err: err, verbose: verbose )
 				return dispatch( parsed: parsed, runtime: runtime )
@@ -53,7 +53,7 @@ module Carson
 
 		def self.build_parser
 			OptionParser.new do |opts|
-				opts.banner = "Usage: carson [status [--json]|setup|audit [--json]|sync [--json]|deliver [--merge] [--json] [--title T] [--body-file F]|prune [--all] [--json]|worktree [--json] create|remove <name>|repos [--json]|onboard|refresh [--all]|offboard|template check|apply|review gate|sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
+				opts.banner = "Usage: carson [status [--json]|setup|audit [--json]|sync [--json]|deliver [--merge] [--json] [--title T] [--body-file F]|prune [--all] [--json]|worktree [--json] create|remove <name>|housekeep [repo] [--json]|repos [--json]|onboard|refresh [--all]|offboard|template check|apply|review gate|sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
 			end
 		end
 
@@ -88,6 +88,8 @@ module Carson
 				parse_worktree_subcommand( argv: argv, parser: parser, err: err )
 			when "repos"
 				parse_repos_command( argv: argv, err: err )
+			when "housekeep"
+				parse_housekeep_command( argv: argv, err: err )
 			when "review"
 				parse_named_subcommand( command: command, usage: "gate|sweep", argv: argv, parser: parser, err: err )
 			when "audit"
@@ -310,6 +312,28 @@ module Carson
 			{ command: "repos", json: json_flag }
 		end
 
+		def self.parse_housekeep_command( argv:, err: )
+			all_flag = argv.delete( "--all" ) ? true : false
+			json_flag = argv.delete( "--json" ) ? true : false
+
+			if all_flag && !argv.empty?
+				err.puts "#{BADGE} --all and repo target are mutually exclusive. Use: carson housekeep --all OR carson housekeep [repo]"
+				return { command: :invalid }
+			end
+
+			return { command: "housekeep:all", json: json_flag } if all_flag
+
+			if argv.length > 1
+				err.puts "#{BADGE} Too many arguments for housekeep. Use: carson housekeep [repo]"
+				return { command: :invalid }
+			end
+
+			target = argv.shift
+			return { command: "housekeep:target", target: target, json: json_flag } if target
+
+			{ command: "housekeep", json: json_flag }
+		end
+
 		def self.parse_govern_subcommand( argv:, err: )
 			options = {
 				dry_run: false,
@@ -389,6 +413,12 @@ module Carson
 				runtime.review_sweep!
 			when "repos"
 				runtime.repos!( json_output: parsed.fetch( :json, false ) )
+			when "housekeep"
+				runtime.housekeep!( json_output: parsed.fetch( :json, false ) )
+			when "housekeep:target"
+				runtime.housekeep_target!( target: parsed.fetch( :target ), json_output: parsed.fetch( :json, false ) )
+			when "housekeep:all"
+				runtime.housekeep_all!( json_output: parsed.fetch( :json, false ) )
 			when "govern"
 				runtime.govern!(
 					dry_run: parsed.fetch( :dry_run, false ),

data/lib/carson/runtime/housekeep.rb

@@ -0,0 +1,168 @@
+# Housekeeping — sync, reap dead worktrees, and prune for a repository.
+# carson housekeep <repo>  — serve one repo by name or path.
+# carson housekeep         — serve the repo you are standing in.
+# carson housekeep --all   — serve all governed repos.
+require "json"
+require "open3"
+require "stringio"
+
+module Carson
+	class Runtime
+		module Housekeep
+			# Serves the current repo: sync + prune.
+			def housekeep!( json_output: false )
+				housekeep_one( repo_path: repo_root, json_output: json_output )
+			end
+
+			# Resolves a target name to a governed repo, then serves it.
+			def housekeep_target!( target:, json_output: false )
+				repo_path = resolve_governed_repo( target: target )
+				unless repo_path
+					result = { command: "housekeep", status: "error", error: "Not a governed repository: #{target}", recovery: "Run carson repos to see governed repositories." }
+					return housekeep_finish( result: result, exit_code: EXIT_ERROR, json_output: json_output )
+				end
+
+				housekeep_one( repo_path: repo_path, json_output: json_output )
+			end
+
+			# Knocks each governed repo's gate in turn.
+			def housekeep_all!( json_output: false )
+				repos = config.govern_repos
+				if repos.empty?
+					result = { command: "housekeep", status: "error", error: "No governed repositories configured.", recovery: "Run carson onboard in each repo to register." }
+					return housekeep_finish( result: result, exit_code: EXIT_ERROR, json_output: json_output )
+				end
+
+				results = []
+				repos.each { |repo_path| results << housekeep_one_entry( repo_path: repo_path, silent: json_output ) }
+
+				succeeded = results.count { |r| r[ :status ] == "ok" }
+				failed = results.count { |r| r[ :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
+
+			# Removes dead worktrees — those with a merged PR and a clean working tree.
+			# Unblocks prune for the branches they hold.
+			# Two-layer dead check:
+			#   1. Fast: branch content is fully absorbed into main (covers simple cases).
+			#   2. Definitive: a merged PR exists for this branch (covers rebase/squash where
+			#      main has since evolved the same files).
+			def reap_dead_worktrees!
+				return unless gh_available?
+
+				main_root = main_worktree_root
+				worktrees = worktree_list
+
+				worktrees.each do |wt|
+					path = wt.fetch( :path )
+					branch = wt.fetch( :branch, nil )
+					next if path == main_root
+					next unless branch
+					next if cwd_inside_worktree?( worktree_path: path )
+
+					# Dead check: absorbed into main, or merged PR evidence.
+					dead = branch_absorbed_into_main?( branch: branch )
+					unless dead
+						tip_sha = git_capture!( "rev-parse", "--verify", branch ).strip rescue nil
+						if tip_sha
+							merged_pr, = merged_pr_for_branch( branch: branch, branch_tip_sha: tip_sha )
+							dead = !merged_pr.nil?
+						end
+					end
+					next unless dead
+
+					# Remove the worktree (no --force: refuses if dirty working tree).
+					_, _, rm_success, = git_run( "worktree", "remove", path )
+					next unless rm_success
+
+					puts_verbose "reaped dead worktree: #{File.basename( path )} (branch: #{branch})"
+
+					# Delete the local branch now that no worktree holds it.
+					if !config.protected_branches.include?( branch )
+						git_run( "branch", "-D", branch )
+						puts_verbose "deleted branch: #{branch}"
+					end
+				end
+			end
+
+		private
+
+			# Runs sync + prune on one repo and returns the exit code directly.
+			def housekeep_one( repo_path:, json_output: false )
+				entry = housekeep_one_entry( repo_path: repo_path, silent: json_output )
+				ok = entry[ :status ] == "ok"
+				result = { command: "housekeep", status: ok ? "ok" : "error", repos: [ entry ], succeeded: ok ? 1 : 0, failed: ok ? 0 : 1 }
+				housekeep_finish( result: result, exit_code: ok ? EXIT_OK : EXIT_ERROR, json_output: json_output, results: [ entry ], succeeded: result[ :succeeded ], failed: result[ :failed ] )
+			end
+
+			# Runs sync + prune on a single repository. Returns a result hash.
+			def housekeep_one_entry( repo_path:, silent: false )
+				repo_name = File.basename( repo_path )
+				unless Dir.exist?( repo_path )
+					puts_line "#{repo_name}: SKIP (path not found)" unless silent
+					return { name: repo_name, path: repo_path, status: "error", error: "path not found" }
+				end
+
+				buf = verbose? ? out : StringIO.new
+				err_buf = verbose? ? err : StringIO.new
+				rt = Runtime.new( repo_root: repo_path, tool_root: tool_root, out: buf, err: err_buf, verbose: verbose? )
+
+				sync_status = rt.sync!
+				if sync_status == EXIT_OK
+					rt.reap_dead_worktrees!
+					prune_status = rt.prune!
+				end
+
+				ok = sync_status == EXIT_OK && prune_status == EXIT_OK
+				unless verbose? || silent
+					summary = strip_badge( buf.string.lines.last.to_s.strip )
+					puts_line "#{repo_name}: #{summary.empty? ? 'OK' : summary}"
+				end
+
+				{ name: repo_name, path: repo_path, status: ok ? "ok" : "error" }
+			rescue StandardError => e
+				puts_line "#{repo_name}: FAIL (#{e.message})" unless silent
+				{ name: repo_name, path: repo_path, status: "error", error: e.message }
+			end
+
+			# Strips the Carson badge prefix from a message to avoid double-badging.
+			def strip_badge( text )
+				text.sub( /\A#{Regexp.escape( BADGE )}\s*/, "" )
+			end
+
+			# Resolves a user-supplied target to a governed repository path.
+			# Accepts: exact path, expandable path, or basename match (case-insensitive).
+			def resolve_governed_repo( target: )
+				repos = config.govern_repos
+				expanded = File.expand_path( target )
+				return expanded if repos.include?( expanded )
+
+				downcased = File.basename( target ).downcase
+				repos.find { |r| File.basename( r ).downcase == downcased }
+			end
+
+			# Unified output — JSON or human-readable.
+			def housekeep_finish( result:, exit_code:, json_output:, results: nil, succeeded: nil, failed: nil )
+				result[ :exit_code ] = exit_code
+
+				if json_output
+					out.puts JSON.pretty_generate( result )
+				else
+					if results && ( succeeded || failed )
+						total = ( succeeded || 0 ) + ( failed || 0 )
+						puts_line ""
+						puts_line "Housekeep complete: #{succeeded} cleaned, #{failed} failed (#{total} repo#{plural_suffix( count: total )})."
+					elsif result[ :error ]
+						puts_line result[ :error ]
+						puts_line "  #{result[ :recovery ]}" if result[ :recovery ]
+					end
+				end
+
+				exit_code
+			end
+		end
+
+		include Housekeep
+	end
+end

data/lib/carson/runtime.rb

@@ -217,6 +217,7 @@ end
 
 require_relative "runtime/local"
 require_relative "runtime/audit"
+require_relative "runtime/housekeep"
 require_relative "runtime/repos"
 require_relative "runtime/review"
 require_relative "runtime/govern"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 3.14.0
+  version: 3.15.1
 platform: ruby
 authors:
 - Hailei Wang
@@ -54,6 +54,7 @@ files:
 - lib/carson/runtime/audit.rb
 - lib/carson/runtime/deliver.rb
 - lib/carson/runtime/govern.rb
+- lib/carson/runtime/housekeep.rb
 - lib/carson/runtime/local.rb
 - lib/carson/runtime/local/hooks.rb
 - lib/carson/runtime/local/onboard.rb