ace-git-worktree 0.19.0

data/lib/ace/git/worktree/atoms/path_expander.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Ace
+  module Git
+    module Worktree
+      module Atoms
+        # Path expansion and validation for worktree operations
+        #
+        # Simplified implementation focused on worktree-specific needs without
+        # over-engineered security patterns.
+        #
+        # @example Expand a user path
+        #   PathExpander.expand("~") # => "/home/user"
+        #
+        # @example Check if a directory is writable
+        #   PathExpander.writable?("/tmp/worktree") # => true/false
+        class PathExpander
+          class << self
+            # Expand a path using standard Ruby path expansion
+            #
+            # @param path [String] Path to expand
+            # @param base [String, nil] Base directory for relative paths (default: current directory)
+            # @return [String] Expanded absolute path
+            def expand(path, base = nil)
+              return "" if path.nil? || path.empty?
+              base ? File.expand_path(path, base) : File.expand_path(path)
+            end
+
+            # Resolve a path relative to a base directory
+            #
+            # @param path [String] Path to resolve
+            # @param base [String] Base directory (default: current directory)
+            # @return [String] Resolved absolute path
+            def resolve(path, base = Dir.pwd)
+              expand_path = expand(path)
+              expanded_base = expand(base)
+
+              if File.absolute_path?(expand_path)
+                expand_path
+              else
+                File.expand_path(path, expanded_base)
+              end
+            end
+
+            # Check if a path is writable
+            #
+            # @param path [String] Path to check
+            # @param create_if_missing [Boolean] Create directory if it doesn't exist
+            # @return [Boolean] true if path is writable
+            def writable?(path, create_if_missing: false)
+              expanded_path = expand(path)
+
+              begin
+                # Check if path exists
+                unless File.exist?(expanded_path)
+                  if create_if_missing
+                    FileUtils.mkdir_p(expanded_path)
+                  else
+                    return false
+                  end
+                end
+
+                # Test writability by trying to create a temp file
+                temp_file = File.join(expanded_path, ".ace_git_worktree_test_#{Time.now.to_i}_#{$$}")
+                File.write(temp_file, "test")
+                File.delete(temp_file)
+                true
+              rescue Errno::EACCES, Errno::EPERM
+                false
+              rescue
+                false
+              end
+            end
+
+            # Validate a path for worktree creation
+            #
+            # @param path [String] Path to validate
+            # @param git_root [String] Git repository root
+            # @return [Hash] Validation result with :valid, :error, :expanded_path keys
+            def validate_for_worktree(path, git_root = nil)
+              expanded_path = expand(path)
+
+              # Check if parent directory exists and is writable
+              parent_dir = File.dirname(expanded_path)
+              unless File.exist?(parent_dir)
+                return {
+                  valid: false,
+                  error: "Parent directory does not exist: #{parent_dir}",
+                  expanded_path: expanded_path
+                }
+              end
+
+              unless writable?(parent_dir)
+                return {
+                  valid: false,
+                  error: "Parent directory is not writable: #{parent_dir}",
+                  expanded_path: expanded_path
+                }
+              end
+
+              # Check if worktree is being created directly in git root (not allowed)
+              # Allow worktrees in subdirectories or outside git root entirely
+              if git_root
+                git_root_expanded = File.expand_path(git_root)
+                expanded_path_abs = File.expand_path(expanded_path)
+
+                # Only prevent creation directly at git root, not in subdirectories
+                if expanded_path_abs == git_root_expanded
+                  return {
+                    valid: false,
+                    error: "Worktree cannot be created at git repository root. Use a subdirectory or different location.",
+                    expanded_path: expanded_path
+                  }
+                end
+              end
+
+              # Check if path already exists
+              if File.exist?(expanded_path)
+                if File.directory?(expanded_path) && !Dir.empty?(expanded_path)
+                  return {
+                    valid: false,
+                    error: "Directory already exists and is not empty: #{expanded_path}",
+                    expanded_path: expanded_path
+                  }
+                elsif File.file?(expanded_path)
+                  return {
+                    valid: false,
+                    error: "Path exists but is a file: #{expanded_path}",
+                    expanded_path: expanded_path
+                  }
+                end
+              end
+
+              {
+                valid: true,
+                error: nil,
+                expanded_path: expanded_path
+              }
+            end
+
+            # Get a relative path from git root
+            #
+            # @param path [String] Absolute path
+            # @param git_root [String] Git repository root
+            # @return [String] Relative path from git root
+            def relative_to_git_root(path, git_root)
+              expanded_path = expand(path)
+              expanded_root = expand(git_root)
+
+              # Use File.expand_path for consistent comparison
+              normalized_path = File.expand_path(expanded_path)
+              normalized_root = File.expand_path(expanded_root)
+
+              if normalized_path.start_with?(normalized_root + "/") || normalized_path == normalized_root
+                if normalized_path == normalized_root
+                  "."
+                else
+                  relative_path = normalized_path[normalized_root.length..-1]
+                  relative_path.start_with?("/") ? relative_path[1..-1] : relative_path
+                end
+              else
+                expanded_path
+              end
+            end
+
+            # Simple path safety validation
+            # Only checks for obviously dangerous patterns
+            #
+            # @param path [String] Path to validate
+            # @return [Boolean] true if path appears safe
+            def safe_path?(path)
+              return false if path.nil? || path.empty?
+
+              path_str = path.to_s
+
+              # Check for null bytes and obviously dangerous patterns
+              return false if path_str.include?("\x00")
+              return false if path_str.include?("../../../")
+
+              true
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/worktree/atoms/slug_generator.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    module Worktree
+      module Atoms
+        # Slug generation atom
+        #
+        # Converts task titles and other text into URL-safe slugs suitable
+        # for git branch names and directory names.
+        #
+        # @example Generate a slug from a task title
+        #   SlugGenerator.from_title("Fix authentication bug in login flow")
+        #   # => "fix-authentication-bug-in-login-flow"
+        #
+        # @example Generate a slug with custom max length
+        #   SlugGenerator.from_title("Very long task title...", max_length: 20)
+        #   # => "very-long-task-title"
+        class SlugGenerator
+          # Default maximum length for slugs
+          DEFAULT_MAX_LENGTH = 50
+
+          # Minimum length to avoid empty or too-short slugs
+          MIN_LENGTH = 3
+
+          # Characters that are not allowed in git branch names
+          FORBIDDEN_CHARS = /[~\^*?\[\]:]/
+
+          # Characters to replace with hyphens
+          SEPARATORS = /[ ._\/\\()]+/
+
+          # Multiple consecutive non-word characters (but allow single hyphens)
+          MULTIPLE_SEPARATORS = /-{2,}|[^a-zA-Z0-9-]+/
+
+          # Leading/trailing separators and hyphens
+          TRIM_SEPARATORS = /^[-_]+|[-_]+$/
+
+          class << self
+            # Generate a slug from a task title
+            #
+            # @param title [String] Task title to convert
+            # @param max_length [Integer] Maximum length of the slug
+            # @param fallback [String] Fallback string if slug is too short/empty
+            # @return [String] URL-safe slug
+            #
+            # @example
+            #   SlugGenerator.from_title("Fix authentication bug")
+            #   # => "fix-authentication-bug"
+            #
+            #   SlugGenerator.from_title("Add user:profile endpoint", max_length: 20)
+            #   # => "add-user-profile-end"
+            def from_title(title, max_length: DEFAULT_MAX_LENGTH, fallback: "task")
+              return fallback if title.nil? || title.empty?
+
+              # Convert to string and strip whitespace
+              title_str = title.to_s.strip
+
+              # Remove forbidden characters that git doesn't allow in branch names
+              cleaned = title_str.gsub(FORBIDDEN_CHARS, "")
+
+              # Replace separators (spaces, dots, underscores, slashes) with hyphens
+              normalized = cleaned.gsub(SEPARATORS, "-")
+
+              # Remove any remaining non-alphanumeric characters except hyphens
+              sanitized = normalized.gsub(MULTIPLE_SEPARATORS, "-")
+
+              # Remove leading/trailing hyphens and underscores
+              trimmed = sanitized.gsub(TRIM_SEPARATORS, "")
+
+              # Convert to lowercase
+              slug = trimmed.downcase
+
+              # Handle empty or too-short result
+              if slug.length < MIN_LENGTH
+                slug = fallback
+              end
+
+              # Truncate to max length, avoiding cutting in the middle of a word if possible
+              if slug.length > max_length
+                slug = truncate_slug(slug, max_length)
+              end
+
+              # Final validation - ensure we still have a valid slug
+              if slug.empty? || slug.length < MIN_LENGTH
+                slug = fallback
+              end
+
+              slug
+            end
+
+            # Generate a slug for a task ID
+            #
+            # @param task_id [String] Task ID (e.g., "081", "task.081", "v.0.9.0+081")
+            # @return [String] Simple task ID slug
+            #
+            # @example
+            #   SlugGenerator.from_task_id("081") # => "task-081"
+            #   SlugGenerator.from_task_id("v.0.9.0+081") # => "task-081"
+            def from_task_id(task_id)
+              return "task" if task_id.nil? || task_id.empty?
+
+              # Extract the numeric part from various task ID formats
+              numeric_part = task_id.to_s.match(/(\d+)$/)
+              return "task-#{task_id}" unless numeric_part
+
+              "task-#{numeric_part[1]}"
+            end
+
+            # Generate a combined slug from task ID and title
+            #
+            # @param task_id [String] Task ID
+            # @param title [String] Task title
+            # @param max_length [Integer] Maximum length of the combined slug
+            # @return [String] Combined slug like "081-fix-authentication-bug"
+            #
+            # @example
+            #   SlugGenerator.combined("081", "Fix authentication bug")
+            #   # => "081-fix-authentication-bug"
+            def combined(task_id, title, max_length: DEFAULT_MAX_LENGTH)
+              task_slug = from_task_id(task_id).gsub(/^task-/, "")
+              title_slug = from_title(title, max_length: max_length - task_slug.length - 1)
+
+              "#{task_slug}-#{title_slug}"
+            end
+
+            # Sanitize an existing slug
+            #
+            # @param slug [String] Slug to sanitize
+            # @return [String] Sanitized slug
+            #
+            # @example
+            #   SlugGenerator.sanitize("invalid@branch#name") # => "invalid-branch-name"
+            def sanitize(slug)
+              return "task" if slug.nil? || slug.empty?
+
+              slug_str = slug.to_s.strip
+
+              # Remove forbidden characters
+              cleaned = slug_str.gsub(FORBIDDEN_CHARS, "")
+
+              # Replace separators with hyphens
+              normalized = cleaned.gsub(SEPARATORS, "-")
+
+              # Remove multiple consecutive separators
+              sanitized = normalized.gsub(MULTIPLE_SEPARATORS, "-")
+
+              # Trim leading/trailing separators
+              trimmed = sanitized.gsub(TRIM_SEPARATORS, "")
+
+              # Convert to lowercase
+              slug = trimmed.downcase
+
+              # Fallback if result is empty
+              slug.empty? ? "task" : slug
+            end
+
+            # Convert a branch name to a safe directory name
+            #
+            # Sanitizes branch names for use as directory names by replacing
+            # characters that are not alphanumeric, hyphens, or underscores with hyphens.
+            # Also handles slash-separated branch names (e.g., "origin/feature/auth").
+            #
+            # @param branch_name [String] Branch name to convert
+            # @return [String] Directory-safe name
+            #
+            # @example Simple branch name
+            #   SlugGenerator.to_directory_name("feature-branch")
+            #   # => "feature-branch"
+            #
+            # @example Branch with slashes (remote or hierarchical)
+            #   SlugGenerator.to_directory_name("origin/feature/auth")
+            #   # => "origin-feature-auth"
+            #
+            # @example Branch with special characters
+            #   SlugGenerator.to_directory_name("fix:bug#123")
+            #   # => "fix-bug-123"
+            def to_directory_name(branch_name)
+              return "worktree" if branch_name.nil? || branch_name.empty?
+
+              # Replace slashes and any non-alphanumeric/hyphen/underscore with hyphens
+              branch_name.to_s.tr("/", "-").gsub(/[^a-zA-Z0-9\-_]/, "-")
+            end
+
+            # Check if a slug is valid for git branch names
+            #
+            # @param slug [String] Slug to validate
+            # @return [Boolean] true if slug is valid
+            #
+            # @example
+            #   SlugGenerator.valid?("valid-branch-name") # => true
+            #   SlugGenerator.valid?("invalid@branch") # => false
+            def valid?(slug)
+              return false if slug.nil? || slug.empty?
+              return false if slug.length > 255 # Git branch name limit
+              return false if slug.match?(FORBIDDEN_CHARS)
+              return false if slug.start_with?("-") || slug.end_with?("-")
+              return false if slug.include?(".")  # Dots not allowed in git branch names
+              return false if slug.include?(" ")  # Spaces not allowed
+
+              # Check for invalid git branch name patterns
+              return false if slug == "HEAD"
+              return false if slug.include?("..")
+              return false if slug.include?("@")
+
+              true
+            end
+
+            private
+
+            # Truncate slug intelligently to avoid cutting words
+            #
+            # @param slug [String] Slug to truncate
+            # @param max_length [Integer] Maximum length
+            # @return [String] Truncated slug
+            def truncate_slug(slug, max_length)
+              return slug if slug.length <= max_length
+
+              # Try to truncate at a hyphen to avoid cutting words
+              truncated = slug[0, max_length]
+
+              # Find the last hyphen before the cutoff
+              last_hyphen = truncated.rindex("-")
+              if last_hyphen && last_hyphen > max_length * 0.7 # Don't cut too much
+                truncated = slug[0, last_hyphen]
+              end
+
+              # Remove trailing hyphen
+              truncated.gsub(/-$/, "")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/worktree/atoms/task_id_extractor.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    module Worktree
+      module Atoms
+        # Extracts task IDs from task data, preserving hierarchical subtask notation
+        #
+        # This atom provides a single source of truth for task ID extraction across
+        # ace-git-worktree, ensuring consistent handling of hierarchical task IDs
+        # (e.g., "121.01" for subtasks).
+        #
+        # @example Extract from task data hash
+        #   TaskIDExtractor.extract({id: "v.0.9.0+task.121.01"}) # => "121.01"
+        #   TaskIDExtractor.extract({id: "v.0.9.0+task.121"})    # => "121"
+        #   TaskIDExtractor.extract({id: "v.0.9.0+ace-t.121.01"}) # => "121.01"
+        #   TaskIDExtractor.extract({id: "v.0.9.0+t.121"})       # => "121"
+        #
+        # @example Normalize a task reference string
+        #   TaskIDExtractor.normalize("v.0.9.0+task.121.01") # => "121.01"
+        #   TaskIDExtractor.normalize("task.121")       # => "121"
+        #   TaskIDExtractor.normalize("ace-t.121")      # => "121"
+        #   TaskIDExtractor.normalize("121.01")         # => "121.01"
+        class TaskIDExtractor
+          # Extract task ID from task data hash
+          #
+          # @param task_data [Hash] Task data with :id and/or :task_number
+          # @return [String] Task ID (e.g., "121" or "121.01")
+          def self.extract(task_data)
+            return "unknown" unless task_data
+
+            # Regex with subtask support
+            if task_data[:id]
+              # B36TS full ID: "8pp.t.hy4" -> "hy4", or subtask "8pp.t.hy4.a" -> "hy4.a"
+              if match = task_data[:id].match(/\A[0-9a-z]{3}\.[a-z]\.([0-9a-z]{3}(?:\.[a-z0-9])?)\z/)
+                return match[1]
+              end
+              # Try subtask pattern first (e.g., "v.0.9.0+task.121.01" -> "121.01")
+              if match = task_data[:id].match(/(?:ace-)?(?:task|t)\.(\d+)\.(\d{2})$/)
+                return "#{match[1]}.#{match[2]}"
+              end
+              # Then simple pattern (e.g., "v.0.9.0+task.094" -> "094")
+              if match = task_data[:id].match(/(?:ace-)?(?:task|t)\.(\d+)$/)
+                return match[1]
+              end
+              # Fallback for partial patterns (e.g., "task.121.1" -> "121", ignoring invalid suffix)
+              if match = task_data[:id].match(/(?:ace-)?(?:task|t)\.(\d+)/)
+                return match[1]
+              end
+            end
+
+            # Last resort: use task_number (doesn't include subtask suffix)
+            task_data[:task_number]&.to_s || "unknown"
+          end
+
+          # Normalize a task reference string to simple ID format
+          #
+          # @param task_ref [String] Task reference (e.g., "121.01", "v.0.9.0+task.121.01")
+          # @return [String, nil] Normalized ID or nil if invalid
+          def self.normalize(task_ref)
+            ref = task_ref.to_s.strip
+            return nil if ref.empty?
+
+            # Regex patterns for recognized ACE task ID formats
+            # B36TS full ID: "8pp.t.hy4" -> "hy4", or subtask "8pp.t.hy4.a" -> "hy4.a"
+            if match = ref.match(/\A[0-9a-z]{3}\.[a-z]\.([0-9a-z]{3}(?:\.[a-z0-9])?)\z/)
+              match[1]
+            # B36TS short ref: exactly 3 lowercase alphanumeric chars (e.g., "hy4")
+            elsif match = ref.match(/\A([0-9a-z]{3})\z/)
+              match[1]
+            # ACE task IDs are 3-digit zero-padded (081, 121, etc.)
+            # Try hierarchical pattern first (e.g., "121.01", "task.121.01")
+            elsif match = ref.match(/(\d{3})\.(\d{2})(?:\b|$)/)
+              "#{match[1]}.#{match[2]}"
+            # Try ace-task/ace-t or task/t directory at end of path (e.g., "ace-task.hy4", "/path/to/task.121")
+            elsif match = ref.match(/(?:ace-)?(?:task|t)\.([0-9a-z]{3})\/?$/)
+              match[1]
+            # Try task./t. prefix in middle of path (e.g., ".cache/test/task.121")
+            # Use negative lookbehind to skip ace-task.XXX / ace-t.XXX parent directories
+            elsif match = ref.match(/(?<!ace-)(?:task|t)\.(\d{3})(?:\b|$)/)
+              match[1]
+            # Try bare 3-digit task ID (e.g., "121", "081")
+            elsif match = ref.match(/\b(\d{3})\b/)
+              match[1]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/worktree/cli/commands/config.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "shared_helpers"
+require_relative "../../commands/config_command"
+
+module Ace
+  module Git
+    module Worktree
+      module CLI
+        module Commands
+          class Config < Ace::Support::Cli::Command
+            include SharedHelpers
+
+            desc "Show and manage worktree configuration"
+
+            example [
+              "                # Show current configuration",
+              "--show          # Show current configuration",
+              "--validate      # Validate configuration",
+              "--files         # Show config file locations"
+            ]
+
+            # Accept extra positional arguments for backward compatibility
+            # (e.g., "show", "validate" as positional args instead of flags)
+            argument :subcommand, required: false, desc: "Subcommand (show, validate, files)"
+
+            option :show, desc: "Show current configuration", type: :boolean, aliases: []
+            option :validate, desc: "Validate configuration", type: :boolean, aliases: []
+            option :files, desc: "Show configuration file locations", type: :boolean, aliases: []
+            option :verbose, desc: "Show verbose output", type: :boolean, aliases: ["-v"]
+            option :quiet, type: :boolean, aliases: ["-q"], desc: "Suppress non-essential output"
+            option :debug, type: :boolean, aliases: ["-d"], desc: "Show debug output"
+
+            def call(subcommand: nil, **options)
+              display_config_summary("config", options)
+
+              # Convert ace-support-cli options to args array format
+              args = options_to_args(options)
+              # Add subcommand as positional argument if provided
+              args << subcommand if subcommand
+
+              Ace::Git::Worktree::Commands::ConfigCommand.new.run(args)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/worktree/cli/commands/create.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "shared_helpers"
+require_relative "../../commands/create_command"
+
+module Ace
+  module Git
+    module Worktree
+      module CLI
+        module Commands
+          class Create < Ace::Support::Cli::Command
+            include SharedHelpers
+
+            desc <<~DESC.strip
+              Create a new worktree
+
+              Supports task-aware, PR, and traditional worktree creation.
+
+              Task-Aware:
+                ace-git-worktree --task 081
+                ace-git-worktree --task 081 --dry-run
+
+              PR-Aware:
+                ace-git-worktree --pr 123
+
+              Traditional:
+                ace-git-worktree feature-branch
+                ace-git-worktree create --from origin/feature
+            DESC
+
+            example [
+              "--task 081          # Create worktree for task",
+              "--pr 123            # Create worktree for PR",
+              "--from origin/feature   # Create from remote branch",
+              "feature/new-auth    # Create with branch name"
+            ]
+
+            argument :branch, required: false, desc: "Branch name for traditional creation"
+
+            option :task, desc: "Task ID for task-aware worktree", aliases: []
+            option :pr, desc: "PR number for PR-aware worktree", aliases: ["--pull-request"]
+            option :from, desc: "Create from specific branch (local or remote)", aliases: ["-b"]
+            option :path, desc: "Custom worktree path", aliases: []
+            option :source, desc: "Git ref to use as start-point", aliases: []
+            option :dry_run, desc: "Show what would be created", type: :boolean, aliases: ["--dry-run"]
+            option :no_status_update, desc: "Skip marking task as in-progress", type: :boolean, aliases: ["--no-status-update"]
+            option :no_commit, desc: "Skip committing task changes", type: :boolean, aliases: ["--no-commit"]
+            option :no_push, desc: "Skip pushing task changes", type: :boolean, aliases: ["--no-push"]
+            option :no_upstream, desc: "Skip pushing with upstream tracking", type: :boolean, aliases: ["--no-upstream"]
+            option :no_pr, desc: "Skip creating draft PR", type: :boolean, aliases: ["--no-pr"]
+            option :push_remote, desc: "Remote to push to", aliases: []
+            option :no_auto_navigate, desc: "Stay in current directory", type: :boolean, aliases: ["--no-auto-navigate"]
+            option :commit_message, desc: "Custom commit message", aliases: []
+            option :target_branch, desc: "Override PR target branch (default: auto-detect from parent)", aliases: []
+            option :force, desc: "Create even if worktree exists", type: :boolean, aliases: []
+            option :quiet, type: :boolean, aliases: ["-q"], desc: "Suppress non-essential output"
+            option :verbose, type: :boolean, aliases: ["-v"], desc: "Show verbose output"
+            option :debug, type: :boolean, aliases: ["-d"], desc: "Show debug output"
+
+            def call(branch: nil, **options)
+              display_config_summary("create", options)
+
+              # Convert --from to --source for the underlying command
+              if options[:from]
+                options[:source] = options.delete(:from)
+              end
+
+              # Convert ace-support-cli options hash to args array format
+              args = options_to_args(options)
+              args << branch if branch
+
+              Ace::Git::Worktree::Commands::CreateCommand.new.run(args)
+            end
+          end
+        end
+      end
+    end
+  end
+end