carson 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 046c14a614687e668eae6d9f3df0eadbe02fcb103a1c93f25657791a0d72962c
-  data.tar.gz: 26ebca4203a0a9b3df1e38795580188bcf6951049304ae0eb4899deda35106f8
+  metadata.gz: 21eb861872b515965379fc3dc8afe24fceb228589b479e475999116aca5eca2a
+  data.tar.gz: da1ac628ac9da29969d973a5265c7ddff472370c1865e08af69f8f7bff3203e5
 SHA512:
-  metadata.gz: 38cb7ebf2e65293d5ea26bfb527314d86f7889949db033649fc49822b65feb7b7ea0e8fa5f35b6d959024ff4d280691432efde50dc15c37bf223665cd7d908b7
-  data.tar.gz: d05902ee1637919dd0a9781fa2de46e4370d2806df83c02c730584095f18811baea6168f3614d81900229dd5ec3c141ffb2ce6a40a8c338f233aa1a88a2a9b81
+  metadata.gz: ebafee0b573830243f4706fd5884ab9cece7ec07ecf657b936ea76d48c79af9eec30a9af2ac23ea1d7e7fbad604d49573aa67c2c53e9a500f16225684e81c67c
+  data.tar.gz: 0aea5423f60e9d33ca4f42f15b5f7bc4ecfd219960cec6d65d0c868fdc53a44831cb0eb4d12264f489b1fd7baafbf55b7226386b9fb1a7e8e4f360b06f9106f7

data/RELEASE.md

@@ -5,6 +5,24 @@ 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

data/VERSION

@@ -1 +1 @@
-3.1.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|audit|sync|prune [--all]|worktree create|done|remove <name>|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|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
@@ -249,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,
@@ -317,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.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.1.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