spec-kitty-cli 0.12.1__py3-none-any.whl

specify_cli/core/git_ops.py

@@ -0,0 +1,129 @@
+"""Git and subprocess helpers for the Spec Kitty CLI."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+from typing import Sequence
+
+from rich.console import Console
+
+ConsoleType = Console | None
+
+
+def _resolve_console(console: ConsoleType) -> Console:
+    """Return the provided console or lazily create one."""
+    return console if console is not None else Console()
+
+
+def run_command(
+    cmd: Sequence[str] | str,
+    *,
+    check_return: bool = True,
+    capture: bool = False,
+    shell: bool = False,
+    console: ConsoleType = None,
+    cwd: Path | str | None = None,
+) -> tuple[int, str, str]:
+    """Run a shell command and return (returncode, stdout, stderr).
+
+    Args:
+        cmd: Command to run
+        check_return: If True, raise on non-zero exit
+        capture: If True, capture stdout/stderr
+        shell: If True, run through shell
+        console: Rich console for output
+        cwd: Working directory for command execution
+
+    Returns:
+        Tuple of (returncode, stdout, stderr)
+    """
+    try:
+        result = subprocess.run(
+            cmd,
+            check=check_return,
+            capture_output=capture,
+            text=True,
+            shell=shell,
+            cwd=str(cwd) if cwd else None,
+        )
+        stdout = (result.stdout or "").strip() if capture else ""
+        stderr = (result.stderr or "").strip() if capture else ""
+        return result.returncode, stdout, stderr
+    except subprocess.CalledProcessError as exc:
+        if check_return:
+            resolved_console = _resolve_console(console)
+            resolved_console.print(f"[red]Error running command:[/red] {cmd if isinstance(cmd, str) else ' '.join(cmd)}")
+            resolved_console.print(f"[red]Exit code:[/red] {exc.returncode}")
+            if exc.stderr:
+                resolved_console.print(f"[red]Error output:[/red] {exc.stderr.strip()}")
+        raise
+
+
+def is_git_repo(path: Path | None = None) -> bool:
+    """Return True when the provided path lives inside a git repository."""
+    target = (path or Path.cwd()).resolve()
+    if not target.is_dir():
+        return False
+    try:
+        subprocess.run(
+            ["git", "rev-parse", "--is-inside-work-tree"],
+            check=True,
+            capture_output=True,
+            cwd=target,
+        )
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return False
+
+
+def init_git_repo(project_path: Path, quiet: bool = False, console: ConsoleType = None) -> bool:
+    """Initialize a git repository with an initial commit."""
+    resolved_console = _resolve_console(console)
+    original_cwd = Path.cwd()
+    try:
+        os.chdir(project_path)
+        if not quiet:
+            resolved_console.print("[cyan]Initializing git repository...[/cyan]")
+        subprocess.run(["git", "init"], check=True, capture_output=True)
+        subprocess.run(["git", "add", "."], check=True, capture_output=True)
+        subprocess.run(
+            ["git", "commit", "-m", "Initial commit from Specify template"],
+            check=True,
+            capture_output=True,
+        )
+        if not quiet:
+            resolved_console.print("[green]✓[/green] Git repository initialized")
+        return True
+    except subprocess.CalledProcessError as exc:
+        if not quiet:
+            resolved_console.print(f"[red]Error initializing git repository:[/red] {exc}")
+        return False
+    finally:
+        os.chdir(original_cwd)
+
+
+def get_current_branch(path: Path | None = None) -> str | None:
+    """Return the current git branch name for the provided repository path."""
+    repo_path = (path or Path.cwd()).resolve()
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            check=True,
+            capture_output=True,
+            text=True,
+            cwd=repo_path,
+        )
+        branch = result.stdout.strip()
+        return branch or None
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None
+
+
+__all__ = [
+    "get_current_branch",
+    "init_git_repo",
+    "is_git_repo",
+    "run_command",
+]

specify_cli/core/multi_parent_merge.py

@@ -0,0 +1,323 @@
+"""Multi-parent dependency handling via automatic merge commits.
+
+This module provides deterministic base branch calculation for work packages
+with multiple dependencies. Instead of forcing the user to pick one dependency
+as base and manually merge others, we automatically create a merge commit
+combining all dependencies.
+
+Example:
+    WP04 depends on both WP02 and WP03:
+
+    Before (ambiguous):
+        spec-kitty implement WP04 --base WP03  # Why WP03? Why not WP02?
+        cd .worktrees/010-feature-WP04/
+        git merge 010-feature-WP02  # Manual merge required
+
+    After (deterministic):
+        spec-kitty implement WP04  # Auto-detects multi-parent, creates merge
+        # WP04 branches from merge commit combining WP02 + WP03
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from rich.console import Console
+
+console = Console()
+
+
+@dataclass
+class MergeResult:
+    """Result of creating a multi-parent merge base."""
+
+    success: bool
+    branch_name: str | None  # Temporary branch name (e.g., "010-feature-WP04-merge-base")
+    commit_sha: str | None  # SHA of merge commit
+    error: str | None  # Error message if failed
+    conflicts: list[str]  # List of files with conflicts (if any)
+
+
+def create_multi_parent_base(
+    feature_slug: str,
+    wp_id: str,
+    dependencies: list[str],
+    repo_root: Path,
+) -> MergeResult:
+    """Create a merge commit combining all dependencies for a work package.
+
+    This function:
+    1. Creates a temporary branch from the first dependency
+    2. Merges all remaining dependencies into it
+    3. Returns the merge commit SHA for use as base branch
+
+    Args:
+        feature_slug: Feature slug (e.g., "010-workspace-per-wp")
+        wp_id: Work package ID (e.g., "WP04")
+        dependencies: List of dependency WP IDs (e.g., ["WP02", "WP03"])
+        repo_root: Repository root path
+
+    Returns:
+        MergeResult with success status and merge commit details
+
+    Example:
+        result = create_multi_parent_base(
+            feature_slug="010-feature",
+            wp_id="WP04",
+            dependencies=["WP02", "WP03"],
+            repo_root=Path("."),
+        )
+        if result.success:
+            # Branch WP04 from result.branch_name or result.commit_sha
+            print(f"Merge base: {result.commit_sha}")
+    """
+    if len(dependencies) < 2:
+        return MergeResult(
+            success=False,
+            branch_name=None,
+            commit_sha=None,
+            error="Multi-parent merge requires at least 2 dependencies",
+            conflicts=[],
+        )
+
+    # Sort dependencies for deterministic ordering
+    sorted_deps = sorted(dependencies)
+
+    # Temporary branch name
+    temp_branch = f"{feature_slug}-{wp_id}-merge-base"
+
+    # Dependency branch names
+    dep_branches = [f"{feature_slug}-{dep}" for dep in sorted_deps]
+
+    try:
+        # Step 1: Validate all dependency branches exist
+        for dep, branch in zip(sorted_deps, dep_branches):
+            result = subprocess.run(
+                ["git", "rev-parse", "--verify", branch],
+                cwd=repo_root,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if result.returncode != 0:
+                return MergeResult(
+                    success=False,
+                    branch_name=None,
+                    commit_sha=None,
+                    error=f"Dependency branch {branch} does not exist (implement {dep} first)",
+                    conflicts=[],
+                )
+
+        # Step 2: Check if temp branch already exists (cleanup from previous run)
+        result = subprocess.run(
+            ["git", "rev-parse", "--verify", temp_branch],
+            cwd=repo_root,
+            capture_output=True,
+            check=False,
+        )
+        if result.returncode == 0:
+            # Delete existing temp branch
+            subprocess.run(
+                ["git", "branch", "-D", temp_branch],
+                cwd=repo_root,
+                capture_output=True,
+                check=False,
+            )
+
+        # Step 3: Create temp branch from first dependency
+        base_branch = dep_branches[0]
+        result = subprocess.run(
+            ["git", "branch", temp_branch, base_branch],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            return MergeResult(
+                success=False,
+                branch_name=None,
+                commit_sha=None,
+                error=f"Failed to create temp branch from {base_branch}: {result.stderr}",
+                conflicts=[],
+            )
+
+        # Step 4: Checkout temp branch
+        result = subprocess.run(
+            ["git", "checkout", temp_branch],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            return MergeResult(
+                success=False,
+                branch_name=None,
+                commit_sha=None,
+                error=f"Failed to checkout temp branch: {result.stderr}",
+                conflicts=[],
+            )
+
+        # Step 5: Merge remaining dependencies
+        conflicts = []
+        for dep_branch in dep_branches[1:]:
+            result = subprocess.run(
+                ["git", "merge", "--no-edit", dep_branch, "-m",
+                 f"Merge {dep_branch} into multi-parent base for {wp_id}"],
+                cwd=repo_root,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+
+            if result.returncode != 0:
+                # Check if merge conflicts
+                conflict_result = subprocess.run(
+                    ["git", "diff", "--name-only", "--diff-filter=U"],
+                    cwd=repo_root,
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                )
+                if conflict_result.returncode == 0 and conflict_result.stdout.strip():
+                    conflicts = conflict_result.stdout.strip().split("\n")
+
+                # Abort merge
+                subprocess.run(
+                    ["git", "merge", "--abort"],
+                    cwd=repo_root,
+                    capture_output=True,
+                    check=False,
+                )
+
+                # Cleanup: delete temp branch
+                subprocess.run(
+                    ["git", "checkout", "-"],  # Return to previous branch
+                    cwd=repo_root,
+                    capture_output=True,
+                    check=False,
+                )
+                subprocess.run(
+                    ["git", "branch", "-D", temp_branch],
+                    cwd=repo_root,
+                    capture_output=True,
+                    check=False,
+                )
+
+                return MergeResult(
+                    success=False,
+                    branch_name=None,
+                    commit_sha=None,
+                    error=f"Merge conflict when merging {dep_branch}",
+                    conflicts=conflicts,
+                )
+
+        # Step 6: Get merge commit SHA
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            return MergeResult(
+                success=False,
+                branch_name=temp_branch,
+                commit_sha=None,
+                error="Failed to get merge commit SHA",
+                conflicts=[],
+            )
+
+        merge_commit_sha = result.stdout.strip()
+
+        # Step 7: Return to previous branch
+        subprocess.run(
+            ["git", "checkout", "-"],
+            cwd=repo_root,
+            capture_output=True,
+            check=False,
+        )
+
+        console.print(f"[cyan]→ Created merge base: {temp_branch} ({merge_commit_sha[:7]})[/cyan]")
+        console.print(f"[cyan]  Combined dependencies: {', '.join(sorted_deps)}[/cyan]")
+
+        return MergeResult(
+            success=True,
+            branch_name=temp_branch,
+            commit_sha=merge_commit_sha,
+            error=None,
+            conflicts=[],
+        )
+
+    except Exception as e:
+        # Cleanup on exception
+        subprocess.run(
+            ["git", "checkout", "-"],
+            cwd=repo_root,
+            capture_output=True,
+            check=False,
+        )
+        subprocess.run(
+            ["git", "branch", "-D", temp_branch],
+            cwd=repo_root,
+            capture_output=True,
+            check=False,
+        )
+
+        return MergeResult(
+            success=False,
+            branch_name=None,
+            commit_sha=None,
+            error=f"Unexpected error: {e}",
+            conflicts=[],
+        )
+
+
+def cleanup_merge_base_branch(
+    feature_slug: str,
+    wp_id: str,
+    repo_root: Path,
+) -> bool:
+    """Delete temporary merge base branch after workspace creation.
+
+    Args:
+        feature_slug: Feature slug (e.g., "010-workspace-per-wp")
+        wp_id: Work package ID (e.g., "WP04")
+        repo_root: Repository root path
+
+    Returns:
+        True if deleted, False if branch didn't exist
+    """
+    temp_branch = f"{feature_slug}-{wp_id}-merge-base"
+
+    # Check if branch exists
+    result = subprocess.run(
+        ["git", "rev-parse", "--verify", temp_branch],
+        cwd=repo_root,
+        capture_output=True,
+        check=False,
+    )
+
+    if result.returncode != 0:
+        return False  # Branch doesn't exist
+
+    # Delete branch
+    result = subprocess.run(
+        ["git", "branch", "-D", temp_branch],
+        cwd=repo_root,
+        capture_output=True,
+        check=False,
+    )
+
+    return result.returncode == 0
+
+
+__all__ = [
+    "MergeResult",
+    "create_multi_parent_base",
+    "cleanup_merge_base_branch",
+]

specify_cli/core/paths.py

@@ -0,0 +1,260 @@
+"""Enhanced path resolution for spec-kitty CLI with worktree detection."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+from typing import Optional, Tuple
+
+
+def locate_project_root(start: Path | None = None) -> Optional[Path]:
+    """
+    Locate the MAIN spec-kitty project root directory, even from within worktrees.
+
+    This function correctly handles git worktrees by detecting when .git is a
+    file (worktree pointer) vs a directory (main repo), and following the
+    pointer back to the main repository.
+
+    Resolution order:
+    1. SPECIFY_REPO_ROOT environment variable (highest priority)
+    2. Walk up directory tree, detecting worktree .git files and following to main repo
+    3. Fall back to .kittify/ marker search
+
+    Args:
+        start: Starting directory for search (defaults to current working directory)
+
+    Returns:
+        Path to MAIN project root (not worktree), or None if not found
+
+    Examples:
+        >>> # From main repo
+        >>> root = locate_project_root()
+        >>> assert (root / ".kittify").exists()
+
+        >>> # From worktree - returns MAIN repo, not worktree
+        >>> root = locate_project_root(Path(".worktrees/my-feature"))
+        >>> assert ".worktrees" not in str(root)
+    """
+    # Tier 1: Check environment variable (allows override for CI/CD)
+    if env_root := os.getenv("SPECIFY_REPO_ROOT"):
+        env_path = Path(env_root).resolve()
+        if env_path.exists() and (env_path / ".kittify").is_dir():
+            return env_path
+        # Invalid env var - fall through to other methods
+
+    # Tier 2: Walk up directory tree, handling worktree .git files
+    current = (start or Path.cwd()).resolve()
+
+    for candidate in [current, *current.parents]:
+        git_path = candidate / ".git"
+
+        if git_path.is_file():
+            # This is a worktree! The .git file contains a pointer to the main repo.
+            # Format: "gitdir: /path/to/main/.git/worktrees/worktree-name"
+            try:
+                content = git_path.read_text().strip()
+                if content.startswith("gitdir:"):
+                    gitdir = Path(content.split(":", 1)[1].strip())
+                    # Navigate: .git/worktrees/name -> .git -> main repo root
+                    main_git_dir = gitdir.parent.parent
+                    main_repo = main_git_dir.parent
+                    if main_repo.exists() and (main_repo / ".kittify").is_dir():
+                        return main_repo
+            except (OSError, ValueError):
+                # If we can't read or parse the .git file, continue searching
+                pass
+
+        elif git_path.is_dir():
+            # This is the main repo (or a regular git repo)
+            if (candidate / ".kittify").is_dir():
+                return candidate
+
+        # Also check for .kittify marker (fallback for non-git scenarios)
+        kittify_path = candidate / ".kittify"
+        if kittify_path.is_symlink() and not kittify_path.exists():
+            # Broken symlink - skip this candidate
+            continue
+        if kittify_path.is_dir():
+            return candidate
+
+    return None
+
+
+def is_worktree_context(path: Path) -> bool:
+    """
+    Detect if the given path is within a git worktree directory.
+
+    Checks if '.worktrees' appears in the path hierarchy, indicating
+    execution from within a feature worktree.
+
+    Args:
+        path: Path to check (typically current working directory)
+
+    Returns:
+        True if path is within .worktrees/ directory, False otherwise
+
+    Examples:
+        >>> is_worktree_context(Path("/repo/.worktrees/feature-001"))
+        True
+        >>> is_worktree_context(Path("/repo/kitty-specs"))
+        False
+    """
+    return ".worktrees" in path.parts
+
+
+def resolve_with_context(start: Path | None = None) -> Tuple[Optional[Path], bool]:
+    """
+    Resolve project root and detect worktree context in one call.
+
+    Args:
+        start: Starting directory for search (defaults to current working directory)
+
+    Returns:
+        Tuple of (project_root, is_worktree)
+        - project_root: Path to repo root or None if not found
+        - is_worktree: True if executing from within .worktrees/
+
+    Examples:
+        >>> # From main repo
+        >>> root, in_worktree = resolve_with_context()
+        >>> assert in_worktree is False
+
+        >>> # From worktree
+        >>> root, in_worktree = resolve_with_context(Path(".worktrees/my-feature"))
+        >>> assert in_worktree is True
+    """
+    current = (start or Path.cwd()).resolve()
+    root = locate_project_root(current)
+    in_worktree = is_worktree_context(current)
+    return root, in_worktree
+
+
+def check_broken_symlink(path: Path) -> bool:
+    """
+    Check if a path is a broken symlink (symlink pointing to non-existent target).
+
+    This helper is useful for graceful error handling when dealing with
+    worktree symlinks that may become invalid.
+
+    Args:
+        path: Path to check
+
+    Returns:
+        True if path is a broken symlink, False otherwise
+
+    Note:
+        A broken symlink returns True for is_symlink() but False for exists().
+        Always check is_symlink() before exists() to detect this condition.
+    """
+    return path.is_symlink() and not path.exists()
+
+
+def get_main_repo_root(current_path: Path) -> Path:
+    """
+    Get the main repository root, even if called from a worktree.
+
+    When in a worktree, .git is a file pointing to the main repo's .git directory.
+    This function follows that pointer to find the main repo root.
+
+    Args:
+        current_path: Current repo root (may be worktree or main repo)
+
+    Returns:
+        Path to the main repository root (resolves worktree pointers)
+
+    Examples:
+        >>> # From main repo - returns same path
+        >>> get_main_repo_root(Path("/repo"))
+        Path('/repo')
+
+        >>> # From worktree - returns main repo
+        >>> get_main_repo_root(Path("/repo/.worktrees/feature-001"))
+        Path('/repo')
+    """
+    git_file = current_path / ".git"
+
+    if git_file.is_file():
+        try:
+            git_content = git_file.read_text().strip()
+            if git_content.startswith("gitdir:"):
+                gitdir = Path(git_content.split(":", 1)[1].strip())
+                # Navigate: .git/worktrees/name -> .git -> main repo root
+                main_git_dir = gitdir.parent.parent
+                main_repo_root = main_git_dir.parent
+                return main_repo_root
+        except (OSError, ValueError):
+            pass
+
+    return current_path
+
+
+def find_feature_slug(repo_root: Path) -> Optional[str]:
+    """
+    Auto-detect feature slug from git branch or highest-numbered feature in kitty-specs.
+
+    Detection strategies (in order):
+    1. Git branch name matching pattern ###-slug (strips -WPxx suffix)
+    2. Highest-numbered directory in kitty-specs/
+
+    Args:
+        repo_root: Repository root path (can be worktree or main repo)
+
+    Returns:
+        Feature slug (e.g., "016-jujutsu-vcs-documentation") or None if not found
+
+    Examples:
+        >>> find_feature_slug(Path("/repo"))
+        '016-jujutsu-vcs-documentation'
+    """
+    import re
+
+    # Get main repo root for kitty-specs access
+    main_repo_root = get_main_repo_root(repo_root)
+
+    # Strategy 1: Get from git branch name
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        branch_name = result.stdout.strip()
+
+        # Strip -WPxx suffix if present (worktree branches)
+        branch_name = re.sub(r'-WP\d+$', '', branch_name)
+
+        # Validate format: ###-slug
+        if len(branch_name) >= 3 and branch_name[:3].isdigit():
+            return branch_name
+
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        pass
+
+    # Strategy 2: Auto-detect highest-numbered feature in kitty-specs
+    kitty_specs_dir = main_repo_root / "kitty-specs"
+    if kitty_specs_dir.is_dir():
+        candidates = []
+        for path in kitty_specs_dir.iterdir():
+            if not path.is_dir():
+                continue
+            match = re.match(r"^(\d{3})-", path.name)
+            if match:
+                candidates.append((int(match.group(1)), path.name))
+        if candidates:
+            _, slug = max(candidates, key=lambda item: item[0])
+            return slug
+
+    return None
+
+
+__all__ = [
+    "locate_project_root",
+    "is_worktree_context",
+    "resolve_with_context",
+    "check_broken_symlink",
+    "get_main_repo_root",
+    "find_feature_slug",
+]