setup

#!/usr/bin/env bash
set -euo pipefail

# ---------------------------------------------------------------------------
# ai-coding-setup installer
# Installs AI coding agent commands/skills for Claude Code, Gemini CLI,
# Codex CLI, and Copilot CLI from this repo into user-level directories.
# ---------------------------------------------------------------------------

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
BOLD='\033[1m'
DIM='\033[2m'
NC='\033[0m'

MD_MARKER="<!-- source: ai-coding-setup -->"
TOML_MARKER="# source: ai-coding-setup"
FORCE=false

# ---- read-only permission sets --------------------------------------------
# Only commands that have NO write/destructive mode, even with flags.
# Excluded: find (-delete), sed (-i), awk (print>"file"), gh api (POST/DELETE),
#           git branch/tag/stash/remote (destructive subcommands).

READONLY_COMMANDS=(
    # Git read-only
    "git status" "git log" "git diff" "git show" "git blame"
    "git ls-files" "git ls-tree" "git ls-remote"
    "git rev-parse" "git cat-file" "git shortlog" "git describe"
    # GitHub CLI read-only
    "gh pr view" "gh pr list" "gh pr diff" "gh pr checks" "gh pr status"
    "gh issue view" "gh issue list" "gh issue status"
    "gh repo view" "gh repo list"
    "gh run view" "gh run list"
    "gh workflow view" "gh workflow list"
    "gh search"
    # File inspection
    "cat" "head" "tail" "file" "stat" "wc"
    "ls" "tree" "du" "diff" "shasum"
    # Text processing
    "grep" "sort" "uniq" "cut" "tr" "jq"
    # System info
    "uname" "which" "command -v" "sw_vers"
    "date" "ps" "id" "df"
)

# Generate tool-specific permission arrays from the shared command list.
CLAUDE_READONLY_PERMS=()
for _cmd in "${READONLY_COMMANDS[@]}"; do
    CLAUDE_READONLY_PERMS+=("Bash($_cmd *)")
done




# ---- MCP server definitions ------------------------------------------------
# Format: "name|command|arg1,arg2,...|permission_pattern"
# To add a new MCP server, append an entry here.
MCP_SERVERS=(
    "playwright|npx|@playwright/mcp@latest|mcp__playwright__browser_*"
)

# ---- helpers --------------------------------------------------------------

print_success() { echo -e "${GREEN}[OK]${NC} $1"; }
print_error()   { echo -e "${RED}[ERROR]${NC} $1"; }
print_warning() { echo -e "${YELLOW}[WARN]${NC} $1"; }
print_info()    { echo -e "${BLUE}[INFO]${NC} $1"; }

prompt_yes_no() {
    local prompt="$1"
    local default="${2:-y}"
    local yn
    if [[ "$default" == "y" ]]; then
        read -rp "$(echo -e "${BOLD}${prompt}${NC} [Y/n]: ")" yn
        yn="${yn:-y}"
    else
        read -rp "$(echo -e "${BOLD}${prompt}${NC} [y/N]: ")" yn
        yn="${yn:-n}"
    fi
    [[ "$yn" =~ ^[Yy]$ ]]
}

# Description extractors — one per file format.
get_md_description() {
    local desc content
    content=$(cat "$1")
    # If file has YAML frontmatter, try extracting description from it first
    if [[ "$content" == ---* ]]; then
        desc=$(echo "$content" | sed '1d' | sed -n '/^---$/q; p' \
            | grep -m 1 '^description:' \
            | sed "s/^description:[[:space:]]*//; s/^['\"]//; s/['\"]$//")
    fi
    # Fallback: first non-blank, non-heading, non-frontmatter line
    if [[ -z "${desc:-}" ]]; then
        desc=$(grep -m 1 -v -E '^\s*$|^\s*#|^---' "$1" | head -1)
    fi
    echo "${desc:-No description available}"
}

get_toml_description() {
    local desc
    desc=$(grep -m 1 '^description' "$1" | sed 's/^description[[:space:]]*=[[:space:]]*"\(.*\)"/\1/')
    echo "${desc:-No description available}"
}

get_skill_description() {
    local desc
    desc=$(grep -m 1 '^description:' "$1" | sed "s/^description:[[:space:]]*//; s/^['\"]//; s/['\"]$//")
    echo "${desc:-No description available}"
}

has_marker() {
    grep -qF "$1" "$2" 2>/dev/null
}

is_up_to_date() {
    local src="$1" dest="$2" marker="$3"
    local expected
    expected=$(cat "$src")
    has_marker "$marker" "$src" || expected=$(printf '%s\n%s\n' "$expected" "$marker")
    [[ "$expected" == "$(cat "$dest")" ]]
}

# Categorise raw command names and display a grouped summary.
# Usage: display_permission_summary "cmd1" "cmd2" ...
display_permission_summary() {
    local git_cmds=() gh_cmds=() file_cmds=() text_cmds=() sys_cmds=()
    for cmd in "$@"; do
        case "$cmd" in
            git\ *)     git_cmds+=("${cmd#git }") ;;
            gh\ *)      gh_cmds+=("${cmd#gh }") ;;
            grep|sort|uniq|cut|tr|jq) text_cmds+=("$cmd") ;;
            uname|which|command\ *|sw_vers|date|ps|id|df) sys_cmds+=("$cmd") ;;
            *)          file_cmds+=("$cmd") ;;
        esac
    done

    [[ ${#git_cmds[@]} -gt 0 ]]  && echo -e "    ${BOLD}Git (${#git_cmds[@]}):${NC} ${git_cmds[*]}"
    [[ ${#gh_cmds[@]} -gt 0 ]]   && echo -e "    ${BOLD}GitHub CLI (${#gh_cmds[@]}):${NC} ${gh_cmds[*]}"
    [[ ${#file_cmds[@]} -gt 0 ]] && echo -e "    ${BOLD}File (${#file_cmds[@]}):${NC} ${file_cmds[*]}"
    [[ ${#text_cmds[@]} -gt 0 ]] && echo -e "    ${BOLD}Text (${#text_cmds[@]}):${NC} ${text_cmds[*]}"
    [[ ${#sys_cmds[@]} -gt 0 ]]  && echo -e "    ${BOLD}System (${#sys_cmds[@]}):${NC} ${sys_cmds[*]}"
}

# ---- MCP server helpers ----------------------------------------------------

# Parse an MCP_SERVERS entry into name, command, args array, and permission.
# Sets: _mcp_name, _mcp_command, _mcp_args (array), _mcp_permission
parse_mcp_server() {
    local IFS='|'
    read -r _mcp_name _mcp_command _mcp_args_csv _mcp_permission <<< "$1"
    IFS=',' read -ra _mcp_args <<< "$_mcp_args_csv"
}

# Display a list of MCP servers for interactive prompts.
# Usage: display_mcp_list "entry1" "entry2" ...
display_mcp_list() {
    for server_def in "$@"; do
        parse_mcp_server "$server_def"
        echo -e "  • ${BOLD}${_mcp_name}${NC} — ${_mcp_command} ${_mcp_args[*]}"
    done
}

# Check whether an MCP server is already configured for a given tool.
# Usage: is_mcp_configured <tool> <server_name>
is_mcp_configured() {
    local tool="$1" name="$2"
    case "$tool" in
        claude)
            [[ -f "$HOME/.claude.json" ]] \
                && jq -e --arg n "$name" '.mcpServers[$n]' "$HOME/.claude.json" &>/dev/null
            ;;
        gemini)
            [[ -f "$HOME/.gemini/settings.json" ]] \
                && jq -e --arg n "$name" '.mcpServers[$n]' "$HOME/.gemini/settings.json" &>/dev/null
            ;;
        codex)
            [[ -f "$HOME/.codex/config.toml" ]] \
                && grep -qF "[mcp_servers.${name}]" "$HOME/.codex/config.toml" 2>/dev/null
            ;;
        copilot)
            [[ -f "$HOME/.copilot/mcp-config.json" ]] \
                && jq -e --arg n "$name" '.mcpServers[$n]' "$HOME/.copilot/mcp-config.json" &>/dev/null
            ;;
    esac
}

# Add an MCP server using the tool's CLI.
# Usage: add_mcp_server <tool> <name> <command> [args...]
add_mcp_server() {
    local tool="$1" name="$2" cmd="$3"
    shift 3
    # On Windows, npx/node commands need a cmd /c wrapper for stdio MCP servers
    if [[ "$(uname -s)" == MINGW* || "$(uname -s)" == MSYS* || "$(uname -s)" == CYGWIN* ]]; then
        set -- "$cmd" "$@"
        cmd="cmd"
        set -- "/c" "$@"
    fi
    case "$tool" in
        claude)  claude mcp add --scope user "$name" -- "$cmd" "$@" 2>/dev/null ;;
        gemini)  gemini mcp add --scope user "$name" "$cmd" "$@" 2>/dev/null ;;
        codex)   codex mcp add "$name" -- "$cmd" "$@" 2>/dev/null ;;
        copilot)
            local config="$HOME/.copilot/mcp-config.json"
            [[ -f "$config" ]] || echo '{"mcpServers":{}}' > "$config"
            local args_json updated
            args_json=$(printf '%s\n' "$@" | jq -R . | jq -s .)
            updated=$(jq --arg n "$name" --arg c "$cmd" --argjson a "$args_json" \
                '.mcpServers[$n] = {"type":"local","command":$c,"args":$a}' "$config")
            echo "$updated" | jq . > "$config"
            ;;
    esac
}

# Check whether an MCP auto-approve permission exists for a given tool.
# Returns success for tools without a known permission model (e.g. codex).
is_mcp_permitted() {
    local tool="$1" permission="$2"
    case "$tool" in
        claude)
            [[ -f "$HOME/.claude/settings.json" ]] \
                && jq -e --arg p "$permission" '(.permissions.allow // []) | index($p)' \
                    "$HOME/.claude/settings.json" &>/dev/null
            ;;
        gemini)
            [[ -f "$HOME/.gemini/settings.json" ]] \
                && jq -e --arg p "$permission" '(.tools.allowed // []) | index($p)' \
                    "$HOME/.gemini/settings.json" &>/dev/null
            ;;
        *) return 0 ;;
    esac
}

# Add an auto-approve permission for MCP tools.
add_mcp_permission() {
    local tool="$1" permission="$2"
    case "$tool" in
        claude)
            local file="$HOME/.claude/settings.json"
            local updated
            updated=$(jq --arg p "$permission" \
                '.permissions.allow = ((.permissions.allow // []) + [$p])' "$file")
            echo "$updated" | jq . > "$file"
            ;;
        gemini)
            local file="$HOME/.gemini/settings.json"
            local updated
            updated=$(jq --arg p "$permission" \
                '.tools.allowed = ((.tools.allowed // []) + [$p])' "$file")
            echo "$updated" | jq . > "$file"
            ;;
    esac
}

# Generic MCP server configuration for any supported tool.
# Usage: configure_mcp <tool> <display_name> <cli_command>
configure_mcp() {
    local tool="$1" display_name="$2" cli_command="$3"

    if ! command -v "$cli_command" &>/dev/null; then
        print_warning "$cli_command command not found — skipping MCP configuration"
        return
    fi

    if ! command -v npx &>/dev/null; then
        print_warning "npx not found — skipping MCP servers (install Node.js)"
        return
    fi

    echo ""
    echo -e "${BOLD}── ${display_name} MCP Servers ──${NC}"

    local missing_mcp=()
    for server_def in "${MCP_SERVERS[@]}"; do
        parse_mcp_server "$server_def"
        is_mcp_configured "$tool" "$_mcp_name" && continue
        missing_mcp+=("$server_def")
    done

    if [[ ${#missing_mcp[@]} -eq 0 ]]; then
        echo -e "  ${DIM}MCP servers already configured${NC}"
    else
        echo ""
        echo "  MCP servers to configure (user scope — available in all projects):"
        echo ""
        display_mcp_list "${missing_mcp[@]}"
        echo ""

        if prompt_yes_no "  Add MCP server configuration?"; then
            for server_def in "${missing_mcp[@]}"; do
                parse_mcp_server "$server_def"
                if add_mcp_server "$tool" "$_mcp_name" "$_mcp_command" "${_mcp_args[@]}"; then
                    print_success "Added $_mcp_name MCP server"
                else
                    print_warning "Failed to add $_mcp_name MCP server"
                fi
            done
        else
            print_info "Skipped ${display_name} MCP servers"
        fi
    fi

    # ── Ensure auto-approve permissions for configured MCP servers ──
    local missing_perms=()
    for server_def in "${MCP_SERVERS[@]}"; do
        parse_mcp_server "$server_def"
        [[ -z "$_mcp_permission" ]] && continue
        is_mcp_configured "$tool" "$_mcp_name" || continue
        is_mcp_permitted "$tool" "$_mcp_permission" && continue
        missing_perms+=("$_mcp_permission")
    done

    if [[ ${#missing_perms[@]} -gt 0 ]]; then
        echo ""
        echo "  Auto-approve permissions to add:"
        echo ""
        for perm in "${missing_perms[@]}"; do
            echo -e "  • ${BOLD}${perm}${NC}"
        done
        echo ""
        if prompt_yes_no "  Add auto-approve permissions for MCP tools?"; then
            for perm in "${missing_perms[@]}"; do
                add_mcp_permission "$tool" "$perm"
                print_success "Auto-approved $perm"
            done
        else
            print_info "Skipped MCP auto-approve permissions"
        fi
    fi
}

# ---- generic install function ----------------------------------------------
#
# Usage:
#   install_commands <display_name> <src_dir> <dest_dir> \
#                    <mode> <marker> <prefix> <desc_fn>
#
# mode:   "file:<ext>" for single-file commands (e.g. "file:md", "file:toml")
#         "skill"      for directory-based Codex skills
# prefix: "/" for slash commands, "\$" for Codex skills

install_commands() {
    local display_name="$1"
    local src_dir="$2"
    local dest_dir="$3"
    local mode="$4"
    local marker="$5"
    local prefix="$6"
    local desc_fn="$7"

    if [[ ! -d "$src_dir" ]]; then
        print_warning "No commands found in $src_dir/"
        return
    fi

    # Discover source entries.
    local entries=()
    if [[ "$mode" == skill ]]; then
        while IFS= read -r -d '' d; do
            [[ -f "$d/SKILL.md" ]] && entries+=("$d")
        done < <(find "$src_dir" -mindepth 1 -maxdepth 1 -type d -print0 | sort -z)
    else
        local ext="${mode#file:}"
        while IFS= read -r -d '' f; do
            entries+=("$f")
        done < <(find "$src_dir" -name "*.$ext" -print0 | sort -z)
    fi

    if [[ ${#entries[@]} -eq 0 ]]; then
        print_warning "No commands found in $src_dir/"
        return
    fi

    echo ""
    echo -e "${BOLD}── ${display_name} ──${NC}"
    mkdir -p "$dest_dir"

    local installed=0 updated=0 skipped=0 current=0

    for entry in "${entries[@]}"; do
        local cmd_name src_file dest_file dest_entry

        if [[ "$mode" == skill ]]; then
            cmd_name=$(basename "$entry")
            src_file="$entry/SKILL.md"
            dest_entry="$dest_dir/$cmd_name"
            dest_file="$dest_entry/SKILL.md"
        else
            local filename
            filename=$(basename "$entry")
            local ext="${mode#file:}"
            cmd_name="${filename%."$ext"}"
            src_file="$entry"
            dest_file="$dest_dir/$filename"
            dest_entry="$dest_file"
        fi

        local desc
        desc=$("$desc_fn" "$src_file")
        local label="${prefix}${cmd_name}"

        # Already installed with our marker?
        local dest_exists=false
        if [[ "$mode" == skill ]]; then
            [[ -d "$dest_entry" ]] && [[ -f "$dest_file" ]] && dest_exists=true
        else
            [[ -f "$dest_file" ]] && dest_exists=true
        fi

        if $dest_exists; then
            if has_marker "$marker" "$dest_file"; then
                if is_up_to_date "$src_file" "$dest_file" "$marker"; then
                    echo -e "  ${DIM}${label} — up to date${NC}"
                    ((++current))
                else
                    if [[ "$mode" == skill ]]; then
                        rm -rf "$dest_entry"
                        cp -r "$entry" "$dest_entry"
                    else
                        cp "$src_file" "$dest_file"
                    fi
                    has_marker "$marker" "$dest_file" || printf '\n%s\n' "$marker" >> "$dest_file"
                    print_success "Updated ${label}"
                    ((++updated))
                fi
            else
                if $FORCE; then
                    if [[ "$mode" == skill ]]; then
                        rm -rf "$dest_entry"
                        cp -r "$entry" "$dest_entry"
                    else
                        cp "$src_file" "$dest_file"
                    fi
                    has_marker "$marker" "$dest_file" || printf '\n%s\n' "$marker" >> "$dest_file"
                    print_success "Overwritten ${label} (was custom)"
                    ((++installed))
                else
                    print_warning "${label} exists (custom) — skipped"
                    ((++skipped))
                fi
            fi
        else
            echo ""
            echo -e "  ${BOLD}${label}${NC}"
            echo -e "  ${desc}"
            if prompt_yes_no "  Install?"; then
                if [[ "$mode" == skill ]]; then
                    cp -r "$entry" "$dest_entry"
                else
                    cp "$src_file" "$dest_file"
                fi
                printf '\n%s\n' "$marker" >> "$dest_file"
                print_success "Installed ${label}"
                ((++installed))
            else
                print_info "Skipped ${label}"
                ((++skipped))
            fi
        fi
    done

    echo -e "  ${BOLD}${display_name}:${NC} $installed installed, $updated updated, $current up to date, $skipped skipped"
}

# ---- Claude Code settings configuration ------------------------------------

configure_claude_settings() {
    local settings_file="$HOME/.claude/settings.json"

    echo ""
    echo -e "${BOLD}── Claude Code Settings ──${NC}"

    mkdir -p "$HOME/.claude"
    if [[ ! -f "$settings_file" ]]; then
        echo '{}' > "$settings_file"
    fi

    if ! jq empty "$settings_file" 2>/dev/null; then
        print_warning "$HOME/.claude/settings.json is not valid JSON — skipping"
        return
    fi

    local settings updated
    settings=$(cat "$settings_file")
    updated="$settings"
    local changed=false

    # ── Check feature settings ──────────────────────────────────
    local feature_changes=()

    if ! echo "$settings" | jq -e '(.permissions.allow // []) | index("WebFetch")' &>/dev/null; then
        feature_changes+=("webfetch")
    fi
    if ! echo "$settings" | jq -e '(.permissions.allow // []) | index("WebSearch")' &>/dev/null; then
        feature_changes+=("websearch")
    fi
    if ! echo "$settings" | jq -e '.attribution' &>/dev/null; then
        feature_changes+=("attribution")
    fi
    if ! echo "$settings" | jq -e '.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS' &>/dev/null; then
        feature_changes+=("teams")
    fi
    if ! echo "$settings" | jq -e '.env.CLAUDE_CODE_NO_FLICKER' &>/dev/null; then
        feature_changes+=("noflicker")
    fi
    if [[ "$(uname -s)" == MINGW* || "$(uname -s)" == MSYS* || "$(uname -s)" == CYGWIN* ]]; then
        if ! echo "$settings" | jq -e '.env.CLAUDE_CODE_USE_POWERSHELL_TOOL' &>/dev/null; then
            feature_changes+=("powershell")
        fi
    fi

    # ── Check read-only permissions (batch jq, handles legacy :* format) ──
    local perms_json
    perms_json=$(printf '%s\n' "${CLAUDE_READONLY_PERMS[@]}" | jq -R . | jq -s .)

    local missing_perms=()
    while IFS= read -r perm; do
        [[ -n "$perm" ]] && missing_perms+=("$perm")
    done < <(echo "$settings" | jq -r --argjson perms "$perms_json" \
        '(.permissions.allow // []) as $e | $perms[] | select(. as $p |
            ($p | sub(" \\*\\)$"; ":*)")) as $legacy |
            ($e | index($p) | not) and ($e | index($legacy) | not))')

    # ── Nothing to do? ──────────────────────────────────────────
    if [[ ${#feature_changes[@]} -eq 0 ]] && [[ ${#missing_perms[@]} -eq 0 ]]; then
        echo -e "  ${DIM}Settings already configured — nothing to do${NC}"
        return
    fi

    # ── Prompt: feature settings ────────────────────────────────
    if [[ ${#feature_changes[@]} -gt 0 ]]; then
        echo ""
        echo "  The following will be added to $HOME/.claude/settings.json:"
        echo ""
        for change in "${feature_changes[@]}"; do
            case "$change" in
                webfetch)    echo -e "  • ${BOLD}WebFetch${NC} — allow web page fetching without prompting" ;;
                websearch)   echo -e "  • ${BOLD}WebSearch${NC} — allow web searches without prompting" ;;
                attribution) echo -e "  • ${BOLD}attribution${NC} — disable commit/PR attribution tags" ;;
                teams)       echo -e "  • ${BOLD}CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1${NC} — enable agent teams" ;;
                noflicker)   echo -e "  • ${BOLD}CLAUDE_CODE_NO_FLICKER=1${NC} — flicker-free fullscreen rendering" ;;
                powershell)  echo -e "  • ${BOLD}CLAUDE_CODE_USE_POWERSHELL_TOOL=1${NC} — enable native PowerShell tool" ;;
            esac
        done
        echo ""
        if prompt_yes_no "  Apply these settings?"; then
            for change in "${feature_changes[@]}"; do
                case "$change" in
                    webfetch)    updated=$(echo "$updated" | jq '.permissions.allow = ((.permissions.allow // []) + ["WebFetch"])') ;;
                    websearch)   updated=$(echo "$updated" | jq '.permissions.allow = ((.permissions.allow // []) + ["WebSearch"])') ;;
                    attribution) updated=$(echo "$updated" | jq '.attribution = {"commit": "", "pr": ""}') ;;
                    teams)       updated=$(echo "$updated" | jq '.env = ((.env // {}) + {"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"})') ;;
                    noflicker)   updated=$(echo "$updated" | jq '.env = ((.env // {}) + {"CLAUDE_CODE_NO_FLICKER": "1"})') ;;
                    powershell)  updated=$(echo "$updated" | jq '.env = ((.env // {}) + {"CLAUDE_CODE_USE_POWERSHELL_TOOL": "1"})') ;;
                esac
            done
            changed=true
        fi
    fi

    # ── Prompt: read-only permissions ───────────────────────────
    if [[ ${#missing_perms[@]} -gt 0 ]]; then
        echo ""
        echo -e "  Recommended read-only developer permissions (${#missing_perms[@]} commands):"
        echo ""

        local raw_cmds=()
        for perm in "${missing_perms[@]}"; do
            local cmd="${perm#Bash(}"
            raw_cmds+=("${cmd% *)}")
        done
        display_permission_summary "${raw_cmds[@]}"

        echo ""
        if prompt_yes_no "  Add recommended read-only permissions?"; then
            local add_json
            add_json=$(printf '%s\n' "${missing_perms[@]}" | jq -R . | jq -s .)
            updated=$(echo "$updated" | jq --argjson add "$add_json" \
                '.permissions.allow = ((.permissions.allow // []) + $add)')
            changed=true
        fi
    fi

    # ── Write result ────────────────────────────────────────────
    if $changed; then
        echo "$updated" | jq . > "$settings_file"
        print_success "Claude Code settings updated"
    else
        print_info "Skipped Claude Code settings"
    fi
}

# ---- Gemini CLI settings configuration -------------------------------------

configure_gemini_settings() {
    local settings_file="$HOME/.gemini/settings.json"
    local policy_dir="$HOME/.gemini/policies"
    local policy_src=".gemini/policies/readonly-tools.toml"
    local policy_dest="$policy_dir/readonly-tools.toml"

    echo ""
    echo -e "${BOLD}── Gemini CLI Settings ──${NC}"

    mkdir -p "$HOME/.gemini" "$policy_dir"

    # Ensure settings.json exists so downstream functions (e.g. add_mcp_permission)
    # can safely run jq against it on fresh installs.
    if [[ ! -f "$settings_file" ]]; then
        echo '{}' > "$settings_file"
    fi

    if ! jq empty "$settings_file" 2>/dev/null; then
        print_warning "$HOME/.gemini/settings.json is not valid JSON — skipping"
        return
    fi

    local actions=()

    # ── Check if policy file needs install/update ───────────────
    if [[ -f "$policy_src" ]]; then
        if [[ ! -f "$policy_dest" ]]; then
            actions+=("install_policy")
        elif ! has_marker "$TOML_MARKER" "$policy_dest"; then
            # Exists but not managed by us — skip unless forced
            if $FORCE; then
                actions+=("install_policy")
            fi
        elif ! is_up_to_date "$policy_src" "$policy_dest" "$TOML_MARKER"; then
            actions+=("update_policy")
        fi
    fi

    # ── Check for deprecated tools.allowed to migrate ──────────
    # Only flag for migration when there are non-MCP entries (mcp__* entries
    # are auto-approve permissions that belong in tools.allowed).
    if [[ -f "$settings_file" ]] && jq empty "$settings_file" 2>/dev/null; then
        if jq -e '[.tools.allowed[]? | select(startswith("mcp__") | not)] | length > 0' \
                "$settings_file" &>/dev/null; then
            actions+=("migrate_tools_allowed")
        fi
    fi

    # ── Nothing to do? ──────────────────────────────────────────
    if [[ ${#actions[@]} -eq 0 ]]; then
        echo -e "  ${DIM}Settings already configured — nothing to do${NC}"
        return
    fi

    # ── Install / update policy file ───────────────────────────
    local policy_active=false
    if [[ " ${actions[*]} " == *" install_policy "* ]] || [[ " ${actions[*]} " == *" update_policy "* ]]; then
        local verb="Install"
        [[ " ${actions[*]} " == *" update_policy "* ]] && verb="Update"

        echo ""
        echo "  Read-only permissions policy file:"
        echo -e "    ${BOLD}$policy_dest${NC}"
        echo ""
        echo "  Covers: web tools, built-in read tools, git, gh, file inspection,"
        echo "  text processing, and system info commands."
        echo ""
        if prompt_yes_no "  $verb read-only policy file?"; then
            cp "$policy_src" "$policy_dest"
            has_marker "$TOML_MARKER" "$policy_dest" || printf '\n%s\n' "$TOML_MARKER" >> "$policy_dest"
            print_success "${verb}ed $policy_dest"
            policy_active=true
        else
            print_info "Skipped policy file"
        fi
    elif has_marker "$TOML_MARKER" "$policy_dest" 2>/dev/null; then
        # Policy file already installed and up-to-date
        policy_active=true
    fi

    # ── Migrate deprecated tools.allowed ───────────────────────
    # Only offer migration when the policy file is in place, otherwise
    # removing tools.allowed leaves the user with no configured permissions.
    if [[ " ${actions[*]} " == *" migrate_tools_allowed "* ]] && $policy_active; then
        echo ""
        echo -e "  ${YELLOW}Deprecated:${NC} tools.allowed in settings.json"
        echo "  These permissions are now handled by the Policy Engine file above."
        echo ""
        if prompt_yes_no "  Remove deprecated tools.allowed from settings.json?"; then
            local updated
            # Preserve MCP auto-approve entries (mcp__*); only strip non-MCP entries.
            # Delete only .tools.allowed (not the entire .tools object) to keep
            # any other user settings under .tools intact.
            updated=$(jq '
                .tools.allowed = [.tools.allowed[] | select(startswith("mcp__"))]
                | if .tools.allowed == [] then del(.tools.allowed) else . end
            ' "$settings_file")
            echo "$updated" | jq . > "$settings_file"
            print_success "Removed deprecated tools.allowed from settings.json"
        else
            print_info "Kept tools.allowed (Gemini will show a deprecation warning)"
        fi
    fi
}

# ---- Codex CLI settings configuration ---------------------------------------

configure_codex_settings() {
    local config_file="$HOME/.codex/config.toml"

    echo ""
    echo -e "${BOLD}── Codex CLI Settings ──${NC}"

    mkdir -p "$HOME/.codex"
    if [[ ! -f "$config_file" ]]; then
        touch "$config_file"
    fi

    local changes=()
    local changed=false

    # Check for deprecated collab feature flag
    if grep -qE '^collab\s*=' "$config_file" 2>/dev/null; then
        changes+=("remove_collab")
    fi

    # Check if multi_agent is enabled under [features]
    if ! grep -qE '^multi_agent\s*=\s*true' "$config_file" 2>/dev/null; then
        changes+=("add_multi_agent")
    fi

    if [[ ${#changes[@]} -eq 0 ]]; then
        echo -e "  ${DIM}Settings already configured — nothing to do${NC}"
        return
    fi

    echo ""
    echo "  The following changes will be applied to $config_file:"
    echo ""
    for change in "${changes[@]}"; do
        case "$change" in
            remove_collab)   echo -e "  • ${BOLD}Remove collab${NC} — deprecated, replaced by multi_agent" ;;
            add_multi_agent) echo -e "  • ${BOLD}multi_agent = true${NC} — enable multi-agent collaboration" ;;
        esac
    done
    echo ""

    if prompt_yes_no "  Apply these settings?"; then
        for change in "${changes[@]}"; do
            case "$change" in
                remove_collab)
                    sed -i.bak '/^collab[[:space:]]*=/d' "$config_file"
                    rm -f "${config_file}.bak"
                    ;;
                add_multi_agent)
                    # Ensure [features] section exists and add multi_agent under it
                    if grep -qE '^\[features\]' "$config_file" 2>/dev/null; then
                        sed -i.bak '/^\[features\]/a\
multi_agent = true' "$config_file"
                        rm -f "${config_file}.bak"
                    else
                        printf '\n[features]\nmulti_agent = true\n' >> "$config_file"
                    fi
                    ;;
            esac
        done
        changed=true
    fi

    if $changed; then
        print_success "Codex CLI settings updated"
    else
        print_info "Skipped Codex CLI settings"
    fi
}

# ---- Copilot CLI settings configuration -------------------------------------

configure_copilot_settings() {
    local config_file="$HOME/.copilot/config.json"

    echo ""
    echo -e "${BOLD}── Copilot CLI Settings ──${NC}"

    mkdir -p "$HOME/.copilot"
    if [[ ! -f "$config_file" ]]; then
        echo '{}' > "$config_file"
    fi

    if ! jq empty "$config_file" 2>/dev/null; then
        print_warning "$HOME/.copilot/config.json is not valid JSON — skipping"
        return
    fi

    echo -e "  ${DIM}No settings to configure${NC}"
}

# ---- review loop script installer -----------------------------------------
#
# Symlinks executable scripts from bin/ to ~/.local/bin/ so they are on PATH.
# Falls back to copying if symlinks are not supported (e.g. Windows without
# developer mode).

install_scripts() {
    local src_dir="$1"
    shift
    local dest_dir="$HOME/.local/bin"

    if [[ ! -d "$src_dir" ]]; then
        return
    fi

    # Use explicit script list if provided, otherwise discover all files
    local scripts=()
    if [[ $# -gt 0 ]]; then
        scripts=("$@")
    else
        while IFS= read -r -d '' f; do
            scripts+=("$f")
        done < <(find "$src_dir" -maxdepth 1 -type f -print0 | LC_ALL=C sort -z 2>/dev/null || find "$src_dir" -maxdepth 1 -type f | LC_ALL=C sort | tr '\n' '\0')
    fi

    if [[ ${#scripts[@]} -eq 0 ]]; then
        return
    fi

    echo ""
    echo -e "${BOLD}── Review Loop Scripts ──${NC}"
    echo ""
    echo "  Scripts to install to $dest_dir/:"
    echo ""
    for script in "${scripts[@]}"; do
        local name
        name=$(basename "$script")
        echo -e "  • ${BOLD}${name}${NC}"
    done
    echo ""

    if ! prompt_yes_no "  Install review loop scripts?"; then
        print_info "Skipped review loop scripts"
        return
    fi

    mkdir -p "$dest_dir"

    local installed=0 updated=0 current=0 skipped=0

    for script in "${scripts[@]}"; do
        local name abs_src dest
        name=$(basename "$script")
        abs_src="$(cd "$(dirname "$script")" && pwd)/$name"
        dest="$dest_dir/$name"

        if [[ -L "$dest" ]]; then
            local target
            target=$(readlink "$dest" 2>/dev/null) || true
            if [[ "$target" == "$abs_src" ]]; then
                echo -e "  ${DIM}${name} — up to date (symlinked)${NC}"
                ((++current))
                continue
            fi
            # Stale symlink (old checkout path) — remove and re-link below
            rm -f "$dest"
            local is_update=true
        fi

        if [[ -f "$dest" ]]; then
            # Check if we manage it (has our marker comment)
            if head -5 "$dest" | grep -qF "source: ai-coding-setup" 2>/dev/null; then
                if diff -q "$abs_src" "$dest" &>/dev/null; then
                    echo -e "  ${DIM}${name} — up to date (copied)${NC}"
                    ((++current))
                    continue
                fi
                rm -f "$dest"
                # falls through to symlink/copy below as an update
                local is_update=true
            else
                if $FORCE; then
                    rm -f "$dest"
                else
                    print_warning "${name} exists in $dest_dir (custom) — skipped"
                    ((++skipped))
                    continue
                fi
            fi
        fi

        # Try symlink first, fall back to copy
        if ln -sf "$abs_src" "$dest" 2>/dev/null; then
            if [[ "${is_update:-}" == true ]]; then
                print_success "Updated $name (symlinked)"
                ((++updated))
            else
                print_success "Symlinked $name"
                ((++installed))
            fi
        else
            cp "$abs_src" "$dest"
            chmod +x "$dest"
            if [[ "${is_update:-}" == true ]]; then
                print_success "Updated $name (copied)"
                ((++updated))
            else
                print_success "Copied $name to $dest_dir/"
                ((++installed))
            fi
        fi
        unset is_update
    done

    # Check PATH
    if [[ ":$PATH:" != *":$dest_dir:"* ]]; then
        echo ""
        print_warning "$dest_dir is not in your PATH"
        echo "  Add this to your shell profile (~/.bashrc, ~/.zshrc, or ~/.profile):"
        echo ""
        echo "    export PATH=\"\$HOME/.local/bin:\$PATH\""
        echo ""
    fi

    echo -e "  ${BOLD}Scripts:${NC} $installed installed, $updated updated, $current up to date, $skipped skipped"
}

# ---- argument parsing ----------------------------------------------------

while [[ $# -gt 0 ]]; do
    case "$1" in
        -f|--force) FORCE=true; shift ;;
        -h|--help)
            echo "Usage: setup [-f|--force]"
            echo "  -f, --force  Overwrite custom (non-managed) files"
            exit 0 ;;
        *) echo "Unknown option: $1"; exit 1 ;;
    esac
done

# ---- prerequisite checks --------------------------------------------------

if [[ ! -d ".claude/commands" ]] && [[ ! -d ".gemini/commands" ]] && [[ ! -d ".codex/skills" ]] && [[ ! -d ".copilot/skills" ]]; then
    print_error "No command directories found (.claude/commands, .gemini/commands, .codex/skills, .copilot/skills)."
    print_error "Please run this script from the ai-coding-setup repository root."
    exit 1
fi

missing=()

if ! command -v gh &>/dev/null; then
    missing+=("gh")
fi

if ! command -v jq &>/dev/null; then
    missing+=("jq")
fi

if [[ ${#missing[@]} -gt 0 ]]; then
    print_error "Missing required tools: ${missing[*]}"
    echo ""
    for tool in "${missing[@]}"; do
        case "$tool" in
            gh) echo "  gh  — GitHub CLI:      brew install gh      (https://cli.github.com/)" ;;
            jq) echo "  jq  — JSON processor:  brew install jq      (https://jqlang.github.io/jq/)" ;;
        esac
    done
    echo ""
    exit 1
fi

# ---- detect installed tools -----------------------------------------------

detected_tools=()

if command -v claude &>/dev/null; then
    detected_tools+=("claude")
fi

if command -v gemini &>/dev/null; then
    detected_tools+=("gemini")
fi

if command -v codex &>/dev/null; then
    detected_tools+=("codex")
fi

if command -v copilot &>/dev/null; then
    detected_tools+=("copilot")
fi

if [[ ${#detected_tools[@]} -eq 0 ]]; then
    print_error "No supported AI coding tools detected."
    echo ""
    echo "  Install at least one of:"
    echo "  - Claude Code:  https://docs.anthropic.com/en/docs/claude-code"
    echo "  - Gemini CLI:   https://github.com/google-gemini/gemini-cli"
    echo "  - Codex CLI:    https://github.com/openai/codex"
    echo "  - Copilot CLI:  https://docs.github.com/en/copilot/copilot-cli"
    echo ""
    exit 1
fi

# ---- tool selection --------------------------------------------------------

echo ""
print_info "Detected AI coding tools:"
echo ""

for i in "${!detected_tools[@]}"; do
    tool="${detected_tools[$i]}"
    case "$tool" in
        claude)  echo -e "  ${BOLD}$((i + 1)))${NC} Claude Code" ;;
        gemini)  echo -e "  ${BOLD}$((i + 1)))${NC} Gemini CLI" ;;
        codex)   echo -e "  ${BOLD}$((i + 1)))${NC} Codex CLI" ;;
        copilot) echo -e "  ${BOLD}$((i + 1)))${NC} Copilot CLI" ;;
    esac
done

echo ""
read -rp "$(echo -e "${BOLD}Which tools to set up? (comma-separated numbers, or 'a' for all):${NC} ")" tool_selection

selected_tools=()
if [[ "$tool_selection" =~ ^[Aa]$ ]]; then
    selected_tools=("${detected_tools[@]}")
else
    IFS=',' read -ra selections <<< "$tool_selection"
    for sel in "${selections[@]}"; do
        sel=$(echo "$sel" | tr -d '[:space:]')
        if [[ "$sel" =~ ^[0-9]+$ ]] && (( sel >= 1 && sel <= ${#detected_tools[@]} )); then
            selected_tools+=("${detected_tools[$((sel - 1))]}")
        fi
    done
fi

if [[ ${#selected_tools[@]} -eq 0 ]]; then
    print_info "No tools selected. Exiting."
    exit 0
fi

# ---- run installs ----------------------------------------------------------

for tool in "${selected_tools[@]}"; do
    case "$tool" in
        claude)
            install_commands "Claude Code" \
                ".claude/commands" "$HOME/.claude/commands" \
                "file:md" "$MD_MARKER" "/" "get_md_description"
            configure_claude_settings
            configure_mcp "claude" "Claude Code" "claude"
            ;;
        gemini)
            install_commands "Gemini CLI" \
                ".gemini/commands" "$HOME/.gemini/commands" \
                "file:toml" "$TOML_MARKER" "/" "get_toml_description"
            configure_gemini_settings
            configure_mcp "gemini" "Gemini CLI" "gemini"
            ;;
        codex)
            install_commands "Codex CLI Skills" \
                ".codex/skills" "$HOME/.codex/skills" \
                "skill" "$MD_MARKER" "\$" "get_skill_description"
            configure_codex_settings
            configure_mcp "codex" "Codex CLI" "codex"
            ;;
        copilot)
            install_commands "Copilot CLI Skills" \
                ".copilot/skills" "$HOME/.copilot/skills" \
                "skill" "$MD_MARKER" "/" "get_skill_description"
            configure_copilot_settings
            configure_mcp "copilot" "Copilot CLI" "copilot"
            ;;
    esac
done

# ---- install shared prompts ------------------------------------------------

# Shared prompts are agent-agnostic and consumed by the review loop scripts.
# Installed to ~/.local/share/ai-coding-setup/prompts/ via symlinks.
_prompts_dest="$HOME/.local/share/ai-coding-setup/prompts"

if [[ -d "prompts" ]]; then
    _prompts_src_dir="$(cd "$(dirname "prompts/code-review.md")" && pwd)"
    mkdir -p "$_prompts_dest"
    for _prompt_file in prompts/*.md; do
        [[ -f "$_prompt_file" ]] || continue
        _name=$(basename "$_prompt_file")
        _src="$_prompts_src_dir/$_name"
        _dest="$_prompts_dest/$_name"
        if [[ -L "$_dest" ]]; then
            _target=$(readlink "$_dest" 2>/dev/null) || true
            [[ "$_target" != "$_src" ]] && ln -sf "$_src" "$_dest"
        elif [[ -f "$_dest" ]]; then
            # Plain file — only replace if it carries our marker (previous
            # copy-based install) or --force is set; otherwise preserve user edits.
            if has_marker "$MD_MARKER" "$_dest" || $FORCE; then
                if ln -sf "$_src" "$_dest" 2>/dev/null && [[ -L "$_dest" ]]; then :; else
                    cp "$_src" "$_dest"
                    has_marker "$MD_MARKER" "$_dest" || printf '\n%s\n' "$MD_MARKER" >> "$_dest"
                fi
            else
                print_warning "$_name exists (custom) — skipped (use --force to overwrite)"
            fi
        else
            if ln -sf "$_src" "$_dest" 2>/dev/null && [[ -L "$_dest" ]]; then :; else
                cp "$_src" "$_dest"
                printf '\n%s\n' "$MD_MARKER" >> "$_dest"
            fi
        fi
    done
fi

# ---- install review loop scripts -------------------------------------------

# Each review-loop script has its own prompt-file dependencies.  Only gate on
# the prompts that the specific script validates at runtime so that one script
# can be installed even when the other's prompts are not yet present.
# Agent selection is configurable at runtime via ~/.ai-coding-setup.conf and
# CLI flags, so we no longer require both claude and codex to be installed.
review_loop_scripts=()

# code-review-loop needs editor + reviewer prompts
if [[ -f "$_prompts_dest/code-review.md" ]] \
    && [[ -f "$_prompts_dest/code-review-followup.md" ]] \
    && [[ -f "$_prompts_dest/code-review-response.md" ]] \
    && [[ -f "$_prompts_dest/code-refinement.md" ]]; then
    review_loop_scripts+=("bin/code-review-loop")
fi
# plan-review-loop needs reviewer prompts
if [[ -f "$_prompts_dest/plan-review.md" ]] \
    && [[ -f "$_prompts_dest/plan-review-followup.md" ]]; then
    review_loop_scripts+=("bin/plan-review-loop")
fi

if [[ ${#review_loop_scripts[@]} -gt 0 ]]; then
    # Install the shared library to ~/.local/lib/ (not bin/ — it's sourced, not executed)
    _lib_dest="$HOME/.local/lib"
    _lib_src="$(cd "$(dirname "lib/lib-review-loop")" && pwd)/lib-review-loop"
    mkdir -p "$_lib_dest"
    if [[ -L "$_lib_dest/lib-review-loop" ]]; then
        _target=$(readlink "$_lib_dest/lib-review-loop" 2>/dev/null) || true
        [[ "$_target" != "$_lib_src" ]] && ln -sf "$_lib_src" "$_lib_dest/lib-review-loop"
    elif [[ -f "$_lib_dest/lib-review-loop" ]]; then
        if head -5 "$_lib_dest/lib-review-loop" | grep -qF "source: ai-coding-setup" 2>/dev/null; then
            ln -sf "$_lib_src" "$_lib_dest/lib-review-loop" 2>/dev/null \
                || cp "$_lib_src" "$_lib_dest/lib-review-loop"
        fi
    else
        ln -sf "$_lib_src" "$_lib_dest/lib-review-loop" 2>/dev/null \
            || cp "$_lib_src" "$_lib_dest/lib-review-loop"
    fi
    install_scripts "bin" "${review_loop_scripts[@]}"
elif [[ -d "bin" ]]; then
    echo ""
    echo -e "  ${DIM}Review loop scripts require shared prompts — skipped${NC}"
fi

# ---- create default config file if missing ---------------------------------

config_file="$HOME/.ai-coding-setup.conf"
if [[ ${#review_loop_scripts[@]} -gt 0 ]] && [[ ! -f "$config_file" ]]; then
    # Pick defaults from installed tools.  Prefer claude for editing (strong at
    # code changes) and codex/gemini for reviewing (second opinion), but fall
    # back to the same agent for both roles if only one tool is available.
    _default_editor="" _default_reviewer=""
    for _t in claude codex gemini copilot; do
        [[ " ${selected_tools[*]} " == *" $_t "* ]] || continue
        [[ -z "$_default_editor" ]] && _default_editor="$_t"
        [[ -n "$_default_editor" ]] && [[ "$_t" != "$_default_editor" ]] && _default_reviewer="$_t"
    done
    : "${_default_reviewer:=$_default_editor}"

    echo ""
    echo -e "${BOLD}── Review Loop Config ──${NC}"
    echo ""
    echo "  Default agent configuration file: $config_file"
    echo ""
    echo "  This file sets default agents for review loops (overridable via CLI flags)."
    echo "  Defaults based on selected tools: editor=$_default_editor, reviewer=$_default_reviewer"
    echo ""
    if prompt_yes_no "  Create config file with defaults?"; then
        cat > "$config_file" <<CONF
# ai-coding-setup — default agent configuration for review loops.
# These defaults can be overridden per-invocation with --editor / --reviewer flags.

# Agent for editing/implementation (claude, codex, gemini, copilot)
EDITOR_AGENT=$_default_editor

# Agent for reviewing (claude, codex, gemini, copilot)
REVIEWER_AGENT=$_default_reviewer
CONF
        print_success "Created $config_file"
    else
        print_info "Skipped config file creation"
    fi
fi

# ---- final summary ---------------------------------------------------------

echo ""
echo -e "${BOLD}=== Done ===${NC}"
echo ""
echo "Use your commands in:"

for tool in "${selected_tools[@]}"; do
    case "$tool" in
        claude)  echo -e "  Claude Code  — type ${BOLD}/command-name${NC} in the prompt" ;;
        gemini)  echo -e "  Gemini CLI   — type ${BOLD}/command-name${NC} in the prompt" ;;
        codex)   echo -e "  Codex CLI    — type ${BOLD}\$skill-name${NC} to invoke a skill" ;;
        copilot) echo -e "  Copilot CLI  — type ${BOLD}/skill-name${NC} in the prompt" ;;
    esac
done

if [[ ${#review_loop_scripts[@]} -gt 0 ]]; then
    echo ""
    echo -e "  Review loops — run ${BOLD}code-review-loop${NC} or ${BOLD}plan-review-loop${NC} from any project"
fi
echo ""