sxn 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce0aa4443b381e4f3e6edb7f5131f5e7749ef37d76c751f6fd9119e12c6e6097
-  data.tar.gz: 4458f97e8982e5dffad49023ad7dc918680f4507a69fe4a18c1c54a0c98a154a
+  metadata.gz: 6c2adba72c82bfd3b3b92c29bf497cc0c486b16261edc38c103135a7391525a4
+  data.tar.gz: fa079e0580d51496bf4d5f4af242b291847854a1d6dd6f17918730b463bb2c9d
 SHA512:
-  metadata.gz: 7bb89bc46f2961d3041c685e0553819e7a32aea6f92f27be4c5f512df1900d3fd7fa85147b49c51bf813d625495b20792ae7ee0a0124aa44c3fff94359316b65
-  data.tar.gz: aefb73b0c8072b5a234d6c4979b43de448dcc39c4521c970acf1e5a050b38adf408ce0a0e0f9136a8cdc853ce75ae3878e5df54df5e5f8d0e259a260cedde981
+  metadata.gz: d8a67b4261fb520b7b64c3c039dcabd5f47f1ae6ca377d1fa4d0a6d0dd9ac2574a83cc0024923273a754527c9e0cba96c75e0923918d1fd997ba62f8f1dd6ae7
+  data.tar.gz: 79218840d95ce17d7a62d40e2f4cfca09498973b784677175ec1cbf67a9ed801074fad18a716dba2a16f89c7499a030b53e3c9c5fbf1b5f412b7cbd0530cd628

data/.parallel_rspec

@@ -0,0 +1,2 @@
+--format progress
+--format ParallelTests::RSpec::RuntimeLogger --out tmp/parallel_runtime_rspec.log

data/.parallel_rspec_options

@@ -0,0 +1,3 @@
+spec/unit
+spec/integration
+spec/performance

data/.rspec

@@ -1,4 +1,5 @@
 --require spec_helper
 --color
 --format documentation
---order random
+--order random
+--pattern '**/*_spec.rb'

data/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.3] - 2025-09-16
+
+### Added
+- Smart branch defaults: worktrees now use session name as default branch
+- Remote branch tracking with `remote:` prefix syntax (e.g., `sxn worktree add project remote:origin/feature`)
+- Automatic orphaned worktree recovery and cleanup
+- Enhanced error messages with actionable suggestions
+
+### Changed
+- Improved worktree creation logic to handle existing/orphaned states
+- Better error handling for remote branch operations
+- Updated CLI documentation with new branch options
+
+### Fixed
+- Orphaned worktree cleanup now works for both existing and missing directories
+- Worktree creation properly handles branch conflicts
+- Test suite compatibility with new worktree features
+
 ## [0.2.1] - 2025-01-20
 
 ### Fixed
@@ -53,5 +71,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial placeholder release
 - Basic gem structure
 
+[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
 [0.1.0]: https://github.com/idl3/sxn/releases/tag/v0.1.0

data/Gemfile

@@ -10,8 +10,9 @@ gem "rake", "~> 13.0"
 
 gem "rubocop", "~> 1.21"
 
-# Test coverage
+# Test coverage and parallel testing
 group :test do
+  gem "parallel_tests", "~> 4.0"
   gem "simplecov", "~> 0.22", require: false
   gem "simplecov-console", require: false
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sxn (0.2.0)
+    sxn (0.2.3)
       async (~> 2.0)
       bcrypt (~> 3.1)
       dry-configurable (~> 1.0)
@@ -146,6 +146,8 @@ GEM
     openssl (3.3.0)
     ostruct (0.6.3)
     parallel (1.27.0)
+    parallel_tests (4.10.1)
+      parallel
     parser (3.3.9.0)
       ast (~> 2.4.1)
       racc
@@ -311,6 +313,7 @@ DEPENDENCIES
   faker (~> 3.2)
   irb
   memory_profiler (~> 1.0)
+  parallel_tests (~> 4.0)
   rake (~> 13.0)
   rbs (~> 3.4)
   rbs_rails (~> 0.12)

data/README.md

@@ -1,10 +1,10 @@
-# Sxn
+# sxn
 
 [![CI](https://github.com/idl3/sxn/actions/workflows/ci.yml/badge.svg)](https://github.com/idl3/sxn/actions/workflows/ci.yml)
 [![Ruby Version](https://img.shields.io/badge/ruby-3.2%2B-red)](https://www.ruby-lang.org)
 [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE.txt)
 
-Sxn is a powerful session management tool for multi-repository development. It helps developers manage complex development environments with multiple git repositories, providing isolated workspaces, automatic project setup, and intelligent session management.
+sxn is a powerful session management tool for multi-repository development. It helps developers manage complex development environments with multiple git repositories, providing isolated workspaces, automatic project setup, and intelligent session management.
 
 ## Features
 
@@ -38,7 +38,7 @@ gem install sxn
 
 ## Quick Start
 
-### Initialize Sxn in your workspace
+### Initialize sxn in your workspace
 
 ```bash
 sxn init
@@ -135,7 +135,7 @@ sxn rules apply my-app
 
 ## Configuration
 
-Sxn stores its configuration in `.sxn/config.yml` in your workspace:
+sxn stores its configuration in `.sxn/config.yml` in your workspace:
 
 ```yaml
 sessions_folder: .sxn-sessions
@@ -168,7 +168,7 @@ rules:
 
 ## Templates
 
-Sxn includes templates for common project types:
+sxn includes templates for common project types:
 
 - **Rails**: CLAUDE.md, database.yml, session-info.md
 - **JavaScript**: README.md, session-info.md
@@ -178,19 +178,87 @@ Templates use Liquid syntax and have access to session, project, and environment
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+### Setup
 
-### Running Tests
+After cloning the repository, run:
+
+```bash
+bundle install
+./script/setup-hooks  # Set up git hooks for automated checks
+```
+
+### Testing and Code Quality
+
+**Important**: All code must pass tests and linting before being pushed to the repository.
+
+#### Running Tests
 
 ```bash
 # Run all tests
 bundle exec rspec
 
+# Run tests in parallel (faster)
+bundle exec rake parallel:spec
+
+# Run with coverage report
+bundle exec rake parallel:spec_with_coverage
+```
+
+#### Code Style
+
+```bash
+# Check code style
+bundle exec rubocop
+
+# Auto-fix code style issues
+bundle exec rubocop -a
+```
+
+#### Git Hooks
+
+The project includes a pre-push hook that automatically runs RuboCop and RSpec before allowing pushes. To set it up:
+
+```bash
+./script/setup-hooks
+```
+
+To bypass hooks in emergency situations (not recommended):
+```bash
+git push --no-verify
+```
+
+### Development Workflow
+
+1. Make your changes
+2. Run `bundle exec rubocop -a` to fix any style issues
+3. Run `bundle exec rspec` to ensure tests pass
+4. Commit your changes
+5. Push (pre-push hooks will run automatically)
+
+### Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Ensure tests pass and code style is correct
+5. Commit your changes with meaningful commit messages
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+### Additional Testing Options
+
+```bash
+# Run all tests in parallel (recommended for speed)
+bundle exec parallel_rspec spec/
+
+# Run all tests sequentially
+bundle exec rspec
+
 # Run only unit tests
 bundle exec rspec spec/unit
 
 # Run with coverage
-ENABLE_SIMPLECOV=true bundle exec rspec
+ENABLE_SIMPLECOV=true bundle exec parallel_rspec spec/
 ```
 
 ### Type Checking
@@ -223,3 +291,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/yourus
 ## License
 
 The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+
+## Author's Note
+
+This is a personal project that leverages Claude Code as the primary and active developer. As we continue to refine the development process and iron out any kinks, you can expect builds to gradually become more stable. Your patience and feedback are greatly appreciated as we evolve this tool together.

data/Rakefile

@@ -13,6 +13,47 @@ rescue LoadError
   # RSpec not available
 end
 
+# Parallel testing tasks
+begin
+  require "parallel_tests/tasks"
+rescue LoadError
+  # parallel_tests not available
+end
+
+namespace :parallel do
+  desc "Run specs in parallel"
+  task :spec do
+    sh "bundle exec parallel_rspec spec/unit spec/integration spec/performance --runtime-log tmp/parallel_runtime_rspec.log"
+  end
+
+  desc "Run specs in parallel with coverage"
+  task :spec_with_coverage do
+    ENV["ENABLE_SIMPLECOV"] = "true"
+    sh "bundle exec parallel_rspec spec/unit spec/integration spec/performance --runtime-log tmp/parallel_runtime_rspec.log"
+  end
+
+  desc "Setup parallel test databases (if needed)"
+  task :setup do
+    puts "No database setup needed for this project"
+  end
+
+  desc "Run specs in parallel with custom processor count"
+  task :spec_custom, [:processors] do |_t, args|
+    processors = args[:processors] || 4
+    sh "bundle exec parallel_rspec -n #{processors} spec/unit spec/integration spec/performance --runtime-log tmp/parallel_runtime_rspec.log"
+  end
+
+  desc "Generate parallel test runtime log"
+  task :generate_runtime do
+    puts "Generating runtime log for balanced test distribution..."
+    ENV["TEST_ENV_NUMBER"] = "1"
+    specs = "spec/unit spec/integration spec/performance"
+    sh "bundle exec rspec --format progress --format ParallelTests::RSpec::RuntimeLogger " \
+       "--out tmp/parallel_runtime_rspec.log #{specs}"
+    puts "Runtime log generated at tmp/parallel_runtime_rspec.log"
+  end
+end
+
 # Type checking tasks
 namespace :rbs do
   desc "Validate RBS files syntax"

data/docs/parallel_testing.md

@@ -0,0 +1,124 @@
+# Parallel Testing Guide
+
+## Overview
+
+The sxn project uses `parallel_tests` gem to run RSpec tests in parallel, significantly reducing test execution time from ~35 seconds to ~11 seconds.
+
+## Configuration
+
+### `.parallel_rspec` File
+
+This file configures RSpec formatters for parallel execution:
+
+```
+--format progress
+--format ParallelTests::RSpec::RuntimeLogger --out tmp/parallel_runtime_rspec.log
+```
+
+The RuntimeLogger records execution times for each test file, enabling balanced test distribution across parallel processes.
+
+### Runtime-Based Test Distribution
+
+Tests are distributed across parallel processes based on their historical execution times, ensuring all processes finish at roughly the same time.
+
+## Local Usage
+
+### Run Tests in Parallel
+
+```bash
+# Default parallel execution (uses all available CPUs)
+bundle exec rake parallel:spec
+
+# With custom processor count
+bundle exec rake parallel:spec_custom[2]  # Use 2 processes
+
+# With coverage
+bundle exec rake parallel:spec_with_coverage
+```
+
+### Generate/Update Runtime Log
+
+```bash
+# Generate initial runtime log or update existing one
+bundle exec rake parallel:generate_runtime
+```
+
+The runtime log is stored at `tmp/parallel_runtime_rspec.log` and contains execution times for each spec file.
+
+### Direct parallel_rspec Command
+
+```bash
+# Run with runtime balancing
+bundle exec parallel_rspec spec/unit spec/integration spec/performance --runtime-log tmp/parallel_runtime_rspec.log
+
+# Verbose output to see how tests are distributed
+bundle exec parallel_rspec spec --verbose-command --runtime-log tmp/parallel_runtime_rspec.log
+```
+
+## CI/CD Integration
+
+GitHub Actions is configured to:
+
+1. **Cache Runtime Log**: The runtime log is cached between runs using the spec files' hash as the cache key
+2. **Parallel Matrix Jobs**: Tests run across 4 parallel jobs
+3. **Automatic Generation**: If no cached runtime log exists, CI generates one automatically
+4. **Result Aggregation**: Test results from all parallel jobs are collected and summarized
+
+### CI Configuration
+
+The workflow uses a matrix strategy to run tests in parallel:
+
+```yaml
+matrix:
+  ruby: ['3.4.5']
+  ci_node_total: [4]
+  ci_node_index: [0, 1, 2, 3]
+```
+
+Each job runs a subset of tests based on the runtime log distribution.
+
+## Benefits
+
+- **Speed**: ~3x faster test execution (35s → 11s)
+- **Balanced Distribution**: Tests are distributed based on execution time, not file count
+- **CI Optimization**: Parallel jobs in CI reduce overall build time
+- **Coverage Support**: SimpleCov properly merges results from parallel processes
+
+## Troubleshooting
+
+### Unbalanced Test Distribution
+
+If tests aren't evenly distributed:
+
+1. Regenerate the runtime log: `bundle exec rake parallel:generate_runtime`
+2. Check the log file exists: `ls -la tmp/parallel_runtime_rspec.log`
+3. Verify the format (should be `path/to/spec.rb:execution_time`)
+
+### Missing Runtime Log
+
+The system will fall back to file-size-based distribution if no runtime log is found. To ensure runtime-based distribution:
+
+```bash
+# Generate if missing
+[ -f tmp/parallel_runtime_rspec.log ] || bundle exec rake parallel:generate_runtime
+```
+
+### Coverage Issues
+
+Ensure SimpleCov is configured for parallel tests in `spec/spec_helper.rb`:
+
+```ruby
+if ENV["TEST_ENV_NUMBER"]
+  SimpleCov.command_name "RSpec_#{ENV['TEST_ENV_NUMBER']}"
+  SimpleCov.merge_timeout 3600
+end
+```
+
+## Performance Metrics
+
+Current performance with 4 parallel processes:
+- Sequential execution: ~35 seconds
+- Parallel execution: ~11 seconds
+- Speedup: ~3.2x
+
+The runtime-based distribution ensures all processes finish within 1-2 seconds of each other, maximizing efficiency.

data/lib/sxn/CLI.rb

@@ -32,16 +32,8 @@ module Sxn
       # steep:ignore:start - Thor dynamic argument validation handled at runtime
       # Thor framework uses metaprogramming for argument parsing that can't be statically typed.
       # Runtime validation ensures type safety through Thor's built-in validation.
-      # Validate arguments, filtering out nil values for optional arguments
-      args_for_validation = [folder].compact
-      expected_arg_count = folder.nil? ? 0 : 1
-
-      RuntimeValidations.validate_thor_arguments("init", args_for_validation, options, {
-                                                   args: { count: [expected_arg_count], types: [String] },
-                                                   options: { force: :boolean, auto_detect: :boolean, quiet: :boolean }
-                                                 })
-
       Commands::Init.new.init(folder)
+      # steep:ignore:end
     rescue Sxn::Error => e
       handle_error(e)
     end
@@ -78,6 +70,30 @@ module Sxn
       handle_error(e)
     end
 
+    desc "remove [SESSION_NAME]", "Remove a session (shortcut for 'sxn sessions remove')"
+    option :force, type: :boolean, aliases: "-f", desc: "Force removal even with uncommitted changes"
+    def remove(session_name = nil)
+      cmd = Commands::Sessions.new
+      cmd.options = options
+      cmd.remove(session_name)
+    rescue Sxn::Error => e
+      handle_error(e)
+    end
+
+    desc "archive [SESSION_NAME]", "Archive a session (shortcut for 'sxn sessions archive')"
+    def archive(session_name = nil)
+      Commands::Sessions.new.archive(session_name)
+    rescue Sxn::Error => e
+      handle_error(e)
+    end
+
+    desc "activate [SESSION_NAME]", "Activate an archived session (shortcut for 'sxn sessions activate')"
+    def activate(session_name = nil)
+      Commands::Sessions.new.activate(session_name)
+    rescue Sxn::Error => e
+      handle_error(e)
+    end
+
     desc "projects SUBCOMMAND", "Manage project configurations"
     def projects(subcommand = nil, *args)
       Commands::Projects.start([subcommand, *args].compact)
@@ -200,18 +216,14 @@ module Sxn
 
       # steep:ignore:start - Safe integer to string coercion for UI display
       # These integer values are safely converted to strings for display purposes.
-      # Runtime validation ensures proper type handling.
-      @ui.key_value("Total Sessions",
-                    RuntimeValidations.validate_and_coerce_type(sessions.size, String, "session count display"))
-      @ui.key_value("Total Projects",
-                    RuntimeValidations.validate_and_coerce_type(projects.size, String, "project count display"))
+      @ui.key_value("Total Sessions", sessions.size.to_s)
+      @ui.key_value("Total Projects", projects.size.to_s)
 
       # Active worktrees
       if current_session
         worktree_manager = Sxn::Core::WorktreeManager.new(config_manager, session_manager)
         worktrees = worktree_manager.list_worktrees(session_name: current_session)
-        @ui.key_value("Active Worktrees",
-                      RuntimeValidations.validate_and_coerce_type(worktrees.size, String, "worktree count display"))
+        @ui.key_value("Active Worktrees", worktrees.size.to_s)
       end
 
       @ui.newline

data/lib/sxn/commands/sessions.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "thor"
+require "time"
 
 module Sxn
   module Commands
@@ -79,7 +80,8 @@ module Sxn
           name = @prompt.select("Select session to remove:", choices)
         end
 
-        unless @prompt.confirm_deletion(name, "session")
+        # Skip confirmation if force flag is used
+        if !options[:force] && !@prompt.confirm_deletion(name, "session")
           @ui.info("Cancelled")
           return
         end
@@ -259,8 +261,8 @@ module Sxn
 
         @ui.key_value("Linear Task", session[:linear_task]) if session[:linear_task]
 
-        @ui.key_value("Created", session[:created_at] || "Unknown")
-        @ui.key_value("Updated", session[:updated_at] || "Unknown")
+        @ui.key_value("Created", format_timestamp(session[:created_at]))
+        @ui.key_value("Updated", format_timestamp(session[:updated_at]))
 
         if verbose && session[:projects]&.any?
           @ui.newline
@@ -295,6 +297,19 @@ module Sxn
         @ui.newline
         @ui.recovery_suggestion("Create your first session with 'sxn add <session-name>'")
       end
+
+      def format_timestamp(timestamp)
+        return "Unknown" if timestamp.nil? || timestamp.empty?
+
+        # Parse the ISO8601 timestamp and convert to local time
+        time = Time.parse(timestamp)
+        local_time = time.localtime
+
+        # Format as "YYYY-MM-DD HH:MM:SS AM/PM Timezone"
+        local_time.strftime("%Y-%m-%d %I:%M:%S %p %Z")
+      rescue ArgumentError
+        timestamp # Return original if parsing fails
+      end
     end
   end
 end

data/lib/sxn/commands/worktrees.rb

@@ -19,7 +19,25 @@ module Sxn
         @worktree_manager = Sxn::Core::WorktreeManager.new(@config_manager, @session_manager)
       end
 
-      desc "add PROJECT [BRANCH]", "Add worktree to current session"
+      desc "add PROJECT [BRANCH]", "Add worktree to current session (defaults branch to session name)"
+      long_desc <<-DESC
+        Add a worktree for a project to the current session.
+
+        Branch options:
+        - No branch specified: Uses the session name as the branch name
+        - Branch name: Creates or checks out the specified branch
+        - remote:<branch>: Fetches and tracks the remote branch
+
+        Examples:
+        - sxn worktree add atlas-core
+          Creates worktree with branch name matching current session
+
+        - sxn worktree add atlas-core feature-branch
+          Creates worktree with specified branch name
+
+        - sxn worktree add atlas-core remote:origin/main
+          Fetches and tracks the remote branch
+      DESC
       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"
@@ -33,10 +51,11 @@ module Sxn
           return if project_name.nil?
         end
 
-        # Interactive branch selection if not provided
+        # Interactive branch selection if not provided and interactive mode
+        # Note: If branch is nil, WorktreeManager will use session name as default
         if options[:interactive] && branch.nil?
-          project = @project_manager.get_project(project_name)
-          branch = @prompt.branch_name("Enter branch name:", default: project[:default_branch])
+          session_name = options[:session] || @config_manager.current_session
+          branch = @prompt.branch_name("Enter branch name:", default: session_name)
         end
 
         session_name = options[:session] || @config_manager.current_session

data/lib/sxn/core/config_manager.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 require "yaml"
 require "pathname"
+require "ostruct"
 
 module Sxn
   module Core
@@ -40,7 +41,10 @@ module Sxn
         raise Sxn::ConfigurationError, "Project not initialized. Run 'sxn init' first." unless initialized?
 
         discovery = Sxn::Config::ConfigDiscovery.new(@base_path)
-        discovery.discover_config
+        config_hash = discovery.discover_config
+
+        # Convert nested hashes to OpenStruct recursively
+        config_to_struct(config_hash)
       end
 
       def update_current_session(session_name)
@@ -194,6 +198,14 @@ module Sxn
 
       private
 
+      def config_to_struct(obj)
+        return obj unless obj.is_a?(Hash)
+
+        OpenStruct.new(
+          obj.transform_values { |v| config_to_struct(v) }
+        )
+      end
+
       def sessions_folder_relative_path
         return ".sxn" unless @sessions_folder
 

data/lib/sxn/core/worktree_manager.rb

@@ -25,8 +25,30 @@ module Sxn
         project = @project_manager.get_project(project_name)
         raise Sxn::ProjectNotFoundError, "Project '#{project_name}' not found" unless project
 
-        # Use default branch if not specified
-        branch ||= project[:default_branch] || "master"
+        # Determine branch name
+        # If no branch specified, use session name as the branch name
+        # If branch starts with "remote:", handle remote branch tracking
+        if branch.nil?
+          branch = session_name
+        elsif branch.start_with?("remote:")
+          remote_branch = branch.sub("remote:", "")
+          # Fetch the remote branch first
+          begin
+            fetch_remote_branch(project[:path], remote_branch)
+            branch = remote_branch
+          rescue StandardError => e
+            raise Sxn::WorktreeCreationError, "Failed to fetch remote branch: #{e.message}"
+          end
+        end
+
+        if ENV["SXN_DEBUG"]
+          puts "[DEBUG] Adding worktree:"
+          puts "  Project: #{project_name}"
+          puts "  Project path: #{project[:path]}"
+          puts "  Session: #{session_name}"
+          puts "  Session path: #{session[:path]}"
+          puts "  Branch: #{branch}"
+        end
 
         # Check if worktree already exists in this session
         existing_worktrees = @session_manager.get_session_worktrees(session_name)
@@ -38,7 +60,12 @@ module Sxn
         # Create worktree path
         worktree_path = File.join(session[:path], project_name)
 
+        puts "  Worktree path: #{worktree_path}" if ENV["SXN_DEBUG"]
+
         begin
+          # Handle orphaned worktree if it exists
+          handle_orphaned_worktree(project[:path], worktree_path)
+
           # Create the worktree
           create_git_worktree(project[:path], worktree_path, branch)
 
@@ -169,6 +196,47 @@ module Sxn
 
       private
 
+      def handle_orphaned_worktree(project_path, worktree_path)
+        Dir.chdir(project_path) do
+          # Try to prune worktrees first
+          system("git worktree prune", out: File::NULL, err: File::NULL)
+
+          # Check if this worktree is registered (whether it exists or not)
+          output = `git worktree list --porcelain 2>/dev/null`
+          if output.include?(worktree_path)
+            # Force remove the orphaned/existing worktree
+            system("git worktree remove --force #{Shellwords.escape(worktree_path)}", out: File::NULL, err: File::NULL)
+          end
+        end
+
+        # Remove the directory if it still exists
+        FileUtils.rm_rf(worktree_path)
+      end
+
+      def fetch_remote_branch(project_path, branch_name)
+        Dir.chdir(project_path) do
+          # First, fetch all remotes to ensure we have the latest branches
+          raise "Failed to fetch remote branches" unless system("git fetch --all", out: File::NULL, err: File::NULL)
+
+          # Check if the branch exists on any remote
+          remotes = `git remote`.lines.map(&:strip)
+          branch_found = false
+
+          remotes.each do |remote|
+            next unless system("git show-ref --verify --quiet refs/remotes/#{remote}/#{Shellwords.escape(branch_name)}",
+                               out: File::NULL, err: File::NULL)
+
+            branch_found = true
+            # Set up tracking for the remote branch
+            system("git branch --track #{Shellwords.escape(branch_name)} #{remote}/#{Shellwords.escape(branch_name)}",
+                   out: File::NULL, err: File::NULL)
+            break
+          end
+
+          raise "Remote branch '#{branch_name}' not found on any remote" unless branch_found
+        end
+      end
+
       def create_git_worktree(project_path, worktree_path, branch)
         Dir.chdir(project_path) do
           # Check if branch exists
@@ -183,8 +251,39 @@ module Sxn
                   ["git", "worktree", "add", "-b", branch, worktree_path]
                 end
 
-          success = system(*cmd, out: File::NULL, err: File::NULL)
-          raise "Git worktree command failed" unless success
+          # Capture stderr for better error messages
+          require "open3"
+          stdout, stderr, status = Open3.capture3(*cmd)
+
+          unless status.success?
+            error_msg = stderr.empty? ? stdout : stderr
+            error_msg = "Git worktree command failed" if error_msg.strip.empty?
+
+            # Add more context to common errors
+            if error_msg.include?("already exists")
+              error_msg += "\nTry removing the existing worktree first with: sxn worktree remove #{File.basename(worktree_path)}"
+            elsif error_msg.include?("is already checked out")
+              error_msg += "\nThis branch is already checked out in another worktree"
+            elsif error_msg.include?("not a git repository")
+              error_msg = "Project '#{File.basename(project_path)}' is not a git repository"
+            elsif error_msg.include?("fatal: invalid reference")
+              # This typically means the branch doesn't exist and we're trying to create from a non-existent base
+              error_msg += "\nMake sure the repository has at least one commit or specify an existing branch"
+            elsif error_msg.include?("fatal:")
+              # Extract just the fatal error message for cleaner output
+              error_msg = error_msg.lines.grep(/fatal:/).first&.strip || error_msg
+            end
+
+            if ENV["SXN_DEBUG"]
+              puts "[DEBUG] Git worktree command failed:"
+              puts "  Command: #{cmd.join(" ")}"
+              puts "  Directory: #{project_path}"
+              puts "  STDOUT: #{stdout}"
+              puts "  STDERR: #{stderr}"
+            end
+
+            raise error_msg
+          end
         end
       end
 

data/lib/sxn/database/session_database.rb

@@ -25,7 +25,7 @@ module Sxn
     # - Bulk operations: < 100ms for 100 sessions
     class SessionDatabase
       # Current database schema version for migrations
-      SCHEMA_VERSION = 1
+      SCHEMA_VERSION = 2
 
       # Default database path relative to sxn config directory
       DEFAULT_DB_PATH = ".sxn/sessions.db"
@@ -122,7 +122,7 @@ module Sxn
         filters ||= {}
         limit = limit.to_i if limit
         offset = offset.to_i if offset
-        
+
         query_parts = ["SELECT * FROM sessions"]
         params = []
 
@@ -420,6 +420,19 @@ module Sxn
       def setup_database
         current_version = get_schema_version
 
+        # Check if this is an old database without version info
+        # If sessions table exists but version is 0, it's likely an old database
+        if current_version.zero? && table_exists?("sessions")
+          # Check if it's the old schema (without worktrees/projects columns)
+          columns = connection.execute("PRAGMA table_info(sessions)").map { |col| col["name"] }
+          if !columns.include?("worktrees") || !columns.include?("projects")
+            # This is an old database, set it to version 1 so we can migrate it
+            Sxn.logger.info "Detected old database schema without version info, treating as version 1"
+            set_schema_version(1)
+            current_version = 1
+          end
+        end
+
         if current_version.zero?
           create_initial_schema
           set_schema_version(SCHEMA_VERSION)
@@ -428,6 +441,14 @@ module Sxn
         end
       end
 
+      # Check if a table exists
+      def table_exists?(table_name)
+        result = connection.execute("SELECT name FROM sqlite_master WHERE type='table' AND name=?", table_name)
+        !result.empty?
+      rescue SQLite3::Exception
+        false
+      end
+
       # Get current schema version from database
       def get_schema_version
         result = connection.execute("PRAGMA user_version").first
@@ -501,12 +522,41 @@ module Sxn
       end
 
       # Run database migrations from old version to current
-      def run_migrations(_from_version)
-        # Future migrations will be implemented here
-        # For now, we only have version 1
+      def run_migrations(from_version)
+        Sxn.logger.info "Running database migrations from version #{from_version} to #{SCHEMA_VERSION}"
+
+        # Run each migration in sequence
+        migrate_to_v1 if from_version < 1
+
+        migrate_to_v2 if from_version < 2
+
         set_schema_version(SCHEMA_VERSION)
       end
 
+      # Migration: Initial schema (v1)
+      def migrate_to_v1
+        # This is handled by create_initial_schema
+        create_initial_schema
+      end
+
+      # Migration: Add worktrees and projects columns (v2)
+      def migrate_to_v2
+        Sxn.logger.info "Migrating database to version 2: Adding worktrees and projects columns"
+
+        # Check if columns already exist
+        columns = connection.execute("PRAGMA table_info(sessions)").map { |col| col["name"] }
+
+        unless columns.include?("worktrees")
+          connection.execute("ALTER TABLE sessions ADD COLUMN worktrees TEXT")
+          Sxn.logger.info "Added worktrees column to sessions table"
+        end
+
+        return if columns.include?("projects")
+
+        connection.execute("ALTER TABLE sessions ADD COLUMN projects TEXT")
+        Sxn.logger.info "Added projects column to sessions table"
+      end
+
       # Generate secure, unique session ID
       def generate_session_id
         SecureRandom.hex(16) # 32 character hex string
@@ -636,7 +686,7 @@ module Sxn
             param.to_s
           end
         end
-        
+
         connection.execute(sql, sanitized_params)
       rescue SQLite3::MismatchException => e
         # Log the error with details for debugging

data/lib/sxn/runtime_validations.rb

@@ -6,6 +6,10 @@ module Sxn
     class << self
       # Validate Thor command arguments at runtime
       def validate_thor_arguments(command_name, args, options, validations)
+        # Ensure args and options are not nil
+        args ||= []
+        options ||= {}
+
         # Validate argument count
         if validations[:args]
           count_range = validations[:args][:count]
@@ -23,7 +27,7 @@ module Sxn
         end
 
         # Validate options
-        if validations[:options]
+        if validations[:options] && options.respond_to?(:each)
           options.each do |key, value|
             validate_option_type(command_name, key, value, validations[:options][key.to_sym]) if validations[:options][key.to_sym]
           end

data/lib/sxn/version.rb

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

data/script/setup-hooks

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+#
+# Setup git hooks for sxn development
+#
+
+set -e
+
+echo "🔧 Setting up git hooks for sxn development..."
+
+# Create hooks directory if it doesn't exist
+mkdir -p .git/hooks
+
+# Create pre-push hook
+cat > .git/hooks/pre-push << 'EOF'
+#!/bin/sh
+#
+# Pre-push hook for sxn project
+# Runs RuboCop and RSpec before allowing push
+#
+
+echo "🔍 Running pre-push checks..."
+
+# Run RuboCop
+echo "📝 Checking code style with RuboCop..."
+bundle exec rubocop
+if [ $? -ne 0 ]; then
+    echo "❌ RuboCop failed! Please fix linting issues before pushing."
+    echo "   Run: bundle exec rubocop -a"
+    exit 1
+fi
+
+# Run RSpec tests
+echo "🧪 Running tests with RSpec..."
+bundle exec rspec --format progress
+if [ $? -ne 0 ]; then
+    echo "❌ Tests failed! Please fix failing tests before pushing."
+    exit 1
+fi
+
+echo "✅ All checks passed! Proceeding with push..."
+exit 0
+EOF
+
+chmod +x .git/hooks/pre-push
+
+echo "✅ Git hooks installed successfully!"
+echo ""
+echo "The following hooks have been set up:"
+echo "  • pre-push: Runs RuboCop and RSpec before pushing"
+echo ""
+echo "To bypass hooks in emergency (not recommended):"
+echo "  git push --no-verify"

data/sig/sxn/cli.rbs

@@ -21,6 +21,12 @@ module Sxn
 
     def current: () -> void
 
+    def remove: (?String? session_name) -> void
+
+    def archive: (?String? session_name) -> void
+
+    def activate: (?String? session_name) -> void
+
     def projects: (?String? subcommand, *String args) -> void
 
     def sessions: (?String? subcommand, *String args) -> void

data/sig/sxn/commands/sessions.rbs

@@ -57,6 +57,10 @@ module Sxn
 
       # Suggest creating a session
       def suggest_create_session: () -> void
+
+      # Format a timestamp string to local timezone
+      # @param timestamp ISO8601 timestamp string
+      def format_timestamp: (String? timestamp) -> String
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sxn
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - Ernest Sim
@@ -488,6 +488,8 @@ files:
 - ".gem_rbs_collection/sqlite3/2.0/.rbs_meta.yaml"
 - ".gem_rbs_collection/sqlite3/2.0/database.rbs"
 - ".gem_rbs_collection/sqlite3/2.0/pragmas.rbs"
+- ".parallel_rspec"
+- ".parallel_rspec_options"
 - ".rspec"
 - ".rubocop.yml"
 - ".simplecov"
@@ -499,6 +501,7 @@ files:
 - Rakefile
 - Steepfile
 - bin/sxn
+- docs/parallel_testing.md
 - lib/sxn.rb
 - lib/sxn/CLI.rb
 - lib/sxn/commands.rb
@@ -555,6 +558,7 @@ files:
 - lib/sxn/version.rb
 - rbs_collection.lock.yaml
 - rbs_collection.yaml
+- script/setup-hooks
 - scripts/test.sh
 - sig/external/liquid.rbs
 - sig/external/thor.rbs
@@ -606,7 +610,6 @@ 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

data/sxn.gemspec

@@ -1,85 +0,0 @@
-# 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