free-coding-models 0.5.53 → 0.5.55

package/changelog/v0.5.54.md

@@ -0,0 +1,18 @@
+# Changelog v0.5.54 - 2026-07-25
+
+### Fixed
+- 🛠️ **`patch-openclaw.js` now respects real model metadata** ([#133](https://github.com/vava-nessa/free-coding-models/issues/133)) — the script was destructuring only 3 of 5 fields from each `nvidiaNim` tuple (`[modelId, label, tier, sweScore, ctx]`), so it dropped the real `ctx` and fell back to a hardcoded `contextWindow` per tier (e.g. all S+ models got 128000, even `DeepSeek V4 Flash` which actually has 1M context). Now it parses the real `ctx` string (`'200k'` → 200000, `'1M'` → 1_000_000) and persists `tier`, `sweScore`, and a `source` field for traceability.
+
+- 🧭 **fcm_router now shows a real label in the TUI** ([#140](https://github.com/vava-nessa/free-coding-models/issues/140)) — added a `fcm_router` entry to `PROVIDER_METADATA` so every UI surface (Setup wizard, Settings panel, tool launchers, TUI filters) resolves "Smart Router Daemon" instead of the raw key `fcm_router` (which users were reading as "Unknown"). The local `getProviderLabel()` in `endpoint-installer.js` was the only place that knew about `fcm_router`; it now falls through to `PROVIDER_METADATA` so all callers stay in sync.
+
+### Maintenance
+- 🧹 **Closed 3 stale issues that were already fixed** in older releases (verified by `git log` on the relevant code paths):
+  - [#116](https://github.com/vava-nessa/free-coding-models/issues/116) — Docker API 404s (fixed in v0.5.28, commit `2c07925`)
+  - [#117](https://github.com/vava-nessa/free-coding-models/issues/117) — "pending" status confusing (fixed in v0.5.28, same commit)
+  - [#118](https://github.com/vava-nessa/free-coding-models/issues/118) — Probe loop silent stall (fixed in v0.5.36, commit `f0dd3d8`)
+- 🧪 **+18 new unit tests** for `patch-openclaw.js` parseCtx/defaultMaxTokens (11) and `provider-metadata.js` fcm_router lookup (7). All test runs go through `pnpm test` (no extra setup needed).
+
+### Pre-flight checks
+- 584/584 tests pass (`pnpm test`)
+- `vite build` succeeds (260 modules, ~283ms)
+- CLI loads cleanly (`free-coding-models --help`)

package/changelog/v0.5.55.md

@@ -0,0 +1,17 @@
+# Changelog v0.5.55 - 2026-07-25
+
+### Fixed
+- 🐳 **Docker "Tool mode save failed" — clear root cause + actionable fix** ([#119](https://github.com/vava-nessa/free-coding-models/issues/119)) — when the `fcm-data` volume was created with files owned by a different UID (older images, host bind-mounts), `chmod -R 777` had no effect because Linux checks file ownership, not mode bits. Two-layer fix:
+  1. `src/core/config.js` — `saveConfig()` now detects `EACCES` / `EPERM` and surfaces a friendly hint via the new exported `formatPermissionHint()` function. The hint explains *why* `chmod` is the wrong tool and gives the exact `docker compose down && docker volume rm <vol> && docker compose up` fix.
+  2. `docker-entrypoint.sh` — proactive ownership check at container startup. If a config file is owned by a different UID than the running `fcm` user, the entrypoint logs a loud `⚠️ WARNING` block *before* the first save attempt fails with a confusing error.
+
+### Closed (upstream, no FCM-side fix possible)
+- 📌 **Caveman CLI install fails on Node 26** ([#101](https://github.com/vava-nessa/free-coding-models/issues/101)) — this is upstream in `@juliusbrussee/caveman-code`. `better-sqlite3 v11.10.0` doesn't compile against Node.js v26 (V8 API churn: `GetPrototype` → `GetPrototypeV2`, etc.). FCM surfaces the npm error verbatim but cannot fix caveman-code's deps. Workaround: use Node v22 or v24 (both LTS, both supported by `better-sqlite3@11`).
+
+### Maintenance
+- 🧪 **+6 new unit tests** for `formatPermissionHint()` (`test/config-permission-hint.test.js`) — covers empty string for non-permission errors, EACCES/EPERM detection, Docker volume mention, "chmod is not the fix" wording, multi-line output.
+
+### Pre-flight checks
+- 590/590 tests pass (`pnpm test`)
+- `vite build` succeeds
+- All three surfaces (CLI, web dashboard, Docker) compatible

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.53",
+  "version": "0.5.55",
   "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,7 +53,7 @@
   ],
   "scripts": {
     "start": "node bin/free-coding-models.js",
-    "test": "node --test test/test.js test/fcm-agent-core.test.js",
+    "test": "node --test test/test.js test/fcm-agent-core.test.js test/patch-openclaw.test.js test/provider-metadata.test.js test/config-permission-hint.test.js",
     "prepack": "npm run build:web",
     "dev": "node scripts/dev-web.mjs",
     "dev:web": "node scripts/dev-web.mjs",

package/patch-openclaw.js

@@ -18,21 +18,24 @@ const OPENCLAW_JSON = join(homedir(), '.openclaw', 'openclaw.json')
 console.log('🦞 Patching OpenClaw for full NVIDIA model support...\n')
 
 // ─── Helper functions ───────────────────────────────────────────────────────────
-function getModelConfig(tier) {
-  // S+/S tier: largest context
-  if (tier === 'S+' || tier === 'S') {
-    return { contextWindow: 128000, maxTokens: 8192 }
-  }
-  // A+ tier
-  if (tier === 'A+') {
-    return { contextWindow: 131072, maxTokens: 4096 }
-  }
-  // A/A- tier
-  if (tier === 'A' || tier === 'A-') {
-    return { contextWindow: 131072, maxTokens: 4096 }
-  }
-  // B+/B/C tier: smaller context
-  return { contextWindow: 32768, maxTokens: 2048 }
+// 📖 Parse a context-window string from sources.js: "200k" → 200_000, "1M" → 1_000_000.
+// Falls back to 8192 if the format is unexpected.
+function parseCtx(ctxStr) {
+  if (typeof ctxStr !== 'string') return 8192
+  const m = ctxStr.trim().match(/^(\d+(?:\.\d+)?)([kKmM]?)$/)
+  if (!m) return 8192
+  const n = Number(m[1])
+  const unit = m[2]
+  if (unit === 'M' || unit === 'm') return Math.round(n * 1_000_000)
+  if (unit === 'K' || unit === 'k') return Math.round(n * 1000)
+  return Math.round(n)
+}
+
+// 📖 Choose a sensible maxTokens from the real contextWindow.
+// Rule: ~5% of context, clamped between 2k and 16k.
+function defaultMaxTokens(ctx) {
+  const pct = Math.round(ctx * 0.05)
+  return Math.max(2048, Math.min(16384, pct))
 }
 
 // ─── Patch models.json ──────────────────────────────────────────────────────────
@@ -70,22 +73,29 @@ if (!modelsConfig.providers.nvidia) {
 const existingModelIds = new Set(modelsConfig.providers.nvidia.models.map(m => m.id))
 
 // Add all models from sources.js
+// 📖 Each nvidiaNim tuple is: [modelId, label, tier, sweScore, ctx] — see sources.js:39
 let addedCount = 0
-for (const [modelId, label, tier] of nvidiaNim) {
+for (const [modelId, label, tier, sweScore, ctx] of nvidiaNim) {
   if (existingModelIds.has(modelId)) {
     continue // Skip already existing models
   }
 
-  const config = getModelConfig(tier)
+  const contextWindow = parseCtx(ctx)
+  const maxTokens = defaultMaxTokens(contextWindow)
   const isThinking = modelId.includes('thinking')
 
   modelsConfig.providers.nvidia.models.push({
     id: modelId,
     name: label,
-    contextWindow: config.contextWindow,
-    maxTokens: config.maxTokens,
+    contextWindow,
+    maxTokens,
     reasoning: isThinking,
     input: ['text'],
+    // 📖 OpenClaw ignores unknown fields, but we persist the real metadata
+    // so anyone reading models.json can see the source-of-truth values.
+    tier,
+    sweScore,
+    source: 'free-coding-models/sources.js',
     cost: {
       input: 0,
       output: 0,

package/src/core/config.js

@@ -760,7 +760,16 @@ export function saveConfig(config, options = {}) {
     // 📖 Write failed - explicit error instead of silent failure
     let errorMsg = `Failed to write config: ${writeError.message}`
     try { unlinkSync(tempPath) } catch { /* ignore temp cleanup failures */ }
-    
+
+    // 📖 Detect permission errors and surface a Docker-specific hint. This
+    // 📖 happens when a volume was created with files owned by another UID
+    // 📖 (e.g. older images running as root, or a host bind-mount where the
+    // 📖 directory is owned by a different user). chmod 777 does NOT fix this
+    // 📖 because Linux checks file ownership, not mode bits, for write access.
+    if (writeError?.code === 'EACCES' || writeError?.code === 'EPERM') {
+      errorMsg += formatPermissionHint(writeError)
+    }
+
     // 📖 Try to restore from backup if we have one
     if (backupCreated) {
       try {
@@ -775,6 +784,37 @@ export function saveConfig(config, options = {}) {
   }
 }
 
+/**
+ * 📖 formatPermissionHint — build a friendly hint for the most common Docker
+ * 📖 permission failure (config file owned by a different UID than the running
+ * 📖 process). Returns an empty string for non-permission errors.
+ *
+ * 📖 Common symptom (issue #119): "Tool mode save failed" in the web dashboard
+ * 📖 even after `chmod -R 777`, because chmod doesn't change ownership.
+ */
+export function formatPermissionHint(writeError) {
+  // 📖 Only emit the hint for actual permission errors — silently no-op for
+  // 📖 anything else so the caller can safely concatenate the result.
+  if (writeError?.code !== 'EACCES' && writeError?.code !== 'EPERM') return ''
+  const lines = []
+  lines.push('')
+  lines.push('  💡 This is almost always a file-ownership issue, not a chmod issue.')
+  lines.push('     The config file is owned by a different user than the one running FCM.')
+  try {
+    const stat = statSync(CONFIG_PATH)
+    lines.push(`     File owner UID: ${stat.uid}, current process UID: ${process.getuid?.() ?? 'n/a'}`)
+  } catch { /* stat may also fail */ }
+  lines.push('')
+  lines.push('  Fix in Docker:')
+  lines.push('     docker compose down')
+  lines.push('     docker volume rm <project>_fcm-data   # or the volume name from `docker volume ls`')
+  lines.push('     docker compose up                    # recreates the volume with the right UID')
+  lines.push('')
+  lines.push('  Fix on host (bind mount):')
+  lines.push('     sudo chown $(id -u):$(id -g) ~/.free-coding-models.json')
+  return '\n' + lines.join('\n')
+}
+
 /**
  * 📖 createBackup: Creates a timestamped backup of the current config file.
  * 📖 Keeps only the 5 most recent backups to avoid disk space issues.

package/src/core/endpoint-installer.js

@@ -136,7 +136,9 @@ function getManagedProviderId(providerKey) {
 }
 
 function getProviderLabel(providerKey) {
-  if (providerKey === 'fcm_router') return 'Smart Router Daemon'
+  // 📖 fcm_router is now in PROVIDER_METADATA (provider-metadata.js) so all
+  // 📖 surfaces resolve to the same label. Issue #140 surfaced because this
+  // 📖 helper was the only place that knew about fcm_router.
   return PROVIDER_METADATA[providerKey]?.label || sources[providerKey]?.name || providerKey
 }
 

package/src/core/provider-metadata.js

@@ -79,6 +79,18 @@ export const OPENCODE_MODEL_MAP = {
 // 📖 `rateLimits` gives a quick reminder of the free-tier quota without opening a browser.
 // 📖 `paidProviderNote` marks providers that require credits/billing despite exposing free/trial/free-tagged models.
 export const PROVIDER_METADATA = {
+  // 📖 fcm_router is the local Smart Router Daemon — it's not a remote provider
+  // 📖 with an API key or signup URL, but several UI surfaces look it up here
+  // 📖 to render a human label. Without this entry, the label resolves to the
+  // 📖 raw key `fcm_router` (which users read as "Unknown" — see issue #140).
+  fcm_router: {
+    label: 'Smart Router Daemon',
+    color: chalk.rgb(80, 200, 120),
+    signupUrl: null,
+    signupHint: null,
+    rateLimits: 'Local daemon on http://127.0.0.1:19280 — start with Shift+S',
+    noKeyNeeded: true,
+  },
   nvidia: {
     label: 'NVIDIA NIM',
     color: chalk.rgb(178, 235, 190),