sxn 0.2.3 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c2adba72c82bfd3b3b92c29bf497cc0c486b16261edc38c103135a7391525a4
-  data.tar.gz: fa079e0580d51496bf4d5f4af242b291847854a1d6dd6f17918730b463bb2c9d
+  metadata.gz: 30ceb6fb94a023b31e9b9c4c4354806a5343b7cefa8f1b43047011f86e3048cf
+  data.tar.gz: 071b888de74d9e284376acf2ed425a5a33ddf329ac01112bc3fbc65acc8dd363
 SHA512:
-  metadata.gz: d8a67b4261fb520b7b64c3c039dcabd5f47f1ae6ca377d1fa4d0a6d0dd9ac2574a83cc0024923273a754527c9e0cba96c75e0923918d1fd997ba62f8f1dd6ae7
-  data.tar.gz: 79218840d95ce17d7a62d40e2f4cfca09498973b784677175ec1cbf67a9ed801074fad18a716dba2a16f89c7499a030b53e3c9c5fbf1b5f412b7cbd0530cd628
+  metadata.gz: 93cb3f85f80ccc13ffcc62662fa86bd0e8b7531105ab08dc49f0213744a858bbaf7fff8823c2d5358617704eeb5aae6f2264ba02f20e14c71003fd8e912136d4
+  data.tar.gz: fc1e076616d354218525d2d8ee6a6454a04dfd5d1db969f7032792c91ec1679605a4d0351573a57cd3b5af64c8d06fdecad1068b51dfd66bc2bea5c92bc52dfc

data/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.5] - 2025-11-30
+
+### Added
+- `sxn enter` command to quickly navigate to current session directory
+- `sxn current enter` subcommand as alternative way to enter session
+- `--path` option for `sxn current` to output only the session path
+- `sxn shell` command to install shell integration (idempotent)
+  - Auto-detects shell type (bash/zsh)
+  - Installs `sxn-enter` function to shell config
+  - Supports `--uninstall` to remove integration
+  - Supports `--shell-type` to specify shell explicitly
+
+## [0.2.4] - 2025-11-30
+
+### Added
+- Interactive worktree wizard after session creation
+  - Prompts to add worktrees with descriptive explanations
+  - Supports adding multiple worktrees in sequence
+  - Explains branch options including remote tracking syntax
+- `--skip-worktree` flag to bypass the wizard when creating sessions
+- `--verbose` flag for worktree debugging with detailed git output
+
+### Changed
+- Sessions now automatically switch to newly created session (no need to run `sxn use` afterwards)
+- Improved project manager to safely handle nil projects configuration
+
+### Fixed
+- Fixed test mocks for verbose parameter in worktree operations
+- Fixed version spec to support semver pre-release format
+
 ## [0.2.3] - 2025-09-16
 
 ### Added
@@ -71,6 +101,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial placeholder release
 - Basic gem structure
 
+[0.2.4]: https://github.com/idl3/sxn/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/idl3/sxn/compare/v0.2.1...v0.2.3
 [0.2.1]: https://github.com/idl3/sxn/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/idl3/sxn/compare/v0.1.0...v0.2.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sxn (0.2.3)
+    sxn (0.2.5)
       async (~> 2.0)
       bcrypt (~> 3.1)
       dry-configurable (~> 1.0)

data/lib/sxn/CLI.rb

@@ -41,8 +41,11 @@ module Sxn
     desc "add SESSION_NAME", "Create a new session (shortcut for 'sxn sessions add')"
     option :description, type: :string, aliases: "-d", desc: "Session description"
     option :linear_task, type: :string, aliases: "-l", desc: "Linear task ID"
+    option :branch, type: :string, aliases: "-b", desc: "Default branch for worktrees"
     def add(session_name)
-      Commands::Sessions.new.add(session_name)
+      cmd = Commands::Sessions.new
+      cmd.options = options
+      cmd.add(session_name)
     rescue Sxn::Error => e
       handle_error(e)
     end
@@ -62,10 +65,102 @@ module Sxn
       handle_error(e)
     end
 
-    desc "current", "Show current session (shortcut for 'sxn sessions current')"
+    desc "current [SUBCOMMAND]", "Show current session (shortcut for 'sxn sessions current')"
     option :verbose, type: :boolean, aliases: "-v", desc: "Show detailed information"
-    def current
-      Commands::Sessions.new.current
+    option :path, type: :boolean, aliases: "-p", desc: "Output only the session path"
+    def current(subcommand = nil)
+      Commands::Sessions.new.current(subcommand)
+    rescue Sxn::Error => e
+      handle_error(e)
+    end
+
+    desc "enter", "Enter current session directory (outputs cd command for shell eval)"
+    long_desc <<-LONGDESC
+      Outputs a cd command to navigate to the current session directory.
+
+      Usage with shell eval:
+        eval "$(sxn enter)"
+
+      Or install shell integration for easier use:
+        sxn shell
+
+      Then simply run:
+        sxn-enter
+    LONGDESC
+    def enter
+      Commands::Sessions.new.enter
+    rescue Sxn::Error => e
+      handle_error(e)
+    end
+
+    desc "up", "Navigate to project root from session (outputs cd command for shell eval)"
+    long_desc <<-LONGDESC
+      Outputs a cd command to navigate to the project root from within a session.
+
+      The project root is determined from the .sxnrc file in the session directory,
+      which points back to the parent .sxn folder.
+
+      Usage with shell eval:
+        eval "$(sxn up)"
+
+      Or install shell integration for easier use:
+        sxn shell
+
+      Then simply run:
+        sxn-up
+    LONGDESC
+    def up
+      require "shellwords"
+
+      session_config = Sxn::Core::SessionConfig.find_from_path(Dir.pwd)
+
+      unless session_config
+        warn "Not in a session directory."
+        warn ""
+        warn "This command works when run from within a session folder."
+        warn "Session folders contain a .sxnrc file that points back to the project."
+        warn ""
+        warn "Tip: Add this function to your shell profile for easier navigation:"
+        warn ""
+        warn "  sxn-up() { eval \"$(sxn up 2>/dev/null)\" || sxn up; }"
+        exit(1)
+      end
+
+      project_root = session_config.project_root
+
+      unless project_root && File.directory?(project_root)
+        warn "Could not determine project root from .sxnrc"
+        warn "parent_sxn_path: #{session_config.parent_sxn_path || "nil"}"
+        exit(1)
+      end
+
+      # Output the cd command for shell integration
+      puts "cd #{Shellwords.escape(project_root)}"
+    rescue Sxn::Error => e
+      handle_error(e)
+    end
+
+    desc "shell", "Install shell integration (sxn-enter function)"
+    option :shell_type, type: :string, enum: %w[bash zsh auto], default: "auto",
+                        desc: "Shell type (bash, zsh, or auto-detect)"
+    option :uninstall, type: :boolean, default: false, desc: "Remove shell integration"
+    long_desc <<-LONGDESC
+      Installs shell integration to your shell configuration file (.zshrc or .bashrc).
+
+      This adds the sxn-enter function which allows you to quickly navigate
+      to your current session directory.
+
+      The installation is idempotent - running it multiple times will not
+      add duplicate entries.
+
+      Examples:
+        sxn shell                   # Auto-detect shell and install
+        sxn shell --shell-type=zsh  # Install for zsh specifically
+        sxn shell --uninstall       # Remove shell integration
+    LONGDESC
+    map "shell" => :install_shell_wrapper
+    def install_shell_wrapper
+      Commands::Init.new.invoke(:install_shell, [], options)
     rescue Sxn::Error => e
       handle_error(e)
     end

data/lib/sxn/commands/init.rb

@@ -8,6 +8,34 @@ module Sxn
     class Init < Thor
       include Thor::Actions
 
+      # Shell integration marker - used to identify sxn shell functions
+      SHELL_MARKER = "# sxn shell integration"
+      SHELL_MARKER_END = "# end sxn shell integration"
+
+      # Shell function that gets installed
+      SHELL_FUNCTION = <<~SHELL.freeze
+        #{SHELL_MARKER}
+        sxn-enter() {
+          local cmd
+          cmd="$(sxn enter 2>/dev/null)"
+          if [ $? -eq 0 ] && [ -n "$cmd" ]; then
+            eval "$cmd"
+          else
+            sxn enter
+          fi
+        }
+        sxn-up() {
+          local cmd
+          cmd="$(sxn up 2>/dev/null)"
+          if [ $? -eq 0 ] && [ -n "$cmd" ]; then
+            eval "$cmd"
+          else
+            sxn up
+          fi
+        }
+        #{SHELL_MARKER_END}
+      SHELL
+
       desc "init [FOLDER]", "Initialize sxn in a project folder"
       option :force, type: :boolean, desc: "Force initialization even if already initialized"
       option :auto_detect, type: :boolean, default: true, desc: "Automatically detect and register projects"
@@ -55,8 +83,116 @@ module Sxn
         end
       end
 
+      desc "install_shell", "Install shell integration (sxn-enter function)"
+      option :shell_type, type: :string, enum: %w[bash zsh auto], default: "auto",
+                          desc: "Shell type (bash, zsh, or auto-detect)"
+      option :uninstall, type: :boolean, default: false, desc: "Remove shell integration"
+      def install_shell
+        @ui.section("Shell Integration")
+
+        shell_type = detect_shell_type
+        rc_file = shell_rc_file(shell_type)
+
+        unless rc_file
+          @ui.error("Could not determine shell configuration file")
+          @ui.info("Supported shells: bash, zsh")
+          exit(1)
+        end
+
+        if options[:uninstall]
+          uninstall_shell_integration(rc_file, shell_type)
+        else
+          install_shell_integration(rc_file, shell_type)
+        end
+      end
+
       private
 
+      def detect_shell_type
+        shell_opt = options[:shell_type] || options[:shell] || "auto"
+        return shell_opt unless shell_opt == "auto"
+
+        # Check SHELL environment variable
+        current_shell = ENV.fetch("SHELL", "")
+        if current_shell.include?("zsh")
+          "zsh"
+        elsif current_shell.include?("bash")
+          "bash"
+        else
+          # Default to bash
+          "bash"
+        end
+      end
+
+      def shell_rc_file(shell_type)
+        home = Dir.home
+        case shell_type
+        when "zsh"
+          File.join(home, ".zshrc")
+        when "bash"
+          # Prefer .bashrc, fall back to .bash_profile on macOS
+          bashrc = File.join(home, ".bashrc")
+          bash_profile = File.join(home, ".bash_profile")
+          File.exist?(bashrc) ? bashrc : bash_profile
+        end
+      end
+
+      def shell_integration_installed?(rc_file)
+        return false unless File.exist?(rc_file)
+
+        content = File.read(rc_file)
+        content.include?(SHELL_MARKER)
+      end
+
+      def install_shell_integration(rc_file, _shell_type)
+        if shell_integration_installed?(rc_file)
+          @ui.info("Shell integration already installed in #{rc_file}")
+          @ui.info("Use --uninstall to remove it first if you want to reinstall")
+          return
+        end
+
+        # Ensure rc file exists
+        FileUtils.touch(rc_file) unless File.exist?(rc_file)
+
+        # Append shell function
+        File.open(rc_file, "a") do |f|
+          f.puts "" # Add blank line before
+          f.puts SHELL_FUNCTION
+        end
+
+        @ui.success("Installed shell integration to #{rc_file}")
+        @ui.newline
+        @ui.info("The following functions were added:")
+        @ui.newline
+        puts "  sxn-enter  - Navigate to current session directory"
+        puts "  sxn-up     - Navigate to project root from session"
+        @ui.newline
+        @ui.recovery_suggestion("Run 'source #{rc_file}' or restart your shell to use them")
+      end
+
+      def uninstall_shell_integration(rc_file, _shell_type)
+        unless File.exist?(rc_file)
+          @ui.info("Shell configuration file not found: #{rc_file}")
+          return
+        end
+
+        unless shell_integration_installed?(rc_file)
+          @ui.info("Shell integration not installed in #{rc_file}")
+          return
+        end
+
+        # Read file and remove sxn block
+        content = File.read(rc_file)
+        # Remove the block between markers (including blank line before)
+        pattern = /\n?#{Regexp.escape(SHELL_MARKER)}.*?#{Regexp.escape(SHELL_MARKER_END)}\n?/m
+        new_content = content.gsub(pattern, "\n")
+
+        File.write(rc_file, new_content)
+
+        @ui.success("Removed shell integration from #{rc_file}")
+        @ui.recovery_suggestion("Run 'source #{rc_file}' or restart your shell")
+      end
+
       def determine_sessions_folder(folder)
         return folder if folder && !options[:quiet]
 

data/lib/sxn/commands/sessions.rb

@@ -2,6 +2,7 @@
 
 require "thor"
 require "time"
+require "shellwords"
 
 module Sxn
   module Commands
@@ -16,12 +17,16 @@ module Sxn
         @table = Sxn::UI::Table.new
         @config_manager = Sxn::Core::ConfigManager.new
         @session_manager = Sxn::Core::SessionManager.new(@config_manager)
+        @project_manager = Sxn::Core::ProjectManager.new(@config_manager)
+        @worktree_manager = Sxn::Core::WorktreeManager.new(@config_manager, @session_manager)
       end
 
       desc "add NAME", "Create a new session"
       option :description, type: :string, aliases: "-d", desc: "Session description"
       option :linear_task, type: :string, aliases: "-l", desc: "Linear task ID"
+      option :branch, type: :string, aliases: "-b", desc: "Default branch for worktrees"
       option :activate, type: :boolean, default: true, desc: "Activate session after creation"
+      option :skip_worktree, type: :boolean, default: false, desc: "Skip worktree creation wizard"
 
       def add(name = nil)
         ensure_initialized!
@@ -32,24 +37,31 @@ module Sxn
           name = @prompt.session_name(existing_sessions: existing_sessions)
         end
 
+        # Get default branch - use provided option, or prompt interactively
+        default_branch = options[:branch]
+        default_branch ||= @prompt.default_branch(session_name: name)
+
         begin
           @ui.progress_start("Creating session '#{name}'")
 
           session = @session_manager.create_session(
             name,
             description: options[:description],
-            linear_task: options[:linear_task]
+            linear_task: options[:linear_task],
+            default_branch: default_branch
           )
 
           @ui.progress_done
           @ui.success("Created session '#{name}'")
 
-          if options[:activate]
-            @session_manager.use_session(name)
-            @ui.success("Activated session '#{name}'")
-          end
+          # Always activate the new session (this is the expected behavior)
+          @session_manager.use_session(name)
+          @ui.success("Switched to session '#{name}'")
 
           display_session_info(session)
+
+          # Offer to add a worktree unless skipped
+          offer_worktree_wizard(name) unless options[:skip_worktree]
         rescue Sxn::Error => e
           @ui.progress_failed
           @ui.error(e.message)
@@ -168,12 +180,23 @@ module Sxn
         end
       end
 
-      desc "current", "Show current session"
+      desc "current [SUBCOMMAND]", "Show current session or enter its directory"
       option :verbose, type: :boolean, aliases: "-v", desc: "Show detailed information"
+      option :path, type: :boolean, aliases: "-p", desc: "Output only the session path (for shell integration)"
 
-      def current
+      def current(subcommand = nil)
         ensure_initialized!
 
+        # Handle 'sxn current enter' subcommand
+        if subcommand == "enter"
+          enter_session
+          return
+        elsif subcommand
+          @ui.error("Unknown subcommand: #{subcommand}")
+          @ui.info("Available: enter")
+          exit(1)
+        end
+
         begin
           session = @session_manager.current_session
 
@@ -183,6 +206,12 @@ module Sxn
             return
           end
 
+          # If --path flag, just output the path for shell integration
+          if options[:path]
+            puts session[:path]
+            return
+          end
+
           @ui.section("Current Session")
           display_session_info(session, verbose: options[:verbose])
         rescue Sxn::Error => e
@@ -191,6 +220,11 @@ module Sxn
         end
       end
 
+      desc "enter", "Enter the current session directory (outputs cd command)"
+      def enter
+        enter_session
+      end
+
       desc "archive NAME", "Archive a session"
       def archive(name = nil)
         ensure_initialized!
@@ -256,6 +290,7 @@ module Sxn
         @ui.key_value("Name", session[:name] || "Unknown")
         @ui.key_value("Status", (session[:status] || "unknown").capitalize)
         @ui.key_value("Path", session[:path] || "Unknown")
+        @ui.key_value("Default Branch", session[:default_branch]) if session[:default_branch]
 
         @ui.key_value("Description", session[:description]) if session[:description]
 
@@ -310,6 +345,161 @@ module Sxn
       rescue ArgumentError
         timestamp # Return original if parsing fails
       end
+
+      def offer_worktree_wizard(session_name)
+        @ui.newline
+        @ui.section("Add Worktree")
+
+        # Check if there are any projects configured
+        projects = @project_manager.list_projects
+        if projects.empty?
+          @ui.info("No projects configured yet.")
+          @ui.recovery_suggestion("Add projects with 'sxn projects add <name> <path>'")
+          return
+        end
+
+        # Ask if user wants to add a worktree
+        return unless @prompt.ask_yes_no("Would you like to add a worktree to this session?", default: true)
+
+        # Step 1: Select project with descriptions
+        @ui.newline
+        @ui.info("A worktree is a linked copy of a project that allows you to work on a branch")
+        @ui.info("without affecting the main repository. Select which project to add:")
+        @ui.newline
+
+        project_choices = projects.map do |p|
+          {
+            name: "#{p[:name]} (#{p[:type]}) - #{p[:path]}",
+            value: p[:name]
+          }
+        end
+        project_name = @prompt.select("Select project:", project_choices)
+
+        # Step 2: Get branch name with explanation
+        # Get session's default branch for the default value
+        session = @session_manager.get_session(session_name)
+        default_branch_for_worktree = session[:default_branch] || session_name
+
+        @ui.newline
+        @ui.info("Enter the branch name for this worktree.")
+        @ui.info("This can be an existing branch or a new one to create.")
+        @ui.info("Tip: Use 'remote:<branch>' to track a remote branch (e.g., 'remote:origin/main')")
+        @ui.newline
+
+        branch = @prompt.branch_name(
+          "Branch name:",
+          default: default_branch_for_worktree
+        )
+
+        # Step 3: Create the worktree
+        create_worktree_for_session(project_name, branch, session_name)
+
+        # Offer to add more worktrees
+        add_more_worktrees(session_name)
+      end
+
+      def create_worktree_for_session(project_name, branch, session_name)
+        @ui.newline
+        @ui.progress_start("Creating worktree for #{project_name}")
+
+        worktree = @worktree_manager.add_worktree(
+          project_name,
+          branch,
+          session_name: session_name
+        )
+
+        @ui.progress_done
+        @ui.success("Created worktree for #{project_name}")
+
+        display_worktree_info(worktree)
+
+        # Apply rules
+        apply_project_rules(project_name, session_name)
+      rescue Sxn::Error => e
+        @ui.progress_failed
+        @ui.error(e.message)
+        @ui.recovery_suggestion("You can try again with 'sxn worktree add #{project_name}'")
+      end
+
+      def add_more_worktrees(session_name)
+        projects = @project_manager.list_projects
+        return if projects.empty?
+
+        # Get session's default branch for the default value
+        session = @session_manager.get_session(session_name)
+        default_branch_for_worktree = session[:default_branch] || session_name
+
+        while @prompt.ask_yes_no("Would you like to add another worktree?", default: false)
+          @ui.newline
+
+          project_choices = projects.map do |p|
+            {
+              name: "#{p[:name]} (#{p[:type]}) - #{p[:path]}",
+              value: p[:name]
+            }
+          end
+          project_name = @prompt.select("Select project:", project_choices)
+
+          branch = @prompt.branch_name(
+            "Branch name:",
+            default: default_branch_for_worktree
+          )
+
+          create_worktree_for_session(project_name, branch, session_name)
+        end
+      end
+
+      def display_worktree_info(worktree)
+        @ui.newline
+        @ui.key_value("Project", worktree[:project])
+        @ui.key_value("Branch", worktree[:branch])
+        @ui.key_value("Path", worktree[:path])
+      end
+
+      def enter_session
+        session = @session_manager.current_session
+
+        if session.nil?
+          # When no session, provide helpful guidance instead of just a cd command
+          warn "No active session. Use 'sxn use <session>' to activate a session first."
+          warn ""
+          warn "Tip: Add this function to your shell profile for easier navigation:"
+          warn ""
+          warn "  sxn-enter() { eval \"$(sxn enter 2>/dev/null)\" || sxn enter; }"
+          warn ""
+          exit(1)
+        end
+
+        session_path = session[:path]
+
+        unless session_path && File.directory?(session_path)
+          warn "Session directory does not exist: #{session_path || "nil"}"
+          exit(1)
+        end
+
+        # Output the cd command for shell integration
+        # Users can use: eval "$(sxn enter)" or the sxn-enter shell function
+        puts "cd #{Shellwords.escape(session_path)}"
+      rescue Sxn::Error => e
+        warn e.message
+        exit(e.exit_code)
+      end
+
+      def apply_project_rules(project_name, session_name)
+        rules_manager = Sxn::Core::RulesManager.new(@config_manager, @project_manager)
+
+        @ui.progress_start("Applying rules for #{project_name}")
+        results = rules_manager.apply_rules(project_name, session_name)
+        @ui.progress_done
+
+        if results[:success]
+          @ui.success("Applied #{results[:applied_count]} rules") if results[:applied_count].positive?
+        else
+          @ui.warning("Some rules failed to apply")
+        end
+      rescue StandardError => e
+        @ui.warning("Could not apply rules: #{e.message}")
+      end
     end
   end
 end

data/lib/sxn/commands/worktrees.rb

@@ -41,6 +41,7 @@ module Sxn
       option :session, type: :string, aliases: "-s", desc: "Target session (defaults to current)"
       option :apply_rules, type: :boolean, default: true, desc: "Apply project rules after creation"
       option :interactive, type: :boolean, aliases: "-i", desc: "Interactive mode"
+      option :verbose, type: :boolean, aliases: "-v", desc: "Show detailed output for debugging"
 
       def add(project_name = nil, branch = nil)
         ensure_initialized!
@@ -66,12 +67,16 @@ module Sxn
         end
 
         begin
+          # Enable debug mode if verbose flag is set
+          ENV["SXN_DEBUG"] = "true" if options[:verbose]
+
           @ui.progress_start("Creating worktree for #{project_name}")
 
           worktree = @worktree_manager.add_worktree(
             project_name,
             branch,
-            session_name: session_name
+            session_name: session_name,
+            verbose: options[:verbose]
           )
 
           @ui.progress_done
@@ -84,7 +89,18 @@ module Sxn
         rescue Sxn::Error => e
           @ui.progress_failed
           @ui.error(e.message)
+
+          if options[:verbose] && e.respond_to?(:details)
+            @ui.newline
+            @ui.subsection("Debug Information")
+            @ui.info(e.details)
+          elsif !options[:verbose]
+            @ui.recovery_suggestion("Run with --verbose flag for more details")
+          end
+
           exit(e.exit_code)
+        ensure
+          ENV.delete("SXN_DEBUG") if options[:verbose]
         end
       end
 

data/lib/sxn/core/config_manager.rb

@@ -62,6 +62,10 @@ module Sxn
         @sessions_folder || (load_config && @sessions_folder)
       end
 
+      def sxn_folder_path
+        File.dirname(@config_path)
+      end
+
       def add_project(name, path, type: nil, default_branch: nil)
         config = load_config_file
         config["projects"] ||= {}

data/lib/sxn/core/project_manager.rb

@@ -193,9 +193,26 @@ module Sxn
 
         # Get project-specific rules from config
         config = @config_manager.get_config
-        project_config = config.projects[name]
 
-        rules = project_config&.dig("rules") || {}
+        # Handle both OpenStruct and Hash for projects config
+        projects = config.projects
+        project_config = if projects.is_a?(OpenStruct)
+                           projects.to_h[name.to_sym] || projects.to_h[name]
+                         elsif projects.is_a?(Hash)
+                           projects[name]
+                         end
+
+        # Extract rules, handling both OpenStruct and Hash
+        rules = if project_config.is_a?(OpenStruct)
+                  project_config.to_h[:rules] || project_config.to_h["rules"] || {}
+                elsif project_config.is_a?(Hash)
+                  project_config["rules"] || project_config[:rules] || {}
+                else
+                  {}
+                end
+
+        # Convert OpenStruct rules to hash if needed
+        rules = rules.to_h if rules.is_a?(OpenStruct)
 
         # Add default rules based on project type
         default_rules = get_default_rules_for_type(project[:type])

data/lib/sxn/core/rules_manager.rb

@@ -87,11 +87,69 @@ module Sxn
                 "No worktree found for project '#{project_name}' in session '#{session_name}'"
         end
 
-        # Get project rules
+        # Get project rules (format: { "copy_files" => [...], "setup_commands" => [...] })
         rules = @project_manager.get_project_rules(project_name)
 
-        # Apply rules to worktree
-        @rules_engine.apply_rules(rules)
+        # Transform rules to RulesEngine format and apply
+        apply_rules_to_worktree(project, worktree, rules)
+      end
+
+      def apply_rules_to_worktree(project, worktree, rules)
+        project_path = project[:path]
+        worktree_path = worktree[:path]
+
+        # Ensure paths exist
+        raise Sxn::InvalidProjectPathError, "Project path does not exist: #{project_path}" unless File.directory?(project_path)
+        raise Sxn::WorktreeNotFoundError, "Worktree path does not exist: #{worktree_path}" unless File.directory?(worktree_path)
+
+        applied_count = 0
+        errors = []
+
+        # Apply copy_files rules
+        rules["copy_files"]&.each do |rule_config|
+          apply_copy_file_rule(project_path, worktree_path, rule_config)
+          applied_count += 1
+        rescue StandardError => e
+          errors << "copy_files: #{e.message}"
+        end
+
+        # Apply setup_commands rules (skip for now as they can be slow)
+        # Users can run these manually if needed
+
+        {
+          success: errors.empty?,
+          applied_count: applied_count,
+          errors: errors
+        }
+      end
+
+      def apply_copy_file_rule(project_path, worktree_path, rule_config)
+        source_pattern = rule_config["source"]
+        strategy = rule_config["strategy"] || "copy"
+
+        # Handle glob patterns
+        source_files = if source_pattern.include?("*")
+                         Dir.glob(File.join(project_path, source_pattern))
+                       else
+                         single_file = File.join(project_path, source_pattern)
+                         File.exist?(single_file) ? [single_file] : []
+                       end
+
+        source_files.each do |file_path|
+          # Calculate relative path from project root
+          relative_path = file_path.sub("#{project_path}/", "")
+          dest_file = File.join(worktree_path, relative_path)
+
+          # Create destination directory if needed
+          FileUtils.mkdir_p(File.dirname(dest_file))
+
+          case strategy
+          when "copy"
+            FileUtils.cp(file_path, dest_file)
+          when "symlink"
+            FileUtils.ln_sf(file_path, dest_file)
+          end
+        end
       end
 
       def validate_rules(project_name)

data/lib/sxn/core/session_config.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Sxn
+  module Core
+    # Manages .sxnrc session configuration files
+    class SessionConfig
+      FILENAME = ".sxnrc"
+
+      attr_reader :session_path, :config_path
+
+      def initialize(session_path)
+        @session_path = session_path
+        @config_path = File.join(session_path, FILENAME)
+      end
+
+      def create(parent_sxn_path:, default_branch:, session_name:)
+        config = {
+          "version" => 1,
+          "parent_sxn_path" => parent_sxn_path,
+          "default_branch" => default_branch,
+          "session_name" => session_name,
+          "created_at" => Time.now.iso8601
+        }
+        File.write(@config_path, YAML.dump(config))
+        config
+      end
+
+      def exists?
+        File.exist?(@config_path)
+      end
+
+      def read
+        return nil unless exists?
+
+        YAML.safe_load_file(@config_path) || {}
+      rescue Psych::SyntaxError
+        nil
+      end
+
+      def parent_sxn_path
+        read&.dig("parent_sxn_path")
+      end
+
+      def default_branch
+        read&.dig("default_branch")
+      end
+
+      def session_name
+        read&.dig("session_name")
+      end
+
+      def project_root
+        parent_path = parent_sxn_path
+        return nil unless parent_path
+
+        # parent_sxn_path points to .sxn folder, project root is its parent
+        File.dirname(parent_path)
+      end
+
+      def update(updates)
+        config = read || {}
+        updates.each do |key, value|
+          config[key.to_s] = value
+        end
+        File.write(@config_path, YAML.dump(config))
+        config
+      end
+
+      # Class method: Find .sxnrc by walking up directory tree
+      def self.find_from_path(start_path)
+        current = File.expand_path(start_path)
+
+        while current != "/" && current != File.dirname(current)
+          config_path = File.join(current, FILENAME)
+          return new(current) if File.exist?(config_path)
+
+          current = File.dirname(current)
+        end
+
+        nil
+      end
+
+      # Class method: Check if path is within a session
+      def self.in_session?(path = Dir.pwd)
+        !find_from_path(path).nil?
+      end
+    end
+  end
+end

data/lib/sxn/core/session_manager.rb

@@ -13,7 +13,7 @@ module Sxn
         @database = initialize_database
       end
 
-      def create_session(name, description: nil, linear_task: nil)
+      def create_session(name, description: nil, linear_task: nil, default_branch: nil)
         validate_session_name!(name)
         ensure_sessions_folder_exists!
 
@@ -21,10 +21,19 @@ module Sxn
 
         session_id = SecureRandom.uuid
         session_path = File.join(@config_manager.sessions_folder_path, name)
+        branch = default_branch || name
 
         # Create session directory
         FileUtils.mkdir_p(session_path)
 
+        # Create .sxnrc configuration file
+        session_config = SessionConfig.new(session_path)
+        session_config.create(
+          parent_sxn_path: @config_manager.sxn_folder_path,
+          default_branch: branch,
+          session_name: name
+        )
+
         # Create session record
         session_data = {
           id: session_id,
@@ -35,6 +44,7 @@ module Sxn
           status: "active",
           description: description,
           linear_task: linear_task,
+          default_branch: branch,
           projects: [],
           worktrees: {}
         }
@@ -162,6 +172,15 @@ module Sxn
         session_data[:worktrees] || {}
       end
 
+      def get_session_default_branch(session_name)
+        session = get_session(session_name)
+        return nil unless session
+
+        # Read from .sxnrc file in session directory
+        session_config = SessionConfig.new(session[:path])
+        session_config.default_branch
+      end
+
       def archive_session(name)
         update_session_status_by_name(name, "archived")
         true
@@ -224,6 +243,7 @@ module Sxn
           status: db_row[:status],
           description: metadata["description"] || db_row[:description],
           linear_task: metadata["linear_task"] || db_row[:linear_task],
+          default_branch: metadata["default_branch"] || db_row[:default_branch],
           # Support both metadata and database columns for backward compatibility
           projects: db_row[:projects] || metadata["projects"] || [],
           worktrees: db_row[:worktrees] || metadata["worktrees"] || {}

data/lib/sxn/core/worktree_manager.rb

@@ -14,7 +14,7 @@ module Sxn
         @project_manager = ProjectManager.new(@config_manager)
       end
 
-      def add_worktree(project_name, branch = nil, session_name: nil)
+      def add_worktree(project_name, branch = nil, session_name: nil, verbose: false)
         # Use current session if not specified
         session_name ||= @config_manager.current_session
         raise Sxn::NoActiveSessionError, "No active session. Use 'sxn use <session>' first." unless session_name
@@ -26,10 +26,12 @@ module Sxn
         raise Sxn::ProjectNotFoundError, "Project '#{project_name}' not found" unless project
 
         # Determine branch name
-        # If no branch specified, use session name as the branch name
+        # If no branch specified, use session's default branch from .sxnrc, then fallback to session name
         # If branch starts with "remote:", handle remote branch tracking
         if branch.nil?
-          branch = session_name
+          session_config = SessionConfig.new(session[:path])
+          branch = session_config.default_branch if session_config.exists?
+          branch ||= session_name
         elsif branch.start_with?("remote:")
           remote_branch = branch.sub("remote:", "")
           # Fetch the remote branch first
@@ -67,7 +69,7 @@ module Sxn
           handle_orphaned_worktree(project[:path], worktree_path)
 
           # Create the worktree
-          create_git_worktree(project[:path], worktree_path, branch)
+          create_git_worktree(project[:path], worktree_path, branch, verbose: verbose)
 
           # Register worktree with session
           @session_manager.add_worktree_to_session(session_name, project_name, worktree_path, branch)
@@ -81,6 +83,11 @@ module Sxn
         rescue StandardError => e
           # Clean up on failure
           FileUtils.rm_rf(worktree_path)
+
+          # If it's already our error with details, re-raise it
+          raise e if e.is_a?(Sxn::WorktreeCreationError)
+
+          # Otherwise wrap it
           raise Sxn::WorktreeCreationError, "Failed to create worktree: #{e.message}"
         end
       end
@@ -237,7 +244,7 @@ module Sxn
         end
       end
 
-      def create_git_worktree(project_path, worktree_path, branch)
+      def create_git_worktree(project_path, worktree_path, branch, verbose: false)
         Dir.chdir(project_path) do
           # Check if branch exists
           branch_exists = system("git show-ref --verify --quiet refs/heads/#{Shellwords.escape(branch)}",
@@ -274,15 +281,35 @@ module Sxn
               error_msg = error_msg.lines.grep(/fatal:/).first&.strip || error_msg
             end
 
-            if ENV["SXN_DEBUG"]
+            details = []
+            details << "Command: #{cmd.join(" ")}"
+            details << "Working directory: #{project_path}"
+            details << "Target path: #{worktree_path}"
+            details << "Branch: #{branch}"
+            details << ""
+            details << "Git output:"
+            details << "STDOUT: #{stdout.strip.empty? ? "(empty)" : stdout}"
+            details << "STDERR: #{stderr.strip.empty? ? "(empty)" : stderr}"
+            details << "Exit status: #{status.exitstatus}"
+
+            # Check for common issues
+            if !File.directory?(project_path)
+              details << "\n⚠️  Project directory does not exist: #{project_path}"
+            elsif !File.directory?(File.join(project_path, ".git"))
+              details << "\n⚠️  Not a git repository: #{project_path}"
+              details << "    This might be a git submodule. Try:"
+              details << "    1. Ensure the project path points to the submodule directory"
+              details << "    2. Check if 'git submodule update --init' has been run"
+            end
+
+            details << "\n⚠️  Target path already exists: #{worktree_path}" if File.exist?(worktree_path)
+
+            if ENV["SXN_DEBUG"] || verbose
               puts "[DEBUG] Git worktree command failed:"
-              puts "  Command: #{cmd.join(" ")}"
-              puts "  Directory: #{project_path}"
-              puts "  STDOUT: #{stdout}"
-              puts "  STDERR: #{stderr}"
+              details.each { |line| puts "  #{line}" }
             end
 
-            raise error_msg
+            raise Sxn::WorktreeCreationError.new(error_msg, details: details.join("\n"))
           end
         end
       end

data/lib/sxn/core.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "core/config_manager"
+require_relative "core/session_config"
 require_relative "core/session_manager"
 require_relative "core/project_manager"
 require_relative "core/worktree_manager"

data/lib/sxn/errors.rb

@@ -37,7 +37,16 @@ module Sxn
   class WorktreeError < GitError; end
   class WorktreeExistsError < WorktreeError; end
   class WorktreeNotFoundError < WorktreeError; end
-  class WorktreeCreationError < WorktreeError; end
+
+  class WorktreeCreationError < WorktreeError
+    attr_reader :details
+
+    def initialize(message, details: nil)
+      super(message)
+      @details = details
+    end
+  end
+
   class WorktreeRemovalError < WorktreeError; end
   class BranchError < GitError; end
 

data/lib/sxn/ui/prompt.rb

@@ -68,6 +68,10 @@ module Sxn
         end
       end
 
+      def default_branch(session_name:)
+        branch_name("Default branch for worktrees:", default: session_name)
+      end
+
       def confirm_deletion(item_name, item_type = "item")
         ask_yes_no("Are you sure you want to delete #{item_type} '#{item_name}'? This action cannot be undone.",
                    default: false)

data/lib/sxn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sxn
-  VERSION = "0.2.3"
+  VERSION = "0.2.5"
 end

data/sxn.gemspec

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "lib/sxn/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "sxn"
+  spec.version       = Sxn::VERSION
+  spec.authors       = ["Ernest Sim"]
+  spec.email         = ["ernest.codes@gmail.com"]
+
+  spec.summary       = "Session management for multi-repository development"
+  spec.description   = "Sxn simplifies git worktree management with intelligent project rules and secure automation"
+  spec.homepage      = "https://github.com/idl3/sxn"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) ||
+        f.match(%r{\A(?:(?:test|spec|features)/|\.(?:git|travis|circleci)|appveyor)}) ||
+        f.match(/\.db-(?:shm|wal)\z/) || # Exclude SQLite temp files
+        f.match(/\.gem\z/) # Exclude gem files
+    end
+  end
+
+  spec.bindir        = "bin"
+  spec.executables   = spec.files.grep(%r{\Abin/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Core CLI dependencies
+  spec.add_dependency "pastel", "~> 0.8"                  # Terminal colors
+  spec.add_dependency "thor", "~> 1.3"                    # CLI framework
+  spec.add_dependency "tty-progressbar", "~> 0.18"        # Progress bars
+  spec.add_dependency "tty-prompt", "~> 0.23"             # Interactive prompts
+  spec.add_dependency "tty-table", "~> 0.12"              # Table formatting
+
+  # Configuration and data management
+  spec.add_dependency "dry-configurable", "~> 1.0"       # Configuration management
+  spec.add_dependency "sqlite3", "~> 1.6"                # Session database
+  spec.add_dependency "zeitwerk", "~> 2.6"               # Code loading
+
+  # Template engine (secure, sandboxed)
+  spec.add_dependency "liquid", "~> 5.4" # Safe template processing
+
+  # MCP server dependencies
+  spec.add_dependency "async", "~> 2.0"                  # Async operations
+  spec.add_dependency "json-schema", "~> 4.0"            # Schema validation
+
+  # Security and encryption
+  spec.add_dependency "bcrypt", "~> 3.1"                 # Password hashing
+  spec.add_dependency "openssl", ">= 3.0"                # Encryption support
+  spec.add_dependency "ostruct"                          # OpenStruct for Ruby 3.5+ compatibility
+
+  # File system operations
+  spec.add_dependency "listen", "~> 3.8"                 # File watching for config cache
+  spec.add_dependency "parallel", "~> 1.23"              # Parallel execution
+
+  # Development dependencies
+  spec.add_development_dependency "aruba", "~> 2.1" # CLI testing
+  spec.add_development_dependency "benchmark" # Benchmark for Ruby 3.5+ compatibility
+  spec.add_development_dependency "benchmark-ips", "~> 2.12" # Performance benchmarking
+  spec.add_development_dependency "bundler", "~> 2.4"
+  spec.add_development_dependency "climate_control", "~> 1.2" # Environment variable testing
+  spec.add_development_dependency "faker", "~> 3.2" # Test data generation
+  spec.add_development_dependency "memory_profiler", "~> 1.0" # Memory profiling
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rubocop", "~> 1.50" # Code linting
+  spec.add_development_dependency "rubocop-performance", "~> 1.16"
+  spec.add_development_dependency "rubocop-rspec", "~> 2.19"
+  spec.add_development_dependency "simplecov", "~> 0.22" # Code coverage
+  spec.add_development_dependency "vcr", "~> 6.2" # HTTP interaction recording
+  spec.add_development_dependency "webmock", "~> 3.19" # HTTP mocking for MCP tests
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sxn
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.5
 platform: ruby
 authors:
 - Ernest Sim
@@ -518,6 +518,7 @@ files:
 - lib/sxn/core/config_manager.rb
 - lib/sxn/core/project_manager.rb
 - lib/sxn/core/rules_manager.rb
+- lib/sxn/core/session_config.rb
 - lib/sxn/core/session_manager.rb
 - lib/sxn/core/worktree_manager.rb
 - lib/sxn/database.rb
@@ -610,6 +611,7 @@ files:
 - sig/sxn/ui/prompt.rbs
 - sig/sxn/ui/table.rbs
 - sig/sxn/version.rbs
+- sxn.gemspec
 homepage: https://github.com/idl3/sxn
 licenses:
 - MIT