carson 3.0.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20f9db167969ae68e42a19efcc96c40108f4f3ab3f8b460369283457c9449e4b
-  data.tar.gz: 7e94bf5adcafdbd532bd6e789304e04c2a555b7adcbce441363e681a27493c25
+  metadata.gz: 21eb861872b515965379fc3dc8afe24fceb228589b479e475999116aca5eca2a
+  data.tar.gz: da1ac628ac9da29969d973a5265c7ddff472370c1865e08af69f8f7bff3203e5
 SHA512:
-  metadata.gz: 7bdc870e0ae003717b5e624d61386a41a89b5dcd20ec0e0c6fa5106b26791b53106bc43f763ca6199e79ca2bac8e76efcbff21d1ebbb126996550b009848f79f
-  data.tar.gz: 19dce95ec2fd4fc5a89de09f8e26b814e6b077285159d425639e68e635eda195d52171c7e388ce27efd27b685f7486e2fc6f8fcf0e7005407cdf672bb9c9f7a2
+  metadata.gz: ebafee0b573830243f4706fd5884ab9cece7ec07ecf657b936ea76d48c79af9eec30a9af2ac23ea1d7e7fbad604d49573aa67c2c53e9a500f16225684e81c67c
+  data.tar.gz: 0aea5423f60e9d33ca4f42f15b5f7bc4ecfd219960cec6d65d0c868fdc53a44831cb0eb4d12264f489b1fd7baafbf55b7226386b9fb1a7e8e4f360b06f9106f7

data/RELEASE.md

@@ -5,6 +5,42 @@ 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.2.0 — Deliver
+
+### What changed
+
+- **`carson deliver`** — pushes the current branch to the remote, creates a PR if none exists, and reports the PR URL. Collapses the manual push/create-PR/report cycle into one command.
+- **`carson deliver --merge`** — does everything above, plus checks CI status and merges the PR if all checks pass. Reports pending or failing CI with actionable guidance. Uses the configured merge method (squash, rebase, or merge). Syncs main after merge.
+- **`carson deliver --title "..." --body-file <path>`** — optional PR title and body file for custom PR metadata. Title defaults to a humanised branch name.
+
+### UX
+
+- `carson deliver` guards against delivering from main — exits with an error and recovery guidance.
+- `carson deliver --merge` reports CI status clearly: pass, pending, or failing.
+- Default PR title is generated from the branch name (e.g. `feature/add-search` becomes "Feature: add search").
+
+### Migration
+
+- No breaking changes. All existing commands continue to work unchanged.
+
+## 3.1.0 — Worktree Lifecycle
+
+### What changed
+
+- **`carson worktree create <name>`** — creates a worktree under `.claude/worktrees/<name>` with a new branch based on main. One command, one result: path and branch name reported.
+- **`carson worktree done <name>`** — marks a worktree as completed without deleting it. Verifies all changes are committed and pushed. Blocks with actionable guidance if uncommitted changes or unpushed commits exist. The worktree directory persists for batch cleanup later.
+- **Deferred deletion model.** The full worktree lifecycle is now: create → work → done → batch cleanup. No worktree is deleted during an active session. Cleanup happens later via `carson worktree remove` or `carson housekeep`.
+
+### UX
+
+- `carson worktree create` reports path and branch — ready to `cd` into immediately.
+- `carson worktree done` gives recovery commands when changes are uncommitted or unpushed.
+- Error messages across worktree subcommands now show `create|done|remove` in usage hints.
+
+### Migration
+
+- No breaking changes. `carson worktree remove` continues to work as before.
+
 ## 3.0.0 — Agent-Oriented Carson
 
 ### Theme

data/VERSION

@@ -1 +1 @@
-3.0.0
+3.2.0

data/lib/carson/cli.rb

@@ -53,7 +53,7 @@ module Carson
 
 		def self.build_parser
 			OptionParser.new do |opts|
-				opts.banner = "Usage: carson [status [--json]|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]"
+				opts.banner = "Usage: carson [status [--json]|setup|audit|sync|deliver [--merge] [--title T] [--body-file F]|prune [--all]|worktree create|done|remove <name>|onboard|refresh [--all]|offboard|template check|apply|review gate|sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
 			end
 		end
 
@@ -90,6 +90,8 @@ module Carson
 				parse_named_subcommand( command: command, usage: "gate|sweep", argv: argv, parser: parser, err: err )
 			when "status"
 				parse_status_command( argv: argv, err: err )
+			when "deliver"
+				parse_deliver_command( argv: argv, err: err )
 			when "govern"
 				parse_govern_subcommand( argv: argv, err: err )
 			else
@@ -170,12 +172,22 @@ module Carson
 		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 "#{BADGE} Missing subcommand for worktree. Use: carson worktree create|done|remove <name>"
 				err.puts parser
 				return { command: :invalid }
 			end
 
 			case action
+			when "create"
+				name = argv.shift
+				if name.to_s.strip.empty?
+					err.puts "#{BADGE} Missing name for worktree create. Use: carson worktree create <name>"
+					return { command: :invalid }
+				end
+				{ command: "worktree:create", worktree_name: name }
+			when "done"
+				name = argv.shift
+				{ command: "worktree:done", worktree_name: name }
 			when "remove"
 				force = argv.delete( "--force" ) ? true : false
 				worktree_path = argv.shift
@@ -185,7 +197,7 @@ module Carson
 				end
 				{ command: "worktree:remove", worktree_path: worktree_path, force: force }
 			else
-				err.puts "#{BADGE} Unknown worktree subcommand: #{action}. Use: carson worktree remove <name-or-path>"
+				err.puts "#{BADGE} Unknown worktree subcommand: #{action}. Use: carson worktree create|done|remove <name>"
 				{ command: :invalid }
 			end
 		end
@@ -239,6 +251,31 @@ module Carson
 			{ command: "status", json: json_flag }
 		end
 
+		def self.parse_deliver_command( argv:, err: )
+			options = { merge: false, title: nil, body_file: nil }
+			deliver_parser = OptionParser.new do |opts|
+				opts.banner = "Usage: carson deliver [--merge] [--title TITLE] [--body-file PATH]"
+				opts.on( "--merge", "Also merge the PR if CI passes" ) { options[ :merge ] = true }
+				opts.on( "--title TITLE", "PR title (defaults to branch name)" ) { |v| options[ :title ] = v }
+				opts.on( "--body-file PATH", "File containing PR body text" ) { |v| options[ :body_file ] = v }
+			end
+			deliver_parser.parse!( argv )
+			unless argv.empty?
+				err.puts "#{BADGE} Unexpected arguments for deliver: #{argv.join( ' ' )}"
+				err.puts deliver_parser
+				return { command: :invalid }
+			end
+			{
+				command: "deliver",
+				merge: options.fetch( :merge ),
+				title: options[ :title ],
+				body_file: options[ :body_file ]
+			}
+		rescue OptionParser::ParseError => e
+			err.puts "#{BADGE} #{e.message}"
+			{ command: :invalid }
+		end
+
 		def self.parse_govern_subcommand( argv:, err: )
 			options = {
 				dry_run: false,
@@ -289,6 +326,10 @@ module Carson
 				runtime.prune!
 			when "prune:all"
 				runtime.prune_all!
+			when "worktree:create"
+				runtime.worktree_create!( name: parsed.fetch( :worktree_name ) )
+			when "worktree:done"
+				runtime.worktree_done!( name: parsed.fetch( :worktree_name, nil ) )
 			when "worktree:remove"
 				runtime.worktree_remove!( worktree_path: parsed.fetch( :worktree_path ), force: parsed.fetch( :force, false ) )
 			when "onboard"
@@ -303,6 +344,12 @@ module Carson
 				runtime.template_check!
 			when "template:apply"
 				runtime.template_apply!( push_prep: parsed.fetch( :push_prep, false ) )
+			when "deliver"
+				runtime.deliver!(
+					merge: parsed.fetch( :merge, false ),
+					title: parsed.fetch( :title, nil ),
+					body_file: parsed.fetch( :body_file, nil )
+				)
 			when "review:gate"
 				runtime.review_gate!
 			when "review:sweep"

data/lib/carson/runtime/deliver.rb

@@ -0,0 +1,192 @@
+# PR delivery lifecycle — push, create PR, and optionally merge.
+# Collapses the 8-step manual PR flow into one or two commands.
+# `carson deliver` pushes and creates the PR.
+# `carson deliver --merge` also merges if CI is green.
+module Carson
+	class Runtime
+		module Deliver
+			# Entry point for `carson deliver`.
+			# Pushes current branch, creates a PR if needed, reports the PR URL.
+			# With merge: true, also merges if CI passes and cleans up.
+			def deliver!( merge: false, title: nil, body_file: nil )
+				branch = current_branch
+				main = config.main_branch
+				remote = config.git_remote
+
+				# Guard: cannot deliver from main.
+				if branch == main
+					puts_line "ERROR: cannot deliver from #{main}. Switch to a feature branch first."
+					return EXIT_ERROR
+				end
+
+				# Step 1: push the branch.
+				push_result = push_branch!( branch: branch, remote: remote )
+				return push_result unless push_result == EXIT_OK
+
+				# Step 2: find or create the PR.
+				pr_number, pr_url = find_or_create_pr!(
+					branch: branch, title: title, body_file: body_file
+				)
+				return EXIT_ERROR if pr_number.nil?
+
+				puts_line "PR: ##{pr_number} #{pr_url}"
+
+				# Without --merge, we are done.
+				return EXIT_OK unless merge
+
+				# Step 3: check CI status.
+				ci_status = check_pr_ci( number: pr_number )
+				case ci_status
+				when :pass
+					puts_line "CI: pass"
+				when :pending
+					puts_line "CI: pending — merge when checks complete."
+					return EXIT_OK
+				when :fail
+					puts_line "CI: failing — fix before merging."
+					return EXIT_BLOCK
+				else
+					puts_line "CI: unknown — check manually."
+					return EXIT_OK
+				end
+
+				# Step 4: merge.
+				merge_result = merge_pr!( number: pr_number )
+				return merge_result unless merge_result == EXIT_OK
+
+				# Step 5: sync main.
+				sync_after_merge!( remote: remote, main: main )
+
+				EXIT_OK
+			end
+
+		private
+
+			# Pushes the branch to the remote with tracking.
+			def push_branch!( branch:, remote: )
+				_, push_stderr, push_success, = git_run( "push", "-u", remote, branch )
+				unless push_success
+					error_text = push_stderr.to_s.strip
+					error_text = "push failed" if error_text.empty?
+					puts_line "ERROR: #{error_text}"
+					return EXIT_ERROR
+				end
+				puts_verbose "pushed #{branch} to #{remote}"
+				EXIT_OK
+			end
+
+			# Finds an existing PR for the branch, or creates a new one.
+			# Returns [number, url] or [nil, nil] on failure.
+			def find_or_create_pr!( branch:, title: nil, body_file: nil )
+				# Check for existing PR.
+				existing = find_existing_pr( branch: branch )
+				return existing if existing.first
+
+				# Create a new PR.
+				create_pr!( branch: branch, title: title, body_file: body_file )
+			end
+
+			# Queries gh for an open PR on this branch.
+			# Returns [number, url] or [nil, nil].
+			def find_existing_pr( branch: )
+				stdout, _, success, = gh_run(
+					"pr", "view", branch,
+					"--json", "number,url"
+				)
+				if success
+					data = JSON.parse( stdout ) rescue nil
+					if data && data[ "number" ]
+						return [ data[ "number" ], data[ "url" ].to_s ]
+					end
+				end
+				[ nil, nil ]
+			end
+
+			# Creates a PR via gh. Title defaults to branch name humanised.
+			# Returns [number, url] or [nil, nil] on failure.
+			def create_pr!( branch:, title: nil, body_file: nil )
+				pr_title = title || default_pr_title( branch: branch )
+
+				args = [ "pr", "create", "--title", pr_title, "--head", branch ]
+				if body_file && File.exist?( body_file )
+					args.push( "--body-file", body_file )
+				else
+					args.push( "--body", "" )
+				end
+
+				stdout, stderr, success, = gh_run( *args )
+				unless success
+					error_text = stderr.to_s.strip
+					error_text = "pr create failed" if error_text.empty?
+					puts_line "ERROR: #{error_text}"
+					return [ nil, nil ]
+				end
+
+				# gh pr create prints the URL on success. Parse number from it.
+				pr_url = stdout.to_s.strip
+				pr_number = pr_url.split( "/" ).last.to_i
+				if pr_number > 0
+					[ pr_number, pr_url ]
+				else
+					# Fallback: query the just-created PR.
+					find_existing_pr( branch: branch )
+				end
+			end
+
+			# Generates a default PR title from the branch name.
+			def default_pr_title( branch: )
+				branch.tr( "-", " " ).gsub( "/", ": " ).sub( /\A\w/ ) { |c| c.upcase }
+			end
+
+			# Checks CI status on a PR. Returns :pass, :fail, :pending, or :none.
+			def check_pr_ci( number: )
+				stdout, _, success, = gh_run(
+					"pr", "checks", number.to_s,
+					"--json", "name,state,conclusion"
+				)
+				return :none unless success
+
+				checks = JSON.parse( stdout ) rescue []
+				return :none if checks.empty?
+
+				conclusions = checks.map { |c| c[ "conclusion" ].to_s.upcase }
+				states = checks.map { |c| c[ "state" ].to_s.upcase }
+
+				return :fail if conclusions.any? { |c| c == "FAILURE" || c == "CANCELLED" || c == "TIMED_OUT" }
+				return :pending if states.any? { |s| s == "PENDING" || s == "QUEUED" || s == "IN_PROGRESS" } ||
+					conclusions.any? { |c| c == "" || c == "PENDING" }
+
+				:pass
+			end
+
+			# Merges the PR using the configured merge method.
+			def merge_pr!( number: )
+				method = config.govern_merge_method
+				stdout, stderr, success, = gh_run(
+					"pr", "merge", number.to_s,
+					"--#{method}",
+					"--delete-branch"
+				)
+
+				if success
+					puts_line "Merged PR ##{number} via #{method}."
+					EXIT_OK
+				else
+					error_text = stderr.to_s.strip
+					error_text = "merge failed" if error_text.empty?
+					puts_line "ERROR: #{error_text}"
+					EXIT_ERROR
+				end
+			end
+
+			# Syncs main after a successful merge.
+			def sync_after_merge!( remote:, main: )
+				git_run( "checkout", main )
+				git_run( "pull", remote, main )
+				puts_verbose "synced #{main} from #{remote}"
+			end
+		end
+
+		include Deliver
+	end
+end

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

@@ -2,7 +2,83 @@ module Carson
 	class Runtime
 		module Local
 			# Safe worktree lifecycle management for coding agents.
-			# Enforces the teardown order: exit worktree → git worktree remove → branch cleanup.
+			# Three operations: create, done (mark completed), remove (batch cleanup).
+			# The deferred deletion model: worktrees persist after use, cleaned up later.
+
+			# Creates a new worktree under .claude/worktrees/<name> with a fresh branch.
+			def worktree_create!( name: )
+				worktrees_dir = File.join( repo_root, ".claude", "worktrees" )
+				wt_path = File.join( worktrees_dir, name )
+
+				if Dir.exist?( wt_path )
+					puts_line "ERROR: worktree already exists: #{name}"
+					puts_line "  Path: #{wt_path}"
+					return EXIT_ERROR
+				end
+
+				# Determine the base branch (main branch from config).
+				base = config.main_branch
+
+				# Create the worktree with a new branch based on the main branch.
+				FileUtils.mkdir_p( worktrees_dir )
+				_, wt_stderr, wt_success, = git_run( "worktree", "add", wt_path, "-b", name, base )
+				unless wt_success
+					error_text = wt_stderr.to_s.strip
+					error_text = "unable to create worktree" if error_text.empty?
+					puts_line "ERROR: #{error_text}"
+					return EXIT_ERROR
+				end
+
+				puts_line "Worktree created: #{name}"
+				puts_line "  Path: #{wt_path}"
+				puts_line "  Branch: #{name}"
+				EXIT_OK
+			end
+
+			# Marks a worktree as completed without deleting it.
+			# Verifies all changes are committed. Deferred deletion — cleanup happens later.
+			def worktree_done!( name: nil )
+				if name.to_s.strip.empty?
+					# Try to detect current worktree from CWD.
+					puts_line "ERROR: missing worktree name. Use: carson worktree done <name>"
+					return EXIT_ERROR
+				end
+
+				resolved_path = resolve_worktree_path( worktree_path: name )
+
+				unless worktree_registered?( path: resolved_path )
+					puts_line "ERROR: #{name} is not a registered worktree."
+					return EXIT_ERROR
+				end
+
+				# Check for uncommitted changes in the worktree.
+				wt_status, _, status_success, = Open3.capture3( "git", "status", "--porcelain", chdir: resolved_path )
+				if status_success && !wt_status.strip.empty?
+					puts_line "Worktree has uncommitted changes: #{name}"
+					puts_line "  Commit your changes first, then run `carson worktree done #{name}` again."
+					return EXIT_BLOCK
+				end
+
+				# Check for unpushed commits.
+				branch = worktree_branch( path: resolved_path )
+				if branch
+					remote = config.git_remote
+					remote_ref = "#{remote}/#{branch}"
+					ahead, _, ahead_ok, = Open3.capture3( "git", "rev-list", "--count", "#{remote_ref}..#{branch}", chdir: resolved_path )
+					if ahead_ok && ahead.strip.to_i > 0
+						puts_line "Worktree has unpushed commits: #{name}"
+						puts_line "  Push with `git -C #{resolved_path} push #{remote} #{branch}` first."
+						return EXIT_BLOCK
+					end
+				end
+
+				puts_line "Worktree done: #{name}"
+				puts_line "  Branch: #{branch || '(detached)'}"
+				puts_line "  Cleanup later with `carson worktree remove #{name}` or `carson housekeep`."
+				EXIT_OK
+			end
+
+			# Removes a worktree: directory, git registration, and branch.
 			# Never forces removal — if the worktree has uncommitted changes, refuses unless
 			# the user explicitly passes force: true via CLI --force flag.
 			def worktree_remove!( worktree_path:, force: false )

data/lib/carson/runtime.rb

@@ -221,3 +221,4 @@ require_relative "runtime/review"
 require_relative "runtime/govern"
 require_relative "runtime/setup"
 require_relative "runtime/status"
+require_relative "runtime/deliver"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.2.0
 platform: ruby
 authors:
 - Hailei Wang
@@ -52,6 +52,7 @@ files:
 - lib/carson/config.rb
 - lib/carson/runtime.rb
 - lib/carson/runtime/audit.rb
+- lib/carson/runtime/deliver.rb
 - lib/carson/runtime/govern.rb
 - lib/carson/runtime/local.rb
 - lib/carson/runtime/local/hooks.rb