free-coding-models 0.1.83 → 0.1.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.1.83",
+  "version": "0.1.84",
   "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",
@@ -40,7 +40,7 @@
   },
   "files": [
     "bin/",
-    "lib/",
+    "src/",
     "sources.js",
     "patch-openclaw.js",
     "patch-openclaw-models.js",

package/src/analysis.js

@@ -0,0 +1,197 @@
+/**
+ * @file analysis.js
+ * @description Analysis functions for model reliability scoring and dynamic model discovery.
+ *
+ * @details
+ *   This module provides high-level analysis functions:
+ *   - Fiable mode: 10-second reliability analysis to find the most stable model
+ *   - Dynamic OpenRouter model discovery: Fetch free models from OpenRouter API
+ *   - Tier filtering with validation
+ *
+ *   🎯 Key features:
+ *   - Run 10-second reliability analysis across all models
+ *   - Find best model based on uptime, avg latency, and stability
+ *   - Fetch real-time OpenRouter free models (replaces static list)
+ *   - Tier filtering validation with helpful error messages
+ *
+ *   → Functions:
+ *   - `runFiableMode`: Analyze models for 10 seconds and output the most reliable one
+ *   - `filterByTierOrExit`: Filter models by tier, exit with error if tier is invalid
+ *   - `fetchOpenRouterFreeModels`: Fetch live free models from OpenRouter API
+ *
+ *   📦 Dependencies:
+ *   - ../sources.js: MODELS, sources
+ *   - ../src/utils.js: findBestModel, filterByTier, formatCtxWindow, labelFromId
+ *   - ../src/config.js: isProviderEnabled, getApiKey
+ *   - ../src/ping.js: ping
+ *   - chalk: Terminal colors and formatting
+ *   - ../src/constants.js: TIER_LETTER_MAP (for validation)
+ *
+ *   ⚙️ Configuration:
+ *   - Analysis duration: 10 seconds (hardcoded in runFiableMode)
+ *   - OpenRouter tier map: Known SWE-bench scores for popular models (fallback for unknown)
+ *
+ *   @see {@link ../src/utils.js} findBestModel implementation
+ *   @see {@link ../src/ping.js} ping implementation
+ */
+
+import { MODELS, sources } from '../sources.js'
+import { findBestModel, filterByTier, formatCtxWindow, labelFromId, TIER_LETTER_MAP } from '../src/utils.js'
+import { isProviderEnabled, getApiKey } from '../src/config.js'
+import { ping } from '../src/ping.js'
+import chalk from 'chalk'
+
+// 📖 runFiableMode: Analyze models for reliability over 10 seconds, output the best one.
+// 📖 Filters to enabled providers with keys, runs initial pings, then waits.
+// 📖 Uses findBestModel() from utils.js to select based on uptime/avg/stability.
+export async function runFiableMode(config) {
+  console.log(chalk.cyan('  ⚡ Analyzing models for reliability (10 seconds)...'))
+  console.log()
+
+  // 📖 Only include models from enabled providers that have API keys
+  let results = MODELS
+    .filter(([,,,,,providerKey]) => {
+      return isProviderEnabled(config, providerKey) && getApiKey(config, providerKey)
+    })
+    .map(([modelId, label, tier, sweScore, ctx, providerKey], i) => ({
+      idx: i + 1, modelId, label, tier, sweScore, ctx, providerKey,
+      status: 'pending',
+      pings: [],
+      httpCode: null,
+    }))
+
+  const startTime = Date.now()
+  const analysisDuration = 10000 // 10 seconds
+
+  // 📖 Run initial pings using per-provider API key and URL
+  const pingPromises = results.map(r => {
+    const rApiKey = getApiKey(config, r.providerKey)
+    const url = sources[r.providerKey]?.url
+    return ping(rApiKey, r.modelId, r.providerKey, url).then(({ code, ms }) => {
+      r.pings.push({ ms, code })
+      if (code === '200') {
+        r.status = 'up'
+      } else if (code === '000') {
+        r.status = 'timeout'
+      } else {
+        r.status = 'down'
+        r.httpCode = code
+      }
+    })
+  })
+
+  await Promise.allSettled(pingPromises)
+
+  // 📖 Continue pinging for the remaining time
+  const remainingTime = Math.max(0, analysisDuration - (Date.now() - startTime))
+  if (remainingTime > 0) {
+    await new Promise(resolve => setTimeout(resolve, remainingTime))
+  }
+
+  // 📖 Find best model
+  const best = findBestModel(results)
+
+  if (!best) {
+    console.log(chalk.red('  ✖ No reliable model found'))
+    process.exit(1)
+  }
+
+  // 📖 Output in format: providerName/modelId
+  const providerName = sources[best.providerKey]?.name ?? best.providerKey ?? 'nvidia'
+  console.log(chalk.green(`  ✓ Most reliable model:`))
+  console.log(chalk.bold(`    ${providerName}/${best.modelId}`))
+  console.log()
+  console.log(chalk.dim(`  📊 Stats:`))
+  const { getAvg, getUptime } = await import('./utils.js')
+  console.log(chalk.dim(`    Avg ping: ${getAvg(best)}ms`))
+  console.log(chalk.dim(`    Uptime: ${getUptime(best)}%`))
+  console.log(chalk.dim(`    Status: ${best.status === 'up' ? '✅ UP' : '❌ DOWN'}`))
+
+  process.exit(0)
+}
+
+// 📖 filterByTierOrExit: Filter models by tier letter (S/A/B/C).
+// 📖 Wrapper around filterByTier() that exits with error message instead of returning null.
+// 📖 This is used by CLI argument parsing to fail fast on invalid tier input.
+export function filterByTierOrExit(results, tierLetter) {
+  const filtered = filterByTier(results, tierLetter)
+  if (filtered === null) {
+    console.error(chalk.red(`  ✖ Unknown tier "${tierLetter}". Valid tiers: S, A, B, C`))
+    process.exit(1)
+  }
+  return filtered
+}
+
+// ─── Dynamic OpenRouter free model discovery ──────────────────────────────────
+// 📖 Fetches the live list of free models from OpenRouter's public API at startup.
+// 📖 Replaces the static openrouter entries in MODELS with fresh data so new free
+// 📖 models appear automatically without a code update.
+// 📖 Falls back silently to the static list on network failure.
+
+// 📖 Known SWE-bench scores for OpenRouter free models.
+// 📖 Keyed by base model ID (without the :free suffix).
+// 📖 Unknown models default to tier 'B' / '25.0%'.
+const OPENROUTER_TIER_MAP = {
+  'qwen/qwen3-coder':                         ['S+', '70.6%'],
+  'mistralai/devstral-2':                      ['S+', '72.2%'],
+  'stepfun/step-3.5-flash':                    ['S+', '74.4%'],
+  'deepseek/deepseek-r1-0528':                 ['S',  '61.0%'],
+  'qwen/qwen3-next-80b-a3b-instruct':          ['S',  '65.0%'],
+  'openai/gpt-oss-120b':                       ['S',  '60.0%'],
+  'openai/gpt-oss-20b':                        ['A',  '42.0%'],
+  'nvidia/nemotron-3-nano-30b-a3b':            ['A',  '43.0%'],
+  'meta-llama/llama-3.3-70b-instruct':         ['A-', '39.5%'],
+  'mimo-v2-flash':                             ['A',  '45.0%'],
+  'google/gemma-3-27b-it':                     ['A-', '36.0%'],
+  'google/gemma-3-12b-it':                     ['B+', '30.0%'],
+  'google/gemma-3-4b-it':                      ['B',  '22.0%'],
+  'google/gemma-3n-e4b-it':                    ['B',  '22.0%'],
+  'google/gemma-3n-e2b-it':                    ['B',  '18.0%'],
+  'meta-llama/llama-3.2-3b-instruct':          ['B',  '20.0%'],
+  'mistralai/mistral-small-3.1-24b-instruct':  ['A-', '35.0%'],
+  'qwen/qwen3-4b':                             ['B',  '22.0%'],
+  'nousresearch/hermes-3-llama-3.1-405b':      ['A',  '40.0%'],
+  'nvidia/nemotron-nano-9b-v2':                ['B+', '28.0%'],
+  'nvidia/nemotron-nano-12b-v2-vl':            ['B+', '30.0%'],
+  'z-ai/glm-4.5-air':                          ['A-', '38.0%'],
+  'arcee-ai/trinity-large-preview':             ['A',  '40.0%'],
+  'arcee-ai/trinity-mini':                      ['B+', '28.0%'],
+  'upstage/solar-pro-3':                       ['A-', '35.0%'],
+  'cognitivecomputations/dolphin-mistral-24b-venice-edition': ['B+', '28.0%'],
+  'liquid/lfm-2.5-1.2b-thinking':              ['B',  '18.0%'],
+  'liquid/lfm-2.5-1.2b-instruct':              ['B',  '18.0%'],
+}
+
+// 📖 fetchOpenRouterFreeModels: Fetch live free models from OpenRouter API.
+// 📖 Returns array of tuples [modelId, label, tier, sweScore, ctx] or null on failure.
+// 📖 Formats context windows using formatCtxWindow and labels using labelFromId.
+// 📖 Uses OPENROUTER_TIER_MAP for known models; others default to tier 'B'/'25.0%'.
+export async function fetchOpenRouterFreeModels() {
+  try {
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), 5000)
+    const res = await fetch('https://openrouter.ai/api/v1/models', {
+      signal: controller.signal,
+      headers: {
+        'HTTP-Referer': 'https://github.com/vava-nessa/free-coding-models',
+        'X-Title': 'free-coding-models',
+      },
+    })
+    clearTimeout(timeout)
+    if (!res.ok) return null
+    const json = await res.json()
+    if (!json.data || !Array.isArray(json.data)) return null
+
+    const freeModels = json.data.filter(m => m.id && m.id.endsWith(':free'))
+
+    return freeModels.map(m => {
+      const baseId = m.id.replace(/:free$/, '')
+      const [tier, swe] = OPENROUTER_TIER_MAP[baseId] || ['B', '25.0%']
+      const ctx = formatCtxWindow(m.context_length)
+      const label = labelFromId(m.id)
+      return [m.id, label, tier, swe, ctx]
+    })
+  } catch {
+    return null
+  }
+}

package/src/constants.js

@@ -0,0 +1,116 @@
+/**
+ * @file constants.js
+ * @description Pure terminal/TUI constants extracted from bin/free-coding-models.js.
+ *
+ * @details
+ *   This module centralises every "magic number" and escape-sequence constant that
+ *   the TUI rendering pipeline depends on.  Having them here means:
+ *   - They are importable by unit tests without pulling in the entire CLI entry point.
+ *   - A single source of truth for column widths, timing values, overlay colours, etc.
+ *   - `msCell` and `spinCell` live here too because they only depend on `CELL_W`,
+ *     `FRAMES`, and chalk — all of which are available at module scope.
+ *
+ *   ⚙️ Key configuration:
+ *   - `PING_TIMEOUT` / `PING_INTERVAL` control how aggressive the health-check loop is.
+ *   - `FPS` controls animation frame rate (braille spinner).
+ *   - `COL_MODEL` / `COL_MS` control legacy ping-column widths (retained for compat).
+ *   - `CELL_W` is derived from `COL_MS` and used by `msCell` / `spinCell`.
+ *   - `TABLE_HEADER_LINES` + `TABLE_FOOTER_LINES` = `TABLE_FIXED_LINES` must stay in sync
+ *     with the actual number of lines rendered by `renderTable()` in bin/.
+ *   - Overlay background colours (chalk.bgRgb) make each overlay panel visually distinct.
+ *
+ * @functions
+ *   → msCell(ms)       — Formats a latency value into a fixed-width coloured cell string
+ *   → spinCell(f, o)   — Returns a braille spinner cell at frame f with optional offset o
+ *
+ * @exports
+ *   ALT_ENTER, ALT_LEAVE, ALT_HOME,
+ *   PING_TIMEOUT, PING_INTERVAL,
+ *   FPS, COL_MODEL, COL_MS, CELL_W,
+ *   FRAMES, TIER_CYCLE,
+ *   SETTINGS_OVERLAY_BG, HELP_OVERLAY_BG, RECOMMEND_OVERLAY_BG, LOG_OVERLAY_BG,
+ *   OVERLAY_PANEL_WIDTH,
+ *   TABLE_HEADER_LINES, TABLE_FOOTER_LINES, TABLE_FIXED_LINES,
+ *   msCell, spinCell
+ *
+ * @see bin/free-coding-models.js  — main entry point that imports these constants
+ * @see src/tier-colors.js         — TIER_COLOR map (chalk-dependent, separate module)
+ */
+
+import chalk from 'chalk'
+
+// 📖 Alternate screen ANSI escape sequences used to enter/leave the TUI buffer.
+// 📖 \x1b[?1049h = enter alt screen  \x1b[?1049l = leave alt screen
+// 📖 \x1b[?25l   = hide cursor        \x1b[?25h   = show cursor
+// 📖 \x1b[H      = cursor to top
+// 📖 \x1b[?7l disables auto-wrap so wide rows clip at the right edge instead of
+// 📖 wrapping to the next line (which would double the row height and overflow).
+export const ALT_ENTER = '\x1b[?1049h\x1b[?25l\x1b[?7l'
+export const ALT_LEAVE = '\x1b[?7h\x1b[?1049l\x1b[?25h'
+export const ALT_HOME  = '\x1b[H'
+
+// 📖 Timing constants — control how fast the health-check loop runs.
+export const PING_TIMEOUT  = 15_000  // 📖 15s per attempt before abort
+export const PING_INTERVAL = 3_000   // 📖 3s between pings for fast model selection feedback
+
+// 📖 Animation and column-width constants.
+export const FPS       = 12
+export const COL_MODEL = 22
+// 📖 COL_MS = dashes in hline per ping column = visual width including 2 padding spaces.
+// 📖 Max value: 12001ms = 7 chars. padStart(COL_MS-2) fits content, +2 spaces = COL_MS dashes.
+export const COL_MS    = 11
+
+// 📖 CELL_W = visual content width of a single ms/spinner cell (COL_MS minus 2 border spaces).
+export const CELL_W = COL_MS - 2  // 📖 9 chars of content per ms cell
+
+// 📖 Braille spinner frames for the "pinging..." animation.
+export const FRAMES = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏']
+
+// 📖 TIER_CYCLE: ordered list of tier-filter states cycled by the T key.
+// 📖 Index 0 = no filter (show all), then each tier name in descending quality order.
+export const TIER_CYCLE = [null, 'S+', 'S', 'A+', 'A', 'A-', 'B+', 'B', 'C']
+
+// 📖 Overlay background chalk functions — each overlay panel has a distinct tint
+// 📖 so users can tell Settings, Help, Recommend, and Log panels apart at a glance.
+export const SETTINGS_OVERLAY_BG  = chalk.bgRgb(14, 20, 30)
+export const HELP_OVERLAY_BG      = chalk.bgRgb(24, 16, 32)
+export const RECOMMEND_OVERLAY_BG = chalk.bgRgb(10, 25, 15)  // 📖 Green tint for Smart Recommend
+export const LOG_OVERLAY_BG       = chalk.bgRgb(10, 20, 26)  // 📖 Dark blue-green tint for Log page
+
+// 📖 OVERLAY_PANEL_WIDTH: fixed character width of all overlay panels so background
+// 📖 tint fills the panel consistently regardless of content length.
+export const OVERLAY_PANEL_WIDTH = 116
+
+// 📖 Table row-budget constants — must stay in sync with renderTable()'s actual output.
+// 📖 If this drifts, model rows overflow and can push the title row out of view.
+export const TABLE_HEADER_LINES = 4  // 📖 title, spacer, column headers, separator
+export const TABLE_FOOTER_LINES = 5  // 📖 spacer, hints line 1, hints line 2, spacer, credit+links
+export const TABLE_FIXED_LINES  = TABLE_HEADER_LINES + TABLE_FOOTER_LINES
+
+// ─── Small cell-formatting helpers ────────────────────────────────────────────
+
+/**
+ * 📖 msCell: Renders a latency measurement into a right-padded coloured cell.
+ * 📖 null  → dim dash (not yet pinged)
+ * 📖 'TIMEOUT' → red TIMEOUT text
+ * 📖 <500ms → bright green, <1500ms → yellow, else red
+ * @param {number|string|null} ms
+ * @returns {string}
+ */
+export const msCell = (ms) => {
+  if (ms === null) return chalk.dim('—'.padStart(CELL_W))
+  const str = String(ms).padStart(CELL_W)
+  if (ms === 'TIMEOUT') return chalk.red(str)
+  if (ms < 500)  return chalk.greenBright(str)
+  if (ms < 1500) return chalk.yellow(str)
+  return chalk.red(str)
+}
+
+/**
+ * 📖 spinCell: Returns a braille spinner character padded to CELL_W.
+ * 📖 f = current frame index, o = row offset so each row animates differently.
+ * @param {number} f - global frame counter
+ * @param {number} [o=0] - per-row offset to stagger animation
+ * @returns {string}
+ */
+export const spinCell = (f, o = 0) => chalk.dim.yellow(FRAMES[(f + o) % FRAMES.length].padEnd(CELL_W))

package/src/favorites.js

@@ -0,0 +1,98 @@
+/**
+ * @file favorites.js
+ * @description Favorites management for model rows — persisted per user in ~/.free-coding-models.json.
+ *              Extracted from bin/free-coding-models.js to allow unit testing in isolation.
+ *
+ * @details
+ *   Favorites are stored as an ordered array of strings in the format "providerKey/modelId"
+ *   (e.g. "groq/llama-3.1-70b-versatile").  Insertion order matters: it determines the
+ *   `favoriteRank` used by `sortResultsWithPinnedFavorites` to keep pinned rows at the top.
+ *
+ *   How it works at runtime:
+ *   1. On startup, `syncFavoriteFlags()` is called once to attach `isFavorite`/`favoriteRank`
+ *      metadata to every result row based on the persisted favorites list.
+ *   2. When the user presses F, `toggleFavoriteModel()` mutates the config array and persists
+ *      immediately via `saveConfig()`.
+ *   3. The renderer reads `r.isFavorite` and `r.favoriteRank` from the row to decide whether
+ *      to show the ⭐ prefix and how to sort the row relative to non-favorites.
+ *
+ * @functions
+ *   → ensureFavoritesConfig(config)             — Ensure config.favorites is a clean deduped array
+ *   → toFavoriteKey(providerKey, modelId)        — Build the canonical "providerKey/modelId" string
+ *   → syncFavoriteFlags(results, config)         — Attach isFavorite/favoriteRank to result rows
+ *   → toggleFavoriteModel(config, providerKey, modelId) — Add/remove favorite and persist
+ *
+ * @exports
+ *   ensureFavoritesConfig, toFavoriteKey, syncFavoriteFlags, toggleFavoriteModel
+ *
+ * @see src/config.js  — saveConfig used here to persist changes immediately
+ * @see bin/free-coding-models.js — calls syncFavoriteFlags on startup and toggleFavoriteModel on F key
+ */
+
+import { saveConfig } from './config.js'
+
+/**
+ * 📖 Ensure favorites config shape exists and remains clean.
+ * 📖 Stored format: ["providerKey/modelId", ...] in insertion order.
+ * @param {Record<string, unknown>} config
+ */
+export function ensureFavoritesConfig(config) {
+  if (!Array.isArray(config.favorites)) config.favorites = []
+  const seen = new Set()
+  config.favorites = config.favorites.filter((entry) => {
+    if (typeof entry !== 'string' || entry.trim().length === 0) return false
+    if (seen.has(entry)) return false
+    seen.add(entry)
+    return true
+  })
+}
+
+/**
+ * 📖 Build deterministic key used to persist one favorite model row.
+ * @param {string} providerKey
+ * @param {string} modelId
+ * @returns {string}
+ */
+export function toFavoriteKey(providerKey, modelId) {
+  return `${providerKey}/${modelId}`
+}
+
+/**
+ * 📖 Sync per-row favorite metadata from config (used by renderer and sorter).
+ * 📖 Mutates each row in-place — adds favoriteKey, isFavorite, favoriteRank.
+ * @param {Array<Record<string, unknown>>} results
+ * @param {Record<string, unknown>} config
+ */
+export function syncFavoriteFlags(results, config) {
+  ensureFavoritesConfig(config)
+  const favoriteRankMap = new Map(config.favorites.map((entry, index) => [entry, index]))
+  for (const row of results) {
+    const favoriteKey = toFavoriteKey(row.providerKey, row.modelId)
+    const rank = favoriteRankMap.get(favoriteKey)
+    row.favoriteKey = favoriteKey
+    row.isFavorite = rank !== undefined
+    row.favoriteRank = rank !== undefined ? rank : Number.MAX_SAFE_INTEGER
+  }
+}
+
+/**
+ * 📖 Toggle favorite state and persist immediately.
+ * 📖 Returns true when row is now favorite, false when removed.
+ * @param {Record<string, unknown>} config
+ * @param {string} providerKey
+ * @param {string} modelId
+ * @returns {boolean}
+ */
+export function toggleFavoriteModel(config, providerKey, modelId) {
+  ensureFavoritesConfig(config)
+  const favoriteKey = toFavoriteKey(providerKey, modelId)
+  const existingIndex = config.favorites.indexOf(favoriteKey)
+  if (existingIndex >= 0) {
+    config.favorites.splice(existingIndex, 1)
+    saveConfig(config)
+    return false
+  }
+  config.favorites.push(favoriteKey)
+  saveConfig(config)
+  return true
+}