gitstow 0.1.0__py3-none-any.whl

gitstow/cli/setup_ai.py

@@ -0,0 +1,247 @@
+"""gitstow setup-ai — detect and configure AI tool integrations.
+
+This is the AI-first onboarding path. gitstow's primary interface is through
+AI tools (Claude Code, Claude Desktop, Cursor, etc.), so this setup should
+be part of the default installation flow, not an afterthought.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+import typer
+from beaupy import confirm as bconfirm
+from rich.console import Console
+from rich.panel import Panel
+
+console = Console()
+err_console = Console(stderr=True)
+
+# Known AI tool config locations
+CLAUDE_CODE_DIR = Path.home() / ".claude"
+CLAUDE_CODE_SKILLS = CLAUDE_CODE_DIR / "skills"
+
+# Claude Desktop config paths (macOS, Linux, Windows)
+CLAUDE_DESKTOP_CONFIGS = [
+    Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json",  # macOS
+    Path.home() / ".config" / "claude" / "claude_desktop_config.json",  # Linux
+    Path.home() / "AppData" / "Roaming" / "Claude" / "claude_desktop_config.json",  # Windows
+]
+
+# Cursor MCP config
+CURSOR_CONFIG = Path.home() / ".cursor" / "mcp.json"
+
+# Generic .mcp.json in home (some tools use this)
+HOME_MCP_CONFIG = Path.home() / ".mcp.json"
+
+
+def setup_ai(
+    auto: bool = typer.Option(
+        False, "--auto", "-a", help="Auto-configure everything without prompts.",
+    ),
+    quiet: bool = typer.Option(
+        False, "--quiet", "-q", help="Suppress output.",
+    ),
+) -> None:
+    """[bold]Set up AI integrations[/bold] — Claude Code skill, MCP server for Claude Desktop, Cursor, etc.
+
+    Detects which AI tools are installed and configures gitstow for each.
+    This is the recommended post-install step — gitstow is designed to be
+    used primarily through AI tools.
+
+    \b
+    Examples:
+      gitstow setup-ai              # Interactive setup
+      gitstow setup-ai --auto       # Auto-configure everything detected
+    """
+    if not quiet:
+        console.print(Panel(
+            "[bold]AI Integration Setup[/bold]\n\n"
+            "gitstow is designed to be used primarily through AI tools.\n"
+            "The Claude Code skill is the recommended integration (zero\n"
+            "context overhead, auto-updates). MCP is optional for tools\n"
+            "that don't support Claude Code skills.",
+            border_style="cyan",
+            padding=(1, 2),
+        ))
+        console.print()
+
+    detected = _detect_ai_tools()
+
+    if not detected and not quiet:
+        console.print("  [dim]No AI tools detected. You can still use gitstow from the terminal.[/dim]")
+        console.print("  [dim]Re-run this command after installing an AI tool.[/dim]\n")
+        return
+
+    if not quiet:
+        console.print(f"  [bold]Detected {len(detected)} AI tool{'s' if len(detected) != 1 else ''}:[/bold]\n")
+        for tool in detected:
+            console.print(f"    [green]✓[/green] {tool['name']}")
+        console.print()
+
+    # Always configure Claude Code skill first (primary integration)
+    claude_code = [t for t in detected if t["type"] == "claude_code"]
+    mcp_tools = [t for t in detected if t["type"] == "mcp_config"]
+
+    for tool in claude_code:
+        _setup_claude_code(auto=auto, quiet=quiet)
+
+    # Offer MCP for non-Claude-Code tools with clear context warning
+    if mcp_tools:
+        if not quiet:
+            console.print()
+            console.print("  [bold]MCP Server[/bold] (optional, for non-Claude-Code tools)")
+            console.print("  [dim]Warning: MCP tools are always loaded into context,")
+            console.print("  costing tokens even when you're not managing repos.[/dim]")
+            console.print("  [dim]The Claude Code skill has zero overhead when inactive.[/dim]")
+            console.print()
+        for tool in mcp_tools:
+            _setup_mcp_config(tool["path"], tool["name"], auto=auto, quiet=quiet)
+
+    if not quiet:
+        console.print("  [bold green]AI setup complete.[/bold green]\n")
+
+
+def _detect_ai_tools() -> list[dict]:
+    """Detect which AI tools are installed on this machine."""
+    detected = []
+
+    # Claude Code
+    if CLAUDE_CODE_DIR.exists():
+        detected.append({
+            "name": "Claude Code",
+            "type": "claude_code",
+            "path": str(CLAUDE_CODE_DIR),
+        })
+
+    # Claude Desktop
+    for config_path in CLAUDE_DESKTOP_CONFIGS:
+        if config_path.parent.exists():
+            detected.append({
+                "name": "Claude Desktop",
+                "type": "mcp_config",
+                "path": str(config_path),
+            })
+            break  # Only one Claude Desktop per machine
+
+    # Cursor
+    if CURSOR_CONFIG.parent.exists():
+        detected.append({
+            "name": "Cursor",
+            "type": "mcp_config",
+            "path": str(CURSOR_CONFIG),
+        })
+
+    return detected
+
+
+def _setup_claude_code(auto: bool = False, quiet: bool = False) -> None:
+    """Install the Claude Code skill."""
+    from gitstow.cli.skill_cmd import _do_install_skill
+
+    skill_path = CLAUDE_CODE_SKILLS / "gitstow" / "SKILL.md"
+    already_installed = skill_path.exists()
+
+    if already_installed and not quiet:
+        console.print("  [dim]Claude Code skill already installed.[/dim]")
+
+    if not already_installed or auto:
+        if auto or bconfirm("  Install Claude Code skill?", default_is_yes=True):
+            _do_install_skill(quiet=quiet)
+    elif not quiet:
+        reinstall = bconfirm("  Reinstall Claude Code skill (update)?", default_is_yes=False)
+        if reinstall:
+            _do_install_skill(quiet=quiet)
+
+
+def _setup_mcp_config(config_path: str, tool_name: str, auto: bool = False, quiet: bool = False) -> None:
+    """Add gitstow MCP server to an AI tool's config."""
+    path = Path(config_path)
+
+    # Check if gitstow-mcp is available
+    mcp_bin = shutil.which("gitstow-mcp")
+    if not mcp_bin:
+        if not quiet:
+            console.print("  [yellow]⚠[/yellow] gitstow-mcp not found on PATH.")
+            console.print("    Install with: [bold]pip install gitstow[mcp][/bold]")
+        return
+
+    # Check if already configured
+    already_configured = False
+    existing_config = {}
+    if path.exists():
+        try:
+            existing_config = json.loads(path.read_text())
+            if "mcpServers" in existing_config and "gitstow" in existing_config["mcpServers"]:
+                already_configured = True
+        except (json.JSONDecodeError, KeyError):
+            pass
+
+    if already_configured:
+        if not quiet:
+            console.print(f"  [dim]{tool_name} MCP already configured.[/dim]")
+        return
+
+    # Offer to configure
+    if not auto:
+        if not quiet:
+            console.print(f"\n  [bold]{tool_name}[/bold] — configure MCP server?")
+            console.print(f"    Config: {config_path}")
+            console.print(f"    Command: {mcp_bin}")
+        proceed = bconfirm(f"  Add gitstow to {tool_name}?", default_is_yes=True)
+        if not proceed:
+            return
+
+    # Add to config
+    if "mcpServers" not in existing_config:
+        existing_config["mcpServers"] = {}
+
+    existing_config["mcpServers"]["gitstow"] = {
+        "command": mcp_bin,
+    }
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(existing_config, indent=2) + "\n")
+
+    if not quiet:
+        console.print(f"  [green]✓[/green] {tool_name} MCP configured ({config_path})")
+
+
+# Also make this callable from onboard.py
+def _setup_ai_integrations(auto: bool = False, quiet: bool = False) -> None:
+    """Run AI setup as part of onboarding.
+
+    During onboarding, only the Claude Code skill is installed by default.
+    MCP setup is offered but explained as opt-in, since MCP tools are always
+    loaded into context and cost tokens even when not in use.
+    """
+    console.print("  [bold]5. AI Integration[/bold]\n")
+
+    detected = _detect_ai_tools()
+
+    if not detected:
+        console.print("     [dim]No AI tools detected. You can set up later with 'gitstow setup-ai'.[/dim]\n")
+        return
+
+    # Always install Claude Code skill (zero context cost when not in use)
+    claude_code = [t for t in detected if t["type"] == "claude_code"]
+    if claude_code:
+        _setup_claude_code(auto=True, quiet=quiet)
+
+    # Offer MCP setup but explain the tradeoff
+    mcp_tools = [t for t in detected if t["type"] == "mcp_config"]
+    if mcp_tools:
+        console.print()
+        console.print("     [bold]MCP server[/bold] (optional)")
+        console.print("     The MCP server lets Claude Desktop, Cursor, etc. manage repos.")
+        console.print("     [dim]Note: MCP tools are always loaded into context and use tokens")
+        console.print("     even when you're not managing repos. Best for dedicated setups.[/dim]")
+        console.print("     [dim]You can set this up later with: gitstow setup-ai[/dim]")
+        console.print()
+
+        for tool in mcp_tools:
+            _setup_mcp_config(tool["path"], tool["name"], auto=False, quiet=quiet)
+
+    console.print()

gitstow/cli/shell.py

@@ -0,0 +1,317 @@
+"""gitstow shell — shell integration helpers (fzf, cd, completions)."""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from gitstow.core.config import load_config
+from gitstow.core.repo import RepoStore
+
+shell_app = typer.Typer(
+    help="Shell integration — fzf picker, cd helper, shell functions.",
+    no_args_is_help=True,
+)
+
+console = Console()
+
+
+@shell_app.command("pick")
+def pick(
+    tag: str | None = typer.Option(None, "--tag", "-t", help="Filter by tag."),
+    owner: str | None = typer.Option(None, "--owner", help="Filter by owner."),
+    path_only: bool = typer.Option(True, "--path/--key", help="Output path (default) or key."),
+) -> None:
+    """Pick a repo interactively using fzf.
+
+    Outputs the selected repo's path (or key) to stdout.
+    Designed for shell integration:
+
+    \b
+      cd "$(gitstow shell pick)"
+      code "$(gitstow shell pick)"
+    """
+    import shutil
+    import subprocess
+
+    from gitstow.cli.helpers import iter_repos_with_workspace
+
+    settings = load_config()
+    store = RepoStore()
+
+    repo_ws_pairs = iter_repos_with_workspace(store, settings)
+    if tag:
+        repo_ws_pairs = [(r, ws) for r, ws in repo_ws_pairs if tag in r.tags]
+    if owner:
+        repo_ws_pairs = [(r, ws) for r, ws in repo_ws_pairs if r.owner == owner]
+
+    if not repo_ws_pairs:
+        sys.exit(1)
+
+    ws_map = {r.global_key: ws for r, ws in repo_ws_pairs}
+    repos = [r for r, _ in repo_ws_pairs]
+    multi_ws = len({r.workspace for r in repos}) > 1
+
+    # Check for fzf
+    if not shutil.which("fzf"):
+        try:
+            from beaupy import select as bselect
+            options = [f"[{r.workspace}] {r.key}" if multi_ws else r.key for r in repos]
+            choice = bselect(options, cursor=">>>", cursor_style="bold cyan")
+            if choice:
+                idx = options.index(choice)
+                r = repos[idx]
+                ws = ws_map[r.global_key]
+                print(str(r.get_path(ws.get_path())) if path_only else r.key)
+            else:
+                sys.exit(1)
+        except ImportError:
+            for r in repos:
+                print(r.key)
+            sys.exit(1)
+        return
+
+    # Build fzf input
+    lines = []
+    for r in repos:
+        prefix = f"[{r.workspace}] " if multi_ws else ""
+        frozen = " ❄" if r.frozen else ""
+        tags_str = f"  [{', '.join(r.tags)}]" if r.tags else ""
+        lines.append(f"{prefix}{r.key}{frozen}{tags_str}")
+
+    fzf_input = "\n".join(lines)
+    try:
+        result = subprocess.run(
+            ["fzf", "--reverse", "--height=40%", "--prompt=repo> "],
+            input=fzf_input,
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0 or not result.stdout.strip():
+            sys.exit(1)
+
+        selected_line = result.stdout.strip()
+        # Find the matching repo by comparing fzf lines
+        idx = lines.index(selected_line) if selected_line in lines else -1
+        if idx >= 0:
+            r = repos[idx]
+            ws = ws_map[r.global_key]
+            print(str(r.get_path(ws.get_path())) if path_only else r.key)
+        else:
+            sys.exit(1)
+    except (FileNotFoundError, ValueError):
+        sys.exit(1)
+
+
+@shell_app.command("init")
+def shell_init(
+    shell_type: str = typer.Argument(
+        default="auto",
+        help="Shell type: bash, zsh, fish, or auto.",
+    ),
+) -> None:
+    """Print shell functions to source in your shell rc file.
+
+    \b
+    Usage:
+      # Add to your ~/.zshrc or ~/.bashrc:
+      eval "$(gitstow shell init)"
+
+      # Or for fish (~/.config/fish/config.fish):
+      gitstow shell init fish | source
+    """
+    import os
+
+    if shell_type == "auto":
+        shell_env = os.environ.get("SHELL", "")
+        if "zsh" in shell_env:
+            shell_type = "zsh"
+        elif "fish" in shell_env:
+            shell_type = "fish"
+        else:
+            shell_type = "bash"
+
+    if shell_type == "fish":
+        print(_FISH_FUNCTIONS)
+    else:
+        print(_BASH_ZSH_FUNCTIONS)
+
+
+@shell_app.command("completions")
+def shell_completions(
+    shell_type: str = typer.Argument(
+        default="auto",
+        help="Shell type: bash, zsh, fish, or auto.",
+    ),
+) -> None:
+    """Print shell completion script for repo names, workspaces, and tags.
+
+    \b
+    Usage:
+      # Add to your ~/.zshrc or ~/.bashrc (after shell init):
+      eval "$(gitstow shell completions)"
+    """
+    import os
+
+    if shell_type == "auto":
+        shell_env = os.environ.get("SHELL", "")
+        if "zsh" in shell_env:
+            shell_type = "zsh"
+        elif "fish" in shell_env:
+            shell_type = "fish"
+        else:
+            shell_type = "bash"
+
+    if shell_type == "zsh":
+        print(_ZSH_COMPLETIONS)
+    elif shell_type == "fish":
+        print(_FISH_COMPLETIONS)
+    else:
+        print(_BASH_COMPLETIONS)
+
+
+@shell_app.command("setup")
+def shell_setup() -> None:
+    """Show instructions for setting up shell integration."""
+    console.print(Panel(
+        "[bold]Shell Integration Setup[/bold]\n\n"
+        "Add one of these to your shell config file:\n\n"
+        "[bold cyan]Bash/Zsh[/bold cyan] (~/.bashrc or ~/.zshrc):\n"
+        '  [green]eval "$(gitstow shell init)"[/green]\n\n'
+        "[bold cyan]Fish[/bold cyan] (~/.config/fish/config.fish):\n"
+        "  [green]gitstow shell init fish | source[/green]\n\n"
+        "This gives you:\n"
+        "  [cyan]gs[/cyan]     — cd into a repo (fzf picker)\n"
+        "  [cyan]gse[/cyan]    — open a repo in your editor (fzf picker)\n"
+        "  [cyan]gsp[/cyan]    — gitstow pull (shorthand)\n"
+        "  [cyan]gss[/cyan]    — gitstow status (shorthand)\n"
+        "  [cyan]gsl[/cyan]    — gitstow list (shorthand)\n\n"
+        "[bold cyan]Tab Completion[/bold cyan] (optional):\n"
+        '  [green]eval "$(gitstow shell completions)"[/green]\n\n'
+        "Completes repo names, workspace labels, and tags.",
+        border_style="cyan",
+        padding=(1, 2),
+    ))
+
+
+# Shell function templates
+_BASH_ZSH_FUNCTIONS = r'''# gitstow shell integration
+# cd into a repo via fzf picker
+gs() {
+  local dir
+  dir="$(gitstow shell pick 2>/dev/null)"
+  if [ -n "$dir" ]; then
+    cd "$dir" || return
+  fi
+}
+
+# Open a repo in editor via fzf picker
+gse() {
+  local dir
+  dir="$(gitstow shell pick 2>/dev/null)"
+  if [ -n "$dir" ]; then
+    ${EDITOR:-code} "$dir"
+  fi
+}
+
+# Shortcuts
+alias gsp="gitstow pull"
+alias gss="gitstow status"
+alias gsl="gitstow list"
+alias gsa="gitstow add"
+'''
+
+_FISH_FUNCTIONS = r'''# gitstow shell integration for fish
+function gs --description "cd into a gitstow repo via fzf"
+  set -l dir (gitstow shell pick 2>/dev/null)
+  if test -n "$dir"
+    cd "$dir"
+  end
+end
+
+function gse --description "Open a gitstow repo in editor via fzf"
+  set -l dir (gitstow shell pick 2>/dev/null)
+  if test -n "$dir"
+    eval $EDITOR "$dir"
+  end
+end
+
+alias gsp "gitstow pull"
+alias gss "gitstow status"
+alias gsl "gitstow list"
+alias gsa "gitstow add"
+'''
+
+# Completion templates
+_BASH_COMPLETIONS = r'''# gitstow bash completions
+_gitstow_repos() {
+  COMPREPLY=($(compgen -W "$(gitstow list --quiet 2>/dev/null)" -- "${COMP_WORDS[COMP_CWORD]}"))
+}
+_gitstow_workspaces() {
+  COMPREPLY=($(compgen -W "$(gitstow workspace list --quiet 2>/dev/null)" -- "${COMP_WORDS[COMP_CWORD]}"))
+}
+_gitstow_tags() {
+  COMPREPLY=($(compgen -W "$(gitstow repo tags --quiet 2>/dev/null)" -- "${COMP_WORDS[COMP_CWORD]}"))
+}
+_gitstow_complete() {
+  local cur prev cmd
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  prev="${COMP_WORDS[COMP_CWORD-1]}"
+  if [[ "$prev" == "-w" || "$prev" == "--workspace" ]]; then
+    _gitstow_workspaces; return
+  fi
+  if [[ "$prev" == "-t" || "$prev" == "--tag" ]]; then
+    _gitstow_tags; return
+  fi
+  case "${COMP_WORDS[1]}" in
+    remove|open|exec) _gitstow_repos ;;
+    repo)
+      case "${COMP_WORDS[2]}" in
+        freeze|unfreeze|tag|untag|info) _gitstow_repos ;;
+      esac ;;
+  esac
+}
+complete -F _gitstow_complete gitstow
+'''
+
+_ZSH_COMPLETIONS = r'''# gitstow zsh completions
+_gitstow_repos() {
+  local repos=(${(f)"$(gitstow list --quiet 2>/dev/null)"})
+  compadd -a repos
+}
+_gitstow_workspaces() {
+  local workspaces=(${(f)"$(gitstow workspace list --quiet 2>/dev/null)"})
+  compadd -a workspaces
+}
+_gitstow_tags() {
+  local tags=(${(f)"$(gitstow repo tags --quiet 2>/dev/null)"})
+  compadd -a tags
+}
+_gitstow() {
+  local cur="${words[CURRENT]}" prev="${words[CURRENT-1]}"
+  if [[ "$prev" == "-w" || "$prev" == "--workspace" ]]; then
+    _gitstow_workspaces; return
+  fi
+  if [[ "$prev" == "-t" || "$prev" == "--tag" ]]; then
+    _gitstow_tags; return
+  fi
+  case "${words[2]}" in
+    remove|open|exec) _gitstow_repos ;;
+    repo)
+      case "${words[3]}" in
+        freeze|unfreeze|tag|untag|info) _gitstow_repos ;;
+      esac ;;
+  esac
+}
+compdef _gitstow gitstow
+'''
+
+_FISH_COMPLETIONS = r'''# gitstow fish completions
+complete -c gitstow -n '__fish_seen_subcommand_from remove open' -xa '(gitstow list --quiet 2>/dev/null)'
+complete -c gitstow -n '__fish_seen_subcommand_from repo; and __fish_seen_subcommand_from freeze unfreeze tag untag info' -xa '(gitstow list --quiet 2>/dev/null)'
+complete -c gitstow -s w -l workspace -xa '(gitstow workspace list --quiet 2>/dev/null)'
+complete -c gitstow -s t -l tag -xa '(gitstow repo tags --quiet 2>/dev/null)'
+'''

gitstow/cli/skill_cmd.py

@@ -0,0 +1,63 @@
+"""gitstow install-skill — install the Claude Code skill."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from gitstow.core.paths import SKILL_TARGET, CLAUDE_SKILLS_DIR, get_skill_source_dir
+
+console = Console()
+
+
+def _do_install_skill(quiet: bool = False) -> bool:
+    """Install the skill. Returns True on success."""
+    source = get_skill_source_dir()
+
+    # Ensure skills directory exists
+    CLAUDE_SKILLS_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Copy skill files
+    if SKILL_TARGET.exists():
+        shutil.rmtree(SKILL_TARGET)
+
+    # Copy the skill directory
+    SKILL_TARGET.mkdir(parents=True, exist_ok=True)
+
+    # Copy SKILL.md
+    source_skill = Path(str(source)) / "SKILL.md"
+    if source_skill.exists():
+        shutil.copy2(source_skill, SKILL_TARGET / "SKILL.md")
+    else:
+        # Fallback: try importlib.resources traversable
+        try:
+            skill_content = (source / "SKILL.md").read_text()
+            (SKILL_TARGET / "SKILL.md").write_text(skill_content)
+        except Exception:
+            if not quiet:
+                console.print("  [red]✗[/red] Could not find bundled SKILL.md")
+            return False
+
+    # Write version marker for auto-update detection
+    from gitstow import __version__
+    (SKILL_TARGET / ".version").write_text(__version__)
+
+    if not quiet:
+        console.print(f"  [green]✓[/green] Skill installed to {SKILL_TARGET}")
+    return True
+
+
+def install_skill() -> None:
+    """[bold]Install[/bold] the Claude Code skill for AI-assisted repo management.
+
+    Copies the gitstow skill to ~/.claude/skills/gitstow/ so Claude Code
+    can manage your repos conversationally.
+    """
+    success = _do_install_skill(quiet=False)
+    if not success:
+        raise typer.Exit(code=1)
+    console.print("\n  You can now use gitstow from Claude Code!")
+    console.print("  Try saying: [cyan]\"add this repo\"[/cyan] or [cyan]\"update my repos\"[/cyan]\n")