free-coding-models 0.5.73 → 0.5.75

package/README.md

@@ -673,6 +673,7 @@ Flags combine freely in any order. Run `free-coding-models --help` to print the
 | `--show-broken` | Don't auto-hide broken models this run |
 | `--check-drift` | Diff `sources.js` against `models.dev`; exit 1 on mismatch |
 | `--no-telemetry` | Disable anonymous telemetry for this run |
+| `--config-dir <dir>` | Store `config.json` + `backups/` in `<dir>` (e.g. `--config-dir ~/.config/free-coding-models`) |
 
 **Tool launchers** — start the TUI pre-configured for a tool, then `Enter` writes the model into that tool's config and launches it:
 
@@ -861,11 +862,11 @@ A: Yes — see [`sources.js`](./sources.js) for the model catalog format.
 
 ## Star History
 
-<a href="https://www.star-history.com/?repos=vava-nessa%2Ffree-coding-models&type=timeline&logscale=&legend=top-left">
+<a href="https://star-history.dera.page/#vava-nessa/free-coding-models&type=timeline&logscale&legend=top-left">
  <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=vava-nessa/free-coding-models&type=timeline&theme=dark&logscale&legend=top-left" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=vava-nessa/free-coding-models&type=timeline&logscale&legend=top-left" />
-   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=vava-nessa/free-coding-models&type=timeline&logscale&legend=top-left" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=vava-nessa/free-coding-models&type=timeline&theme=dark&logscale&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=vava-nessa/free-coding-models&type=timeline&logscale&legend=top-left" />
+   <img alt="Star History Chart" src="https://star-history.dera.page/svg?repos=vava-nessa/free-coding-models&type=timeline&logscale&legend=top-left" />
  </picture>
 </a>
 
@@ -893,6 +894,8 @@ A: Yes — see [`sources.js`](./sources.js) for the model catalog format.
     <td align="center" width="120"><a href="https://github.com/stgreenb"><img src="https://avatars.githubusercontent.com/u/18483964?v=4&s=80" width="80" height="80" style="border-radius:50%" alt="stgreenb"></a></td>
     <td align="center" width="120"><a href="https://github.com/MoriDanWork"><img src="https://avatars.githubusercontent.com/u/55363096?v=4&s=80" width="80" height="80" style="border-radius:50%" alt="MoriDanWork"></a></td>
     <td align="center" width="120"><a href="https://github.com/fan92rus"><img src="https://avatars.githubusercontent.com/u/13201333?v=4&s=80" width="80" height="80" style="border-radius:50%" alt="fan92rus"></a></td>
+    <td align="center" width="120"><a href="https://github.com/Muhammad95959"><img src="https://avatars.githubusercontent.com/u/75130655?v=4&s=80" width="80" height="80" style="border-radius:50%" alt="Muhammad95959"></a></td>
+    <td align="center" width="120"><a href="https://github.com/FaintFlower"><img src="https://avatars.githubusercontent.com/u/310248465?v=4&s=80" width="80" height="80" style="border-radius:50%" alt="FaintFlower"></a></td>
   </tr>
   <tr>
     <td align="center"><a href="https://github.com/vava-nessa"><sub><b>vava-nessa</b></sub></a></td>
@@ -905,9 +908,17 @@ A: Yes — see [`sources.js`](./sources.js) for the model catalog format.
     <td align="center"><a href="https://github.com/stgreenb"><sub><b>stgreenb</b></sub></a></td>
     <td align="center"><a href="https://github.com/MoriDanWork"><sub><b>MoriDanWork</b></sub></a></td>
     <td align="center"><a href="https://github.com/fan92rus"><sub><b>fan92rus</b></sub></a></td>
+    <td align="center"><a href="https://github.com/Muhammad95959"><sub><b>Muhammad95959</b></sub></a></td>
+    <td align="center"><a href="https://github.com/FaintFlower"><sub><b>FaintFlower</b></sub></a></td>
   </tr>
   <tr>
-    <td align="center" colspan="10"><sub>🛡️ <b>fan92rus</b> — Windows path traversal fix (<code>path.sep</code>)</sub></td>
+    <td align="center" colspan="12"><sub>🛡️ <b>fan92rus</b> — Windows path traversal fix (<code>path.sep</code>)</sub></td>
+  </tr>
+  <tr>
+    <td align="center" colspan="12"><sub>📁 <b>Muhammad95959</b> — <code>--config-dir</code> flag & XDG support</sub></td>
+  </tr>
+  <tr>
+    <td align="center" colspan="12"><sub>⭐ <b>FaintFlower</b> — Star History chart mirror fix</sub></td>
   </tr>
 </table>
 

package/bin/free-coding-models.js

@@ -11,11 +11,23 @@
 // 📖 IMPORTANT: these checks MUST run synchronously before any static imports
 // 📖 resolve, because router-daemon.js reads FCM_DEV at module load time.
 import { existsSync, readFileSync } from 'node:fs'
-import { join, dirname } from 'node:path'
+import { join, dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { homedir } from 'node:os'
 if (process.argv.includes('--dev') || (!process.env.FCM_DEV && existsSync(join(dirname(fileURLToPath(import.meta.url)), '..', '.git')))) {
   process.env.FCM_DEV = '1'
 }
+// 📖 --config-dir <dir>: point FCM's config files (config.json + backups/) at an
+// 📖 arbitrary directory (e.g. the XDG layout ~/.config/free-coding-models).
+// 📖 Stored as FCM_CONFIG_DIR BEFORE any static imports resolve so
+// 📖 src/core/config.js picks the path up at module load time. An externally-set
+// 📖 FCM_CONFIG_DIR (e.g. Docker) is preserved when the flag is absent.
+const _configDirIdx = process.argv.indexOf('--config-dir')
+if (_configDirIdx !== -1 && process.argv[_configDirIdx + 1] && !process.argv[_configDirIdx + 1].startsWith('--')) {
+  const _raw = process.argv[_configDirIdx + 1].trim()
+  const _expanded = _raw === '~' ? homedir() : _raw.startsWith('~/') ? join(homedir(), _raw.slice(2)) : _raw
+  process.env.FCM_CONFIG_DIR = resolve(_expanded)
+}
 
 import chalk from 'chalk';
 import { parseArgs, TIER_LETTER_MAP } from '../src/core/utils.js';

package/changelog/v0.5.74.md

@@ -0,0 +1,17 @@
+# Changelog v0.5.74 - 2026-08-22
+
+### Added
+- **`--config-dir <dir>` flag for XDG and custom config locations** — you can now point free-coding-models at any directory for its state files via `free-coding-models --config-dir ~/.config/free-coding-models` (or any path) or via `FCM_CONFIG_DIR` (useful for Docker). When set, `config.json`, `backups/` and `cache.json` all live together in the chosen directory instead of scattering `~/.free-coding-models.json` + `~/.free-coding-models.cache.json` + `~/.free-coding-models.backups`. The flag is parsed before any module loads so `src/core/config.js`, `src/core/cache.js` and `src/core/security.js` all respect it, `docker-entrypoint.sh` and `src/tui/cli-help.js` are updated, and 12 new tests cover `getConfigDir()`, `CONFIG_PATH` and cache relocation. With the follow-up fix, `~` and `~/` are now correctly expanded to your homedir (previously `resolve()` would treat `~` as a literal folder) and `saveConfig()` / `saveCache()` auto-create the target directory on first run so an empty XDG folder no longer throws `ENOENT`. Thanks @Muhammad95959 for the feature (PR #158).
+- **Dependabot auto-merge workflow** — new `.github/workflows/dependabot-auto-merge.yml` that squash-merges the `patch-and-minor` group automatically when required checks (`audit`, `lockfile-lint`, `Vercel`, `semgrep`) are green. Major updates stay manual for human review. This keeps weekly dependency churn low while preserving safety for breaking changes.
+
+### Fixed
+- **Star History chart in README was showing a "GitHub restricted access" placeholder** — GitHub restricted stargazer data and `api.star-history.com/chart` now returns an SVG with `x-chart-status: restricted` and a message instead of the real graph. The README now points to the working mirror `star-history.dera.page/svg` and link `star-history.dera.page/#...`, verified to return a real 200 SVG. Fixes the broken image at the bottom of the README. Thanks @FaintFlower (PR #159).
+- **First-run crash when `--config-dir` points to a fresh directory** — previously `saveConfig` wrote to `${CONFIG_PATH}.tmp-...` and then `rename` without ensuring the parent dir exists, which threw `ENOENT` on a non-existent XDG path. Both `saveConfig` (via `dirname(CONFIG_PATH)`) and `saveCache` (via `dirname(cachePath)`) now `mkdir -p` with `0o700` before writing.
+- **Tilde not expanded for `--config-dir` / `FCM_CONFIG_DIR`** — `resolve("~/...")` would create a literal `~/` folder under `cwd`. Added `expandTilde()` that maps `~` and `~/` to `homedir()` before `resolve()`, in both `src/core/config.js` and the pre-import handling in `bin/free-coding-models.js`.
+- **Test `MODELS flat array matches sources count` now accounts for deprecated models** — `sources.js` filters models with `deprecatedAfter < today` (e.g. `cerebras/zai-glm-4.7` deprecated 2026-08-17) when building `MODELS`, but the test counted all models. The test now mirrors the same filter so the suite is green (813/813).
+
+### Changed
+- **Dependencies (deps #152, patch-and-minor group, 6 updates)** — `@tabler/icons-react` 3.45.0 -> 3.46.0, `kandown` 0.34.3 -> 0.50.0, `@tanstack/react-virtual` 3.14.8 -> 3.14.9, `@vitejs/plugin-react` 6.0.4 -> 6.0.5, `vite` 8.1.5 -> 8.2.1, `vite-plus` 0.2.6 -> 0.2.9. All checks (audit, lockfile-lint, Vercel, semgrep, notify-discord) passed. Major group (`chalk` 5.6.2 -> 6.0.0 which requires Node 22, plus `@tanstack/react-table` 8 -> 9) is left for manual review and not auto-merged.
+
+### Tests
+- 813 tests passing (up from 812 after fixing the deprecated-model count and adding 12 new tests for `--config-dir` / cache relocation).

package/changelog/v0.5.75.md

@@ -0,0 +1,7 @@
+# Changelog v0.5.75 - 2026-08-22
+
+### Fixed
+- **Contributors table now lists the two latest contributors** — `README.md:883` previously showed 10 avatars ending at `fan92rus`. Added `@Muhammad95959` (`--config-dir` flag, PR #158) and `@FaintFlower` (Star History mirror, PR #159) with their avatars and a dedicated footer line each, and updated `colspan` from 10 to 12. `AGENTS.md:104` contributor list also updated so future automation picks them up.
+
+### Docs
+- **No code changes** — pure documentation sync so the published npm README and GitHub README correctly credit recent PR authors.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.73",
+  "version": "0.5.75",
   "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",
@@ -58,7 +58,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/config-permission-hint.test.js test/probe-cache.test.js test/passive-quota.test.js test/runtime-telemetry.test.js test/extended-benchmarks.test.js test/models-dev.test.js test/model-merger.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 test/probe-cache.test.js test/passive-quota.test.js test/runtime-telemetry.test.js test/extended-benchmarks.test.js test/models-dev.test.js test/model-merger.test.js test/config-dir.test.js test/cache-dir.test.js",
     "test:extended-benchmarks": "node --test test/extended-benchmarks.test.js",
     "test:models-dev": "node --test test/models-dev.test.js",
     "update:benchmarks": "node scripts/update-benchmarks.mjs",
@@ -76,7 +76,7 @@
     "@tabler/icons-react": "^3.44.0",
     "@tanstack/react-table": "^8.21.3",
     "chalk": "^5.6.2",
-    "kandown": "^0.34.3",
+    "kandown": "^0.50.0",
     "socket.io": "^4.8.3",
     "socket.io-client": "^4.8.3",
     "@tanstack/react-virtual": "^3.14.2"

package/src/core/cache.js

@@ -2,7 +2,8 @@
  * @file cache.js
  * @description Persistent cache for ping results to speed up startup.
  *
- * 📖 Cache file location: ~/.free-coding-models.cache.json
+ * 📖 Cache file location: <config-dir>/cache.json when a config dir is chosen
+ * 📖   (--config-dir / FCM_CONFIG_DIR), else ~/.free-coding-models.cache.json.
  * 📖 File permissions: 0o600 (user read/write only — contains API timing data)
  *
  * 📖 Why caching matters:
@@ -50,13 +51,18 @@ import fs from 'node:fs'
 import path from 'node:path'
 import os from 'node:os'
 import { fileURLToPath } from 'node:url'
+import { getConfigDir } from './config.js'
 
 // 📖 Cache TTL: 5 minutes in milliseconds
 // 📖 Ping results are considered fresh for this duration
 const CACHE_TTL = 5 * 60 * 1000
 
-// 📖 Get cache file path — platform-aware home directory resolution
+// 📖 Get cache file path — follows the chosen config dir (--config-dir /
+// 📖 FCM_CONFIG_DIR) so the cache lands next to config.json + backups/;
+// 📖 falls back to the classic ~/.free-coding-models.cache.json otherwise.
 export function getCachePath() {
+  const configDir = getConfigDir()
+  if (configDir) return path.join(configDir, 'cache.json')
   const homeDir = os.homedir()
   return path.join(homeDir, '.free-coding-models.cache.json')
 }
@@ -96,6 +102,11 @@ export function loadCache() {
 // 📖 providerTier: Current ping cadence ("fast" | "normal" | "slow")
 export function saveCache(results, providerTier = 'normal') {
   const cachePath = getCachePath()
+  // 📖 Ensure parent dir exists (XDG first-run would otherwise ENOENT when cache lives in --config-dir)
+  try {
+    const parentDir = path.dirname(cachePath)
+    if (!fs.existsSync(parentDir)) fs.mkdirSync(parentDir, { mode: 0o700, recursive: true })
+  } catch { /* best-effort */ }
 
   try {
     const models = {}

package/src/core/config.js

@@ -103,11 +103,55 @@
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, unlinkSync, renameSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { join } from 'node:path'
+import { join, resolve, dirname } from 'node:path'
 import { syncShellEnv } from './shell-env.js'
 
-// 📖 New JSON config path — stores all providers' API keys + enabled state
-export const CONFIG_PATH = join(homedir(), '.free-coding-models.json')
+// 📖 Expand leading ~/ or bare ~ to homedir so --config-dir ~/.config/... works.
+// 📖 resolve() alone does NOT expand tilde, it would treat ~ as a literal folder.
+function expandTilde(input) {
+  if (input === '~') return homedir()
+  if (input.startsWith('~/')) return join(homedir(), input.slice(2))
+  return input
+}
+
+// 📖 Resolve a raw config dir string to an absolute path with tilde support.
+function resolveConfigDir(raw) {
+  if (typeof raw !== 'string' || !raw.trim()) return null
+  const expanded = expandTilde(raw.trim())
+  return resolve(expanded)
+}
+
+// 📖 getConfigDir: Resolve the user-chosen config directory — set via the
+// 📖 `--config-dir <dir>` CLI flag or via FCM_CONFIG_DIR directly (Docker).
+// 📖 The CLI flag wins over the env var, and the env var wins over nothing.
+// 📖 Returns null so the default dotfile layout in $HOME keeps working unchanged.
+// 📖 NOTE: scanning process.argv here (rather than only trusting the env var)
+// 📖 matters because ESM static imports are hoisted — the bin entry's flag
+// 📖 handling runs after config.js is evaluated, so CONFIG_PATH must be able
+// 📖 to see `--config-dir` on its own.
+export function getConfigDir() {
+  const fromArgv = configDirFromArgv()
+  if (fromArgv) return fromArgv
+  return resolveConfigDir(process.env.FCM_CONFIG_DIR)
+}
+
+// 📖 Scan process.argv for `--config-dir <dir>` — the raw value before any
+// 📖 other arg parsing so module-load-time constants like CONFIG_PATH pick it up.
+function configDirFromArgv() {
+  const argv = process.argv || []
+  const idx = argv.indexOf('--config-dir')
+  if (idx === -1) return null
+  const raw = argv[idx + 1]
+  if (typeof raw !== 'string' || !raw.trim() || raw.startsWith('--')) return null
+  return resolveConfigDir(raw)
+}
+
+// 📖 New JSON config path — stores all providers' API keys + enabled state.
+// 📖 Overridable via `--config-dir <dir>`: config.json lives inside the chosen
+// 📖 directory (e.g. the XDG layout ~/.config/free-coding-models).
+export const CONFIG_PATH = getConfigDir()
+  ? join(getConfigDir(), 'config.json')
+  : join(homedir(), '.free-coding-models.json')
 export { ENV_VARS }
 
 // 📖 Runtime data directory — backups and local snapshots live here.
@@ -690,6 +734,11 @@ export function loadConfig() {
  * @returns {{ success: boolean, error?: string, backupCreated?: boolean }}
  */
 export function saveConfig(config, options = {}) {
+  // 📖 Ensure the config directory exists before first write (XDG first-run would otherwise ENOENT)
+  try {
+    const parentDir = dirname(CONFIG_PATH)
+    if (!existsSync(parentDir)) mkdirSync(parentDir, { mode: 0o700, recursive: true })
+  } catch { /* best-effort, write will surface the error */ }
   // 📖 Create backup of existing config before overwriting
   const backupCreated = createBackup()
   const tempPath = `${CONFIG_PATH}.tmp-${process.pid}-${Date.now()}`
@@ -815,6 +864,15 @@ export function formatPermissionHint(writeError) {
   return '\n' + lines.join('\n')
 }
 
+// 📖 getBackupsDir: Backup directory for config snapshots. Follows the chosen
+// 📖 config dir (`--config-dir` / FCM_CONFIG_DIR) so backups stay next to the
+// 📖 config file they protect; falls back to ~/.free-coding-models.backups.
+function getBackupsDir() {
+  return getConfigDir()
+    ? join(getConfigDir(), 'backups')
+    : join(homedir(), '.free-coding-models.backups')
+}
+
 /**
  * 📖 createBackup: Creates a timestamped backup of the current config file.
  * 📖 Keeps only the 5 most recent backups to avoid disk space issues.
@@ -829,7 +887,7 @@ function createBackup() {
     }
 
     // 📖 Create backup directory if it doesn't exist
-    const backupDir = join(homedir(), '.free-coding-models.backups')
+    const backupDir = getBackupsDir()
     if (!existsSync(backupDir)) {
       mkdirSync(backupDir, { mode: 0o700, recursive: true })
     }
@@ -876,7 +934,7 @@ function createBackup() {
  * @throws {Error} if no backup exists or restoration fails
  */
 function restoreFromBackup() {
-  const backupDir = join(homedir(), '.free-coding-models.backups')
+  const backupDir = getBackupsDir()
   
   if (!existsSync(backupDir)) {
     throw new Error('No backup directory found')

package/src/core/security.js

@@ -35,10 +35,12 @@ import fs from 'node:fs'
 import path from 'node:path'
 import os from 'node:os'
 import readline from 'node:readline'
+import { CONFIG_PATH } from './config.js'
 
-// 📖 Config file path — matches the path used in config.js
+// 📖 Config file path — matches the path used in config.js (honours the
+// 📖 --config-dir / FCM_CONFIG_DIR override when set).
 function getConfigPath() {
-  return path.join(os.homedir(), '.free-coding-models.json')
+  return CONFIG_PATH
 }
 
 // 📖 Secure file permissions: user read/write only (0o600 = 384 in decimal)

package/src/core/utils.js

@@ -465,6 +465,8 @@ export function findBestModel(results) {
 //     --reprobe / --no-cache (boolean) — force-rebuild the probe cache this run
 //     --probe-ttl <ms> (value)          — override the 24h default TTL
 //     --show-broken (boolean)           — don't auto-hide broken models (one-shot)
+//   - Config location flag:
+//     --config-dir <dir> (value)        — override where config.json + backups/ live
 //
 // Returns:
 //   { apiKey, bestMode, fiableMode, openCodeMode, openCodeDesktopMode, openCodeWebMode, openClawMode,
@@ -512,6 +514,14 @@ export function parseArgs(argv) {
     ? syncSetIdx + 1
     : -1
 
+  // 📖 --config-dir <dir> — override where FCM's config files (config.json + backups/)
+  // 📖 live. Any directory works, e.g. --config-dir ~/.config/free-coding-models for the
+  // 📖 XDG layout. The bin entry point persists this as FCM_CONFIG_DIR before imports.
+  const configDirIdx = args.findIndex(a => a.toLowerCase() === '--config-dir')
+  const configDirValueIdx = (configDirIdx !== -1 && args[configDirIdx + 1] && !args[configDirIdx + 1].startsWith('--'))
+    ? configDirIdx + 1
+    : -1
+
   // 📖 Set of arg indices that are values for flags (not API keys)
   const skipIndices = new Set()
   if (tierValueIdx !== -1) skipIndices.add(tierValueIdx)
@@ -520,6 +530,7 @@ export function parseArgs(argv) {
   if (pingIntervalValueIdx !== -1) skipIndices.add(pingIntervalValueIdx)
   if (syncSetValueIdx !== -1) skipIndices.add(syncSetValueIdx)
   if (probeTtlValueIdx !== -1) skipIndices.add(probeTtlValueIdx)
+  if (configDirValueIdx !== -1) skipIndices.add(configDirValueIdx)
 
   for (const [i, arg] of args.entries()) {
     if (arg.startsWith('--') || arg === '-h') {
@@ -673,6 +684,8 @@ export function parseArgs(argv) {
     showBrokenMode,
     // 📖 Runtime telemetry flag (t3) — see src/core/runtime-telemetry.js
     clearRuntimeMode,
+    // 📖 Config location flag — see src/core/config.js getConfigDir()
+    configDir: configDirValueIdx !== -1 ? args[configDirValueIdx] : null,
   }
 }
 

package/src/tui/cli-help.js

@@ -48,6 +48,7 @@ const CONFIG_FLAGS = [
   { flag: '--daemon-status', description: 'Print FCM Router daemon status JSON' },
   { flag: '--daemon-stop', description: 'Gracefully stop the FCM Router daemon' },
   { flag: '--sync-set [name]', description: 'Auto-discover and live-probe models into a router set' },
+  { flag: '--config-dir <dir>', description: 'Store config.json + backups/ in <dir> (e.g. --config-dir ~/.config/free-coding-models for the XDG layout)' },
   { flag: '--no-telemetry', description: 'Disable anonymous telemetry for this run' },
   { flag: '--help, -h', description: 'Print this help and exit' },
 ]