carson 3.1.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 046c14a614687e668eae6d9f3df0eadbe02fcb103a1c93f25657791a0d72962c
-  data.tar.gz: 26ebca4203a0a9b3df1e38795580188bcf6951049304ae0eb4899deda35106f8
+  metadata.gz: 91c767b37c33c1d69a377f509b5503ef342fef4ff4f3629439e998938d99b24b
+  data.tar.gz: 2b615ad6df7610917d400166a5d735c9bc3f7e51b52eeda33d48446be9916d9c
 SHA512:
-  metadata.gz: 38cb7ebf2e65293d5ea26bfb527314d86f7889949db033649fc49822b65feb7b7ea0e8fa5f35b6d959024ff4d280691432efde50dc15c37bf223665cd7d908b7
-  data.tar.gz: d05902ee1637919dd0a9781fa2de46e4370d2806df83c02c730584095f18811baea6168f3614d81900229dd5ec3c141ffb2ce6a40a8c338f233aa1a88a2a9b81
+  metadata.gz: df671d4ed658b1aa98290cfcdbc5cd47c78c702d83254bdc4e79d9ed5755320b3cd9c08f664e20633830661506fe8a0cdcb0f8c03e1314623a6074a444f7d23d
+  data.tar.gz: e05a41a7fb961deac1f63eccb77b8d03eb7d694a557baebaead88f5f38d9bab91a1b4643f71b4bf09741e51946ab2c6707a288e7a22fe2ea981ee5769e370b2f

data/RELEASE.md

@@ -5,6 +5,41 @@ 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.3.0 — Deliver Refinements
+
+### What changed
+
+- **`carson deliver --json`** — machine-readable JSON output for agent consumption. The JSON envelope includes `command`, `branch`, `pr_number`, `pr_url`, `ci`, `merged`, `exit_code`, and — on failure — `error` and `recovery` fields.
+- **Recovery-aware errors** — every deliver error path now includes a concrete `recovery` command showing the user exactly what to run next. Human output shows `Recovery: <command>`, JSON output includes a `recovery` field.
+
+### UX
+
+- JSON output uses `JSON.pretty_generate` for readability when inspected by humans.
+- Recovery commands are context-specific: push failures suggest `git pull --rebase && git push`, main-branch errors suggest `git checkout -b <branch>`, CI failures suggest `gh pr checks` with re-deliver.
+- Human output for CI pending and CI fail states now includes recovery guidance.
+
+### Migration
+
+- No breaking changes. `carson deliver` without `--json` behaves identically to 3.2.0.
+
+## 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.3.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] [--json] [--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,33 @@ module Carson
 			{ command: "status", json: json_flag }
 		end
 
+		def self.parse_deliver_command( argv:, err: )
+			options = { merge: false, json: false, title: nil, body_file: nil }
+			deliver_parser = OptionParser.new do |opts|
+				opts.banner = "Usage: carson deliver [--merge] [--json] [--title TITLE] [--body-file PATH]"
+				opts.on( "--merge", "Also merge the PR if CI passes" ) { options[ :merge ] = true }
+				opts.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = 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 ),
+				json: options.fetch( :json ),
+				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 +346,13 @@ 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 ),
+					json_output: parsed.fetch( :json, false )
+				)
 			when "review:gate"
 				runtime.review_gate!
 			when "review:sweep"

data/lib/carson/runtime/deliver.rb

@@ -0,0 +1,257 @@
+# 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.
+# `carson deliver --json` outputs structured result for agent consumption.
+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, json_output: false )
+				branch = current_branch
+				main = config.main_branch
+				remote = config.git_remote
+				result = { command: "deliver", branch: branch }
+
+				# Guard: cannot deliver from main.
+				if branch == main
+					result[ :error ] = "cannot deliver from #{main}"
+					result[ :recovery ] = "git checkout -b <branch-name>"
+					return deliver_finish( result: result, exit_code: EXIT_ERROR, json_output: json_output )
+				end
+
+				# Step 1: push the branch.
+				push_exit = push_branch!( branch: branch, remote: remote, result: result )
+				return deliver_finish( result: result, exit_code: push_exit, json_output: json_output ) unless push_exit == 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, result: result
+				)
+				if pr_number.nil?
+					return deliver_finish( result: result, exit_code: EXIT_ERROR, json_output: json_output )
+				end
+
+				result[ :pr_number ] = pr_number
+				result[ :pr_url ] = pr_url
+
+				# Without --merge, we are done.
+				unless merge
+					return deliver_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
+				end
+
+				# Step 3: check CI status.
+				ci_status = check_pr_ci( number: pr_number )
+				result[ :ci ] = ci_status.to_s
+
+				case ci_status
+				when :pass
+					# Continue to merge.
+				when :pending
+					result[ :recovery ] = "gh pr checks #{pr_number} --watch && carson deliver --merge"
+					return deliver_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
+				when :fail
+					result[ :recovery ] = "gh pr checks #{pr_number} — fix failures, push, then `carson deliver --merge`"
+					return deliver_finish( result: result, exit_code: EXIT_BLOCK, json_output: json_output )
+				else
+					result[ :recovery ] = "gh pr checks #{pr_number}"
+					return deliver_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
+				end
+
+				# Step 4: merge.
+				merge_exit = merge_pr!( number: pr_number, result: result )
+				return deliver_finish( result: result, exit_code: merge_exit, json_output: json_output ) unless merge_exit == EXIT_OK
+
+				result[ :merged ] = true
+
+				# Step 5: sync main.
+				sync_after_merge!( remote: remote, main: main )
+
+				deliver_finish( result: result, exit_code: EXIT_OK, json_output: json_output )
+			end
+
+		private
+
+			# Outputs the final result — JSON or human-readable — and returns exit code.
+			def deliver_finish( result:, exit_code:, json_output: )
+				result[ :exit_code ] = exit_code
+
+				if json_output
+					out.puts JSON.pretty_generate( result )
+				else
+					print_deliver_human( result: result )
+				end
+
+				exit_code
+			end
+
+			# Human-readable output for deliver results.
+			def print_deliver_human( result: )
+				exit_code = result.fetch( :exit_code )
+
+				if result[ :error ]
+					puts_line "ERROR: #{result[ :error ]}"
+					puts_line "  Recovery: #{result[ :recovery ]}" if result[ :recovery ]
+					return
+				end
+
+				if result[ :pr_number ]
+					puts_line "PR: ##{result[ :pr_number ]} #{result[ :pr_url ]}"
+				end
+
+				if result[ :ci ]
+					ci = result[ :ci ]
+					case ci
+					when "pass"
+						puts_line "CI: pass"
+					when "pending"
+						puts_line "CI: pending — merge when checks complete."
+						puts_line "  Recovery: #{result[ :recovery ]}" if result[ :recovery ]
+					when "fail"
+						puts_line "CI: failing — fix before merging."
+						puts_line "  Recovery: #{result[ :recovery ]}" if result[ :recovery ]
+					else
+						puts_line "CI: #{ci} — check manually."
+						puts_line "  Recovery: #{result[ :recovery ]}" if result[ :recovery ]
+					end
+				end
+
+				if result[ :merged ]
+					puts_line "Merged PR ##{result[ :pr_number ]} via #{result[ :merge_method ]}."
+				end
+			end
+
+			# Pushes the branch to the remote with tracking.
+			def push_branch!( branch:, remote:, result: )
+				_, 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?
+					result[ :error ] = error_text
+					result[ :recovery ] = "git pull #{remote} #{branch} --rebase && git push -u #{remote} #{branch}"
+					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, result: )
+				# 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, result: result )
+			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, result: )
+				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?
+					result[ :error ] = error_text
+					result[ :recovery ] = "gh pr create --title '#{pr_title}' --head #{branch}"
+					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:, result: )
+				method = config.govern_merge_method
+				result[ :merge_method ] = method
+
+				_, stderr, success, = gh_run(
+					"pr", "merge", number.to_s,
+					"--#{method}",
+					"--delete-branch"
+				)
+
+				if success
+					EXIT_OK
+				else
+					error_text = stderr.to_s.strip
+					error_text = "merge failed" if error_text.empty?
+					result[ :error ] = error_text
+					result[ :recovery ] = "gh pr merge #{number} --#{method} --delete-branch"
+					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.3.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