feat(git): add git_worktree_add to lean interface (#167)

[MementoRC]

Summary

The lean git MCP interface exposed git_worktree_list and git_worktree_remove but was missing git_worktree_add. This blocked any workflow that needed to commit on a different branch without disturbing the current working tree — for example, adding a submodule on a configuration branch while WIP exists on a fix branch — forcing agents to fall back to shell-exec MCPs in violation of the "no Bash for git" principle.

Signature

def git_worktree_add(
    repo: Repo,
    worktree_path: str,
    branch: str | None = None,        # Existing branch to check out
    new_branch: str | None = None,    # NEW branch to create (-b, or -B if force=True)
    force: bool = False,              # Adds --force; upgrades -b to -B when new_branch set
) -> str:

Behavior Matrix

new_branch	branch	force	git command
None	None	False	git worktree add <wt_path> (detached HEAD)
None	"main"	False	git worktree add <wt_path> main
None	None/"main"	True	adds --force to the above
"feature"	None	False	git worktree add -b feature <wt_path>
"feature"	"main"	False	git worktree add -b feature <wt_path> main
"feature"	*	True	uses -B feature (force-create) AND adds --force

Changes

• src/mcp_server_git/git/operations_extended.py - git_worktree_add implementation with input validation (DANGEROUS_CHARS) and error handling matching the existing worktree functions
• src/mcp_server_git/git/models.py - GitWorktreeAdd Pydantic model
• src/mcp_server_git/lean/registry_git.py - tool registration (imports + ToolDefinition)
• tests/unit/git/test_git_worktree.py - TestGitWorktreeAdd with 8 tests covering all four behavior paths, input validation rejection, and error handling

Test Coverage

• test_worktree_add_detached_head - no branch/new_branch -> bare add <path>
• test_worktree_add_existing_branch - branch='main' -> add <path> main
• test_worktree_add_new_branch - new_branch='feature' -> uses -b, not -B
• test_worktree_add_force_new_branch_uses_B - force + new_branch -> -B + --force
• test_worktree_add_new_branch_with_start_point - new_branch + branch -> creates from start-point
• test_worktree_add_rejects_dangerous_chars_in_worktree_path - injection guard
• test_worktree_add_handles_git_command_error - GitCommandError handling
• test_worktree_add_handles_general_exception - generic exception handling

Closes #167

[github-actions]

Claude finished @MementoRC's task —— View job

---

PR Review: git_worktree_add Implementation

Todo List:

• Read repository guidelines (CLAUDE.md)
• Review core implementation in operations_extended.py
• Review data model in models.py
• Review tool registration in registry_git.py
• Review test coverage and quality
• Analyze security considerations
• Check performance implications
• Provide comprehensive feedback

Review Summary ✅

This is a well-implemented feature that adds the missing git_worktree_add functionality to complete the worktree operations suite. The implementation demonstrates excellent attention to detail, follows established patterns, and provides comprehensive test coverage.

Code Quality: Excellent ⭐⭐⭐⭐⭐

✅ Strengths

1. Perfect Pattern Consistency

• Follows identical patterns to existing git_worktree_list and git_worktree_remove functions
• Uses the same DANGEROUS_CHARS validation, error handling, and return message formats
• Consistent wrap_repo_op integration in registry matches other tools
• Maintains the same complexity classification ("focused") as peer functions

2. Robust Input Validation

• operations_extended.py:190-195: Validates all three string inputs (worktree_path, branch, new_branch) against DANGEROUS_CHARS regex
• Prevents command injection attacks through proper input sanitization
• Early validation returns with clear error messages before any git operations

3. Comprehensive Test Coverage

• 8 test methods covering all behavioral paths from the spec matrix
• Input validation tests with parameterized dangerous characters
• Both GitCommandError and generic exception handling
• Tests verify exact git command arguments match expected behavior

4. Clear API Design

• models.py:280-299: Well-documented Pydantic model with field descriptions
• Intuitive parameter names that map directly to git worktree semantics
• Optional parameters with sensible defaults

5. Excellent Error Handling

• operations_extended.py:219-223: Handles both GitCommandError and generic exceptions
• Proper stderr decoding (handles both bytes and string formats)
• User-friendly error messages with ❌ prefix matching repository conventions

⚠️ Minor Observations

1. Branch Validation Logic (operations_extended.py:192-194)

if branch and DANGEROUS_CHARS.search(branch):
if new_branch and DANGEROUS_CHARS.search(new_branch):

The conditional validation is correct since these parameters are optional, but consider documenting why worktree_path validation is unconditional while branch validations are conditional.

2. Force Flag Behavior
The force flag serves dual purposes (git --force + -B upgrade), which is appropriate but could benefit from a docstring comment explaining this behavior.

Security: Excellent 🔒

• ✅ Input sanitization prevents command injection
• ✅ Uses the same DANGEROUS_CHARS pattern as peer functions
• ✅ No hardcoded paths or unsafe string concatenation
• ✅ Validation occurs before any git operations

Performance: Optimal ⚡

• ✅ Single git command execution
• ✅ No unnecessary validations or operations
• ✅ Efficient argument building without string concatenation
• ✅ Early validation prevents expensive git operations on invalid input

Test Coverage: Comprehensive 🧪

The test suite covers:

• ✅ All 4 behavioral matrix combinations
• ✅ Input validation edge cases
• ✅ Error handling (both GitCommandError types and generic exceptions)
• ✅ Command argument verification
• ✅ Return message format validation

Test quality highlights:

• test_git_worktree.py:287-300: Excellent verification of force flag behavior (confirms -B instead of -b)
• test_git_worktree.py:316-325: Proper injection prevention testing
• Mock usage is appropriate and focused

Architecture Integration: Perfect 🏗️

• ✅ Seamless integration with existing MCP lean interface
• ✅ Proper tool registration in registry_git.py:474-481
• ✅ Follows established complexity classification ("focused")
• ✅ Consistent with worktree operations family

Documentation: Good 📚

The implementation includes:

• ✅ Clear docstring explaining the 4 operation modes
• ✅ Reference to issue [gap] git_worktree_add missing from lean git interface #167 for context
• ✅ Detailed field descriptions in Pydantic model

Recommendations

1. Consider enhancing the docstring to explain the dual nature of the force parameter:

"""Create a new linked worktree at `worktree_path`.

Args:
    force: Adds --force to git command. When combined with new_branch, 
           upgrades -b to -B (force branch creation).
"""

2. Optional: Add a docstring comment explaining the conditional branch validation pattern for future maintainers.

Final Assessment

This PR represents excellent engineering practices with:

• ✅ Complete API coverage (closes the worktree functionality gap)
• ✅ Security-conscious implementation
• ✅ Comprehensive test coverage
• ✅ Perfect integration with existing codebase patterns
• ✅ Clear documentation and error handling

Recommendation: APPROVE

The implementation is production-ready and maintains the high quality standards of the existing codebase.

---

[github-actions]

Claude finished @MementoRC's task —— View job

---

PR Review: git_worktree_add Implementation ✅

Todo List:

• Read repository guidelines (CLAUDE.md)
• Review core implementation in operations_extended.py
• Review data model in models.py
• Review tool registration in registry_git.py
• Review test coverage and quality
• Analyze security considerations
• Check performance implications
• Provide comprehensive feedback

Review Summary ✅

This is a well-implemented feature that adds the missing git_worktree_add functionality to complete the worktree operations suite. The implementation demonstrates excellent attention to detail, follows established patterns, and provides comprehensive test coverage.

Code Quality: Excellent ⭐⭐⭐⭐⭐

✅ Strengths

1. Perfect Pattern Consistency

• Follows identical patterns to existing git_worktree_list and git_worktree_remove functions
• Uses the same DANGEROUS_CHARS validation, error handling, and return message formats
• Consistent wrap_repo_op integration in registry matches other tools
• Maintains the same complexity classification ("focused") as peer functions

2. Robust Input Validation

• operations_extended.py:190-195: Validates all three string inputs (worktree_path, branch, new_branch) against DANGEROUS_CHARS regex
• Prevents command injection attacks through proper input sanitization
• Early validation returns with clear error messages before any git operations

3. Comprehensive Test Coverage

• 8 test methods covering all behavioral paths from the spec matrix
• Input validation tests with parameterized dangerous characters
• Both GitCommandError and generic exception handling
• Tests verify exact git command arguments match expected behavior

4. Clear API Design

• models.py:280-299: Well-documented Pydantic model with field descriptions
• Intuitive parameter names that map directly to git worktree semantics
• Optional parameters with sensible defaults

5. Excellent Error Handling

• operations_extended.py:219-223: Handles both GitCommandError and generic exceptions
• Proper stderr decoding (handles both bytes and string formats)
• User-friendly error messages with ❌ prefix matching repository conventions

⚠️ Minor Observations

1. Branch Validation Logic (operations_extended.py:192-194)

if branch and DANGEROUS_CHARS.search(branch):
if new_branch and DANGEROUS_CHARS.search(new_branch):

The conditional validation is correct since these parameters are optional, but consider documenting why worktree_path validation is unconditional while branch validations are conditional.

2. Force Flag Behavior
The force flag serves dual purposes (git --force + -B upgrade), which is appropriate but could benefit from a docstring comment explaining this behavior.

Security: Excellent 🔒

• ✅ Input sanitization prevents command injection
• ✅ Uses the same DANGEROUS_CHARS pattern as peer functions
• ✅ No hardcoded paths or unsafe string concatenation
• ✅ Validation occurs before any git operations

Performance: Optimal ⚡

• ✅ Single git command execution
• ✅ No unnecessary validations or operations
• ✅ Efficient argument building without string concatenation
• ✅ Early validation prevents expensive git operations on invalid input

Test Coverage: Comprehensive 🧪

The test suite covers:

• ✅ All 4 behavioral matrix combinations
• ✅ Input validation edge cases
• ✅ Error handling (both GitCommandError types and generic exceptions)
• ✅ Command argument verification
• ✅ Return message format validation

Test quality highlights:

• test_git_worktree.py:287-300: Excellent verification of force flag behavior (confirms -B instead of -b)
• test_git_worktree.py:316-325: Proper injection prevention testing
• Mock usage is appropriate and focused

Architecture Integration: Perfect 🏗️

• ✅ Seamless integration with existing MCP lean interface
• ✅ Proper tool registration in registry_git.py:474-481
• ✅ Follows established complexity classification ("focused")
• ✅ Consistent with worktree operations family

Documentation: Good 📚

The implementation includes:

• ✅ Clear docstring explaining the 4 operation modes
• ✅ Reference to issue [gap] git_worktree_add missing from lean git interface #167 for context
• ✅ Detailed field descriptions in Pydantic model

Recommendations

1. Consider enhancing the docstring to explain the dual nature of the force parameter:

"""Create a new linked worktree at `worktree_path`.

Args:
    force: Adds --force to git command. When combined with new_branch, 
           upgrades -b to -B (force branch creation).
"""

2. Optional: Add a docstring comment explaining the conditional branch validation pattern for future maintainers.

Final Assessment

This PR represents excellent engineering practices with:

• ✅ Complete API coverage (closes the worktree functionality gap)
• ✅ Security-conscious implementation
• ✅ Comprehensive test coverage
• ✅ Perfect integration with existing codebase patterns
• ✅ Clear documentation and error handling

Recommendation: APPROVE

The implementation is production-ready and maintains the high quality standards of the existing codebase.

---