free-coding-models 0.1.82 → 0.1.84

package/src/tier-colors.js

@@ -0,0 +1,37 @@
+/**
+ * @file tier-colors.js
+ * @description Chalk colour functions for each tier level, extracted from bin/free-coding-models.js.
+ *
+ * @details
+ *   The tier system maps model quality tiers (S+, S, A+, A, A-, B+, B, C) to a
+ *   green → yellow → orange → red gradient.  Keeping these colour definitions in their
+ *   own module allows the renderer, overlays, and any future CLI tools to share a
+ *   single, consistent visual language without depending on the whole TUI entry point.
+ *
+ *   The gradient is deliberately designed so that the higher the tier the more
+ *   "neon" and attention-grabbing the colour, while lower tiers fade toward dark red.
+ *   `chalk.rgb()` is used for fine-grained control — terminal 256-colour and truecolour
+ *   modes both support this; on terminals that don't, chalk gracefully degrades.
+ *
+ * @exports
+ *   TIER_COLOR — object mapping tier string → chalk colouring function
+ *
+ * @see src/constants.js   — TIER_CYCLE ordering that drives the T-key filter
+ * @see bin/free-coding-models.js — renderTable() uses TIER_COLOR per row
+ */
+
+import chalk from 'chalk'
+
+// 📖 Tier colors: green gradient (best) → yellow → orange → red (worst).
+// 📖 Uses chalk.rgb() for fine-grained color control across 8 tier levels.
+// 📖 Each entry is a function (t) => styled string so it can be applied to any text.
+export const TIER_COLOR = {
+  'S+': t => chalk.bold.rgb(0,   255,  80)(t),   // 🟢 bright neon green  — elite
+  'S':  t => chalk.bold.rgb(80,  220,   0)(t),   // 🟢 green              — excellent
+  'A+': t => chalk.bold.rgb(170, 210,   0)(t),   // 🟡 yellow-green       — great
+  'A':  t => chalk.bold.rgb(240, 190,   0)(t),   // 🟡 yellow             — good
+  'A-': t => chalk.bold.rgb(255, 130,   0)(t),   // 🟠 amber              — decent
+  'B+': t => chalk.bold.rgb(255,  70,   0)(t),   // 🟠 orange-red         — average
+  'B':  t => chalk.bold.rgb(210,  20,   0)(t),   // 🔴 red                — below avg
+  'C':  t => chalk.bold.rgb(140,   0,   0)(t),   // 🔴 dark red           — lightweight
+}

package/src/token-stats.js

@@ -0,0 +1,310 @@
+/**
+ * @file lib/token-stats.js
+ * @description Persistent token usage tracking for the multi-account proxy.
+ *
+ * Records per-account and per-model token usage, hourly/daily aggregates,
+ * an in-memory ring buffer of the 100 most-recent requests, and an
+ * append-only JSONL log file for detailed history.
+ *
+ * Quota snapshots are intentionally stored at two granularities:
+ * - byProviderModel: precise UI data for a specific Origin + model pair
+ * - byProvider: fallback when a provider exposes account-level remaining quota
+ *
+ * We still keep the legacy byModel aggregate for backward compatibility and
+ * debugging, but the TUI no longer trusts it for display because the same
+ * model ID can exist under multiple Origins with different limits.
+ *
+ * Storage locations:
+ *   ~/.free-coding-models/token-stats.json  — aggregated stats (auto-saved every 10 records)
+ *   ~/.free-coding-models/request-log.jsonl — timestamped per-request log (pruned after 30 days)
+ *
+ * @exports TokenStats
+ */
+
+import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const DEFAULT_DATA_DIR = join(homedir(), '.free-coding-models')
+const MAX_RING_BUFFER = 100
+const RETENTION_DAYS = 30
+
+function timestampToMillis(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string') {
+    const numeric = Number(value)
+    if (Number.isFinite(numeric)) return numeric
+    const parsed = Date.parse(value)
+    if (!Number.isNaN(parsed)) return parsed
+  }
+  return null
+}
+
+export class TokenStats {
+  /**
+   * @param {{ dataDir?: string }} [opts]
+   *   dataDir  — override the default ~/.free-coding-models directory (used in tests)
+   */
+  constructor({ dataDir } = {}) {
+    this._dataDir = dataDir || DEFAULT_DATA_DIR
+    this._statsFile = join(this._dataDir, 'token-stats.json')
+    this._logFile = join(this._dataDir, 'request-log.jsonl')
+    this._stats = {
+      byAccount: {},
+      byModel: {},
+      hourly: {},
+      daily: {},
+      quotaSnapshots: { byAccount: {}, byModel: {}, byProvider: {}, byProviderModel: {} },
+    }
+    this._ringBuffer = []
+    this._recordsSinceLastSave = 0
+    this._load()
+    setImmediate(() => this._pruneOldLogs())
+  }
+
+  _load() {
+    try {
+      mkdirSync(this._dataDir, { recursive: true })
+      if (existsSync(this._statsFile)) {
+        const loaded = JSON.parse(readFileSync(this._statsFile, 'utf8'))
+        this._stats = loaded
+      }
+    } catch { /* start fresh */ }
+    // Ensure quotaSnapshots always exists (backward compat for old files)
+    if (!this._stats.quotaSnapshots || typeof this._stats.quotaSnapshots !== 'object') {
+      this._stats.quotaSnapshots = { byAccount: {}, byModel: {}, byProvider: {}, byProviderModel: {} }
+    }
+    if (!this._stats.quotaSnapshots.byAccount) this._stats.quotaSnapshots.byAccount = {}
+    if (!this._stats.quotaSnapshots.byModel) this._stats.quotaSnapshots.byModel = {}
+    if (!this._stats.quotaSnapshots.byProvider) this._stats.quotaSnapshots.byProvider = {}
+    if (!this._stats.quotaSnapshots.byProviderModel) this._stats.quotaSnapshots.byProviderModel = {}
+  }
+
+  _pruneOldLogs() {
+    try {
+      if (!existsSync(this._logFile)) return
+      const cutoff = Date.now() - RETENTION_DAYS * 86400000
+      const lines = readFileSync(this._logFile, 'utf8').split('\n').filter(Boolean)
+      const kept = lines.filter(line => {
+        try {
+          const millis = timestampToMillis(JSON.parse(line).timestamp)
+          return millis !== null && millis >= cutoff
+        } catch {
+          return false
+        }
+      })
+      writeFileSync(this._logFile, kept.join('\n') + (kept.length ? '\n' : ''))
+    } catch { /* ignore */ }
+  }
+
+  /**
+   * Record a single request's token usage.
+   *
+   * @param {{ accountId: string, modelId: string, providerKey?: string, statusCode?: number|string, requestType?: string, promptTokens?: number, completionTokens?: number, latencyMs?: number, success?: boolean }} entry
+   */
+  record(entry) {
+    const {
+      accountId,
+      modelId,
+      providerKey = 'unknown',
+      statusCode = 200,
+      requestType = 'chat.completions',
+      promptTokens = 0,
+      completionTokens = 0,
+      latencyMs = 0,
+      success = true,
+    } = entry
+    const totalTokens = promptTokens + completionTokens
+    const now = new Date()
+    const hourKey = now.toISOString().slice(0, 13)
+    const dayKey = now.toISOString().slice(0, 10)
+
+    // By account
+    const acct = this._stats.byAccount[accountId] ||= { requests: 0, tokens: 0, errors: 0 }
+    acct.requests++
+    acct.tokens += totalTokens
+    if (!success) acct.errors++
+
+    // By model
+    const model = this._stats.byModel[modelId] ||= { requests: 0, tokens: 0 }
+    model.requests++
+    model.tokens += totalTokens
+
+    // Hourly
+    this._stats.hourly[hourKey] ||= { requests: 0, tokens: 0 }
+    this._stats.hourly[hourKey].requests++
+    this._stats.hourly[hourKey].tokens += totalTokens
+
+    // Daily
+    this._stats.daily[dayKey] ||= { requests: 0, tokens: 0 }
+    this._stats.daily[dayKey].requests++
+    this._stats.daily[dayKey].tokens += totalTokens
+
+    // Ring buffer (newest at end)
+    this._ringBuffer.push({ ...entry, timestamp: now.toISOString() })
+    if (this._ringBuffer.length > MAX_RING_BUFFER) this._ringBuffer.shift()
+
+    // JSONL log
+    try {
+      const logEntry = {
+        timestamp: now.toISOString(),
+        accountId,
+        modelId,
+        providerKey,
+        statusCode,
+        requestType,
+        promptTokens,
+        completionTokens,
+        latencyMs,
+        success,
+      }
+      appendFileSync(this._logFile, JSON.stringify(logEntry) + '\n')
+    } catch { /* ignore */ }
+
+    // Auto-save every 10 records
+    this._recordsSinceLastSave++
+    if (this._recordsSinceLastSave >= 10) this.save()
+  }
+
+  save() {
+    try {
+      mkdirSync(this._dataDir, { recursive: true })
+      writeFileSync(this._statsFile, JSON.stringify(this._stats, null, 2))
+      this._recordsSinceLastSave = 0
+    } catch { /* ignore */ }
+  }
+
+  /**
+   * Persist a quota snapshot for a single account.
+   * Also recomputes the per-model aggregate quota if modelId is provided.
+   * Tracks latest provider-level quota snapshot when providerKey is provided.
+   *
+   * Quota snapshots are lightweight (not per-request) and are written to
+   * token-stats.json immediately so the TUI can read them without waiting
+   * for the next 10-record auto-save cycle.
+   *
+   * @param {string} accountId
+   * @param {{ quotaPercent: number, providerKey?: string, modelId?: string, updatedAt?: string }} opts
+   */
+  updateQuotaSnapshot(accountId, { quotaPercent, providerKey, modelId, updatedAt } = {}) {
+    const previousSnap = this._stats.quotaSnapshots.byAccount[accountId]
+    const snap = {
+      quotaPercent,
+      updatedAt: updatedAt || new Date().toISOString(),
+    }
+    if (providerKey !== undefined) snap.providerKey = providerKey
+    if (modelId !== undefined) snap.modelId = modelId
+
+    this._stats.quotaSnapshots.byAccount[accountId] = snap
+
+    // 📖 Recompute the old aggregate buckets first when an account switches model/provider.
+    if (previousSnap?.modelId !== undefined) {
+      this._recomputeModelQuota(previousSnap.modelId)
+    }
+    if (previousSnap?.providerKey !== undefined && previousSnap?.modelId !== undefined) {
+      this._recomputeProviderModelQuota(previousSnap.providerKey, previousSnap.modelId)
+    }
+
+    if (modelId !== undefined) {
+      this._recomputeModelQuota(modelId)
+    }
+    if (providerKey !== undefined && modelId !== undefined) {
+      this._recomputeProviderModelQuota(providerKey, modelId)
+    }
+
+    if (providerKey !== undefined) {
+      this._stats.quotaSnapshots.byProvider[providerKey] = {
+        quotaPercent,
+        updatedAt: snap.updatedAt,
+      }
+    }
+
+    // Persist immediately (quota data must be fresh for TUI reads)
+    this.save()
+  }
+
+  /**
+   * Build a stable key for provider-scoped model quota snapshots.
+   *
+   * @param {string} providerKey
+   * @param {string} modelId
+   * @returns {string}
+   */
+  _providerModelKey(providerKey, modelId) {
+    return `${providerKey}::${modelId}`
+  }
+
+  /**
+   * Recompute the per-model quota snapshot by averaging all account snapshots
+   * that share the given modelId.
+   *
+   * @param {string} modelId
+   */
+  _recomputeModelQuota(modelId) {
+    const accountSnaps = Object.values(this._stats.quotaSnapshots.byAccount)
+      .filter(s => s.modelId === modelId)
+
+    if (accountSnaps.length === 0) {
+      delete this._stats.quotaSnapshots.byModel[modelId]
+      return
+    }
+
+    const avgPercent = Math.round(
+      accountSnaps.reduce((sum, s) => sum + s.quotaPercent, 0) / accountSnaps.length
+    )
+    const latestUpdatedAt = accountSnaps.reduce(
+      (latest, s) => (s.updatedAt > latest ? s.updatedAt : latest),
+      accountSnaps[0].updatedAt
+    )
+
+    this._stats.quotaSnapshots.byModel[modelId] = {
+      quotaPercent: avgPercent,
+      updatedAt: latestUpdatedAt,
+    }
+  }
+
+  /**
+   * Recompute the provider-scoped quota snapshot for one Origin + model pair.
+   * This is the canonical source used by the TUI Usage column.
+   *
+   * @param {string} providerKey
+   * @param {string} modelId
+   */
+  _recomputeProviderModelQuota(providerKey, modelId) {
+    const accountSnaps = Object.values(this._stats.quotaSnapshots.byAccount)
+      .filter((s) => s.providerKey === providerKey && s.modelId === modelId)
+
+    const key = this._providerModelKey(providerKey, modelId)
+    if (accountSnaps.length === 0) {
+      delete this._stats.quotaSnapshots.byProviderModel[key]
+      return
+    }
+
+    const avgPercent = Math.round(
+      accountSnaps.reduce((sum, s) => sum + s.quotaPercent, 0) / accountSnaps.length
+    )
+    const latestUpdatedAt = accountSnaps.reduce(
+      (latest, s) => (s.updatedAt > latest ? s.updatedAt : latest),
+      accountSnaps[0].updatedAt
+    )
+
+    this._stats.quotaSnapshots.byProviderModel[key] = {
+      quotaPercent: avgPercent,
+      updatedAt: latestUpdatedAt,
+      providerKey,
+      modelId,
+    }
+  }
+
+  /**
+   * Return a summary snapshot including the 10 most-recent requests.
+   *
+   * @returns {{ byAccount: object, byModel: object, hourly: object, daily: object, recentRequests: object[] }}
+   */
+  getSummary() {
+    return {
+      ...this._stats,
+      recentRequests: this._ringBuffer.slice(-10),
+    }
+  }
+}

package/src/token-usage-reader.js

@@ -0,0 +1,63 @@
+/**
+ * @file token-usage-reader.js
+ * @description Reads historical token usage from request-log.jsonl and aggregates it by exact provider + model pair.
+ *
+ * @details
+ *   The TUI already shows live latency and quota state, but that does not tell
+ *   you how much you've actually consumed on a given Origin. This module reads
+ *   the persistent JSONL request log once at startup and builds a compact
+ *   `provider::model -> totalTokens` map for table display.
+ *
+ *   Why this exists:
+ *   - `token-stats.json` keeps convenience aggregates, but not the exact
+ *     provider+model sum needed for the new table column.
+ *   - `request-log.jsonl` is the source of truth because every proxied request
+ *     records prompt and completion token counts with provider context.
+ *   - Startup-only parsing keeps runtime overhead negligible during TUI redraws.
+ *
+ * @functions
+ *   → `buildProviderModelTokenKey` — creates a stable aggregation key
+ *   → `loadTokenUsageByProviderModel` — reads request-log.jsonl and returns total tokens by provider+model
+ *   → `formatTokenTotalCompact` — renders totals as integer K / M strings for narrow columns
+ *
+ * @exports buildProviderModelTokenKey, loadTokenUsageByProviderModel, formatTokenTotalCompact
+ *
+ * @see src/log-reader.js
+ * @see src/render-table.js
+ */
+
+import { loadRecentLogs } from './log-reader.js'
+
+// 📖 buildProviderModelTokenKey keeps provider-scoped totals isolated even when
+// 📖 multiple Origins expose the same model ID.
+export function buildProviderModelTokenKey(providerKey, modelId) {
+  return `${providerKey}::${modelId}`
+}
+
+// 📖 loadTokenUsageByProviderModel reads the full bounded log history available
+// 📖 through log-reader and sums tokens per exact provider+model pair.
+export function loadTokenUsageByProviderModel({ logFile, limit = 50_000 } = {}) {
+  const rows = loadRecentLogs({ logFile, limit })
+  const totals = {}
+
+  for (const row of rows) {
+    const providerKey = typeof row.provider === 'string' ? row.provider : 'unknown'
+    const modelId = typeof row.model === 'string' ? row.model : 'unknown'
+    const tokens = Number(row.tokens) || 0
+    if (tokens <= 0) continue
+
+    const key = buildProviderModelTokenKey(providerKey, modelId)
+    totals[key] = (totals[key] || 0) + tokens
+  }
+
+  return totals
+}
+
+// 📖 formatTokenTotalCompact keeps the new column narrow and scannable:
+// 📖 0-999 => raw integer, 1k-999k => Nk, 1m+ => NM, no decimals.
+export function formatTokenTotalCompact(totalTokens) {
+  const safeTotal = Number(totalTokens) || 0
+  if (safeTotal >= 1_000_000) return `${Math.floor(safeTotal / 1_000_000)}M`
+  if (safeTotal >= 1_000) return `${Math.floor(safeTotal / 1_000)}k`
+  return String(Math.floor(safeTotal))
+}

package/src/updater.js

@@ -0,0 +1,237 @@
+/**
+ * @file updater.js
+ * @description Update detection and installation helpers, extracted from bin/free-coding-models.js.
+ *
+ * @details
+ *   This module handles all npm version-check and auto-update logic:
+ *
+ *   - `checkForUpdateDetailed()` — hits the npm registry to compare the published version
+ *     against the locally installed one.  Returns `{ latestVersion, error }` so callers
+ *     can surface meaningful status text in the Settings overlay.
+ *
+ *   - `checkForUpdate()` — thin backward-compatible wrapper used at startup for the
+ *     auto-update guard.  Returns `latestVersion` (string) or `null`.
+ *
+ *   - `runUpdate(latestVersion)` — runs `npm i -g free-coding-models@<version> --prefer-online`,
+ *     retrying with `sudo` on EACCES/EPERM.  On success, relaunches the process with the
+ *     same argv.  On failure, prints manual instructions and exits with code 1.
+ *     Uses `require('child_process').execSync` inline because ESM dynamic import is async
+ *     but `execSync` must block to give `stdio: 'inherit'` feedback in the terminal.
+ *
+ *   - `promptUpdateNotification(latestVersion)` — renders a small centered interactive menu
+ *     that lets the user choose: Update Now / Read Changelogs / Continue without update.
+ *     Uses raw mode readline keypress events (same pattern as the main TUI).
+ *     This function is called BEFORE the alt-screen is entered, so it writes to the
+ *     normal terminal buffer.
+ *
+ *   ⚙️ Notes:
+ *   - `LOCAL_VERSION` is resolved from package.json via `createRequire` so this module
+ *     can be imported independently from the bin entry point.
+ *   - The auto-update flow in `main()` skips update if `isDevMode` is detected (presence of
+ *     a `.git` directory next to the package root) to avoid an infinite update loop in dev.
+ *
+ * @functions
+ *   → checkForUpdateDetailed()           — Fetch npm latest with explicit error info
+ *   → checkForUpdate()                   — Startup wrapper, returns version string or null
+ *   → runUpdate(latestVersion)           — Install new version via npm global + relaunch
+ *   → promptUpdateNotification(version)  — Interactive pre-TUI update menu
+ *
+ * @exports
+ *   checkForUpdateDetailed, checkForUpdate, runUpdate, promptUpdateNotification
+ *
+ * @see bin/free-coding-models.js — calls checkForUpdate() at startup and runUpdate() on confirm
+ */
+
+import chalk from 'chalk'
+import { createRequire } from 'module'
+
+const require = createRequire(import.meta.url)
+const readline = require('readline')
+const pkg = require('../package.json')
+const LOCAL_VERSION = pkg.version
+
+/**
+ * 📖 checkForUpdateDetailed: Fetch npm latest version with explicit error details.
+ * 📖 Used by settings manual-check flow to display meaningful status in the UI.
+ * @returns {Promise<{ latestVersion: string|null, error: string|null }>}
+ */
+export async function checkForUpdateDetailed() {
+  try {
+    const res = await fetch('https://registry.npmjs.org/free-coding-models/latest', { signal: AbortSignal.timeout(5000) })
+    if (!res.ok) return { latestVersion: null, error: `HTTP ${res.status}` }
+    const data = await res.json()
+    if (data.version && data.version !== LOCAL_VERSION) return { latestVersion: data.version, error: null }
+    return { latestVersion: null, error: null }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error'
+    return { latestVersion: null, error: message }
+  }
+}
+
+/**
+ * 📖 checkForUpdate: Backward-compatible wrapper for startup update prompt.
+ * @returns {Promise<string|null>}
+ */
+export async function checkForUpdate() {
+  const { latestVersion } = await checkForUpdateDetailed()
+  return latestVersion
+}
+
+/**
+ * 📖 runUpdate: Run npm global install to update to latestVersion.
+ * 📖 Retries with sudo on permission errors.
+ * 📖 Relaunches the process on success, exits with code 1 on failure.
+ * @param {string} latestVersion
+ */
+export function runUpdate(latestVersion) {
+  const { execSync } = require('child_process')
+  console.log()
+  console.log(chalk.bold.cyan('  ⬆ Updating free-coding-models to v' + latestVersion + '...'))
+  console.log()
+
+  try {
+    // 📖 Force install from npm registry (ignore local cache)
+    // 📖 Use --prefer-online to ensure we get the latest published version
+    execSync(`npm i -g free-coding-models@${latestVersion} --prefer-online`, { stdio: 'inherit' })
+    console.log()
+    console.log(chalk.green('  ✅ Update complete! Version ' + latestVersion + ' installed.'))
+    console.log()
+    console.log(chalk.dim('  🔄 Restarting with new version...'))
+    console.log()
+
+    // 📖 Relaunch automatically with the same arguments
+    const args = process.argv.slice(2)
+    execSync(`node ${process.argv[1]} ${args.join(' ')}`, { stdio: 'inherit' })
+    process.exit(0)
+  } catch (err) {
+    console.log()
+    // 📖 Check if error is permission-related (EACCES or EPERM)
+    const isPermissionError = err.code === 'EACCES' || err.code === 'EPERM' ||
+                             (err.stderr && (err.stderr.includes('EACCES') || err.stderr.includes('permission') ||
+                                              err.stderr.includes('EACCES'))) ||
+                             (err.message && (err.message.includes('EACCES') || err.message.includes('permission')))
+
+    if (isPermissionError) {
+      console.log(chalk.yellow('  ⚠️ Permission denied. Retrying with sudo...'))
+      console.log()
+      try {
+        execSync(`sudo npm i -g free-coding-models@${latestVersion} --prefer-online`, { stdio: 'inherit' })
+        console.log()
+        console.log(chalk.green('  ✅ Update complete with sudo! Version ' + latestVersion + ' installed.'))
+        console.log()
+        console.log(chalk.dim('  🔄 Restarting with new version...'))
+        console.log()
+
+        // 📖 Relaunch automatically with the same arguments
+        const args = process.argv.slice(2)
+        execSync(`node ${process.argv[1]} ${args.join(' ')}`, { stdio: 'inherit' })
+        process.exit(0)
+      } catch (sudoErr) {
+        console.log()
+        console.log(chalk.red('  ✖ Update failed even with sudo. Try manually:'))
+        console.log(chalk.dim('    sudo npm i -g free-coding-models@' + latestVersion))
+        console.log()
+      }
+    } else {
+      console.log(chalk.red('  ✖ Update failed. Try manually: npm i -g free-coding-models@' + latestVersion))
+      console.log()
+    }
+  }
+  process.exit(1)
+}
+
+/**
+ * 📖 promptUpdateNotification: Show a centered interactive menu when a new version is available.
+ * 📖 Returns 'update', 'changelogs', or null (continue without update).
+ * 📖 Called BEFORE entering the alt-screen so it renders in the normal terminal buffer.
+ * @param {string|null} latestVersion
+ * @returns {Promise<'update'|'changelogs'|null>}
+ */
+export async function promptUpdateNotification(latestVersion) {
+  if (!latestVersion) return null
+
+  return new Promise((resolve) => {
+    let selected = 0
+    const options = [
+      {
+        label: 'Update now',
+        icon: '⬆',
+        description: `Update free-coding-models to v${latestVersion}`,
+      },
+      {
+        label: 'Read Changelogs',
+        icon: '📋',
+        description: 'Open GitHub changelog',
+      },
+      {
+        label: 'Continue without update',
+        icon: '▶',
+        description: 'Use current version',
+      },
+    ]
+
+    // 📖 Centered render function
+    const render = () => {
+      process.stdout.write('\x1b[2J\x1b[H') // clear screen + cursor home
+
+      // 📖 Calculate centering
+      const terminalWidth = process.stdout.columns || 80
+      const maxWidth = Math.min(terminalWidth - 4, 70)
+      const centerPad = ' '.repeat(Math.max(0, Math.floor((terminalWidth - maxWidth) / 2)))
+
+      console.log()
+      console.log(centerPad + chalk.bold.red('  ⚠ UPDATE AVAILABLE'))
+      console.log(centerPad + chalk.red(`  Version ${latestVersion} is ready to install`))
+      console.log()
+      console.log(centerPad + chalk.bold('  ⚡ Free Coding Models') + chalk.dim(` v${LOCAL_VERSION}`))
+      console.log()
+
+      for (let i = 0; i < options.length; i++) {
+        const isSelected = i === selected
+        const bullet = isSelected ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
+        const label = isSelected
+          ? chalk.bold.white(options[i].icon + ' ' + options[i].label)
+          : chalk.dim(options[i].icon + ' ' + options[i].label)
+
+        console.log(centerPad + bullet + label)
+        console.log(centerPad + chalk.dim('       ' + options[i].description))
+        console.log()
+      }
+
+      console.log(centerPad + chalk.dim('  ↑↓ Navigate  •  Enter Select  •  Ctrl+C Continue'))
+      console.log()
+    }
+
+    render()
+
+    readline.emitKeypressEvents(process.stdin)
+    if (process.stdin.isTTY) process.stdin.setRawMode(true)
+
+    const onKey = (_str, key) => {
+      if (!key) return
+      if (key.ctrl && key.name === 'c') {
+        if (process.stdin.isTTY) process.stdin.setRawMode(false)
+        process.stdin.removeListener('keypress', onKey)
+        resolve(null) // Continue without update
+        return
+      }
+      if (key.name === 'up' && selected > 0) {
+        selected--
+        render()
+      } else if (key.name === 'down' && selected < options.length - 1) {
+        selected++
+        render()
+      } else if (key.name === 'return') {
+        if (process.stdin.isTTY) process.stdin.setRawMode(false)
+        process.stdin.removeListener('keypress', onKey)
+        process.stdin.pause()
+
+        if (selected === 0) resolve('update')
+        else if (selected === 1) resolve('changelogs')
+        else resolve(null) // Continue without update
+      }
+    }
+
+    process.stdin.on('keypress', onKey)
+  })
+}