free-coding-models 0.2.0 → 0.2.2

package/README.md

@@ -84,6 +84,7 @@
 - **💻 OpenCode integration** — Auto-detects NIM setup, sets model as default, launches OpenCode
 - **🦞 OpenClaw integration** — Sets selected model as default provider in `~/.openclaw/openclaw.json`
 - **🧰 Public tool launchers** — `Enter` can auto-configure and launch `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, and `Goose`
+- **🔌 Install Endpoints flow** — Press `Y` to install one configured provider directly into `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, or `Goose`, either with the full provider catalog or a curated subset of models
 - **📝 Feature Request (J key)** — Send anonymous feedback directly to the project team
 - **🐛 Bug Report (I key)** — Send anonymous bug reports directly to the project team
  - **🎨 Clean output** — Zero scrollback pollution, interface stays open until Ctrl+C
@@ -446,7 +447,7 @@ The main table displays one row per model with the following columns:
 | Column | Sort key | Description |
 |--------|----------|-------------|
 | **Rank** | `R` | Position based on current sort order (medals for top 3: 🥇🥈🥉) |
-| **Tier** | `Y` | SWE-bench tier (S+, S, A+, A, A-, B+, B, C) |
+| **Tier** | — | SWE-bench tier (S+, S, A+, A, A-, B+, B, C) |
 | **SWE%** | `S` | SWE-bench Verified score — industry-standard for coding |
 | **CTX** | `C` | Context window size (e.g. `128k`) |
 | **Model** | `M` | Model display name (favorites show ⭐ prefix) |
@@ -844,7 +845,7 @@ This script:
 **Keyboard shortcuts (main TUI):**
 - **↑↓** — Navigate models
 - **Enter** — Select model and launch the current target tool from the header badge
-- **R/Y/S/C/M/O/L/A/H/V/B/U/G** — Sort by Rank/Tier/SWE/Ctx/Model/Provider/Latest/Avg/Health/Verdict/Stability/Up%/Usage
+- **R/S/C/M/O/L/A/H/V/B/U/G** — Sort by Rank/SWE/Ctx/Model/Provider/Latest/Avg/Health/Verdict/Stability/Up%/Usage
 - **F** — Toggle favorite on selected model (⭐ in Model column, pinned at top)
 - **T** — Cycle tier filter (All → S+ → S → A+ → A → A- → B+ → B → C → All)
 - **D** — Cycle provider filter (All → NIM → Groq → ...)
@@ -852,6 +853,7 @@ This script:
 - **Z** — Cycle target tool (OpenCode CLI → OpenCode Desktop → OpenClaw → Crush → Goose)
 - **X** — Toggle request logs (recent proxied request/token usage logs)
 - **P** — Open Settings (manage API keys, toggles, updates, profiles)
+- **Y** — Open Install Endpoints (`provider → tool → all models` or `selected models only`, no proxy)
 - **Shift+P** — Cycle through saved profiles (switches live TUI settings)
 - **Shift+S** — Save current TUI settings as a named profile (inline prompt)
 - **Q** — Open Smart Recommend overlay (find the best model for your task)
@@ -862,6 +864,21 @@ This script:
 
 Pressing **K** now shows a full in-app reference: main hotkeys, settings hotkeys, and CLI flags with usage examples.
 
+### 🔌 Install Endpoints (`Y`)
+
+`Y` opens a dedicated install flow for configured providers. The flow is:
+
+1. Pick one provider that already has an API key in Settings
+2. Pick the target tool: `OpenCode CLI`, `OpenCode Desktop`, `OpenClaw`, `Crush`, or `Goose`
+3. Choose either `Install all models` or `Install selected models only`
+
+Important behavior:
+
+- Installs are written directly into the target tool config as FCM-managed entries, without going through `fcm-proxy`
+- `Install all models` is the recommended path because FCM can refresh that catalog automatically on later launches when the provider model list changes
+- `Install selected models only` is useful when you want a smaller curated picker inside the target tool
+- `OpenCode CLI` and `OpenCode Desktop` share the same `opencode.json`, so the managed provider appears in both
+
  **Keyboard shortcuts (Settings screen — `P` key):**
  - **↑↓** — Navigate providers, maintenance row, and profile rows
  - **Enter** — Edit API key inline, check/install update, or load a profile

package/bin/free-coding-models.js

@@ -20,10 +20,11 @@
  *   - Automatic config detection and model setup for both tools
  *   - JSON config stored in ~/.free-coding-models.json (auto-migrates from old plain-text)
  *   - Multi-provider support via sources.js (NIM/Groq/Cerebras/OpenRouter/Hugging Face/Replicate/DeepInfra/... — extensible)
- *   - Settings screen (P key) to manage API keys, provider toggles, and manual updates
+ *   - Settings screen (P key) to manage API keys, provider toggles, manual updates, and provider-key diagnostics
+ *   - Install Endpoints flow (Y key) to push provider catalogs into OpenCode, OpenClaw, Crush, and Goose
  *   - Favorites system: toggle with F, pin rows to top, persist between sessions
  *   - Uptime percentage tracking (successful pings / total pings)
- *   - Sortable columns (R/Y/O/M/L/A/S/N/H/V/B/U keys)
+ *   - Sortable columns (R/O/M/L/A/S/C/H/V/B/U/G keys)
  *   - Tier filtering via T key (cycles S+→S→A+→A→A-→B+→B→C→All)
  *
  *   → Functions:
@@ -118,6 +119,7 @@ import { createOverlayRenderers } from '../src/overlays.js'
 import { createKeyHandler } from '../src/key-handler.js'
 import { getToolModeOrder } from '../src/tool-metadata.js'
 import { startExternalTool } from '../src/tool-launchers.js'
+import { getConfiguredInstallableProviders, installProviderEndpoints, refreshInstalledEndpoints, getInstallTargetModes, getProviderCatalogModels } from '../src/endpoint-installer.js'
 
 // 📖 mergedModels: cross-provider grouped model list (one entry per label, N providers each)
 // 📖 mergedModelByLabel: fast lookup map from display label → merged model entry
@@ -216,9 +218,11 @@ async function main() {
   // 📖 Backward-compat: keep apiKey var for startOpenClaw() which still needs it
   let apiKey = getApiKey(config, 'nvidia')
 
-  // 📖 Default mode: OpenCode CLI.
-  // 📖 Additional external tools can now be selected via dedicated flags.
-  let mode = 'opencode'
+  // 📖 Default mode: use the last persisted launcher choice when valid,
+  // 📖 otherwise fall back to OpenCode CLI.
+  let mode = getToolModeOrder().includes(config.settings?.preferredToolMode)
+    ? config.settings.preferredToolMode
+    : 'opencode'
   const requestedMode = getToolModeOrder().find((toolMode) => {
     const flagByMode = {
       opencode: cliArgs.openCodeMode,
@@ -308,6 +312,10 @@ async function main() {
     console.log(chalk.yellow('  OpenRouter: using cached model list (live fetch failed)'))
   }
 
+  // 📖 Re-sync tracked external-tool catalogs after the live provider catalog has settled.
+  // 📖 This keeps prior `Y` installs aligned with the current FCM model list.
+  refreshInstalledEndpoints(config)
+
   // 📖 Build results from MODELS — only include enabled providers
   // 📖 Each result gets providerKey so ping() knows which URL + API key to use
 
@@ -391,7 +399,8 @@ async function main() {
     settingsAddKeyMode: false,    // 📖 Whether we're in add-key mode (append a new key to provider)
     settingsEditBuffer: '',       // 📖 Typed characters for the API key being edited
     settingsErrorMsg: null,       // 📖 Temporary error message to display in settings
-    settingsTestResults: {},      // 📖 { providerKey: 'pending'|'ok'|'fail'|null }
+    settingsTestResults: {},      // 📖 { providerKey: 'pending'|'ok'|'auth_error'|'rate_limited'|'no_callable_model'|'fail'|'missing_key'|null }
+    settingsTestDetails: {},      // 📖 Long-form diagnostics shown under Setup Instructions after a Settings key test.
     settingsUpdateState: 'idle',  // 📖 'idle'|'checking'|'available'|'up-to-date'|'error'|'installing'
     settingsUpdateLatestVersion: null, // 📖 Latest npm version discovered from manual check
     settingsUpdateError: null,    // 📖 Last update-check error message for maintenance row
@@ -402,6 +411,17 @@ async function main() {
     helpVisible: false,           // 📖 Whether the help overlay (K key) is active
     settingsScrollOffset: 0,      // 📖 Vertical scroll offset for Settings overlay viewport
     helpScrollOffset: 0,          // 📖 Vertical scroll offset for Help overlay viewport
+    // 📖 Install Endpoints overlay state (Y key opens it)
+    installEndpointsOpen: false,  // 📖 Whether the install-endpoints overlay is active
+    installEndpointsPhase: 'providers', // 📖 providers | tools | scope | models | result
+    installEndpointsCursor: 0,    // 📖 Selected row within the current install phase
+    installEndpointsScrollOffset: 0, // 📖 Vertical scroll offset for the install overlay viewport
+    installEndpointsProviderKey: null, // 📖 Selected provider for endpoint installation
+    installEndpointsToolMode: null, // 📖 Selected target tool mode
+    installEndpointsScope: null,  // 📖 all | selected
+    installEndpointsSelectedModelIds: new Set(), // 📖 Multi-select buffer for the selected-models phase
+    installEndpointsErrorMsg: null, // 📖 Temporary validation/error message inside the install flow
+    installEndpointsResult: null, // 📖 Final install result shown in the result phase
     // 📖 Smart Recommend overlay state (Q key opens it)
     recommendOpen: false,         // 📖 Whether the recommend overlay is active
     recommendPhase: 'questionnaire', // 📖 'questionnaire'|'analyzing'|'results' — current phase
@@ -593,7 +613,10 @@ async function main() {
     toFavoriteKey,
     getTopRecommendations,
     adjustScrollOffset,
-    getPingModel: () => pingModel
+    getPingModel: () => pingModel,
+    getConfiguredInstallableProviders,
+    getInstallTargetModes,
+    getProviderCatalogModels,
   })
 
   onKeyPress = createKeyHandler({
@@ -614,6 +637,10 @@ async function main() {
     saveAsProfile,
     setActiveProfile,
     saveConfig,
+    getConfiguredInstallableProviders,
+    getInstallTargetModes,
+    getProviderCatalogModels,
+    installProviderEndpoints,
     syncFavoriteFlags,
     toggleFavoriteModel,
     sortResultsWithPinnedFavorites,
@@ -687,12 +714,14 @@ async function main() {
     refreshAutoPingMode()
     state.frame++
     // 📖 Cache visible+sorted models each frame so Enter handler always matches the display
-    if (!state.settingsOpen && !state.recommendOpen && !state.featureRequestOpen && !state.bugReportOpen) {
+    if (!state.settingsOpen && !state.installEndpointsOpen && !state.recommendOpen && !state.featureRequestOpen && !state.bugReportOpen) {
       const visible = state.results.filter(r => !r.hidden)
       state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
     }
     const content = state.settingsOpen
       ? overlays.renderSettings()
+      : state.installEndpointsOpen
+        ? overlays.renderInstallEndpoints()
       : state.recommendOpen
         ? overlays.renderRecommend()
         : state.featureRequestOpen
@@ -703,7 +732,7 @@ async function main() {
                 ? overlays.renderHelp()
               : state.logVisible
                 ? overlays.renderLog()
-                : renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed)
+                : renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true)
     process.stdout.write(ALT_HOME + content)
   }, Math.round(1000 / FPS))
 
@@ -711,7 +740,7 @@ async function main() {
   const initialVisible = state.results.filter(r => !r.hidden)
   state.visibleSorted = sortResultsWithPinnedFavorites(initialVisible, state.sortColumn, state.sortDirection)
 
-  process.stdout.write(ALT_HOME + renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed))
+  process.stdout.write(ALT_HOME + renderTable(state.results, state.pendingPings, state.frame, state.cursor, state.sortColumn, state.sortDirection, state.pingInterval, state.lastPingTime, state.mode, state.tierFilterMode, state.scrollOffset, state.terminalRows, state.terminalCols, state.originFilterMode, state.activeProfile, state.profileSaveMode, state.profileSaveBuffer, state.proxyStartupStatus, state.pingMode, state.pingModeSource, state.hideUnconfiguredModels, state.widthWarningStartedAt, state.widthWarningDismissed, state.settingsUpdateState, state.settingsUpdateLatestVersion, getProxySettings(state.config).enabled === true))
 
   // 📖 If --recommend was passed, auto-open the Smart Recommend overlay on start
   if (cliArgs.recommendMode) {
@@ -756,10 +785,10 @@ async function main() {
         r.status = 'up'
       } else if (code === '000') {
         r.status = 'timeout'
-      } else if (code === '401') {
-        // 📖 401 = server is reachable but no API key set (or wrong key)
-        // 📖 Treated as 'noauth' — server is UP, latency is real, just needs a key
-        r.status = 'noauth'
+      } else if (code === '401' || code === '403') {
+        // 📖 Distinguish "no key configured" from "configured key rejected" so the
+        // 📖 Health column stays honest when Configured Only mode is enabled.
+        r.status = providerApiKey ? 'auth_error' : 'noauth'
         r.httpCode = code
       } else {
         r.status = 'down'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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/config.js

@@ -64,14 +64,17 @@
  *       "work":     { "apiKeys": {...}, "providers": {...}, "favorites": [...], "settings": {...} },
  *       "personal": { "apiKeys": {...}, "providers": {...}, "favorites": [...], "settings": {...} },
  *       "fast":     { "apiKeys": {...}, "providers": {...}, "favorites": [...], "settings": {...} }
- *     }
+ *     },
+ *     "endpointInstalls": [
+ *       { "providerKey": "nvidia", "toolMode": "opencode", "scope": "all", "modelIds": [], "lastSyncedAt": "2026-03-09T10:00:00.000Z" }
+ *     ]
  *   }
  *
  * 📖 Profiles store a snapshot of the user's configuration. Each profile contains:
  *   - apiKeys: API keys per provider (can differ between work/personal setups)
  *   - providers: enabled/disabled state per provider
  *   - favorites: list of pinned favorite models
- *   - settings: extra TUI preferences (tierFilter, sortColumn, sortAsc, pingInterval, hideUnconfiguredModels, proxy)
+ *   - settings: extra TUI preferences (tierFilter, sortColumn, sortAsc, pingInterval, hideUnconfiguredModels, preferredToolMode, proxy)
  *
  * 📖 When a profile is loaded via --profile <name> or Shift+P, the main config's
  *    apiKeys/providers/favorites are replaced with the profile's values. The profile
@@ -97,11 +100,12 @@
  *   → setActiveProfile(config, name) — Set which profile is active (null to clear)
  *   → _emptyProfileSettings() — Default TUI settings for a profile
  *   → getProxySettings(config) — Return normalized proxy settings from config
+ *   → normalizeEndpointInstalls(endpointInstalls) — Keep tracked endpoint installs stable across app versions
  *
  * @exports loadConfig, saveConfig, getApiKey, isProviderEnabled
  * @exports addApiKey, removeApiKey, listApiKeys — multi-key management helpers
  * @exports saveAsProfile, loadProfile, listProfiles, deleteProfile
- * @exports getActiveProfileName, setActiveProfile, getProxySettings
+ * @exports getActiveProfileName, setActiveProfile, getProxySettings, normalizeEndpointInstalls
  * @exports CONFIG_PATH — path to the JSON config file
  *
  * @see bin/free-coding-models.js — main CLI that uses these functions
@@ -175,6 +179,7 @@ export function loadConfig() {
       if (typeof parsed.telemetry.enabled !== 'boolean') parsed.telemetry.enabled = null
       if (typeof parsed.telemetry.consentVersion !== 'number') parsed.telemetry.consentVersion = 0
       if (typeof parsed.telemetry.anonymousId !== 'string' || !parsed.telemetry.anonymousId.trim()) parsed.telemetry.anonymousId = null
+      parsed.endpointInstalls = normalizeEndpointInstalls(parsed.endpointInstalls)
       // 📖 Ensure profiles section exists (added in profile system)
       if (!parsed.profiles || typeof parsed.profiles !== 'object') parsed.profiles = {}
       for (const profile of Object.values(parsed.profiles)) {
@@ -395,7 +400,7 @@ export function isProviderEnabled(config, providerKey) {
  * 📖 These settings are saved/restored when switching profiles so each profile
  *    can have different sort, filter, and ping preferences.
  *
- * @returns {{ tierFilter: string|null, sortColumn: string, sortAsc: boolean, pingInterval: number, hideUnconfiguredModels: boolean }}
+ * @returns {{ tierFilter: string|null, sortColumn: string, sortAsc: boolean, pingInterval: number, hideUnconfiguredModels: boolean, preferredToolMode: string }}
  */
 export function _emptyProfileSettings() {
   return {
@@ -404,6 +409,7 @@ export function _emptyProfileSettings() {
     sortAsc: true,        // 📖 true = ascending (fastest first for latency)
     pingInterval: 10000,  // 📖 default ms between pings in the steady "normal" mode
     hideUnconfiguredModels: true, // 📖 true = default to providers that are actually configured
+    preferredToolMode: 'opencode', // 📖 remember the last Z-selected launcher across app restarts
     proxy: normalizeProxySettings(),
   }
 }
@@ -438,6 +444,39 @@ export function getProxySettings(config) {
   return normalizeProxySettings(config?.settings?.proxy)
 }
 
+/**
+ * 📖 normalizeEndpointInstalls keeps the endpoint-install tracking list safe to replay.
+ *
+ * 📖 Each entry represents one managed catalog install performed through the `Y` flow:
+ *   - `providerKey`: FCM provider identifier (`nvidia`, `groq`, ...)
+ *   - `toolMode`: canonical tool id (`opencode`, `openclaw`, `crush`, `goose`)
+ *   - `scope`: `all` or `selected`
+ *   - `modelIds`: only used when `scope === 'selected'`
+ *   - `lastSyncedAt`: informational timestamp updated on successful refresh
+ *
+ * @param {unknown} endpointInstalls
+ * @returns {{ providerKey: string, toolMode: string, scope: 'all'|'selected', modelIds: string[], lastSyncedAt: string | null }[]}
+ */
+export function normalizeEndpointInstalls(endpointInstalls) {
+  if (!Array.isArray(endpointInstalls)) return []
+  return endpointInstalls
+    .map((entry) => {
+      if (!entry || typeof entry !== 'object') return null
+      const providerKey = typeof entry.providerKey === 'string' ? entry.providerKey.trim() : ''
+      const toolMode = typeof entry.toolMode === 'string' ? entry.toolMode.trim() : ''
+      if (!providerKey || !toolMode) return null
+      const scope = entry.scope === 'selected' ? 'selected' : 'all'
+      const modelIds = Array.isArray(entry.modelIds)
+        ? [...new Set(entry.modelIds.filter((modelId) => typeof modelId === 'string' && modelId.trim().length > 0))]
+        : []
+      const lastSyncedAt = typeof entry.lastSyncedAt === 'string' && entry.lastSyncedAt.trim().length > 0
+        ? entry.lastSyncedAt
+        : null
+      return { providerKey, toolMode, scope, modelIds, lastSyncedAt }
+    })
+    .filter(Boolean)
+}
+
 /**
  * 📖 saveAsProfile: Snapshot the current config state into a named profile.
  *
@@ -562,6 +601,8 @@ function _emptyConfig() {
       consentVersion: 0,
       anonymousId: null,
     },
+    // 📖 Tracked `Y` installs — used to refresh external tool catalogs automatically.
+    endpointInstalls: [],
     // 📖 Active profile name — null means no profile is loaded (using raw config).
     activeProfile: null,
     // 📖 Named profiles: each is a snapshot of apiKeys + providers + favorites + settings.