free-coding-models 0.5.54 → 0.5.55

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.54",
+  "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/patch-openclaw.test.js test/provider-metadata.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/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.