free-coding-models 0.5.10 → 0.5.14

package/src/core/utils.js

@@ -417,6 +417,7 @@ export function findBestModel(results) {
 //     --xcode, --gemini, --jcode, --copilot, --forgecode,
 //     --daemon, --daemon-bg, --daemon-stop,
 //     --daemon-status, --no-telemetry, --json, --help/-h (case-insensitive)
+//     --playground / playground subcommand (open the in-TUI chat playground)
 //   - Value flag: --tier <letter> (the next non-flag arg is the tier value)
 //
 // Returns:
@@ -519,6 +520,11 @@ export function parseArgs(argv) {
   // 📖 --web / --gui / web subcommand — launch the web dashboard instead of the TUI
   const webMode = flags.includes('--web') || flags.includes('--gui') || args[0] === 'web'
 
+  // 📖 --playground / playground subcommand — boot the TUI directly into the
+  // 📖 Playground chat overlay (assumes the router daemon is running or can
+  // 📖 be started with `free-coding-models --daemon-bg` first).
+  const playgroundMode = flags.includes('--playground') || args[0] === 'playground'
+
   // New boolean flags
   const sortDesc = flags.includes('--desc')
   const sortAscFlag = flags.includes('--asc')
@@ -574,6 +580,7 @@ export function parseArgs(argv) {
     showUnconfigured,
     premiumMode,
     webMode,
+    playgroundMode,
     daemonMode,
     daemonBackgroundMode,
     daemonStopMode,

package/src/tui/app.js

@@ -343,6 +343,12 @@ export async function runApp(cliArgs, config, startupOptions = {}) {
     updateInstallFailures: startupUpdate.failures || 0,
   })
 
+  // 📖 `--playground` / `playground` subcommand: open the in-TUI chat
+  // 📖 overlay on first render so the user lands directly in the chat.
+  if (startupOptions.wantPlayground === true) {
+    state.playgroundOpen = true
+  }
+
   // 📖 Apply the pre-fetched last release date now that state is initialized
   state.lastReleaseDate = lastReleaseDate
 
@@ -759,7 +765,7 @@ export async function runApp(cliArgs, config, startupOptions = {}) {
     // 📖 usable right now: models enter/leave as soon as ping status changes.
     applyTierFilter()
     // 📖 Cache visible+sorted models each frame so Enter handler always matches the display
-    if (!state.settingsOpen && !state.installEndpointsOpen && !state.toolInstallPromptOpen && !state.incompatibleFallbackOpen && !state.recommendOpen && !state.changelogOpen && !state.installedModelsOpen && !state.routerDashboardOpen && !state.commandPaletteOpen) {
+    if (!state.settingsOpen && !state.installEndpointsOpen && !state.toolInstallPromptOpen && !state.incompatibleFallbackOpen && !state.recommendOpen && !state.changelogOpen && !state.installedModelsOpen && !state.routerDashboardOpen && !state.playgroundOpen && !state.commandPaletteOpen) {
       const visible = state.results.filter(r => !r.hidden)
       state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection, {
         pinFavorites: state.favoritesPinnedAndSticky,
@@ -834,6 +840,8 @@ export async function runApp(cliArgs, config, startupOptions = {}) {
         ? overlays.renderInstalledModels()
       : state.routerDashboardOpen
         ? overlays.renderRouterDashboard()
+      : state.playgroundOpen
+        ? overlays.renderPlayground()
       : state.tokenUsageOpen
         ? overlays.renderTokenUsage()
       : state.routerOnboardingOpen

package/src/tui/cli-help.js

@@ -37,6 +37,7 @@ const ANALYSIS_FLAGS = [
 
 const CONFIG_FLAGS = [
   { flag: 'web | --web | --gui', description: 'Start the full-catalog realtime Web Dashboard' },
+  { flag: 'playground | --playground', description: 'Open the in-TUI Playground chat overlay (auto-starts the router if needed)' },
   { 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' },
@@ -54,6 +55,7 @@ const EXAMPLES = [
   'free-coding-models --daemon-status',
   'free-coding-models --sync-set',
   'free-coding-models --sync-set my-coding-set',
+  'free-coding-models --playground',
   'free-coding-models --openclaw --tier S',
   "free-coding-models --json | jq '.[0]'",
 ]

package/src/tui/command-palette.js

@@ -211,6 +211,7 @@ const BASE_COMMAND_TREE = [
   { id: 'open-changelog', label: 'Changelog', icon: '📋', type: 'page', description: 'Version history', keywords: ['changelog', 'release'] },
 
   { id: 'open-recommend', label: 'Smart recommend', shortcut: 'Q', icon: '🎯', type: 'page', description: 'Find best model for task', keywords: ['recommend', 'best model'] },
+  { id: 'open-playground', label: 'Playground', shortcut: ';', icon: '💬', type: 'page', description: 'Chat with the FCM router', keywords: ['playground', 'chat', 'try', 'prompt', 'router'] },
   { id: 'open-install-endpoints', label: 'Install endpoints', icon: '🔌', type: 'page', description: 'Install provider catalogs', keywords: ['install', 'endpoints', 'providers'] },
   { id: 'open-installed-models', label: 'Installed models', icon: '🗂️', type: 'page', description: 'View models configured in tools', keywords: ['installed', 'models', 'configured', 'tools', 'manager', 'goose', 'crush', 'aider'] },
 ]

package/src/tui/key-handler.js

@@ -55,6 +55,11 @@ import {
   restartRouterDashboardDaemon,
   toggleRouterDashboardProbePause,
 } from '../core/router-dashboard.js'
+import {
+  closePlaygroundOverlay,
+  openPlaygroundOverlay,
+  handlePlaygroundKeypress,
+} from '../core/playground.js'
 import { benchmarkModel } from '../core/benchmark.js'
 
 // 📖 Some providers need an explicit probe model because the first catalog entry
@@ -1283,6 +1288,7 @@ export function createKeyHandler(ctx) {
       || state.toolInstallPromptOpen
       || state.installedModelsOpen
       || state.routerDashboardOpen
+      || state.playgroundOpen
       || state.recommendOpen
 
       || state.helpVisible
@@ -1475,6 +1481,7 @@ export function createKeyHandler(ctx) {
 
       case 'open-recommend': return openRecommendOverlay()
       case 'open-router-dashboard': return openRouterDashboardOverlay(state)
+      case 'open-playground': return openPlaygroundOverlay(state)
       case 'open-token-usage': return openTokenUsageOverlay()
       case 'open-install-endpoints': return openInstallEndpointsOverlay()
       case 'open-installed-models': return openInstalledModelsOverlay()
@@ -1745,6 +1752,14 @@ export function createKeyHandler(ctx) {
       return
     }
 
+    // 📖 Playground overlay: handles Enter, Esc, Backspace, Ctrl+S, Ctrl+L,
+    // 📖 PageUp/PageDown, and printable input itself. The dedicated handler
+    // 📖 in core/playground.js owns the draft and submission state.
+    if (state.playgroundOpen) {
+      if (handlePlaygroundKeypress(key.string != null ? key.string : key.name, { fetchFn: globalThis.fetch })) return
+      return
+    }
+
     // 📖 Install Endpoints overlay: provider → tool → connection → scope → optional model subset.
     if (state.installEndpointsOpen) {
       if (key.ctrl && key.name === 'c') { exit(0); return }
@@ -2838,6 +2853,13 @@ export function createKeyHandler(ctx) {
       return
     }
 
+    // 📖 ; (semicolon) key: open the Playground chat overlay. Avoids clashes
+    // 📖 with P (settings), K (help), Z (tool), N (changelog), etc.
+    if (key.name === ';' || (key.shift && key.name === ':')) {
+      void openPlaygroundOverlay(state)
+      return
+    }
+
     // 📖 Y key toggles favorites display mode (pinned+sticky vs normal rows).
     if (key.name === 'y' && !key.ctrl && !key.meta) {
       toggleFavoritesDisplayMode()

package/src/tui/overlays.js

@@ -22,6 +22,7 @@
 import { loadChangelog } from '../core/changelog-loader.js'
 import { buildCliHelpLines } from './cli-help.js'
 import { renderRouterDashboard as renderRouterDashboardOverlay } from '../core/router-dashboard.js'
+import { renderPlayground as renderPlaygroundOverlay } from '../core/playground.js'
 import { themeColors, getThemeStatusLabel, getProviderRgb } from './theme.js'
 
 export function createOverlayRenderers(state, deps) {
@@ -1334,6 +1335,15 @@ export function createOverlayRenderers(state, deps) {
     return renderRouterDashboardOverlay(state, { LOCAL_VERSION })
   }
 
+  // ─── Playground overlay ───────────────────────────────────────────────────────
+  // 📖 Renders the in-TUI chat playground when the user presses `;` or opens
+  // 📖 it from the command palette. All chat traffic flows to the local
+  // 📖 daemon over HTTP, so the TUI process never has to import the
+  // 📖 provider catalog.
+  function renderPlayground() {
+    return renderPlaygroundOverlay(state, state.terminalRows, state.terminalCols)
+  }
+
   // ─── Incompatible fallback overlay ─────────────────────────────────────────
   // 📖 renderIncompatibleFallback shows when user presses Enter on a model that
   // 📖 is NOT compatible with the active tool. Two sections:
@@ -1615,6 +1625,7 @@ export function createOverlayRenderers(state, deps) {
     renderChangelog,
     renderInstalledModels,
     renderRouterDashboard,
+    renderPlayground,
     renderIncompatibleFallback,
     renderTokenUsage,
     renderRouterOnboarding,

package/src/tui/render-helpers.js

@@ -31,6 +31,8 @@
  *   - `calculateViewport`: Compute visible slice of model rows
  *   - `sortResultsWithPinnedFavorites`: Sort with pinned items at top
  *   - `adjustScrollOffset`: Clamp scrollOffset so cursor stays visible
+ *   - `fadedRow`: Multiply every 24-bit RGB channel by a factor to fade an
+ *     entire ANSI-colored line uniformly — used for "unusable" rows.
  *
  *   📦 Dependencies:
  *   - chalk: Terminal colors and formatting
@@ -56,6 +58,39 @@ export function stripAnsi(input) {
   return String(input).replace(/\x1b\[[0-9;]*m/g, '').replace(/\x1b\][^\x1b]*\x1b\\/g, '')
 }
 
+// 📖 fadedRow: Multiply every 24-bit RGB channel inside an ANSI-colored string by `factor`
+// 📖 (default 0.8 = 80% opacity, i.e. 20% less opaque) so the whole line reads as
+// 📖 uniformly faded. Only foreground/background 24-bit SGR codes (38;2;R;G;B and
+// 📖 48;2;R;G;B) are touched — bold, dim, reset codes, hyperlinks, and cursor SGRs
+// 📖 pass through unchanged so the structural styling stays intact.
+// 📖 Used to make "unusable" rows (NO KEY / AUTH FAIL) visually de-emphasized at
+// 📖 the row level rather than dimming a single cell, which is easier to miss at
+// 📖 a glance when scanning the table.
+// 📖 Channels are clamped to 0–255 and rounded to integers so terminal parsers
+// 📖 never receive an out-of-range byte. When `factor >= 1` the input is returned
+// 📖 untouched (identity fast path) so callers can wire this in without paying
+// 📖 the cost on every row.
+export function fadedRow(input, factor = 0.8) {
+  const text = String(input)
+  if (factor >= 1) return text
+  // 📖 Pre-clamp factor to [0, 1] to avoid negative channel values that would
+  // 📖 confuse downstream regex replacements; we still respect very small values
+  // 📖 so a caller can pass e.g. 0.1 to almost black-out a row.
+  const safeFactor = Math.max(0, Math.min(1, factor))
+  return text.replace(
+    /\x1b\[(38|48);2;(\d+);(\d+);(\d+)m/g,
+    (_match, kind, rStr, gStr, bStr) => {
+      const r = parseInt(rStr, 10)
+      const g = parseInt(gStr, 10)
+      const b = parseInt(bStr, 10)
+      const nr = Math.max(0, Math.min(255, Math.round(r * safeFactor)))
+      const ng = Math.max(0, Math.min(255, Math.round(g * safeFactor)))
+      const nb = Math.max(0, Math.min(255, Math.round(b * safeFactor)))
+      return `\x1b[${kind};2;${nr};${ng};${nb}m`
+    }
+  )
+}
+
 // 📖 maskApiKey: Mask all but first 4 and last 3 characters of an API key.
 // 📖 Prevents accidental disclosure of secrets in TUI display.
 export function maskApiKey(key) {

package/src/tui/render-table.js

@@ -17,6 +17,8 @@
  *   - High-visibility active text-filter banner with one-key clear action (`X`)
  *   - Full-width red outdated-version banner when a newer npm release is known
  *   - Distinct auth-failure vs missing-key health labels so configured providers stay honest
+ *   - 80%-opacity row fade for "unusable" models (NO KEY / AUTH FAIL) so the user can spot at a glance
+ *     which rows are not actually reachable, even when the cursor is parked elsewhere
  *
  *   → Functions:
  *   - `renderTable` — Render the full TUI table as a string (no side effects)
@@ -27,7 +29,7 @@
  *   - ../src/tier-colors.js: TIER_COLOR
  *   - ../src/utils.js: getAvg, getVerdict, getUptime, getStabilityScore
  *   - ../src/ping.js: usagePlaceholderForProvider
- *   - ../src/render-helpers.js: calculateViewport, sortResultsWithPinnedFavorites, padEndDisplay
+ *   - ../src/render-helpers.js: calculateViewport, sortResultsWithPinnedFavorites, padEndDisplay, fadedRow
  *
  *   @see bin/free-coding-models.js — main entry point that calls renderTable
  */
@@ -50,7 +52,7 @@ import { TIER_COLOR } from './tier-colors.js'
 import { getAvg, getVerdict, getUptime, getStabilityScore, getVersionStatusInfo } from '../core/utils.js'
 import { usagePlaceholderForProvider } from '../core/ping.js'
 import { formatBenchmarkLatency, formatBenchmarkTps } from '../core/benchmark.js'
-import { calculateViewport, sortResultsWithPinnedFavorites, padEndDisplay, displayWidth, stripAnsi } from './render-helpers.js'
+import { calculateViewport, sortResultsWithPinnedFavorites, padEndDisplay, displayWidth, stripAnsi, fadedRow } from './render-helpers.js'
 import { getToolMeta, TOOL_METADATA, TOOL_MODE_ORDER, isModelCompatibleWithTool } from '../core/tool-metadata.js'
 import { getColumnSpacing } from './ui-config.js'
 import { detectPackageManager, getManualInstallCmd } from '../core/updater.js'
@@ -946,20 +948,33 @@ export function renderTable({
     if (showBenchmarkColumns) rowParts.push(latencyCell, tpsCell)
     const row = '  ' + rowParts.join(COL_SEP)
 
+    // 📖 "Unusable" models (no key / bad key) are visually de-emphasized at the
+    // 📖 row level. The user cannot actually send a request to these models, so
+    // 📖 we drop the whole line to 80% opacity (20% less opaque) so it stands
+    // 📖 out from working rows at a glance, even if the cursor is parked on a
+    // 📖 different model. The cursor always wins so the user never loses track
+    // 📖 of their active selection. fadedRow multiplies every 24-bit RGB
+    // 📖 channel by 0.8 so the result works on every terminal that supports
+    // 📖 truecolor (no reliance on the SGR 2 "faint" code, which is ignored by
+    // 📖 some terminals).
+    const isUnusable = r.status === 'noauth' || r.status === 'auth_error'
+
+    let renderedRow
     if (isCursor) {
-      lines.push(themeColors.bgModelCursor(row))
+      renderedRow = themeColors.bgModelCursor(row)
     } else if (isIncompatible) {
       // 📖 Dark red background for models incompatible with the active tool mode.
       // 📖 This visually warns the user that selecting this model won't work with their current tool.
-      lines.push(chalk.bgRgb(60, 15, 15).rgb(180, 130, 130)(row))
+      renderedRow = chalk.bgRgb(60, 15, 15).rgb(180, 130, 130)(row)
     } else if (r.isRecommended) {
       // 📖 Medium green background for recommended models (distinguishable from favorites)
-      lines.push(themeColors.bgModelRecommended(row))
+      renderedRow = themeColors.bgModelRecommended(row)
     } else if (r.isFavorite) {
-      lines.push(themeColors.bgModelFavorite(row))
+      renderedRow = themeColors.bgModelFavorite(row)
     } else {
-      lines.push(row)
+      renderedRow = row
     }
+    lines.push(isUnusable ? fadedRow(renderedRow, 0.8) : renderedRow)
   }
 
   // 📖 Mouse support: record the 1-based terminal row range of model data rows.

package/src/tui/theme.js

@@ -53,6 +53,7 @@ const PALETTES = {
       feedback: [31, 13, 20],
       changelog: [12, 24, 44],
       commandPalette: [14, 20, 36],
+      playground: [10, 22, 18],
     },
     cursor: {
       defaultBg: [39, 55, 90],
@@ -99,6 +100,7 @@ const PALETTES = {
       feedback: [255, 247, 248],
       changelog: [244, 248, 255],
       commandPalette: [242, 247, 255],
+      playground: [244, 252, 246],
     },
     cursor: {
       defaultBg: [217, 231, 255],
@@ -326,5 +328,6 @@ export const themeColors = {
   overlayBgRecommend: (text) => paintBg(currentPalette().overlayBg.recommend, text, currentPalette().overlayFg),
   overlayBgFeedback: (text) => paintBg(currentPalette().overlayBg.feedback, text, currentPalette().overlayFg),
   overlayBgChangelog: (text) => paintBg(currentPalette().overlayBg.changelog, text, currentPalette().overlayFg),
+  overlayBgPlayground: (text) => paintBg(currentPalette().overlayBg.playground, text, currentPalette().overlayFg),
   overlayBgCommandPalette: (text) => paintBg(currentPalette().overlayBg.commandPalette, text, currentPalette().overlayFg),
 }