carson 3.4.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 514509a6422a4c2237a48feac1bff1c10e4705afe62fb574d400b8364cf131ba
-  data.tar.gz: 1f7bbf53a01ee92d8a97d62d0a7957bb823c0aabd70e31a7e27e37de8ab3b8c6
+  metadata.gz: e8fc2b54698568aaec7d7f4ec39ecd32f56f44a395555a34099b24ec52a1d608
+  data.tar.gz: e3b0a5a14c733d6b2e9f5c08475d89a53f0a3d1faf8a2fb85ed72bcb76f662ef
 SHA512:
-  metadata.gz: a536b8a85ba6b2a737ce913485e3d58b5672b6b13af40261b181dd234bf1052ffa93a5f9b51307d9ce7e433e588b92ce294e88118b758747d4bb5cbad898c6c5
-  data.tar.gz: d476ba9ed57c7c97967c0cb2fab8b8390debfa196d657ae6d2e6c51e143248f8160bc543eb0d9b4e5c3c434ba4a25aa16b8af9aa6ec3b9cfcf5b7c974cd8fa9e
+  metadata.gz: 9d3733f98a23dffdc69c1ebde71e94595c22e662f5ead86b97988fa3f5cf0e8daf56806deb82ceb1d034e0913640d9a8b7cafc26992f94e43dd96a3e304d6812
+  data.tar.gz: eb44eca84a943a461668b478e2bed295b3a73ee7e916cc5d85a837c52f5be09326b369e07a99812d4ffdc883914511d18c7f0489e151f3d4d66afe8ddaf97402

data/RELEASE.md

@@ -5,6 +5,22 @@ 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.5.0 — Sync JSON + Recovery
+
+### What changed
+
+- **`carson sync --json`** — machine-readable JSON output for the sync command. The JSON envelope includes `command`, `status`, `ahead`, `behind`, `main_branch`, `remote`, `exit_code`, and on failure: `error` and `recovery`.
+- **Recovery-aware sync errors** — dirty working tree now includes a recovery command in both human (`Recovery: ...`) and JSON output.
+
+### UX
+
+- JSON output suppresses git command output (fetch, pull) to keep the JSON envelope clean.
+- Human output remains unchanged when `--json` is not passed.
+
+### Migration
+
+- No breaking changes. `carson sync` without `--json` behaves identically to 3.4.0.
+
 ## 3.4.0 — Audit JSON
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.4.0
+3.5.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 [--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]"
+				opts.banner = "Usage: carson [status [--json]|setup|audit [--json]|sync [--json]|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 "audit"
 				parse_audit_command( argv: argv, err: err )
+			when "sync"
+				parse_sync_command( argv: argv, err: err )
 			when "status"
 				parse_status_command( argv: argv, err: err )
 			when "deliver"
@@ -253,6 +255,15 @@ module Carson
 			{ command: "audit", json: json_flag }
 		end
 
+		def self.parse_sync_command( argv:, err: )
+			json_flag = argv.delete( "--json" ) ? true : false
+			unless argv.empty?
+				err.puts "#{BADGE} Unexpected arguments for sync: #{argv.join( ' ' )}"
+				return { command: :invalid }
+			end
+			{ command: "sync", json: json_flag }
+		end
+
 		def self.parse_status_command( argv:, err: )
 			json_flag = argv.delete( "--json" ) ? true : false
 			unless argv.empty?
@@ -334,7 +345,7 @@ module Carson
 			when "audit"
 				runtime.audit!( json_output: parsed.fetch( :json, false ) )
 			when "sync"
-				runtime.sync!
+				runtime.sync!( json_output: parsed.fetch( :json, false ) )
 			when "prune"
 				runtime.prune!
 			when "prune:all"

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

@@ -1,39 +1,83 @@
+# Syncs local main branch with remote main.
+# Supports --json for machine-readable structured output.
 module Carson
 	class Runtime
 		module Local
-			def sync!
+			def sync!( json_output: false )
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 
 				unless working_tree_clean?
-					puts_line "BLOCK: working tree is dirty; commit/stash first, then run carson sync."
-					return EXIT_BLOCK
+					return sync_finish(
+						result: { command: "sync", status: "block", error: "working tree is dirty", recovery: "git add -A && git commit, then carson sync" },
+						exit_code: EXIT_BLOCK, json_output: json_output
+					)
 				end
 				start_branch = current_branch
 				switched = false
-				git_system!( "fetch", config.git_remote, "--prune" )
+				sync_git!( "fetch", config.git_remote, "--prune", json_output: json_output )
 				if start_branch != config.main_branch
-					git_system!( "switch", config.main_branch )
+					sync_git!( "switch", config.main_branch, json_output: json_output )
 					switched = true
 				end
-				git_system!( "pull", "--ff-only", config.git_remote, config.main_branch )
+				sync_git!( "pull", "--ff-only", config.git_remote, config.main_branch, json_output: json_output )
 				ahead_count, behind_count, error_text = main_sync_counts
 				if error_text
-					puts_line "BLOCK: unable to verify main sync state (#{error_text})."
-					return EXIT_BLOCK
+					return sync_finish(
+						result: { command: "sync", status: "block", error: "unable to verify main sync state (#{error_text})" },
+						exit_code: EXIT_BLOCK, json_output: json_output
+					)
 				end
 				if ahead_count.zero? && behind_count.zero?
-					puts_line "OK: local #{config.main_branch} is now in sync with #{config.git_remote}/#{config.main_branch}."
-					return EXIT_OK
+					return sync_finish(
+						result: { command: "sync", status: "ok", ahead: 0, behind: 0, main_branch: config.main_branch, remote: config.git_remote },
+						exit_code: EXIT_OK, json_output: json_output
+					)
 				end
-				puts_line "BLOCK: local #{config.main_branch} still diverges (ahead=#{ahead_count}, behind=#{behind_count})."
-				EXIT_BLOCK
+				sync_finish(
+					result: { command: "sync", status: "block", ahead: ahead_count, behind: behind_count, main_branch: config.main_branch, remote: config.git_remote, error: "local #{config.main_branch} still diverges" },
+					exit_code: EXIT_BLOCK, json_output: json_output
+				)
 			ensure
 				git_system!( "switch", start_branch ) if switched && branch_exists?( branch_name: start_branch )
 			end
 
 		private
 
+			# Runs a git command, suppressing stdout/stderr in JSON mode to keep output clean.
+			def sync_git!( *args, json_output: false )
+				if json_output
+					_, stderr_text, success, = git_run( *args )
+					raise "git #{args.join( ' ' )} failed: #{stderr_text.to_s.strip}" unless success
+				else
+					git_system!( *args )
+				end
+			end
+
+			# Unified output for sync results — JSON or human-readable.
+			def sync_finish( result:, exit_code:, json_output: )
+				result[ :exit_code ] = exit_code
+
+				if json_output
+					out.puts JSON.pretty_generate( result )
+				else
+					print_sync_human( result: result )
+				end
+
+				exit_code
+			end
+
+			# Human-readable output for sync results.
+			def print_sync_human( result: )
+				if result[ :error ]
+					puts_line "BLOCK: #{result[ :error ]}."
+					puts_line "  Recovery: #{result[ :recovery ]}" if result[ :recovery ]
+					return
+				end
+
+				puts_line "OK: local #{result[ :main_branch ]} is now in sync with #{result[ :remote ]}/#{result[ :main_branch ]}."
+			end
+
 			# Returns ahead/behind counts for local main versus configured remote main.
 			def main_sync_counts
 				target = "#{config.main_branch}...#{config.git_remote}/#{config.main_branch}"

metadata

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