publish.sh

#!/bin/bash
# ============================================================================
# publish.sh - Unified publishing and versioning tool for Knowledge Graph System
#
# Manages:
#   - Version bumping (platform, scripts, packages)
#   - Docker images (api, web, operator) → GitHub Container Registry
#   - npm package (CLI/MCP)              → npm registry (via GitHub Actions, see below)
#   - Python package (FUSE)              → PyPI
#
# Usage:
#   ./scripts/publish.sh status                  # Show all versions
#   ./scripts/publish.sh bump patch              # Bump platform version
#   ./scripts/publish.sh bump cli patch          # Bump CLI version
#   ./scripts/publish.sh sync-scripts            # Update script versions
#   ./scripts/publish.sh release patch -m "msg"  # Full release workflow
#   ./scripts/publish.sh images [api|web]        # Publish Docker images
#   ./scripts/publish.sh cli                     # Dispatch the npm publish workflow
#   ./scripts/publish.sh fuse                    # Publish PyPI package
#
# Options:
#   -m, --message "desc"   Description for release
#   --dry-run              Preview without making changes
#   --skip-build           Skip build step
#
# npm publishing (the `cli` command):
#   @aaronsb/kg-cli is published by .github/workflows/publish-npm.yml through
#   npm's trusted publisher (OIDC, with provenance). No npm login, token or
#   2FA on this machine. The workflow runs on every pushed v*.*.* tag and
#   publishes whatever version cli/package.json carries at that commit, so
#   bump the CLI BEFORE `release` when cli/ changed:
#       ./scripts/publish.sh bump cli minor && ./scripts/publish.sh release minor -m "..."
#   `cli` here dispatches that workflow on the current branch (workflow_dispatch)
#   for the case where the CLI was bumped after the tag.
#
# GHCR authentication (the `images` commands):
#   docker is logged in to ghcr.io with the gh CLI token. Pushing needs the
#   write:packages scope: `gh auth refresh -h github.com -s write:packages`.
# ============================================================================

set -e

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

# Resolve symlinks to get actual script location
SCRIPT_PATH="$(readlink -f "${BASH_SOURCE[0]}")"
SCRIPT_DIR="$(dirname "$SCRIPT_PATH")"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"

# Registries
GHCR_REGISTRY="ghcr.io"
IMAGE_PREFIX="aaronsb/knowledge-graph-system"

# ============================================================================
# Parse arguments
# ============================================================================

DRY_RUN=false
SKIP_BUILD=false
FORCE=false
USE_TESTPYPI=false
MULTI_ARCH=false
DESCRIPTION=""
COMMAND=""
BUMP_TYPE=""
BUMP_TARGET="platform"
TARGETS=()

show_help() {
    cat << 'EOF'
Usage: publish.sh <command> [options]

Version Management:
  status                    Show all versions and auth status
  bump <type> [target]      Bump version (type: major|minor|patch)
                            target: platform (default), cli, fuse
  sync-scripts              Update script versions to match VERSION file
  release <type> -m "msg"   Full release: bump, sync, tag (needs a CHANGELOG.md entry)
  notes [version]           Print a version's CHANGELOG.md entry (default: VERSION)

Publishing:
  images [api|web|operator] Publish Docker images to GHCR
  images-rocm [variant...]  Publish kg-api ROCm variants (rocm72-host)
                            Defaults to rocm72-host only; --force enables deferred variants
  gh-release                Create the GitHub release for VERSION from its
                            CHANGELOG.md entry plus generated PR notes
  cli                       Dispatch publish-npm.yml (npm trusted publisher) for @aaronsb/kg-cli
  fuse                      Publish Python package (kg-fuse) to PyPI
  appliance                 Build + attach the thin-appliance OVA to the GitHub
                            release (bootstrap seed; stay current via operator upgrade)
  all                       Publish everything (images, cli, fuse)

Options:
  -m, --message "desc"      Description for release/publish
  --dry-run                 Build locally but don't push to registries
  --skip-build              Skip build step (push existing images only)
  --force                   Bypass "already published" checks
  --multi-arch              Build for amd64 + arm64 (auto on release branch)
  --test                    Use TestPyPI instead of PyPI (fuse only)
  -h, --help                Show this help

Examples:
  publish.sh status
  publish.sh bump patch                    # 0.6.5 → 0.6.6
  publish.sh bump cli minor                # CLI 0.6.6 → 0.7.0
  publish.sh release patch -m "Bug fixes"  # Full release workflow
  publish.sh images -m "API improvements"
  publish.sh all -m "Release v0.7.0"
EOF
}

while [[ $# -gt 0 ]]; do
    case "$1" in
        status|bump|sync-scripts|release|notes|gh-release|images|images-rocm|appliance|all)
            COMMAND="$1"
            shift
            ;;
        cli|fuse)
            if [ -z "$COMMAND" ]; then
                COMMAND="$1"
            elif [ "$COMMAND" = "bump" ]; then
                BUMP_TARGET="$1"
            else
                TARGETS+=("$1")
            fi
            shift
            ;;
        major|minor|patch)
            BUMP_TYPE="$1"
            shift
            ;;
        platform)
            if [ "$COMMAND" = "bump" ]; then
                BUMP_TARGET="$1"
            fi
            shift
            ;;
        api|web|operator|postgres|rocm72-host)
            TARGETS+=("$1")
            shift
            ;;
        [0-9]*.[0-9]*.[0-9]*)
            # A version argument (publish.sh notes 0.19.0)
            TARGETS+=("$1")
            shift
            ;;
        --dry-run)
            DRY_RUN=true
            shift
            ;;
        --skip-build)
            SKIP_BUILD=true
            shift
            ;;
        --force)
            FORCE=true
            shift
            ;;
        --test)
            USE_TESTPYPI=true
            shift
            ;;
        --multi-arch)
            MULTI_ARCH=true
            shift
            ;;
        -m|--message)
            DESCRIPTION="$2"
            shift 2
            ;;
        -h|--help)
            show_help
            exit 0
            ;;
        *)
            echo -e "${RED}Unknown argument: $1${NC}"
            echo "Run '$0 --help' for usage"
            exit 1
            ;;
    esac
done

if [ -z "$COMMAND" ]; then
    echo -e "${RED}No command specified${NC}"
    echo "Run '$0 --help' for usage"
    exit 1
fi

# ============================================================================
# Version reading
# ============================================================================

get_versions() {
    VERSION=$(cat "$PROJECT_ROOT/VERSION" 2>/dev/null | tr -d '[:space:]' || echo "0.0.0")
    GIT_SHA=$(git -C "$PROJECT_ROOT" rev-parse --short HEAD 2>/dev/null || echo "unknown")
    GIT_BRANCH=$(git -C "$PROJECT_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
    BUILD_DATE=$(date -Iseconds)

    # Package versions
    CLI_VERSION=$(node -p "require('$PROJECT_ROOT/cli/package.json').version" 2>/dev/null || echo "unknown")
    FUSE_VERSION=$(grep -E "^version" "$PROJECT_ROOT/fuse/pyproject.toml" 2>/dev/null | cut -d'"' -f2 || echo "unknown")

    # Script versions (embedded) - match only static definitions like VAR="x.y.z"
    INSTALL_VERSION=$(grep -E '^INSTALLER_VERSION="[0-9]' "$PROJECT_ROOT/install.sh" 2>/dev/null | head -1 | cut -d'"' -f2 || echo "unknown")
    OPERATOR_VERSION=$(grep -E '^OPERATOR_VERSION="[0-9]' "$PROJECT_ROOT/operator.sh" 2>/dev/null | head -1 | cut -d'"' -f2 || echo "unknown")
    CLIENT_MGR_VERSION=$(grep -E '^CLIENT_MANAGER_VERSION="[0-9]' "$PROJECT_ROOT/client-manager.sh" 2>/dev/null | head -1 | cut -d'"' -f2 || echo "unknown")

    # Git tag info for smart publish checks
    LATEST_TAG=$(git -C "$PROJECT_ROOT" describe --tags --abbrev=0 2>/dev/null || echo "")
    if [ -n "$LATEST_TAG" ]; then
        COMMITS_SINCE_TAG=$(git -C "$PROJECT_ROOT" rev-list "$LATEST_TAG"..HEAD --count 2>/dev/null || echo "0")
    else
        COMMITS_SINCE_TAG=$(git -C "$PROJECT_ROOT" rev-list HEAD --count 2>/dev/null || echo "0")
    fi
}

# is_image_published <image_name> <version>
# True if THIS specific image (e.g. kg-postgres) is already published at version.
# cmd_images checks each image individually so a lagging image is never masked by
# a sibling that is already at this version.
is_image_published() {
    local image_name="$1" version="$2"
    docker manifest inspect "$GHCR_REGISTRY/$IMAGE_PREFIX/$image_name:$version" &>/dev/null
}

# Check if version is already published
is_version_published() {
    local target="$1"
    local version="$2"

    case "$target" in
        images)
            # Per-image checks live in cmd_images via is_image_published(); this
            # whole-target check is kept only for callers that pass "images" with
            # a single representative image. Prefer is_image_published().
            docker manifest inspect "$GHCR_REGISTRY/$IMAGE_PREFIX/kg-api:$version" &>/dev/null
            return $?
            ;;
        cli)
            npm view "@aaronsb/kg-cli@$version" version &>/dev/null
            return $?
            ;;
        fuse)
            # Try pip index first (pip 21.2+), fall back to pip show with version check
            if pip index versions kg-fuse 2>/dev/null | grep -q "$version"; then
                return 0
            fi
            # Fallback: check if installed version matches (less reliable)
            pip show kg-fuse 2>/dev/null | grep -q "Version: $version"
            return $?
            ;;
    esac
    return 1
}

# Smart pre-publish check
check_publish_needed() {
    local target="$1"
    local version="$2"
    local force="${3:-false}"

    if [ "$force" = "true" ]; then
        return 0
    fi

    # Check if already published
    if is_version_published "$target" "$version"; then
        echo -e "${YELLOW}⚠ $target v$version already published${NC}"
        if [ "$COMMITS_SINCE_TAG" -gt 0 ]; then
            echo -e "  ${DIM}$COMMITS_SINCE_TAG commit(s) since last tag ($LATEST_TAG)${NC}"
            echo -e "  ${DIM}Run: ./scripts/publish.sh release patch -m \"description\"${NC}"
        else
            echo -e "  ${DIM}No new commits. Nothing to publish.${NC}"
        fi
        return 1
    fi

    return 0
}

# ============================================================================
# Version bumping
# ============================================================================

bump_version() {
    local current="$1"
    local type="$2"

    IFS='.' read -r major minor patch <<< "${current%-*}"  # Strip any -dev suffix
    patch=${patch:-0}

    case "$type" in
        major) echo "$((major + 1)).0.0" ;;
        minor) echo "$major.$((minor + 1)).0" ;;
        patch) echo "$major.$minor.$((patch + 1))" ;;
        *) echo "$current" ;;
    esac
}

update_version_file() {
    local new_version="$1"
    if [ "$DRY_RUN" = "true" ]; then
        echo -e "${DIM}Would update VERSION to $new_version${NC}"
    else
        echo "$new_version" > "$PROJECT_ROOT/VERSION"
        echo -e "${GREEN}✓ Updated VERSION to $new_version${NC}"
    fi
}

update_script_version() {
    local file="$1"
    local var_name="$2"
    local new_version="$3"

    if [ ! -f "$file" ]; then
        echo -e "${YELLOW}⚠ $file not found${NC}"
        return 1
    fi

    local file_basename=$(basename "$file")
    if [ "$DRY_RUN" = "true" ]; then
        echo -e "${DIM}Would update $file_basename $var_name to $new_version${NC}"
    else
        sed -i "s/^${var_name}=\"[^\"]*\"/${var_name}=\"${new_version}\"/" "$file"
        # Verify the update succeeded
        if grep -q "^${var_name}=\"${new_version}\"" "$file"; then
            echo -e "${GREEN}✓ Updated $file_basename to $new_version${NC}"
        else
            echo -e "${RED}✗ Failed to update $file_basename${NC}"
            return 1
        fi
    fi
}

update_cli_version() {
    local new_version="$1"
    local package_json="$PROJECT_ROOT/cli/package.json"

    if [ ! -f "$package_json" ]; then
        echo -e "${RED}✗ cli/package.json not found${NC}"
        return 1
    fi

    if [ "$DRY_RUN" = "true" ]; then
        echo -e "${DIM}Would update cli/package.json to $new_version${NC}"
    else
        # Use node to update package.json properly
        node -e "
            const fs = require('fs');
            const pkg = JSON.parse(fs.readFileSync('$package_json'));
            pkg.version = '$new_version';
            fs.writeFileSync('$package_json', JSON.stringify(pkg, null, 2) + '\n');
        "
        echo -e "${GREEN}✓ Updated cli/package.json to $new_version${NC}"
    fi
}

update_fuse_version() {
    local new_version="$1"
    local pyproject="$PROJECT_ROOT/fuse/pyproject.toml"

    if [ ! -f "$pyproject" ]; then
        echo -e "${RED}✗ fuse/pyproject.toml not found${NC}"
        return 1
    fi

    if [ "$DRY_RUN" = "true" ]; then
        echo -e "${DIM}Would update fuse/pyproject.toml to $new_version${NC}"
    else
        sed -i "s/^version = \"[^\"]*\"/version = \"$new_version\"/" "$pyproject"
        # Verify the update succeeded
        if grep -q "^version = \"$new_version\"" "$pyproject"; then
            echo -e "${GREEN}✓ Updated fuse/pyproject.toml to $new_version${NC}"
        else
            echo -e "${RED}✗ Failed to update fuse/pyproject.toml${NC}"
            return 1
        fi
    fi
}

# ============================================================================
# Authentication checks
# ============================================================================

check_ghcr_auth() {
    if docker login ghcr.io --get-login &>/dev/null; then
        return 0
    fi
    if command -v gh &>/dev/null; then
        if gh auth token 2>/dev/null | docker login ghcr.io -u "$(gh api user -q .login 2>/dev/null)" --password-stdin &>/dev/null; then
            return 0
        fi
    fi
    return 1
}

check_npm_auth() {
    npm whoami &>/dev/null
}

check_pypi_auth() {
    command -v twine &>/dev/null
}

# ============================================================================
# Commands
# ============================================================================

cmd_status() {
    get_versions

    echo -e "${BOLD}Knowledge Graph System - Version Status${NC}"
    echo ""

    echo -e "${CYAN}Platform:${NC}"
    echo "  VERSION file:     $VERSION"
    echo "  Git commit:       $GIT_SHA"
    echo "  Git branch:       $GIT_BRANCH"
    if [ -n "$LATEST_TAG" ]; then
        if [ "$COMMITS_SINCE_TAG" -gt 0 ]; then
            echo -e "  Latest tag:       $LATEST_TAG ${YELLOW}(+$COMMITS_SINCE_TAG commits)${NC}"
        else
            echo -e "  Latest tag:       $LATEST_TAG ${GREEN}(current)${NC}"
        fi
    else
        echo -e "  Latest tag:       ${DIM}none${NC}"
    fi
    echo ""

    echo -e "${CYAN}Scripts (embedded versions):${NC}"
    local scripts_match=true
    if [ "$INSTALL_VERSION" != "$VERSION" ]; then
        echo -e "  install.sh:       ${YELLOW}$INSTALL_VERSION${NC} (differs from VERSION)"
        scripts_match=false
    else
        echo -e "  install.sh:       ${GREEN}$INSTALL_VERSION${NC}"
    fi
    if [ "$OPERATOR_VERSION" != "$VERSION" ]; then
        echo -e "  operator.sh:      ${YELLOW}$OPERATOR_VERSION${NC} (differs from VERSION)"
        scripts_match=false
    else
        echo -e "  operator.sh:      ${GREEN}$OPERATOR_VERSION${NC}"
    fi
    if [ "$CLIENT_MGR_VERSION" != "$VERSION" ]; then
        echo -e "  client-manager:   ${YELLOW}$CLIENT_MGR_VERSION${NC} (differs from VERSION)"
        scripts_match=false
    else
        echo -e "  client-manager:   ${GREEN}$CLIENT_MGR_VERSION${NC}"
    fi
    if [ "$scripts_match" = "false" ]; then
        echo -e "  ${DIM}Run 'publish.sh sync-scripts' to update${NC}"
    fi
    echo ""

    echo -e "${CYAN}Packages (independent versions):${NC}"
    echo "  CLI (npm):        $CLI_VERSION"
    echo "  FUSE (PyPI):      $FUSE_VERSION"
    echo ""

    echo -e "${CYAN}Registry Authentication:${NC}"
    if check_ghcr_auth; then
        echo -e "  GHCR:   ${GREEN}✓ authenticated${NC}"
    else
        echo -e "  GHCR:   ${RED}✗ not logged in${NC}"
    fi
    if gh auth status &>/dev/null; then
        echo -e "  npm:    ${GREEN}✓ trusted publisher${NC} (publish-npm.yml on tag push; gh authenticated)"
        if ! gh auth status 2>&1 | grep -q "write:packages"; then
            echo -e "          ${YELLOW}⚠ gh token lacks write:packages; image pushes will be denied${NC}"
            echo -e "          ${DIM}gh auth refresh -h github.com -s write:packages${NC}"
        fi
    else
        echo -e "  npm:    ${YELLOW}○ trusted publisher${NC} (publish-npm.yml); ${RED}gh not authenticated${NC} for dispatch"
    fi
    if check_pypi_auth; then
        echo -e "  PyPI:   ${GREEN}✓ twine available${NC}"
    else
        echo -e "  PyPI:   ${RED}✗ twine not found${NC}"
    fi
    echo ""

    echo -e "${CYAN}Published versions:${NC}"
    local npm_pub=$(npm view @aaronsb/kg-cli version 2>/dev/null || echo "not published")
    local pypi_pub=$(pip index versions kg-fuse 2>/dev/null | grep -oP '\d+\.\d+\.\d+' | head -1 || echo "not published")
    echo "  npm (@aaronsb/kg-cli):  $npm_pub"
    echo "  PyPI (kg-fuse):         $pypi_pub"
    echo ""

    # Publish readiness summary
    echo -e "${CYAN}Publish Readiness:${NC}"

    if is_version_published "cli" "$CLI_VERSION" 2>/dev/null; then
        echo -e "  CLI:    ${GREEN}✓ v$CLI_VERSION published${NC}"
    else
        echo -e "  CLI:    ${BLUE}○ v$CLI_VERSION ready to publish${NC}"
    fi

    if is_version_published "fuse" "$FUSE_VERSION" 2>/dev/null; then
        echo -e "  FUSE:   ${GREEN}✓ v$FUSE_VERSION published${NC}"
    else
        echo -e "  FUSE:   ${BLUE}○ v$FUSE_VERSION ready to publish${NC}"
    fi

    # Check if current VERSION tag exists (images use platform version)
    if is_version_published "images" "$VERSION" 2>/dev/null; then
        echo -e "  Images: ${GREEN}✓ v$VERSION published${NC}"
    else
        echo -e "  Images: ${BLUE}○ v$VERSION ready to publish${NC}"
    fi

    echo ""

    # Recommendations
    if [ "$COMMITS_SINCE_TAG" -gt 0 ]; then
        echo -e "${CYAN}Recommendation:${NC}"
        echo -e "  $COMMITS_SINCE_TAG commit(s) since $LATEST_TAG"
        echo -e "  → ${BOLD}./publish.sh release patch -m \"description\"${NC}"
        echo ""
    fi
}

cmd_bump() {
    if [ -z "$BUMP_TYPE" ]; then
        echo -e "${RED}Bump type required: major, minor, or patch${NC}"
        exit 1
    fi

    get_versions

    case "$BUMP_TARGET" in
        platform)
            local new_version=$(bump_version "$VERSION" "$BUMP_TYPE")
            echo -e "${BOLD}Bumping platform version${NC}"
            echo "  Current: $VERSION"
            echo "  New:     $new_version"
            echo ""
            update_version_file "$new_version"
            ;;
        cli)
            local new_version=$(bump_version "$CLI_VERSION" "$BUMP_TYPE")
            echo -e "${BOLD}Bumping CLI version${NC}"
            echo "  Current: $CLI_VERSION"
            echo "  New:     $new_version"
            echo ""
            update_cli_version "$new_version"
            ;;
        fuse)
            local new_version=$(bump_version "$FUSE_VERSION" "$BUMP_TYPE")
            echo -e "${BOLD}Bumping FUSE version${NC}"
            echo "  Current: $FUSE_VERSION"
            echo "  New:     $new_version"
            echo ""
            update_fuse_version "$new_version"
            ;;
    esac
}

cmd_sync_scripts() {
    get_versions

    echo -e "${BOLD}Syncing script versions to $VERSION${NC}"
    echo ""

    update_script_version "$PROJECT_ROOT/install.sh" "INSTALLER_VERSION" "$VERSION"
    update_script_version "$PROJECT_ROOT/operator.sh" "OPERATOR_VERSION" "$VERSION"
    update_script_version "$PROJECT_ROOT/client-manager.sh" "CLIENT_MANAGER_VERSION" "$VERSION"
}

# changelog_entry <version>
#
# Print the body of CHANGELOG.md's "## [<version>]" section (without the
# heading), stopping at the next "## [" heading. Empty output means the version
# has no entry.  @verified (new)
changelog_entry() {
    local version="$1" file="$PROJECT_ROOT/CHANGELOG.md"
    [ -f "$file" ] || return 0
    awk -v v="$version" '
        index($0, "## [" v "]") == 1 { on = 1; next }
        on && /^## \[/ { exit }
        on { print }
    ' "$file" | sed -e '/./,$!d'
}

# unwrap_markdown — join hard-wrapped paragraph and list-item lines.
#
# CHANGELOG.md wraps at ~80 columns; GitHub renders each newline in a release
# body as a line break, so wrapped lines would display ragged. Headings, list
# item starts, blank lines and fenced code keep their line breaks.  @verified (new)
unwrap_markdown() {
    awk '
        function flush() { if (buf != "") { print buf; buf = "" } }
        /^```/ { flush(); print; code = !code; next }
        code { print; next }
        /^[[:space:]]*$/ { flush(); print ""; next }
        /^#/ { flush(); print; next }
        /^[[:space:]]*([-*]|[0-9]+\.) / { flush(); buf = $0; next }
        { line = $0; sub(/^[[:space:]]+/, "", line); buf = (buf == "") ? line : buf " " line }
        END { flush() }
    '
}

cmd_notes() {
    get_versions
    local version="${TARGETS[0]:-$VERSION}"
    local body
    body=$(changelog_entry "$version")
    if [ -z "$body" ]; then
        echo -e "${RED}✗ CHANGELOG.md has no entry for $version${NC}" >&2
        exit 1
    fi
    printf '%s\n' "$body"
}

# cmd_gh_release — create the GitHub release for VERSION. The body is the
# version's CHANGELOG.md entry; --generate-notes appends GitHub's PR list.
cmd_gh_release() {
    get_versions
    local tag="v$VERSION" body
    body=$(changelog_entry "$VERSION" | unwrap_markdown)
    if [ -z "$body" ]; then
        echo -e "${RED}✗ CHANGELOG.md has no entry for $VERSION; write it before publishing${NC}"
        exit 1
    fi
    if ! git -C "$PROJECT_ROOT" ls-remote --exit-code --tags origin "$tag" >/dev/null 2>&1; then
        echo -e "${RED}✗ $tag is not on origin; push it first: git push origin --tags${NC}"
        exit 1
    fi
    if gh release view "$tag" >/dev/null 2>&1; then
        echo -e "${YELLOW}⚠ GitHub release $tag already exists${NC}"
        exit 0
    fi
    if [ "$DRY_RUN" = "true" ]; then
        echo -e "${DIM}Would create GitHub release $tag with:${NC}"
        printf '%s\n' "$body"
        return 0
    fi
    printf '%s\n' "$body" | gh release create "$tag" --title "$tag" --notes-file - --generate-notes
    echo -e "${GREEN}✓ GitHub release $tag created${NC}"
}

cmd_release() {
    if [ -z "$BUMP_TYPE" ]; then
        echo -e "${RED}Release requires bump type: major, minor, or patch${NC}"
        echo "Usage: publish.sh release <patch|minor|major> -m \"message\""
        exit 1
    fi

    get_versions
    local new_version=$(bump_version "$VERSION" "$BUMP_TYPE")

    echo -e "${BOLD}Release workflow: $VERSION → $new_version${NC}"

    # Release notes come from CHANGELOG.md; a tag without an entry would
    # publish a release that says nothing about what it contains.
    if [ "$FORCE" != "true" ] && [ -z "$(changelog_entry "$new_version")" ]; then
        echo -e "${RED}✗ CHANGELOG.md has no entry for $new_version.${NC}"
        echo -e "  Add ${BOLD}## [$new_version] - $(date +%Y-%m-%d)${NC} describing the release, then rerun."
        exit 1
    fi

    # The tag push triggers publish-npm.yml, which publishes cli/package.json's
    # version. If that version is already on npm the workflow fails and the CLI
    # changes in this release never ship. Catch it before the tag exists.
    if [ "$FORCE" != "true" ] && is_version_published "cli" "$CLI_VERSION" 2>/dev/null; then
        # A bump-only change (cli/package.json) is not shippable code; look past it.
        if [ -n "$(git -C "$PROJECT_ROOT" log --oneline "${LATEST_TAG:-HEAD}..HEAD" -- cli/ ':!cli/package.json' 2>/dev/null)" ]; then
            echo -e "${RED}✗ cli/ changed since $LATEST_TAG but cli/package.json is still $CLI_VERSION, already on npm.${NC}"
            echo -e "  The v$new_version tag push would run publish-npm.yml against a published version."
            echo -e "  Bump first: ${BOLD}./publish.sh bump cli <patch|minor|major>${NC}  (or --force to release anyway)"
            exit 1
        fi
    fi
    [ -n "$DESCRIPTION" ] && echo -e "  Message: $DESCRIPTION"
    [ "$DRY_RUN" = "true" ] && echo -e "  ${YELLOW}DRY RUN MODE${NC}"
    echo ""

    # Step 1: Bump VERSION
    echo -e "${CYAN}Step 1: Bump version${NC}"
    update_version_file "$new_version"
    VERSION="$new_version"  # Update for subsequent steps

    # Step 2: Sync scripts
    echo ""
    echo -e "${CYAN}Step 2: Sync script versions${NC}"
    update_script_version "$PROJECT_ROOT/install.sh" "INSTALLER_VERSION" "$VERSION"
    update_script_version "$PROJECT_ROOT/operator.sh" "OPERATOR_VERSION" "$VERSION"
    update_script_version "$PROJECT_ROOT/client-manager.sh" "CLIENT_MANAGER_VERSION" "$VERSION"

    # Step 3: Commit and tag
    echo ""
    echo -e "${CYAN}Step 3: Commit and tag${NC}"
    if [ "$DRY_RUN" = "true" ]; then
        echo -e "${DIM}Would commit: 'Release v$VERSION'${NC}"
        echo -e "${DIM}Would tag: v$VERSION${NC}"
    else
        git -C "$PROJECT_ROOT" add VERSION install.sh operator.sh client-manager.sh CHANGELOG.md
        local commit_msg="Release v$VERSION"
        [ -n "$DESCRIPTION" ] && commit_msg="$commit_msg: $DESCRIPTION"
        git -C "$PROJECT_ROOT" commit -m "$commit_msg"
        git -C "$PROJECT_ROOT" tag -a "v$VERSION" -m "$commit_msg"
        echo -e "${GREEN}✓ Committed and tagged v$VERSION${NC}"
    fi

    # Step 4: Instructions
    echo ""
    echo -e "${CYAN}Next steps:${NC}"
    local current_branch=$(git -C "$PROJECT_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
    echo "  1. Push: git push origin $current_branch --tags"
    echo "     → the tag push runs publish-npm.yml: @aaronsb/kg-cli@$CLI_VERSION via npm trusted publisher"
    echo "  2. GitHub release: ./publish.sh gh-release   (CHANGELOG.md entry + generated PR list)"
    echo "  3. Publish images: ./publish.sh images   (+ ./publish.sh images-rocm)"
    echo "  4. Publish FUSE (if needed): ./publish.sh fuse"
    echo ""
}

# retag_postgres_to_version
#
# Re-tag the already-published kg-postgres image to the current platform VERSION
# (and refresh :latest) WITHOUT rebuilding. Used on releases where the postgres
# image does not need a rebuild — i.e. the graph-accel artifacts are absent
# because the extension did not change. Without this, kg-postgres:latest/:VERSION
# stay frozen at the last build (e.g. platform 0.15.0 but postgres still tagged
# 0.13.2), and standalone installs that pull kg-postgres:latest silently lag.
#
# Uses `docker buildx imagetools create`, which copies the source manifest
# (preserving multi-arch) under new tags entirely server-side: no pull, no
# rebuild, same digest.
#
# Caveat: the postgres image also bakes schema/00_baseline.sql. A re-tag keeps
# whatever baseline the last build captured, so a re-tagged :VERSION may carry an
# older baseline than its label suggests. This is safe — a fresh DB inits from
# the baked baseline and the operator's runtime migrations reconcile it to the
# current schema regardless — but when the baseline itself has changed and you
# want the image to bake it, build properly (artifacts present) instead of
# re-tagging.
retag_postgres_to_version() {
    local image="$GHCR_REGISTRY/$IMAGE_PREFIX/kg-postgres"
    echo -e "${BLUE}→ Re-tagging existing $image to $VERSION (no rebuild needed)${NC}"

    if [ "$DRY_RUN" = "true" ]; then
        echo -e "  ${DIM}Would run: docker buildx imagetools create --tag $image:$VERSION --tag $image:latest $image:latest${NC}"
        return 0
    fi

    # Need an existing :latest to copy from (first-ever publish must build).
    if ! docker buildx imagetools inspect "$image:latest" >/dev/null 2>&1; then
        echo -e "${YELLOW}⚠ No existing $image:latest to re-tag.${NC}"
        echo -e "  ${DIM}Build it once: ./graph-accel/build-in-container.sh --all && ./publish.sh images postgres${NC}"
        return 0
    fi

    if docker buildx imagetools create \
        --tag "$image:$VERSION" \
        --tag "$image:latest" \
        "$image:latest"; then
        echo -e "${GREEN}✓ Re-tagged $image → :$VERSION (+ :latest), digest unchanged${NC}"
    else
        echo -e "${RED}✗ Failed to re-tag $image (is buildx available and are you logged in to GHCR?)${NC}"
    fi
}

cmd_images() {
    get_versions

    if [ ${#TARGETS[@]} -eq 0 ]; then
        TARGETS=(api web operator postgres)
    fi

    # Auto-enable multi-arch on release branch
    local use_multi_arch="$MULTI_ARCH"
    if [ "$GIT_BRANCH" = "release" ] || [ "$GIT_BRANCH" = "main" ]; then
        use_multi_arch=true
    fi

    echo -e "${BOLD}Publishing Docker images to GHCR${NC}"
    echo -e "  Version: ${BLUE}$VERSION${NC}"
    echo -e "  Commit:  ${BLUE}$GIT_SHA${NC}"
    echo -e "  Targets: ${BLUE}${TARGETS[*]}${NC}"
    if [ "$use_multi_arch" = "true" ]; then
        echo -e "  Arch:    ${CYAN}linux/amd64, linux/arm64${NC}"
    else
        echo -e "  Arch:    ${DIM}host only (use --multi-arch for amd64+arm64)${NC}"
    fi
    [ -n "$DESCRIPTION" ] && echo -e "  Message: ${BLUE}$DESCRIPTION${NC}"
    [ "$DRY_RUN" = "true" ] && echo -e "  Mode:    ${YELLOW}DRY RUN${NC}"
    echo ""

    # Per-image "already published" checks happen inside the loop below, so a
    # lagging image is published even when its siblings are already at $VERSION.

    if [ "$DRY_RUN" = "false" ] && ! check_ghcr_auth; then
        echo -e "${RED}Not authenticated to GHCR${NC}"
        echo "Run: docker login ghcr.io"
        exit 1
    fi

    # Ensure buildx builder exists for multi-arch
    if [ "$use_multi_arch" = "true" ]; then
        if ! docker buildx inspect multiarch &>/dev/null; then
            echo -e "${BLUE}→ Creating buildx builder for multi-arch...${NC}"
            docker buildx create --name multiarch --use --bootstrap
        else
            docker buildx use multiarch
        fi
    fi

    cd "$PROJECT_ROOT"

    local built_count=0 skipped_count=0
    for target in "${TARGETS[@]}"; do
        local context dockerfile image_name
        local target_multi_arch="$use_multi_arch"

        # Resolve the image name first so we can do a PER-IMAGE published check.
        case "$target" in
            api)      image_name="kg-api" ;;
            web)      image_name="kg-web" ;;
            operator) image_name="kg-operator" ;;
            postgres) image_name="kg-postgres" ;;
            *) echo -e "${RED}Unknown target: $target${NC}"; continue ;;
        esac

        # Skip images already published at this version (unless --force). Checked
        # per-image, so e.g. postgres still gets built when api/web are current.
        if [ "$DRY_RUN" = "false" ] && [ "$FORCE" = "false" ] && is_image_published "$image_name" "$VERSION"; then
            echo -e "${YELLOW}⚠ $image_name:$VERSION already published — skipping (--force to rebuild)${NC}"
            skipped_count=$((skipped_count + 1))
            continue
        fi
        built_count=$((built_count + 1))

        case "$target" in
            api)
                context="."
                dockerfile="./api/Dockerfile"
                image_name="kg-api"
                ;;
            web)
                context="./web"
                dockerfile="./web/Dockerfile"
                image_name="kg-web"
                ;;
            operator)
                context="."
                dockerfile="./operator/Dockerfile"
                image_name="kg-operator"
                ;;
            postgres)
                # Requires per-arch pre-built artifacts in graph-accel/dist/pg18/.
                # When they are absent (graph-accel unchanged, normal release) we
                # do not rebuild — instead re-tag the existing published image to
                # the new version so its tags track the platform. See
                # retag_postgres_to_version() for the rationale.
                if [ ! -d "./graph-accel/dist/pg18/amd64" ]; then
                    echo -e "${YELLOW}⚠ graph-accel/dist/pg18/amd64/ missing — not rebuilding postgres${NC}"
                    echo -e "  ${DIM}(rebuild only if graph-accel changed: ./graph-accel/build-in-container.sh --all)${NC}"
                    retag_postgres_to_version
                    continue
                fi
                if [ "$target_multi_arch" = "true" ] && [ ! -d "./graph-accel/dist/pg18/arm64" ]; then
                    echo -e "${YELLOW}⚠ Multi-arch requested but graph-accel/dist/pg18/arm64/ missing${NC}"
                    echo -e "  Build with: ${BLUE}./graph-accel/build-in-container.sh --all${NC}"
                    echo -e "  Building amd64 only."
                    target_multi_arch=false
                fi
                context="."
                dockerfile="./docker/Dockerfile.postgres"
                image_name="kg-postgres"
                ;;
            *)
                echo -e "${RED}Unknown target: $target${NC}"
                continue
                ;;
        esac

        local full_image="$GHCR_REGISTRY/$IMAGE_PREFIX/$image_name"

        if [ "$SKIP_BUILD" = "false" ]; then
            echo -e "${BLUE}→ Building $target...${NC}"

            local label_args=(
                --label "org.opencontainers.image.version=$VERSION"
                --label "org.opencontainers.image.revision=$GIT_SHA"
                --label "org.opencontainers.image.created=$BUILD_DATE"
                --label "org.opencontainers.image.source=https://github.com/$IMAGE_PREFIX"
            )
            [ -n "$DESCRIPTION" ] && label_args+=(--label "org.opencontainers.image.description=$DESCRIPTION")

            if [ "$target_multi_arch" = "true" ]; then
                # Multi-arch build with buildx (builds and pushes in one step)
                local push_flag=""
                [ "$DRY_RUN" = "false" ] && push_flag="--push"

                docker buildx build \
                    --platform linux/amd64,linux/arm64 \
                    --file "$dockerfile" \
                    --build-arg GIT_COMMIT="$GIT_SHA" \
                    --build-arg BUILD_DATE="$BUILD_DATE" \
                    "${label_args[@]}" \
                    --tag "$full_image:latest" \
                    --tag "$full_image:$VERSION" \
                    --tag "$full_image:sha-$GIT_SHA" \
                    $push_flag \
                    "$context"

                echo -e "${GREEN}✓ Built $full_image (amd64 + arm64)${NC}"
                [ "$DRY_RUN" = "false" ] && echo -e "${GREEN}✓ Pushed $full_image:$VERSION${NC}"
            else
                # Single-arch build (host architecture)
                docker build \
                    --file "$dockerfile" \
                    --build-arg GIT_COMMIT="$GIT_SHA" \
                    --build-arg BUILD_DATE="$BUILD_DATE" \
                    "${label_args[@]}" \
                    --tag "$full_image:latest" \
                    --tag "$full_image:$VERSION" \
                    --tag "$full_image:sha-$GIT_SHA" \
                    "$context"

                echo -e "${GREEN}✓ Built $full_image${NC}"
            fi
        fi

        # Push for single-arch (multi-arch pushes during build)
        if [ "$DRY_RUN" = "false" ] && [ "$target_multi_arch" = "false" ]; then
            echo -e "${BLUE}→ Pushing $target...${NC}"
            docker push "$full_image:latest"
            docker push "$full_image:$VERSION"
            docker push "$full_image:sha-$GIT_SHA"
            echo -e "${GREEN}✓ Pushed $full_image:$VERSION${NC}"
        fi
        echo ""
    done

    # Summary — make "nothing to do" explicit instead of silently exiting.
    if [ "$DRY_RUN" = "false" ] && [ "$built_count" -eq 0 ] && [ "$skipped_count" -gt 0 ]; then
        echo -e "${GREEN}✓ All ${skipped_count} target image(s) already published at v$VERSION${NC}"
        if [ "${COMMITS_SINCE_TAG:-0}" -gt 0 ]; then
            echo -e "  ${DIM}${COMMITS_SINCE_TAG} commit(s) since ${LATEST_TAG} — cut a release: ./scripts/publish.sh release patch -m \"...\"${NC}"
        fi
    fi
}

# ============================================================================
# ADR-101: Publish ROCm variants of kg-api
#
# Builds and pushes one or more ROCm-specific kg-api images to GHCR. The
# default-published kg-api:latest carries PyPI's default torch wheel (CUDA
# runtime bundled, works for NVIDIA + CPU). AMD ROCm needs separate wheels
# from PyTorch's ROCm index OR AMD's official rocm/pytorch base image.
#
# Variants:
#   rocm72-host api/Dockerfile.rocm-host                       ROCm 7.x via base image
#
# The wheel-based variants (rocm60, rocm61) were never published and were
# removed in ADR-101's 2026-05-28 update — see the addendum there for the
# rationale. Adding a future variant: tested-by-maintainer goes in
# DEFAULT_VARIANTS, untested goes in DEFERRED_VARIANTS (gated behind
# --force).
#
# Single-arch (linux/amd64). ROCm has no production arm64 build path.
# Tagged as kg-api:<variant> and kg-api:<VERSION>-<variant>; does NOT touch
# the :latest tag.
# ============================================================================
cmd_images_rocm() {
    get_versions

    # Variants the maintainer has personally verified end-to-end. If you're
    # adding a variant after testing, append to this list. Untested variants
    # belong in DEFERRED_VARIANTS until someone runs them on real hardware.
    local DEFAULT_VARIANTS=(rocm72-host)
    local DEFERRED_VARIANTS=()

    local variants=("${DEFAULT_VARIANTS[@]}")
    # TARGETS may carry explicit variant names from CLI.
    if [ ${#TARGETS[@]} -gt 0 ]; then
        variants=("${TARGETS[@]}")
    fi

    echo -e "${BOLD}Publishing ROCm variants of kg-api to GHCR${NC} (ADR-101)"
    echo -e "  Version:  ${BLUE}$VERSION${NC}"
    echo -e "  Commit:   ${BLUE}$GIT_SHA${NC}"
    echo -e "  Variants: ${BLUE}${variants[*]}${NC}"
    echo -e "  Arch:     ${DIM}linux/amd64 (ROCm has no arm64 path)${NC}"
    [ -n "$DESCRIPTION" ] && echo -e "  Message:  ${BLUE}$DESCRIPTION${NC}"
    [ "$DRY_RUN" = "true" ] && echo -e "  Mode:     ${YELLOW}DRY RUN${NC}"
    echo ""

    if [ "$DRY_RUN" = "false" ] && ! check_ghcr_auth; then
        echo -e "${RED}Not authenticated to GHCR${NC}"
        echo "Run: docker login ghcr.io"
        exit 1
    fi

    cd "$PROJECT_ROOT"

    local image_name="kg-api"
    local full_image="$GHCR_REGISTRY/$IMAGE_PREFIX/$image_name"

    for variant in "${variants[@]}"; do
        local dockerfile=""
        local build_arg=""

        case "$variant" in
            rocm72-host)
                dockerfile="./api/Dockerfile.rocm-host"
                build_arg=""  # base image pins torch
                ;;
            *)
                echo -e "${RED}Unknown ROCm variant: $variant${NC}"
                echo -e "  Known variants: rocm72-host"
                continue
                ;;
        esac

        # Gate deferred (untested) variants behind an explicit confirmation
        # in the variants list — refusing to silently build something we
        # haven't personally verified.
        local is_deferred=false
        for d in "${DEFERRED_VARIANTS[@]}"; do
            if [ "$d" = "$variant" ]; then
                is_deferred=true
                break
            fi
        done
        if [ "$is_deferred" = "true" ] && [ "${FORCE:-false}" != "true" ]; then
            echo -e "${YELLOW}⚠ Skipping deferred variant ${variant}${NC} — no maintainer-verified test on real hardware."
            echo -e "  Re-run with ${BLUE}--force${NC} to publish anyway."
            echo ""
            continue
        fi

        echo -e "${BLUE}→ Building $image_name:$variant from $dockerfile...${NC}"

        local label_args=(
            --label "org.opencontainers.image.version=$VERSION"
            --label "org.opencontainers.image.revision=$GIT_SHA"
            --label "org.opencontainers.image.created=$BUILD_DATE"
            --label "org.opencontainers.image.source=https://github.com/$IMAGE_PREFIX"
            --label "knowledge-graph.rocm.variant=$variant"
        )
        [ -n "$DESCRIPTION" ] && label_args+=(--label "org.opencontainers.image.description=$DESCRIPTION")

        local build_arg_flag=()
        [ -n "$build_arg" ] && build_arg_flag=(--build-arg "$build_arg")

        if [ "$SKIP_BUILD" = "false" ]; then
            docker build \
                --file "$dockerfile" \
                --build-arg GIT_COMMIT="$GIT_SHA" \
                --build-arg BUILD_DATE="$BUILD_DATE" \
                "${build_arg_flag[@]}" \
                "${label_args[@]}" \
                --tag "$full_image:$variant" \
                --tag "$full_image:$VERSION-$variant" \
                --tag "$full_image:sha-$GIT_SHA-$variant" \
                .
            echo -e "${GREEN}✓ Built $full_image:$variant${NC}"
        fi

        if [ "$DRY_RUN" = "false" ]; then
            echo -e "${BLUE}→ Pushing $image_name:$variant...${NC}"
            docker push "$full_image:$variant"
            docker push "$full_image:$VERSION-$variant"
            docker push "$full_image:sha-$GIT_SHA-$variant"
            echo -e "${GREEN}✓ Pushed $full_image:$variant${NC}"
        fi
        echo ""
    done
}

cmd_cli() {
    get_versions
    echo -e "${BOLD}Publishing CLI to npm via trusted publisher${NC}"
    echo -e "  Version:  ${BLUE}$CLI_VERSION${NC} (cli/package.json)"
    echo -e "  Workflow: ${BLUE}.github/workflows/publish-npm.yml${NC} (OIDC, provenance)"
    [ "$DRY_RUN" = "true" ] && echo -e "  Mode:     ${YELLOW}DRY RUN${NC}"
    echo ""

    # A pushed v* tag already runs the workflow. This command is for the case
    # where cli/package.json was bumped after the tag.
    if [ "$DRY_RUN" = "false" ] && ! check_publish_needed "cli" "$CLI_VERSION" "$FORCE"; then
        echo -e "  ${DIM}Bump first: ./scripts/publish.sh bump cli patch${NC}"
        exit 0
    fi
    if ! gh auth status &>/dev/null; then
        echo -e "${RED}gh is not authenticated; cannot dispatch the workflow${NC}"
        echo "Run: gh auth login"
        exit 1
    fi
    if [ -n "$(git -C "$PROJECT_ROOT" status --porcelain cli/package.json)" ]; then
        echo -e "${RED}cli/package.json has uncommitted changes; commit and push the bump first${NC}"
        exit 1
    fi

    local ref
    ref=$(git -C "$PROJECT_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
    if [ "$DRY_RUN" = "true" ]; then
        echo -e "${DIM}Would run: gh workflow run publish-npm.yml --ref $ref${NC}"
        return 0
    fi
    echo -e "${BLUE}→ Dispatching publish-npm.yml on $ref...${NC}"
    gh workflow run publish-npm.yml --ref "$ref"
    sleep 5
    local run_url
    run_url=$(gh run list --workflow publish-npm.yml --limit 1 --json url --jq '.[0].url' 2>/dev/null)
    echo -e "${GREEN}✓ Dispatched${NC}${run_url:+ — $run_url}"
    echo -e "  ${DIM}gh run watch; then: npm view @aaronsb/kg-cli version${NC}"
}

cmd_fuse() {
    get_versions

    local registry="PyPI"
    local twine_repo=""
    if [ "$USE_TESTPYPI" = "true" ]; then
        registry="TestPyPI"
        twine_repo="--repository testpypi"
    fi

    echo -e "${BOLD}Publishing FUSE driver to $registry${NC}"
    echo -e "  Version: ${BLUE}$FUSE_VERSION${NC}"
    [ "$USE_TESTPYPI" = "true" ] && echo -e "  Registry: ${YELLOW}TestPyPI (test.pypi.org)${NC}"
    [ "$DRY_RUN" = "true" ] && echo -e "  Mode:    ${YELLOW}DRY RUN${NC}"
    echo ""

    # Smart check: skip for testpypi (versions can be reused for testing)
    if [ "$DRY_RUN" = "false" ] && [ "$USE_TESTPYPI" = "false" ]; then
        if ! check_publish_needed "fuse" "$FUSE_VERSION" "$FORCE"; then
            echo -e "  ${DIM}Bump first: ./publish.sh bump fuse patch${NC}"
            exit 0
        fi
    fi

    if ! command -v twine &>/dev/null; then
        echo -e "${RED}twine not found${NC}"
        echo "Run: pip install twine build"
        exit 1
    fi

    cd "$PROJECT_ROOT/fuse"

    if [ "$SKIP_BUILD" = "false" ]; then
        echo -e "${BLUE}→ Building package...${NC}"
        rm -rf dist/ build/ *.egg-info/
        python -m build 2>/dev/null || { pip install build && python -m build; }
        echo -e "${GREEN}✓ Build complete${NC}"
    fi

    echo ""
    if [ "$DRY_RUN" = "false" ]; then
        echo -e "${BLUE}→ Uploading to $registry...${NC}"
        twine upload $twine_repo dist/*
        echo -e "${GREEN}✓ Published kg-fuse==$FUSE_VERSION to $registry${NC}"
        if [ "$USE_TESTPYPI" = "true" ]; then
            echo -e "  ${DIM}Install with: pip install -i https://test.pypi.org/simple/ kg-fuse${NC}"
        fi
    fi
}

# cmd_appliance
#
# Publish the x86 thin-appliance OVA (+ compressed qcow2) as assets on the
# current GitHub release. DELIBERATELY decoupled from the per-release cadence:
# the OVA is a thin *bootstrap seed* (ADR-103) — downloaded once, run, then kept
# current by `operator.sh upgrade` pulling fresh GHCR images. The container
# images are the per-release artifacts; the OVA is refreshed occasionally to move
# the baseline, not on every patch. So this is its own command, not a step in
# `release`. Automates the previously-manual "attach to a Release by hand" flow
# (appliance/README.md).
cmd_appliance() {
    get_versions

    local out_dir="$PROJECT_ROOT/appliance/out"
    local label="$VERSION"
    local tag="v${VERSION}"

    # Two kernel variants ship per release (ADR-119): cloud (default, unsuffixed)
    # and generic (homelab/desktop, "-generic" suffix, hi-res console + AHCI).
    # Each entry is "<name-suffix>:<--kernel flavor>".
    local -a variants=( ":cloud" "-generic:generic" )

    echo -e "${BOLD}Publishing appliance bootstrap images (cloud + generic)${NC}"
    echo -e "  Version: ${BLUE}${label}${NC}  →  GitHub release ${BLUE}${tag}${NC}"
    [ "$DRY_RUN" = "true" ] && echo -e "  Mode:    ${YELLOW}DRY RUN${NC}"
    echo ""
    echo -e "  ${DIM}Convergence contract (ADR-103): the OVA is a thin bootstrap seed —${NC}"
    echo -e "  ${DIM}download once, run, then 'operator.sh upgrade' keeps it current via${NC}"
    echo -e "  ${DIM}GHCR images. Not re-downloaded per release; published occasionally.${NC}"
    echo ""

    if ! command -v gh &>/dev/null; then
        echo -e "${RED}gh (GitHub CLI) not found${NC}"; echo "  Install: https://cli.github.com/"; exit 1
    fi

    # --- Build each variant (unless --skip-build) ----------------------------
    if [ "$SKIP_BUILD" = "false" ]; then
        local v suf kern
        for v in "${variants[@]}"; do
            suf="${v%%:*}"; kern="${v##*:}"
            echo -e "${BLUE}→ Building ${kern} variant (kg-appliance-${label}${suf})...${NC}"
            "$PROJECT_ROOT/appliance/build-appliance.sh" --ova --version "$label" --kernel "$kern"
        done
        echo -e "${GREEN}✓ Builds complete${NC}"
        echo ""
    fi

    # --- Resolve the asset set for both variants -----------------------------
    # OVA always; the qcow2's .xz only when a source qcow2 exists this run (a
    # --skip-build OVA-only run ships just the OVA, never a stale leftover .xz).
    local -a assets=()
    local v suf base ova qcow2
    for v in "${variants[@]}"; do
        suf="${v%%:*}"; base="kg-appliance-${label}${suf}"
        ova="$out_dir/${base}.ova"; qcow2="$out_dir/${base}.qcow2"
        if [ ! -f "$ova" ]; then
            # Post-build, a missing OVA means the build silently failed → hard stop.
            # With --skip-build, publish whatever IS ready: warn and skip (M1).
            if [ "$SKIP_BUILD" = "true" ]; then
                echo -e "${YELLOW}⚠ ${base}.ova not present — skipping ${v##*:} variant (--skip-build)${NC}"
                continue
            fi
            echo -e "${RED}OVA not found: $ova${NC}"
            echo -e "  ${DIM}Build it: appliance/build-appliance.sh --ova --version $label --kernel ${v##*:}${NC}"
            exit 1
        fi
        assets+=( "$ova" )
        [ -f "$qcow2" ] && assets+=( "${qcow2}.xz" )
    done
    if [ "${#assets[@]}" -eq 0 ]; then
        echo -e "${RED}No appliance OVAs found to publish (build first, or drop --skip-build).${NC}"; exit 1
    fi

    # --- Dry run: report intent only, NO side effects (no xz, no SHA file) ---
    if [ "$DRY_RUN" = "true" ]; then
        echo -e "${DIM}Would compress, checksum, and upload to release ${tag}:${NC}"
        for a in "${assets[@]}"; do echo "    $(basename "$a")"; done
        echo "    SHA256SUMS"
        return 0
    fi

    # --- Compress each variant's qcow2 FRESH every run ------------------------
    # The .xz name is keyed on the clean VERSION+variant, so a stale same-name .xz
    # from a prior build must never be reused (xz -f overwrites).
    for v in "${variants[@]}"; do
        suf="${v%%:*}"; qcow2="$out_dir/kg-appliance-${label}${suf}.qcow2"
        if [ -f "$qcow2" ]; then
            echo -e "${BLUE}→ Compressing $(basename "$qcow2") → .xz (a few minutes)...${NC}"
            xz -T0 -k -f "$qcow2"
        fi
    done

    # --- Checksums over exactly the binary assets we publish -----------------
    echo -e "${BLUE}→ Writing SHA256SUMS${NC}"
    ( cd "$out_dir" && sha256sum $(for a in "${assets[@]}"; do basename "$a"; done) > SHA256SUMS )
    sed 's/^/    /' "$out_dir/SHA256SUMS"
    echo ""

    # --- Ensure the release exists, then upload ------------------------------
    # Decoupled from `release`: if $tag doesn't exist this MINTS the GitHub
    # release — a bootstrap image can ship for a baseline that was never formally
    # `release`d. Upload binaries first, then SHA256SUMS LAST as the commit
    # marker, so a mid-upload failure never leaves a checksum ahead of its bytes.
    if ! gh release view "$tag" >/dev/null 2>&1; then
        echo -e "${BLUE}→ Creating release ${tag}${NC}"
        gh release create "$tag" --title "$tag" --notes "${DESCRIPTION:-Appliance bootstrap image ${tag}}"
    fi
    echo -e "${BLUE}→ Uploading ${#assets[@]} image asset(s) to ${tag}${NC}"
    gh release upload "$tag" "${assets[@]}" --clobber
    gh release upload "$tag" "$out_dir/SHA256SUMS" --clobber
    echo -e "${GREEN}✓ Published ${#assets[@]} appliance asset(s) — cloud + generic — to release ${tag}${NC}"
    echo -e "  ${DIM}Verify: gh release download ${tag} -p 'kg-appliance-*' -p SHA256SUMS && sha256sum -c SHA256SUMS${NC}"
}

cmd_all() {
    echo -e "${BOLD}Publishing all packages${NC}"
    echo ""
    cmd_images
    cmd_cli
    cmd_fuse
    echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
    echo -e "${GREEN}✅ All packages published${NC}"
    echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
}

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

case "$COMMAND" in
    status)       cmd_status ;;
    bump)         cmd_bump ;;
    sync-scripts) cmd_sync_scripts ;;
    release)      cmd_release ;;
    notes)        cmd_notes ;;
    gh-release)   cmd_gh_release ;;
    images)       cmd_images ;;
    images-rocm)  cmd_images_rocm ;;
    cli)          cmd_cli ;;
    fuse)         cmd_fuse ;;
    appliance)    cmd_appliance ;;
    all)          cmd_all ;;
esac