free-coding-models 0.5.4 → 0.5.5

package/bin/free-coding-models.js

@@ -11,11 +11,12 @@ if (process.argv.includes('--dev')) {
 
 import chalk from 'chalk';
 import { parseArgs, TIER_LETTER_MAP } from '../src/core/utils.js';
-import { loadConfig } from '../src/core/config.js';
+import { loadConfig, saveConfig } from '../src/core/config.js';
 import { ensureTelemetryConfig } from '../src/core/telemetry.js';
 import { ensureFavoritesConfig } from '../src/core/favorites.js';
 import { buildCliHelpText } from '../src/tui/cli-help.js';
 import { ALT_LEAVE } from '../src/core/constants.js';
+import { enforceMandatoryStartupUpdate, isPackageDevMode } from '../src/core/updater.js';
 import { runApp } from '../src/tui/app.js';
 
 // Global error handlers to ensure terminal is restored if something crashes catastrophically
@@ -53,13 +54,32 @@ async function main() {
     process.exit(0);
   }
 
+  // Load JSON config before operational modes so the mandatory update policy can
+  // 📖 persist failure counters for TUI, Web Dashboard, Docker daemon, and Desktop sidecar launches.
+  const config = loadConfig();
+  ensureTelemetryConfig(config);
+  ensureFavoritesConfig(config);
+
+  const isDevMode = isPackageDevMode();
+  const shouldEnforceUpdate = !cliArgs.daemonStopMode && !cliArgs.daemonStatusMode;
+  const startupUpdate = shouldEnforceUpdate
+    ? await enforceMandatoryStartupUpdate(config, {
+      saveConfig,
+      isDevMode,
+      surface: cliArgs.webMode ? 'web dashboard' : cliArgs.daemonMode ? 'router daemon' : 'TUI',
+    })
+    : { latestVersion: null, allowedOutdated: false, warningMessage: null, failures: 0, checked: false, updated: false, blocked: false };
+
+  if (startupUpdate.updated) return;
+  if (startupUpdate.blocked) process.exit(1);
+
   // 📖 Standalone web dashboard: same full-catalog ping UI as the TUI, served
   // 📖 locally with Socket.IO/SSE/REST realtime updates.
   if (cliArgs.webMode) {
     const { startWebServer } = await import('../web/server.js');
     const parsedPort = Number.parseInt(process.env.FCM_WEB_PORT || process.env.FCM_PORT || '3333', 10);
     const port = Number.isFinite(parsedPort) && parsedPort > 0 ? parsedPort : 3333;
-    await startWebServer(port, { open: true, startPingLoop: true });
+    await startWebServer(port, { open: true, startPingLoop: true, updateStatus: startupUpdate });
     return;
   }
 
@@ -102,12 +122,7 @@ async function main() {
     process.exit(1);
   }
 
-  // Load JSON config
-  const config = loadConfig();
-  ensureTelemetryConfig(config);
-  ensureFavoritesConfig(config);
-
-  await runApp(cliArgs, config);
+  await runApp(cliArgs, config, { startupUpdate, isDevMode });
 }
 
 main().catch((err) => {

package/changelog/v0.5.5.md

@@ -0,0 +1,15 @@
+# Changelog v0.5.5 - 2026-06-01
+
+### Changed
+- ⬆️ **deps-dev**: bump `vite` from `8.0.14` → `8.0.16` (#105)
+- ⬆️ **deps-dev**: bump `vite-plus` from `0.1.20` → `0.1.23` (#106)
+- ⬆️ **deps-dev**: bump `@vitejs/plugin-react` from `6.0.1` → `6.0.2` (#107)
+
+### CI
+- ⬆️ bump `docker/setup-buildx-action` from `3` → `4` (#104)
+- ⬆️ bump `docker/login-action` from `3` → `4` (#103)
+- ⬆️ bump `pnpm/action-setup` from `4` → `6` (#102)
+
+### Notes
+- All 6 dependabot PRs merged in a single batch with conflict resolution on `pnpm-lock.yaml`.
+- 440/440 tests passing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "Find the fastest coding LLM models in seconds — ping free models from multiple providers, pick the best one for OpenCode, Cursor, or any AI coding assistant.",
   "keywords": [
     "nvidia",

package/src/core/updater.js

@@ -32,22 +32,29 @@
  *   → getManualInstallCmd(pm, version)   — Human-readable install command string for error messages
  *   → checkForUpdateDetailed()           — Fetch npm latest with explicit error info
  *   → checkForUpdate()                   — Startup wrapper, returns version string or null
+ *   → isPackageDevMode()                 — Detect git/dev checkouts that must not self-update
+ *   → enforceMandatoryStartupUpdate()    — Mandatory startup self-update with two-failure fallback
  *   → runUpdate(latestVersion)           — Install new version via detected PM + relaunch
  * @exports
  *   detectPackageManager, getInstallArgs, getManualInstallCmd,
- *   checkForUpdateDetailed, checkForUpdate, runUpdate, fetchLastReleaseDate
+ *   checkForUpdateDetailed, checkForUpdate, isPackageDevMode,
+ *   enforceMandatoryStartupUpdate, runUpdate, fetchLastReleaseDate
  *
  * @see bin/free-coding-models.js — calls checkForUpdate() at startup and runUpdate() on confirm
  */
 
 import chalk from 'chalk'
 import { createRequire } from 'module'
-import { accessSync, constants } from 'fs'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+import { accessSync, constants, existsSync } from 'fs'
 
 const require = createRequire(import.meta.url)
 const readline = require('readline')
 const pkg = require('../../package.json')
 const LOCAL_VERSION = pkg.version
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..')
+export const UPDATE_FAILURE_THRESHOLD = 2
 
 /**
  * 📖 detectPackageManager: figure out which package manager owns the current installation.
@@ -65,6 +72,70 @@ export function detectPackageManager() {
   return 'npm'
 }
 
+/**
+ * 📖 isPackageDevMode: true for repo checkouts and explicit --dev runs.
+ * 📖 Self-updating a git checkout creates noisy loops during local development,
+ * 📖 while published npm installs do not ship a .git directory and can update safely.
+ * @returns {boolean}
+ */
+export function isPackageDevMode() {
+  return process.env.FCM_DEV === '1' || existsSync(join(PACKAGE_ROOT, '.git'))
+}
+
+/**
+ * 📖 getUpdateInstallFailureCount: sanitized persistent failure counter.
+ * @param {object} config
+ * @returns {number}
+ */
+export function getUpdateInstallFailureCount(config) {
+  const raw = Number(config?.settings?.updateInstallFailures || 0)
+  if (!Number.isFinite(raw) || raw < 0) return 0
+  return Math.floor(raw)
+}
+
+function ensureUpdateSettings(config) {
+  if (!config.settings || typeof config.settings !== 'object') config.settings = {}
+  return config.settings
+}
+
+function persistUpdateSettings(config, saveConfig) {
+  if (typeof saveConfig !== 'function') return
+  try { saveConfig(config) } catch {}
+}
+
+function resetUpdateInstallFailures(config, saveConfig) {
+  const settings = ensureUpdateSettings(config)
+  if (!settings.updateInstallFailures && !settings.updateLastFailureAt && !settings.updateLastFailureMessage) return
+  settings.updateInstallFailures = 0
+  delete settings.updateLastFailureAt
+  delete settings.updateLastFailureMessage
+  delete settings.updateInstallFailureVersion
+  persistUpdateSettings(config, saveConfig)
+}
+
+function recordUpdateInstallFailure(config, latestVersion, error, saveConfig) {
+  const settings = ensureUpdateSettings(config)
+  const nextFailures = Math.min(getUpdateInstallFailureCount(config) + 1, UPDATE_FAILURE_THRESHOLD)
+  settings.updateInstallFailures = nextFailures
+  settings.updateInstallFailureVersion = latestVersion
+  settings.updateLastFailureAt = new Date().toISOString()
+  settings.updateLastFailureMessage = error instanceof Error ? error.message : String(error || 'Unknown update error')
+  persistUpdateSettings(config, saveConfig)
+  return nextFailures
+}
+
+/**
+ * 📖 buildOutdatedWarningMessage: one-line message shown when mandatory updates
+ * 📖 failed twice and FCM must let the UI start instead of trapping the user.
+ * @param {string|null} latestVersion
+ * @param {number} failures
+ * @returns {string}
+ */
+export function buildOutdatedWarningMessage(latestVersion, failures = UPDATE_FAILURE_THRESHOLD) {
+  const target = latestVersion ? `v${LOCAL_VERSION} → v${latestVersion}` : `v${LOCAL_VERSION}`
+  return `⚠️ OUTDATED VERSION (${target}) — automatic update failed ${failures} times. Models and free quotas change often; update as soon as possible for the freshest catalog.`
+}
+
 /**
  * 📖 getInstallArgs: return the correct binary and argument list for a given PM.
  * 📖 Each PM has different syntax for global install — this normalises them.
@@ -120,6 +191,89 @@ export async function checkForUpdate() {
   return latestVersion
 }
 
+/**
+ * 📖 enforceMandatoryStartupUpdate: startup policy for every user-facing surface.
+ * 📖 If npm has a newer release, FCM installs it immediately without asking.
+ * 📖 The first failed install blocks startup so the next launch retries. After two
+ * 📖 consecutive install failures, startup is allowed with a loud outdated warning
+ * 📖 so offline/proxy/permission users are not permanently locked out.
+ *
+ * @param {object} config
+ * @param {{ saveConfig?: Function, isDevMode?: boolean, surface?: string }} [options]
+ * @returns {Promise<{ latestVersion: string|null, allowedOutdated: boolean, warningMessage: string|null, failures: number, checked: boolean, updated: boolean, blocked: boolean }>}
+ */
+export async function enforceMandatoryStartupUpdate(config, options = {}) {
+  const { saveConfig, surface = 'app' } = options
+  const devMode = typeof options.isDevMode === 'boolean' ? options.isDevMode : isPackageDevMode()
+  const base = {
+    latestVersion: null,
+    allowedOutdated: false,
+    warningMessage: null,
+    failures: getUpdateInstallFailureCount(config),
+    checked: false,
+    updated: false,
+    blocked: false,
+  }
+
+  if (devMode) return base
+
+  const { latestVersion, error } = await checkForUpdateDetailed()
+  base.checked = true
+
+  if (error) {
+    const settings = ensureUpdateSettings(config)
+    settings.updateCheckFailures = Math.min(Number(settings.updateCheckFailures || 0) + 1, UPDATE_FAILURE_THRESHOLD)
+    persistUpdateSettings(config, saveConfig)
+    return base
+  }
+
+  const settings = ensureUpdateSettings(config)
+  if (settings.updateCheckFailures) {
+    settings.updateCheckFailures = 0
+    persistUpdateSettings(config, saveConfig)
+  }
+
+  if (!latestVersion) {
+    resetUpdateInstallFailures(config, saveConfig)
+    return base
+  }
+
+  base.latestVersion = latestVersion
+  const failuresBeforeInstall = getUpdateInstallFailureCount(config)
+  if (failuresBeforeInstall >= UPDATE_FAILURE_THRESHOLD) {
+    base.allowedOutdated = true
+    base.failures = failuresBeforeInstall
+    base.warningMessage = buildOutdatedWarningMessage(latestVersion, failuresBeforeInstall)
+    return base
+  }
+
+  console.log(chalk.dim(`  ⬆ New version v${latestVersion} detected for ${surface}; updating automatically...`))
+  const updateResult = runUpdate(latestVersion, { exitOnFailure: false })
+  if (updateResult?.ok) {
+    resetUpdateInstallFailures(config, saveConfig)
+    base.updated = true
+    return base
+  }
+
+  const failures = recordUpdateInstallFailure(config, latestVersion, updateResult?.error, saveConfig)
+  base.failures = failures
+
+  if (failures >= UPDATE_FAILURE_THRESHOLD) {
+    base.allowedOutdated = true
+    base.warningMessage = buildOutdatedWarningMessage(latestVersion, failures)
+    console.log(chalk.red(`  ${base.warningMessage}`))
+    console.log(chalk.dim(`  Manual update: ${getManualInstallCmd(detectPackageManager(), latestVersion)}`))
+    console.log()
+    return base
+  }
+
+  base.blocked = true
+  console.log(chalk.red('  ✖ Mandatory update failed. FCM will retry on the next launch.'))
+  console.log(chalk.dim(`  Attempt ${failures}/${UPDATE_FAILURE_THRESHOLD}. Manual update: ${getManualInstallCmd(detectPackageManager(), latestVersion)}`))
+  console.log()
+  return base
+}
+
 /**
  * 📖 fetchLastReleaseDate: Get the human-readable publish date of the latest npm release.
  * 📖 Used in the TUI footer to show users how fresh the package is.
@@ -265,10 +419,15 @@ function installUpdateCommand(latestVersion, useSudo) {
 /**
  * 📖 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.
+ * 📖 Relaunches the process on success. Manual update actions keep the historic
+ * 📖 behavior and exit on failure; mandatory startup checks pass exitOnFailure=false
+ * 📖 so they can persist failure counters and decide whether to let the UI start.
  * @param {string} latestVersion
+ * @param {{ exitOnFailure?: boolean, relaunchOnSuccess?: boolean }} [options]
+ * @returns {{ ok: boolean, error?: unknown }}
  */
-export function runUpdate(latestVersion) {
+export function runUpdate(latestVersion, options = {}) {
+  const { exitOnFailure = true, relaunchOnSuccess = true } = options
   console.log()
   console.log(chalk.bold.cyan('  ⬆ Updating free-coding-models to v' + latestVersion + '...'))
   console.log()
@@ -276,6 +435,7 @@ export function runUpdate(latestVersion) {
   const pm = detectPackageManager()
   const { needsSudo, checkedPath } = detectGlobalInstallPermission(pm)
   const sudoAvailable = process.platform !== 'win32' && hasSudoCommand()
+  let lastError = null
 
   if (needsSudo && checkedPath && sudoAvailable) {
     console.log(chalk.yellow(`  ⚠ Global ${pm} path is not writable: ${checkedPath}`))
@@ -288,9 +448,10 @@ export function runUpdate(latestVersion) {
     console.log()
     console.log(chalk.green(`  ✅ Update complete! Version ${latestVersion} installed.`))
     console.log()
-    relaunchCurrentProcess()
-    return
+    if (relaunchOnSuccess) relaunchCurrentProcess()
+    return { ok: true }
   } catch (err) {
+    lastError = err
     const manualCmd = getManualInstallCmd(pm, latestVersion)
     console.log()
     if (isPermissionError(err) && !needsSudo && sudoAvailable) {
@@ -301,9 +462,10 @@ export function runUpdate(latestVersion) {
         console.log()
         console.log(chalk.green(`  ✅ Update complete with sudo! Version ${latestVersion} installed.`))
         console.log()
-        relaunchCurrentProcess()
-        return
-      } catch {
+        if (relaunchOnSuccess) relaunchCurrentProcess()
+        return { ok: true }
+      } catch (sudoErr) {
+        lastError = sudoErr
         console.log()
         console.log(chalk.red('  ✖ Update failed even with sudo. Try manually:'))
         console.log(chalk.dim(`    sudo ${manualCmd}`))
@@ -318,7 +480,9 @@ export function runUpdate(latestVersion) {
       console.log()
     }
   }
-  process.exit(1)
+
+  if (exitOnFailure) process.exit(1)
+  return { ok: false, error: lastError }
 }
 
 

package/src/tui/app.js

@@ -91,11 +91,7 @@
 
 import chalk from 'chalk'
 import { createRequire } from 'module'
-import { fileURLToPath } from 'url'
-import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from 'fs'
 import { randomUUID } from 'crypto'
-import { homedir } from 'os'
-import { join, dirname } from 'path'
 import { MODELS, sources } from '../../sources.js'
 import { getAvg, getVerdict, getUptime, getP95, getJitter, getStabilityScore, sortResults, filterByTier, findBestModel, parseArgs, TIER_ORDER, VERDICT_ORDER, TIER_LETTER_MAP, scoreModelForTask, getTopRecommendations, TASK_TYPES, PRIORITY_TYPES, CONTEXT_BUDGETS, formatCtxWindow, labelFromId, formatResultsAsJSON } from '../core/utils.js'
 import { loadConfig, saveConfig, getApiKey, resolveApiKeys, addApiKey, removeApiKey, isProviderEnabled, persistApiKeysForProvider } from '../core/config.js'
@@ -181,7 +177,7 @@ const LOCAL_VERSION = pkg.version
 // ─── OpenCode integration ──────────────────────────────────────────────────────
 // 📖 OpenCode helpers are imported from ../src/opencode.js
 
-export async function runApp(cliArgs, config) {
+export async function runApp(cliArgs, config, startupOptions = {}) {
 
   // 📖 Detect user active terminal theme
   detectActiveTheme(config.settings?.theme || 'auto')
@@ -278,32 +274,12 @@ export async function runApp(cliArgs, config) {
     },
   })
 
-  // 📖 Auto-update detection: check npm registry for new versions at startup.
-  // 📖 If a new version is available, show an interactive prompt (Update / Changelogs / Skip).
-  // 📖 Dev mode (git checkout) skips auto-update to avoid infinite relaunch loops.
-  let latestVersion = null
-  const isDevMode = existsSync(join(dirname(fileURLToPath(import.meta.url)), '..', '.git'))
-  try {
-    latestVersion = await checkForUpdate()
-    // 📖 Reset failure counter on successful check
-    if (config.settings?.updateCheckFailures) {
-      config.settings.updateCheckFailures = 0
-      saveConfig(config)
-    }
-  } catch (err) {
-    const failures = (config.settings?.updateCheckFailures || 0) + 1
-    if (!config.settings) config.settings = {}
-    config.settings.updateCheckFailures = Math.min(failures, 3)
-    saveConfig(config)
-  }
-
-  // 📖 Auto-update: if a new version is available, install it immediately (skip in dev mode)
-  // 📖 runUpdate() will relaunch the process with the new version after install completes
-  if (latestVersion && !isDevMode) {
-    console.log(chalk.dim(`  ⬆ New version v${latestVersion} detected, updating...`))
-    runUpdate(latestVersion)
-    return // 📖 runUpdate relaunches the process — this line is a safety guard
-  }
+  // 📖 Mandatory startup update is enforced in the bin entry before any user-facing
+  // 📖 surface starts. runApp receives the result so the TUI can display the
+  // 📖 two-failure fallback warning without repeating npm registry/install work.
+  const startupUpdate = startupOptions.startupUpdate || {}
+  const latestVersion = startupUpdate.latestVersion || null
+  const isDevMode = startupOptions.isDevMode === true
 
   // 📖 Dynamic OpenRouter free model discovery — fetch live free models from API
   // 📖 Replaces static openrouter entries in MODELS with fresh data.
@@ -363,6 +339,8 @@ export async function runApp(cliArgs, config) {
     sessionId,
     latestVersion,
     isDevMode,
+    updateWarningMessage: startupUpdate.warningMessage || null,
+    updateInstallFailures: startupUpdate.failures || 0,
   })
 
   // 📖 Apply the pre-fetched last release date now that state is initialized
@@ -823,6 +801,7 @@ export async function runApp(cliArgs, config) {
       settingsUpdateLatestVersion: state.settingsUpdateLatestVersion,
       startupLatestVersion: state.startupLatestVersion,
       versionAlertsEnabled: state.versionAlertsEnabled,
+      updateWarningMessage: state.updateWarningMessage,
       favoritesPinnedAndSticky: state.favoritesPinnedAndSticky,
       customTextFilter: state.customTextFilter,
       lastReleaseDate: state.lastReleaseDate,
@@ -914,6 +893,7 @@ export async function runApp(cliArgs, config) {
     settingsUpdateLatestVersion: state.settingsUpdateLatestVersion,
     startupLatestVersion: state.startupLatestVersion,
     versionAlertsEnabled: state.versionAlertsEnabled,
+    updateWarningMessage: state.updateWarningMessage,
     favoritesPinnedAndSticky: state.favoritesPinnedAndSticky,
     customTextFilter: state.customTextFilter,
     lastReleaseDate: state.lastReleaseDate,

package/src/tui/render-table.js

@@ -136,6 +136,7 @@ export const PROVIDER_COLOR = new Proxy({}, {
  *   settingsUpdateLatestVersion: string|null,
  *   startupLatestVersion: string|null,
  *   versionAlertsEnabled: boolean,
+ *   updateWarningMessage?: string|null,
  *   favoritesPinnedAndSticky: boolean,
  *   customTextFilter: string|null,
  *   lastReleaseDate: string|null,
@@ -174,6 +175,7 @@ export function renderTable({
   settingsUpdateLatestVersion = null,
   startupLatestVersion = null,
   versionAlertsEnabled = true,
+  updateWarningMessage = null,
   favoritesPinnedAndSticky = false,
   customTextFilter = null,
   lastReleaseDate = null,
@@ -1073,15 +1075,19 @@ export function renderTable({
   )
 
   if (versionStatus.isOutdated) {
-    const updateMsg = `  🚀⬆️ UPDATE AVAILABLE — v${LOCAL_VERSION} → v${versionStatus.latestVersion}  •  Click here or press Shift+U to update  🚀⬆️  `
+    const updateMsg = updateWarningMessage
+      ? `  ${updateWarningMessage}  •  Press Shift+U to retry update  `
+      : `  🚀⬆️ UPDATE AVAILABLE — v${LOCAL_VERSION} → v${versionStatus.latestVersion}  •  Click here or press Shift+U to update  🚀⬆️  `
     const paddedBanner = terminalCols > 0
       ? updateMsg + ' '.repeat(Math.max(0, terminalCols - displayWidth(updateMsg)))
       : updateMsg
-    const fluoGreenBanner = chalk.bgRgb(57, 255, 20).rgb(0, 0, 0).bold(paddedBanner)
+    const updateBanner = updateWarningMessage
+      ? chalk.bgRed.white.bold(paddedBanner)
+      : chalk.bgRgb(57, 255, 20).rgb(0, 0, 0).bold(paddedBanner)
     const updateBannerRow = lines.length + 1
     _lastLayout.updateBannerRow = updateBannerRow
     footerHotkeys.push({ key: 'update-click', row: updateBannerRow, xStart: 1, xEnd: Math.max(terminalCols, displayWidth(updateMsg)) })
-    lines.push(fluoGreenBanner)
+    lines.push(updateBanner)
   } else {
     _lastLayout.updateBannerRow = 0
   }

package/src/tui/tui-state.js

@@ -70,6 +70,8 @@ export function intervalToPingMode(intervalMs) {
  *   sessionId: string,
  *   latestVersion: string|null,
  *   isDevMode: boolean,
+ *   updateWarningMessage?: string|null,
+ *   updateInstallFailures?: number,
  * }} opts
  * @returns {object} The complete TUI state (mutable)
  */
@@ -80,6 +82,8 @@ export function createTuiState({
   sessionId,
   latestVersion,
   isDevMode,
+  updateWarningMessage = null,
+  updateInstallFailures = 0,
 }) {
   const now = Date.now()
 
@@ -110,6 +114,8 @@ export function createTuiState({
 
     // 📖 Version tracking — startup auto-check + periodic re-check
     startupLatestVersion: latestVersion,
+    updateWarningMessage,
+    updateInstallFailures,
     lastReleaseDate: null,
     versionAlertsEnabled: !isDevMode,