kadi-deploy 0.19.0

package/scripts/preflight.sh

@@ -0,0 +1,300 @@
+#!/usr/bin/env bash
+# ──────────────────────────────────────────────────────────────
+# kadi-deploy preflight script
+#
+# Runs during `kadi install` to validate prerequisites.
+# Checks for required and optional dependencies:
+#   - Node.js 18+ (required)
+#   - Docker or Podman (required for local deploys)
+#   - frpc (required for KADI tunnel — Akash deploys)
+#
+# If frpc is missing, attempts auto-install via Homebrew (macOS)
+# or provides clear instructions for manual installation.
+# ──────────────────────────────────────────────────────────────
+
+set -euo pipefail
+
+# ── PATH augmentation ────────────────────────────────────────
+# Non-interactive shells (SSH, lifecycle runners) often have a
+# minimal PATH. Ensure common install locations are included so
+# we can find node, brew, docker, frpc, etc.
+EXTRA_PATHS=(
+  /opt/homebrew/bin
+  /opt/homebrew/sbin
+  /usr/local/bin
+  /usr/local/sbin
+  "$HOME/.local/bin"
+  "$HOME/bin"
+  "$HOME/.nvm/versions/node/*/bin"    # nvm
+  "$HOME/.volta/bin"                  # volta
+  "$HOME/.fnm/aliases/default/bin"    # fnm
+)
+for p in "${EXTRA_PATHS[@]}"; do
+  # Expand globs (e.g. nvm node versions — pick the latest)
+  for resolved in $p; do
+    if [[ -d "$resolved" ]] && ! echo "$PATH" | tr ':' '\n' | grep -qF "$resolved"; then
+      PATH="$resolved:$PATH"
+    fi
+  done
+done
+export PATH
+
+# If nvm is installed, source it to get the correct node
+if [[ -s "$HOME/.nvm/nvm.sh" ]]; then
+  # shellcheck disable=SC1091
+  source "$HOME/.nvm/nvm.sh" 2>/dev/null || true
+fi
+
+# Colors (if terminal supports them)
+if [[ -t 1 ]] && command -v tput &>/dev/null; then
+  GREEN=$(tput setaf 2)
+  YELLOW=$(tput setaf 3)
+  RED=$(tput setaf 1)
+  BOLD=$(tput bold)
+  RESET=$(tput sgr0)
+else
+  GREEN="" YELLOW="" RED="" BOLD="" RESET=""
+fi
+
+ok()   { echo "${GREEN}  ✓${RESET} $*"; }
+warn() { echo "${YELLOW}  ⚠${RESET} $*"; }
+fail() { echo "${RED}  ✗${RESET} $*"; }
+info() { echo "    $*"; }
+
+echo "${BOLD}kadi-deploy preflight${RESET}"
+echo ""
+
+ERRORS=0
+WARNINGS=0
+
+# ── Node.js ──────────────────────────────────────────────────
+
+echo "Checking Node.js..."
+if command -v node &>/dev/null; then
+  NODE_VERSION=$(node --version 2>/dev/null | sed 's/v//')
+  NODE_MAJOR=$(echo "$NODE_VERSION" | cut -d. -f1)
+  if [[ "$NODE_MAJOR" -ge 18 ]]; then
+    ok "Node.js $NODE_VERSION"
+  else
+    fail "Node.js $NODE_VERSION (18+ required)"
+    ERRORS=$((ERRORS + 1))
+  fi
+else
+  fail "Node.js not found"
+  info "Install from https://nodejs.org/"
+  ERRORS=$((ERRORS + 1))
+fi
+
+# ── Container engine (Docker / Podman) ───────────────────────
+
+echo "Checking container engine..."
+if command -v docker &>/dev/null; then
+  DOCKER_VERSION=$(docker --version 2>/dev/null | head -1 || echo "unknown")
+  ok "Docker: $DOCKER_VERSION"
+elif command -v podman &>/dev/null; then
+  PODMAN_VERSION=$(podman --version 2>/dev/null | head -1 || echo "unknown")
+  ok "Podman: $PODMAN_VERSION"
+else
+  warn "No container engine found (Docker or Podman)"
+  info "Required for local deploys. Not needed for Akash-only deploys."
+  info "Install Docker: https://docs.docker.com/get-docker/"
+  WARNINGS=$((WARNINGS + 1))
+fi
+
+# ── frpc (KADI tunnel client) ────────────────────────────────
+
+echo "Checking frpc (tunnel client)..."
+
+# Check if frpc is available in PATH
+FRPC_FOUND=0
+FRPC_PATH=""
+
+if command -v frpc &>/dev/null; then
+  FRPC_PATH=$(command -v frpc)
+  FRPC_FOUND=1
+else
+  # Check common install locations not in PATH
+  for candidate in \
+    /usr/local/bin/frpc \
+    /opt/homebrew/bin/frpc \
+    "$HOME/.local/bin/frpc" \
+    "$HOME/bin/frpc"; do
+    if [[ -x "$candidate" ]]; then
+      FRPC_PATH="$candidate"
+      FRPC_FOUND=1
+      break
+    fi
+  done
+fi
+
+if [[ "$FRPC_FOUND" -eq 1 ]]; then
+  FRPC_VERSION=$("$FRPC_PATH" --version 2>/dev/null || echo "unknown")
+  ok "frpc $FRPC_VERSION ($FRPC_PATH)"
+else
+  # frpc not found — try to install it
+  INSTALLED=0
+
+  # macOS: try Homebrew first, then direct download
+  if [[ "$(uname -s)" == "Darwin" ]]; then
+    if command -v brew &>/dev/null; then
+      warn "frpc not found — attempting install via Homebrew..."
+      if brew install frpc 2>/dev/null; then
+        # Verify the binary actually exists (Homebrew sometimes installs the formula
+        # but macOS XProtect may quarantine/delete the binary)
+        if command -v frpc &>/dev/null; then
+          FRPC_VERSION=$(frpc --version 2>/dev/null || echo "unknown")
+          ok "frpc $FRPC_VERSION (installed via Homebrew)"
+          INSTALLED=1
+        elif [[ -x /opt/homebrew/bin/frpc ]]; then
+          FRPC_VERSION=$(/opt/homebrew/bin/frpc --version 2>/dev/null || echo "unknown")
+          ok "frpc $FRPC_VERSION (installed at /opt/homebrew/bin/frpc)"
+          INSTALLED=1
+        else
+          warn "Homebrew installed frpc formula but binary is missing (XProtect may have removed it)"
+        fi
+      else
+        warn "Homebrew install failed — trying direct download..."
+      fi
+    fi
+
+    # macOS direct download fallback
+    if [[ "$INSTALLED" -eq 0 ]]; then
+      ARCH=$(uname -m)
+      case "$ARCH" in
+        arm64)  FRP_ARCH="darwin_arm64" ;;
+        x86_64) FRP_ARCH="darwin_amd64" ;;
+        *)      FRP_ARCH="" ;;
+      esac
+
+      if [[ -n "$FRP_ARCH" ]] && command -v curl &>/dev/null; then
+        warn "frpc not found — attempting direct download..."
+        FRP_VERSION="0.67.0"
+        FRP_URL="https://github.com/fatedier/frp/releases/download/v${FRP_VERSION}/frp_${FRP_VERSION}_${FRP_ARCH}.tar.gz"
+        INSTALL_DIR="$HOME/.local/bin"
+        mkdir -p "$INSTALL_DIR"
+
+        TMPFILE=$(mktemp /tmp/frpc-XXXXXX.tar.gz)
+        if curl -fsSL "$FRP_URL" -o "$TMPFILE" 2>/dev/null; then
+          EXTRACT_DIR="frp_${FRP_VERSION}_${FRP_ARCH}"
+          if tar -xzf "$TMPFILE" -C /tmp "${EXTRACT_DIR}/frpc" 2>/dev/null; then
+            mv "/tmp/${EXTRACT_DIR}/frpc" "$INSTALL_DIR/frpc"
+            chmod +x "$INSTALL_DIR/frpc"
+            rm -rf "/tmp/${EXTRACT_DIR}" "$TMPFILE"
+
+            # Remove quarantine attribute so macOS doesn't block it
+            xattr -d com.apple.quarantine "$INSTALL_DIR/frpc" 2>/dev/null || true
+
+            if "$INSTALL_DIR/frpc" --version &>/dev/null; then
+              FRPC_VERSION=$("$INSTALL_DIR/frpc" --version 2>/dev/null)
+              ok "frpc $FRPC_VERSION (installed to $INSTALL_DIR/frpc)"
+              INSTALLED=1
+
+              # Ensure ~/.local/bin is noted for PATH
+              if ! echo "$PATH" | tr ':' '\n' | grep -qF "$INSTALL_DIR"; then
+                PATH="$INSTALL_DIR:$PATH"
+                warn "$INSTALL_DIR added to PATH for this session"
+                info "Add permanently to your shell profile:"
+                info "  echo 'export PATH=\"\$HOME/.local/bin:\$PATH\"' >> ~/.zshrc"
+              fi
+            else
+              fail "frpc downloaded but binary won't execute (XProtect may be blocking)"
+              info "Try manually: xattr -d com.apple.quarantine $INSTALL_DIR/frpc"
+            fi
+          fi
+        fi
+        rm -f "$TMPFILE"
+      fi
+    fi
+  fi
+
+  # Linux: try apt or provide download instructions
+  if [[ "$INSTALLED" -eq 0 ]] && [[ "$(uname -s)" == "Linux" ]]; then
+    # Detect architecture
+    ARCH=$(uname -m)
+    case "$ARCH" in
+      x86_64)  FRP_ARCH="amd64" ;;
+      aarch64) FRP_ARCH="arm64" ;;
+      armv7l)  FRP_ARCH="arm" ;;
+      *)       FRP_ARCH="" ;;
+    esac
+
+    if [[ -n "$FRP_ARCH" ]]; then
+      warn "frpc not found — attempting download..."
+      FRP_VERSION="0.67.0"
+      FRP_URL="https://github.com/fatedier/frp/releases/download/v${FRP_VERSION}/frp_${FRP_VERSION}_linux_${FRP_ARCH}.tar.gz"
+      INSTALL_DIR="$HOME/.local/bin"
+      mkdir -p "$INSTALL_DIR"
+
+      if command -v curl &>/dev/null; then
+        TMPFILE=$(mktemp /tmp/frpc-XXXXXX.tar.gz)
+        if curl -fsSL "$FRP_URL" -o "$TMPFILE" 2>/dev/null; then
+          if tar -xzf "$TMPFILE" -C /tmp "frp_${FRP_VERSION}_linux_${FRP_ARCH}/frpc" 2>/dev/null; then
+            mv "/tmp/frp_${FRP_VERSION}_linux_${FRP_ARCH}/frpc" "$INSTALL_DIR/frpc"
+            chmod +x "$INSTALL_DIR/frpc"
+            rm -rf "/tmp/frp_${FRP_VERSION}_linux_${FRP_ARCH}" "$TMPFILE"
+
+            if "$INSTALL_DIR/frpc" --version &>/dev/null; then
+              FRPC_VERSION=$("$INSTALL_DIR/frpc" --version 2>/dev/null)
+              ok "frpc $FRPC_VERSION (installed to $INSTALL_DIR/frpc)"
+              INSTALLED=1
+
+              # Check if ~/.local/bin is in PATH
+              if ! echo "$PATH" | tr ':' '\n' | grep -q "$INSTALL_DIR"; then
+                warn "$INSTALL_DIR is not in your PATH"
+                info "Add to your shell profile:"
+                info "  echo 'export PATH=\"\$HOME/.local/bin:\$PATH\"' >> ~/.bashrc"
+                info "  source ~/.bashrc"
+              fi
+            fi
+          fi
+        fi
+        rm -f "$TMPFILE"
+      fi
+    fi
+  fi
+
+  if [[ "$INSTALLED" -eq 0 ]]; then
+    warn "frpc not installed — KADI tunnel will not work"
+    echo ""
+    info "${BOLD}frpc is required for Akash deployments with local images.${RESET}"
+    info "Without it, kadi-deploy cannot create a tunnel for providers"
+    info "to pull your container images."
+    echo ""
+    info "${BOLD}Install frpc:${RESET}"
+    if [[ "$(uname -s)" == "Darwin" ]]; then
+      info "  brew install frpc"
+      info ""
+      info "If Homebrew install fails (macOS XProtect may block it):"
+      info "  1. Download from https://github.com/fatedier/frp/releases"
+      info "     (choose frp_*_darwin_arm64.tar.gz for Apple Silicon)"
+      info "  2. Extract: tar xzf frp_*.tar.gz"
+      info "  3. Move:    sudo mv frp_*/frpc /usr/local/bin/"
+      info "  4. Allow:   xattr -d com.apple.quarantine /usr/local/bin/frpc"
+    elif [[ "$(uname -s)" == "Linux" ]]; then
+      info "  Download from https://github.com/fatedier/frp/releases"
+      info "  Extract and move frpc to ~/.local/bin/ or /usr/local/bin/"
+    else
+      info "  Download from https://github.com/fatedier/frp/releases"
+    fi
+    echo ""
+    info "After installing, re-run: kadi install"
+    echo ""
+    WARNINGS=$((WARNINGS + 1))
+  fi
+fi
+
+# ── Summary ──────────────────────────────────────────────────
+
+echo ""
+if [[ "$ERRORS" -gt 0 ]]; then
+  fail "${BOLD}Preflight failed with $ERRORS error(s)${RESET}"
+  exit 1
+elif [[ "$WARNINGS" -gt 0 ]]; then
+  warn "${BOLD}Preflight passed with $WARNINGS warning(s)${RESET}"
+  info "kadi-deploy will work but some features may be limited."
+  # Don't exit 1 for warnings — allow install to continue
+  exit 0
+else
+  ok "${BOLD}All checks passed${RESET}"
+  exit 0
+fi

package/src/cli/bid-selector.ts

@@ -0,0 +1,222 @@
+/**
+ * Interactive Bid Selector
+ *
+ * Provides an interactive CLI interface for selecting provider bids during
+ * Akash deployments. Displays bids with color-coded reliability, pricing,
+ * location, and audit status.
+ *
+ * @module cli/bid-selector
+ */
+
+import enquirer from 'enquirer';
+import type { EnhancedBid } from '@kadi.build/deploy-ability/akash';
+import { success, error, warning, dim, chalk } from './colors.js';
+
+/**
+ * Formats uptime percentage with color coding
+ *
+ * Color scheme:
+ * - Green (≥95%): Excellent reliability
+ * - Yellow/Orange (85-94%): Concerning but acceptable
+ * - Red (<85%): Poor reliability
+ * - Gray (no data): Unknown
+ *
+ * @param uptime - Uptime value (0.0 to 1.0)
+ * @returns Colored uptime string
+ */
+function formatUptimeWithColor(uptime: number | undefined): string {
+  if (uptime === undefined) {
+    return dim('No reliability data');
+  }
+
+  const percentage = uptime * 100;
+  const uptimeStr = `${percentage.toFixed(1)}% uptime`;
+
+  if (percentage >= 95) {
+    return success(uptimeStr); // Green
+  } else if (percentage >= 85) {
+    return warning(uptimeStr); // Yellow/Orange
+  } else {
+    return error(uptimeStr); // Red
+  }
+}
+
+/**
+ * Formats a provider bid for display in the selector
+ *
+ * Creates a compact single-line display showing available information:
+ * - Provider name/address (truncated if needed)
+ * - Price in AKT and USD (if AKT price available)
+ * - Additional metadata when available (uptime, location, audit status)
+ *
+ * **Graceful Degradation:**
+ * When provider metadata isn't available (e.g., API returns 403), we show:
+ * - Provider address (always available from blockchain)
+ * - Price in AKT (always available from bid)
+ * - Price in USD (if aktPriceUsd parameter provided)
+ *
+ * @param bid - Enhanced bid to format
+ * @param aktPriceUsd - Optional AKT price in USD for conversion
+ * @returns Formatted display string
+ *
+ * @example With full metadata
+ * ```
+ * Cloudmos | 99.5% | US | 12.5 AKT/mo ($6) | ✓
+ * ```
+ *
+ * @example Without metadata (graceful degradation)
+ * ```
+ * akash1xyz...abcd | 12.5 AKT/mo ($6)
+ * ```
+ */
+function formatBidDisplay(bid: EnhancedBid, aktPriceUsd?: number): string {
+  const provider = bid.provider;
+
+  // Provider name or address (truncate long addresses)
+  let providerName = provider.name || provider.owner;
+  if (!provider.name && provider.owner.length > 20) {
+    // Truncate long addresses to first 10 and last 4 chars
+    providerName = `${provider.owner.slice(0, 10)}...${provider.owner.slice(-4)}`;
+  }
+
+  // Price in AKT (always available)
+  const aktPerMonth = bid.pricing.akt.perMonth.toFixed(1);
+  let priceDisplay = `${aktPerMonth} AKT/mo`;
+
+  // Add USD price if available
+  if (aktPriceUsd) {
+    const usd = bid.pricing.toUSD(aktPriceUsd);
+    // Use 2 decimal places for better precision on small amounts
+    priceDisplay += dim(` ($${usd.perMonth.toFixed(2)})`);
+  }
+
+  // Check if we have metadata available
+  const hasMetadata = provider.reliability || provider.location;
+
+  if (hasMetadata) {
+    // Full display with metadata
+    const uptime = provider.reliability?.uptime7d;
+    const uptimeDisplay = uptime !== undefined
+      ? formatUptimeWithColor(uptime)
+      : dim('No data');
+
+    const location = provider.location?.countryCode || dim('??');
+
+    const auditStatus = provider.isAudited
+      ? success('✓')
+      : dim('✗');
+
+    return `${providerName} ${dim('|')} ${uptimeDisplay} ${dim('|')} ${location} ${dim('|')} ${priceDisplay} ${dim('|')} ${auditStatus}`;
+  } else {
+    // Simplified display when metadata unavailable
+    // Show just provider and price
+    return `${providerName} ${dim('|')} ${priceDisplay}`;
+  }
+}
+
+/**
+ * Prompts user to select a provider bid interactively
+ *
+ * Displays all available bids with color-coded reliability, pricing,
+ * location, and audit status. Uses enquirer's select prompt for
+ * keyboard navigation (arrow keys + Enter).
+ *
+ * **User Experience:**
+ * - Arrow keys to navigate
+ * - Enter to select
+ * - Ctrl+C to cancel
+ * - Clear visual hierarchy with colors
+ * - All relevant information at a glance
+ *
+ * @param bids - Array of enhanced bids to choose from
+ * @param aktPriceUsd - Optional AKT price in USD for price display
+ * @returns Promise resolving to selected bid or null if cancelled/no bids
+ *
+ * @example
+ * ```typescript
+ * const selected = await selectBidInteractively(bids, 0.45);
+ * if (selected) {
+ *   console.log('Selected provider:', selected.provider.name);
+ * } else {
+ *   console.log('No provider selected');
+ * }
+ * ```
+ */
+export async function selectBidInteractively(
+  bids: EnhancedBid[],
+  aktPriceUsd?: number
+): Promise<EnhancedBid | null> {
+  // Handle edge case: no bids available
+  if (bids.length === 0) {
+    return null;
+  }
+
+  // Handle edge case: only one bid (still show prompt for visibility)
+  if (bids.length === 1) {
+    console.log(warning('\nOnly one provider bid available:'));
+    console.log('');
+  }
+
+  try {
+    // Create choices for enquirer
+    const choices = bids.map((bid, index) => ({
+      // Use the formatted display as the name (what user sees)
+      name: formatBidDisplay(bid, aktPriceUsd),
+      // Use the index as the value (what gets returned)
+      value: index
+    }));
+
+    // Show interactive prompt
+    // Note: enquirer's select prompt returns the NAME of the selected choice, not the value!
+    // This is a quirk of enquirer - it returns the display text, not the value field
+    const response = await enquirer.prompt<{ selected: string }>({
+      type: 'select',
+      name: 'selected',
+      message: chalk.bold.cyan('Select a provider:'),
+      choices: choices as any, // Type assertion for enquirer compatibility
+    });
+
+    // Find the bid by matching the display text
+    const selectedIndex = choices.findIndex(c => c.name === response.selected);
+    return selectedIndex >= 0 ? bids[selectedIndex] : null;
+  } catch (err) {
+    // User cancelled (Ctrl+C) or other error
+    return null;
+  }
+}
+
+/**
+ * Sort bids by quality score for better UX
+ *
+ * Sorts bids to show best options first:
+ * 1. Audited providers first
+ * 2. Higher uptime first
+ * 3. Lower price first (tie-breaker)
+ *
+ * This ensures users see the most reliable providers at the top,
+ * making selection easier.
+ *
+ * @param bids - Array of enhanced bids
+ * @returns Sorted array (does not mutate original)
+ *
+ * @example
+ * ```typescript
+ * const sortedBids = sortBidsByQuality(bids);
+ * const selected = await selectBidInteractively(sortedBids);
+ * ```
+ */
+export function sortBidsByQuality(bids: EnhancedBid[]): EnhancedBid[] {
+  return [...bids].sort((a, b) => {
+    // 1. Audited providers first
+    if (a.provider.isAudited && !b.provider.isAudited) return -1;
+    if (!a.provider.isAudited && b.provider.isAudited) return 1;
+
+    // 2. Higher uptime first (use 7d uptime)
+    const uptimeA = a.provider.reliability?.uptime7d ?? 0;
+    const uptimeB = b.provider.reliability?.uptime7d ?? 0;
+    if (uptimeA !== uptimeB) return uptimeB - uptimeA;
+
+    // 3. Lower price as tie-breaker
+    return a.pricing.uakt.perMonth - b.pricing.uakt.perMonth;
+  });
+}