free-coding-models 0.5.4 → 0.5.6

package/web/src/components/update/UpdateChip.module.css

@@ -0,0 +1,146 @@
+/**
+ * @file web/src/components/update/UpdateChip.module.css
+ * @description Styles for the header update chip + popover.
+ */
+
+.wrap {
+  position: relative;
+  display: inline-flex;
+}
+
+.chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  height: 28px;
+  padding: 0 10px;
+  font-size: 11px;
+  font-weight: 700;
+  font-family: var(--font-mono);
+  background: var(--color-success-dim);
+  color: var(--color-success);
+  border: 1px solid var(--color-success);
+  border-radius: 6px;
+  cursor: pointer;
+  font-family: var(--font-mono);
+  transition: all 150ms;
+  white-space: nowrap;
+}
+.chip:hover {
+  background: var(--color-success);
+  color: var(--color-bg);
+}
+
+.checking {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 22px;
+  height: 22px;
+  opacity: 0.5;
+}
+.dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--color-text-muted);
+  animation: pulse 1.5s ease-in-out infinite;
+}
+@keyframes pulse {
+  0%, 100% { opacity: 0.3; }
+  50% { opacity: 1; }
+}
+
+.popover {
+  position: absolute;
+  top: calc(100% + 6px);
+  right: 0;
+  width: 320px;
+  background: var(--color-bg-elevated);
+  border: 1px solid var(--color-border-hover);
+  border-radius: 10px;
+  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.4);
+  z-index: 200;
+  overflow: hidden;
+}
+
+.popoverHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 10px 12px;
+  border-bottom: 1px solid var(--color-border);
+}
+.popoverTitle {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--color-success);
+}
+.popoverClose {
+  background: transparent;
+  border: none;
+  color: var(--color-text-muted);
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 2px;
+  border-radius: 4px;
+}
+.popoverClose:hover { color: var(--color-text); background: var(--color-bg-hover); }
+
+.popoverBody {
+  padding: 10px 12px;
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--color-text);
+}
+.popoverBody strong {
+  color: var(--color-success);
+  font-family: var(--font-mono);
+}
+
+.popoverActions {
+  display: flex;
+  gap: 6px;
+  padding: 8px 12px 12px;
+}
+
+.primaryAction,
+.secondaryAction {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  flex: 1;
+  height: 32px;
+  padding: 0 10px;
+  font-size: 11px;
+  font-weight: 600;
+  border-radius: 6px;
+  cursor: pointer;
+  justify-content: center;
+  font-family: var(--font-sans);
+  transition: all 150ms;
+}
+.primaryAction {
+  background: var(--color-success);
+  color: var(--color-bg);
+  border: 1px solid var(--color-success);
+}
+.primaryAction:hover {
+  background: var(--color-success);
+  filter: brightness(0.9);
+}
+.secondaryAction {
+  background: var(--color-surface);
+  color: var(--color-text);
+  border: 1px solid var(--color-border);
+}
+.secondaryAction:hover {
+  background: var(--color-bg-hover);
+  border-color: var(--color-text-muted);
+}

package/web/src/global.css

@@ -202,6 +202,21 @@ code { font-family: var(--font-mono); font-size: 12px; background: var(--color-s
   min-height: 0;
 }
 
+.update-warning-banner {
+  position: sticky;
+  top: var(--header-h, 60px);
+  z-index: 90;
+  padding: 10px 18px;
+  background: var(--color-danger);
+  color: #fff;
+  border-bottom: 1px solid rgba(255, 255, 255, 0.22);
+  font-weight: 800;
+  font-size: 13px;
+  letter-spacing: 0.01em;
+  text-align: center;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.22);
+}
+
 /* ─── Scrollbar ─── */
 ::-webkit-scrollbar { width: 8px; height: 8px; }
 ::-webkit-scrollbar-track { background: var(--color-bg); }

package/web/src/hooks/urlState.constants.js

@@ -0,0 +1,25 @@
+/**
+ * @file web/src/hooks/urlState.constants.js
+ * @description URL param validation tables — extracted from useUrlState for testability.
+ * 📖 Keep these in sync with src/tui/tui-state.js TIER_CYCLE / VERDICT_CYCLE /
+ * 📖 HEALTH_CYCLE constants so the URL reflects the same filter universe
+ * 📖 the TUI uses.
+ */
+
+const TIER_VALUES = new Set(['S+', 'S', 'A+', 'A', 'A-', 'B+', 'B', 'C', 'all'])
+const STATUS_VALUES = new Set(['up', 'down', 'pending', 'all'])
+const SORT_VALUES = new Set([
+  'mood', 'idx', 'tier', 'sweScore', 'ctx', 'label', 'origin',
+  'latestPing', 'avg', 'condition', 'verdict', 'stability', 'uptime',
+  'aiLatency', 'tps', 'trend',
+])
+const VIEW_VALUES = new Set(['dashboard', 'settings', 'analytics', 'recommend', 'router', 'help', 'changelog'])
+const DIR_VALUES = new Set(['asc', 'desc'])
+
+export {
+  TIER_VALUES as VALID_TIERS,
+  STATUS_VALUES as VALID_STATUS,
+  SORT_VALUES as VALID_SORTS,
+  VIEW_VALUES as VALID_VIEWS,
+  DIR_VALUES as VALID_DIRS,
+}

package/web/src/hooks/useChangelog.js

@@ -0,0 +1,51 @@
+/**
+ * @file web/src/hooks/useChangelog.js
+ * @description React hook for the changelog data — M2 parity with the TUI's `N` key overlay.
+ * 📖 Loads `/api/changelog` once on mount, exposes the parsed { versions } map,
+ * 📖 and provides helpers for the index/details two-phase modal.
+ *
+ * @functions
+ *   → useChangelog() — { versions, sortedVersions, getVersion, loading, error, refresh }
+ */
+import { useEffect, useMemo, useState, useCallback } from 'react'
+
+export function useChangelog() {
+  const [versions, setVersions] = useState({})
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState(null)
+
+  const refresh = useCallback(async () => {
+    try {
+      const resp = await fetch('/api/changelog')
+      if (!resp.ok) throw new Error(`HTTP ${resp.status}`)
+      const data = await resp.json()
+      setVersions(data?.versions ?? {})
+      setError(null)
+    } catch (err) {
+      setError(err.message || 'Failed to load changelog')
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  useEffect(() => { refresh() }, [refresh])
+
+  // 📖 Sort versions in descending semver order. We do a string-based compare
+  // 📖 on the dotted tuples so '0.10.0' > '0.9.0' works correctly.
+  const sortedVersions = useMemo(() => {
+    return Object.keys(versions).sort((a, b) => {
+      const ap = a.split('.').map(Number)
+      const bp = b.split('.').map(Number)
+      for (let i = 0; i < Math.max(ap.length, bp.length); i++) {
+        const av = ap[i] || 0
+        const bv = bp[i] || 0
+        if (bv !== av) return bv - av
+      }
+      return 0
+    })
+  }, [versions])
+
+  const getVersion = useCallback((v) => versions[v] ?? null, [versions])
+
+  return { versions, sortedVersions, getVersion, loading, error, refresh }
+}

package/web/src/hooks/useSocket.js

@@ -42,6 +42,7 @@ export function useSocket(serverUrl = '') {
   const [globalBenchmarkRunning, setGlobalBenchmarkRunning] = useState(false)
   const [globalBenchmarkTotal, setGlobalBenchmarkTotal] = useState(0)
   const [globalBenchmarkCompleted, setGlobalBenchmarkCompleted] = useState(0)
+  const [updateStatus, setUpdateStatus] = useState(null)
 
   const socketRef = useRef(null)
   const esRef = useRef(null)
@@ -62,6 +63,7 @@ export function useSocket(serverUrl = '') {
     setGlobalBenchmarkRunning(Boolean(data.globalBenchmarkRunning))
     setGlobalBenchmarkTotal(Number.isFinite(data.globalBenchmarkTotal) ? data.globalBenchmarkTotal : 0)
     setGlobalBenchmarkCompleted(Number.isFinite(data.globalBenchmarkCompleted) ? data.globalBenchmarkCompleted : 0)
+    setUpdateStatus(data.updateStatus && data.updateStatus.allowedOutdated ? data.updateStatus : null)
     setUpdateCount((count) => count + 1)
     lastUpdateRef.current = Date.now()
     if (source !== 'poll') {
@@ -196,5 +198,6 @@ export function useSocket(serverUrl = '') {
     globalBenchmarkRunning,
     globalBenchmarkTotal,
     globalBenchmarkCompleted,
+    updateStatus,
   }
 }

package/web/src/hooks/useUpdateChecker.js

@@ -0,0 +1,91 @@
+/**
+ * @file web/src/hooks/useUpdateChecker.js
+ * @description React hook for the update chip + popover — M2 parity with TUI `Shift+U`.
+ * 📖 Polls `/api/version` every 5 minutes (matches the TUI cadence) and exposes
+ * 📖 `updateAvailable` (boolean) + `latestVersion` (string) for the header chip.
+ * 📖 The chip's "Update now" button calls `/api/update/run` which spawns the
+ * 📖 detected package manager in the background; the Web UI just surfaces a
+ * 📖 toast and tells the user to restart the dashboard to apply the update.
+ *
+ * @functions
+ *   → useUpdateChecker({ onToast }) — { latestVersion, updateAvailable, runUpdate, checkNow, loading }
+ */
+import { useCallback, useEffect, useState, useRef } from 'react'
+
+const POLL_INTERVAL_MS = 5 * 60_000
+
+// 📖 Lightweight semver compare: returns 1 if a > b, -1 if a < b, 0 if equal.
+function semverCompare(a, b) {
+  if (!a || !b) return 0
+  const ap = a.replace(/^v/, '').split('.').map(Number)
+  const bp = b.replace(/^v/, '').split('.').map(Number)
+  for (let i = 0; i < Math.max(ap.length, bp.length); i++) {
+    const av = ap[i] || 0
+    const bv = bp[i] || 0
+    if (bv !== av) return bv - av
+  }
+  return 0
+}
+
+export function useUpdateChecker({ onToast } = {}) {
+  const [localVersion, setLocalVersion] = useState(null)
+  const [latestVersion, setLatestVersion] = useState(null)
+  const [lastReleaseDate, setLastReleaseDate] = useState(null)
+  const [error, setError] = useState(null)
+  const [loading, setLoading] = useState(false)
+  const intervalRef = useRef(null)
+
+  const checkNow = useCallback(async () => {
+    setLoading(true)
+    try {
+      const resp = await fetch('/api/version')
+      if (!resp.ok) throw new Error(`HTTP ${resp.status}`)
+      const data = await resp.json()
+      setLocalVersion(data.local ?? null)
+      setLatestVersion(data.latest ?? null)
+      setLastReleaseDate(data.lastReleaseDate ?? null)
+      setError(data.error ?? null)
+    } catch (err) {
+      setError(err.message || 'update check failed')
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  // 📖 Initial check + 5-minute polling. We stop polling on unmount.
+  useEffect(() => {
+    checkNow()
+    intervalRef.current = setInterval(checkNow, POLL_INTERVAL_MS)
+    return () => {
+      if (intervalRef.current) clearInterval(intervalRef.current)
+    }
+  }, [checkNow])
+
+  // 📖 updateAvailable is true when latest > local. A null latest means the
+  // 📖 npm registry is unreachable, so we don't surface a chip.
+  const updateAvailable = Boolean(latestVersion && localVersion && semverCompare(latestVersion, localVersion) > 0)
+
+  const runUpdate = useCallback(async () => {
+    if (!updateAvailable) {
+      onToast?.('No update available.', 'info')
+      return
+    }
+    try {
+      const resp = await fetch('/api/update/run', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ version: latestVersion }),
+      })
+      const data = await resp.json().catch(() => ({}))
+      if (resp.ok && data?.started) {
+        onToast?.(`Update to v${latestVersion} started — restart the dashboard to apply.`, 'success')
+      } else {
+        onToast?.(data?.error || data?.message || 'Update failed', 'error')
+      }
+    } catch (err) {
+      onToast?.(err.message || 'Update request failed', 'error')
+    }
+  }, [updateAvailable, latestVersion, onToast])
+
+  return { localVersion, latestVersion, lastReleaseDate, updateAvailable, checkNow, runUpdate, loading, error }
+}

package/web/src/hooks/useUrlState.js

@@ -1,52 +1,37 @@
 /**
  * @file web/src/hooks/useUrlState.js
  * @description URL deep-linking hook — the Web's answer to TUI CLI flags (--tier, --sort, etc.).
- * 📖 M1 ships read-only hydration: on mount, parses the query string and hydrates the Web view.
- * 📖 M2 will add write-back (push filter/sort/view changes back to the URL via history.replaceState).
+ * 📖 M1 = read-only hydration on mount.
+ * 📖 M2 = adds write-back: every filter / sort / view / tool-mode / palette
+ * 📖 change pushes to the URL via `history.replaceState` so the URL stays
+ * 📖 in sync with the visible Web state and any URL is shareable.
  *
- * 📖 Supported query params (M1 = read-only):
- * 📖   ?tier=S+|S|A+|A|A-|B+|B|C|all  — sets the tier filter
- * 📖   ?status=up|down|pending|all   — sets the health/status filter
- * 📖   ?provider=<providerKey>|all   — sets the provider filter
- * 📖   ?verdict=<verdict>|all        — sets the verdict filter
- * 📖   ?health=<health>|all          — sets the health filter
- * 📖   ?sort=<col>&dir=asc|desc      — sets the sort column + direction
- * 📖   ?view=dashboard|settings|analytics  — sets the active view
- * 📖   ?q=<text>                     — sets the search query
- * 📖   ?tier=S&sort=verdict&dir=asc  — compose freely; the same URL is shareable
+ * 📖 URL params (all optional, all shareable):
+ * 📖   ?view=dashboard|settings|analytics|recommend|router|help|changelog
+ * 📖   ?tier=S+|S|A+|A|A-|B+|B|C|all
+ * 📖   ?status=up|down|pending|all
+ * 📖   ?provider=<providerKey>|all
+ * 📖   ?verdict=<verdict>|all
+ * 📖   ?health=<health>|all
+ * 📖   ?sort=<col>&dir=asc|desc
+ * 📖   ?q=<searchText>
+ * 📖   ?toolMode=<toolKey>
+ * 📖   ?palette=open        (when the palette should be open on load)
  *
  * @functions
- *   → useUrlState({ currentView, setCurrentView, filterState }) — hydrates Web state from URL
- *
- * @see ideas/tui-web-feature-parity.md §5.4 — full CLI-flag ↔ URL-param mapping
+ *   → useUrlState({ currentView, setCurrentView, filterState, paletteOpen, setPaletteOpen })
+ *   → buildUrlParams(state) — pure helper exposed for tests
  */
-import { useEffect } from 'react'
-
-// 📖 Valid enum values for cycle-style params. Keys here determine which params
-// 📖 get accepted silently vs ignored. Anything not in the list is dropped.
-const VALID_TIERS = new Set(['S+', 'S', 'A+', 'A', 'A-', 'B+', 'B', 'C', 'all'])
-const VALID_STATUS = new Set(['up', 'down', 'pending', 'all'])
-const VALID_SORTS = new Set([
-  'mood', 'idx', 'tier', 'sweScore', 'ctx', 'label', 'origin',
-  'latestPing', 'avg', 'condition', 'verdict', 'stability', 'uptime',
-  'aiLatency', 'tps', 'trend',
-])
-const VALID_VIEWS = new Set(['dashboard', 'settings', 'analytics'])
-const VALID_DIRS = new Set(['asc', 'desc'])
+import { useEffect, useRef, useCallback } from 'react'
+import { VALID_TIERS, VALID_STATUS, VALID_SORTS, VALID_VIEWS, VALID_DIRS } from './urlState.constants.js'
 
-/**
- * 📖 parseUrlParams: extract a normalized set of params from the current URL.
- * 📖 Returns a flat object with camelCase keys, only including recognized params.
- * @returns {{
- *   tier: string|null, status: string|null, provider: string|null,
- *   verdict: string|null, health: string|null,
- *   sort: string|null, dir: string|null, view: string|null, q: string,
- * }}
- */
+// 📖 Read the current URL params as a normalized object. Returns null on SSR
+// 📖 or when the URL is invalid.
 function parseUrlParams() {
   if (typeof window === 'undefined') return null
   const params = new URLSearchParams(window.location.search)
   const out = {}
+  if (params.has('view') && VALID_VIEWS.has(params.get('view'))) out.view = params.get('view')
   if (params.has('tier') && VALID_TIERS.has(params.get('tier'))) out.tier = params.get('tier')
   if (params.has('status') && VALID_STATUS.has(params.get('status'))) out.status = params.get('status')
   if (params.has('provider')) out.provider = params.get('provider')
@@ -54,40 +39,115 @@ function parseUrlParams() {
   if (params.has('health')) out.health = params.get('health')
   if (params.has('sort') && VALID_SORTS.has(params.get('sort'))) out.sort = params.get('sort')
   if (params.has('dir') && VALID_DIRS.has(params.get('dir'))) out.dir = params.get('dir')
-  if (params.has('view') && VALID_VIEWS.has(params.get('view'))) out.view = params.get('view')
   if (params.has('q')) out.q = params.get('q')
+  if (params.has('toolMode')) out.toolMode = params.get('toolMode')
+  if (params.has('palette') && params.get('palette') === 'open') out.palette = 'open'
   return out
 }
 
-/**
- * 📖 useUrlState: hydrate the Web view from the current URL on mount.
- * 📖 M1 = read-only. Pass setters; the hook calls them once on mount with
- * 📖 whatever the URL declares, then leaves the URL alone.
- *
- * 📖 The hook is intentionally non-intrusive: if the URL has no params, it does
- * 📖 nothing. The caller is free to call the setters independently — the URL
- * 📖 simply becomes the *initial* state.
- *
- * @param {{
- *   currentView: string,
- *   setCurrentView: (view: string) => void,
- *   filterState: object | null,  // wired in M2
- * }} opts
- */
-export function useUrlState({ currentView, setCurrentView, filterState }) {
+// 📖 Build a URLSearchParams object from the live state. Pure for testing.
+export function buildUrlParams(state) {
+  const params = new URLSearchParams()
+  if (!state) return params
+  if (state.currentView && state.currentView !== 'dashboard') params.set('view', state.currentView)
+  if (state.filterTier && state.filterTier !== 'all') params.set('tier', state.filterTier)
+  if (state.filterStatus && state.filterStatus !== 'all') params.set('status', state.filterStatus)
+  if (state.filterProvider && state.filterProvider !== 'all') params.set('provider', state.filterProvider)
+  if (state.filterVerdict && state.filterVerdict !== 'all') params.set('verdict', state.filterVerdict)
+  if (state.filterHealth && state.filterHealth !== 'all') params.set('health', state.filterHealth)
+  if (state.sortColumn) {
+    params.set('sort', state.sortColumn)
+    if (state.sortDirection) params.set('dir', state.sortDirection)
+  }
+  if (state.searchQuery) params.set('q', state.searchQuery)
+  if (state.toolMode) params.set('toolMode', state.toolMode)
+  if (state.paletteOpen) params.set('palette', 'open')
+  return params
+}
+
+// 📖 Debounced write-back helper. We don't want to push 5 history entries per
+// 📖 second when the user is typing in the search box.
+function writeUrl(state) {
+  if (typeof window === 'undefined') return
+  const params = buildUrlParams(state)
+  const search = params.toString()
+  const newUrl = search
+    ? `${window.location.pathname}?${search}${window.location.hash}`
+    : `${window.location.pathname}${window.location.hash}`
+  // 📖 replaceState (not pushState) so back/forward don't fill up with
+  // 📖 every keystroke. The current URL still updates visibly.
+  window.history.replaceState({}, '', newUrl)
+}
+
+export function useUrlState({
+  currentView, setCurrentView,
+  filterState = null,
+  paletteOpen = false, setPaletteOpen = () => {},
+  toolMode = null, setToolMode = () => {},
+}) {
+  // 📖 Track a debounce handle so we can coalesce rapid filter / sort changes.
+  const writeTimerRef = useRef(null)
+
+  // 📖 Hydrate from URL on mount, exactly once. We don't want to re-hydrate
+  // 📖 on every render — the user's actions should drive the URL, not vice versa.
+  const hydratedRef = useRef(false)
   useEffect(() => {
+    if (hydratedRef.current) return
+    hydratedRef.current = true
+
     const params = parseUrlParams()
     if (!params) return
 
-    if (params.view && params.view !== currentView) {
+    if (params.view && setCurrentView && params.view !== currentView) {
       setCurrentView(params.view)
     }
+    if (params.tier && filterState?.setFilterTier) filterState.setFilterTier(params.tier)
+    if (params.status && filterState?.setFilterStatus) filterState.setFilterStatus(params.status)
+    if (params.provider && filterState?.setFilterProvider) filterState.setFilterProvider(params.provider)
+    if (params.verdict && filterState?.setFilterVerdict) filterState.setFilterVerdict(params.verdict)
+    if (params.health && filterState?.setFilterHealth) filterState.setFilterHealth(params.health)
+    if (params.sort && filterState?.toggleSort) {
+      // 📖 Re-trigger sort: pass the column to setSortColumn + setSortDirection
+      // 📖 The hook exposes toggleSort which is a 3-state cycle; for hydration
+      // 📖 we want a deterministic state, so we use the lower-level setters.
+      if (filterState.setSortColumn) filterState.setSortColumn(params.sort)
+      if (params.dir && filterState.setSortDirection) filterState.setSortDirection(params.dir)
+    }
+    if (params.q !== undefined && filterState?.setSearchQuery) filterState.setSearchQuery(params.q)
+    if (params.toolMode && setToolMode) setToolMode(params.toolMode)
+    if (params.palette === 'open' && setPaletteOpen) setPaletteOpen(true)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
 
-    // 📖 Filter hydration is wired through the filterState prop in M2. M1 just
-    // 📖 sets the view; the rest of the URL params act as documentation for
-    // 📖 the user and get the write-back loop fully closed in M2.
-  }, [currentView, setCurrentView, filterState])
+  // 📖 Write-back: any change to currentView / filter / toolMode / palette
+  // 📖 updates the URL. Debounced at 80ms so rapid filter typing doesn't
+  // 📖 thrash the history stack.
+  useEffect(() => {
+    if (!hydratedRef.current) return
+    if (writeTimerRef.current) clearTimeout(writeTimerRef.current)
+    writeTimerRef.current = setTimeout(() => {
+      writeUrl({
+        currentView,
+        filterTier: filterState?.filterTier,
+        filterStatus: filterState?.filterStatus,
+        filterProvider: filterState?.filterProvider,
+        filterVerdict: filterState?.filterVerdict,
+        filterHealth: filterState?.filterHealth,
+        sortColumn: filterState?.sortColumn,
+        sortDirection: filterState?.sortDirection,
+        searchQuery: filterState?.searchQuery,
+        toolMode,
+        paletteOpen,
+      })
+    }, 80)
+    return () => {
+      if (writeTimerRef.current) clearTimeout(writeTimerRef.current)
+    }
+  }, [
+    currentView, paletteOpen, toolMode,
+    filterState?.filterTier, filterState?.filterStatus, filterState?.filterProvider,
+    filterState?.filterVerdict, filterState?.filterHealth,
+    filterState?.sortColumn, filterState?.sortDirection,
+    filterState?.searchQuery,
+  ])
 }
-
-// 📖 Re-export the parser so M2's write-back path can use the same validator.
-export { parseUrlParams, VALID_TIERS, VALID_STATUS, VALID_SORTS, VALID_VIEWS, VALID_DIRS }