carson 3.17.0 → 3.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5474bed385b09305a9a467655447faa7dc5b908486cf69d3124cca99cd7cc2f2
-  data.tar.gz: 4efa36d52f6642967abc25b35ae5a9bcfcfb97072064478873c99693c90a54cd
+  metadata.gz: 5c18ffa310a6fdb0b0e1581eba83b9ab7dcb8c88a546c391f83200871e17d7f6
+  data.tar.gz: 77c0d6e97438a1f9512e3dbef51a22981caf1b6b0126ffe8ab3bdbf3c7ec3bbb
 SHA512:
-  metadata.gz: 51a319323b1c96b15085cbdb5380a7b2b27c088cf4bade168e5b64947734f9aec2ddea05e5a359bee75b93eb253ba275280c4cb9959165457b559b022d61bcd8
-  data.tar.gz: 8665f26fb62718e6b5b6df1addeedee0caa9130c956e7f40f8aba2e79048438dacf4e49a4cd460cbc1c4a90f7ef85a7916531ec4edae3fc345f3864ff1c7c3f9
+  metadata.gz: 5ac7c43bd96d94c1013c5ade599bd906dbda305b3c0216c184093b62292de30c93d7b8f7bd0e090ffe13fd272e97345d6adb30b321df3188f48b2e5ef50913d6
+  data.tar.gz: 00da3a36874c8dca3ade2736e2e0d5852018cbe13c7a68cb0af746a59cbcbda51b4f992ebe862a88cf855824d7388c2a3b09b04d5950da385f3bdcf6ff09af12

data/API.md

@@ -29,6 +29,21 @@ carson <command> [subcommand] [arguments]
 | `carson prune` | Remove stale local branches whose upstream refs no longer exist. |
 | `carson template check` | Detect drift between managed templates and host `.github/*` files. |
 | `carson template apply` | Write canonical managed template content into host `.github/*` files. |
+| `carson status` | Show repository state (branch, worktrees, PRs, governance). |
+
+### Batch commands (Layer 2)
+
+All batch commands operate across every governed repository registered in `govern.repos`.
+
+| Command | Purpose |
+|---|---|
+| `carson refresh --all` | Re-apply hooks, templates, and audit across all governed repos. Skips repos with active worktrees or uncommitted changes. |
+| `carson audit --all` | Run governance audit across all governed repos. Reports pass/block/fail per repo. |
+| `carson sync --all` | Sync main branch across all governed repos. |
+| `carson prune --all` | Remove stale branches across all governed repos. |
+| `carson status --all [--json]` | Portfolio-wide status overview with branch, worktrees, and governance state per repo. |
+| `carson template check --all` | Read-only template drift detection across all governed repos. |
+| `carson housekeep --all` | Sync, reap dead worktrees, and prune across all governed repos. |
 
 ### Govern commands
 
@@ -132,7 +147,7 @@ Environment overrides:
 ```json
 {
   "template": {
-    "canonical": "~/AI/LINT"
+    "canonical": "~/AI/CODING/LINT"
   }
 }
 ```

data/MANUAL.md

@@ -89,7 +89,7 @@ Set `template.canonical` in `~/.carson/config.json`:
 ```json
 {
   "template": {
-    "canonical": "~/AI/LINT"
+    "canonical": "~/AI/CODING/LINT"
   }
 }
 ```
@@ -97,7 +97,7 @@ Set `template.canonical` in `~/.carson/config.json`:
 That directory mirrors the `.github/` structure:
 
 ```
-~/AI/LINT/
+~/AI/CODING/LINT/
 ├── workflows/
 │   └── lint.yml          → deployed to .github/workflows/lint.yml
 ├── .mega-linter.yml      → deployed to .github/.mega-linter.yml
@@ -207,8 +207,24 @@ carson review gate
 ```bash
 carson repos           # list all governed repositories
 carson repos --json    # machine-readable output
+carson status --all    # branch, worktrees, governance per repo
 ```
 
+**Portfolio maintenance (Layer 2):**
+
+All `--all` commands run across every governed repository registered via `carson onboard`.
+
+```bash
+carson refresh --all           # re-apply hooks, templates, audit across all repos
+carson sync --all              # fast-forward main across all repos
+carson audit --all             # governance audit across all repos
+carson prune --all             # remove stale branches across all repos
+carson template check --all    # detect template drift across all repos
+carson housekeep --all         # full maintenance cycle across all repos
+```
+
+`refresh --all` checks each repo for safety before operating: repos with active worktrees or uncommitted changes are skipped with clear reasons. Other batch commands attempt each repo and report failures without stopping.
+
 **Periodic maintenance:**
 
 ```bash

data/RELEASE.md

@@ -5,6 +5,25 @@ 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.18.0
+
+### What changed
+
+- **Layer 2 batch operations** — every command that operates on a single repo now has an `--all` variant that runs across the entire governed portfolio:
+  - `carson refresh --all` — refresh hooks, templates, and audit across all repos. Checks each repo for safety (active worktrees, uncommitted changes) and skips unsafe repos.
+  - `carson prune --all` — prune stale branches across all repos.
+  - `carson audit --all` — run governance audit across all repos. Reports pass/block/fail per repo.
+  - `carson sync --all` — sync main branch across all repos.
+  - `carson status --all` — portfolio-wide status overview with branch, worktrees, and governance state per repo. Supports `--json`.
+  - `carson template check --all` — read-only template drift detection across all repos.
+- **Portfolio safety checks** — before batch `refresh`, Carson checks each repo for active worktrees and uncommitted changes. Unsafe repos are skipped with reasons, not failed.
+- **Shared `portfolio_repo_safety` helper** — centralised safety check in `Runtime` for all batch operations. Non-git directories pass through (the command reports the real error).
+- **CLI `--all` flag registration** — `audit`, `sync`, and `status` parsers now correctly register the `--all` flag with OptionParser (previously the flag was checked but never registered).
+
+### UX improvement
+
+- A user or agent managing multiple repositories can now run a single command to maintain the entire portfolio. `carson status --all` gives a quick overview; `carson refresh --all` keeps everything in sync; `carson housekeep --all` runs the full maintenance cycle. Unsafe repos are clearly reported with skip reasons instead of cryptic failures.
+
 ## 3.17.0
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.17.0
+3.18.0

data/lib/carson/cli.rb

@@ -12,7 +12,7 @@ module Carson
 				return Runtime::EXIT_OK
 			end
 
-			if %w[repos refresh:all prune:all housekeep:all housekeep:target].include?( command )
+			if %w[repos refresh:all prune:all housekeep:all housekeep:target template:check:all audit:all sync:all status:all].include?( command )
 				verbose = parsed.fetch( :verbose, false )
 				runtime = Runtime.new( repo_root: repo_root, tool_root: tool_root, out: out, err: err, verbose: verbose )
 				return dispatch( parsed: parsed, runtime: runtime )
@@ -409,6 +409,7 @@ module Carson
 			end
 
 			action = argv.shift
+			return { command: "template:check:all" } if action == "check" && argv.include?( "--all" )
 			return { command: "template:#{action}" } unless action == "apply"
 
 			options = { push_prep: false }
@@ -438,26 +439,29 @@ module Carson
 		# --- audit ---
 
 		def self.parse_audit_command( argv:, err: )
-			options = { json: false }
+			options = { json: false, all: false }
 			audit_parser = OptionParser.new do |opts|
-				opts.banner = "Usage: carson audit [--json]"
+				opts.banner = "Usage: carson audit [--all] [--json]"
 				opts.separator ""
 				opts.separator "Run pre-commit health checks on the repository."
 				opts.separator "Validates hooks, main-branch sync, PR status, and CI baseline."
 				opts.separator "Exits with a non-zero status when policy violations are found."
 				opts.separator ""
 				opts.separator "Options:"
+				opts.on( "--all", "Audit all governed repositories" ) { options[ :all ] = true }
 				opts.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
 				opts.separator ""
 				opts.separator "Examples:"
 				opts.separator "    carson audit           Check repository health (also the default command)"
 				opts.separator "    carson audit --json    Structured output for agent consumption"
+				opts.separator "    carson audit --all     Audit all governed repos"
 			end
 			audit_parser.parse!( argv )
 			unless argv.empty?
 				err.puts "#{BADGE} Unexpected arguments for audit: #{argv.join( ' ' )}"
 				return { command: :invalid }
 			end
+			return { command: "audit:all" } if options[ :all ]
 			{ command: "audit", json: options[ :json ] }
 		rescue OptionParser::ParseError => e
 			err.puts "#{BADGE} #{e.message}"
@@ -467,25 +471,28 @@ module Carson
 		# --- sync ---
 
 		def self.parse_sync_command( argv:, err: )
-			options = { json: false }
+			options = { json: false, all: false }
 			sync_parser = OptionParser.new do |opts|
-				opts.banner = "Usage: carson sync [--json]"
+				opts.banner = "Usage: carson sync [--all] [--json]"
 				opts.separator ""
 				opts.separator "Sync the local main branch with the remote."
 				opts.separator "Fetches and fast-forwards main without switching branches."
 				opts.separator ""
 				opts.separator "Options:"
+				opts.on( "--all", "Sync all governed repositories" ) { options[ :all ] = true }
 				opts.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
 				opts.separator ""
 				opts.separator "Examples:"
 				opts.separator "    carson sync            Pull latest changes from remote main"
 				opts.separator "    carson sync --json     Structured output for agent consumption"
+				opts.separator "    carson sync --all      Sync all governed repos"
 			end
 			sync_parser.parse!( argv )
 			unless argv.empty?
 				err.puts "#{BADGE} Unexpected arguments for sync: #{argv.join( ' ' )}"
 				return { command: :invalid }
 			end
+			return { command: "sync:all" } if options[ :all ]
 			{ command: "sync", json: options[ :json ] }
 		rescue OptionParser::ParseError => e
 			err.puts "#{BADGE} #{e.message}"
@@ -495,25 +502,28 @@ module Carson
 		# --- status ---
 
 		def self.parse_status_command( argv:, err: )
-			options = { json: false }
+			options = { json: false, all: false }
 			status_parser = OptionParser.new do |opts|
-				opts.banner = "Usage: carson status [--json]"
+				opts.banner = "Usage: carson status [--all] [--json]"
 				opts.separator ""
 				opts.separator "Show the current state of the repository."
 				opts.separator "Reports branch, worktrees, open PRs, stale branches, and version."
 				opts.separator ""
 				opts.separator "Options:"
+				opts.on( "--all", "Show status for all governed repositories" ) { options[ :all ] = true }
 				opts.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
 				opts.separator ""
 				opts.separator "Examples:"
 				opts.separator "    carson status           Quick overview of repository state"
 				opts.separator "    carson status --json    Structured output for agent consumption"
+				opts.separator "    carson status --all     Portfolio-wide status overview"
 			end
 			status_parser.parse!( argv )
 			unless argv.empty?
 				err.puts "#{BADGE} Unexpected arguments for status: #{argv.join( ' ' )}"
 				return { command: :invalid }
 			end
+			return { command: "status:all", json: options[ :json ] } if options[ :all ]
 			{ command: "status", json: options[ :json ] }
 		rescue OptionParser::ParseError => e
 			err.puts "#{BADGE} #{e.message}"
@@ -734,6 +744,14 @@ module Carson
 					json_output: parsed.fetch( :json, false ),
 					loop_seconds: parsed.fetch( :loop_seconds, nil )
 				)
+			when "template:check:all"
+				runtime.template_check_all!
+			when "audit:all"
+				runtime.audit_all!
+			when "sync:all"
+				runtime.sync_all!
+			when "status:all"
+				runtime.status_all!( json_output: parsed.fetch( :json, false ) )
 			else
 				runtime.send( :puts_line, "Unknown command: #{command}" )
 				Runtime::EXIT_ERROR

data/lib/carson/runtime/audit.rb

@@ -157,6 +157,54 @@ module Carson
 				exit_code
 			end
 
+			# Runs audit across all governed repositories.
+			def audit_all!
+				repos = config.govern_repos
+				if repos.empty?
+					puts_line "No governed repositories configured."
+					puts_line "  Run carson onboard in each repo to register."
+					return EXIT_ERROR
+				end
+
+				puts_line ""
+				puts_line "Audit all (#{repos.length} repo#{plural_suffix( count: repos.length )})"
+				passed = 0
+				blocked = 0
+				failed = 0
+
+				repos.each do |repo_path|
+					repo_name = File.basename( repo_path )
+					unless Dir.exist?( repo_path )
+						puts_line "#{repo_name}: FAIL (path not found)"
+						failed += 1
+						next
+					end
+
+					begin
+						rt = build_scoped_runtime( repo_path: repo_path )
+						status = rt.audit!
+						case status
+						when EXIT_OK
+							puts_line "#{repo_name}: ok" unless verbose?
+							passed += 1
+						when EXIT_BLOCK
+							puts_line "#{repo_name}: BLOCK" unless verbose?
+							blocked += 1
+						else
+							puts_line "#{repo_name}: FAIL" unless verbose?
+							failed += 1
+						end
+					rescue StandardError => e
+						puts_line "#{repo_name}: FAIL (#{e.message})"
+						failed += 1
+					end
+				end
+
+				puts_line ""
+				puts_line "Audit all complete: #{passed} ok, #{blocked} blocked, #{failed} failed."
+				blocked.zero? && failed.zero? ? EXIT_OK : EXIT_BLOCK
+			end
+
 		private
 			def pr_and_check_report
 				report = {

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

@@ -81,6 +81,8 @@ module Carson
 			end
 
 			# Re-applies hooks, templates, and audit across all governed repositories.
+			# Checks each repo for safety (active worktrees, uncommitted changes) and
+			# skips unsafe repos to avoid disrupting active work.
 			def refresh_all!
 				repos = config.govern_repos
 				if repos.empty?
@@ -92,6 +94,7 @@ module Carson
 				puts_line ""
 				puts_line "Refresh all (#{repos.length} repo#{plural_suffix( count: repos.length )})"
 				refreshed = 0
+				skipped = 0
 				failed = 0
 
 				repos.each do |repo_path|
@@ -102,6 +105,13 @@ module Carson
 						next
 					end
 
+					safety = portfolio_repo_safety( repo_path: repo_path )
+					unless safety.fetch( :safe )
+						puts_line "#{repo_name}: SKIP (#{safety.fetch( :reasons ).join( ', ' )})"
+						skipped += 1
+						next
+					end
+
 					status = refresh_single_repo( repo_path: repo_path, repo_name: repo_name )
 					if status == EXIT_ERROR
 						failed += 1
@@ -111,8 +121,11 @@ module Carson
 				end
 
 				puts_line ""
-				puts_line "Refresh all complete: #{refreshed} refreshed, #{failed} failed."
-				failed.zero? ? EXIT_OK : EXIT_ERROR
+				parts = [ "#{refreshed} refreshed" ]
+				parts << "#{skipped} skipped" if skipped.positive?
+				parts << "#{failed} failed" if failed.positive?
+				puts_line "Refresh all complete: #{parts.join( ', ' )}."
+				failed.zero? && skipped.zero? ? EXIT_OK : EXIT_ERROR
 			end
 
 			def prune_all!

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

@@ -42,6 +42,49 @@ module Carson
 				git_system!( "switch", start_branch ) if switched && branch_exists?( branch_name: start_branch )
 			end
 
+			# Syncs main branch across all governed repositories.
+			def sync_all!
+				repos = config.govern_repos
+				if repos.empty?
+					puts_line "No governed repositories configured."
+					puts_line "  Run carson onboard in each repo to register."
+					return EXIT_ERROR
+				end
+
+				puts_line ""
+				puts_line "Sync all (#{repos.length} repo#{plural_suffix( count: repos.length )})"
+				synced = 0
+				failed = 0
+
+				repos.each do |repo_path|
+					repo_name = File.basename( repo_path )
+					unless Dir.exist?( repo_path )
+						puts_line "#{repo_name}: FAIL (path not found)"
+						failed += 1
+						next
+					end
+
+					begin
+						rt = build_scoped_runtime( repo_path: repo_path )
+						status = rt.sync!
+						if status == EXIT_OK
+							puts_line "#{repo_name}: ok" unless verbose?
+							synced += 1
+						else
+							puts_line "#{repo_name}: FAIL" unless verbose?
+							failed += 1
+						end
+					rescue StandardError => e
+						puts_line "#{repo_name}: FAIL (#{e.message})"
+						failed += 1
+					end
+				end
+
+				puts_line ""
+				puts_line "Sync all complete: #{synced} synced, #{failed} failed."
+				failed.zero? ? EXIT_OK : EXIT_ERROR
+			end
+
 		private
 
 			# Runs a git command, suppressing stdout/stderr in JSON mode to keep output clean.

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

@@ -43,6 +43,50 @@ module Carson
 				( drift_count + stale_count ).positive? ? EXIT_BLOCK : EXIT_OK
 			end
 
+			# Read-only template drift check across all governed repositories.
+			def template_check_all!
+				repos = config.govern_repos
+				if repos.empty?
+					puts_line "No governed repositories configured."
+					puts_line "  Run carson onboard in each repo to register."
+					return EXIT_ERROR
+				end
+
+				puts_line ""
+				puts_line "Template check all (#{repos.length} repo#{plural_suffix( count: repos.length )})"
+				in_sync = 0
+				drifted = 0
+				failed = 0
+
+				repos.each do |repo_path|
+					repo_name = File.basename( repo_path )
+					unless Dir.exist?( repo_path )
+						puts_line "#{repo_name}: FAIL (path not found)"
+						failed += 1
+						next
+					end
+
+					begin
+						rt = build_scoped_runtime( repo_path: repo_path )
+						status = rt.template_check!
+						if status == EXIT_OK
+							puts_line "#{repo_name}: in sync" unless verbose?
+							in_sync += 1
+						else
+							puts_line "#{repo_name}: DRIFT" unless verbose?
+							drifted += 1
+						end
+					rescue StandardError => e
+						puts_line "#{repo_name}: FAIL (#{e.message})"
+						failed += 1
+					end
+				end
+
+				puts_line ""
+				puts_line "Template check complete: #{in_sync} in sync, #{drifted} drifted, #{failed} failed."
+				drifted.zero? && failed.zero? ? EXIT_OK : EXIT_BLOCK
+			end
+
 			# Applies managed template files as full-file writes from Carson sources.
 			# Also removes superseded files that are no longer part of the managed set.
 			def template_apply!( push_prep: false )

data/lib/carson/runtime/status.rb

@@ -17,6 +17,65 @@ module Carson
 				EXIT_OK
 			end
 
+			# Portfolio-wide status overview across all governed repositories.
+			def status_all!( json_output: false )
+				repos = config.govern_repos
+				if repos.empty?
+					puts_line "No governed repositories configured."
+					puts_line "  Run carson onboard in each repo to register."
+					return EXIT_ERROR
+				end
+
+				if json_output
+					results = []
+					repos.each do |repo_path|
+						repo_name = File.basename( repo_path )
+						unless Dir.exist?( repo_path )
+							results << { name: repo_name, status: "error", error: "path not found" }
+							next
+						end
+						begin
+							rt = build_scoped_runtime( repo_path: repo_path )
+							data = rt.send( :gather_status )
+							results << { name: repo_name, status: "ok" }.merge( data )
+						rescue StandardError => e
+							results << { name: repo_name, status: "error", error: e.message }
+						end
+					end
+					out.puts JSON.pretty_generate( { command: "status", repos: results } )
+					return EXIT_OK
+				end
+
+				puts_line "Carson #{Carson::VERSION} — Portfolio (#{repos.length} repo#{plural_suffix( count: repos.length )})"
+				puts_line ""
+
+				repos.each do |repo_path|
+					repo_name = File.basename( repo_path )
+					unless Dir.exist?( repo_path )
+						puts_line "#{repo_name}: MISSING"
+						next
+					end
+
+					begin
+						rt = build_scoped_runtime( repo_path: repo_path )
+						data = rt.send( :gather_status )
+						branch = data.fetch( :branch )
+						dirty = branch.fetch( :dirty ) ? " (dirty)" : ""
+						worktrees = data.fetch( :worktrees )
+						gov = data.fetch( :governance )
+						parts = []
+						parts << branch.fetch( :name ) + dirty
+						parts << "#{worktrees.count} worktree#{plural_suffix( count: worktrees.count )}" if worktrees.any?
+						parts << "templates #{gov.fetch( :templates )}" unless gov.fetch( :templates ) == :in_sync
+						puts_line "#{repo_name}: #{parts.join( '  ' )}"
+					rescue StandardError => e
+						puts_line "#{repo_name}: FAIL (#{e.message})"
+					end
+				end
+
+				EXIT_OK
+			end
+
 		private
 
 			# Collects all status facets into a structured hash.

data/lib/carson/runtime.rb

@@ -212,6 +212,48 @@ module Carson
 		def gh_run( *args )
 			github_adapter.run( *args )
 		end
+
+		# --- Portfolio helpers (shared by all --all commands) ---
+
+		# Checks whether a governed repo is safe for batch operations.
+		# Returns { safe: true/false, reasons: [...] }.
+		# Safe means: no active worktrees beyond main, no uncommitted changes.
+		# Non-git directories pass through as safe — let the command handle the error.
+		def portfolio_repo_safety( repo_path: )
+			git = Adapters::Git.new( repo_root: repo_path )
+
+			# Non-git directories pass through — the calling command reports the real error.
+			stdout, _, git_ok, = git.run( "rev-parse", "--is-inside-work-tree" )
+			return { safe: true, reasons: [] } unless git_ok && stdout.to_s.strip == "true"
+
+			reasons = []
+
+			# Active worktrees beyond the main working tree.
+			rt = build_scoped_runtime( repo_path: repo_path )
+			worktrees = rt.send( :worktree_list )
+			main_root = rt.send( :realpath_safe, repo_path )
+			active = worktrees.reject { |wt| wt.fetch( :path ) == main_root }
+			if active.any?
+				reasons << "#{active.count} active worktree#{active.count == 1 ? '' : 's'}"
+			end
+
+			# Uncommitted changes in the main working tree.
+			stdout, _, success, = git.run( "status", "--porcelain" )
+			if success && !stdout.strip.empty?
+				reasons << "uncommitted changes"
+			end
+
+			{ safe: reasons.empty?, reasons: reasons }
+		rescue StandardError => e
+			{ safe: false, reasons: [ e.message ] }
+		end
+
+		# Creates a scoped Runtime for a governed repo with captured output.
+		def build_scoped_runtime( repo_path: )
+			buf = verbose? ? out : StringIO.new
+			err_buf = verbose? ? err : StringIO.new
+			Runtime.new( repo_root: repo_path, tool_root: tool_root, out: buf, err: err_buf, verbose: verbose? )
+		end
 	end
 end
 

metadata

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