Add GitHub shorthand syntax and auto-detection to swap-deps

- Support shorthand syntax for gem-specific flags:
  - `--shakapacker '#main'` expands to shakacode/shakapacker#main
  - `--shakapacker '@v9.0.0'` expands to shakacode/[email protected]
  - `--shakapacker 'shakacode/shakapacker#branch'` for full spec

- Auto-detect default branch when none specified:
  - `--shakapacker shakacode/shakapacker` detects main/master
  - Uses `git ls-remote --symref` for zero-cost detection

- Add zsh escaping documentation:
  - Document that # and @ require quotes in zsh
  - Update help text with examples

- Map gem names to default repos:
  - shakapacker -> shakacode/shakapacker
  - react_on_rails -> shakacode/react_on_rails
  - cypress-on-rails -> shakacode/cypress-on-rails

Fixes issue where zsh interprets # as comment marker.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: justin808

lib/demo_scripts/gem_swapper.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'English'
 require 'yaml'
 require 'json'
 require 'pathname'
@@ -599,14 +600,14 @@ def validate_github_repos(repos)
                    repo, ref, ref_type = parse_github_spec(value)
                    {
                      repo: repo,
-                     branch: ref || 'main',
+                     branch: ref,
                      ref_type: ref_type || :branch
                    }
                  elsif value.is_a?(Hash)
                    # Hash format with repo and optional branch
                    {
                      repo: value['repo'] || value[:repo],
-                     branch: value['branch'] || value[:branch] || 'main',
+                     branch: value['branch'] || value[:branch],
                      ref_type: (value['ref_type'] || value[:ref_type] || :branch).to_sym
                    }
                  else
@@ -615,13 +616,33 @@ def validate_github_repos(repos)
 
         # Use shared validation methods
         validate_github_repo(result[:repo])
+
+        # Auto-detect default branch if not specified
+        result[:branch] ||= detect_default_branch(result[:repo])
+
         validate_github_branch(result[:branch]) if result[:branch]
 
         result
       end
     end
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
 
+    def detect_default_branch(repo)
+      puts "  🔍 Detecting default branch for #{repo}..."
+
+      # Use git ls-remote to find the default branch without cloning
+      output = `git ls-remote --symref https://github.com/#{repo}.git HEAD 2>/dev/null`
+
+      if $CHILD_STATUS.success? && output =~ %r{ref: refs/heads/(\S+)\s+HEAD}
+        branch = ::Regexp.last_match(1)
+        puts "     Detected: #{branch}"
+        branch
+      else
+        puts "     Could not detect, defaulting to 'main'"
+        'main'
+      end
+    end
+
     def validate_local_paths!
       gem_paths.each do |gem_name, path|
         next if File.directory?(path)

lib/demo_scripts/swap_deps_cli.rb

@@ -74,8 +74,69 @@ def run!
     end
     # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
+    # Map gem names to their default GitHub repositories
+    GEM_REPOS = {
+      'shakapacker' => 'shakacode/shakapacker',
+      'react_on_rails' => 'shakacode/react_on_rails',
+      'cypress-on-rails' => 'shakacode/cypress-on-rails'
+    }.freeze
+
     private
 
+    def process_gem_value(gem_name, value)
+      # Check if it's a GitHub spec (starts with #, @, or contains /)
+      if value.start_with?('#', '@') || value.include?('/')
+        # It's a GitHub spec
+        repo, ref, ref_type = parse_github_spec(gem_name, value)
+        @github_repos[gem_name] = { repo: repo, branch: ref, ref_type: ref_type }
+      else
+        # It's a local path
+        @gem_paths[gem_name] = value
+      end
+    end
+
+    # rubocop:disable Metrics/MethodLength
+    def parse_github_spec(gem_name, spec)
+      # Handle shorthand formats:
+      # - #branch -> shakacode/gem#branch
+      # - @tag -> shakacode/gem@tag
+      # - user/repo#branch -> user/repo#branch
+      # - user/repo@tag -> user/repo@tag
+      # - user/repo -> user/repo (will auto-detect default branch)
+
+      if spec.start_with?('#')
+        # Shorthand: #branch
+        repo = GEM_REPOS[gem_name]
+        raise Error, "No default repo for gem: #{gem_name}" unless repo
+
+        ref = spec[1..]
+        ref_type = :branch
+      elsif spec.start_with?('@')
+        # Shorthand: @tag
+        repo = GEM_REPOS[gem_name]
+        raise Error, "No default repo for gem: #{gem_name}" unless repo
+
+        ref = spec[1..]
+        ref_type = :tag
+      elsif spec.include?('@')
+        # Full: user/repo@tag
+        repo, ref = spec.split('@', 2)
+        ref_type = :tag
+      elsif spec.include?('#')
+        # Full: user/repo#branch
+        repo, ref = spec.split('#', 2)
+        ref_type = :branch
+      else
+        # Just repo name: user/repo
+        repo = spec
+        ref = nil # Will auto-detect default branch
+        ref_type = :branch
+      end
+
+      [repo, ref, ref_type]
+    end
+    # rubocop:enable Metrics/MethodLength
+
     def detect_context!
       # Check if we're in a demo directory by looking for Gemfile and presence of ../../.swap-deps.yml
       if File.exist?('Gemfile') && File.exist?('../../.swap-deps.yml')
@@ -107,23 +168,26 @@ def parse_options!
         opts.separator ''
         opts.separator 'Gem options (specify one or more):'
 
-        opts.on('--shakapacker PATH', 'Path to local shakapacker repository') do |path|
-          @gem_paths['shakapacker'] = path
+        opts.on('--shakapacker VALUE', 'Local path or GitHub spec (e.g., #branch, @tag, user/repo#branch)') do |value|
+          process_gem_value('shakapacker', value)
         end
 
-        opts.on('--react-on-rails PATH', 'Path to local react_on_rails repository') do |path|
-          @gem_paths['react_on_rails'] = path
+        opts.on('--react-on-rails VALUE',
+                'Local path or GitHub spec (e.g., #branch, @tag, user/repo#branch)') do |value|
+          process_gem_value('react_on_rails', value)
         end
 
-        opts.on('--cypress-on-rails PATH', 'Path to local cypress-on-rails repository') do |path|
-          @gem_paths['cypress-on-rails'] = path
+        opts.on('--cypress-on-rails VALUE',
+                'Local path or GitHub spec (e.g., #branch, @tag, user/repo#branch)') do |value|
+          process_gem_value('cypress-on-rails', value)
         end
 
         opts.separator ''
         opts.separator 'GitHub options:'
 
         opts.on('--github REPO[#BRANCH|@TAG]',
-                'GitHub repository (e.g., user/repo, user/repo#branch, or user/repo@tag)') do |value|
+                'GitHub repository (e.g., user/repo, user/repo#branch, or user/repo@tag)',
+                'Note: In zsh, quote values with # or @ (e.g., \'user/repo#main\')') do |value|
           if value.include?('@')
             repo, ref = value.split('@', 2)
             ref_type = :tag
@@ -132,7 +196,7 @@ def parse_options!
             ref_type = :branch
           else
             repo = value
-            ref = 'main'
+            ref = nil # Auto-detect default branch
             ref_type = :branch
           end
           gem_name = infer_gem_from_repo(repo)
@@ -228,25 +292,32 @@ def parse_options!
           puts '  bin/swap-deps --shakapacker ~/dev/shakapacker \\'
           puts '                --react-on-rails ~/dev/react_on_rails'
           puts ''
+          puts '  # Use shorthand for GitHub branches (quotes required in zsh!)'
+          puts '  bin/swap-deps --shakapacker \'#main\''
+          puts '  bin/swap-deps --react-on-rails \'#feature-x\''
+          puts ''
+          puts '  # Use shorthand for GitHub tags'
+          puts '  bin/swap-deps --shakapacker \'@v9.0.0\''
+          puts ''
+          puts '  # Use full GitHub repo spec'
+          puts '  bin/swap-deps --shakapacker \'shakacode/shakapacker#fix-hmr\''
+          puts '  bin/swap-deps --shakapacker \'otheruser/shakapacker#custom-branch\''
+          puts ''
+          puts '  # Auto-detect default branch (no # needed, no quotes needed)'
+          puts '  bin/swap-deps --shakapacker shakacode/shakapacker'
+          puts ''
           puts '  # Apply to specific demo only'
           puts '  bin/swap-deps --demo basic-v16-rspack --react-on-rails ~/dev/react_on_rails'
           puts ''
           puts '  # Apply to demos-scratch directory'
           puts '  bin/swap-deps --demos-dir demos-scratch --react-on-rails ~/dev/react_on_rails'
           puts ''
-          puts '  # Use a GitHub repository with a branch (# for branches)'
-          puts '  bin/swap-deps --github shakacode/shakapacker#fix-hmr'
-          puts ''
-          puts '  # Use a release tag (@ for tags)'
-          puts '  bin/swap-deps --github shakacode/[email protected]'
-          puts ''
-          puts '  # Mix branches and tags'
-          puts '  bin/swap-deps --github shakacode/shakapacker#v8-stable \\'
-          puts '                --github shakacode/[email protected]'
+          puts '  # Use --github flag (alternative to gem-specific flags)'
+          puts '  bin/swap-deps --github \'shakacode/shakapacker#fix-hmr\''
           puts ''
           puts '  # Mix local paths and GitHub repos'
           puts '  bin/swap-deps --shakapacker ~/dev/shakapacker \\'
-          puts '                --github shakacode/react_on_rails#feature-x'
+          puts '                --react-on-rails \'#feature-x\''
           puts ''
           puts '  # Use config file'
           puts '  bin/swap-deps --apply'