free-coding-models 0.5.0 → 0.5.1

package/README.md

@@ -145,7 +145,15 @@ docker run -p 19280:19280 ghcr.io/vava-nessa/free-coding-models:latest
 docker run -p 19280:19280 -e OPENROUTER_API_KEY=your_key ghcr.io/vava-nessa/free-coding-models:latest
 ```
 
-Access the web dashboard at `http://localhost:19280/` and configure your coding tool to use `http://localhost:19280/v1` with model `fcm`.
+Access the daemon web dashboard at `http://localhost:19280/` and configure your coding tool to use `http://localhost:19280/v1` with model `fcm`.
+
+For the full TUI-style catalog dashboard from an npm install, run:
+
+```bash
+free-coding-models web
+```
+
+This starts the realtime Web Dashboard locally, opens it in your browser, and uses `http://localhost:3333/` by default. Override the port with `FCM_WEB_PORT=3334 free-coding-models web`.
 
 ### Available Image Tags
 

package/bin/free-coding-models.js

@@ -53,6 +53,16 @@ async function main() {
     process.exit(0);
   }
 
+  // 📖 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 });
+    return;
+  }
+
   // 📖 Router daemon lifecycle flags run before the TUI so automation and
   // 📖 editor integrations can manage the local OpenAI-compatible endpoint.
   if (cliArgs.daemonMode || cliArgs.daemonBackgroundMode || cliArgs.daemonStopMode || cliArgs.daemonStatusMode) {

package/changelog/v0.5.1.md

@@ -0,0 +1,24 @@
+# Changelog v0.5.1 - 2026-05-31
+
+### Added
+- Added `free-coding-models web` as the npm-friendly way to launch the full TUI-style realtime Web Dashboard from a global install.
+- Added Socket.IO as the primary dashboard realtime transport, with SSE and REST polling fallbacks so the UI keeps updating even when one transport is unavailable.
+- Added `/api/state` support for dashboard clients and daemon dashboard clients, including ping mode, countdown, per-model ping state, and benchmark progress metadata.
+- Added tests that lock every visible web table column as sortable, including display-only columns such as `❔`, Last Ping, AI Latency, TPS, and Trend.
+
+### Changed
+- Reworked the standalone web server to mirror the TUI ping cadence more closely: startup speed mode, normal cadence, idle slow mode, per-model `isPinging`, and frequent incremental updates.
+- Changed the Web Dashboard AI Latency global benchmark to benchmark only the models currently visible after filters and search, instead of always benchmarking the full catalog.
+- Made every dashboard table column cycle through ascending, descending, and reset sorting, with missing values consistently pushed to the bottom.
+- Removed the top stats card row from the dashboard for a cleaner, table-first layout.
+- Removed the `ms` suffix from Last Ping and Avg cells in the dashboard table to make dense latency columns easier to scan.
+- Improved dashboard table borders and added visible column separators, including stronger light-theme borders.
+- Updated npm and web documentation to distinguish the full catalog dashboard (`free-coding-models web`, default `localhost:3333`) from the router daemon dashboard (`free-coding-models --daemon`, default `localhost:19280`).
+
+### Fixed
+- Fixed `free-coding-models web` being parsed as an API key by treating `web` as a real subcommand.
+- Fixed dashboard benchmark spinners so only the actively benchmarked row shows running state instead of making unrelated rows spin during global scans.
+- Fixed benchmark result keys by using provider/model identifiers, avoiding collisions and invisible results when providers share model ids.
+- Fixed the Tier “All” filter mismatch in the Web Dashboard.
+- Fixed light-theme button contrast where accent buttons could render unreadable black-on-black text.
+- Fixed the web development readiness check so it waits for the correct local server response.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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",
@@ -53,6 +53,7 @@
     "start": "node bin/free-coding-models.js",
     "test": "node --test test/test.js",
     "prepack": "npm run build:web",
+    "dev": "node scripts/dev-web.mjs",
     "dev:web": "node scripts/dev-web.mjs",
     "build:web": "vite build",
     "preview:web": "vite preview",
@@ -60,7 +61,11 @@
     "test:fcm:mock": "node scripts/testfcm-runner.mjs --tool crush --tool-bin-dir test/fixtures/mock-bin"
   },
   "dependencies": {
-    "chalk": "^5.6.2"
+    "@tabler/icons-react": "^3.44.0",
+    "@tanstack/react-table": "^8.21.3",
+    "chalk": "^5.6.2",
+    "socket.io": "^4.8.3",
+    "socket.io-client": "^4.8.3"
   },
   "packageManager": "pnpm@10.33.2",
   "engines": {

package/src/core/router-daemon.js

@@ -48,6 +48,7 @@ import {
   saveConfig,
 } from './config.js'
 import { buildChatCompletionPingBody, resolveCloudflareUrl, shouldUseDisabledThinkingForProvider } from './ping.js'
+import { benchmarkModel, BENCHMARK_TIMEOUT_MS } from './benchmark.js'
 import { sendUsageTelemetry } from './telemetry.js'
 
 export const ROUTER_DEFAULT_PORT = 19280
@@ -343,12 +344,32 @@ function getWebModelsPayload(runtime) {
         pingCount: pings.length,
         hasApiKey,
         inRouterSet: inSetIndex.has(`${providerKey}::${modelId}`),
+        benchmarkKey: key,
+        isBenchmarking: runtime.webBenchmarkRunning?.has(key) || false,
+        benchmark: runtime.webBenchmarkResults?.get(key) || null,
       })
     }
   }
   return payload
 }
 
+function getWebStatePayload(runtime) {
+  const router = runtime.routerConfig()
+  const probeInterval = router.probeIntervals?.[router.probeMode] || DEFAULT_ROUTER_SETTINGS.probeIntervals.balanced
+  return {
+    pingMode: router.probeMode === 'aggressive' ? 'speed' : router.probeMode === 'eco' ? 'slow' : 'normal',
+    pingModeSource: 'daemon-probe-mode',
+    pingInterval: probeInterval,
+    nextPingAt: runtime.lastProbeAt ? runtime.lastProbeAt + probeInterval : null,
+    pendingPings: runtime.probeTimeouts?.size || 0,
+    isPinging: (runtime.probeTimeouts?.size || 0) > 0,
+    globalBenchmarkRunning: runtime.webGlobalBenchmarkRunning || false,
+    globalBenchmarkTotal: runtime.webGlobalBenchmarkTotal || 0,
+    globalBenchmarkCompleted: runtime.webGlobalBenchmarkCompleted || 0,
+    models: getWebModelsPayload(runtime),
+  }
+}
+
 function getWebConfigPayload(runtime) {
   const providers = {}
   for (const [key, src] of Object.entries(sources)) {
@@ -786,6 +807,11 @@ class RouterRuntime {
     this.quotaExhausted = new Set()
     this.quotaDetails = new Map()
     this.staleNotifications = new Set()
+    this.webBenchmarkRunning = new Set()
+    this.webBenchmarkResults = new Map()
+    this.webGlobalBenchmarkRunning = false
+    this.webGlobalBenchmarkTotal = 0
+    this.webGlobalBenchmarkCompleted = 0
     this.refreshRouteState()
   }
 
@@ -1131,6 +1157,99 @@ class RouterRuntime {
     }
   }
 
+  broadcastWebState() {
+    this.broadcast('models', getWebStatePayload(this))
+  }
+
+  async runWebBenchmark(providerKey, modelId) {
+    const key = modelKey(providerKey, modelId)
+    if (this.webBenchmarkRunning.has(key)) return { skipped: true }
+    const source = sources[providerKey]
+    if (!source?.url) {
+      return { ok: false, code: 'UNSUPPORTED', totalMs: 0, error: 'Provider has no benchmark URL', retries: 0 }
+    }
+
+    this.webBenchmarkRunning.add(key)
+    this.broadcastWebState()
+    try {
+      const result = await benchmarkModel({
+        apiKey: this.getApiKeyForProvider(providerKey) ?? null,
+        modelId,
+        providerKey,
+        url: source.url,
+        timeoutMs: BENCHMARK_TIMEOUT_MS,
+      })
+      this.webBenchmarkResults.set(key, result)
+      return result
+    } catch (err) {
+      const fallback = { ok: false, code: 'ERR', totalMs: 0, error: err?.message || 'Benchmark failed', retries: 0 }
+      this.webBenchmarkResults.set(key, fallback)
+      return fallback
+    } finally {
+      this.webBenchmarkRunning.delete(key)
+      this.broadcastWebState()
+    }
+  }
+
+  async runWebGlobalBenchmark(models) {
+    if (this.webGlobalBenchmarkRunning) return { started: false, error: 'Global benchmark already running' }
+    const knownModels = []
+    const seen = new Set()
+    for (const item of Array.isArray(models) ? models : []) {
+      const providerKey = typeof item?.providerKey === 'string' ? item.providerKey : ''
+      const modelId = typeof item?.modelId === 'string' ? item.modelId : ''
+      const key = modelKey(providerKey, modelId)
+      if (!this.modelCatalog.has(key) || seen.has(key)) continue
+      seen.add(key)
+      knownModels.push({ providerKey, modelId, key })
+    }
+
+    const fallbackModels = knownModels.length > 0
+      ? knownModels
+      : [...this.modelCatalog.values()].filter((m) => sources[m.providerKey]?.url && !sources[m.providerKey]?.cliOnly)
+
+    this.webGlobalBenchmarkRunning = true
+    this.webGlobalBenchmarkTotal = fallbackModels.length
+    this.webGlobalBenchmarkCompleted = 0
+    this.broadcastWebState()
+
+    const healthPriority = { up: 0, pending: 1, timeout: 2, noauth: 3, auth_error: 4, down: 5 }
+    const sorted = [...fallbackModels].sort((a, b) => {
+      const aw = this.probeWindows.get(modelKey(a.providerKey, a.modelId)) || []
+      const bw = this.probeWindows.get(modelKey(b.providerKey, b.modelId)) || []
+      const aLast = aw.at(-1)
+      const bLast = bw.at(-1)
+      const aState = aLast?.ok ? 'up' : aw.length ? 'down' : 'pending'
+      const bState = bLast?.ok ? 'up' : bw.length ? 'down' : 'pending'
+      const hpA = healthPriority[aState] ?? 6
+      const hpB = healthPriority[bState] ?? 6
+      if (hpA !== hpB) return hpA - hpB
+      return (aLast?.latencyMs ?? 99999) - (bLast?.latencyMs ?? 99999)
+    })
+
+    const workers = new Array(Math.min(5, sorted.length)).fill(null).map(async () => {
+      while (sorted.length > 0) {
+        const next = sorted.shift()
+        if (!next) break
+        try {
+          await this.runWebBenchmark(next.providerKey, next.modelId)
+        } finally {
+          this.webGlobalBenchmarkCompleted += 1
+          this.broadcastWebState()
+        }
+      }
+    })
+
+    void Promise.all(workers).finally(() => {
+      this.webGlobalBenchmarkRunning = false
+      this.webGlobalBenchmarkTotal = 0
+      this.webGlobalBenchmarkCompleted = 0
+      this.broadcastWebState()
+    })
+
+    return { started: true, total: fallbackModels.length }
+  }
+
   statusPayload() {
     const router = this.routerConfig()
     const activeSet = this.getSet(router.activeSet)
@@ -1892,6 +2011,10 @@ class RouterRuntime {
         sendJson(res, 200, getWebModelsPayload(this), { 'x-request-id': requestId })
         return
       }
+      if (req.method === 'GET' && url.pathname === '/api/state') {
+        sendJson(res, 200, getWebStatePayload(this), { 'x-request-id': requestId })
+        return
+      }
       if (req.method === 'GET' && url.pathname === '/api/config') {
         sendJson(res, 200, getWebConfigPayload(this), { 'x-request-id': requestId })
         return
@@ -1907,11 +2030,53 @@ class RouterRuntime {
           'Connection': 'keep-alive',
           'x-request-id': requestId,
         })
-        res.write(`data: ${JSON.stringify(getWebModelsPayload(this))}\n\n`)
+        res.write(`data: ${JSON.stringify(getWebStatePayload(this))}\n\n`)
         this.sseClients.add(res)
         req.on('close', () => this.sseClients.delete(res))
         return
       }
+      if (req.method === 'POST' && url.pathname === '/api/activity') {
+        sendJson(res, 200, { ok: true }, { 'x-request-id': requestId })
+        return
+      }
+      if (req.method === 'POST' && url.pathname === '/api/benchmark') {
+        const body = await readJsonBody(req)
+        const providerKey = typeof body.providerKey === 'string' ? body.providerKey : ''
+        const modelId = typeof body.modelId === 'string' ? body.modelId : ''
+        if (!this.modelCatalog.has(modelKey(providerKey, modelId))) {
+          sendJson(res, 404, { error: 'Model not found' }, { 'x-request-id': requestId })
+          return
+        }
+        if (this.webBenchmarkRunning.has(modelKey(providerKey, modelId))) {
+          sendJson(res, 409, { error: 'Benchmark already in progress for this model' }, { 'x-request-id': requestId })
+          return
+        }
+        const result = await this.runWebBenchmark(providerKey, modelId)
+        sendJson(res, 200, result, { 'x-request-id': requestId })
+        return
+      }
+      if (url.pathname === '/api/global-benchmark') {
+        if (req.method === 'GET') {
+          sendJson(res, 200, {
+            running: this.webGlobalBenchmarkRunning,
+            total: this.webGlobalBenchmarkTotal,
+            completed: this.webGlobalBenchmarkCompleted,
+          }, { 'x-request-id': requestId })
+          return
+        }
+        if (req.method !== 'POST') {
+          sendError(res, 405, 'Method not allowed', 'invalid_request_error', 'method_not_allowed', requestId)
+          return
+        }
+        if (this.webGlobalBenchmarkRunning) {
+          sendJson(res, 409, { error: 'Global benchmark already running' }, { 'x-request-id': requestId })
+          return
+        }
+        const body = await readJsonBody(req)
+        const result = await this.runWebGlobalBenchmark(body.models)
+        sendJson(res, result.started ? 202 : 409, result, { 'x-request-id': requestId })
+        return
+      }
       if (req.method === 'GET' && url.pathname.startsWith('/api/key/')) {
         // 📖 Reveals raw API keys — same-origin only to prevent malicious sites
         // 📖 from exfiltrating provider credentials via XHR/fetch.

package/src/core/utils.js

@@ -471,6 +471,8 @@ export function parseArgs(argv) {
       flags.push(arg.toLowerCase())
     } else if (skipIndices.has(i)) {
       // 📖 Skip — this is a value for --tier, not an API key
+    } else if (i === 0 && arg.toLowerCase() === 'web') {
+      // 📖 `free-coding-models web` is a subcommand, not a provider API key.
     } else if (!apiKey) {
       apiKey = arg
     }

package/src/tui/cli-help.js

@@ -36,6 +36,7 @@ const ANALYSIS_FLAGS = [
 ]
 
 const CONFIG_FLAGS = [
+  { flag: 'web | --web | --gui', description: 'Start the full-catalog realtime Web Dashboard' },
   { flag: '--daemon', description: 'Start the FCM Router daemon + web dashboard (same port)' },
   { flag: '--daemon-bg', description: 'Start the FCM Router daemon in the background' },
   { flag: '--daemon-status', description: 'Print FCM Router daemon status JSON' },
@@ -47,6 +48,7 @@ const CONFIG_FLAGS = [
 
 const EXAMPLES = [
   'free-coding-models --help',
+  'free-coding-models web',
   'free-coding-models --daemon',
   'free-coding-models --daemon-bg',
   'free-coding-models --daemon-status',

package/src/tui/render-table.js

@@ -412,7 +412,7 @@ export function renderTable({
   })
 
   const lines = [
-    `  ${themeColors.accentBold(`🚀 free-coding-models v${LOCAL_VERSION}`)}${modeBadge}${pingControlBadge}${tierBadge}${originBadge}${chalk.reset('')}   ` +
+    `  ${chalk.rgb(118, 185, 0).bgRgb(0, 0, 0).bold(' > ')}${chalk.rgb(118, 185, 0).bgRgb(0, 0, 0).bold('free')}${chalk.rgb(255, 255, 255).bgRgb(0, 0, 0).bold('-coding-models')}${chalk.rgb(118, 185, 0).bgRgb(0, 0, 0).bold('_ ')} ${themeColors.dim(`v${LOCAL_VERSION}`)}${modeBadge}${pingControlBadge}${tierBadge}${originBadge}${chalk.reset('')}   ` +
       themeColors.dim('📦 ') + themeColors.accentBold(`${completedPings}/${totalVisible}`) + themeColors.dim('  ') +
       themeColors.success(`✅ ${up}`) + themeColors.dim(' up  ') +
       themeColors.warning(`⏳ ${timeout}`) + themeColors.dim(' timeout  ') +

package/web/README.md

@@ -14,11 +14,14 @@ To maintain maximum code sharing, **95%+ of all components and logic are kept co
 
 ## ⚡ API & Event Integration
 
-The React app relies on HTTP and Server-Sent Events (SSE) to talk to the engine:
-* `GET /api/models`: Fetches the live model catalog, complete with stability scores and latency details.
-* `GET /api/config`: Retrieves active provider toggles (keys are masked).
-* `POST /api/settings`: Updates API keys and provider preferences.
-* `GET /api/events` / `EventSource`: Listens for real-time SSE updates broadcasted by the ping and benchmark loops.
+The React app uses a realtime-first connection strategy against the local engine:
+* **Socket.IO** is preferred in dev/web-server mode for instant per-model ping and benchmark updates.
+* **`GET /api/events` / `EventSource`** is the streaming fallback used by daemon/Docker surfaces.
+* **`GET /api/state`** returns the wrapped live dashboard state for REST fallback polling.
+* **`GET /api/models`** remains the legacy flat model catalog endpoint for simple clients.
+* **`GET /api/config`** retrieves active provider toggles (keys are masked).
+* **`POST /api/settings`** updates API keys and provider preferences.
+* **`POST /api/global-benchmark`** benchmarks only the models currently visible in the web table, so filters/search control the benchmark scope.
 
 ---