free-coding-models 0.2.4 → 0.2.8

package/src/security.js

@@ -0,0 +1,210 @@
+/**
+ * @file security.js
+ * @description Security checks and auto-fix for config file permissions.
+ *
+ * 📖 Problem: API keys stored in ~/.free-coding-models.json must be protected.
+ *    If the file has incorrect permissions (e.g., 644 = world-readable), keys can leak.
+ *
+ * 📖 This module:
+ *    - Checks config file permissions on startup
+ *    - Warns user if permissions are too open
+ *    - Offers auto-fix option with user confirmation
+ *    - Fixes permissions securely (chmod 600 = user read/write only)
+ *
+ * 📖 Secure permissions:
+ *    - 0o600 (octal 600) = user:rw, group:---, world:---
+ *    - Only the file owner can read or write
+ *    - This is the standard for files containing secrets (SSH keys, API keys, etc.)
+ *
+ * 📖 Why this matters:
+ *    - Shared systems: Other users could read your API keys
+ *    - Git accidents: File could be committed with wrong permissions
+ *    - Backup tools: Might copy files with permissions intact
+ *
+ * @functions
+ *   → checkConfigSecurity() — Main security check, prompts for auto-fix if needed
+ *   → getConfigPermissions() — Returns file mode object for config
+ *   → isConfigSecure() — Boolean check if permissions are correct
+ *   → fixConfigPermissions() — Applies chmod 600 to config file
+ *   → promptSecurityFix() — Interactive prompt asking user to fix permissions
+ *
+ * @exports checkConfigSecurity, isConfigSecure, fixConfigPermissions
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import readline from 'node:readline'
+
+// 📖 Config file path — matches the path used in config.js
+function getConfigPath() {
+  return path.join(os.homedir(), '.free-coding-models.json')
+}
+
+// 📖 Secure file permissions: user read/write only (0o600 = 384 in decimal)
+// 📖 This means: owner can read+write, group and others have no permissions
+const SECURE_MODE = 0o600
+
+// 📖 Get file stats including permissions for the config file
+// 📖 Returns null if file doesn't exist
+function getConfigPermissions() {
+  const configPath = getConfigPath()
+
+  try {
+    if (!fs.existsSync(configPath)) {
+      return null
+    }
+
+    const stats = fs.statSync(configPath)
+    return {
+      mode: stats.mode,
+      isSecure: (stats.mode & 0o777) === SECURE_MODE,
+      path: configPath
+    }
+  } catch (err) {
+    return null
+  }
+}
+
+// 📖 Check if config file has secure permissions
+// 📖 Returns true if file doesn't exist (nothing to secure) or if permissions are correct
+export function isConfigSecure() {
+  const perms = getConfigPermissions()
+
+  // 📖 No file = nothing to secure
+  if (!perms) return true
+
+  return perms.isSecure
+}
+
+// 📖 Fix config file permissions to secure mode (chmod 600)
+// 📖 Returns true if successful, false otherwise
+export function fixConfigPermissions() {
+  const configPath = getConfigPath()
+
+  try {
+    if (!fs.existsSync(configPath)) {
+      return false
+    }
+
+    fs.chmodSync(configPath, SECURE_MODE)
+    return true
+  } catch (err) {
+    return false
+  }
+}
+
+// 📖 Format permission mode in octal (e.g., 0o644 → "644")
+function formatMode(mode) {
+  return (mode & 0o777).toString(8).padStart(3, '0')
+}
+
+// 📖 Format permission mode in human-readable rwx format (e.g., 0o644 → "rw-r--r--")
+function formatModeRwx(mode) {
+  const perms = []
+  const types = ['r', 'w', 'x']
+
+  for (let i = 6; i >= 0; i -= 3) {
+    for (let j = 0; j < 3; j++) {
+      if (mode & (1 << (i + j))) {
+        perms.push(types[j])
+      } else {
+        perms.push('-')
+      }
+    }
+  }
+
+  return [
+    perms.slice(0, 3).join(''),  // Owner permissions
+    perms.slice(3, 6).join(''),  // Group permissions
+    perms.slice(6, 9).join('')   // Others permissions
+  ].join(' / ')
+}
+
+// 📖 Check security and prompt for auto-fix if needed
+// 📖 Call this on startup before loading config
+// 📖 Returns: { wasSecure: boolean, wasFixed: boolean, error?: string }
+export function checkConfigSecurity() {
+  const perms = getConfigPermissions()
+
+  // 📖 No file yet = nothing to check
+  if (!perms) {
+    return { wasSecure: true, wasFixed: false }
+  }
+
+  // 📖 Permissions are already secure
+  if (perms.isSecure) {
+    return { wasSecure: true, wasFixed: false }
+  }
+
+  // 📖 Security issue detected! Show warning and offer fix.
+  const currentMode = formatMode(perms.mode)
+  const currentRwx = formatModeRwx(perms.mode)
+
+  console.error('')
+  console.error('⚠️  SECURITY WARNING ⚠️')
+  console.error('')
+  console.error(`Your config file has insecure permissions: ${currentMode} (${currentRwx})`)
+  console.error(`File: ${perms.path}`)
+  console.error('')
+  console.error('This means other users on this system may be able to read your API keys.')
+  console.error('')
+  console.error('Recommended: Fix permissions to 600 (rw-------) — owner read/write only')
+
+  return promptSecurityFix()
+}
+
+// 📖 Interactive prompt asking user if they want to auto-fix
+// 📖 Returns: { wasSecure: boolean, wasFixed: boolean, error?: string }
+async function promptSecurityFix() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  })
+
+  try {
+    const answer = await new Promise((resolve) => {
+      rl.question('Fix permissions automatically? (Y/n): ', resolve)
+    })
+
+    rl.close()
+
+    // 📖 Default to yes if user just presses Enter
+    if (answer.toLowerCase() === 'y' || answer === '') {
+      const success = fixConfigPermissions()
+
+      if (success) {
+        console.error('')
+        console.error('✅ Permissions fixed! Your API keys are now secure.')
+        console.error('')
+        return { wasSecure: false, wasFixed: true }
+      } else {
+        console.error('')
+        console.error('❌ Failed to fix permissions automatically.')
+        console.error('')
+        console.error('Run this command manually:')
+        console.error(`  chmod 600 ${getConfigPath()}`)
+        console.error('')
+        return { wasSecure: false, wasFixed: false, error: 'chmod_failed' }
+      }
+    } else {
+      console.error('')
+      console.error('⚠️  Permissions not fixed. Your API keys may be at risk.')
+      console.error('')
+      console.error('To fix later, run:')
+      console.error(`  chmod 600 ${getConfigPath()}`)
+      console.error('')
+      return { wasSecure: false, wasFixed: false, error: 'user_declined' }
+    }
+  } catch (err) {
+    rl.close()
+    // 📖 If we can't prompt (e.g., non-interactive TTY), just warn and continue
+    console.error('')
+    console.error('⚠️  Unable to prompt for permission fix (non-interactive terminal?)')
+    console.error('')
+    console.error('To fix manually, run:')
+    console.error(`  chmod 600 ${getConfigPath()}`)
+    console.error('')
+    return { wasSecure: false, wasFixed: false, error: 'no_tty' }
+  }
+}

package/src/tool-launchers.js

@@ -32,6 +32,7 @@ import { homedir } from 'os'
 import { dirname, join } from 'path'
 import { spawn } from 'child_process'
 import { sources } from '../sources.js'
+import { PROVIDER_COLOR } from './render-table.js'
 import { getApiKey, getProxySettings } from './config.js'
 import { ENV_VAR_NAMES, isWindows } from './provider-metadata.js'
 import { getToolMeta } from './tool-metadata.js'
@@ -262,7 +263,11 @@ export async function startExternalTool(mode, model, config) {
   const proxySettings = getProxySettings(config)
 
   if (!apiKey && mode !== 'amp') {
-    console.log(chalk.yellow(`  ⚠ No API key configured for ${model.providerKey}.`))
+    // 📖 Color provider name the same way as in the main table
+    const providerRgb = PROVIDER_COLOR[model.providerKey] ?? [105, 190, 245]
+    const providerName = sources[model.providerKey]?.name || model.providerKey
+    const coloredProviderName = chalk.bold.rgb(...providerRgb)(providerName)
+    console.log(chalk.yellow(`  ⚠ No API key configured for ${coloredProviderName}.`))
     console.log(chalk.dim('  Configure the provider first from the Settings screen (P) or via env vars.'))
     console.log()
     return 1

package/src/utils.js

@@ -389,13 +389,13 @@ export function findBestModel(results) {
 //   - API key: first positional arg that doesn't start with "--" (e.g., "nvapi-xxx")
 //   - Boolean flags: --best, --fiable, --opencode, --opencode-desktop, --openclaw,
 //     --aider, --crush, --goose, --claude-code, --codex, --gemini, --qwen,
-//     --openhands, --amp, --pi, --no-telemetry (case-insensitive)
+//     --openhands, --amp, --pi, --no-telemetry, --json (case-insensitive)
 //   - Value flag: --tier <letter> (the next non-flag arg is the tier value)
 //
 // 📖 Returns:
 //   { apiKey, bestMode, fiableMode, openCodeMode, openCodeDesktopMode, openClawMode,
 //     aiderMode, crushMode, gooseMode, claudeCodeMode, codexMode, geminiMode,
-//     qwenMode, openHandsMode, ampMode, piMode, noTelemetry, tierFilter }
+//     qwenMode, openHandsMode, ampMode, piMode, noTelemetry, jsonMode, tierFilter }
 //
 // 📖 Note: apiKey may be null here — the main CLI falls back to env vars and saved config.
 export function parseArgs(argv) {
@@ -446,6 +446,7 @@ export function parseArgs(argv) {
   const piMode = flags.includes('--pi')
   const noTelemetry = flags.includes('--no-telemetry')
   const cleanProxyMode = flags.includes('--clean-proxy') || flags.includes('--proxy-clean')
+  const jsonMode = flags.includes('--json')
 
   let tierFilter = tierValueIdx !== -1 ? args[tierValueIdx].toUpperCase() : null
 
@@ -473,6 +474,7 @@ export function parseArgs(argv) {
     piMode,
     noTelemetry,
     cleanProxyMode,
+    jsonMode,
     tierFilter,
     profileName,
     recommendMode
@@ -728,3 +730,66 @@ export function getVersionStatusInfo(updateState, latestVersion) {
     latestVersion: null,
   }
 }
+
+/**
+ * 📖 formatResultsAsJSON converts model results to clean JSON output for scripting/automation.
+ *
+ * 📖 This is used by the --json flag to output results in a machine-readable format.
+ * 📖 The output is designed to be:
+ *    - Easy to parse with jq, grep, awk, or any JSON library
+ *    - Human-readable for debugging
+ *    - Stable (field names won't change between versions)
+ *
+ * 📖 Output format:
+ *   [
+ *     {
+ *       "rank": 1,
+ *       "modelId": "nvidia/deepseek-ai/deepseek-v3.2",
+ *       "label": "DeepSeek V3.2",
+ *       "provider": "nvidia",
+ *       "tier": "S+",
+ *       "sweScore": "73.1%",
+ *       "context": "128k",
+ *       "latestPing": 245,
+ *       "avgPing": 260,
+ *       "p95": 312,
+ *       "jitter": 45,
+ *       "stability": 87,
+ *       "uptime": 95.5,
+ *       "verdict": "Perfect",
+ *       "status": "up"
+ *     },
+ *     ...
+ *   ]
+ *
+ * 📖 Note: NaN and Infinity values are converted to null for cleaner JSON.
+ *
+ * @param {Array} results — Model result objects from the TUI
+ * @param {string} sortBy — Current sort column (for rank calculation)
+ * @param {number} limit — Maximum number of results to return (0 = all)
+ * @returns {string} JSON string of formatted results
+ */
+export function formatResultsAsJSON(results, sortBy = 'avg', limit = 0) {
+  const formatted = results
+    .map((r, idx) => ({
+      rank: r.idx || idx + 1,
+      modelId: r.modelId || null,
+      label: r.label || null,
+      provider: r.providerKey || null,
+      tier: r.tier || null,
+      sweScore: r.sweScore || null,
+      context: r.ctx || null,
+      latestPing: (r.pings && r.pings.length > 0) ? r.pings[r.pings.length - 1].ms : null,
+      avgPing: (Number.isFinite(r.avg)) ? r.avg : null,
+      p95: (Number.isFinite(r.p95)) ? r.p95 : null,
+      jitter: (Number.isFinite(r.jitter)) ? r.jitter : null,
+      stability: (Number.isFinite(r.stability)) ? r.stability : null,
+      uptime: (Number.isFinite(r.uptime)) ? r.uptime : null,
+      verdict: r.verdict || null,
+      status: r.status || null,
+      httpCode: r.httpCode || null
+    }))
+    .slice(0, limit || undefined)
+
+  return JSON.stringify(formatted, null, 2)
+}