free-coding-models 0.4.3 → 0.5.0

package/bin/free-coding-models.js

@@ -10,13 +10,13 @@ if (process.argv.includes('--dev')) {
 }
 
 import chalk from 'chalk';
-import { parseArgs, TIER_LETTER_MAP } from '../src/utils.js';
-import { loadConfig } from '../src/config.js';
-import { ensureTelemetryConfig } from '../src/telemetry.js';
-import { ensureFavoritesConfig } from '../src/favorites.js';
-import { buildCliHelpText } from '../src/cli-help.js';
-import { ALT_LEAVE } from '../src/constants.js';
-import { runApp } from '../src/app.js';
+import { parseArgs, TIER_LETTER_MAP } from '../src/core/utils.js';
+import { loadConfig } from '../src/core/config.js';
+import { ensureTelemetryConfig } from '../src/core/telemetry.js';
+import { ensureFavoritesConfig } from '../src/core/favorites.js';
+import { buildCliHelpText } from '../src/tui/cli-help.js';
+import { ALT_LEAVE } from '../src/core/constants.js';
+import { runApp } from '../src/tui/app.js';
 
 // Global error handlers to ensure terminal is restored if something crashes catastrophically
 process.on('uncaughtException', (err) => {
@@ -61,7 +61,7 @@ async function main() {
       runRouterDaemon,
       startRouterDaemonBackground,
       stopRouterDaemon,
-    } = await import('../src/router-daemon.js');
+    } = await import('../src/core/router-daemon.js');
 
     if (cliArgs.daemonMode) {
       await runRouterDaemon();
@@ -80,7 +80,7 @@ async function main() {
 
   // 📖 --sync-set [name] — auto-discover, probe, and populate a router set
   if (cliArgs.syncSetMode) {
-    const { syncSet } = await import('../src/sync-set.js');
+    const { syncSet } = await import('../src/core/sync-set.js');
     const result = await syncSet({ name: cliArgs.syncSetName || 'auto' });
     console.log(JSON.stringify(result, null, 2));
     process.exit(result.ok ? 0 : 1);

package/changelog/v0.5.0.md

@@ -0,0 +1,15 @@
+# Changelog v0.5.0 - 2026-05-31
+
+### Added
+- **Final Desktop PRD**: Completed `desktop/prd-desktop.md` defining Tauri v2 shell, Bun/Node sidecar integration, zombie process prevention (parent-death binding), and loopback-only security models.
+- **Sub-Project Documentation**: Added `/web/README.md` and `/desktop/README.md` to guide modular frontend and desktop sidecar development.
+
+### Changed
+- **Architectural Segregation (Core vs. TUI)**: Partitioned the codebase into isolated layers:
+  - `src/core/` for 100% shared business logic (routing, scoring, pings, daemon, quota, and config management) shared 1:1 with CLI, Docker, and Tauri sidecar.
+  - `src/tui/` for terminal-only layouts, keystroke handlers, ANSI renderers, and interactive loops.
+- **Relative Import Pathways**: Restructured and re-routed relative imports across all entry points, TUI assets, and core logic files.
+- **Port Consistency**: Standardized loopback proxy and daemon endpoints on port `19280` across all CLI, Docker, and Desktop configurations.
+
+### Fixed
+- **Clean workspace**: Fully purged `.kandown` task manager logs, `.claude-mcp.json`, and stale planning/analysis documents to ensure a zero-noise, lightweight npm package profile.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "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",

package/src/{analysis.js → core/analysis.js}

@@ -35,11 +35,11 @@
  *   @see {@link ../src/ping.js} ping implementation
  */
 
-import { MODELS, sources } from '../sources.js'
-import { findBestModel, filterByTier, formatCtxWindow, labelFromId, TIER_LETTER_MAP } from '../src/utils.js'
-import { isProviderEnabled, getApiKey } from '../src/config.js'
-import { ping } from '../src/ping.js'
-import { PROVIDER_COLOR } from './render-table.js'
+import { MODELS, sources } from '../../sources.js'
+import { findBestModel, filterByTier, formatCtxWindow, labelFromId, TIER_LETTER_MAP } from './utils.js'
+import { isProviderEnabled, getApiKey } from './config.js'
+import { ping } from './ping.js'
+import { PROVIDER_COLOR } from '../tui/render-table.js'
 import chalk from 'chalk'
 
 // 📖 runFiableMode: Analyze models for reliability over 10 seconds, output the best one.

package/src/{constants.js → core/constants.js}

@@ -48,7 +48,7 @@ import chalk from 'chalk'
 // 📖 \x1b[?7l disables auto-wrap so wide rows clip at the right edge instead of
 // 📖 wrapping to the next line (which would double the row height and overflow).
 // 📖 Mouse tracking sequences are appended/prepended so clicks and scroll work in the TUI.
-import { MOUSE_ENABLE, MOUSE_DISABLE } from './mouse.js'
+import { MOUSE_ENABLE, MOUSE_DISABLE } from '../tui/mouse.js'
 
 export const ALT_ENTER = '\x1b[?1049h\x1b[?25l\x1b[?7l' + MOUSE_ENABLE
 export const ALT_LEAVE = MOUSE_DISABLE + '\x1b[?7h\x1b[?1049l\x1b[?25h'

package/src/{endpoint-installer.js → core/endpoint-installer.js}

@@ -43,7 +43,7 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
-import { MODELS, sources } from '../sources.js'
+import { MODELS, sources } from '../../sources.js'
 import { getApiKey, saveConfig } from './config.js'
 import { ENV_VAR_NAMES, PROVIDER_METADATA } from './provider-metadata.js'
 import { getToolMeta } from './tool-metadata.js'

package/src/{installed-models-manager.js → core/installed-models-manager.js}

@@ -48,7 +48,7 @@
 import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, dirname } from 'node:path'
-import { sources } from '../sources.js'
+import { sources } from '../../sources.js'
 
 const BACKUP_PATH = join(homedir(), '.free-coding-models-backups.json')
 

package/src/{kilo.js → core/kilo.js}

@@ -4,12 +4,11 @@
  */
 
 import chalk from 'chalk'
-import { PROVIDER_COLOR } from './render-table.js'
+import { sources } from '../../sources.js'
 import { loadKiloConfig, saveKiloConfig, getKiloConfigPath } from './kilo-config.js'
 import { getApiKey } from './config.js'
 import { ENV_VAR_NAMES, OPENCODE_MODEL_MAP } from './provider-metadata.js'
 import { resolveToolBinaryPath } from './tool-bootstrap.js'
-import { sources } from '../sources.js'
 
 // 📖 Map source model IDs to Kilo built-in IDs (same as OpenCode).
 function getKiloModelId(providerKey, modelId) {

package/src/{openclaw.js → core/openclaw.js}

@@ -31,7 +31,7 @@ import { homedir } from 'os'
 import { dirname, join } from 'path'
 import { installProviderEndpoints } from './endpoint-installer.js'
 import { ENV_VAR_NAMES } from './provider-metadata.js'
-import { PROVIDER_COLOR } from './render-table.js'
+import { PROVIDER_COLOR } from '../tui/render-table.js'
 import { resolveToolBinaryPath } from './tool-bootstrap.js'
 import { getApiKey } from './config.js'
 import { syncShellEnv } from './shell-env.js'

package/src/{opencode.js → core/opencode.js}

@@ -28,7 +28,8 @@ import { request as httpsRequest } from 'https'
 import { homedir } from 'os'
 import { join } from 'path'
 import { copyFileSync, existsSync } from 'fs'
-import { PROVIDER_COLOR } from './render-table.js'
+import { PROVIDER_COLOR } from '../tui/render-table.js'
+import { sources } from '../../sources.js'
 import { loadOpenCodeConfig, saveOpenCodeConfig } from './opencode-config.js'
 import { getApiKey } from './config.js'
 import { ENV_VAR_NAMES, OPENCODE_MODEL_MAP, isWindows, isMac, isLinux } from './provider-metadata.js'

package/src/{ping-loop.js → core/ping-loop.js}

@@ -28,7 +28,7 @@ import {
   PING_MODE_INTERVALS,
   SPEED_MODE_DURATION_MS,
   IDLE_SLOW_AFTER_MS,
-} from './tui-state.js'
+} from '../tui/tui-state.js'
 
 /**
  * 📖 createPingLoop: Build the ping loop control functions for a given TUI state.

package/src/{router-daemon.js → core/router-daemon.js}

@@ -37,7 +37,7 @@ import { randomUUID } from 'node:crypto'
 import { appendFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { fileURLToPath } from 'node:url'
-import { MODELS, sources } from '../sources.js'
+import { MODELS, sources } from '../../sources.js'
 import {
   CONFIG_PATH,
   DEFAULT_ROUTER_SETTINGS,
@@ -71,7 +71,7 @@ export function getRouterPortRange() {
 }
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
-const CLI_ENTRY_PATH = join(__dirname, '..', 'bin', 'free-coding-models.js')
+const CLI_ENTRY_PATH = join(__dirname, '..', '..', 'bin', 'free-coding-models.js')
 const MAX_BODY_BYTES = 10 * 1024 * 1024
 const MAX_REQUEST_LOG = 200
 const MAX_SSE_CLIENTS = 10
@@ -365,7 +365,7 @@ function getWebConfigPayload(runtime) {
   return { providers, totalModels: MODELS.length }
 }
 
-const WEB_DIST_DIR = resolvePath(__dirname, '..', 'web', 'dist')
+const WEB_DIST_DIR = resolvePath(__dirname, '..', '..', 'web', 'dist')
 
 function serveStaticFromDist(res, absPath) {
   const ext = absPath.slice(absPath.lastIndexOf('.'))

package/src/{router-dashboard.js → core/router-dashboard.js}

@@ -41,9 +41,9 @@
 
 import chalk from 'chalk'
 import { existsSync, readFileSync } from 'node:fs'
-import { displayWidth, padEndDisplay, sliceOverlayLines, tintOverlayLines } from './render-helpers.js'
+import { displayWidth, padEndDisplay, sliceOverlayLines, tintOverlayLines } from '../tui/render-helpers.js'
 import { ROUTER_DEFAULT_PORT, ROUTER_MAX_PORT, ROUTER_PID_PATH, ROUTER_PORT_PATH, getRouterPortRange } from './router-daemon.js'
-import { themeColors, getTierRgb } from './theme.js'
+import { themeColors, getTierRgb } from '../tui/theme.js'
 import { formatTokenTotalCompact } from './token-usage-reader.js'
 import { sendUsageTelemetry } from './telemetry.js'
 import { getAvg, getVerdict } from './utils.js'

package/src/{setup.js → core/setup.js}

@@ -35,7 +35,7 @@
 
 import chalk from 'chalk'
 import { createRequire } from 'module'
-import { sources } from '../sources.js'
+import { sources } from '../../sources.js'
 import { PROVIDER_METADATA } from './provider-metadata.js'
 import { saveConfig } from './config.js'
 

package/src/{sync-set.js → core/sync-set.js}

@@ -28,7 +28,7 @@
  * @see ../sources.js — model catalog
  */
 
-import { sources } from '../sources.js'
+import { sources } from '../../sources.js'
 import {
   CONFIG_PATH,
   getApiKey,

package/src/{telemetry.js → core/telemetry.js}

@@ -51,7 +51,7 @@ import { createRequire } from 'module'
 import { saveConfig } from './config.js'
 
 const require = createRequire(import.meta.url)
-const pkg = require('../package.json')
+const pkg = require('../../package.json')
 const LOCAL_VERSION = pkg.version
 
 // 📖 PostHog capture endpoint and defaults.

package/src/{tool-launchers.js → core/tool-launchers.js}

@@ -41,8 +41,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from
 import { homedir } from 'os'
 import { dirname, join } from 'path'
 import { spawn, spawnSync } from 'child_process'
-import { sources } from '../sources.js'
-import { PROVIDER_COLOR } from './render-table.js'
+import { sources } from '../../sources.js'
+import { PROVIDER_COLOR } from '../tui/render-table.js'
 import { getApiKey } from './config.js'
 import { ENV_VAR_NAMES, isWindows } from './provider-metadata.js'
 import { getToolMeta, TOOL_METADATA } from './tool-metadata.js'

package/src/{updater.js → core/updater.js}

@@ -46,7 +46,7 @@ import { accessSync, constants } from 'fs'
 
 const require = createRequire(import.meta.url)
 const readline = require('readline')
-const pkg = require('../package.json')
+const pkg = require('../../package.json')
 const LOCAL_VERSION = pkg.version
 
 /**

package/src/{app.js → tui/app.js}

@@ -96,45 +96,45 @@ import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from
 import { randomUUID } from 'crypto'
 import { homedir } from 'os'
 import { join, dirname } from 'path'
-import { MODELS, sources } from '../sources.js'
-import { getAvg, getVerdict, getUptime, getP95, getJitter, getStabilityScore, sortResults, filterByTier, findBestModel, parseArgs, TIER_ORDER, VERDICT_ORDER, TIER_LETTER_MAP, scoreModelForTask, getTopRecommendations, TASK_TYPES, PRIORITY_TYPES, CONTEXT_BUDGETS, formatCtxWindow, labelFromId, formatResultsAsJSON } from '../src/utils.js'
-import { loadConfig, saveConfig, getApiKey, resolveApiKeys, addApiKey, removeApiKey, isProviderEnabled, persistApiKeysForProvider } from '../src/config.js'
-import { buildMergedModels } from '../src/model-merger.js'
-import { loadOpenCodeConfig, saveOpenCodeConfig } from '../src/opencode-config.js'
-import { usageForRow as _usageForRow } from '../src/usage-reader.js'
-import { buildProviderModelTokenKey, loadTokenUsageByProviderModel } from '../src/token-usage-reader.js'
-import { parseOpenRouterResponse, fetchProviderQuota as _fetchProviderQuotaFromModule } from '../src/provider-quota-fetchers.js'
-import { isKnownQuotaTelemetry } from '../src/quota-capabilities.js'
-import { ALT_ENTER, ALT_LEAVE, ALT_HOME, PING_TIMEOUT, PING_INTERVAL, FPS, COL_MODEL, COL_MS, CELL_W, FRAMES, TIER_CYCLE, VERDICT_CYCLE, HEALTH_CYCLE, SETTINGS_OVERLAY_BG, HELP_OVERLAY_BG, RECOMMEND_OVERLAY_BG, OVERLAY_PANEL_WIDTH, TABLE_HEADER_LINES, TABLE_FOOTER_LINES, TABLE_FIXED_LINES, WIDTH_WARNING_MIN_COLS, msCell, spinCell } from '../src/constants.js'
-import { TIER_COLOR } from '../src/tier-colors.js'
-import { resolveCloudflareUrl, buildPingRequest, ping, extractQuotaPercent, getProviderQuotaPercentCached, usagePlaceholderForProvider } from '../src/ping.js'
-import { runFiableMode, filterByTierOrExit, fetchOpenRouterFreeModels } from '../src/analysis.js'
-import { PROVIDER_METADATA, ENV_VAR_NAMES, isWindows, isMac } from '../src/provider-metadata.js'
-import { parseTelemetryEnv, isTelemetryDebugEnabled, telemetryDebug, ensureTelemetryConfig, getTelemetryDistinctId, getTelemetrySystem, getTelemetryTerminal, isTelemetryEnabled, sendUsageTelemetry } from '../src/telemetry.js'
-import { ensureFavoritesConfig, toFavoriteKey, syncFavoriteFlags, toggleFavoriteModel, reorderFavorite, pruneOrphanedFavorites } from '../src/favorites.js'
-import { checkForUpdateDetailed, checkForUpdate, runUpdate, fetchLastReleaseDate } from './updater.js'
+import { MODELS, sources } from '../../sources.js'
+import { getAvg, getVerdict, getUptime, getP95, getJitter, getStabilityScore, sortResults, filterByTier, findBestModel, parseArgs, TIER_ORDER, VERDICT_ORDER, TIER_LETTER_MAP, scoreModelForTask, getTopRecommendations, TASK_TYPES, PRIORITY_TYPES, CONTEXT_BUDGETS, formatCtxWindow, labelFromId, formatResultsAsJSON } from '../core/utils.js'
+import { loadConfig, saveConfig, getApiKey, resolveApiKeys, addApiKey, removeApiKey, isProviderEnabled, persistApiKeysForProvider } from '../core/config.js'
+import { buildMergedModels } from '../core/model-merger.js'
+import { loadOpenCodeConfig, saveOpenCodeConfig } from '../core/opencode-config.js'
+import { usageForRow as _usageForRow } from '../core/usage-reader.js'
+import { buildProviderModelTokenKey, loadTokenUsageByProviderModel } from '../core/token-usage-reader.js'
+import { parseOpenRouterResponse, fetchProviderQuota as _fetchProviderQuotaFromModule } from '../core/provider-quota-fetchers.js'
+import { isKnownQuotaTelemetry } from '../core/quota-capabilities.js'
+import { ALT_ENTER, ALT_LEAVE, ALT_HOME, PING_TIMEOUT, PING_INTERVAL, FPS, COL_MODEL, COL_MS, CELL_W, FRAMES, TIER_CYCLE, VERDICT_CYCLE, HEALTH_CYCLE, SETTINGS_OVERLAY_BG, HELP_OVERLAY_BG, RECOMMEND_OVERLAY_BG, OVERLAY_PANEL_WIDTH, TABLE_HEADER_LINES, TABLE_FOOTER_LINES, TABLE_FIXED_LINES, WIDTH_WARNING_MIN_COLS, msCell, spinCell } from '../core/constants.js'
+import { TIER_COLOR } from './tier-colors.js'
+import { resolveCloudflareUrl, buildPingRequest, ping, extractQuotaPercent, getProviderQuotaPercentCached, usagePlaceholderForProvider } from '../core/ping.js'
+import { runFiableMode, filterByTierOrExit, fetchOpenRouterFreeModels } from '../core/analysis.js'
+import { PROVIDER_METADATA, ENV_VAR_NAMES, isWindows, isMac } from '../core/provider-metadata.js'
+import { parseTelemetryEnv, isTelemetryDebugEnabled, telemetryDebug, ensureTelemetryConfig, getTelemetryDistinctId, getTelemetrySystem, getTelemetryTerminal, isTelemetryEnabled, sendUsageTelemetry } from '../core/telemetry.js'
+import { ensureFavoritesConfig, toFavoriteKey, syncFavoriteFlags, toggleFavoriteModel, reorderFavorite, pruneOrphanedFavorites } from '../core/favorites.js'
+import { checkForUpdateDetailed, checkForUpdate, runUpdate, fetchLastReleaseDate } from '../core/updater.js'
 import { createTuiState, PING_MODE_INTERVALS, PING_MODE_CYCLE, SPEED_MODE_DURATION_MS, IDLE_SLOW_AFTER_MS, intervalToPingMode } from './tui-state.js'
-import { createPingLoop } from './ping-loop.js'
+import { createPingLoop } from '../core/ping-loop.js'
 import { createTuiFilters } from './tui-filters.js'
-import { promptApiKey } from '../src/setup.js'
-import { syncShellEnv, ensureShellRcSource, removeShellEnv } from '../src/shell-env.js'
-import { stripAnsi, maskApiKey, displayWidth, padEndDisplay, tintOverlayLines, keepOverlayTargetVisible, sliceOverlayLines, calculateViewport, sortResultsWithPinnedFavorites, adjustScrollOffset } from '../src/render-helpers.js'
-import { renderTable, PROVIDER_COLOR } from '../src/render-table.js'
-import { setOpenCodeModelData, startOpenCode, startOpenCodeDesktop, startOpenCodeWeb } from '../src/opencode.js'
-import { startKilo } from '../src/kilo.js'
-import { startOpenClaw } from '../src/openclaw.js'
-import { createOverlayRenderers } from '../src/overlays.js'
-import { createKeyHandler, createMouseEventHandler } from '../src/key-handler.js'
-import { createMouseHandler, containsMouseSequence } from '../src/mouse.js'
-import { stopRouterDashboardClient } from '../src/router-dashboard.js'
-import { getToolModeOrder, getToolMeta } from '../src/tool-metadata.js'
-import { startExternalTool } from '../src/tool-launchers.js'
-import { getToolInstallPlan, installToolWithPlan, isToolInstalled } from '../src/tool-bootstrap.js'
-import { getConfiguredInstallableProviders, installProviderEndpoints, refreshInstalledEndpoints, getInstallTargetModes, getProviderCatalogModels } from '../src/endpoint-installer.js'
-import { loadCache, saveCache, clearCache, getCacheAge } from '../src/cache.js'
-import { checkConfigSecurity } from '../src/security.js'
-import { buildCliHelpText } from '../src/cli-help.js'
-import { detectActiveTheme } from '../src/theme.js'
+import { promptApiKey } from '../core/setup.js'
+import { syncShellEnv, ensureShellRcSource, removeShellEnv } from '../core/shell-env.js'
+import { stripAnsi, maskApiKey, displayWidth, padEndDisplay, tintOverlayLines, keepOverlayTargetVisible, sliceOverlayLines, calculateViewport, sortResultsWithPinnedFavorites, adjustScrollOffset } from './render-helpers.js'
+import { renderTable, PROVIDER_COLOR } from './render-table.js'
+import { setOpenCodeModelData, startOpenCode, startOpenCodeDesktop, startOpenCodeWeb } from '../core/opencode.js'
+import { startKilo } from '../core/kilo.js'
+import { startOpenClaw } from '../core/openclaw.js'
+import { createOverlayRenderers } from './overlays.js'
+import { createKeyHandler, createMouseEventHandler } from './key-handler.js'
+import { createMouseHandler, containsMouseSequence } from './mouse.js'
+import { stopRouterDashboardClient } from '../core/router-dashboard.js'
+import { getToolModeOrder, getToolMeta } from '../core/tool-metadata.js'
+import { startExternalTool } from '../core/tool-launchers.js'
+import { getToolInstallPlan, installToolWithPlan, isToolInstalled } from '../core/tool-bootstrap.js'
+import { getConfiguredInstallableProviders, installProviderEndpoints, refreshInstalledEndpoints, getInstallTargetModes, getProviderCatalogModels } from '../core/endpoint-installer.js'
+import { loadCache, saveCache, clearCache, getCacheAge } from '../core/cache.js'
+import { checkConfigSecurity } from '../core/security.js'
+import { buildCliHelpText } from './cli-help.js'
+import { detectActiveTheme } from './theme.js'
 
 // 📖 mergedModels: cross-provider grouped model list (one entry per label, N providers each)
 // 📖 mergedModelByLabel: fast lookup map from display label → merged model entry
@@ -149,7 +149,7 @@ const require = createRequire(import.meta.url)
 const readline = require('readline')
 
 // ─── Version check ────────────────────────────────────────────────────────────
-const pkg = require('../package.json')
+const pkg = require('../../package.json')
 const LOCAL_VERSION = pkg.version
 
 // 📖 sendBugReport → imported from ../src/telemetry.js

package/src/{cli-help.js → tui/cli-help.js}

@@ -18,7 +18,7 @@
  * @see ./tool-metadata.js — source of truth for launcher modes and their CLI flags
  */
 
-import { getToolModeOrder, getToolMeta } from './tool-metadata.js'
+import { getToolModeOrder, getToolMeta } from '../core/tool-metadata.js'
 
 const ANALYSIS_FLAGS = [
   { flag: '--best', description: 'Show only top tiers (A+, S, S+)' },

package/src/{command-palette.js → tui/command-palette.js}

@@ -15,8 +15,8 @@
  * @see src/overlays.js
  */
 
-import { TOOL_METADATA, TOOL_MODE_ORDER } from './tool-metadata.js'
-import { sources } from '../sources.js'
+import { TOOL_METADATA, TOOL_MODE_ORDER } from '../core/tool-metadata.js'
+import { sources } from '../../sources.js'
 
 const PROVIDER_FILTER_COMMANDS = Object.entries(sources).map(([providerKey, source]) => {
   const label = source?.name || providerKey

package/src/{key-handler.js → tui/key-handler.js}

@@ -31,21 +31,21 @@
  * @exports { buildProviderModelsUrl, parseProviderModelIds, listProviderTestModels, classifyProviderTestOutcome, buildProviderTestDetail, createKeyHandler }
  */
 
-import { loadChangelog } from './changelog-loader.js'
-import { getToolMeta, isModelCompatibleWithTool, getCompatibleTools, findSimilarCompatibleModels } from './tool-metadata.js'
-import { loadConfig, saveConfig, replaceConfigContents, getApiKey } from './config.js'
-import { sources } from '../sources.js'
+import { loadChangelog } from '../core/changelog-loader.js'
+import { getToolMeta, isModelCompatibleWithTool, getCompatibleTools, findSimilarCompatibleModels } from '../core/tool-metadata.js'
+import { loadConfig, saveConfig, replaceConfigContents, getApiKey } from '../core/config.js'
+import { sources } from '../../sources.js'
 import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { spawn } from 'node:child_process'
-import { cleanupLegacyProxyArtifacts } from './legacy-proxy-cleanup.js'
+import { cleanupLegacyProxyArtifacts } from '../core/legacy-proxy-cleanup.js'
 import { getLastLayout, COLUMN_SORT_MAP } from './render-table.js'
 import { cycleThemeSetting, detectActiveTheme } from './theme.js'
-import { syncShellEnv, ensureShellRcSource, removeShellEnv } from './shell-env.js'
+import { syncShellEnv, ensureShellRcSource, removeShellEnv } from '../core/shell-env.js'
 import { buildCommandPaletteTree, flattenCommandTree, filterCommandPaletteEntries } from './command-palette.js'
-import { WIDTH_WARNING_MIN_COLS, VERDICT_CYCLE, HEALTH_CYCLE } from './constants.js'
-import { scanAllToolConfigs, softDeleteModel } from './installed-models-manager.js'
-import { startExternalTool } from './tool-launchers.js'
+import { WIDTH_WARNING_MIN_COLS, VERDICT_CYCLE, HEALTH_CYCLE } from '../core/constants.js'
+import { scanAllToolConfigs, softDeleteModel } from '../core/installed-models-manager.js'
+import { startExternalTool } from '../core/tool-launchers.js'
 import {
   clearRouterDashboardRequestLog,
   closeRouterDashboardOverlay,
@@ -54,8 +54,8 @@ import {
   openRouterDashboardOverlay,
   restartRouterDashboardDaemon,
   toggleRouterDashboardProbePause,
-} from './router-dashboard.js'
-import { benchmarkModel } from './benchmark.js'
+} from '../core/router-dashboard.js'
+import { benchmarkModel } from '../core/benchmark.js'
 
 // 📖 Some providers need an explicit probe model because the first catalog entry
 // 📖 is not guaranteed to be accepted by their chat endpoint.

package/src/{overlays.js → tui/overlays.js}

@@ -19,9 +19,9 @@
  * @see ./key-handler.js — handles keypresses for all overlay interactions
  */
 
-import { loadChangelog } from './changelog-loader.js'
+import { loadChangelog } from '../core/changelog-loader.js'
 import { buildCliHelpLines } from './cli-help.js'
-import { renderRouterDashboard as renderRouterDashboardOverlay } from './router-dashboard.js'
+import { renderRouterDashboard as renderRouterDashboardOverlay } from '../core/router-dashboard.js'
 import { themeColors, getThemeStatusLabel, getProviderRgb } from './theme.js'
 
 export function createOverlayRenderers(state, deps) {

package/src/{render-helpers.js → tui/render-helpers.js}

@@ -47,8 +47,8 @@
  */
 
 import chalk from 'chalk'
-import { OVERLAY_PANEL_WIDTH, TABLE_FIXED_LINES, TABLE_HEADER_LINES, TABLE_FOOTER_LINES } from './constants.js'
-import { sortResults } from './utils.js'
+import { OVERLAY_PANEL_WIDTH, TABLE_FIXED_LINES, TABLE_HEADER_LINES, TABLE_FOOTER_LINES } from '../core/constants.js'
+import { sortResults } from '../core/utils.js'
 
 // 📖 stripAnsi: Remove ANSI color/control sequences to estimate visible text width before padding.
 // 📖 Strips CSI sequences (SGR colors) and OSC sequences (hyperlinks).

package/src/{render-table.js → tui/render-table.js}

@@ -34,7 +34,7 @@
 
 import chalk from 'chalk'
 import { createRequire } from 'module'
-import { sources } from '../sources.js'
+import { sources } from '../../sources.js'
 import {
   COL_MODEL,
   TIER_CYCLE,
@@ -44,19 +44,19 @@ import {
   WIDTH_WARNING_MIN_COLS,
   TABLE_FOOTER_LINES,
   FRAMES
-} from './constants.js'
+} from '../core/constants.js'
 import { themeColors, currentPalette, getProviderRgb, getTierRgb, getReadableTextRgb, getTheme } from './theme.js'
 import { TIER_COLOR } from './tier-colors.js'
-import { getAvg, getVerdict, getUptime, getStabilityScore, getVersionStatusInfo } from './utils.js'
-import { usagePlaceholderForProvider } from './ping.js'
-import { formatBenchmarkLatency, formatBenchmarkTps } from './benchmark.js'
+import { getAvg, getVerdict, getUptime, getStabilityScore, getVersionStatusInfo } from '../core/utils.js'
+import { usagePlaceholderForProvider } from '../core/ping.js'
+import { formatBenchmarkLatency, formatBenchmarkTps } from '../core/benchmark.js'
 import { calculateViewport, sortResultsWithPinnedFavorites, padEndDisplay, displayWidth, stripAnsi } from './render-helpers.js'
-import { getToolMeta, TOOL_METADATA, TOOL_MODE_ORDER, isModelCompatibleWithTool } from './tool-metadata.js'
+import { getToolMeta, TOOL_METADATA, TOOL_MODE_ORDER, isModelCompatibleWithTool } from '../core/tool-metadata.js'
 import { getColumnSpacing } from './ui-config.js'
-import { detectPackageManager, getManualInstallCmd } from './updater.js'
+import { detectPackageManager, getManualInstallCmd } from '../core/updater.js'
 
 const require = createRequire(import.meta.url)
-const { version: LOCAL_VERSION } = require('../package.json')
+const { version: LOCAL_VERSION } = require('../../package.json')
 
 // 📖 Mouse support: column boundary map updated every frame by renderTable().
 // 📖 Each entry maps a column name to its display X-start and X-end (1-based, inclusive).

package/src/{tui-filters.js → tui/tui-filters.js}

@@ -26,9 +26,9 @@
  * @see src/tui-state.js — state shape for filter mode indices
  */
 
-import { TIER_CYCLE, VERDICT_CYCLE, HEALTH_CYCLE } from './constants.js'
-import { TIER_LETTER_MAP } from './utils.js'
-import { getVerdict } from './utils.js'
+import { TIER_CYCLE, VERDICT_CYCLE, HEALTH_CYCLE } from '../core/constants.js'
+import { TIER_LETTER_MAP } from '../core/utils.js'
+import { getVerdict } from '../core/utils.js'
 
 /**
  * 📖 createTuiFilters: Build the filter functions for a given TUI state + dependencies.

package/src/{tui-state.js → tui/tui-state.js}

@@ -24,7 +24,7 @@
  * @see src/ping-loop.js — reads ping mode fields from the state
  */
 
-import { WIDTH_WARNING_MIN_COLS } from './constants.js'
+import { WIDTH_WARNING_MIN_COLS } from '../core/constants.js'
 
 // 📖 Ping cadence intervals per mode (ms). Speed = startup burst, normal = steady,
 // 📖 slow = idle throttle, forced = user-triggered fast burst.

package/web/README.md

@@ -0,0 +1,43 @@
+# 📦 free-coding-models-web
+
+This directory contains the shared React SPA (Single Page Application) dashboard for `free-coding-models`.
+
+## 🌐 Architecture
+
+The frontend is a single SPA that is served in two distinct scenarios:
+1. **Web Dashboard / Docker Mode (`--daemon`):** Served directly by the local Node.js `router-daemon` process on `http://localhost:19280/`.
+2. **Desktop Mode (Tauri App):** Loaded locally inside Tauri's native webview from embedded assets in `web/dist/`, communicating via HTTP fetch to the background engine.
+
+To maintain maximum code sharing, **95%+ of all components and logic are kept completely identical** between the two distributions.
+
+---
+
+## ⚡ API & Event Integration
+
+The React app relies on HTTP and Server-Sent Events (SSE) to talk to the engine:
+* `GET /api/models`: Fetches the live model catalog, complete with stability scores and latency details.
+* `GET /api/config`: Retrieves active provider toggles (keys are masked).
+* `POST /api/settings`: Updates API keys and provider preferences.
+* `GET /api/events` / `EventSource`: Listens for real-time SSE updates broadcasted by the ping and benchmark loops.
+
+---
+
+## 🛠️ Development & Building
+
+### Prerequisites
+Make sure you have `pnpm` installed and dependencies initialized at the root of the project.
+
+### 1. Dev Server (HMR)
+To start the React frontend with Vite HMR (Hot Module Replacement):
+```bash
+cd web
+pnpm dev
+```
+By default, the dev server runs on `http://localhost:5173/`. Ensure a background daemon is running on port `19280` so the API requests proxy correctly.
+
+### 2. Production Build
+To compile the production-ready SPA:
+```bash
+pnpm build
+```
+This bundles the HTML, JS, and CSS assets into the `web/dist/` directory, which is then embedded inside both the CLI daemon and the Tauri desktop app binary.