shipwright-cli 1.7.0

package/scripts/cct-templates.sh

@@ -0,0 +1,242 @@
+#!/usr/bin/env bash
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  cct-templates.sh — Browse and inspect team templates                   ║
+# ║                                                                          ║
+# ║  Templates define reusable agent team configurations (roles, layout,    ║
+# ║  focus areas) that shipwright session --template can use to scaffold teams.    ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+set -euo pipefail
+
+# ─── Colors ──────────────────────────────────────────────────────────────────
+CYAN='\033[38;2;0;212;255m'
+PURPLE='\033[38;2;124;58;237m'
+BLUE='\033[38;2;0;102;255m'
+GREEN='\033[38;2;74;222;128m'
+YELLOW='\033[38;2;250;204;21m'
+RED='\033[38;2;248;113;113m'
+DIM='\033[2m'
+BOLD='\033[1m'
+RESET='\033[0m'
+
+info()    { echo -e "${CYAN}${BOLD}▸${RESET} $*"; }
+success() { echo -e "${GREEN}${BOLD}✓${RESET} $*"; }
+warn()    { echo -e "${YELLOW}${BOLD}⚠${RESET} $*"; }
+error()   { echo -e "${RED}${BOLD}✗${RESET} $*" >&2; }
+
+# ─── Template Discovery ─────────────────────────────────────────────────────
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_TEMPLATES_DIR="$(cd "$SCRIPT_DIR/../tmux/templates" 2>/dev/null && pwd)" || REPO_TEMPLATES_DIR=""
+USER_TEMPLATES_DIR="${HOME}/.claude-teams/templates"
+
+# Find all template directories (user dir takes priority)
+find_template_dirs() {
+    local dirs=()
+    [[ -d "$USER_TEMPLATES_DIR" ]] && dirs+=("$USER_TEMPLATES_DIR")
+    [[ -n "$REPO_TEMPLATES_DIR" && -d "$REPO_TEMPLATES_DIR" ]] && dirs+=("$REPO_TEMPLATES_DIR")
+    printf '%s\n' "${dirs[@]}"
+}
+
+# Find a specific template file by name (user templates override repo)
+find_template() {
+    local name="$1"
+    # Strip .json extension if provided
+    name="${name%.json}"
+
+    if [[ -f "$USER_TEMPLATES_DIR/${name}.json" ]]; then
+        echo "$USER_TEMPLATES_DIR/${name}.json"
+        return 0
+    fi
+    if [[ -n "$REPO_TEMPLATES_DIR" && -f "$REPO_TEMPLATES_DIR/${name}.json" ]]; then
+        echo "$REPO_TEMPLATES_DIR/${name}.json"
+        return 0
+    fi
+    return 1
+}
+
+# ─── JSON Parsing (jq preferred, grep fallback) ──────────────────────────────
+
+# Extract a top-level string field from JSON
+json_field() {
+    local file="$1" field="$2"
+    if command -v jq &>/dev/null; then
+        jq -r ".${field} // \"\"" "$file" 2>/dev/null
+    else
+        grep -o "\"${field}\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" "$file" | head -1 | sed 's/.*: *"//;s/"$//'
+    fi
+}
+
+# Extract agent count from JSON
+json_agent_count() {
+    local file="$1"
+    if command -v jq &>/dev/null; then
+        jq -r '.agents // [] | length' "$file" 2>/dev/null
+    else
+        grep -c '"name"' "$file" 2>/dev/null | head -1
+    fi
+}
+
+# Print agent details from a template
+print_agents() {
+    local file="$1"
+    if command -v jq &>/dev/null; then
+        jq -r '.agents // [] | .[] | "\(.name // "?")|\(.role // "")|\(.focus // "")"' "$file" 2>/dev/null
+    else
+        # Best-effort grep fallback for simple cases
+        grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' "$file" | sed 's/.*"name"[[:space:]]*:[[:space:]]*"//;s/"$//'
+    fi
+}
+
+# ─── Commands ────────────────────────────────────────────────────────────────
+
+cmd_list() {
+    echo ""
+    echo -e "${CYAN}${BOLD}  Team Templates${RESET}"
+    echo -e "  ${DIM}─────────────────────────────────────────────${RESET}"
+    echo ""
+
+    local found=0
+
+    while IFS= read -r dir; do
+        [[ -z "$dir" ]] && continue
+        for file in "$dir"/*.json; do
+            [[ -f "$file" ]] || continue
+            found=1
+
+            local name description agent_count layout layout_style display_layout source
+            name="$(json_field "$file" "name")"
+            description="$(json_field "$file" "description")"
+            agent_count="$(json_agent_count "$file")"
+            layout="$(json_field "$file" "layout")"
+            layout_style="$(json_field "$file" "layout_style")"
+            display_layout="${layout_style:-$layout}"
+
+            # Tag user-created vs built-in
+            if [[ "$dir" == "$USER_TEMPLATES_DIR" ]]; then
+                source="${PURPLE}custom${RESET}"
+            else
+                source="${DIM}built-in${RESET}"
+            fi
+
+            echo -e "  ${CYAN}${BOLD}${name}${RESET}  ${DIM}(${agent_count} agents, ${display_layout})${RESET}  [${source}]"
+            echo -e "    ${description}"
+            echo ""
+        done
+    done < <(find_template_dirs)
+
+    if [[ "$found" -eq 0 ]]; then
+        warn "No templates found."
+        echo -e "  Templates are loaded from:"
+        echo -e "    ${DIM}${USER_TEMPLATES_DIR}/${RESET}  ${DIM}(custom)${RESET}"
+        [[ -n "$REPO_TEMPLATES_DIR" ]] && echo -e "    ${DIM}${REPO_TEMPLATES_DIR}/${RESET}  ${DIM}(built-in)${RESET}"
+        echo ""
+        return 1
+    fi
+
+    echo -e "  ${DIM}Usage: shipwright session my-feature --template <name>${RESET}"
+    echo -e "  ${DIM}Details: shipwright templates show <name>${RESET}"
+    echo ""
+}
+
+cmd_show() {
+    local name="${1:-}"
+    if [[ -z "$name" ]]; then
+        error "Template name required."
+        echo -e "  Usage: ${DIM}shipwright templates show <name>${RESET}"
+        exit 1
+    fi
+
+    local file
+    if ! file="$(find_template "$name")"; then
+        error "Template '${name}' not found."
+        echo ""
+        echo -e "  Available templates:"
+        while IFS= read -r dir; do
+            [[ -z "$dir" ]] && continue
+            for f in "$dir"/*.json; do
+                [[ -f "$f" ]] || continue
+                local tname
+                tname="$(json_field "$f" "name")"
+                echo -e "    ${CYAN}${tname}${RESET}"
+            done
+        done < <(find_template_dirs)
+        echo ""
+        exit 1
+    fi
+
+    local description layout layout_style main_pane_pct
+    description="$(json_field "$file" "description")"
+    layout="$(json_field "$file" "layout")"
+    layout_style="$(json_field "$file" "layout_style")"
+    main_pane_pct="$(json_field "$file" "main_pane_percent")"
+
+    echo ""
+    echo -e "  ${CYAN}${BOLD}Template: ${name}${RESET}"
+    echo -e "  ${DIM}─────────────────────────────────────────────${RESET}"
+    echo -e "  ${description}"
+    if [[ -n "$layout_style" ]]; then
+        echo -e "  Layout: ${BOLD}${layout_style}${RESET} ${DIM}(leader pane ${main_pane_pct:-65}%)${RESET}"
+    else
+        echo -e "  Layout: ${BOLD}${layout}${RESET}"
+    fi
+    echo ""
+    echo -e "  ${BOLD}Agents:${RESET}"
+
+    while IFS='|' read -r aname arole afocus; do
+        [[ -z "$aname" ]] && continue
+        echo -e "    ${PURPLE}${BOLD}${aname}${RESET}"
+        echo -e "      Role:  ${arole}"
+        echo -e "      Focus: ${DIM}${afocus}${RESET}"
+        echo ""
+    done < <(print_agents "$file")
+
+    echo -e "  ${DIM}Use: shipwright session my-feature --template ${name}${RESET}"
+    echo ""
+}
+
+show_help() {
+    echo ""
+    echo -e "${CYAN}${BOLD}  shipwright templates${RESET} — Browse and inspect team templates"
+    echo ""
+    echo -e "  ${BOLD}USAGE${RESET}"
+    echo -e "    ${CYAN}shipwright templates${RESET} list              List available templates"
+    echo -e "    ${CYAN}shipwright templates${RESET} show <name>       Show template details"
+    echo ""
+    echo -e "  ${BOLD}TEMPLATE LOCATIONS${RESET}"
+    echo -e "    ${DIM}~/.claude-teams/templates/${RESET}        Custom templates ${DIM}(takes priority)${RESET}"
+    [[ -n "$REPO_TEMPLATES_DIR" ]] && echo -e "    ${DIM}${REPO_TEMPLATES_DIR}/${RESET}  Built-in templates"
+    echo ""
+    echo -e "  ${BOLD}CREATING TEMPLATES${RESET}"
+    echo -e "    Drop a JSON file in ${DIM}~/.claude-teams/templates/${RESET}:"
+    echo ""
+    echo -e "    ${DIM}{"
+    echo -e "      \"name\": \"my-template\","
+    echo -e "      \"description\": \"What this team does\","
+    echo -e "      \"agents\": ["
+    echo -e "        {\"name\": \"agent-1\", \"role\": \"Does X\", \"focus\": \"src/\"},"
+    echo -e "        {\"name\": \"agent-2\", \"role\": \"Does Y\", \"focus\": \"tests/\"}"
+    echo -e "      ],"
+    echo -e "      \"layout\": \"tiled\""
+    echo -e "    }${RESET}"
+    echo ""
+}
+
+# ─── Main ────────────────────────────────────────────────────────────────────
+
+main() {
+    local subcmd="${1:-list}"
+    shift 2>/dev/null || true
+
+    case "$subcmd" in
+        list|ls)      cmd_list ;;
+        show|info)    cmd_show "$@" ;;
+        help|--help)  show_help ;;
+        *)
+            error "Unknown subcommand: ${subcmd}"
+            show_help
+            exit 1
+            ;;
+    esac
+}
+
+main "$@"

package/scripts/cct-upgrade.sh

@@ -0,0 +1,422 @@
+#!/usr/bin/env bash
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  cct upgrade — Detect and apply updates from the repo                   ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MANIFEST_DIR="$HOME/.claude-teams"
+MANIFEST="$MANIFEST_DIR/manifest.json"
+
+# ─── Colors ────────────────────────────────────────────────────────────────
+CYAN='\033[38;2;0;212;255m'
+PURPLE='\033[38;2;124;58;237m'
+BLUE='\033[38;2;0;102;255m'
+GREEN='\033[38;2;74;222;128m'
+YELLOW='\033[38;2;250;204;21m'
+RED='\033[38;2;248;113;113m'
+DIM='\033[2m'
+BOLD='\033[1m'
+RESET='\033[0m'
+
+info()    { echo -e "${CYAN}${BOLD}▸${RESET} $*"; }
+success() { echo -e "${GREEN}${BOLD}✓${RESET} $*"; }
+warn()    { echo -e "${YELLOW}${BOLD}⚠${RESET} $*"; }
+error()   { echo -e "${RED}${BOLD}✗${RESET} $*" >&2; }
+
+# ─── Parse flags ───────────────────────────────────────────────────────────
+APPLY=false
+REPO_OVERRIDE=""
+
+for arg in "$@"; do
+    case "$arg" in
+        --apply) APPLY=true ;;
+        --repo-path)  shift_next=true ;;
+        --repo-path=*) REPO_OVERRIDE="${arg#--repo-path=}" ;;
+        *)
+            if [[ "${shift_next:-}" == "true" ]]; then
+                REPO_OVERRIDE="$arg"
+                shift_next=false
+            fi
+            ;;
+    esac
+done
+
+# ─── Locate repo ──────────────────────────────────────────────────────────
+find_repo() {
+    # 1. Explicit override
+    if [[ -n "$REPO_OVERRIDE" ]]; then
+        echo "$REPO_OVERRIDE"
+        return
+    fi
+
+    # 2. Environment variable
+    if [[ -n "${CCT_REPO_PATH:-}" ]]; then
+        echo "$CCT_REPO_PATH"
+        return
+    fi
+
+    # 3. Walk up from script dir
+    local dir="$SCRIPT_DIR"
+    while [[ "$dir" != "/" ]]; do
+        if [[ -f "$dir/install.sh" && -d "$dir/scripts" && -f "$dir/scripts/cct" ]]; then
+            echo "$dir"
+            return
+        fi
+        dir="$(dirname "$dir")"
+    done
+
+    # 4. Check manifest for stored repo_path
+    if [[ -f "$MANIFEST" ]]; then
+        local stored
+        stored="$(jq -r '.repo_path // ""' "$MANIFEST" 2>/dev/null || true)"
+        if [[ -n "$stored" && -d "$stored" ]]; then
+            echo "$stored"
+            return
+        fi
+    fi
+
+    return 1
+}
+
+REPO_PATH="$(find_repo)" || {
+    error "Cannot locate the Shipwright repo."
+    echo ""
+    echo -e "  Try one of:"
+    echo -e "    ${DIM}export CCT_REPO_PATH=/path/to/shipwright${RESET}"
+    echo -e "    ${DIM}shipwright upgrade --repo-path /path/to/shipwright${RESET}"
+    exit 1
+}
+
+# ─── File registry ─────────────────────────────────────────────────────────
+# Each entry: "key|src_relative|dest_absolute|protected|executable"
+BIN_DIR="$HOME/.local/bin"
+
+FILES=(
+    "tmux.conf|tmux/tmux.conf|$HOME/.tmux.conf|false|false"
+    "claude-teams-overlay.conf|tmux/claude-teams-overlay.conf|$HOME/.tmux/claude-teams-overlay.conf|false|false"
+    "settings.json.template|claude-code/settings.json.template|$HOME/.claude/settings.json.template|false|false"
+    "settings.json||$HOME/.claude/settings.json|true|false"
+    "cct|scripts/cct|$BIN_DIR/cct|false|true"
+    "cct-session.sh|scripts/cct-session.sh|$BIN_DIR/cct-session.sh|false|true"
+    "cct-status.sh|scripts/cct-status.sh|$BIN_DIR/cct-status.sh|false|true"
+    "cct-cleanup.sh|scripts/cct-cleanup.sh|$BIN_DIR/cct-cleanup.sh|false|true"
+    "cct-upgrade.sh|scripts/cct-upgrade.sh|$BIN_DIR/cct-upgrade.sh|false|true"
+    "cct-doctor.sh|scripts/cct-doctor.sh|$BIN_DIR/cct-doctor.sh|false|true"
+    "cct-logs.sh|scripts/cct-logs.sh|$BIN_DIR/cct-logs.sh|false|true"
+    "cct-ps.sh|scripts/cct-ps.sh|$BIN_DIR/cct-ps.sh|false|true"
+    "cct-templates.sh|scripts/cct-templates.sh|$BIN_DIR/cct-templates.sh|false|true"
+    "cct-loop.sh|scripts/cct-loop.sh|$BIN_DIR/cct-loop.sh|false|true"
+    "cct-pipeline.sh|scripts/cct-pipeline.sh|$BIN_DIR/cct-pipeline.sh|false|true"
+    "cct-pipeline-test.sh|scripts/cct-pipeline-test.sh|$BIN_DIR/cct-pipeline-test.sh|false|true"
+    "cct-worktree.sh|scripts/cct-worktree.sh|$BIN_DIR/cct-worktree.sh|false|true"
+    "cct-init.sh|scripts/cct-init.sh|$BIN_DIR/cct-init.sh|false|true"
+    "cct-prep.sh|scripts/cct-prep.sh|$BIN_DIR/cct-prep.sh|false|true"
+    "cct-daemon.sh|scripts/cct-daemon.sh|$BIN_DIR/cct-daemon.sh|false|true"
+    "cct-daemon-test.sh|scripts/cct-daemon-test.sh|$BIN_DIR/cct-daemon-test.sh|false|true"
+    "cct-prep-test.sh|scripts/cct-prep-test.sh|$BIN_DIR/cct-prep-test.sh|false|true"
+    "cct-memory.sh|scripts/cct-memory.sh|$BIN_DIR/cct-memory.sh|false|true"
+    "cct-memory-test.sh|scripts/cct-memory-test.sh|$BIN_DIR/cct-memory-test.sh|false|true"
+    "cct-cost.sh|scripts/cct-cost.sh|$BIN_DIR/cct-cost.sh|false|true"
+    "cct-fleet.sh|scripts/cct-fleet.sh|$BIN_DIR/cct-fleet.sh|false|true"
+    "cct-fleet-test.sh|scripts/cct-fleet-test.sh|$BIN_DIR/cct-fleet-test.sh|false|true"
+    "cct-fix.sh|scripts/cct-fix.sh|$BIN_DIR/cct-fix.sh|false|true"
+    "cct-fix-test.sh|scripts/cct-fix-test.sh|$BIN_DIR/cct-fix-test.sh|false|true"
+    "cct-reaper.sh|scripts/cct-reaper.sh|$BIN_DIR/cct-reaper.sh|false|true"
+    "CLAUDE.md.shipwright|claude-code/CLAUDE.md.shipwright|$HOME/.claude/CLAUDE.md|true|false"
+    "teammate-idle.sh|claude-code/hooks/teammate-idle.sh|$HOME/.claude/hooks/teammate-idle.sh|false|true"
+    "task-completed.sh|claude-code/hooks/task-completed.sh|$HOME/.claude/hooks/task-completed.sh|false|true"
+    "notify-idle.sh|claude-code/hooks/notify-idle.sh|$HOME/.claude/hooks/notify-idle.sh|false|true"
+    "pre-compact-save.sh|claude-code/hooks/pre-compact-save.sh|$HOME/.claude/hooks/pre-compact-save.sh|false|true"
+    "feature-dev.json|tmux/templates/feature-dev.json|$HOME/.claude-teams/templates/feature-dev.json|false|false"
+    "code-review.json|tmux/templates/code-review.json|$HOME/.claude-teams/templates/code-review.json|false|false"
+    "refactor.json|tmux/templates/refactor.json|$HOME/.claude-teams/templates/refactor.json|false|false"
+    "exploration.json|tmux/templates/exploration.json|$HOME/.claude-teams/templates/exploration.json|false|false"
+    "definition-of-done.example.md|docs/definition-of-done.example.md|$HOME/.claude-teams/templates/definition-of-done.example.md|false|false"
+    "pipeline-standard.json|templates/pipelines/standard.json|$HOME/.claude-teams/pipelines/standard.json|false|false"
+    "pipeline-fast.json|templates/pipelines/fast.json|$HOME/.claude-teams/pipelines/fast.json|false|false"
+    "pipeline-full.json|templates/pipelines/full.json|$HOME/.claude-teams/pipelines/full.json|false|false"
+    "pipeline-hotfix.json|templates/pipelines/hotfix.json|$HOME/.claude-teams/pipelines/hotfix.json|false|false"
+    "pipeline-autonomous.json|templates/pipelines/autonomous.json|$HOME/.claude-teams/pipelines/autonomous.json|false|false"
+    "pipeline-cost-aware.json|templates/pipelines/cost-aware.json|$HOME/.claude-teams/pipelines/cost-aware.json|false|false"
+    "pipeline-enterprise.json|templates/pipelines/enterprise.json|$HOME/.claude-teams/pipelines/enterprise.json|false|false"
+)
+
+# ─── Checksum helper ──────────────────────────────────────────────────────
+file_checksum() {
+    local file="$1"
+    if [[ -f "$file" ]]; then
+        md5 -q "$file" 2>/dev/null || md5sum "$file" 2>/dev/null | awk '{print $1}'
+    else
+        echo ""
+    fi
+}
+
+# ─── Manifest helpers ─────────────────────────────────────────────────────
+read_manifest_checksum() {
+    local key="$1"
+    if [[ ! -f "$MANIFEST" ]]; then
+        echo ""
+        return
+    fi
+    jq -r ".files[\"$key\"].checksum // \"\"" "$MANIFEST" 2>/dev/null || echo ""
+}
+
+write_manifest() {
+    mkdir -p "$MANIFEST_DIR"
+    local json='{\n  "schema": 1,\n  "version": "1.1.0",\n  "installed_at": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'",\n  "repo_path": "'"$REPO_PATH"'",\n  "files": {'
+    local first=true
+
+    for entry in "${FILES[@]}"; do
+        IFS='|' read -r key src dest protected executable <<< "$entry"
+        # Only include files that exist at dest
+        if [[ ! -f "$dest" ]]; then
+            continue
+        fi
+        local cksum
+        cksum="$(file_checksum "$dest")"
+
+        if ! $first; then json+=','; fi
+        first=false
+
+        json+='\n    "'"$key"'": {'
+        if [[ -n "$src" ]]; then
+            json+='\n      "src": "'"$src"'",'
+        fi
+        json+='\n      "dest": "'"$dest"'",'
+        json+='\n      "checksum": "'"$cksum"'",'
+        json+='\n      "protected": '"$protected"','
+        json+='\n      "executable": '"$executable"
+        json+='\n    }'
+    done
+
+    json+='\n  }\n}'
+    echo -e "$json" > "$MANIFEST"
+}
+
+# ─── Bootstrap manifest if missing ────────────────────────────────────────
+bootstrap_manifest() {
+    echo ""
+    warn "No upgrade manifest found at $MANIFEST"
+    info "Bootstrapping from currently installed files..."
+    echo ""
+
+    local found=0
+    for entry in "${FILES[@]}"; do
+        IFS='|' read -r key _ dest _ _ <<< "$entry"
+        if [[ -f "$dest" ]]; then
+            echo -e "  ${GREEN}✓${RESET} ${DIM}$key${RESET}  →  $dest"
+            ((found++))
+        fi
+    done
+
+    echo ""
+    if [[ $found -eq 0 ]]; then
+        error "No installed files found. Run install.sh first."
+        exit 1
+    fi
+
+    info "Found $found installed files. Writing manifest..."
+    write_manifest
+    success "Manifest created at $MANIFEST"
+    echo ""
+}
+
+# ─── Main logic ────────────────────────────────────────────────────────────
+echo ""
+echo -e "${CYAN}${BOLD}shipwright${RESET} ${DIM}v1.3.0${RESET} — ${BOLD}$(if $APPLY; then echo "Applying Upgrade"; else echo "Upgrade Check"; fi)${RESET}"
+echo -e "${CYAN}═══════════════════════════════════════════════${RESET}"
+echo ""
+echo -e "Comparing installed files against repo at:"
+echo -e "  ${DIM}$REPO_PATH${RESET}"
+
+# Bootstrap if needed
+if [[ ! -f "$MANIFEST" ]]; then
+    bootstrap_manifest
+fi
+
+# ─── Diff detection ───────────────────────────────────────────────────────
+declare -a UPGRADEABLE=()
+declare -a UP_TO_DATE=()
+declare -a CONFLICTS=()
+declare -a MISSING=()
+declare -a PROTECTED=()
+
+for entry in "${FILES[@]}"; do
+    IFS='|' read -r key src dest protected executable <<< "$entry"
+
+    # Protected files — never auto-upgrade
+    if [[ "$protected" == "true" ]]; then
+        PROTECTED+=("$key|$dest")
+        continue
+    fi
+
+    # No source in repo means it's user-only (shouldn't happen for non-protected, but guard)
+    if [[ -z "$src" ]]; then
+        continue
+    fi
+
+    local_src="$REPO_PATH/$src"
+
+    # Source file missing from repo (shouldn't happen unless repo is incomplete)
+    if [[ ! -f "$local_src" ]]; then
+        continue
+    fi
+
+    repo_hash="$(file_checksum "$local_src")"
+    manifest_hash="$(read_manifest_checksum "$key")"
+    installed_hash="$(file_checksum "$dest")"
+
+    if [[ -z "$installed_hash" ]]; then
+        # File missing on disk
+        MISSING+=("$key|$src|$dest|$executable")
+    elif [[ "$repo_hash" == "$manifest_hash" ]]; then
+        # Repo hasn't changed since last install/upgrade
+        UP_TO_DATE+=("$key")
+    elif [[ "$installed_hash" == "$manifest_hash" ]]; then
+        # Repo changed, user hasn't touched it → safe to upgrade
+        UPGRADEABLE+=("$key|$src|$dest|$executable")
+    else
+        # Both repo and user changed → conflict
+        CONFLICTS+=("$key|$src|$dest")
+    fi
+done
+
+# ─── Display results ──────────────────────────────────────────────────────
+echo ""
+
+if [[ ${#UPGRADEABLE[@]} -gt 0 ]]; then
+    echo -e "${GREEN}${BOLD}UPGRADEABLE${RESET} ${DIM}(repo has newer version):${RESET}"
+    for item in "${UPGRADEABLE[@]}"; do
+        IFS='|' read -r key src dest _ <<< "$item"
+        printf "  ${GREEN}✓${RESET} %-28s ${DIM}%s → %s${RESET}\n" "$key" "$src" "$dest"
+    done
+    echo ""
+fi
+
+if [[ ${#MISSING[@]} -gt 0 ]]; then
+    echo -e "${YELLOW}${BOLD}MISSING${RESET} ${DIM}(not found on disk — will reinstall):${RESET}"
+    for item in "${MISSING[@]}"; do
+        IFS='|' read -r key src dest _ <<< "$item"
+        printf "  ${YELLOW}?${RESET} %-28s ${DIM}%s → %s${RESET}\n" "$key" "$src" "$dest"
+    done
+    echo ""
+fi
+
+if [[ ${#CONFLICTS[@]} -gt 0 ]]; then
+    echo -e "${RED}${BOLD}CONFLICTS${RESET} ${DIM}(both repo and local file changed — skipped):${RESET}"
+    for item in "${CONFLICTS[@]}"; do
+        IFS='|' read -r key src dest <<< "$item"
+        printf "  ${RED}!${RESET} %-28s ${DIM}review manually: diff %s %s${RESET}\n" "$key" "$REPO_PATH/$src" "$dest"
+    done
+    echo ""
+fi
+
+if [[ ${#UP_TO_DATE[@]} -gt 0 ]]; then
+    echo -e "${DIM}UP TO DATE:${RESET}"
+    for key in "${UP_TO_DATE[@]}"; do
+        echo -e "  ${DIM}○ $key${RESET}"
+    done
+    echo ""
+fi
+
+if [[ ${#PROTECTED[@]} -gt 0 ]]; then
+    echo -e "${PURPLE}${BOLD}PROTECTED${RESET} ${DIM}(never auto-upgraded):${RESET}"
+    for item in "${PROTECTED[@]}"; do
+        IFS='|' read -r key dest <<< "$item"
+        echo -e "  ${PURPLE}✗${RESET} ${key}  ${DIM}— user config, review template for new options${RESET}"
+    done
+    echo ""
+fi
+
+# ─── Summary ──────────────────────────────────────────────────────────────
+total_actionable=$(( ${#UPGRADEABLE[@]} + ${#MISSING[@]} ))
+echo -e "${BOLD}SUMMARY:${RESET} ${GREEN}$total_actionable upgradeable${RESET}, ${#UP_TO_DATE[@]} up to date, ${#CONFLICTS[@]} conflicts, ${#PROTECTED[@]} protected"
+echo ""
+
+if [[ $total_actionable -eq 0 && ${#CONFLICTS[@]} -eq 0 ]]; then
+    success "Everything is up to date!"
+    exit 0
+fi
+
+# ─── Apply ────────────────────────────────────────────────────────────────
+if ! $APPLY; then
+    if [[ $total_actionable -gt 0 ]]; then
+        echo -e "Run with ${BOLD}--apply${RESET} to upgrade:"
+        echo -e "  ${DIM}shipwright upgrade --apply${RESET}"
+        echo ""
+    fi
+    if [[ ${#CONFLICTS[@]} -gt 0 ]]; then
+        warn "Conflicting files must be resolved manually."
+    fi
+    exit 0
+fi
+
+# Apply upgrades
+CCT_SELF_UPGRADED=false
+
+echo -e "${BOLD}Applying...${RESET}"
+echo ""
+
+apply_file() {
+    local key="$1" src="$2" dest="$3" executable="$4"
+    local src_full="$REPO_PATH/$src"
+
+    # Create parent directory if needed
+    local dest_dir
+    dest_dir="$(dirname "$dest")"
+    mkdir -p "$dest_dir"
+
+    # Backup existing file
+    if [[ -f "$dest" ]]; then
+        cp "$dest" "${dest}.pre-upgrade.bak"
+        echo -e "  ${DIM}Backed up: $dest → ${dest}.pre-upgrade.bak${RESET}"
+    fi
+
+    # Copy new version
+    cp "$src_full" "$dest"
+    if [[ "$executable" == "true" ]]; then
+        chmod +x "$dest"
+    fi
+
+    echo -e "  ${GREEN}✓${RESET} Updated: ${BOLD}$key${RESET}"
+}
+
+# Process upgradeable files
+if [[ ${#UPGRADEABLE[@]} -gt 0 ]]; then
+    for item in "${UPGRADEABLE[@]}"; do
+        IFS='|' read -r key src dest executable <<< "$item"
+        apply_file "$key" "$src" "$dest" "$executable"
+        if [[ "$key" == cct* ]]; then
+            CCT_SELF_UPGRADED=true
+        fi
+    done
+fi
+
+# Process missing files (reinstall)
+if [[ ${#MISSING[@]} -gt 0 ]]; then
+    for item in "${MISSING[@]}"; do
+        IFS='|' read -r key src dest executable <<< "$item"
+        apply_file "$key" "$src" "$dest" "$executable"
+    done
+fi
+
+echo ""
+
+# Rebuild manifest with current checksums for all installed files
+write_manifest
+success "Manifest updated: $MANIFEST"
+
+# Self-upgrade warning
+if $CCT_SELF_UPGRADED; then
+    echo ""
+    echo -e "${YELLOW}${BOLD}⚠${RESET}  The Shipwright CLI itself was upgraded."
+    echo -e "   Your current command completed, but re-run to use the new version."
+fi
+echo ""
+
+# Tip for tmux users
+if [[ ${#UPGRADEABLE[@]} -gt 0 ]] && printf '%s\n' "${UPGRADEABLE[@]}" | grep -q "tmux\|overlay"; then
+    info "Tip: Reload tmux config with: ${DIM}prefix + r${RESET}"
+    echo ""
+fi