carson 4.1.1 → 4.2.0

data/lib/carson/warehouse.rb

@@ -1,18 +1,24 @@
 # A governed repository. In the FedEx metaphor, the warehouse is where
-# parcels (committed changes) are stored on shelves (worktrees) with
-# labels (branches). Git and gh commands are hidden inside — callers
-# never see git or GitHub terms.
-require "digest"
+# parcels are built on workbenches (worktrees) with labels (branches).
+# Git and gh commands are hidden inside — callers never see git or
+# GitHub terms.
 require "fileutils"
-require "json"
 require "open3"
 
+require_relative "warehouse/workbench"
+require_relative "warehouse/seal"
+require_relative "warehouse/bureau"
+
 module Carson
-	# A governed repository — the warehouse where parcels are stored on
-	# shelves (worktrees) with labels (branches). Wraps git operations
-	# with story-language methods. An intelligent warehouse that manages
-	# itself: packing parcels, checking compliance, and sweeping up.
+	# A governed repository — the warehouse where parcels are built on
+	# workbenches (worktrees) with labels (branches). An intelligent
+	# warehouse that manages itself: packing parcels, checking compliance,
+	# managing workbenches, and sweeping up.
 	class Warehouse
+		include Workbench
+		include Seal
+		include Bureau
+
 		attr_reader :path
 
 		def initialize( path:, main_label: "main", bureau_address: "github", compliance_checker: nil )
@@ -24,12 +30,12 @@ module Carson
 
 		# --- What the warehouse knows ---
 
-		# The label on the current shelf (branch name).
+		# The label on the current workbench (branch name).
 		def current_label
 			git( "rev-parse", "--abbrev-ref", "HEAD" ).first.strip
 		end
 
-		# The tip of the parcel on the current shelf (commit SHA).
+		# The tip of the parcel on the current workbench (commit SHA).
 		def current_head
 			git( "rev-parse", "HEAD" ).first.strip
 		end
@@ -44,7 +50,7 @@ module Carson
 			@bureau_address
 		end
 
-		# Is the warehouse floor clean? No uncommitted changes on the current shelf.
+		# Is the warehouse floor clean? No uncommitted changes on the current workbench.
 		def clean?
 			output, _, status = git( "status", "--porcelain" )
 			status.success? && output.strip.empty?
@@ -78,7 +84,6 @@ module Carson
 		# Ensure the warehouse complies with company standards (template sync).
 		# Delegates to the injected compliance checker. If no checker is set,
 		# the warehouse assumes compliance — no templates to enforce.
-		# Returns a hash: { compliant: true/false, committed: true/false, error: nil/string }
 		def submit_compliance!
 			return { compliant: true, committed: false } unless @compliance_checker
 
@@ -87,15 +92,13 @@ module Carson
 
 		# Update the warehouse's production standard — rebase onto latest registry state.
 		# Called after the bureau refuses a parcel for being behind standard.
-		# Returns true on success, false on failure.
 		def rebase_on_latest_standard!( registry: "#{bureau_address}/#{main_label}" )
 			_, _, status = git( "rebase", registry )
 			status.success?
 		end
 
 		# Pack a parcel — stage all changes and commit.
-		# Refuses if the shelf is sealed (parcel already in flight).
-		# Returns true on success, false on failure.
+		# Refuses if the workbench is sealed (parcel already in flight).
 		def pack!( message: )
 			if sealed?
 				raise "Branch is locked — PR ##{sealed_tracking_number} in flight. " \
@@ -106,38 +109,8 @@ module Carson
 			status.success?
 		end
 
-		# --- Shelf seal ---
-
-		# Seal the shelf — no more packing until the delivery outcome is confirmed.
-		# The courier seals the shelf after shipping and filing the waybill.
-		# The marker lives outside the worktree (~/.carson/seals/) so it does
-		# not pollute git status or block delivery with a dirty-tree guard.
-		def seal_shelf!( tracking_number: )
-			marker = delivering_marker_path
-			FileUtils.mkdir_p( File.dirname( marker ) )
-			File.write( marker, "#{tracking_number}\n#{@path}" )
-		end
-
-		# Unseal the shelf — the courier brought back the parcel.
-		# Called when the delivery outcome is held or rejected.
-		def unseal_shelf!
-			File.delete( delivering_marker_path ) if File.exist?( delivering_marker_path )
-		end
-
-		# Is this shelf sealed for a delivery in flight?
-		def sealed?
-			File.exist?( delivering_marker_path )
-		end
-
-		# The tracking number of the in-flight delivery (nil if not sealed).
-		def sealed_tracking_number
-			return nil unless sealed?
-			File.read( delivering_marker_path ).lines.first.strip
-		end
-
 		# Receive the latest standard from the registry after a parcel is accepted.
 		# Fast-forwards local main without switching branches.
-		# Returns true on success, false on failure.
 		#
 		# Two paths depending on the main worktree's checkout state:
 		# - Main checked out → merge --ff-only (updates ref + working tree).
@@ -146,24 +119,20 @@ module Carson
 		def receive_latest_standard!( remote: bureau_address )
 			root = main_worktree_root
 
-			# Fetch remote tracking refs — always safe, even when main is checked out.
 			_, _, fetch_status = Open3.capture3( "git", "-C", root, "fetch", remote )
 			return false unless fetch_status.success?
 
-			# Determine how to advance local main.
 			head_ref, _, head_status = Open3.capture3(
 				"git", "-C", root, "rev-parse", "--abbrev-ref", "HEAD"
 			)
 			return false unless head_status.success?
 
 			if head_ref.strip == @main_label
-				# Main is checked out in the main worktree — fast-forward via merge.
 				_, _, merge_status = Open3.capture3(
 					"git", "-C", root, "merge", "--ff-only", "#{remote}/#{@main_label}"
 				)
 				merge_status.success?
 			else
-				# Main is not checked out — safe to update the ref via fetch refspec.
 				_, _, refspec_status = Open3.capture3(
 					"git", "-C", root, "fetch", remote, "#{@main_label}:#{@main_label}"
 				)
@@ -171,72 +140,8 @@ module Carson
 			end
 		end
 
-		# --- Bureau interaction ---
-		# The warehouse owns the connection to the bureau (GitHub).
-		# It queries, files, and registers on behalf of the courier.
-
-		# Check the parcel's status at the bureau using the waybill.
-		# Calls gh pr view + gh pr checks. Records findings onto the waybill.
-		def check_parcel_at_bureau_with( waybill )
-			state = fetch_pr_state_for( waybill.tracking_number )
-			ci, ci_diagnostic = fetch_ci_state_for( waybill.tracking_number )
-			waybill.record( state: state, ci: ci, ci_diagnostic: ci_diagnostic )
-		end
-
-		# File a waybill at the bureau for this parcel.
-		# Calls gh pr create. Returns a Waybill with tracking number, or nil on failure.
-		def file_waybill_for!( parcel, title: nil, body_file: nil )
-			filing_title = title || Waybill.default_title_for( parcel.label )
-			arguments = [ "pr", "create", "--title", filing_title, "--head", parcel.label ]
-
-			if body_file && File.exist?( body_file )
-				arguments.push( "--body-file", body_file )
-			else
-				arguments.push( "--body", "" )
-			end
-
-			stdout, _, status = gh( *arguments )
-			tracking_number = nil
-			url = nil
-
-			if status.success?
-				url = stdout.to_s.strip
-				tracking_number = url.split( "/" ).last.to_i
-				tracking_number = nil if tracking_number == 0
-			end
-
-			# If create failed or returned no number, try to find an existing PR.
-			unless tracking_number
-				tracking_number, url = find_existing_waybill_for( parcel.label )
-			end
-
-			return nil unless tracking_number
-
-			Waybill.new( label: parcel.label, tracking_number: tracking_number, url: url )
-		end
-
-		# Register the parcel at the bureau using the waybill.
-		# Calls gh pr merge. Stamps the waybill on success.
-		def register_parcel_at_bureau_with!( waybill, method: )
-			_, _, status = gh( "pr", "merge", waybill.tracking_number.to_s, "--#{method}" )
-			if status.success?
-				waybill.stamp( :accepted )
-			else
-				# Re-check the state — the merge may have revealed a new blocker.
-				check_parcel_at_bureau_with( waybill )
-			end
-		end
-
 		# --- Inventory ---
 
-		# All shelves (worktree paths).
-		def shelves
-			output, = git( "worktree", "list", "--porcelain" )
-			output.lines
-				.select { it.start_with?( "worktree " ) }
-				.map { it.sub( "worktree ", "" ).strip }
-		end
-
 		# All labels (branch names).
 		def labels
 			output, = git( "branch", "--format", "%(refname:short)" )
@@ -249,88 +154,31 @@ module Carson
 			merged_output.lines.map { it.strip }.include?( name )
 		end
 
-		# The main warehouse location — resolves correctly even from a side shelf.
-		# Used by sync! and ledger recording to always reference the canonical path.
+		# All worktree paths (transitional — use workbenches for Worktree instances).
+		def shelves
+			output, = git( "worktree", "list", "--porcelain" )
+			output.lines
+				.select { it.start_with?( "worktree " ) }
+				.map { it.sub( "worktree ", "" ).strip }
+		end
+
+		# The main warehouse location — resolves correctly even from a workbench.
 		def main_worktree_root
 			git_common_dir, = git( "rev-parse", "--path-format=absolute", "--git-common-dir" )
 			common = git_common_dir.strip
-			# If it ends with /.git, the parent is the main worktree root.
 			common.end_with?( "/.git" ) ? File.dirname( common ) : common
 		end
 
 	private
 
-		# Path to the delivery marker file — signals the shelf is sealed.
-		# Lives outside the worktree at ~/.carson/seals/<sha256-of-path>
-		# so it does not pollute git status.
-		def delivering_marker_path
-			seals_dir = File.join( Dir.home, ".carson", "seals" )
-			key = Digest::SHA256.hexdigest( @path )
-			File.join( seals_dir, key )
-		end
-
 		# All git commands go through this single gateway.
-		# Returns [stdout, stderr, status].
 		def git( *arguments )
 			Open3.capture3( "git", "-C", path, *arguments )
 		end
 
 		# All gh commands go through this single gateway.
-		# Returns [stdout, stderr, status].
 		def gh( *arguments )
 			Open3.capture3( "gh", *arguments, chdir: path )
 		end
-
-		# Fetch PR state from the bureau for a tracking number.
-		# Returns the parsed state hash, or nil on failure.
-		def fetch_pr_state_for( tracking_number )
-			stdout, _, status = gh(
-				"pr", "view", tracking_number.to_s,
-				"--json", "number,state,isDraft,url,mergeStateStatus,mergeable,mergedAt"
-			)
-			return nil unless status.success?
-
-			JSON.parse( stdout )
-		rescue JSON::ParserError
-			nil
-		end
-
-		# Fetch CI state from the bureau for a tracking number.
-		# Returns [ci_symbol, diagnostic_or_nil].
-		# Captures the first line of stderr as diagnostic when the command fails.
-		def fetch_ci_state_for( tracking_number )
-			stdout, stderr, status = gh(
-				"pr", "checks", tracking_number.to_s,
-				"--json", "name,bucket"
-			)
-			unless status.success?
-				return [ :error, stderr.to_s.strip.lines.first&.strip ]
-			end
-
-			checks = JSON.parse( stdout ) rescue []
-			return [ :none, nil ] if checks.empty?
-
-			buckets = checks.map { it[ "bucket" ].to_s.downcase }
-			return [ :fail, nil ] if buckets.include?( "fail" )
-			return [ :pending, nil ] if buckets.include?( "pending" )
-
-			[ :pass, nil ]
-		end
-
-		# Try to find an existing PR for this label at the bureau.
-		# Returns [tracking_number, url] or [nil, nil].
-		def find_existing_waybill_for( label )
-			stdout, _, status = gh(
-				"pr", "view", label,
-				"--json", "number,url,state"
-			)
-			if status.success?
-				data = JSON.parse( stdout ) rescue nil
-				if data && data[ "number" ] && data[ "state" ] == "OPEN"
-					return [ data[ "number" ], data[ "url" ].to_s ]
-				end
-			end
-			[ nil, nil ]
-		end
 	end
 end

data/lib/carson/worktree.rb

@@ -420,6 +420,16 @@ module Carson
 			false
 		end
 
+		# Is the workbench surface clean? (no uncommitted changes)
+		def clean?
+			return false unless exists?
+
+			stdout, = Open3.capture3( "git", "status", "--porcelain", chdir: path )
+			stdout.to_s.strip.empty?
+		rescue StandardError
+			false
+		end
+
 	# rubocop:disable Layout/AccessModifierIndentation -- tab-width calculation produces unfixable mixed tabs+spaces
 	private
 	# rubocop:enable Layout/AccessModifierIndentation

data/lib/carson.rb

@@ -93,4 +93,4 @@ require_relative "carson/adapters/prompt"
 require_relative "carson/adapters/codex"
 require_relative "carson/adapters/claude"
 require_relative "carson/runtime"
-require_relative "carson/cli"
+require_relative "cli"

data/lib/{carson/cli.rb → cli.rb}

@@ -5,7 +5,7 @@ require "optparse"
 module Carson
 	class CLI
 		PORTFOLIO_COMMANDS = %w[onboard offboard list refresh version].freeze
-		REPO_COMMANDS = %w[deliver receive sync status audit prune housekeep worktree abandon recover review template setup].freeze
+		REPO_COMMANDS = %w[deliver receive sync status audit prune housekeep worktree abandon recover review template setup checkin checkout].freeze
 		ALL_COMMANDS = ( PORTFOLIO_COMMANDS + REPO_COMMANDS ).freeze
 
 		def self.start( arguments:, repo_root:, tool_root:, output:, error: )
@@ -229,6 +229,10 @@ module Carson
 				parse_housekeep_command( arguments: arguments, error: error )
 			when "worktree"
 				parse_worktree_subcommand( arguments: arguments, error: error )
+			when "checkin"
+				parse_checkin_command( arguments: arguments, error: error )
+			when "checkout"
+				parse_checkout_command( arguments: arguments, error: error )
 			when "abandon"
 				parse_abandon_command( arguments: arguments, error: error )
 			when "recover"
@@ -523,6 +527,71 @@ module Carson
 			{ command: :invalid }
 		end
 
+		# --- checkin ---
+
+		def self.parse_checkin_command( arguments:, error: )
+			options = { json: false }
+			checkin_parser = OptionParser.new do |parser|
+				parser.banner = "Usage: carson checkin <name> [--json]"
+				parser.separator ""
+				parser.separator "Prepare a fresh workbench from the latest standard."
+				parser.separator "The agent names the workbench — it becomes the branch."
+				parser.separator ""
+				parser.separator "Options:"
+				parser.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
+				parser.separator ""
+				parser.separator "Examples:"
+				parser.separator "    carson checkin feature-auth"
+				parser.separator "    carson checkin oo/refactor-courier"
+			end
+			checkin_parser.parse!( arguments )
+			name = arguments.shift.to_s.strip
+			if name.empty?
+				error.puts "#{BADGE} Missing name. Use: carson checkin <name>"
+				error.puts checkin_parser
+				return { command: :invalid }
+			end
+
+			{ command: "checkin", workbench_name: name, json: options.fetch( :json ) }
+		rescue OptionParser::ParseError => exception
+			error.puts "#{BADGE} #{exception.message}"
+			error.puts checkin_parser
+			{ command: :invalid }
+		end
+
+		# --- checkout ---
+
+		def self.parse_checkout_command( arguments:, error: )
+			options = { json: false, force: false }
+			checkout_parser = OptionParser.new do |parser|
+				parser.banner = "Usage: carson checkout <name> [--json] [--force]"
+				parser.separator ""
+				parser.separator "Release a workbench when safe."
+				parser.separator "Removes the directory and local branch."
+				parser.separator ""
+				parser.separator "Options:"
+				parser.on( "--json", "Machine-readable JSON output" ) { options[ :json ] = true }
+				parser.on( "--force", "Skip safety checks" ) { options[ :force ] = true }
+				parser.separator ""
+				parser.separator "Examples:"
+				parser.separator "    carson checkout feature-auth"
+				parser.separator "    carson checkout oo/refactor-courier --force"
+			end
+			checkout_parser.parse!( arguments )
+			name = arguments.shift.to_s.strip
+			if name.empty?
+				error.puts "#{BADGE} Missing name. Use: carson checkout <name>"
+				error.puts checkout_parser
+				return { command: :invalid }
+			end
+
+			{ command: "checkout", workbench_name: name, force: options.fetch( :force ), json: options.fetch( :json ) }
+		rescue OptionParser::ParseError => exception
+			error.puts "#{BADGE} #{exception.message}"
+			error.puts checkout_parser
+			{ command: :invalid }
+		end
+
 		# --- review ---
 
 		def self.parse_review_subcommand( arguments:, error: )
@@ -898,7 +967,7 @@ module Carson
 		# referenced by Claude Code's PreToolUse hook. It must exist regardless of
 		# whether `carson refresh` has been run in any governed repo.
 		def self.ensure_global_artefacts!( tool_root: )
-			source = File.join( tool_root, "config", ".github", "hooks", "command-guard" )
+			source = File.join( tool_root, "config", "hooks", "command-guard" )
 			return unless File.file?( source )
 
 			hooks_base = File.expand_path( "~/.carson/hooks" )
@@ -937,6 +1006,10 @@ module Carson
 				runtime.worktree_list!( json_output: parsed.fetch( :json, false ) )
 			when "worktree:remove"
 				runtime.worktree_remove!( worktree_path: parsed.fetch( :worktree_path ), force: parsed.fetch( :force, false ), json_output: parsed.fetch( :json, false ) )
+			when "checkin"
+				dispatch_checkin( parsed: parsed, runtime: runtime )
+			when "checkout"
+				dispatch_checkout( parsed: parsed, runtime: runtime )
 			when "onboard"
 				runtime.onboard!
 			when "refresh:all"
@@ -978,5 +1051,77 @@ module Carson
 				Runtime::EXIT_ERROR
 			end
 		end
+
+		# --- Direct Warehouse dispatch for checkin/checkout ---
+		# No Runtime — CLI builds the Warehouse and calls domain methods directly.
+		# This is the target architecture; other commands migrate here as Runtime dissolves.
+
+		def self.dispatch_checkin( parsed:, runtime: )
+			warehouse = build_warehouse( runtime: runtime )
+			result = warehouse.checkin!( name: parsed.fetch( :workbench_name ) )
+			report_workbench( result: result, json: parsed.fetch( :json, false ), output: runtime.output )
+		end
+
+		def self.dispatch_checkout( parsed:, runtime: )
+			warehouse = build_warehouse( runtime: runtime )
+			workbench = warehouse.workbench_named( parsed.fetch( :workbench_name ) )
+
+			unless workbench
+				name = parsed.fetch( :workbench_name )
+				result = { command: "checkout", status: "error",
+					name: name,
+					error: "#{name} is not a registered workbench",
+					recovery: "carson worktree list" }
+				return report_workbench( result: result, json: parsed.fetch( :json, false ), output: runtime.output )
+			end
+
+			result = warehouse.checkout!( workbench, force: parsed.fetch( :force, false ) )
+			report_workbench( result: result, json: parsed.fetch( :json, false ), output: runtime.output )
+		end
+
+		# Build a Warehouse rooted at the main worktree.
+		# Uses runtime's resolved root and config for remote/branch names.
+		def self.build_warehouse( runtime: )
+			Warehouse.new(
+				path: runtime.send( :main_worktree_root ),
+				main_label: runtime.config.main_branch,
+				bureau_address: runtime.config.git_remote
+			)
+		end
+
+		# Render a workbench result as JSON or human text.
+		# Returns the appropriate exit code.
+		def self.report_workbench( result:, json:, output: )
+			status = result[ :status ]
+			exit_code = case status
+				when "ok" then Runtime::EXIT_OK
+				when "block" then Runtime::EXIT_BLOCK
+				else Runtime::EXIT_ERROR
+			end
+
+			if json
+				output.puts JSON.pretty_generate( result )
+			else
+				case status
+				when "ok"
+					case result[ :command ]
+					when "checkin"
+						output.puts "#{BADGE} Workbench ready: #{result[ :name ]}"
+						output.puts "  path: #{result[ :path ]}"
+						output.puts "  branch: #{result[ :branch ]}"
+					when "checkout"
+						output.puts "#{BADGE} Workbench released: #{result[ :name ]}"
+					end
+				when "error"
+					output.puts "#{BADGE} #{result[ :error ]}"
+					output.puts "  \u2192 #{result[ :recovery ]}" if result[ :recovery ]
+				when "block"
+					output.puts "#{BADGE} #{result[ :error ]}"
+					output.puts "  \u2192 #{result[ :recovery ]}" if result[ :recovery ]
+				end
+			end
+
+			exit_code
+		end
 	end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 4.1.1
+  version: 4.2.0
 platform: ruby
 authors:
 - Hailei Wang
@@ -10,27 +10,7 @@ authors:
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '1.3'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '3'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '1.3'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '3'
+dependencies: []
 description: 'Carson is an autonomous git strategist and repositories governor that
   lives outside the repositories it governs — no Carson-owned artefacts in your repo.
   As strategist, Carson knows when to branch, how to isolate concurrent work, and
@@ -53,11 +33,11 @@ files:
 - RELEASE.md
 - VERSION
 - carson.gemspec
-- config/.github/hooks/command-guard
-- config/.github/hooks/pre-commit
-- config/.github/hooks/pre-merge-commit
-- config/.github/hooks/pre-push
-- config/.github/hooks/prepare-commit-msg
+- config/hooks/command-guard
+- config/hooks/pre-commit
+- config/hooks/pre-merge-commit
+- config/hooks/pre-push
+- config/hooks/prepare-commit-msg
 - exe/carson
 - icon.svg
 - lib/carson.rb
@@ -68,7 +48,6 @@ files:
 - lib/carson/adapters/github.rb
 - lib/carson/adapters/prompt.rb
 - lib/carson/branch.rb
-- lib/carson/cli.rb
 - lib/carson/config.rb
 - lib/carson/courier.rb
 - lib/carson/delivery.rb
@@ -103,8 +82,12 @@ files:
 - lib/carson/runtime/status.rb
 - lib/carson/version.rb
 - lib/carson/warehouse.rb
+- lib/carson/warehouse/bureau.rb
+- lib/carson/warehouse/seal.rb
+- lib/carson/warehouse/workbench.rb
 - lib/carson/waybill.rb
 - lib/carson/worktree.rb
+- lib/cli.rb
 homepage: https://github.com/wanghailei/carson
 licenses:
 - PolyForm-Shield-1.0.0