free-coding-models 0.1.83 → 0.1.84

package/src/updater.js

@@ -0,0 +1,237 @@
+/**
+ * @file updater.js
+ * @description Update detection and installation helpers, extracted from bin/free-coding-models.js.
+ *
+ * @details
+ *   This module handles all npm version-check and auto-update logic:
+ *
+ *   - `checkForUpdateDetailed()` — hits the npm registry to compare the published version
+ *     against the locally installed one.  Returns `{ latestVersion, error }` so callers
+ *     can surface meaningful status text in the Settings overlay.
+ *
+ *   - `checkForUpdate()` — thin backward-compatible wrapper used at startup for the
+ *     auto-update guard.  Returns `latestVersion` (string) or `null`.
+ *
+ *   - `runUpdate(latestVersion)` — runs `npm i -g free-coding-models@<version> --prefer-online`,
+ *     retrying with `sudo` on EACCES/EPERM.  On success, relaunches the process with the
+ *     same argv.  On failure, prints manual instructions and exits with code 1.
+ *     Uses `require('child_process').execSync` inline because ESM dynamic import is async
+ *     but `execSync` must block to give `stdio: 'inherit'` feedback in the terminal.
+ *
+ *   - `promptUpdateNotification(latestVersion)` — renders a small centered interactive menu
+ *     that lets the user choose: Update Now / Read Changelogs / Continue without update.
+ *     Uses raw mode readline keypress events (same pattern as the main TUI).
+ *     This function is called BEFORE the alt-screen is entered, so it writes to the
+ *     normal terminal buffer.
+ *
+ *   ⚙️ Notes:
+ *   - `LOCAL_VERSION` is resolved from package.json via `createRequire` so this module
+ *     can be imported independently from the bin entry point.
+ *   - The auto-update flow in `main()` skips update if `isDevMode` is detected (presence of
+ *     a `.git` directory next to the package root) to avoid an infinite update loop in dev.
+ *
+ * @functions
+ *   → checkForUpdateDetailed()           — Fetch npm latest with explicit error info
+ *   → checkForUpdate()                   — Startup wrapper, returns version string or null
+ *   → runUpdate(latestVersion)           — Install new version via npm global + relaunch
+ *   → promptUpdateNotification(version)  — Interactive pre-TUI update menu
+ *
+ * @exports
+ *   checkForUpdateDetailed, checkForUpdate, runUpdate, promptUpdateNotification
+ *
+ * @see bin/free-coding-models.js — calls checkForUpdate() at startup and runUpdate() on confirm
+ */
+
+import chalk from 'chalk'
+import { createRequire } from 'module'
+
+const require = createRequire(import.meta.url)
+const readline = require('readline')
+const pkg = require('../package.json')
+const LOCAL_VERSION = pkg.version
+
+/**
+ * 📖 checkForUpdateDetailed: Fetch npm latest version with explicit error details.
+ * 📖 Used by settings manual-check flow to display meaningful status in the UI.
+ * @returns {Promise<{ latestVersion: string|null, error: string|null }>}
+ */
+export async function checkForUpdateDetailed() {
+  try {
+    const res = await fetch('https://registry.npmjs.org/free-coding-models/latest', { signal: AbortSignal.timeout(5000) })
+    if (!res.ok) return { latestVersion: null, error: `HTTP ${res.status}` }
+    const data = await res.json()
+    if (data.version && data.version !== LOCAL_VERSION) return { latestVersion: data.version, error: null }
+    return { latestVersion: null, error: null }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error'
+    return { latestVersion: null, error: message }
+  }
+}
+
+/**
+ * 📖 checkForUpdate: Backward-compatible wrapper for startup update prompt.
+ * @returns {Promise<string|null>}
+ */
+export async function checkForUpdate() {
+  const { latestVersion } = await checkForUpdateDetailed()
+  return latestVersion
+}
+
+/**
+ * 📖 runUpdate: Run npm global install to update to latestVersion.
+ * 📖 Retries with sudo on permission errors.
+ * 📖 Relaunches the process on success, exits with code 1 on failure.
+ * @param {string} latestVersion
+ */
+export function runUpdate(latestVersion) {
+  const { execSync } = require('child_process')
+  console.log()
+  console.log(chalk.bold.cyan('  ⬆ Updating free-coding-models to v' + latestVersion + '...'))
+  console.log()
+
+  try {
+    // 📖 Force install from npm registry (ignore local cache)
+    // 📖 Use --prefer-online to ensure we get the latest published version
+    execSync(`npm i -g free-coding-models@${latestVersion} --prefer-online`, { stdio: 'inherit' })
+    console.log()
+    console.log(chalk.green('  ✅ Update complete! Version ' + latestVersion + ' installed.'))
+    console.log()
+    console.log(chalk.dim('  🔄 Restarting with new version...'))
+    console.log()
+
+    // 📖 Relaunch automatically with the same arguments
+    const args = process.argv.slice(2)
+    execSync(`node ${process.argv[1]} ${args.join(' ')}`, { stdio: 'inherit' })
+    process.exit(0)
+  } catch (err) {
+    console.log()
+    // 📖 Check if error is permission-related (EACCES or EPERM)
+    const isPermissionError = err.code === 'EACCES' || err.code === 'EPERM' ||
+                             (err.stderr && (err.stderr.includes('EACCES') || err.stderr.includes('permission') ||
+                                              err.stderr.includes('EACCES'))) ||
+                             (err.message && (err.message.includes('EACCES') || err.message.includes('permission')))
+
+    if (isPermissionError) {
+      console.log(chalk.yellow('  ⚠️ Permission denied. Retrying with sudo...'))
+      console.log()
+      try {
+        execSync(`sudo npm i -g free-coding-models@${latestVersion} --prefer-online`, { stdio: 'inherit' })
+        console.log()
+        console.log(chalk.green('  ✅ Update complete with sudo! Version ' + latestVersion + ' installed.'))
+        console.log()
+        console.log(chalk.dim('  🔄 Restarting with new version...'))
+        console.log()
+
+        // 📖 Relaunch automatically with the same arguments
+        const args = process.argv.slice(2)
+        execSync(`node ${process.argv[1]} ${args.join(' ')}`, { stdio: 'inherit' })
+        process.exit(0)
+      } catch (sudoErr) {
+        console.log()
+        console.log(chalk.red('  ✖ Update failed even with sudo. Try manually:'))
+        console.log(chalk.dim('    sudo npm i -g free-coding-models@' + latestVersion))
+        console.log()
+      }
+    } else {
+      console.log(chalk.red('  ✖ Update failed. Try manually: npm i -g free-coding-models@' + latestVersion))
+      console.log()
+    }
+  }
+  process.exit(1)
+}
+
+/**
+ * 📖 promptUpdateNotification: Show a centered interactive menu when a new version is available.
+ * 📖 Returns 'update', 'changelogs', or null (continue without update).
+ * 📖 Called BEFORE entering the alt-screen so it renders in the normal terminal buffer.
+ * @param {string|null} latestVersion
+ * @returns {Promise<'update'|'changelogs'|null>}
+ */
+export async function promptUpdateNotification(latestVersion) {
+  if (!latestVersion) return null
+
+  return new Promise((resolve) => {
+    let selected = 0
+    const options = [
+      {
+        label: 'Update now',
+        icon: '⬆',
+        description: `Update free-coding-models to v${latestVersion}`,
+      },
+      {
+        label: 'Read Changelogs',
+        icon: '📋',
+        description: 'Open GitHub changelog',
+      },
+      {
+        label: 'Continue without update',
+        icon: '▶',
+        description: 'Use current version',
+      },
+    ]
+
+    // 📖 Centered render function
+    const render = () => {
+      process.stdout.write('\x1b[2J\x1b[H') // clear screen + cursor home
+
+      // 📖 Calculate centering
+      const terminalWidth = process.stdout.columns || 80
+      const maxWidth = Math.min(terminalWidth - 4, 70)
+      const centerPad = ' '.repeat(Math.max(0, Math.floor((terminalWidth - maxWidth) / 2)))
+
+      console.log()
+      console.log(centerPad + chalk.bold.red('  ⚠ UPDATE AVAILABLE'))
+      console.log(centerPad + chalk.red(`  Version ${latestVersion} is ready to install`))
+      console.log()
+      console.log(centerPad + chalk.bold('  ⚡ Free Coding Models') + chalk.dim(` v${LOCAL_VERSION}`))
+      console.log()
+
+      for (let i = 0; i < options.length; i++) {
+        const isSelected = i === selected
+        const bullet = isSelected ? chalk.bold.cyan('  ❯ ') : chalk.dim('    ')
+        const label = isSelected
+          ? chalk.bold.white(options[i].icon + ' ' + options[i].label)
+          : chalk.dim(options[i].icon + ' ' + options[i].label)
+
+        console.log(centerPad + bullet + label)
+        console.log(centerPad + chalk.dim('       ' + options[i].description))
+        console.log()
+      }
+
+      console.log(centerPad + chalk.dim('  ↑↓ Navigate  •  Enter Select  •  Ctrl+C Continue'))
+      console.log()
+    }
+
+    render()
+
+    readline.emitKeypressEvents(process.stdin)
+    if (process.stdin.isTTY) process.stdin.setRawMode(true)
+
+    const onKey = (_str, key) => {
+      if (!key) return
+      if (key.ctrl && key.name === 'c') {
+        if (process.stdin.isTTY) process.stdin.setRawMode(false)
+        process.stdin.removeListener('keypress', onKey)
+        resolve(null) // Continue without update
+        return
+      }
+      if (key.name === 'up' && selected > 0) {
+        selected--
+        render()
+      } else if (key.name === 'down' && selected < options.length - 1) {
+        selected++
+        render()
+      } else if (key.name === 'return') {
+        if (process.stdin.isTTY) process.stdin.setRawMode(false)
+        process.stdin.removeListener('keypress', onKey)
+        process.stdin.pause()
+
+        if (selected === 0) resolve('update')
+        else if (selected === 1) resolve('changelogs')
+        else resolve(null) // Continue without update
+      }
+    }
+
+    process.stdin.on('keypress', onKey)
+  })
+}

package/{lib → src}/usage-reader.js

@@ -1,9 +1,13 @@
 /**
  * @file lib/usage-reader.js
- * @description Pure functions to read model quota usage from token-stats.json.
+ * @description Pure functions to read provider-scoped Usage snapshots from token-stats.json.
  *
- * Designed for TUI consumption: reads the pre-computed `quotaSnapshots.byModel`
- * section from the JSON file written by TokenStats.  Never reads the JSONL log.
+ * Designed for TUI consumption: reads the pre-computed provider-scoped quota
+ * snapshots written by TokenStats. Never reads the JSONL log.
+ *
+ * The UI must distinguish the same model served by different Origins
+ * (for example NVIDIA vs Groq). Because of that, the canonical snapshot source
+ * is `quotaSnapshots.byProviderModel`, not the legacy `byModel` aggregate.
  *
  * All functions are pure (no shared mutable state) and handle missing/malformed
  * files gracefully by returning safe fallback values.
@@ -30,6 +34,7 @@
  * @exports CACHE_TTL_MS
  * @exports clearUsageCache
  * @exports loadUsageSnapshot
+ * @exports buildUsageSnapshotKey
  * @exports loadUsageMap
  * @exports usageForModelId
  * @exports usageForRow
@@ -38,6 +43,7 @@
 import { readFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
+import { supportsUsagePercent, usageResetsDaily } from './quota-capabilities.js'
 
 const DEFAULT_STATS_FILE = join(homedir(), '.free-coding-models', 'token-stats.json')
 
@@ -57,7 +63,7 @@ export const CACHE_TTL_MS = 750
 
 /**
  * Module-level cache: path → { snapshot, expiresAt }
- * @type {Map<string, { snapshot: { byModel: Record<string, number>, byProvider: Record<string, number> }, expiresAt: number }>}
+ * @type {Map<string, { snapshot: { byProviderModel: Record<string, number>, byProvider: Record<string, number>, legacyByModel: Record<string, number> }, expiresAt: number }>}
  */
 const _cache = new Map()
 
@@ -81,13 +87,29 @@ export function clearUsageCache() {
  * @param {number} [nowMs] - optional current time (ms) for testability
  * @returns {boolean}
  */
-function isSnapshotFresh(entry, nowMs = Date.now()) {
+function isSnapshotFresh(entry, nowMs = Date.now(), providerKey = null) {
   if (!entry || typeof entry.updatedAt !== 'string') return true // backward compat
   const updatedMs = Date.parse(entry.updatedAt)
   if (!Number.isFinite(updatedMs)) return true // unparseable: be generous
+  if (providerKey && usageResetsDaily(providerKey)) {
+    const nowDay = new Date(nowMs).toISOString().slice(0, 10)
+    const updatedDay = entry.updatedAt.slice(0, 10)
+    if (updatedDay !== nowDay) return false
+  }
   return nowMs - updatedMs < SNAPSHOT_TTL_MS
 }
 
+/**
+ * Build the canonical map key for one Origin + model pair.
+ *
+ * @param {string} providerKey
+ * @param {string} modelId
+ * @returns {string}
+ */
+export function buildUsageSnapshotKey(providerKey, modelId) {
+  return `${providerKey}::${modelId}`
+}
+
 /**
  * Load token-stats.json and return model/provider usage maps.
  * Entries with stale `updatedAt` (older than SNAPSHOT_TTL_MS) are excluded.
@@ -96,7 +118,7 @@ function isSnapshotFresh(entry, nowMs = Date.now()) {
  * The 30-minute data freshness filter is re-applied on every cache miss (parse).
  *
  * @param {string} [statsFile]
- * @returns {{ byModel: Record<string, number>, byProvider: Record<string, number> }}
+ * @returns {{ byProviderModel: Record<string, number>, byProvider: Record<string, number>, legacyByModel: Record<string, number> }}
  */
 export function loadUsageSnapshot(statsFile = DEFAULT_STATS_FILE) {
   const now = Date.now()
@@ -118,23 +140,40 @@ export function loadUsageSnapshot(statsFile = DEFAULT_STATS_FILE) {
  *
  * @param {string} statsFile
  * @param {number} now - current time in ms (for freshness checks)
- * @returns {{ byModel: Record<string, number>, byProvider: Record<string, number> }}
+ * @returns {{ byProviderModel: Record<string, number>, byProvider: Record<string, number>, legacyByModel: Record<string, number> }}
  */
 function _parseSnapshot(statsFile, now) {
   try {
-    if (!existsSync(statsFile)) return { byModel: {}, byProvider: {} }
+    if (!existsSync(statsFile)) return { byProviderModel: {}, byProvider: {}, legacyByModel: {} }
     const raw = readFileSync(statsFile, 'utf8')
     const data = JSON.parse(raw)
 
+    const byProviderModelSrc = data?.quotaSnapshots?.byProviderModel
     const byModelSrc = data?.quotaSnapshots?.byModel
     const byProviderSrc = data?.quotaSnapshots?.byProvider
 
-    const byModel = {}
+    const byProviderModel = {}
+    if (byProviderModelSrc && typeof byProviderModelSrc === 'object') {
+      for (const [snapshotKey, entry] of Object.entries(byProviderModelSrc)) {
+        const providerKey = typeof entry?.providerKey === 'string'
+          ? entry.providerKey
+          : snapshotKey.split('::', 1)[0]
+        if (!supportsUsagePercent(providerKey)) continue
+        if (entry && typeof entry.quotaPercent === 'number' && Number.isFinite(entry.quotaPercent)) {
+          if (isSnapshotFresh(entry, now, providerKey)) {
+            byProviderModel[snapshotKey] = entry.quotaPercent
+          }
+        }
+      }
+    }
+
+    // 📖 Legacy map kept only for backward compatibility helpers/tests.
+    const legacyByModel = {}
     if (byModelSrc && typeof byModelSrc === 'object') {
       for (const [modelId, entry] of Object.entries(byModelSrc)) {
         if (entry && typeof entry.quotaPercent === 'number' && Number.isFinite(entry.quotaPercent)) {
           if (isSnapshotFresh(entry, now)) {
-            byModel[modelId] = entry.quotaPercent
+            legacyByModel[modelId] = entry.quotaPercent
           }
         }
       }
@@ -143,44 +182,45 @@ function _parseSnapshot(statsFile, now) {
     const byProvider = {}
     if (byProviderSrc && typeof byProviderSrc === 'object') {
       for (const [providerKey, entry] of Object.entries(byProviderSrc)) {
+        if (!supportsUsagePercent(providerKey)) continue
         if (entry && typeof entry.quotaPercent === 'number' && Number.isFinite(entry.quotaPercent)) {
-          if (isSnapshotFresh(entry, now)) {
+          if (isSnapshotFresh(entry, now, providerKey)) {
             byProvider[providerKey] = entry.quotaPercent
           }
         }
       }
     }
 
-    return { byModel, byProvider }
+    return { byProviderModel, byProvider, legacyByModel }
   } catch {
-    return { byModel: {}, byProvider: {} }
+    return { byProviderModel: {}, byProvider: {}, legacyByModel: {} }
   }
 }
 
 /**
- * Load token-stats.json and return a plain object mapping modelId → quotaPercent.
+ * Load token-stats.json and return a plain object mapping provider+model → quotaPercent.
  *
  * Only includes models whose `quotaPercent` is a finite number and whose
  * snapshot is fresh (within SNAPSHOT_TTL_MS).
  * Returns an empty object on any error (missing file, bad JSON, missing keys).
  *
  * @param {string} [statsFile] - Path to token-stats.json (defaults to ~/.free-coding-models/token-stats.json)
- * @returns {Record<string, number>}  e.g. { 'claude-3-5': 80, 'gpt-4o': 45 }
+ * @returns {Record<string, number>}  e.g. { 'groq::openai/gpt-oss-120b': 37 }
  */
 export function loadUsageMap(statsFile = DEFAULT_STATS_FILE) {
-  return loadUsageSnapshot(statsFile).byModel
+  return loadUsageSnapshot(statsFile).byProviderModel
 }
 
 /**
- * Return the quota percent remaining for a specific model.
- * Returns null if the model has no snapshot or its snapshot is stale.
+ * Return the legacy quota percent remaining for a specific modelId.
+ * This helper is retained for backward compatibility tests only.
  *
  * @param {string} modelId
  * @param {string} [statsFile] - Path to token-stats.json (defaults to ~/.free-coding-models/token-stats.json)
  * @returns {number | null}  quota percent (0–100), or null if unknown/stale
  */
 export function usageForModelId(modelId, statsFile = DEFAULT_STATS_FILE) {
-  const map = loadUsageMap(statsFile)
+  const map = loadUsageSnapshot(statsFile).legacyByModel
   const value = map[modelId]
   return value !== undefined ? value : null
 }
@@ -196,8 +236,10 @@ export function usageForModelId(modelId, statsFile = DEFAULT_STATS_FILE) {
  * @returns {number | null}
  */
 export function usageForRow(providerKey, modelId, statsFile = DEFAULT_STATS_FILE) {
-  const { byModel, byProvider } = loadUsageSnapshot(statsFile)
-  if (byModel[modelId] !== undefined) return byModel[modelId]
+  if (!supportsUsagePercent(providerKey)) return null
+  const { byProviderModel, byProvider } = loadUsageSnapshot(statsFile)
+  const providerModelKey = buildUsageSnapshotKey(providerKey, modelId)
+  if (byProviderModel[providerModelKey] !== undefined) return byProviderModel[providerModelKey]
   if (byProvider[providerKey] !== undefined) return byProvider[providerKey]
   return null
 }

package/lib/quota-capabilities.js

@@ -1,79 +0,0 @@
-/**
- * @file lib/quota-capabilities.js
- * @description Provider quota telemetry capability map.
- *
- * Describes how we can observe quota state for each provider:
- * - header:   Provider sends x-ratelimit-remaining / x-ratelimit-limit headers
- * - endpoint: Provider has a dedicated usage/quota REST endpoint we can poll
- * - unknown:  No reliable quota signal available
- *
- * supportsEndpoint (optional, for openrouter/siliconflow):
- *   true  — provider has a known usage endpoint
- *   false — no endpoint, header-only or unknown
- *
- * @exports PROVIDER_CAPABILITIES — full map keyed by providerKey (matches sources.js)
- * @exports getQuotaTelemetry(providerKey) — returns capability object (defaults to unknown)
- * @exports isKnownQuotaTelemetry(providerKey) — true when telemetryType !== 'unknown'
- */
-
-/**
- * @typedef {Object} ProviderCapability
- * @property {'header'|'endpoint'|'unknown'} telemetryType
- * @property {boolean} [supportsEndpoint]
- */
-
-/** @type {Record<string, ProviderCapability>} */
-export const PROVIDER_CAPABILITIES = {
-  // Providers that return x-ratelimit-remaining / x-ratelimit-limit headers
-  nvidia: { telemetryType: 'header', supportsEndpoint: false },
-  groq: { telemetryType: 'header', supportsEndpoint: false },
-  cerebras: { telemetryType: 'header', supportsEndpoint: false },
-  sambanova: { telemetryType: 'header', supportsEndpoint: false },
-  deepinfra: { telemetryType: 'header', supportsEndpoint: false },
-  fireworks: { telemetryType: 'header', supportsEndpoint: false },
-  together: { telemetryType: 'header', supportsEndpoint: false },
-  hyperbolic: { telemetryType: 'header', supportsEndpoint: false },
-  scaleway: { telemetryType: 'header', supportsEndpoint: false },
-  googleai: { telemetryType: 'header', supportsEndpoint: false },
-  codestral: { telemetryType: 'header', supportsEndpoint: false },
-  perplexity: { telemetryType: 'header', supportsEndpoint: false },
-  qwen: { telemetryType: 'header', supportsEndpoint: false },
-
-  // Providers that have a dedicated usage/credits endpoint
-  openrouter: { telemetryType: 'endpoint', supportsEndpoint: true },
-  siliconflow: { telemetryType: 'endpoint', supportsEndpoint: true },
-
-  // Providers with no reliable quota signal
-  huggingface: { telemetryType: 'unknown', supportsEndpoint: false },
-  replicate: { telemetryType: 'unknown', supportsEndpoint: false },
-  cloudflare: { telemetryType: 'unknown', supportsEndpoint: false },
-  zai: { telemetryType: 'unknown', supportsEndpoint: false },
-  iflow: { telemetryType: 'unknown', supportsEndpoint: false },
-}
-
-/** Fallback for unrecognized providers */
-const UNKNOWN_CAPABILITY = { telemetryType: 'unknown', supportsEndpoint: false }
-
-/**
- * Get quota telemetry capability for a provider.
- * Returns `{ telemetryType: 'unknown', supportsEndpoint: false }` for unrecognized providers.
- *
- * @param {string} providerKey - Provider key matching sources.js (e.g. 'groq', 'openrouter')
- * @returns {ProviderCapability}
- */
-export function getQuotaTelemetry(providerKey) {
-  return PROVIDER_CAPABILITIES[providerKey] ?? UNKNOWN_CAPABILITY
-}
-
-/**
- * Returns true when we have a reliable quota telemetry signal for this provider
- * (either via response headers or a dedicated endpoint).
- *
- * Returns false for 'unknown' providers where quota state must be inferred.
- *
- * @param {string} providerKey
- * @returns {boolean}
- */
-export function isKnownQuotaTelemetry(providerKey) {
-  return getQuotaTelemetry(providerKey).telemetryType !== 'unknown'
-}