carson 3.3.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91c767b37c33c1d69a377f509b5503ef342fef4ff4f3629439e998938d99b24b
-  data.tar.gz: 2b615ad6df7610917d400166a5d735c9bc3f7e51b52eeda33d48446be9916d9c
+  metadata.gz: e8fc2b54698568aaec7d7f4ec39ecd32f56f44a395555a34099b24ec52a1d608
+  data.tar.gz: e3b0a5a14c733d6b2e9f5c08475d89a53f0a3d1faf8a2fb85ed72bcb76f662ef
 SHA512:
-  metadata.gz: df671d4ed658b1aa98290cfcdbc5cd47c78c702d83254bdc4e79d9ed5755320b3cd9c08f664e20633830661506fe8a0cdcb0f8c03e1314623a6074a444f7d23d
-  data.tar.gz: e05a41a7fb961deac1f63eccb77b8d03eb7d694a557baebaead88f5f38d9bab91a1b4643f71b4bf09741e51946ab2c6707a288e7a22fe2ea981ee5769e370b2f
+  metadata.gz: 9d3733f98a23dffdc69c1ebde71e94595c22e662f5ead86b97988fa3f5cf0e8daf56806deb82ceb1d034e0913640d9a8b7cafc26992f94e43dd96a3e304d6812
+  data.tar.gz: eb44eca84a943a461668b478e2bed295b3a73ee7e916cc5d85a837c52f5be09326b369e07a99812d4ffdc883914511d18c7f0489e151f3d4d66afe8ddaf97402

data/RELEASE.md

@@ -5,6 +5,39 @@ 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
+
+- **`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

data/VERSION

@@ -1 +1 @@
-3.3.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|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
 
@@ -88,6 +88,10 @@ 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 "sync"
+				parse_sync_command( argv: argv, err: err )
 			when "status"
 				parse_status_command( argv: argv, err: err )
 			when "deliver"
@@ -242,6 +246,24 @@ 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_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?
@@ -321,9 +343,9 @@ 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!
+				runtime.sync!( json_output: parsed.fetch( :json, false ) )
 			when "prune"
 				runtime.prune!
 			when "prune:all"

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/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.3.0
+  version: 3.5.0
 platform: ruby
 authors:
 - Hailei Wang