operator.sh

#!/bin/bash
# ============================================================================
# operator.sh - Knowledge Graph Platform Manager (Thin Shim)
# ============================================================================
OPERATOR_VERSION="0.19.0"
# ============================================================================
#
# Minimal host-side script that delegates to operator container.
# Only host-critical operations run directly; everything else via docker exec.
#
# GitHub repository for self-update
KG_REPO="aaronsb/knowledge-graph-system"
KG_REPO_RAW="https://raw.githubusercontent.com/${KG_REPO}/main"
KG_GHCR="ghcr.io/${KG_REPO}"
#
# ============================================================================

set -e

# Colors (disabled if not a terminal)
if [ -t 1 ]; then
    RED=$'\033[0;31m'
    GREEN=$'\033[0;32m'
    YELLOW=$'\033[1;33m'
    BLUE=$'\033[0;34m'
    BOLD=$'\033[1m'
    NC=$'\033[0m'
else
    RED=''
    GREEN=''
    YELLOW=''
    BLUE=''
    BOLD=''
    NC=''
fi

# Script location
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

# Detect standalone vs repo install
if [ -d "$SCRIPT_DIR/docker" ]; then
    DOCKER_DIR="$SCRIPT_DIR/docker"
else
    DOCKER_DIR="$SCRIPT_DIR"
fi

CONFIG_FILE="$SCRIPT_DIR/.operator.conf"
ENV_FILE="$SCRIPT_DIR/.env"
OPERATOR_CONTAINER="kg-operator"

# ============================================================================
# Configuration
# ============================================================================

load_config() {
    if [ -f "$CONFIG_FILE" ]; then
        source "$CONFIG_FILE"
    fi
    DEV_MODE="${DEV_MODE:-false}"
    GPU_MODE="${GPU_MODE:-cpu}"
    # ADR-105 in-VM router; default off so non-traefik deployments are unchanged.
    ROUTER_MODE="${ROUTER_MODE:-none}"
    export ROUTER_MODE
    # ADR-105 TLS termination mode (none|selfsigned); only meaningful with traefik.
    TLS_MODE="${TLS_MODE:-none}"
    export TLS_MODE
    # Dev mode uses local builds by default, standalone uses GHCR
    if [ "$DEV_MODE" = "true" ]; then
        IMAGE_SOURCE="${IMAGE_SOURCE:-local}"
    else
        IMAGE_SOURCE="${IMAGE_SOURCE:-ghcr}"
    fi

    # ADR-101: derive kg-api image tag via the shared helper. The mapping
    # used to live inline here AND in operator/lib/common.sh's
    # load_operator_config AND in operator/lib/guided-init.sh — the
    # triplication drifted (commit c448f098 fixed one of the gaps after
    # the bug had silently shipped). Now there is one definition.
    if [ -z "$KG_API_IMAGE_TAG" ]; then
        if [ -f "$SCRIPT_DIR/operator/lib/image-tag.sh" ]; then
            # shellcheck source=operator/lib/image-tag.sh
            source "$SCRIPT_DIR/operator/lib/image-tag.sh"
            KG_API_IMAGE_TAG=$(derive_kg_api_image_tag "$GPU_MODE" "$ROCM_VERSION")
        else
            # Standalone installs that predate shipping image-tag.sh: don't hard
            # crash. Default to the GHCR convention (kg-api:latest = CUDA/CPU).
            # AMD-host users: set KG_API_IMAGE_TAG=rocm72-host in .operator.conf.
            echo -e "${YELLOW}⚠ operator/lib/image-tag.sh missing; defaulting KG_API_IMAGE_TAG=latest${NC}" >&2
            KG_API_IMAGE_TAG="latest"
        fi
    fi
    export KG_API_IMAGE_TAG
}

# Build compose command with overlays
get_compose_cmd() {
    load_config
    local cmd="docker compose -f $DOCKER_DIR/docker-compose.yml"

    # GHCR images overlay (must come before standalone)
    [ "$IMAGE_SOURCE" = "ghcr" ] && [ -f "$DOCKER_DIR/docker-compose.ghcr.yml" ] && cmd="$cmd -f $DOCKER_DIR/docker-compose.ghcr.yml"

    # Standalone mode (curl installer) - removes dev mounts, fixes container names
    [ -f "$DOCKER_DIR/docker-compose.standalone.yml" ] && cmd="$cmd -f $DOCKER_DIR/docker-compose.standalone.yml"

    # SSL overlay (if configured)
    [ -f "$DOCKER_DIR/docker-compose.ssl.yml" ] && cmd="$cmd -f $DOCKER_DIR/docker-compose.ssl.yml"

    # Traefik router overlay (ADR-105) + TLS overlays selected by TLS_MODE.
    if [ "$ROUTER_MODE" = "traefik" ] && [ -f "$DOCKER_DIR/docker-compose.traefik.yml" ]; then
        cmd="$cmd -f $DOCKER_DIR/docker-compose.traefik.yml"
        case "$TLS_MODE" in
            selfsigned|manual|letsencrypt)
                [ -f "$DOCKER_DIR/docker-compose.traefik-tls.yml" ] && cmd="$cmd -f $DOCKER_DIR/docker-compose.traefik-tls.yml"
                [ "$TLS_MODE" = "manual" ]      && [ -f "$DOCKER_DIR/docker-compose.traefik-tls-manual.yml" ]      && cmd="$cmd -f $DOCKER_DIR/docker-compose.traefik-tls-manual.yml"
                # letsencrypt: dns-01 uses the lego DNS overlay; otherwise TLS-ALPN-01.
                if [ "$TLS_MODE" = "letsencrypt" ]; then
                    if [ "${ACME_CHALLENGE:-tls-alpn-01}" = "dns-01" ] && [ -f "$DOCKER_DIR/docker-compose.traefik-tls-letsencrypt-dns.yml" ]; then
                        cmd="$cmd -f $DOCKER_DIR/docker-compose.traefik-tls-letsencrypt-dns.yml"
                    elif [ -f "$DOCKER_DIR/docker-compose.traefik-tls-letsencrypt.yml" ]; then
                        cmd="$cmd -f $DOCKER_DIR/docker-compose.traefik-tls-letsencrypt.yml"
                    fi
                fi
                ;;
        esac
    fi

    # Cockpit host console behind Traefik at /cockpit (ADR-105) when enabled.
    [ "${COCKPIT_PROXY:-false}" = "true" ] && [ "$ROUTER_MODE" = "traefik" ] \
        && [ -f "$DOCKER_DIR/docker-compose.traefik-cockpit.yml" ] \
        && cmd="$cmd -f $DOCKER_DIR/docker-compose.traefik-cockpit.yml"

    # Dev mode overlay (adds hot reload, source mounts)
    [ "$DEV_MODE" = "true" ] && [ -f "$DOCKER_DIR/docker-compose.dev.yml" ] && cmd="$cmd -f $DOCKER_DIR/docker-compose.dev.yml"

    # GPU overlays
    case "$GPU_MODE" in
        nvidia)        [ -f "$DOCKER_DIR/docker-compose.gpu-nvidia.yml" ]   && cmd="$cmd -f $DOCKER_DIR/docker-compose.gpu-nvidia.yml" ;;
        amd|amd-host)  [ -f "$DOCKER_DIR/docker-compose.gpu-amd-host.yml" ] && cmd="$cmd -f $DOCKER_DIR/docker-compose.gpu-amd-host.yml" ;;
        mac)           [ -f "$DOCKER_DIR/docker-compose.override.mac.yml" ] && cmd="$cmd -f $DOCKER_DIR/docker-compose.override.mac.yml" ;;
    esac

    echo "$cmd --env-file $ENV_FILE"
}

run_compose() {
    $(get_compose_cmd) "$@"
}

# ============================================================================
# Checks
# ============================================================================

check_env() {
    if [ ! -f "$ENV_FILE" ]; then
        echo -e "${RED}✗ .env not found. Run ./operator.sh init${NC}"
        exit 1
    fi
}

check_operator() {
    if ! docker ps --format '{{.Names}}' | grep -q "^${OPERATOR_CONTAINER}$"; then
        echo -e "${YELLOW}Operator not running. Starting infrastructure...${NC}"
        cmd_start_infra
    fi
}

wait_for_container() {
    local container=$1
    local max_wait=${2:-30}
    for i in $(seq 1 $max_wait); do
        docker ps --format '{{.Names}} {{.Status}}' | grep -qE "^${container}.*healthy" && return 0
        docker ps --format '{{.Names}}' | grep -q "^${container}$" && [ $i -gt 5 ] && return 0
        sleep 2
    done
    return 1
}

# ============================================================================
# HOST-ONLY: Bootstrap infrastructure (can't run in container - chicken/egg)
# ============================================================================

cmd_start_infra() {
    check_env
    load_config
    cd "$DOCKER_DIR"

    # Start postgres and garage
    echo -e "${BLUE}→ Starting infrastructure (postgres, garage)...${NC}"
    run_compose up -d postgres garage

    # Only start operator if not already running (don't recreate - it's the brain!)
    if docker ps --format '{{.Names}}' | grep -q "^${OPERATOR_CONTAINER}$"; then
        echo -e "${GREEN}✓ Operator already running${NC}"
    else
        echo -e "${BLUE}→ Starting operator...${NC}"
        run_compose up -d operator

        echo -e "${BLUE}→ Waiting for operator...${NC}"
        if wait_for_container "$OPERATOR_CONTAINER" 30; then
            echo -e "${GREEN}✓ Operator ready${NC}"
        else
            echo -e "${RED}✗ Operator failed to start${NC}"
            exit 1
        fi
    fi
}

# ============================================================================
# DELEGATED TO CONTAINER: Complex operations
# ============================================================================

# reconcile_age_catalog — bring the AGE extension catalog up to the library the
# running postgres image ships, via operator/lib/age-catalog.sh inside the
# operator container (the same place migrate-db.sh runs from). `up -d postgres`
# recreates the container on a pulled image without touching the catalog in
# the volume; until ALTER EXTENSION age UPDATE runs, graph writes succeed and
# every graph read fails. A failed update is fatal. A missing script means the
# operator image predates it: warn and continue.  @verified 060280191
reconcile_age_catalog() {
    if ! docker exec "$OPERATOR_CONTAINER" test -x /workspace/operator/lib/age-catalog.sh 2>/dev/null; then
        echo -e "${YELLOW}  ⚠ operator image lacks operator/lib/age-catalog.sh; AGE catalog not checked${NC}"
        echo -e "${YELLOW}    (run ./operator.sh self-update, then ./operator.sh start)${NC}"
        return 0
    fi
    docker exec "$OPERATOR_CONTAINER" /workspace/operator/lib/age-catalog.sh || exit 1
}

# up_app_services — bring up api and web. In dev mode the web container keeps
# node_modules in an anonymous volume (docker-compose.dev.yml), which compose
# reuses across recreates; without --renew-anon-volumes a package.json change
# never reaches the running Vite server. Only web is built: `up --build web`
# would also build its depends_on chain (api, postgres), and the api image
# re-bakes the embedding models after any api/ edit. api comes up on its own
# first: --renew-anon-volumes recreates every service it touches, and a
# needless api recreate reloads the embedding models.
# @verified (new)
up_app_services() {
    if [ "$DEV_MODE" = "true" ]; then
        run_compose build web
        run_compose up -d api
        run_compose up -d --no-deps --renew-anon-volumes web
    else
        run_compose up -d api web
    fi
}

cmd_start() {
    check_env
    load_config

    # Bootstrap: start infra from host
    cmd_start_infra

    # Catalog before schema (see reconcile_age_catalog).
    reconcile_age_catalog

    # Run migrations via container
    echo -e "${BLUE}→ Running migrations...${NC}"
    docker exec "$OPERATOR_CONTAINER" /workspace/operator/database/migrate-db.sh -y 2>/dev/null || true

    # Start api/web - must run on HOST for dev mode volume mounts to resolve correctly
    # (running compose inside container causes paths like ../api to resolve to /workspace/api)
    echo -e "${BLUE}→ Starting application (api, web)...${NC}"
    cd "$DOCKER_DIR"
    up_app_services

    # Bring up the in-VM router when enabled (ADR-105). cmd_start ups services by
    # name, so the traefik overlay being in the compose command isn't enough — it
    # must be named explicitly.
    if [ "$ROUTER_MODE" = "traefik" ]; then
        echo -e "${BLUE}→ Starting router (traefik)...${NC}"
        run_compose up -d traefik
    fi

    # Wait for API health
    echo -e "${BLUE}→ Waiting for API...${NC}"
    for i in {1..30}; do
        if curl -sf http://localhost:8000/health >/dev/null 2>&1; then
            echo -e "${GREEN}✓ API healthy${NC}"
            echo -e "${GREEN}✓ Platform started${NC}"
            return 0
        fi
        sleep 2
    done
    echo -e "${YELLOW}⚠ API may still be starting${NC}"
}

cmd_stop() {
    check_env
    load_config
    cd "$DOCKER_DIR"

    local services=()
    local keep_infra=false

    while [[ $# -gt 0 ]]; do
        case $1 in
            --keep-infra) keep_infra=true; shift ;;
            *)
                if is_known_service "$1" || [ "$1" = "all" ]; then
                    services+=("$1")
                else
                    echo -e "${RED}Unknown service: $1${NC}"
                    echo "Known services: $KNOWN_SERVICES"
                    exit 1
                fi
                shift
                ;;
        esac
    done

    echo -e "${BLUE}→ Stopping containers...${NC}"
    if [ "$keep_infra" = true ]; then
        run_compose stop api web
    elif [ ${#services[@]} -gt 0 ] && [ "${services[0]}" != "all" ]; then
        run_compose stop "${services[@]}"
    else
        run_compose stop
    fi
    echo -e "${GREEN}✓ Stopped${NC}"
}

# PostgreSQL major-version compatibility gate.
# A major-version bump (e.g. 17 -> 18) cannot be applied by swapping the
# container image — the new server refuses to start on an older cluster's data
# directory. Apache AGE compounds this: graph identity is tied to schema OIDs
# and does not survive a logical dump/restore across clusters (ADR-205). This
# is a hard refuse — a major-version change aborts the upgrade before any
# container is recreated. Major-version migration is a deliberate, separate
# procedure with no automated path yet.
check_pg_major_compatibility() {
    echo -e "${BLUE}→ Checking PostgreSQL major version...${NC}"

    local pg_container pg_image="" target_major="" data_major=""
    pg_container=$(resolve_container postgres)

    # Major version the new postgres image expects (PG_MAJOR env)
    pg_image=$(run_compose config --format json 2>/dev/null | python3 -c \
        'import sys,json; print(json.load(sys.stdin)["services"]["postgres"].get("image",""))' \
        2>/dev/null)
    [ -n "$pg_image" ] && target_major=$(docker inspect "$pg_image" \
        --format '{{range .Config.Env}}{{println .}}{{end}}' 2>/dev/null \
        | sed -n 's/^PG_MAJOR=//p' | tr -dc '0-9')

    # Major version of the existing cluster's data directory (PG_VERSION).
    # Read from the live container when running, otherwise straight from the
    # data volume — a cold upgrade (platform stopped) is exactly when this
    # gate matters most, so it must not silently skip there.
    if docker ps --format '{{.Names}}' | grep -q "^${pg_container}$"; then
        data_major=$(docker exec "$pg_container" \
            sh -c 'cat "$PGDATA/PG_VERSION" 2>/dev/null' 2>/dev/null | tr -dc '0-9')
    else
        local pg_data_src
        pg_data_src=$(docker inspect "$pg_container" --format \
            '{{range .Mounts}}{{if eq .Destination "/var/lib/postgresql"}}{{.Source}}{{end}}{{if eq .Destination "/var/lib/postgresql/data"}}{{.Source}}{{end}}{{end}}' \
            2>/dev/null)
        if [ -n "$pg_data_src" ] && [ -n "$pg_image" ]; then
            # PG_VERSION is at the volume root (pre-18) or <major>/docker/ (18+)
            data_major=$(docker run --rm -v "${pg_data_src}:/v:ro" --entrypoint sh \
                "$pg_image" -c \
                'cat /v/PG_VERSION 2>/dev/null || cat /v/*/docker/PG_VERSION 2>/dev/null' \
                2>/dev/null | tr -dc '0-9')
        fi
    fi

    if [ -z "$data_major" ] || [ -z "$target_major" ]; then
        echo -e "${YELLOW}  ⚠ Could not determine PG major (data: ${data_major:-?}, image: ${target_major:-?})${NC}"
        echo -e "${YELLOW}    Verify the image and data directory agree before continuing.${NC}"
        echo ""
        return 0
    fi

    if [ "$data_major" = "$target_major" ]; then
        echo -e "${GREEN}  ✓ PostgreSQL $data_major — no major-version change${NC}"
        echo ""
        return 0
    fi

    echo ""
    echo -e "${RED}${BOLD}PostgreSQL major-version change detected — upgrade halted${NC}"
    echo ""
    echo -e "  Data directory: ${BOLD}PostgreSQL $data_major${NC}"
    echo -e "  New image:      ${BOLD}PostgreSQL $target_major${NC}"
    echo ""
    echo -e "  A major-version bump cannot be applied by swapping the image —"
    echo -e "  PostgreSQL $target_major will not start on a PostgreSQL $data_major data directory,"
    echo -e "  and Apache AGE graphs do not survive a logical dump/restore across"
    echo -e "  clusters (graph identity is OID-coupled)."
    echo ""
    echo -e "  Major-version migration is a deliberate, separate procedure."
    echo -e "  Back up first, then see"
    echo -e "  ${BLUE}docs/architecture/database-schema/ADR-205-postgresql-18-migration.md${NC}"
    echo ""
    echo -e "${RED}Upgrade aborted — no containers recreated, database untouched.${NC}"
    exit 1
}

cmd_upgrade() {
    check_env
    load_config
    cd "$DOCKER_DIR"

    local dry_run=false
    local no_backup=false
    local auto_yes=false

    while [[ $# -gt 0 ]]; do
        case $1 in
            --dry-run|--whatif) dry_run=true; shift ;;
            --no-backup) no_backup=true; shift ;;
            -y|--yes) auto_yes=true; shift ;;
            --help|-h)
                echo "Usage: ./operator.sh upgrade [OPTIONS]"
                echo ""
                echo "Options:"
                echo "  --dry-run     Show what would be done (also: --whatif)"
                echo "  -y, --yes     Skip confirmation prompt"
                echo "  --no-backup   Skip pre-upgrade backup"
                exit 0
                ;;
            *) shift ;;
        esac
    done

    echo -e "${BLUE}${BOLD}Platform Upgrade${NC}"
    echo ""

    # Pre-flight checks
    echo -e "${BLUE}→ Pre-flight checks...${NC}"
    [ -f "$ENV_FILE" ] && echo -e "${GREEN}  ✓ .env exists${NC}" || { echo -e "${RED}  ✗ .env missing${NC}"; exit 1; }
    [ -f "$CONFIG_FILE" ] && echo -e "${GREEN}  ✓ .operator.conf exists${NC}" || { echo -e "${RED}  ✗ .operator.conf missing${NC}"; exit 1; }
    docker ps >/dev/null 2>&1 && echo -e "${GREEN}  ✓ Docker available${NC}" || { echo -e "${RED}  ✗ Docker not running${NC}"; exit 1; }
    echo ""

    # Show config and versions
    echo -e "${BOLD}Configuration:${NC}"
    echo -e "  Image source: ${BLUE}$IMAGE_SOURCE${NC}"
    echo ""
    echo -e "${BOLD}Running versions:${NC}"
    show_versions_table false
    echo ""

    if [ "$dry_run" = true ]; then
        if [ "$IMAGE_SOURCE" = "local" ]; then
            echo -e "${YELLOW}[DRY RUN] Would build images, update infra, run migrations, restart application${NC}"
        else
            echo -e "${YELLOW}[DRY RUN] Would pull images, update infra, run migrations, restart application${NC}"
        fi
        echo -e "${YELLOW}[DRY RUN] A PostgreSQL major-version change would be refused (see ADR-205)${NC}"
        return
    fi

    # Confirmation
    if [ "$auto_yes" = false ]; then
        read -p "Proceed with upgrade? [y/N] " -r
        echo ""
        [[ ! "$REPLY" =~ ^[Yy]$ ]] && echo "Cancelled." && return
    fi

    # Build or pull images
    if [ "$IMAGE_SOURCE" = "local" ]; then
        echo -e "${BLUE}→ Building local images...${NC}"
        run_compose build
    else
        echo -e "${BLUE}→ Pulling images...${NC}"
        run_compose pull
    fi
    echo ""

    # Refuse a PostgreSQL major-version swap before touching any container
    check_pg_major_compatibility

    # Stop app containers
    echo -e "${BLUE}→ Stopping application containers...${NC}"
    run_compose stop api web 2>/dev/null || true
    echo ""

    # Update infra containers (recreates if image changed, no-op otherwise)
    echo -e "${BLUE}→ Updating infrastructure...${NC}"
    run_compose up -d postgres garage
    echo -e "${BLUE}→ Waiting for postgres...${NC}"
    local pg_container
    pg_container=$(resolve_container postgres)
    if wait_for_container "$pg_container" 30; then
        echo -e "${GREEN}  ✓ Postgres ready${NC}"
    else
        echo -e "${RED}  ✗ Postgres failed to start${NC}"
        exit 1
    fi
    echo ""

    # Catalog before schema: the postgres recreate above may be the first boot
    # on a pulled image (see reconcile_age_catalog).
    if docker ps --format '{{.Names}}' | grep -q "^${OPERATOR_CONTAINER}$"; then
        reconcile_age_catalog
    fi

    # Run migrations via operator container (uses psql)
    echo -e "${BLUE}→ Running migrations...${NC}"
    if docker ps --format '{{.Names}}' | grep -q "^${OPERATOR_CONTAINER}$"; then
        docker exec "$OPERATOR_CONTAINER" /workspace/operator/database/migrate-db.sh -y 2>/dev/null || echo -e "${YELLOW}  ⚠ Migration script not found or failed${NC}"
    else
        echo -e "${YELLOW}  ⚠ Operator container not running, skipping migrations${NC}"
    fi
    echo ""

    # Start application
    echo -e "${BLUE}→ Starting application...${NC}"
    up_app_services

    # Health check
    echo -e "${BLUE}→ Waiting for API health...${NC}"
    for i in {1..30}; do
        if curl -sf http://localhost:8000/health >/dev/null 2>&1; then
            echo -e "${GREEN}  ✓ API healthy${NC}"
            break
        fi
        [ $i -eq 30 ] && echo -e "${YELLOW}  ⚠ API may still be starting${NC}"
        sleep 2
    done
    echo ""

    echo -e "${BOLD}Current versions:${NC}"
    show_versions_table false
    echo ""

    echo -e "${GREEN}${BOLD}✅ Upgrade complete${NC}"
}

cmd_teardown() {
    # Delegate to operator/lib/teardown.sh when present (dev / git
    # checkout install). That script has the full implementation:
    # overlay-aware compose down (honors GPU_MODE etc.), --remove-
    # orphans, kg-owned vs. unrelated dangling-volume classification
    # (PR #427), plus --keep-env / --remove-images / --include-operator
    # flags that the inline fallback below doesn't support.
    #
    # Pre-fix history: this function inlined a simplified `run_compose
    # down -v` that left SHA-named anonymous volumes (e.g. the PG18
    # cluster at /var/lib/postgresql/18/docker) orphaned after teardown
    # --full. The lib script's dangling sweep was the actual fix; we
    # were just bypassing it from the user-facing entry point.
    #
    # Deliberately NOT calling check_env here — the lib script handles
    # missing .env explicitly (one of the things PR #427 added), and
    # check_env's hard-exit would defeat that path. The inline fallback
    # below also tolerates missing .env via run_compose's lazy load.
    local lib_teardown="$SCRIPT_DIR/operator/lib/teardown.sh"
    if [ -x "$lib_teardown" ]; then
        exec "$lib_teardown" "$@"
    fi

    # Inline fallback — used by curl-installer / standalone deployments
    # where install.sh doesn't ship operator/lib/. MUST match the
    # safety profile of the lib script (preserve volumes by default,
    # prompt before destructive action). DO NOT make this `down -v`
    # by default: a user typing `./operator.sh teardown` (no args)
    # expects a stop, not a data wipe.
    load_config
    cd "$DOCKER_DIR"

    local remove_volumes=false
    local auto_yes=false
    while [[ $# -gt 0 ]]; do
        case $1 in
            --full|--remove-volumes) remove_volumes=true; shift ;;
            -y|--yes) auto_yes=true; shift ;;
            -h|--help)
                echo "Usage: $0 teardown [--full|--remove-volumes] [-y|--yes]"
                echo ""
                echo "Note: standalone fallback path. For --keep-env, --remove-images,"
                echo "--include-operator, install the full git checkout."
                return 0
                ;;
            *) shift ;;
        esac
    done

    echo -e "${RED}${BOLD}TEARDOWN${NC}"
    if [ "$remove_volumes" = true ]; then
        echo -e "${RED}⚠️  All database data and uploaded files will be LOST!${NC}"
    else
        echo -e "${GREEN}✓ Volumes will be preserved${NC}"
    fi
    if [ "$auto_yes" = false ]; then
        read -p "Type 'yes' to confirm: " -r
        [[ "$REPLY" != "yes" ]] && echo "Cancelled" && exit 0
    fi

    local flags="--remove-orphans"
    [ "$remove_volumes" = true ] && flags="$flags -v"

    run_compose down $flags
    echo -e "${GREEN}✓ Teardown complete${NC}"
}

# ============================================================================
# SIMPLE HOST OPERATIONS
# ============================================================================

cmd_status() {
    echo -e "\n${BOLD}Container Status:${NC}"
    docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}' \
        --filter 'name=kg-' --filter 'name=knowledge-graph' 2>/dev/null || \
        echo "  No containers running"
}

# Known compose services
KNOWN_SERVICES="postgres garage api web operator"

is_known_service() {
    local service=$1
    case "$service" in
        postgres|garage|api|web|operator) return 0 ;;
        *) return 1 ;;
    esac
}

# Resolve actual container name for a compose service.
# Uses docker compose as the source of truth — reads the merged overlay chain.
# Results are cached after first call to avoid repeated subprocess spawns.
_RESOLVE_CACHE=""
_resolve_all_containers() {
    [ -n "$_RESOLVE_CACHE" ] && return
    load_config
    # Try running/stopped containers first (most common path)
    _RESOLVE_CACHE=$(cd "$DOCKER_DIR" && eval "$(get_compose_cmd) ps -a --format '{{.Service}}={{.Name}}'" 2>/dev/null)
    if [ -z "$_RESOLVE_CACHE" ]; then
        # Nothing running — parse compose config
        _RESOLVE_CACHE=$(cd "$DOCKER_DIR" && eval "$(get_compose_cmd) config" 2>/dev/null | \
            awk '/^  [a-z].*:$/{svc=substr($1,1,length($1)-1)} svc && /container_name:/{print svc "=" $2; svc=""}')
    fi
}

resolve_container() {
    local service=$1
    _resolve_all_containers
    local name
    name=$(echo "$_RESOLVE_CACHE" | grep "^${service}=" | head -1 | cut -d= -f2)
    if [ -n "$name" ]; then
        echo "$name"
    else
        echo "kg-${service}"
    fi
}

# Read an OCI label from a running container
inspect_label() {
    local container=$1 label=$2
    docker inspect --format "{{index .Config.Labels \"$label\"}}" "$container" 2>/dev/null
}

# Get the latest semver version tag from GHCR for a service
get_remote_version() {
    local service=$1
    gh api "/users/aaronsb/packages/container/knowledge-graph-system%2Fkg-${service}/versions" \
        --jq '[.[] | select(.metadata.container.tags | length > 0) | .metadata.container.tags[] | select(test("^[0-9]"))] | first' 2>/dev/null
}

# Get the target image name for a service (respects IMAGE_SOURCE)
get_image_ref() {
    local service=$1
    if [ "$IMAGE_SOURCE" = "ghcr" ]; then
        echo "${KG_GHCR}/kg-${service}:latest"
    else
        echo "kg-${service}:latest"
    fi
}

# Display version table for platform services
show_versions_table() {
    local show_stale=${1:-false}

    # Check if gh CLI is available for remote version queries
    local has_gh=false
    command -v gh &>/dev/null && gh auth status &>/dev/null 2>&1 && has_gh=true

    if [ "$has_gh" = "true" ]; then
        printf "  %-14s %-26s %-10s %-10s %-12s %s\n" "Service" "Local" "Remote" "Commit" "Built" "Image"
        printf "  %-14s %-26s %-10s %-10s %-12s %s\n" "-------" "-----" "------" "------" "-----" "-----"
    else
        printf "  %-14s %-26s %-10s %-12s %s\n" "Service" "Version" "Commit" "Built" "Image"
        printf "  %-14s %-26s %-10s %-12s %s\n" "-------" "-------" "------" "-----" "-----"
    fi

    local any_stale=false
    for service in postgres api web operator; do
        local container
        container=$(resolve_container "$service")

        # Check if running
        if [ -z "$container" ] || ! docker ps --format '{{.Names}}' | grep -q "^${container}$"; then
            printf "  %-14s ${YELLOW}%-10s${NC}\n" "$service" "(stopped)"
            continue
        fi

        local ver=$(inspect_label "$container" "org.opencontainers.image.version")
        local rev=$(inspect_label "$container" "org.opencontainers.image.revision")
        local blt=$(inspect_label "$container" "org.opencontainers.image.created")

        # Normalize "unknown" to empty
        [ "$ver" = "unknown" ] && ver=""
        [ "$rev" = "unknown" ] && rev=""
        [ "$blt" = "unknown" ] && blt=""

        # Postgres fallback: query extension versions from the running database
        if [ "$service" = "postgres" ] && [ -z "$ver" ]; then
            local age_ver=$(docker exec "$container" psql -U admin -d knowledge_graph -tAc \
                "SELECT extversion FROM pg_extension WHERE extname='age'" 2>/dev/null | tr -d '[:space:]')
            local accel_ver=$(docker exec "$container" psql -U admin -d knowledge_graph -tAc \
                "SELECT extversion FROM pg_extension WHERE extname='graph_accel'" 2>/dev/null | tr -d '[:space:]')
            local parts=""
            [ -n "$age_ver" ] && parts="AGE ${age_ver}"
            [ -n "$accel_ver" ] && parts="${parts:+${parts}, }accel ${accel_ver}"
            [ -n "$parts" ] && ver="$parts"
        fi

        # Truncate built date to date-only
        [ -n "$blt" ] && blt="${blt%%T*}"

        # Short image SHA for display
        local img_sha=$(docker inspect --format '{{.Image}}' "$container" 2>/dev/null)
        local short_sha=""
        [ -n "$img_sha" ] && short_sha="${img_sha:7:12}"

        # Stale detection: compare running image vs locally available image
        local stale_flag=""
        if [ "$show_stale" = "true" ]; then
            local image_ref
            # Dev-mode postgres uses stock apache/age, not kg-postgres
            if [ "$service" = "postgres" ] && [ "$DEV_MODE" = "true" ]; then
                image_ref="apache/age"
            else
                image_ref=$(get_image_ref "$service")
            fi
            local local_sha=$(docker image inspect --format '{{.Id}}' "$image_ref" 2>/dev/null)
            if [ -n "$local_sha" ] && [ -n "$img_sha" ] && [ "$img_sha" != "$local_sha" ]; then
                stale_flag=" ${YELLOW}↑${NC}"
                any_stale=true
            fi
        fi

        # Remote version lookup
        if [ "$has_gh" = "true" ]; then
            local remote_ver=$(get_remote_version "$service")
            local remote_display="${remote_ver:--}"
            # Color: green if matching, yellow if different
            if [ -n "$remote_ver" ] && [ -n "$ver" ] && [ "$remote_ver" = "$ver" ]; then
                remote_display="${GREEN}${remote_ver}${NC}"
            elif [ -n "$remote_ver" ] && [ -n "$ver" ] && [ "$remote_ver" != "$ver" ]; then
                remote_display="${YELLOW}${remote_ver}${NC}"
            fi
            printf "  %-14s %-26s %-10b %-10s %-12s %s%b\n" \
                "$service" "${ver:--}" "$remote_display" "${rev:--}" "${blt:--}" "${short_sha:--}" "$stale_flag"
        else
            printf "  %-14s %-26s %-10s %-12s %s%b\n" \
                "$service" "${ver:--}" "${rev:--}" "${blt:--}" "${short_sha:--}" "$stale_flag"
        fi
    done

    # operator.sh script version
    if [ "$has_gh" = "true" ]; then
        printf "  %-14s %-26s %-10s %s\n" "operator.sh" "$OPERATOR_VERSION" "" "(host script)"
    else
        printf "  %-14s %-26s %s\n" "operator.sh" "$OPERATOR_VERSION" "(host script)"
    fi

    if [ "$show_stale" = "true" ] && [ "$any_stale" = "true" ]; then
        echo ""
        echo -e "  ${YELLOW}↑ = newer image available, run './operator.sh upgrade' to apply${NC}"
    fi
}

cmd_versions() {
    load_config
    echo ""
    echo -e "${BOLD}Platform Versions${NC} (operator.sh v${OPERATOR_VERSION})"
    echo ""
    show_versions_table true
}

cmd_logs() {
    local service="${1:-api}"
    shift 2>/dev/null || true

    load_config
    cd "$DOCKER_DIR"
    run_compose logs "$@" "$service"
}

cmd_restart() {
    local service="${1:-}"
    [ -z "$service" ] && echo "Usage: $0 restart <service|all>" && exit 1

    check_env
    load_config
    cd "$DOCKER_DIR"

    if [ "$service" = "all" ]; then
        echo -e "${BLUE}→ Restarting all services...${NC}"
        run_compose restart
        echo -e "${GREEN}✓ All services restarted${NC}"
    elif is_known_service "$service"; then
        echo -e "${BLUE}→ Restarting $service...${NC}"
        run_compose restart "$service"
        echo -e "${GREEN}✓ $service restarted${NC}"
    else
        echo -e "${RED}Unknown service: $service${NC}"
        echo "Known services: $KNOWN_SERVICES"
        exit 1
    fi
}

# Configure the source-IP allowlist in front of the /cockpit host console.
# This is defense in depth ahead of Cockpit's own PAM login (a root-capable
# surface). Default is open (no restriction); lock it to a LAN/VPN/admin range.
cmd_cockpit_access() {
    check_env
    load_config

    if [ "${COCKPIT_PROXY:-false}" != "true" ]; then
        echo -e "${YELLOW}⚠ Cockpit proxy not enabled (COCKPIT_PROXY != true).${NC}"
        echo "  Enable it first: provision.env KG_COCKPIT_PROXY=true, or init --cockpit-proxy."
        exit 1
    fi

    local arg="${1:-status}" cidrs
    case "$arg" in
        status|"")
            local cur
            cur="$(grep -E '^KG_COCKPIT_ALLOW_CIDRS=' "$ENV_FILE" 2>/dev/null | cut -d= -f2-)"
            echo -e "${BLUE}/cockpit allow CIDRs:${NC} ${cur:-0.0.0.0/0,::/0 (open — no restriction)}"
            echo "Usage: $0 cockpit-access <open|private|CIDR[,CIDR...]>"
            return 0 ;;
        open)                 cidrs="0.0.0.0/0,::/0" ;;
        private|rfc1918|lan)  cidrs="127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16" ;;
        *)                    cidrs="$arg" ;;   # custom comma-separated CIDR list
    esac

    # Upsert KG_COCKPIT_ALLOW_CIDRS in .env; compose substitutes it into the
    # cockpit router's ipallowlist label when the sidecar is (re)created.
    if grep -qE '^KG_COCKPIT_ALLOW_CIDRS=' "$ENV_FILE" 2>/dev/null; then
        sed -i "s|^KG_COCKPIT_ALLOW_CIDRS=.*|KG_COCKPIT_ALLOW_CIDRS=$cidrs|" "$ENV_FILE"
    else
        echo "KG_COCKPIT_ALLOW_CIDRS=$cidrs" >> "$ENV_FILE"
    fi

    echo -e "${BLUE}→ Applying /cockpit allowlist: ${BOLD}$cidrs${NC}"
    cd "$DOCKER_DIR"
    run_compose up -d --force-recreate cockpit-proxy
    echo -e "${GREEN}✓ /cockpit access updated${NC}"
    [ "$cidrs" = "0.0.0.0/0,::/0" ] && echo -e "  ${YELLOW}(open — any source IP that can reach the box)${NC}"
}

cmd_update() {
    check_env
    load_config
    cd "$DOCKER_DIR"

    local dry_run=false
    while [[ $# -gt 0 ]]; do
        case $1 in
            --dry-run|--whatif) dry_run=true; shift ;;
            *) break ;;
        esac
    done

    echo -e "\n${BOLD}Current versions:${NC}"
    show_versions_table false
    echo ""

    if [ "$dry_run" = true ]; then
        if [ "$IMAGE_SOURCE" = "local" ]; then
            echo -e "${YELLOW}[WHATIF] Would rebuild local images${NC}"
        else
            echo -e "${YELLOW}[WHATIF] Would pull latest images from GHCR${NC}"
        fi
        return
    fi

    if [ "$IMAGE_SOURCE" = "local" ]; then
        echo -e "${BLUE}→ Building local images...${NC}"
        run_compose build "$@"
    else
        echo -e "${BLUE}→ Pulling images...${NC}"
        run_compose pull "$@"
    fi

    echo ""
    echo -e "${BOLD}Updated images:${NC}"
    show_versions_table true
    echo ""
    echo -e "${GREEN}✓ Images updated. Run './operator.sh upgrade' to apply.${NC}"
}

# ============================================================================
# CONTAINER DELEGATION: Config commands
# ============================================================================

# Run command in operator container
run_in_operator() {
    check_operator
    # -t for TTY (colors/formatting)
    # -i only if stdin is a real TTY (needed for interactive prompts)
    local docker_flags=""
    if [ -t 0 ] && [ -t 1 ]; then
        docker_flags="-it"
    elif [ -t 1 ]; then
        docker_flags="-t"
    fi
    docker exec $docker_flags "$OPERATOR_CONTAINER" "$@"
}

cmd_admin()       { run_in_operator python /workspace/operator/configure.py admin "$@"; }
cmd_ai_provider() { run_in_operator python /workspace/operator/configure.py ai-provider "$@"; }
cmd_embedding()   { run_in_operator python /workspace/operator/configure.py embedding "$@"; }
cmd_api_key()     { run_in_operator python /workspace/operator/configure.py api-key "$@"; }
cmd_query() {
    # Run SQL query against PostgreSQL (host-side, uses docker compose)
    local query="$1"
    if [ -z "$query" ]; then
        echo -e "${RED}Usage: $0 query 'SQL query'${NC}"
        echo ""
        echo "Examples:"
        echo "  $0 query 'SELECT count(*) FROM kg_auth.users'"
        echo "  $0 query 'SELECT username, primary_role FROM kg_auth.users'"
        exit 1
    fi
    $(get_compose_cmd) exec -T postgres psql -U admin -d knowledge_graph -c "$query"
}
cmd_garage()      { run_in_operator /workspace/operator/lib/garage-manager.sh "$@"; }

# ============================================================================
# Help
# ============================================================================

show_help() {
    cat << EOF
${BOLD}Knowledge Graph Platform Manager${NC} v${OPERATOR_VERSION}

Usage: $0 <command> [options]

${BOLD}Lifecycle:${NC}
  start              Start platform (infra + app)
  stop [service|--keep-infra] Stop platform or specific service
  restart <service|all>  Restart a service (or all)
  upgrade            Pull, migrate, restart
  update             Pull images only
  teardown [opts]    Remove platform (delegates to operator/lib/teardown.sh)
                     --full              Containers + volumes + images + operator
                     --remove-volumes    Volumes only (incl. dangling-volume sweep)
                     --remove-images     Force image rebuild on next start
                     --include-operator  Also remove the operator container
                     --keep-env          Keep .env (default deletes secrets)
                     -y, --yes           Skip confirmation prompts

${BOLD}Management:${NC}
  status             Show container status
  versions           Show version info for all containers
  logs <service> [-f] View logs (default: api)
  shell              Open shell in operator container

${BOLD}Configuration:${NC}
  admin              Manage admin user
  ai-provider        Configure AI extraction
  embedding          Configure embeddings
  api-key            Store API keys

${BOLD}Database:${NC}
  query 'SQL'        Run SQL query (also: pg)

${BOLD}Infrastructure:${NC}
  garage             Manage Garage storage (status, init, repair)

${BOLD}Security:${NC}
  cockpit-access <x> /cockpit source-IP allowlist: open | private | CIDR[,CIDR...]
                     (no arg shows current; default open)

${BOLD}Maintenance:${NC}
  self-update        Update operator.sh and operator container

${BOLD}Development (repo only):${NC}
  init               Guided setup
  init --headless    Automated setup

EOF
}

# ============================================================================
# Main
# ============================================================================

case "${1:-help}" in
    # Init: only in repo mode
    init)
        shift
        if [ -f "$SCRIPT_DIR/operator/lib/guided-init.sh" ]; then
            [[ "$1" == "--headless" ]] && "$SCRIPT_DIR/operator/lib/headless-init.sh" "$@" || "$SCRIPT_DIR/operator/lib/guided-init.sh" "$@"
        else
            echo -e "${RED}Init only available in repo mode${NC}"
            exit 1
        fi
        ;;

    # Lifecycle
    start)    shift; cmd_start "$@" ;;
    stop)     shift; cmd_stop "$@" ;;
    restart)  shift; cmd_restart "$@" ;;
    upgrade)  shift; cmd_upgrade "$@" ;;
    update)   shift; cmd_update "$@" ;;
    teardown) shift; cmd_teardown "$@" ;;

    # Management
    status)   cmd_status ;;
    versions) cmd_versions ;;
    logs)     shift; cmd_logs "$@" ;;
    shell)  check_operator; docker exec -it "$OPERATOR_CONTAINER" /bin/bash ;;

    # Config (delegated)
    admin)       shift; cmd_admin "$@" ;;
    ai-provider) shift; cmd_ai_provider "$@" ;;
    embedding)   shift; cmd_embedding "$@" ;;
    api-key)     shift; cmd_api_key "$@" ;;
    query|pg)    shift; cmd_query "$@" ;;

    # Infrastructure
    garage)      shift; cmd_garage "$@" ;;

    # SSL
    recert)
        check_operator
        docker exec "$OPERATOR_CONTAINER" /workspace/operator/lib/recert.sh "$@"
        ;;

    # Cockpit /cockpit source-IP allowlist (defense in depth before PAM login)
    cockpit-access) shift; cmd_cockpit_access "$@" ;;

    # Self-update: update operator.sh and operator container
    self-update)
        echo -e "${BLUE}${BOLD}Self-Update${NC}"
        echo ""

        # Check docker permissions
        if ! docker ps >/dev/null 2>&1; then
            echo -e "${RED}✗ Cannot access Docker. Try: sudo ./operator.sh self-update${NC}"
            exit 1
        fi

        # Check write permissions to script directory
        if [ ! -w "$SCRIPT_DIR" ]; then
            echo -e "${RED}✗ Cannot write to $SCRIPT_DIR. Try: sudo ./operator.sh self-update${NC}"
            exit 1
        fi

        local_version="$OPERATOR_VERSION"
        container_version=""

        echo -e "${BLUE}→ Checking versions...${NC}"
        echo -e "  Local:     ${BOLD}$local_version${NC}"

        # Get version from container (if running)
        if docker ps --format '{{.Names}}' | grep -q "^${OPERATOR_CONTAINER}$"; then
            container_version=$(docker exec "$OPERATOR_CONTAINER" grep '^OPERATOR_VERSION=' /etc/kg/operator.sh 2>/dev/null | cut -d'"' -f2 || echo "")
            if [ -n "$container_version" ]; then
                echo -e "  Container: ${BOLD}$container_version${NC}"
            else
                echo -e "  Container: ${YELLOW}unknown${NC}"
            fi
        else
            echo -e "  Container: ${YELLOW}not running${NC}"
        fi
        echo ""

        # Compare versions (simple string comparison - newer versions should sort higher)
        update_script=false
        if [ -n "$container_version" ] && [ "$container_version" != "$local_version" ]; then
            # Use sort -V for version comparison
            newer=$(printf '%s\n%s\n' "$local_version" "$container_version" | sort -V | tail -1)
            if [ "$newer" = "$container_version" ] && [ "$newer" != "$local_version" ]; then
                echo -e "${BLUE}→ Container has newer operator.sh ($container_version)${NC}"
                update_script=true
            fi
        fi

        # Update operator.sh from container if newer
        if [ "$update_script" = true ]; then
            echo -e "${BLUE}→ Extracting operator.sh from container...${NC}"
            ORIG_OWNER=$(stat -c '%u:%g' "$SCRIPT_DIR/operator.sh" 2>/dev/null || echo "")
            if docker cp "$OPERATOR_CONTAINER":/etc/kg/operator.sh "$SCRIPT_DIR/operator.sh.new"; then
                chmod +x "$SCRIPT_DIR/operator.sh.new"
                if [ -n "$ORIG_OWNER" ]; then
                    chown "$ORIG_OWNER" "$SCRIPT_DIR/operator.sh.new" 2>/dev/null || true
                fi
                mv "$SCRIPT_DIR/operator.sh.new" "$SCRIPT_DIR/operator.sh"
                echo -e "${GREEN}  ✓ operator.sh updated to $container_version${NC}"
            else
                echo -e "${RED}  ✗ Failed to extract operator.sh${NC}"
            fi
        else
            echo -e "${GREEN}  ✓ operator.sh is current${NC}"
        fi

        # Always pull and recreate operator container
        echo ""
        echo -e "${BLUE}→ Updating operator container...${NC}"

        # Pull latest operator image
        echo -e "  Pulling ${KG_GHCR}/kg-operator:latest..."
        if docker pull "${KG_GHCR}/kg-operator:latest" >/dev/null 2>&1; then
            echo -e "${GREEN}  ✓ Image pulled${NC}"
        else
            echo -e "${RED}  ✗ Failed to pull operator image${NC}"
            exit 1
        fi

        # Get current container config for recreation
        load_config
        install_dir="$SCRIPT_DIR"

        # Stop and remove old container
        echo -e "  Recreating container..."
        docker rm -f "$OPERATOR_CONTAINER" >/dev/null 2>&1 || true

        # Start new container with same mounts as install.sh creates
        docker run -d \
            --name "$OPERATOR_CONTAINER" \
            --network knowledge-graph-network \
            --env-file "$ENV_FILE" \
            -e COMPOSE_PROJECT_NAME=knowledge-graph \
            -v /var/run/docker.sock:/var/run/docker.sock \
            -v "$install_dir:/project" \
            "${KG_GHCR}/kg-operator:latest" >/dev/null

        echo -e "${GREEN}  ✓ Operator container updated${NC}"

        # Check if new container has newer script
        echo ""
        new_container_version=$(docker exec "$OPERATOR_CONTAINER" grep '^OPERATOR_VERSION=' /etc/kg/operator.sh 2>/dev/null | cut -d'"' -f2 || echo "")
        if [ -n "$new_container_version" ] && [ "$new_container_version" != "$local_version" ] && [ "$update_script" = false ]; then
            newer=$(printf '%s\n%s\n' "$local_version" "$new_container_version" | sort -V | tail -1)
            if [ "$newer" = "$new_container_version" ]; then
                echo -e "${YELLOW}Note: New container has operator.sh $new_container_version${NC}"
                echo -e "${YELLOW}Run './operator.sh self-update' again to update the script${NC}"
            fi
        fi

        echo ""
        echo -e "${GREEN}${BOLD}✅ Self-update complete${NC}"
        ;;

    # Help
    help|--help|-h) show_help ;;

    *) echo -e "${RED}Unknown: $1${NC}"; show_help; exit 1 ;;
esac