git-worktree-wrapper 0.1.0__py3-none-any.whl

gww/utils/shell.py

@@ -0,0 +1,894 @@
+"""Shell autocompletion generation utilities."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from gww.utils.xdg import APP_NAME
+
+
+def get_completion_path(shell: str) -> Path:
+    """Get the default installation path for completion scripts.
+
+    Args:
+        shell: Shell name (bash, zsh, fish).
+
+    Returns:
+        Path where completion script should be installed.
+
+    Raises:
+        ValueError: If shell is not supported.
+    """
+    home = Path.home()
+
+    if shell == "bash":
+        return home / ".bash_completion.d" / APP_NAME
+    elif shell == "zsh":
+        return home / ".zsh" / "completions" / f"_{APP_NAME}"
+    elif shell == "fish":
+        return home / ".config" / "fish" / "completions" / f"{APP_NAME}.fish"
+    else:
+        raise ValueError(f"Unsupported shell: {shell}. Must be one of: bash, zsh, fish")
+
+
+def get_aliases_path(shell: str) -> Path | dict[str, Path]:
+    """Get the default installation path for alias functions.
+
+    Args:
+        shell: Shell name (bash, zsh, fish).
+
+    Returns:
+        For bash/zsh: Path where aliases script should be installed.
+        For fish: Dictionary mapping function name to its file path.
+
+    Raises:
+        ValueError: If shell is not supported.
+    """
+    home = Path.home()
+
+    if shell == "bash":
+        return home / ".bash_completion.d" / f"{APP_NAME}-aliases"
+    elif shell == "zsh":
+        return home / ".zsh" / "functions" / f"{APP_NAME}-aliases"
+    elif shell == "fish":
+        functions_dir = home / ".config" / "fish" / "functions"
+        return {
+            "gwc": functions_dir / "gwc.fish",
+            "gwa": functions_dir / "gwa.fish",
+            "gwr": functions_dir / "gwr.fish",
+        }
+    else:
+        raise ValueError(f"Unsupported shell: {shell}. Must be one of: bash, zsh, fish")
+
+
+_BASH_REMOVE_AWK = r'''
+/^worktree / { path = substr($0, 10) }
+/^HEAD / { head = substr($0, 6) }
+/^branch refs\/heads\// { branch = substr($0, 19) }
+/^$/ {
+    if (skip) {
+        skip = 0
+        path = ""; branch = ""; head = ""
+    } else if (path != "") {
+        if (branch != "") {
+            print path
+            print branch
+        } else {
+            print path
+        }
+        path = ""; branch = ""; head = ""
+    }
+}
+END {
+    if (path != "" && !skip) {
+        if (branch != "") {
+            print path
+            print branch
+        } else {
+            print path
+        }
+    }
+}
+'''.strip("\n")
+
+
+def generate_bash_completion() -> str:
+    """Generate bash completion script.
+
+    Returns:
+        Bash completion script content.
+    """
+    return f'''# Bash completion for {APP_NAME}
+# Generated by {APP_NAME} init shell bash
+
+_{APP_NAME}_completions() {{
+    local cur prev opts
+    COMPREPLY=()
+    cur="${{COMP_WORDS[COMP_CWORD]}}"
+    prev="${{COMP_WORDS[COMP_CWORD-1]}}"
+
+    # Main commands
+    local commands="clone add remove pull migrate init"
+
+    # Options
+    local global_opts="--help --verbose --quiet"
+
+    case "${{COMP_CWORD}}" in
+        1)
+            COMPREPLY=( $(compgen -W "${{commands}}" -- "${{cur}}") )
+            return 0
+            ;;
+    esac
+
+    case "${{prev}}" in
+        clone)
+            # No specific completions for clone URI
+            return 0
+            ;;
+        add)
+            # Complete with branch names
+            if git rev-parse --git-dir > /dev/null 2>&1; then
+                local branches=$(git branch --format='%(refname:short)' 2>/dev/null)
+                local remote_branches=$(git branch -r --format='%(refname:short)' 2>/dev/null | sed 's/origin\\///')
+                COMPREPLY=( $(compgen -W "${{branches}} ${{remote_branches}}" -- "${{cur}}") )
+            fi
+            return 0
+            ;;
+        remove)
+            # Complete with worktree paths and checked-out branches only (not all branches).
+            # `gwr` mirrors `gww remove` which accepts a branch or a path.
+            if git rev-parse --git-dir > /dev/null 2>&1; then
+                # First entry of `git worktree list --porcelain` is the source repo — git's invariant. Skip it.
+                local candidates=$(git worktree list --porcelain 2>/dev/null | awk -v skip=1 '{_BASH_REMOVE_AWK}')
+                COMPREPLY=( $(compgen -W "${{candidates}}" -- "${{cur}}") )
+            fi
+            return 0
+            ;;
+        -t|--tag)
+            # Tag value is a free-form key[=value]; no completion to offer.
+            return 0
+            ;;
+        init)
+            COMPREPLY=( $(compgen -W "config shell" -- "${{cur}}") )
+            return 0
+            ;;
+        shell)
+            COMPREPLY=( $(compgen -W "bash zsh fish" -- "${{cur}}") )
+            return 0
+            ;;
+        migrate)
+            # Complete with directories
+            COMPREPLY=( $(compgen -d -- "${{cur}}") )
+            return 0
+            ;;
+        -c|--create-branch)
+            return 0
+            ;;
+        -f|--force)
+            return 0
+            ;;
+        --dry-run|-n|--move)
+            return 0
+            ;;
+    esac
+
+    # Default to global options
+    COMPREPLY=( $(compgen -W "${{global_opts}}" -- "${{cur}}") )
+    return 0
+}}
+
+complete -F _{APP_NAME}_completions {APP_NAME}
+'''
+
+
+_ZSH_REMOVE_AWK = r'''
+/^worktree / { path = substr($0, 10) }
+/^HEAD / { head = substr($0, 6) }
+/^branch refs\/heads\// { branch = substr($0, 19) }
+/^$/ {
+    if (skip) {
+        skip = 0
+        path = ""; branch = ""; head = ""
+    } else if (path != "") {
+        if (branch != "") {
+            print path "\tpath (branch: " branch ")"
+            print branch "\tbranch (worktree at " path ")"
+        } else {
+            print path "\tpath (detached at " substr(head, 1, 7) ")"
+        }
+        path = ""; branch = ""; head = ""
+    }
+}
+END {
+    if (path != "" && !skip) {
+        if (branch != "") {
+            print path "\tpath (branch: " branch ")"
+            print branch "\tbranch (worktree at " path ")"
+        } else {
+            print path "\tpath (detached at " substr(head, 1, 7) ")"
+        }
+    }
+}
+'''.strip("\n")
+
+
+def generate_zsh_completion() -> str:
+    """Generate zsh completion script.
+
+    Returns:
+        Zsh completion script content.
+    """
+    return f'''#compdef {APP_NAME}
+# Zsh completion for {APP_NAME}
+# Generated by {APP_NAME} init shell zsh
+
+_{APP_NAME}() {{
+    local -a commands
+    commands=(
+        'clone:Clone a repository to configured location'
+        'add:Add a worktree for a branch'
+        'remove:Remove a worktree'
+        'pull:Update source repository'
+        'migrate:Migrate repositories to new locations'
+        'init:Initialize config or shell completion'
+    )
+
+    local -a init_commands
+    init_commands=(
+        'config:Create default configuration file'
+        'shell:Install shell completion'
+    )
+
+    local -a shells
+    shells=(bash zsh fish)
+
+    _arguments -C \\
+        '1: :->command' \\
+        '*: :->args' \\
+        && return 0
+
+    case $state in
+        command)
+            _describe -t commands '{APP_NAME} command' commands
+            ;;
+        args)
+            case $words[2] in
+                clone)
+                    _message 'repository URI'
+                    ;;
+                add)
+                    _arguments \\
+                        '-c[Create branch if not exists]' \\
+                        '--create-branch[Create branch if not exists]' \\
+                        '1:branch:_git_branch_names'
+                    ;;
+                remove)
+                    _arguments \\
+                        '-f[Force removal]' \\
+                        '--force[Force removal]' \\
+                        '-t[Tag in key=value form]:tag:' \\
+                        '--tag[Tag in key=value form]:tag:' \\
+                        '1:branch or path:_{APP_NAME}_worktrees'
+                    ;;
+                pull)
+                    ;;
+                migrate)
+                    _arguments \\
+                        '-n[Dry run]' \\
+                        '--dry-run[Dry run]' \\
+                        '--move[Move instead of copy]' \\
+                        '1:old repos directory:_files -/'
+                    ;;
+                init)
+                    case $words[3] in
+                        shell)
+                            _describe -t shells 'shell' shells
+                            ;;
+                        *)
+                            _describe -t init_commands 'init command' init_commands
+                            ;;
+                    esac
+                    ;;
+            esac
+            ;;
+    esac
+}}
+
+_{APP_NAME}_worktrees() {{
+    local -a candidates
+    if git rev-parse --git-dir > /dev/null 2>&1; then
+        # First entry of `git worktree list --porcelain` is the source repo — git's invariant. Skip it.
+        local raw=$(git worktree list --porcelain 2>/dev/null | awk -v skip=1 '{_ZSH_REMOVE_AWK}')
+        local IFS=$'\\n'
+        for entry in $raw; do
+            candidates+=("$entry")
+        done
+    fi
+    _describe -t worktrees 'worktree' candidates
+}}
+
+_git_branch_names() {{
+    local -a branches
+    if git rev-parse --git-dir > /dev/null 2>&1; then
+        branches=($(git branch --format='%(refname:short)' 2>/dev/null))
+        _describe -t branches 'branch' branches
+    fi
+}}
+
+_{APP_NAME} "$@"
+'''
+
+
+_FISH_REMOVE_AWK = r'''
+/^worktree / { path = substr($0, 10) }
+/^HEAD / { head = substr($0, 6) }
+/^branch refs\/heads\// { branch = substr($0, 19) }
+/^$/ {
+    if (skip) {
+        skip = 0
+        path = ""; branch = ""; head = ""
+    } else if (path != "") {
+        if (branch != "") {
+            print path "\tpath (branch: " branch ")"
+            print branch "\tbranch (worktree at " path ")"
+        } else {
+            print path "\tpath (detached at " substr(head, 1, 7) ")"
+        }
+        path = ""; branch = ""; head = ""
+    }
+}
+END {
+    if (path != "" && !skip) {
+        if (branch != "") {
+            print path "\tpath (branch: " branch ")"
+            print branch "\tbranch (worktree at " path ")"
+        } else {
+            print path "\tpath (detached at " substr(head, 1, 7) ")"
+        }
+    }
+}
+'''.strip("\n")
+
+
+def generate_fish_completion() -> str:
+    """Generate fish completion script.
+
+    Returns:
+        Fish completion script content.
+    """
+    return f'''# Fish completion for {APP_NAME}
+# Generated by {APP_NAME} init shell fish
+
+# Source git.fish to import __fish_git_branches and other git completion functions
+# This uses $__fish_data_dir which is set by fish at runtime
+if test -f $__fish_data_dir/completions/git.fish
+    source $__fish_data_dir/completions/git.fish
+end
+
+# Disable file completions for all commands
+complete -c {APP_NAME} -f
+
+# Main commands
+complete -c {APP_NAME} -n __fish_use_subcommand -a clone -d 'Clone a repository'
+complete -c {APP_NAME} -n __fish_use_subcommand -a add -d 'Add a worktree'
+complete -c {APP_NAME} -n __fish_use_subcommand -a remove -d 'Remove a worktree'
+complete -c {APP_NAME} -n __fish_use_subcommand -a pull -d 'Update source repository'
+complete -c {APP_NAME} -n __fish_use_subcommand -a migrate -d 'Migrate repositories'
+complete -c {APP_NAME} -n __fish_use_subcommand -a init -d 'Initialize config or completion'
+
+# clone completions
+# (no specific completions for URI)
+
+# add completions
+complete -c {APP_NAME} -n '__fish_seen_subcommand_from add' -s c -l create-branch -d 'Create branch if not exists'
+complete -c {APP_NAME} -n '__fish_seen_subcommand_from add' -a '(__fish_git_branches)'
+
+# remove completions — only worktree paths and checked-out branches, not all branches.
+# First entry of `git worktree list --porcelain` is the source repo — git's invariant. Skip it.
+function __{APP_NAME}_remove_worktrees
+    git worktree list --porcelain 2>/dev/null | awk -v skip=1 '{_FISH_REMOVE_AWK}'
+end
+complete -c {APP_NAME} -n '__fish_seen_subcommand_from remove' -s f -l force -d 'Force removal'
+complete -c {APP_NAME} -n '__fish_seen_subcommand_from remove' -s t -l tag -d 'Tag in key=value form'
+complete -c {APP_NAME} -n '__fish_seen_subcommand_from remove' -a '(__{APP_NAME}_remove_worktrees)'
+
+# migrate completions
+complete -c {APP_NAME} -n '__fish_seen_subcommand_from migrate' -s n -l dry-run -d 'Show what would be migrated'
+complete -c {APP_NAME} -n '__fish_seen_subcommand_from migrate' -l move -d 'Move instead of copy'
+complete -c {APP_NAME} -n '__fish_seen_subcommand_from migrate' -a '(__fish_complete_directories)'
+
+# init subcommands
+complete -c {APP_NAME} -n '__fish_seen_subcommand_from init; and not __fish_seen_subcommand_from config shell' -a config -d 'Create default config file'
+complete -c {APP_NAME} -n '__fish_seen_subcommand_from init; and not __fish_seen_subcommand_from config shell' -a shell -d 'Install shell completion'
+
+# init shell completions
+complete -c {APP_NAME} -n '__fish_seen_subcommand_from init; and __fish_seen_subcommand_from shell' -a 'bash zsh fish'
+
+# Global options
+complete -c {APP_NAME} -s h -l help -d 'Show help'
+complete -c {APP_NAME} -s v -l verbose -d 'Increase verbosity'
+complete -c {APP_NAME} -s q -l quiet -d 'Suppress output'
+'''
+
+
+def generate_bash_aliases() -> str:
+    """Generate bash alias functions for gwc, gwa, and gwr.
+
+    Returns:
+        Bash function definitions for gwc (clone), gwa (add), and gwr (remove).
+    """
+    return f'''# Alias functions for {APP_NAME}
+# Generated by {APP_NAME} init shell bash
+
+# gwc - Clone a repository and navigate to it
+# Streams git's progress (stderr) to the terminal in real time.
+# Only stdout's last line (the new path) is captured for navigation.
+gwc() {{
+    local target_path
+    local exit_code
+    # `set -o pipefail` inside the subshell so $? reflects `gww clone`'s exit,
+    # not `tail`'s. Stderr from the subshell still streams to the terminal.
+    target_path=$(set -o pipefail; command {APP_NAME} clone "$@" | tail -n 1)
+    exit_code=$?
+    if [ $exit_code -eq 0 ]; then
+        if [ -n "$target_path" ] && [ -d "$target_path" ]; then
+            printf "Navigate to %s? [Y/n] " "$target_path"
+            read -r reply
+            if [ -z "$reply" ] || [ "$reply" = "y" ] || [ "$reply" = "Y" ]; then
+                cd "$target_path" || return 1
+            fi
+        fi
+    else
+        return $exit_code
+    fi
+}}
+
+# gwa - Add a worktree and navigate to it
+# Streams git's progress (stderr) to the terminal in real time.
+# Only stdout's last line (the new path) is captured for navigation.
+gwa() {{
+    local target_path
+    local exit_code
+    target_path=$(set -o pipefail; command {APP_NAME} add "$@" | tail -n 1)
+    exit_code=$?
+    if [ $exit_code -eq 0 ]; then
+        if [ -n "$target_path" ] && [ -d "$target_path" ]; then
+            printf "Navigate to %s? [Y/n] " "$target_path"
+            read -r reply
+            if [ -z "$reply" ] || [ "$reply" = "y" ] || [ "$reply" = "Y" ]; then
+                cd "$target_path" || return 1
+            fi
+        fi
+    else
+        return $exit_code
+    fi
+}}
+
+# gwr - Remove a worktree (prompts for force if dirty)
+# Streams stdout to the terminal; only stderr is captured so the dirty-state
+# check (looking for "uncommitted changes" / "untracked files") still works.
+gwr() {{
+    local errfile
+    local exit_code
+    errfile=$(mktemp)
+    command {APP_NAME} remove "$@" 2>"$errfile"
+    exit_code=$?
+    if [ $exit_code -eq 0 ]; then
+        rm -f "$errfile"
+    elif grep -q "uncommitted changes\\|untracked files" "$errfile"; then
+        cat "$errfile" >&2
+        rm -f "$errfile"
+        printf "Force removal? [y/N] "
+        read -r reply
+        if [ "$reply" = "y" ] || [ "$reply" = "Y" ]; then
+            command {APP_NAME} remove --force "$@"
+        else
+            return 1
+        fi
+    else
+        cat "$errfile" >&2
+        rm -f "$errfile"
+        return $exit_code
+    fi
+}}
+
+# Completion wrappers - reuse gww completions for aliases
+_gwc_completions() {{
+    COMP_WORDS=({APP_NAME} clone "${{COMP_WORDS[@]:1}}")
+    COMP_CWORD=$((COMP_CWORD + 1))
+    _{APP_NAME}_completions
+}}
+
+_gwa_completions() {{
+    COMP_WORDS=({APP_NAME} add "${{COMP_WORDS[@]:1}}")
+    COMP_CWORD=$((COMP_CWORD + 1))
+    _{APP_NAME}_completions
+}}
+
+_gwr_completions() {{
+    COMP_WORDS=({APP_NAME} remove "${{COMP_WORDS[@]:1}}")
+    COMP_CWORD=$((COMP_CWORD + 1))
+    _{APP_NAME}_completions
+}}
+
+complete -F _gwc_completions gwc
+complete -F _gwa_completions gwa
+complete -F _gwr_completions gwr
+'''
+
+
+def generate_zsh_aliases() -> str:
+    """Generate zsh alias functions for gwc, gwa, and gwr.
+
+    Returns:
+        Zsh function definitions for gwc (clone), gwa (add), and gwr (remove).
+    """
+    return f'''# Alias functions for {APP_NAME}
+# Generated by {APP_NAME} init shell zsh
+
+# gwc - Clone a repository and navigate to it
+# Streams git's progress (stderr) to the terminal in real time.
+# Only stdout's last line (the new path) is captured for navigation.
+gwc() {{
+    local target_path
+    local exit_code
+    # `setopt pipefail` inside the subshell so $? reflects `gww clone`'s exit,
+    # not `tail`'s. Stderr from the subshell still streams to the terminal.
+    target_path=$(setopt pipefail; command {APP_NAME} clone "$@" | tail -n 1)
+    exit_code=$?
+    if [[ $exit_code -eq 0 ]]; then
+        if [[ -n "$target_path" ]] && [[ -d "$target_path" ]]; then
+            printf "Navigate to %s? [Y/n] " "$target_path"
+            read -r reply
+            if [[ -z "$reply" ]] || [[ "$reply" == "y" ]] || [[ "$reply" == "Y" ]]; then
+                cd "$target_path" || return 1
+            fi
+        fi
+    else
+        return $exit_code
+    fi
+}}
+
+# gwa - Add a worktree and navigate to it
+# Streams git's progress (stderr) to the terminal in real time.
+# Only stdout's last line (the new path) is captured for navigation.
+gwa() {{
+    local target_path
+    local exit_code
+    target_path=$(setopt pipefail; command {APP_NAME} add "$@" | tail -n 1)
+    exit_code=$?
+    if [[ $exit_code -eq 0 ]]; then
+        if [[ -n "$target_path" ]] && [[ -d "$target_path" ]]; then
+            printf "Navigate to %s? [Y/n] " "$target_path"
+            read -r reply
+            if [[ -z "$reply" ]] || [[ "$reply" == "y" ]] || [[ "$reply" == "Y" ]]; then
+                cd "$target_path" || return 1
+            fi
+        fi
+    else
+        return $exit_code
+    fi
+}}
+
+# gwr - Remove a worktree (prompts for force if dirty)
+# Streams stdout to the terminal; only stderr is captured so the dirty-state
+# check (looking for "uncommitted changes" / "untracked files") still works.
+gwr() {{
+    local errfile
+    local exit_code
+    errfile=$(mktemp)
+    command {APP_NAME} remove "$@" 2>"$errfile"
+    exit_code=$?
+    if [[ $exit_code -eq 0 ]]; then
+        rm -f "$errfile"
+    elif grep -q "uncommitted changes\\|untracked files" "$errfile"; then
+        cat "$errfile" >&2
+        rm -f "$errfile"
+        printf "Force removal? [y/N] "
+        read -r reply
+        if [[ "$reply" == "y" ]] || [[ "$reply" == "Y" ]]; then
+            command {APP_NAME} remove --force "$@"
+        else
+            return 1
+        fi
+    else
+        cat "$errfile" >&2
+        rm -f "$errfile"
+        return $exit_code
+    fi
+}}
+
+# Completion wrappers - reuse gww completions for aliases
+_gwc() {{
+    words[1]={APP_NAME}
+    words=(clone "${{words[@]:1}}")
+    ((CURRENT++))
+    _{APP_NAME}
+}}
+
+_gwa() {{
+    words[1]={APP_NAME}
+    words=(add "${{words[@]:1}}")
+    ((CURRENT++))
+    _{APP_NAME}
+}}
+
+_gwr() {{
+    words[1]={APP_NAME}
+    words=(remove "${{words[@]:1}}")
+    ((CURRENT++))
+    _{APP_NAME}
+}}
+
+compdef _gwc gwc
+compdef _gwa gwa
+compdef _gwr gwr
+'''
+
+
+def generate_fish_aliases() -> dict[str, str]:
+    """Generate fish alias functions for gwc, gwa, and gwr.
+
+    Returns:
+        Dictionary mapping function name to fish function content.
+        Fish convention: one function per file.
+    """
+    gwc_content = f'''# gwc - Clone a repository and navigate to it
+# Generated by {APP_NAME} init shell fish
+#
+# Streams git's progress (stderr) to the terminal in real time.
+# Only stdout's last line (the new path) is captured for navigation.
+
+function gwc --wraps="{APP_NAME} clone" --description "Clone a repository and navigate to it"
+    set -l target_path (command {APP_NAME} clone $argv | tail -n 1)
+    set -l exit_code $pipestatus[1]
+    if test $exit_code -eq 0
+        if test -n "$target_path" -a -d "$target_path"
+            read -P "Navigate to $target_path? [Y/n] " reply
+            if test -z "$reply" -o "$reply" = "y" -o "$reply" = "Y"
+                cd "$target_path"
+                commandline -f repaint
+            end
+        end
+    else
+        return $exit_code
+    end
+end
+'''
+
+    gwa_content = f'''# gwa - Add a worktree and navigate to it
+# Generated by {APP_NAME} init shell fish
+#
+# Streams git's progress (stderr) to the terminal in real time.
+# Only stdout's last line (the new path) is captured for navigation.
+
+function gwa --wraps="{APP_NAME} add" --description "Add a worktree and navigate to it"
+    set -l target_path (command {APP_NAME} add $argv | tail -n 1)
+    set -l exit_code $pipestatus[1]
+    if test $exit_code -eq 0
+        if test -n "$target_path" -a -d "$target_path"
+            read -P "Navigate to $target_path? [Y/n] " reply
+            if test -z "$reply" -o "$reply" = "y" -o "$reply" = "Y"
+                cd "$target_path"
+                commandline -f repaint
+            end
+        end
+    else
+        return $exit_code
+    end
+end
+'''
+
+    gwr_content = f'''# gwr - Remove a worktree (prompts for force if dirty)
+# Generated by {APP_NAME} init shell fish
+#
+# Streams stdout to the terminal; only stderr is captured so the dirty-state
+# check (looking for "uncommitted changes" / "untracked files") still works.
+
+function gwr --wraps="{APP_NAME} remove" --description "Remove a worktree (prompts for force if dirty)"
+    set -l errfile (mktemp)
+    command {APP_NAME} remove $argv 2>$errfile
+    set -l exit_code $status
+    if test $exit_code -eq 0
+        rm -f $errfile
+        commandline -f repaint
+    else if grep -q -E "uncommitted changes|untracked files" $errfile
+        cat $errfile >&2
+        rm -f $errfile
+        read -P "Force removal? [y/N] " reply
+        if test "$reply" = "y" -o "$reply" = "Y"
+            command {APP_NAME} remove --force $argv
+            commandline -f repaint
+        else
+            commandline -f repaint
+            return 1
+        end
+    else
+        cat $errfile >&2
+        rm -f $errfile
+        commandline -f repaint
+        return $exit_code
+    end
+end
+'''
+
+    return {"gwc": gwc_content, "gwa": gwa_content, "gwr": gwr_content}
+
+
+def generate_completion(shell: str) -> str:
+    """Generate completion script for specified shell.
+
+    Args:
+        shell: Shell name (bash, zsh, fish).
+
+    Returns:
+        Completion script content.
+
+    Raises:
+        ValueError: If shell is not supported.
+    """
+    if shell == "bash":
+        return generate_bash_completion()
+    elif shell == "zsh":
+        return generate_zsh_completion()
+    elif shell == "fish":
+        return generate_fish_completion()
+    else:
+        raise ValueError(f"Unsupported shell: {shell}. Must be one of: bash, zsh, fish")
+
+
+def install_completion(shell: str, path: Optional[Path] = None) -> Path:
+    """Install completion script for specified shell.
+
+    Args:
+        shell: Shell name (bash, zsh, fish).
+        path: Custom installation path (optional).
+
+    Returns:
+        Path where script was installed.
+
+    Raises:
+        ValueError: If shell is not supported.
+        OSError: If installation fails.
+    """
+    if path is None:
+        path = get_completion_path(shell)
+
+    script = generate_completion(shell)
+
+    # Ensure parent directory exists
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write script
+    path.write_text(script)
+
+    return path
+
+
+def install_aliases(shell: str) -> Path | list[Path]:
+    """Install alias functions for specified shell.
+
+    Args:
+        shell: Shell name (bash, zsh, fish).
+
+    Returns:
+        For bash/zsh: Path where aliases script was installed.
+        For fish: List of paths where function files were installed.
+
+    Raises:
+        ValueError: If shell is not supported.
+        OSError: If installation fails.
+    """
+    if shell == "bash":
+        path = get_aliases_path(shell)
+        assert isinstance(path, Path)
+        script = generate_bash_aliases()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(script)
+        return path
+    elif shell == "zsh":
+        path = get_aliases_path(shell)
+        assert isinstance(path, Path)
+        script = generate_zsh_aliases()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(script)
+        return path
+    elif shell == "fish":
+        paths_dict = get_aliases_path(shell)
+        assert isinstance(paths_dict, dict)
+        functions = generate_fish_aliases()
+        installed_paths = []
+        for name, content in functions.items():
+            path = paths_dict[name]
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content)
+            installed_paths.append(path)
+        return installed_paths
+    else:
+        raise ValueError(f"Unsupported shell: {shell}. Must be one of: bash, zsh, fish")
+
+
+def get_installation_instructions(
+    shell: str,
+    completion_path: Path,
+    aliases_path: Path | list[Path] | None = None,
+) -> str:
+    """Get instructions for activating completion and aliases after installation.
+
+    Args:
+        shell: Shell name.
+        completion_path: Path where completion was installed.
+        aliases_path: Path(s) where aliases were installed (optional).
+
+    Returns:
+        Human-readable activation instructions.
+    """
+    if shell == "bash":
+        instructions = (
+            f"Installed bash completion script: {completion_path}\n"
+        )
+        if aliases_path:
+            assert isinstance(aliases_path, Path)
+            instructions += f"Installed bash alias functions: {aliases_path}\n"
+            instructions += (
+                f"\nTo activate, add to ~/.bashrc:\n"
+                f"  source {completion_path}\n"
+                f"  source {aliases_path}\n"
+                f"\nAlias functions installed:\n"
+                f"  gwc - Clone a repository and navigate to it\n"
+                f"  gwa - Add a worktree and navigate to it\n"
+                f"  gwr - Remove a worktree (prompts for force if dirty)"
+            )
+        else:
+            instructions += (
+                f"To activate, run: source {completion_path}\n"
+                f"Or add to ~/.bashrc: source {completion_path}"
+            )
+        return instructions
+    elif shell == "zsh":
+        instructions = (
+            f"Installed zsh completion script: {completion_path}\n"
+        )
+        if aliases_path:
+            assert isinstance(aliases_path, Path)
+            instructions += f"Installed zsh alias functions: {aliases_path}\n"
+            instructions += (
+                f"\nTo activate, add to ~/.zshrc:\n"
+                f"  fpath=(~/.zsh/completions $fpath)\n"
+                f"  autoload -Uz compinit && compinit\n"
+                f"  source {aliases_path}\n"
+                f"\nAlias functions installed:\n"
+                f"  gwc - Clone a repository and navigate to it\n"
+                f"  gwa - Add a worktree and navigate to it\n"
+                f"  gwr - Remove a worktree (prompts for force if dirty)\n"
+                f"\nThen restart your shell."
+            )
+        else:
+            instructions += (
+                f"To activate, ensure your ~/.zshrc contains:\n"
+                f"  fpath=(~/.zsh/completions $fpath)\n"
+                f"  autoload -Uz compinit && compinit\n"
+                f"Then restart your shell."
+            )
+        return instructions
+    elif shell == "fish":
+        instructions = (
+            f"Installed fish completion script: {completion_path}\n"
+        )
+        if aliases_path:
+            assert isinstance(aliases_path, list)
+            for p in aliases_path:
+                instructions += f"Installed fish function: {p}\n"
+            instructions += (
+                f"\nAlias functions installed:\n"
+                f"  gwc - Clone a repository and navigate to it\n"
+                f"  gwa - Add a worktree and navigate to it\n"
+                f"  gwr - Remove a worktree (prompts for force if dirty)\n"
+                f"\nRestart fish shell to activate."
+            )
+        else:
+            instructions += f"Restart fish shell or run: source {completion_path}"
+        return instructions
+    else:
+        return f"Installed completion script: {completion_path}"