worktrees 0.1.0

data/lib/worktrees/models/repository.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Worktrees
+  module Models
+    class Repository
+      attr_reader :root_path
+
+      def initialize(root_path)
+        @root_path = File.expand_path(root_path)
+        validate_git_repository!
+      end
+
+      def default_branch
+        git_default_branch
+      end
+
+      def branch_exists?(branch_name)
+        git_branch_exists?(branch_name)
+      end
+
+      def remote_url
+        git_remote_url
+      end
+
+      def worktrees_path
+        config.expand_worktrees_root
+      end
+
+      def config
+        @config ||= WorktreeConfig.load
+      end
+
+      private
+
+      def validate_git_repository!
+        git_dir = File.join(@root_path, '.git')
+        # .git can be either a directory (main repo) or a file (worktree)
+        unless File.exist?(git_dir)
+          raise GitError, "Not a git repository: #{@root_path}"
+        end
+      end
+
+      def git_default_branch
+        # Try to get default branch from remote HEAD
+        result = `cd "#{@root_path}" && git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null`.strip
+        if $?.success? && !result.empty?
+          return result.split('/').last
+        end
+
+        # Fallback: check if main exists, then master
+        if git_branch_exists?('main')
+          'main'
+        elsif git_branch_exists?('master')
+          'master'
+        else
+          # Use current branch as last resort
+          git_current_branch
+        end
+      end
+
+      def git_branch_exists?(branch_name)
+        system('git', 'show-ref', '--verify', '--quiet', "refs/heads/#{branch_name}", chdir: @root_path)
+      end
+
+      def git_current_branch
+        `cd "#{@root_path}" && git rev-parse --abbrev-ref HEAD`.strip
+      end
+
+      def git_remote_url
+        result = `cd "#{@root_path}" && git remote get-url origin 2>/dev/null`.strip
+        $?.success? && !result.empty? ? result : nil
+      end
+    end
+  end
+end

data/lib/worktrees/models/worktree_config.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'pathname'
+
+module Worktrees
+  module Models
+    class WorktreeConfig
+      DEFAULT_ROOT = '~/.worktrees'
+      NAME_PATTERN = /^[0-9]{3}-[a-z0-9-]{1,40}$/.freeze
+      RESERVED_NAMES = %w[main master].freeze
+
+      attr_reader :worktrees_root, :default_base, :force_cleanup, :name_pattern
+
+      def initialize(worktrees_root: DEFAULT_ROOT, default_base: nil, force_cleanup: false, name_pattern: NAME_PATTERN)
+        @worktrees_root = worktrees_root
+        @default_base = default_base
+        @force_cleanup = force_cleanup
+        @name_pattern = name_pattern
+      end
+
+      def self.load(config_path = default_config_path)
+        if File.exist?(config_path)
+          begin
+            config_data = YAML.load_file(config_path)
+            new(
+              worktrees_root: config_data['worktrees_root'] || DEFAULT_ROOT,
+              default_base: config_data['default_base'],
+              force_cleanup: config_data['force_cleanup'] || false,
+              name_pattern: config_data['name_pattern'] ? Regexp.new(config_data['name_pattern']) : NAME_PATTERN
+            )
+          rescue Psych::SyntaxError => e
+            raise Error, "Invalid configuration file #{config_path}: #{e.message}"
+          end
+        else
+          new
+        end
+      end
+
+      def self.default_config_path
+        File.join(Dir.home, '.worktrees', 'config.yml')
+      end
+
+      def valid_name?(name)
+        return false unless name.is_a?(String)
+        return false unless name.match?(@name_pattern)
+
+        # Extract feature part after NNN-
+        feature_part = name.split('-', 2)[1]
+        return false if feature_part.nil?
+
+        # Check for reserved names
+        !RESERVED_NAMES.include?(feature_part.downcase)
+      end
+
+      def expand_worktrees_root
+        if @worktrees_root.start_with?('~')
+          File.expand_path(@worktrees_root)
+        else
+          File.expand_path(@worktrees_root)
+        end
+      end
+
+      def to_h
+        {
+          worktrees_root: @worktrees_root,
+          default_base: @default_base,
+          force_cleanup: @force_cleanup,
+          name_pattern: @name_pattern.source
+        }
+      end
+    end
+  end
+end

data/lib/worktrees/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Worktrees
+  VERSION = '0.1.0'
+end

data/lib/worktrees/worktree_manager.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Worktrees
+  class WorktreeManager
+    attr_reader :repository, :config
+
+    def initialize(repository = nil, config = nil)
+      begin
+        repo_root = find_git_repository_root
+        @repository = repository || Models::Repository.new(repo_root)
+      rescue GitError => e
+        # Re-raise with more context if we're not in a git repo
+        raise GitError, "Not in a git repository. #{e.message}"
+      end
+      @config = config || Models::WorktreeConfig.load
+    end
+
+    def create_worktree(name, base_ref = nil, options = {})
+      # Validate arguments
+      raise ValidationError, 'Name is required' if name.nil?
+      raise ValidationError, 'Name cannot be empty' if name.empty?
+
+      # Use FeatureWorktree validation for better error messages
+      unless Models::FeatureWorktree.validate_name(name)
+        # Check what specific error to show
+        unless name.match?(Models::FeatureWorktree::NAME_PATTERN)
+          raise ValidationError, "Invalid name format '#{name}'. Names must match pattern: NNN-kebab-feature"
+        end
+        feature_part = name.split('-', 2)[1]
+        if feature_part && Models::FeatureWorktree::RESERVED_NAMES.include?(feature_part.downcase)
+          raise ValidationError, "Reserved name '#{feature_part}' not allowed in worktree names"
+        end
+      end
+
+      # Use default base if none provided
+      base_ref ||= @repository.default_branch
+
+      # Check if base reference exists
+      unless @repository.branch_exists?(base_ref)
+        raise GitError, "Base reference '#{base_ref}' not found"
+      end
+
+      # Check for duplicate worktree
+      existing = find_worktree(name)
+      if existing
+        raise ValidationError, "Worktree '#{name}' already exists"
+      end
+
+      # Create worktree path
+      worktree_path = File.join(@config.expand_worktrees_root, name)
+
+      # Create worktrees root directory if it doesn't exist
+      FileUtils.mkdir_p(@config.expand_worktrees_root)
+
+      # Create the worktree
+      unless GitOperations.create_worktree(worktree_path, name, base_ref)
+        raise GitError, "Failed to create worktree '#{name}'"
+      end
+
+      # Verify worktree was created
+      unless File.directory?(worktree_path)
+        raise FileSystemError, "Worktree directory was not created: #{worktree_path}"
+      end
+
+      # Return the created worktree
+      Models::FeatureWorktree.new(
+        name: name,
+        path: worktree_path,
+        branch: name,
+        base_ref: base_ref,
+        status: :clean,
+        created_at: Time.now,
+        repository_path: @repository.root_path
+      )
+    end
+
+    def list_worktrees(format: :objects, status: nil)
+      git_worktrees = GitOperations.list_worktrees
+      worktrees = []
+
+      git_worktrees.each do |git_wt|
+        next unless git_wt[:path] && File.directory?(git_wt[:path])
+
+        # Extract name from path
+        name = File.basename(git_wt[:path])
+        next unless @config.valid_name?(name)
+
+        # Determine status
+        wt_status = determine_status(git_wt[:path])
+
+        # Skip if status filter doesn't match
+        next if status && wt_status != status
+
+        worktree = Models::FeatureWorktree.new(
+          name: name,
+          path: git_wt[:path],
+          branch: git_wt[:branch] || name,
+          base_ref: detect_base_ref(git_wt[:branch] || name),
+          status: wt_status,
+          created_at: File.ctime(git_wt[:path]),
+          repository_path: @repository.root_path
+        )
+
+        worktrees << worktree
+      end
+
+      worktrees.sort_by(&:name)
+    end
+
+    def find_worktree(name)
+      worktrees = list_worktrees
+      worktrees.find { |wt| wt.name == name }
+    end
+
+    def switch_to_worktree(name)
+      worktree = find_worktree(name)
+      raise ValidationError, "Worktree '#{name}' not found" unless worktree
+
+      # Check current state for warnings
+      current = current_worktree
+      if current && current.dirty?
+        warn "Warning: Previous worktree '#{current.name}' has uncommitted changes"
+      end
+
+      # Change to worktree directory
+      Dir.chdir(worktree.path)
+      worktree
+    end
+
+    def remove_worktree(name, options = {})
+      worktree = find_worktree(name)
+      raise NotFoundError, "Worktree '#{name}' not found" unless worktree
+
+      # Safety checks
+      if worktree.active?
+        raise StateError, "Cannot remove active worktree '#{name}'. Switch to a different worktree first"
+      end
+
+      if worktree.dirty? && !options[:force_untracked]
+        raise StateError, "Worktree '#{name}' has uncommitted changes. Commit or stash changes, or use --force-untracked for untracked files only"
+      end
+
+      # Check for unpushed commits
+      if GitOperations.has_unpushed_commits?(worktree.branch)
+        raise StateError, "Worktree '#{name}' has unpushed commits. Push commits first or use --force"
+      end
+
+      # Remove the worktree
+      force = options[:force_untracked] || options[:force]
+      unless GitOperations.remove_worktree(worktree.path, force: force)
+        raise GitError, "Failed to remove worktree '#{name}'"
+      end
+
+      # Optionally delete branch
+      if options[:delete_branch]
+        if GitOperations.is_merged?(worktree.branch)
+          GitOperations.delete_branch(worktree.branch)
+        else
+          raise StateError, "Branch '#{worktree.branch}' is not fully merged. Use merge-base check or --force"
+        end
+      end
+
+      true
+    end
+
+    def current_worktree
+      current_path = Dir.pwd
+      worktrees = list_worktrees
+
+      worktrees.find do |worktree|
+        current_path.start_with?(worktree.path)
+      end
+    end
+
+    private
+
+    def find_git_repository_root
+      # Use git to find the main repository root (not worktree)
+      result = `git rev-parse --git-common-dir 2>/dev/null`.strip
+      if $?.success? && !result.empty?
+        # git-common-dir returns the .git directory, we need its parent
+        File.dirname(result)
+      else
+        # Fallback: try to find repository by walking up directories
+        current_dir = Dir.pwd
+        while current_dir != '/'
+          if File.exist?(File.join(current_dir, '.git'))
+            return current_dir
+          end
+          current_dir = File.dirname(current_dir)
+        end
+        # Last fallback
+        Dir.pwd
+      end
+    end
+
+    def determine_status(worktree_path)
+      # Check if this is the current worktree
+      current_path = Dir.pwd
+      is_current = current_path.start_with?(worktree_path)
+
+      # Check if worktree is clean
+      is_clean = GitOperations.is_clean?(worktree_path)
+
+      if is_current
+        :active
+      elsif is_clean
+        :clean
+      else
+        :dirty
+      end
+    rescue StandardError
+      :unknown
+    end
+
+    def detect_base_ref(branch_name)
+      # Try to determine base branch using git merge-base
+      default_branch = @repository.default_branch
+
+      # Use merge-base to find the best common ancestor
+      result = `git merge-base #{branch_name} #{default_branch} 2>/dev/null`.strip
+      if $?.success? && !result.empty?
+        return default_branch
+      end
+
+      # Fallback: if branch exists and default branch exists, assume default
+      if GitOperations.branch_exists?(branch_name) && GitOperations.branch_exists?(default_branch)
+        return default_branch
+      end
+
+      'unknown'
+    rescue StandardError
+      'unknown'
+    end
+  end
+end

data/lib/worktrees.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'worktrees/version'
+
+require_relative 'worktrees/models/feature_worktree'
+require_relative 'worktrees/models/repository'
+require_relative 'worktrees/models/worktree_config'
+
+require_relative 'worktrees/git_operations'
+require_relative 'worktrees/worktree_manager'
+
+require_relative 'worktrees/commands/create'
+require_relative 'worktrees/commands/list'
+require_relative 'worktrees/commands/switch'
+require_relative 'worktrees/commands/remove'
+require_relative 'worktrees/commands/status'
+
+require_relative 'worktrees/cli'
+
+module Worktrees
+  class Error < StandardError; end
+  class ValidationError < Error; end
+  class GitError < Error; end
+  class StateError < Error; end
+  class FileSystemError < Error; end
+  class NotFoundError < Error; end
+end

data/specs/001-build-a-tool/GEMINI.md

@@ -0,0 +1,20 @@
+# Gemini CLI Agent Context
+
+Use Gemini for broad codebase or multi-file analysis beyond Cursor context. Paths are absolute or relative to repo root.
+
+Examples:
+
+```bash
+gemini -p "@./ Summarize this project's structure and identify any existing Git tooling"
+
+gemini -p "@specs/001-build-a-tool/ @src/ Verify whether a worktrees CLI exists; if not, outline key modules"
+
+gemini -p "@specs/001-build-a-tool/contracts/ Analyze CLI contracts and propose test cases for bats"
+```
+
+Conventions:
+- Prefer `--all_files` when scanning the entire repo.
+- Use `@specs/001-build-a-tool/` to keep the feature context in view.
+- Keep prompts specific to contracts, data model, and quickstart to generate targeted insights.
+
+

data/specs/001-build-a-tool/contracts/cli-contracts.md

@@ -0,0 +1,43 @@
+# CLI Contracts: Manage Git feature worktrees
+
+All commands operate within a Git repository unless noted. Outputs default to human-readable text; `--format json` returns structured JSON. Errors/warnings go to stderr. Exit codes: 0 success, 2 validation error, 3 precondition failure, 4 conflict, 5 unsafe state, 6 not found.
+
+## worktrees create <NNN-kebab-feature>
+- Flags:
+  - `--base <ref>`: base reference; if omitted, auto-detect default base
+  - `--root <path>`: override global root (default `$HOME/.worktrees`)
+  - `--reuse-branch`: reuse existing local branch if present and not checked out
+  - `--sibling <suffix>`: create sibling branch if branch already checked out elsewhere
+  - `--format <text|json>`: output format
+- Behavior:
+  - Validates name against `^[0-9]{3}-[a-z0-9-]{1,40}$`; reserved names disallowed
+  - Auto-fetch base if remote-only; abort with guidance on fetch failure
+  - Prevent duplicate checkout; suggest existing worktree or `--sibling`
+  - Create worktree directory under root and checkout branch (create or reuse per rules)
+- Output (json): `{ name, branch, baseRef, path, active: true }`
+
+## worktrees list [--filter-name <substr>] [--filter-base <branch>] [--page N] [--page-size N]
+- Behavior: Lists known worktrees for current repository with paging
+- Output (json): `{ items: [ { name, branch, baseRef, path, active, isDirty, hasUnpushedCommits } ], page, pageSize, total }`
+
+## worktrees switch <name>
+- Behavior: Switches active working copy to the specified worktree; allowed even if current worktree is dirty; prints a warning summarizing dirty state
+- Output (json): `{ current: { name, path }, previous: { name, path }, warnings: [ ... ] }`
+
+## worktrees remove <name>
+- Flags:
+  - `--delete-branch`: also delete the associated branch if fully merged
+  - `--merged-into <base>`: base branch to verify full merge
+  - `--force`: allow deletion of untracked/ignored files only; tracked changes or ops in progress never allowed
+  - `--format <text|json>`
+- Behavior: Disallows removal if tracked changes, unpushed commits/no upstream, or operation in progress. Never deletes tags.
+- Output (json): `{ removed: true, branchDeleted: boolean }`
+
+## worktrees status
+- Behavior: Shows current worktree status: name, base reference (if known), path
+- Output (json): `{ name, baseRef, path }`
+
+## Global
+- `--help`, `--version`, `--format`, consistent across commands
+
+

data/specs/001-build-a-tool/contracts/openapi.yaml

@@ -0,0 +1,135 @@
+openapi: 3.1.0
+info:
+  title: Worktrees Management API (contract for CLI behaviors)
+  version: 0.1.0
+paths:
+  /worktrees:
+    get:
+      summary: List worktrees
+      parameters:
+        - in: query
+          name: filterName
+          schema: { type: string }
+        - in: query
+          name: filterBase
+          schema: { type: string }
+        - in: query
+          name: page
+          schema: { type: integer, minimum: 1, default: 1 }
+        - in: query
+          name: pageSize
+          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Worktree'
+                  page: { type: integer }
+                  pageSize: { type: integer }
+                  total: { type: integer }
+    post:
+      summary: Create a worktree
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [ name ]
+              properties:
+                name: { type: string }
+                base: { type: string }
+                root: { type: string }
+                reuseBranch: { type: boolean }
+                siblingSuffix: { type: string }
+      responses:
+        '201':
+          description: Created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Worktree'
+  /worktrees/{name}/switch:
+    post:
+      summary: Switch to a worktree by name
+      parameters:
+        - in: path
+          name: name
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  current: { $ref: '#/components/schemas/WorktreeRef' }
+                  previous: { $ref: '#/components/schemas/WorktreeRef' }
+                  warnings:
+                    type: array
+                    items: { type: string }
+  /worktrees/{name}:
+    delete:
+      summary: Remove a worktree
+      parameters:
+        - in: path
+          name: name
+          required: true
+          schema: { type: string }
+        - in: query
+          name: deleteBranch
+          schema: { type: boolean }
+        - in: query
+          name: mergedInto
+          schema: { type: string }
+        - in: query
+          name: force
+          schema: { type: boolean }
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  removed: { type: boolean }
+                  branchDeleted: { type: boolean }
+  /status:
+    get:
+      summary: Show current worktree status
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WorktreeRef'
+components:
+  schemas:
+    Worktree:
+      type: object
+      properties:
+        name: { type: string }
+        branch: { type: string }
+        baseRef: { type: string }
+        path: { type: string }
+        active: { type: boolean }
+        isDirty: { type: boolean }
+        hasUnpushedCommits: { type: boolean }
+    WorktreeRef:
+      type: object
+      properties:
+        name: { type: string }
+        path: { type: string }
+
+

data/specs/001-build-a-tool/data-model.md

@@ -0,0 +1,51 @@
+# Data Model: Manage Git feature worktrees
+
+## Entities
+
+### Repository
+- rootPath: absolute path to repo root
+- defaultBranch: name (detected from remote HEAD or `main`/`master`)
+- remotes: list of `{ name, url }`
+
+### FeatureName
+- value: string matching `^[0-9]{3}-[a-z0-9-]{1,40}$`
+- normalized: lowercase
+- reserved: boolean (true if `main` or `master`)
+
+### Worktree
+- name: FeatureName
+- branch: branch name (may equal `name`)
+- baseRef: reference name used to create/rebase
+- path: absolute filesystem path
+- isActive: boolean
+- checkedOut: boolean (branch checkout status)
+- upstream: optional remote tracking branch
+- hasUnpushedCommits: boolean
+- isDirty: boolean (tracked changes present)
+- hasUntracked: boolean
+- opInProgress: one of `none|merge|rebase|cherry-pick|bisect`
+
+### ListQuery
+- filterName: optional substring match (case-insensitive)
+- filterBase: optional base branch
+- page: integer ≥ 1 (default 1)
+- pageSize: integer (default 20, max 100)
+
+## Relationships
+- Repository has many Worktrees
+- Worktree belongs to a Repository
+- FeatureName is associated with Worktree.name and branch naming
+
+## Validation Rules
+- FeatureName must match `^[0-9]{3}-[a-z0-9-]{1,40}$` and be unique (case-insensitive) across existing worktrees.
+- Reserved names `main`, `master` are disallowed for FeatureName.
+- Branch reuse: if a local branch named FeatureName exists and is not checked out in any worktree → reuse; otherwise create.
+- Duplicate checkout: if branch is checked out in another worktree → disallow; offer selection or sibling creation via explicit flag.
+- Removal preconditions: disallow if tracked changes exist, op in progress, or unpushed commits/no upstream; allow `--force` only for untracked/ignored file deletion.
+- Branch deletion allowed only with explicit opt-in and only if fully merged into a specified base (merge-base ancestor check).
+
+## Derived State
+- activeWorktree: computed from `git worktree list --porcelain` current path
+- defaultBase: computed from repo remote HEAD → `main` → `master`
+
+