carson 2.30.0 → 2.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 374e4a7af2ec608b1c3c9d07ca4a5ad8b028715434c1f02fb4b4034a71b153d2
-  data.tar.gz: a795fabcecbe2b43d03f155b0d4b730f804d0879ef4a1fe280cc4e082350c76f
+  metadata.gz: 96820bedb9187d90787072b441c35129457a7d45202899ea520a9bb1e3b50876
+  data.tar.gz: f8963204bde45cee5e7e662dcc5f5bb947e84372f0d24a03d6ef494c3653adbf
 SHA512:
-  metadata.gz: 83b920da278fa2e457c424babaf3b06955a2317f920b5ad3681ae4da8a90fc5d5c3969d7160796b0febc49669a7cf7995c8f83ba674ce7f0865ca72eb6a48cbf
-  data.tar.gz: 8506fe647fe4538a27dd0ef25e0ecbeb1d9c0b78c8251d45b6023e562091cd6c861ef660707684b4e3d202a69728b0779a8a623ceb79313efc7e86eb0b482b17
+  metadata.gz: 616dbf56c4c09e6327767ccaaa8b88595a51ae4e8275290d1b6f1349fb6b2e25cb3789e4891699b3e6b8ff878d209bf4503adcc4974506b1a72ddcee374e432d
+  data.tar.gz: 83b8827df9139e9a81fa587a00816333d37fc87d03a3f7f0388bbd3fb8722138978b7b99844ccbfa6713243a651c4886774f88400c226c060398f1824b64e7ba

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`.
 
+## 2.31.0 — Worktree Lifecycle + Prune --all
+
+### What changed
+
+- **`carson worktree remove <name-or-path>`** — Safe worktree teardown in the correct order: removes the worktree directory and git registration, deletes the local branch, and cleans up the remote branch. Accepts either a full path or a short name (resolves under `.claude/worktrees/`). Prevents agents from being stranded in deleted directories.
+- **`carson prune --all`** — Prunes stale branches across all governed repositories. Same discipline as single-repo prune, applied to the full estate.
+
+### Migration
+
+- No action required. Both commands are additive.
+
 ## 2.30.0 — Prune Rebase Merge Support + Audit Noise Reduction
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-2.30.0
+2.31.0

data/lib/carson/cli.rb

@@ -12,7 +12,7 @@ module Carson
 				return Runtime::EXIT_OK
 			end
 
-			if command == "refresh:all"
+			if %w[refresh:all prune:all].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 [setup [--remote NAME] [--main-branch NAME] [--workflow STYLE] [--merge METHOD] [--canonical PATH]|audit|sync|prune|onboard [repo_path]|refresh [--all|repo_path]|offboard [repo_path]|template check|template apply|review gate|review sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
+				opts.banner = "Usage: carson [setup [--remote NAME] [--main-branch NAME] [--workflow STYLE] [--merge METHOD] [--canonical PATH]|audit|sync|prune [--all]|worktree remove <name-or-path>|onboard [repo_path]|refresh [--all|repo_path]|offboard [repo_path]|template check|template apply|review gate|review sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
 			end
 		end
 
@@ -82,6 +82,10 @@ module Carson
 				parse_refresh_command( argv: argv, parser: parser, err: err )
 			when "template"
 				parse_template_subcommand( argv: argv, parser: parser, err: err )
+			when "prune"
+				parse_prune_command( argv: argv, parser: parser, err: err )
+			when "worktree"
+				parse_worktree_subcommand( argv: argv, parser: parser, err: err )
 			when "review"
 				parse_named_subcommand( command: command, usage: "gate|sweep", argv: argv, parser: parser, err: err )
 			when "govern"
@@ -154,6 +158,35 @@ module Carson
 			}
 		end
 
+		def self.parse_prune_command( argv:, parser:, err: )
+			all_flag = argv.delete( "--all" ) ? true : false
+			parser.parse!( argv )
+			return { command: "prune:all" } if all_flag
+			{ command: "prune" }
+		end
+
+		def self.parse_worktree_subcommand( argv:, parser:, err: )
+			action = argv.shift
+			if action.to_s.strip.empty?
+				err.puts "#{BADGE} Missing subcommand for worktree. Use: carson worktree remove <name-or-path>"
+				err.puts parser
+				return { command: :invalid }
+			end
+
+			case action
+			when "remove"
+				worktree_path = argv.shift
+				if worktree_path.to_s.strip.empty?
+					err.puts "#{BADGE} Missing path for worktree remove. Use: carson worktree remove <name-or-path>"
+					return { command: :invalid }
+				end
+				{ command: "worktree:remove", worktree_path: worktree_path }
+			else
+				err.puts "#{BADGE} Unknown worktree subcommand: #{action}. Use: carson worktree remove <name-or-path>"
+				{ command: :invalid }
+			end
+		end
+
 		def self.parse_named_subcommand( command:, usage:, argv:, parser:, err: )
 			action = argv.shift
 			parser.parse!( argv )
@@ -240,6 +273,10 @@ module Carson
 				runtime.sync!
 			when "prune"
 				runtime.prune!
+			when "prune:all"
+				runtime.prune_all!
+			when "worktree:remove"
+				runtime.worktree_remove!( worktree_path: parsed.fetch( :worktree_path ) )
 			when "onboard"
 				runtime.onboard!
 			when "refresh"

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

@@ -115,6 +115,48 @@ module Carson
 				failed.zero? ? EXIT_OK : EXIT_ERROR
 			end
 
+			def prune_all!
+				repos = config.govern_repos
+				if repos.empty?
+					puts_line "No governed repositories configured."
+					puts_line "  Run carson onboard in each repo to register."
+					return EXIT_ERROR
+				end
+
+				puts_line ""
+				puts_line "Prune all (#{repos.length} repo#{plural_suffix( count: repos.length )})"
+				succeeded = 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)"
+						failed += 1
+						next
+					end
+
+					begin
+						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? )
+						status = rt.prune!
+						unless verbose?
+							summary = buf.string.lines.last.to_s.strip
+							puts_line "#{repo_name}: #{summary.empty? ? 'OK' : summary}"
+						end
+						status == EXIT_ERROR ? ( failed += 1 ) : ( succeeded += 1 )
+					rescue StandardError => e
+						puts_line "#{repo_name}: FAIL (#{e.message})"
+						failed += 1
+					end
+				end
+
+				puts_line ""
+				puts_line "Prune all complete: #{succeeded} pruned, #{failed} failed."
+				failed.zero? ? EXIT_OK : EXIT_ERROR
+			end
+
 			# Removes Carson-managed repository integration so a host repository can retire Carson cleanly.
 			def offboard!
 				puts_verbose ""

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

@@ -0,0 +1,103 @@
+module Carson
+	class Runtime
+		module Local
+			# Safe worktree lifecycle management for coding agents.
+			# Enforces the teardown order: exit worktree → git worktree remove → branch cleanup.
+			def worktree_remove!( worktree_path: )
+				fingerprint_status = block_if_outsider_fingerprints!
+				return fingerprint_status unless fingerprint_status.nil?
+
+				resolved_path = resolve_worktree_path( worktree_path: worktree_path )
+
+				unless worktree_registered?( path: resolved_path )
+					puts_line "ERROR: #{resolved_path} is not a registered worktree."
+					puts_line "  Registered worktrees:"
+					worktree_list.each { |wt| puts_line "  - #{wt.fetch( :path )} [#{wt.fetch( :branch )}]" }
+					return EXIT_ERROR
+				end
+
+				branch = worktree_branch( path: resolved_path )
+				puts_verbose "worktree_remove: path=#{resolved_path} branch=#{branch}"
+
+				# Step 1: remove the worktree (directory + git registration).
+				rm_stdout, rm_stderr, rm_success, = git_run( "worktree", "remove", "--force", resolved_path )
+				unless rm_success
+					error_text = rm_stderr.to_s.strip
+					error_text = "unable to remove worktree" if error_text.empty?
+					puts_line "ERROR: #{error_text}"
+					return EXIT_ERROR
+				end
+				puts_verbose "worktree_removed: #{resolved_path}"
+
+				# Step 2: delete the local branch.
+				if branch && !config.protected_branches.include?( branch )
+					_, del_stderr, del_success, = git_run( "branch", "-D", branch )
+					if del_success
+						puts_verbose "branch_deleted: #{branch}"
+					else
+						puts_verbose "branch_delete_skipped: #{branch} reason=#{del_stderr.to_s.strip}"
+					end
+				end
+
+				# Step 3: delete the remote branch (best-effort).
+				if branch && !config.protected_branches.include?( branch )
+					remote_branch = branch
+					git_run( "push", config.git_remote, "--delete", remote_branch )
+					puts_verbose "remote_branch_deleted: #{config.git_remote}/#{remote_branch}"
+				end
+
+				unless verbose?
+					puts_line "Worktree removed: #{File.basename( resolved_path )}"
+				end
+				EXIT_OK
+			end
+
+		private
+
+			# Resolves a worktree path: if it's a bare name, look under .claude/worktrees/.
+			def resolve_worktree_path( worktree_path: )
+				return File.expand_path( worktree_path ) if worktree_path.include?( "/" )
+
+				candidate = File.join( repo_root, ".claude", "worktrees", worktree_path )
+				return candidate if Dir.exist?( candidate )
+
+				File.expand_path( worktree_path )
+			end
+
+			# Returns true if the path is a registered git worktree.
+			def worktree_registered?( path: )
+				worktree_list.any? { |wt| wt.fetch( :path ) == path }
+			end
+
+			# Returns the branch name checked out in a worktree, or nil.
+			def worktree_branch( path: )
+				entry = worktree_list.find { |wt| wt.fetch( :path ) == path }
+				entry&.fetch( :branch, nil )
+			end
+
+			# Parses `git worktree list --porcelain` into structured entries.
+			def worktree_list
+				output = git_capture!( "worktree", "list", "--porcelain" )
+				entries = []
+				current = {}
+				output.lines.each do |line|
+					line = line.strip
+					if line.empty?
+						entries << current unless current.empty?
+						current = {}
+					elsif line.start_with?( "worktree " )
+						current[ :path ] = line.sub( "worktree ", "" )
+					elsif line.start_with?( "branch " )
+						current[ :branch ] = line.sub( "branch refs/heads/", "" )
+					elsif line == "detached"
+						current[ :branch ] = nil
+					end
+				end
+				entries << current unless current.empty?
+				entries
+			end
+		end
+
+		include Local
+	end
+end

data/lib/carson/runtime/local.rb

@@ -3,6 +3,7 @@ require_relative "local/prune"
 require_relative "local/template"
 require_relative "local/hooks"
 require_relative "local/onboard"
+require_relative "local/worktree"
 
 module Carson
 	class Runtime

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 2.30.0
+  version: 2.31.0
 platform: ruby
 authors:
 - Hailei Wang
@@ -59,6 +59,7 @@ files:
 - lib/carson/runtime/local/prune.rb
 - lib/carson/runtime/local/sync.rb
 - lib/carson/runtime/local/template.rb
+- lib/carson/runtime/local/worktree.rb
 - lib/carson/runtime/review.rb
 - lib/carson/runtime/review/data_access.rb
 - lib/carson/runtime/review/gate_support.rb