carson 3.2.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21eb861872b515965379fc3dc8afe24fceb228589b479e475999116aca5eca2a
-  data.tar.gz: da1ac628ac9da29969d973a5265c7ddff472370c1865e08af69f8f7bff3203e5
+  metadata.gz: 514509a6422a4c2237a48feac1bff1c10e4705afe62fb574d400b8364cf131ba
+  data.tar.gz: 1f7bbf53a01ee92d8a97d62d0a7957bb823c0aabd70e31a7e27e37de8ab3b8c6
 SHA512:
-  metadata.gz: ebafee0b573830243f4706fd5884ab9cece7ec07ecf657b936ea76d48c79af9eec30a9af2ac23ea1d7e7fbad604d49573aa67c2c53e9a500f16225684e81c67c
-  data.tar.gz: 0aea5423f60e9d33ca4f42f15b5f7bc4ecfd219960cec6d65d0c868fdc53a44831cb0eb4d12264f489b1fd7baafbf55b7226386b9fb1a7e8e4f360b06f9106f7
+  metadata.gz: a536b8a85ba6b2a737ce913485e3d58b5672b6b13af40261b181dd234bf1052ffa93a5f9b51307d9ce7e433e588b92ce294e88118b758747d4bb5cbad898c6c5
+  data.tar.gz: d476ba9ed57c7c97967c0cb2fab8b8390debfa196d657ae6d2e6c51e143248f8160bc543eb0d9b4e5c3c434ba4a25aa16b8af9aa6ec3b9cfcf5b7c974cd8fa9e

data/RELEASE.md

@@ -5,6 +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.4.0 — Audit JSON
+
+### What changed
+
+- **`carson audit --json`** — machine-readable JSON output for the audit command. The JSON envelope includes `command`, `status`, `branch`, `hooks`, `main_sync`, `pr`, `checks`, `baseline`, `problems`, and `exit_code`. Agents can parse audit results programmatically instead of regex-matching human-readable text.
+
+### UX
+
+- JSON output is only produced when `--json` is passed; default human-readable output is unchanged.
+- The `problems` array contains the same concise problem strings shown in non-verbose human output, making it easy for agents to surface actionable issues.
+- `hooks.status` is `"ok"` or `"mismatch"`, `main_sync.status` is `"ok"`, `"ahead"`, `"behind"`, or `"unknown"`.
+
+### Migration
+
+- No breaking changes. `carson audit` without `--json` behaves identically to 3.3.0.
+- The `audit!` method now accepts `json_output:` keyword argument (default `false`).
+
+## 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

data/VERSION

@@ -1 +1 @@
-3.2.0
+3.4.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|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]"
+				opts.banner = "Usage: carson [status [--json]|setup|audit [--json]|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
 
@@ -88,6 +88,8 @@ module Carson
 				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 "audit"
+				parse_audit_command( argv: argv, err: err )
 			when "status"
 				parse_status_command( argv: argv, err: err )
 			when "deliver"
@@ -242,6 +244,15 @@ module Carson
 			{ command: :invalid }
 		end
 
+		def self.parse_audit_command( argv:, err: )
+			json_flag = argv.delete( "--json" ) ? true : false
+			unless argv.empty?
+				err.puts "#{BADGE} Unexpected arguments for audit: #{argv.join( ' ' )}"
+				return { command: :invalid }
+			end
+			{ command: "audit", json: json_flag }
+		end
+
 		def self.parse_status_command( argv:, err: )
 			json_flag = argv.delete( "--json" ) ? true : false
 			unless argv.empty?
@@ -252,10 +263,11 @@ module Carson
 		end
 
 		def self.parse_deliver_command( argv:, err: )
-			options = { merge: false, title: nil, body_file: nil }
+			options = { merge: false, json: false, title: nil, body_file: nil }
 			deliver_parser = OptionParser.new do |opts|
-				opts.banner = "Usage: carson deliver [--merge] [--title TITLE] [--body-file PATH]"
+				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
@@ -268,6 +280,7 @@ module Carson
 			{
 				command: "deliver",
 				merge: options.fetch( :merge ),
+				json: options.fetch( :json ),
 				title: options[ :title ],
 				body_file: options[ :body_file ]
 			}
@@ -319,7 +332,7 @@ module Carson
 			when "setup"
 				runtime.setup!( cli_choices: parsed.fetch( :cli_choices, {} ) )
 			when "audit"
-				runtime.audit!
+				runtime.audit!( json_output: parsed.fetch( :json, false ) )
 			when "sync"
 				runtime.sync!
 			when "prune"
@@ -348,7 +361,8 @@ module Carson
 				runtime.deliver!(
 					merge: parsed.fetch( :merge, false ),
 					title: parsed.fetch( :title, nil ),
-					body_file: parsed.fetch( :body_file, nil )
+					body_file: parsed.fetch( :body_file, nil ),
+					json_output: parsed.fetch( :json, false )
 				)
 			when "review:gate"
 				runtime.review_gate!

data/lib/carson/runtime/audit.rb

@@ -1,13 +1,20 @@
+# Pre-commit audit — checks hooks, main sync, PR checks, and CI baseline.
+# Exits with EXIT_BLOCK when policy violations are found.
+# Supports --json for machine-readable structured output.
 require "cgi"
 
 module Carson
 	class Runtime
 		module Audit
-			def audit!
+			def audit!( json_output: false )
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 				unless head_exists?
-					puts_line "No commits yet — audit skipped for initial commit."
+					if json_output
+						out.puts JSON.pretty_generate( { command: "audit", status: "skipped", reason: "no commits yet", exit_code: EXIT_OK } )
+					else
+						puts_line "No commits yet — audit skipped for initial commit."
+					end
 					return EXIT_OK
 				end
 				audit_state = "ok"
@@ -22,6 +29,7 @@ module Carson
 				puts_verbose ""
 				puts_verbose "[Hooks]"
 				hooks_ok = hooks_health_report
+				hooks_status = hooks_ok ? "ok" : "mismatch"
 				unless hooks_ok
 					audit_state = "block"
 					audit_concise_problems << "Hooks: mismatch — run carson refresh."
@@ -29,23 +37,27 @@ module Carson
 				puts_verbose ""
 				puts_verbose "[Main Sync Status]"
 				ahead_count, behind_count, main_error = main_sync_counts
+				main_sync = { ahead: 0, behind: 0, status: "ok" }
 				if main_error
 					puts_verbose "main_vs_remote_main: unknown"
 					puts_verbose "WARN: unable to calculate main sync status (#{main_error})."
 					audit_state = "attention" if audit_state == "ok"
 					audit_concise_problems << "Main sync: unable to determine — check remote connectivity."
+					main_sync = { ahead: 0, behind: 0, status: "unknown", error: main_error }
 				elsif ahead_count.positive?
 					puts_verbose "main_vs_remote_main_ahead: #{ahead_count}"
 					puts_verbose "main_vs_remote_main_behind: #{behind_count}"
 					puts_verbose "ACTION: local #{config.main_branch} is ahead of #{config.git_remote}/#{config.main_branch} by #{ahead_count} commit#{plural_suffix( count: ahead_count )}; reset local drift before commit/push workflows."
 					audit_state = "block"
 					audit_concise_problems << "Main sync (#{config.git_remote}): ahead by #{ahead_count} — git fetch #{config.git_remote}, or carson setup to switch remote."
+					main_sync = { ahead: ahead_count, behind: behind_count, status: "ahead" }
 				elsif behind_count.positive?
 					puts_verbose "main_vs_remote_main_ahead: #{ahead_count}"
 					puts_verbose "main_vs_remote_main_behind: #{behind_count}"
 					puts_verbose "ACTION: local #{config.main_branch} is behind #{config.git_remote}/#{config.main_branch} by #{behind_count} commit#{plural_suffix( count: behind_count )}; run carson sync."
 					audit_state = "attention" if audit_state == "ok"
 					audit_concise_problems << "Main sync (#{config.git_remote}): behind by #{behind_count} — run carson sync."
+					main_sync = { ahead: ahead_count, behind: behind_count, status: "behind" }
 				else
 					puts_verbose "main_vs_remote_main_ahead: 0"
 					puts_verbose "main_vs_remote_main_behind: 0"
@@ -109,15 +121,40 @@ module Carson
 							audit_status: audit_state
 						)
 					)
-				puts_verbose ""
-				puts_verbose "[Audit Result]"
-				puts_verbose "status: #{audit_state}"
-				puts_verbose( audit_state == "block" ? "ACTION: local policy block must be resolved before commit/push." : "ACTION: no local hard block detected." )
-				unless verbose?
-					audit_concise_problems.each { |problem| puts_line problem }
-					puts_line "Audit: #{audit_state}"
+				exit_code = audit_state == "block" ? EXIT_BLOCK : EXIT_OK
+
+				if json_output
+					result = {
+						command: "audit",
+						status: audit_state,
+						branch: current_branch,
+						hooks: { status: hooks_status },
+						main_sync: main_sync,
+						pr: monitor_report[ :pr ],
+						checks: monitor_report.fetch( :checks ),
+						baseline: {
+							status: default_branch_baseline.fetch( :status ),
+							repository: default_branch_baseline[ :repository ],
+							failing_count: default_branch_baseline.fetch( :failing_count ),
+							pending_count: default_branch_baseline.fetch( :pending_count ),
+							advisory_failing_count: default_branch_baseline.fetch( :advisory_failing_count ),
+							advisory_pending_count: default_branch_baseline.fetch( :advisory_pending_count )
+						},
+						problems: audit_concise_problems,
+						exit_code: exit_code
+					}
+					out.puts JSON.pretty_generate( result )
+				else
+					puts_verbose ""
+					puts_verbose "[Audit Result]"
+					puts_verbose "status: #{audit_state}"
+					puts_verbose( audit_state == "block" ? "ACTION: local policy block must be resolved before commit/push." : "ACTION: no local hard block detected." )
+					unless verbose?
+						audit_concise_problems.each { |problem| puts_line problem }
+						puts_line "Audit: #{audit_state}"
+					end
 				end
-				audit_state == "block" ? EXIT_BLOCK : EXIT_OK
+				exit_code
 			end
 
 		private

data/lib/carson/runtime/deliver.rb

@@ -2,73 +2,135 @@
 # 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 )
+			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
-					puts_line "ERROR: cannot deliver from #{main}. Switch to a feature branch first."
-					return EXIT_ERROR
+					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_result = push_branch!( branch: branch, remote: remote )
-				return push_result unless push_result == EXIT_OK
+				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
+					branch: branch, title: title, body_file: body_file, result: result
 				)
-				return EXIT_ERROR if pr_number.nil?
+				if pr_number.nil?
+					return deliver_finish( result: result, exit_code: EXIT_ERROR, json_output: json_output )
+				end
 
-				puts_line "PR: ##{pr_number} #{pr_url}"
+				result[ :pr_number ] = pr_number
+				result[ :pr_url ] = pr_url
 
 				# Without --merge, we are done.
-				return EXIT_OK unless merge
+				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
-					puts_line "CI: pass"
+					# Continue to merge.
 				when :pending
-					puts_line "CI: pending — merge when checks complete."
-					return EXIT_OK
+					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
-					puts_line "CI: failing — fix before merging."
-					return EXIT_BLOCK
+					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
-					puts_line "CI: unknown — check manually."
-					return EXIT_OK
+					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_result = merge_pr!( number: pr_number )
-				return merge_result unless merge_result == EXIT_OK
+				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 )
 
-				EXIT_OK
+				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: )
+			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?
-					puts_line "ERROR: #{error_text}"
+					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}"
@@ -77,13 +139,13 @@ module Carson
 
 			# 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 )
+			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 )
+				create_pr!( branch: branch, title: title, body_file: body_file, result: result )
 			end
 
 			# Queries gh for an open PR on this branch.
@@ -104,7 +166,7 @@ module Carson
 
 			# 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 )
+			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 ]
@@ -118,7 +180,8 @@ module Carson
 				unless success
 					error_text = stderr.to_s.strip
 					error_text = "pr create failed" if error_text.empty?
-					puts_line "ERROR: #{error_text}"
+					result[ :error ] = error_text
+					result[ :recovery ] = "gh pr create --title '#{pr_title}' --head #{branch}"
 					return [ nil, nil ]
 				end
 
@@ -160,21 +223,23 @@ module Carson
 			end
 
 			# Merges the PR using the configured merge method.
-			def merge_pr!( number: )
+			def merge_pr!( number:, result: )
 				method = config.govern_merge_method
-				stdout, stderr, success, = gh_run(
+				result[ :merge_method ] = method
+
+				_, 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}"
+					result[ :error ] = error_text
+					result[ :recovery ] = "gh pr merge #{number} --#{method} --delete-branch"
 					EXIT_ERROR
 				end
 			end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 3.4.0
 platform: ruby
 authors:
 - Hailei Wang