carson 2.15.3 → 2.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0c21d5ea31230fc4612636239e9de191266fa2d34b2cce7ea7259ac41f931a2
-  data.tar.gz: 3af15a3d35fa85c7ab0b0af8113f4f7210ad3b95097767c1e8056c6c75b02c56
+  metadata.gz: 0c0c99d97f1939fc304d067069e80b38319192a67c738ecfb2358d78e22bc5c6
+  data.tar.gz: 2233f42b74551f7cea4445130c4a5acd06f47839bc27288673f9c60792c9659d
 SHA512:
-  metadata.gz: 4c541901df28b9a174e31fb4e1ce6f2cefda6ec4a8968853cc542cc44490addb6f2b751348c58eb88c9aeb0ac0e010fc4cea5fa8b759c3f6795cb56bc5f6b0f1
-  data.tar.gz: 7d597b6b65469ad0cf969b960ddd01dace459ba463bebc1749e57d1056a3a2651c9186c6ad8f38d5810994513f75207d75eac0ae6d375d22384fc627d6a54b99
+  metadata.gz: c03226c3e685b672675e6aee16e4027d3f4ffb992a9ad6894a971a6c079d0f0f6c749e0806605109a588805788aa73f6e1c23aa0cec5ab448ee7d48f1c5c63c5
+  data.tar.gz: c9587d82f0b6f75fe0146d74da495e229486a49d4fb39fc3b3a6e774391dbb6439f099f2f2474b2cf603a49c9eaf1ffeaaf416f2baf49f0ab303b6fcfd17c930

data/API.md

@@ -19,8 +19,8 @@ carson <command> [subcommand] [arguments]
 | `carson lint policy --source <path-or-git-url> [--ref <git-ref>] [--force]` | Distribute lint configs from a central source into the governed repo's `.github/linters/`. |
 | `carson onboard [repo_path]` | Apply one-command baseline setup for a target git repository. Auto-triggers `setup` on first run. |
 | `carson prepare` | Install or refresh Carson-managed global hooks. |
-| `carson refresh [repo_path]` | Re-apply hooks, templates, and audit after upgrading Carson. |
-| `carson offboard [repo_path]` | Remove Carson-managed host artefacts and detach Carson hooks path where applicable. |
+| `carson refresh [repo_path]` | Re-apply hooks, templates, and audit after upgrading Carson. Auto-propagates template updates to the remote via worktree (branch workflow: PR on `carson/template-sync`; trunk workflow: push to main). |
+| `carson offboard [repo_path]` | Remove Carson-managed host artefacts, detach Carson hooks path, and deregister from `govern.repos`. |
 
 ### Daily commands
 

data/MANUAL.md

@@ -354,6 +354,15 @@ carson template check
 - Run `carson refresh` to re-apply hooks and templates for the new Carson version.
 - Run `carson refresh --all` to refresh all governed repositories at once.
 
+**Template auto-propagation**
+
+When `carson refresh` detects template drift, it applies the updates locally and then auto-propagates them to the remote:
+
+- **Branch workflow** (default): creates a `carson/template-sync` branch, pushes updates, and opens (or updates) a PR. Re-running refresh force-pushes to the same branch — idempotent.
+- **Trunk workflow**: pushes template changes directly to main.
+
+Propagation uses a temporary git worktree so the user's working tree and current branch are never disturbed. If propagation fails (no remote, push denied), the local apply still succeeds — propagation errors are reported but non-blocking.
+
 ## Offboard a Repository
 
 To retire Carson from a repository:
@@ -362,7 +371,7 @@ To retire Carson from a repository:
 carson offboard /path/to/your-repo
 ```
 
-This removes Carson-managed host artefacts and unsets `core.hooksPath` when it points to Carson-managed global hooks.
+This removes Carson-managed host artefacts, unsets `core.hooksPath` when it points to Carson-managed global hooks, and deregisters the repository from `govern.repos` so `carson govern` and `carson refresh --all` no longer target it.
 
 ## Related Documents
 

data/RELEASE.md

@@ -5,6 +5,31 @@ 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`.
 
+## 2.16.0 — Auto-propagate Template Changes
+
+### What changed
+
+- `carson refresh` now auto-propagates template updates to the remote. When template drift is detected and applied locally, Carson creates a git worktree, writes the updated templates, commits, and pushes — no manual git workflow required.
+- **Branch workflow** (default): pushes to `carson/template-sync` and creates (or updates) a PR. Re-running refresh force-pushes updates to the same branch.
+- **Trunk workflow**: pushes template changes directly to main.
+- The worktree approach ensures zero disturbance to the user's working tree and current branch.
+- `carson refresh --all` now surfaces PR URLs and push refs in the per-repo summary line.
+- New public `template_sync_result` accessor on `Runtime` for cross-module access to propagation outcomes.
+
+### Migration
+
+No configuration changes needed. Run `carson refresh` — template updates are now automatically pushed upstream.
+
+## 2.15.4 — Lint Workflow Fix
+
+### What changed
+
+- Removed explicit `LINTER_RULES_PATH: .github/linters` from the Carson Lint workflow template. MegaLinter v8 crashes with `ValueError` when the directory does not exist. The path is already MegaLinter's default — omitting it lets MegaLinter use `.github/linters/` when present and silently skip when absent.
+
+### Migration
+
+Run `carson refresh` in governed repositories to pick up the updated workflow.
+
 ## 2.15.3 — Initial Commit Guard
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-2.15.3
+2.16.0

data/lib/carson/runtime/local.rb

@@ -1,6 +1,8 @@
 module Carson
 	class Runtime
 		module Local
+			TEMPLATE_SYNC_BRANCH = "carson/template-sync".freeze
+
 			def sync!
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
@@ -216,9 +218,12 @@ module Carson
 					hook_status = prepare!
 					return hook_status unless hook_status == EXIT_OK
 
+					drift_count = template_results.count { |entry| entry.fetch( :status ) != "ok" }
 					template_status = template_apply!
 					return template_status unless template_status == EXIT_OK
 
+					@template_sync_result = template_propagate!( drift_count: drift_count )
+
 					audit_status = audit!
 					if audit_status == EXIT_OK
 						puts_line "OK: Carson refresh completed for #{repo_root}."
@@ -242,6 +247,8 @@ module Carson
 					puts_line "Templates in sync."
 				end
 
+				@template_sync_result = template_propagate!( drift_count: template_drift_count )
+
 				audit_status = audit!
 				puts_line "Refresh complete."
 				audit_status
@@ -307,6 +314,8 @@ module Carson
 					end
 				end
 				remove_empty_offboard_directories!
+				remove_govern_repo!( repo_path: File.expand_path( repo_root ) )
+				puts_verbose "govern_deregistered: #{File.expand_path( repo_root )}"
 				puts_verbose "offboard_summary: removed=#{removed_count} missing=#{missing_count}"
 				if verbose?
 					puts_line "OK: Carson offboard completed for #{repo_root}."
@@ -422,6 +431,201 @@ module Carson
 
 		private
 
+			# Orchestrates worktree-based template propagation to the remote.
+			# Skips silently when there is no drift or no remote configured.
+			# Returns a result hash stored in @template_sync_result.
+			def template_propagate!( drift_count: )
+				if drift_count.zero?
+					puts_verbose "template_propagate: skip (no drift)"
+					return { status: :skip, reason: "no drift" }
+				end
+
+				unless git_remote_exists?( remote_name: config.git_remote )
+					puts_verbose "template_propagate: skip (no remote #{config.git_remote})"
+					return { status: :skip, reason: "no remote" }
+				end
+
+				worktree_dir = nil
+				begin
+					worktree_dir = template_propagate_create_worktree!
+					template_propagate_write_files!( worktree_dir: worktree_dir )
+					committed = template_propagate_commit!( worktree_dir: worktree_dir )
+					unless committed
+						puts_verbose "template_propagate: skip (no changes after write)"
+						return { status: :skip, reason: "no changes" }
+					end
+					result = template_propagate_deliver!( worktree_dir: worktree_dir )
+					template_propagate_report!( result: result )
+					result
+				rescue StandardError => e
+					puts_verbose "template_propagate: error (#{e.message})"
+					{ status: :error, reason: e.message }
+				ensure
+					template_propagate_cleanup!( worktree_dir: worktree_dir ) if worktree_dir
+				end
+			end
+
+			# Creates a detached worktree from the remote main, checks out the sync branch,
+			# and disables hooks so Carson's own pre-commit never fires inside the worktree.
+			def template_propagate_create_worktree!
+				worktree_dir = File.join( Dir.tmpdir, "carson-template-sync-#{Process.pid}-#{Time.now.to_i}" )
+				wt_git = Adapters::Git.new( repo_root: worktree_dir )
+
+				git_system!( "fetch", config.git_remote, config.main_branch )
+				git_system!( "worktree", "add", "--detach", worktree_dir, "#{config.git_remote}/#{config.main_branch}" )
+				wt_git.run( "checkout", "-B", TEMPLATE_SYNC_BRANCH )
+				wt_git.run( "config", "core.hooksPath", "/dev/null" )
+				puts_verbose "template_propagate: worktree created at #{worktree_dir}"
+				worktree_dir
+			end
+
+			# Copies all Carson template source files into the worktree.
+			# Also removes superseded files present in the worktree.
+			def template_propagate_write_files!( worktree_dir: )
+				config.template_managed_files.each do |managed_file|
+					relative_within_github = managed_file.delete_prefix( ".github/" )
+					template_path = File.join( github_templates_dir, relative_within_github )
+					template_path = File.join( github_templates_dir, File.basename( managed_file ) ) unless File.file?( template_path )
+					next unless File.file?( template_path )
+
+					target_path = File.join( worktree_dir, managed_file )
+					FileUtils.mkdir_p( File.dirname( target_path ) )
+					expected_content = normalize_text( text: File.read( template_path ) )
+					File.write( target_path, expected_content )
+					puts_verbose "template_propagate: wrote #{managed_file}"
+				end
+
+				template_superseded_present_in( root: worktree_dir ).each do |file|
+					file_path = File.join( worktree_dir, file )
+					File.delete( file_path )
+					puts_verbose "template_propagate: removed superseded #{file}"
+				end
+			end
+
+			# Stages all changes in the worktree and commits if there is an actual diff.
+			# Returns true if a commit was created, false if worktree content matches remote.
+			def template_propagate_commit!( worktree_dir: )
+				wt_git = Adapters::Git.new( repo_root: worktree_dir )
+				wt_git.run( "add", "--all" )
+
+				_, _, no_diff, = wt_git.run( "diff", "--cached", "--quiet" )
+				return false if no_diff
+
+				wt_git.run( "commit", "-m", "chore: sync Carson #{Carson::VERSION} managed templates" )
+				puts_verbose "template_propagate: committed"
+				true
+			end
+
+			# Dispatches to trunk or branch delivery based on workflow style.
+			def template_propagate_deliver!( worktree_dir: )
+				if config.workflow_style == "trunk"
+					template_propagate_deliver_trunk!( worktree_dir: worktree_dir )
+				else
+					template_propagate_deliver_branch!( worktree_dir: worktree_dir )
+				end
+			end
+
+			# Trunk mode: push template changes directly to main.
+			def template_propagate_deliver_trunk!( worktree_dir: )
+				wt_git = Adapters::Git.new( repo_root: worktree_dir )
+				stdout_text, stderr_text, success, = wt_git.run( "push", config.git_remote, "HEAD:refs/heads/#{config.main_branch}" )
+				unless success
+					error_text = stderr_text.to_s.strip
+					error_text = "push to #{config.main_branch} failed" if error_text.empty?
+					raise error_text
+				end
+				puts_verbose "template_propagate: pushed to #{config.main_branch}"
+				{ status: :pushed, ref: config.main_branch }
+			end
+
+			# Branch mode: force-push the sync branch and ensure a PR exists.
+			def template_propagate_deliver_branch!( worktree_dir: )
+				wt_git = Adapters::Git.new( repo_root: worktree_dir )
+				stdout_text, stderr_text, success, = wt_git.run( "push", "--force-with-lease", config.git_remote, "#{TEMPLATE_SYNC_BRANCH}:#{TEMPLATE_SYNC_BRANCH}" )
+				unless success
+					error_text = stderr_text.to_s.strip
+					error_text = "push #{TEMPLATE_SYNC_BRANCH} failed" if error_text.empty?
+					raise error_text
+				end
+				puts_verbose "template_propagate: pushed #{TEMPLATE_SYNC_BRANCH}"
+
+				pr_url = template_propagate_ensure_pr!( worktree_dir: worktree_dir )
+				{ status: :pr, branch: TEMPLATE_SYNC_BRANCH, pr_url: pr_url }
+			end
+
+			# Checks for an existing open PR from the sync branch; creates one if none exists.
+			# Returns the PR URL.
+			def template_propagate_ensure_pr!( worktree_dir: )
+				wt_gh = Adapters::GitHub.new( repo_root: worktree_dir )
+
+				# Check for existing open PR.
+				stdout_text, _, success, = wt_gh.run(
+					"pr", "list",
+					"--head", TEMPLATE_SYNC_BRANCH,
+					"--base", config.main_branch,
+					"--state", "open",
+					"--json", "url",
+					"--jq", ".[0].url"
+				)
+				existing_url = stdout_text.to_s.strip
+				if success && !existing_url.empty?
+					puts_verbose "template_propagate: existing PR #{existing_url}"
+					return existing_url
+				end
+
+				# Create new PR.
+				stdout_text, stderr_text, success, = wt_gh.run(
+					"pr", "create",
+					"--head", TEMPLATE_SYNC_BRANCH,
+					"--base", config.main_branch,
+					"--title", "chore: sync Carson #{Carson::VERSION} managed templates",
+					"--body", "Auto-generated by `carson refresh`.\n\nUpdates managed template files to match Carson #{Carson::VERSION}."
+				)
+				unless success
+					error_text = stderr_text.to_s.strip
+					error_text = "gh pr create failed" if error_text.empty?
+					raise error_text
+				end
+				pr_url = stdout_text.to_s.strip
+				puts_verbose "template_propagate: created PR #{pr_url}"
+				pr_url
+			end
+
+			# Removes the worktree regardless of state.
+			def template_propagate_cleanup!( worktree_dir: )
+				git_run( "worktree", "remove", "--force", worktree_dir )
+				puts_verbose "template_propagate: worktree cleaned up"
+			rescue StandardError => e
+				puts_verbose "template_propagate: cleanup warning (#{e.message})"
+			end
+
+			# Prints a human-readable summary of the propagation result.
+			def template_propagate_report!( result: )
+				case result.fetch( :status )
+				when :pushed
+					puts_line "Templates pushed to #{result.fetch( :ref )}."
+				when :pr
+					puts_line "Template sync PR: #{result.fetch( :pr_url )}"
+				end
+			end
+
+			# Checks which superseded files exist under an arbitrary root directory.
+			def template_superseded_present_in( root: )
+				config.template_superseded_files.select do |file|
+					File.file?( File.join( root, file ) )
+				end
+			end
+
+			def refresh_sync_suffix( result: )
+				return "" if result.nil?
+
+				case result.fetch( :status )
+				when :pushed then " (templates pushed to #{result.fetch( :ref )})"
+				when :pr then " (PR: #{result.fetch( :pr_url )})"
+				else ""
+				end
+			end
+
 			# Refreshes a single governed repository using a scoped Runtime.
 			def refresh_single_repo( repo_path:, repo_name: )
 				if verbose?
@@ -431,7 +635,8 @@ module Carson
 				end
 				status = rt.refresh!
 				label = refresh_status_label( status: status )
-				puts_line "#{repo_name}: #{label}"
+				sync_suffix = refresh_sync_suffix( result: rt.template_sync_result )
+				puts_line "#{repo_name}: #{label}#{sync_suffix}"
 				status
 			rescue StandardError => e
 				puts_line "#{repo_name}: FAIL (#{e.message})"

data/lib/carson/runtime/setup.rb

@@ -376,6 +376,22 @@ module Carson
 				input.start_with?( "y" )
 			end
 
+			# Removes a repo path from govern.repos in global config.
+			def remove_govern_repo!( repo_path: )
+				config_path = Config.global_config_path( repo_root: repo_root )
+				return if config_path.empty? || !File.file?( config_path )
+
+				existing_data = load_existing_config( path: config_path )
+				repos = Array( existing_data.dig( "govern", "repos" ) )
+				updated = repos.reject { |entry| File.expand_path( entry ) == File.expand_path( repo_path ) }
+				return if updated.length == repos.length
+
+				existing_data[ "govern" ] ||= {}
+				existing_data[ "govern" ][ "repos" ] = updated
+				File.write( config_path, JSON.pretty_generate( existing_data ) )
+				reload_config_after_setup!
+			end
+
 			# Appends a repo path to govern.repos without replacing the array via deep_merge.
 			def append_govern_repo!( repo_path: )
 				config_path = Config.global_config_path( repo_root: repo_root )

data/lib/carson/runtime.rb

@@ -33,8 +33,11 @@ module Carson
 			@config = Config.load( repo_root: repo_root )
 			@git_adapter = Adapters::Git.new( repo_root: repo_root )
 			@github_adapter = Adapters::GitHub.new( repo_root: repo_root )
+			@template_sync_result = nil
 		end
 
+		attr_reader :template_sync_result
+
 	private
 
 		attr_reader :repo_root, :tool_root, :out, :err, :in, :config, :git_adapter, :github_adapter

data/templates/.github/workflows/carson-lint.yml

@@ -20,4 +20,3 @@ jobs:
         env:
           VALIDATE_ALL_CODEBASE: false
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          LINTER_RULES_PATH: .github/linters

metadata

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